Review before you commit

The cheapest place to catch a bug is before it becomes a commit. There are two ways to get CommitBrief in front of a change at that point: run it yourself, once, right before git commit — or install a hook so it happens automatically, every time.

Run it by hand

Stage the change, then review it:

git add .
commitbrief --staged

--staged is the default scope, so a bare commitbrief does the same thing. See Review scopes for the other scopes (--unstaged, historic ranges via diff).

If you want the same pass/fail gate a hook gives you, add --fail-on:

commitbrief --staged --fail-on=critical

A non-zero exit means at least one finding met the threshold — fix it (or decide it’s fine and move on) before you commit. The full value table and exit-code semantics are in Severity and CI gating.

Install a hook so you don’t have to remember

commitbrief install-hook

This writes .git/hooks/pre-commit, a script that runs

commitbrief --staged --fail-on=critical --quiet --no-cost-check

on every commit and blocks it if a critical-severity finding turns up. --hook=commit-msg and --hook=pre-push install the same idea at a different point in the git flow; the full flag list, conflict handling, and how it finds the commitbrief binary from inside a GUI git client are in Git hooks.

The bundled hook body is fixed at --fail-on=critical — it isn’t a flag you can override on install-hook itself. If you want a different threshold, skip the scaffolder and point your own .git/hooks/pre-commit at commitbrief --staged --fail-on=<severity> --quiet directly.

Already using the pre-commit framework to manage hooks? CommitBrief ships hook ids for it too (commitbrief / commitbrief-system) instead of install-hook writing into .git/hooks/ directly — see pre-commit framework integration. Pick one approach per repo; don’t run both against the same hook.

Why --no-cost-check and --quiet

A hook runs unattended — there’s no one at the keyboard to answer the cost preflight prompt CommitBrief would otherwise show on an expensive diff, and a chatty splash/progress UI is noise on every single commit. Both are already baked into the generated hook body; you only need to think about them if you’re wiring up your own command instead.

A new repo, or a legacy one?

On a repo CommitBrief has never seen, the first --staged run reviews exactly what you staged — there’s nothing to filter yet. On a large existing codebase you’re adopting CommitBrief into, a first review can surface a pile of pre-existing findings that have nothing to do with your current change. Brownfield adoption covers baselining that noise away before you turn a hook on.

See also

• Git hooks — the full install-hook reference: flags, conflict handling, uninstalling.
• Severity and CI gating — what --fail-on values mean and which exit code each produces.
• Safety, cost, and cache — the cost preflight and secret scanner --no-cost-check and --allow-secrets opt out of.
• Brownfield adoption — quiet pre-existing findings before gating a legacy repo.