Line diffs are too coarse, and here is what to use instead

Three levels of comparison

Character-level comparison is the most precise and the least useful for review, because it loses the structure of the file. Line-level comparison is the useful default. Structural comparison goes further, ignoring the layout entirely and comparing the data.

The right choice depends on the question. Are these two text files the same? Use lines. Does this payload have the same data? Use structure.

• Character — for a single line, a token or a string value
• Line — for files, code and configuration
• Structural — for JSON, where key order carries no meaning

Word-level narrowing

When a line is marked as changed, most of the line has not changed. A word-level pass narrows the highlight to the words that actually differ, which turns a wall of red into two highlighted words.

This matters most for long lines: a minified JSON file on one line produces a single unreadable changed line, and a configuration file with a long value is unreadable for the same reason.

Structure beats text for data

Two JSON payloads with the same data in a different order are different strings and the same document. A text diff will report every line as changed. A structural comparison reports nothing, which is the correct answer.

Structural comparison also catches changes a text diff hides. A number that becomes a quoted string, a field that changes type, a key that quietly appears in one branch and not another — all of these are invisible in a line diff and obvious in a structural one.

• Key order is ignored for objects; array order is significant.
• A type change from `2` to `"2"` is reported separately from a value change.
• The path in the difference identifies exactly where the change lives.

A diff you can act on

The output of a diff is only useful if it can be acted on. That means each difference should carry a path, a type and the two values involved, and the whole list should be small enough to read.

When a diff produces hundreds of differences, the change was too broad to review as a diff. Narrow the scope, or split the change, rather than reading through the noise.