---
title: tld git compare
description: Visualize the architectural impact of the changes between two Git
  revisions — commits, branches, or a PR.
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

`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.

```bash
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:

```bash
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.

```bash
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:

```bash
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.

```bash
# 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.

```bash
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:

```bash
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](https://github.com/Mertcikla/tld-pr-bot).