git describe: Usage, Options & Common CI Errors

git describe turns the current commit into a version string based on the most recent tag.

describe is the go-to for embedding a version like v1.2.0-5-gabc123 into a build. It needs tags present.

What it does

git describe finds the most recent tag reachable from a commit and appends the number of commits since and a short SHA, e.g. v1.2.0-5-gabc1234.

Common usage

Terminal

git describe                  # nearest annotated tag
git describe --tags           # include lightweight tags
git describe --tags --always  # fall back to a SHA if no tag
git describe --dirty          # add -dirty if tree is modified

Options

Flag	What it does
--tags	Consider lightweight tags too
--always	Fall back to an abbreviated SHA
--dirty[=<mark>]	Append a mark if the tree is dirty
--abbrev=<n>	Set SHA abbreviation length
--match <pattern>	Only consider matching tags

Common errors in CI

fatal: No names found, cannot describe anything / "No annotated tags can describe …" - there are no (annotated) tags reachable, often because the clone is shallow or skipped tags. Use --tags --always, and set fetch-depth: 0 so tags are fetched.

Related guides

git tag: Usage, Options & Common CI Errorsgit tag creates and lists tags for releases. Reference for -a, -m, -d, pushing tags, and the "tag already exi… git rev-parse: Usage, Options & Common CI Errorsgit rev-parse resolves refs to SHAs and reports repo paths - core CI plumbing. Reference for --short, --abbre… git show: Usage, Options & Common CI Errorsgit show displays a commit, tag, or object with its diff. Reference for --stat, --name-only, blob viewing, an… git fetch: Usage, Options & Common CI Errorsgit fetch downloads remote objects and refs without touching your working tree. Reference for --depth, --unsh…