The answer first: diff minimizes edit steps and has no "move"
"I only moved line 3 down to line 9, why does git diff mark both blocks red?" Because the objective is to turn the old text into the new one with the fewest deletions and insertions — there is no move operation. Once that lands, most counter-intuitive output explains itself: the content did not change, the edit path did.
Grid model: every diff is a path
Put the old text on the horizontal axis and the new text on the vertical axis:
new text y
↑
… ○──○──● (diagonal = equal chars, free)
…
- One step right → delete one old character;
- One step up → insert one new character;
- A diagonal whose endpoints match → free, no step counted.
Every route from start to finish is one way of editing the text, and diff picks the route with the fewest steps — the one that takes as many free diagonals as possible. That directly explains why a move becomes all-delete/all-add: the identical block at its new position is not on the same shortest path, and the algorithm will not invent a move operation for it.
Myers: layer by edit count, exhaust the diagonals
Myers advances in layers of edit count d: layer d enumerates every position reachable in exactly d steps and, on arrival, walks the diagonal as far as it goes to consume free matches. The first layer that reaches the end is the minimal edit distance.
Among equally good options it prefers concentrated edits over scattered ones, which keeps output compact and readable. git diff and GNU diff implement it by default.
Line-level vs character-level: choose by granularity
| Dimension | Line-level diff | Character-level diff |
|---|---|---|
| Granularity | lines added or removed | words/characters inside a line |
| Best for | code review, config comparison | a parameter change in a long line |
| Noise | low | high (large files turn red) |
| Data like JSON | misreads whole-line changes | more semantic (use a dedicated JSON diff) |
Read line-level first to grasp structure, then enable character highlighting on the lines you care about; prefer structured diffs for data. A dedicated JSON diff recognises array moves, which is closer to the actual semantics than line comparison.
Reading one real diff
Suppose a config raises timeout from 30 to 60 and moves a comment; git diff --no-index a.txt b.txt might output:
--- timeout: 30
+++ timeout: 60
@@ -1,5 +1,5 @@
server { listen 80 }
- # TODO tune
- timeout: 30
+ timeout: 60
@@ -1,5 +1,5 @@is the hunk's range;-lines exist only in the old text,+lines only in the new;- unprefixed lines are context, preserved around the edit wherever possible.
Do not conclude "the comment was deleted": along the shortest path, removing the comment and changing the value costs less edit distance than keeping it and moving it.
Practice: predict all-delete/all-add
Take two config snippets with small edits and run them through the text diff tool or local diff -u:
- Watch how the
@@context range is chosen; - Deliberately move a large block up or down and see it become all deleted plus all added;
- Compare two JSON blobs with a JSON diff and note how it recognises array moves where a line diff cannot.
When you can predict "this block will probably show as all-delete/all-add", you are already reading diffs through edit distance.
30-second verification
import difflib
a = ['GET /api/users', 'GET /api/orders', 'POST /api/orders']
b = ['GET /api/users', 'GET /api/orders/v2', 'POST /api/orders', 'DELETE /api/orders/1']
print('\n'.join(difflib.unified_diff(a, b, 'old', 'new', lineterm='')))
--- old
+++ new
@@ -1,3 +1,4 @@
GET /api/users
-GET /api/orders
+GET /api/orders/v2
POST /api/orders
+DELETE /api/orders/1
@@ -1,3 +1,4 @@ is the hunk header (old file: 3 lines from line 1; new file: 4 lines from line 1); - and + mark deletions and additions, while unprefixed lines are context. Those three markers are everything you need to audit a code review.