move-diff 0.3.1

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`](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:

![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](docs/example.svg)

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