How To Clone A Git Tag

When you clone a git repo, you get the entirety of the cod base onto your computer, with all the history, all the branches, commits, all the metadata – everything. A perfect copy of the entire project is downloaded. While fine for many projects, the entire development history of a large project can be several gigabytes or more, particularly if the rep also includes binary data like video or images. Git is very efficient with text, but even so, it’s not uncommon to see repos span several gigabytes. To deal with this problem, it’s often more efficient to clone a git tag, instead.

In this article, I’ll explain how to both checkout a git tag as well as how to clone it, both with and without the history leading up to it.

Setting up the Environment

To prepare the environment, I’m going to use the public git repo Hello Git World. Here’s a screenshot of the project on Github:

Clicking the “Code” button gives us the URL we’re going to use to clone the repo.

You can see that this project has two tags. Here’s a screenshot:

These two tags are:

1. RELEASE_1.0
2. RELEASE_1.1

Our goal is to clone only that part of the git repo related to the “RELEASE_1.0” tag.

Cloning a Git Tag with Limited History

To download or clone a git project at a given tag, use the following command:

git clone --branch RELEASE_1.0 --single-branch https://github.com/githubtraining/hellogitworld.git

This gives the following result:

In the above screenshot, you can see that we’ve downloaded the git repo.

You can verify that this is the tag by typing the following command:

git describe --tag

The above command shows you the name of the tag that is the closest to the current state of the project in terms of commits. We can see that the tag name is “RELEASE_1.0”:

We also know that we’re currently in a tag because of the following message.

Consequences of Cloning a Tag

Because we’re in a tag, and not a branch, we see the following message:

You are in 'detached HEAD' state.

This state has the following consequences:

No branch progression

While you can make changes to the copy of the project, these changes are not linked to any branch. So even if you commit changes, you won’t be able to easily find the commits once you navigate away to another branch. You’ll have to make a note of the specific commit hash and refer to that when you want to switch to your commit.

Commits Can be Garbage Collected

Even if you make a note of the commit hash and use it to continue working on your changes, there’s a risk that Git’s garbage collection will pick it up since it’s not linked to any specific branch or commit. So at best, it’s only a temporary playing ground for unsystematic stuff.

Create a New Branch if you Want

If you want to start working from the commit, it’s best to create a new branch at that point. Creating a new branch ensures that it becomes part of git’s history and will save it from being pruned.

The above commands will download the git repo at a specific tag with its entire history. But what if you don’t want the burden of the project’s history? Let’s say you just want to download the state of the code at a certain tag, and nothing else. Here’s how to do it.

Cloning Git Tags with Full History

When you use git to clone a tag as above, it downloads only the specific branch at which the tag was created. The following command:

git clone --branch RELEASE_1.0 --single-branch https://github.com/githubtraining/hellogitworld.git

Has “–single-branch” on it, which means that if you use the following command:

git branch -a

You won’t see anything. If, on the other hand, you want to checkout a git tag with the full history in place, you have to download the entire git repo from scratch like this:

git clone https://github.com/githubtraining/hellogitworld.git

From here, you can checkout a specific tag with the following command:

git checkout tags/RELEASE_1.1

From here, you can get a full history of the git tag.

You can see below that it lists the complete history of the git project:

So you have access to the complete history of the project.

Size Considerations for Git Repos

As you can imagine, large git repos can take up a lot of space, particularly for complex projects spanning a long time. Even with optimization techniques, garbage collection, and more, it can be intimidating to work with such a large repo. As a result, even when you want to clone a git tag at a particular point in time, you might be signing up for an overwhelming amount of data being transferred onto your server.

It’s worse if your git repo has blobs of data like images or videos. So before you casually clone something, make sure you know how large the repo is. To save space, you can only clone the branch containing the particular commit or tag that you’re interested in. So use the “–single-branch” parameter to get a specific version of the code.

Impossible to Download “Just a Snapshot” of a Tag

Even with the “–single-branch” command, git will download the full history of the branch containing the “RELEASE_1.1” tag. So if “RELEASE_1.0” was a previous release on the same branch, it will download the history of that as well.

There is no direct way to tell git to download only a snapshot of a git project at a specific point in time. You’ll have to do that manually if you download the snapshot and then keep only the files related to the project and wipe out everything else.

How to Identify the Branch to Which a Tag Belongs

Strangely, it’s no simple matter to identify the branch to which a specific tag belongs. The steps to do that are as follows.

First, we get the commit hash of the tag:

git show <tagname> --pretty=format:"%H" -s

The “–pretty=format” parameter tells git to display the full hash, and the “-s” parameter tells it to suppress any description. You get only the hash.

Next, we use the commit hash in the previous step to get the branch containing that hash:

git branch --contains <commit-hash>

This will give you a list of all branches containing the commit. If you also want to include remote branches, the command is:

git branch -a --contains <commit-hash>

You can use the above information to download specific parts of a git project without its entire history.

Conclusion

As you can see, cloning a git tag is easy if you want to just download the history of the project up to a specific commit. Or if you want the full history, then just download the entire repo and switch to the tag you want to explore. Keep in mind that the changes you make to a tag aren’t saved as part of a branch and aren’t part of the versioning. So if you want your changes to be part of the git repo’s history, then create a new branch from that point and work on it.