How to List Git Tags

First of all, what are Git tags? Tags are labels or ref’s that point to specific points in your Git history. They are generally used to mark or highlight a significant git commit in your project, for example, when you have a version release (e.g. v1.0.1 could be the tag value). When a commit is tagged it is easy to find, so if you wanted to find a particular version release, you can find it quickly because of the git tag. This tutorial will show you how you can list git tags in your code repository.

List Git Tags in a Local Repository

Most commonly you will need to list local git tags. The simplest version of the command is simply to run the git tag command, without any additional arguments:

$ git tag

v0.11.0
v0.11.0-rc1
v0.11.1
v0.11.2

If you have many git tags in the list you can filter the output of the git tag command by using the -l or –-list option when running the command:

$ git tag -l *-rc*
v0.11.0-rc1 

This is a great way to quickly find what you need if you have many git tags in a complex project, but it also highlights the need to have a consistent git tagging strategy.

It’s important to be aware that Git supports two types of tags – these are annotated and lightweight tags. The examples up to now have been listing git lightweight tags. Annotated git tags can contain more detailed information, such as a more detailed description. You can use the -n option to list this additional information.

$ git tag -n
V1.0        Version 1.0 
v2.0        Version 2.0

Sort your Git Tags List!

If you have many git tags you can list and sort them at the same time. Again, it’s useful to have a consistent strategy for tag naming, but sorting can help you make sense of a long list of git tags. To sort your git tag output add the –sort=refname option to the command:

$ git tag -l --sort=version:refname
v0.11.0
v0.11.0-rc1
v0.11.1
v0.11.2

$ git tag -l --sort=version:refname *rc*
v0.11.0-rc1

You can also sort the list by your most recently added tags by using the —sort=committerdate option with the git tag command.

$ git tag --sort=committerdate
v0.11.0
v0.11.0-rc1
v0.11.1
v0.11.2

Great work! Now you know how to sort git tags. Now lets move on to take a look at how we can list remote git tags.

How to List Remote Git Tags

Of course, with git you are often working with a remote repository to which you can push your code updates to share with other developers in your teams. At the same time, they may also be pushing updates to the central repository, including updates that include tags. Therefore, it’s important to understand how to fetch and list tags that have been added to the remote repository.

To list remote tags, we use the git ls-remote –tags command. So, for example to list the remote tags in our repository named ‘origin’ we could do the following:

$ git ls-remote --tags origin

43fg5cf7ca57e05d456321b40673acd3rf2f2326        refs/tags/v1.0
6gd04tgd794bfs4g455gd3d3ynn5as438e6355gt        refs/tags/v2.0

Now, we can fetch these tags down to our local repository by using the git fetch command, but specifically asking to fetch git tags:

$ git fetch --all --tags

Our local git repo should now be up to date with any tags that were added to the remote repository. Awesome!

Final Word

Great, you made it to the end! You should now have a good idea of how you can list git tags, both in local and remote git repositories. We also took a look at how to sort the list of git tags and how to filter the list, both of which are useful in a busy project where you have many tags and commits.