Git Tag: An Overview of the Basic Functions

September 6, 2022

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.

Git tag - an overview.

Prerequisites

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.

Listing Git tags in a repository.

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
Sorting listed Git tags by version number.

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

git tag --sort=taggerdate
Sorting Git tags by creation date.

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.

Listing Git tags in a remote repository.

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*
Searching for Git tags.

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
Showing tag and commit details in Git.

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
Obtaining a commit's SHA hash.

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:

Git throws an error when creating a tag that already exists.

Important: Be careful when specifying the -f option, as it overwrites any existing tag data.

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"
Updating an existing Git tag.

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.

Note: To push only a single tag, specify the tag name instead of the --tags option.

For example:

git push origin --tags
Pushing tags to a remote repository.

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
Fetching Git tags from a remote repository.

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
Checking out a Git tag.

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
Creating a new branch in Git.

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
Deleting a Git tag.

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
Deleting a remote Git tag.

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.

Was this article helpful?
YesNo
Bosko Marijan
Having worked as an educator and content writer, combined with his lifelong passion for all things high-tech, Bosko strives to simplify intricate concepts and make them user-friendly. That has led him to technical writing at PhoenixNAP, where he continues his mission of spreading knowledge.
Next you should read
Git Tag Commit Guide
August 30, 2022

This tutorial shows how to create a Git tag for the latest commit in the repository, and for a specific commit in the Git project history.
Read more
Git Clone Tag Guide
August 29, 2022

This tutorial shows how to clone a specific Git tag from a remote repository, and address the detached HEAD state.
Read more
How To Pull The Latest Git Submodule
August 17, 2022

This tutorial shows how to pull the latest Git submodule to use other Git sources in a project without copying the code.
Read more
Git Rename Tag Guide
August 11, 2022

Git tags are reference points in a project's history. This tutorial shows how to rename a Git tag in a local or remote repository.
Read more