How to Use Kdiff3 as a 3-way Merge Tool With Mercurial, Git, and Tower.app

Jan 12th, 2012 | Comments

There are a few very nice looking, mac-like diff tools for OSX (Kaleidoscope and
Changes come to mind), but none for doing “real” merges. By this, I mean real,
3-way merges with all of the information you need in front of you.

There are no good-looking, “mac-like” merge tools, but if you swallow your pride there are a few different options for 3-way merges, including
Araxis Merge ($$$!),
DiffMerge,
DeltaWalker, and
FileMerge which comes free with XCode.

I’ve tried them all, and find them all confusing. They all tend use a 3-pane display to do the merging with your file in the left pane, the file you’re merging in the right pane, and the messy half-merged file in the middle.

That’s not enough information.

A 3-way merge actually has four important sources of information:

LOCAL - your file with the changes you’ve made to it
REMOTE - the file you’re merging in, possibly authored by someone else
BASE - the common ancestor file that LOCAL and REMOTE came from
MERGE_RESULT - the file resulting from the merge where you resolve conflicts

You often need to see all four of these pieces of information to make intelligent choices. Where you came from (LOCAL), where the other person’s changes came from (REMOTE), where you both started (BASE) and where you
are now (MERGE_RESULT).

Most other 3-way merge tools either conflate or omit the BASE and that can make it harder to see what the right thing to do is.

Kdiff3 is my merge tool of choice. It’s not pretty; it’s cross-platform
Qt based so it has a very old-school linux GUI feel to it. But like linux, it’s functional and can help you quickly be productive once you get over the learning curve.

If you’ve got 2 heads that you need to merge in your current repository: We made this modification to
file.txt:

diff --git a/file.txt b/file.txt
--- a/file.txt
+++ b/file.txt
@@ -1,1 +1,1 @@
-BASE: common_ancestor
+LOCAL: file in current working branch

and they made this change to the same file and line:

diff --git a/file.txt b/file.txt
--- a/file.txt
+++ b/file.txt
@@ -1,1 +1,1 @@
-BASE: common_ancestor
+REMOTE: other branch we're merging in

If you run your SCM’s merge command (here, in mercurial: hg merge -r 2), and have kdiff3 configured as your merge tool, you’ll get a pop-up window like this:
As you can see, it shows you all 4 pieces of information,
BASE, LOCAL, and REMOTE on top, and the MERGE_RESULT file on the bottom. It currently has a Merge Conflict that you need to fix.

You can move from one unresolved conflict to the next using the triple up and triple-down colored arrows in the middle of the tool bar. When a conflict is highlighted, you can press any combination of the A, B, and C buttons in the toolbar. Pressing one
of those buttons will resolve the conflict with the code from pane A, B, or C on top. So if the
LOCAL file (your file) had the right changes in it, you’d press B.

It’s possible to press more than one button if code from multiple panes is valid. You can also directly edit the file in the
MERGE_RESULT pane to make manual changes if the correct merge is not the exact text in A/B/C.

Another option, if you want to take all of the changes from one file and discard any changes from the others, is to go to the “Merge” menu and pick one of “Choose A Everywhere”, “Choose B Everywhere”, or “Choose C Everywhere”.

Once you’ve resolved your file, simply save it (cmd-S) and quit out of kdiff3. Your SCM should see the
MERGE_RESULT no longer has any merge conflicts and will mark it as resolved, ready for you to commit it. If there are other files with merge conflicts, you can repeat the process with those files.

Installing kdiff3

Installing kdiff3 is as easy as downloading the latest version from sourceforge and copying it to your /Applications directory.

The app is a simple wrapper around a Qt-based application. It can be run from the command line at
/Applications/kdiff3.app/Contents/MacOS/kdiff3. You can make a symlink of that into your path, but I assume in the instructions below only that you’ve got kdiff3 in your
/Applications folder.

Mercurial Integration

Mercurial command line integration is pretty easy. Just open up your ~/.hgrc file (or create one if you don’t have it already), and add this to it:

[extdiff]
cmd.kdiff3 = /Applications/kdiff3.app/Contents/MacOS/kdiff3

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

That configures kdiff3 as your merge tool of choice, so it should pop up automatically when you hit a merge conflict. You can also use it as a diff tool:

hg kdiff3 -r revision_to_compare_to

Git Command-Line Integration

To configure the git command line to use kdiff3 as a diff and merge tool, add this to your ~/.gitconfig:

[difftool "kdiff3"]
    path = /Applications/kdiff3.app/Contents/MacOS/kdiff3
    trustExitCode = false
[difftool]
    prompt = false
[diff]
    tool = kdiff3
[mergetool "kdiff3"]
    path = /Applications/kdiff3.app/Contents/MacOS/kdiff3
    trustExitCode = false
[mergetool]
    keepBackup = false
[merge]
    tool = kdiff3

Now you can use the external tool commands to look at diffs:

git difftool [revision_sha]

and fix unresolved merge conflicts:

git mergetool

Git Tower Integration

I’m normally a pretty hard-core command line user, but I still sometimes find the places I get myself in git confusing enough that I’m willing to use a GUI to get myself out. I think that
git-tower is the best git GUI available right now.

It can show you diff files and lets you browse through history in it’s UI. It also lets you do a number of basic and mid-level commands (adding, committing, rebasing, squashing commits, cherry-picking, etc), but it doesn’t have a built-in diff or merge tool.

It does come with the ability to integrate with a few different merge tools out of the box, but not kdiff3.

After a little digging around, I found a generic post showing how configure Tower with a plist file and a shim shell script, but nothing specific to kdiff3.

I figured out how to get Tower and kdiff3 to play nice with each other, and have the instructions and files in a
GitHub repository. To get it working, just clone the repository to a temporary directory, and run the install.sh script:

cd /tmp
git clone git://github.com/tednaleid/git-tower-kdiff3-shim.git
cd git-tower-kdiff3-shim
./install.sh

It simply copies the plist file and the shim script into the appropriate directories (and Tower is
very picky about those locations).

Then you need to go into Tower’s Preferences->Git Config control panel, and choose kdiff3 as the diff and merge tool:
For a quick rundown of how Tower works with kdiff3 as a merge tool, here’s an example where
we’ve got one commit where we made changes to locally: And another commit on
origin/master where someone else made changes to the same piece of code:
We’ve pulled it down
and now have 2 heads within our repository. To fix this, we need to merge and resolve the conflicts, hit the merge button and we’ll get an error message because there are conflicts that git can’t resolve automatically:
If you highlight
a file with merge conflicts, and then hit the “Merge Tool” button, it will bring up kdiff3 and let us use it to resolve the issue:
Fix the merge conflicts
in kdiff3 (ex: press “C” to change it to “Goodbye Cruel World”), save it, and quit out of kdiff3. Tower should see that the file has had it’s conflicts resolved and lets you commit the merge and carry on.

You can also use Kdiff3 as a regular diff tool if you don’t like looking at diff files. Just choose a file that you’ve modified to diff:
Press the “Diff Tool” button,
and it’ll pop up in kdiff3: Kdiff3 might be homely, but it’s easy to use once you understand how it works.

Copied from: http://naleid.com/blog/2012/01/12/how-to-use-kdiff3-as-a-3-way-merge-tool-with-mercurial-git-and-tower-app/