GIT: Using Tags

15.1. What are tags?

Git has the option to tag a commit in the repository history so that you find it easier at a later point in time. Most commonly, this is used to tag a certain version which has been released.

If you tag a commit, you create an annotated or lightweight tag.

15.1.1. Lightweight and annotated tags

Git supports two different types of tags, lightweight and annotated tags.

A lightweight tag is a pointer to a commit, without any additional information about the tag. An annotated tag contains additional information about the tag, e.g., the name and email of the person who created the tag, a tagging message and the date of the tagging. Annotated tags can also be signed and verified with GNU Privacy Guard (GPG).

15.1.2. Naming conventions for tags

Tags are frequently used to tag the state of a release of the Git repository. In this case they are typically called release tags.

Convention is that release tags are labeled based on the [major].[minor].[patch] naming scheme, for example "1.0.0". Several projects also use the "v" prefix.

The idea is that the patch version is incremented if (only) backwards compatible bug fixes are introduced, the minorversion is incremented if new, backwards compatible functionality is introduced to the public API and the major version is incremented if any backwards incompatible changes are introduced to the public API.

15.2. List tags

You can list the available tags via the following command:

git tag

15.3. Search by pattern for a tag

You can use the -l parameter in the git tag command to search for a pattern in the tag.

git tag -l <pattern>

15.4. Creating lightweight tags

To create a lightweight tag don’t use the -m, -a or -s option.

The term build describes the conversion of your source code into another state, e.g., converting Java sources to an executable JAR file. Lightweight tags in Git are often used to identify the input for a build. Frequently this does not require additional information other than a build identifier or the timestamp.

# create lightweight tag
git tag 1.7.1

# see the tag
git show 1.7.1

15.5. Creating annotated tags

You can create a new annotated tag via the git tag -a command. An annotated tag can also be created using the -mparameter, which is used to specify the description of the tag. The following command tags the current active HEAD.

# create tag
git tag 1.6.1 -m 'Release 1.6.1'

# show the tag
git show 1.6.1

You can also create tags for a certain commit id.

git tag 1.5.1 -m 'version 1.5' [commit id]

15.6. Creating signed tags

You can use the option -s to create a signed tag. These tags are signed with GNU Privacy Guard (GPG) and can also be verified with GPG.

15.7. Checkout tags

If you want to use the code associated with the tag, use:

git checkout <tag_name>

If you checkout a tag, you are in the detached head mode and commits created in this mode are harder to find after you checkout a branch again. .

15.8. Push tags

By default the git push command does not transfer tags to remote repositories. You explicitly have to push the tag with the following command.

# push a tag or branch called tagname
git push origin [tagname]

# to explicitly push a tag and not a branch
git push origin tag <tagname>

# push all tags
git push --tags

15.9. Delete tags

You can delete tags with the -d parameter. This deletes the tag from your local repository. By default Git does not push tag deletions to a remote repository, you have to trigger that explicitly.

The following commands demonstrate how to push a tag deletion.

# delete tag locally
git tag -d 1.7.0

# delete tag in remote repository
# called origin
git push origin :refs/tags/1.7.0