# How to Configure Sparse Checkout in actions/checkout for Specific Directories

> Learn to configure sparse checkout in actions/checkout for specific directories. Optimize your GitHub Actions workflow by fetching only necessary files, saving time and bandwidth. Control with sparse checkout and cone mode inputs.

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

---

**Set the `sparse-checkout` input with the directories or files you need, and optionally adjust `sparse-checkout-cone-mode` to control whether Git uses fast directory-level matching or precise file-level patterns.**

The `actions/checkout` GitHub Action supports Git’s sparse checkout feature, allowing you to fetch only specific directories instead of cloning the entire repository. This significantly reduces network traffic and speeds up CI/CD workflows, particularly for large monorepos with multiple projects. According to the source code in `actions/checkout`, the action automatically handles pattern parsing and Git command execution when you configure the appropriate inputs.

## Understanding Sparse Checkout Inputs

### The sparse-checkout Input

The primary input for partial clones is `sparse-checkout`, which accepts multiline patterns defining which files and directories to include. In [[`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts)](https://github.com/actions/checkout/blob/main/src/input-helper.ts#L112-L119), the action reads this input and processes each line as a separate pattern. The action writes these patterns to Git’s `sparse-checkout` file before initializing the repository.

### Cone Mode vs. Non-Cone Mode

The `sparse-checkout-cone-mode` input controls Git’s pattern matching algorithm. When set to `true` (the default), **cone mode** enables a fast directory-level matching algorithm optimized for CI/CD performance. Set it to `false` to enable precise file-level pattern matching, which is necessary when you need individual files scattered across different directories rather than entire folder structures.

## Implementation Details from Source Code

### Input Processing

The action parses your configuration in [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts), where it extracts the multiline `sparse-checkout` value and prepares it for the Git command manager. This processing ensures that each line you provide becomes a distinct inclusion rule passed to Git’s configuration.

### Git Command Execution

In [[`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts)](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts#L197-L211), the action implements the sparse checkout workflow through precise Git operations. It first disables any existing sparse-checkout configuration to ensure a clean state, then writes your new patterns to Git’s `sparse-checkout` file and enables the feature. This reset-and-apply approach prevents stale patterns from previous workflow runs from affecting your current checkout.

### Version Compatibility

The source code in [`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts) (line 14) and [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) includes runtime checks for Git version 2.28. If the runner uses an older Git version, the action automatically disables sparse checkout to prevent command failures, falling back to a full repository clone.

## Configuration Examples for Specific Directories

### Fetching Only Root Files

To fetch only the repository root without any subdirectories, use a single dot pattern:

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

```

### Selecting Multiple Directories

Use cone mode (the default) to fetch specific folders efficiently:

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

```

### Checking Out Individual Files

Disable cone mode when you need specific files rather than entire directories:

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

```

### Combining with Branch Selection

Configure sparse checkout alongside specific branch references or commit SHAs:

```yaml
- uses: actions/checkout@v7
  with:
    ref: feature/awesome
    sparse-checkout: |
      docs
      lib/utils
    sparse-checkout-cone-mode: true

```

## Summary

- The `sparse-checkout` input accepts multiline patterns processed by [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts) to determine which files to fetch
- Cone mode (`sparse-checkout-cone-mode: true`) provides faster performance for directory-level patterns using optimized algorithms
- The action automatically resets existing sparse-checkout configurations before applying new patterns, ensuring clean state
- Git version 2.28 or later is required; older versions trigger automatic fallback to full clones in [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts)
- Disable cone mode when you need to checkout individual files rather than complete directories

## Frequently Asked Questions

### What Git version is required for sparse checkout in actions/checkout?

Sparse checkout requires Git 2.28 or later. The action automatically detects the Git version on the runner and disables sparse checkout if the version is older than 2.28, as implemented in [`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts) and [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts). This prevents workflow failures on older runner images.

### Why should I use cone mode for sparse checkout?

Cone mode uses a simplified pattern matching algorithm that significantly speeds up operations when you're including entire directories. According to the `actions/checkout` source code, cone mode is enabled by default because it provides better performance for the typical CI/CD use case of checking out specific project folders within a monorepo.

### Can I exclude specific directories instead of including them?

Git's sparse checkout works on an inclusion basis. To exclude directories, you must define patterns that include everything except what you want to exclude, or use negation patterns when cone mode is set to `false`. The `actions/checkout` action passes your patterns directly to Git's sparse-checkout configuration without modification.

### What happens if my sparse-checkout patterns overlap?

Git processes sparse-checkout patterns in order, with later patterns overriding earlier ones when conflicts occur. The `actions/checkout` action writes your patterns exactly as provided in the YAML configuration to the sparse-checkout file, maintaining the order you specify in the multiline input.