What is a Git Shallow Clone?
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.
How shallow cloning works
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:
git clone --depth <depth> <repository-url>
Using git clone with the --depth option
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:
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.
Git clone with specific depth
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:
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.
Git clone no checkout
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:
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.
Handling branches
If you need to clone a specific branch with limited depth, use the -b option with the --depth flag:
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.
Checkout the latest commit of a remote branch
To checkout a remote branch in a shallow-cloned repository, you first need to fetch the branch with depth, then checkout:
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.
Expanding shallow clones
If you've performed a shallow clone and later decide you need more history, you can deepen the clone with the --deepen flag:
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:
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.
