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 for the exact
input and 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:
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 {
}
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. Default10%.--no-color— disable colour. Colour is also disabled automatically when stdout isn't a TTY or$NO_COLORis 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 themr-reviewcommand it was extracted from). - An unknown revision exits
128, like a fatal git error. move-diff … | headexits quietly instead of panicking on a broken pipe.- Colour honours
$NO_COLORand TTY detection, and--no-coloris 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, 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