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

> Discover actions/checkout sparse checkout modes: cone for directory prefixes and non-cone for file glob patterns. Learn how to use the sparse-checkout-cone-mode input effectively.

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

---

**actions/checkout supports two sparse checkout modes—cone mode (default) for directory prefixes and non-cone (legacy) mode for file-level glob patterns—controlled by the `sparse-checkout-cone-mode` input.**

The `actions/checkout` GitHub Action provides sparse checkout capabilities to fetch only specific portions of a repository, significantly reducing clone times and disk usage in CI/CD workflows. Understanding the different sparse checkout modes available in this action is essential for optimizing your pipeline performance. The implementation in `actions/checkout` distinguishes between modern cone-mode patterns and legacy path-matching algorithms to handle various repository filtering scenarios.

## Cone Mode vs Non-Cone Mode

### Cone Mode (Default)

In cone mode, which is the default behavior when `sparse-checkout-cone-mode` is set to `true` or left unspecified, patterns are treated as directory prefixes. According to the `actions/checkout` source code in [`src/inputs.ts`](https://github.com/actions/checkout/blob/main/src/inputs.ts), this mode interprets each line in the `sparse-checkout` input as a literal directory path, making the checkout operation fast and memory-efficient. This approach leverages Git's modern cone-mode sparse-checkout algorithm, which optimizes performance for large monorepos by avoiding complex glob matching in favor of simple directory inclusion.

### Non-Cone (Legacy) Mode

When `sparse-checkout-cone-mode` is explicitly set to `false`, the action switches to non-cone mode, which uses the older path-matching algorithm. As implemented in [`src/main.ts`](https://github.com/actions/checkout/blob/main/src/main.ts), this mode treats each pattern as a glob expression that can match individual files, enabling complex filtering scenarios. This mode is required when you need to checkout a single specific file or use advanced glob patterns that do not conform to directory prefixes.

## Configuring Sparse Checkout in GitHub Actions

The `sparse-checkout` input accepts a newline-separated list of patterns, while `sparse-checkout-cone-mode` determines how those patterns are interpreted. According to the [`README.md`](https://github.com/actions/checkout/blob/main/README.md) documentation, when using the `filter` input for partial clones, it will override any sparse-checkout configuration if both are provided.

### Cone Mode Examples

Fetch only the root directory using default cone mode:

```yaml
- uses: actions/checkout@v7
  with:
    sparse-checkout: .

```

Fetch specific folders in cone mode:

```yaml
- uses: actions/checkout@v7
  with:
    sparse-checkout: |
      .github
      src

```

### Non-Cone Mode Example

Fetch a single file using legacy pattern matching:

```yaml
- uses: actions/checkout@v7
  with:
    sparse-checkout: |
      README.md
    sparse-checkout-cone-mode: false

```

## Implementation Architecture

The sparse checkout functionality is orchestrated across several key files in the repository. The [`src/inputs.ts`](https://github.com/actions/checkout/blob/main/src/inputs.ts) file defines the `sparse-checkout` and `sparse-checkout-cone-mode` inputs along with their default values, while [`src/main.ts`](https://github.com/actions/checkout/blob/main/src/main.ts) implements the core logic that parses these inputs and executes the appropriate Git commands to apply the selected mode. The [`README.md`](https://github.com/actions/checkout/blob/main/README.md) provides the canonical documentation for these configuration options, outlining the behavior differences between cone mode and non-cone mode implementations.

## Summary

- **Cone mode** is the default sparse checkout mode in `actions/checkout`, treating patterns as directory prefixes for optimal performance and simplified pattern matching.
- **Non-cone mode** enables file-level and glob pattern matching by setting `sparse-checkout-cone-mode: false`, which is required for single-file checkouts and complex filtering.
- Both modes use the `sparse-checkout` input with newline-separated patterns, but interpret them differently based on the cone-mode boolean setting.
- The `filter` input for partial clones overrides sparse-checkout configurations when specified in the workflow.
- Implementation details are located in [`src/inputs.ts`](https://github.com/actions/checkout/blob/main/src/inputs.ts) for input definitions and [`src/main.ts`](https://github.com/actions/checkout/blob/main/src/main.ts) for the execution logic that runs the underlying Git sparse-checkout commands.

## Frequently Asked Questions

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

Cone mode is the default sparse checkout mode. When you use the `sparse-checkout` input without specifying `sparse-checkout-cone-mode`, or when you explicitly set it to `true`, the action treats all patterns as directory prefixes using Git's modern cone-mode algorithm as implemented in the action's source code.

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

Use non-cone mode when you need to checkout individual files rather than entire directories, or when you require complex glob patterns that match specific file paths rather than directory prefixes. Set `sparse-checkout-cone-mode: false` to enable this legacy path-matching behavior required for single-file selection.

### Can I use sparse checkout with partial clone filters?

Yes, but the `filter` input takes precedence over sparse-checkout settings. According to the `actions/checkout` documentation, if you specify a partial clone filter using the `filter` input, it will override any sparse-checkout configuration you have provided in the same step.

### How do I checkout a single file using actions/checkout?

To checkout a single file, you must set `sparse-checkout-cone-mode: false` and specify the exact file path in the `sparse-checkout` input. This disables the directory-based cone mode and allows the pattern to match the specific file path using the legacy glob matching algorithm.