Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Branches and Tags

git tag command

Reference for git tag: create lightweight and annotated tags, list and filter, delete, move, verify signatures, sort versions and push tags to a remote.

git tag gives a permanent, human-friendly name to a commit, usually a release such as v1.4.0. Unlike a branch, a tag does not move when you commit.

There are two kinds. A lightweight tag is just a ref pointing straight at a commit. An annotated tag (-a, -m or -s) is a real object with its own tagger, date, message and optional signature, and the ref points to that object. Use annotated tags for releases, because tools such as git describe ignore lightweight tags by default.

Terminal
git tag v1.0                      # lightweight
git tag -a v1.0 -m "Release 1.0"  # annotated
git tag -l 'v1.*'                 # list matching

Try it

Bash Lightweight and annotated tags

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Filter, sort, move and delete

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Sending tags to a remote

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
git tag [-a | -s | -u <key>] [-f] [-m <msg> | -F <file>] <tagname> [<commit>]
git tag [-l [<pattern>...]] [-n[<num>]] [--sort=<key>] [--contains <c>]
        [--points-at <obj>] [--merged <c>] [--no-merged <c>] [--format=<fmt>]
git tag -d <tagname>...
git tag -v <tagname>...
Name Description
<tagname> [<commit>] Create a lightweight tag at a commit (default HEAD).
-a, --annotate Create an annotated tag object (opens an editor unless -m is given).
-m, -F Tag message from a string or file; implies -a.
-s, -u <key> Create a signed tag with the default or a specific key.
-f, --force Replace an existing tag.
-d Delete tags locally.
-v Verify the signature of tags.
-l, --list List tags, optionally matching glob patterns.
-n[<num>] Show up to num lines of each tag message (default 1).
--sort=<key> Sort by refname, version:refname, creatordate and others (prefix - to reverse).
--contains, --points-at, --merged Filter by reachability.

Returns: a listing, or nothing on creation; deleting prints Deleted tag '<name>' (was <hash>).

Errors: an existing name fails with "tag '' already exists"; a missing target fails with "Failed to resolve ... as a valid ref".

Usage notes

  • Tags are not pushed automatically. Use git push origin <tag>, git push --tags (all, including lightweight) or git push --follow-tags (annotated tags that point into the pushed commits).
  • Fetch behavior: git fetch brings tags that point at fetched history; --tags brings all of them.
  • Moving tags is rude. Consumers who already fetched a tag keep the old one; change releases by creating a new tag instead.
  • Delete on the remote with git push origin --delete v1.0 (or :refs/tags/v1.0).
  • Default sort is alphabetical, so v1.10.0 appears before v1.2.0. Use --sort=version:refname, or set tag.sort.
  • Annotated tags carry authorship (git show <tag> prints the tagger and message), and can be signed and verified.
  • Tag names follow the same rules as branch names; a tag and a branch with the same name make git checkout name ambiguous.
  • Checking out a tag gives a detached HEAD; make a branch to commit on top (git switch -c hotfix v1.0).