Git List Tags

August 25, 2022

Introduction

Git tags highlight specific points in a project's development history, such as commits or program versions. Tags are especially useful when going back to an earlier version, as they help locate a version quickly.

Listing Git tags is a practical option when dealing with multiple commits or versions in a repository and pinpointing a single one.

In this tutorial, you will learn to list existing Git tags in a local and remote repository.

How to list tags in Git.

Prerequisites

How to List Git Tags?

There are two ways to obtain a tag list in Git:

  • List tags from a local repository.
  • List tags from a remote repository.

The sections below show the steps for listing Git tags in both repository types.

1. List Local Git Tags

Local Git tags are tags stored in the local repository. Below are different ways of listing local Git tags:

List All Tags

Run the following command to create a list of all Git tags in the local repository:

git tag
List all existing Git tags.

The command outputs an alphabetical list of all existing tags in the repository.

List Tags With Description

Annotated tags contain metadata with a description for each tag. To get an extensive list containing each annotated tag's description, add the -n flag to the git tag command:

git tag -n
List tags with an added description.

The command prints a list of tags along with the first line of existing tag descriptions.

Note: Git tags can be lightweight or annotated. Learn the difference and see how to create Git tags.

See Full Description

To see more than just the first line of the tag description, specify the number of lines to show in the output. For example, to show two lines of each tag description, run:

git tag -n2

Filter Tags

To show only tags containing a particular string, specify the -l option followed by the string. The syntax is:

git tag -l [string]

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

git tag -l v2*

The asterisk (*) is a wildcard replacing any character string.

Filter tag list in Git.

2. List Remote Git Tags

Developers have access to remote repositories when collaborating on a joint project. A remote repository is hosted on a server and accessible by all team members.

A local and remote repository can differ if one of the team members has made changes that you haven't pulled to the local repository yet. Those changes can include new or deleted commits, branches, or tags.

Use the following syntax to obtain a list of tags on a remote repository:

git ls-remote --tags [remote_name]

Replace [remote_name] with the remote repository name. For example, to list tags from a remote repository named origin, run:

git ls-remote --tags origin
List remote Git tags.

The command outputs a list of tags specified with the complete references and SHA hashes to avoid confusion if there are multiple Git objects with the same name.

How to Fetch Remote Git Tags

When collaborating on a project, some objects may exist only in a remote repository before importing them to the local one. When listing Git tags locally, fetch any new tags from the remote repository before listing to ensure all changes are synchronized.

Fetch tags from a remote repository by running:

git fetch --all --tags --prune
Fetch remote tags to local repository.

The --prune option cleans up unreachable Git tags inaccessible by any refs. Any commit that cannot be accessed through a branch or tag is considered unreachable.

How to Sort Git Tags

Git allows users to sort tags in three ways:

  • By refname, in alphabetical order.
  • By version number.
  • By creation time.

When listing Git tags, the default sorting way is in alphabetical order. Below are examples of sorting Git tags in different ways.

1. Sort Git Tags by Refname

Git sorts tags by their refname using the alphabetical order, which is the default sorting setting. To sort tags alphabetically, list all tags by running:

git tag

1. Sort Git Tags by Version

Sorting tags alphabetically and by version number uses a different principle. For example, sorting in alphabetical order places the v1.10 tag before v1.2, which is not the expected order:

Git tags sorted alphabetically.

When sorting tags by version number, Git treats all tag names as version numbers and sorts them correctly.

Run the following command to test:

git tag --sort v:refname
Git tags sorted by version number, in ascending order.

The tags are sorted by the version number in ascending order. To switch the direction and sort tags in descending order, prepend a dash (-):

git tag --sort=-v:refname
Git tags sorted by version number, in descending order.

Note: To change the default sorting order and make v:refname the default one, run:

git config --global tag.sort v:refname

After setting the default sorting order, running git tag outputs a list of tags sorted by version number.

3. Sort Most Recent Git Tags

Sorting Git tags by the creation date outputs a list with the most recent Git tags at the top. Run the following command:

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

The command sorts all tags from the oldest to the most recent. To get the most recent tags first, prepend the command with a dash (-):

git tag --sort=-taggerdate

How to Find the Latest Git Tag Available

Use the git describe command to locate the most recent tag reachable from a commit:

Obtaining the latest available Git tag.

By default, the output shows only annotated tags and requires the --tags flag to display any tag found in refs/tags namespace, including lightweight tags. Enter this command:

git describe --tags
Showing the latest available Git tag, regardless of the tag type.

The command outputs the tag associated with the latest commit.

Conclusion

This guide showed how to list and sort Git tags in a local and remote repository. Learn more about Git in our article on pushing Git tags to a remote repository, or learn to delete a Git tag locally and remotely.

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 Rename Tag Guide
August 11, 2022

Git tags are specific reference points in a project's development. This tutorial shows how to rename a Git tag in a local or remote repository.
Read more
Git Push Tag to Remote Guide
August 17, 2022

Follow this guide to learn to create and push local Git tags to a remote repository. See examples for pushing single, multiple, or all existing local tags to a remote repo.
Read more
Git Tag Release Management
December 29, 2021

Git releases are GitHub objects created from Git tags, allowing you to show official program versions on your project page. Learn how to work with Git releases in this guide.
Read more
Git Checkout Tag
December 2, 2021

Git tags help track program versions by creating reference points for release versions. Learn how to checkout a Git tag, how to connect it to a branch and how to fetch the latest changes in this tutorial.
Read more
  • © 2022 Copyright phoenixNAP | Global IT Services. All Rights Reserved.