Shallow fetch: negotiate from mirror tips with alternate ref discovery off (#50)

* Shallow fetch: negotiate from mirror tips with alternate ref discovery off

With the mirror attached as an alternate, a deepening fetch treats every
mirror ref as a known tip: negotiation offers them all as haves and the
post-fetch connectivity check walks the whole mirror object graph, so the
shallow path costs time proportional to mirror history instead of to the
requested checkout.

Set core.alternateRefsCommand to a no-op so alternates only contribute
objects, and pass the mirror's copy of the requested branch/tag (or the
PR base branch, or mirror HEAD) as --negotiation-tip so the server still
sends only the delta from the mirror. Requires git >= 2.19; older git
keeps the previous behaviour.

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* test: cover shallow fetch when the mirror is ahead of the wanted commit

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* Gate core.alternateRefsCommand on git 2.20

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: piob-io

README.md

@@ -48,6 +48,8 @@ When a mirror already exists, the action mounts its Sticky Disk and uses [Git's
 
 The workspace then performs the normal upstream-compatible fetch. Objects already present in the mirror are reused locally, while objects that are newer than the mirror are fetched from GitHub. This means a stale mirror does not block checkout or prevent the requested commit from being fetched.
 
+For shallow checkouts (`fetch-depth` greater than 0), the fetch tells GitHub which commits the mirror already has for the requested branch or tag, so only the delta since the mirror was last refreshed is transferred. Git is also stopped from treating every mirror ref as a starting point for its post-fetch checks, which would otherwise cost time proportional to the whole mirror history rather than to the requested checkout.
+
 The mirror always contains full history, but the workspace still respects inputs such as `fetch-depth`, `fetch-tags`, sparse checkout, LFS, and submodules. For example, `fetch-depth: 1` still produces a shallow workspace checkout.
 
 ### 3. Post-job refresh

__test__/blacksmith-cache.test.ts

@@ -448,6 +448,49 @@ describe('blacksmith-cache tests', () => {
     })
   })
 
+  describe('shallowNegotiationTipRefs', () => {
+    it('offers the same branch then HEAD', () => {
+      expect(
+        blacksmithCache.shallowNegotiationTipRefs('refs/heads/feature', '')
+      ).toEqual(['refs/heads/feature', 'HEAD'])
+    })
+
+    it('offers the same tag then HEAD', () => {
+      expect(
+        blacksmithCache.shallowNegotiationTipRefs('refs/tags/v1', 'main')
+      ).toEqual(['refs/tags/v1', 'HEAD'])
+    })
+
+    it('offers the base branch for pull request refs', () => {
+      expect(
+        blacksmithCache.shallowNegotiationTipRefs('refs/pull/42/merge', 'main')
+      ).toEqual(['refs/heads/main', 'HEAD'])
+      expect(
+        blacksmithCache.shallowNegotiationTipRefs(
+          'refs/pull/42/head',
+          'refs/heads/release'
+        )
+      ).toEqual(['refs/heads/release', 'HEAD'])
+    })
+
+    it('falls back to HEAD for pull request refs without a base and for bare SHAs', () => {
+      expect(
+        blacksmithCache.shallowNegotiationTipRefs('refs/pull/42/merge', '')
+      ).toEqual(['HEAD'])
+      expect(blacksmithCache.shallowNegotiationTipRefs('', '')).toEqual([
+        'HEAD'
+      ])
+    })
+
+    it('tries both branch and tag for an unqualified ref', () => {
+      expect(blacksmithCache.shallowNegotiationTipRefs('v1', '')).toEqual([
+        'refs/heads/v1',
+        'refs/tags/v1',
+        'HEAD'
+      ])
+    })
+  })
+
   describe('parseMissingRemoteRefs', () => {
     it('extracts a single missing ref', () => {
       const stderr =

__test__/git-command-manager.test.ts

@@ -375,4 +375,46 @@ describe('Test fetchDepth and fetchTags options', () => {
       expect.any(Object)
     )
   })
+
+  it('should disable alternate ref discovery and pass negotiation tips for a shallow mirror fetch', async () => {
+    jest.spyOn(exec, 'exec').mockImplementation(mockExec)
+
+    const workingDirectory = 'test'
+    const lfs = false
+    const doSparseCheckout = false
+    git = await commandManager.createCommandManager(
+      workingDirectory,
+      lfs,
+      doSparseCheckout
+    )
+    const refSpec = ['refspec1']
+    const options = {
+      fetchDepth: 1,
+      fetchTags: false,
+      ignoreAlternateRefs: true,
+      negotiationTips: ['aaaa', 'bbbb']
+    }
+
+    await git.fetch(refSpec, options)
+
+    expect(mockExec).toHaveBeenCalledWith(
+      expect.any(String),
+      [
+        '-c',
+        'protocol.version=2',
+        '-c',
+        'core.alternateRefsCommand=true',
+        'fetch',
+        '--no-tags',
+        '--prune',
+        '--no-recurse-submodules',
+        '--negotiation-tip=aaaa',
+        '--negotiation-tip=bbbb',
+        '--depth=1',
+        'origin',
+        'refspec1'
+      ],
+      expect.any(Object)
+    )
+  })
 })