Configuration

Diff Guardian uses a single JSON configuration file at the root of your project. All fields are optional — the tool works with zero configuration out of the box.

Config file

The configuration file is dg.config.json in your project root. Create it manually or run npx dg init to scaffold it.

Full reference

{
  "baseBranch": "main",
  "failOnWarnings": false,
  "enableTracer": true,
  "maxGrepResults": 500,
  "maxBarrelDepth": 10,
  "maxTracerFiles": 100
}

Options

baseBranch

The default branch used as the base ref when running npx dgin smart default mode (no command specified). Diff Guardian auto-detects the default branch by querying git remote show origin, but this field overrides that behavior.

failOnWarnings

When enabled, warning-level changes (e.g., return type widened, default value changed) will also cause exit code 1. Useful for teams that want strict API stability guarantees.

enableTracer

Enable or disable the call-site tracer. When disabled, breaking changes are still detected, but the report will not show affected call sites. Useful for very large repos where tracing is too slow.

maxGrepResults

Maximum number of files returned by git grepper symbol during the tracing phase. If a symbol name is very common (e.g., "get"), this prevents the tracer from scanning thousands of files.

maxBarrelDepth

Maximum depth for following barrel re-export chains (e.g., index.tsfiles that re-export from other index files). Prevents infinite loops in circular re-exports.

maxTracerFiles

Maximum number of importer files to AST-parse for call-site analysis per symbol. Caps the work done by the tracer for extremely popular symbols.

Related

• dg init — scaffold this config file
• dg trace — uses tracer settings