How to Checkout a Git Tag (Step-by-Step Guide)

Git tags are used to mark specific commits in your repository, often for releases. If you need to checkout a tag, this guide will show you how.

1. List Available Tags

To see all tags in your Git repository, run:

git tag

For detailed tag information:

git show <tag-name>

2. Checkout a Tag

To move your working directory to a tag’s state:

git checkout <tag-name>

Example:

git checkout v1.2.3

Detached HEAD Warning

When checking out a tag, Git moves you to a detached HEAD state, meaning:

• You can view and modify files, but any new commits won’t belong to a branch.
• To return to your branch:

  git checkout main  # Or your working branch name

3. Checkout a Tag and Create a Branch (Recommended)

If you want to make changes based on a tag, create a new branch from it:

git checkout -b my-feature-branch <tag-name>

Or using the newer git switch command:

git switch -c my-feature-branch <tag-name>

4. Checkout a Remote Tag

To checkout a tag from a remote repository:

1. Fetch all tags:

   git fetch --tags
   

2. Checkout the tag:

   git checkout tags/<tag-name>
   

5. Switch Back to a Branch

If you’re in a detached HEAD state and want to return:

git checkout main  # Or any branch name

Or with git switch:

git switch main

FAQs

Why does `git checkout <tag>` put me in a detached HEAD state?

Because a tag is not a branch—it’s just a pointer to a commit. You need to create a branch if you want to make changes.

Can I push changes after checking out a tag?

Not directly. You need to create a branch first using `git checkout -b new-branch <tag>`.

What is the difference between `git checkout` and `git switch`?

`git checkout` is older and used for both branches and files. `git switch` is a newer, clearer alternative for switching branches.

Conclusion

Checking out a Git tag is useful for viewing a snapshot of your repository at a specific point. However, since tags are not branches, you should create a new branch if you need to make changes.