Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Objects, Refs and Internals

Tag objects

Reference for Git tag objects: the object, type, tag and tagger headers of an annotated tag, how it differs from a lightweight tag, and how to create one by hand.

Git has two kinds of tags. A lightweight tag is only a ref, a file under refs/tags/ that holds an object ID. An annotated tag is a real object in the database, with its own ID, a tagger, a date and a message; the ref under refs/tags/ then points at that tag object, and the tag object points at the thing being tagged.

Release tags are normally annotated, because they record who made the release and when, and they can carry a signature. A tag object can point at any kind of object, usually a commit, but also a tree, a blob or another tag.

Terminal
git tag -a v1.0 -m "Release 1.0"   # annotated
git tag v1.0-light                 # lightweight
git cat-file -p v1.0               # show the tag object

Try it

Bash Compare an annotated and a lightweight tag

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 Write a tag object by hand with git mktag

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.

Format

TEXT
object <object-id>
type <commit|tree|blob|tag>
tag <tag-name>
tagger Name <email> <unix-time> <zone>

<message>
<optional signature block>
Header Description
object The ID of the tagged object.
type The type of that object, so Git can check it without loading it.
tag The tag name without the refs/tags/ prefix.
tagger Who created the tag, with a time stamp in the same format as commit headers. Very old tags may lack it.

The message follows the first blank line. For a signed tag the signature is appended to the end of the message as an ASCII-armored PGP block, an SSH signature block, or an X.509 block (see Signed commits and tags). Unlike a commit, a tag has no gpgsig header: the signature is part of the message text.

Usage notes

  • The ref can disagree with the object. The name in the tag header and the ref name are separate. git fsck and git mktag check that they are well-formed, but a tag object does not have to match the ref that points at it.
  • Peeling. v1.0^{} follows tag objects until it reaches a non-tag object; v1.0^{commit} insists on a commit. See Peeling revisions.
  • Tag of a tag. A tag can point at another tag. Peeling goes through every level.
  • Lightweight tags have no metadata. There is no date or message to show, and git describe ignores them by default (use --tags).
  • Moving a tag. Because tags are refs, they can be moved with git tag -f, but published tags should be treated as permanent: anyone who fetched them keeps the old target, and Git does not overwrite an existing tag during fetch unless you force it.
  • Fetching. git fetch brings in tags that point at commits it downloads. --tags fetches all of them and --no-tags none.
  • git mktag validates its input. It rejects a missing field, a wrong type or an object that does not exist.