Git is a beautiful and quite necessary tool for developers. It eases our lives in maintaining codebases shared across multiple people with ease.

Using Git-scm's definition:

Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency.

If you are not familiar with git, learn the basics first:

In this article, we are going to understand the what, why, when and how of Git tags. This should be enough to get you started using tags in your projects.

What are Git Tags?

Tagging refers to having references to certain points (milestones) in Git history. Tags allow you to capture specific points in your code's git history which can be used anytime later.

You can treat a tag like a branch that doesn't change.

A tag represents a version of a particular branch at a moment in time. Tags essentially let developers mark important checkpoints in their development process.

Why and When?

You've probably seen something like v1.0.0. This generally denotes the version/release number of a product. When major changes need to be shipped to users, a tag is created.

Tags are usually used to mark milestones like new feature releases or bug fixes which can be distributed to users. If you use tags to trigger deployments, they pair well with a solid CI/CD pipeline that can build and release automatically when a new tag is pushed. You can even automate the tagging process itself as part of your release workflow.

You don't want this to change again and again. Using tags ensures that the user gets the version which was created at a certain point of time irrespective of new commits added to the codebase.

How to Use Git Tags

Creating a tag

git tag <tag_name>
// Eg. git tag v1.0.1

This command tags the latest commit in your current branch. The tag_name is a name you give to this commit. It is generally something like v1.0.1, although you can name it anything.

The naming pattern generally followed is:

v<major>.<minor>.<patch>
  • major: breaking changes
  • minor: version compatible with previous version
  • patch: bug fix

Once you create a tag, push it to remote:

git push --tags

You can also create a tag with a message:

git tag -a <tag_name> -m "message"
// Eg. git tag -a v1.0.1 -m "First release"

Types of Git Tags

There are 2 types of git tags, and the Pro Git Book covers both in depth:

  • Annotated
  • Lightweight

Annotated Git Tags

Annotated tags store extra metadata such as author name, release notes, tag-message, and date as full objects in the Git database. This data is important for a public release of your project.

The -a flag makes the tag annotated:

git tag -a v1.0.1 -m "First release"

Lightweight Git Tags

Lightweight tags are the simplest way to add a tag. They just store the name and hash of the commit they refer to. They act like simple bookmarks.

git tag v2.1-lw

Tag a Specific Commit

git tag <tag_name> <commit_sha>

If you want to create a tag for an older commit, use the commit SHA.

Listing All Tags

git tag

Output:

1.0.0
1.0.1
1.0.2
1.0.3
2.0.0
2.1.0

You can filter tags using -l with a pattern:

git tag -l "1.0*"

Fetch Tag Details

git show <tag_name>
// Eg. git show v1.0.1

This shows the author, tag message, respective commit, date and other details.

Deleting a Tag

git tag -d <tag_name>

Pushing Tags

git push origin <branch> --tags

Pulling Tags

git fetch --tags

Checkout Tags

git checkout <tag_name>
// Eg. git checkout v1.0.1

If you want to go back to the state of the codebase at a certain tag, use the checkout command.

More Resources