Marking Milestones

Commits are identified by SHA-1 hashes (e.g., a1b2c3d), which are great for computers but terrible for humans. When you reach a significant point in your development—like a release—you want to give it a permanent, meaningful name like v1.0.0. This is what Tags are for.

Types of Tags

Git supports two types of tags: Lightweight and Annotated.

Lightweight Tags

A lightweight tag is very much like a branch that doesn’t change. It’s just a pointer to a specific commit. It contains no extra information—no author, no date, no message. It is simply a bookmark.

git tag v1.0-beta

Annotated Tags

Annotated tags are stored as full objects in the Git database. They are checksummed; contain the tagger name, email, and date; have a tagging message; and can be signed and verified with GNU Privacy Guard (GPG).

You should generally use annotated tags for all public releases. This preserves the information of who created the release and when, independently of the commit it points to.

git tag -a v1.0.0 -m "Release version 1.0.0"

Semantic Versioning

While Git allows any string as a tag, the industry standard is Semantic Versioning (SemVer). A version number looks like MAJOR.MINOR.PATCH.

• MAJOR: Incompatible API changes. Increment this when you make breaking changes.
• MINOR: Backward-compatible functionality. Increment this when you add functionality in a backward-compatible manner.
• PATCH: Backward-compatible bug fixes. Increment this when you make backward-compatible bug fixes.

Example: v2.14.3 indicates Major version 2, Minor version 14, Patch 3. Pre-release versions can be denoted with a hyphen, e.g., v1.0.0-alpha.1.

Managing Tags

Listing Tags

Listing tags is straightforward, but in a large project, you might have hundreds.

git tag

You can search for tags with patterns using the -l or --list option:

git tag -l "v1.8*"

Sorting Tags

By default, Git sorts tags lexicographically. However, this can be confusing because v1.10 comes before v1.2. To sort by version number properly:

git tag --sort=version:refname

Sharing Tags

By default, git push does not transfer tags to remote servers. You must explicitly push tags.

To push a single tag:

git push origin v1.0.0

To push all tags that are not yet on the remote:

git push origin --tags

Deleting Tags

To delete a tag locally:

git tag -d v1.0.0

To delete it from the remote:

git push origin --delete v1.0.0

Checking Out Tags

You can checkout a tag to put your repository in “detached HEAD” state at that version. This is useful for building old versions or debugging regressions.

git checkout v1.0.0

Note: You cannot commit changes directly to a tag. You must create a branch from it first.

Signing Tags

For high-security projects, it is critical to prove that a release was actually created by the maintainer and not a malicious actor.

git tag -s v1.5.0 -m "Signed release"

This requires GPG to be set up. Users can verify the signature with:

git tag -v v1.5.0

If the signature is valid and the key is trusted, Git will report a “Good signature”.

# Create some history
git init
git commit --allow-empty -m "Initial"
git commit --allow-empty -m "Feature Complete"

# Create an annotated tag
git tag -a v1.0 -m "First Release"

# Show the tag details
git show v1.0

tag v1.0
Tagger: ...

First Release
...

# You have created several tags locally. Push ALL of them to origin.
git push origin --tags

# You have created several tags locally. Push ALL of them to origin.
git push origin