How to clone a specific tag using git

A tag in Git is a pointer to a specific commit, used to capture a snapshot of a project at a particular point in time, marking specific points in a repository's history as important—typically used for marking release points (e.g., v1.0, v2.0). Cloning a repository based on tags is essential for developers who need to work with specific versions of a codebase. This guide covers various methods and commands to clone and work with Git tags efficiently.

Cloning a repository at a specific tag

Unlike branches, tags in Git are not automatically fetched when you clone a repository. To work on a specific tag, you will first need to clone the repository and then checkout the tag. Here are detailed steps and commands:

1. Clone the repository

First, clone the repository without specifying a tag. You can't directly clone only a tag as Git does not support this directly.

git clone https://github.com/example/repo.git
cd repo

2. List available tags

Before checking out a tag, you may want to list all available tags:

git tag

3. Checkout a specific tag

Once you have identified the specific tag you need, you can check it out using:

git checkout tags/<tag-name>

For example, to checkout version 1.0:

git checkout tags/v1.0

This command checks out the code in a detached HEAD state because you are not working on the tip of a branch.

For a more detailed guide on the 'detached HEAD state', including how to get out of it, see this guide on resolving a detached head state.

Advanced cloning techniques

Cloning and checking out a tag in one line

For a quicker setup, you can clone the repository and checkout a tag in one line using the following:

git clone --branch <tag-name> --single-branch https://github.com/example/repo.git

For instance, to clone and checkout the v1.0 tag:

git clone --branch v1.0 --single-branch https://github.com/example/repo.git

This method clones the least amount of data as it only fetches history associated with the specified tag.

Fetching a specific tag from a remote

If you already have a cloned repository and need to fetch a specific tag, use:

git fetch origin tag <tag-name>

For example:

git fetch origin tag v1.0

Pull using a tag

Although git pull is not directly used with tags, you can fetch and checkout like this:

git fetch origin tag <tag-name>
git checkout tags/<tag-name>

Downloading all tags

To fetch all tags from a remote, use:

git fetch --tags

This command downloads all the tags along with the commits they refer to.

Cloning the latest tag

To clone the latest tag, you can use a combination of git commands to sort and retrieve the latest tag name, then use it to clone:

git clone --branch $(git ls-remote --tags --sort="v:refname" https://github.com/example/repo.git | tail -n1 | sed 's/.*\///; s/\^{}//') --single-branch https://github.com/example/repo.git

1. git clone --branch <branch-name> This part of the command initiates the cloning of a repository, but instead of cloning the default branch (usually main or master), it clones a specific tag specified by <branch-name>.

2. $(...) This syntax is used in shell commands to execute the command inside the parentheses and use its output as part of the outer command. Here, it's used to dynamically determine the branch or tag to clone.

3. git ls-remote --tags --sort="v:refname" https://github.com/example/repo.git

   • git ls-remote lists references (like branches and tags) available in a remote repository.
   • --tags filters the output to show only tags.
   • --sort="v:refname" sorts the tags. The prefix v: indicates a version sort, which is useful when tags represent versions (as it sorts them numerically and lexicographically considering typical versioning schemes).
   • The URL https://github.com/example/repo.git specifies the remote repository from which to list tags.

4. tail -n1 This Unix command takes the last line of the input provided to it, which, due to the previous sorting, will be the latest tag.

5. sed 's/.*\///; s/\^{}//'

   • This sed command performs two substitutions on the input string (the latest tag):
     • s/.*\/// removes everything up to and including the last slash (/), essentially extracting the tag name from the full ref path.
     • s/\^{}// is used to remove any trailing ^{} from the tag name. This sequence can appear in git ls-remote output for annotated tags, pointing to the commit associated with the tag.

6. --single-branch This option tells git clone to only clone the history of the specified branch or tag, reducing the amount of data transferred.

For more information on Git tags, see the official Git documentation on tagging.