README: Suggest user.email to be 41898282+github-actions[bot]@users.noreply.github.com (#1707)

* README: Set `user.email` to GitHub Actions Bot

* Update workflow to use proper bot GitHub Bot email

* Prefix `user.email` with `41898282+`

To match squash merge user, else showing as two different users, see: b0948d0da0

* Update README.md

---------

Co-authored-by: Pelle Wessman <pelle@kodfabrik.se>

.github/dependabot.yml

@@ -0,0 +1,20 @@
+---
+version: 2
+
+updates:
+- package-ecosystem: "npm"
+  directory: "/"
+  schedule:
+    interval: "weekly"
+  groups:
+    minor-npm-dependencies:
+      # NPM: Only group minor and patch updates (we want to carefully review major updates)
+      update-types: [minor, patch]
+- package-ecosystem: "github-actions"
+  directory: "/"
+  schedule:
+    interval: "weekly"
+  groups:
+    minor-actions-dependencies:
+      # GitHub Actions: Only group minor and patch updates (we want to carefully review major updates)
+      update-types: [minor, patch]

.github/workflows/check-dist.yml

@@ -24,10 +24,10 @@ jobs:
     steps:
       - uses: actions/checkout@v3
 
-      - name: Set Node.js 16.x
-        uses: actions/setup-node@v1
+      - name: Set Node.js 20.x
+        uses: actions/setup-node@v4
         with:
-          node-version: 16.x
+          node-version: 20.x
 
       - name: Install dependencies
         run: npm ci
@@ -44,7 +44,7 @@ jobs:
           fi
 
       # If dist/ was different than expected, upload the expected version as an artifact
-      - uses: actions/upload-artifact@v2
+      - uses: actions/upload-artifact@v4
         if: ${{ failure() && steps.diff.conclusion == 'failure' }}
         with:
           name: dist

.github/workflows/codeql-analysis.yml

@@ -42,7 +42,7 @@ jobs:
       uses: actions/checkout@v3
 
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v1
+      uses: github/codeql-action/init@v3
       with:
         languages: ${{ matrix.language }}
         # If you wish to specify custom queries, you can do so here or in a config file.
@@ -55,4 +55,4 @@ jobs:
     - run: rm -rf dist # We want code scanning to analyze lib instead (individual .js files)
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v1
+      uses: github/codeql-action/analyze@v3

.github/workflows/test.yml

@@ -7,13 +7,18 @@ on:
       - main
       - releases/*
 
+
+# Note that when you see patterns like "ref: test-data/v2/basic" within this workflow,
+# these refer to "test-data" branches on this actions/checkout repo.
+# (For example, test-data/v2/basic -> https://github.com/actions/checkout/tree/test-data/v2/basic)
+
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/setup-node@v1
+      - uses: actions/setup-node@v4
         with:
-          node-version: 16.x
+          node-version: 20.x
       - uses: actions/checkout@v3
       - run: npm ci
       - run: npm run build
@@ -32,7 +37,7 @@ jobs:
     steps:
       # Clone this repo
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4.1.1
 
       # Basic checkout
       - name: Checkout basic
@@ -72,6 +77,53 @@ jobs:
         shell: bash
         run: __test__/verify-side-by-side.sh
 
+      # Filter
+      - name: Fetch filter
+        uses: ./
+        with:
+          filter: 'blob:none'
+          path: fetch-filter
+
+      - name: Verify fetch filter
+        run: __test__/verify-fetch-filter.sh
+
+      # Sparse checkout
+      - name: Sparse checkout
+        uses: ./
+        with:
+          sparse-checkout: |
+            __test__
+            .github
+            dist
+          path: sparse-checkout
+
+      - name: Verify sparse checkout
+        run: __test__/verify-sparse-checkout.sh
+
+      # Disabled sparse checkout in existing checkout
+      - name: Disabled sparse checkout
+        uses: ./
+        with:
+          path: sparse-checkout
+
+      - name: Verify disabled sparse checkout
+        shell: bash
+        run: set -x && ls -l sparse-checkout/src/git-command-manager.ts
+
+      # Sparse checkout (non-cone mode)
+      - name: Sparse checkout (non-cone mode)
+        uses: ./
+        with:
+          sparse-checkout: |
+            /__test__/
+            /.github/
+            /dist/
+          sparse-checkout-cone-mode: false
+          path: sparse-checkout-non-cone-mode
+
+      - name: Verify sparse checkout (non-cone mode)
+        run: __test__/verify-sparse-checkout-non-cone-mode.sh
+
       # LFS
       - name: Checkout LFS
         uses: ./
@@ -138,7 +190,7 @@ jobs:
   test-proxy:
     runs-on: ubuntu-latest
     container:
-      image: alpine/git:latest
+      image: ghcr.io/actions/test-ubuntu-git:main.20240221.114913.703z
       options: --dns 127.0.0.1
     services:
       squid-proxy:
@@ -205,7 +257,7 @@ jobs:
           path: basic
       - name: Verify basic
         run: __test__/verify-basic.sh --archive
-    
+
   test-git-container:
     runs-on: ubuntu-latest
     container: bitnami/git:latest
@@ -242,4 +294,4 @@ jobs:
       - name: Fix Checkout v3
         uses: actions/checkout@v3
         with:
-          path: v3
+          path: v3

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

@@ -1,5 +1,5 @@
 name: Update Main Version
-run-name: Move ${{ github.event.inputs.main_version }} to ${{ github.event.inputs.target }}
+run-name: Move ${{ github.event.inputs.major_version }} to ${{ github.event.inputs.target }}
 
 on:
   workflow_dispatch:
@@ -7,24 +7,29 @@ on:
       target:
         description: The tag or reference to use
         required: true
-      main_version:
+      major_version:
         type: choice
-        description: The main version to update
+        description: The major version to update
         options:
+          - v4
           - v3
+          - v2
 
 jobs:
   tag:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    # 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.1
       with:
         fetch-depth: 0
     - name: Git config
       run: |
-        git config user.name github-actions
-        git config user.email github-actions@github.com
+        git config user.name "github-actions[bot]"
+        git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
     - name: Tag new target
-      run: git tag -f ${{ github.event.inputs.main_version }} ${{ github.event.inputs.target }}
+      run: git tag -f ${{ github.event.inputs.major_version }} ${{ github.event.inputs.target }}
     - name: Push new tag
-      run: git push origin ${{ github.event.inputs.main_version }} --force
+      run: git push origin ${{ github.event.inputs.major_version }} --force

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

@@ -0,0 +1,59 @@
+name: Publish test-ubuntu-git Container
+
+on:
+  # Use an on demand workflow trigger.  
+  # (Forked copies of actions/checkout won't have permission to update GHCR.io/actions, 
+  #  so avoid trigger events that run automatically.)
+  workflow_dispatch:
+    inputs:
+      publish:
+        description:  'Publish to ghcr.io? (main branch only)'
+        type: boolean
+        required: true
+        default: false
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: actions/test-ubuntu-git
+
+jobs:
+  build-and-push-image:
+    runs-on: ubuntu-latest
+    # Sets the permissions granted to the `GITHUB_TOKEN` for the actions in this job.
+    permissions:
+      contents: read
+      packages: write
+ 
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # Use `docker/login-action` to log in to GHCR.io. 
+      # Once published, the packages are scoped to the account defined here.
+      - name: Log in to the ghcr.io container registry
+        uses: docker/login-action@v3.1.0
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Format Timestamp
+        id: timestamp
+        # Use `date` with a custom format to achieve the key=value format GITHUB_OUTPUT expects.
+        run: date -u "+now=%Y%m%d.%H%M%S.%3NZ" >> "$GITHUB_OUTPUT"
+
+      - name: Issue Image Publish Warning
+        if:  ${{ inputs.publish && github.ref_name != 'main' }}
+        run: echo "::warning::test-ubuntu-git images can only be published from the actions/checkout 'main' branch.  Workflow will continue with push/publish disabled."
+
+      # Use `docker/build-push-action` to build (and optionally publish) the image. 
+      - name: Build Docker Image (with optional Push)
+        uses: docker/build-push-action@v5.3.0
+        with:
+          context: .
+          file: images/test-ubuntu-git.Dockerfile
+          # For now, attempts to push to ghcr.io must target the `main` branch.
+          # In the future, consider also allowing attempts from `releases/*` branches.
+          push: ${{ inputs.publish && github.ref_name == 'main' }}
+          tags: |
+            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.ref_name }}.${{ steps.timestamp.outputs.now }}

CHANGELOG.md

@@ -1,5 +1,66 @@
 # Changelog
 
+## v4.1.4
+- Disable `extensions.worktreeConfig` when disabling `sparse-checkout` by @jww3 in https://github.com/actions/checkout/pull/1692
+- Add dependabot config by @cory-miller in https://github.com/actions/checkout/pull/1688
+- Bump the minor-actions-dependencies group with 2 updates by @dependabot in https://github.com/actions/checkout/pull/1693
+- Bump word-wrap from 1.2.3 to 1.2.5 by @dependabot in https://github.com/actions/checkout/pull/1643
+
+## v4.1.3
+- Check git version before attempting to disable `sparse-checkout` by @jww3 in https://github.com/actions/checkout/pull/1656
+- Add SSH user parameter by @cory-miller in https://github.com/actions/checkout/pull/1685
+- Update `actions/checkout` version in `update-main-version.yml` by @jww3 in https://github.com/actions/checkout/pull/1650
+
+## v4.1.2
+- Fix: Disable sparse checkout whenever `sparse-checkout` option is not present @dscho in https://github.com/actions/checkout/pull/1598
+
+## v4.1.1
+- Correct link to GitHub Docs by @peterbe in https://github.com/actions/checkout/pull/1511
+- Link to release page from what's new section by @cory-miller in https://github.com/actions/checkout/pull/1514
+
+## v4.1.0
+- [Add support for partial checkout filters](https://github.com/actions/checkout/pull/1396)
+
+## v4.0.0
+- [Support fetching without the --progress option](https://github.com/actions/checkout/pull/1067)
+- [Update to node20](https://github.com/actions/checkout/pull/1436)
+
+## v3.6.0
+- [Fix: Mark test scripts with Bash'isms to be run via Bash](https://github.com/actions/checkout/pull/1377)
+- [Add option to fetch tags even if fetch-depth > 0](https://github.com/actions/checkout/pull/579)
+
+## v3.5.3
+- [Fix: Checkout fail in self-hosted runners when faulty submodule are checked-in](https://github.com/actions/checkout/pull/1196)
+- [Fix typos found by codespell](https://github.com/actions/checkout/pull/1287)
+- [Add support for sparse checkouts](https://github.com/actions/checkout/pull/1369)
+
+## v3.5.2
+- [Fix api endpoint for GHES](https://github.com/actions/checkout/pull/1289)
+
+## v3.5.1
+- [Fix slow checkout on Windows](https://github.com/actions/checkout/pull/1246)
+
+## v3.5.0
+* [Add new public key for known_hosts](https://github.com/actions/checkout/pull/1237)
+
+## v3.4.0
+- [Upgrade codeql actions to v2](https://github.com/actions/checkout/pull/1209)
+- [Upgrade dependencies](https://github.com/actions/checkout/pull/1210)
+- [Upgrade @actions/io](https://github.com/actions/checkout/pull/1225)
+
+## v3.3.0
+- [Implement branch list using callbacks from exec function](https://github.com/actions/checkout/pull/1045)
+- [Add in explicit reference to private checkout options](https://github.com/actions/checkout/pull/1050)
+- [Fix comment typos (that got added in #770)](https://github.com/actions/checkout/pull/1057)
+
+## v3.2.0
+- [Add GitHub Action to perform release](https://github.com/actions/checkout/pull/942)
+- [Fix status badge](https://github.com/actions/checkout/pull/967)
+- [Replace datadog/squid with ubuntu/squid Docker image](https://github.com/actions/checkout/pull/1002)
+- [Wrap pipeline commands for submoduleForeach in quotes](https://github.com/actions/checkout/pull/964)
+- [Update @actions/io to 1.1.2](https://github.com/actions/checkout/pull/1029)
+- [Upgrading version to 3.2.0](https://github.com/actions/checkout/pull/1039)
+
 ## v3.1.0
 - [Use @actions/core `saveState` and `getState`](https://github.com/actions/checkout/pull/939)
 - [Add `github-server-url` input](https://github.com/actions/checkout/pull/922)

CODEOWNERS

@@ -1 +1 @@
-* @actions/actions-runtime
+* @actions/actions-launch

README.md

@@ -1,10 +1,10 @@
 [![Build and Test](https://github.com/actions/checkout/actions/workflows/test.yml/badge.svg)](https://github.com/actions/checkout/actions/workflows/test.yml)
 
-# Checkout V3
+# Checkout V4
 
 This action checks-out your repository under `$GITHUB_WORKSPACE`, so your workflow can access it.
 
-Only a single commit is fetched by default, for the ref/SHA that triggered the workflow. Set `fetch-depth: 0` to fetch all history for all branches and tags. Refer [here](https://help.github.com/en/articles/events-that-trigger-workflows) to learn which commit `$GITHUB_SHA` points to for different events.
+Only a single commit is fetched by default, for the ref/SHA that triggered the workflow. Set `fetch-depth: 0` to fetch all history for all branches and tags. Refer [here](https://docs.github.com/actions/using-workflows/events-that-trigger-workflows) to learn which commit `$GITHUB_SHA` points to for different events.
 
 The auth token is persisted in the local git config. This enables your scripts to run authenticated git commands. The token is removed during post-job cleanup. Set `persist-credentials: false` to opt-out.
 
@@ -12,14 +12,13 @@ When Git 2.18 or higher is not in your PATH, falls back to the REST API to downl
 
 # What's new
 
-- Updated to the node16 runtime by default
-  - This requires a minimum [Actions Runner](https://github.com/actions/runner/releases/tag/v2.285.0) version of v2.285.0 to run, which is by default available in GHES 3.4 or later.
+Please refer to the [release page](https://github.com/actions/checkout/releases/latest) for the latest release notes.
 
 # Usage
 
 <!-- start usage -->
 ```yaml
-- uses: actions/checkout@v3
+- uses: actions/checkout@v4
   with:
     # Repository name with owner. For example, actions/checkout
     # Default: ${{ github.repository }}
@@ -63,6 +62,11 @@ When Git 2.18 or higher is not in your PATH, falls back to the REST API to downl
     # Default: true
     ssh-strict: ''
 
+    # The user to use when connecting to the remote SSH host. By default 'git' is
+    # used.
+    # Default: git
+    ssh-user: ''
+
     # Whether to configure the token or SSH key with the local git config
     # Default: true
     persist-credentials: ''
@@ -74,10 +78,31 @@ When Git 2.18 or higher is not in your PATH, falls back to the REST API to downl
     # Default: true
     clean: ''
 
+    # Partially clone against a given filter. Overrides sparse-checkout if set.
+    # Default: null
+    filter: ''
+
+    # Do a sparse checkout on given patterns. Each pattern should be separated with
+    # new lines.
+    # Default: null
+    sparse-checkout: ''
+
+    # Specifies whether to use cone-mode when doing a sparse checkout.
+    # Default: true
+    sparse-checkout-cone-mode: ''
+
     # Number of commits to fetch. 0 indicates all history for all branches and tags.
     # Default: 1
     fetch-depth: ''
 
+    # Whether to fetch tags, even if fetch-depth > 0.
+    # Default: false
+    fetch-tags: ''
+
+    # Whether to show progress status output when fetching.
+    # Default: true
+    show-progress: ''
+
     # Whether to download Git-LFS files
     # Default: false
     lfs: ''
@@ -106,6 +131,9 @@ When Git 2.18 or higher is not in your PATH, falls back to the REST API to downl
 
 # Scenarios
 
+- [Fetch only the root files](#Fetch-only-the-root-files)
+- [Fetch only the root files and `.github` and `src` folder](#Fetch-only-the-root-files-and-github-and-src-folder)
+- [Fetch only a single file](#Fetch-only-a-single-file)
 - [Fetch all history for all tags and branches](#Fetch-all-history-for-all-tags-and-branches)
 - [Checkout a different branch](#Checkout-a-different-branch)
 - [Checkout HEAD^](#Checkout-HEAD)
@@ -116,10 +144,38 @@ When Git 2.18 or higher is not in your PATH, falls back to the REST API to downl
 - [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)
 
+## Fetch only the root files
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    sparse-checkout: .
+```
+
+## Fetch only the root files and `.github` and `src` folder
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    sparse-checkout: |
+      .github
+      src
+```
+
+## Fetch only a single file
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    sparse-checkout: |
+      README.md
+    sparse-checkout-cone-mode: false
+```
+
 ## Fetch all history for all tags and branches
 
 ```yaml
-- uses: actions/checkout@v3
+- uses: actions/checkout@v4
   with:
     fetch-depth: 0
 ```
@@ -127,7 +183,7 @@ When Git 2.18 or higher is not in your PATH, falls back to the REST API to downl
 ## Checkout a different branch
 
 ```yaml
-- uses: actions/checkout@v3
+- uses: actions/checkout@v4
   with:
     ref: my-branch
 ```
@@ -135,7 +191,7 @@ When Git 2.18 or higher is not in your PATH, falls back to the REST API to downl
 ## Checkout HEAD^
 
 ```yaml
-- uses: actions/checkout@v3
+- uses: actions/checkout@v4
   with:
     fetch-depth: 2
 - run: git checkout HEAD^
@@ -145,40 +201,42 @@ When Git 2.18 or higher is not in your PATH, falls back to the REST API to downl
 
 ```yaml
 - name: Checkout
-  uses: actions/checkout@v3
+  uses: actions/checkout@v4
   with:
     path: main
 
 - name: Checkout tools repo
-  uses: actions/checkout@v3
+  uses: actions/checkout@v4
   with:
     repository: my-org/my-tools
     path: my-tools
 ```
+> - If your secondary repository is private you will need to add the option noted in [Checkout multiple repos (private)](#Checkout-multiple-repos-private)
 
 ## Checkout multiple repos (nested)
 
 ```yaml
 - name: Checkout
-  uses: actions/checkout@v3
+  uses: actions/checkout@v4
 
 - name: Checkout tools repo
-  uses: actions/checkout@v3
+  uses: actions/checkout@v4
   with:
     repository: my-org/my-tools
     path: my-tools
 ```
+> - If your secondary repository is private you will need to add the option noted in [Checkout multiple repos (private)](#Checkout-multiple-repos-private)
 
 ## Checkout multiple repos (private)
 
 ```yaml
 - name: Checkout
-  uses: actions/checkout@v3
+  uses: actions/checkout@v4
   with:
     path: main
 
 - name: Checkout private tools
-  uses: actions/checkout@v3
+  uses: actions/checkout@v4
   with:
     repository: my-org/my-private-tools
     token: ${{ secrets.GH_PAT }} # `GH_PAT` is a secret that contains your PAT
@@ -191,7 +249,7 @@ When Git 2.18 or higher is not in your PATH, falls back to the REST API to downl
 ## Checkout pull request HEAD commit instead of merge commit
 
 ```yaml
-- uses: actions/checkout@v3
+- uses: actions/checkout@v4
   with:
     ref: ${{ github.event.pull_request.head.sha }}
 ```
@@ -207,7 +265,7 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 ```
 
 ## Push a commit using the built-in token
@@ -218,11 +276,12 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - run: |
           date > generated.txt
-          git config user.name github-actions
-          git config user.email github-actions@github.com
+          # Note: the following account information will not work on GHES
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
           git add .
           git commit -m "generated"
           git push

__test__/git-auth-helper.test.ts

@@ -169,8 +169,9 @@ describe('git-auth-helper tests', () => {
 
     // Mock fs.promises.readFile
     const realReadFile = fs.promises.readFile
-    jest.spyOn(fs.promises, 'readFile').mockImplementation(
-      async (file: any, options: any): Promise<Buffer> => {
+    jest
+      .spyOn(fs.promises, 'readFile')
+      .mockImplementation(async (file: any, options: any): Promise<Buffer> => {
         const userKnownHostsPath = path.join(
           os.homedir(),
           '.ssh',
@@ -181,8 +182,7 @@ describe('git-auth-helper tests', () => {
         }
 
         return await realReadFile(file, options)
-      }
-    )
+      })
 
     // Act
     const authHelper = gitAuthHelper.createAuthHelper(git, settings)
@@ -727,6 +727,9 @@ async function setup(testName: string): Promise<void> {
     branchDelete: jest.fn(),
     branchExists: jest.fn(),
     branchList: jest.fn(),
+    disableSparseCheckout: jest.fn(),
+    sparseCheckout: jest.fn(),
+    sparseCheckoutNonConeMode: jest.fn(),
     checkout: jest.fn(),
     checkoutDetach: jest.fn(),
     config: jest.fn(
@@ -770,6 +773,9 @@ async function setup(testName: string): Promise<void> {
       return ''
     }),
     submoduleSync: jest.fn(),
+    submoduleStatus: jest.fn(async () => {
+      return true
+    }),
     submoduleUpdate: jest.fn(),
     tagExists: jest.fn(),
     tryClean: jest.fn(),
@@ -790,14 +796,20 @@ async function setup(testName: string): Promise<void> {
     ),
     tryDisableAutomaticGarbageCollection: jest.fn(),
     tryGetFetchUrl: jest.fn(),
-    tryReset: jest.fn()
+    tryReset: jest.fn(),
+    version: jest.fn()
   }
 
   settings = {
     authToken: 'some auth token',
     clean: true,
     commit: '',
+    filter: undefined,
+    sparseCheckout: [],
+    sparseCheckoutConeMode: true,
     fetchDepth: 1,
+    fetchTags: false,
+    showProgress: true,
     lfs: false,
     submodules: false,
     nestedSubmodules: false,
@@ -809,6 +821,7 @@ async function setup(testName: string): Promise<void> {
     sshKey: sshPath ? 'some ssh private key' : '',
     sshKnownHosts: '',
     sshStrict: true,
+    sshUser: '',
     workflowOrganizationId: 123456,
     setSafeDirectory: true,
     githubServerUrl: githubServerUrl

__test__/git-command-manager.test.ts

@@ -0,0 +1,378 @@
+import * as exec from '@actions/exec'
+import * as fshelper from '../lib/fs-helper'
+import * as commandManager from '../lib/git-command-manager'
+
+let git: commandManager.IGitCommandManager
+let mockExec = jest.fn()
+
+describe('git-auth-helper tests', () => {
+  beforeAll(async () => {})
+
+  beforeEach(async () => {
+    jest.spyOn(fshelper, 'fileExistsSync').mockImplementation(jest.fn())
+    jest.spyOn(fshelper, 'directoryExistsSync').mockImplementation(jest.fn())
+  })
+
+  afterEach(() => {
+    jest.restoreAllMocks()
+  })
+
+  afterAll(() => {})
+
+  it('branch list matches', async () => {
+    mockExec.mockImplementation((path, args, options) => {
+      console.log(args, options.listeners.stdout)
+
+      if (args.includes('version')) {
+        options.listeners.stdout(Buffer.from('2.18'))
+        return 0
+      }
+
+      if (args.includes('rev-parse')) {
+        options.listeners.stdline(Buffer.from('refs/heads/foo'))
+        options.listeners.stdline(Buffer.from('refs/heads/bar'))
+        return 0
+      }
+
+      return 1
+    })
+    jest.spyOn(exec, 'exec').mockImplementation(mockExec)
+    const workingDirectory = 'test'
+    const lfs = false
+    const doSparseCheckout = false
+    git = await commandManager.createCommandManager(
+      workingDirectory,
+      lfs,
+      doSparseCheckout
+    )
+
+    let branches = await git.branchList(false)
+
+    expect(branches).toHaveLength(2)
+    expect(branches.sort()).toEqual(['foo', 'bar'].sort())
+  })
+
+  it('ambiguous ref name output is captured', async () => {
+    mockExec.mockImplementation((path, args, options) => {
+      console.log(args, options.listeners.stdout)
+
+      if (args.includes('version')) {
+        options.listeners.stdout(Buffer.from('2.18'))
+        return 0
+      }
+
+      if (args.includes('rev-parse')) {
+        options.listeners.stdline(Buffer.from('refs/heads/foo'))
+        // If refs/tags/v1 and refs/heads/tags/v1 existed on this repository
+        options.listeners.errline(
+          Buffer.from("error: refname 'tags/v1' is ambiguous")
+        )
+        return 0
+      }
+
+      return 1
+    })
+    jest.spyOn(exec, 'exec').mockImplementation(mockExec)
+    const workingDirectory = 'test'
+    const lfs = false
+    const doSparseCheckout = false
+    git = await commandManager.createCommandManager(
+      workingDirectory,
+      lfs,
+      doSparseCheckout
+    )
+
+    let branches = await git.branchList(false)
+
+    expect(branches).toHaveLength(1)
+    expect(branches.sort()).toEqual(['foo'].sort())
+  })
+})
+
+describe('Test fetchDepth and fetchTags options', () => {
+  beforeEach(async () => {
+    jest.spyOn(fshelper, 'fileExistsSync').mockImplementation(jest.fn())
+    jest.spyOn(fshelper, 'directoryExistsSync').mockImplementation(jest.fn())
+    mockExec.mockImplementation((path, args, options) => {
+      console.log(args, options.listeners.stdout)
+
+      if (args.includes('version')) {
+        options.listeners.stdout(Buffer.from('2.18'))
+      }
+
+      return 0
+    })
+  })
+
+  afterEach(() => {
+    jest.restoreAllMocks()
+  })
+
+  it('should call execGit with the correct arguments when fetchDepth is 0 and fetchTags is true', 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: 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)
+
+    expect(mockExec).toHaveBeenCalledWith(
+      expect.any(String),
+      [
+        '-c',
+        'protocol.version=2',
+        'fetch',
+        '--no-tags',
+        '--prune',
+        '--no-recurse-submodules',
+        '--filter=filterValue',
+        'origin',
+        'refspec1',
+        'refspec2'
+      ],
+      expect.any(Object)
+    )
+  })
+
+  it('should call execGit with the correct arguments when fetchDepth is 1 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: 1,
+      fetchTags: false
+    }
+
+    await git.fetch(refSpec, options)
+
+    expect(mockExec).toHaveBeenCalledWith(
+      expect.any(String),
+      [
+        '-c',
+        'protocol.version=2',
+        'fetch',
+        '--no-tags',
+        '--prune',
+        '--no-recurse-submodules',
+        '--filter=filterValue',
+        '--depth=1',
+        'origin',
+        'refspec1',
+        'refspec2'
+      ],
+      expect.any(Object)
+    )
+  })
+
+  it('should call execGit with the correct arguments when fetchDepth is 1 and fetchTags is true', 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: 1,
+      fetchTags: true
+    }
+
+    await git.fetch(refSpec, options)
+
+    expect(mockExec).toHaveBeenCalledWith(
+      expect.any(String),
+      [
+        '-c',
+        'protocol.version=2',
+        'fetch',
+        '--prune',
+        '--no-recurse-submodules',
+        '--filter=filterValue',
+        '--depth=1',
+        'origin',
+        'refspec1',
+        'refspec2'
+      ],
+      expect.any(Object)
+    )
+  })
+
+  it('should call execGit with the correct arguments when showProgress is true', 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',
+      showProgress: true
+    }
+
+    await git.fetch(refSpec, options)
+
+    expect(mockExec).toHaveBeenCalledWith(
+      expect.any(String),
+      [
+        '-c',
+        'protocol.version=2',
+        'fetch',
+        '--no-tags',
+        '--prune',
+        '--no-recurse-submodules',
+        '--progress',
+        '--filter=filterValue',
+        'origin',
+        'refspec1',
+        'refspec2'
+      ],
+      expect.any(Object)
+    )
+  })
+
+  it('should call execGit with the correct arguments when fetchDepth is 42 and showProgress is true', 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: 42,
+      showProgress: true
+    }
+
+    await git.fetch(refSpec, options)
+
+    expect(mockExec).toHaveBeenCalledWith(
+      expect.any(String),
+      [
+        '-c',
+        'protocol.version=2',
+        'fetch',
+        '--no-tags',
+        '--prune',
+        '--no-recurse-submodules',
+        '--progress',
+        '--filter=filterValue',
+        '--depth=42',
+        'origin',
+        'refspec1',
+        'refspec2'
+      ],
+      expect.any(Object)
+    )
+  })
+
+  it('should call execGit with the correct arguments when fetchTags is true and showProgress is true', 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',
+      fetchTags: true,
+      showProgress: true
+    }
+
+    await git.fetch(refSpec, options)
+
+    expect(mockExec).toHaveBeenCalledWith(
+      expect.any(String),
+      [
+        '-c',
+        'protocol.version=2',
+        'fetch',
+        '--prune',
+        '--no-recurse-submodules',
+        '--progress',
+        '--filter=filterValue',
+        'origin',
+        'refspec1',
+        'refspec2'
+      ],
+      expect.any(Object)
+    )
+  })
+})

__test__/git-directory-helper.test.ts

@@ -281,6 +281,65 @@ describe('git-directory-helper tests', () => {
     expect(git.branchDelete).toHaveBeenCalledWith(false, 'local-branch-2')
   })
 
+  const cleanWhenSubmoduleStatusIsFalse =
+    'cleans when submodule status is false'
+
+  it(cleanWhenSubmoduleStatusIsFalse, async () => {
+    // Arrange
+    await setup(cleanWhenSubmoduleStatusIsFalse)
+    await fs.promises.writeFile(path.join(repositoryPath, 'my-file'), '')
+
+    //mock bad submodule
+
+    const submoduleStatus = git.submoduleStatus as jest.Mock<any, any>
+    submoduleStatus.mockImplementation(async (remote: boolean) => {
+      return false
+    })
+
+    // Act
+    await gitDirectoryHelper.prepareExistingDirectory(
+      git,
+      repositoryPath,
+      repositoryUrl,
+      clean,
+      ref
+    )
+
+    // Assert
+    const files = await fs.promises.readdir(repositoryPath)
+    expect(files).toHaveLength(0)
+    expect(git.tryClean).toHaveBeenCalled()
+  })
+
+  const doesNotCleanWhenSubmoduleStatusIsTrue =
+    'does not clean when submodule status is true'
+
+  it(doesNotCleanWhenSubmoduleStatusIsTrue, async () => {
+    // Arrange
+    await setup(doesNotCleanWhenSubmoduleStatusIsTrue)
+    await fs.promises.writeFile(path.join(repositoryPath, 'my-file'), '')
+
+    const submoduleStatus = git.submoduleStatus as jest.Mock<any, any>
+    submoduleStatus.mockImplementation(async (remote: boolean) => {
+      return true
+    })
+
+    // Act
+    await gitDirectoryHelper.prepareExistingDirectory(
+      git,
+      repositoryPath,
+      repositoryUrl,
+      clean,
+      ref
+    )
+
+    // Assert
+
+    const files = await fs.promises.readdir(repositoryPath)
+    expect(files.sort()).toEqual(['.git', 'my-file'])
+    expect(git.tryClean).toHaveBeenCalled()
+  })
+
   const removesLockFiles = 'removes lock files'
   it(removesLockFiles, async () => {
     // Arrange
@@ -403,6 +462,9 @@ async function setup(testName: string): Promise<void> {
     branchList: jest.fn(async () => {
       return []
     }),
+    disableSparseCheckout: jest.fn(),
+    sparseCheckout: jest.fn(),
+    sparseCheckoutNonConeMode: jest.fn(),
     checkout: jest.fn(),
     checkoutDetach: jest.fn(),
     config: jest.fn(),
@@ -423,6 +485,9 @@ async function setup(testName: string): Promise<void> {
     submoduleForeach: jest.fn(),
     submoduleSync: jest.fn(),
     submoduleUpdate: jest.fn(),
+    submoduleStatus: jest.fn(async () => {
+      return true
+    }),
     tagExists: jest.fn(),
     tryClean: jest.fn(async () => {
       return true
@@ -436,6 +501,7 @@ async function setup(testName: string): Promise<void> {
     }),
     tryReset: jest.fn(async () => {
       return true
-    })
+    }),
+    version: jest.fn()
   }
 }

__test__/git-version.test.ts

@@ -1,4 +1,5 @@
-import {GitVersion} from '../lib/git-version'
+import {GitVersion} from '../src/git-version'
+import {MinimumGitSparseCheckoutVersion} from '../src/git-command-manager'
 
 describe('git-version tests', () => {
   it('basics', async () => {
@@ -42,4 +43,44 @@ describe('git-version tests', () => {
     expect(version.checkMinimum(new GitVersion('5.1'))).toBeFalsy()
     expect(version.checkMinimum(new GitVersion('5.1.2'))).toBeFalsy()
   })
+
+  it('sparse checkout', async () => {
+    const minSparseVer = MinimumGitSparseCheckoutVersion
+    expect(new GitVersion('1.0').checkMinimum(minSparseVer)).toBeFalsy()
+    expect(new GitVersion('1.99').checkMinimum(minSparseVer)).toBeFalsy()
+    expect(new GitVersion('2.0').checkMinimum(minSparseVer)).toBeFalsy()
+    expect(new GitVersion('2.24').checkMinimum(minSparseVer)).toBeFalsy()
+    expect(new GitVersion('2.24.0').checkMinimum(minSparseVer)).toBeFalsy()
+    expect(new GitVersion('2.24.9').checkMinimum(minSparseVer)).toBeFalsy()
+    expect(new GitVersion('2.25').checkMinimum(minSparseVer)).toBeFalsy()
+    expect(new GitVersion('2.25.0').checkMinimum(minSparseVer)).toBeFalsy()
+    expect(new GitVersion('2.25.1').checkMinimum(minSparseVer)).toBeFalsy()
+    expect(new GitVersion('2.25.9').checkMinimum(minSparseVer)).toBeFalsy()
+    expect(new GitVersion('2.26').checkMinimum(minSparseVer)).toBeFalsy()
+    expect(new GitVersion('2.26.0').checkMinimum(minSparseVer)).toBeFalsy()
+    expect(new GitVersion('2.26.1').checkMinimum(minSparseVer)).toBeFalsy()
+    expect(new GitVersion('2.26.9').checkMinimum(minSparseVer)).toBeFalsy()
+    expect(new GitVersion('2.27').checkMinimum(minSparseVer)).toBeFalsy()
+    expect(new GitVersion('2.27.0').checkMinimum(minSparseVer)).toBeFalsy()
+    expect(new GitVersion('2.27.1').checkMinimum(minSparseVer)).toBeFalsy()
+    expect(new GitVersion('2.27.9').checkMinimum(minSparseVer)).toBeFalsy()
+    //                             /---------------------------------------
+    //         ^^^ before         /         after vvv
+    // --------------------------/
+    expect(new GitVersion('2.28').checkMinimum(minSparseVer)).toBeTruthy()
+    expect(new GitVersion('2.28.0').checkMinimum(minSparseVer)).toBeTruthy()
+    expect(new GitVersion('2.28.1').checkMinimum(minSparseVer)).toBeTruthy()
+    expect(new GitVersion('2.28.9').checkMinimum(minSparseVer)).toBeTruthy()
+    expect(new GitVersion('2.29').checkMinimum(minSparseVer)).toBeTruthy()
+    expect(new GitVersion('2.29.0').checkMinimum(minSparseVer)).toBeTruthy()
+    expect(new GitVersion('2.29.1').checkMinimum(minSparseVer)).toBeTruthy()
+    expect(new GitVersion('2.29.9').checkMinimum(minSparseVer)).toBeTruthy()
+    expect(new GitVersion('2.99').checkMinimum(minSparseVer)).toBeTruthy()
+    expect(new GitVersion('3.0').checkMinimum(minSparseVer)).toBeTruthy()
+    expect(new GitVersion('3.99').checkMinimum(minSparseVer)).toBeTruthy()
+    expect(new GitVersion('4.0').checkMinimum(minSparseVer)).toBeTruthy()
+    expect(new GitVersion('4.99').checkMinimum(minSparseVer)).toBeTruthy()
+    expect(new GitVersion('5.0').checkMinimum(minSparseVer)).toBeTruthy()
+    expect(new GitVersion('5.99').checkMinimum(minSparseVer)).toBeTruthy()
+  })
 })

__test__/input-helper.test.ts

@@ -79,7 +79,12 @@ describe('input-helper tests', () => {
     expect(settings.clean).toBe(true)
     expect(settings.commit).toBeTruthy()
     expect(settings.commit).toBe('1234567890123456789012345678901234567890')
+    expect(settings.filter).toBe(undefined)
+    expect(settings.sparseCheckout).toBe(undefined)
+    expect(settings.sparseCheckoutConeMode).toBe(true)
     expect(settings.fetchDepth).toBe(1)
+    expect(settings.fetchTags).toBe(false)
+    expect(settings.showProgress).toBe(true)
     expect(settings.lfs).toBe(false)
     expect(settings.ref).toBe('refs/heads/some-ref')
     expect(settings.repositoryName).toBe('some-repo')

__test__/ref-helper.test.ts

@@ -7,11 +7,11 @@ let git: IGitCommandManager
 
 describe('ref-helper tests', () => {
   beforeEach(() => {
-    git = ({} as unknown) as IGitCommandManager
+    git = {} as unknown as IGitCommandManager
   })
 
   it('getCheckoutInfo requires git', async () => {
-    const git = (null as unknown) as IGitCommandManager
+    const git = null as unknown as IGitCommandManager
     try {
       await refHelper.getCheckoutInfo(git, 'refs/heads/my/branch', commit)
       throw new Error('Should not reach here')

__test__/retry-helper.test.ts

@@ -68,7 +68,7 @@ describe('retry-helper tests', () => {
 
   it('all attempts fail succeeds', async () => {
     let attempts = 0
-    let error: Error = (null as unknown) as Error
+    let error: Error = null as unknown as Error
     try {
       await retryHelper.execute(() => {
         throw new Error(`some error ${++attempts}`)

__test__/verify-basic.sh

@@ -18,6 +18,20 @@ else
     exit 1
   fi
 
+  # Verify that sparse-checkout is disabled.
+  SPARSE_CHECKOUT_ENABLED=$(git -C ./basic config --local --get-all core.sparseCheckout)
+  if [ "$SPARSE_CHECKOUT_ENABLED" != "" ]; then
+    echo "Expected sparse-checkout to be disabled (discovered: $SPARSE_CHECKOUT_ENABLED)"
+    exit 1
+  fi
+
+  # Verify git configuration shows worktreeConfig is effectively disabled
+  WORKTREE_CONFIG_ENABLED=$(git -C ./basic config --local --get-all extensions.worktreeConfig)
+  if [[ "$WORKTREE_CONFIG_ENABLED" != "" ]]; then
+    echo "Expected extensions.worktreeConfig (boolean) to be disabled in git config.  This could be an artifact of sparse checkout functionality."
+    exit 1
+  fi
+
   # Verify auth token
   cd basic
   git fetch --no-tags --depth=1 origin +refs/heads/main:refs/remotes/origin/main

__test__/verify-fetch-filter.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+
+# Verify .git folder
+if [ ! -d "./fetch-filter/.git" ]; then
+  echo "Expected ./fetch-filter/.git folder to exist"
+  exit 1
+fi
+
+# Verify .git/config contains partialclonefilter
+
+CLONE_FILTER=$(git -C fetch-filter config --local --get remote.origin.partialclonefilter)
+
+if [ "$CLONE_FILTER" != "blob:none" ]; then
+  echo "Expected ./fetch-filter/.git/config to have 'remote.origin.partialclonefilter' set to 'blob:none'"
+  exit 1
+fi

__test__/verify-sparse-checkout-non-cone-mode.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+
+# Verify .git folder
+if [ ! -d "./sparse-checkout-non-cone-mode/.git" ]; then
+  echo "Expected ./sparse-checkout-non-cone-mode/.git folder to exist"
+  exit 1
+fi
+
+# Verify sparse-checkout (non-cone-mode)
+cd sparse-checkout-non-cone-mode
+
+ENABLED=$(git config --local --get-all core.sparseCheckout)
+
+if [ "$?" != "0" ]; then
+    echo "Failed to verify that sparse-checkout is enabled"
+    exit 1
+fi
+
+# Check that sparse-checkout is enabled
+if [ "$ENABLED" != "true" ]; then
+  echo "Expected sparse-checkout to be enabled (is: $ENABLED)"
+  exit 1
+fi
+
+SPARSE_CHECKOUT_FILE=$(git rev-parse --git-path info/sparse-checkout)
+
+if [ "$?" != "0" ]; then
+    echo "Failed to validate sparse-checkout"
+    exit 1
+fi
+
+# Check that sparse-checkout list is not empty
+if [ ! -f "$SPARSE_CHECKOUT_FILE" ]; then
+  echo "Expected sparse-checkout file to exist"
+  exit 1
+fi
+
+# Check that all folders from sparse-checkout exists
+for pattern in $(cat "$SPARSE_CHECKOUT_FILE")
+do
+  if [ ! -d "${pattern#/}" ]; then
+    echo "Expected directory '${pattern#/}' to exist"
+    exit 1
+  fi
+done
+
+# Verify that the root directory is not checked out
+if [ -f README.md ]; then
+  echo "Expected top-level files not to exist"
+  exit 1
+fi

__test__/verify-sparse-checkout.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+
+# Verify .git folder
+if [ ! -d "./sparse-checkout/.git" ]; then
+  echo "Expected ./sparse-checkout/.git folder to exist"
+  exit 1
+fi
+
+# Verify sparse-checkout
+cd sparse-checkout
+
+SPARSE=$(git sparse-checkout list)
+
+if [ "$?" != "0" ]; then
+    echo "Failed to validate sparse-checkout"
+    exit 1
+fi
+
+# Check that sparse-checkout list is not empty
+if [ -z "$SPARSE" ]; then
+  echo "Expected sparse-checkout list to not be empty"
+  exit 1
+fi
+
+# Check that all folders of the sparse checkout exist
+for pattern in $SPARSE
+do
+  if [ ! -d "$pattern" ]; then
+    echo "Expected directory '$pattern' to exist"
+    exit 1
+  fi
+done
+
+checkSparse () {
+  if [ ! -d "./$1" ]; then
+    echo "Expected directory '$1' to exist"
+    exit 1
+  fi
+
+  for file in $(git ls-tree -r --name-only HEAD $1)
+  do
+    if [ ! -f "$file" ]; then
+      echo "Expected file '$file' to exist"
+      exit 1
+    fi
+  done
+}
+
+# Check that all folders and their children have been checked out
+checkSparse __test__
+checkSparse .github
+checkSparse dist
+
+# Check that only sparse-checkout folders have been checked out
+for pattern in $(git ls-tree --name-only HEAD)
+do
+  if [ -d "$pattern" ]; then
+    if [[ "$pattern" != "__test__" && "$pattern" != ".github" && "$pattern" != "dist" ]]; then
+      echo "Expected directory '$pattern' to not exist"
+      exit 1
+    fi
+  fi
+done

action.yml

@@ -45,6 +45,10 @@ inputs:
       and `CheckHostIP=no` to the SSH command line. Use the input `ssh-known-hosts` to
       configure additional hosts.
     default: true
+  ssh-user:
+    description: >
+      The user to use when connecting to the remote SSH host. By default 'git' is used.
+    default: git
   persist-credentials:
     description: 'Whether to configure the token or SSH key with the local git config'
     default: true
@@ -53,9 +57,29 @@ inputs:
   clean:
     description: 'Whether to execute `git clean -ffdx && git reset --hard HEAD` before fetching'
     default: true
+  filter:
+    description: >
+      Partially clone against a given filter.
+      Overrides sparse-checkout if set.
+    default: null
+  sparse-checkout:
+    description: >
+      Do a sparse checkout on given patterns.
+      Each pattern should be separated with new lines.
+    default: null
+  sparse-checkout-cone-mode:
+    description: >
+      Specifies whether to use cone-mode when doing a sparse checkout.
+    default: true
   fetch-depth:
     description: 'Number of commits to fetch. 0 indicates all history for all branches and tags.'
     default: 1
+  fetch-tags:
+    description: 'Whether to fetch tags, even if fetch-depth > 0.'
+    default: false
+  show-progress:
+    description: 'Whether to show progress status output when fetching.'
+    default: true
   lfs:
     description: 'Whether to download Git-LFS files'
     default: false
@@ -75,6 +99,6 @@ inputs:
     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
 runs:
-  using: node16
+  using: node20
   main: dist/index.js
   post: dist/index.js

adrs/0153-checkout-v2.md

@@ -181,7 +181,7 @@ GITHUB_WORKSPACE=/home/runner/work/foo/foo
 RUNNER_WORKSPACE=/home/runner/work/foo
 ```
 
-V2 introduces a new contraint on the checkout path. The location must now be under `github.workspace`. Whereas the checkout@v1 constraint was one level up, under `runner.workspace`.
+V2 introduces a new constraint on the checkout path. The location must now be under `github.workspace`. Whereas the checkout@v1 constraint was one level up, under `runner.workspace`.
 
 V2 no longer changes `github.workspace` to follow wherever the self repo is checked-out.
 
@@ -287,4 +287,4 @@ Note:
 - Update samples to consume `actions/checkout@v2`
 - Job containers now require git in the PATH for checkout, otherwise fallback to REST API
 - Minimum git version 2.18
-- Update problem matcher logic regarding source file verification (runner)
+- Update problem matcher logic regarding source file verification (runner)

images/test-ubuntu-git.Dockerfile

@@ -0,0 +1,12 @@
+# Defines the test-ubuntu-git Container Image.
+# Consumed by actions/checkout CI/CD validation workflows.
+
+FROM ubuntu:latest
+
+RUN apt update
+RUN apt install -y git
+
+LABEL org.opencontainers.image.title="Ubuntu + git (validation image)"
+LABEL org.opencontainers.image.description="Ubuntu image with git pre-installed. Intended primarily for testing `actions/checkout` during CI/CD workflows."
+LABEL org.opencontainers.image.documentation="https://github.com/actions/checkout/tree/main/images/test-ubuntu-git.md"
+LABEL org.opencontainers.image.licenses=MIT

images/test-ubuntu-git.md

@@ -0,0 +1,15 @@
+# `test-ubuntu-git` Container Image
+
+[![Publish test-ubuntu-git Container](https://github.com/actions/checkout/actions/workflows/update-test-ubuntu-git.yml/badge.svg)](https://github.com/actions/checkout/actions/workflows/update-test-ubuntu-git.yml)
+
+## Purpose
+
+`test-ubuntu-git` is a container image hosted on the GitHub Container Registry, `ghcr.io`.  
+
+It is intended primarily for testing the [`actions/checkout` repository](https://github.com/actions/checkout) as part of `actions/checkout`'s CI/CD workflows.
+
+The composition of `test-ubuntu-git` is intentionally minimal.  It is comprised of [git](https://git-scm.com/) installed on top of a [base-level ubuntu image](https://hub.docker.com/_/ubuntu/tags).
+
+# License
+
+`test-ubuntu-git` is released under the [MIT License](/LICENSE).

jest.config.js

@@ -1,5 +1,6 @@
 module.exports = {
   clearMocks: true,
+  fakeTimers: {},
   moduleFileExtensions: ['js', 'ts'],
   testEnvironment: 'node',
   testMatch: ['**/*.test.ts'],

package.json

@@ -1,10 +1,9 @@
 {
   "name": "checkout",
-  "version": "3.1.0",
+  "version": "4.1.4",
   "description": "checkout action",
   "main": "lib/main.js",
   "scripts": {
-    "build-full": "npm i --package-lock && npm ci && npm run format && npm run build && npm run test",
     "build": "tsc && ncc build && node lib/misc/generate-docs.js",
     "format": "prettier --write '**/*.ts'",
     "format-check": "prettier --check '**/*.ts'",
@@ -29,27 +28,28 @@
   },
   "homepage": "https://github.com/actions/checkout#readme",
   "dependencies": {
-    "@actions/core": "^1.10.0",
-    "@actions/exec": "^1.0.1",
-    "@actions/github": "^2.2.0",
-    "@actions/io": "file:actions-io-1.1.3.tgz",
-    "@actions/tool-cache": "^1.1.2",
-    "uuid": "^3.3.3"
+    "@actions/core": "^1.10.1",
+    "@actions/exec": "^1.1.1",
+    "@actions/github": "^6.0.0",
+    "@actions/io": "^1.1.3",
+    "@actions/tool-cache": "^2.0.1",
+    "uuid": "^9.0.1"
   },
   "devDependencies": {
-    "@types/jest": "^27.0.2",
-    "@types/node": "^12.7.12",
-    "@types/uuid": "^3.4.6",
-    "@typescript-eslint/parser": "^5.1.0",
-    "@zeit/ncc": "^0.20.5",
-    "eslint": "^7.32.0",
-    "eslint-plugin-github": "^4.3.2",
-    "eslint-plugin-jest": "^25.2.2",
-    "jest": "^27.3.0",
-    "jest-circus": "^27.3.0",
-    "js-yaml": "^3.13.1",
-    "prettier": "^1.19.1",
-    "ts-jest": "^27.0.7",
-    "typescript": "^4.4.4"
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.12.7",
+    "@types/uuid": "^9.0.8",
+    "@typescript-eslint/eslint-plugin": "^7.7.1",
+    "@typescript-eslint/parser": "^7.7.1",
+    "@vercel/ncc": "^0.38.1",
+    "eslint": "^8.57.0",
+    "eslint-plugin-github": "^4.10.2",
+    "eslint-plugin-jest": "^28.2.0",
+    "jest": "^29.7.0",
+    "jest-circus": "^29.7.0",
+    "js-yaml": "^4.1.0",
+    "prettier": "^3.2.5",
+    "ts-jest": "^29.1.2",
+    "typescript": "^5.4.5"
   }
 }

src/fs-helper.ts

@@ -18,8 +18,9 @@ export function directoryExistsSync(path: string, required?: boolean): boolean {
     }
 
     throw new Error(
-      `Encountered an error when checking whether path '${path}' exists: ${(error as any)
-        ?.message ?? error}`
+      `Encountered an error when checking whether path '${path}' exists: ${
+        (error as any)?.message ?? error
+      }`
     )
   }
 
@@ -45,8 +46,9 @@ export function existsSync(path: string): boolean {
     }
 
     throw new Error(
-      `Encountered an error when checking whether path '${path}' exists: ${(error as any)
-        ?.message ?? error}`
+      `Encountered an error when checking whether path '${path}' exists: ${
+        (error as any)?.message ?? error
+      }`
     )
   }
 
@@ -67,8 +69,9 @@ export function fileExistsSync(path: string): boolean {
     }
 
     throw new Error(
-      `Encountered an error when checking whether path '${path}' exists: ${(error as any)
-        ?.message ?? error}`
+      `Encountered an error when checking whether path '${path}' exists: ${
+        (error as any)?.message ?? error
+      }`
     )
   }
 

src/git-auth-helper.ts

@@ -8,7 +8,7 @@ import * as path from 'path'
 import * as regexpHelper from './regexp-helper'
 import * as stateHelper from './state-helper'
 import * as urlHelper from './url-helper'
-import {default as uuid} from 'uuid/v4'
+import {v4 as uuid} from 'uuid'
 import {IGitCommandManager} from './git-command-manager'
 import {IGitSourceSettings} from './git-source-settings'
 
@@ -49,7 +49,7 @@ class GitAuthHelper {
     gitSourceSettings: IGitSourceSettings | undefined
   ) {
     this.git = gitCommandManager
-    this.settings = gitSourceSettings || (({} as unknown) as IGitSourceSettings)
+    this.settings = gitSourceSettings || ({} as unknown as IGitSourceSettings)
 
     // Token auth header
     const serverUrl = urlHelper.getServerUrl(this.settings.githubServerUrl)
@@ -247,7 +247,7 @@ class GitAuthHelper {
     if (this.settings.sshKnownHosts) {
       knownHosts += `# Begin from input known hosts\n${this.settings.sshKnownHosts}\n# end from input known hosts\n`
     }
-    knownHosts += `# Begin implicitly added github.com\ngithub.com ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ==\n# End implicitly added github.com\n`
+    knownHosts += `# Begin implicitly added github.com\ngithub.com ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCj7ndNxQowgcQnjshcLrqPEiiphnt+VTTvDP6mHBL9j1aNUkY4Ue1gvwnGLVlOhGeYrnZaMgRK6+PKCUXaDbC7qtbW8gIkhL7aGCsOr/C56SJMy/BCZfxd1nWzAOxSDPgVsmerOBYfNqltV9/hWCqBywINIR+5dIg6JTJ72pcEpEjcYgXkE2YEFXV1JHnsKgbLWNlhScqb2UmyRkQyytRLtL+38TGxkxCflmO+5Z8CSSNY7GidjMIZ7Q4zMjA2n1nGrlTDkzwDCsw+wqFPGQA179cnfGWOWRVruj16z6XyvxvjJwbz0wQZ75XK5tKSb7FNyeIEs4TT4jk+S4dhPeAUC5y+bDYirYgM4GC7uEnztnZyaVWQ7B381AK4Qdrwt51ZqExKbQpTUNn+EjqoTwvqNj4kqx5QUCI0ThS/YkOxJCXmPUWZbhjpCg56i+2aB6CmK2JGhn57K5mj0MNdBXA4/WnwH6XoPWJzK5Nyu2zB3nAZp+S5hpQs+p1vN1/wsjk=\n# End implicitly added github.com\n`
     this.sshKnownHostsPath = path.join(runnerTemp, `${uniqueId}_known_hosts`)
     stateHelper.setSshKnownHostsPath(this.sshKnownHostsPath)
     await fs.promises.writeFile(this.sshKnownHostsPath, knownHosts)

src/git-command-manager.ts

@@ -1,5 +1,6 @@
 import * as core from '@actions/core'
 import * as exec from '@actions/exec'
+import * as fs from 'fs'
 import * as fshelper from './fs-helper'
 import * as io from '@actions/io'
 import * as path from 'path'
@@ -10,12 +11,17 @@ import {GitVersion} from './git-version'
 
 // Auth header not supported before 2.9
 // Wire protocol v2 not supported before 2.18
+// sparse-checkout not [well-]supported before 2.28 (see https://github.com/actions/checkout/issues/1386)
 export const MinimumGitVersion = new GitVersion('2.18')
+export const MinimumGitSparseCheckoutVersion = new GitVersion('2.28')
 
 export interface IGitCommandManager {
   branchDelete(remote: boolean, branch: string): Promise<void>
   branchExists(remote: boolean, pattern: string): Promise<boolean>
   branchList(remote: boolean): Promise<string[]>
+  disableSparseCheckout(): Promise<void>
+  sparseCheckout(sparseCheckout: string[]): Promise<void>
+  sparseCheckoutNonConeMode(sparseCheckout: string[]): Promise<void>
   checkout(ref: string, startPoint: string): Promise<void>
   checkoutDetach(): Promise<void>
   config(
@@ -25,7 +31,15 @@ export interface IGitCommandManager {
     add?: boolean
   ): Promise<void>
   configExists(configKey: string, globalConfig?: boolean): Promise<boolean>
-  fetch(refSpec: string[], fetchDepth?: number): Promise<void>
+  fetch(
+    refSpec: string[],
+    options: {
+      filter?: string
+      fetchDepth?: number
+      fetchTags?: boolean
+      showProgress?: boolean
+    }
+  ): Promise<void>
   getDefaultBranch(repositoryUrl: string): Promise<string>
   getWorkingDirectory(): string
   init(): Promise<void>
@@ -41,19 +55,26 @@ export interface IGitCommandManager {
   submoduleForeach(command: string, recursive: boolean): Promise<string>
   submoduleSync(recursive: boolean): Promise<void>
   submoduleUpdate(fetchDepth: number, recursive: boolean): Promise<void>
+  submoduleStatus(): Promise<boolean>
   tagExists(pattern: string): Promise<boolean>
   tryClean(): Promise<boolean>
   tryConfigUnset(configKey: string, globalConfig?: boolean): Promise<boolean>
   tryDisableAutomaticGarbageCollection(): Promise<boolean>
   tryGetFetchUrl(): Promise<string>
   tryReset(): Promise<boolean>
+  version(): Promise<GitVersion>
 }
 
 export async function createCommandManager(
   workingDirectory: string,
-  lfs: boolean
+  lfs: boolean,
+  doSparseCheckout: boolean
 ): Promise<IGitCommandManager> {
-  return await GitCommandManager.createCommandManager(workingDirectory, lfs)
+  return await GitCommandManager.createCommandManager(
+    workingDirectory,
+    lfs,
+    doSparseCheckout
+  )
 }
 
 class GitCommandManager {
@@ -63,7 +84,9 @@ class GitCommandManager {
   }
   private gitPath = ''
   private lfs = false
+  private doSparseCheckout = false
   private workingDirectory = ''
+  private gitVersion: GitVersion = new GitVersion()
 
   // Private constructor; use createCommandManager()
   private constructor() {}
@@ -94,8 +117,11 @@ class GitCommandManager {
 
     // Note, this implementation uses "rev-parse --symbolic-full-name" because the output from
     // "branch --list" is more difficult when in a detached HEAD state.
-    // Note, this implementation uses "rev-parse --symbolic-full-name" because there is a bug
-    // in Git 2.18 that causes "rev-parse --symbolic" to output symbolic full names.
+
+    // TODO(https://github.com/actions/checkout/issues/786): this implementation uses
+    // "rev-parse --symbolic-full-name" because there is a bug
+    // in Git 2.18 that causes "rev-parse --symbolic" to output symbolic full names. When
+    // 2.18 is no longer supported, we can switch back to --symbolic.
 
     const args = ['rev-parse', '--symbolic-full-name']
     if (remote) {
@@ -104,24 +130,79 @@ class GitCommandManager {
       args.push('--branches')
     }
 
-    const output = await this.execGit(args)
+    const stderr: string[] = []
+    const errline: string[] = []
+    const stdout: string[] = []
+    const stdline: string[] = []
 
-    for (let branch of output.stdout.trim().split('\n')) {
-      branch = branch.trim()
-      if (branch) {
-        if (branch.startsWith('refs/heads/')) {
-          branch = branch.substr('refs/heads/'.length)
-        } else if (branch.startsWith('refs/remotes/')) {
-          branch = branch.substr('refs/remotes/'.length)
-        }
-
-        result.push(branch)
+    const listeners = {
+      stderr: (data: Buffer) => {
+        stderr.push(data.toString())
+      },
+      errline: (data: Buffer) => {
+        errline.push(data.toString())
+      },
+      stdout: (data: Buffer) => {
+        stdout.push(data.toString())
+      },
+      stdline: (data: Buffer) => {
+        stdline.push(data.toString())
       }
     }
 
+    // Suppress the output in order to avoid flooding annotations with innocuous errors.
+    await this.execGit(args, false, true, listeners)
+
+    core.debug(`stderr callback is: ${stderr}`)
+    core.debug(`errline callback is: ${errline}`)
+    core.debug(`stdout callback is: ${stdout}`)
+    core.debug(`stdline callback is: ${stdline}`)
+
+    for (let branch of stdline) {
+      branch = branch.trim()
+      if (!branch) {
+        continue
+      }
+
+      if (branch.startsWith('refs/heads/')) {
+        branch = branch.substring('refs/heads/'.length)
+      } else if (branch.startsWith('refs/remotes/')) {
+        branch = branch.substring('refs/remotes/'.length)
+      }
+
+      result.push(branch)
+    }
+
     return result
   }
 
+  async disableSparseCheckout(): Promise<void> {
+    await this.execGit(['sparse-checkout', 'disable'])
+    // Disabling 'sparse-checkout` leaves behind an undesirable side-effect in config (even in a pristine environment).
+    await this.tryConfigUnset('extensions.worktreeConfig', false)
+  }
+
+  async sparseCheckout(sparseCheckout: string[]): Promise<void> {
+    await this.execGit(['sparse-checkout', 'set', ...sparseCheckout])
+  }
+
+  async sparseCheckoutNonConeMode(sparseCheckout: string[]): Promise<void> {
+    await this.execGit(['config', 'core.sparseCheckout', 'true'])
+    const output = await this.execGit([
+      'rev-parse',
+      '--git-path',
+      'info/sparse-checkout'
+    ])
+    const sparseCheckoutPath = path.join(
+      this.workingDirectory,
+      output.stdout.trimRight()
+    )
+    await fs.promises.appendFile(
+      sparseCheckoutPath,
+      `\n${sparseCheckout.join('\n')}\n`
+    )
+  }
+
   async checkout(ref: string, startPoint: string): Promise<void> {
     const args = ['checkout', '--progress', '--force']
     if (startPoint) {
@@ -170,15 +251,31 @@ class GitCommandManager {
     return output.exitCode === 0
   }
 
-  async fetch(refSpec: string[], fetchDepth?: number): Promise<void> {
+  async fetch(
+    refSpec: string[],
+    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)) {
+    if (!refSpec.some(x => x === refHelper.tagsRefSpec) && !options.fetchTags) {
       args.push('--no-tags')
     }
 
-    args.push('--prune', '--progress', '--no-recurse-submodules')
-    if (fetchDepth && fetchDepth > 0) {
-      args.push(`--depth=${fetchDepth}`)
+    args.push('--prune', '--no-recurse-submodules')
+    if (options.showProgress) {
+      args.push('--progress')
+    }
+
+    if (options.filter) {
+      args.push(`--filter=${options.filter}`)
+    }
+
+    if (options.fetchDepth && options.fetchDepth > 0) {
+      args.push(`--depth=${options.fetchDepth}`)
     } else if (
       fshelper.fileExistsSync(
         path.join(this.workingDirectory, '.git', 'shallow')
@@ -257,8 +354,8 @@ class GitCommandManager {
   }
 
   async log1(format?: string): Promise<string> {
-    var args = format ? ['log', '-1', format] : ['log', '-1']
-    var silent = format ? false : true
+    const args = format ? ['log', '-1', format] : ['log', '-1']
+    const silent = format ? false : true
     const output = await this.execGit(args, false, silent)
     return output.stdout
   }
@@ -326,6 +423,12 @@ class GitCommandManager {
     await this.execGit(args)
   }
 
+  async submoduleStatus(): Promise<boolean> {
+    const output = await this.execGit(['submodule', 'status'], true)
+    core.debug(output.stdout)
+    return output.exitCode === 0
+  }
+
   async tagExists(pattern: string): Promise<boolean> {
     const output = await this.execGit(['tag', '--list', pattern])
     return !!output.stdout.trim()
@@ -383,19 +486,29 @@ class GitCommandManager {
     return output.exitCode === 0
   }
 
+  async version(): Promise<GitVersion> {
+    return this.gitVersion
+  }
+
   static async createCommandManager(
     workingDirectory: string,
-    lfs: boolean
+    lfs: boolean,
+    doSparseCheckout: boolean
   ): Promise<GitCommandManager> {
     const result = new GitCommandManager()
-    await result.initializeCommandManager(workingDirectory, lfs)
+    await result.initializeCommandManager(
+      workingDirectory,
+      lfs,
+      doSparseCheckout
+    )
     return result
   }
 
   private async execGit(
     args: string[],
     allowAllExitCodes = false,
-    silent = false
+    silent = false,
+    customListeners = {}
   ): Promise<GitOutput> {
     fshelper.directoryExistsSync(this.workingDirectory, true)
 
@@ -409,28 +522,36 @@ class GitCommandManager {
       env[key] = this.gitEnv[key]
     }
 
-    const stdout: string[] = []
+    const defaultListener = {
+      stdout: (data: Buffer) => {
+        stdout.push(data.toString())
+      }
+    }
 
+    const mergedListeners = {...defaultListener, ...customListeners}
+
+    const stdout: string[] = []
     const options = {
       cwd: this.workingDirectory,
       env,
       silent,
       ignoreReturnCode: allowAllExitCodes,
-      listeners: {
-        stdout: (data: Buffer) => {
-          stdout.push(data.toString())
-        }
-      }
+      listeners: mergedListeners
     }
 
     result.exitCode = await exec.exec(`"${this.gitPath}"`, args, options)
     result.stdout = stdout.join('')
+
+    core.debug(result.exitCode.toString())
+    core.debug(result.stdout)
+
     return result
   }
 
   private async initializeCommandManager(
     workingDirectory: string,
-    lfs: boolean
+    lfs: boolean,
+    doSparseCheckout: boolean
   ): Promise<void> {
     this.workingDirectory = workingDirectory
 
@@ -445,23 +566,23 @@ class GitCommandManager {
 
     // Git version
     core.debug('Getting git version')
-    let gitVersion = new GitVersion()
+    this.gitVersion = new GitVersion()
     let gitOutput = await this.execGit(['version'])
     let stdout = gitOutput.stdout.trim()
     if (!stdout.includes('\n')) {
       const match = stdout.match(/\d+\.\d+(\.\d+)?/)
       if (match) {
-        gitVersion = new GitVersion(match[0])
+        this.gitVersion = new GitVersion(match[0])
       }
     }
-    if (!gitVersion.isValid()) {
+    if (!this.gitVersion.isValid()) {
       throw new Error('Unable to determine git version')
     }
 
     // Minimum git version
-    if (!gitVersion.checkMinimum(MinimumGitVersion)) {
+    if (!this.gitVersion.checkMinimum(MinimumGitVersion)) {
       throw new Error(
-        `Minimum required git version is ${MinimumGitVersion}. Your git ('${this.gitPath}') is ${gitVersion}`
+        `Minimum required git version is ${MinimumGitVersion}. Your git ('${this.gitPath}') is ${this.gitVersion}`
       )
     }
 
@@ -493,8 +614,16 @@ class GitCommandManager {
       }
     }
 
+    this.doSparseCheckout = doSparseCheckout
+    if (this.doSparseCheckout) {
+      if (!this.gitVersion.checkMinimum(MinimumGitSparseCheckoutVersion)) {
+        throw new Error(
+          `Minimum Git version required for sparse checkout is ${MinimumGitSparseCheckoutVersion}. Your git ('${this.gitPath}') is ${this.gitVersion}`
+        )
+      }
+    }
     // Set the user agent
-    const gitHttpUserAgent = `git/${gitVersion} (github-actions-checkout)`
+    const gitHttpUserAgent = `git/${this.gitVersion} (github-actions-checkout)`
     core.debug(`Set git useragent to: ${gitHttpUserAgent}`)
     this.gitEnv['GIT_HTTP_USER_AGENT'] = gitHttpUserAgent
   }