Book Your Free Call

The Complete Guide On Git Tag

Tim Mouskhelichvili
Tim Mouskhelichvili
4 minutes to read

In Git, tags are used to create references to specific commits. Think of a tag as a checkpoint in your application development history. Typically, tags are used to mark release versions (for example, v1.0.1). Luckily, it is easy to create and manage tags because Git provides straightforward and easy-to-use commands.

To create a new tag in Git, use this command:

bashgit tag <tagname>

By the end of this article, you will know everything about tags in Git, how to create a tag, delete a tag, list all the tags, and many more.

Let’s get to it 😎.

git tag

What is a Git tag?

A tag is a pointer to a specific commit typically used to mark a release version or as a bookmark.

Unlike the branch, you cannot add more code to a tag. Tags always point to the same object.

By default, tags are created on the commit referenced by HEAD (the current commit).

How to create a tag?

In Git, you can create Lightweight or Annotated tags.

1. Create a lightweight tag

Lightweight tags only contain the commit checksum.

Use the below command to create a lightweight tag.

bashgit tag <tagname>

Since a lightweight tag only contains a reference to a specific commit, it can be seen as a bookmark or as a quick link.

2. Create an annotated tag

Annotated tags contain extra metadata like the name of the tagger, the email, and the date.

Like commits, annotated tags have a tagging message that you need to specify.

Use the below command to create an annotated tag.

bashgit tag -a <tagname> -m "tag message"

Additionally, annotated tags can be signed and verified by the GNU Privacy Guard (GPG).

lightweight vs annotated tag

When to use a lightweight vs an annotated tag?

For public releases, it is a best practice to use annotated tags.

For private releases, you can use lightweight tags.

How to view a tag's data?

To view a tag's data, you can use the git show command with the tag's name.

bashgit show <tagname>

For a lightweight tag, the command will output the referenced commit's data.

For an annotated tag, the command will output the tag's data AND the commit's data.

How to list all the tags?

To list all the stored tags, use the git tag command.

bash> git tag

Note: The tags will appear in alphabetical order.

List all the tags sorted by date.

To list all the stored tags and sort them by date, use this command.

bashgit for-each-ref --sort=creatordate --format '%(refname) %(creatordate)' refs/tags

Find a tag that contains specific characters.

To find a tag containing specific characters, use the git tag -l command with a wildcard expression.

bash> git tag -l "v2*"

How to tag an old commit?

git tag old commit

When you create a new tag by default, it references the current commit (HEAD).

However, you can choose to tag an older commit. For that, you first need to find the checksum of the commit that you want to reference.

Then, simply use this command:

bashgit tag -a <tagname> <checksum_commit>

How to replace an old tag?

If you attempt to create a tag with an existing tag name or tag an older commit with an existing tag, you will get an error (fatal: tag '<tagname>' already exists).

To retag or replace an old tag, you need to use the git tag command with the force option, like so:

bashgit tag -a -f <tagname> <checksum_commit>

How to checkout a tag?

To checkout a tag, use the git checkout command with the tag's name.

bashgit checkout <tagname>

Note: This will result in the HEAD being detached.

Note: Any changes made to the repository will not modify the tag but rather create a new detached commit.

How to push a tag to a remote?

To push a tag to a remote server, use the git push command with the tag's name.

bashgit push origin <tagname>

You can also push all your local tags using the git push --tags command.

bashgit push --tags

How to delete a tag?

To delete a git tag completely, you will need to remove it locally and remotely.

git tag delete

1. Delete a local tag

To delete a local tag, use the git tag -d command with the tag's name.

bashgit tag -d <tagname>

2. Delete a remote tag

To delete a remote tag, use this command:

bashgit push --delete origin <tagname>

Final thoughts

Tags are a great way to create a checkpoint of your repository code to mark release versions or bookmarks.

Luckily, Git offers all the necessary tools to create and manage tags easily.

Even though lightweight tags exist, I always recommend using annotated tags because they offer better visibility with their metadata information.

Comments (0)