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.

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
# 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 mainAn annotated tag object on disk looks like this, and git show prints it before the commit:
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
| Property | Lightweight tag | Annotated tag | Signed tag |
|---|---|---|---|
| Object type | commit | tag | tag |
| Stores tagger, date, message | No | Yes | Yes |
git describe uses it by default | No | Yes | Yes |
Carried by push --follow-tags | No | Yes | Yes |
| Verifiable origin | No | Only the object hash | Yes, cryptographically |
Created without -a/-s | Yes | No | No |
| Cost | One ref | One ref plus a small object | Tag object plus signature |
| Tag name | Meaning | Sort position with v:refname |
|---|---|---|
v1.9.0 | Release | Before v1.10.0 (numeric, not string, compare) |
v2.0.0-rc.1 | Pre-release | After v2.0.0-rc.0, before v2.0.0 |
v2.0.0 | Release | Last within the 2.0.0 group |
v2.0.0+build.5 | Build metadata, same precedence as v2.0.0 | Ignored by SemVer precedence |
release-2026-11 | Calendar tag, not SemVer | Sorts lexically unless you exclude it |
Practical Edge Cases and Deep Dives
1. git describe ignoring your tags
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 toogit 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
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.0v: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:
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.0Build 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
git tag -f v2.1.0 8b7e6d5 # local tag now points elsewhere
git push --force origin refs/tags/v2.1.0Anyone 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
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/releasegit 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
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 firstChecking 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
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 1Two 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
| Symptom | Cause | Fix |
|---|---|---|
fatal: No annotated tags can describe | Only lightweight tags exist | git describe --tags, or re-tag with -a |
v1.10.0 sorts before v1.9.0 | Default refname sort is lexicographic | --sort=v:refname |
v2.0.0-rc.1 sorts after v2.0.0 | Pre-release suffix not configured | versionsort.suffix=-rc |
| Tag push rejected as already exists | Tag exists on the remote at another commit | --force deliberately, or publish a new version |
| Teammate still sees the old tag | Tag refs update only with force | git fetch --tags --force |
dst refspec matches more than one | Branch and tag share a name | Push refs/tags/... explicitly |
| Release tag points at the wrong commit | Tag created before the merge landed | git tag -d plus re-tag from the release commit |
git describe says -dirty in CI | Build artifacts modified the tree | Clean before tagging, or use --always |
| Signed tag fails verification elsewhere | Public key missing, or different keyring | Import the signer's key, pin it in CI |
Try matching browser tools
All toolsSmall utilities that fit Git work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Git guides
All Git guidesGit config: Aliases, rerere, and Credential Helpers
Five config scopes decide one value at a time. Aliases are user-level shorthand, rerere records conflict resolutions, and credential helpers choose where your secret lives.
Git Hooks: pre-commit, commit-msg, and Husky Automation
Hooks live in .git/hooks, which a clone never receives, so core.hooksPath and Husky are how they travel. Exit codes abort the operation, and every hook is bypassable.
Git bisect: Binary Search, Automated Scripts, and Bug Hunting
Mark one bad and one good commit and Git halves the range each step. bisect run automates it through exit codes, and monotonicity is the assumption that must hold.
Git ignore: Patterns, Negation, and Untracking Cached Files
Patterns are relative and last match wins, but a negation cannot revive a file inside an excluded directory. Ignore rules never touch tracked files: rm --cached first.
More in Git
All Git guidesThe guides filed next to this one in Git, in library order.