Unified diff viewer

The unified diff viewer parses standard unified diffs and renders them as minimally as possible. It merges nearby insertions and deletions into a single “modified” row and shows small character-level edits inline to make it easier to understand changes.  

Below is documentation for how to use it, and an in-depth explanation of how it works. To the right, you can see the DiffViewer component. During the in-depth explanation you will see how we go from a verbose Github style diff, to a more minimal diff.

Parsing diffs

GitHub shows diffs without merging modified lines. Inserted and deleted blocks are rendered separately, sometimes far apart. Take a look at line 4, where the ChevronDown icon is added to the import. You need to read two lines to understand that only an icon was added and nothing deleted.

Copy- import { Check, Copy } from "lucide-react";
+ import { Check, Copy, ChevronDown } from "lucide-react";

Now look at line 4 again. The separate insert and delete are merged together, making it much easier to understand what changed.

The naive approach is to iterate over all changes and merge adjacent insertions and deletions into one "normal" line where segments are marked as insert or delete.

Copyconst mergeAdjacentLines = (changes: _Change[]): Line[] => {
  const out: Line[] = [];
  for (let i = 0; i < changes.length; i++) {
    const current = changes[i];
    const next = changes[i + 1];
    if (current.type === "delete" && next?.type === "insert") {
      out.push({
        ...current,
        type: "normal",
        isNormal: true,
        oldLineNumber: current.lineNumber,
        newLineNumber: next.lineNumber,
        content: buildInlineDiffSegments(current, next),
      });
      i++; // Skip next
    } else {
      out.push(current);
    }
  }
 
  return out;
};

The problem with just merging every delete+insert pair is that when the lines are very different, the result is noisy. See line 6 – not very nice.

To solve this, we can add a maximum change ratio. So only lines where the change ratio is less than this limit are merged.

Copyconst calculateChangeRatio = (a: string, b: string): number => {
  const totalChars = a.length + b.length;
  if (totalChars === 0) return 1;
  const tokens = diffWords(a, b);
  const changedChars = tokens
    .filter((token) => token.added || token.removed)
    .reduce((sum, token) => sum + token.value.length, 0);
  return changedChars / totalChars;
};
 
// Then we check for it before merging
if (current.type === "delete" && next.type === "insert" 
  && calculateChangeRatio(current.content, next.content) < options.maxChangeRatio) { /* ... */ }

Setting the max change ratio to 0.45 prevents the parser from merging line 6. Try playing with it to see what happens.

But deletions and insertions of modified lines are not always next to each other. Look at line 20. The deleted version of that line is displayed below line 38, making it very difficult to see that the only change is adding min-h-16.

What if we find the best possible match for each deletion while maintaining the order?

Now look at line 20 again. The separate insert and delete are merged together, making it much easier to understand what changed.

But why isn't the small typo that was fixed by adding x merged together? Try increasing the inline max char edits to see how it works.

Copyconst charDiff = diffCharsIfWithinEditLimit(
  current.value,
  next.value,
  options.inlineMaxCharEdits
);
 
if (!charDiff.exceededLimit) {
  charDiff.diffs.forEach(mergeIntoResult);
  i++;
} else {
  result.push(current);
}

Using word-diff

Git has another mode for generating diffs called word-diff. Github doesn't support this, but you can run it in your terminal like this:

Copygit diff --word-diff --no-index <old-file> <new-file>

Unlike the default Myer's algorithm, word-diff outputs the diff on a word-by-word basis. Each inserted word is wrapped in {+ and +} and each deleted word is wrapped in [- and -]. So we no longer need to guess which lines are modified.

Because it's parsing on word-level, we still need to merge adjacent insertions and deletions on each line using the same heuristics as before.

Copyimport { Check, [-Copy-]{+Copy, ChevronDown+} } from "lucide-react";

It does not have any options for when lines are similar enough. Our anti-example will be merged as well:

Copyimport [-{ useTheme }-]{+* as Collapsible+} from [-"next-themes";-]{+"@radix-ui/react-collapsible";+}

So we can use the same change ratio to split merged lines into separate insertions and deletions.

Copy// before
import [-{ useTheme }-]{+* as Collapsible+} from [-"next-themes";-]{+"@radix-ui/react-collapsible";+}
 
// after
[-import { useTheme } from "next-themes";-]
{+import * as Collapsible from "@radix-ui/react-collapsible";+}

And that's probably the best results we can get.