DEV Community

Srebalaji Thirumalai
Srebalaji Thirumalai

Posted on • Originally published at gitbetter.substack.com on

Git tagging - A brief guide

This post was originally posted in the newsletter GitBetter. If you are interested in leveling up your game in Git, you can subscribe to it.

Git provides an option to tag (or mark) a specific point in your repo which helps you to identify the tag later and also review the changes at any time in the future.

You can see tags as a checkpoint in your repo. They are like branches but you can’t add more changes to it once a tag is created. Simple.

Most people use tagging to mark a specific release in the project. So they can review those releases later.

And it is also a very good practice to use tagging. It helps people to understand how the project has evolved over a period of time.

Creating tag

Before creating tags, I like to mention that there are two types of tags.

  1. Lightweight

  2. Annotated

Lightweight tags are just simple tags that are just a pointer to a particular commit hash. Mostly these tags are used for temporary reasons.

Annotated tags are mostly used and have additional info like tagger name, date, and tagging message. If you are tagging for a permanent pointer, you should use annotated tags.

Creating lightweight tags

git tag <tag_name>

Example:
git tag v1.1-1w
Enter fullscreen mode Exit fullscreen mode

In the above command, v1.1-1w is the tag name.

Creating annotated tags

git tag -a <tag_name>

Example:
git tag -a v1.2
Enter fullscreen mode Exit fullscreen mode

-a is the option used to create an annotated tag.

You will be prompted with a tag message

You can write some relevant message for the release and save the file.

The shorthand of the above command is

git tag -a v1.2 -m "Release V1.2"
Enter fullscreen mode Exit fullscreen mode

The above command will take a tag message option.

And also remember that Git will take the HEAD commit (latest commit) to create the tag.

Pushing the tags to the remote

You have to explicitly push tags to the remote.

git push origin v1.2 // Will push the mentioned tag.

git push origin --tags // Will push all the tags to the origin.
Enter fullscreen mode Exit fullscreen mode

Tagging old commits

You can also create a tag from explicitly mentioning the commit hash. As I said before by default, Git will take the HEAD commit to tag.

To tag an explicit commit

git tag -a <tag_name> <commit_hash>

Example:
git tag -a v1.1 84b2bbd
Enter fullscreen mode Exit fullscreen mode

Listing all tags

git tag
Enter fullscreen mode Exit fullscreen mode

The above command will list all tags of the repo.

To search through the tags, you can use

git tag -l "v1*"
Enter fullscreen mode Exit fullscreen mode

-l will take a search pattern and list the relevant tags. The above command will list all tags in the v1 series. * acts as a wildcard.

Tag info

You can view the tag info using

git show <tag_name>
Enter fullscreen mode Exit fullscreen mode

In the above example, we have shown the tag info. You can see the tag name, tagger, date, tag message, and the respective commit.

Checking out a tag

One of the useful features of tagging is that we can review that pointer in the future. You can check-out a tag similar to a branch.

git checkout <tag_name>
Enter fullscreen mode Exit fullscreen mode

But by checking-out, you will be gone to the “Detached HEAD” state. It means that you are not supposed to commit any changes to the tag. Even if you commit any change, it won’t be available in the tag or even in any branch.

Checking-out the tag helps you to go that pointer and just review the changes.

Deleting a tag

Tags are very lightweight. They won’t consume much space in the repo. But if you need to clean the tags, then you can delete older tags.

git tag -d <tag_name>
Enter fullscreen mode Exit fullscreen mode

To remove the tag from remote

git push origin --delete <tag_name>
Enter fullscreen mode Exit fullscreen mode

Retagging tags

Sometimes, you have created a wrong tag. You have to add some commits or remove some commits from the tag.

As we can’t create tags with similar names (tag name is unique), the no-brainer workaround is to delete the tag and create the new one with the same name.

Another option is to force create a tag.

git tag -a -f <tag_name> <optional_commit_hash>

Example:
git tag -a -f v1.2 // Considering HEAD commit
git tag -a -f v1.2 84b2bbd // Considering a particular commit
Enter fullscreen mode Exit fullscreen mode

-f is the option to force create a tag. So the tag that was already created will be replaced with the new commit hash.

To force push the created tag to remote

git push origin -f --tags
Enter fullscreen mode Exit fullscreen mode

This will force push the tags to the remote.

Remember to use this with caution. If you are force pushing the tags, then your team members who have the tags in their local will face conflicts when they push.

Tags and releases in Github

Tags will be listed in Github too. You can see all your tags, edit, and create new ones.

Github also has a feature called Releases. Releases are tied to a tag. Whenever you push a tag, a release is also created. You can also create your own release in Github itself which will create a respective tag too.

Most people will create a new release when new version of the product is released to prod.

You can see the releases of Rails repo here

Tagging is one of the useful features of Git. It helps you to see how your project has evolved over time.

Thank you for reading :)

This post was originally posted in the newsletter GitBetter. If you are interested in leveling up your game in Git, you can subscribe to it.

Top comments (0)