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

> Learn about sparse-checkout-cone-mode in actions/checkout. Discover how to leverage this faster Git algorithm for efficient checkouts and improve your CI/CD performance.

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

---

**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`](https://github.com/actions/checkout/blob/main/src/input-helper.ts):

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

```bash
git sparse-checkout set --cone <patterns>

```

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

```bash
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`](https://github.com/actions/checkout/blob/main/__test__/verify-sparse-checkout.sh) validates cone-mode functionality, while [`__test__/verify-sparse-checkout-non-cone-mode.sh`](https://github.com/actions/checkout/blob/main/__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:

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

```yaml
- 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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/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.