Git Tags: Immutable Milestones for Release History

Why it exists

Software releases need fixed coordinates in history. A branch head moves forward with every merge, so pointing a release script at main is nondeterministic. Git tags solve this by creating a permanent, human-readable name that resolves to exactly one commit hash forever. They give teams a shared vocabulary to talk about specific moments in time, such as the exact state of code that went to production on Tuesday.

The mental model

Think of a tag as a commemorative plaque bolted to a specific brick in a wall. The wall keeps growing, but the plaque stays on its original brick. A lightweight tag is like writing the brick's coordinates on a sticky note: cheap, local, and easy to lose. An annotated tag is like a bronze plaque with a date, the installer's signature, and a description cast into the metal: heavier, official, and verifiable.

How it works

Git stores annotated tags as full objects in its database. Each contains an object ID, the target commit hash, the tagger's name and email, a timestamp, an optional message, and an optional GPG signature. Because they are objects, annotated tags can be transferred between repositories with full fidelity during git fetch and git push. Lightweight tags are merely refs that point directly to a commit, similar to branch pointers, but they do not move. You create an annotated tag with git tag -a v1.0 -m message and a lightweight tag with git tag v1.0. Listing tags with git tag shows both types alphabetically, and you can filter patterns with git tag -l v1.8.5 followed by an asterisk.

When to use it

Use annotated tags for every release candidate, versioned deploy, or artifact that leaves the team. The embedded metadata and optional GPG signing let downstream systems and future maintainers verify who created the mark and when. Use lightweight tags only for quick local bookmarks or temporary pointers during private experiments that will never reach a remote.

When not to use it

Do not use lightweight tags as triggers for production CI/CD pipelines. Because they lack tagger identity, timestamps, and signatures, they provide no audit trail and can be silently recreated to point to a different commit without leaving evidence. Do not treat tags as mutable: while Git allows force-updating a tag reference, doing so breaks the social contract of immutability and confuses anyone who already fetched the old version.

One canonical example

The Git project itself maintains over 500 tags. When the maintainers released the 1.8.5 series, they created tags such as v1.8.5, v1.8.5-rc0 through v1.8.5-rc3, and patch releases v1.8.5.1 through v1.8.5.5. A developer wanting to inspect that exact line of history runs git tag -l v1.8.5 followed by an asterisk to list them, then git checkout v1.8.5.2 to land on the precise commit, confident that the tag has not drifted since it was signed.