Configuring the MergeToolChooser application

I previously wrote about the MergeToolChooser application that lets you select different merge tools for different file types. Setting Git up to use it is defined in that blog post (you point your .gitconfig’s [merge] properties to the tool, and go from there), but I wanted to run through how to configure the MergeToolChooser application itself. (Official documentation is here)

The MergeToolChooser.exe is found in
C:\Program Files (x86)\Hedgehog Development\Team Development for Sitecore (VS2017)
(or the folder of your latest Visual Studio version’s TDS Classic install)

And alongside it is a config file that configures the merge tool designation.
C:\Program Files (x86)\Hedgehog Development\Team Development for Sitecore (VS2017)\MergeToolChooserConfig.xml

By default, there are only two Merge Tools listed in there….the Sitecore Item Merge Tool, and KDiff3, but I have a couple more examples you could use in my Gist.

Now, when git calls the tool, it can pass a number of parameters to it by using what you define in the .gitconfig.

i.e

[mergetool "merge_chooser"]
	cmd = \"C:/Program Files (x86)/Hedgehog Development/Team Development for Sitecore (VS2017)/MergeToolChooser.exe\" \"$BASE\" \"$LOCAL\" \"$REMOTE\" \"$MERGED\" \"Local\" \"Remote\" \"Original then Result (when field is selected)\"

In the above example, I am passing 7 arguments.
$BASE, $LOCAL, $REMOTE, $MERGED, “Local”, “Remote”, “Original then Result (when field is selected)”

The first four are the file paths that Git will need to resolve the merge. The last three are the labels I just want my tools to know about, simply to aesthetically label the window panes so I know what I’m working with.

Now, for a merge in Git, $BASE is what the file looked like before we branched at all.
$LOCAL is what the file looks like in the current branch I’m on.
$REMOTE is what the file in the branch looks like. It’s what we’re merging into the branch I’m on.
And $MERGED is the resulting file that I want saved when I’ve finalized the merge.

Passing these four arguments, plus the three labels to the MergeToolChooser, they can then be represented in the same numerical order in which they arrive.

i.e in the example above, the MergeToolChooser knows $1 as $BASE, $2 as $LOCAL, $3 as $REMOTE and so on.

Now in the MergeToolChooserConfig.xml, I can pass these arguments on to each tool that I want to use for each file type.
The difficult thing here is that each application deals with the arguments in different ways. Some expect a certain order of arguments, some expect them to be passed as named parameters, some only deal with one or two arguments….

So in my example Gist of the MergeToolChooserConfig.xml, you can see that each of the tools has been configured with the parameter order as it expects. (If you find errors, or have other tools that we can configured, please let me know).

The TDS Sitecore Item Merge Tool (SitecoreItemMerge.exe) expects the arguments in the order of $BASE, $LOCAL, $REMOTE, $MERGED, Left Label, Right Label, Result Label. (as defined here).

Parameters=""$1" "$2" "$3" "$4" "$5" "$6" "$7""

The Visual Studio Diff Merge tool (vsDiffMerge.exe) expects the order differently. i.e $LOCAL, $REMOTE, $BASE, $MERGED. (as defined here)

Parameters=""$2" "$3" "$1" "$4" /t /m"

TortoiseMerge (TortoiseMerge.exe) expects $REMOTE, $LOCAL, and then named parameters for $MERGED and the labels.

Parameters=""$3" "$1" "$2" /merged "$4" /minename="$5" /theirsname="$6" /mergedname="$7""

So to configure any tool in the MergeToolChooserConfig.xml, you just need to know what parameters your tool accepts, and how you would pass them in the command line.
Then just define the file extension you want to use it for, the tool’s path, and those parameters, and the MergeToolChooser will work for you.

Note: The MergeToolChooser works from top to bottom…. so the first Extension match will be used for your file type.
Also, any MergeTool with no Extension defined (like the ‘Default Entry’ in the example) will be the catch all for any file types. Make sure you only have this as the last entry in the config.

If you have any other questions about configuring the MergeToolChooser application, or have any ones we could add to the example Gist, please let me know.