Description
Shows a commit's id, author, date and full message, followed by the change that commit introduced (delta-style patch by default, like grit diff <commit>). With no argument, it shows the current commit.
<object> can be a commit id (full or short), an expression like HEAD~2, a branch or a tag. For a branch or tag, the first line names it. For an annotated tag, the tag's own author, date and message come before the commit it points at.
Merge commits default to combined parent diffs (--diff-merges=combined, like git show --cc). Use --diff-merges=first-parent for a diff against the first parent only.
Pass several <object> values to show more than one commit (human and markdown output are concatenated). With --json, multiple objects are wrapped as { "objects": [ … ] }; a single object keeps the usual top-level shape.
revision:path specs (same resolution as grit cat) show blob contents or list tree entries without commit metadata.
Use --stat (or other diff format flags below) instead of the default patch. Limit output to paths with -- <path>… after the commit arguments.
In a shallow clone, a commit listed in .git/shallow is diffed like a root (against the empty tree), even when its object still names a missing parent.
Options
| Option | Description |
|---|---|
<object>… |
Commits, branches, tags, or rev:path specs. Defaults to HEAD. |
--diff-merges |
combined (default) or first-parent for merge commits. |
-p, --patch |
Full patch (the default). |
--patch-text |
Git-apply-compatible unified patch on stdout (git diff --binary shape): branch or tag metadata (when present), commit metadata, then diff --git / index / hunks. Preserves this order when stdout is piped or redirected. Honors trailing pathspecs. Merge commits omit the patch unless --diff-merges=first-parent. Human output only; not combinable with --json or --markdown. |
-W, --function-context |
Expand patch hunks to enclosing function boundaries (same as grit diff). |
--stat |
Summary with change bars per file instead of a full patch. |
--numstat |
Machine-readable insertions<TAB>deletions<TAB>path lines. |
--shortstat |
Only the summary line (N files changed, …). |
--name-only |
Changed paths, one per line. |
--name-status |
Status letter and path(s) per line. |
-p, --patch |
Unified patch (default when no other format flag is set). |
-U, --unified <n> |
Lines of context around each change in patch mode (bare -U means 3). |
-W, --function-context |
Expand hunks to enclosing function boundaries (patch mode). |
-p, --patch |
Unified patch output (default when no other format flag is set). |
--pathspec-from-file <file|-> |
Read pathspecs from a file (- for stdin), in addition to argv paths after --. |
--pathspec-file-nul |
--pathspec-from-file entries are NUL-separated. |
-- <path>… |
Limit the diff to these paths (pathspecs). |
JSON output
Schema: v1
Pass --json for stable, scripting-friendly output:
| Field | Type | Meaning |
|---|---|---|
objects |
array | When more than one <object> is requested: each element is a commit show object or a rev:path blob/tree object (below). |
warnings |
array | Non-fatal diagnostics emitted while resolving the object; omitted when empty. |
kind |
string | For a commit, branch, tag, or annotated tag: commit, branch, tag, or annotated_tag. For rev:path: blob or tree. |
ref_name |
string | Branch or tag name when you named a ref; omitted for a raw commit id. |
tag |
object | For an annotated tag: name, tagger, and message. |
commit |
object | Shared CommitJson row: oid, parents, author, committer, subject, message, ref decorations, change_id, and change_id_stored. |
files |
array | Per-file diff rows (same shape as grit diff --json), including optional combined_status (MM, DD, …) on combined merge name-status output. |
totals |
object | Aggregate line counts when a stat-style format is selected; omitted for patch-only output unless the library computed totals. |
stat |
object | Summary diffstat with files, files_changed, insertions, and deletions (always present on commit shows). |
spec |
string | For rev:path: the object spec you passed (for example HEAD:README.md). |
path |
string | For rev:path: repository-relative path after the first revision colon. |
oid |
string | For rev:path: object id of the blob or tree. |
size |
integer | For rev:path: uncompressed object size in bytes. |
text |
string | For a text blob at rev:path; omitted for binary blobs. |
data_base64 |
string | For a binary blob at rev:path; standard base64 of raw bytes. |
binary |
boolean | For rev:path blobs: true when data_base64 is used instead of text. |
entries |
array | For rev:path trees: mode, type, oid, and path per entry. |
Combined merge hunks may attach a parents array on each patch line in files[].hunks[].lines[].
Markdown output
Schema: v1
Exit status
See Exit codes for shared rules and structured --json kind values.