gritHEAD → docs/describe
Commands / HistoryMarkdown

grit describe

Nearest reachable tag, exact commit distance, and abbreviated id for a revision.

grit describe [REV] [--tags] [--match GLOB] [--first-parent] [--abbrev N]

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.