git describe

Inspection & Comparison

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>...]
[ ] optional| or<arg> placeholder... repeatable--flag option

Options

Click any option to expand

Beginner (3)

Use any tag, including lightweight ones, not only annotated tags.

When neededWhen your project uses lightweight tags

Example

git describe --tags

Show the abbreviated commit hash when no tag can describe the commit.

RecommendedNever fail: print the short hash when no tag is found

Example

git describe --always

Append -dirty when the working tree has uncommitted changes.

RecommendedFlag builds made from uncommitted changes

Example

git describe --dirty

Choosing the Right Option

Reading a describe name

v1.0-2-g1a2b3c4

CommandMeaning
v1.0The nearest tag
2Commits since that tag
g1a2b3c4"g" for git + the abbreviated hash
-dirtyUncommitted changes (with --dirty)

Examples

Describe HEAD

git describe

v1.0-2-g1a2b3c4: two commits after v1.0.


Include lightweight tags

git describe --tags

Also consider tags made without -a.


Never fail

git describe --always --dirty

Hash if no tag, -dirty if there are local edits.

Workflow Examples

1
git describe --tags --always --dirty

Compute the version string

2
echo "$(git describe --tags --always)" > version.txt

Write 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

A:

It uses the tag with the fewest commits between it and the described commit.