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.
Key Takeaways
git checkout <tag>lets you view the code at a specific tag.- You end up in a detached HEAD state, meaning changes won’t be linked to a branch.
- For active development, use
git switch -c <branch> <tag>to create a new branch from the tag.
1. List Available Tags
To see all tags in your Git repository, run:
git tagFor 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.3Detached 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 name3. 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:
-
Fetch all tags:
git fetch --tags -
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 nameOr with git switch:
git switch mainFAQs
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.
Not directly. You need to create a branch first using `git checkout -b new-branch <tag>`.
`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.
