Description
Finds the nearest tag reachable from REV (default HEAD) and reports the exact number of commits in the range from the tag’s peeled commit to REV. Output uses the long form tag-distance-gabbrev (including -0- when REV is exactly the tag commit).
By default only annotated tags are considered; --tags includes lightweight tags. The distance is the exact peeled..REV count (what grit revs --count reports), which can differ from Git’s lazy git describe depth and from which tag Git picks when many tags are reachable.
Options
| Option | Description |
|---|---|
REV |
Commit or ref to describe (default HEAD). |
--tags |
Include lightweight tags (default: annotated only). |
--match GLOB |
Only consider tags whose short name matches GLOB. |
--first-parent |
Count distance along first-parent chains only. |
--abbrev N |
Minimum abbreviated commit id length (default follows core.abbrev, extending on collision like Git). |
JSON output
Schema: v1
Pass --json for stable, scripting-friendly output:
| Field | Type | Meaning |
|---|---|---|
tag |
string | Full refs/tags/… name. |
tag_short |
string | Short tag name. |
tag_oid |
string | Object id at the tag ref. |
peeled |
string | Peeled commit oid. |
distance |
integer | Exact commits in peeled..commit. |
commit |
string | Described commit oid. |
abbrev |
string | Abbreviated commit oid. |
long_format |
string | tag-distance-gabbrev line. |
Markdown output
Schema: v1
Pass --markdown for a short heading and bullet list of the tag, distance, and abbrev.
Exit status
| Code | Meaning |
|---|---|
0 |
Success. |
1 |
No reachable tag, or other failure. |
2 |
Invalid flags (usage). |
See Exit codes.