Tagging is a great feature of Git and most other VCSs for that matter, that allows you to hmmm… tag (a warm round of applause for Captain Obvious) specific points in history as being important.
And this is the exact context in which Semantic Versioning starts to make more sense than ever. Following the wisdom within these two posts will at least make you look serious about software development, releasing new versions and fancy patches and stuff…
Listing Your Tags
Running the tag command with no options or arguments will list all the available tags in your repository:
But you can also list only the tags with a particular pattern. The Git source repo, for instance, contains more than 240 tags. If you’re only interested in looking at the 1.4.2 series, you can run this:
$ git tag -l 'v1.4.2.*' v18.104.22.168 v22.214.171.124 v126.96.36.199 v188.8.131.52
Creating New Tags
We can have two different types of tags: lightweight and annotated. I’m not going to go on about the differences between those two, or why one of them is better than the other, they are both acting like pointers to a specific commit, but I prefer annotated tags as they can store additional information and be signed and verified with GNU Privacy Guard (GPG) – which you can probably read more about in the man page or the official docs.
To create an annotated tag, just use the
-a option with the
git tag command like this:
git tag -a v1.0.0 -m 'Version 1.0.0'
-m option specifies the tagging message which is stored within the tag object, but if you don’t specify it, Git will launch your editor so you can type it in.
Note to self: I’m planning on writing some script at some point that would help me automate the creation of change logs for major and minor versions, based on the commit messages between versions or todo list entries.
Also if, say you forgot to tag an important commit sometime earlier, you can still do it now by referencing its checksum:
git tag -a <tagname>. -m '<message>' <checksum>
Update: One more thing, in case you made a horrible typo on the tag you just created (like I just shamefully did), there’s something you can do that works pretty much like the
--amend option for
git tag <tag-name> <tag-name> -f -m "<new-message>"
That will create a new tag with the same name by overwriting the original, or you could pop up your editor to type in more complex messages by running:
git tag <tag-name> <tag-name> -f -a
Viewing detailed information about individual tags, to be more precise, can be done using the
git show command followed by the tag’s name:
git show v1.0.0
Again, this command has tons of useful options but you’re gonna try them all out on your own. I’m now giving you some more interesting combos that might come in handy:
git tag -l v1* -n999
That one will display the first maximum of 999 lines of all the tags starting with v1 – feel free to filter these as you like and display more or less lines of the tag message.
git log --oneline --decorate --reverse v1.0.0 v2.0.0
Use the one above to display a list of all the commits between major versions v1 and v2 in reverse order.
git log --oneline --decorate --graph --reverse --all
Or list the entire repository history in the same format as the above while also displaying branch graphs.
For some reason,
git push doesn’t transfer tags too by default, so it needs to be done separately. You can either do it one tag at a time:
git push origin <tagname>
or by using the
--tags option for all tags at once (it will only transfer tags that are not already on the remote anyway):
git push origin --tags
After this, any clone or pull operation will fetch all the tags as well so you can just go and take a long nice poop because:
- you deserve it
- your repo looks legit
- according to semver, it now also has a meaning