How to programmatically determine whether the Git checkout is a tag and if so, what is the tag name

In a Unix or GNU scripting environment (e.g. a Linux distro, Cygwin, OSX), what is the best way to determine whether the current checkout is a Git tag. If it is a tag, how can I determine the tag name?

One use of this technique would be automatically labeling a release (like svnversion would do with Subversion).

See my related question about programmatically detecting the Git branch.

The solution to your question is to use

git describe --exact-match HEAD

(which would consider only annotated tags, but you should use annotated and probably even signed tags for tagging releases).

If you want to consider all tags, also lightweight tags (which are usually used for local tagging), you can use --tags option:

git describe --exact-match --tags HEAD

But I think you have "XY problem" here, in that you are asking question about possible solution to the problem, rather than asking question about a problem... which can have better solution.

The solution to your problem is to take a look how Git does it in GIT-VERSION-GEN script, and how it uses it in its Makefile.

A better solution (from Greg Hewgill's answer in the other question) would be:

git name-rev --name-only --tags HEAD

If it returns "undefined" then you are not on a tag. Otherwise it returns the tag name. So a one-liner to do something like my other answer would be:

git_tag=`git name-rev --name-only --tags HEAD | sed 's/^undefined$//'`

Interactive shell example of how it works:

$ git checkout master
Already on "master"
$ git name-rev --name-only --tags HEAD
undefined
$ git checkout some-tag
Note: moving to "some-tag" which isnt a local branch
If you want to create a new branch from this checkout, you may do so
(now or later) by using -b with the checkout command again. Example:
  git checkout -b <new_branch_name>
HEAD is now at 1234567... Some comment blah blah
$ git name-rev --name-only --tags HEAD
some-tag

Usage of git-name-rev is preferred for scripts, since it is part of git plumbing, whereas git-describe is part of porcelain.

Use this command to print the name of the tag if the HEAD points to one, otherwise nothing.

git name-rev --name-only --tags --no-undefined HEAD 2>/dev/null | sed -n 's/^\([^^~]\{1,\}\)\(\^0\)\{0,1\}$/\1/p'

Note the redirection of stderr to /dev/null - otherwise you'll get an error message saying:

fatal: cannot describe 'SOMESHA'"

EDIT: Fixed the regex in sed to support both lighweight and annotated/signed tags.

The best way to do this is to use the git describe command:

git-describe - Show the most recent tag that is reachable from a commit

The command finds the most recent tag that is reachable from a commit. If the tag points to the commit, then only the tag is shown. Otherwise, it suffixes the tag name with the number of additional commits on top of the tagged object and the abbreviated object name of the most recent commit.

You cannot determine if the current checkout “is a tag”. You can only determine if the current checkout was a commit that has tags.

The difference is: if there are several tags pointing to this commit, git can’t tell you which you used to checkout, nor if you actually used one to get there at all.

Jakub’s answer here based on git describe --exact-match (--tags) gives you “the first” of all the (annotated) tags.

And git describe sorts them like this:

• annotated tags first
  • sorted youngest first
• lightweight tags come afterwards
  • binary sorted by tag name (that means alphabetically if it’s English encoded in ASCII)
  • git doesn’t store meta-data with lightweight tags, so “youngest-first” can not be realized