# How the Filter Option Enables Partial Clone in actions/checkout

> Learn how the filter option in actions/checkout enables partial clone by using Git's --filter flag to reduce data transfer and storage. Optimize your workflows!

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

---

**The `filter` input enables partial clone by passing the `--filter` flag to Git's fetch command, allowing workflows to omit specific object types like blobs or trees to reduce data transfer and storage.**

The `actions/checkout` GitHub Action exposes Git's partial clone functionality through the `filter` input, which controls precisely which repository objects are downloaded from the remote. By leveraging filters such as `blob:none` or `tree:0`, CI/CD pipelines can significantly reduce network overhead and disk consumption when working with large monorepos. This article examines the source code implementation to explain how the action translates YAML configuration into Git's native filtering capabilities.

## Input Processing and Validation

The implementation flows through three critical TypeScript modules that transform the user-provided filter value into a command-line argument for the underlying Git process.

### Reading the Input in input-helper.ts

In [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts), the action retrieves the optional `filter` input using the `@actions/core` library and conditionally adds it to the result settings object.

```typescript
const filter = core.getInput('filter')
if (filter) {
  result.filter = filter
}

```

This logic ensures that only explicitly provided filter values are propagated through the system, maintaining backward compatibility for workflows that do not require partial clone functionality.

### Configuring Fetch Options in git-source-provider.ts

In [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts), the code maps the filter setting to the `fetchOptions` object passed to the Git command manager. A key implementation detail is the automatic fallback to `blob:none` when sparse-checkout is enabled without an explicit filter.

```typescript
if (settings.filter) {
  fetchOptions.filter = settings.filter
} else if (settings.sparseCheckout) {
  fetchOptions.filter = 'blob:none'
}

```

This fallback prevents unnecessary blob downloads when the workflow only requires a subset of the repository's files, optimizing both network usage and storage.

### Constructing the Git Command in git-command-manager.ts

Finally, in [`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts), the `GitCommandManager.fetch` method constructs the argument array for the `git fetch` command. When a filter option is present, it pushes the `--filter` flag with the specified value.

```typescript
if (options.filter) {
  args.push(`--filter=${options.filter}`)
}

```

This direct mapping allows the action to support any valid Git filter specification that the underlying Git version supports, without requiring changes to the action code when Git introduces new filter types.

## Practical Usage Examples

The `filter` option accepts any string value recognized by Git's `--filter` syntax. Here are common patterns for optimizing checkout performance.

### Implicit Filter with Sparse Checkout

When using `sparse-checkout` without an explicit filter, the action automatically applies `blob:none` to skip downloading file contents outside the sparse paths.

```yaml
steps:
  - uses: actions/checkout@v4
    with:
      sparse-checkout: |
        src/
        README.md

```

### Explicit Custom Filters

You can specify custom filters to control exactly which Git objects are fetched. The `tree:0` option downloads only commit objects and refs, excluding all directories and file contents.

```yaml
steps:
  - uses: actions/checkout@v4
    with:
      filter: 'tree:0'

```

### Combining with Shallow Clones

For maximum efficiency in CI environments, combine the filter option with `fetch-depth` to create minimal clones that contain only the latest commit metadata.

```yaml
steps:
  - uses: actions/checkout@v4
    with:
      fetch-depth: 1
      filter: 'blob:none'

```

## Summary

- The `filter` input in `actions/checkout` passes the `--filter` flag to the underlying `git fetch` command
- Implementation spans three files: [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts), [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts), and [`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts)
- When `sparse-checkout` is enabled without an explicit filter, the action defaults to `blob:none` automatically
- Supports standard Git filter specifications including `blob:none`, `tree:0`, and size-based filters
- Reduces CI/CD pipeline execution time and storage requirements for large repositories

## Frequently Asked Questions

### What is the difference between filter and sparse-checkout?

Sparse-checkout controls which files appear in your working directory by modifying the `.git/info/sparse-checkout` file, while the `filter` option controls which objects are physically downloaded from the remote repository. When using sparse-checkout without an explicit filter, `actions/checkout` automatically sets `filter: blob:none` to avoid downloading file contents outside the sparse paths, optimizing both network and storage usage.

### Can I use multiple filter values in one checkout step?

Git's partial clone implementation accepts only one filter specification at a time through the `--filter` flag. You cannot combine `blob:none` with `tree:0` simultaneously in a single fetch operation. However, you can select the most restrictive single filter that meets your workflow requirements, or perform multiple checkout steps with different filters if necessary.

### Does the filter option work with all Git providers?

Partial clone requires Git version 2.27 or later on the client side and server-side support for the `filter` capability. While major hosting providers like GitHub, GitLab, and Bitbucket support this feature, older on-premises Git servers or those with custom configurations may reject the `--filter` flag, causing the fetch operation to fail.

### How does filter: blob:none affect subsequent git operations?

With `blob:none`, file contents are excluded from the initial fetch and downloaded on-demand when accessed (lazy loading). This means subsequent commands like `git checkout`, `git show`, or `git diff` may trigger additional network requests to fetch missing blobs, which could impact performance if your workflow frequently accesses files outside the initial sparse definition.