How to Use P4merge as a 4-pane, 3-way Merge Tool With Git and

| Comments

Last year, I blogged about how I was using kdiff3 as my merge tool with git, mercurial and Git Tower.

Since then, I’ve had a number of troubles with kdiff3 around it’s usability and font handling that make it difficult to use (the text you click on isn’t the text your editing, very painful).

That made me look around for alternatives and I found that the freely available p4merge tool from Perforce is probably the best option. It has a more native mac feel and properly handles fonts.

Why 4-pane merge tools are important

I still think that 4-pane, 3-way merge tools are valuable because they give you information that other 2 and 3-pane tools are missing.

2-pane merge tools (DiffMerge)

Most tools (like OSX’s built in FileMerge and Kaliedoscope) are 2-pane merge tools that give you:

  • LOCAL – your file with the changes you’ve made to it
  • REMOTE – the file you’re merging in, possibly authored by someone else

two pane merge with diffmerge

4-pane merge tools (p4merge)

4-pane merge tools show you these panes:

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

The BASE is important as it gives you the context you need to understand how each branch got to it’s current location.

The MERGE_RESULT is an explicit view of what the final, merged and resolved file will look like. Without this, you need to keep a bunch of state in your brain about what that file will look like depending on which version you “keep”. Here it’s right before your eyes and is much easier to reason about.

four pane merge p4merge

You can see how easy it is in the gif above to pick and see the final MERGE_RESULT in the bottom pane. It might look like a lot of information, but it’s all important for resolving the merge correctly.

Installing p4merge

First, you’ll need to download p4merge from Perforce (it’s free, but also installs the Perforce client that we won’t be using). It should install into your /Applications directory.

Setting up p4merge with git

In your ~/.gitconfig file, create a stanza like this:

[mergetool "p4merge"]
  cmd = /Applications/ "$BASE" "$LOCAL" "$REMOTE" "$MERGED"
  keepTemporaries = false
  trustExitCode = false
  keepBackup = false

and modify the merge stanza (if you have one) or create one that tells git to use p4merge as the preferred merge tool:

  tool = p4merge 

With that set up, you should be able to run it with the git mergetool command whenever you hit an issue:

% git mergetool

Normal merge conflict for 'underscore.js':
  {local}: modified file
  {remote}: modified file
Hit return to start merge resolution tool (p4merge):

Getting p4merge working with Git Tower

To configure Git Tower to use p4merge as it’s merge tool, just go into preferences and pick it:

gittower config p4merge

To launch it during a merge/rebase conflict, just highlight the file with the conflict and press the “Merge Tool” button inbetween the file list and the file diff panes:

launch p4merge from gittower

That will launch p4merge, allow you to resolve all conflicts and save the file and then return back to Tower to “commit” the merge/rebase.