Visual Studio and vsDiffMerge with Mercurial and TortoiseHg

Typically, when I have worked within Visual Studio on source-controlled projects I have used Team Foundation Server (TFS). With my current employer, we use Mercurial, and we use TortoiseHg to interface with it. For me this seemed to be a disconnected experience and I have been looking for ways to deeply integrate it. To that end, I have been using VisualHg as my source code control provider in Visual Studio, and recently found a way to use Visual Studio as my Diff and Merge tool from TortoiseHg. I have detailed the process of setting this up below, and authored an installer, which automates these steps. I will not cover the steps for setting up, nor using VisualHg as its own site does a good job of that already.

What you will need

• Visual Studio (I used Visual Studio 2013 Ultimate)
• Mercurial
• TortoiseHg
• A text editor (I used Sublime Text)

Verify a few things first

• You should have a file named vsDiffMerge.exe in the Visual Studio IDE directory, typically “C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\vsDiffMerge.exe”.
• You should have a file named Mercurial.ini in your user directory, typically “C:\Users\%USERNAME%” or “%USERPROFILE%”.
• TortoiseHg is NOT currently running. If you cannot shut down TortoiseHg, that is fine but will require a restart at the end.

If we have everything we need, and have verified the few things mentioned above, we are ready to proceed. We will do most of the work in Mercurial.ini, and a new batch file that we will create. The batch file will handle calling the Visual Studio components and give us a simple path to configure in Mercurial.ini. Therefore, we will start there.

Wire it up

Open the text editor and create a new file. Copy the batch script code below into the new file and then save the new file as HgVsDiffMerge.bat in your user directory (%USERPROFILE%).

@ECHO OFF
IF "%1" == "/Diff" GOTO DIFF
IF "%1" == "/Merge" GOTO MERGE
EXIT

:DIFF
%COMSPEC% /C ""%VS120COMNTOOLS%VsDevCmd.bat" && devenv.exe /diff %2 %3"
EXIT

:MERGE
%COMSPEC% /C ""%VS120COMNTOOLS%VsDevCmd.bat" && VsDiffMerge.exe /t /m %2 %3 %4 %5
EXIT

If you are using Visual Studio 2012, then change the variable “VS120COMNTOOLS” to “VS110COMNTOOLS”, or if you are using Visual Studio 2010 then change the variable “VS120COMNTOOLS” to “VS100COMNTOOLS”.

Now, make a backup copy of your Mercurial.ini file. If you just read that and ignored it, please stop and go make that backup copy of Mercurial.ini now.

Now open Mercurial.ini in your text editor. We will focus on a couple of sections in here. The first section (which may not exist) is the “merge-tools” section. If you do not have a “merge-tools” section, you will create one. Here we tell Mercurial, and TortoiseHg, about the batch script we created earlier. The section should look like the snippet below.

[merge-tools]
vsDiffMerge.executable=%UserProfile%\HgVsDiffMerge.bat
vsDiffMerge.args=/Merge $local $other $base $output
vsDiffMerge.priority=1
vsDiffMerge.premerge=True
vsDiffMerge.gui=True
vsDiffMerge.diffargs=/Diff $parent $child
vsDiffMerge.dirdiff=True

Now Mercurial and TortoiseHg know that there is a merge tool called vsDiffMerge. They know where to find it, and how to invoke it for a merge or diff. Now we will tell them to do so. In the “ui” section, set the value of “merge” to “vsDiffMerge”. In the “tortoisehg” section, set the value of “vdiff” to “vsDiffMerge”.

Save the Mercurial.ini file.

If TortoiseHg has been running this whole time, shut it down. Now launch TortoiseHg and select a change-set, right click any non-binary file in the change-set and select “Diff to parent”. If all went well, you should be looking at Visual Studio comparing your two file versions. You will also notice that now you have some of the benefits like hovering to see variable types and other useful diff and merge tools. This will be similar for merges, but will have an additional pane below those two, showing the result of the merge that would be committed.

In a Diff, the file on the left will be the parent and the file on the right will be the local copy. In a merge, the order is; local on the left, remote on the right, merged on the bottom.

Here’s a screen shot of a simple Diff.

vsDiffMerge – Diff to parent.

You can also download the installer I authored which automates these tasks. It is available here as HgVsDiffMergeSetup.zip (zipped MSI).