How to Use Sparse Checkout in actions/checkout: Configuration Guide and Examples

Set the sparse-checkout input to a multiline list of directory patterns to fetch only specific portions of your repository, and use sparse-checkout-cone-mode: false only when you need to target individual files.

The actions/checkout GitHub Action supports Git's sparse-checkout feature to reduce clone times and disk usage by fetching only specific paths from your repository. This is particularly valuable for monorepos or workflows that only need a subset of the source tree. By configuring sparse checkout in actions/checkout, you can significantly reduce network traffic and speed up CI/CD pipelines.

Sparse Checkout Inputs and Options

The action exposes three inputs that control sparse checkout behavior, parsed in src/input-helper.ts (lines 95-102):

• sparse-checkout: A multiline list of path patterns that should be checked out. Each line represents a separate pattern. Defaults to null (disabled).
• sparse-checkout-cone-mode: Enables Git 2.25+ cone mode for faster and simpler pattern syntax. Defaults to true. Set to false to use classic pattern matching.
• filter: Git partial clone filter (e.g., blob:none). When set, this overrides sparse-checkout because Git applies the filter before sparse-checkout rules.

Cone Mode vs. Classic Patterns

When sparse-checkout-cone-mode is true (the default), the action uses Git's cone mode, which treats each line as a top-level directory or file path. This is the recommended approach for most use cases. To check out individual files or use complex wildcard patterns, you must disable cone mode and use classic pattern matching syntax.

How Sparse Checkout Works Internally

The sparse checkout implementation spans three key source files in the repository:

Input Validation

In src/input-helper.ts, the action reads and normalizes the multiline sparse-checkout value and the boolean sparse-checkout-cone-mode flag. This validation ensures that the inputs are properly formatted before being passed to the Git command manager.

Git Command Execution

The src/git-command-manager.ts file (lines 197-204) handles the underlying Git operations. When sparse checkout is enabled, the action executes a sequence of commands: it first disables any existing sparse-checkout configuration with git sparse-checkout disable, then enables the requested mode using git sparse-checkout set with the provided patterns.

Version Compatibility

Before executing sparse-checkout commands, src/git-source-provider.ts (lines 255-257) verifies that the runner's Git version is at least 2.28. If the version check fails, the action disables sparse-checkout to prevent errors on older Git versions.

Configuration Examples

Checkout Specific Directories (Cone Mode)

Use cone mode to fetch only specific top-level directories. This is the most common configuration:

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

Checkout a Single File (Classic Mode)

To fetch a specific file, you must disable cone mode because cone mode only supports directory-level patterns:

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

Combine with Shallow Fetch

Optimize further by limiting history depth while using sparse checkout:

- uses: actions/checkout@v7
  with:
    sparse-checkout: |
      src/
    fetch-depth: 1

Repository Root Only

Fetch only the root directory contents without subdirectories:

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

Filter Override Example

When using the filter input for partial clone, note that it takes precedence over sparse-checkout:

- uses: actions/checkout@v7
  with:
    filter: blob:none
    sparse-checkout: |
      src/

Important Considerations

Filter Precedence: When the filter input is set (e.g., blob:none), it overrides sparse-checkout settings. Git applies the filter before evaluating sparse-checkout rules, which may result in different behavior than expected from path patterns alone.

Git Version Requirement: The action requires Git 2.28 or higher on the runner. The version check in src/git-source-provider.ts ensures compatibility before attempting to execute sparse-checkout commands.

Pattern Syntax: In cone mode (default), patterns are simple directory or file paths. In classic mode (when cone mode is disabled), you can use Git's full pattern syntax including wildcards and negations.

Summary

• Use sparse-checkout with a multiline list to limit fetched paths to specific directories or files
• Keep sparse-checkout-cone-mode: true (default) for directory-level inclusion and better performance
• Set sparse-checkout-cone-mode: false when you need file-level patterns or complex wildcards
• Ensure your runner has Git 2.28 or higher, as verified by the action in src/git-source-provider.ts
• Remember that the filter input overrides sparse-checkout when both are specified

Frequently Asked Questions

Why is my sparse checkout not working?

Check that your runner has Git 2.28 or higher. The action validates the Git version in src/git-source-provider.ts and silently disables sparse-checkout on older versions to prevent command failures. You can also verify that your patterns exist in the target commit and that you're using the correct syntax for your cone mode setting.

Can I use sparse checkout with a shallow clone?

Yes. The sparse-checkout and fetch-depth inputs work together without conflict. Set fetch-depth: 1 to create a shallow clone while still filtering paths to only the directories you need, optimizing both network transfer and disk usage.

How do I checkout just one file?

You must set sparse-checkout-cone-mode: false because cone mode only supports directory-level patterns. Then list the specific file path in the sparse-checkout input. According to the implementation in src/git-command-manager.ts, this switches to classic pattern mode which supports individual file paths.

What happens if I use the filter input with sparse checkout?

The filter input takes precedence over sparse-checkout. When both are set, Git applies the partial clone filter first (e.g., excluding blobs), then applies sparse-checkout rules to the remaining objects. This is handled by the action's input processing in src/input-helper.ts, where filter settings are validated separately from sparse-checkout patterns.

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