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

actions/checkout supports two distinct sparse checkout implementation modes—cone-mode (default) which leverages Git 2.28+ directory pattern matching for optimal performance, and non-cone legacy mode which manually configures the info/sparse-checkout file for backward compatibility.

The sparse checkout implementation in actions/checkout allows GitHub Actions workflows to clone only specific portions of a repository, significantly reducing fetch time for large monorepos. According to the actions/checkout source code, the action abstracts Git's native sparse-checkout capabilities behind a boolean input flag that selects between modern cone-mode patterns and legacy path-based matching. Understanding these two implementations ensures you select the appropriate method for your Git version and pattern complexity requirements.

The Two Sparse Checkout Implementation Modes

Cone-Mode (Default)

The cone-mode implementation relies on Git 2.28 or later and executes the git sparse-checkout set command with directory prefix patterns. This approach treats pattern entries as directory cones, offering faster performance and simpler syntax for including entire directory subtrees. In src/git-command-manager.ts, the GitCommandManager.sparseCheckout() method (lines 202-204) handles this implementation by invoking the modern Git CLI interface. Cone-mode is automatically selected when the sparse-checkout-cone-mode input is omitted or explicitly set to true.

Non-Cone (Legacy) Mode

The non-cone implementation activates when sparse-checkout-cone-mode: false is specified, enabling pre-2.28 Git compatibility. This mode sets the core.sparseCheckout configuration to true and writes patterns directly to the .git/info/sparse-checkout file, supporting full path and glob pattern matching rather than directory cones. The source code in src/git-command-manager.ts implements this via the GitCommandManager.sparseCheckoutNonConeMode() method spanning lines 206-221, which manually handles file I/O for the sparse-checkout definition.

Internal Architecture and Source Code

Input Parsing in input-helper.ts

The boolean flag determining which sparse checkout implementation to use is parsed in src/input-helper.ts at lines 112-119. Here, the action extracts the sparse-checkout pattern list and the sparse-checkout-cone-mode boolean from the workflow inputs, storing these values in the GitSourceSettings object that propagates through the provider layer.

Command Execution in git-command-manager.ts

The actual Git operations are encapsulated in src/git-command-manager.ts, which exposes two distinct private methods: sparseCheckout() for cone-mode (lines 202-204) and sparseCheckoutNonConeMode() for legacy behavior (lines 206-221). The former invokes git sparse-checkout set with cone patterns, while the latter manually configures the repository's sparse-checkout configuration file using older Git mechanisms.

Mode Selection in git-source-provider.ts

At line 261 of src/git-source-provider.ts, the action determines which implementation to invoke by checking the sparseCheckoutConeMode property on the settings object. This conditional logic routes execution to either the modern cone-mode path or the legacy non-cone implementation based on the user's workflow configuration.

Workflow Configuration Examples

Configure cone-mode (default) for modern Git versions and directory-based patterns:

steps:
  - uses: actions/checkout@v4
    with:
      sparse-checkout: |
        src/
        docs/
      # Cone-mode is default; this line is optional

      # sparse-checkout-cone-mode: true

Force non-cone legacy mode for older Git compatibility or complex glob patterns:

steps:
  - uses: actions/checkout@v4
    with:
      sparse-checkout: |
        src/
        docs/
      sparse-checkout-cone-mode: false

Summary

• Cone-mode uses git sparse-checkout set with directory cone patterns and requires Git 2.28+, implemented in GitCommandManager.sparseCheckout() at lines 202-204 of src/git-command-manager.ts.
• Non-cone mode manually sets core.sparseCheckout=true and writes to info/sparse-checkout, implemented in GitCommandManager.sparseCheckoutNonConeMode() at lines 206-221.
• Mode selection is controlled by the sparse-checkout-cone-mode input parsed in src/input-helper.ts (lines 112-119) and evaluated in src/git-source-provider.ts at line 261.
• Cone-mode offers superior performance for directory-based sparse checkouts, while non-cone mode provides backward compatibility and advanced pattern matching.

Frequently Asked Questions

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

Cone-mode is the default implementation when the sparse-checkout-cone-mode input is omitted or set to true. This uses the modern git sparse-checkout set command available in Git 2.28 and later, optimizing for directory-based pattern matching.

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

Use non-cone mode when working with Git versions older than 2.28, or when your sparse checkout patterns require full path globbing that cannot be expressed as directory cones. Set sparse-checkout-cone-mode: false to activate the legacy implementation.

Where is the sparse checkout logic implemented in the source code?

The core logic resides in src/git-command-manager.ts, specifically in the sparseCheckout() method (lines 202-204) for cone-mode and sparseCheckoutNonConeMode() (lines 206-221) for legacy mode. The routing decision occurs in src/git-source-provider.ts at line 261 based on the sparseCheckoutConeMode boolean flag.

How do I enable sparse checkout for specific directories only?

Add the sparse-checkout input to your actions/checkout step with the desired directory paths, one per line. The action will automatically use cone-mode to fetch only those directory subtrees, or you can explicitly set sparse-checkout-cone-mode: false if you need legacy pattern matching behavior.

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