git tag

Lightweight versus annotated tags, listing, and local deletion, checked on Git 2.39.5, without signing or remote push.

コマンドページの本文は現在英語です。

A lightweight tag is a name that points at a commit. An annotated tag, created with -a and a message, is a tag object with a tagger and a date, and that object then points at the commit. git cat-file -t reports commit for the lightweight name and tag for the annotated one.

This page does not create signed tags, use a private key, or push tags to a remote. Deleting a tag with -d only removes the local name. Examples were checked on Git 2.39.5 in isolated temporary repositories.

Examples were checked against Git 2.39.5. See the official documentation for the complete command.

Git command catalog → · Git tutorial overview →

Lightweight versus annotated tags

git tag v1.0.0 creates a lightweight tag at HEAD. git tag -a v1.1.0 -m "Release 1.1.0" creates an annotated tag. git tag -l lists both names.

git show --no-patch on the lightweight tag prints the commit. The same command on the annotated tag prints the tag object first (tagger, date, and message) and then the commit. That is also how you inspect a tag from the git show page, without signing or pushing anything.

git tag, git tag -a -m, git cat-file -t

git tag <tagname>
git tag -a <tagname> -m <message>
git tag -l
git cat-file -t <tagname>

Create a lightweight or annotated tag at HEAD, list tags, and report the object type.

ParameterDescription
<tagname>The tag name. Lightweight tags store no separate message.
-a / --annotateCreate an annotated tag object. Combine it with -m, or Git will open an editor for the message.
-m <message>The annotation stored on the tag object.

Returns: A new tag ref. For -a, a tag object is also written and the ref points at that object.

  • Signed tags (-s, -u) are not covered here and are not created in the example. They would require a signing key.
bash
git init -b main >/dev/null
git config user.name "Practice Author"
git config user.email "[email protected]"
git config commit.gpgsign false
git config color.ui false
mkdir -p .disabled-hooks
git config core.hooksPath ".disabled-hooks"
printf 'base\n' > file.txt
git add file.txt
git commit -m "Add file" >/dev/null
git tag v1.0.0
git tag -a v1.1.0 -m "Release 1.1.0"
echo "list"
git tag -l
echo "v1.0.0-type=$(git cat-file -t v1.0.0)"
echo "v1.1.0-type=$(git cat-file -t v1.1.0)"
echo "show-light"
git show --no-patch --pretty=format:%h%x20%s v1.0.0
echo
echo "show-annot"
git show --no-patch --pretty=medium v1.1.0

Expected output

list
v1.0.0
v1.1.0
v1.0.0-type=commit
v1.1.0-type=tag
show-light
8bb07df Add file
show-annot
tag v1.1.0
Tagger: Practice Author <[email protected]>
Date:   Mon Jan 15 12:00:00 2024 +0000

Release 1.1.0

commit 8bb07df53f0f824d66b045c6ee66dab277c9350d
Author: Practice Author <[email protected]>
Date:   Mon Jan 15 12:00:00 2024 +0000

    Add file

Related: git show

Official documentation →

Point a tag at a commit and delete it locally

git tag v0.9 <commit> names an earlier commit. In the example v0.9 points at the first commit, while v1.0.0 points at HEAD. git tag -d removes a local tag name. Deleting the lightweight v1.0.0 prints the commit SHA it pointed at; deleting the annotated v1.1.0 prints the tag object SHA, which is not the same as the commit.

Deletion here is local only. A tag that was already pushed stays on the remote until a separate remote delete, which this page does not run. Do not force-move a published tag as a casual rewrite.

git tag <name> <commit>, git tag -d

git tag <tagname> <commit>
git tag -d <tagname>

Create a tag at a chosen commit and delete a local tag name.

ParameterDescription
<commit>The object to tag, when you do not want HEAD. The example tags HEAD~1 as v0.9.
-d / --deleteDelete the local tag ref. This does not update a remote.

Returns: A new tag name, or a removed local tag plus the short SHA Git reports for the deleted object.

  • v0.9 remains after the other two names are deleted, still pointing at the first commit.
bash
git init -b main >/dev/null
git config user.name "Practice Author"
git config user.email "[email protected]"
git config commit.gpgsign false
git config color.ui false
mkdir -p .disabled-hooks
git config core.hooksPath ".disabled-hooks"
printf 'base\n' > file.txt
git add file.txt
git commit -m "Add file" >/dev/null
printf 'two\n' > file.txt
git add file.txt
GIT_AUTHOR_DATE='2024-01-15T13:00:00+0000' GIT_COMMITTER_DATE='2024-01-15T13:00:00+0000' git commit -m "Edit file" >/dev/null
first=$(git rev-parse --short HEAD~1)
git tag v0.9 $first
git tag v1.0.0
git tag -a v1.1.0 -m "Release 1.1.0"
echo "before"
git tag -l
echo "v0.9=$(git rev-parse --short v0.9)"
echo "v1.0.0=$(git rev-parse --short v1.0.0)"
echo "delete"
git tag -d v1.0.0
echo "del-light-exit=$?"
git tag -d v1.1.0
echo "del-annot-exit=$?"
echo "after"
git tag -l

Expected output

before
v0.9
v1.0.0
v1.1.0
v0.9=8bb07df
v1.0.0=544b831
delete
Deleted tag 'v1.0.0' (was 544b831)
del-light-exit=0
Deleted tag 'v1.1.0' (was 431a2dd)
del-annot-exit=0
after
v0.9

Official documentation →