How to Compare Text Files (Diff)

What a diff shows you

A diff compares two texts line by line and reports the smallest set of changes that turns one into the other. Lines present in both texts are context; lines only in the first text were removed; lines only in the second were added. Changed lines appear as a removal plus an addition, because at the line level, "changed" is just "this line went away and a different line took its place".

That line-based view has one consequence worth understanding: a diff is about lines, not words. If you edit a single word in a 200-word paragraph that sits on one line, the diff marks the entire line as changed. That is why experienced developers keep lines short — one idea per line — so that diffs stay precise and code reviews stay readable. A diff of a well-formatted file shows exactly what changed; a diff of a file with very long lines shows almost nothing useful.

Reading a unified diff

The standard format is the unified diff, the format Git produces. It starts with a header naming the two files, then a series of hunks — one per changed region. Each hunk begins with a @@ line giving the line numbers, then the lines themselves: unchanged context lines start with a space, removed lines with a minus sign, added lines with a plus sign. Read it top to bottom and you can reconstruct both versions of the file.

A small example makes it concrete. If a config file changes its port from 8080 to 9090, the hunk shows two context lines around the change, the old line marked -port: 8080, and the new line marked +port: 9090. The minus and plus are the whole story: everything else is context to help you find where the change sits. When a diff has many hunks, read the @@ headers first — they tell you where each change is before you read what it is.

--- config.yaml (old)
+++ config.yaml (new)
@@ -1,4 +1,4 @@
 server: api.example.com
-port: 8080
+port: 9090
 features:
   - auth

Word-level and character-level diffs

Line diffs are coarse, and for prose or long lines they hide the real change. Word-level diffing solves this: it compares within a changed line and highlights only the words that differ, so a one-word edit in a long paragraph is visible at a glance. Character-level diffing goes further and highlights the exact characters. Most visual diff tools offer all three levels — lines for structure, words for reading, characters for precision — and you switch between them depending on what you are comparing.

Structured data deserves a structured diff. Comparing two JSON files as text will flag differences in key order and whitespace that do not change the meaning at all. A JSON diff parses both documents and compares the structure, so reordered keys and reformatted indentation are ignored and only real value changes are shown. The rule is simple: compare data in its own terms — text as text, JSON as JSON, and never let formatting noise hide a real change.

Practical uses

Diffs show up in more places than code review. When a server suddenly behaves differently, diffing the current configuration against the last known-good one usually finds the cause in seconds — a changed port, a missing flag, a swapped value. When an API starts returning different results, diffing the old and new responses isolates the change. When a document comes back from review, a diff shows exactly what the reviewer altered, instead of forcing you to re-read the whole thing.

The habit that makes diffs useful is diffing before you act. Before deploying a config change, diff the new file against the live one. Before overwriting a file, diff your version against the one on disk. Before submitting code, read your own diff — you will catch mistakes, leftover debug lines and accidental formatting changes that you would never spot by reading the file itself.

Tips for clean diffs

A clean diff is a readable diff, and a few habits keep them that way. Keep lines short and one idea per line, so changes stay local. Do not reformat unrelated lines in the same change — mixing a real fix with a whitespace cleanup produces a diff where the fix is buried. Ignore whitespace when it does not matter: most diff tools have an option to hide whitespace-only changes, which removes a whole class of noise.

Finally, format before you compare. If two files use different indentation or line endings, the diff will be full of false differences. Run both through the same formatter first — a JSON prettifier, a SQL formatter, or a YAML formatter — and the real changes will stand out. And save both versions before comparing: a diff is only as good as the two inputs you feed it.

• One idea per line — short lines make precise diffs.
• Never mix a real change with a reformat in the same edit.
• Use the "ignore whitespace" option to hide formatting noise.
• Format both files the same way before comparing.
• Diff before you deploy, overwrite or submit.