How to Checkout Git Tags: Everything You Need to Know

When working with Git, developers often create tags as reference points in their development process, particularly for release versions.

Git tags are Git objects that can be checked out similarly to a branch or a commit.

In this tutorial, we will explore how to easily checkout Git tags.

How to checkout a specific tag?

Step 1 - Fetch latest tag list from remote repository

The first thing you need to ensure is that you have obtained the most up-to-date tag list from the remote repository.

To retrieve tags from your remote repository, execute the git fetch command with both the --all and --tags options.

This will ensure that your local repository is updated with the latest tags from the remote repository, allowing you to access specific code versions and identify the latest releases of your project.

$ git fetch --all --tags

This command will print the following output:

# Output
From <remote url>
 * [new tag]    v1.0.0    -> v1.0.0

Step 2 - List all the tags

To view a complete list of tags in a remote repository, we use the git tag command.

$ git tag

The output of this command will be:

# Output
v1.0.0
v1.0.1

Step 3 - List all the branchs

Similarly, we can view the list of branches that are currently available on the remote repository by executing the following command.

$ git branch -r

You will see the output as below:

# Output
origin/HEAD -> origin/main
origin/dev
origin/main

Step 4 - Performing checkout of a specific tag version to a new branch

This step performs a checkout of a specific tag (acquired during Step 2) to a new branch that is not in the list of current branches obtained in Step 3.

You can use the git checkout command to check out a Git tag by specifying the tag name along with the branch.

$ git checkout <tag_name> -b <branch>

For example, if you want to check out tag v1.0.0 to a new branch named v1.0.0-branch, run the following command.

$ git checkout v1.0.0 -b v1.0.0-branch

Here is the output after running above command:

# Output
Switched to a new branch 'v1.0.0-branch'

By running the above command, you have successfully checked out the v1.0.0 tag.

When you run the command git checkout <tag_name> without using the -b option, Git will switch your local repository to a state called “Detached HEAD”.

In this state, you are working directly with a specific commit instead of a branch. This can cause confusion and difficulty in managing your source code, so you should use the -b option to create a new branch from the tag.

To check the status of your branch, use the git log command and ensure that the HEAD pointer, which represents the latest commit, is pointing to your annotated tag.

$ git log --oneline --graph

The output of this command will be:

# Output
* 5848c3c (HEAD -> v1.0.0-branch, tag: v1.0.0, main, dev) first commit

You can now begin working on your branch, using the tag you specified earlier as a starting point.

How to checkout the latest tag?

If you ever need to check out the latest tag, refer to the following section.

Step 1 - Update your local repository

To checkout the latest Git tag, you need to update your repository by fetching any available remote tags. Please run the following command.

$ git fetch --tags

# Output
From <remote_url>
 * [new tag]    v1.0.0    -> v1.0.0
 * [new tag]    v1.0.2    -> v1.0.2

Step 2 - Fetch the latest tag that is available

We will assign a variable named latest-tag with the value returned by the git describe command, which is the name of the latest tag on your remote repository.

Run the following command:

$ latest_tag=$(git describe --tags `git rev-list --tags --max-count=1`)

Then, run the following command to see the value of the $latest_tag variable:

$ echo $latest_tag

# Output
v1.0.2

Step 3 - Checkout the latest tag in your repository

$ git checkout $latest_tag -b latest

# Output
Switched to a new branch 'latest'

That’s all, you have successfully checked out the latest tag.

Run the following command to ensure that you are working on your latest tag.

$ git log --oneline --graph

Conclusion

In this tutorial, you have learned how to easily check out tags on Git using the git checkout command.

Additionally, you have gained more knowledge about checking out the latest Git tags from your repository, especially when dealing with multiple tags.

By following the steps outlined in this tutorial, you can now effectively manage your Git repository and work with tags more efficiently.