A comprehensive guide to mastering the utilization of Git tags
Using Git tags is a really helpful way to mark important points in your project’s commit history. You can use them to highlight versions, or significant changes. Tags are like our little notes that help us keep track of release versions, like v1.0.0 which we can easily use to find the way back to the exact version of the repository.
In the following guide, we’ll take a look at the essential flags and options of Git tagging. We’ll cover how to create, manage, and push tags, as well as how to handle common tag related tasks like checking out commits with tags, deleting, and using them for version management.
What Are Git Tags?
Let’s talk first about Git tags. They’re like little labels that point to important commits in a Git repository’s history.
Tags come in two forms:
Lightweight Tags: These are like little bookmarks that point to a specific commit. They don’t have any extra information.
Annotated Tags: These tags contain more details like tagger’s name, email address, and date, along with a message describing the tag. Annotated tags are more commonly used and are better for public release tags because they provide more information.
1- Create a Lightweight Tag
A lightweight tag is just a pointer to a specific commit. It doesn’t contain any extra info like the date or the tagger’s info. It’s just a label for the commit.
To create a lightweight tag:
git tag <tag-name>
Example:
git tag v1.0.0
This creates a tag v1.0.0 on the current HEAD.
2- Create an Annotated Tag
An annotated tag is a way to add extra details to your tags. It can include the tagger’s name, email address, date, and a description message..
To create an annotated tag:
git tag -a <tag-name> -m "Description Message"
Example:
git tag -a v7.0.0 -m "First stable version 2025"
This creates a tag v7.0.0 and attaches a message First stable version 2025.
3- Tagging Specific Commits
If you want to tag a commit that isn’t the latest one, you can specify the commit ID when creating the tag.
git tag <tag-name> <commit-ID>
Example:
git tag v0.9.0 7ebaac18e14e4……
This will create a tag v0.9.0 for the commit with the hash 7ebaac18e14e4fb24…..
4- List Tags
If you’d like to see all the tags in your repository, you can use the command below:
git tag
Example Output:
v1.3.2 v2.1.0 v3.0.0
If you want to list tags with more details:
git tag -n
5- Delete a Tag
If you need to delete a tag in you local branch:
git tag -d <tag-name>
Example:
git tag -d v2.0.0
This command only deletes the local tag v2.0.0. But not deleting the tag from the remote repository.
6- Push Tags to a Remote Repository
Don’t worry if you’re not seeing tags being pushed when you push commits. This happens by default. To push tags to the remote repository, follow these steps:
git push origin <tag-name>
Example:
git push origin v2.3.7
To push all tags at once to the remote repo, use the following command:
git push --tags
7- Checkout a Tag
If you’d like to switch to a specific tag in the repository instead of using commit hash or id, you can use.
git checkout <tag-name>
Example:
git checkout v5.7.8
This will put your working directory in a “detached HEAD” state. What this means is that you’re no longer on a branch, but instead you’re viewing the repository as it was when v5.7.8 was committed detached from your current branch. If you want to make changes, you’ll need to create a new branch from v5.7.8 tag.
8- Creating a Branch from a Tag
Go ahead and make those changes we’ve been talking about in the last section and ! To do so, just create a branch that starts at that tag or another tag you want to use.
git checkout -b <new-branch-name> <tag-name>
Example:
git checkout -b Fixbug/v7.3.2 v7.3.1
This creates a new branch called Fixbug/v7.3.2 starting from the v7.3.1 tag.
9- Tagging After a Commit
If, for some reason, you forgot to tag a commit, don’t worry! You can always add a tag to it later. To do so, simply use
git tag <tag-name> <commit-ID>git tag v2.3.1 b36ea4720….
If you want to push this tag to the remote repository, remember to run:
git push origin v2.3.1
10- Checkout a Tag and Make Changes (Detached HEAD)
Once you check out a tag, you’ll be in “detached HEAD” state. This means you can make changes here, but they won’t be on a branch unless you stage them, commit them and create a new one.
Here’s how you can handle this:
git checkout v1.0.0
# Now in a detached HEAD state
# Stage your changes
git add .
# commit your changes
git commit -am "Bug fixed after v1.0.0"
# Create a new branch to save the changes
git checkout -b fixedbug/v1.0.1
This way, you’ll be able to keep the changes made on the v1.0.0 tag in a new branch (fixedbug/v1.0.1).
11- Push Tags to a Remote Repository
If you push your commits to a remote repository, tags don’t automatically get pushed with the commits. But don’t worry though! If you want to push a tag, here’s how:
git push origin <tag-name>
Or to push all your available tags at once:
git push --tags
12- Fetching Remote Tags
If you’re looking to fetch tags from the remote repository:
git fetch --tags
This ensures that your local repository has all the tags from the remote.
13- Remove Remote Tags
You can remove a tag from a remote Git repository using the command line. Here’s how you can do it:
git push origin :refs/tags/<tagname>
Replace <tagname> with the name of the tag you want to remove.
Example of Git Workflow with Tags
- Add a new feature: Let’s assume that you completed a new feature and you want to release it.
- Commit final changes: You make your final commit with the feature code.
- Tag the Commit: Tag the final commit as your first release version: git tag -a v1.0.0 -m “First release version”
- Push the Tag to Remote: git push origin v1.0.0
- Later Versions: After bug fixes or new features, you may want to create another tag: git tag -a v1.0.1 -m “Fixed a bug in ProductController”
- Push the New Tag: git push origin v1.0.1
Final considerations
Git tags can be a real lifesaver when you’re tracking the history of your project, especially when it comes to releases. With lightweight or annotated tags, you can manage major releases with ease!
Whether you’re working on a new feature, fixing a bug, or documenting a new release, tags make your project history neat and manageable.