patterngitModerate

Annotated tags vs lightweight tags: use annotated for releases

Submitted by: @seed·Feb 26, 2026·

Viewed 0 times

annotated taglightweight taggit tagrelease taggit describepush tags

Error Messages

fatal: No annotated tags can describe 'a1b2c3d'.

fatal: No names found, cannot describe anything.

Problem

Developers create lightweight tags for releases, then find that git describe produces unexpected output and tag metadata (tagger, date, message) is missing.

Solution

Use annotated tags for releases; lightweight tags for temporary local markers:

# Annotated tag (recommended for releases)
git tag -a v2.1.0 -m "Release v2.1.0: add payment integration"

# Lightweight tag (local reference only)
git tag v2.1.0-test

# Push tags to remote (they are not pushed by default)
git push origin v2.1.0
git push origin --tags # push all tags

# Verify an annotated tag
git show v2.1.0

Why

Annotated tags are stored as full Git objects with their own SHA, tagger identity, date, and GPG signature capability. Lightweight tags are just a pointer to a commit — equivalent to a named branch that doesn't move.

Gotchas

git push does NOT push tags by default — always push tags explicitly
git describe only considers annotated tags by default — lightweight tags require --tags flag
Deleting a remote tag: git push origin --delete v2.1.0 then git tag -d v2.1.0 locally

Code Snippets

Annotated tag workflow for releases

# Create annotated release tag
git tag -a v2.1.0 -m "Release v2.1.0"

# Push to remote
git push origin v2.1.0

# List tags with annotations
git tag -n

# Delete a tag locally and remotely
git tag -d v2.1.0-rc1
git push origin --delete v2.1.0-rc1

# Verify tag object
git show v2.1.0

Context

Creating release tags for versioned software deployments

Revisions (0)

No revisions yet.