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.
Prerequisites
- Git installed (see how to install Git on Windows, macOS, Ubuntu, CentOS 7, or CentOS 8).
- A local and remote Git repository.
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
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
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 -n2Filter 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.
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
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
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.
Note: Learn how to use the Git prune command.
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 tag1. 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:
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
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
Note: To change the default sorting order and make v:refname the default one, run:
git config --global tag.sort v:refnameAfter 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
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=-taggerdateHow to Find the Latest Git Tag Available
Use the git describe command to locate the most recent tag reachable from a commit:
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
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.
