How to Use sparse-checkout to Fetch Only Specific Folders or Files in actions/checkout

Set the sparse-checkout input to a multiline list of path patterns and optionally disable sparse-checkout-cone-mode to fetch individual files rather than directories.

The actions/checkout GitHub Action supports Git's sparse-checkout feature, allowing workflows to retrieve only specific portions of a repository instead of cloning the entire history. This capability significantly reduces checkout times and storage usage for large monorepos by limiting the working directory to only the folders or files you specify.

Configuring the sparse-checkout Input

To enable partial checkouts, add the sparse-checkout input to your workflow step. This input accepts a multiline string where each line represents a path pattern that Git will include in the working directory. According to the source code in src/input-helper.ts (lines 112-115), the action parses these values and stores them in the settings.sparseCheckout configuration object.

When you leave sparse-checkout-cone-mode at its default value of true, the action uses cone mode patterns. These are fast, directory-based patterns that include entire folder trees rather than individual file matches.

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

Cone Mode vs. Non-Cone Mode

The action provides two distinct operational modes controlled by the sparse-checkout-cone-mode boolean input.

Cone mode (default) interprets patterns as directory paths, enabling optimized performance for large repositories. The implementation in src/git-source-provider.ts (lines 261-264) determines which method to invoke based on this setting. When cone mode is enabled, the action calls git.sparseCheckout() to configure directory-based filtering.

Non-cone mode provides fine-grained, file-level control but requires explicit disabling of cone mode. When you set sparse-checkout-cone-mode: false, the action invokes git.sparseCheckoutNonConeMode() as implemented in src/git-command-manager.ts (lines 202-219). This method writes patterns directly to .git/info/sparse-checkout and runs git sparse-checkout set without the --cone flag, allowing precise file selection using standard gitignore-style patterns.

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

Practical Workflow Examples

The following examples demonstrate common sparse-checkout configurations as documented in the repository README:

Fetch only the repository root without subdirectories:

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

Fetch specific directories for a microservice build:

- uses: actions/checkout@v7
  with:
    sparse-checkout: |
      .github
      src
      packages/shared

Fetch a single configuration file from a large monorepo:

- uses: actions/checkout@v7
  with:
    sparse-checkout: config/production.yml
    sparse-checkout-cone-mode: false

Implementation Architecture

The sparse-checkout feature spans three core source files that coordinate the partial checkout process:

1. src/input-helper.ts parses the sparse-checkout multiline string and sparse-checkout-cone-mode boolean from the workflow configuration, storing these values in the settings object.

2. src/git-source-provider.ts acts as the orchestration layer, evaluating settings.sparseCheckoutConeMode to determine whether to invoke cone mode or non-cone mode operations.

3. src/git-command-manager.ts executes the underlying Git commands. For cone mode, it initializes sparse-checkout with cone patterns. For non-cone mode, it manually writes the .git/info/sparse-checkout file and executes git sparse-checkout set with the appropriate arguments.

This architecture ensures that directory-based checkouts use optimized Git internals while still supporting complex file-level patterns when necessary.

Summary

• Use the sparse-checkout input to define which paths to include in your working directory using multiline patterns.
• Enable cone mode (default) for fast, directory-based partial checkouts suitable for most monorepo workflows.
• Disable cone mode when you need to fetch specific individual files rather than entire directories.
• Reference the implementation in src/input-helper.ts, src/git-source-provider.ts, and src/git-command-manager.ts to understand how the action processes your configuration.

Frequently Asked Questions

What is the difference between cone mode and non-cone mode in sparse-checkout?

Cone mode interprets patterns as directory paths, creating a fast, performant checkout that includes entire folder trees. Non-cone mode treats patterns as gitignore-style expressions, allowing you to match specific files but with slower performance. The actions/checkout source code in src/git-source-provider.ts automatically selects the appropriate Git command based on your sparse-checkout-cone-mode setting.

Can I use sparse-checkout with large monorepos to speed up workflow execution?

Yes. Sparse-checkout is specifically designed to reduce clone times and storage requirements for large repositories. By fetching only the directories required for your build process—such as specific service folders in a microservices architecture—you can reduce checkout duration from minutes to seconds.

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

Set the sparse-checkout input to the file path and explicitly disable cone mode by setting sparse-checkout-cone-mode: false. This configuration triggers the non-cone code path in src/git-command-manager.ts, which writes the file pattern to .git/info/sparse-checkout and initializes the repository with only that specific file.

Where does the action store the sparse-checkout configuration patterns?

The action writes your patterns to the .git/info/sparse-checkout file within the repository workspace. In cone mode, Git manages this file automatically. In non-cone mode, the action explicitly writes the file before executing git sparse-checkout set to apply the file-level filters.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}