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.

By default, grails uses ~/.grails as the working directory. If you’re doing branchy development, you can run into problems with this if you’ve got plugins installed in one branch that aren’t in the other. Having a unique directory per branch prevents you from having to run grails clean all the time.

Here’s a quick shell script that changes the grails working directory to have the branch name as a suffix if your source is contained in a mercurial repository (ex: the default branch would be ~/.grails_default and the 1.0 branch would be ~/.grails_1.0). If your application is not in a repo, it just uses the regular ~/.grails directory.

#!/bin/sh
HG_BRANCH=`hg branch 2>/dev/null`
GRAILS_SCRIPT=$GRAILS_HOME/bin/grails
 
if [ $HG_BRANCH ]; then
	GRAILS_WORK_DIR=`echo ~`/.grails_$HG_BRANCH
	echo "** grails working directory: $GRAILS_WORK_DIR"
	$GRAILS_SCRIPT -Dgrails.work.dir=$GRAILS_WORK_DIR $@
else
	echo "** default grails working directory"
	$GRAILS_SCRIPT $@
fi

Just save this script as “grails” and put it in your PATH before the $GRAILS_HOME/bin directory (also make sure that you’ve defined $GRAILS_HOME). I have a ~/bin directory that’s the first thing in my PATH.

If you use the grails-debug command, you can repeat these steps for that, just change GRAILS_SCRIPT to $GRAILS_HOME/bin/grails-debug.

This same technique could easily be modified to be used for other source control systems such as git or subversion.

The turnout at the meeting was great, and a heated discussion followed the presentation (as it always does at that meeting).

I’ve checked the original keynote files along with a PDF version into a mercurial repository.

Here’s the presentation on SlideShare:

My home directory has a bin folder in it that’s continually getting new jigs added to it, and my zshrc file is an ever-expanding list of quick shell functions.

Recently, I’ve been doing a lot more work with Mercurial as the team that I’m on switched from Subversion a couple of months ago on our Grails project. The initial transition was a little difficult for some people, but I think just about everyone is pretty happy with the transition now that we’ve made it.

Something that has helped everyone get comfortable with more complex Distributed Version Control System like Mercurial has been the distribution of shims and jigs amongst the team. I thought these tips might be useful to others as well.

Configuring Mercurial

After installing mercurial (the easiest way is to just get the appropriate binary package for your OS), you’ll want to get it configured.

A good place to start is with someone else’s configuration file. Here’s my my current ~/.hgrc configuration file (with the username replaced):

[extensions] 
fetch=
extdiff=
color=
hgext.graphlog=
hgshelve=~/Documents/workspace/hgshelve/hgshelve.py
rdiff=~/Documents/workspace/rdiff/rdiff.py
hgext.mq =
 
[diff]
git = 1
 
[ui]
username = YOUR NAME <YOUR_NAME@YOUR_COMPANY.com>
 
[extdiff]
cmd.kdiff3 =
cmd.chdiff =
opts.chdiff = --wait
 
[merge-tools]
kdiff3.args = $base $local $other -o $output

In it, you’ll see a number of useful extensions, including:

• hg fetch – automates the pull/update working copy/merge/commit merge steps
• extdiff extension – Mercurial allows you to set up external tools to do diffs and merges. I’m using 2 different graphical merge tools for different purposes
• hg chdiff – Changes.app for just comparing two files in a diff. Changes is a beautiful shareware diff tool for the mac, it unfortunately doesn’t do a 3-way merge.
• hg kdiff3 – For merging, (and some diff situations), I need the power of a 3-way merge tool and I’ve found kdiff3 to be the best one that I’ve used. It’s an open source, free, cross platform 3-way merge tool. Using a 3-way merge tool is imperative for getting your merges correct.
• color extension – just colorizes some output including the status command
• hg glog – an ascii graphical log of the commit tree (enhanced “hg log”)
• hg shelve – simplified patch management that allows you to “shelve” changes without committing them locally, for instance if you want to do a fetch, I asked about this on Stack Overflow
• hg rdiff – remote diff, allows you to compare a file checked into your local repo with a file in the remote repository, I also asked about this on Stack Overflow
• mq extension – mercurial queues, a more advanced topic that I don’t think anyone else at my workplace uses, but there’s a lot of power in mqueue if you look into it. The Mozilla guys have a really nice introductory tutorial to using this plugin.

Setting up KDiff3 so you can do 3-way merges

The simplest way to get KDiff3 is to download the binary from the main website (click on the download link and then choose the binary appropriate for your platform).

For the mac, you’ll just get a zip file with a KDiff3.app file in it that you should drag to your /Applications directory. Then, you need to make sure that the actual executable in the application is in your path. I just create a symlink in my path to the executable inside the application package:

ln -s /Applications/kdiff3.app/Contents/MacOS/kdiff3 /usr/local/bin/kdiff3

You might not have /usr/local/bin in your path by default. If you can execute kdiff3 --help on the command line, you’re ready to go.

Setting up the “shelve” extension

The easiest way to get the shelve extention set up is to simply clone the project that holds the python script to your local filesystem:

hg clone http://freehg.org/u/tksoh/hgshelve/ hgshelve

Then just make sure that the path in your ~/.hgrc file points to the correct location of the hgshelve.py file in the cloned repository.

You can test that it’s working by just executing:

hg help shelve

If you don’t get an error message, it’s set up right and you can start using it.

Setting up the “rdiff” extension

Setting up the rdiff extension is similar to the shelve extension above. Just clone the repository:

hg clone -r c3ac1c497bf0 http://hg.kublai.com/mercurial/extensions/rdiff

We clone an older revision currently as the tip in that project uses some unsupported stuff that isn’t in mercurial 1.0.2, if you’ve got a newer version of mercurial, you might be able to get the tip of the rdiff extension and have it work.

Then make sure that your ~/.hgrc is pointed to the right path for the rdiff.py file in the repo you just cloned.

It’s a little quirky in that it actually modifies the existing “hg diff” command by detecting if the first parameter is a remote URL. If it is then it will diff that file against your tip file in your local repo (not the working copy). This as the remote repo is first in the arguments, it’s the reverse of what I’d expect, but you can pass “–reverse” to the hg diff command to switch that around.

I could see these being potential enhancements to the extension, but for now, I can work around them with a bash/zsh shell function in my startup file. It does a temp checkin of my working copy (held by the mercurial transaction so it can be rolled back), executes the reverse diff, and then rolls the transaction back to return things back to the way they were:

hgrdiff() {
    hg commit -m "temp commit for remote diff" && 
    hg diff --reverse http://my_hardcoded_repo $* &&
    hg rollback      # revert the temporary commit
}

And then call it with:

hgrdiff <filename to diff against remote repo tip>

Other Mercurial Jigs and Shims

Here are some other jigs and shims that I’ve found useful.

Jig to Get a List of Files With the Same Status

One jig that I’ve gotten a ton of use out of, is a modification to the normal “hg status” command. Normally, “hg status” returns a list of all files that are different in the working directory when compared to the tip if the repository. In the output of status, each file is printed with a character in the first column that signifies the status of that file. Ex:

% hg status
M build.xml
A src/groovy/Foobar.groovy
A src/groovy/Quux.groovy
? src/groovy/Bar.groovy
? src/groovy/Baz.groovy

Some of the most common statuses are:

• ? – not tracked, unknown to the source control repository
• M – modified, this file is different in the working copy than on the file system
• A – added, source control is aware of this file, but it hasn’t yet been committed
• R – removed, this file has been marked for deletion on the next commit
• ! – missing, this file is not present in the working copy but is in source control

Often, I’ll want to do something with all of the files in a particular status, but I can’t easily do that as they’re mixed in with the other file types. Also, the status flag at the beginning of the line prevents me from piping the status into another command.

I’ve come up with this shell function to allow me to filter lists of files (it actually works for subversion too, so there are 2 aliases). Just paste this into your bash/zsh startup file:

vcst() {
	# print out all of the files with a passed in status flag (M - modified, A - added, ? - unknown, etc) (default ?)
	# expects first parameter to be the version control command (likely svn or hg)
	STATUS='\?'
	if [ -n "$2" ]
	then
		STATUS=$2
	fi
	$1 status | egrep "^$STATUS" | awk '{print $2}'
}

alias svnst='vcst svn'
alias hgst='vcst hg'

Then you can use the “hgst” command to see all the files in a particular status, one per line. By default, it shows files that aren’t tracked (“?“), but you can pass a parameter that specifies another flag type if it’s other than “?“.

To see the list of files that aren’t in source control, just use:

% hgst
src/groovy/Bar.groovy
src/groovy/Baz.groovy

If you want to delete all of the files that aren’t in source control, all you have to do is send the results of that command to rm:

rm `hgst`
# removes src/groovy/Bar.groovy and src/groovy/Baz.groovy

If you want to edit all of the files that have been added in TextMate:

mate `hgst A`
# opens src/groovy/Foobar.groovy and src/groovy/Quux.groovy in TextMate

If you want to do a diff and see only the files that have been modified using kdiff3:

hg kdiff3 `hgst M`
# would show a diff of build.xml vs the working copy

Shim to See a List Incoming and Outgoing Files

When I’m about to push changes out to a remote server, or pull changes down from that server, I often want to know what files will be affected by this action. Surprisingly, there isn’t an easy built-in way to do this.

There is the hg incoming -v command, which will print out a log format of all of the different changesets. But I don’t really care about all the changesets, I just want to know which files will be affected. Here’s a sample run of incoming with 3 changesets:

% hg incoming -v
comparing with /Users/ted.naleid/temp/foo
searching for changes
changeset:   1:5c5f71bda234
user:        Ted Naleid <ted.naleid@carol.com>
date:        Tue Nov 25 20:30:51 2008 -0600
files:       src/groovy/Foobar.groovy
description:
initial commit of foobar.groovy
 
 
changeset:   2:fe4a615747af
user:        Ted Naleid <ted.naleid@carol.com>
date:        Tue Nov 25 20:31:36 2008 -0600
files:       src/groovy/Bar.groovy src/groovy/Foobar.groovy
description:
committing 2 files
 
 
changeset:   3:21e3d26bc3eb
tag:         tip
user:        Ted Naleid <ted.naleid@carol.com>
date:        Tue Nov 25 20:31:54 2008 -0600
files:       build.xml src/groovy/Baz.groovy src/groovy/Foobar.groovy src/groovy/Quux.groovy
description:
3rd commit of files

That’s not very useful as it’s hard to parse out the actual files in that list (and see only the unique list).

I use the following shim (just put in your bash/zsh rc file) to make this simple:

# look for lists of files in piped output, sort the unique set of them and print them one per line
lf() {
    egrep "^files:" | awk '{for (i=2; i<=NF; i++) print $i}' | sort | uniq 
}
 
alias ic="hg incoming -v | lf"
alias og="hg outgoing -v | lf"

Once this is installed, you can simply use the og (outgoing) or ic (incoming) aliases to see what you’ll affect if you actually do a push or a pull.

Here’s the output using the incoming shim on same changeset above:

% ic
build.xml
src/groovy/Bar.groovy
src/groovy/Baz.groovy
src/groovy/Foobar.groovy
src/groovy/Quux.groovy

That makes it quick and easy to see the real things that you’ll affect by your actions.

Enhancing Your Shell Prompt With Mercurial Info

A couple of other commands that I have in my zshrc (they should also work in a bash startup file):

hgtarget() {
    hg_root=`hg root 2>&1 | egrep -v "$abort:"`
   	if [ $hg_root ]; then
    	if [ -f $hg_root/.hg/hgrc ]; then
        	hg_target=`cat $hg_root/.hg/hgrc | egrep "^default =" | sed 's/\(^default = \(http:\/\/\)*\)\(.*@\)*//'`
        	echo "$hg_target"
        fi
    fi
}

hgbranch() {
	hg_root=`hg root 2>&1 | egrep -v "$abort:"`
	if [ $hg_root ]; then
		hg_branch=`hg branch`
		echo "$hg_branch"
	fi
}

These commands will tell you the path to the default push/pull target for your repository (hgtarget) as well as the current branch that you’re working on (hgbranch) in your repo.

I’ve added these to my shell prompt so that when I’m in a mercurial repository I’m more informed of the context that I’m working in. My prompt is a little complicated (lots more going on there besides this), but there are a number of good tutorials out there for modifying yours.

The presentation starts with the pros and cons of distributed systems and gives a brief overview of the top 3 most popular DVCS systems:

• Git
• Bazaar
• Mercurial

I go into the details of why I chose to use Mercurial and describe some common usage patterns for people used to using Subversion.

I then did a live-coding session where I created a quick grails application, added it to a new repository, cloned the repository and pushed changes back and forth to show how mercurial handles merging and history.

I also suggest how developers can use mercurial as a “super client” to enable much of this power while still working on a team that uses subversion.

Overall the presentation was well received, and many of the developers seemed excited about the potential in a DVCS like mercurial. I know a number of them downloaded mercurial this afternoon and gave it a shot. I also spoke with our build guy and one of our architects who both seem interested in switching over.

If you’re interested in installing mercurial, you can easily download binaries, or else you can go to the main mercurial website and compile it from source.

Here’s the presentation (without notes):

| View | Upload your own

I’ve also uploaded a version of the presentation with full notes on slideshare. Adding the notes makes it too small to read in their flash app, so I suggest downloading the presentation if you want to see them. The notes also include all of the detail in the live coding session (though you have to have grails 1.0.2 or better installed to get the same stuff I did).

I’d be interested to hear from others who have convinced their teams to switch from using a centralized repository to a distributed one like Mercurial.