Open-source project
Wilfred/difftastic avatar
Wilfred/difftastic

difftastic: Dijkstra over a syntax graph, and no patch output at all

a structural diff that understands syntax 🟥🟩

26,187 stars538 forksRustMIT

At a glance

What is it?
A structural diff that compares parse trees instead of lines, so reformatting your code does not fill the output with noise. The mechanism is Dijkstra's algorithm over a graph. The cost is a set of boundaries the project states plainly: it will not produce a patch you can apply, it will not merge, it always considers order significant, it falls back to a line diff the moment it hits a parse error, and it scales poorly on heavily changed files.
Who is it for?
difftastic fits someone reading a large, heavily reformatted diff and trying to work out what actually changed, and it fits scripting through the check-only mode with an exit code. It does not fit a merge workflow or a patch pipeline, and both of those are declared non-goals rather than gaps.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly Rust, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • Wilfred/difftastic26,187 ★ · +241
Star history
Repository2026-09-282026-11-15
Wilfred/difftastic25.9k26.2k

241 Stars in the last 48 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The output is for humans, and it will not produce a patch you can apply

The most important sentence in this README is in a section called non-goals, and it is about patching. Difftastic output is intended for human consumption, and it does not generate patches that you can apply later. The instruction is to use `diff` if you need a patch.

The reason given is not a missing feature, it is a contradiction in the format. Patch files are line-oriented, which is too limited for this tool. Difftastic might find additions and removals on the same line, and it tracks the relationship between line numbers in the old and the new file, so a line-oriented patch has nowhere to put that.

That is a coherent argument and it has a direct consequence for how you use the tool. It belongs in a review, in a terminal, in front of a person deciding what changed. It does not belong in `git am`, in a cherry-pick, in a release script, or anywhere a machine consumes the output. If your workflow needs a patch, this is not the tool, and the README says so before you discover it.

The second non-goal is merging, and the reasoning is the same from the other direction. AST diffing is lossy from the perspective of a text diff. Difftastic ignores whitespace that is not syntactically significant, and merging requires tracking whitespace, so the information needed to merge is not information the diff keeps. AST merging is described as a hard problem that the tool does not address.

The README names the tool that does address it: mergiraf, which offers merges based on a tree-sitter AST. If merging is your requirement, that is the project to evaluate.

Dijkstra's algorithm over a syntax graph is why reformatting does not show up

The question at the bottom of the FAQ, how does it work, gets a two-sentence answer: structural diffing is treated as a graph problem, and Dijkstra's algorithm is used.

That is enough to predict the behaviour, and the behaviour is the reason to use the tool. Because the comparison happens between parse trees rather than between lines, the tool knows which pieces of syntax changed and can highlight them in context. It knows when whitespace matters, when it is a real change, and when it is only an indentation change. And it is not line-oriented, so if you reformat code so that a statement now spans several lines, the output still shows what actually changed rather than a wall of replaced lines.

The graph framing also explains the order sensitivity. In a tree, the order of children is structural, so a search for the cheapest edit path treats a reordering as a real change. Difftastic always considers order to be important, and diffing `set(1, 2)` against `set(2, 1)` will show changes even though the set is equal. For JSON, the README's advice is to sort the keys before you diff, and the example does exactly that with a key-sorting filter on each side of a process substitution.

Language coverage is broad, over thirty programming languages, with the full list in the manual. And the fallback is stated rather than hidden: if a file has an unrecognised extension, difftastic uses a line-oriented diff with word highlighting, which is a reasonable degradation and one you can detect, since the output shape is different.

There is a separate internals section in the manual and a blog post that describes the design, for anyone who wants to go past the two sentences.

A parse error silently downgrades the whole file to a line diff

This is the behaviour most likely to confuse you on first contact, because it changes the tool's output without telling you loudly.

By default, difftastic falls back to a line-oriented diff whenever parse errors are encountered. The stated reason is conservative and sensible: it ensures that difftastic never claims that two syntactically different files are the same. In other words, when the tool cannot understand the file, it refuses to use its clever mode rather than risk a false negative.

Parse errors happen for three reasons the documentation lists. The file may use language features the parser does not understand. The language may rely on a preprocessor before parsing, and C++ is the named example, which means any macro-heavy or conditionally compiled code is a candidate. Or the file may have genuine syntactic mistakes.

The tuning is an environment variable, and the documentation goes further than just naming it, telling you to consider allowing a small number of parse errors in practice because the tool virtually always produces a good result when there are a few:

sh
$ export DFT_PARSE_ERROR_LIMIT=20
$ difft foo1.c foo2.c

So the recommended posture is not to leave the default alone and not to disable the checks entirely. Set a limit, in the way you would set any other build tolerance, and know that a C or C++ codebase should probably set it before its first review rather than after someone wonders why the output looks like plain `diff`.

The other environment variable in the same family is one you will hit immediately on a dark terminal. Bright ANSI colours are used by default, and some themes render them as grey, with Solarized named as a popular theme that does this. Setting the background to light disables bright colours.

Order is always significant, so reordering data is your problem to solve

There is a whole FAQ entry devoted to this, which tells you how often people hit it.

The question is whether difftastic can ignore reordering, and the answer is no. It always considers order to be important, so two sets written with their elements in different orders will show as changed. There is no configuration flag to relax this, and the reasoning is inherent: order in a syntax tree is structure, not presentation.

For most code that is exactly right, because reordering arguments or parameters is a real change worth seeing. It becomes a problem for data formats where order is not meaningful, and JSON is the case the documentation picks. The fix is to normalise before you diff, sorting the keys on each side before the tool ever sees them:

sh
$ difft <(jq --sort-keys < file_1.json) <(jq --sort-keys < file_2.json)

That works, and it is a small piece of ceremony you now own. For a single comparison it costs nothing. For a pipeline it means the normalisation lives somewhere in your tooling, and if someone forgets it, they get a diff full of reordering noise and no error telling them why.

There is a longer discussion of unordered data types in the manual, linked from that answer, and a whole page on tricky cases, which suggests this is a category the project has thought about rather than stumbled into.

Merge conflicts are a related feature worth knowing about, since they arrived a while back. Since version 0.50, released on 2023-08-16, difftastic understands conflict markers. You pass the conflicted file as a single argument and it reconstructs the two conflicting files and diffs those, which is a genuinely useful thing to be able to do.

It scales poorly on heavily changed files, and the project tracks its own numbers

The Known Issues section of this README is short and unusually honest, and the first item is performance. Difftastic scales relatively poorly on files with a large number of changes, and can use a lot of memory.

That is the inherent cost of the design. A graph search over parse trees is cheap when the trees are similar and the edit is small, which is the common review case. It is expensive when the two versions of a file have diverged a lot, because the search space grows with the difference rather than with the size. So the tool is at its best on the diff you most want to read carefully, a focused change, and at its worst on a file that was rewritten.

The memory point compounds it, and it is the reason to know this before you point the tool at a generated file or a vendored dependency.

What is more interesting is how the project responds to its own stated weaknesses. The build has a target that runs an output regression test over a directory of sample files, which is how a display change gets caught. There is a separate performance target that builds in release mode and runs the system profiler against named baseline file pairs, one pair for a typing scenario and one for a slow scenario, writing timestamped baseline files. So the project measures its performance on known-slow inputs on purpose, and keeps the results.

The second known issue is display. The side-by-side display usually works well but can be confusing, which is a design tension rather than a bug: a structural diff has nested changes, and nesting two of them across two columns is a lot to read. The third is robustness, and the phrasing is the most honest line in the file: difftastic regularly has releases that fix crashes.

The MSRV is 1.85 for packagers, and one dependency is capped for the same reason

The manifest has a comment explaining its minimum supported Rust version, and the reason is not technical taste.

The stated goal is to support at least twelve months of Rust versions and to be conservative about upgrades to help packagers. The minimum is 1.85.0, and the comment notes that Debian stable is on 1.85 while Debian does not currently package difftastic, with other distributions being somewhat newer.

So the floor is set by a distribution's Rust version rather than by a language feature the code needs. That is a deliberate choice, and it has a cost you can see in the dependency list. One dependency is capped with an inline comment explaining that it does not declare its own minimum Rust version, but it is part of ripgrep, which has a slightly more aggressive minimum than difftastic, and that a particular version of it requires a newer Rust. The result is a range with an upper bound below the latest release, pinned to keep the project's own floor intact.

That is the shape of a real trade-off made explicitly. A project chasing the newest Rust would take the newest version of that dependency and raise its own floor. This one holds the floor for the benefit of packagers and accepts an older version of that dependency.

Two more packaging details are worth knowing. The published crate's include list contains the vendored parser sources, including C and header files and the highlight query files, so the crate you download is not pure Rust. And there is a prebuilt-binary URL template configured for the binstall installer, with a format override for one Windows target so it gets a zip rather than the default archive format.

--check-only with --exit-code is the part to put in a script

The most immediately useful thing in this README is a short answer to a question about not diffing at all.

Yes, difftastic can check whether two files have the same abstract syntax tree without calculating a diff. It is much faster than normal diffing, and it is explicitly described as useful for building tools that check for changes.

sh
$ difft --check-only --exit-code before.js after.js

The exit code is the contract: zero if there are no syntactic changes, one if changes are found. That is the whole interface, and it is enough to put a syntax-level check in a pipeline.

What it is good for is worth being specific about, because it is not the same as the other checks you could put there. A formatter check asks whether the file is formatted. A linter asks whether it satisfies a set of rules. This asks whether the two versions of the file are the same program, which means a reformat that touches no syntax passes, and a whitespace change that does affect a language where whitespace is significant fails. That is a check you cannot easily write yourself, and it is fast enough to run on every commit.

The README does not say how this mode treats parse errors, so test it against files that fail to parse before you rely on it in a pipeline.

On integration, the FAQ is blunt: probably not, because the tool is young, and the author invites you to write a plugin for your own tool and link it in the README. Two integrations are named anyway, an Emacs package and a blog post about using it with magit, along with documented git and Mercurial usage.

The version in the manifest is the one you do not have yet

A small versioning detail that will save you a confused afternoon if you are tracking releases.

The manifest declares version 0.73.0. The most recent release is 0.72.0, published on 2026-10-29, with 0.71.0 from 2026-09-18 and 0.70.0 from 2026-08-07. The last push to the repository was on 2026-11-02.

So the version in the manifest is ahead of the newest release, and that is by design rather than by accident. The release recipe reads the current version out of the package metadata, tags it, pushes the tags to trigger a release on the CI, and then bumps the minor version. So the sequence is: the manifest holds the version you are about to publish, the tag is cut from it, and then the manifest moves on to the next one. A clone of the default branch is always one minor version ahead of what you can download.

The release notes are generated rather than written at tag time. A separate recipe produces notes for the currently unreleased version by searching the changelog for release markers and extracting the paragraphs since the last one, so the changelog is the source of truth and the release body is a slice of it.

Two other pieces of the release machinery are visible in the build. The man page is generated from a markdown source through a document converter, so the man page is maintained as Markdown. And the documentation itself is an mdbook served from its own directory during development, which means the manual is versioned in the repository rather than being an external site that can change under you.

The repository also carries a Chinese translation, a citation file, an AI policy document, and a changelog.

Editorial conclusion

difftastic fits someone reading a large, heavily reformatted diff and trying to work out what actually changed, and it fits scripting through the check-only mode with an exit code. It does not fit a merge workflow or a patch pipeline, and both of those are declared non-goals rather than gaps. Verify first by running it on a file in a language that uses a preprocessor, since that is the case the documentation flags as most likely to hit a parse error, and raise the parse error limit deliberately rather than accepting the line diff you get by default.

Frequently asked questions

How does the diff algorithm work?

Difftastic treats structural diffing as a graph problem and uses Dijkstra's algorithm to find the cheapest edit path between two parse trees. That is why it understands which pieces of syntax changed, distinguishes significant whitespace from an indentation change, and is not line-oriented, so reformatting a statement across several lines still shows what actually changed. There is an internals section in the manual and a blog post describing the design.

how to use difftastic

Point it at two files, or use the documented git and Mercurial integration. Useful flags covered in the README include --check-only with --exit-code, which reports only whether the two files have the same syntax tree and sets the exit code accordingly, and the environment variables for tolerating parse errors and for fixing colours on themes that render bright colours as grey.

difftastic alternative

For merging, the README names mergiraf, which does merges based on a tree-sitter AST, and explains why difftastic does not: it ignores whitespace that is not syntactically significant, and merging requires tracking whitespace. For producing a patch you can apply, the answer is diff, since difftastic's output is for human consumption and is not a patch file.

difftastic vs git delta

The README does not compare itself to git delta, so there is no measured claim to repeat here. It does name its own boundaries: it is not line-oriented, it will not produce an applicable patch, it will not merge, it always treats order as significant, and it falls back to a line diff when a file cannot be parsed. Its own comparison target is mergiraf, for merging rather than diffing.

Official sources

  1. License: MIT
  2. Project website
  3. README
  4. Releases
  5. Wilfred/difftastic on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/wilfred-difftastic.svg)](https://hysenlabs.com/projects/wilfred-difftastic)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/wilfred-difftastic.svg)](https://hysenlabs.com/projects/wilfred-difftastic)

Was this useful?