# git describe: Usage, Options & Common CI Errors

> git describe produces a readable name from the nearest tag, ideal for build versions. Reference for --tags, --always, --dirty, and the no-tag error.

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

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

> `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: Usage, Options & Common CI Errors?

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 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.

---

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