Git Tag: An Overview of the Basic Functions

Introduction

Git tags highlight important milestones in a project's development history. Tags mark program release versions, bug fixes, patches, or specific commits, and help you find every project stage quickly.

This tutorial provides an overview of basic Git tag actions.

Prerequisites

• Git installed (depending on the system, see how to install Git on Windows, macOS, Ubuntu, CentOS 7, or CentOS 8).
• A local and remote Git repository.

Creating A Tag

There are two types of tags available in Git:

• Annotated tags. These tags are usually created for public releases. Annotated tags contain additional metadata that includes information about the tagger, tag creation date, and a specific tag message.
• Lightweight tags. These tags are used for internal purposes. They only point to a commit or program version and don't contain any additional data.

The sections below explain how to create each of the two tag types.

Annotated Tags

The syntax for creating an annotated tag is:

git tag -a [tag_name] [commit_SHA] -m "Tag notes"

• Replace [tag_name] with the name of the tag. The best practice is to follow semantic versioning rules. The rules denote if a tag describes a release candidate, program version, patch, bug fix, or commit.
• For [commit_SHA], enter the exact commit SHA hash when creating a tag for a specific commit.

For example:

git tag -a v1.0.1 -m "Bug fix"

The command creates an annotated tag named v1.0.1 with the specified message.

Lightweight Tags

Use the following syntax to create a lightweight tag:

git tag [tag_name]

For example:

git tag v1.1

The command creates a lightweight tag named v1.1.

Listing Tags

Git allows users to list the existing tags in a local or remote repository using the git tag command:

List Local Tags

To list tags in a local repository, run:

git tag

By default, listing sorts Git tags by their refname in alphabetical order.

However, Git also allows users to sort tags by:

• Version number.
• Creation time.

To sort tags by their version number, run:

git tag --sort v:refname

Run the following command to sort Git tags by their creation date:

git tag --sort=taggerdate

List Remote Tags

List tags in a remote repository using the following syntax:

git ls-remote --tags [remote_name]

The following example shows a list of all tags in the remote repository with a unique SHA hash for each tag and a full reference.

Search Git Tags

Search for a particular Git tag using the -l option. The syntax is:

git tag -l [string]

• Replace [string] with a search term.

For example, run the following command to show a list of tags starting with v2:

git tag -l v2*

View Git Tags

Use the git show command to view tag details and commit information. The syntax is:

git show [tag_name]

For example:

git show rc0.9

The command outputs the tag details, including the creator's username and email address, creation date, message, existing GnuPG signatures, and the referenced commit information. In the case of a lightweight tag, the output only contains information about the referenced commit.

Tag Old Commits

Tagging helps keep the repository organized and allows users to quickly and easily find a specific program version or commit. However, if an old commit in the repository isn't tagged, tag the commit by specifying the exact commit SHA hash.

Obtain the commit SHA hash by running:

git log --oneline

The output contains all the commits in the repository, each designated with a specific SHA hash. Copy the old commit's SHA value and use it to tag the old commit.

The syntax is:

git tag -a [tag_name] [commit_SHA] -m "Message"

For example:

git tag -a v1.0 85dd733 -m "Initial version released"

The command creates a tag called v1.0 for the specified commit.

Replacing Old Tags

Replace an existing tag in Git using the git tag command and the -f (--force) option. Not specifying the -f option results in an error when trying to replace an existing tag:

The syntax for replacing a tag is:

git tag -a -f [tag_name] [commit_SHA] -m "Message"

• For [tag_name], specify the tag you want to replace.
• For [commit_SHA], specify the exact commit SHA value to map the tag to.

For example:

git tag -a -f v1.1 -m "Version 1.1 released"

The command updates the existing tag with new data.

Push Git Tags

Pushing Git tags exports tags from the local repository to a remote one. While the git push command allows you to send all changes from the local repository to the remote one, it does not push the tags unless the --tags option is specified.

Use the following syntax to push all local tags to the remote repo:

git push [remote_name] --tags

• For [remote_name], specify the name of the remote repository.

For example:

git push origin --tags

The command pushes all local tags to the origin repository.

Checkout Git Tags

The git checkout command allows users to navigate between branches. However, since Git tags are objects in a Git repository, users can also checkout a Git tag in the same way as branches.

Follow the steps below to checkout a Git tag:

1. Ensure the local repository has the latest tag list from your remote repository. Run:

git fetch --all --tags

2. Use the following syntax to checkout to a Git tag:

git checkout [tag_name]

For example, to checkout to the tag v2.1, run:

git checkout v2.1

The command checks out the v2.1 tag but leaves the repository in a detached HEAD state. You can view, make changes, and commit, but no branch is tracking the changes.

3. To create a new branch and start tracking changes, enter:

git branch

Delete Git Tags

Keeping the repository clean and deleting unnecessary Git tags is essential, especially when collaborating on a project. Delete a Git tag by passing the -d option.

Delete Local Git Tags

Use the following syntax to delete a local Git tag:

git tag -d [tag_name]

For example:

git tag -d v1.0

The command deletes the specified local Git tag.

Delete Remote Git Tags

The syntax for deleting a remote Git tag is:

git push --delete [remote_name] [tag_name]

• For [remote_name], specify the name of the remote repository.
• For [tag_name], specify the tag you want to delete.

For example:

git push --delete origin v1.0

The command deletes the specified remote tag.

Conclusion

This tutorial gave an overview of the basic Git tag functions and possible tag actions. For more Git tutorials, see how Git works, how to use Git, or learn to use Git Bash and Git Bash commands.