Understanding shallow clones in Git

Greg Foster
Greg Foster
Graphite software engineer


Note

This guide explains this concept in vanilla Git. For Graphite documentation, see our CLI docs.


A shallow clone in Git is a clone of a repository with truncated history of the commits. Unlike a regular clone, which downloads the entire history of the repository, a shallow clone limits the number of commits in the history, thus saving bandwidth and disk space. This is particularly useful in continuous integration/continuous deployment (CI/CD) environments or when working with large monorepos.

This guide will dive deep into what shallow clones are, how they work, and how to use them, incorporating key concepts such as git clone depth, shallow fetching, and more.

When you perform a shallow clone, you specify a depth (--depth) which indicates how many recent commits of each branch you want to retrieve. Here's how the basic command structure looks:

Terminal
git clone --depth <depth> <repository-url>

The --depth option works by instructing Git to fetch only the last n commits from the remote history where n is the number you specify. When you use --depth 1, you're telling Git to only fetch the latest commit.

--depth 1 is the most commonly used depth. It means you are cloning the repository with only the latest commit of the main branch. The repository is significantly lighter as it contains the minimal amount of data needed to start working with the repository.

For example, to clone only the latest commit, run:

Terminal
git clone --depth 1 https://github.com/example/repo.git

This command creates a shallow clone where the .git directory only contains the single most recent commit from the branch you are cloning instead of the entire commit history.

If you need more than just the latest commit, you can adjust the depth accordingly. For instance, cloning with a depth of 3 retrieves the latest three commits:

Terminal
git clone --depth 3 https://github.com/example/repo.git

This will allow you to compare code changes among the latest 3 commits without downloading the other, potentially less relevant commit history.

Sometimes, you might want to clone the repository metadata without checking out the files into your working directory. This can be done using the --no-checkout flag:

Terminal
git clone --depth 1 --no-checkout https://github.com/example/repo.git

This command clones the repository at the specified depth but leaves the working directory empty. This allows you to view all of the metadata for the repository and the latest commit such as author, date, and commit message, in addition to the code diff of the latest commit.

If you need to clone a specific branch with limited depth, use the -b option with the --depth flag:

Terminal
git clone --depth 1 -b <branch-name> https://github.com/example/repo.git

This will clone the specified branch with only the most recent commit.

To checkout a remote branch in a shallow-cloned repository, you first need to fetch the branch with depth, then checkout:

Terminal
git fetch --depth 1 origin <branch-name>
git checkout <branch-name>

This will fetch the latest commit from a single specific branch of a remote repository, rather than the entire repository's history across all of its branches.

If you've performed a shallow clone and later decide you need more history, you can deepen the clone with the --deepen flag:

Terminal
git fetch --deepen <additional-depth>

This command increases the depth of the clone by the specified additional depth, adding more commits to your history. This allows you to incrementally expand context of the repository while saving local storage space and network bandwidth.

For example, to increase the depth of the clone by an additional 10 commits, you would run:

Terminal
git fetch --deepen 10

This fetches 10 more commits into your shallow clone.

For further information on shallow cloning in Git see the official Git documentation.

Git inspired
Graphite's CLI and VS Code extension make working with Git effortless.
Learn more

Graphite
Git stacked on GitHub

Stacked pull requests are easier to read, easier to write, and easier to manage.
Teams that stack ship better software, faster.

Or install our CLI.
Product Screenshot 1
Product Screenshot 2