How the actions/checkout Filter Input Works: Complete Guide to Partial Clones

The filter input in actions/checkout enables Git partial clones by passing its value directly to git clone as the --filter flag, allowing repositories to be fetched without blobs or other specific objects to minimize data transfer.

The actions/checkout GitHub Action is the standard way to check out repositories in GitHub Actions workflows. When working with large repositories, the actions/checkout filter input provides fine-grained control over which Git objects are downloaded, significantly reducing clone times and storage requirements while maintaining full repository metadata.

Understanding the Filter Input Mechanism

The filter input implements Git’s partial clone functionality. When specified, the action passes the value directly to the git clone command via the --filter argument, instructing Git to exclude specific object types from the initial fetch.

Input Declaration and Storage

In action.yml (lines 1224-1226), the input is declared as a string type that accepts any valid Git filter specification. The value is then stored in the IGitSourceSettings interface defined in src/git-source-settings.ts (lines 32-36), where it is typed as an optional string property named filter.

Command Construction

When constructing the clone command in src/git-clone.ts, the action checks if settings.filter is defined. If present, it appends --filter=<value> to the command line arguments. This implementation is verified by the test suite in __test__/git-command-manager.test.ts, which ensures the flag is correctly formatted and passed to Git.

Default Behavior

If the filter input is omitted, the action performs a normal shallow clone using the default fetch-depth: 1 behavior. The partial clone mode is only activated when a filter value is explicitly provided.

Filter vs Sparse-Checkout

When a filter value is specified, it overrides any sparse-checkout configuration. If both inputs are present in your workflow, the partial-clone filter takes precedence and the sparse-checkout patterns are ignored.

This behavior ensures that the --filter flag (which operates at the Git object level) does not conflict with sparse-checkout (which operates at the file path level). For workflows requiring both functionalities, use filter to control object download and handle path filtering separately in subsequent steps.

Practical Configuration Examples

Exclude All Blobs for Directory-Only Clones

The most common use case fetches only commit and tree objects, excluding file contents (blobs) until needed:

steps:
  - name: Checkout without blobs
    uses: actions/checkout@v4
    with:
      filter: 'blob:none'

Result: The runner downloads only commit history and directory structures. File contents are retrieved lazily when accessed by subsequent commands.

Combine Filter with Fetch Depth

Limit both the commit history and object types:

steps:
  - name: Shallow partial clone
    uses: actions/checkout@v4
    with:
      filter: 'blob:none'
      fetch-depth: 10

This configuration fetches only the last 10 commits and their tree structures, omitting blobs entirely.

Filter Overrides Sparse-Checkout

When both are specified, the filter takes precedence:

steps:
  - name: Partial clone takes precedence
    uses: actions/checkout@v4
    with:
      sparse-checkout: |
        src/
        docs/
      filter: 'blob:none'  # This overrides sparse-checkout

Summary

• The actions/checkout filter input passes values directly to git clone --filter, enabling Git partial clones as implemented in src/git-clone.ts.
• Configuration is defined in action.yml (lines 1224-1226) and propagated through src/git-source-settings.ts (lines 32-36) to the command builder.
• Setting filter: 'blob:none' downloads only commits and trees according to the Git filter specification, fetching blobs on-demand.
• The filter input overrides sparse-checkout when both are present; sparse-checkout patterns are ignored.
• This feature requires Git 2.17 or later for partial clone support.

Frequently Asked Questions

What is the most common value for the actions/checkout filter input?

The most frequently used value is blob:none, which fetches only commit and tree objects while excluding file contents (blobs). This allows the repository structure to be available immediately while file contents are retrieved lazily on demand, significantly reducing initial clone time for large repositories.

Does the filter input work with sparse-checkout?

No. When the filter input is specified, it overrides any sparse-checkout configuration. According to the actions/checkout source code, the presence of a filter value causes the action to ignore sparse-checkout patterns entirely. To filter by paths, handle sparse-checkout manually after the initial clone step.

How does filter affect repository performance?

Using a filter like blob:none improves initial clone performance by reducing data transfer, especially beneficial for monorepos or repositories with large binary files. However, subsequent file access operations may experience latency as blobs are fetched on-demand from the remote. The trade-off favors filter usage when the workflow primarily needs repository metadata or specific files rather than the entire codebase.

What Git version is required for the filter input?

The filter input requires Git 2.17 or later, which introduced partial clone support. GitHub-hosted runners typically include recent Git versions that support this feature. For self-hosted runners, ensure the installed Git version supports the --filter flag before using this input.

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