Using Git Tags: A Practical Guide

Tags in Git are references that point to specific points in your repository’s history. They’re commonly used to mark release points (v1.0, v2.0, etc.) and provide a way to bookmark important commits. Unlike branches, tags don’t change once created — they’re fixed pointers to a specific commit.

Types of Tags

Git supports two types of tags:

Lightweight tags are simply a pointer to a commit. They’re quick to create but contain no additional information.

Annotated tags are stored as full objects in the Git database. They contain the tagger’s name, email, date, and a tagging message. They can also be signed and verified with GPG. For releases and any tags you want to share, annotated tags are recommended.

Creating Tags

Creating a Lightweight Tag

To create a lightweight tag on the current commit:

git tag v1.0.0

Creating an Annotated Tag

To create an annotated tag with a message:

git tag -a v1.0.0 -m "Release version 1.0.0"

The -a flag specifies an annotated tag, and -m provides the tag message. If you omit -m, Git will open your editor for you to write a message.

Tagging a Specific Commit

If you need to tag a commit that isn’t the current HEAD, specify the commit hash:

git tag -a v1.0.0 -m "Release version 1.0.0" 9fceb02

You can find commit hashes using git log --oneline.

Listing Tags

To list all tags in your repository:

git tag

To filter tags by pattern:

git tag -l "v1.*"

To see tag details along with commit information:

git tag -n

For more detailed information about a specific tag:

git show v1.0.0

Pushing Tags to Remote

By default, git push doesn’t transfer tags to remote servers. You need to explicitly push them.

Push a Single Tag

git push origin v1.0.0

Push All Tags

To push all your local tags at once:

git push origin --tags

If you only want to push annotated tags (not lightweight tags):

git push origin --follow-tags

Deleting Tags

Sometimes you need to remove a tag — perhaps you tagged the wrong commit or made a typo in the tag name.

Delete a Local Tag

To delete a tag from your local repository:

git tag -d v1.0.0

The -d flag stands for delete. You’ll see output confirming the deletion:

Deleted tag 'v1.0.0' (was 9fceb02)

Delete a Remote Tag

Deleting locally doesn’t affect the remote. To delete a tag from the remote repository:

git push origin --delete v1.0.0

Alternatively, you can use the older syntax:

git push origin :refs/tags/v1.0.0

Both commands achieve the same result. The first is more readable; the second pushes an empty reference to the remote tag, effectively deleting it.

Delete Both Local and Remote

To completely remove a tag, run both commands:

git tag -d v1.0.0
git push origin --delete v1.0.0

Checking Out Tags

To view the code at a specific tag, you can check it out:

git checkout v1.0.0

This puts you in a “detached HEAD” state — you’re not on any branch. If you want to make changes based on a tag, create a new branch:

git checkout -b release-1.0-hotfix v1.0.0

Renaming a Tag

Git doesn’t have a direct rename command for tags. Instead, you create a new tag pointing to the same commit, then delete the old one:

# Create new tag pointing to the same commit as old tag
git tag new-tag old-tag

# Delete old tag locally
git tag -d old-tag

# Delete old tag from remote
git push origin --delete old-tag

# Push new tag to remote
git push origin new-tag

Comparing Tags

To see what changed between two tags:

git diff v1.0.0 v2.0.0

To see the commits between two tags:

git log v1.0.0..v2.0.0

Fetching Remote Tags

To fetch all tags from a remote:

git fetch --tags

If remote tags have been deleted and you want to sync your local tags:

git fetch --prune --prune-tags

Best Practices

1. Use annotated tags for releases — they contain metadata that helps with tracking who created the tag and when.

2. Follow semantic versioning — use a consistent naming scheme like v1.0.0, v1.0.1, v1.1.0 to make versions meaningful.

3. Write meaningful tag messages — document what’s included in the release.

4. Don’t move tags after pushing — if a tag has been pushed to a shared remote, treat it as immutable. Create a new tag instead.

5. Use lightweight tags for temporary or private markers — they’re perfect for bookmarking commits during development.

Summary

Git tags are a simple but powerful feature for marking important points in your project’s history. The key commands to remember:

With these commands in your toolkit, you’ll be able to effectively manage releases and important milestones in your Git repositories.