tld git compare

tld git compare shows what a set of code changes does to your architecture. Point it at two revisions and it renders the difference as a diagram.

tld git compare HEAD~1 HEAD

What you get

By default you get a self-contained JSON impact scene. It matches changes to authored diagrams where possible, falls back to mapped or file elements, and includes a ledger of changed files.

To export Mermaid:

tld git compare HEAD~1 HEAD --mermaid
tld git compare HEAD~1 HEAD --markdown

--markdown just adds a code fence for easy copy-paste into your docs.

Choosing revisions

Pass two Git revisions: commit hashes, tags, or branches.

tld git compare HEAD~1 HEAD
tld git compare main feature-branch
tld git compare abc123 def456
tld git compare HEAD~5 HEAD --mermaid

Comparing another repository

The repository is optional and defaults to the current checkout. Pass a repository id, local path, or remote URL:

tld git compare github.com/org/repo main feature
tld git compare /path/to/repo HEAD~1 HEAD

Remote repositories are cloned on demand; missing snapshots are indexed on demand.

Blast radius

--blast-radius adds 0–2 dependency hops around changes (default: 0). Relevant authored view context is retained.

# Direct changes only — fast and focused
tld git compare HEAD~1 HEAD --blast-radius 0

# Include two hops of dependencies
tld git compare HEAD~1 HEAD --blast-radius 2

Flags

Flag	Default	What it does
--mermaid	false	Emit the Mermaid change diagram instead of the scene
--markdown	false	Wrap the Mermaid diagram in a Markdown code fence
--url / --url-local	false	Export a self-contained web / desktop link (maximum 10,000 characters)
--url-base	local server	Application URL for --url, e.g. https://tldiagram.com/app
--plain	false	Hide context without change impact
--view		Restrict to an authored view ID or name substring
--debug-provenance	false	Include matching and dependency evidence
-v, --verbose	false	Report indexing progress for both revisions on stderr
--blast-radius	0	Dependency hops to include (0–2)
--max-nodes	400	Node budget; the blast radius is narrowed when exceeded (0 disables)
--max-bytes	2097152	Output byte budget (0 disables)
--max-elements	0	Skip output when the diagram exceeds this element count (0 disables)
--max-connectors	0	Skip output when the diagram exceeds this connector count (0 disables)
--report-json		Write comparison status, counts, revisions, and index warnings to a JSON file
--prepare-command		Run a Bash command in each uncached revision before indexing
--data-dir		Override the data directory

Indexing progress is quiet by default so scripted runs only emit the payload and budget warnings. Pass --verbose to follow the base and head scans on stderr.

--url does not start a server; run tld serve for local links. Use --url --url-base https://tldiagram.com/app for a hosted viewer link. Links contain the scene without uploading it; anyone with the link can read it. Choose one URL output mode, without --mermaid or --markdown.

Prepare command

Some repositories need a build or dependency step before indexing. --prepare-command runs once in each uncached revision before indexing, and its contents become part of the snapshot config hash, so changing it invalidates cached snapshots.

tld git compare HEAD~1 HEAD --prepare-command "npm ci --ignore-scripts"

Setup must leave the tracked indexing inputs unchanged. Failure stops the comparison.

Reports and limits

--report-json writes a machine-readable report for CI:

tld git compare HEAD~1 HEAD --report-json compare.json

The report includes status (ready, skipped, or empty), element/connector counts, base/head revisions, index warnings, and change stats: files, directories, subsystems, lines added/removed, and symbols added/modified/removed.

--max-elements and --max-connectors are hard limits checked before rendering. Exceeding either suppresses stdout and exits successfully; the snapshots stay in the database. Equality is allowed.

PR diagram bot

To post these diagrams on pull requests automatically, use the PR diagram bot.