git describe
Give a commit a readable name based on the nearest tag
The 'git describe' command names a commit after the nearest tag reachable from it: the tag itself if the commit is tagged, otherwise tag-N-gHASH (N commits after the tag, then the abbreviated hash). Build scripts use it to stamp a version on every build. By default only annotated tags are used.
Synopsis
git describe [--tags] [--always] [--dirty] [--abbrev=<n>] [<commit-ish>...]Options
Choosing the Right Option
Reading a describe name
v1.0-2-g1a2b3c4
| Command | Meaning |
|---|---|
v1.0 | The nearest tag |
2 | Commits since that tag |
g1a2b3c4 | "g" for git + the abbreviated hash |
-dirty | Uncommitted changes (with --dirty) |
Examples
Describe HEAD
git describev1.0-2-g1a2b3c4: two commits after v1.0.
Include lightweight tags
git describe --tagsAlso consider tags made without -a.
Never fail
git describe --always --dirtyHash if no tag, -dirty if there are local edits.
Workflow Examples
git describe --tags --always --dirtyCompute the version string
echo "$(git describe --tags --always)" > version.txtWrite it into the build
Troubleshooting
fatal: No names found, cannot describe anything.
Cause: The repository has no tags
Create one (git tag -a v0.1 -m ...) or use --always
fatal: No annotated tags can describe ...
Cause: Only lightweight tags exist
Use --tags, or re-create the tag with -a
Tips & Pitfalls
Best Practices
- ✓Use annotated tags for releases so describe works without --tags.
- ✓Use --always in scripts so they never fail.
Common Mistakes
- ✗Getting "No names found" because the project only has lightweight tags — add --tags.
- ✗Reading the g in -g1a2b3c4 as part of the hash: it just means "git".
FAQ
It uses the tag with the fewest commits between it and the described commit.