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

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

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

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

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

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

```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/blob/main/docs/pr-bot.md).