# grit show

> Show a commit, tag or branch, and the change it introduced.

## Synopsis

```text
grit show [<object>…] [--diff-merges first-parent|combined] [--stat | --numstat | --shortstat | --name-only | --name-status] [-U[n]] [-W]
  [--pathspec-from-file <file|->] [--pathspec-file-nul] [-- <path>…]
```

## 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`](https://grit-scm.com/docs/show/cat.md/index.md)) 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`](https://grit-scm.com/docs/show/diff.md/index.md)). |
| `--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). |

## Examples

Show the latest commit with patch (default):

```console
$ grit show
branch feature
commit cf18394a62c3f845bd9c44927a5a55e014b2a99d
change yrwyvtvk
Author: Ada Lovelace <ada@example.com>
Date:   2026-10-07 10:00:00 +0000

    Say hi

## main.rs
**status:** modified

- 1  1
+ 1  2
 context line
- old line
+ new line
```

Show only the diffstat (previous default style):

```console
$ grit show HEAD --stat
```

Show one file from a commit:

```console
$ grit show HEAD~1 -- README.md
```

Show what a tag points at:

```console
$ grit show v0.1
```

Get the subject of a commit:

```console
$ grit show HEAD~1 --json --filter .commit.subject
"Start the project"
```

## JSON output

Schema: [v1](https://grit-scm.com/docs/show/schemas/show/v1.json/index.md)

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`](https://grit-scm.com/docs/README.md/index.md#commit-json-object-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`](https://grit-scm.com/docs/show/diff.md/index.md) `--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[]`.

Example:

```json
{
  "kind": "branch",
  "ref_name": "main",
  "commit": {
    "oid": "83352a61f6715ec3f0a297c6d6150725154fb833",
    "parents": [
      "062ca6e74f5603f4d09063c0f46cd07d8c96e019"
    ],
    "author": {
      "name": "Test",
      "email": "test@example.com",
      "date": "2023-11-14T22:13:20Z"
    },
    "committer": {
      "name": "Test",
      "email": "test@example.com",
      "date": "2023-11-14T22:13:20Z"
    },
    "subject": "second",
    "message": "second",
    "refs": [
      {
        "name": "HEAD",
        "kind": "head"
      },
      {
        "name": "main",
        "kind": "branch"
      }
    ],
    "relative_date": "[TIME_AGO]",
    "change_id": "xzyqzyyzswyupvtlsovyzultryuqzlvk",
    "change_id_stored": true
  },
  "files": [
    {
      "path": "second.txt",
      "status": "added",
      "new_mode": "100644",
      "binary": false,
      "hunks": [
        {
          "old_start": 0,
          "new_start": 1,
          "old_lines": 0,
          "new_lines": 1,
          "lines": [
            {
              "kind": "add",
              "new": 1,
              "text": "second file"
            }
          ]
        }
      ]
    },
    {
      "path": "tracked.txt",
      "status": "modified",
      "old_mode": "100644",
      "new_mode": "100644",
      "binary": false,
      "hunks": [
        {
          "old_start": 1,
          "new_start": 1,
          "old_lines": 1,
          "new_lines": 1,
          "lines": [
            {
              "kind": "del",
              "old": 1,
              "text": "tracked v1"
            },
            {
              "kind": "add",
              "new": 1,
              "text": "tracked v2"
            }
          ]
        }
      ]
    }
  ],
  "stat": {
    "files": [
      {
        "path": "second.txt",
        "status": "added",
        "insertions": 1,
        "deletions": 0,
        "binary": false
      },
      {
        "path": "tracked.txt",
        "status": "modified",
        "insertions": 1,
        "deletions": 1,
        "binary": false
      }
    ],
    "files_changed": 2,
    "insertions": 2,
    "deletions": 1
  }
}
```

## Markdown output

Schema: [v1](https://grit-scm.com/docs/show/schemas/show/v1.json/index.md)

Pass [`--markdown`](https://grit-scm.com/docs/global-options/index.md) for headings, commit metadata, the message body in a length-adaptive `text` fence (so commit text cannot forge grit headings or tables), and fenced `diff` blocks per file (or a diffstat table with `--stat`):

```text
# Commit `b52cca6`

**Oid:** `92501f188ae0815af09a0cef6e121eddda4113cf`
**Change:** `yrwyvtvk`
**Author:** Ada Lovelace <ada@example.com>
**Date:** 2026-10-07T14:54:02Z

## second

~~~diff
@@ -1,1 +1,2 @@
 line
+added
~~~
```


With no commits on the current branch yet, default `HEAD` fails with `branch_no_commits`:

```console
$ grit show
error: no commits yet on branch main — make one with `grit commit "message"`
hint: make one with `grit commit "message"`
```

## Exit status

| Code | Meaning |
| ---: | --- |
| `0` | Success ([`success`](https://grit-scm.com/docs/exit-codes/index.md)). |
| `1` | Command failed ([`failure`](https://grit-scm.com/docs/exit-codes/index.md)). |
| `2` | Invalid flags or arguments ([`usage`](https://grit-scm.com/docs/exit-codes/index.md)). |

See [Exit codes](https://grit-scm.com/docs/exit-codes/index.md) for shared rules and structured `--json` `kind` values.


## See also

- [`grit diff`](https://grit-scm.com/docs/show/diff.md/index.md) — compare commits, ranges, or the working tree without commit metadata.
- [`grit log`](https://grit-scm.com/docs/show/log.md/index.md) — list recent commits.
