# How to Use Sparse Checkout in actions/checkout: Configuration Guide and Examples

> Learn to use sparse checkout in actions/checkout. Configure it with directory patterns to fetch only needed repo sections. Simplify your workflow now.

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

---

**Set the `sparse-checkout` input to a multiline list of directory patterns to fetch only specific portions of your repository, and use `sparse-checkout-cone-mode: false` only when you need to target individual files.**

The `actions/checkout` GitHub Action supports Git's sparse-checkout feature to reduce clone times and disk usage by fetching only specific paths from your repository. This is particularly valuable for monorepos or workflows that only need a subset of the source tree. By configuring sparse checkout in actions/checkout, you can significantly reduce network traffic and speed up CI/CD pipelines.

## Sparse Checkout Inputs and Options

The action exposes three inputs that control sparse checkout behavior, parsed in [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts) (lines 95-102):

- **`sparse-checkout`**: A multiline list of path patterns that should be checked out. Each line represents a separate pattern. Defaults to `null` (disabled).
- **`sparse-checkout-cone-mode`**: Enables Git 2.25+ cone mode for faster and simpler pattern syntax. Defaults to `true`. Set to `false` to use classic pattern matching.
- **`filter`**: Git partial clone filter (e.g., `blob:none`). When set, this overrides `sparse-checkout` because Git applies the filter before sparse-checkout rules.

### Cone Mode vs. Classic Patterns

When `sparse-checkout-cone-mode` is `true` (the default), the action uses Git's cone mode, which treats each line as a top-level directory or file path. This is the recommended approach for most use cases. To check out individual files or use complex wildcard patterns, you must disable cone mode and use classic pattern matching syntax.

## How Sparse Checkout Works Internally

The sparse checkout implementation spans three key source files in the repository:

### Input Validation

In [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts), the action reads and normalizes the multiline `sparse-checkout` value and the boolean `sparse-checkout-cone-mode` flag. This validation ensures that the inputs are properly formatted before being passed to the Git command manager.

### Git Command Execution

The [`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts) file (lines 197-204) handles the underlying Git operations. When sparse checkout is enabled, the action executes a sequence of commands: it first disables any existing sparse-checkout configuration with `git sparse-checkout disable`, then enables the requested mode using `git sparse-checkout set` with the provided patterns.

### Version Compatibility

Before executing sparse-checkout commands, [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) (lines 255-257) verifies that the runner's Git version is at least 2.28. If the version check fails, the action disables sparse-checkout to prevent errors on older Git versions.

## Configuration Examples

### Checkout Specific Directories (Cone Mode)

Use cone mode to fetch only specific top-level directories. This is the most common configuration:

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

```

### Checkout a Single File (Classic Mode)

To fetch a specific file, you must disable cone mode because cone mode only supports directory-level patterns:

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

```

### Combine with Shallow Fetch

Optimize further by limiting history depth while using sparse checkout:

```yaml
- uses: actions/checkout@v7
  with:
    sparse-checkout: |
      src/
    fetch-depth: 1

```

### Repository Root Only

Fetch only the root directory contents without subdirectories:

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

```

### Filter Override Example

When using the `filter` input for partial clone, note that it takes precedence over sparse-checkout:

```yaml
- uses: actions/checkout@v7
  with:
    filter: blob:none
    sparse-checkout: |
      src/

```

## Important Considerations

**Filter Precedence**: When the `filter` input is set (e.g., `blob:none`), it overrides `sparse-checkout` settings. Git applies the filter before evaluating sparse-checkout rules, which may result in different behavior than expected from path patterns alone.

**Git Version Requirement**: The action requires Git 2.28 or higher on the runner. The version check in [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) ensures compatibility before attempting to execute sparse-checkout commands.

**Pattern Syntax**: In cone mode (default), patterns are simple directory or file paths. In classic mode (when cone mode is disabled), you can use Git's full pattern syntax including wildcards and negations.

## Summary

- Use `sparse-checkout` with a multiline list to limit fetched paths to specific directories or files
- Keep `sparse-checkout-cone-mode: true` (default) for directory-level inclusion and better performance
- Set `sparse-checkout-cone-mode: false` when you need file-level patterns or complex wildcards
- Ensure your runner has Git 2.28 or higher, as verified by the action in [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts)
- Remember that the `filter` input overrides sparse-checkout when both are specified

## Frequently Asked Questions

### Why is my sparse checkout not working?

Check that your runner has Git 2.28 or higher. The action validates the Git version in [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) and silently disables sparse-checkout on older versions to prevent command failures. You can also verify that your patterns exist in the target commit and that you're using the correct syntax for your cone mode setting.

### Can I use sparse checkout with a shallow clone?

Yes. The `sparse-checkout` and `fetch-depth` inputs work together without conflict. Set `fetch-depth: 1` to create a shallow clone while still filtering paths to only the directories you need, optimizing both network transfer and disk usage.

### How do I checkout just one file?

You must set `sparse-checkout-cone-mode: false` because cone mode only supports directory-level patterns. Then list the specific file path in the `sparse-checkout` input. According to the implementation in [`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts), this switches to classic pattern mode which supports individual file paths.

### What happens if I use the filter input with sparse checkout?

The `filter` input takes precedence over `sparse-checkout`. When both are set, Git applies the partial clone filter first (e.g., excluding blobs), then applies sparse-checkout rules to the remaining objects. This is handled by the action's input processing in [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts), where filter settings are validated separately from sparse-checkout patterns.