Text Diff Algorithms: How to Read the Output Differently

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:

  1. Watch how the @@ context range is chosen;
  2. Deliberately move a large block up or down and see it become all deleted plus all added;
  3. 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.

Frequently Asked Questions

How are the '+' and '-' in diff output decided?

Diff finds the minimal set of edit operations (insert/delete/change) turning the old text into the new one. Line by line: a line present only in the new text gets '+', only in the old gets '-', lines equal on the minimal path stay untouched. When you move a block and see the whole block shown as deletions/additions, that's because the algorithm optimizes minimal edit cost rather than human 'move' intuition—Myers' algorithm explicitly balances edit steps against the number of inserted/deleted lines.

What does the 'diagonal' in Myers diff mean?

Set the old text on the x-axis and the new text on the y-axis to build a grid from bottom-left start to top-right end. Moving right deletes an old char, moving up inserts a new char, and moving along a diagonal step is 'free' when the chars match. Myers' algorithm tracks progress by 'diagonal number' (k) and expands k one round at a time; the first path to arrive at the end is the one with the fewest edit steps. Once you grasp 'walk free diagonals as much as possible', you understand why diffs grow long runs of unchanged content and concentrate changes into minimal hunks.

When should I use line-level vs character-level diff?

Line-level diff (with context) is enough to convey which lines were added/removed and how structure changed, so it is the default for code review and config comparison—low noise and readable. Character/word-level diff (supported by many visual tools) pins changes within a long line to individual tokens, handy for checking whether one parameter value changed. Rule: use line-level for structure, char-level highlight for in-line tweaks. For JSON, a dedicated JSON diff maps additions/deletions/moves more semantically than raw line diff.

Why does diff sometimes show all-delete/all-add for identical blocks?

Usually diff isn't wrong—it's that identicalness only counts when blocks align on the same candidate path. When two versions reorder large blocks or change nesting, those blocks don't sit on the same minimal edit path and get split into 'removed then added' even though the content is byte-identical. So git diff reports edit distance, not content similarity. To catch moves, use move-detection tools or a JSON diff that recognizes array relocation.

← Back to Blog