# How `fetch-depth` Configuration Affects `actions/checkout` Performance

> Optimize GitHub Actions CI performance by understanding how fetch-depth affects actions/checkout speed and bandwidth. Learn how shallow vs full clones impact your workflows.

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

---

**Setting the `fetch-depth` input in `actions/checkout` controls whether Git performs a shallow clone (fast, minimal data) or full history fetch (slow, complete data), directly impacting CI workflow execution time and bandwidth usage.**

The `actions/checkout` GitHub Action is the standard method for pulling repository code into CI workflows. By adjusting the `fetch-depth` configuration parameter, you control how much Git history is downloaded, creating a direct trade-off between checkout speed and the availability of historical commit data.

## How `fetch-depth` Is Parsed

The action reads the `fetch-depth` input value in **[`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts)** (lines 122-128), where it is retrieved from the workflow configuration and normalized for the Git command manager.

This parsed value determines the behavior of subsequent fetch operations, serving as the primary mechanism for performance optimization in the checkout process.

## Git Command Generation and Performance

The core performance logic resides in **[`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts)** (lines 299-306), where the action constructs the `git fetch` command based on the depth value.

### Shallow Cloning (`fetch-depth` > 0)

When `fetchDepth` is greater than zero, the action appends `--depth=<value>` to the fetch command. This creates a **shallow clone** limited to the specified number of commits, dramatically reducing the amount of data transferred and speeding up the checkout process, especially for large repositories with extensive histories.

According to the source code in [`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts) (lines 299-301), this flag instructs Git to fetch only the recent commit history, minimizing network overhead.

### Full History Unshallowing (`fetch-depth` = 0)

When `fetchDepth` is set to `0`, the code checks whether a shallow repository already exists by looking for `.git/shallow`. If detected, it adds the `--unshallow` flag to retrieve the full history (lines 302-306 in [`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts)). This converts an existing shallow clone into a complete repository but requires significantly more time and bandwidth.

## Performance Comparison by Configuration

| `fetch-depth` value | Git command effect | Data transfer | Checkout speed | Best used for |
|---------------------|-------------------|---------------|----------------|---------------|
| **1** (default) | `--depth=1` | Minimal | Fastest | Standard CI builds, minimal history |
| **> 0** | `--depth=<n>` | Reduced | Fast | Recent history analysis, limited depth needs |
| **0** | `--unshallow` (if shallow) | Complete | Slowest | Full changelog generation, version calculation |

## Practical Configuration Examples

Use these configurations to optimize your workflow performance based on your requirements:

```yaml

# Fast shallow checkout – only the latest commit

- uses: actions/checkout@v4
  with:
    fetch-depth: 1   # default, minimal data transfer

```

```yaml

# Full history – useful for tools that need the complete commit graph

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # disables shallow cloning, fetches all commits

```

```yaml

# Deeper shallow clone – fetch the last 50 commits

- uses: actions/checkout@v4
  with:
    fetch-depth: 50

```

## Testing and Verification

The behavior is validated by the test suite in **[`__test__/git-command-manager.test.ts`](https://github.com/actions/checkout/blob/main/__test__/git-command-manager.test.ts)** (lines 36-86), which confirms that the exact arguments are passed to `git fetch` for different `fetch-depth` values. These tests verify that the performance characteristics match the configuration, ensuring shallow clones use `--depth` and full history requests trigger `--unshallow` when appropriate.

## Summary

- The **`fetch-depth`** parameter in `actions/checkout` directly translates to Git's `--depth` or `--unshallow` flags.
- Values greater than `0` trigger **shallow clones**, minimizing data transfer and maximizing checkout speed for CI pipelines.
- Setting `fetch-depth` to `0` forces a **full history fetch**, which is slower but necessary for workflows requiring complete commit graphs.
- The default value of `1` provides optimal performance for most CI workflows by fetching only the latest commit.

## Frequently Asked Questions

### What is the default fetch-depth in actions/checkout?

The default value is `1`, which performs a shallow clone of only the most recent commit. This minimizes network usage and checkout time, making it ideal for standard CI builds that do not require historical data.

### When should I use fetch-depth: 0?

Use `fetch-depth: 0` when your workflow requires access to the complete Git history, such as for generating changelogs, calculating version bumps based on commit history, or running analysis tools that examine the full commit graph. Be aware this increases checkout time and bandwidth usage.

### Does fetch-depth: 0 always download the full repository?

If the repository is already shallow, `fetch-depth: 0` triggers the `--unshallow` flag to fetch the remaining history. If the repository already contains full history, the action fetches without depth restrictions, ensuring all commits are available without redundant data transfer.

### How does fetch-depth affect large repository performance?

For large repositories with extensive histories, shallow cloning (`fetch-depth` > 0) can reduce checkout time from minutes to seconds by transferring only recent commits rather than the entire codebase history. This is a critical optimization for monorepos or long-running projects with thousands of commits.