Install
// docs · v1.x

Review scopes

How to scope a CommitBrief review — staged, unstaged, arbitrary diff ranges, path filters, and the three-layer ignore pipeline.

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.

Glob patterns (v1.7.0)

Both flags also accept gitignore-style glob patterns, not just exact paths (ADR-0026). A value containing *, ?, or [ is compiled as a glob; the slash decides how it anchors:

  • Slash-less patterns match the basename at any depth — --file '*.go' keeps every changed .go file, anywhere in the tree.
  • Slash-bearing patterns are anchored to the repo root — --file 'internal/**/*.ts' matches only under internal/, and --dir 'app/**' scopes to the app/ subtree.
commitbrief --staged --file '*.go'                 # any Go file, any depth
commitbrief --staged --file 'internal/**/*.ts'     # root-anchored
commitbrief diff main...feature --dir 'app/**'     # globbed directory scope

Quote the pattern so your shell doesn’t expand * before CommitBrief sees it.

Backward compatible: a value with no glob metacharacter keeps its exact pre-v1.7 behavior — --file src/main.go still matches that one path (and its rename pair). An invalid glob errors clearly up front instead of silently mis-filtering.

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