A diff does not work out what you changed. It finds the longest sequence of lines present in both versions in the same order, and reports everything else as an insertion or a deletion.
That single algorithm explains every diff result that looks unhelpful, because a diff has no vocabulary for editing, reordering or moving. It has two verbs, and it describes all changes using them.
Why does a moved block show as two changes?
Because there is no way to say "moved". A paragraph that has travelled from the top of a file to the bottom appears once as a deletion and once as an addition, and the two are only obviously related to a reader.
The same applies to a rename, a reorder of function definitions, or a list sorted differently. All of them are large diffs describing small changes.
Some tools detect moves afterwards by looking for identical added and removed blocks and pairing them. That is a presentation layer on top of the result rather than a different computation.
Why did my whole paragraph change?
Because the comparison is line by line and the paragraph was reflowed. Changing one word in a paragraph that then rewraps changes every line after it, and the diff correctly reports every one of them as different.
The fix is either to compare at a finer granularity or to write in a way that avoids the problem.
| Granularity | Good for |
|---|---|
| Line | code, configuration, data |
| Word | prose, translated text |
| Character | short strings, identifiers |
A word-level comparison on prose shows what actually changed and ignores where the lines happen to break, which is why documents and code want different settings from the same tool.
What does the unified format mean?
It is the notation almost every tool prints: a header naming the two versions, then blocks of lines prefixed with a space for unchanged, a minus for removed and a plus for added.
Each block starts with a line giving the positions and lengths in both files. That is what lets the diff be applied to the original rather than only read — a patch is a diff plus enough context to find its place.
The context lines around each change exist for exactly that. Three lines either side is the convention, and it is why a patch still applies after unrelated edits elsewhere in the file.
Should whitespace count?
It depends what you are comparing, and the option exists because both answers are right. In code, an indentation change is usually noise and hiding it makes a review readable.
In data it is the opposite. A trailing space in a field is a real difference and hiding it means comparing two things that are not the same and being told they are.
Line endings are the version of this that produces the most confusing result: a file converted between conventions shows every line as changed while looking identical on screen. Any diff reporting a whole file as different is worth checking for that before anything else.
How is comparing two lists different?
It ignores order, which a diff cannot. Two lists compared as sets answer three questions a diff does not: what is in the first only, what is in the second only, and what is in both.
That is the right tool for reconciling exports, checking a migration, or finding which records are missing — questions where the order is arbitrary and the membership is the point.
The distinction worth keeping is that a diff preserves sequence and a set comparison discards it. Using a diff on two differently sorted exports of the same data produces a wall of changes and no information.
What makes a diff easy to review?
Small, single-purpose changes. A diff mixing a rename, a reformat and a behaviour change is unreadable because the interesting lines are buried among mechanical ones — and no tool can separate them afterwards.
Separating them at the time is the whole technique. Reformatting in one pass and changing behaviour in another produces two diffs, one of which can be skimmed in seconds and one of which deserves attention.
The same logic applies to generated files. Anything rebuilt from a source produces a large diff carrying no decisions, which is why generated output is usually best kept out of the comparison entirely.
Questions people ask
Can two files with identical content differ? Yes — trailing newline, line endings, or an invisible byte order mark at the front. All three show as a difference and none is visible.
Does file order matter in a comparison? For a diff, entirely. For a set comparison, not at all, which is usually the reason to reach for the second one.
Why is the diff bigger than the change? Almost always reflowing, reindentation or line endings.
Can a diff be applied backwards? Yes. Reversing the additions and deletions undoes it, which is what a revert does.
Does a diff understand syntax? No. It compares text, which is why a formatting-only change looks as large as a rewrite.
Why do some diffs show a single changed line twice? Because a modification has no verb of its own — it is reported as the old line removed and the new one added, on consecutive lines.
What is a three-way diff? A comparison of two versions against their common ancestor, which is what makes automatic merging possible.
Pick the granularity to match the content. The diff checker and text compare handle ordered comparison, and compare two lists and list difference answer the membership questions instead.