# Move Diff
`move-diff` renders a local `git diff` with extra markers for **moved** and
**reformatted** code, on top of the usual `+`/`-`, so that large mechanical
refactors are much easier to review.
It's a drop-in replacement for `git diff`: same argument shape, same behaviour
on a clean tree (no output, exit 0).
## Why
A refactor that moves code around produces a diff that is technically correct
but visually useless: the same function appears once as a deletion and again,
somewhere else, as an unrelated-looking addition. `move-diff` pairs those up,
so the real changes are the only ones left to read.
The example below is a small but realistic refactor that does four things at
once — it moves `receipts_for_customer` above `calculate_total`, wraps one line
(`x`), drops a dead struct field and a stale `TODO` (`-`), and adds a new
`audit_trail` function (`+`). It's a real `git diff`, not a hand-typed
illustration — see [`docs/example.diff`](docs/example.diff) for the exact
input and [`src/bin/svg.rs`](src/bin/svg.rs) for how the second image below
is regenerated straight from this crate's own renderer.
Plain `git diff` reports **20 additions and 10 removals**. Read on its own,
that looks like the file was substantially rewritten:
```diff
--- a/src/orders.rs
+++ b/src/orders.rs
@@ -1,30 +1,33 @@
pub struct Order {
pub id: u64,
pub items: Vec<Item>,
- pub legacy_discount: Decimal,
}
pub fn process_order(order: &Order) -> Result<Receipt, Error> {
- let total = calculate_total(&order.items)?;
+ let total =
+ calculate_total(&order.items)?;
Ok(Receipt::new(order.id, total))
}
+pub fn receipts_for_customer(orders: &[Order], name: &str) -> Vec<Receipt> {
+ orders
+ .iter()
+ .filter(|o| o.customer == name)
+ .map(process_order)
+ .collect::<Result<Vec<_>, _>>()
+}
+
fn calculate_total(items: &[Item]) -> Result<Money, Error> {
+ if items.is_empty() {
+ return Err(Error::NoItems);
+ }
let mut total = Money::zero();
- // TODO: fold in legacy_discount
for item in items {
total = total.checked_add(item.price)?;
}
Ok(total)
}
-pub fn receipts_for_customer(orders: &[Order], name: &str) -> Vec<Receipt> {
- orders.iter()
- .filter(|o| o.customer == name)
- .map(process_order)
- .collect::<Result<Vec<_>, _>>()
-}
-
pub fn legacy_totals(orders: &[Order]) -> Result<Vec<Money>, Error> {
let mut out = Vec::new();
for order in orders {
@@ -32,3 +35,10 @@ pub fn legacy_totals(orders: &[Order]) -> Result<Vec<Money>, Error> {
}
Ok(out)
}
+
+pub fn audit_trail(orders: &[Order]) -> Vec<String> {
+ orders
+ .iter()
+ .map(|o| format!("order {} settled", o.id))
+ .collect()
+}
```
`move-diff` on the same change:

The moved function (15 lines, counting both its old and new spots) is set
apart with `<`/`>` instead of being re-read as an unrelated deletion and
addition, and the deleted half of the rewrapped line (`x`) is dropped
entirely rather than shown as a whitespace-only duplicate. What's left to
actually review shrinks from 30 raw `+`/`-` lines to **10 genuine additions,
2 genuine removals, and 2 reformatted lines**.
## Markers
| Marker | Meaning | Colour |
| ------ | ------- | ------ |
| `+` | genuine addition | green |
| `-` | genuine removal | red |
| `>` | line moved **out** of its old spot | cyan |
| `<` | line moved **in** from elsewhere | blue |
| `x` | reformatted in place — only the new side is shown; the old side would be a whitespace-only duplicate | magenta |
| ` ` | context (unchanged) | — |
Moved and reformatted lines are matched whitespace-insensitively, so
reindentation or a linter rewrapping a line doesn't disguise it as a rewrite.
## Usage
```
move-diff [OPTIONS] [ARGS]...
```
`ARGS` are handed to `git diff` unchanged, so anything that invocation accepts
works here: a revision (`commit`, branch, tag, or a range like
`main...feature`), pathspecs that limit the diff to those paths, or both — git
resolves which is which. Omit `ARGS` to diff the working tree against the
index, behaving just like bare `git diff`; a lone path that isn't a git
reference resolves to a pathspec on its own, so no `--` is needed.
```
move-diff # working tree vs index (like `git diff`)
move-diff main # diff against a branch (like `git diff main`)
move-diff main...feature # diff a merge-base range
move-diff HEAD README.md # diff just one path (like `git diff HEAD README.md`)
move-diff README.md # diff one path vs the index (like `git diff README.md`)
move-diff -C ../other-repo # operate on another repository
```
### Options
- `-C`, `--dir <PATH>` — repository directory (default `.`).
- `--max-move-gap <N>` — how many *real* content changes are tolerated inside an
otherwise-moved block before move detection gives up on it. Accepts an
absolute count (`2`), a fraction (`0.1`), or a percentage (`10%`) of the
remaining block length in each direction. Default `10%`.
- `--no-color` — disable colour. Colour is also disabled automatically when
stdout isn't a TTY or `$NO_COLOR` is set, so piping is safe by default.
### Git parity
`move-diff` intentionally mirrors `git diff`'s contract:
- A clean tree prints nothing and exits `0` (it does **not** error with
"nothing to review", unlike the `mr-review` command it was extracted from).
- An unknown revision exits `128`, like a fatal git error.
- `move-diff … | head` exits quietly instead of panicking on a broken pipe.
- Colour honours `$NO_COLOR` and TTY detection, and `--no-color` is also passed
through to git itself so the parsed diff is never pre-coloured.
## Install
```
cargo install move-diff
```
Each release also carries prebuilt archives, so you can skip compiling:
| Platform | Archive |
| -------- | ------- |
| x86_64 Linux | `move-diff-<version>-x86_64-unknown-linux-gnu.tar.gz` |
| arm64 Linux | `move-diff-<version>-aarch64-unknown-linux-gnu.tar.gz` |
| x86_64 Windows | `move-diff-<version>-x86_64-pc-windows-gnu.zip` |
Grab them from [releases](https://gitlab.com/loikki/move-diff/-/releases), along
with the `SHA256SUMS` file covering that release. The Linux archives are built
against glibc and are not statically linked; the Windows `.exe` is standalone.
## Docker
```
docker run --rm -v "$PWD:/workspace" registry.gitlab.com/loikki/move-diff:latest
```
The image needs `git` at runtime, so mount the repository you want to inspect.
## Build from source
Requires a recent rustc (edition 2024, i.e. **rustc >= 1.85**).
```
make build # cargo build --release
make test # cargo test
make check # cargo fmt + clippy + cargo deny
```
The `svg-gen` feature builds an extra `move-diff-svg` binary used only to
regenerate `docs/example.svg` for this README; it's never built by `cargo
build`/`cargo install` and adds no dependency:
```
cargo run --features svg-gen --bin move-diff-svg -- docs/example.diff docs/example.svg
```