What is sparse-checkout-cone-mode in actions/checkout?

The sparse-checkout-cone-mode input controls whether Git's cone-mode algorithm interprets sparse-checkout patterns as directory prefixes (when true) or arbitrary glob patterns (when false), defaulting to true for optimal performance.

The actions/checkout GitHub Action enables selective repository downloads through sparse checkout functionality. The sparse-checkout-cone-mode input determines how the action interprets the patterns you specify when performing a partial clone. This setting directly impacts which Git commands the action executes and how efficiently it filters the repository tree.

How sparse-checkout-cone-mode Works Internally

When sparse-checkout-cone-mode is set to true (the default), the action executes git sparse-checkout set --cone after initializing the sparse-checkout patterns. This cone mode interprets your patterns as directory prefixes rather than complex glob patterns, resulting in fewer Git operations and faster checkouts.

The implementation spans three key files in the repository:

• Input parsing: src/input-helper.ts (lines 101-104) reads the workflow input and converts it to a boolean.
• Settings storage: src/git-source-settings.ts (lines 42-45) defines the IGitSourceSettings interface where the flag is stored as sparseCheckoutConeMode.
• Execution logic: src/git-source-provider.ts (lines 261-267) checks this flag to decide whether to invoke git sparse-checkout set with or without the --cone argument.

If you set the input to false, the action falls back to classic sparse-checkout behavior, passing your patterns directly to Git without the cone-mode optimization.

Configuration Examples

Standard Usage with Cone Mode Enabled

Since true is the default, you only need to specify this explicitly for clarity:

name: Sparse checkout with cone mode
on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          sparse-checkout: |
            src/
            docs/
          sparse-checkout-cone-mode: true  # Optional; defaults to true

Legacy Patterns Requiring Non-Cone Mode

Disable cone mode when using complex glob patterns that don't represent directory prefixes:

name: Sparse checkout with legacy patterns
on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          sparse-checkout: |
            src/**/*.ts
            docs/**/*.md
          sparse-checkout-cone-mode: false  # Required for complex globs

When to Disable Cone Mode

According to the actions/checkout source code, you should set sparse-checkout-cone-mode: false in two specific scenarios:

Legacy Pattern Compatibility: Workflows using complex glob patterns (e.g., */src/** or **/test/**) that don't map cleanly to directory prefixes require non-cone mode. Cone mode only recognizes patterns that match complete directory trees.

Git Version Compatibility: CI runners using Git versions older than 2.25 may not support cone mode. Disabling this option ensures the sparse checkout succeeds on older toolchains.

Important: This setting only takes effect when you provide the sparse-checkout input. If sparse-checkout is omitted, the action performs a full clone regardless of the cone-mode setting.

Summary

• The sparse-checkout-cone-mode input defaults to true in actions/checkout, enabling Git's cone-mode algorithm for faster sparse checkouts.
• When enabled, patterns are interpreted as directory prefixes via git sparse-checkout set --cone as implemented in src/git-source-provider.ts.
• Set it to false for complex glob patterns or older Git versions (< 2.25) that lack cone-mode support.
• The setting is parsed in src/input-helper.ts (lines 101-104) and stored in the IGitSourceSettings interface.
• Without the sparse-checkout input, this setting has no effect on the checkout behavior.

Frequently Asked Questions

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

The default value is true (represented as the string 'true' in workflow YAML). This aligns with Git's recommended default for versions 2.25 and later, where cone mode provides better performance for sparse checkouts.

Does sparse-checkout-cone-mode work without the sparse-checkout input?

No. The sparse-checkout-cone-mode setting only affects the checkout process when you explicitly provide the sparse-checkout input with specific patterns. Without sparse-checkout patterns, the action performs a full repository clone regardless of this setting.

Why would I set sparse-checkout-cone-mode to false?

You should disable cone mode when your workflow uses complex glob patterns like */src/** or **/*.md that don't represent simple directory prefixes. Additionally, set it to false when running on CI runners with Git versions older than 2.25 that lack cone-mode support.

Where is sparse-checkout-cone-mode defined in the action?

The input is defined in action.yml (lines 70-74) and documented in the README. The runtime implementation spans src/input-helper.ts for parsing, src/git-source-settings.ts for the interface definition, and src/git-source-provider.ts for the execution logic that invokes the appropriate Git commands.

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