# Summarize changes — summary

> commitbrief summary explains a set of changes in plain language — a read-only digest grouped by logical area, attributed to the short commit hash for a range.

CommitBrief docs · v1.x · Reviewing

Canonical URL: https://commitbrief.com/docs/1.x/summary

---

`commitbrief summary` explains a set of changes in plain language — a
short, human-readable digest of *what* changed and, when the commit
messages make it clear, *why*, grouped by logical area rather than file
by file. It is **read-only** and produces **no findings** (no severity,
no JSON, nothing to gate CI on); the provider returns prose that is
printed as-is.

Added in v1.6.0. See ADR-0020.

## Usage

```sh
commitbrief summary                         # digest the staged diff
commitbrief summary --unstaged              # digest unstaged working-tree changes
commitbrief summary main...develop          # digest a range (git-diff passthrough, like diff)
commitbrief summary HEAD~3 HEAD             # digest the last three commits
commitbrief summary main...develop -o RELEASE.md   # write the digest to a file
commitbrief summary main...develop --lang tr       # Turkish digest
```

With no positional arguments it summarizes the staged diff (`--unstaged`
for the working tree). Pass `git diff` arguments to summarize an
arbitrary range, exactly like the [`diff`](/docs/1.x/review-scopes)
scope.

## Output shape

One line per logical area, ordered from most to least significant:

```text
Invoice Service: Rounding bug in fee calculation fixed. (a1b2c3d)
Auth: Token refresh flow added. (d4e5f6a)
DB: Index added to the invoices table. (f7a8b9c)
```

The parenthesised tag is the **short commit hash(es)** responsible for
that area, taken from the range's commit log. Attribution is always the
commit hash — never a branch name, which a squash- or rebase-merged
history would not preserve. Staged and unstaged changes have no commits
yet, so their lines carry no attribution.

## What it does

1. Resolves the scope (staged by default, `--unstaged`, or a range from
   positional args) and fetches the diff.
2. Filters the diff through the built-in and `.commitbriefignore` layers
   (and any `--file` / `--dir` filters) so generated/noise files don't
   dominate.
3. **For a range**, reads the commit messages in that range (`git log`,
   read only) — short hash, subject, body, and the files each commit
   touched — to ground and attribute the summary.
4. Runs the pre-send `.commitbrief/**` guard, the secret scan, and the
   cost preflight on the diff — exactly as a review does.
5. Asks the configured provider for the digest in a single call, then
   prints it (or writes it to `--output <file>`).

## Flags

| Flag | Default | Effect |
|------|---------|--------|
| `-s, --staged` / `-u, --unstaged` | `--staged` | Scope, when no positional range is given. Mutually exclusive. |
| `-o, --output <file>` | stdout | Write the digest to a file instead of stdout. |
| `--lang <code>` | from config | Output language. The digest is written in this language (e.g. `--lang tr`). |
| `-f, --file` / `-d, --dir` | — | Narrow to these files / directories (repeatable; exact path or glob). |
| `--exclude-file` / `--exclude-dir` | — | Remove from that set (v1.15.0). Applied after the allowlist, so an exclusion wins. |
| `--author` / `--committer` / `--start-date` / `--end-date` / `--text` | — | [Commit filters](/docs/1.x/review-scopes#commit-filters-v1150) (v1.15.0). Any of them digests a *set of commits* instead of the index — `commitbrief summary --author alice --start-date 2026-06-01` is a plain-language "what did Alice ship this quarter". |
| `--with-context` | `false` | CLI providers only — let the host CLI agent read files beyond the diff to ground the digest. Errors on an API provider. |

Inherited globals that apply: `--provider` / `--model` /
`--cli`, `--no-cache`, `--allow-secrets`, `--no-cost-check`,
`--verbose` / `--quiet`, `--show-prompt`.

## Rejected flags

`summary` emits prose, not findings, so the findings-oriented flags are
rejected with a clear message rather than silently ignored:

- `--json`, `--markdown` — there is no findings envelope to serialize.
  Use `--output` to capture the plain text to a file.
- `--suggest-commit`, `--fail-on`, `--min-severity` — there are no
  findings to act on.

## How it compares

- A **review** ([default command](/docs/1.x/first-review)) *critiques*
  the change — structured findings, severity, CI gating.
- [`commit`](/docs/1.x/commit) *authors* a commit message for the staged
  index and writes to git.
- `summary` *narrates* an arbitrary range for a human reader, read-only.

All three share the provider selection, pre-send guards, and cache.

## See also

- [Review scopes](/docs/1.x/review-scopes) — the `git diff` argument surface `summary` mirrors.
- [Safety, cost, and cache](/docs/1.x/safety-and-cost) — the pre-send guards `summary` shares with reviews.
- [Providers](/docs/1.x/providers) — picking the backend with `--provider` / `--cli` and `--with-context`.