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

> Learn how the actions/checkout filter input enables efficient Git partial clones. This guide explains how to minimize data transfer by fetching repositories without blobs or specific objects.

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

---

**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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/__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:

```yaml
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:

```yaml
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:

```yaml
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`](https://github.com/actions/checkout/blob/main/src/git-clone.ts).
- Configuration is defined in [`action.yml`](https://github.com/actions/checkout/blob/main/action.yml) (lines 1224-1226) and propagated through [`src/git-source-settings.ts`](https://github.com/actions/checkout/blob/main/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.