Git Tagging: Lightweight vs Annotated Tags & Semantic Versioning (SemVer)

Branches in Git are moving targets that advance with every new commit. But when you deploy software to production (e.g. v1.0.0), you need a permanent, immutable bookmark anchored to that exact release snapshot. That is the purpose of Git Tags.

Lightweight vs Annotated Tags

Git supports two types of tags:

Creating Tags in Terminal

1. Creating an Annotated Tag (Recommended)

# Create annotated release tag with a message:
$ git tag -a v1.0.0 -m "Release version 1.0.0: Initial production release with auth & payments"

2. Creating a Lightweight Tag

# Simple lightweight tag (no -a or -m flag):
$ git tag v1.0.0-beta

3. Tagging an Older Historical Commit

You can tag any commit from the past by passing its commit hash:

$ git tag -a v0.9.0 9a1b2c4 -m "Tagged beta release candidate"

Listing and Inspecting Tags

# List all tags in alphabetical order:
$ git tag

# Search tags matching a pattern:
$ git tag -l "v1.8.*"

# Inspect tag metadata, author, and commit details:
$ git show v1.0.0

Pushing Tags to GitHub

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

# Push a single specific tag to GitHub:
$ git push origin v1.0.0

# Push ALL local tags to GitHub simultaneously:
$ git push origin --tags

Pushing a tag to GitHub automatically creates an entry under the repository's Releases tab, allowing users to download source code .zip and .tar.gz archives!

Understanding Semantic Versioning (SemVer)

The global software engineering standard for tag naming is Semantic Versioning (MAJOR.MINOR.PATCH):

• MAJOR (v2.0.0): Incompatible API changes, breaking architectural modifications.
• MINOR (v1.1.0): Backwards-compatible new features and enhancements.
• PATCH (v1.0.1): Backwards-compatible bug fixes and security patches.

# Delete a tag locally:
$ git tag -d v1.0.0

# Delete a tag on the remote GitHub repository:
$ git push origin --delete v1.0.0