# Review before you commit

> Catch a defect before it lands in history — run a review by hand right before you commit, or install a hook that runs it for you on every commit.

CommitBrief docs · v1.x · Guides

Canonical URL: https://commitbrief.com/docs/1.x/pre-commit-review/

---

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:

```sh
git add .
commitbrief --staged
```

`--staged` is the default scope, so a bare `commitbrief` does the same
thing. See [Review scopes](/docs/1.x/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`:

```sh
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](/docs/1.x/severity#the---fail-on-flag).

## Install a hook so you don't have to remember

```sh
commitbrief install-hook
```

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

```sh
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](/docs/1.x/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](https://pre-commit.com) 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](/docs/1.x/git-hooks#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](/docs/1.x/safety-and-cost#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](/docs/1.x/brownfield-adoption)
covers baselining that noise away before you turn a hook on.

## See also

- [Git hooks](/docs/1.x/git-hooks) — the full `install-hook` reference:
  flags, conflict handling, uninstalling.
- [Severity and CI gating](/docs/1.x/severity) — what `--fail-on`
  values mean and which exit code each produces.
- [Safety, cost, and cache](/docs/1.x/safety-and-cost) — the cost
  preflight and secret scanner `--no-cost-check` and `--allow-secrets`
  opt out of.
- [Brownfield adoption](/docs/1.x/brownfield-adoption) — quiet
  pre-existing findings before gating a legacy repo.