Git Describe: Label Builds for Reliable Traceability

When a user reports a defect, the first question is often which build is running. A filename such as app-final.zip or a latest label cannot reliably lead back to source. Git describe provides a readable commit label, but dependable build traceability also needs the full commit ID and artifact metadata.

1. Read the label without overinterpreting it

git describe --tags --long --always

An illustrative result is v2.3.0-5-gabc1234: the selected tag, additional commit count, and abbreviated commit ID prefixed with g. Five does not mean five deployments or features. Merge history need not form a straight sequence.

The Git describe manual documents annotated tags as the default; --tags includes lightweight tags, --long retains the extended form at a tagged commit, and --always permits an abbreviated hash fallback.

Treat this as an operational label. Do not automatically use it as a package version: the ordering rules of a registry or deployment tool require a separate policy.

2. Record the label and full commit ID

git describe --tags --long --always
git rev-parse --verify "HEAD^{commit}"
git status --porcelain=v1 --untracked-files=all

The second command identifies the commit; the third provides script-friendly status including untracked files. See the rev-parse and status documentation. Avoid hardcoding a hash length in metadata storage.

A practical team manifest has five fields: readable label, full commit ID, CI run ID, artifact checksum or digest, and build time. The label helps people communicate; the digest identifies the delivered product. Two builds from one commit may differ because dependencies, tools, or environment inputs changed.

3. Separate development builds from releases

For a developer checkout, a modification warning can be useful:

git describe --tags --long --always --dirty

The absence of a dirty suffix is not proof of clean inputs: untracked or ignored files may affect a build. Inspect status separately and define which ignored inputs a build may consume. Do not automatically delete developers' files to satisfy a cleanliness check.

For releases, define an explicit policy: use an isolated checkout, validate permitted tags, lock dependencies, and capture metadata before generating files. Computing a label after a build changes the working tree may describe build side effects rather than the original inputs.

4. Restrict the tag namespace

git describe --tags --match "v[0-9]*" --long --always
git describe --tags --match "v[0-9]*" --exact-match HEAD

The match is a glob, not a SemVer validator. Exact matching requires a tag directly on the commit and fails without one. Do not introduce a fallback that converts a failed release gate into success.

Finding a tag does not establish its author, signature, or publishing authority. Those belong to separate release controls. A multi-product repository should agree on tag namespaces and selection policy before placing labels in deployment notifications.

5. Investigate different CI and local results

git rev-parse --is-shallow-repository
git tag --list "v*"
git rev-parse HEAD

Compare commits first, then inspect the checkout's history and tags. A shallow clone or missing tags is a reason to examine CI checkout settings, not to rewrite repository tags. Fetching tags alone does not necessarily supply every historical path needed for traversal.

Choose a history-fetching policy appropriate to the project and test it on the runner. Always preserve the full commit ID even if the readable label falls back to a hash. If a release requires a tag, stop with a clear diagnostic when that requirement is unmet.

6. Make metadata available to support

• Store a manifest with the artifact, not only in CI logs that may expire.
• Expose a label in an information screen or startup log without unnecessarily publishing internal details.
• Record the deployed digest to distinguish different artifacts built from one commit.
• Exercise the support workflow: locate the CI job, artifact, and commit from a reported label.

Test tagged and untagged repositories, exact-tag commits, tracked modifications, and untracked files. Results should remain understandable beyond the script author's checkout. Git describe works best as one part of the build record, not its only source of truth.