Review scopes

A review needs a diff. CommitBrief gives you three sources for that diff plus two layers of filtering on top.

The default — staged changes

commitbrief
commitbrief --staged   # explicit
commitbrief -s         # short form

Reviews git diff --cached. This is the default when no scope flag is set — picked because it lines up with the pre-commit moment.

Working-tree changes

commitbrief --unstaged
commitbrief -u

Reviews git diff (working tree vs the index). Useful when you have edits you have not staged yet.

--staged and --unstaged are mutually exclusive — passing both is a cobra-level error before any work begins.

Historic ranges — commitbrief diff

For anything outside the working tree, use the diff subcommand. The positional arguments are forwarded verbatim to git diff --no-color --no-ext-diff <args>, so anything git diff accepts works.

Invocation	Equivalent	What it reviews
commitbrief diff HEAD	git diff HEAD	Working tree vs HEAD.
commitbrief diff HEAD~3 HEAD	git diff HEAD~3 HEAD	The last three commits’ net change.
commitbrief diff main feature	git diff main feature	One branch vs another.
commitbrief diff main...feature	git diff main...feature	Three-dot range — feature’s changes since branching off main (PR style).
commitbrief diff <merge-sha>	git diff <merge-sha>	First-parent diff of a merge commit.
commitbrief diff HEAD -- '*.go'	git diff HEAD -- '*.go'	Filter by git pathspec after --.

At least one positional argument is required.

Path filters — --file and --dir

Repeatable filter flags that compose on top of any scope:

commitbrief --staged -f src/main.go -f src/util.go
commitbrief --unstaged -d database/seeder -d app/Models
commitbrief diff HEAD~3 HEAD --dir docs

• --file <path> (-f) matches a file path exactly (the diff’s b/ path relative to repo root). Renamed files match on either the new path or the old path.
• --dir <path> (-d) matches any file whose path begins with the given directory plus a slash. database/seed does not match database/seedother/*.
• Both flags repeat. Multiple instances are unioned — a file matching any one of them is kept.
• They combine: --file foo.go --dir handlers/ keeps foo.go AND everything under handlers/.

Path filters apply after the ignore layers below.

The three-layer filter pipeline

The full pipeline that decides which files reach the LLM:

1. Built-in ignore patterns — hardcoded into the binary. Lock files (*.lock, go.sum, package-lock.json, …), vendored code (vendor/**, node_modules/**), generated code (*.pb.go, *.gen.go), mocks, build artefacts, editor detritus, and binary blobs (*.png, *.zip, *.pdf).
2. .commitbriefignore — repo-local gitignore-syntax overlay. Drop a file at the repo root. Glob syntax is the same as .gitignore; *, **, and a leading ! to re-include a previously-excluded path all work.
3. --file / --dir path filters from the command line.

Later layers can override earlier ones. To force review on a path the built-in layer would exclude:

# .commitbriefignore
!vendor/**

The ! re-inclusion overrides the built-in vendor/** pattern.

Inspecting filter behavior

commitbrief dry-run reports the per-layer counts:

Files (input): 12
  built-in ignore filtered:        3
  .commitbriefignore net filtered: 1
  --file/--dir path filter:        2
Files (review): 6

A negative .commitbriefignore net filtered means a !pattern reverted a built-in exclusion.

Mutually exclusive scope flags

Cobra enforces these mutex groups before any pipeline work runs:

• --staged × --unstaged
• --provider × --cli
• --cli × --json × --markdown (CLI providers emit pre-formatted plain text; you cannot also ask for JSON)

See also

• Output formats — how findings render once a scope is fixed.
• Severity and CI gating — --fail-on and exit codes.
• Configuration — where flags slot into the broader config surface.