move-diff 0.3.0

Render a git diff with extra markers for moved and reformatted code
Documentation

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:

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

move-diff's annotated output: the moved function is set apart in blue/cyan (8 lines marked < where it now lives, 7 lines marked > where it used to be) instead of being re-read as an unrelated deletion and addition; the rewrapped line is marked x in magenta with its old single-line form dropped entirely; two genuine removals are red and ten genuine additions are green

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