Baselines

Introducing Periphery to an established codebase often surfaces a large number of results. Fixing them all before you can start using Periphery in CI isn’t always practical. A baseline records the results that exist today, excluding them from future scans so that only newly introduced unused code is reported.

Writing a Baseline

periphery scan --write-baseline baseline.json

The scan runs as normal and reports its results, and additionally writes them to baseline.json. Commit this file to source control.

Using a Baseline

Pass the same file to --baseline on subsequent scans:

periphery scan --baseline baseline.json

Results recorded in the baseline are now excluded. Anything reported is unused code introduced since the baseline was written.

What you do with the remaining results is up to you. If you’d like a non-zero exit status when any are reported, combine the baseline with --strict, so that only results introduced since the baseline was written affect the exit status:

periphery scan --baseline baseline.json --strict

Updating a Baseline

Passing both options together updates the baseline in place:

periphery scan --baseline baseline.json --write-baseline baseline.json

Caution

When both options are given, the new baseline is the union of the existing baseline and the current results. Entries are never removed, so a baseline updated this way only ever grows, and will retain entries for declarations you’ve since deleted.

To discard stale entries, regenerate the baseline from scratch by passing only --write-baseline.

Regenerating the baseline from scratch periodically — and after any large refactor — keeps it an accurate record of the remaining unused code.

How Results Are Matched

Declarations are matched by their identity — module, enclosing context, and name — rather than by file and line number, so moving code between files won’t cause baselined results to reappear. Renaming a declaration, or moving it to a different type or module, changes its identity, and it will be reported as a new result.