What a text diff actually shows you
A diff does not tell you what changed. It tells you the shortest set of edits that turns one text into the other — which is usually the same thing, and occasionally is not. Knowing the difference is what separates reading a diff from trusting it.
How the comparison works
The algorithm looks for the longest common subsequence of lines: the longest list of lines that appears, in the same order, in both texts. Everything in that list is marked unchanged. Everything else is an insertion or a deletion, and a line that appears as a deletion immediately followed by an insertion is what we display as a rewrite.
Worked example. The original is two lines — The report is due on Friday. and Send it to the team. — and the new version changes only the first, to The report is due on Monday.
The common subsequence is the second line. The first line is one deletion plus one insertion — and because they are adjacent, the word-level pass runs on that pair and highlights only Friday → Monday instead of repainting the whole sentence.
Why a diff sometimes looks wrong
There is no single correct diff, only a shortest one, and ties get broken arbitrarily. Two cases account for almost every "that's not what I changed":
- Moved blocks read as delete + add. Move a paragraph from the top of a document to the bottom and a line-based diff reports the whole paragraph twice: removed up there, added down here. Nothing was rewritten, but nothing in the algorithm knows that.
- A repeated line matches the wrong occurrence. In a list where several lines are identical, the algorithm may pair your new line with the first identical one it finds and mark a different one as deleted. The result is correct — it produces the same output text — but it can be attributed to the wrong place.
Options that change the answer
- Ignore case compares
Totalandtotalas the same line. Useful for prose, dangerous for code and for anything case-sensitive downstream. - Ignore whitespace collapses runs of spaces and tabs and trims the ends of lines. This is the option that turns an unreadable diff into a readable one after a reformat — and the option that hides a genuine indentation bug in a Python file or a YAML block.
Both options apply to comparison only: the text shown is always exactly what you pasted.
When to reach for it
Contract redlines where the other side sent a "clean" copy. Two exports of the same dataset that should be identical. A machine-translated page against its human-reviewed version. A prompt you edited twenty times and a colleague's version of it. Any case where the question is not "what does this say" but "what is different from what I already read".