Understanding sparse-checkout-cone-mode in actions/checkout: A Complete Guide

The sparse-checkout-cone-mode input in actions/checkout controls whether Git uses the faster cone-mode algorithm (default) or the legacy pattern-matching syntax when performing a sparse checkout.

When you need to clone only specific parts of a repository in your GitHub Actions workflows, the actions/checkout action provides sparse checkout functionality. The sparse-checkout-cone-mode boolean input determines which underlying Git algorithm handles your file patterns, directly impacting performance and pattern syntax flexibility.

What Is sparse-checkout-cone-mode?

Cone-mode is a simplified sparse-checkout algorithm introduced in Git 2.25 that optimizes performance for directory-based patterns. When enabled, Git interprets each pattern in your sparse-checkout list as a top-level directory or file path, using an efficient internal data structure that reduces memory consumption and speeds up index updates.

When disabled, the action falls back to the classic sparse-checkout algorithm that supports the full pattern syntax—including globbing (*), negation (!), and recursive wildcards—but operates significantly slower due to legacy pattern-matching overhead.

According to the source code in actions/checkout, the input is parsed in src/input-helper.ts:

result.sparseCheckoutConeMode =
  (core.getInput('sparse-checkout-cone-mode') || 'true').toUpperCase() === 'TRUE';

This logic establishes true as the default value, meaning cone-mode is automatically enabled unless explicitly disabled.

How the Input Translates to Git Commands

The value of sparse-checkout-cone-mode directly influences the Git commands executed by the action. When set to true, the action invokes:

git sparse-checkout set --cone <patterns>

When set to false, the action omits the --cone flag:

git sparse-checkout set <patterns>

This distinction is critical because the --cone flag restricts pattern interpretation to directory-style paths only, while the non-cone mode allows complex pattern matching at the cost of performance.

When to Enable vs Disable Cone Mode

Use sparse-checkout-cone-mode: true (Default) For:

• Directory-only patterns such as src/ or docs/
• Maximum performance in large repositories where you only need specific folders
• Reduced CI/CD execution time due to faster index updates and fewer Git processes
• Simpler configuration when you don't need advanced pattern matching

Use sparse-checkout-cone-mode: false For:

• Complex pattern syntax including wildcards (*.md), negation (!README.md), or brace expansion
• File-level exclusions where you need to check out a directory but exclude specific file types
• Legacy compatibility with existing sparse-checkout definitions using full pattern syntax

The repository includes dedicated test scripts verifying both behaviors: __test__/verify-sparse-checkout.sh validates cone-mode functionality, while __test__/verify-sparse-checkout-non-cone-mode.sh ensures legacy pattern handling works correctly when the flag is disabled.

Configuration Examples

Enable Cone Mode (Default Behavior)

When checking out only specific directories with simple path patterns, rely on the default cone-mode for optimal performance:

- uses: actions/checkout@v4
  with:
    sparse-checkout: |
      src
      docs
      .github
    # sparse-checkout-cone-mode defaults to true

Disable Cone Mode for Complex Patterns

When you require globbing or negation patterns, explicitly disable cone-mode:

- uses: actions/checkout@v4
  with:
    sparse-checkout: |
      *.md
      !README.md
      src/**/*.test.js
    sparse-checkout-cone-mode: false

Summary

• Cone-mode (sparse-checkout-cone-mode: true) provides faster, memory-efficient sparse checkouts for directory-based patterns and is the default setting in actions/checkout.
• Legacy mode (sparse-checkout-cone-mode: false) supports full pattern syntax including globs and negation but executes slower due to complex pattern-matching algorithms.
• The input is parsed in src/input-helper.ts with a default value of true, translating directly to the presence or absence of the --cone flag in git sparse-checkout set commands.
• Choose cone-mode for simple directory paths and maximum performance; disable it only when you need advanced pattern matching syntax.

Frequently Asked Questions

What is the default value of sparse-checkout-cone-mode?

The default value is true. As implemented in src/input-helper.ts, the action automatically enables cone-mode unless you explicitly set sparse-checkout-cone-mode: false in your workflow configuration. This default is also documented in the README.md file lines 32-34.

Does cone-mode work with all Git versions?

No, cone-mode requires Git 2.25 or later. The actions/checkout action typically runs on GitHub-hosted runners with modern Git versions, but if you use self-hosted runners with older Git installations, the cone-mode feature may not be available or may behave unexpectedly.

Can I use wildcards with sparse-checkout-cone-mode enabled?

No. When sparse-checkout-cone-mode is set to true, Git interprets patterns as literal directory or file paths only. If your workflow requires wildcard patterns such as *.md or negation patterns like !test/, you must set sparse-checkout-cone-mode: false to use the legacy sparse-checkout algorithm.

Is there a performance difference between cone-mode and legacy mode?

Yes, significant performance differences exist. Cone-mode uses a newer internal data structure in Git that yields quicker index updates and consumes less memory, making it ideal for large repositories. The legacy mode requires more processing power to evaluate complex patterns against the repository index, resulting in slower checkout operations.

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