KDiff3 merges three-way conflicts in a side by side editor

Comparing files, directories, and three versions at once

KDiff3 is described as a program that compares and merges two or three input files or directories, shows the differences line by line and character by character, provides an automatic merge facility and an integrated editor for solving merge conflicts.

The three-way support is the reason this tool still matters. A two-way diff tool tells you what changed between two files. A three-way tool takes a base and two modified versions and works out which change belongs to which side, which is what a version control conflict actually is. The command line notes make the base explicit: when you pass three files, file1 is treated as the base of file2 and file3.

Directories are treated as first class inputs, not as something you point at file by file. If all the files have the same name but are in different directories, the documentation says you can reduce typing by specifying the filename only for the first file, for example kdiff3 dir1/filename dir2 dir3, and that this also works in the open dialog.

Around that core the tool carries a set of features that place it in its era. It has support for KDE-KIO for ftp, sftp, http, fish and smb, a context menu integration for KDE-Dolphin and Windows Explorer, support for 64 bit systems, and support for many encodings and Unicode.

The audience is a person resolving a conflict by hand, or comparing two directory trees. It is a desktop application, not a tool for a pipeline, which matters for how you would use it.

Character level diffs inside a line level diff

The two-level diff is what makes the display readable. KDiff3 shows changes at the granularity of lines, and when a line has changed it drills down to show which characters within that line differ.

That structure is the reason to choose this over a line-only diff. A one-line change to a long configuration line or a minified file is unreadable when you only see the whole line, and the usual workarounds are to reformat the file first or to squint. Character level highlighting localises the change without requiring either.

The merge facility is built on the same view. Because the tool already has a structural understanding of what changed inside each line, it can offer an automatic merge for the parts that do not conflict and isolate the parts that do, and the integrated editor is where you resolve what is left. That is a different workflow from merging outside the tool and then re-reading the result to see what went wrong.

The documentation points to the help menu and the doc subdirectory for more, and notes that the old pre KF5/Qt5 build instructions have been removed to avoid confusion. The top-level readme is about building and current state rather than about usage, which means the in-application help and the doc directory are where the usage detail lives.

Command line invocations that all open the same window

The command line interface is short, and every form of it starts the graphical program. The usage notes list the invocations like this:

   - Comparing 2 files:     kdiff3 file1 file2
   - Merging 2 files:       kdiff3 file1 file2 -o outputfile
   - Comparing 3 files:     kdiff3 file1 file2 file3
   - Merging 3 files:       kdiff3 file1 file2 file3 -o outputfile

With three files, the note explains that file1 will be treated as base of file2 and file3. The -o flag writes the merged result to a file, which is how you script a merge that still happens in the interface. If you start without arguments, a dialog appears where you can select the files through a file browser.

This is the design decision that most affects adoption. There is no headless mode described anywhere in the documentation, and no output format for the diff itself. So KDiff3 is a tool you sit down at, not a tool you call from a script that wants machine readable differences.

For a team that wants a diff in a terminal or in a CI log, that rules it out, and the alternative is a line oriented diff tool. For a person resolving a nasty conflict, opening a window is not a disadvantage.

One historical note explains a limitation you may hit. The Konqueror specific plug-in is not ported and no longer maintained, and the documentation says it would only apply to KDE before 4.6. The repository still carries a kdiff3fileitemactionplugin directory, which is the Dolphin file manager integration, and a diff_ext_for_kdiff3 directory, which is the Windows Explorer integration.

Building it means Qt 5.12, KF5 5.70 and CMake

The build requirements are stated plainly. The project documentation says it now requires Qt 5.12 or later and KF5 5.70 or newer, and that legacy 0.9.98 and earlier builds are not supported. As of 1/13/17 cmake 3.1 or later is the targeted cmake version.

cmake is the only build system supported. The documentation is direct about why: KF5 and Qt5 were a big jump, a lot changed besides just the API, and the author is not against a Qt5-only build variant but sees no reason to maintain two separate build systems. At present KF5 is the focus.

There is a historical layer underneath that. The original pre KF5/Qt5 documentation said KDiff3 runs best on KDE but can be built without it, depending only on Qt libraries, and those are available for Unix, Windows and Mac, so there are many setup possibilities to consider. That older text listed supported Qt versions of 4.8 and 5.2 or higher and supported KDE versions 4 and 5, with a pointer to KDiff3-0.9.92 or older for KDE3/Qt3. Those instructions have been removed to avoid confusion, so treat them as history rather than instructions.

The repository is a modern KDE project in structure even if the version numbers are old. There is a CMakeLists.txt at the root, a .craft.ini, .gitlab-ci.yml and .kde-ci.yml for continuous integration, a .clang-format and .clang-tidy, a UBSan.supp suppression file, a CppCheckSuppressions.txt, po/ for translations, doc/ for documentation, test/ for tests and src/ for the source. There is also a flatpak-manifest.json, which means a flatpak build is available for distributions that want one.

Two known issues, one of them binary comparison

The known issues list is short and worth reading before you choose the tool.

The first is that binary comparison has been temporarily disabled due to stability issues. That is a real functional gap. If your workflow includes comparing compiled artefacts, images, or other binary files, KDiff3 as currently built will not do it, and there is no documented workaround in the project documentation. Any plan that depends on it needs a different tool for that step.

The second is that the network comparison operation via non-file URLs may fail for some configurations, and the documentation says this is under investigation. Note the scope. The KIO support for ftp, sftp, http, fish and smb is listed as a feature of the application, and the caveat concerns the comparison operation specifically, over non-file URLs. So opening a remote location and browsing it is not the same thing as reliably diffing two remote locations.

The rest of the documentation is about state rather than features. The macOS X build is 64-bit only, and the author adds that he cannot test the build locally, which is a candid note about where the confidence is lower.

For a tool that has been in development since 2002, with a copyright line running 2002 to 2014 for Joachim Eibl and a port to KF5 and Qt5 by Michael Reeves, this is a project with a long history and a current maintainer who is explicit about what is unfinished.

Where to get binaries, and what the packaging gives you

The current repository is at invent.kde.org, which is where the source now lives, and the packaging has moved on from the standalone program into the distribution channels.

For binaries, the readme points at the KDE download server at download.kde.org/stable/kdiff3, and bugs can be reported at bugs.kde.org. The default branch is master and the project publishes no GitHub releases, so the KDE infrastructure rather than GitHub is where you get a packaged artifact.

The flatpak manifest is the other distribution route, and for KDE applications it is the one that gives you a consistent environment without chasing dependencies. That matters here specifically, because the build requirements are not trivial: Qt 5.12, KF5 5.70, and CMake 3.1 or later.

The translation story is also worth noting. The project asks for help translating and points to the KDE localisation site, and the po/ directory in the repository is the gettext catalogue for that work. A widely translated diff tool is a real advantage when you are comparing files across languages, and the documented support for many encodings and Unicode is the practical counterpart to that.

For a project that runs best on KDE but can be built against Qt alone, the practical choice is usually to install the distribution package if you are on a KDE desktop, and to use the flatpak or a Qt-only build elsewhere.

Editorial conclusion

KDiff3 suits a developer or sysadmin who needs a real three-way merge with a readable conflict view, particularly on a KDE desktop where it is already packaged, or anyone who wants to compare directories rather than just files. It is the wrong choice if you need a terminal-only workflow, since every documented invocation opens the graphical interface, and the wrong choice if you rely on binary comparison, which the documentation lists as temporarily disabled because of stability issues. Before adopting it, check the two known issues against your case, that binary comparison is disabled and that network comparison via non-file URLs may fail for some configurations, and build it against a Qt and KF5 version at or above the stated minimums.

Frequently asked questions

Official sources

1. Issues
2. KDE/kdiff3 on GitHub
3. License: GPL-2.0
4. Project website
5. README