Difftastic: A Syntax-Aware Diff Tool
Difftastic replaces the red-and-green line diff in your terminal with output that follows the actual syntax tree, so a reformatted function shows up as one small change instead of a wall of noise. It earns a spot in your review workflow the first time a rustfmt or gofmt run stops looking like a full rewrite. The catch: no patch output. You still need plain `diff` for anything you plan to apply with `patch`.
Why line-by-line diffs miss what actually changed in code
Standard `diff` compares files line by line, so moving a closing brace, reindenting a block, or wrapping a long call across multiple lines all show up as deletions and insertions even though nothing about the code's meaning changed. Reviewers end up scanning walls of red and green to find the one line that actually matters. Reformatting commits become unreviewable this way. Difftastic exists because line-based diffing has no concept of syntax — it treats a stray `{` and a renamed function the same way, as just more changed characters.
What is Difftastic
Difftastic is a structural diff tool written in Rust that compares files by their syntax rather than their text, using tree-sitter parsers to understand each language's actual grammar. It supports over 30 programming languages, and falls back to a line-oriented diff with word highlighting for any file extension it doesn't recognize. Under the hood, it treats diffing as a graph problem and finds the edit path with Dijkstra's algorithm.
Syntax-aware diffing with tree-sitter
- ✓Highlights only the syntax that actually changed, not every line touched by reformatting
- ✓Distinguishes whitespace that changes meaning from whitespace that's just indentation
- ✓Understands git merge conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`) directly
- ✓`--check-only --exit-code` reports whether two files are syntactically identical without printing a diff
- ✓Falls back to a line-oriented diff with word highlighting when a file's syntax can't be parsed
- ✓Finds the diff by treating edits as a graph problem and running Dijkstra's algorithm over it, instead of a simple line-matching heuristic
Installing Difftastic
The README doesn't list install commands directly — it points to a dedicated Installation page in the official manual instead. That's a deliberate choice: package availability across different package managers and Linux distros changes faster than a README can track, so the project keeps the authoritative list off-repo. If you're evaluating Difftastic, expect to leave GitHub and check the manual before you get a working `difft` binary. Installation steps themselves are not clearly documented in the repository facts available here.
Using Difftastic with git and on the command line
Once installed, the command-line binary is `difft`, and the README documents git and Mercurial compatibility with configuration instructions kept in the manual rather than in the repo itself. A handful of behaviors are controlled through environment variables and flags you use directly. Hitting parse errors on a file? Raise the tolerance with `export DFT_PARSE_ERROR_LIMIT=20` before running `difft foo1.c foo2.c`. Feed it a file with unresolved git conflict markers and it reconstructs both sides: `difft file_with_conflicts.js`. For CI, skip the diff output and get a pass/fail signal instead with `difft --check-only --exit-code before.js after.js`, which exits 1 only if the AST changed. Terminal showing bright colors as grey (a known Solarized issue)? Set `export DFT_BACKGROUND=light`. For diffing unordered data like JSON, sort keys first, since Difftastic treats reordering as a real change: `difft <(jq --sort-keys < file_1.json) <(jq --sort-keys < file_2.json)`.
What Difftastic gets right
- ✓Reformatting a function no longer buries the real change in a diff full of red and green
- ✓Parses git merge conflict markers directly, so you can inspect both sides without a separate three-way diff step
- ✓`--check-only --exit-code` is a fast, scriptable way to ask "did the AST change" in CI
- ✓MIT-licensed, so it drops into a commercial toolchain without a licensing conversation
Known limitations and edge cases
- △Speed suffers on heavily-edited files with lots of changed hunks, and memory use can climb, per the project's own Known Issues list
- △The side-by-side display usually works but the README itself calls it confusing at times
- △No patch output — it's built for reading, not for generating a file you can apply with `patch`
- △Doesn't do AST-aware merging; the README points to the separate mergiraf tool for that job
- △The README describes the project as young and says it probably doesn't integrate with your favorite editor or tool yet
Difftastic alternatives
Frequently asked questions
Difftastic ships git and Mercurial support, but the exact configuration commands live in the project's manual rather than in the README itself. Once set up there, running `git diff` calls the `difft` binary automatically instead of the default line-based diff, so your usual git workflow doesn't otherwise change.
Difftastic supports over 30 programming languages through tree-sitter parsers, with the full list maintained in the official manual rather than the README. A file with an extension Difftastic doesn't recognize still gets diffed — it just falls back to a line-oriented diff with word-level highlighting instead of a syntax-aware one.
Difftastic switches over to a plain line-by-line comparison whenever it hits a parse error, a deliberate conservative choice so it never claims two syntactically different files are identical. Errors happen with unsupported language features, preprocessor-dependent languages like C++, or genuine syntax mistakes. Raise the tolerance for minor errors with `export DFT_PARSE_ERROR_LIMIT=20`.
Difftastic can parse git merge conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`) directly, as of version 0.50, released 2023-08-16. Pass the conflicted file as a single argument, like `difft file_with_conflicts.js`, and Difftastic reconstructs both sides and diffs them, though it still can't perform the merge itself.
Difftastic is released under the MIT license and hosted publicly on GitHub, so it's free to use, modify, and ship inside commercial tooling. The bundled tree-sitter parsers in its vendored_parsers directory carry a mix of MIT and Apache licenses from their original authors, worth checking if you redistribute the binary.
Difftastic automatically drops down to a line-oriented diff with word-level highlighting for any file it can't parse, whether that's an unrecognized extension or a file with too many syntax errors. This keeps Difftastic usable outside its supported languages, just without the syntax-aware comparison that's its main selling point.
Best use cases
- •Reviewing pull requests where a formatter like rustfmt or gofmt reflowed a file and you need to see the logic change, not the reflow
- •Diffing reformatted config or source files, since Difftastic ignores whitespace that isn't syntactically significant
- •CI checks that only care whether a generated file's AST changed, using `--check-only --exit-code` instead of parsing diff text
- •Resolving a merge conflict by hand, since Difftastic can parse both sides of the conflict markers structurally instead of as raw text
Who should try it — and who should skip
Try Difftastic if you review a lot of pull requests in statically-parseable languages and keep getting diffs dominated by reformatting noise. Skip it if you need patch files you can apply elsewhere, or if you mostly work in file formats outside its 30-plus supported languages, since you'll just get the line-oriented fallback anyway.
Related repositories
Want a second opinion on difftastic?
Ask an AI that can read this page — one click and you get its take on difftastic.
