Working with Git Tags

Git has been around for almost 20 years, yet it remains the most popular distributed version control system. It is best known for GitHub, the largest remote Git repository where developers store their code, document changes, and save previous versions. To help manage versions efficiently, Git provides special markers called tags. This article will explore what Git tags are and how to use them.

What Are Git Tags?

Copy link

To understand Git tags, let's first clarify some related concepts.

• Commit: A commit is a saved version of a project.
• Branch: A collection of commits that visually represents the history of changes in a project. Multiple branches can exist simultaneously.

Now, let’s define tags.

Git tags are markers used to highlight important commits. They help track version history, as responsible developers often tag each new version. Like branches, Git tags point to a specific commit, but unlike branches, they do not have a history of commits.

Now, let's see how to work with Git tags—create, view, publish, replace, switch, and delete them.

How to Create Git Tags

Copy link

Git has two main types of tags: annotated and lightweight. Each is created differently.

Creating Annotated Tags

Annotated tags store complete version information, including developer names, emails, and timestamps. They are created using special Git flags, -a and -m, as shown in the example below:

git tag -a ver-2.5 -m "beta version 2.5"
git tag

Output:

ver-0.1  
ver-1.6  
ver-2.5  

• git tag is the main command for working with tags.

• -a creates an annotated tag with a specified identifier.

• -m adds a message. If omitted, a text editor will open for message input.

To view details of an annotated tag along with its commit, use:

git show ver-2.5

Output:

tag ver-2.5  
Tagger: Marianne Smith <m.smith@company.com>  
Date: Fri Mar 28 11:02:35 2025  


beta version 2.5  


commit bf93b7eaa928fd77a55453118313701b04874051  
Author: James Brown <j.brown@company.com>  
Date: Mon Jan 6 09:41:02 2025  

This displays the tagger's information, the commit hash, the author, and the creation date.

To verify that the tag was created successfully, use:

git tag -n

Creating Lightweight Tags

Lightweight tags are simple pointers to commits, typically used for temporary markers. They store only the commit’s hash. Here’s how to create one:

git tag ver-2.5a
git tag

Output:

ver-0.1  
ver-1.6  
ver-2.5  
ver-2.5a  
ver-2.6  

To view a lightweight tag's commit information:

git show ver-2.5a

Output:

commit bf93b7eaa928fd77a55453118313701b04874051  
Author: James Brown <j.brown@company.com>  
Date: Mon Jan 6 09:41:02 2022 -0300  

Unlike annotated tags, lightweight tags do not store additional metadata.

Adding and Deleting Git Tags in Remote Repositories

Copy link

To push a tag to a remote repository:

git push origin ver-2.5

Here, origin refers to the default remote repository. To push all tags at once:

git push origin --tags

To delete a tag from a remote repository:

git push origin --delete ver-2.5

To delete a tag locally (not on the remote repository):

git tag -d ver-2.5

Switching Between Tags

Copy link

To switch to a specific tag:

git checkout ver-2.5

However, this detaches the HEAD pointer, meaning any subsequent changes will not be associated with any existing branch. If you make changes, create a new branch to keep them:

git checkout -b new-branch

Viewing a List of Git Tags

Copy link

To list all available tags:

git tag

Output:

ver-0.1  
ver-1.6  
ver-2.5  
ver-2.5a  
ver-2.6  

To filter tags using a pattern:

git tag -l *xyz*

If you have tags like ver-1.6xyz, ver-2.5xyz, and ver-2.6xyz, this command will output:

ver-1.6xyz
ver-2.5xyz
ver-2.6xyz

Reassigning or Replacing Tags

Copy link

To update an existing tag, use the -f flag for forced replacement:

git tag -a -f ver-2.5a bf93b7eaa928fd77a55453118313701b04874051

This reassigns the tag to a specific commit hash. However, this will delete the old tag information, so use it carefully.

Summary

Copy link

Git tags make version control more flexible and manageable. The commands covered here are simple yet powerful, making them easy to learn even for beginners.