mapdiff 0.1.0

Review a change on a map of your code

[Install] - [Quick start] - [Review] - [Map] - [Docs] - [Changelog]

A diff shows you lines. mapdiff shows you the functions and types that changed, where they sit in the codebase, and the code that uses them. Run it in a repository and it opens in your browser.

• The change as code, not lines. "This function's signature changed", "this type moved there", with before and after side by side.
• What it touches. Unchanged code that uses something you removed or renamed is marked. A line diff has no place for it.
• A sensible order. What is used comes before what uses it. One keypress per change.
• One command. mapdiff in any git repository. There is nothing to set up.

Install

Pick one. Each installs the mapdiff command.

Homebrew

macOS and Linux.

brew install avgvi/tap/mapdiff

Shell installer

A prebuilt binary for macOS or Linux, arm64 or x86_64.

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/avgvi/mapdiff/releases/latest/download/mapdiff-installer.sh | sh

Cargo

cargo install mapdiff

That builds from source. To download the release binary instead:

cargo binstall mapdiff

npm

npm install -g mapdiff-cli

The package is called mapdiff-cli on npm; the command it installs is still mapdiff.

Python tools

uv tool install mapdiff

With pipx it is pipx install mapdiff.

From source

With Rust and Node installed:

git clone https://github.com/avgvi/mapdiff && cd mapdiff
cd ui && npm ci && npm run build && cd ..   # builds the page, which goes inside the binary
cargo install --path crates/mapdiff-cli     # installs `mapdiff`

Quick start

In any git repository:

mapdiff                  # the map, with your uncommitted changes drawn on it
mapdiff main...HEAD      # what this branch changed
mapdiff --commit HEAD    # one commit
mapdiff --pr 123         # a GitHub pull request

Then press N to go to the first change, R when you have read it, and N again.

Reviewing a change

N and P step through the changes, and each one opens its before and after under the map. R marks it reviewed.

On a large change, Only what changed cuts the map down to it. One commit of ripgrep goes from 4,390 boxes to 7.

More in the review guide.

The map

Untick Changes and the map is a way to read a codebase, at four levels:

Click a box to see who uses it and what it uses, with a path drawn to each.

Press T to trace it: its code in the middle, callers on the left, what it calls on the right.

Press / to find a function, type or file by a few letters. All the keys are in the docs.

Languages

Rust, Python, TypeScript and JavaScript.

References are found by name out of the box. mapdiff index runs the language's own indexer (rust-analyzer, scip-typescript, scip-python) to add methods called on a value. Tests are left off the map, and a changed test still shows in a review. More on languages.

In the terminal

What the page shows is also a command, most with --json:

mapdiff diff main...HEAD              # the change, by function and type
mapdiff impact --commit HEAD          # unchanged code that uses what the commit altered
mapdiff refs 'src/lib.rs::parse()'    # what uses a function, and what it uses

The rest are in the command reference.

Development

.github/scripts/fetch-repos.sh    # four pinned open-source repositories, used as test data
cargo test                        # Rust tests
cd ui && npm test                 # layout and viewer tests

Licence

MIT