export-diff
Use when a change set should be reviewed visually outside the terminal — two versions of a file or directory tree, or an existing unified diff from any tool, rendered to a self-contained side-by-side HTML page set (no git required; e.g. before/after snapshots of docs, skills, or generated trees). Sets itself apart from line-based diff viewers by attributing content that moved, merged into another line, or split apart — even across line breaks — with word-level marks on only the real edits, wrapped prose lines, and a dropdown viewer for large multi-directory diffs.
Run
bash: uv run scripts/render_diff.py <--old OLD --new NEW | --diff FILE> --out DIR [--title T] [--split auto|always|never] — script path relative to this skill's directory (in Claude Code, ${CLAUDE_SKILL_DIR}/scripts/render_diff.py)
--old/--new: two files or trees, compared with diff -ruN. --diff: an existing unified diff.
- Output:
DIR/index.html — open in a browser. A large diff spanning several top-level directories splits into one page per directory behind a dropdown viewer; section pages must stay beside index.html.
- Fully self-contained:
uv supplies the python deps; no network or node tooling.
Report the printed per-section summary (files, ±lines, moved runs, change blocks, rewrite pairs) with the output path. Every page is auto-linted against the box contract (SPEC.md I17); LINT lines in the output are defects — investigate, don't ship silently. scripts/lint_diff.py PAGE.html re-checks any page standalone.
Reading the output
- Every changed region is a box: gray outline, faint red fill (removed side) or green fill (added side) — whether edited in place, moved, merged, split, wholly removed, or wholly added.
- Heavy red/green ink inside a box marks the exact removed/added tokens; a wholly removed or added block is fully inked.
- Gutter connectors pair counterpart boxes: straight = changed in place, crossing = moved; no connector = no counterpart.
- Hovering anywhere in a box highlights both sides and the connector; clicking pins one pair (click again to unpin), so an off-screen counterpart can be scrolled to.
- Unchanged spans between hunks render as separators labeled per side with that side's line range ("54-57 unchanged"). When the new-side source files are present and match the diff (rendering from
--old/--new, or --diff run where the diff's paths resolve), the separators expand — per-fold, or all at once via the top Show/Hide button — so the full file is readable in place.
- Right-clicking a box copies a block reference: per present side, an
OLD: path:lines / NEW: path:lines marker line followed by that side's verbatim contents — pasteable into a conversation or grep; the quote stays resolvable after line numbers drift.
- The split viewer carries this legend; for a single page, relay it to the reader.
Engine and provenance
Custom matching on stock scaffolding — represent it as such:
- GNU
diff (stock): line-level chunking.
scripts/render_diff.py (this skill): parses the diff and emits its own side-by-side page — one table per file, both sides of a change in the same table row, so alignment holds by construction — plus the box/connector overlay.
scripts/engine.py (this skill's engine): token-stream matching — greedy string tiling (RKR-GST family) for exact anchors that cross line boundaries, anchored gap refinement, bag-of-words Jaccard fallback, then move/merge/split classification and word marks.
The algorithms are established families from the plagiarism-detection and diff literature; the composition — cross-line move/merge/split attribution rendered in a side-by-side HTML view — is what stock viewers (git --color-moved, diff2html, difit, GitHub) don't offer. Never present the algorithms themselves as novel.
Spec
SPEC.md (this directory) is the contract: the ordered pipeline, every invariant that must hold on output, thresholds, and known limits. Consult it before debugging or changing matching behavior; a divergence between spec and behavior is a defect — fix whichever is wrong and keep both in sync.
1---2name: export-diff3description: Use when a change set should be reviewed visually outside the terminal — two versions of a file or directory tree, or an existing unified diff from any tool, rendered to a self-contained side-by-side HTML page set (no git required; e.g. before/after snapshots of docs, skills, or generated trees). Sets itself apart from line-based diff viewers by attributing content that moved, merged into another line, or split apart — even across line breaks — with word-level marks on only the real edits, wrapped prose lines, and a dropdown viewer for large multi-directory diffs.4compatibility: Requires uv (runs the bundled Python scripts with their declared dependencies)5metadata:6 source: https://skillmd.com/skills/a-horde-o-bees/export-diff7---89# export-diff1011Use when a change set should be reviewed visually outside the terminal — two versions of a file or directory tree, or an existing unified diff from any tool, rendered to a self-contained side-by-side HTML page set (no git required; e.g. before/after snapshots of docs, skills, or generated trees). Sets itself apart from line-based diff viewers by attributing content that moved, merged into another line, or split apart — even across line breaks — with word-level marks on only the real edits, wrapped prose lines, and a dropdown viewer for large multi-directory diffs.1213## Run1415bash: `uv run scripts/render_diff.py <--old OLD --new NEW | --diff FILE> --out DIR [--title T] [--split auto|always|never]` — script path relative to this skill's directory (in Claude Code, `${CLAUDE_SKILL_DIR}/scripts/render_diff.py`)1617- `--old/--new`: two files or trees, compared with `diff -ruN`. `--diff`: an existing unified diff.18- Output: `DIR/index.html` — open in a browser. A large diff spanning several top-level directories splits into one page per directory behind a dropdown viewer; section pages must stay beside `index.html`.19- Fully self-contained: `uv` supplies the python deps; no network or node tooling.2021Report the printed per-section summary (files, ±lines, moved runs, change blocks, rewrite pairs) with the output path. Every page is auto-linted against the box contract (SPEC.md I17); `LINT` lines in the output are defects — investigate, don't ship silently. `scripts/lint_diff.py PAGE.html` re-checks any page standalone.2223## Reading the output2425- Every changed region is a box: gray outline, faint red fill (removed side) or green fill (added side) — whether edited in place, moved, merged, split, wholly removed, or wholly added.26- Heavy red/green ink inside a box marks the exact removed/added tokens; a wholly removed or added block is fully inked.27- Gutter connectors pair counterpart boxes: straight = changed in place, crossing = moved; no connector = no counterpart.28- Hovering anywhere in a box highlights both sides and the connector; clicking pins one pair (click again to unpin), so an off-screen counterpart can be scrolled to.29- Unchanged spans between hunks render as separators labeled per side with that side's line range ("54-57 unchanged"). When the new-side source files are present and match the diff (rendering from `--old/--new`, or `--diff` run where the diff's paths resolve), the separators expand — per-fold, or all at once via the top Show/Hide button — so the full file is readable in place.30- Right-clicking a box copies a block reference: per present side, an `OLD: path:lines` / `NEW: path:lines` marker line followed by that side's verbatim contents — pasteable into a conversation or grep; the quote stays resolvable after line numbers drift.31- The split viewer carries this legend; for a single page, relay it to the reader.3233## Engine and provenance3435Custom matching on stock scaffolding — represent it as such:3637- GNU `diff` (stock): line-level chunking.38- `scripts/render_diff.py` (this skill): parses the diff and emits its own side-by-side page — one table per file, both sides of a change in the same table row, so alignment holds by construction — plus the box/connector overlay.39- `scripts/engine.py` (this skill's engine): token-stream matching — greedy string tiling (RKR-GST family) for exact anchors that cross line boundaries, anchored gap refinement, bag-of-words Jaccard fallback, then move/merge/split classification and word marks.4041The algorithms are established families from the plagiarism-detection and diff literature; the composition — cross-line move/merge/split attribution rendered in a side-by-side HTML view — is what stock viewers (git `--color-moved`, diff2html, difit, GitHub) don't offer. Never present the algorithms themselves as novel.4243## Spec4445`SPEC.md` (this directory) is the contract: the ordered pipeline, every invariant that must hold on output, thresholds, and known limits. Consult it before debugging or changing matching behavior; a divergence between spec and behavior is a defect — fix whichever is wrong and keep both in sync.