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

Periphery excludes pre-existing results recorded in the baseline and reports newly introduced unused code.

A baselined result is still shown when it must be addressed before new unused code can be removed. For example, if a baselined unused function calls a newly unused function, Periphery shows the caller as a baselined prerequisite. Report filters still apply to both findings and prerequisites.

Pass --always-exclude-baseline-results to hide all baselined findings. Check for remaining callers before deleting code when using this option.

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

The updated baseline keeps existing entries that still match findings, adds newly reported findings, and removes entries that no longer match. Existing findings hidden by report filters stay in the baseline.

Use the same targets and scan configuration when updating a baseline. Entries for code outside the current scan can be pruned because the scan cannot match them.

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.