git tag

Branching & Merging

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>...]
[ ] optional| or<arg> placeholder... repeatable--flag option

Options

Click any option to expand

Beginner (3)

Create an annotated tag object with tagger, date and message.

RecommendedReleases should record who tagged, when and why

Example

git tag -a v1.0 -m "First release"

List tags, optionally only those matching a pattern.

RecommendedFilter a long tag list with a pattern

Example

git tag -l "v1.*"

Delete the given local tags.

When neededFix a wrong local tag; avoid deleting tags others use

Example

git tag -d v1.0

Intermediate (1)

Replace an existing tag, moving it to another commit.

Not recommendedMoving a published tag confuses everyone who fetched it

Example

git tag -f v1.0

Choosing the Right Option

Lightweight vs annotated

Two kinds of tags

CommandStoresUse for
git tag v1.0Only the namePrivate bookmarks
git tag -a v1.0 -m "..."Tagger, date, messageReleases

Tag vs branch

Both name a commit

CommandMoves on commit?Pushed by git push?
BranchYesYes (the current branch)
TagNeverNo, push it explicitly

Examples

Tag the current commit

git tag v1.0

A 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.0

Share the tag on the remote.


List tags

git tag -l "v1.*"

List tags matching a pattern.

Workflow Examples

1
git switch main && git pull

Be on the latest main

2
git tag -a v1.0 -m "First release"

Create the release tag

3
git push origin v1.0

Share 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

A:

git switch --detach v1.0, or create a branch from it: git switch -c hotfix v1.0.

A:

git push --tags (or git push --follow-tags for annotated tags on pushed commits).

A:

It names a commit after the nearest tag, e.g. v1.0-3-g1a2b3c4.