What is an Annotated Tag in Git?

Table of Contents

introduction

Git users who are aware of some of the internals of Git understand that Git has 3 core object types stored in the object database – blobs, trees, and commits.

In this article, we’ll discuss Git’s fourth object, the Annotated tag.

A Git tag is a type of ref (like a branch name), which is basically just a label that points to a specific commit. Tags are created using the git tag command.

Git has 2 main types of tags – light tags and annotated tags. When you create any of the tag types, a ref for that tag is created and stored in the .git/refs/tags folder. The ref is just a file with the tag name that contains the commit ID the tag is attached to.

If both light tags and annotated tags create a ref in .git/refs/tags A folder containing the commit ID that the tag points to, what’s the difference between them?

Well, the difference is that it’s all there is to lightweight Git tags. On the other hand, annotated tags store an additional message – or Annotation – In addition to the actual tag name.

Because annotated tags actually store user-generated content other than the tag name, Git actually formats it into an object, stores it, and stores it in the object database.

Create a lightweight tag in Git

You are probably familiar with creating easy tags in Git. Lightweight tags are the default type of tag created when you run a git tag like:

$ git tag v1.0

As mentioned, this just creates a new ref tag file here: .git/refs/tags/v1.0.

Feel free to check it out and open the newly created ref file v1.0 seeing that it only contains the commit ID it refers to.

Create an annotated tag in Git

Annotated tags are created by adding the -a Flag for the git tag command:

$ git tag v2.0 -a

This will name the tag v2.0 (just like a lightweight tag), but in addition Git will open the default text editor so you can enter the comment message, similar to how it works for commit messages without -m flag. So for this tag you can enter something like This is version 2.0.

If you want to specify the commented tag message directly on the command line, you can use -m Mark just like you do for a commit message:

$ git tag v3.0 -m "This is version 3.0"

Note that using -m The flag implies that it will be an annotated tag, so you should not include the -a flag In this case.

Annotated tag message list

You can register an annotated tag message using the git tag command along with the tags name and -n flag:

$ git tag v3.0 -n
v3.0            This is version 3.0

An annotated tag in the object database

As mentioned earlier, since commented tags contain a custom message that cannot be stored as a ref filename, Git will actually create a new object for each tag in the Git repository.

This means that any commented tag content is hashed, compressed, and stored in the object database like any other Git object. To get the SHA-1 hash value of the commented tag itself, you can use the git rev-parse command along with the tag name:

$ git rev-parse v3.0
bd0bf094154490236f7fb7d4d48c105151631fa1

We can verify that this is a tag object using the git cat-file command along with the -t flag:

$ git cat-file -t bd0bf094154490236f7fb7d4d48c105151631fa1
tag

Furthermore, we can see the actual tag storage format and content using git cat-file again but with the -p flag:

$ git cat-file -p bd0bf094154490236f7fb7d4d48c105151631fa1
object 051ef0038ca3d8273bb6750ccf07c624821f9c4d
type commit
tag v3.0
tagger Jacob Stopak <jacob@initialcommit.io> 1664374520 -0700

This is version 3.0

It shows that annotated tags store the following information:

1. The object ID of the commit to which the tag points (in this case 051ef0038ca3d8273bb6750ccf07c624821f9c4d)
2. The type of object to which the tag points, in this case commit
3. The tag name, in this case v3.0
4. The tagging – meaning the user who created the tag and the tagging time
5. The comment message itself, in this case This is version 3.0

Summary

In this article, we have provided a detailed overview of annotated tags in Git. We explained that tags are just labels associated with specific commitments. We also saw that annotated tags differ from light tags by a custom message that is received and stored as a full object in the buffer.

We learned how to create annotated tags and list them along with their messages. Finally, we popped the hood and saw the actual format and structure of an annotated tag as stored in a Git repository.

next steps

If you’re interested in learning more about how Git works under the hood, check out our Baby Git guide for developers, which dives into the Git code in an accessible way. We wrote it for developers who are curious to learn how Git works at the code level. To that end, we’ve documented the first version of Git’s code and discussed it in detail.

We hope you enjoyed this post! Feel free to email me at jacob@initialcommit.io with any questions or comments.