Skip to content

Git Describe

In one line

git describe produces a human-readable name for the current commit based on the nearest annotated tag.

In simple words

git describe gives a commit a human-readable name by finding the nearest tag reachable from it and counting how many commits are between. For example, if the nearest tag is v1.2.0 and there are 5 commits since, it outputs v1.2.0-5-gabc1234. This is far more meaningful than a raw hash for version identification.

It is the standard way to generate a version string from a Git repo: build tools run git describe --tags --always to produce a version like 1.2.0-5-gabc1234 for unreleased builds, or just 1.2.0 if the commit is exactly a tag. The --always flag falls back to the hash if no tags exist.

Use git describe in build scripts, CI, and release tooling to embed the exact source version into binaries, logs, and about pages. It works with annotated tags (preferred) or lightweight tags (--tags), and you can limit how far back it searches with --match.

Example

bash
# At a commit 5 past the v1.2.0 tag
git describe
# v1.2.0-5-gabc1234

# At exactly a tag
git checkout v1.2.0
git describe
# v1.2.0

# Use lightweight tags too, fall back to hash if no tags
git describe --tags --always

# In a build script — embed the version
VERSION=$(git describe --tags --always)
echo "Building version $VERSION"

describe finds the nearest tag, counts commits since, and appends the short hash: tag-N-gHASH. --always falls back to the hash if no tags exist.

Related terms

Related Resources

Related Lessons

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors

← Back to glossary