feat: override fetch-depth to 0 when reference-cache is active

When reference-cache is enabled, shallow fetches (fetch-depth > 0) are
counterproductive because objects are served from the local cache.
Shallow negotiation only adds network latency without saving bandwidth.

If fetch-depth was not explicitly set by the user, it is automatically
overridden to 0. If explicitly set, a warning is emitted explaining
the performance impact.

Signed-off-by: Michael Wyraz <mw@brick4u.de>

.github/workflows/check-dist.yml

@@ -22,12 +22,12 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4.1.6
+      - uses: actions/checkout@v6
 
-      - name: Set Node.js 20.x
+      - name: Set Node.js 24.x
         uses: actions/setup-node@v4
         with:
-          node-version: 20.x
+          node-version: 24.x
 
       - name: Install dependencies
         run: npm ci

.github/workflows/codeql-analysis.yml

@@ -39,7 +39,7 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v4.1.6
+      uses: actions/checkout@v6
 
     - name: Initialize CodeQL
       uses: github/codeql-action/init@v3

.github/workflows/licensed.yml

@@ -9,6 +9,6 @@ jobs:
     runs-on: ubuntu-latest
     name: Check licenses
     steps:
-      - uses: actions/checkout@v4.1.6
+      - uses: actions/checkout@v6
       - run: npm ci
       - run: npm run licensed-check

.github/workflows/publish-immutable-actions.yml

@@ -14,7 +14,7 @@ jobs:
 
     steps:
       - name: Checking out
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
       - name: Publish
         id: publish
         uses: actions/publish-immutable-action@0.0.3

.github/workflows/test.yml

@@ -18,8 +18,8 @@ jobs:
     steps:
       - uses: actions/setup-node@v4
         with:
-          node-version: 20.x
+          node-version: 24.x
-      - uses: actions/checkout@v4.1.6
+      - uses: actions/checkout@v6
       - run: npm ci
       - run: npm run build
       - run: npm run format-check
@@ -37,7 +37,7 @@ jobs:
     steps:
       # Clone this repo
       - name: Checkout
-        uses: actions/checkout@v4.1.6
+        uses: actions/checkout@v6
 
       # Basic checkout
       - name: Checkout basic
@@ -87,6 +87,17 @@ jobs:
       - name: Verify fetch filter
         run: __test__/verify-fetch-filter.sh
 
+      # Fetch tags
+      - name: Checkout with fetch-tags
+        uses: ./
+        with:
+          ref: test-data/v2/basic
+          path: fetch-tags-test
+          fetch-tags: true
+      - name: Verify fetch-tags
+        shell: bash
+        run: __test__/verify-fetch-tags.sh
+
       # Sparse checkout
       - name: Sparse checkout
         uses: ./
@@ -165,6 +176,22 @@ jobs:
       - name: Verify submodules recursive
         run: __test__/verify-submodules-recursive.sh
 
+      # Worktree credentials
+      - name: Checkout for worktree test
+        uses: ./
+        with:
+          path: worktree-test
+      - name: Verify worktree credentials
+        shell: bash
+        run: __test__/verify-worktree.sh worktree-test worktree-branch
+
+      # Worktree credentials in container step
+      - name: Verify worktree credentials in container step
+        if: runner.os == 'Linux'
+        uses: docker://bitnami/git:latest
+        with:
+          args: bash __test__/verify-worktree.sh worktree-test container-worktree-branch
+
       # Basic checkout using REST API
       - name: Remove basic
         if: runner.os != 'windows'
@@ -202,7 +229,7 @@ jobs:
     steps:
       # Clone this repo
       - name: Checkout
-        uses: actions/checkout@v4.1.6
+        uses: actions/checkout@v6
 
       # Basic checkout using git
       - name: Checkout basic
@@ -234,7 +261,7 @@ jobs:
     steps:
       # Clone this repo
       - name: Checkout
-        uses: actions/checkout@v4.1.6
+        uses: actions/checkout@v6
 
       # Basic checkout using git
       - name: Checkout basic
@@ -264,7 +291,7 @@ jobs:
     steps:
       # Clone this repo
       - name: Checkout
-        uses: actions/checkout@v4.1.6
+        uses: actions/checkout@v6
         with:
           path: localClone
 
@@ -291,8 +318,8 @@ jobs:
           git fetch --no-tags --depth=1 origin +refs/heads/main:refs/remotes/origin/main
 
       # needed to make checkout post cleanup succeed
-      - name: Fix Checkout v4
+      - name: Fix Checkout v6
-        uses: actions/checkout@v4.1.6
+        uses: actions/checkout@v6
         with:
           path: localClone
 
@@ -301,13 +328,16 @@ jobs:
     steps:
       # Clone this repo
       - name: Checkout
-        uses: actions/checkout@v4.1.6
+        uses: actions/checkout@v6
+        with:
+          path: actions-checkout
 
       # Basic checkout using git
       - name: Checkout basic
         id: checkout
-        uses: ./
+        uses: ./actions-checkout
         with:
+          path: cloned-using-local-action
           ref: test-data/v2/basic
 
       # Verify output
@@ -325,7 +355,3 @@ jobs:
             echo "Expected commit to be 82f71901cf8c021332310dcc8cdba84c4193ff5d"
             exit 1
           fi
-
-      # needed to make checkout post cleanup succeed
-      - name: Fix Checkout
-        uses: actions/checkout@v4.1.6

.github/workflows/update-main-version.yml

@@ -11,6 +11,7 @@ on:
         type: choice
         description: The major version to update
         options:
+          - v5
           - v4
           - v3
           - v2
@@ -22,7 +23,7 @@ jobs:
     # Note this update workflow can also be used as a rollback tool.
     # For that reason, it's best to pin `actions/checkout` to a known, stable version
     # (typically, about two releases back).
-    - uses: actions/checkout@v4.1.6
+    - uses: actions/checkout@v6
       with:
         fetch-depth: 0
     - name: Git config

.github/workflows/update-test-ubuntu-git.yml

@@ -26,7 +26,7 @@ jobs:
  
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       # Use `docker/login-action` to log in to GHCR.io. 
       # Once published, the packages are scoped to the account defined here.

CHANGELOG.md

@@ -1,6 +1,25 @@
 # Changelog
 
-## V4.3.0
+## v6.0.2
+* Fix tag handling: preserve annotations and explicit fetch-tags by @ericsciple in https://github.com/actions/checkout/pull/2356
+
+## v6.0.1
+* Add worktree support for persist-credentials includeIf by @ericsciple in https://github.com/actions/checkout/pull/2327
+
+## v6.0.0
+* Persist creds to a separate file by @ericsciple in https://github.com/actions/checkout/pull/2286
+* Update README to include Node.js 24 support details and requirements by @salmanmkc in https://github.com/actions/checkout/pull/2248
+
+## v5.0.1
+* Port v6 cleanup to v5 by @ericsciple in https://github.com/actions/checkout/pull/2301
+
+## v5.0.0
+* Update actions checkout to use node 24 by @salmanmkc in https://github.com/actions/checkout/pull/2226
+
+## v4.3.1
+* Port v6 cleanup to v4 by @ericsciple in https://github.com/actions/checkout/pull/2305
+
+## v4.3.0
 * docs: update README.md by @motss in https://github.com/actions/checkout/pull/1971
 * Add internal repos for checking out multiple repositories by @mouismail in https://github.com/actions/checkout/pull/1977
 * Documentation update - add recommended permissions to Readme by @benwells in https://github.com/actions/checkout/pull/2043

README.md

@@ -1,6 +1,22 @@
 [![Build and Test](https://github.com/actions/checkout/actions/workflows/test.yml/badge.svg)](https://github.com/actions/checkout/actions/workflows/test.yml)
 
-# Checkout V4
+# Checkout v6
+
+## What's new
+
+- Improved credential security: `persist-credentials` now stores credentials in a separate file under `$RUNNER_TEMP` instead of directly in `.git/config`
+- No workflow changes required — `git fetch`, `git push`, etc. continue to work automatically
+- Running authenticated git commands from a [Docker container action](https://docs.github.com/actions/sharing-automations/creating-actions/creating-a-docker-container-action) requires Actions Runner [v2.329.0](https://github.com/actions/runner/releases/tag/v2.329.0) or later
+
+# Checkout v5
+
+## What's new
+
+- Updated to the node24 runtime
+  - This requires a minimum Actions Runner version of [v2.327.1](https://github.com/actions/runner/releases/tag/v2.327.1) to run.
+
+
+# Checkout v4
 
 This action checks-out your repository under `$GITHUB_WORKSPACE`, so your workflow can access it.
 
@@ -36,7 +52,7 @@ Please refer to the [release page](https://github.com/actions/checkout/releases/
 
 <!-- start usage -->
 ```yaml
-- uses: actions/checkout@v4
+- uses: actions/checkout@v6
   with:
     # Repository name with owner. For example, actions/checkout
     # Default: ${{ github.repository }}
@@ -144,29 +160,44 @@ Please refer to the [release page](https://github.com/actions/checkout/releases/
     # running from unless specified. Example URLs are https://github.com or
     # https://my-ghes-server.example.com
     github-server-url: ''
+
+    # Path to a local directory used as a reference cache for Git clones. Over time,
+    # this directory will contain bare clones of the checked-out repositories (and
+    # their submodules). Using this significantly reduces network bandwidth and speeds
+    # up clones.
+    reference-cache: ''
 ```
 <!-- end usage -->
 
 # Scenarios
 
-- [Fetch only the root files](#Fetch-only-the-root-files)
+- [Checkout V5](#checkout-v5)
-- [Fetch only the root files and `.github` and `src` folder](#Fetch-only-the-root-files-and-github-and-src-folder)
+  - [What's new](#whats-new)
-- [Fetch only a single file](#Fetch-only-a-single-file)
+- [Checkout V4](#checkout-v4)
-- [Fetch all history for all tags and branches](#Fetch-all-history-for-all-tags-and-branches)
+    - [Note](#note)
-- [Checkout a different branch](#Checkout-a-different-branch)
+- [What's new](#whats-new-1)
-- [Checkout HEAD^](#Checkout-HEAD)
+- [Usage](#usage)
-- [Checkout multiple repos (side by side)](#Checkout-multiple-repos-side-by-side)
+- [Scenarios](#scenarios)
-- [Checkout multiple repos (nested)](#Checkout-multiple-repos-nested)
+  - [Fetch only the root files](#fetch-only-the-root-files)
-- [Checkout multiple repos (private)](#Checkout-multiple-repos-private)
+  - [Fetch only the root files and `.github` and `src` folder](#fetch-only-the-root-files-and-github-and-src-folder)
-- [Checkout pull request HEAD commit instead of merge commit](#Checkout-pull-request-HEAD-commit-instead-of-merge-commit)
+  - [Fetch only a single file](#fetch-only-a-single-file)
-- [Checkout pull request on closed event](#Checkout-pull-request-on-closed-event)
+  - [Fetch all history for all tags and branches](#fetch-all-history-for-all-tags-and-branches)
-- [Push a commit using the built-in token](#Push-a-commit-using-the-built-in-token)
+  - [Checkout a different branch](#checkout-a-different-branch)
-- [Push a commit to a PR using the built-in token](#Push-a-commit-to-a-PR-using-the-built-in-token)
+  - [Checkout HEAD^](#checkout-head)
+  - [Checkout multiple repos (side by side)](#checkout-multiple-repos-side-by-side)
+  - [Checkout multiple repos (nested)](#checkout-multiple-repos-nested)
+  - [Checkout multiple repos (private)](#checkout-multiple-repos-private)
+  - [Checkout pull request HEAD commit instead of merge commit](#checkout-pull-request-head-commit-instead-of-merge-commit)
+  - [Checkout pull request on closed event](#checkout-pull-request-on-closed-event)
+  - [Push a commit using the built-in token](#push-a-commit-using-the-built-in-token)
+  - [Push a commit to a PR using the built-in token](#push-a-commit-to-a-pr-using-the-built-in-token)
+- [Recommended permissions](#recommended-permissions)
+- [License](#license)
 
 ## Fetch only the root files
 
 ```yaml
-- uses: actions/checkout@v4
+- uses: actions/checkout@v6
   with:
     sparse-checkout: .
 ```
@@ -174,7 +205,7 @@ Please refer to the [release page](https://github.com/actions/checkout/releases/
 ## Fetch only the root files and `.github` and `src` folder
 
 ```yaml
-- uses: actions/checkout@v4
+- uses: actions/checkout@v6
   with:
     sparse-checkout: |
       .github
@@ -184,7 +215,7 @@ Please refer to the [release page](https://github.com/actions/checkout/releases/
 ## Fetch only a single file
 
 ```yaml
-- uses: actions/checkout@v4
+- uses: actions/checkout@v6
   with:
     sparse-checkout: |
       README.md
@@ -194,7 +225,7 @@ Please refer to the [release page](https://github.com/actions/checkout/releases/
 ## Fetch all history for all tags and branches
 
 ```yaml
-- uses: actions/checkout@v4
+- uses: actions/checkout@v6
   with:
     fetch-depth: 0
 ```
@@ -202,7 +233,7 @@ Please refer to the [release page](https://github.com/actions/checkout/releases/
 ## Checkout a different branch
 
 ```yaml
-- uses: actions/checkout@v4
+- uses: actions/checkout@v6
   with:
     ref: my-branch
 ```
@@ -210,7 +241,7 @@ Please refer to the [release page](https://github.com/actions/checkout/releases/
 ## Checkout HEAD^
 
 ```yaml
-- uses: actions/checkout@v4
+- uses: actions/checkout@v6
   with:
     fetch-depth: 2
 - run: git checkout HEAD^
@@ -220,12 +251,12 @@ Please refer to the [release page](https://github.com/actions/checkout/releases/
 
 ```yaml
 - name: Checkout
-  uses: actions/checkout@v4
+  uses: actions/checkout@v6
   with:
     path: main
 
 - name: Checkout tools repo
-  uses: actions/checkout@v4
+  uses: actions/checkout@v6
   with:
     repository: my-org/my-tools
     path: my-tools
@@ -236,10 +267,10 @@ Please refer to the [release page](https://github.com/actions/checkout/releases/
 
 ```yaml
 - name: Checkout
-  uses: actions/checkout@v4
+  uses: actions/checkout@v6
 
 - name: Checkout tools repo
-  uses: actions/checkout@v4
+  uses: actions/checkout@v6
   with:
     repository: my-org/my-tools
     path: my-tools
@@ -250,12 +281,12 @@ Please refer to the [release page](https://github.com/actions/checkout/releases/
 
 ```yaml
 - name: Checkout
-  uses: actions/checkout@v4
+  uses: actions/checkout@v6
   with:
     path: main
 
 - name: Checkout private tools
-  uses: actions/checkout@v4
+  uses: actions/checkout@v6
   with:
     repository: my-org/my-private-tools
     token: ${{ secrets.GH_PAT }} # `GH_PAT` is a secret that contains your PAT
@@ -268,7 +299,7 @@ Please refer to the [release page](https://github.com/actions/checkout/releases/
 ## Checkout pull request HEAD commit instead of merge commit
 
 ```yaml
-- uses: actions/checkout@v4
+- uses: actions/checkout@v6
   with:
     ref: ${{ github.event.pull_request.head.sha }}
 ```
@@ -284,7 +315,7 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 ```
 
 ## Push a commit using the built-in token
@@ -295,7 +326,7 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - run: |
           date > generated.txt
           # Note: the following account information will not work on GHES
@@ -317,7 +348,7 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           ref: ${{ github.head_ref }}
       - run: |

__test__/git-auth-helper.test.ts

@@ -86,16 +86,29 @@ describe('git-auth-helper tests', () => {
     // Act
     await authHelper.configureAuth()
 
-    // Assert config
+    // Assert config - check that .git/config contains includeIf entries
-    const configContent = (
+    const localConfigContent = (
       await fs.promises.readFile(localGitConfigPath)
     ).toString()
+    expect(
+      localConfigContent.indexOf('includeIf.gitdir:')
+    ).toBeGreaterThanOrEqual(0)
+
+    // Assert credentials config file contains the actual credentials
+    const credentialsFiles = (await fs.promises.readdir(runnerTemp)).filter(
+      f => f.startsWith('git-credentials-') && f.endsWith('.config')
+    )
+    expect(credentialsFiles.length).toBe(1)
+    const credentialsConfigPath = path.join(runnerTemp, credentialsFiles[0])
+    const credentialsContent = (
+      await fs.promises.readFile(credentialsConfigPath)
+    ).toString()
     const basicCredential = Buffer.from(
       `x-access-token:${settings.authToken}`,
       'utf8'
     ).toString('base64')
     expect(
-      configContent.indexOf(
+      credentialsContent.indexOf(
         `http.${expectedServerUrl}/.extraheader AUTHORIZATION: basic ${basicCredential}`
       )
     ).toBeGreaterThanOrEqual(0)
@@ -120,7 +133,7 @@ describe('git-auth-helper tests', () => {
     'inject https://github.com as github server url'
   it(configureAuth_AcceptsGitHubServerUrlSetToGHEC, async () => {
     await testAuthHeader(
-      configureAuth_AcceptsGitHubServerUrl,
+      configureAuth_AcceptsGitHubServerUrlSetToGHEC,
       'https://github.com'
     )
   })
@@ -141,12 +154,17 @@ describe('git-auth-helper tests', () => {
       // Act
       await authHelper.configureAuth()
 
-      // Assert config
+      // Assert config - check credentials config file (not local .git/config)
-      const configContent = (
+      const credentialsFiles = (await fs.promises.readdir(runnerTemp)).filter(
-        await fs.promises.readFile(localGitConfigPath)
+        f => f.startsWith('git-credentials-') && f.endsWith('.config')
+      )
+      expect(credentialsFiles.length).toBe(1)
+      const credentialsConfigPath = path.join(runnerTemp, credentialsFiles[0])
+      const credentialsContent = (
+        await fs.promises.readFile(credentialsConfigPath)
       ).toString()
       expect(
-        configContent.indexOf(
+        credentialsContent.indexOf(
           `http.https://github.com/.extraheader AUTHORIZATION`
         )
       ).toBeGreaterThanOrEqual(0)
@@ -251,13 +269,16 @@ describe('git-auth-helper tests', () => {
       expectedSshCommand
     )
 
-    // Asserty git config
+    // Assert git config
     const gitConfigLines = (await fs.promises.readFile(localGitConfigPath))
       .toString()
       .split('\n')
       .filter(x => x)
-    expect(gitConfigLines).toHaveLength(1)
+    // Should have includeIf entries pointing to credentials file
-    expect(gitConfigLines[0]).toMatch(/^http\./)
+    expect(gitConfigLines.length).toBeGreaterThan(0)
+    expect(
+      gitConfigLines.some(line => line.indexOf('includeIf.gitdir:') >= 0)
+    ).toBeTruthy()
   })
 
   const configureAuth_setsSshCommandWhenPersistCredentialsTrue =
@@ -419,8 +440,20 @@ describe('git-auth-helper tests', () => {
     expect(
       configContent.indexOf('value-from-global-config')
     ).toBeGreaterThanOrEqual(0)
+    // Global config should have include.path pointing to credentials file
+    expect(configContent.indexOf('include.path')).toBeGreaterThanOrEqual(0)
+
+    // Check credentials in the separate config file
+    const credentialsFiles = (await fs.promises.readdir(runnerTemp)).filter(
+      f => f.startsWith('git-credentials-') && f.endsWith('.config')
+    )
+    expect(credentialsFiles.length).toBeGreaterThan(0)
+    const credentialsConfigPath = path.join(runnerTemp, credentialsFiles[0])
+    const credentialsContent = (
+      await fs.promises.readFile(credentialsConfigPath)
+    ).toString()
     expect(
-      configContent.indexOf(
+      credentialsContent.indexOf(
         `http.https://github.com/.extraheader AUTHORIZATION: basic ${basicCredential}`
       )
     ).toBeGreaterThanOrEqual(0)
@@ -463,8 +496,20 @@ describe('git-auth-helper tests', () => {
       const configContent = (
         await fs.promises.readFile(path.join(git.env['HOME'], '.gitconfig'))
       ).toString()
+      // Global config should have include.path pointing to credentials file
+      expect(configContent.indexOf('include.path')).toBeGreaterThanOrEqual(0)
+
+      // Check credentials in the separate config file
+      const credentialsFiles = (await fs.promises.readdir(runnerTemp)).filter(
+        f => f.startsWith('git-credentials-') && f.endsWith('.config')
+      )
+      expect(credentialsFiles.length).toBeGreaterThan(0)
+      const credentialsConfigPath = path.join(runnerTemp, credentialsFiles[0])
+      const credentialsContent = (
+        await fs.promises.readFile(credentialsConfigPath)
+      ).toString()
       expect(
-        configContent.indexOf(
+        credentialsContent.indexOf(
           `http.https://github.com/.extraheader AUTHORIZATION: basic ${basicCredential}`
         )
       ).toBeGreaterThanOrEqual(0)
@@ -550,15 +595,15 @@ describe('git-auth-helper tests', () => {
       await authHelper.configureSubmoduleAuth()
 
       // Assert
-      expect(mockSubmoduleForeach).toHaveBeenCalledTimes(4)
+      // Should configure insteadOf (2 calls for two values)
+      expect(mockSubmoduleForeach).toHaveBeenCalledTimes(3)
       expect(mockSubmoduleForeach.mock.calls[0][0]).toMatch(
         /unset-all.*insteadOf/
       )
-      expect(mockSubmoduleForeach.mock.calls[1][0]).toMatch(/http.*extraheader/)
+      expect(mockSubmoduleForeach.mock.calls[1][0]).toMatch(
-      expect(mockSubmoduleForeach.mock.calls[2][0]).toMatch(
         /url.*insteadOf.*git@github.com:/
       )
-      expect(mockSubmoduleForeach.mock.calls[3][0]).toMatch(
+      expect(mockSubmoduleForeach.mock.calls[2][0]).toMatch(
         /url.*insteadOf.*org-123456@github.com:/
       )
     }
@@ -589,12 +634,12 @@ describe('git-auth-helper tests', () => {
       await authHelper.configureSubmoduleAuth()
 
       // Assert
-      expect(mockSubmoduleForeach).toHaveBeenCalledTimes(3)
+      // Should configure sshCommand (1 call)
+      expect(mockSubmoduleForeach).toHaveBeenCalledTimes(2)
       expect(mockSubmoduleForeach.mock.calls[0][0]).toMatch(
         /unset-all.*insteadOf/
       )
-      expect(mockSubmoduleForeach.mock.calls[1][0]).toMatch(/http.*extraheader/)
+      expect(mockSubmoduleForeach.mock.calls[1][0]).toMatch(/core\.sshCommand/)
-      expect(mockSubmoduleForeach.mock.calls[2][0]).toMatch(/core\.sshCommand/)
     }
   )
 
@@ -660,19 +705,201 @@ describe('git-auth-helper tests', () => {
     await setup(removeAuth_removesToken)
     const authHelper = gitAuthHelper.createAuthHelper(git, settings)
     await authHelper.configureAuth()
-    let gitConfigContent = (
+
+    // Verify includeIf entries exist in local config
+    let localConfigContent = (
       await fs.promises.readFile(localGitConfigPath)
     ).toString()
-    expect(gitConfigContent.indexOf('http.')).toBeGreaterThanOrEqual(0) // sanity check
+    expect(
+      localConfigContent.indexOf('includeIf.gitdir:')
+    ).toBeGreaterThanOrEqual(0)
+
+    // Verify both host and container includeIf entries are present
+    const hostGitDir = path.join(workspace, '.git').replace(/\\/g, '/')
+    expect(
+      localConfigContent.indexOf(`includeIf.gitdir:${hostGitDir}.path`)
+    ).toBeGreaterThanOrEqual(0)
+    expect(
+      localConfigContent.indexOf('includeIf.gitdir:/github/workspace/.git.path')
+    ).toBeGreaterThanOrEqual(0)
+
+    // Verify credentials file exists
+    let credentialsFiles = (await fs.promises.readdir(runnerTemp)).filter(
+      f => f.startsWith('git-credentials-') && f.endsWith('.config')
+    )
+    expect(credentialsFiles.length).toBe(1)
+    const credentialsFilePath = path.join(runnerTemp, credentialsFiles[0])
+
+    // Verify credentials file contains the auth token
+    let credentialsContent = (
+      await fs.promises.readFile(credentialsFilePath)
+    ).toString()
+    const basicCredential = Buffer.from(
+      `x-access-token:${settings.authToken}`,
+      'utf8'
+    ).toString('base64')
+    expect(
+      credentialsContent.indexOf(
+        `http.https://github.com/.extraheader AUTHORIZATION: basic ${basicCredential}`
+      )
+    ).toBeGreaterThanOrEqual(0)
+
+    // Verify the includeIf entries point to the credentials file
+    const containerCredentialsPath = path.posix.join(
+      '/github/runner_temp',
+      path.basename(credentialsFilePath)
+    )
+    expect(
+      localConfigContent.indexOf(credentialsFilePath)
+    ).toBeGreaterThanOrEqual(0)
+    expect(
+      localConfigContent.indexOf(containerCredentialsPath)
+    ).toBeGreaterThanOrEqual(0)
 
     // Act
     await authHelper.removeAuth()
 
-    // Assert git config
+    // Assert all includeIf entries removed from local git config
-    gitConfigContent = (
+    localConfigContent = (
       await fs.promises.readFile(localGitConfigPath)
     ).toString()
-    expect(gitConfigContent.indexOf('http.')).toBeLessThan(0)
+    expect(localConfigContent.indexOf('includeIf.gitdir:')).toBeLessThan(0)
+    expect(
+      localConfigContent.indexOf(`includeIf.gitdir:${hostGitDir}.path`)
+    ).toBeLessThan(0)
+    expect(
+      localConfigContent.indexOf('includeIf.gitdir:/github/workspace/.git.path')
+    ).toBeLessThan(0)
+    expect(localConfigContent.indexOf(credentialsFilePath)).toBeLessThan(0)
+    expect(localConfigContent.indexOf(containerCredentialsPath)).toBeLessThan(0)
+
+    // Assert credentials config file deleted
+    credentialsFiles = (await fs.promises.readdir(runnerTemp)).filter(
+      f => f.startsWith('git-credentials-') && f.endsWith('.config')
+    )
+    expect(credentialsFiles.length).toBe(0)
+
+    // Verify credentials file no longer exists on disk
+    try {
+      await fs.promises.stat(credentialsFilePath)
+      throw new Error('Credentials file should have been deleted')
+    } catch (err) {
+      if ((err as any)?.code !== 'ENOENT') {
+        throw err
+      }
+    }
+  })
+
+  const removeAuth_removesTokenFromSubmodules =
+    'removeAuth removes token from submodules'
+  it(removeAuth_removesTokenFromSubmodules, async () => {
+    // Arrange
+    await setup(removeAuth_removesTokenFromSubmodules)
+
+    // Create fake submodule config paths
+    const submodule1Dir = path.join(workspace, '.git', 'modules', 'submodule-1')
+    const submodule2Dir = path.join(workspace, '.git', 'modules', 'submodule-2')
+    const submodule1ConfigPath = path.join(submodule1Dir, 'config')
+    const submodule2ConfigPath = path.join(submodule2Dir, 'config')
+
+    await fs.promises.mkdir(submodule1Dir, {recursive: true})
+    await fs.promises.mkdir(submodule2Dir, {recursive: true})
+    await fs.promises.writeFile(submodule1ConfigPath, '')
+    await fs.promises.writeFile(submodule2ConfigPath, '')
+
+    // Mock getSubmoduleConfigPaths to return our fake submodules (for both configure and remove)
+    const mockGetSubmoduleConfigPaths =
+      git.getSubmoduleConfigPaths as jest.Mock<any, any>
+    mockGetSubmoduleConfigPaths.mockResolvedValue([
+      submodule1ConfigPath,
+      submodule2ConfigPath
+    ])
+
+    const authHelper = gitAuthHelper.createAuthHelper(git, settings)
+    await authHelper.configureAuth()
+    await authHelper.configureSubmoduleAuth()
+
+    // Verify credentials file exists
+    let credentialsFiles = (await fs.promises.readdir(runnerTemp)).filter(
+      f => f.startsWith('git-credentials-') && f.endsWith('.config')
+    )
+    expect(credentialsFiles.length).toBe(1)
+    const credentialsFilePath = path.join(runnerTemp, credentialsFiles[0])
+
+    // Verify submodule 1 config has includeIf entries
+    let submodule1Content = (
+      await fs.promises.readFile(submodule1ConfigPath)
+    ).toString()
+    const submodule1GitDir = submodule1Dir.replace(/\\/g, '/')
+    expect(
+      submodule1Content.indexOf(`includeIf.gitdir:${submodule1GitDir}.path`)
+    ).toBeGreaterThanOrEqual(0)
+    expect(
+      submodule1Content.indexOf(credentialsFilePath)
+    ).toBeGreaterThanOrEqual(0)
+
+    // Verify submodule 2 config has includeIf entries
+    let submodule2Content = (
+      await fs.promises.readFile(submodule2ConfigPath)
+    ).toString()
+    const submodule2GitDir = submodule2Dir.replace(/\\/g, '/')
+    expect(
+      submodule2Content.indexOf(`includeIf.gitdir:${submodule2GitDir}.path`)
+    ).toBeGreaterThanOrEqual(0)
+    expect(
+      submodule2Content.indexOf(credentialsFilePath)
+    ).toBeGreaterThanOrEqual(0)
+
+    // Verify both host and container paths are in each submodule config
+    const containerCredentialsPath = path.posix.join(
+      '/github/runner_temp',
+      path.basename(credentialsFilePath)
+    )
+    expect(
+      submodule1Content.indexOf(containerCredentialsPath)
+    ).toBeGreaterThanOrEqual(0)
+    expect(
+      submodule2Content.indexOf(containerCredentialsPath)
+    ).toBeGreaterThanOrEqual(0)
+
+    // Act - ensure mock persists for removeAuth
+    mockGetSubmoduleConfigPaths.mockResolvedValue([
+      submodule1ConfigPath,
+      submodule2ConfigPath
+    ])
+    await authHelper.removeAuth()
+
+    // Assert submodule 1 includeIf entries removed
+    submodule1Content = (
+      await fs.promises.readFile(submodule1ConfigPath)
+    ).toString()
+    expect(submodule1Content.indexOf('includeIf.gitdir:')).toBeLessThan(0)
+    expect(submodule1Content.indexOf(credentialsFilePath)).toBeLessThan(0)
+    expect(submodule1Content.indexOf(containerCredentialsPath)).toBeLessThan(0)
+
+    // Assert submodule 2 includeIf entries removed
+    submodule2Content = (
+      await fs.promises.readFile(submodule2ConfigPath)
+    ).toString()
+    expect(submodule2Content.indexOf('includeIf.gitdir:')).toBeLessThan(0)
+    expect(submodule2Content.indexOf(credentialsFilePath)).toBeLessThan(0)
+    expect(submodule2Content.indexOf(containerCredentialsPath)).toBeLessThan(0)
+
+    // Assert credentials config file deleted
+    credentialsFiles = (await fs.promises.readdir(runnerTemp)).filter(
+      f => f.startsWith('git-credentials-') && f.endsWith('.config')
+    )
+    expect(credentialsFiles.length).toBe(0)
+
+    // Verify credentials file no longer exists on disk
+    try {
+      await fs.promises.stat(credentialsFilePath)
+      throw new Error('Credentials file should have been deleted')
+    } catch (err) {
+      if ((err as any)?.code !== 'ENOENT') {
+        throw err
+      }
+    }
   })
 
   const removeGlobalConfig_removesOverride =
@@ -701,6 +928,52 @@ describe('git-auth-helper tests', () => {
       }
     }
   })
+
+  const testCredentialsConfigPath_matchesCredentialsConfigPaths =
+    'testCredentialsConfigPath matches credentials config paths'
+  it(testCredentialsConfigPath_matchesCredentialsConfigPaths, async () => {
+    // Arrange
+    await setup(testCredentialsConfigPath_matchesCredentialsConfigPaths)
+    const authHelper = gitAuthHelper.createAuthHelper(git, settings)
+
+    // Get a real credentials config path
+    const credentialsConfigPath = await (
+      authHelper as any
+    ).getCredentialsConfigPath()
+
+    // Act & Assert
+    expect(
+      (authHelper as any).testCredentialsConfigPath(credentialsConfigPath)
+    ).toBe(true)
+    expect(
+      (authHelper as any).testCredentialsConfigPath(
+        '/some/path/git-credentials-12345678-abcd-1234-5678-123456789012.config'
+      )
+    ).toBe(true)
+    expect(
+      (authHelper as any).testCredentialsConfigPath(
+        '/some/path/git-credentials-abcdef12-3456-7890-abcd-ef1234567890.config'
+      )
+    ).toBe(true)
+
+    // Test invalid paths
+    expect(
+      (authHelper as any).testCredentialsConfigPath(
+        '/some/path/other-config.config'
+      )
+    ).toBe(false)
+    expect(
+      (authHelper as any).testCredentialsConfigPath(
+        '/some/path/git-credentials-invalid.config'
+      )
+    ).toBe(false)
+    expect(
+      (authHelper as any).testCredentialsConfigPath(
+        '/some/path/git-credentials-.config'
+      )
+    ).toBe(false)
+    expect((authHelper as any).testCredentialsConfigPath('')).toBe(false)
+  })
 })
 
 async function setup(testName: string): Promise<void> {
@@ -715,6 +988,7 @@ async function setup(testName: string): Promise<void> {
   await fs.promises.mkdir(tempHomedir, {recursive: true})
   process.env['RUNNER_TEMP'] = runnerTemp
   process.env['HOME'] = tempHomedir
+  process.env['GITHUB_WORKSPACE'] = workspace
 
   // Create git config
   globalGitConfigPath = path.join(tempHomedir, '.gitconfig')
@@ -733,10 +1007,20 @@ async function setup(testName: string): Promise<void> {
     checkout: jest.fn(),
     checkoutDetach: jest.fn(),
     config: jest.fn(
-      async (key: string, value: string, globalConfig?: boolean) => {
+      async (
-        const configPath = globalConfig
+        key: string,
-          ? path.join(git.env['HOME'] || tempHomedir, '.gitconfig')
+        value: string,
-          : localGitConfigPath
+        globalConfig?: boolean,
+        add?: boolean,
+        configFile?: string
+      ) => {
+        const configPath =
+          configFile ||
+          (globalConfig
+            ? path.join(git.env['HOME'] || tempHomedir, '.gitconfig')
+            : localGitConfigPath)
+        // Ensure directory exists
+        await fs.promises.mkdir(path.dirname(configPath), {recursive: true})
         await fs.promises.appendFile(configPath, `\n${key} ${value}`)
       }
     ),
@@ -756,14 +1040,17 @@ async function setup(testName: string): Promise<void> {
     env: {},
     fetch: jest.fn(),
     getDefaultBranch: jest.fn(),
+    getSubmoduleConfigPaths: jest.fn(async () => []),
     getWorkingDirectory: jest.fn(() => workspace),
     init: jest.fn(),
     isDetached: jest.fn(),
     lfsFetch: jest.fn(),
     lfsInstall: jest.fn(),
     log1: jest.fn(),
+    referenceAdd: jest.fn(),
     remoteAdd: jest.fn(),
     removeEnvironmentVariable: jest.fn((name: string) => delete git.env[name]),
+    execGit: jest.fn(),
     revParse: jest.fn(),
     setEnvironmentVariable: jest.fn((name: string, value: string) => {
       git.env[name] = value
@@ -794,8 +1081,72 @@ async function setup(testName: string): Promise<void> {
         return true
       }
     ),
+    tryConfigUnsetValue: jest.fn(
+      async (
+        key: string,
+        value: string,
+        globalConfig?: boolean,
+        configPath?: string
+      ): Promise<boolean> => {
+        const targetConfigPath =
+          configPath ||
+          (globalConfig
+            ? path.join(git.env['HOME'] || tempHomedir, '.gitconfig')
+            : localGitConfigPath)
+        let content = await fs.promises.readFile(targetConfigPath)
+        let lines = content
+          .toString()
+          .split('\n')
+          .filter(x => x)
+          .filter(x => !(x.startsWith(key) && x.includes(value)))
+        await fs.promises.writeFile(targetConfigPath, lines.join('\n'))
+        return true
+      }
+    ),
     tryDisableAutomaticGarbageCollection: jest.fn(),
     tryGetFetchUrl: jest.fn(),
+    tryGetConfigValues: jest.fn(
+      async (
+        key: string,
+        globalConfig?: boolean,
+        configPath?: string
+      ): Promise<string[]> => {
+        const targetConfigPath =
+          configPath ||
+          (globalConfig
+            ? path.join(git.env['HOME'] || tempHomedir, '.gitconfig')
+            : localGitConfigPath)
+        const content = await fs.promises.readFile(targetConfigPath)
+        const lines = content
+          .toString()
+          .split('\n')
+          .filter(x => x && x.startsWith(key))
+          .map(x => x.substring(key.length).trim())
+        return lines
+      }
+    ),
+    tryGetConfigKeys: jest.fn(
+      async (
+        pattern: string,
+        globalConfig?: boolean,
+        configPath?: string
+      ): Promise<string[]> => {
+        const targetConfigPath =
+          configPath ||
+          (globalConfig
+            ? path.join(git.env['HOME'] || tempHomedir, '.gitconfig')
+            : localGitConfigPath)
+        const content = await fs.promises.readFile(targetConfigPath)
+        const lines = content
+          .toString()
+          .split('\n')
+          .filter(x => x)
+        const keys = lines
+          .filter(x => new RegExp(pattern).test(x.split(' ')[0]))
+          .map(x => x.split(' ')[0])
+        return [...new Set(keys)] // Remove duplicates
+      }
+    ),
     tryReset: jest.fn(),
     version: jest.fn()
   }
@@ -808,6 +1159,7 @@ async function setup(testName: string): Promise<void> {
     sparseCheckout: [],
     sparseCheckoutConeMode: true,
     fetchDepth: 1,
+    fetchDepthExplicit: false,
     fetchTags: false,
     showProgress: true,
     lfs: false,
@@ -824,12 +1176,14 @@ async function setup(testName: string): Promise<void> {
     sshUser: '',
     workflowOrganizationId: 123456,
     setSafeDirectory: true,
-    githubServerUrl: githubServerUrl
+    githubServerUrl: githubServerUrl,
+    referenceCache: ''
   }
 }
 
 async function getActualSshKeyPath(): Promise<string> {
   let actualTempFiles = (await fs.promises.readdir(runnerTemp))
+    .filter(x => !x.startsWith('git-credentials-')) // Exclude credentials config file
     .sort()
     .map(x => path.join(runnerTemp, x))
   if (actualTempFiles.length === 0) {
@@ -843,6 +1197,7 @@ async function getActualSshKeyPath(): Promise<string> {
 
 async function getActualSshKnownHostsPath(): Promise<string> {
   let actualTempFiles = (await fs.promises.readdir(runnerTemp))
+    .filter(x => !x.startsWith('git-credentials-')) // Exclude credentials config file
     .sort()
     .map(x => path.join(runnerTemp, x))
   if (actualTempFiles.length === 0) {

__test__/git-cache-helper.test.ts

@@ -0,0 +1,109 @@
+import * as path from 'path'
+import * as fs from 'fs'
+import * as io from '@actions/io'
+import { GitCacheHelper } from '../src/git-cache-helper'
+import { IGitCommandManager } from '../src/git-command-manager'
+
+describe('GitCacheHelper', () => {
+  let cacheHelper: GitCacheHelper
+  let mockGit: jest.Mocked<IGitCommandManager>
+
+  const cacheDir = path.join(__dirname, 'test-cache')
+
+  beforeEach(async () => {
+    cacheHelper = new GitCacheHelper(cacheDir)
+    mockGit = {
+      execGit: jest.fn().mockImplementation(async (args) => {
+        // If git clone is called, simulate creating the destination dir
+        if (args && args.includes('clone')) {
+          const dest = args.find((a: string) => a.includes('.tmp.'));
+          if (dest) {
+            await io.mkdirP(dest);
+          } else {
+            console.log('No .tmp. found in args:', args);
+          }
+        }
+        return { exitCode: 0, stdout: '', stderr: '' };
+      }),
+      gitEnv: {}
+    } as any
+
+    await io.mkdirP(cacheDir)
+  })
+
+  afterEach(async () => {
+    await io.rmRF(cacheDir)
+  })
+
+  it('generates a consistent, short, and safe cache directory name', () => {
+    const url1 = 'https://github.com/mwyraz/forgejo-actions-checkout.git'
+    const name1 = (cacheHelper as any).generateCacheDirName(url1)
+    
+    // Check structure: safe string + hash
+    expect(name1).toMatch(/^https___github_com_mwyraz_forgejo_actions_checkout_git_[0-9a-f]{8}\.git$/)
+
+    // Same URL should produce the same directory name
+    const url1_duplicate = 'https://github.com/mwyraz/forgejo-actions-checkout.git'
+    expect((cacheHelper as any).generateCacheDirName(url1_duplicate)).toBe(name1)
+
+    // Different URL should produce a different directory name
+    const url2 = 'https://github.com/mwyraz/forgejo-actions-checkout-other.git'
+    expect((cacheHelper as any).generateCacheDirName(url2)).not.toBe(name1)
+
+    // SSH URL
+    const url3 = 'git@github.com:auth/repo.git'
+    const name3 = (cacheHelper as any).generateCacheDirName(url3)
+    expect(name3).toMatch(/^git_github_com_auth_repo_git_[0-9a-f]{8}\.git$/)
+    
+    // Unclean URLs
+    const url4 = 'https://github.com/foo/bar.git?v=1'
+    const name4 = (cacheHelper as any).generateCacheDirName(url4)
+    expect(name4).toMatch(/^https___github_com_foo_bar_git_v_1_[0-9a-f]{8}\.git$/)
+  })
+
+  it('sets up a cache directory if it does not exist', async () => {
+    const repositoryUrl = 'https://github.com/mwyraz/test-repo.git'
+    const resultPath = await cacheHelper.setupCache(mockGit, repositoryUrl)
+
+    const expectedName = (cacheHelper as any).generateCacheDirName(repositoryUrl)
+    expect(resultPath).toBe(path.join(cacheDir, expectedName))
+
+    // It should have executed git clone --bare
+    expect(mockGit.execGit).toHaveBeenCalledWith(
+      expect.arrayContaining([
+        '-C',
+        cacheDir,
+        'clone',
+        '--bare',
+        repositoryUrl,
+        expect.stringContaining(`${expectedName}.tmp`) // should use tmp dir
+      ])
+    )
+  })
+
+  it('fetches updates if the cache directory already exists', async () => {
+    const repositoryUrl = 'https://github.com/mwyraz/existing-repo.git'
+    const expectedName = (cacheHelper as any).generateCacheDirName(repositoryUrl)
+    const fixedPath = path.join(cacheDir, expectedName)
+
+    // Fake existing directory
+    await io.mkdirP(path.join(fixedPath, 'objects'))
+
+    const resultPath = await cacheHelper.setupCache(mockGit, repositoryUrl)
+    expect(resultPath).toBe(fixedPath)
+
+    // It should have executed git fetch
+    expect(mockGit.execGit).toHaveBeenCalledWith(
+      expect.arrayContaining([
+        '-C',
+        fixedPath,
+        'fetch',
+        '--force',
+        '--prune',
+        '--tags',
+        'origin',
+        '+refs/heads/*:refs/heads/*'
+      ])
+    )
+  })
+})

__test__/git-command-manager.test.ts

@@ -108,7 +108,7 @@ describe('Test fetchDepth and fetchTags options', () => {
     jest.restoreAllMocks()
   })
 
-  it('should call execGit with the correct arguments when fetchDepth is 0 and fetchTags is true', async () => {
+  it('should call execGit with the correct arguments when fetchDepth is 0', async () => {
     jest.spyOn(exec, 'exec').mockImplementation(mockExec)
     const workingDirectory = 'test'
     const lfs = false
@@ -122,45 +122,7 @@ describe('Test fetchDepth and fetchTags options', () => {
     const refSpec = ['refspec1', 'refspec2']
     const options = {
       filter: 'filterValue',
-      fetchDepth: 0,
+      fetchDepth: 0
-      fetchTags: true
-    }
-
-    await git.fetch(refSpec, options)
-
-    expect(mockExec).toHaveBeenCalledWith(
-      expect.any(String),
-      [
-        '-c',
-        'protocol.version=2',
-        'fetch',
-        '--prune',
-        '--no-recurse-submodules',
-        '--filter=filterValue',
-        'origin',
-        'refspec1',
-        'refspec2'
-      ],
-      expect.any(Object)
-    )
-  })
-
-  it('should call execGit with the correct arguments when fetchDepth is 0 and fetchTags is false', 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', 'refspec2']
-    const options = {
-      filter: 'filterValue',
-      fetchDepth: 0,
-      fetchTags: false
     }
 
     await git.fetch(refSpec, options)
@@ -183,7 +145,45 @@ describe('Test fetchDepth and fetchTags options', () => {
     )
   })
 
-  it('should call execGit with the correct arguments when fetchDepth is 1 and fetchTags is false', async () => {
+  it('should call execGit with the correct arguments when fetchDepth is 0 and refSpec includes tags', 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', 'refspec2', '+refs/tags/*:refs/tags/*']
+    const options = {
+      filter: 'filterValue',
+      fetchDepth: 0
+    }
+
+    await git.fetch(refSpec, options)
+
+    expect(mockExec).toHaveBeenCalledWith(
+      expect.any(String),
+      [
+        '-c',
+        'protocol.version=2',
+        'fetch',
+        '--no-tags',
+        '--prune',
+        '--no-recurse-submodules',
+        '--filter=filterValue',
+        'origin',
+        'refspec1',
+        'refspec2',
+        '+refs/tags/*:refs/tags/*'
+      ],
+      expect.any(Object)
+    )
+  })
+
+  it('should call execGit with the correct arguments when fetchDepth is 1', async () => {
     jest.spyOn(exec, 'exec').mockImplementation(mockExec)
 
     const workingDirectory = 'test'
@@ -197,8 +197,7 @@ describe('Test fetchDepth and fetchTags options', () => {
     const refSpec = ['refspec1', 'refspec2']
     const options = {
       filter: 'filterValue',
-      fetchDepth: 1,
+      fetchDepth: 1
-      fetchTags: false
     }
 
     await git.fetch(refSpec, options)
@@ -222,7 +221,7 @@ describe('Test fetchDepth and fetchTags options', () => {
     )
   })
 
-  it('should call execGit with the correct arguments when fetchDepth is 1 and fetchTags is true', async () => {
+  it('should call execGit with the correct arguments when fetchDepth is 1 and refSpec includes tags', async () => {
     jest.spyOn(exec, 'exec').mockImplementation(mockExec)
 
     const workingDirectory = 'test'
@@ -233,11 +232,10 @@ describe('Test fetchDepth and fetchTags options', () => {
       lfs,
       doSparseCheckout
     )
-    const refSpec = ['refspec1', 'refspec2']
+    const refSpec = ['refspec1', 'refspec2', '+refs/tags/*:refs/tags/*']
     const options = {
       filter: 'filterValue',
-      fetchDepth: 1,
+      fetchDepth: 1
-      fetchTags: true
     }
 
     await git.fetch(refSpec, options)
@@ -248,13 +246,15 @@ describe('Test fetchDepth and fetchTags options', () => {
         '-c',
         'protocol.version=2',
         'fetch',
+        '--no-tags',
         '--prune',
         '--no-recurse-submodules',
         '--filter=filterValue',
         '--depth=1',
         'origin',
         'refspec1',
-        'refspec2'
+        'refspec2',
+        '+refs/tags/*:refs/tags/*'
       ],
       expect.any(Object)
     )
@@ -338,7 +338,7 @@ describe('Test fetchDepth and fetchTags options', () => {
     )
   })
 
-  it('should call execGit with the correct arguments when fetchTags is true and showProgress is true', async () => {
+  it('should call execGit with the correct arguments when showProgress is true and refSpec includes tags', async () => {
     jest.spyOn(exec, 'exec').mockImplementation(mockExec)
 
     const workingDirectory = 'test'
@@ -349,10 +349,9 @@ describe('Test fetchDepth and fetchTags options', () => {
       lfs,
       doSparseCheckout
     )
-    const refSpec = ['refspec1', 'refspec2']
+    const refSpec = ['refspec1', 'refspec2', '+refs/tags/*:refs/tags/*']
     const options = {
       filter: 'filterValue',
-      fetchTags: true,
       showProgress: true
     }
 
@@ -364,15 +363,134 @@ describe('Test fetchDepth and fetchTags options', () => {
         '-c',
         'protocol.version=2',
         'fetch',
+        '--no-tags',
         '--prune',
         '--no-recurse-submodules',
         '--progress',
         '--filter=filterValue',
         'origin',
         'refspec1',
-        'refspec2'
+        'refspec2',
+        '+refs/tags/*:refs/tags/*'
       ],
       expect.any(Object)
     )
   })
 })
+
+describe('git user-agent with orchestration ID', () => {
+  beforeEach(async () => {
+    jest.spyOn(fshelper, 'fileExistsSync').mockImplementation(jest.fn())
+    jest.spyOn(fshelper, 'directoryExistsSync').mockImplementation(jest.fn())
+  })
+
+  afterEach(() => {
+    jest.restoreAllMocks()
+    // Clean up environment variable to prevent test pollution
+    delete process.env['ACTIONS_ORCHESTRATION_ID']
+  })
+
+  it('should include orchestration ID in user-agent when ACTIONS_ORCHESTRATION_ID is set', async () => {
+    const orchId = 'test-orch-id-12345'
+    process.env['ACTIONS_ORCHESTRATION_ID'] = orchId
+
+    let capturedEnv: any = null
+    mockExec.mockImplementation((path, args, options) => {
+      if (args.includes('version')) {
+        options.listeners.stdout(Buffer.from('2.18'))
+      }
+      // Capture env on any command
+      capturedEnv = options.env
+      return 0
+    })
+    jest.spyOn(exec, 'exec').mockImplementation(mockExec)
+
+    const workingDirectory = 'test'
+    const lfs = false
+    const doSparseCheckout = false
+    git = await commandManager.createCommandManager(
+      workingDirectory,
+      lfs,
+      doSparseCheckout
+    )
+
+    // Call a git command to trigger env capture after user-agent is set
+    await git.init()
+
+    // Verify the user agent includes the orchestration ID
+    expect(git).toBeDefined()
+    expect(capturedEnv).toBeDefined()
+    expect(capturedEnv['GIT_HTTP_USER_AGENT']).toBe(
+      `git/2.18 (github-actions-checkout) actions_orchestration_id/${orchId}`
+    )
+  })
+
+  it('should sanitize invalid characters in orchestration ID', async () => {
+    const orchId = 'test (with) special/chars'
+    process.env['ACTIONS_ORCHESTRATION_ID'] = orchId
+
+    let capturedEnv: any = null
+    mockExec.mockImplementation((path, args, options) => {
+      if (args.includes('version')) {
+        options.listeners.stdout(Buffer.from('2.18'))
+      }
+      // Capture env on any command
+      capturedEnv = options.env
+      return 0
+    })
+    jest.spyOn(exec, 'exec').mockImplementation(mockExec)
+
+    const workingDirectory = 'test'
+    const lfs = false
+    const doSparseCheckout = false
+    git = await commandManager.createCommandManager(
+      workingDirectory,
+      lfs,
+      doSparseCheckout
+    )
+
+    // Call a git command to trigger env capture after user-agent is set
+    await git.init()
+
+    // Verify the user agent has sanitized orchestration ID (spaces, parentheses, slash replaced)
+    expect(git).toBeDefined()
+    expect(capturedEnv).toBeDefined()
+    expect(capturedEnv['GIT_HTTP_USER_AGENT']).toBe(
+      'git/2.18 (github-actions-checkout) actions_orchestration_id/test__with__special_chars'
+    )
+  })
+
+  it('should not modify user-agent when ACTIONS_ORCHESTRATION_ID is not set', async () => {
+    delete process.env['ACTIONS_ORCHESTRATION_ID']
+
+    let capturedEnv: any = null
+    mockExec.mockImplementation((path, args, options) => {
+      if (args.includes('version')) {
+        options.listeners.stdout(Buffer.from('2.18'))
+      }
+      // Capture env on any command
+      capturedEnv = options.env
+      return 0
+    })
+    jest.spyOn(exec, 'exec').mockImplementation(mockExec)
+
+    const workingDirectory = 'test'
+    const lfs = false
+    const doSparseCheckout = false
+    git = await commandManager.createCommandManager(
+      workingDirectory,
+      lfs,
+      doSparseCheckout
+    )
+
+    // Call a git command to trigger env capture after user-agent is set
+    await git.init()
+
+    // Verify the user agent does NOT contain orchestration ID
+    expect(git).toBeDefined()
+    expect(capturedEnv).toBeDefined()
+    expect(capturedEnv['GIT_HTTP_USER_AGENT']).toBe(
+      'git/2.18 (github-actions-checkout)'
+    )
+  })
+})

__test__/git-directory-helper.test.ts

@@ -471,14 +471,17 @@ async function setup(testName: string): Promise<void> {
     configExists: jest.fn(),
     fetch: jest.fn(),
     getDefaultBranch: jest.fn(),
+    getSubmoduleConfigPaths: jest.fn(async () => []),
     getWorkingDirectory: jest.fn(() => repositoryPath),
     init: jest.fn(),
     isDetached: jest.fn(),
     lfsFetch: jest.fn(),
     lfsInstall: jest.fn(),
     log1: jest.fn(),
+    referenceAdd: jest.fn(),
     remoteAdd: jest.fn(),
     removeEnvironmentVariable: jest.fn(),
+    execGit: jest.fn(),
     revParse: jest.fn(),
     setEnvironmentVariable: jest.fn(),
     shaExists: jest.fn(),
@@ -493,12 +496,15 @@ async function setup(testName: string): Promise<void> {
       return true
     }),
     tryConfigUnset: jest.fn(),
+    tryConfigUnsetValue: jest.fn(),
     tryDisableAutomaticGarbageCollection: jest.fn(),
     tryGetFetchUrl: jest.fn(async () => {
       // Sanity check - this function shouldn't be called when the .git directory doesn't exist
       await fs.promises.stat(path.join(repositoryPath, '.git'))
       return repositoryUrl
     }),
+    tryGetConfigValues: jest.fn(),
+    tryGetConfigKeys: jest.fn(),
     tryReset: jest.fn(async () => {
       return true
     }),

__test__/git-source-provider.test.ts

@@ -0,0 +1,88 @@
+import * as core from '@actions/core'
+import {adjustFetchDepthForCache} from '../src/git-source-provider'
+
+// Mock @actions/core
+jest.mock('@actions/core')
+
+describe('adjustFetchDepthForCache', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  it('does nothing when referenceCache is not set', () => {
+    const settings = {
+      referenceCache: '',
+      fetchDepth: 1,
+      fetchDepthExplicit: false
+    }
+    adjustFetchDepthForCache(settings)
+    expect(settings.fetchDepth).toBe(1)
+    expect(core.warning).not.toHaveBeenCalled()
+    expect(core.info).not.toHaveBeenCalled()
+  })
+
+  it('overrides fetchDepth to 0 when referenceCache is set and fetchDepth is default', () => {
+    const settings = {
+      referenceCache: '/cache/git-reference-cache',
+      fetchDepth: 1,
+      fetchDepthExplicit: false
+    }
+    adjustFetchDepthForCache(settings)
+    expect(settings.fetchDepth).toBe(0)
+    expect(core.info).toHaveBeenCalledWith(
+      expect.stringContaining('Overriding fetch-depth from 1 to 0')
+    )
+    expect(core.warning).not.toHaveBeenCalled()
+  })
+
+  it('warns but keeps fetchDepth when referenceCache is set and fetchDepth is explicit', () => {
+    const settings = {
+      referenceCache: '/cache/git-reference-cache',
+      fetchDepth: 1,
+      fetchDepthExplicit: true
+    }
+    adjustFetchDepthForCache(settings)
+    expect(settings.fetchDepth).toBe(1)
+    expect(core.warning).toHaveBeenCalledWith(
+      expect.stringContaining("'fetch-depth: 1' is set with reference-cache enabled")
+    )
+    expect(core.info).not.toHaveBeenCalled()
+  })
+
+  it('does nothing when referenceCache is set and fetchDepth is already 0 (explicit)', () => {
+    const settings = {
+      referenceCache: '/cache/git-reference-cache',
+      fetchDepth: 0,
+      fetchDepthExplicit: true
+    }
+    adjustFetchDepthForCache(settings)
+    expect(settings.fetchDepth).toBe(0)
+    expect(core.warning).not.toHaveBeenCalled()
+    expect(core.info).not.toHaveBeenCalled()
+  })
+
+  it('does nothing when referenceCache is set and fetchDepth is already 0 (default)', () => {
+    const settings = {
+      referenceCache: '/cache/git-reference-cache',
+      fetchDepth: 0,
+      fetchDepthExplicit: false
+    }
+    adjustFetchDepthForCache(settings)
+    expect(settings.fetchDepth).toBe(0)
+    expect(core.warning).not.toHaveBeenCalled()
+    expect(core.info).not.toHaveBeenCalled()
+  })
+
+  it('warns with correct depth value when explicit fetchDepth is > 1', () => {
+    const settings = {
+      referenceCache: '/cache/git-reference-cache',
+      fetchDepth: 42,
+      fetchDepthExplicit: true
+    }
+    adjustFetchDepthForCache(settings)
+    expect(settings.fetchDepth).toBe(42)
+    expect(core.warning).toHaveBeenCalledWith(
+      expect.stringContaining("'fetch-depth: 42' is set with reference-cache enabled")
+    )
+  })
+})

__test__/input-helper.test.ts

@@ -91,6 +91,7 @@ describe('input-helper tests', () => {
     expect(settings.repositoryOwner).toBe('some-owner')
     expect(settings.repositoryPath).toBe(gitHubWorkspace)
     expect(settings.setSafeDirectory).toBe(true)
+    expect(settings.referenceCache || '').toBe('')
   })
 
   it('qualifies ref', async () => {

__test__/ref-helper.test.ts

@@ -152,7 +152,22 @@ describe('ref-helper tests', () => {
   it('getRefSpec sha + refs/tags/', async () => {
     const refSpec = refHelper.getRefSpec('refs/tags/my-tag', commit)
     expect(refSpec.length).toBe(1)
-    expect(refSpec[0]).toBe(`+${commit}:refs/tags/my-tag`)
+    expect(refSpec[0]).toBe(`+refs/tags/my-tag:refs/tags/my-tag`)
+  })
+
+  it('getRefSpec sha + refs/tags/ with fetchTags', async () => {
+    // When fetchTags is true, only include tags wildcard (specific tag is redundant)
+    const refSpec = refHelper.getRefSpec('refs/tags/my-tag', commit, true)
+    expect(refSpec.length).toBe(1)
+    expect(refSpec[0]).toBe('+refs/tags/*:refs/tags/*')
+  })
+
+  it('getRefSpec sha + refs/heads/ with fetchTags', async () => {
+    // When fetchTags is true, include both the branch refspec and tags wildcard
+    const refSpec = refHelper.getRefSpec('refs/heads/my/branch', commit, true)
+    expect(refSpec.length).toBe(2)
+    expect(refSpec[0]).toBe('+refs/tags/*:refs/tags/*')
+    expect(refSpec[1]).toBe(`+${commit}:refs/remotes/origin/my/branch`)
   })
 
   it('getRefSpec sha only', async () => {
@@ -168,6 +183,14 @@ describe('ref-helper tests', () => {
     expect(refSpec[1]).toBe('+refs/tags/my-ref*:refs/tags/my-ref*')
   })
 
+  it('getRefSpec unqualified ref only with fetchTags', async () => {
+    // When fetchTags is true, skip specific tag pattern since wildcard covers all
+    const refSpec = refHelper.getRefSpec('my-ref', '', true)
+    expect(refSpec.length).toBe(2)
+    expect(refSpec[0]).toBe('+refs/tags/*:refs/tags/*')
+    expect(refSpec[1]).toBe('+refs/heads/my-ref*:refs/remotes/origin/my-ref*')
+  })
+
   it('getRefSpec refs/heads/ only', async () => {
     const refSpec = refHelper.getRefSpec('refs/heads/my/branch', '')
     expect(refSpec.length).toBe(1)
@@ -187,4 +210,21 @@ describe('ref-helper tests', () => {
     expect(refSpec.length).toBe(1)
     expect(refSpec[0]).toBe('+refs/tags/my-tag:refs/tags/my-tag')
   })
+
+  it('getRefSpec refs/tags/ only with fetchTags', async () => {
+    // When fetchTags is true, only include tags wildcard (specific tag is redundant)
+    const refSpec = refHelper.getRefSpec('refs/tags/my-tag', '', true)
+    expect(refSpec.length).toBe(1)
+    expect(refSpec[0]).toBe('+refs/tags/*:refs/tags/*')
+  })
+
+  it('getRefSpec refs/heads/ only with fetchTags', async () => {
+    // When fetchTags is true, include both the branch refspec and tags wildcard
+    const refSpec = refHelper.getRefSpec('refs/heads/my/branch', '', true)
+    expect(refSpec.length).toBe(2)
+    expect(refSpec[0]).toBe('+refs/tags/*:refs/tags/*')
+    expect(refSpec[1]).toBe(
+      '+refs/heads/my/branch:refs/remotes/origin/my/branch'
+    )
+  })
 })

__test__/verify-fetch-tags.sh

@@ -0,0 +1,9 @@
+#!/bin/sh
+
+# Verify tags were fetched
+TAG_COUNT=$(git -C ./fetch-tags-test tag | wc -l)
+if [ "$TAG_COUNT" -eq 0 ]; then
+    echo "Expected tags to be fetched, but found none"
+    exit 1
+fi
+echo "Found $TAG_COUNT tags"

__test__/verify-submodules-recursive.sh

@@ -17,7 +17,7 @@ fi
 
 echo "Testing persisted credential"
 pushd ./submodules-recursive/submodule-level-1/submodule-level-2
-git config --local --name-only --get-regexp http.+extraheader && git fetch
+git config --local --includes --name-only --get-regexp http.+extraheader && git fetch
 if [ "$?" != "0" ]; then
     echo "Failed to validate persisted credential"
     popd

__test__/verify-submodules-true.sh

@@ -17,7 +17,7 @@ fi
 
 echo "Testing persisted credential"
 pushd ./submodules-true/submodule-level-1
-git config --local --name-only --get-regexp http.+extraheader && git fetch
+git config --local --includes --name-only --get-regexp http.+extraheader && git fetch
 if [ "$?" != "0" ]; then
     echo "Failed to validate persisted credential"
     popd

__test__/verify-worktree.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+set -e
+
+# Verify worktree credentials
+# This test verifies that git credentials work in worktrees created after checkout
+# Usage: verify-worktree.sh <checkout-path> <worktree-name>
+
+CHECKOUT_PATH="$1"
+WORKTREE_NAME="$2"
+
+if [ -z "$CHECKOUT_PATH" ] || [ -z "$WORKTREE_NAME" ]; then
+  echo "Usage: verify-worktree.sh <checkout-path> <worktree-name>"
+  exit 1
+fi
+
+cd "$CHECKOUT_PATH"
+
+# Add safe directory for container environments
+git config --global --add safe.directory "*" 2>/dev/null || true
+
+# Show the includeIf configuration
+echo "Git config includeIf entries:"
+git config --list --show-origin | grep -i include || true
+
+# Create the worktree
+echo "Creating worktree..."
+git worktree add "../$WORKTREE_NAME" HEAD --detach
+
+# Change to worktree directory
+cd "../$WORKTREE_NAME"
+
+# Verify we're in a worktree
+echo "Verifying worktree gitdir:"
+cat .git
+
+# Verify credentials are available in worktree by checking extraheader is configured
+echo "Checking credentials in worktree..."
+if git config --list --show-origin | grep -q "extraheader"; then
+  echo "Credentials are configured in worktree"
+else
+  echo "ERROR: Credentials are NOT configured in worktree"
+  echo "Full git config:"
+  git config --list --show-origin
+  exit 1
+fi
+
+# Verify fetch works in the worktree
+echo "Fetching in worktree..."
+git fetch origin
+
+echo "Worktree credentials test passed!"

action.yml

@@ -98,12 +98,18 @@ inputs:
   github-server-url:
     description: The base URL for the GitHub instance that you are trying to clone from, will use environment defaults to fetch from the same instance that the workflow is running from unless specified. Example URLs are https://github.com or https://my-ghes-server.example.com
     required: false
+  reference-cache:
+    description: >
+      Path to a local directory used as a reference cache for Git clones. Over time,
+      this directory will contain bare clones of the checked-out repositories (and their submodules).
+      Using this significantly reduces network bandwidth and speeds up clones.
+    required: false
 outputs:
   ref:
     description: 'The branch, tag or SHA that was checked out'
   commit:
     description: 'The commit SHA that was checked out'
 runs:
-  using: node20
+  using: node24
   main: dist/index.js
   post: dist/index.js

adrs/2303-reference-cache.md

@@ -0,0 +1,37 @@
+# Reference Cache für schnelle Checkouts
+
+## Zusammenfassung
+Einführung eines lokal verwalteten Git-Referenz-Caches für Haupt-Repositories und Submodule, um Netzwerk-Traffic und Checkout-Zeiten auf persistenten Runnern (z.B. Self-Hosted) massiv zu reduzieren.
+
+## Implementierungsplan
+
+1. **Inputs:**
+   - In `action.yml` einen neuen Input `reference-cache` (Pfad zum Cache-Verzeichnis) hinzufügen. Default ist leer.
+   - In `src/git-source-settings.ts` und `src/input-helper.ts` den Input auslesen und bereitstellen (`settings.referenceCache`).
+
+2. **Cache Manager (`src/git-cache-helper.ts`):**
+   - Eine neue Klasse/Helper-Logik, die das Erstellen (`git clone --bare`) und Aktualisieren (`git fetch --force`) von Bare Cache-Repos übernimmt.
+   - **Namenskonvention Cache-Verzeichnis:** Damit Admin-Lesbarkeit und Kollisionsfreiheit gewährleistet sind, wird das Cache-Verzeichnis aus der Repository-URL gebildet:
+     - Alle Sonderzeichen in der URL durch `_` ersetzen.
+     - Ein kurzer Hash (z. B. erste 8 Zeichen des SHA256) der echten URL zur Eindeutigkeit anhängen.
+     - Beispiel: `<reference-cache>/https___github_com_actions_checkout_8f9b1c2a.git`
+
+3. **Haupt-Repo Checkout (`src/git-source-provider.ts`):**
+   - Vor dem Setup des Checkouts prüfen, ob `reference-cache` gesetzt ist.
+   - Wenn ja: den Cache-Ordner für die Haupt-URL aktualisieren/anlegen.
+   - Nach dem initialen `git.init()` den Pfad in `.git/objects/info/alternates` schreiben, der auf das `objects`-Verzeichnis des Cache-Ordners zeigt.
+
+4. **Submodule Checkouts (Iterativ statt monolithisch):**
+   - Der aktuelle Befehl `git submodule update --recursive` funktioniert nicht out-of-the-box mit `reference`, wenn jedes Submodul seinen individuellen Referenz-Cache benötigt.
+   - Wenn `reference-cache` aktiv ist und Submodule initialisiert werden sollen:
+     - Lese `.gitmodules` aus (alle Sub-URLs ermitteln).
+     - Für jedes Submodul den Cache (genauso wie in Step 2) anlegen oder aktualisieren.
+     - Submodul einzeln auschecken per `git submodule update --init --reference <cache-pfad/.git> <pfad>`.
+     - Bei der Einstellung `recursive`: In jedes Submodul-Verzeichnis wechseln und den Vorgang für `.gitmodules` rekursiv auf Skript-Ebene durchführen (anstatt Git's `--recursive` Flag einfach weiterzugeben).
+
+## Akzeptanzkriterien
+1. **Neue Option konfigurierbar**: Der Input `reference-cache` kann übergeben werden, der Code reagiert darauf.
+2. **Ordnerstruktur korrekt**: Der Cache-Ordner für das Hauptrepo und Submodule erhält Namen nach der "URL_Sonderzeichen_Ersetzt+SHA_Cut"-Logik.
+3. **Bandbreite gespart / Alternates genutzt**: Beim Hauptcheckout wird eine `.git/objects/info/alternates`-Datei mit Pfad zum lokalen Cache erzeugt. Danach ausgeführte `git fetch`-Befehle sind signifikant schneller bzw. laden deutlich weniger Bytes herunter.
+4. **Submodule erhalten Caches**: Auch tiefe (rekursive) Submodule profitieren für deren jeweilige Remote-URL vom Cache, da pro Submodul ein passender `--reference` Punkt dynamisch berechnet und übergeben wird.
+5. **Kein --dissociate**: Aus Performance-Gründen bleibt der Arbeitsordner an den Cache gebunden (`git repack` ist zeitaufwändig). Fällt der Cache weg, muss der Workspace erst einmal neu erzeugt werden (was bei Action Runnern die Norm ist, falls es nicht ohnehin "single-use" Runner sind).

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "checkout",
-  "version": "4.3.0",
+  "version": "5.0.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "checkout",
-      "version": "4.3.0",
+      "version": "5.0.0",
       "license": "MIT",
       "dependencies": {
         "@actions/core": "^1.10.1",
@@ -18,7 +18,8 @@
       },
       "devDependencies": {
         "@types/jest": "^29.5.12",
-        "@types/node": "^20.12.12",
+        "@types/node": "^24.1.0",
+        "@types/proper-lockfile": "^4.1.4",
         "@types/uuid": "^9.0.8",
         "@typescript-eslint/eslint-plugin": "^7.9.0",
         "@typescript-eslint/parser": "^7.9.0",
@@ -30,6 +31,7 @@
         "jest-circus": "^29.7.0",
         "js-yaml": "^4.1.0",
         "prettier": "^3.3.3",
+        "proper-lockfile": "^4.1.2",
         "ts-jest": "^29.2.5",
         "typescript": "^5.5.4"
       }
@@ -1515,14 +1517,31 @@
       "dev": true
     },
     "node_modules/@types/node": {
-      "version": "20.12.12",
+      "version": "24.1.0",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-20.12.12.tgz",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-24.1.0.tgz",
-      "integrity": "sha512-eWLDGF/FOSPtAvEqeRAQ4C8LSA7M1I7i0ky1I8U7kD1J5ITyW3AsRhQrKVoWf5pFKZ2kILsEGJhsI9r93PYnOw==",
+      "integrity": "sha512-ut5FthK5moxFKH2T1CUOC6ctR67rQRvvHdFLCD2Ql6KXmMuCrjsSsRI9UsLCm9M18BMwClv4pn327UvB7eeO1w==",
       "dev": true,
       "dependencies": {
-        "undici-types": "~5.26.4"
+        "undici-types": "~7.8.0"
       }
     },
+    "node_modules/@types/proper-lockfile": {
+      "version": "4.1.4",
+      "resolved": "https://registry.npmjs.org/@types/proper-lockfile/-/proper-lockfile-4.1.4.tgz",
+      "integrity": "sha512-uo2ABllncSqg9F1D4nugVl9v93RmjxF6LJzQLMLDdPaXCUIDPeOJ21Gbqi43xNKzBi/WQ0Q0dICqufzQbMjipQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/retry": "*"
+      }
+    },
+    "node_modules/@types/retry": {
+      "version": "0.12.5",
+      "resolved": "https://registry.npmjs.org/@types/retry/-/retry-0.12.5.tgz",
+      "integrity": "sha512-3xSjTp3v03X/lSQLkczaN9UIEwJMoMCA1+Nb5HfbJEQWogdeQIyVtTvxPXDQjZ5zws8rFQfVfRdz03ARihPJgw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/stack-utils": {
       "version": "2.0.3",
       "resolved": "https://registry.npmjs.org/@types/stack-utils/-/stack-utils-2.0.3.tgz",
@@ -5980,6 +5999,18 @@
         "node": ">= 6"
       }
     },
+    "node_modules/proper-lockfile": {
+      "version": "4.1.2",
+      "resolved": "https://registry.npmjs.org/proper-lockfile/-/proper-lockfile-4.1.2.tgz",
+      "integrity": "sha512-TjNPblN4BwAWMXU8s9AEz4JmQxnD1NNL7bNOY/AKUzyamc379FWASUhc/K1pL2noVb+XmZKLL68cjzLsiOAMaA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "graceful-fs": "^4.2.4",
+        "retry": "^0.12.0",
+        "signal-exit": "^3.0.2"
+      }
+    },
     "node_modules/punycode": {
       "version": "2.3.1",
       "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.3.1.tgz",
@@ -6135,6 +6166,16 @@
         "node": ">=10"
       }
     },
+    "node_modules/retry": {
+      "version": "0.12.0",
+      "resolved": "https://registry.npmjs.org/retry/-/retry-0.12.0.tgz",
+      "integrity": "sha512-9LkiTwjUh6rT555DtE9rTX+BKByPfrMzEAtnlEtdEwr3Nkffwiihqe2bWADg+OQRjt9gl6ICdmB/ZFDCGAtSow==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 4"
+      }
+    },
     "node_modules/reusify": {
       "version": "1.0.4",
       "resolved": "https://registry.npmjs.org/reusify/-/reusify-1.0.4.tgz",
@@ -6865,9 +6906,9 @@
       }
     },
     "node_modules/undici-types": {
-      "version": "5.26.5",
+      "version": "7.8.0",
-      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-5.26.5.tgz",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.8.0.tgz",
-      "integrity": "sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA==",
+      "integrity": "sha512-9UJ2xGDvQ43tYyVMpuHlsgApydB8ZKfVYTsLDhXkFL/6gfkp+U8xTGdh8pMJv1SpZna0zxG1DwsKZsreLbXBxw==",
       "dev": true
     },
     "node_modules/universal-user-agent": {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "checkout",
-  "version": "4.3.0",
+  "version": "5.0.0",
   "description": "checkout action",
   "main": "lib/main.js",
   "scripts": {
@@ -37,7 +37,8 @@
   },
   "devDependencies": {
     "@types/jest": "^29.5.12",
-    "@types/node": "^20.12.12",
+    "@types/node": "^24.1.0",
+    "@types/proper-lockfile": "^4.1.4",
     "@types/uuid": "^9.0.8",
     "@typescript-eslint/eslint-plugin": "^7.9.0",
     "@typescript-eslint/parser": "^7.9.0",
@@ -49,6 +50,7 @@
     "jest-circus": "^29.7.0",
     "js-yaml": "^4.1.0",
     "prettier": "^3.3.3",
+    "proper-lockfile": "^4.1.2",
     "ts-jest": "^29.2.5",
     "typescript": "^5.5.4"
   }

src/git-auth-helper.ts

@@ -21,6 +21,7 @@ export interface IGitAuthHelper {
   configureSubmoduleAuth(): Promise<void>
   configureTempGlobalConfig(): Promise<string>
   removeAuth(): Promise<void>
+  removeGlobalAuth(): Promise<void>
   removeGlobalConfig(): Promise<void>
 }
 
@@ -43,6 +44,7 @@ class GitAuthHelper {
   private sshKeyPath = ''
   private sshKnownHostsPath = ''
   private temporaryHomePath = ''
+  private credentialsConfigPath = '' // Path to separate credentials config file in RUNNER_TEMP
 
   constructor(
     gitCommandManager: IGitCommandManager,
@@ -126,16 +128,21 @@ class GitAuthHelper {
 
   async configureGlobalAuth(): Promise<void> {
     // 'configureTempGlobalConfig' noops if already set, just returns the path
-    const newGitConfigPath = await this.configureTempGlobalConfig()
+    await this.configureTempGlobalConfig()
     try {
       // Configure the token
-      await this.configureToken(newGitConfigPath, true)
+      await this.configureToken(true)
 
       // Configure HTTPS instead of SSH
       await this.git.tryConfigUnset(this.insteadOfKey, true)
       if (!this.settings.sshKey) {
         for (const insteadOfValue of this.insteadOfValues) {
-          await this.git.config(this.insteadOfKey, insteadOfValue, true, true)
+          await this.git.config(
+            this.insteadOfKey,
+            insteadOfValue,
+            true, // globalConfig?
+            true // add?
+          )
         }
       }
     } catch (err) {
@@ -150,24 +157,60 @@ class GitAuthHelper {
 
   async configureSubmoduleAuth(): Promise<void> {
     // Remove possible previous HTTPS instead of SSH
-    await this.removeGitConfig(this.insteadOfKey, true)
+    await this.removeSubmoduleGitConfig(this.insteadOfKey)
 
     if (this.settings.persistCredentials) {
-      // Configure a placeholder value. This approach avoids the credential being captured
+      // Get the credentials config file path in RUNNER_TEMP
-      // by process creation audit events, which are commonly logged. For more information,
+      const credentialsConfigPath = this.getCredentialsConfigPath()
-      // refer to https://docs.microsoft.com/en-us/windows-server/identity/ad-ds/manage/component-updates/command-line-process-auditing
+
-      const output = await this.git.submoduleForeach(
+      // Container credentials config path
-        // wrap the pipeline in quotes to make sure it's handled properly by submoduleForeach, rather than just the first part of the pipeline
+      const containerCredentialsPath = path.posix.join(
-        `sh -c "git config --local '${this.tokenConfigKey}' '${this.tokenPlaceholderConfigValue}' && git config --local --show-origin --name-only --get-regexp remote.origin.url"`,
+        '/github/runner_temp',
+        path.basename(credentialsConfigPath)
+      )
+
+      // Get submodule config file paths.
+      const configPaths = await this.git.getSubmoduleConfigPaths(
         this.settings.nestedSubmodules
       )
 
-      // Replace the placeholder
+      // For each submodule, configure includeIf entries pointing to the shared credentials file.
-      const configPaths: string[] =
+      // Configure both host and container paths to support Docker container actions.
-        output.match(/(?<=(^|\n)file:)[^\t]+(?=\tremote\.origin\.url)/g) || []
       for (const configPath of configPaths) {
-        core.debug(`Replacing token placeholder in '${configPath}'`)
+        // Submodule Git directory
-        await this.replaceTokenPlaceholder(configPath)
+        let submoduleGitDir = path.dirname(configPath) // The config file is at .git/modules/submodule-name/config
+        submoduleGitDir = submoduleGitDir.replace(/\\/g, '/') // Use forward slashes, even on Windows
+
+        // Configure host includeIf
+        await this.git.config(
+          `includeIf.gitdir:${submoduleGitDir}.path`,
+          credentialsConfigPath,
+          false, // globalConfig?
+          false, // add?
+          configPath
+        )
+
+        // Container submodule git directory
+        const githubWorkspace = process.env['GITHUB_WORKSPACE']
+        assert.ok(githubWorkspace, 'GITHUB_WORKSPACE is not defined')
+        let relativeSubmoduleGitDir = path.relative(
+          githubWorkspace,
+          submoduleGitDir
+        )
+        relativeSubmoduleGitDir = relativeSubmoduleGitDir.replace(/\\/g, '/') // Use forward slashes, even on Windows
+        const containerSubmoduleGitDir = path.posix.join(
+          '/github/workspace',
+          relativeSubmoduleGitDir
+        )
+
+        // Configure container includeIf
+        await this.git.config(
+          `includeIf.gitdir:${containerSubmoduleGitDir}.path`,
+          containerCredentialsPath,
+          false, // globalConfig?
+          false, // add?
+          configPath
+        )
       }
 
       if (this.settings.sshKey) {
@@ -193,6 +236,12 @@ class GitAuthHelper {
     await this.removeToken()
   }
 
+  async removeGlobalAuth(): Promise<void> {
+    core.debug('Removing global auth entries')
+    await this.git.tryConfigUnset('include.path', true)
+    await this.git.tryConfigUnset(this.insteadOfKey, true)
+  }
+
   async removeGlobalConfig(): Promise<void> {
     if (this.temporaryHomePath?.length > 0) {
       core.debug(`Unsetting HOME override`)
@@ -201,6 +250,10 @@ class GitAuthHelper {
     }
   }
 
+  /**
+   * Configures SSH authentication by writing the SSH key and known hosts,
+   * and setting up the GIT_SSH_COMMAND environment variable.
+   */
   private async configureSsh(): Promise<void> {
     if (!this.settings.sshKey) {
       return
@@ -272,57 +325,127 @@ class GitAuthHelper {
     }
   }
 
-  private async configureToken(
+  /**
-    configPath?: string,
+   * Configures token-based authentication by creating a credentials config file
-    globalConfig?: boolean
+   * and setting up includeIf entries to reference it.
-  ): Promise<void> {
+   * @param globalConfig Whether to configure global config instead of local
-    // Validate args
+   */
-    assert.ok(
+  private async configureToken(globalConfig?: boolean): Promise<void> {
-      (configPath && globalConfig) || (!configPath && !globalConfig),
+    // Get the credentials config file path in RUNNER_TEMP
-      'Unexpected configureToken parameter combinations'
+    const credentialsConfigPath = this.getCredentialsConfigPath()
-    )
 
-    // Default config path
+    // Write placeholder to the separate credentials config file using git config.
-    if (!configPath && !globalConfig) {
+    // This approach avoids the credential being captured by process creation audit events,
-      configPath = path.join(this.git.getWorkingDirectory(), '.git', 'config')
+    // which are commonly logged. For more information, refer to
-    }
+    // https://docs.microsoft.com/en-us/windows-server/identity/ad-ds/manage/component-updates/command-line-process-auditing
-
-    // Configure a placeholder value. This approach avoids the credential being captured
-    // by process creation audit events, which are commonly logged. For more information,
-    // refer to https://docs.microsoft.com/en-us/windows-server/identity/ad-ds/manage/component-updates/command-line-process-auditing
     await this.git.config(
       this.tokenConfigKey,
       this.tokenPlaceholderConfigValue,
-      globalConfig
+      false, // globalConfig?
+      false, // add?
+      credentialsConfigPath
     )
 
-    // Replace the placeholder
+    // Replace the placeholder in the credentials config file
-    await this.replaceTokenPlaceholder(configPath || '')
+    let content = (await fs.promises.readFile(credentialsConfigPath)).toString()
-  }
-
-  private async replaceTokenPlaceholder(configPath: string): Promise<void> {
-    assert.ok(configPath, 'configPath is not defined')
-    let content = (await fs.promises.readFile(configPath)).toString()
     const placeholderIndex = content.indexOf(this.tokenPlaceholderConfigValue)
     if (
       placeholderIndex < 0 ||
       placeholderIndex != content.lastIndexOf(this.tokenPlaceholderConfigValue)
     ) {
-      throw new Error(`Unable to replace auth placeholder in ${configPath}`)
+      throw new Error(
+        `Unable to replace auth placeholder in ${credentialsConfigPath}`
+      )
     }
     assert.ok(this.tokenConfigValue, 'tokenConfigValue is not defined')
     content = content.replace(
       this.tokenPlaceholderConfigValue,
       this.tokenConfigValue
     )
-    await fs.promises.writeFile(configPath, content)
+    await fs.promises.writeFile(credentialsConfigPath, content)
+
+    // Add include or includeIf to reference the credentials config
+    if (globalConfig) {
+      // Global config file is temporary
+      await this.git.config(
+        'include.path',
+        credentialsConfigPath,
+        true // globalConfig?
+      )
+    } else {
+      // Host git directory
+      let gitDir = path.join(this.git.getWorkingDirectory(), '.git')
+      gitDir = gitDir.replace(/\\/g, '/') // Use forward slashes, even on Windows
+
+      // Configure host includeIf
+      const hostIncludeKey = `includeIf.gitdir:${gitDir}.path`
+      await this.git.config(hostIncludeKey, credentialsConfigPath)
+
+      // Configure host includeIf for worktrees
+      const hostWorktreeIncludeKey = `includeIf.gitdir:${gitDir}/worktrees/*.path`
+      await this.git.config(hostWorktreeIncludeKey, credentialsConfigPath)
+
+      // Container git directory
+      const workingDirectory = this.git.getWorkingDirectory()
+      const githubWorkspace = process.env['GITHUB_WORKSPACE']
+      assert.ok(githubWorkspace, 'GITHUB_WORKSPACE is not defined')
+      let relativePath = path.relative(githubWorkspace, workingDirectory)
+      relativePath = relativePath.replace(/\\/g, '/') // Use forward slashes, even on Windows
+      const containerGitDir = path.posix.join(
+        '/github/workspace',
+        relativePath,
+        '.git'
+      )
+
+      // Container credentials config path
+      const containerCredentialsPath = path.posix.join(
+        '/github/runner_temp',
+        path.basename(credentialsConfigPath)
+      )
+
+      // Configure container includeIf
+      const containerIncludeKey = `includeIf.gitdir:${containerGitDir}.path`
+      await this.git.config(containerIncludeKey, containerCredentialsPath)
+
+      // Configure container includeIf for worktrees
+      const containerWorktreeIncludeKey = `includeIf.gitdir:${containerGitDir}/worktrees/*.path`
+      await this.git.config(
+        containerWorktreeIncludeKey,
+        containerCredentialsPath
+      )
+    }
   }
 
+  /**
+   * Gets or creates the path to the credentials config file in RUNNER_TEMP.
+   * @returns The absolute path to the credentials config file
+   */
+  private getCredentialsConfigPath(): string {
+    if (this.credentialsConfigPath) {
+      return this.credentialsConfigPath
+    }
+
+    const runnerTemp = process.env['RUNNER_TEMP'] || ''
+    assert.ok(runnerTemp, 'RUNNER_TEMP is not defined')
+
+    // Create a unique filename for this checkout instance
+    const configFileName = `git-credentials-${uuid()}.config`
+    this.credentialsConfigPath = path.join(runnerTemp, configFileName)
+
+    core.debug(`Credentials config path: ${this.credentialsConfigPath}`)
+    return this.credentialsConfigPath
+  }
+
+  /**
+   * Removes SSH authentication configuration by cleaning up SSH keys,
+   * known hosts files, and SSH command configurations.
+   */
   private async removeSsh(): Promise<void> {
     // SSH key
     const keyPath = this.sshKeyPath || stateHelper.SshKeyPath
     if (keyPath) {
       try {
+        core.info(`Removing SSH key '${keyPath}'`)
         await io.rmRF(keyPath)
       } catch (err) {
         core.debug(`${(err as any)?.message ?? err}`)
@@ -335,40 +458,149 @@ class GitAuthHelper {
       this.sshKnownHostsPath || stateHelper.SshKnownHostsPath
     if (knownHostsPath) {
       try {
+        core.info(`Removing SSH known hosts '${knownHostsPath}'`)
         await io.rmRF(knownHostsPath)
-      } catch {
+      } catch (err) {
-        // Intentionally empty
+        core.debug(`${(err as any)?.message ?? err}`)
+        core.warning(`Failed to remove SSH known hosts '${knownHostsPath}'`)
       }
     }
 
     // SSH command
+    core.info('Removing SSH command configuration')
     await this.removeGitConfig(SSH_COMMAND_KEY)
+    await this.removeSubmoduleGitConfig(SSH_COMMAND_KEY)
   }
 
+  /**
+   * Removes token-based authentication by cleaning up HTTP headers,
+   * includeIf entries, and credentials config files.
+   */
   private async removeToken(): Promise<void> {
-    // HTTP extra header
+    // Remove HTTP extra header
+    core.info('Removing HTTP extra header')
     await this.removeGitConfig(this.tokenConfigKey)
-  }
+    await this.removeSubmoduleGitConfig(this.tokenConfigKey)
 
-  private async removeGitConfig(
+    // Collect credentials config paths that need to be removed
-    configKey: string,
+    const credentialsPaths = new Set<string>()
-    submoduleOnly: boolean = false
+
-  ): Promise<void> {
+    // Remove includeIf entries that point to git-credentials-*.config files
-    if (!submoduleOnly) {
+    core.info('Removing includeIf entries pointing to credentials config files')
-      if (
+    const mainCredentialsPaths = await this.removeIncludeIfCredentials()
-        (await this.git.configExists(configKey)) &&
+    mainCredentialsPaths.forEach(path => credentialsPaths.add(path))
-        !(await this.git.tryConfigUnset(configKey))
+
-      ) {
+    // Remove submodule includeIf entries that point to git-credentials-*.config files
-        // Load the config contents
+    const submoduleConfigPaths = await this.git.getSubmoduleConfigPaths(true)
-        core.warning(`Failed to remove '${configKey}' from the git config`)
+    for (const configPath of submoduleConfigPaths) {
-      }
+      const submoduleCredentialsPaths =
+        await this.removeIncludeIfCredentials(configPath)
+      submoduleCredentialsPaths.forEach(path => credentialsPaths.add(path))
     }
 
+    // Remove credentials config files
+    for (const credentialsPath of credentialsPaths) {
+      // Only remove credentials config files if they are under RUNNER_TEMP
+      const runnerTemp = process.env['RUNNER_TEMP']
+      assert.ok(runnerTemp, 'RUNNER_TEMP is not defined')
+      if (credentialsPath.startsWith(runnerTemp)) {
+        try {
+          core.info(`Removing credentials config '${credentialsPath}'`)
+          await io.rmRF(credentialsPath)
+        } catch (err) {
+          core.debug(`${(err as any)?.message ?? err}`)
+          core.warning(
+            `Failed to remove credentials config '${credentialsPath}'`
+          )
+        }
+      } else {
+        core.debug(
+          `Skipping removal of credentials config '${credentialsPath}' - not under RUNNER_TEMP`
+        )
+      }
+    }
+  }
+
+  /**
+   * Removes a git config key from the local repository config.
+   * @param configKey The git config key to remove
+   */
+  private async removeGitConfig(configKey: string): Promise<void> {
+    if (
+      (await this.git.configExists(configKey)) &&
+      !(await this.git.tryConfigUnset(configKey))
+    ) {
+      // Load the config contents
+      core.warning(`Failed to remove '${configKey}' from the git config`)
+    }
+  }
+
+  /**
+   * Removes a git config key from all submodule configs.
+   * @param configKey The git config key to remove
+   */
+  private async removeSubmoduleGitConfig(configKey: string): Promise<void> {
     const pattern = regexpHelper.escape(configKey)
     await this.git.submoduleForeach(
-      // wrap the pipeline in quotes to make sure it's handled properly by submoduleForeach, rather than just the first part of the pipeline
+      // Wrap the pipeline in quotes to make sure it's handled properly by submoduleForeach, rather than just the first part of the pipeline.
       `sh -c "git config --local --name-only --get-regexp '${pattern}' && git config --local --unset-all '${configKey}' || :"`,
       true
     )
   }
+
+  /**
+   * Removes includeIf entries that point to git-credentials-*.config files.
+   * @param configPath Optional path to a specific git config file to operate on
+   * @returns Array of unique credentials config file paths that were found and removed
+   */
+  private async removeIncludeIfCredentials(
+    configPath?: string
+  ): Promise<string[]> {
+    const credentialsPaths = new Set<string>()
+
+    try {
+      // Get all includeIf.gitdir keys
+      const keys = await this.git.tryGetConfigKeys(
+        '^includeIf\\.gitdir:',
+        false, // globalConfig?
+        configPath
+      )
+
+      for (const key of keys) {
+        // Get all values for this key
+        const values = await this.git.tryGetConfigValues(
+          key,
+          false, // globalConfig?
+          configPath
+        )
+        if (values.length > 0) {
+          // Remove only values that match git-credentials-<uuid>.config pattern
+          for (const value of values) {
+            if (this.testCredentialsConfigPath(value)) {
+              credentialsPaths.add(value)
+              await this.git.tryConfigUnsetValue(key, value, false, configPath)
+            }
+          }
+        }
+      }
+    } catch (err) {
+      // Ignore errors - this is cleanup code
+      if (configPath) {
+        core.debug(`Error during includeIf cleanup for ${configPath}: ${err}`)
+      } else {
+        core.debug(`Error during includeIf cleanup: ${err}`)
+      }
+    }
+
+    return Array.from(credentialsPaths)
+  }
+
+  /**
+   * Tests if a path matches the git-credentials-*.config pattern.
+   * @param path The path to test
+   * @returns True if the path matches the credentials config pattern
+   */
+  private testCredentialsConfigPath(path: string): boolean {
+    return /git-credentials-[0-9a-f-]+\.config$/i.test(path)
+  }
 }

src/git-cache-helper.ts

@@ -0,0 +1,98 @@
+import * as core from '@actions/core'
+import * as path from 'path'
+import * as fs from 'fs'
+import * as crypto from 'crypto'
+import * as lockfile from 'proper-lockfile'
+import {IGitCommandManager} from './git-command-manager'
+
+export class GitCacheHelper {
+  constructor(private referenceCache: string) {}
+
+  /**
+   * Prepares the reference cache for a given repository URL.
+   * If the cache does not exist, it performs a bare clone.
+   * If it exists, it performs a fetch to update it.
+   * Returns the absolute path to the bare cache repository.
+   */
+  async setupCache(git: IGitCommandManager, repositoryUrl: string): Promise<string> {
+    const cacheDirName = this.generateCacheDirName(repositoryUrl)
+    const cachePath = path.join(this.referenceCache, cacheDirName)
+    
+    // Ensure the base cache directory exists before we try to lock inside it
+    if (!fs.existsSync(this.referenceCache)) {
+      await fs.promises.mkdir(this.referenceCache, { recursive: true })
+    }
+
+    // We use a dedicated lock dir specifically for this repository's cache
+    // since we cannot place a lock *inside* a repository that might not exist yet
+    const lockfilePath = `${cachePath}.lock`
+    
+    // Ensure the file we are locking exists
+    if (!fs.existsSync(lockfilePath)) {
+      await fs.promises.writeFile(lockfilePath, '')
+    }
+
+    core.debug(`Acquiring lock for ${repositoryUrl} at ${lockfilePath}`)
+    
+    let releaseLock: () => Promise<void>
+    try {
+      // proper-lockfile creates a ".lock" directory next to the target file.
+      // We configure it to wait up to 10 minutes (600,000 ms) for another process to finish.
+      // E.g. cloning a very large monorepo might take minutes.
+      releaseLock = await lockfile.lock(lockfilePath, {
+        retries: {
+          retries: 60,         // try 60 times
+          factor: 1,           // linear backoff
+          minTimeout: 10000,   // wait 10 seconds between tries
+          maxTimeout: 10000,   // (total max wait time: 600s = 10m)
+          randomize: true
+        }
+      })
+      core.debug(`Lock acquired.`)
+    } catch (err) {
+      throw new Error(`Failed to acquire lock for repository cache ${repositoryUrl}: ${err}`)
+    }
+
+    try {
+      if (fs.existsSync(path.join(cachePath, 'objects'))) {
+        core.info(`Reference cache for ${repositoryUrl} exists. Updating...`)
+        const args = ['-C', cachePath, 'fetch', '--force', '--prune', '--tags', 'origin', '+refs/heads/*:refs/heads/*']
+        await git.execGit(args)
+      } else {
+        core.info(`Reference cache for ${repositoryUrl} does not exist. Cloning --bare...`)
+        
+        // Use a temporary clone pattern to prevent corrupted repos if process is killed mid-clone
+        const tmpPath = `${cachePath}.tmp.${crypto.randomUUID()}`
+        try {
+          const args = ['-C', this.referenceCache, 'clone', '--bare', repositoryUrl, tmpPath]
+          await git.execGit(args)
+          
+          if (fs.existsSync(cachePath)) {
+             // In rare cases where it somehow exists but objects/ didn't, clean it up
+             await fs.promises.rm(cachePath, { recursive: true, force: true })
+          }
+          await fs.promises.rename(tmpPath, cachePath)
+        } catch (cloneErr) {
+          // Cleanup partial clone if an error occurred
+          await fs.promises.rm(tmpPath, { recursive: true, force: true }).catch(() => {})
+          throw cloneErr
+        }
+      }
+    } finally {
+      await releaseLock()
+    }
+
+    return cachePath
+  }
+
+  /**
+   * Generates a directory name for the cache based on the URL.
+   * Replaces non-alphanumeric characters with underscores
+   * and appends a short SHA256 hash of the original URL.
+   */
+  generateCacheDirName(url: string): string {
+    const cleanUrl = url.replace(/[^a-zA-Z0-9]/g, '_')
+    const hash = crypto.createHash('sha256').update(url).digest('hex').substring(0, 8)
+    return `${cleanUrl}_${hash}.git`
+  }
+}

src/git-command-manager.ts

@@ -15,6 +15,11 @@ import {GitVersion} from './git-version'
 export const MinimumGitVersion = new GitVersion('2.18')
 export const MinimumGitSparseCheckoutVersion = new GitVersion('2.28')
 
+export class GitOutput {
+  stdout = ''
+  exitCode = 0
+}
+
 export interface IGitCommandManager {
   branchDelete(remote: boolean, branch: string): Promise<void>
   branchExists(remote: boolean, pattern: string): Promise<boolean>
@@ -28,7 +33,8 @@ export interface IGitCommandManager {
     configKey: string,
     configValue: string,
     globalConfig?: boolean,
-    add?: boolean
+    add?: boolean,
+    configFile?: string
   ): Promise<void>
   configExists(configKey: string, globalConfig?: boolean): Promise<boolean>
   fetch(
@@ -36,17 +42,18 @@ export interface IGitCommandManager {
     options: {
       filter?: string
       fetchDepth?: number
-      fetchTags?: boolean
       showProgress?: boolean
     }
   ): Promise<void>
   getDefaultBranch(repositoryUrl: string): Promise<string>
+  getSubmoduleConfigPaths(recursive: boolean): Promise<string[]>
   getWorkingDirectory(): string
   init(): Promise<void>
   isDetached(): Promise<boolean>
   lfsFetch(ref: string): Promise<void>
   lfsInstall(): Promise<void>
   log1(format?: string): Promise<string>
+  referenceAdd(referenceObjects: string): Promise<void>
   remoteAdd(remoteName: string, remoteUrl: string): Promise<void>
   removeEnvironmentVariable(name: string): void
   revParse(ref: string): Promise<string>
@@ -59,10 +66,32 @@ export interface IGitCommandManager {
   tagExists(pattern: string): Promise<boolean>
   tryClean(): Promise<boolean>
   tryConfigUnset(configKey: string, globalConfig?: boolean): Promise<boolean>
+  tryConfigUnsetValue(
+    configKey: string,
+    configValue: string,
+    globalConfig?: boolean,
+    configFile?: string
+  ): Promise<boolean>
   tryDisableAutomaticGarbageCollection(): Promise<boolean>
   tryGetFetchUrl(): Promise<string>
+  tryGetConfigValues(
+    configKey: string,
+    globalConfig?: boolean,
+    configFile?: string
+  ): Promise<string[]>
+  tryGetConfigKeys(
+    pattern: string,
+    globalConfig?: boolean,
+    configFile?: string
+  ): Promise<string[]>
   tryReset(): Promise<boolean>
   version(): Promise<GitVersion>
+  execGit(
+    args: string[],
+    allowAllExitCodes?: boolean,
+    silent?: boolean,
+    customListeners?: any
+  ): Promise<GitOutput>
 }
 
 export async function createCommandManager(
@@ -223,9 +252,15 @@ class GitCommandManager {
     configKey: string,
     configValue: string,
     globalConfig?: boolean,
-    add?: boolean
+    add?: boolean,
+    configFile?: string
   ): Promise<void> {
-    const args: string[] = ['config', globalConfig ? '--global' : '--local']
+    const args: string[] = ['config']
+    if (configFile) {
+      args.push('--file', configFile)
+    } else {
+      args.push(globalConfig ? '--global' : '--local')
+    }
     if (add) {
       args.push('--add')
     }
@@ -256,14 +291,13 @@ class GitCommandManager {
     options: {
       filter?: string
       fetchDepth?: number
-      fetchTags?: boolean
       showProgress?: boolean
     }
   ): Promise<void> {
     const args = ['-c', 'protocol.version=2', 'fetch']
-    if (!refSpec.some(x => x === refHelper.tagsRefSpec) && !options.fetchTags) {
+    // Always use --no-tags for explicit control over tag fetching
-      args.push('--no-tags')
+    // Tags are fetched explicitly via refspec when needed
-    }
+    args.push('--no-tags')
 
     args.push('--prune', '--no-recurse-submodules')
     if (options.showProgress) {
@@ -323,6 +357,21 @@ class GitCommandManager {
     throw new Error('Unexpected output when retrieving default branch')
   }
 
+  async getSubmoduleConfigPaths(recursive: boolean): Promise<string[]> {
+    // Get submodule config file paths.
+    // Use `--show-origin` to get the config file path for each submodule.
+    const output = await this.submoduleForeach(
+      `git config --local --show-origin --name-only --get-regexp remote.origin.url`,
+      recursive
+    )
+
+    // Extract config file paths from the output (lines starting with "file:").
+    const configPaths =
+      output.match(/(?<=(^|\n)file:)[^\t]+(?=\tremote\.origin\.url)/g) || []
+
+    return configPaths
+  }
+
   getWorkingDirectory(): string {
     return this.workingDirectory
   }
@@ -364,6 +413,32 @@ class GitCommandManager {
     await this.execGit(['remote', 'add', remoteName, remoteUrl])
   }
 
+  async referenceAdd(referenceObjects: string): Promise<void> {
+    const alternatesPath = path.join(
+      this.workingDirectory,
+      '.git',
+      'objects',
+      'info',
+      'alternates'
+    )
+    core.info(`Configuring git alternate to reference objects at ${referenceObjects}`)
+    const infoDir = path.dirname(alternatesPath)
+    if (!fs.existsSync(infoDir)) {
+      await fs.promises.mkdir(infoDir, { recursive: true })
+    }
+    
+    let existing = ''
+    if (fs.existsSync(alternatesPath)) {
+      existing = (await fs.promises.readFile(alternatesPath, 'utf8')).trim()
+    }
+    
+    const lines = existing ? existing.split('\n') : []
+    if (!lines.includes(referenceObjects)) {
+      lines.push(referenceObjects)
+      await fs.promises.writeFile(alternatesPath, lines.join('\n') + '\n')
+    }
+  }
+
   removeEnvironmentVariable(name: string): void {
     delete this.gitEnv[name]
   }
@@ -455,6 +530,24 @@ class GitCommandManager {
     return output.exitCode === 0
   }
 
+  async tryConfigUnsetValue(
+    configKey: string,
+    configValue: string,
+    globalConfig?: boolean,
+    configFile?: string
+  ): Promise<boolean> {
+    const args = ['config']
+    if (configFile) {
+      args.push('--file', configFile)
+    } else {
+      args.push(globalConfig ? '--global' : '--local')
+    }
+    args.push('--unset', configKey, configValue)
+
+    const output = await this.execGit(args, true)
+    return output.exitCode === 0
+  }
+
   async tryDisableAutomaticGarbageCollection(): Promise<boolean> {
     const output = await this.execGit(
       ['config', '--local', 'gc.auto', '0'],
@@ -481,6 +574,56 @@ class GitCommandManager {
     return stdout
   }
 
+  async tryGetConfigValues(
+    configKey: string,
+    globalConfig?: boolean,
+    configFile?: string
+  ): Promise<string[]> {
+    const args = ['config']
+    if (configFile) {
+      args.push('--file', configFile)
+    } else {
+      args.push(globalConfig ? '--global' : '--local')
+    }
+    args.push('--get-all', configKey)
+
+    const output = await this.execGit(args, true)
+
+    if (output.exitCode !== 0) {
+      return []
+    }
+
+    return output.stdout
+      .trim()
+      .split('\n')
+      .filter(value => value.trim())
+  }
+
+  async tryGetConfigKeys(
+    pattern: string,
+    globalConfig?: boolean,
+    configFile?: string
+  ): Promise<string[]> {
+    const args = ['config']
+    if (configFile) {
+      args.push('--file', configFile)
+    } else {
+      args.push(globalConfig ? '--global' : '--local')
+    }
+    args.push('--name-only', '--get-regexp', pattern)
+
+    const output = await this.execGit(args, true)
+
+    if (output.exitCode !== 0) {
+      return []
+    }
+
+    return output.stdout
+      .trim()
+      .split('\n')
+      .filter(key => key.trim())
+  }
+
   async tryReset(): Promise<boolean> {
     const output = await this.execGit(['reset', '--hard', 'HEAD'], true)
     return output.exitCode === 0
@@ -504,7 +647,7 @@ class GitCommandManager {
     return result
   }
 
-  private async execGit(
+  async execGit(
     args: string[],
     allowAllExitCodes = false,
     silent = false,
@@ -623,13 +766,21 @@ class GitCommandManager {
       }
     }
     // Set the user agent
-    const gitHttpUserAgent = `git/${this.gitVersion} (github-actions-checkout)`
+    let gitHttpUserAgent = `git/${this.gitVersion} (github-actions-checkout)`
+
+    // Append orchestration ID if set
+    const orchId = process.env['ACTIONS_ORCHESTRATION_ID']
+    if (orchId) {
+      // Sanitize the orchestration ID to ensure it contains only valid characters
+      // Valid characters: 0-9, a-z, _, -, .
+      const sanitizedId = orchId.replace(/[^a-z0-9_.-]/gi, '_')
+      if (sanitizedId) {
+        gitHttpUserAgent = `${gitHttpUserAgent} actions_orchestration_id/${sanitizedId}`
+      }
+    }
+
     core.debug(`Set git useragent to: ${gitHttpUserAgent}`)
     this.gitEnv['GIT_HTTP_USER_AGENT'] = gitHttpUserAgent
   }
 }
 
-class GitOutput {
-  stdout = ''
-  exitCode = 0
-}

src/git-source-provider.ts

@@ -14,6 +14,156 @@ import {
   IGitCommandManager
 } from './git-command-manager'
 import {IGitSourceSettings} from './git-source-settings'
+import {GitCacheHelper} from './git-cache-helper'
+import * as fs from 'fs'
+
+interface SubmoduleInfo {
+  name: string
+  path: string
+  url: string
+}
+
+async function iterativeSubmoduleUpdate(
+  git: IGitCommandManager,
+  cacheHelper: GitCacheHelper,
+  repositoryPath: string,
+  fetchDepth: number,
+  nestedSubmodules: boolean
+): Promise<void> {
+  const gitmodulesPath = path.join(repositoryPath, '.gitmodules')
+  if (!fs.existsSync(gitmodulesPath)) {
+    return
+  }
+
+  const submodules = new Map<string, SubmoduleInfo>()
+
+  // Get all submodule config keys
+  try {
+    const output = await git.execGit([
+      '-C', repositoryPath,
+      'config', '--file', gitmodulesPath, '--get-regexp', 'submodule\\..*'
+    ], true, true)
+
+    const lines = output.stdout.split('\n').filter(l => l.trim().length > 0)
+    for (const line of lines) {
+      const match = line.match(/^submodule\.(.+?)\.(path|url)\s+(.*)$/)
+      if (match) {
+        const [, name, key, value] = match
+        if (!submodules.has(name)) {
+          submodules.set(name, { name, path: '', url: '' })
+        }
+        const info = submodules.get(name)!
+        if (key === 'path') info.path = value
+        if (key === 'url') info.url = value
+      }
+    }
+  } catch (err) {
+    core.warning(`Failed to read .gitmodules: ${err}`)
+    return
+  }
+
+  for (const info of submodules.values()) {
+    if (!info.path || !info.url) continue
+
+    core.info(`Processing submodule ${info.name} at ${info.path}`)
+    
+    // Resolve relative URLs or valid URLs
+    let subUrl = info.url
+    if (subUrl.startsWith('../') || subUrl.startsWith('./')) {
+      // In checkout action, relative URLs are handled automatically by git.
+      // But for our bare cache clone, we need an absolute URL.
+      let originUrl = ''
+      try {
+        const originOut = await git.execGit(['-C', repositoryPath, 'remote', 'get-url', 'origin'], true, true)
+        if (originOut.exitCode === 0) {
+          originUrl = originOut.stdout.trim()
+        }
+        
+        if (originUrl) {
+          try {
+            if (originUrl.match(/^https?:\/\//)) {
+              // Using Node's URL class to resolve relative paths for HTTP(s)
+              const parsedOrigin = new URL(originUrl.replace(/\.git$/, ''))
+              const resolvedUrl = new URL(subUrl, parsedOrigin.href + '/')
+              subUrl = resolvedUrl.href
+            } else {
+              // Fallback for SSH URLs which new URL() cannot parse (e.g. git@github.com:org/repo)
+              let originParts = originUrl.replace(/\.git$/, '').split('/')
+              originParts.pop() // remove current repo
+              
+              // Handle multiple ../
+              let subTarget = subUrl
+              while (subTarget.startsWith('../')) {
+                if (originParts.length === 0) break // Can't go higher
+                originParts.pop()
+                subTarget = subTarget.substring(3)
+              }
+              if (subTarget.startsWith('./')) {
+                subTarget = subTarget.substring(2)
+              }
+              
+              if (originParts.length > 0) {
+                subUrl = originParts.join('/') + '/' + subTarget
+              }
+            }
+          } catch {
+            // Fallback does not work
+          }
+        }
+      } catch {
+        // ignore
+      }
+    }
+
+    if (!subUrl || subUrl.startsWith('../') || subUrl.startsWith('./')) {
+      core.warning(`Could not resolve absolute URL for submodule ${info.name}. Falling back to standard clone.`)
+      await invokeStandardSubmoduleUpdate(git, repositoryPath, fetchDepth, info.path)
+      continue
+    }
+
+    try {
+      // Prepare cache
+      const cachePath = await cacheHelper.setupCache(git, subUrl)
+      
+      // Submodule update for this specific one
+      const args = ['-C', repositoryPath, '-c', 'protocol.version=2', 'submodule', 'update', '--init', '--force']
+      if (fetchDepth > 0) {
+        args.push(`--depth=${fetchDepth}`)
+      }
+      args.push('--reference', cachePath)
+      args.push(info.path)
+
+      const output = await git.execGit(args, true)
+      if (output.exitCode !== 0) {
+        throw new Error(`Submodule update failed with exit code ${output.exitCode}`)
+      }
+    } catch (err) {
+      core.warning(`Reference cache failed for submodule ${info.name} (${err}). Falling back to standard clone...`)
+      await invokeStandardSubmoduleUpdate(git, repositoryPath, fetchDepth, info.path)
+    }
+    
+    // Recursive update inside the submodule
+    if (nestedSubmodules) {
+      const subRepoPath = path.join(repositoryPath, info.path)
+      await iterativeSubmoduleUpdate(
+        git,
+        cacheHelper,
+        subRepoPath,
+        fetchDepth,
+        nestedSubmodules
+      )
+    }
+  }
+}
+
+async function invokeStandardSubmoduleUpdate(git: IGitCommandManager, repositoryPath: string, fetchDepth: number, submodulePath: string) {
+  const args = ['-C', repositoryPath, '-c', 'protocol.version=2', 'submodule', 'update', '--init', '--force']
+  if (fetchDepth > 0) {
+    args.push(`--depth=${fetchDepth}`)
+  }
+  args.push(submodulePath)
+  await git.execGit(args)
+}
 
 export async function getSource(settings: IGitSourceSettings): Promise<void> {
   // Repository URL
@@ -105,6 +255,19 @@ export async function getSource(settings: IGitSourceSettings): Promise<void> {
     // Save state for POST action
     stateHelper.setRepositoryPath(settings.repositoryPath)
 
+    // If we didn't initialize it above, do it now
+    if (!authHelper) {
+      authHelper = gitAuthHelper.createAuthHelper(git, settings)
+    }
+
+    // Check if we need global auth setup early for reference cache
+    // Global auth does not require a local .git directory
+    if (settings.referenceCache) {
+      core.startGroup('Setting up global auth for reference cache')
+      await authHelper.configureGlobalAuth()
+      core.endGroup()
+    }
+
     // Initialize the repository
     if (
       !fsHelper.directoryExistsSync(path.join(settings.repositoryPath, '.git'))
@@ -113,8 +276,35 @@ export async function getSource(settings: IGitSourceSettings): Promise<void> {
       await git.init()
       await git.remoteAdd('origin', repositoryUrl)
       core.endGroup()
+
+      // Setup reference cache if requested
+      if (settings.referenceCache) {
+        core.startGroup('Setting up reference repository cache')
+        const cacheHelper = new GitCacheHelper(settings.referenceCache)
+        const cachePath = await cacheHelper.setupCache(git, repositoryUrl)
+        const cacheObjects = path.join(cachePath, 'objects')
+        if (fsHelper.directoryExistsSync(cacheObjects, false)) {
+          await git.referenceAdd(cacheObjects)
+        } else {
+          core.warning(`Reference repository cache objects directory ${cacheObjects} does not exist`)
+        }
+        core.endGroup()
+      }
     }
 
+    // Remove global auth if it was set for reference cache,
+    // to avoid duplicate AUTHORIZATION headers during fetch
+    if (settings.referenceCache) {
+      core.startGroup('Removing global auth after reference cache setup')
+      await authHelper.removeGlobalAuth()
+      core.endGroup()
+    }
+
+    // Configure auth (must happen after git init so .git exists)
+    core.startGroup('Setting up auth')
+    await authHelper.configureAuth()
+    core.endGroup()
+
     // Disable automatic garbage collection
     core.startGroup('Disabling automatic garbage collection')
     if (!(await git.tryDisableAutomaticGarbageCollection())) {
@@ -124,15 +314,6 @@ export async function getSource(settings: IGitSourceSettings): Promise<void> {
     }
     core.endGroup()
 
-    // If we didn't initialize it above, do it now
-    if (!authHelper) {
-      authHelper = gitAuthHelper.createAuthHelper(git, settings)
-    }
-    // Configure auth
-    core.startGroup('Setting up auth')
-    await authHelper.configureAuth()
-    core.endGroup()
-
     // Determine the default branch
     if (!settings.ref && !settings.commit) {
       core.startGroup('Determining the default branch')
@@ -154,12 +335,15 @@ export async function getSource(settings: IGitSourceSettings): Promise<void> {
       await git.lfsInstall()
     }
 
+    // When using reference cache, fetch-depth > 0 is counterproductive:
+    // objects are served from the local cache, so shallow negotiation only adds latency.
+    adjustFetchDepthForCache(settings)
+
     // Fetch
     core.startGroup('Fetching the repository')
     const fetchOptions: {
       filter?: string
       fetchDepth?: number
-      fetchTags?: boolean
       showProgress?: boolean
     } = {}
 
@@ -182,12 +366,35 @@ export async function getSource(settings: IGitSourceSettings): Promise<void> {
       if (!(await refHelper.testRef(git, settings.ref, settings.commit))) {
         refSpec = refHelper.getRefSpec(settings.ref, settings.commit)
         await git.fetch(refSpec, fetchOptions)
+
+        // Verify the ref now matches. For branches, the targeted fetch above brings
+        // in the specific commit. For tags (fetched by ref), this will fail if
+        // the tag was moved after the workflow was triggered.
+        if (!(await refHelper.testRef(git, settings.ref, settings.commit))) {
+          throw new Error(
+            `The ref '${settings.ref}' does not point to the expected commit '${settings.commit}'. ` +
+              `The ref may have been updated after the workflow was triggered.`
+          )
+        }
       }
     } else {
       fetchOptions.fetchDepth = settings.fetchDepth
-      fetchOptions.fetchTags = settings.fetchTags
+      const refSpec = refHelper.getRefSpec(
-      const refSpec = refHelper.getRefSpec(settings.ref, settings.commit)
+        settings.ref,
+        settings.commit,
+        settings.fetchTags
+      )
       await git.fetch(refSpec, fetchOptions)
+
+      // For tags, verify the ref still points to the expected commit.
+      // Tags are fetched by ref (not commit), so if a tag was moved after the
+      // workflow was triggered, we would silently check out the wrong commit.
+      if (!(await refHelper.testRef(git, settings.ref, settings.commit))) {
+        throw new Error(
+          `The ref '${settings.ref}' does not point to the expected commit '${settings.commit}'. ` +
+            `The ref may have been updated after the workflow was triggered.`
+        )
+      }
     }
     core.endGroup()
 
@@ -242,7 +449,21 @@ export async function getSource(settings: IGitSourceSettings): Promise<void> {
       // Checkout submodules
       core.startGroup('Fetching submodules')
       await git.submoduleSync(settings.nestedSubmodules)
-      await git.submoduleUpdate(settings.fetchDepth, settings.nestedSubmodules)
+      
+      if (settings.referenceCache) {
+        core.info('Iterative submodule update using reference cache')
+        const cacheHelper = new GitCacheHelper(settings.referenceCache)
+        await iterativeSubmoduleUpdate(
+          git,
+          cacheHelper,
+          settings.repositoryPath,
+          settings.fetchDepth,
+          settings.nestedSubmodules
+        )
+      } else {
+        await git.submoduleUpdate(settings.fetchDepth, settings.nestedSubmodules)
+      }
+      
       await git.submoduleForeach(
         'git config --local gc.auto 0',
         settings.nestedSubmodules
@@ -351,3 +572,30 @@ async function getGitCommandManager(
     return undefined
   }
 }
+
+/**
+ * Adjusts fetchDepth when reference-cache is active.
+ * Shallow fetches are counterproductive with a local cache because
+ * objects are served from disk, making shallow negotiation pure overhead.
+ */
+export function adjustFetchDepthForCache(
+  settings: Pick<
+    IGitSourceSettings,
+    'referenceCache' | 'fetchDepth' | 'fetchDepthExplicit'
+  >
+): void {
+  if (settings.referenceCache && settings.fetchDepth > 0) {
+    if (settings.fetchDepthExplicit) {
+      core.warning(
+        `'fetch-depth: ${settings.fetchDepth}' is set with reference-cache enabled. ` +
+          `This may slow down checkout because shallow negotiation bypasses the local cache. ` +
+          `Consider using 'fetch-depth: 0' for best performance with reference-cache.`
+      )
+    } else {
+      core.info(
+        `Overriding fetch-depth from ${settings.fetchDepth} to 0 because reference-cache is enabled`
+      )
+      settings.fetchDepth = 0
+    }
+  }
+}

src/git-source-settings.ts

@@ -49,6 +49,11 @@ export interface IGitSourceSettings {
    */
   fetchDepth: number
 
+  /**
+   * Whether fetch-depth was explicitly set by the user
+   */
+  fetchDepthExplicit: boolean
+
   /**
    * Fetch tags, even if fetchDepth > 0 (default: false)
    */
@@ -59,6 +64,11 @@ export interface IGitSourceSettings {
    */
   showProgress: boolean
 
+  /**
+   * The path to a local directory used as a reference cache for Git clones
+   */
+  referenceCache: string
+
   /**
    * Indicates whether to fetch LFS objects
    */

src/input-helper.ts

@@ -102,7 +102,9 @@ export async function getInputs(): Promise<IGitSourceSettings> {
     'TRUE'
 
   // Fetch depth
-  result.fetchDepth = Math.floor(Number(core.getInput('fetch-depth') || '1'))
+  const fetchDepthInput = core.getInput('fetch-depth')
+  result.fetchDepthExplicit = fetchDepthInput !== ''
+  result.fetchDepth = Math.floor(Number(fetchDepthInput || '1'))
   if (isNaN(result.fetchDepth) || result.fetchDepth < 0) {
     result.fetchDepth = 0
   }
@@ -161,5 +163,9 @@ export async function getInputs(): Promise<IGitSourceSettings> {
   result.githubServerUrl = core.getInput('github-server-url')
   core.debug(`GitHub Host URL = ${result.githubServerUrl}`)
 
+  // Reference Cache
+  result.referenceCache = core.getInput('reference-cache')
+  core.debug(`Reference Cache = ${result.referenceCache}`)
+
   return result
 }

src/misc/generate-docs.ts

@@ -120,7 +120,7 @@ function updateUsage(
 }
 
 updateUsage(
-  'actions/checkout@v4',
+  'actions/checkout@v6',
   path.join(__dirname, '..', '..', 'action.yml'),
   path.join(__dirname, '..', '..', 'README.md')
 )

src/ref-helper.ts

@@ -76,55 +76,75 @@ export function getRefSpecForAllHistory(ref: string, commit: string): string[] {
   return result
 }
 
-export function getRefSpec(ref: string, commit: string): string[] {
+export function getRefSpec(
+  ref: string,
+  commit: string,
+  fetchTags?: boolean
+): string[] {
   if (!ref && !commit) {
     throw new Error('Args ref and commit cannot both be empty')
   }
 
   const upperRef = (ref || '').toUpperCase()
+  const result: string[] = []
+
+  // When fetchTags is true, always include the tags refspec
+  if (fetchTags) {
+    result.push(tagsRefSpec)
+  }
 
   // SHA
   if (commit) {
     // refs/heads
     if (upperRef.startsWith('REFS/HEADS/')) {
       const branch = ref.substring('refs/heads/'.length)
-      return [`+${commit}:refs/remotes/origin/${branch}`]
+      result.push(`+${commit}:refs/remotes/origin/${branch}`)
     }
     // refs/pull/
     else if (upperRef.startsWith('REFS/PULL/')) {
       const branch = ref.substring('refs/pull/'.length)
-      return [`+${commit}:refs/remotes/pull/${branch}`]
+      result.push(`+${commit}:refs/remotes/pull/${branch}`)
     }
     // refs/tags/
     else if (upperRef.startsWith('REFS/TAGS/')) {
-      return [`+${commit}:${ref}`]
+      if (!fetchTags) {
+        result.push(`+${ref}:${ref}`)
+      }
     }
     // Otherwise no destination ref
     else {
-      return [commit]
+      result.push(commit)
     }
   }
   // Unqualified ref, check for a matching branch or tag
   else if (!upperRef.startsWith('REFS/')) {
-    return [
+    result.push(`+refs/heads/${ref}*:refs/remotes/origin/${ref}*`)
-      `+refs/heads/${ref}*:refs/remotes/origin/${ref}*`,
+    if (!fetchTags) {
-      `+refs/tags/${ref}*:refs/tags/${ref}*`
+      result.push(`+refs/tags/${ref}*:refs/tags/${ref}*`)
-    ]
+    }
   }
   // refs/heads/
   else if (upperRef.startsWith('REFS/HEADS/')) {
     const branch = ref.substring('refs/heads/'.length)
-    return [`+${ref}:refs/remotes/origin/${branch}`]
+    result.push(`+${ref}:refs/remotes/origin/${branch}`)
   }
   // refs/pull/
   else if (upperRef.startsWith('REFS/PULL/')) {
     const branch = ref.substring('refs/pull/'.length)
-    return [`+${ref}:refs/remotes/pull/${branch}`]
+    result.push(`+${ref}:refs/remotes/pull/${branch}`)
   }
   // refs/tags/
-  else {
+  else if (upperRef.startsWith('REFS/TAGS/')) {
-    return [`+${ref}:${ref}`]
+    if (!fetchTags) {
+      result.push(`+${ref}:${ref}`)
+    }
   }
+  // Other refs
+  else {
+    result.push(`+${ref}:${ref}`)
+  }
+
+  return result
 }
 
 /**
@@ -170,8 +190,10 @@ export async function testRef(
   // refs/tags/
   else if (upperRef.startsWith('REFS/TAGS/')) {
     const tagName = ref.substring('refs/tags/'.length)
+    // Use ^{commit} to dereference annotated tags to their underlying commit
     return (
-      (await git.tagExists(tagName)) && commit === (await git.revParse(ref))
+      (await git.tagExists(tagName)) &&
+      commit === (await git.revParse(`${ref}^{commit}`))
     )
   }
   // Unexpected