Diffing Two Markdown Versions
How a line-based diff shows what changed, why reformatted prose floods the output, and how to read a diff without drowning.
The algorithm in one paragraph
The comparison aligns the two files using a longest-common-subsequence match: it finds the longest run of lines that appear in both versions, marks that run as unchanged, then recurses on the lines before and after. The result is the smallest set of additions and removals that turns the first document into the second. This is the same family of algorithm used for version control, and it is why the diff is small and readable for real edits.
Reading the marks
Each row carries a mark and the line number on each side. Added lines exist only in the new version; removed lines exist only in the old one; unchanged lines appear in both. Because the line numbers are shown, you can jump straight to the change in either document instead of scrolling. Long runs of unchanged lines are collapsed so the actual change stays in view.
When a diff becomes noise
A line diff is poor for a document that was reflowed wholesale. If every paragraph was rewrapped, then every line differs from its counterpart and the output is a wall of red and green that hides the handful of real changes. In that situation, compare a section at a time, or render both versions and read them side by side, or normalise the wrapping first so the line breaks are stable.
What a diff will not tell you
A diff tells you where the text differs, not why. It cannot see that a moved paragraph is the same argument reordered, or that two edits are part of one larger rewrite. Use it to locate the change fast, then read the surrounding section to judge whether the edit does what you meant. The diff is a pointer, not an opinion.
Diffing a moved section
Moving a block of text is the one edit a line diff reports as pure deletion plus pure addition: every line in the moved block is removed from its old place and added at its new one. That is technically correct and practically useless for review. If you know a change is a move, say so in the commit message or the review note, or diff the section against itself before and after the move. The reader needs to know the block did not vanish and reappear.
Keeping the diff small on purpose
The size of a diff is a design choice as much as a technical one. Editing a paragraph in place keeps it small; reflowing the whole document to fix one sentence makes every line differ and buries the sentence. When you edit, edit in place. When you reformat, do it in its own commit so the formatting noise is separate from the content change. Reviewers will thank you, and so will the version of you that has to read it back.
Diffing is not reviewing
A diff shows that text changed; a review decides whether the change should ship. The two are different jobs. A clean diff can still contain a wrong fact, a broken promise to a reader, or a section that contradicts the one above it. Use the diff to find the change, then read the changed section in full, in context, with fresh eyes. The diff gets you to the paragraph; the reading is what catches the mistake inside it.