Getting Started

Diff Guardian is a CLI that parses your git diffs into abstract syntax trees, classifies every structural change, and traces call sites to show you exactly what breaks. This guide will have you running your first analysis in under two minutes.

Requirements

  • Node.js 18 or higher
  • A git repository with at least two branches (or commits) to compare
  • npm, yarn, or pnpm

1. Install

Install Diff Guardian as a dev dependency in your project. This gives you access to both the diff-guardian and the shorthand dg binary.

npm install --save-dev diff-guardian

2. Initialize

Run the init command to scaffold two files into your project:

npx dg init

This creates:

  • .github/workflows/diff-guardian.yml — a GitHub Actions workflow that runs Diff Guardian on every pull request and posts a comment with the results.
  • dg.config.json — a minimal configuration file with sensible defaults.

If either file already exists, the init command will skip it and tell you.

dg.config.json
{
  "baseBranch": "main",
  "failOnWarnings": false
}

3. Run your first analysis

The fastest way to see Diff Guardian in action is the check command. It analyzes your uncommitted changes against HEAD:

npx dg check

If you have staged changes (git add), you can analyze only those:

npx dg check --staged

To compare two branches (e.g. your feature branch against main):

npx dg compare main

4. Understanding the output

Diff Guardian prints a structured report to your terminal. Each detected change is categorized into one of three severity levels:

SeverityLabelMeaning
BREAKINGRedCallers will fail at runtime or compile time. Requires action.
WARNINGYellowNon-breaking but worth reviewing (e.g., return type widened).
SAFEGreenHarmless API expansion (e.g., new function added).

For breaking changes, Diff Guardian also traces call sites — showing you every file that imports the broken symbol and whether the caller has the correct number of arguments. This is powered by the Lazy Graph Engine.

What is next