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.
git describe # v1.4.0-12-g3f2a9c1 git describe --tags --dirty # also include lightweight tags and a -dirty suffix
Try it
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.
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
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;
--containssearches forward instead. - Abbreviation grows with repository size; to keep a stable length set
--abbrev=<n>orcore.abbrev. - Shallow clones often lack the tag history, so
describeprints nothing useful; fetch tags or deepen the clone (CI systems commonly needfetch-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
--matchto 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-parentmakes it predictable. - Build scripts can embed the result in a binary or a package version, e.g.
VERSION=$(git describe --tags --always --dirty).
Related
git tag,git name-rev,git rev-parse,git log- Lessons: Tags, Release process project