How to Diff Two Versions of Your Docs

The diff command compares two sets of AsciiDoc sources and reports which traceable items were added, removed, or modified.

Prerequisites

  • The antora-tracer CLI installed.

  • Two snapshots of your docs — for example two directories, or two git worktrees/refs checked out side by side.

Run the diff

npx antora-tracer diff --from docs-v1 --to docs-v2

The output lists each changed item:

Kind     ID       Role         Changed fields
added    REQ-043  requirement
removed  REQ-041  requirement
modified REQ-042  requirement  content

Add --json for machine-readable output.

How the diff works

  • Items are matched by stable ID, so it works with any role or relation vocabulary.

  • A surviving item is modified when its title, content, role, status, or attributes changed; the changed fields are listed.

  • Relationship changes are reported only for items that survive the diff.

  • A superseded requirement appears as removed plus its successor added, with the supersedes link listed as a new relationship.

Diff two published versions without sources

For multi-repository sites, compare two full snapshots instead of checking out both versions.

Harvest a snapshot from each playbook at release time:

npx antora-tracer site-graph antora-playbook.yml --out v1.json
# ... later, on the next release ...
npx antora-tracer site-graph antora-playbook.yml --out v2.json

Then diff the stored snapshots:

npx antora-tracer diff-graphs --from v1.json --to v2.json

site-graph runs Antora’s aggregation and classification only (no site output), so the snapshot spans every content source, component, and version the playbook resolves. diff-graphs matches items by component-qualified identity, so the same ID in different components is not conflated.

Published graph snapshots

Every site build also publishes a per-version graph.json snapshot next to the generated matrices, at traceability/graph.json under each component version. The snapshot records the version’s items and relationships in the canonical { format, component, version, items, relationships } shape, so a published version carries a machine-readable record of its traceability graph without re-checking out the sources. See Configuration Reference for the generateMatrices option that gates it.

Related