# info > GIT-DESCRIBE

---
type: CommandReference
command: git-describe
mode: man
section: 1
source: man-pages
---

## Quick Reference
- `git describe` — Describe HEAD using the most recent annotated tag.
- `git describe --tags` — Include lightweight (non-annotated) tags.
- `git describe --all` — Use any ref (branches, tags) instead of only annotated tags.
- `git describe --contains` — Find a tag that contains the commit, not one that predates it.
- `git describe --abbrev=0` — Output only the closest tag name, no suffix.
- `git describe --dirty` — Append `-dirty` if the working tree has local modifications.
- `git describe --long` — Always output the long format (tag, commits count, abbreviated hash).
- `git describe <blob>` — Describe a blob as `<commit-ish>:<path>`.

## Name
git-describe — Give an object a human readable name based on an available ref.

## Synopsis
shell
git describe [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...]
git describe [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]
git describe <blob>
## Options

### Ref Selection
- `--all` — Use any ref in `refs/` namespace (branches, remote-tracking branches, lightweight tags).
- `--tags` — Use any tag in `refs/tags` namespace (lightweight tags included).
- `--contains` — Find a tag that contains the commit (comes after) instead of one that predates it. Implies `--tags`.
- `--match <pattern>` — Only consider refs matching the given glob pattern (excluding `refs/tags/` prefix). If used with `--all`, also matches branches and remote-tracking refs. Repeatable.
- `--exclude <pattern>` — Exclude refs matching the given glob pattern. Works with `--all` similarly. Repeatable. Use `--no-exclude` to clear the pattern list.

### Output Formatting
- `--abbrev=<n>` — Use <n> digits for the abbreviated object name, or as many as needed to form a unique name. A value of 0 suppresses the long format, showing only the closest tag.
- `--long` — Always output the long format (`<tag>-<commits>-g<abbrev>`), even when the commit is exactly a tagged version.
- `--always` — Show uniquely abbreviated commit object as fallback when no tag is found.
- `--dirty[=<mark>]` — Append the suffix `<mark>` (default `-dirty`) if the working tree has local modifications.
- `--broken[=<mark>]` — If the repository is corrupt and local modification status cannot be determined, append `<mark>` (default `-broken`) instead of erroring out.

### Search Behavior
- `--candidates=<n>` — Consider up to <n> most recent tags as candidates. Default is 10. Higher values may produce more accurate results but take longer. 0 outputs only exact matches.
- `--exact-match` — Output only exact matches (tag directly references the commit). Synonym for `--candidates=0`.
- `--debug` — Print searching strategy details to stderr.
- `--first-parent` — Follow only the first parent of merge commits.

## Examples

Describe the current HEAD:
shell
$ git describe
v1.0.4-14-g2414721
Describe a specific commit-ish:
shell
$ git describe parent
v1.0.4-14-g2414721
Describe a tag itself (exact match):
shell
$ git describe v1.0.4
v1.0.4
Use branch heads as reference points:
shell
$ git describe --all --abbrev=4 v1.0.5^2
tags/v1.0.0-21-g975b

$ git describe --all --abbrev=4 HEAD^
heads/lt/describe-7-g975b
Find the closest tag name without any suffix:
shell
$ git describe --abbrev=0 v1.0.5^2
tags/v1.0.0
Show working tree state:
shell
$ git describe --dirty
v1.0.4-14-g2414721-dirty
## See Also
- [git(1)](http://localhost/phpMan.php/man/git/1/markdown)
- [git-tag(1)](http://localhost/phpMan.php/man/git-tag/1/markdown)
- [git-log(1)](http://localhost/phpMan.php/man/git-log/1/markdown)
- [glob(7)](http://localhost/phpMan.php/man/glob/7/markdown)