Sparse Checkout Modes in actions/checkout: Cone vs Non-Cone Explained

actions/checkout supports two sparse checkout modes—cone mode (default) for directory prefixes and non-cone (legacy) mode for file-level glob patterns—controlled by the sparse-checkout-cone-mode input.

The actions/checkout GitHub Action provides sparse checkout capabilities to fetch only specific portions of a repository, significantly reducing clone times and disk usage in CI/CD workflows. Understanding the different sparse checkout modes available in this action is essential for optimizing your pipeline performance. The implementation in actions/checkout distinguishes between modern cone-mode patterns and legacy path-matching algorithms to handle various repository filtering scenarios.

Cone Mode vs Non-Cone Mode

Cone Mode (Default)

In cone mode, which is the default behavior when sparse-checkout-cone-mode is set to true or left unspecified, patterns are treated as directory prefixes. According to the actions/checkout source code in src/inputs.ts, this mode interprets each line in the sparse-checkout input as a literal directory path, making the checkout operation fast and memory-efficient. This approach leverages Git's modern cone-mode sparse-checkout algorithm, which optimizes performance for large monorepos by avoiding complex glob matching in favor of simple directory inclusion.

Non-Cone (Legacy) Mode

When sparse-checkout-cone-mode is explicitly set to false, the action switches to non-cone mode, which uses the older path-matching algorithm. As implemented in src/main.ts, this mode treats each pattern as a glob expression that can match individual files, enabling complex filtering scenarios. This mode is required when you need to checkout a single specific file or use advanced glob patterns that do not conform to directory prefixes.

Configuring Sparse Checkout in GitHub Actions

The sparse-checkout input accepts a newline-separated list of patterns, while sparse-checkout-cone-mode determines how those patterns are interpreted. According to the README.md documentation, when using the filter input for partial clones, it will override any sparse-checkout configuration if both are provided.

Cone Mode Examples

Fetch only the root directory using default cone mode:

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

Fetch specific folders in cone mode:

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

Non-Cone Mode Example

Fetch a single file using legacy pattern matching:

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

Implementation Architecture

The sparse checkout functionality is orchestrated across several key files in the repository. The src/inputs.ts file defines the sparse-checkout and sparse-checkout-cone-mode inputs along with their default values, while src/main.ts implements the core logic that parses these inputs and executes the appropriate Git commands to apply the selected mode. The README.md provides the canonical documentation for these configuration options, outlining the behavior differences between cone mode and non-cone mode implementations.

Summary

• Cone mode is the default sparse checkout mode in actions/checkout, treating patterns as directory prefixes for optimal performance and simplified pattern matching.
• Non-cone mode enables file-level and glob pattern matching by setting sparse-checkout-cone-mode: false, which is required for single-file checkouts and complex filtering.
• Both modes use the sparse-checkout input with newline-separated patterns, but interpret them differently based on the cone-mode boolean setting.
• The filter input for partial clones overrides sparse-checkout configurations when specified in the workflow.
• Implementation details are located in src/inputs.ts for input definitions and src/main.ts for the execution logic that runs the underlying Git sparse-checkout commands.

Frequently Asked Questions

What is the default sparse checkout mode in actions/checkout?

Cone mode is the default sparse checkout mode. When you use the sparse-checkout input without specifying sparse-checkout-cone-mode, or when you explicitly set it to true, the action treats all patterns as directory prefixes using Git's modern cone-mode algorithm as implemented in the action's source code.

When should I use non-cone mode instead of cone mode?

Use non-cone mode when you need to checkout individual files rather than entire directories, or when you require complex glob patterns that match specific file paths rather than directory prefixes. Set sparse-checkout-cone-mode: false to enable this legacy path-matching behavior required for single-file selection.

Can I use sparse checkout with partial clone filters?

Yes, but the filter input takes precedence over sparse-checkout settings. According to the actions/checkout documentation, if you specify a partial clone filter using the filter input, it will override any sparse-checkout configuration you have provided in the same step.

How do I checkout a single file using actions/checkout?

To checkout a single file, you must set sparse-checkout-cone-mode: false and specify the exact file path in the sparse-checkout input. This disables the directory-based cone mode and allows the pattern to match the specific file path using the legacy glob matching algorithm.

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