Terminal Guidegit tag Command Guide
Create, list, delete or verify a tag object signed with GPG
Dai Aoki
CEO at init, Inc. / CTO at US & JP startups / Creator of WebTerm
Quick Reference
Create
git tag <name>Lightweight taggit tag -a <name> -m "msg"Annotated taggit tag <name> <commit>Tag specific commitList/Show
git tagList all tagsgit tag -l "v1.*"Filter tagsgit show <tag>Show tag detailsRemote
git push origin <tag>Push single taggit push --tagsPush all tagsgit push origin --delete <tag>Delete remote tagDownloadable Image Preview
Basic Usage
The git tag command creates, lists, and deletes tags. Tags mark specific points in history, typically used for releases.
# Create a lightweight tag
git tag v1.0.0
# Create an annotated tag (recommended)
git tag -a v1.0.0 -m "Release version 1.0.0"
# List all tags
git tagAnnotated vs Lightweight Tags
Annotated (-a)
- • Stores tagger name, email, date
- • Has a tagging message
- • Can be GPG signed
- • Recommended for releases
Lightweight
- • Just a pointer to commit
- • No extra metadata
- • Cannot be signed
- • Good for temporary markers
# Annotated tag (full metadata)
git tag -a v1.0.0 -m "First stable release"
# View annotated tag info
git show v1.0.0
# Shows: tagger, date, message, and commit
# Lightweight tag (just a pointer)
git tag v1.0.0-light
# View lightweight tag
git show v1.0.0-light
# Shows: only the commit infoListing and Filtering Tags
# List all tags
git tag
# List with pattern matching
git tag -l "v1.*"
git tag -l "release-*"
# Sort by version (semantic versioning)
git tag -l --sort=-version:refname
# Show tag with commit info
git tag -n
git tag -n1 # Show first line of message
# Find which tag contains a commit
git tag --contains abc1234Pushing Tags to Remote
Tags are not pushed automatically. You must explicitly push them:
# Push a single tag
git push origin v1.0.0
# Push all tags
git push --tags
# Push only annotated tags (recommended)
git push --follow-tags
# Fetch tags from remote
git fetch --tagsgit push --tags as it pushes ALL local tags. Prefer pushing specific tags or use --follow-tags.Deleting Tags
# Delete local tag
git tag -d v1.0.0
# Delete remote tag
git push origin --delete v1.0.0
git push origin :refs/tags/v1.0.0 # Alternative syntax
# Delete and recreate (move tag)
git tag -d v1.0.0
git tag v1.0.0 <new-commit>
git push origin -f v1.0.0Practical Examples
# Release workflow
git checkout main
git pull
git tag -a v2.0.0 -m "Version 2.0.0 - New features"
git push origin v2.0.0
# Tag a past commit
git log --oneline
git tag -a v0.9.0 abc1234 -m "Tagging old release"
# Checkout a specific tag
git checkout v1.0.0
# Note: This puts you in detached HEAD state
# Create branch from tag
git checkout -b hotfix-v1 v1.0.0
# Compare tags
git diff v1.0.0 v2.0.0
git log v1.0.0..v2.0.0 --oneline
# GPG signed tag
git tag -s v1.0.0 -m "Signed release"
git tag -v v1.0.0 # Verify signature| Option | Description |
|---|---|
| -a | Create annotated tag |
| -m <msg> | Tag message |
| -d | Delete tag |
| -l <pattern> | List tags matching pattern |
| -s | Create GPG-signed tag |
Frequently Asked Questions
What is the difference between annotated and lightweight tags?
Annotated tags (-a) store metadata like tagger name, date, and message. Lightweight tags are just pointers to commits. Use annotated tags for releases.
How do I tag a past commit?
Use "git tag <tagname> <commit-hash>" to tag any commit. Find the commit hash with git log first.
Why don't my tags appear on the remote?
Tags are not pushed by default. Use "git push origin <tagname>" or "git push --tags" to push tags to the remote.
How do I rename a tag?
Git doesn't support renaming tags directly. Create a new tag pointing to the same commit, then delete the old tag.
Summary
git tag marks important points in your repository history. Use annotated tags for releases and remember to push tags explicitly.
Quick Reference
git tag -a v1.0 -m "msg"- Annotated taggit tag -l "v1.*"- List matching tagsgit push origin <tag>- Push taggit tag -d <tag>- Delete local tag
Official Documentation
For authoritative information, refer to the official documentation: