gritHEAD → docs/resolve
Commands / PlumbingMarkdown

grit resolve

Resolve revision specs to object ids and types.

grit resolve [--short] [--abbrev-ref | --symbolic-full-name] [--verify <SPEC> [-q]] <SPEC>...

Description

Resolves one or more revision specs to an object id, plus the object type and uncompressed size. Type and size follow git cat-file semantics, including refs/replace when replace refs are enabled (honor GIT_NO_REPLACE_OBJECTS to read the stored object instead). Supported forms match the library rev-parse surface: branches and tags, HEAD~n, peel suffixes such as ^{tree}, path suffixes such as main:path/file, reflog selectors like main@{1} or HEAD@{yesterday} (date text uses the same relaxed grammar as grit log --since, for example yesterday, last week, noon yesterday, Oct 27, 10/27/2026), abbreviated object ids, and change ids (reverse-hex tokens in k–z, 4–32 characters — stored header or derived id). See Change ids — Revisions. When a date selector is older than every reflog entry, grit resolves to the oldest entry and emits a warning (same behavior as Git).

Each spec prints on its own line as OID TYPE (full hex by default). With --short, oids are abbreviated using the same uniqueness rules as elsewhere in grit.

The :/<text> message search resolves to the youngest matching commit by committer date among all commits reachable from any ref (including HEAD), not merely the first match walking back from one branch tip.

With --abbrev-ref or --symbolic-full-name, output switches to ref names (one line per spec): the shortest unambiguous short name, or the full symbolic ref name, matching git rev-parse for the same flags. Specs that are not refs (commit oids, peeled objects, unknown names) produce no line for that spec; exit status stays 0 unless a spec fails for another reason (for example @{u} with no upstream).

With --verify <SPEC>, exactly one spec is resolved strictly (like git rev-parse --verify): revision ranges (A..B, A...B), revision-set excludes (^ref), and other multi-revision forms are rejected with a typed error. Full hex ids must exist in the object database, and peel suffixes such as ^{commit} are honored. Clap rejects extra positional specs when --verify is used (usage exit 2). Success prints one object id line (abbreviated when --short is set). Combine with -q / --quiet to suppress all stdout and stderr and answer with exit status only (0 = exists, 1 = not). --json --quiet prints nothing; the exit code alone answers.

Options

Option Description
<SPEC>… One or more revision specs to resolve (required).
--short Print abbreviated object ids instead of full hex.
--abbrev-ref Print the shortest unambiguous ref name for each spec (conflicts with default oid output).
--symbolic-full-name Print the full symbolic ref name for each spec.
--verify <SPEC> Resolve one spec strictly (git rev-parse --verify); conflicts with ref-name modes and extra positionals.
-q, --quiet With --verify, suppress stdout and stderr; exit 0 or 1 only.

JSON output

Schema: v1

Pass --json for stable, scripting-friendly output:

Field Type Meaning
warnings array Non-fatal warnings collected while resolving.
results array One entry per input spec.
results[].spec string Input spec.
results[].oid string Resolved object id (abbreviated when --short is set).
results[].kind string blob, tree, commit, or tag.
results[].size number Uncompressed object size in bytes.
results[].ref_name string In oid mode: short ref name when the spec named a ref (for example main for HEAD). In ref-name modes: the printed ref line (abbrev or full, matching the active flag).
results[].full_ref string Full symbolic ref when the spec named a ref (for example refs/heads/main).
results[].ref_display string Same as ref_name in ref-name modes (stable alias for scripts).
results[].oid / kind / size Required in default oid mode; omitted in ref-name modes.

Markdown output

Schema: v1

Pass --markdown for a table of resolved specs, oids, kinds, and sizes.

Exit status

Code Meaning
0 Every spec resolved (default mode), or --verify / --verify --quiet resolved the spec.
1 At least one spec failed, or --verify / --verify --quiet could not resolve the spec.
2 Invalid flags (usage), or --verify with zero or multiple specs.

See Exit codes.