How to Configure Sparse Checkout in actions/checkout for Specific Directories

Set the sparse-checkout input with the directories or files you need, and optionally adjust sparse-checkout-cone-mode to control whether Git uses fast directory-level matching or precise file-level patterns.

The actions/checkout GitHub Action supports Git’s sparse checkout feature, allowing you to fetch only specific directories instead of cloning the entire repository. This significantly reduces network traffic and speeds up CI/CD workflows, particularly for large monorepos with multiple projects. According to the source code in actions/checkout, the action automatically handles pattern parsing and Git command execution when you configure the appropriate inputs.

Understanding Sparse Checkout Inputs

The sparse-checkout Input

The primary input for partial clones is sparse-checkout, which accepts multiline patterns defining which files and directories to include. In [src/input-helper.ts](https://github.com/actions/checkout/blob/main/src/input-helper.ts#L112-L119), the action reads this input and processes each line as a separate pattern. The action writes these patterns to Git’s sparse-checkout file before initializing the repository.

Cone Mode vs. Non-Cone Mode

The sparse-checkout-cone-mode input controls Git’s pattern matching algorithm. When set to true (the default), cone mode enables a fast directory-level matching algorithm optimized for CI/CD performance. Set it to false to enable precise file-level pattern matching, which is necessary when you need individual files scattered across different directories rather than entire folder structures.

Implementation Details from Source Code

Input Processing

The action parses your configuration in src/input-helper.ts, where it extracts the multiline sparse-checkout value and prepares it for the Git command manager. This processing ensures that each line you provide becomes a distinct inclusion rule passed to Git’s configuration.

Git Command Execution

In [src/git-command-manager.ts](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts#L197-L211), the action implements the sparse checkout workflow through precise Git operations. It first disables any existing sparse-checkout configuration to ensure a clean state, then writes your new patterns to Git’s sparse-checkout file and enables the feature. This reset-and-apply approach prevents stale patterns from previous workflow runs from affecting your current checkout.

Version Compatibility

The source code in src/git-command-manager.ts (line 14) and src/git-source-provider.ts includes runtime checks for Git version 2.28. If the runner uses an older Git version, the action automatically disables sparse checkout to prevent command failures, falling back to a full repository clone.

Configuration Examples for Specific Directories

Fetching Only Root Files

To fetch only the repository root without any subdirectories, use a single dot pattern:

- uses: actions/checkout@v7
  with:
    sparse-checkout: .

Selecting Multiple Directories

Use cone mode (the default) to fetch specific folders efficiently:

- uses: actions/checkout@v7
  with:
    sparse-checkout: |
      .github
      src

Checking Out Individual Files

Disable cone mode when you need specific files rather than entire directories:

- uses: actions/checkout@v7
  with:
    sparse-checkout: |
      README.md
    sparse-checkout-cone-mode: false

Combining with Branch Selection

Configure sparse checkout alongside specific branch references or commit SHAs:

- uses: actions/checkout@v7
  with:
    ref: feature/awesome
    sparse-checkout: |
      docs
      lib/utils
    sparse-checkout-cone-mode: true

Summary

• The sparse-checkout input accepts multiline patterns processed by src/input-helper.ts to determine which files to fetch
• Cone mode (sparse-checkout-cone-mode: true) provides faster performance for directory-level patterns using optimized algorithms
• The action automatically resets existing sparse-checkout configurations before applying new patterns, ensuring clean state
• Git version 2.28 or later is required; older versions trigger automatic fallback to full clones in src/git-source-provider.ts
• Disable cone mode when you need to checkout individual files rather than complete directories

Frequently Asked Questions

What Git version is required for sparse checkout in actions/checkout?

Sparse checkout requires Git 2.28 or later. The action automatically detects the Git version on the runner and disables sparse checkout if the version is older than 2.28, as implemented in src/git-command-manager.ts and src/git-source-provider.ts. This prevents workflow failures on older runner images.

Why should I use cone mode for sparse checkout?

Cone mode uses a simplified pattern matching algorithm that significantly speeds up operations when you're including entire directories. According to the actions/checkout source code, cone mode is enabled by default because it provides better performance for the typical CI/CD use case of checking out specific project folders within a monorepo.

Can I exclude specific directories instead of including them?

Git's sparse checkout works on an inclusion basis. To exclude directories, you must define patterns that include everything except what you want to exclude, or use negation patterns when cone mode is set to false. The actions/checkout action passes your patterns directly to Git's sparse-checkout configuration without modification.

What happens if my sparse-checkout patterns overlap?

Git processes sparse-checkout patterns in order, with later patterns overriding earlier ones when conflicts occur. The actions/checkout action writes your patterns exactly as provided in the YAML configuration to the sparse-checkout file, maintaining the order you specify in the multiline input.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}