Getting started

Getting started

Install

pipx install system-diff

or pip install system-diff into a virtual environment. Python 3.11 or newer; no other dependency. Both system-diff and the shorter sysdiff are installed.

The first map

From anywhere inside a git repository:

system-diff map --dir . --out docs/diagrams

This writes docs/diagrams/system.svg (open it in a browser) and docs/diagrams/system.json (everything that was found, including what the picture leaves out). With no configuration, every folder of code is a part named by its path, which is a fair first picture. Then name the parts and their columns in a system-diff.toml (see Configuration) and run it again.

--ref main (or any commit) maps a commit instead of the working tree, straight from git.

The first diff

system-diff diff --base origin/main --out out     # this branch against main
system-diff diff --base HEAD --head . --out out   # your uncommitted work

• out/headline.txt: one sentence, e.g. Adds 1 endpoint (DELETE /api/orders/{id}); changes 1 table (public.orders).
• out/plan.txt: the exact list, terraform plan-style, with the impact of each line (new-interface, breaking-interface, data-schema-change, new-external, test-gap …).
• out/diff.svg: the parts that changed, lit, with the parts they touch beside them. There is no picture when nothing structural changed.
• out/diff.json: all of it, for tools.

Add --narrate for a plain-words summary written by your own LLM (out/narrative.md). See Commands.

The map in your README

Put two marker lines where the map should go:

<!-- system-map:begin -->
<!-- system-map:end -->

and run system-diff readme --json docs/diagrams/system.json. Point [readme] image at docs/diagrams/system.svg; GitHub shows SVG. In pull requests keeps it current.