Difftastic

Difftastic is a structural diff tool that compares files based on their syntax rather than just lines of text. It understands the underlying AST (Abstract Syntax Tree) of a file, allowing it to:

• Highlight exactly which syntactic pieces have changed.
• Distinguish between significant whitespace and mere indentation changes.
• Handle code reformatting (e.g., splitting a single line into multiple lines) without showing them as massive changes.
• Fall back to a line-oriented diff with word highlighting if a file extension is unrecognized or if parsing fails.

Difftastic performs syntactic diffing by detecting the language, parsing the code into syntax trees, and comparing those trees directly. This allows the tool to recognize that code logic remains unchanged even if whitespace or line breaks are modified (e.g., changing a single-line method chain into a multi-line chain).

Unlike standard line-oriented diffs that see a change in line structure as a complete replacement of the line, Difftastic identifies matched delimiters and unchanged components within the syntax tree.

// old.rs
let ts_lang = guess(path, guess_src).map(tsp::from_language);

// new.rs
let ts_lang = language_override
    .or_else(|| guess(path, guess_src))
    .map(tsp::from_language);

Difftastic uses specific heuristics to avoid common diffing errors:

• Sliders (Flat and Nested): In text diffs, 'sliders' occur when lines are matched incorrectly (e.g., matching a delimiter line instead of a content line). In tree diffs, this happens when an insertion causes ambiguity in which delimiters match. Difftastic's behavior depends on the language; most languages prefer matching the inner delimiter, while Lisps and JSON prefer the outer delimiter.
• Minimizing Depth Changes: When multiple nodes could potentially match (e.g., matching foo(123) vs foo(456) against a new foo(789)), Difftastic prefers the match that maintains the same nesting depth.

Difftastic's tree-based approach provides specific behaviors for structural changes:

• Reordering Within a List: For changes like (x y) to (y x), Difftastic aims to highlight the list contents as changed rather than the delimiters.
• Middle Insertions: When a new node is inserted into the middle of a nested structure (e.g., foo(bar(123)) to foo(extra(bar(123)))), Difftastic attempts to treat the surrounding nodes (foo and bar) as unchanged.
• Unordered Data Types: Unlike some tools that might ignore order in sets or maps, Difftastic considers ordering to be meaningful everywhere. It will always report changes if the order of elements in a list, set, or object changes.

// Before
(x y)

// After
(y x)

Difftastic uses a fallback mechanism when syntactic parsing is not possible. It will use a conventional line-oriented diff with word highlighting in the following scenarios:

1. Unsupported Formats: If the input files are not in a format that Difftastic recognizes or can parse.
2. Large Inputs: When the input files are extremely large, Difftastic defaults to line-oriented diffing to maintain performance.

Difftastic applies specific logic to non-code elements to improve readability:

• Comments:
  • Matching Substrings: For code, Difftastic avoids matching common prefixes (like foobar vs foobaz). However, for comments, it allows matching common prefixes or suffixes.
  • Multiline/Reflowing Comments: Difftastic treats the inner content of block comments as identical even if decorative prefixes (like * in a doc comment) move or change due to reflowing.
• Strings: While it is difficult to handle small changes in very large strings, Difftastic aims to show changes within string literals rather than simply marking the entire string as replaced.

When reading Difftastic's output, the following terms describe the comparison results:

• LHS (Left-Hand Side): The first item being compared.
• RHS (Right-Hand Side): The second item being compared.
• Novel: Syntax that is an addition or a removal (it exists in only one of the two items being compared).
• Hunk: A group of lines displayed together in the diff output. The size of a hunk is determined by the number of context lines.
• Slider: A specific diffing scenario where multiple minimal diffs are possible due to adjacent content. Difftastic can 'slide' to find a better structural match.
• Line-oriented: A reference to traditional diff tools (like GNU diff or GitHub's default view) that compare line additions/removals rather than syntax tree structures.

Difftastic can use a MIME database (the same one used by the file command) to detect binary files more accurately. If a database is present at one of the standard XDG specification paths, Difftastic will automatically use it.

Supported paths for the MIME database:

• /usr/share/mime/magic
• /usr/local/share/mime/magic
• $HOME/.local/share/mime/magic

Because Difftastic performs syntactic diffing (comparing tokens), it does not 'see' blank lines by default.

• Standard Behavior: Generally, syntactic diffing ignores blank lines, meaning adding or removing them typically shows no change.
• Limitations: This can occasionally hide accidental reformatting. If a user inserts code and a blank line simultaneously, the syntactic diff may only show the code addition, potentially hiding the fact that blank lines were also modified.