Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Git Tags: Lightweight vs Annotated and SemVer Release Tags

An annotated tag stores the tagger, date, and message; describe and --follow-tags only use those. How v:refname sorting and versionsort.suffix fix pre-release order.

~4 min readGit
#Git#Tags#Release#SemVer
3D illustration of a commit timeline with a plain tag plate and a sealed annotated tag block

Quick Summary

A Git tag is a ref under refs/tags/ that never moves on its own. There are two shapes: a lightweight tag is a ref pointing straight at a commit, and an annotated tag is a ref pointing at a tag object that stores the tagger name, email, timestamp, message, and optionally a signature. Signed tags (git tag -s) are annotated tags whose object carries a GPG or SSH signature.

The difference matters less at creation time and more at consumption. git describe only uses annotated tags unless told otherwise, git push --follow-tags only carries annotated tags, and an annotated tag survives a repository that later re-points branches because it records who declared the release and when. A lightweight tag records only "this commit was called v1.2.0".

Semantic versioning is a contract on top of tag names: MAJOR.MINOR.PATCH, with -prerelease and +build suffixes. Git does not enforce it, but git tag --sort=v:refname and versionsort.suffix are what make tag lists and CI release notes come out in the order humans expect.

Basic Syntax and Core Signatures

bash
# List and inspect git tag # all tags git tag -l "v1.*" # glob filter git tag --sort=-v:refname # newest version first git tag -n5 # first 5 lines of each annotation git show v2.1.0 # tag object, then the commit git cat-file -t v2.1.0 # "tag" (annotated) or "commit" (lightweight) git ls-remote --tags origin # what the server actually has # Create git tag v2.1.0 # lightweight, at HEAD git tag v2.1.0 9c1e2f4 # lightweight, at a commit git tag -a v3.0.0 -m "3.0.0: drop Node 18" # annotated git tag -a v3.0.0 9c1e2f4 -m "3.0.0" # annotated at a commit git tag -s v3.0.0 -m "3.0.0" # signed (GPG) git tag -s v3.0.0 -m "3.0.0" --format=ssh # signed with an SSH key # Verify, move, delete git tag -v v3.0.0 # verify signature git verify-tag v3.0.0 git tag -f v2.1.0 # move an existing tag (rewrites the ref) git tag -d v2.1.0 # local delete git push origin --delete tag v2.1.0 # Describe and publish git describe --tags --always --dirty git describe --tags --match "v*" --exact-match git push origin v2.1.0 git push --follow-tags origin main

An annotated tag object on disk looks like this, and git show prints it before the commit:

text
object 9c1e2f4a1b7c3d9e0f2a4b6c8d0e1f3a5b7c9d1e type commit tag v3.0.0 tagger Ryu <dev@example.com> 1763260000 +0900 3.0.0: drop Node 18 -----BEGIN PGP SIGNATURE----- ...

Key Comparison Table

PropertyLightweight tagAnnotated tagSigned tag
Object typecommittagtag
Stores tagger, date, messageNoYesYes
git describe uses it by defaultNoYesYes
Carried by push --follow-tagsNoYesYes
Verifiable originNoOnly the object hashYes, cryptographically
Created without -a/-sYesNoNo
CostOne refOne ref plus a small objectTag object plus signature
Tag nameMeaningSort position with v:refname
v1.9.0ReleaseBefore v1.10.0 (numeric, not string, compare)
v2.0.0-rc.1Pre-releaseAfter v2.0.0-rc.0, before v2.0.0
v2.0.0ReleaseLast within the 2.0.0 group
v2.0.0+build.5Build metadata, same precedence as v2.0.0Ignored by SemVer precedence
release-2026-11Calendar tag, not SemVerSorts lexically unless you exclude it

Practical Edge Cases and Deep Dives

1. git describe ignoring your tags

bash
git tag v1.0.0 9c1e2f4 # lightweight git describe # fatal: No annotated tags can describe '3f2a1b9' # hint: try --tags git describe --tags # now works, finds the nearest lightweight tag too

git describe walks first-parent ancestry looking for an annotated tag and prints v1.0.0-4-g3f2a1b9 (four commits past the tag, at abbreviated hash 3f2a1b9). CI version strings generated this way silently fail on legacy repositories that only have lightweight tags, which is the usual reason a VERSION in a build says fatal: No names found. Fix the tags, not the build script: git tag -a on the release commits.

2. Version-aware sorting and pre-releases

bash
git tag --sort=-v:refname # v2.0.0 # v2.0.0-rc.2 <- sorts AFTER v2.0.0 by default # v2.0.0-rc.1 # v1.10.0

v:refname compares numerically rather than as strings, which fixes v1.10.0 vs v1.9.0, but SemVer says a pre-release sorts before its release while plain string order puts -rc.1 after the empty suffix. Git exposes versionsort.suffix for exactly this:

bash
git config --global versionsort.suffix -alpha git config --global versionsort.suffix -beta git config --global versionsort.suffix -rc git tag --sort=v:refname # v2.0.0-rc.1 < v2.0.0

Build metadata (+sha.abc123) is ignored in precedence by SemVer, so v2.0.0+build.1 and v2.0.0+build.2 are the same version; do not encode an increment there and expect ordering.

3. Moving or re-creating a published tag

bash
git tag -f v2.1.0 8b7e6d5 # local tag now points elsewhere git push --force origin refs/tags/v2.1.0

Anyone who already fetched keeps the old ref, and a plain git fetch will not update it, because ref updates to tags are refused without force. Teammates need git fetch --tags --force (or delete and refetch) to see the move. This is why release tags are conventionally immutable: a moved tag makes two identical version strings mean different code, and package managers, container builders, and legal audits all rely on that being false. If the release was wrong, publish v2.1.1 and deprecate v2.1.0.

4. Branch and tag sharing a name

bash
git tag release git branch release git push origin release # error: dst refspec release matches more than one git push origin refs/heads/release git push origin refs/tags/release

git checkout release prefers the branch but warns, git log release shows an ambiguity warning, and git push origin release fails outright. Deleting is equally ambiguous: git push origin :refs/tags/release vs :refs/heads/release. Namespacing release tags (v1.2.3) makes a collision impossible, which is most of why the v prefix exists.

5. Working from a tag means detached HEAD

bash
git switch --detach v2.1.0 # or: git checkout v2.1.0 # HEAD is now at 9c1e2f4 3.0.0: drop Node 18 git switch -c hotfix/2.1.1 # keep work by branching first

Checking out a tag or a tag's commit detaches HEAD; commits made there belong to no branch and are invisible in git branch. Tags themselves are not on any branch, so git push from a detached HEAD has no upstream and refuses to guess. For a patch release from a tag, branch immediately, commit, then git tag -a v2.1.1 on the new commit.

6. Automating release tags in CI

bash
VERSION=$(node -p "require('./package.json').version") git tag -a "v$VERSION" -m "v$VERSION" git push origin "refs/tags/v$VERSION" # Verify a tag before deploying it git fetch --tags origin git verify-tag "v$VERSION" || exit 1 git rev-list -n1 "v$VERSION" | grep -qx "$GITHUB_SHA" || exit 1

Two checks are worth having in a release pipeline: the signature verifies (verify-tag, with the signer's public key pinned in CI), and the tag's commit is the artifact's commit (rev-list -n1 v… equals GITHUB_SHA). Without the second check, a tag pushed at the wrong moment deploys the previous commit under the new version number — a failure mode that is invisible until someone compares git describe against the built binary.

Common Git Operation Mistakes

SymptomCauseFix
fatal: No annotated tags can describeOnly lightweight tags existgit describe --tags, or re-tag with -a
v1.10.0 sorts before v1.9.0Default refname sort is lexicographic--sort=v:refname
v2.0.0-rc.1 sorts after v2.0.0Pre-release suffix not configuredversionsort.suffix=-rc
Tag push rejected as already existsTag exists on the remote at another commit--force deliberately, or publish a new version
Teammate still sees the old tagTag refs update only with forcegit fetch --tags --force
dst refspec matches more than oneBranch and tag share a namePush refs/tags/... explicitly
Release tag points at the wrong commitTag created before the merge landedgit tag -d plus re-tag from the release commit
git describe says -dirty in CIBuild artifacts modified the treeClean before tagging, or use --always
Signed tag fails verification elsewherePublic key missing, or different keyringImport the signer's key, pin it in CI

Try matching browser tools

All tools

Small utilities that fit Git work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Git guides

More in Git

All Git guides

The guides filed next to this one in Git, in library order.