GIT Tags Guide - Create, delete, push tags to remote and much more

Posted by Gulab Bisht

GIT Tagging is a mechanism of referencing a point in GIT history. Unlike a git branch, once you create a git tag it cannot be changed and that is kind of its SUPERPOWER. In real life projects, it is used to make a reference point in GIT history for a release.

This blog post will be a complete guide on how to create a tag, list/view tags, git push tag to remote, git delete tag from local and remote and much more.

"Git create tag" to create tag

git tag <tagname>

Above command can be used to create a tag by replacing <tagname> with the actual tag name. Here is an example of how someone might use this git command in real life to create tag.

git tag v1.0

Create tag from a different Commit

Normally above command will create a tag on the commit that HEAD is referencing to. Git also provides you the flexibility of creating a tag from other commits.

You can simply list all the commits by "git log" command and choose the SHA hash. Pass that particular hash as an argument in the git command to create a tag from a particular commit.

git tag v1.0 35a3a6c8e025da8fc6be5058fe6bc4024fd76642

List/View all available Git Tags

git tag

This is the command which is used to list all the tags available in GIT history. The output of this command could be something like:

v1.0
v2.0
v2.5
v3.0

-l option can be added to "git tag" command to further refine the result if you have a big list of tags. For example, if you only want to see tags for v2.0 and sub-releases.

$ git tag -l "v2.*"
v2.0
v2.5

Git push tag to remote

Pushing a tag in git to a remote is similar to pushing a branch to a git remote. The only difference is that you need to mention the tag name after the "git push" command as by default this command only pushed the branch.

$ git push origin v1.0                                                                                                                                              
Counting objects: 247, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (167/167), done.
Writing objects: 100% (247/247), 333.76 KiB | 27.81 MiB/s, done.
Total 247 (delta 75), reused 245 (delta 74)
remote: Resolving deltas: 100% (75/75), completed with 2 local objects.
To github.com:gulabbisht/drupixels.git
 * [new tag]               v1.0 -> v1.0

And if you want to push all tags from your local to the remote then add "--tags" to the git command and it will push all tags to the remote.

git push origin --tags

Git delete local tag

Deleting a Git tag on local is as simple as deleting a git branch and a good option to clear the clutter.

Best practice to delete a Git tag is to run "git tag" command to list them, identify the tag you want to delete and run the "git tag" command with -d and tag as arguments.

$ git tag
v1.0
v2.0
v2.5
v3.0
$ git tag -d v2.5
Deleted tag 'v2.5' (was aea93f1727)
$ git tag
v1.0
v2.0
v3.0

Git delete remote tag

Once the tag is removed from local, the next step would be to remove the tag from the remote as well and this can be done using the command below.

$ git push origin :refs/tags/v2.5
To [email protected]:gulabbisht/drupixels.git
 - [deleted]               v2.5

Git checkout tag

Sometimes you need to checkout a tag to see changes in the files. You can do so by simply running the "git checkout <tagname>" command as below.

$ git checkout v1.0
Checking out files: 100% (1146/1146), done.
Note: checking out 'v1.0'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by performing another checkout.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -b with the checkout command again. Example:

  git checkout -b <new-branch-name>

HEAD is now at aea93f1727... Merge branch 'master' of github.com:gulabbisht/drupixels

As you can see in the output of the command that we are in a 'detached HEAD' state. This means that any update in code and then commit will not update the tag, remember it was the SUPERPOWER. Instead, that commit will also behave like detached commit and cannot be referred to any branch or tag later unless you refer the exact commit hash.

If you want to make any changes after checking out a tag then best practice would be to create a new branch out of it.

 

Here are some references to detailed documentation around Git Tagging:

https://git-scm.com/book/en/v2/Git-Basics-Tagging

https://www.atlassian.com/git/tutorials/inspecting-a-repository/git-tag

Tags