Guide · Open source
How to use difftastic: structural diffs in the terminal
Updated · written with AI from the project's own documentation and checked against our catalogue data
Difftastic is a command-line tool that compares two versions of a file by their code structure instead of line by line. This guide is for developers and reviewers who want to see what actually changed in code, without reformatting noise. After reading it you will know how to install difftastic, compare files, use it with git, and check when its output is not the right tool.
difftasticWilfred/difftastic · ★ 26.1k · MIT Install options & downloads Quick start
- 1Install difftastic. Follow the Installation page in the difftastic manual and use a package manager for your system.
- 2Run a basic comparison. Call difft with the old file and the new file to see structural changes highlighted.
- 3Connect it to git. Follow the git instructions in the manual so git uses difftastic for diffs.
- 4Check syntax only. Use difft with --check-only and --exit-code to get a pass or fail exit code for syntactic changes.
- 5Plan around the limits. Use diff for patch files and mergiraf for merges, and expect slowness on very large diffs.
What difftastic does differently from diff
Difftastic is a structural diff tool that compares files based on their syntax. It highlights what actually changed, so if you reformat code and it now splits across several lines, difftastic shows no real change for that part.
If a file has an unrecognised extension, difftastic falls back to a line-oriented diff with word highlighting.
- Works with over 30 programming languages; the manual has the full list.
- Understands when whitespace matters and when it is only an indentation change.
Install difftastic
The project's installation instructions are in the manual at difftastic.wilfred.me.uk. The README points to the Installation page there, and the install method for this tool is a package manager. Check that page for the commands for your system.
The README also shows how to clone the source repository from GitHub if you want to work from the code.
git clone https://github.com/Wilfred/difftasticCompare two files with difftastic
Run the difft command with the old file first and the new file second. The output highlights the syntactic changes in context.
Difftastic uses a side-by-side display, which usually works well but can be confusing at first. Its output is meant for people to read.
difft foo1.c foo2.cUse difftastic with git
Difftastic is compatible with git. The manual has the configuration instructions in its git usage section, and it also covers mercurial and other version control systems.
Emacs users can look at difftastic.el and a blog post on using difftastic with magit, both linked from the README.
- Full git setup: see the git page in the difftastic manual.
- Mercurial setup: see the mercurial page in the manual.
Check for syntactic changes without a diff
Difftastic can check whether two files have the same AST without calculating a diff. The README says this is much faster than normal diffing and useful for building tools that check for changes.
With --exit-code, the exit code is 0 when there are no syntactic changes and 1 when changes are found.
difft --check-only --exit-code before.js after.jsHandle merge conflicts, parse errors and reordering
Pass a file containing conflict markers (<<<<<<<, ======= and >>>>>>>) as a single argument. Difftastic builds the two conflicting files and diffs those.
By default, difftastic falls back to a line-oriented diff when it hits parse errors, so it never claims two syntactically different files are the same. If you accept a small number of parse errors, you can raise the limit with DFT_PARSE_ERROR_LIMIT.
Difftastic always treats order as significant. For JSON, sort the keys first with jq.
- Terminal colours look grey? Solarized users can run export DFT_BACKGROUND=light to disable bright colours.
$ difft file_with_conflicts.js
$ export DFT_PARSE_ERROR_LIMIT=20
$ difft foo1.c foo2.c
$ difft <(jq --sort-keys < file_1.json) <(jq --sort-keys < file_2.json)Know the limits before you rely on it
Difftastic scales relatively poorly on files with many changes and can use a lot of memory. Its output is for human reading and does not generate patches, so use diff if you need a patch file.
Difftastic does not perform AST merging. For merges, the README points to mergiraf, which does.
- Need a patch: use diff.
- Need merges: use mergiraf.
- Very large files with many changes: expect slowness and high memory use.
What people use it for
- Reviewing a git commit where code was reformatted and you only want to see real changes.
- Comparing two source files in a supported language to see which syntax changed.
- Checking in a script that two files have the same syntax, using --check-only.
- Viewing syntax-aware diffs inside an Emacs workflow with magit.
Frequently asked questions
Is difftastic free to use?
Difftastic is open source under the MIT license, according to the README. The license file in the repository has the full terms.
What do I need to run difftastic?
The source material does not list any prerequisites for difftastic. Check the installation instructions in the manual for your platform.
Can I use difftastic with git?
Yes. The difftastic manual includes instructions for git usage, and the README also mentions mercurial and other version control systems.
Why does difftastic show a line-by-line diff for my file?
Difftastic falls back to a line-oriented diff when a file has an unrecognised extension or when it hits parse errors. You can raise the parse error limit with DFT_PARSE_ERROR_LIMIT if a few minor errors are expected.
Is difftastic a replacement for diff?
Not for every job. Difftastic output is for human reading and does not produce patches, so the README says to use diff when you need a patch file.
What is the difference between difftastic and mergiraf?
Difftastic compares files by structure but does not merge them. The README says mergiraf does AST merging, which difftastic does not address.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Difftastic suits developers reviewing code in supported languages, especially when reformatting adds noise, and teams that want a syntax-only check. Pick diff if you need patch files, mergiraf if you need AST merges, or another tool if you regularly diff very large files with many changes.
Install options & downloads