git describe: Usage, Options & Common CI Errors

By Kaveh Alemi·Latchkey

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.

Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

.github/workflows/ci.yml

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached

Frequently asked questions

git describe: Usage, Options & Common CI Errors?