Signal control — baseline and suppression
Cut repeat noise without hiding findings from review — a user-private baseline that accepts a brownfield repo's existing findings, plus inline commitbrief-ignore comments with a visible reason.
A reviewer that re-reports the same pre-existing findings on every
run is a reviewer you start ignoring. Signal control gives you two
ways to drop findings you’ve already triaged — a baseline for
“accept everything this brownfield repo already has” and an inline
// commitbrief-ignore comment for “this one specific finding is
fine” — without ever hiding a finding from the next reviewer.
Both are true removals, not display filters: a dropped finding no
longer counts toward --fail-on and no longer
appears in --json findings[].
That makes them stronger than --min-severity — see
How this differs from --min-severity
below. And neither is silent: every removal is counted and reported.
Baseline
A baseline records the findings already present in your repo so that subsequent runs show only new ones. It’s the answer to “I just pointed CommitBrief at a 200k-line legacy repo and got 90 findings I already know about.”
Recording a baseline
commitbrief --update-baseline
This runs a review and writes the current findings to
.commitbrief/baseline.json instead of failing on them. From the
next run on, anything in the baseline is dropped from the output, and
only findings not in the baseline surface.
It’s user-private — it cannot hide a bug from review
.commitbrief/baseline.json is per-developer and gitignored
(commitbrief setup --local and the review cache add .commitbrief/
to .gitignore; writing the baseline does not, so with --no-cache on a repo that never ran setup --local the file is not ignored until one of them runs). Once ignored, it is never committed and never propagates:
- CI still sees everything. A CI runner has no baseline file, so it reviews the full diff — the baseline can’t weaken the gate.
- The next reviewer still sees everything. Their checkout has no baseline either, or has their own.
So a baseline is local convenience only. A teammate cannot bake a bug into a shared baseline to slip it past review, because there is no shared baseline to bake it into. It quiets repeat noise for you without lowering the bar for anyone else.
Fingerprinting — survives code drift
Requires v1.19.0 or later. A baselined finding is identified by its
fingerprint: a SHA-256 of
file + rule id + enclosing symbol. Line number,
title and severity are deliberately not part of it. Adding ten lines
above a baselined finding shifts its line but not its fingerprint, and
a model rewording the title between runs does not resurrect it. The
symbol is the function or method the finding sits in, taken from git’s
funcname rule for the hunk.
The file is .commitbrief/baseline.json, shape
{"version":2,"fingerprints":[...]}, sorted. --update-baseline
always writes this form and replaces the file rather than merging.
The identity is coarse by design. It ignores the title, so
baselining one finding also hides a later, different finding with the
same file, rule and symbol. A finding with no symbol (typically
general.other) hides every finding of that rule in that file. If that
is too wide, fix the finding or use an inline marker
on the one line.
Upgrading a v1 baseline
A baseline written by an older binary ("version": 1) is still read, using
the old file + severity + title formula, and CommitBrief prints a
one-time warning. The migration is lossy: the old entries carry no rule
id or symbol, so they cannot be converted. Re-run --update-baseline
over the same range to write a v2 file. Any other version value is a
hard error.
Turning it off
# Per-run: ignore the baseline for this invocation (review everything).
commitbrief --staged --no-baseline
# Per-config: disable baseline reads entirely.
review:
baseline: false # default true; --no-baseline is the per-run equivalent
commitbrief config set review.baseline false
With review.baseline: false the file is ignored on read; it still
exists on disk until you remove it.
Inline suppression
When a single finding is a known false positive — or an accepted trade-off you don’t want re-flagged — drop a comment on the same line (or on the line directly above it):
const id = items[0].id; // commitbrief-ignore: list is guaranteed non-empty here
That line’s findings are removed from the output. Scope the suppression to one severity with a bracket:
eval(userInput); // commitbrief-ignore[high]: sandboxed; tracked in TICKET-123
commitbrief-ignore[high]: … drops only high-severity findings on
that line; a critical finding on the same line still surfaces. A
bare commitbrief-ignore: … drops findings of any severity.
Scoping to a rule
Requires v1.19.0 or later. A token with a dot is a rule id or a category glob:
query := "SELECT * FROM t WHERE id=" + id // commitbrief-ignore[sec.injection]: id is an int from our own router
// commitbrief-ignore[perf.*]: hot path measured, see TICKET-456
| Token | Drops |
|---|---|
| none | Every finding on the line |
high (no dot) | That severity only |
sec.injection | That rule id only |
perf.* | Every rule in that category |
An unrecognised token does not fail the run. The marker falls back to
unscoped, which drops everything on the line, and CommitBrief prints a
warning so a typo is visible. Any commitbrief-ignore[token]: line
counts as a marker, including [todo-1].
Markers are read from the added lines of the diff and keyed by file and line. Older versions let a marker leak across files; findings that were wrongly suppressed that way reappear after upgrading.
In remote pr
Requires v1.21.0 or later. remote pr
applies inline suppression too, including the --no-post preview. A
suppressed finding posts no comment and its open thread is resolved on
the next run; --fail-on under --no-post judges the findings that
remain. The baseline is not applied there, because it is user-private
and absent in CI.
The reason is recommended and visible
The : reason is part of the documented syntax (an empty reason
still suppresses, but write one) and lands in the diff the next
reviewer reads — so a suppression is never a silent override. It’s a
note to the human reviewer explaining why this is fine, sitting
right next to the code, reviewable like any other line. A suppression
with no justification is one a reviewer can push back on in the same
PR.
How this differs from --min-severity
It’s easy to confuse three things that all “make a finding go away.” They are not the same:
| Mechanism | Removes the finding? | Affects --fail-on / --json? | Scope |
|---|---|---|---|
--min-severity | No — display only | No (the finding still counts and still appears in --json) | Per run |
| Baseline | Yes — true removal | Yes | User-private, persists across runs |
Inline commitbrief-ignore | Yes — true removal | Yes | One line, lives in the code |
--min-severity only hides lower-severity
findings from the rendered view; they still count toward CI gating and
still show up in JSON. Signal control genuinely removes the finding
from the result. Reach for the baseline or a commitbrief-ignore
comment when you want a finding gone from the gate, not just out of
sight.
Removals are reported, never silent
Whatever you drop, CommitBrief tells you it dropped it:
-
A one-line stderr footer summarizes the run:
3 baselined · 1 suppressed -
The
--jsonpayload carries additive optionalmeta.baselinedandmeta.suppressedcounts. These are additive — the JSON schema stays v1, so existing consumers are unaffected and new ones can read the counts:{ "meta": { "baselined": 3, "suppressed": 1 }, "findings": [ ... ] }
You always know how many findings were held back, even though the findings themselves are gone from the list. That visibility is the point: signal control trims noise loudly.
See also
- Adopting CommitBrief on an existing codebase — a guided walkthrough of baselining a legacy repo.
- Severity and CI gating —
--fail-on,--min-severity, and how removed findings change the exit code. - Output formats — the JSON schema v1 and
where
meta.*counts live. - Review rules —
COMMITBRIEF.md, the other way to steer what gets flagged. - Configuration —
review.baselinein the config reference.