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 the impact diagram: the exact payload the canvas loads, self-contained, so it renders without the repository, its index, or its snapshots. Each placement carries a change overlay with the file’s line counts and structured symbol changes, and the view names what it compared.

To render it as a diagram instead:

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

Any Git revision works: hashes, tags, branches, or ranges.

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 and depth

--depth controls how many dependency hops of unchanged context are included in the diagram:

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

# Wider context. This can easily explode the diagram if the change touches a widely-used symbol.
tld git compare HEAD~1 HEAD --depth 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
-v, --verbose	false	Report indexing progress for both revisions on stderr
--depth	3	Dependency hops of unchanged context to include (0 = direct changes only)
--radius	--depth	Blast radius to display
--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.

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.