This guide will cover everything that you need to know about git tags. However, if you are simply interested in learning how to get started with using git tags, I recommend skipping down to the Git Tags in Action section. Otherwise, simply continue reading in order.

OK, let’s get to it.

What Are Git Tags

A git tag is a marker for a specific point in time for your repository. Well, although I say a "specific point in time", they are really just a reference to a commit. These tags are stored as files inside of the refs folder within the .git folder that is a part of every git repository.

Why Use Git Tags

There are many reasons you may want to use git tags. Here are a few.

1. Rolling Back

Have you ever found yourself in a situation where you want to roll back to a specific state of your repository or application?

Without tags, you would have to do some detective work and set off on and endless search through your commit history until you finally find that one specific commit you need. It’s also possible that in a sufficiently large repository with many team members commiting code on a regular basis, you may not even be able to even find that specific commit you are searching for. In such a case, having a git tag really comes in handy.

2. Release Management

Have you ever noticed how popular open source packages have version numbers? This is necessary for a number of reasons.

  • New package versions sometimes make "breaking changes" that will literally break existing code that depends on an older version of that package.
  • Packages often depend on other packages. It’s very common that certain versions of packages only work with specific versions of those other packages.

In order to create such versioned releases in your own applications, you can use git tags.

Types of Tags

Git has two different types of tags: lightweight tags and annotated tags.

Lightweight Tags

A lightweight tag is just a reference to a commit and nothing more. No other data about the tag is stored. It’s simple and it works.

Annotated Tags

An annotated tag is basically the same as a lightweight tag with some additional metadata about the tag. Because of this metadata, these tags are stored as full git objects. The metadata that theannotated tags store is essentially the same data that is stored when someone makes a commit.

This metadata consists of:

  • The name of the person who created the tag
  • The email of the person who created the tag
  • A timestamp from tag creation.
  • A message about the tag.

Speaking from experience, annotated tags are way more useful than lightweight tags. The case where I use them the most is for release versioning. When creating a versioned release using git tags, it’s always better to have more information about when the release was created along with a nice message about the changes included in that release.

And in general, I think it’s always useful to have more information rather than less, since you never know when you’ll need it.

Long story short, use annotated tags.

How Do Git Tags Work?

As I mentioned before, tags are nothing more than references to a commit. They are stored as files inside of the refs folder inside of the .git folder in the root of your repository. Or in the case of annotated tags, as full git objects.

To prove to you that there is no magic, let’s take a look at the refs folder inside of the .git folder and see what’s going on.


1
2
cd .git/refs/tags
ls

You should now see a list of all your tags (for the purposes of this example assume i already created these tags)


1
mytag  v1.0.0

Now, let’s try opening up one of these tag files.

For example:


1
vim v1.0.0

You should see something like the follow:


1
cn75192m4dzz31fcf154zs4hds4e6a78zz950124

That’s it. The file is nothing more than a commit hash. Simple and easy to understand — no magic.

Naming Git Tags

Valid names for git tags are the same as the valid names for any git ref. The naming conventions that need to be followed for naming git tags or any other ref can be found here .

All of the rules are pretty straight forward, so you shouldn’t have any issues.

There is also a really nifty trick for checking if your tag name is valid. To check if a tag name is valid, use the following command:


1
git check-ref-format "tags/<some-tag>" && echo "Valid tag" || echo "Invalid tag"

This nice one liner will print out "Valid tag" is your tag name is valid, or "Invalid tag" if it is not valid. Wonderful!

I want to thank the stack overflow user Willem Van Onsem for sharing this awesome snippet in his answer to this stackoverflow post.

Git Tags in Action

Let’s put everything together and go over some practical examples involving a very common git tags workflow. This workflow will consist of creating a tag, checking it’s details, pushing the tag to a remote repository, and optionally, deleting the tag.

First, let’s checkout the branch that we want to use. For simplicity, let’s use the master branch.


1
cd master

Ok, we are now on the master branch. Let’s create a commit.


1
git commit -m "An amazing code change."

Perfect, now we have our commit and we are ready to create a tag. Let’s create a tag called v1.0.0 that will represent the first version of our application.

1
git tag v1.0.0 -m "V1.0.0 for the world's greatest application"

OK, we should have a tag now. Let’s make sure that our tag has been created by taking a look at the list of all of our tags.

1
git tag


1
v1.0.0

Perfect, our tag was in fact created.

Now let’s take a look at the details for that tag to make sure it’s pointing to the correct commit.

1
git show v1.0.0


1
2
3
4
5
6
7
8
9
10
11
tag v1.0.0
Tagger: Alan <myemail@myemail.com>
Date:   Tue Jun 30 15:53:44 2020 -0500

V1.0.0 for the world's greatest application

commit 815514ac041c5076e80ef0dce57ba7dbff9e28bf (HEAD -> master, tag: v1.0.0)
Author: Alan <myemail@myemail.com>
Date:   Tue Jun 30 15:51:14 2020 -0400

    An amazing code change.

Perfect! As you can see, our new tag is pointing to the commit that we made earlier.

Having this tag locally is fine, but it would be really nice to push this tag to our remote repository.

Let’s do that with the following command:


1
git push origin tag v1.0.0

1
2
3
4
5
6
7
Counting objects: 2, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (2/2), 337 bytes | 168.00 KiB/s, done.
Total 2 (delta 0), reused 0 (delta 0)
To github.com:my-amazing-user/my-repo.git
 * [new tag]         v1.0.0 -> v1.0.0

Awesome, our tag was pushed to our remote repository.

But wait! 3 months down the line, say, for whatever reason, you don’t think you need this tag anymore. OK, let’s delete it.


1
 git tag -d v1.0.0

1
Deleted tag 'v1.0.0' (was 80d94b5)

Now the tag is deleted from the local repository. Let’s confirm that the tag was in fact deleted.


1
git tag

Awesome, that is exactly what we want. We deleted our only tag, so when we type “git tag”, there is no output. Perfect!

Let’s say we also want to delete it from the remote repository. We can do that too.


1
git push --delete origin v1.0.0

1
2
To github.com:my-awesome-user/my-repo.git
 - [deleted]         v1.0.0

And now we have completely cleaned up our tag.

That about covers it. Now you should have no problems creating, managing, and deleting your git tags.

Common Git Tag Commands

For your convenience, here is a quick list of common git tag commands. Enjoy.

How To List All Tags

1
git tag
How To View the Details of A Specific Tag

1
git show <my_tag_name>
How To Delete a tag locally

1
git tag -d mytag
How To Delete A Tag From A Remote Repository

1
git push --delete origin v1.0
How To Push A Single Tag To A Remote Repository

1
git push origin tag <my_tag_name>
How To Push All Tags To A Remote Repository

1
git push --tags

That’s all

If you enjoyed this, maybe you’ll enjoy some of my other git content.

For example, check out my guide on how How To Delete All Local Git Branches.

Or perhaps you may enjoy my article on How To Search Git Commit History.

Have a great day!