Comparing Two Versions of a Document, Config or Contract: A Practical Diff Workflow

A diff finds the longest sequence of text that two versions share and reports everything outside it as an addition or a removal. The same idea is behind version control. A good diff shows the smallest set of changes that turns one version into the other, which is also the easiest to read.

• ▸Lines: best for code, configuration, lists and structured text. Each changed line is shown whole. A single changed word marks the entire line.
• ▸Words: best for prose such as articles, emails and contracts, because it highlights the exact words that changed inside a paragraph.
• ▸Characters: best for spotting a typo, a changed digit or an altered identifier, but noisy on anything longer than a sentence or two.

Start with lines to see the shape of the change, then switch to words for the paragraphs that differ.

The most common reason a diff is useless is that everything differs for boring reasons.

• ▸Whitespace: different indentation, trailing spaces and tabs versus spaces. Use the option that ignores extra whitespace.
• ▸Line endings: Windows files use a carriage return plus line feed and others use only a line feed, which can mark every line as changed. Normalize them first.
• ▸Case: ignore case when capitalization is not the question.
• ▸Line wrapping: one version wrapped at 80 characters and the other not. Join the lines in each version into paragraphs before comparing.
• ▸Smart quotes and dashes: a word processor may have replaced straight quotes with curly ones throughout. Normalize them with the Plain Text Converter first.

Two JSON documents with the same content can differ in key order and spacing, which makes a line diff meaningless. Format both with the same indentation and sort the keys alphabetically, then compare. The JSON Formatter has a key sorting option for this. The same approach works for YAML after converting it, and for CSV exports sorted by the same column. Only then does the diff show real changes in values.

• ▸Look at the summary counts first. A few additions and removals means a small edit. Hundreds of changes suggest a reformat or a different base document.
• ▸Moved paragraphs show as a removal in one place and an addition in another. Search for a distinctive phrase from the removed block to confirm that it moved and did not change.
• ▸Pair a removal next to an addition when they are consecutive. They are usually one edit, not two.
• ▸Read the context around each change, since a one word change can reverse the meaning, such as the word not appearing or disappearing.

• ▸A diff compares text, not meaning. It will not tell you that a reworded clause means the same thing, or that a small change is legally important.
• ▸For contracts that will be negotiated, use a proper redline with tracked changes and an audit trail, and use a diff as a quick check on top.
• ▸Do not paste confidential documents into tools that upload them. The Text Diff Checker on this site compares everything locally in your browser, but you should still follow your organization's rules about sensitive material.