Install
// docs · v1.x

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 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

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 scope.

Output shape

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

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).
--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) critiques the change — structured findings, severity, CI gating.
  • 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