A tag is a static reference used to mark a specific and immutable point in the history of your repository.
We have learned that branches are movable pointers. When you make a commit, the branch advances. They are living, dynamic labels.
But sometimes we need to do the exact opposite: we want to mark a fixed and immutable point in history. We want to say: “This exact commit is the Version 1.0 we delivered to the client”.
For this, Git offers us Tags or git tag. Today we will see how to use these “pushpins” to organize our releases and how to use them to manage our project’s versioning 👇.
What is a Tag?
Technically, a tag is very similar to a branch: it’s a pointer to a specific commit. The big difference is that the tag does NOT move.
If you make a new commit, the branch will advance, but the tag will forever point to that old commit. It’s the perfect way to mark milestones: v1.0, v2.1-beta, release-2023.
Although you can name your tags however you like, the industry standard is to use Semantic Versioning.
Types of tags
Git has two types of tags. Choosing one or the other depends on the importance of what you are marking.
They are simply a pointer to a commit (like a branch that doesn’t change). They don’t store author, date, or their own message. They are like a quick “bookmark”.
How to create them:
git tag v1.0-wip
When to use them? For personal or temporary use. “I want to mark this point to test something later”.
This is the proper option for software releases. Annotated tags are stored in Git’s database as complete objects.
They contain:
- The tag name.
- The name and email of the person who created the tag.
- The tagging date.
- A tagging message (similar to a commit message).
How to create them: We use the -a (annotated) and -m (message) options:
git tag -a v1.0.0 -m "Version 1.0.0 - Official Release"
When to use them? Whenever you are going to release a public version of the software.
It’s recommended to use Annotated Tags by default. The extra information (who made the release and when) is important for identifying them in the future.
Working with Tags
If you’ve been working for years, you’ll have many versions. To see them:
git tag
If you’re looking for a specific series (e.g., all 1.x versions):
git tag -l "v1.*"
Sometimes you forget to create the tag on release day. You realize three days later. No problem.
You can tag an old commit by specifying its Hash at the end of the command:
git tag -a v0.9.0 a1b2c3d -m "Forgotten Beta Version"
To see the details of an annotated tag and the commit it points to:
git show v1.0.0
Pushing tags to the server
By default, the git push command does not transfer tags to remote servers. You have to push them explicitly.
To push a specific tag:
git push origin v1.0.0
To push ALL your tags at once:
git push origin --tags
Use --tags with care if you have many “garbage” tags locally that you don’t want to share with the team.
Deleting tags
If you made a mistake (for example, you put v1.0.1 on a commit that had a bug), you can delete the tag.
Delete locally:
git tag -d v1.0.1
Delete remotely (GitHub/GitLab): Just like deleting remote branches, we need a special push command:
git push origin --delete v1.0.1
