Skip to content

git tag

Marking releases with git tag — lightweight and annotated tags for version management.

What you'll learn

  • How to create lightweight and annotated tags
  • Why annotated tags are preferred for releases
  • Listing, pushing, and deleting tags
  • Semantic versioning conventions for tags

Concept

What git tag Does

git tag marks a specific commit with a named pointer. Tags are commonly used to mark release versions — v1.0.0, v1.1.0, v2.0.0 — so you can easily find and checkout a specific release.

git tag v1.0.0

Unlike branches, tags do not move. They point to one commit forever, making them perfect for marking significant points in history like releases.

Lightweight vs Annotated Tags

There are two types of tags:

Lightweight Tags

git tag v1.0.0

A lightweight tag is just a named pointer to a commit — like a bookmark. It stores no metadata (no author, date, or message).

Annotated Tags

git tag -a v1.0.0 -m "Release 1.0.0: initial public release"

An annotated tag is a full Git object with:

  • A tag message
  • The tagger's name and email
  • A timestamp
  • A pointer to the commit

Always use annotated tags for releases. They store metadata and can be signed with GPG for verification.

Creating Tags

# Lightweight tag on the current commit
git tag v1.0.0

# Annotated tag on the current commit
git tag -a v1.0.0 -m "Initial release"

# Tag a specific commit (not the current one)
git tag -a v1.0.0 -m "Initial release" abc1234

# Signed tag (requires GPG key setup)
git tag -s v1.0.0 -m "Signed release"

Listing and Viewing Tags

git tag                    # list all tags
git tag -l "v1.*"          # list tags matching a pattern
git tag -l --sort=-v:refname  # sort by version (newest first)

git show v1.0.0            # see the tag details and the commit it points to

Pushing Tags

Tags are NOT pushed by default with git push. You must push them explicitly:

git push origin v1.0.0     # push a specific tag
git push origin --tags     # push all tags
git push --follow-tags     # push commits and any annotated tags

To always push annotated tags with commits:

git config --global push.followTags true

Deleting Tags

git tag -d v1.0.0              # delete a local tag
git push origin --delete v1.0.0  # delete a remote tag

Semantic Versioning

Tags typically follow Semantic Versioning (SemVer): MAJOR.MINOR.PATCH

  • MAJOR — incompatible API changes (1.0.0 → 2.0.0)
  • MINOR — new features, backward-compatible (1.0.0 → 1.1.0)
  • PATCH — bug fixes, backward-compatible (1.0.0 → 1.0.1)
git tag -a v1.0.0 -m "Initial release"
git tag -a v1.0.1 -m "Fix login bug"
git tag -a v1.1.0 -m "Add search feature"
git tag -a v2.0.0 -m "Breaking: new API design"

Pre-release versions use a hyphen: v2.0.0-beta.1, v2.0.0-rc.1.

Checking Out a Tag

To view the code at a specific release:

git checkout v1.0.0
# You are now in detached HEAD at the v1.0.0 release

# To make changes from a tag, create a branch:
git checkout -b hotfix-1.0.1 v1.0.0

GitHub Releases

On GitHub, tags can be turned into Releases — a web page with release notes, downloadable assets, and a tag. You can create releases via the GitHub website or CLI:

gh release create v1.0.0 --title "Release 1.0.0" --notes "Initial release"
gh release create v1.0.0 --generate-notes  # auto-generate from PRs

Releases are the public face of your tags — they are what users see on your GitHub repo's "Releases" page.

Example

              # --- Create an annotated tag for a release ---
git tag -a v1.0.0 -m "Initial public release"
git tag -a v1.0.1 -m "Fix: resolve crash on empty cart"
git tag -a v1.1.0 -m "Feature: add dark mode"
git tag -a v2.0.0 -m "Breaking: redesign API"

# --- List and inspect tags ---
git tag
# v1.0.0
# v1.0.1
# v1.1.0
# v2.0.0

git tag -l "v1.*"        # list only v1.x tags
git show v1.0.0          # see tag details + commit

# --- Push tags to remote ---
git push origin v1.0.0           # push one tag
git push origin --tags           # push all tags

# --- Tag a specific past commit ---
git log --oneline
# abc1234 feat: initial commit
git tag -a v0.1.0 -m "Pre-release" abc1234

# --- Checkout a release ---
git checkout v1.0.0
# (detached HEAD — just looking)
git checkout main  # go back

# --- Create a hotfix branch from a tag ---
git checkout -b hotfix-1.0.2 v1.0.1

# --- Delete a tag ---
git tag -d v0.1.0                  # delete locally
git push origin --delete v0.1.0    # delete on remote

# --- Create a GitHub release ---
gh release create v1.1.0 --title "v1.1.0 - Dark Mode" --notes "Adds dark mode toggle and theme persistence."

# --- Configure to always push annotated tags ---
git config --global push.followTags true
            

Shows creating annotated tags with messages, listing and filtering tags, pushing tags to remote, tagging a past commit, checking out a release, creating a hotfix branch from a tag, deleting tags, creating a GitHub release, and configuring automatic tag pushing. Annotated tags with SemVer are the professional standard.

Try it

Common mistakes

The mistake

Creating a lightweight tag instead of an annotated tag for a release

The fix

Lightweight tags store no metadata (no message, author, or date). For releases, always use annotated tags: git tag -a v1.0.0 -m 'Release message'. Annotated tags can be signed with GPG, store release information, and are the recommended practice for version marking.

The mistake

Forgetting to push tags — they are not pushed with git push

The fix

git push only pushes commits and branches, not tags. After creating a tag, run git push origin <tag> or git push origin --tags to push it to the remote. Set git config --global push.followTags true to push annotated tags automatically with commits.

Related Cheatsheets

Practice git tag

4 exercises

Practice git tag

Look up unfamiliar terms

A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.

View glossary

Build real projects

Apply what you learned by building guided projects with starter code and solutions.

View projects

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors