Why are tags used in Git

git ready


registered on 03 Feb 2009

Tagging in Git is a great way to tag a specific version of code, or to reference exactly one commit in your version history for whatever reason. This post covers the right (and wrong) ways to use it.

Probably the best way to describe a day is a sticky note that indicates a commit. It includes a name, something like or, and also a message, if you want. Git for Computer Scientists visualizes a day as follows:

How is a tag created? Easy right? NOT CORRECT. You want that usually do not do. Some people think that this command does the wrong thing by default. With no arguments, it creates a "lightweight" tag that is essentially a branch that never moves. Lightweight tags are still useful, for example, for marking a known good (or bad) version, or marking a series of commits that you might want to use in the future. Nevertheless, you shouldn't push these types of tags into a remote repository.

Usually you at least give the option to generate an unsigned tag, or you sign a tag with your GPG key using the or option. Once that's done, you can use to see how many commits you've made since the previous day or the day mentioned. Git-fu has a nice guide on how to use this command (and deserves a tip of its own in the future too!).

Then let's just create a new tag and see how we can reference it, even if some commits have been made. Then we push the day into a remote repository. It's a lot easier than you think:

$ git tag -a v1.0.0 -m "Creating the first official version." $ git show v1.0.0 tag v1.0.0 Tagger: Nick Quaranto Date: Tue Feb 3 20:37:45 2009 -0500 Creating the first official version. commit a8d1b55c5d4bdec843d9942cabf1b678bc1d4eed Merge: 00b9675 ... 1b487b8 ... Author: Nick Quaranto Date: Sun Nov 30 00:41:08 2008 -0500 Merge branch 'master' of [email protected]: qrush / config $ git describe --tags v1.0.0 $ touch test $ git add test $ git commit -am "Adding test files" Created commit a7aafb8: Adding test files 0 files changed, 0 insertions (+), 0 deletions (-) create mode 100644 test $ git describe --tags v1.0.0-1-ga7aafb8 $ git push --tags Counting objects: 40, done. Compressing objects: 100% (37/37), done. Writing objects: 100% (40/40), 29.32 KiB, done. Total 40 (delta 15), reused 9 (delta 2) To [email protected]: qrush / config.git * [new tag] v1.0.0 -> v1.0.0

The second describe command shows us that we are committed before the last day we made it. This is an easy way to find out how much work has been done since the last commit. The option was used here to push the tags as well. But only one day could be pushed with. On GitHub (or in your remote repository) you should see the transferred tags:

A small side note, if you want to move or rename your transferred tags, Git makes it very difficult for you to do this. Check the man page. Here is an explanation of why it is so complicated and should be used with caution.

If you know of a unique way for integrating tags into your Git workflow, let us know in the comments or send us a tip so others can learn from it!