Git Tags

Git tags are permanent labels that point to a specific commit, usually to mark release versions like v1.0.0. Unlike branches, tags do not move when you make new commits, so v1.0.0 always means exactly the same code.

Creating Tags

Annotated tags store the tagger, date and a message, and can be signed. Use annotated tags for releases; lightweight tags are like private bookmarks.

git tag v0.1.0                                   # lightweight tag
git tag -a v1.0.0 -m "First public release"      # annotated tag
git tag -a v0.9.0 4d5e6f7 -m "Beta"              # tag an older commit
(no output)

Listing and Inspecting Tags

git tag
git tag -l "v1.*"
git show v1.0.0 --stat
v0.1.0
v0.9.0
v1.0.0

tag v1.0.0
Tagger: Naeem Amin <you@example.com>
Date:   Sat Oct 31 11:20:00 2026 +0500

First public release

commit 9e1f3b7...

Pushing Tags

git push does not send tags by default. Push them explicitly.

git push origin v1.0.0       # one tag
git push --tags              # all tags
git push --follow-tags       # commits plus annotated tags
To github.com:you/portfolio.git
 * [new tag]         v1.0.0 -> v1.0.0

Deleting Tags

git tag -d v0.1.0
git push origin --delete v0.1.0
Deleted tag 'v0.1.0' (was a1b2c3d)
To github.com:you/portfolio.git
 - [deleted]         v0.1.0

Semantic Versioning

  • MAJOR — incompatible changes (v2.0.0)
  • MINOR — new backward-compatible features (v1.3.0)
  • PATCH — backward-compatible bug fixes (v1.3.2)
  • Pre-releases use suffixes: v2.0.0-beta.1
  • On GitHub and GitLab, a tag can become a Release with notes and downloadable files.

Checking Out a Tag

git switch --detach v1.0.0 lets you look at the code of a release. You are in "detached HEAD" state, not on a branch. To make fixes, create a branch from the tag: git switch -c hotfix/1.0.1 v1.0.0.

Frequently asked questions

What is the difference between a lightweight and an annotated tag?

A lightweight tag is just a name for a commit. An annotated tag is a full Git object with tagger, date and message, and is recommended for releases.

Why are my tags not on GitHub?

git push does not include tags by default. Run git push origin <tag> or git push --tags.

What is the difference between a tag and a branch?

A branch moves forward with every new commit. A tag stays fixed on one commit forever, making it ideal for marking releases.