= KDiff3 =

This is a subjective evaluation of KDiff3. Please add your opinion. 

== Description ==

[[https://apps.kde.org/en/kdiff3|KDiff3]] is a KDE / Qt graphical merge and diff tool. For 3-way merge it can show both the 2 parent versions and their common ancestor side-by-side in top panes and the editable merge result in the bottom pane.

It is GPL and runs on "all" platforms. It is included in the TortoiseHg installer for Windows.

== Usage notes and tips ==

 * The first time you use the program to merge, the text coloring system might throw you for a loop.  Text is colored according to the file that is different.
   * Each file has a unique color, and you can tell what that color is by looking up by the file name.  By default File A has a color of blue, File B has a color of green, and file C has a color of purple.
   * Red text indicates text that is unique to that file.
   * Text that is colored blue, green or purple (or whatever you've set file colors to) is the same in every file '''except''' the file whose color the text belongs to.
   * As a quick example, if a line is identical in File A and File B, but is different in File C, then that line will be colored purple in Files A and B, and red in File C.
 * The option {{{--auto}}} will try to auto-merge silently, similar to what Mercurial premerge does. Disabling Mercurial premerge will not disable kdiff3 auto merge.
 * KDiff3 can be used with {{{kdiff3.args=--L1 base --L2 local --L3 other $base $local $other -o $output}}}
 * One change has focus at a time; the currently selected change is yellow-ish - move with up/down triangle buttons or use ctrl+up/down.
 * The 3 input files are labelled A, B and C, and appearance of the 3 sides of a change in the merge result can be toggled with buttons or ctrl+1/2/3.
 * The margin of the merge result shows where the lines come from (or m for manual changes).
 * Usage example in [[http://hgbook.red-bean.com/hgbookch3.html|hgbook]].

== More tips ==

Add to {{{~/.hgrc}}}:

{{{
[extensions]
hgext.extdiff =

[extdiff]
cmd.kdiff3 =

[merge-tools]
kdiff3.args = $base $local $other -o $output
}}}

This adds a new graphical diff command {{{hg kdiff3}}} (using ExtdiffExtension), and tells Mercurial to use kdiff3 for merges.

Useful shortcuts that can be defined in '''Settings / Configure Shortcuts''':

 * Ctrl-U: Unfold All Subdirs
 * Ctrl-T: Dir & Split Screen View (on/off) 

You can move between file panes and directory pane using Alt-Left and Alt-Right.

You can compare arbitrarily selected files. Click on left square of old file, and "A" appears in the square. Click on right square of new file, and "B" appears in the square. Right-click on the "B", and select "Compare Explicitly Selected Files".

If you want to view some file in your favorite editor (e.g., to get usual syntax highlighting, and large window), you can copy-and-paste file name at the top of the file window pane, and open it in your editor. All other modified or added files are in the same directory, so you can just navigate to them from your editor instead of selecting them in kdiff3 and repeating cut-and-paste. (In order for this to work, don't use the {{{--L1 base --L2 local --L3 other}}} described in earlier section.)

When you run kdiff3 directly, the following may help when comparing two source trees:

 * '''Settings / Configure KDiff3... / Directory Merge / Dir-anti-pattern(s)''': append: {{{;.hg}}}
 * '''Settings / Configure KDiff3... / Directory Merge / File-anti-pattern(s)''': append: {{{;*~}}} 

== Mac ==

On Mac, kdiff3.app executable location is {{{/Applications/kdiff3.app/Contents/MacOS/kdiff3}}}.
Make sure you add {{{/Applications/kdiff3.app/Contents/MacOS}}} to your $PATH,
or create a symlink from a directory in your $PATH to {{{/Applications/kdiff3.app/Contents/MacOS/kdiff3}}}
(or create a wrapper script, or ...),
if you want to invoke kdiff3 from command line
or from Mercurial invoked from command line.

== Issues ==

 * Will try to merge binaries if you tell it to - so configure your merge-tools properly (or choose "whole file" as a workaround)
 * Doesn't look fancy
 * Qt and KDE dependencies
 * Doesn't do a good job of handling UTF and encodings on windows.

== Conclusion ==

KDiff3 is the "best" merge tool; stable and feature rich.