Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Branches and Tags

git describe command

Reference for git describe: how the tag-count-ghash output is built, --tags, --always, --dirty, --long, --abbrev and --match, with version-string examples.

git describe finds the most recent tag reachable from a commit and prints a name made of that tag, the number of commits since it, and the abbreviated hash of the commit. If the commit itself is tagged, only the tag name is printed. The output is a human-readable, monotonically meaningful build identifier, often used as a version string.

By default only annotated tags are considered. Use --tags to include lightweight tags, and --always to fall back to a bare hash when no tag is found.

Terminal
git describe                 # v1.4.0-12-g3f2a9c1
git describe --tags --dirty  # also include lightweight tags and a -dirty suffix

Try it

Bash Anatomy of the output

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Lightweight tags, matching and abbreviation

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
git describe [--all] [--tags] [--contains] [--abbrev=<n> | --long] [--always]
             [--dirty[=<mark>]] [--broken[=<mark>]] [--match <glob>]
             [--exclude <glob>] [--first-parent] [--candidates=<n>] [<commit-ish>...]
Name Description
<commit-ish> Commit(s) to describe; defaults to HEAD.
--tags Use any tag, lightweight or annotated.
--all Use any ref, including branches and remote-tracking branches.
--always Show an abbreviated hash if nothing matches instead of failing.
--long Always print the tag-count-ghash form, even exactly on a tag.
--abbrev=<n> Length of the hash; 0 suppresses the count and hash part.
--dirty[=<mark>] Append -dirty (or the mark) if the working tree has changes.
--broken[=<mark>] Like --dirty, and append -broken when the repository is damaged.
--match, --exclude Only consider (or ignore) tags matching a glob; may be repeated.
--contains Find the tag that comes after the commit (like git name-rev --tags).
--first-parent Follow only the first parent when searching.

Returns: a name like v1.0-3-g1a2b3c4; the g marks a Git hash.

Errors: with no suitable tag it fails with "fatal: No names found, cannot describe anything." (use --always); a commit that is not a descendant of a tag may report "No tags can describe ...".

Usage notes

  • Annotated by default. A repository with only lightweight tags needs --tags; this is the usual cause of "No annotated tags can describe".
  • The count is the number of commits reachable from the commit but not from the tag, which makes the string sort sensibly within a release line.
  • It looks backwards only. The nearest tag is found along ancestors; --contains searches forward instead.
  • Abbreviation grows with repository size; to keep a stable length set --abbrev=<n> or core.abbrev.
  • Shallow clones often lack the tag history, so describe prints nothing useful; fetch tags or deepen the clone (CI systems commonly need fetch-depth: 0).
  • Several tags on one commit: annotated tags are preferred over lightweight ones, but between two annotated tags the choice is not something to rely on. Use --match to pick a tag family explicitly.
  • Merge commits may be described by whichever parent path has the closest tag, so builds from merges can look surprising; --first-parent makes it predictable.
  • Build scripts can embed the result in a binary or a package version, e.g. VERSION=$(git describe --tags --always --dirty).