The Complete Guide On Git Tag
In Git, tags are used to create references to specific commits. Think of a tag as a checkpoint in your application development history. Typically, tags are used to mark release versions (for example, v1.0.1). Luckily, it is easy to create and manage tags because Git provides straightforward and easy-to-use commands.
To create a new tag in Git, use this command:
bashgit tag <tagname>
By the end of this article, you will know everything about tags in Git, how to create a tag, delete a tag, list all the tags, and many more.
Let’s get to it 😎.
What is a Git tag?
A tag is a pointer to a specific commit typically used to mark a release version or as a bookmark.
Unlike the branch, you cannot add more code to a tag. Tags always point to the same object.
By default, tags are created on the commit referenced by HEAD (the current commit).
How to create a tag?
In Git, you can create Lightweight or Annotated tags.
1. Create a lightweight tag
Lightweight tags only contain the commit checksum.
Use the below command to create a lightweight tag.
bashgit tag <tagname>
Since a lightweight tag only contains a reference to a specific commit, it can be seen as a bookmark or as a quick link.
2. Create an annotated tag
Annotated tags contain extra metadata like the name of the tagger, the email, and the date.
Like commits, annotated tags have a tagging message that you need to specify.
Use the below command to create an annotated tag.
bashgit tag -a <tagname> -m "tag message"
Additionally, annotated tags can be signed and verified by the GNU Privacy Guard (GPG).
When to use a lightweight vs an annotated tag?
For public releases, it is a best practice to use annotated tags.
For private releases, you can use lightweight tags.
How to view a tag's data?
To view a tag's data, you can use the git show command with the tag's name.
bashgit show <tagname>
For a lightweight tag, the command will output the referenced commit's data.
For an annotated tag, the command will output the tag's data AND the commit's data.
How to list all the tags?
To list all the stored tags, use the git tag command.
bash> git tag
v1.0.0
v1.0.1
v1.0.2
v2.0.0
Note: The tags will appear in alphabetical order.
List all the tags sorted by date.
To list all the stored tags and sort them by date, use this command.
bashgit for-each-ref --sort=creatordate --format '%(refname) %(creatordate)' refs/tags
Find a tag that contains specific characters.
To find a tag containing specific characters, use the git tag -l command with a wildcard expression.
bash> git tag -l "v2*"
v2.0.0
How to tag an old commit?
When you create a new tag by default, it references the current commit (HEAD).
However, you can choose to tag an older commit. For that, you first need to find the checksum of the commit that you want to reference.
Then, simply use this command:
bashgit tag -a <tagname> <checksum_commit>
How to replace an old tag?
If you attempt to create a tag with an existing tag name or tag an older commit with an existing tag, you will get an error (fatal: tag '<tagname>' already exists).
To retag or replace an old tag, you need to use the git tag command with the force option, like so:
bashgit tag -a -f <tagname> <checksum_commit>
How to checkout a tag?
To checkout a tag, use the git checkout command with the tag's name.
bashgit checkout <tagname>
Note: This will result in the HEAD being detached.
Note: Any changes made to the repository will not modify the tag but rather create a new detached commit.
How to push a tag to a remote?
To push a tag to a remote server, use the git push command with the tag's name.
bashgit push origin <tagname>
You can also push all your local tags using the git push --tags command.
bashgit push --tags
How to delete a tag?
To delete a git tag completely, you will need to remove it locally and remotely.
1. Delete a local tag
To delete a local tag, use the git tag -d command with the tag's name.
bashgit tag -d <tagname>
2. Delete a remote tag
To delete a remote tag, use this command:
bashgit push --delete origin <tagname>
Final thoughts
Tags are a great way to create a checkpoint of your repository code to mark release versions or bookmarks.
Luckily, Git offers all the necessary tools to create and manage tags easily.
Even though lightweight tags exist, I always recommend using annotated tags because they offer better visibility with their metadata information.