Tagging

Tagging in Git serves as a valuable method to denote specific release versions of your code or to reference a particular commit in your project’s history. However, understanding the right (and wrong) ways to utilize git tag is essential. This post will cover the proper techniques for tagging in Git.

Think of a tag as a post-it note that refers to a specific commit. It typically includes a name (e.g., v1.0.0 or production) and an optional message. Git for Computer Scientists visualizes a tag in this manner:

So, how do you create a tag? Is it simply git tag v1.0.0? Not quite. By default, this command creates a “lightweight” tag, essentially a reference to a commit that doesn’t move. While lightweight tags can be useful for marking specific versions or commits, it’s generally advisable not to push these tags.

Ideally, when creating a tag, you should at least use the -a option to create an annotated tag. Optionally, you can sign the tag with your GPG key using the -s or -u <key-id> options. Annotated tags provide more information about the tag, such as the tagger’s name, date, and an associated message. They are preferable for release versions or significant milestones.

Let’s create a new annotated tag and explore how to reference it even after additional commits have been made, then push it to a remote repository:

  Merge branch 'master' of git@github.com: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 git@github.com:qrush/config.git

[new tag] v1.0.0 -> v1.0.0

The git describe --tags command shows that we are one commit ahead of the last tag. This provides an easy way to determine the amount of work done since the last commit. Additionally, the --tags option is used to push all tags to the remote repository. However, you can push a single tag with git push origin v1.0.0.

In conclusion, understanding how to properly tag commits in Git is crucial for managing project versions and releases effectively. If you have unique methods for integrating tags into your Git workflow, share them in the comments or submit a tip to help others learn!