dg compare

Compare two git refs — branches, tags, or commit SHAs — and detect every structural API change between them.

Usage

npx dg compare <base> [head]

base is required. head defaults to HEAD if omitted.

Examples

# Compare current branch against main
npx dg compare main

# Compare two specific branches
npx dg compare main feature/payments

# Compare two release tags
npx dg compare v1.0.0 v2.0.0

# Compare last 3 commits
npx dg compare HEAD~3 HEAD

# Compare a specific commit SHA
npx dg compare abc1234 def5678

How it works

The compare command runs the full 4-phase pipeline:

Extracts full source from both base and head for every changed file
Parses both sides into ASTs using the appropriate WASM Tree-Sitter grammar
Classifies every signature difference using the rule engine
Traces call sites for any breaking changes found

Smart default mode

If you run npx dg with no command at all, Diff Guardian auto-detects your environment:

Environment	Behavior
GitHub Actions (`GITHUB_ACTIONS=true`)	Compares PR base to head SHA. Posts a PR comment. Always exits 0 (advisory).
Local terminal	Compares the default branch (main/master) to HEAD. Terminal output. Strict mode.

Exit codes

Code	Meaning
`0`	No breaking changes found.
`1`	Breaking changes detected (strict mode).
`2`	Pipeline infrastructure error.

Example output

$ npx dg compare main feature/payments

  Diff-Guardian API Analysis
  Base: main -> Head: feature/payments
  ────────────────────────────────────────

  [BREAKING] Changes (2)

  > processPayment (signature_change)
    src/api/payments.ts:42
    R01: Parameter 'currency' was removed.
    Affected call sites (3):
      X  src/checkout/handler.ts:18 -- provides 3 arg(s), needs 2
      OK src/invoices/gen.ts:31 -- Fixed by developer in this PR
      . 1 other call site(s) have correct arguments

  > UserConfig (interface_property_removed)
    src/types/config.ts:8
    R26: Property 'timeout' was removed from interface.

  ────────────────────────────────────────
  [STRICT MODE]
  2 breaking changes found. Exiting with code 1.

dg check — analyze uncommitted changes
CI/CD Integration — auto-run compare on PRs
How It Works — full pipeline explained