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
- CI/CD YAML Generator
Tags can trigger release pipelines — generate one that builds on tag push.
- .gitignore Generator
Keep build artifacts out of your tagged releases.
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 Resources
Related Cheatsheets
- Git Cheatsheet
tag, tag -a, tag -l, and tag push commands.
Practice git tag
4 exercises
Look up unfamiliar terms
A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.
Build real projects
Apply what you learned by building guided projects with starter code and solutions.
Decode error messages
Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.