Git Tag

Tagging is a feature used to keep track of specific points in a Git repository’s history.

Over time, when you’re working with a Git repository, you’ll make a large number of changes to your codebase. In Git, commits are used to keep track of individual changes.

However, if you want to capture a point in the history of your repository such as a version, then you’ll want to use the Git tagging feature.

This tutorial will discuss, with examples, the basics of tagging and how to use the git tag command to work with tags in a Git repository. By the end of reading this tutorial, you’ll be an expert at working with tags in Git.

Git Tagging

Tags are references (refs) which point to a specific part of a Git repository’s history.

Tags are generally used by developers to capture a specific point in the history of a repo to create a version release. For instance, when a developer is ready to launch a new version of a project, they may create a tag for the project.

In essence, tags are branches that do not change. After you create a tag, there will be no more commits added to the history of the tag. Instead, the tag will store a snapshot of how the repository appeared when the tag was added.

There are two different types of tags supported in Git. These are:

• Annotated tags. These are tags that are stored as full objects in the Git database.
• Lightweight tags. These are tags that are a name and a pointer to a commit.

Now we’ve discussed the basics of Git tagging, explore how you can work with tags in Git.

Create a Tag

Before you can start working with tags in Git, you need to create a tag. The syntax for creating a tag in Git is as follows:

git tag <name>

The “name” parameter refers to the name of the tag you want to create. Because tagging is usually used to track versions of a project, you may want to use a name like “v1.2” or “beta-v0.9” for a tag.

The tag you create will be applied to the current commit you are on in your repository.

Annotated Tags

An annotated tag is a tag which stores a full object in the Git database. When you create an annotated tag, metadata such as the name of the person who created the tag, their email, and the date on which the tag was created will be stored.

In addition, annotated tags are stored with a message for the tag. Generally speaking, annotated tags are preferred over lightweight tags because the metadata stored by annotated tags can have a number of uses down the line.

For instance, if you want to track who has been responsible for versioning over time, you’ll need access to the metadata stored by an annotated tag.

Here’s the syntax for creating an annotated tag in Git:

git tag -a <name>

The -a flag is used to tell Git to create an annotated tag. The “name” parameter is the name of the tag we want to create.

After we run this command, the system-default text editor will open and ask us to insert a message for our annotated tag. This happens because, as we discussed earlier, annotated tags are stored with a message.

Alternatively, you can specify the message with which a tag will be created directly. You can do so using this code:

git tag -a <name> -m <message>

The -m tag is used to add a message to an annotated tag. Suppose we wanted to create a tag called v1.9 with the message “version 1.9”. We could do so using this code:

git tag -a v1.9 -m "version 1.9"

When we run this command, a tag called v1.9 will be created with the accompanying message “version 1.9”.

Running this command is more convenient than using git tag without a message, because this way allows us to specify a commit message directly, without having to type one into the default text editor which appears when you don’t specify a commit message.

Lightweight Tags

To create a lightweight tag, you should use the standard git tag syntax we discussed earlier. Suppose you want to create a lightweight tag called “v1.9.1”. You could do so using this code:

git tag v1.9.1

This command will create a lightweight tag called v1.9.1. When you create a lightweight tag, you do not need to specify a tag message. Instead, a new tag checksum will be created and stored in the project’s .git folder.

List a Project’s Tags

When you’re working on a large project, you may have a number of tagged versions of your repository. To retrieve a list of tags stored with a project, you can use the following command:

git tag

This command returns a list of tags. Here’s an example output from this command:

v1.9.1
v1.9.0
v1.8.11
v1.8.10
v1.8.9
...

In addition, the -l flag can be used to filter out the tags used with a project. For instance, if you want to retrieve a list of every tag that starts with “v1.8”, you could use this code:

"Career Karma entered my life when I needed it most and quickly helped me match with a bootcamp. Two months after graduating, I found my dream job that aligned with my values and goals in life!"

Venus, Software Engineer at Rockbot

Find Your Bootcamp Match

git tag -l v1.8*

In our command, we have specified an -l flag, followed by “v1.8*”. This instructs Git to retrieve a list of all tags that start with v1.8. The asterisk (*) denotes that the tags to be returned can include any characters after “v1.8”.

Here’s an example output from this command:

v1.8.11
v1.8.10
v1.8.9
v1.8.8
...

As you can see, all the tags returned start with “v1.8”.

Checkout a Tag

The git checkout command can be used to view the state of a repository in a commit with a specific tag. For instance, suppose you wanted to view your repository when it was in v1.1. You could do so using this code:

git checkout v1.1

This command moves the repository into a “detached HEAD” state, which means any changes you make will not update the tagged version of the repo. Instead, a new detached commit will be created which will not be associated with any branch.

After we run this command, we are able to see how our codebase appeared in the commit which was tagged v1.1.

Tag an Old Commit

In our previous examples, we have discussed how to use the git tag function to add a tag to the current version of git with which you are working. This is because, by default, git tag will create a tag for the HEAD commit (the commit you are currently viewing).

However, you can also tag an old commit using the git tag command. You can do so by specifying the reference of a specific commit to which you want to add a tag.

Suppose you want to add a tag to the last commit in your repository. To do so, you’ll first need to run git log. This will allow you to retrieve a list of recent commits. Here’s an example of the git log command in action (with the –pretty=oneline flag, which makes it easy for us to see our commits):

git log --pretty=oneline

Our command returns:

8cd29ae5d04abbdbd856d2c2f55f2b82133903e8 Push new logging feature
2911aae73ed1dd372bcdf8f520b174c3817c818b Initialize logging feature
9646aa785211f3069ce01177da98e23b7890d859 Fix issue #342

Now, suppose we wanted to add a tag to our “Fix issue #342” commit. We want this tag to be called “v1.3”. We could add this tag using the following code:

git tag -a v1.3 9646aa785211f3069ce01177da98e23b7890d859

This command adds the tag 1.3 to the commit we referenced in our code. In this case, we specified the SHA hash for the commit with the message “Fix issue #342”.

Replace Old Tag

Each commit can only have one tag. If you decide that you want to replace the tag associated with a commit with another tag, you can do so using git tag. However, you must specify the -f (force) option, which will override the existing tag in place

Suppose we wanted to add the tag “v1.3.1” to the commit we discussed in our previous example. If we tried to do so without using the -f flag, an error message would appear. To add the tag “v1.3.1” to our previous commit, we could use this command:

git tag -a -f v1.3.1 9646aa785211f3069ce01177da98e23b7890d859

This command adds the tag “v1.3.1” to our commit and overrides the “v1.3” tag we had earlier.

Delete a Tag

To delete a tag using git, you can use the -d flag. Suppose we want to delete the tag “v1.3” from our repository. We could do so using this code:

git tag -d v1.3
git tag

Our code returns:

v1.4
v1.2
v1.1

The first command deletes the tag v1.3 from our repository. The second command returns a list of tags. As you can see, when we retrieve a list of tags, the tag v1.3 is missing. This is because we deleted the tag using the -d flag.

Conclusion

Tagging is an important feature of Git used by developers to keep track of different versions of a Git repository. Tags can be added to the current commit a developer is viewing, or to an existing commit in a repository.

This tutorial discussed, with examples, the basics of tagging in Git and how to use the Git tag command. Now you’re ready to start using the git tag command like a professional developer!