Git commands that you need to know to work with tags

4 min read

Updated: November 14, 2019

Like most VCSs, Git has the ability to tag specific points in history as being important. Typically people use this functionality to mark release points (v0.1, v1.0 and so on). In this post, you’ll learn how to list the available tags, how to create new tags and how to rename or delete the tags.

Listing Tags

Listing the available tags in Git is straightforward. Just type git tag:

git tag

v0.1
v0.2
v1.0
v1.1
v1.2

This command lists the tags in alphabetical order. The order in which they appear has no real importance.

To view the available tags sorted by date we can use the following command:

                                git log --tags --simplify-by-decoration --pretty="format:%ai %d"

                            

2018-06-04 14:58:43 +0300  (HEAD, tag: v1.2, origin/master, master)
2018-05-22 20:00:52 +0300  (tag: v1.1)
2018-05-21 03:00:02 +0300  (tag: v1.0)
2018-05-20 20:31:02 +0300  (tag: v0.2)
2018-05-16 19:45:58 +0300  (tag: v0.1)

You can see the tag data along with the commit that was tagged by using the git show command:

git show v1.2

tag v1.2
Tagger: Arthur Gareginyan <your@email.com>
Date:   Wed Nov 25 05:13:35 2015 +0300

version 1.2

commit 3ab06e59c904bc716ca5e3b6e6ff18bd30435c7e
Author: Arthur Gareginyan <your@email.com>
Date:   Mon Sep 21 19:07:05 2015 +0300

    Updated to version 1.2.

That shows the tagger information, the date the commit was tagged, and the annotation message before showing the commit information.

Creating Tags

Creating an annotated tag in Git is simple. The easiest way is to specify -a when you run the tag command:

                                git tag -a v1.2 -m "version 1.2"

                            

Syntaxis:

                                git tag -a [tag number] -m "[message]"

                            

The -m specifies a tagging message, which is stored with the tag. If you don’t specify a message for an annotated tag, Git launches your editor so you can type it in.

Tagging Later

You can also tag commits after you’ve moved past them. Suppose your commit history looks like this:

git log --pretty=oneline

5123c63717d1a5947855be440232d4c6bd9bafc6 Edited README.md
4ad3f4cd3b75dde7e8118e0b6d1510e9e6f57ff9 Edited README.md
b633e3ca3b447ff555a68779e16bb08a68d54b32 Edited README.md
7144da906ae83366d92cfed597deb714ad7a48be Created README.md and CONTRIBUTING.md
1cc52695c3bdd029e69fe85b0c900f1b4770c826 Plugin updated to version 1.2

Now, suppose you forgot to tag the project at v1.2, which was at the Plugin updated to version 1.2 commit. You can add it after the fact. To tag that commit, you need to specify the commit checksum (or part of it) in the command:

                                git tag -a v1.2 1cc5269 -m "version 1.2"

                            

Syntaxis:

                                git tag -a [version number] [commit checksum] -m "[message]"

                            

By default, the git push command doesn’t transfer tags to remote servers. You will have to explicitly push tags to a shared server after you have created them. This process is just like sharing remote branches – you can run git push origin [tagname].

git push origin v1.2

If you have a lot of tags that you want to push up at once, you can also use the —tags option to the git push command. This will transfer all of your tags to the remote server that are not already there.

git push origin --tags

Now, when someone else clones or pulls from your repository, they will get all your tags as well.

Deleting Tags

If you mistakenly added a tag or branch, and want to remove it (assuming you haven’t created a release with the tag), you can remove it by running the following commands:

                                git tag -d v1.2
git push origin :v1.2

Syntaxis:

                                git tag -d [tagname]
git push origin :[tagname]

The second command is only necessary if you already pushed it to the repository.

Renaming Tags

If you mistakenly make a typo in the tag name some time ago and want to rename this tag, you can do it by running the following commands:

                                git tag v1.2 v1.2nb
git tag -d v1.2nb
git push origin :refs/tags/v1.2nb
git push --tags

                            

Syntaxis:

                                git tag [tagname-new] [tagname-old]
git tag -d [tagname-old]
git push origin :refs/tags/[tagname-old]
git push --tags

                            

The colon in the push command removes the tag from the remote repository. If you don’t do this, git will create the old tag on your machine when you pull.

Conclusion

In this post I showed you the basic set of Git commands that I often use to work with tags.

If you think that I missed something in this post or you would like to share a handy command that you know, please let me know in the comment section below and I’ll be happy to add it to the post. Thanks!

If this article has helped you then please leave a comment