The layout: two panels, one row per unit
The original goes on the left and the changed version on the right. The comparison then aligns them, which is the part worth understanding: matching content is pulled onto the same row, so corresponding text sits opposite itself even when the two versions have drifted a long way apart in length. Where one side has content the other does not, the opposite cell is left blank rather than filled with the next available line.
That alignment is why a diff is readable across rather than down. You are not comparing line 40 with line 40; you are comparing a block with whatever the tool believes that block became. When the alignment looks wrong, that is real information — it usually means the two blocks were matched differently than you expected, and the categories below explain what the tool decided instead.
The five categories
Every row falls into exactly one of five states, and each carries an icon and a gutter marker as well as a colour, so the result stays readable if you do not distinguish red from green.
Unmodified means present on both sides, in the same place, byte for byte. Added means present only in the modified text; Deleted means present only in the original. These three are factual — there is no judgement in them.
Moved means the same content was found on both sides but in a different position. Modified means two blocks were matched to each other and then found to differ, so the row shows a per-block similarity score alongside the changed words highlighted inside it. These last two are inferences: the tool decided that a block on the left corresponds to a block on the right. That decision is usually obvious and occasionally arguable, which is the single most useful thing to know when a result surprises you.
What the similarity percentage measures
One formula produces the headline number, in both comparison modes. Content that matched exactly counts in full. Content that was matched but edited counts in proportion to how similar the two versions of it are. Content that was added or deleted counts as zero. Everything is weighted by size, so a relocated fifty-line function moves the number considerably more than a moved one-liner.
A pure relocation costs nothing at all in Smart mode — a file whose sections were shuffled but not otherwise touched scores at or near 100%, because nothing was actually lost. A block that was both moved and edited is weighted by its edit score rather than credited in full, so the headline cannot claim a perfect match while a row underneath it visibly disagrees.
The number is a summary of that one calculation and nothing more. It is not a measure of whether the change was correct, whether the two versions behave the same way, or whether the difference matters. Read it as "how much of this content survived unchanged", which is precisely what it computes.
Word-level highlighting inside a changed row
When a row is Modified rather than replaced, the specific words that differ are marked inside it. That is what makes a single changed digit in a long line of configuration findable, instead of leaving you to scan a row that is merely flagged as different.
On extremely long lines this highlighting is withheld — the row is still shown and still correctly categorised, but the intra-line detail is skipped rather than spending an unbounded amount of time on it. This affects single lines of a few thousand characters and above, which in practice means minified files and long encoded strings.
When the tool tells you it skipped something
A quietly reduced comparison looks exactly like a complete one, which is the failure this next part exists to prevent. Where the analysis has been cut short, the status line under the panels says so in plain language, and that notice is worth taking literally.
Three messages mean content genuinely went uncompared. One says the input was too large to compare in full. One says the input was large enough that only exact block matching ran, so some edited blocks are reported as an addition plus a deletion rather than as a modification. One says the comparison ran out of time and returned a partial result. In all three cases the result on screen is real but incomplete, and the missing part is not marked — so a diff carrying one of these notices should not be used as evidence that nothing else changed.
Messages that merely name which strategy ran are deliberately not shown, because a warning that is always present teaches people to ignore the two that matter.
Reading a result you disagree with
If a block you know was edited is showing as a deletion plus an unrelated addition, the two versions were probably too different to be matched to each other, and the tool declined to guess. If a block you know was moved is showing as unchanged, it may not have crossed anything — position is judged relative to the surrounding content, not to absolute line numbers.
If content that was relocated is being reported as removed and re-added, that is a specific and common situation with its own explanation: see moved and reordered blocks. If the whole result is marked as changed when you altered very little, the cause is usually mechanical rather than meaningful, and whitespace and case covers it.
The limits worth carrying away
A comparison is an analysis, not a proof. Matched blocks are the tool's best inference; a similarity score is one specific calculation; and an order-independent comparison deliberately treats relocation as inexpensive, which is right for prose and is not always right for code, where sequence can carry meaning.
For anything consequential — a contract clause, a filing, a medical record, a production configuration, a financial figure — read the changed parts yourself rather than trusting the summary. The comparison is very good at telling you where to look. Deciding what it means is still yours.