Summary command

Home / Commands / summary

commitbrief summary

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

Synopsis

commitbrief summary [<git diff args>...] [--staged | --unstaged] [-o <file>] [provider flags]

With no positional arguments it summarizes the staged diff. Pass git diff arguments to summarize an arbitrary range, exactly like the diff subcommand.

What it does

1. Resolves the scope (staged by default, --unstaged, or a range from positional args) and fetches the diff — the same hybrid git path the review uses.
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.
6. Prints the digest (or writes it to --output <file>).

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.

Scope

Invocation	Summarizes
commitbrief summary	the staged diff (default)
commitbrief summary --unstaged	unstaged working-tree changes
commitbrief summary HEAD	the working tree vs HEAD
commitbrief summary HEAD~3 HEAD	the last three commits
commitbrief summary main feature	one branch vs another
commitbrief summary main...develop	a three-dot, PR-style range

Positional arguments are forwarded verbatim to git diff, so any ref combination git understands works. The commit messages are ingested only when the arguments form a clean two-endpoint range (e.g. main...develop, HEAD~3 HEAD); a bare ref or a -- pathspec produces a diff-only summary with no attribution.

Flags

Flag	Default	Description
-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 (e.g. tr). The digest is written in this language.
-f, --file / -d, --dir	—	Narrow to these files / directories (repeatable).
--provider, --model, --cli	from config	Select the backend, identical to a review. --cli claude|gemini|codex uses a host CLI tool.
--with-context	off	CLI providers only — let the host CLI agent read files beyond the diff to ground the digest. Errors on an API provider. See --with-context.
--no-cost-check, --allow-secrets, --no-cache	off	Same meaning as on a review.
--show-prompt	off	Print the exact prompt that would be sent, then exit (no provider call).

Unlike a commit message, the summary honours --lang — --lang tr yields a Turkish digest.

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.

Examples

# Digest what's staged, grouped by area.
commitbrief summary

# Digest a PR-style range, using the commit messages in it for attribution.
commitbrief summary main...develop

# Write release notes for the last three commits to a file.
commitbrief summary HEAD~3 HEAD -o NOTES.md

# Turkish digest of a range.
commitbrief summary main...develop --lang tr

# Use a host CLI tool as the backend, and let it read beyond the diff.
commitbrief summary main...develop --cli claude --with-context

# See the prompt (including the commit manifest) without calling a provider.
commitbrief summary HEAD~3 HEAD --show-prompt

Relationship to review and commit

• Review 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 guard, secret scan, cost preflight, and cache.

See also

• diff — the git diff passthrough whose argument surface summary mirrors.
• Review — the structured-findings review path.
• Filtering — the ignore and path-filter layers applied to the diff.
• Secret scanner / Cost preflight — the pre-send guards summary shares with reviews.
• Global flags — flags shared with every command.