Tags are quite a simple aspect of git, but there are a few things that a lot of people don’t know about. These shortcuts will make it quick for you to tag and manage those tags in your git repositories.

Probably the most common use of tags is to note when a version of the software the repository is tracking is released. Usually this will be something like ‘1.2.8’ if you are sticking with SemVer.

Creating tags

Lightweight tags

At its simplest level you can simply add a tag to your git repository with:

git tag 1.2.8

These tags can then be used to easily revert to or diff between versions of the project. For example to see the changes between versions of the project you can simply execute:

git diff 1.2.6 1.2.8

Annotated tags

Tags can also include a more descriptive body message or annotation much like a commit message. Usually this is achieved using (-a for annotation):

git tag -a 1.2.8

This will open up your commit editor - in my case this is vim - so that you can enter an annotation with your tag.

However if you only have a one line description to include then you can simply use -m just like you can with git commit:

git tag -m "Releasing version 1.2.8" 1.2.8

Listing tags

Lightweight tags

To simply list the tags in your repository you can call:

git tag

If your project has many tags then it can be very useful to filter the list you are getting:

git tag -l '1.2.*'

Which would show you all the tags beginning with 1.2. as * is a wildcard.

Annotated tags

You will notice that when you call git tag you do not get to see the contents of your annotations, but just the headline tag (1.2.8). To see the annotations you must add -n to your command:

git tag -n

If you have entered multiple lines in your annotation then you will need to specify how many of those lines you want git tag to display. By default -n only shows the first line so if you wanted to see the first 10 lines for example you would use:

git tag -n10

Tag details

To see the details of a particular tag you can call git show much like you would with a commit hash:

git show 1.2.8

This will present you with the tag details and the information from the commit that was tagged.

Publishing tags

When you push your changes to another repository git does not transfer the tags along with it by default.

This is easily overriden like so:

git push --tags origin master

If you are pulling in someone elses changes then their tags will be pulled in and tracked by default. If you do not want this to happen then you can add the following switch:

git pull --no-tags origin master