Git Tag

A tag is a named pointer to a specific commit in the history. Unlike branches, tags do not move — they permanently mark a specific moment in the project's history. Tags are most commonly used to mark software release versions.

Real-life analogy: A branch is like a bookmark that moves as new pages are added to a book. A tag is like a permanent stamp on a specific page — "Version 1.0 released on this date." The stamp never moves.

Types of Tags

1. Lightweight Tags

A lightweight tag is simply a pointer to a specific commit — like a branch that never moves. It has no extra information attached.

git tag v1.0

2. Annotated Tags (Recommended)

Annotated tags store extra information: the tagger's name, email, date, and a message. They are proper Git objects stored in the database and can be verified and signed.

git tag -a v1.0 -m "Release version 1.0 - Initial public release"

For releases and version tracking, always use annotated tags.

Creating Tags

Tag the Most Recent Commit

# Annotated tag
git tag -a v1.0.0 -m "Version 1.0.0 - First stable release"

# Lightweight tag
git tag v1.0.0

Tag a Specific Past Commit

First, find the commit hash:

git log --oneline
# a3f92b1 Fix login bug
# b7c3d45 Add user dashboard
# c1a2b3c Initial release

Then tag a specific commit by its hash:

git tag -a v0.9.0 b7c3d45 -m "Version 0.9.0 - Beta release"

Listing Tags

git tag

Output:

v0.9.0
v1.0.0
v1.1.0
v2.0.0

List Tags with a Filter

git tag -l "v1.*"

Output:

v1.0.0
v1.1.0

Viewing Tag Details

git show v1.0.0

For an annotated tag, the output shows the tagger info, the tag message, and the commit it points to:

tag v1.0.0
Tagger: Ravi Kumar <ravi@example.com>
Date:   Mon Oct 9 14:32:10 2023

Version 1.0.0 - First stable release

commit a3f92b1c...
Author: Ravi Kumar <ravi@example.com>
...

Pushing Tags to GitHub

By default, git push does NOT push tags. They must be pushed explicitly:

Push a Single Tag

git push origin v1.0.0

Push All Tags

git push origin --tags

Once a tag is pushed to GitHub, it appears under the "Releases" and "Tags" sections of the repository.

Deleting Tags

Delete a Local Tag

git tag -d v1.0.0

Delete a Remote Tag

git push origin --delete v1.0.0

Checking Out a Tag

The project can be viewed as it was at the time of a specific release:

git checkout v1.0.0

This puts Git into "Detached HEAD" state — the code is in read-only mode at that tag's state. To make changes from this point, create a new branch:

git switch -c hotfix-from-v1.0

Semantic Versioning (SemVer)

Tags typically follow semantic versioning, which uses the format MAJOR.MINOR.PATCH:

GitHub Releases

GitHub has a "Releases" feature that builds on top of Git tags. When creating a release on GitHub:

1. Go to the repository on GitHub
2. Click Releases in the right sidebar
3. Click "Draft a new release"
4. Choose an existing tag or create a new one
5. Write release notes describing what is new
6. Optionally attach downloadable files (binaries, archives)
7. Click "Publish release"

Summary

Tags mark specific points in commit history, typically for software releases. Annotated tags (git tag -a) are preferred as they store metadata. Tags do not move after creation. They must be pushed to GitHub separately with git push origin --tags. Use semantic versioning (v1.0.0, v2.1.3) to make version numbers meaningful.