# git describe Command: Version Strings in CI

> git describe builds a human-readable version from tags. Reference for --tags and --always to derive build versions in CI even when no tag exists.

Source: https://latchkey.dev/learn/command-reference/git-describe-command-reference  
Updated: 2026-06-26

git describe produces a version string by finding the most recent tag reachable from a commit.

git describe is the standard way to turn commit state into a version like v1.2.0-5-gabc1234. It is a favorite in CI for stamping builds with a meaningful, sortable identifier.

## Common flags

- `--tags` - consider lightweight tags too, not just annotated ones
- `--always` - fall back to a short SHA when no tag is reachable
- `--abbrev=N` - set the number of SHA hex digits in the suffix (0 hides it)
- `--dirty[=<mark>]` - append a marker if the working tree has uncommitted changes
- `--long` - always include the commit count and SHA suffix
- `--match <pattern>` - only consider tags matching a glob

## Example

```shell
# Robust version that never fails, even on an untagged commit
VERSION="$(git describe --tags --always --dirty)"
echo "version=${VERSION}"
```

## In CI

git describe fails with "fatal: No names found" when no tags are present or the clone is too shallow to reach one. Combine --tags --always so it degrades to a SHA, and ensure tags are fetched (fetch-depth: 0 and --tags) so the nearest tag is reachable.

## 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
```

> `git rev-parse --abbrev-ref HEAD` returns the literal string `HEAD` on a detached checkout rather than a branch name. On GitHub Actions read `github.ref_name` instead; the git command cannot know what it was checked out for.

## FAQ

### git describe Command: Version Strings in CI?

git describe is the standard way to turn commit state into a version like v1.2.0-5-gabc1234. It is a favorite in CI for stamping builds with a meaningful, sortable identifier.

### In CI?

git describe fails with "fatal: No names found" when no tags are present or the clone is too shallow to reach one. Combine --tags --always so it degrades to a SHA, and ensure tags are fetched (fetch-depth: 0 and --tags) so the nearest tag is reachable.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt