diff
Compare export surfaces between refs. Default: HEAD → working tree.
By default diff is informational — exit 0 even when exports were removed. Use opt-in fail flags for CI gates on a frozen 1.x surface.
expgov diff
expgov diff HEAD
expgov diff v0.1.3..v0.1.4
expgov diff HEAD~30..HEAD~1
expgov diff v1.0.0..HEAD --fail-on-removed
expgov diff v1.0.0..HEAD --fail-on-removed --fail-on-tier-violations
expgov diff v1.0.0..HEAD -v -j
expgov diff v1.0.0..HEAD -F -jRef ranges
| Form | Meaning |
|---|---|
older..newer | Snapshot at older vs snapshot at newer — order matters |
(omit) / default | HEAD → working tree |
single ref v0.1.4 | v0.1.4 → working tree |
Diff-only — timeline time ranges (@4w, ISO dates) are not supported here.
Reports added/removed flat exports and tier violations (internal/advanced promoted to root).
With --json, -v or -F also adds data.addedDetail / data.removedDetail (tier, category, symbolKind, targetSubpath, module) under the same -T/-F list policy. Name arrays added / removed stay complete for CI gates — only the detail rows truncate. See JSON output.
Fail flags (CI)
| Flag | Behavior |
|---|---|
--fail-on-removed | Exit 1 when any flat export was removed |
--fail-on-tier-violations | Exit 1 when the right-side snapshot has tier violations |
| (neither) | Always exit 0 — report only |
With --json, failing runs set ok: false and emit issues[] with codes expgov.diff.exports_removed and/or expgov.diff.tier_violation. data.added / data.removed / data.tierViolations stay present for agents.
Additions never fail the gate — only removals (and optional tier violations).
When to use --fail-on-removed
Use it after publishing a stable SDK baseline (usually a v1.x tag) when removing or renaming a root export would break consumers:
# CI: protect the public surface released at v1.0.0
expgov diff v1.0.0..HEAD --fail-on-removed
# Local: check uncommitted barrel edits against the current commit
expgov diff HEAD --fail-on-removedChoose an immutable released tag or commit for the left side. The right side is the candidate release (HEAD in CI, or the working tree when only one ref is supplied).
Do not use this flag to reject additive API growth: additions remain allowed. It also does not replace expgov validate, which checks current-tree tier classification and package/config policy.
Prefer the one-command gate when you want both checks:
expgov validate --since v1.0.0That runs current-tree validate and fails on flat removals vs the baseline. Keep diff --fail-on-removed when you only want the surface compare (or need --fail-on-tier-violations on the right-side snapshot).