Git Tag Explained: Create, Push and Delete Release Tags
A git tag is a permanent name for one commit, usually a release such as v1.0.0. Learn annotated vs lightweight tags, how to list, push and delete them, why git push skips tags by default, and how git describe builds version strings, with output from a tested repository.
- A git tag is a fixed name for a commit. Unlike a branch, it does not move when you add commits.
- Use annotated tags (
git tag -a v1.0.0 -m "...") for releases. They store the tagger, date and message. git pushdoes not send tags. Usegit push origin v1.0.0,--tags, or--follow-tags.- Deleting is two steps:
git tag -dlocally andgit push origin --deleteon the remote.
When a bug report says “broken since version 1.1”, you need to know exactly which code shipped as 1.1. Commit hashes like b1c0a8b are precise but meaningless to humans. A git tag gives that commit a name you can type, share and build from. CI pipelines often trigger releases when a tag is pushed, and package managers read versions from tags.
We tested every command in a throwaway repository with a local bare remote, using Git 2.56 and a demo identity. Hashes shown come from that repository.
What is a git tag?
A tag is a reference that points at a commit and stays there. A branch is a moving pointer that advances with every new commit; a tag is a bookmark. Tags live under refs/tags/, just as branches live under refs/heads/. New to these ideas? Our Git tutorial for beginners explains commits and branches first.
Annotated vs lightweight tags
Git has two kinds of tag, and the difference is real. We created one of each on the same commit, then asked Git what each name points to:
git tag v1.0.0-light
git tag -a v1.0.0 -m "Release 1.0.0"
git cat-file -t v1.0.0-light # commit
git cat-file -t v1.0.0 # tag
A lightweight tag is just a name pointing straight at a commit. An annotated tag is a full object in the Git database, with its own author, date and message, and it points at the commit.
| Lightweight | Annotated | |
|---|---|---|
| Command | git tag NAME |
git tag -a NAME -m MSG |
| Stores tagger and date | No | Yes |
| Message | No | Yes |
| Can be signed | No | Yes, with -s |
Used by git describe by default |
No | Yes |
Pushed by --follow-tags |
No | Yes |
| Best for | Private, temporary markers | Releases |
The Git book recommends annotated tags for anything you share, and the last two rows show why: several tools ignore lightweight tags by default.
Creating tags
After two more commits we tagged a second release:
git commit -qam "Fix typo"
git commit -qam "Add export"
git tag -a v1.1.0 -m "Release 1.1.0"
Without -m, Git opens your editor for the message. Tag names cannot be reused. Trying again gave:
git tag -a v1.0.0 -m x
fatal: tag 'v1.0.0' already exists
Use -f to force a move only on tags nobody has pulled yet. Moving a published tag confuses everyone who already fetched the old one.
Listing and sorting tags
git tag -l
v1.0.0
v1.0.0-light
v1.1.0
git tag -l "v1.1*"
v1.1.0
git tag -n
v1.0.0 Release 1.0.0
v1.0.0-light First release
v1.1.0 Release 1.1.0
-n shows the first line of each annotation. For a lightweight tag, Git shows the commit message instead. Plain listing sorts alphabetically, so v1.10.0 would appear before v1.2.0. Sort by version instead:
git tag -l --sort=-v:refname
v1.1.0
v1.0.0-light
v1.0.0
Notice v1.0.0-light sorted above v1.0.0. Version sort treats the suffix as part of a later version. If you use pre-release names such as v2.0.0-rc1, set versionsort.suffix so they sort before the final release.
Inspecting a tag
git show v1.0.0 --no-patch
tag v1.0.0
Tagger: Demo <demo@example.com>
Date: Mon Nov 16 10:00:00 2026
Release 1.0.0
The tag header is followed by the commit it points to. For the lightweight tag, git show goes straight to the commit, because there is no tag object to show.
Pushing tags to a remote
This is the step most people miss. We pushed the branch, then listed the remote’s tags:
git push origin main
git ls-remote --tags origin
(no output)
Nothing. git push sends branches, not tags. You have three options:
git push origin v1.1.0pushes one tag. Safest.git push origin --tagspushes all local tags, including stray experiments.git push --follow-tagspushes the branch plus annotated tags on the pushed commits.
git push --follow-tags origin main
git ls-remote --tags origin
refs/tags/v1.0.0
refs/tags/v1.0.0^{}
refs/tags/v1.1.0
refs/tags/v1.1.0^{}
--follow-tags sent both annotated tags and skipped v1.0.0-light. The ^{} lines are the commits that the annotated tag objects point to. To make it the default, run git config push.followTags true.
Deleting tags
We pushed the lightweight tag by name, then removed it in both places:
git tag -d v1.0.0-light
Deleted tag 'v1.0.0-light' (was b4c82db)
git push origin --delete v1.0.0-light
After that, git ls-remote listed only the two annotated tags again. Local and remote tags are separate, so deleting one does not delete the other. The older syntax git push origin :refs/tags/NAME does the same thing. Teammates who already fetched the tag keep their copy until they run git fetch --prune --prune-tags.
Tagging an older commit
Forgot to tag a release? Pass the commit as an argument:
git tag -a v0.9.0 HEAD~2 -m "Backfilled"
Any commit reference works: a hash, HEAD~2 or a branch name. To find which tags contain a given commit, useful when checking whether a fix shipped, use git tag --contains COMMIT. In our repo, git tag --contains HEAD~1 returned only v1.1.0.
git describe: versions from tags
git describe names a commit relative to the nearest annotated tag, which makes a handy build version:
git describe
v1.1.0
git describe HEAD~1
v1.0.0-1-ga68e163
On a tagged commit you get the tag alone. Otherwise you get the tag, the number of commits since it (1), and g plus the short hash (a68e163). Add --tags to consider lightweight tags too, and --dirty to flag uncommitted changes. Many build tools embed this string in version output so testers can tell exactly which build they have.
Checking out a tag
git checkout v1.0.0
git status
HEAD detached at v1.0.0
You get a detached HEAD, because a tag cannot move to follow new commits. That is fine for building or testing an old release. To make a hotfix, create a branch from the tag: git switch -c hotfix-1.0.1 v1.0.0. For more on recovering work, see our guides on reset vs revert and git bisect, which pairs nicely with tags to find the release that introduced a bug.
Best practices
- Use annotated tags for every release, and follow semantic versioning such as
v2.3.1. - Pick one style for the prefix, with or without
v, and stick to it. - Never move or reuse a published tag. Make a new version instead.
- Push tags one at a time, or enable
push.followTags. - Sign release tags with
git tag -sif your project verifies releases. - Trigger CI release jobs on tag pushes, as described in our GitHub Actions guide.
Common git tag errors and fixes
Pushing a tag that already exists on the remote
We deleted v1.1.0 locally, recreated it on a different commit and tried to push:
git push origin v1.1.0
! [rejected] v1.1.0 -> v1.1.0 (already exists)
hint: Updates were rejected because the tag already exists in the remote.
Git protects published tags. This is a feature: if a tag could silently move, two people could build “v1.1.0” from different code. The right fix is almost always a new version number. Forcing with git push --force origin v1.1.0 works but leaves everyone who already fetched the old tag out of sync.
Missing tags after a clone or pull
git clone fetches tags, and git pull fetches tags that point into the history it downloads. Tags on other branches or added later may be missing. Run git fetch --tags to get them all. In our repo, after deleting the bad local tag, git fetch origin --tags brought v1.1.0 back from the remote, pointing at the right commit.
A tag and a branch with the same name
If you create a branch called v1.0.0, commands such as git checkout v1.0.0 become ambiguous and Git warns about it. Use full names such as refs/tags/v1.0.0 to be explicit, and keep version numbers for tags only.
Tags in CI pipelines
Many pipelines publish a release when a tag matching v* is pushed. Shallow CI checkouts often fetch no tags, so git describe fails with “No names found”. Fetch full history or tags in the checkout step before building version strings.
Final thoughts
A git tag is a small feature with big value: it turns a hash into a release name everyone understands. Create annotated tags with git tag -a, remember that tags need their own push, delete them in both places, and use git describe for build versions. With those habits, “which version has this bug?” becomes a question you can answer in seconds.
FAQ
What is the difference between a git tag and a branch?
A branch moves forward with each new commit. A tag stays fixed on one commit, which makes it ideal for marking releases.
Why are my git tags not on GitHub?
Git push does not send tags by default. Push them with git push origin and the tag name, or use the tags or follow-tags options.
Should I use annotated or lightweight tags?
Use annotated tags for releases because they store the tagger, date and message and work with git describe and follow-tags. Lightweight tags suit private markers.
How do I delete a remote git tag?
Run git push origin with the delete option and the tag name. Also delete your local copy with git tag and the d option.
Can I move a git tag to another commit?
Yes, with the force option, but avoid it for published tags. Others keep the old tag, so create a new version tag instead.
Keep learning
Need help with testing, WordPress or SEO?
We help teams ship better software and grow their sites. Tell us what you are working on and we will suggest a clear next step.