Shallow Cloning

The git clone command clones the entire repository, all releases. Git manages release tags efficiently, so you can use the git checkout command to switch to a specific release after you have cloned the entire repository.

However, you can clone and switch to a specific branch, or, use the --depth 1 option in your git command to do what is known as a shallow clone.

Clone only the latest 2 releases on a repository (the head and at least one release prior)

time git clone --depth 1 http://abc.net/git/abc.git This command creates a shallow clone with a history truncated to the head (latest release) plus the specified number of revisions after the --depth option specifier. Shallow cloning is adequate if you are only interested in the recent revisions of a large project with a long, established release history.

You can also do a shallow clone on a specific branch or release tag. Say you have a master branch and an update branch named 1023.6U. Here is how you can execute a shallow clone bringing in the last 2 releases on the 1023.6U branch:

time git clone --depth 1 -b 1023.6U http://abc.net/git/abc.git Say you need to get a specific release tag r3030441.1 that is at --depth 35 on a repository that is 10GB or more in size and has 5 branches and 60 releases. You do not need to do a full clone to get there. You can use the following command to get that release in the most efficient way:

time git clone -b r3030441.1 --depth 1 http://abc.net/git/abc.git When to clone?

CLONE is expensive, especially when you clone an entire repository that has many releases on it already. CLONE is also a one-time event in Git. In these situations, you can do a shallow clone instead to reduce time needed to establish your local repository and get the latest code. Once the shallow or normal CLONE is completed, you should only be executing PULL commands thereafter. The PULL will only download the files that have changed and only what is necessary to bring the repository up to date. PULL commands should take minutes (not days), even behind the China firewall. We have had reports of customers repeating a full clone every time a new release is made. That is not efficient and definitely not recommended.

Problems with cloning large repositories

Say you are trying to clone a repository that has over 30 releases on it. If you try to clone this repository, it may take longer to transfer all of those releases (compressed) than the network will allow, and as a result, the connection will be dropped ("The remote end hung up unexpectedly"). This is especially the case with repositories with binary file compositions (Pre-compiled DEVICE or AMSS DEVICE context). Since binary files are not as efficiently stored in git compared to ASCII source code files, attempting to clone a repository with 30+ binary releases will certainly require a lot of bandwidth and extensive or non-existent timeout values on the network connections between yourself and ChipCode. Therefore, it is strongly recommended that clone requests be shallow when a repository with an extensive history of releases is involved.

Shallow Clone Depth Choice When choosing the value for shallow clone's depth, the value of 1 will allow you to clone the head + 1 release, in other words, the last 2 releases on the repository.

For example, say this is the release history on the repository you wish to clone:

r1005.1 r1006.1 r1007.1 r1008.1 r1009.1 r1010.1 r1011.1 r1012.1 And you wish to obtain r1009.1. Since you cannot clone a release tag in the middle of the repository’s history, you can do a shallow clone with —depth option set to 3. This means the head (r1012.1) plus an additional 3 releases deep (r1011.1, r1010.1, and r1009.1).

Converting a Shallow Clone to a Full Clone

If you need to get a deeper list of releases after a shallow clone has already been executed, you can use the following commands to convert a shallow-cloned repository into a fully cloned repository without having to do another clone to a new directory or starting over. This command is available as of git version 1.8.3:

git pull --rebase --unshallow git pull --rebase