How to Shallow Clone a Git Repository?

In Git, you can shallow clone a repository by using any of the following options with the git clone command:

• git clone --depth=<depth>;
• git clone --shallow-since=<date>;
• git clone --shallow-exclude=<revision>.

When shallow cloning a Git repository, you may use any of these options together or on their own with the git clone command.

Please note that shallow cloning has its limitations. Since only a limited number of commits are fetched, some operations that require access to the full commit history, such as examining older commits or switching to different branches that are not included in the shallow clone, may not work until you convert the shallow clone to a fully cloned repository.

Using git clone --depth

You can use the --depth option with git clone command to specify the number of most recent commits to include in the shallow clone. It has the following syntax:

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

Here, the depth option specifies the number of most recent commits that should be fetched during the cloning process, up to the specified depth. It determines the depth of the history that is downloaded and limits the number of commits included in the clone.

For example, if you specify --depth=1, only the latest commit on the branch will be fetched, resulting in a very shallow clone that contains only the most recent state of the repository. Similarly, specifying --depth=2 will fetch only the two most recent commits from the repository's history, and so on.

The maximum depth you can specify is 2147483647 (or 0x7fffffff).

By specifying a shallow clone depth, you can significantly reduce the amount of data transferred and speed up the cloning process, especially for repositories with a large commit history. This is particularly useful if you are only interested in the latest state of the repository and don't need access to the complete commit history.

Using git clone --shallow-since

You can use the --shallow-since option with git clone command to limit the cloned history to only commits after the specified date. It has the following syntax:

git clone --shallow-since=<date> <repository-url>

Here, the date can be specified in the following absolute date formats:

$ git clone --shallow-since=2022-01-01 <repository-url>
$ git clone --shallow-since="2022-01-01 10:30:00" <repository-url>
$ git clone --shallow-since="2022-01-01T10:30:00" <repository-url>

However, depending on the Git version and the platform you are using, several other acceptable formats for date might be supported, such as the following:

# relative dates
$ git clone --shallow-since="2 days ago" <repository-url>
$ git clone --shallow-since="1 week before now" <repository-url>

# specific dates
$ git clone --shallow-since=now <repository-url>
$ git clone --shallow-since=yesterday <repository-url>
$ git clone --shallow-since=today <repository-url>

If you encounter any issues with the date format, you can refer to the Git documentation or refer to the git help clone command for your specific Git version to find the accepted formats and additional guidelines.

Using git clone --shallow-exclude

You can use the --shallow-exclude option with git clone command to exclude a revision from the shallow clone. It has the following syntax:

git clone --shallow-exclude=<revision> <repository-url>

Here, the revision refers to a branch or tag name that you want to exclude from the shallow clone. It excludes commits that are reachable from that branch or tag. This means that it includes commits belonging to the specified branch or tag's commit history, as well as their ancestors.

For example, to exclude the commits reachable from the "development" branch, you can use the following command:

$ git clone --shallow-exclude=development <repository-url>

This will create a shallow clone that includes all branches and tags except for the commits reachable from the "development" branch.