Why a one-line insert makes a whole diff look changed

Comparing two versions of something by eye works until the thing is about fifteen lines long. Past that, human attention slides over the identical parts and the one character that changed is exactly the one you do not see. That is what a diff is for: it does the comparison mechanically, so the boring parts stay boring and the real change is the only thing left on screen.

What a diff is trying to compute

The proper definition is worth knowing because it explains every diff you have ever found confusing. A diff answers: what is the smallest set of changes that turns text A into text B? The standard approach finds the longest sequence of lines the two texts have in common, in order, and calls everything outside that sequence either a removal or an addition.

“Smallest” is the whole idea. If you add one line to the top of a hundred-line file, the other hundred lines are still there in the same order, so a minimal diff reports one addition. That is why a good diff of a large file is usually short, and why a diff that is entirely red and green is telling you something — usually not what you think.

This tool compares by line number, and that changes the advice

The comparison here is a simpler one, and being clear about it is the difference between using it well and being misled by it. It puts the two texts side by side and compares line 1 against line 1, line 2 against line 2, and so on to the end of the longer text. It does not search for a common sequence.

For two texts of the same shape that is exactly right and very fast. For an insertion it is brutal. Compare alpha / beta / gamma against intro / alpha / beta / gamma — a single line added at the top — and the real output is:

• - alpha
• + intro
• - beta
• + alpha
• - gamma
• + beta
• + gamma

Every line is marked changed. Nothing was changed; one line was inserted, and everything after it shifted down by one, so line 2 is now being compared against what used to be line 1. A minimal diff would have printed + intro and nothing else.

So use this for texts that are aligned: two configuration files with the same keys in the same order, the same block of text before and after an edit, two exports of the same report. The moment lines have been inserted or deleted, read the output as “something moved at this point” rather than trying to read every pair. Line-shift is the signature: a run of paired removals and additions where each addition is the previous removal.

The invisible differences

Two texts that look identical on screen can differ on every line, and this is where most of the wasted time goes.

Trailing whitespace. Add one space to the end of the middle line and the comparison correctly reports it:

• alpha
• - beta
• + beta
• gamma

The removal and the addition look the same, because the difference is a space you cannot see. Any time a diff shows you two apparently identical lines, that is what has happened.

Line endings. Windows ends a line with a carriage return and a newline; Unix and macOS use the newline alone. This comparison splits on the newline, which leaves the carriage return sitting on the end of every line of the Windows text as an invisible extra character. Comparing a CRLF version of alpha / beta / gamma against the LF version gives:

• - alpha then + alpha
• - beta then + beta
• gamma

Two lines differ and the third does not — because the final line has no line ending after it, so it is the only one without the stray character. That asymmetry is the tell. If every line except the last is marked changed and they all look identical, you have a line-ending mismatch, not an edit.

Normalise first, then compare

The method is the same wherever you diff. Before comparing, make the two texts agree on the things you do not care about: convert both to the same line endings, strip trailing spaces, and settle tabs against spaces one way or the other. Then diff. Every difference that survives is a real one.

Aim the comparison at the smallest region you can: two whole 500-line files produce noise, while the twenty lines around your actual change produce an answer.

The scope of this tool

Output is one line per position: two leading spaces for unchanged, - for a line only in A, + for a line only in B. It works at line level and never at word or character level, so a one-character change prints the whole line twice and leaves you to spot the character. There is no similarity percentage, no context setting, no ignore-whitespace option and no way to merge the result — it reports, it does not resolve.

Both texts stay on your device; Text Diff compares inside the page and uploads nothing, which is the only reason pasting two versions of a configuration file into a web page is a sensible thing to do. Knowing what the output means when it goes entirely red is the part that saves the afternoon.