git tag
Create, list and delete tags
The 'git tag' command gives a fixed name to a commit, usually a release such as v1.0. Unlike a branch, a tag never moves. A lightweight tag is just a name; an annotated tag (-a) is a full object with the tagger, a date and a message, and is the recommended kind for releases. Tags are not pushed automatically: push them with git push origin <tag>.
Synopsis
git tag [-a | -s] [-f] [-m <msg>] <tagname> [<commit>]
git tag -d <tagname>...
git tag [-n[<num>]] -l [<pattern>...]Options
Choosing the Right Option
Lightweight vs annotated
Two kinds of tags
| Command | Stores | Use for |
|---|---|---|
git tag v1.0 | Only the name | Private bookmarks |
git tag -a v1.0 -m "..." | Tagger, date, message | Releases |
Tag vs branch
Both name a commit
| Command | Moves on commit? | Pushed by git push? |
|---|---|---|
Branch | Yes | Yes (the current branch) |
Tag | Never | No, push it explicitly |
Examples
Tag the current commit
git tag v1.0A lightweight tag named v1.0.
Annotated tag
git tag -a v1.0 -m "First release"A tag with tagger, date and message.
Push a tag
git push origin v1.0Share the tag on the remote.
List tags
git tag -l "v1.*"List tags matching a pattern.
Workflow Examples
git switch main && git pullBe on the latest main
git tag -a v1.0 -m "First release"Create the release tag
git push origin v1.0Share it
Troubleshooting
fatal: tag 'v1.0' already exists
Cause: The name is taken
Pick another name, or delete it first (git tag -d v1.0)
My tag is not on GitHub
Cause: git push does not send tags
git push origin v1.0, or git push --tags
A deleted tag comes back after fetch
Cause: It still exists on the remote
Also delete it there: git push origin --delete v1.0
Tips & Pitfalls
Best Practices
- ✓Use annotated tags for releases.
- ✓Follow semantic versioning (v1.2.3).
- ✓Never move or reuse a tag once it is published.
Common Mistakes
- ✗Expecting git push to send tags — push them explicitly or use --follow-tags.
- ✗Using lightweight tags for releases: they record no author, date or message.
- ✗Moving a tag that others already fetched.
FAQ
git switch --detach v1.0, or create a branch from it: git switch -c hotfix v1.0.
git push --tags (or git push --follow-tags for annotated tags on pushed commits).
It names a commit after the nearest tag, e.g. v1.0-3-g1a2b3c4.