Tagging git commits

Git provides the functionality to mark a point in your repository’s history with a "tag". These tags are typically used to indicate the release of a version. With Git you can create two types of tags: Annotated and Lightweight. These two types differ in how they are stored in the Git repository and the amount of meta data they contain.

Annotated Tags

Annotated tags are normally what you want when tagging a release. You want this because they have more meta-data attached to them, much like regular commits. They contain a checksum, name, email, date and have a tagging message. Optionally you can sign annotated tags with your GPG key.

Lightweight Tags

Lightweight tags point to a commit in a similar way as branches do. The difference being that a branch points to the next commit as soon as you add a commit. Lightweight tags will keep pointing to the commit that was tagged. Lightweight are useful for private use. You can use them like a bookmark for yourself.

Manage tags

Git comes with a whole set of commands to deal with tags. We'll go over all the commands you need to manage the tags in your repository.

Create tags

You can create a Lightweight tag by using the git tag command and provide a name for the tag. This creates a lightweight tag to the last commit it your currently active branch.

$ git tag lw-bookmark

Creating Annotated tags is similar to creating lightweight tags. You use the same git tag command but have to add the -a option. Since annotated tags require a message Git will launch an editor for you to enter one. If you prefer you can also use the -m option to specify the message directly.

$ git tag -a v0.2-annotated
# or
$ git tag -a v0.2-annotated -m "Release v0.2"

Both examples tag the current place in time of your Git repository. You can ofcourse also tag previous commits. This can be done by adding the commit hash after the name of the tag.

$ git tag -a v0.1-annotated -m "Release v0.1" 3f18d02

To list the tags we just created we can use the git tag command without any arguments. This lists all the lightweight and annotated tags in your repository in alphabetical order.

$ git tag
lw-bookmark
v0.1-annotated
v0.2-annotated

This listing tags gets quickly out of hand in a large Git repository. So it might be useful to list tags with a pattern. For example, if you’re only interested in seeing tags for the v0 releases you can run the following command.

$ git tag -l "v0.*"
v0.1-annotated
v0.2-annotated

Tag details

Listing the tags doesn’t provide a whole lot of details. It is just a list of what is available in your repository. To show more details of a tag you use the git show command.

$ git show v0.2-annotated
tag v0.2-annotated
Tagger: John Developer <john.developer@example.com>
Date:   Tue Feb 24 20:56:07 2020 +0100

Release v0.2

commit 321f7dde2c3bc5458c030ee6e9ee3825d91514ca (HEAD -> master, tag: v0.2-annotated)
Author: John Developer <john.developer@example.com>
Date:   Tue Feb 24 20:55:36 2020 +0100

    Add an awesome feature

As you can see above you can see quite some details of annotated tags. You see details about the tag created and the commit that was tagged. Lightweight tags are a lot less detailed. As you can see below they just show details of the commit that was tagged.

$ git show lw-bookmark
commit c773c5822b253b6f483e6c63ba73ec55f61faf8f (tag: lw-bookmark)
Author: John Developer <john.developer@example.com>
Date:   Tue Feb 24 20:51:18 2020 +0100

    Tiny bug fix

Push tags

When you push changes to a remote server Git doesn't include tags by default. If you want to push your tags you have to do this explicitly. To push a single tag to a remote server you run the command git push [remote] [tagname].

$ git push origin v0.2-annotated

In case you have multiple tags to push you can use the --tags option instead. But keep in mind that this will push all your tags, lightweight and annotated.

$ git push origin --tags

Delete tags

Deleting a tag from just your local repository is straight forward. It works the same for annotated and lightweight tags and you do it by running the command git tag -d [tagname].

See the example below where we delete the lightweight tag that we created before.

$ git tag -d lw-bookmark
Deleted tag 'lw-bookmark' (was c773c58)

In case you pushed the tag to a remote server before you can delete by passing the --delete option to the Git push command.

$ git push --delete origin lw-bookmark