Compare text revisions and verify a unified diff

Problem

A comparison can look clean while hiding the wrong difference. CRLF versus LF may overwhelm a review, trimming may conceal meaningful indentation, a missing final newline can break checks, and position-by-position comparison can turn one insertion into hundreds of apparent replacements. A unified diff adds another risk: context and file headers must match the target, and a patch created under an ignore rule no longer represents every source byte. The reliable workflow therefore keeps an exact baseline, treats filtered views as diagnosis, distinguishes patch additions and removals from visual replacement pairing, and proves the exported artifact against a copy of the intended file.

When to use this

• A code or configuration revision must be reviewed outside a full repository client.
• Two environment files appear different and CRLF or line-edge whitespace may be the cause.
• A document edit needs exact inserted and deleted text without uploading confidential content.
• Generated output or a snapshot changed and the producing step needs to be audited.
• A unified diff will be handed to another person or checked before repository application.

Steps

1. Step 1

   Freeze and classify both sources

   Keep untouched copies and label which is original and which is revised. Confirm text encoding before pasting, identify whether secrets or personal data are present, and remove only data that is not required for the comparison. Do not reformat either source yet.

2. Step 2

   Create an exact line baseline

   Load the original on the left and revision on the right. Choose Line mode, leave both equivalence filters off, use three context lines, and run the comparison. Record raw added lines, raw removed lines, hunk count, and final-newline markers.

3. Step 3

   Explain each changed block

   Read hunk ranges before individual rows. Check whether every addition and removal is intentional. Paired replacement rows are adjacent patch lines aligned for display; compare their actual text instead of assuming the pair is semantically related.

4. Step 4

   Diagnose line-ending and edge-whitespace noise

   If the exact baseline is dominated by formatting, first inspect the files with Line Ending Detector. Then rerun with Treat CRLF as LF or Ignore line-edge whitespace one option at a time. Keep internal spaces significant and preserve the exact baseline as the source of truth.

5. Step 5

   Use character mode only for a bounded edit

   For a short changed sentence or identifier, compare the relevant excerpt in Character mode. Interpret highlights as Unicode code points, not grapheme clusters; combining marks, flags, and ZWJ emoji may use several units. Return to Line mode for patch output.

6. Step 6

   Export only an unfiltered patch

   Disable both filters, rerun, open Unified patch, and confirm the `--- before.txt` and `+++ after.txt` headers, hunk ranges, and missing-final-newline markers. The default labels are review names; replace them with validated repository-relative paths only in a controlled patch preparation step.

7. Step 7

   Dry-run, apply to a copy, and retest

   Use the destination tool's check mode, such as `git apply --check` after preparing correct path headers, or a patch dry run. Apply to a disposable working copy, compare the result with the intended revision, run formatters and tests separately, and retain the exact inputs and reviewed patch with the change record.

Example

before.txt (ends with newline)
server:
  port: 8080
  log: info
routes:
  - /health

after.txt (ends with newline)
server:
  port: 8081
  log: debug
routes:
  - /health
  - /ready

Exact line result: 3 added patch lines, 2 removed patch lines, 2 visually paired replacements, 1 changed hunk. Review port and log changes, confirm /ready is intentional, keep filters off, inspect generic before.txt/after.txt headers, then prepare and dry-run destination paths separately.

Common mistakes

FAQ