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

> Understand sparse-checkout-cone-mode in actions/checkout. Learn how it optimizes Git performance by interpreting patterns as directory prefixes or glob patterns for efficient code checking.

- Repository: [GitHub Actions/checkout](https://github.com/actions/checkout)
- Tags: deep-dive
- Published: 2026-07-05

---

**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`](https://github.com/actions/checkout/blob/main/src/input-helper.ts) (lines 101-104) reads the workflow input and converts it to a boolean.
- **Settings storage**: [`src/git-source-settings.ts`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/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:

```yaml
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:

```yaml
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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/action.yml) (lines 70-74) and documented in the README. The runtime implementation spans [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts) for parsing, [`src/git-source-settings.ts`](https://github.com/actions/checkout/blob/main/src/git-source-settings.ts) for the interface definition, and [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) for the execution logic that invokes the appropriate Git commands.