How to Use Git Tags

This article goes over what is a Git tag and how to use Git tags, including creating, listing, and deleting.

What is a Git Tag

Tags are references that point to a specific point in Git history. They capture a historical point for a marked version release (such as v1.0.0). A tag is like a branch that does not change.

Why Create Git Tags

Git Tags are often used when creating a release or a hot-fix. Here is a list of Git Tag use cases:

• Marking Release Version
• Deployment Snapshots
• Releasing Milestones or Important Events
• Hotfix Tracking
• Branching for Legacy Support
• etc

Create a Tag

When releasing a new software version using Git flow, a tag is usually created (automatically if via the CI process in the CI/CD pipeline).

The bash script below shows how to create and push a tag to the remote server.

Checkout the branch

git checkout develop

create a tag off the head of the current branch

 git tag -a v1.0.1 -m "version 1.0.1"

push the tag to remote server

 git push origin v1.0.1

verify that the tag has been pushed to the remote server

git tag -l "v1.0.1"

Create a Branch based on a Tag

Why Create Branches off a Tag

• Support Legacy Version
• Apply Hotfixes to a Past Release
• Building a Stable Point for New Development
• Create a Patch Version from a Past Release
• more..

I’ve created Git Tags most often for Apply Hotfixes to a Past Release. The section below shows a common example that a hotfix is needed after releasing a software version (say with tag v1.0.1) to production.

How to create a branch off a tag

To create a “hot-fix” version based on v1.0.1, a common practice is to create a branch based on the release tag (“v1.0.1”), then apply bug fixes to that branch, then create a hot-fix tag based on the head of that hotfix branch.

create a branch off a tag

git checkout -b v1.0.1-hotfix-branch v1.0.1-tag

make changes to the local hotfix branch

git add 
git commit 

push the hostfix branch to the remote git repo

git push origin

For hotfix release, create a hotfix tag off this hotfix branch

git tag -a v1.0.1-hotfix-tag
git push origin v1.0.1-hotfix-tag

Clean up Git Tags

After you have cut many releases (which result in the release tags) or tested the CI/CD process (which results in the test tags), you may want to delete the git tags. The bash script shows how to delete unwanted git tags.

Delete a tag from local repo

git tag -d v1.0.1

apply the deletion at the remote repo

git push origin :refs/tags/v1.0.1

confirm that the tag has been removed

git tag