How to configure MKS to use KDiff3

Phil Gilmore

One of my clients is using MKS for source control and task management.  I have configured the source control system on my workstation to use KDiff3 for diff and merge operations.  I couldn't find any information on the command line to use and could find very little information on the parameters that are made available by MKS to pass to third party tools.

It took some effort to figure this out and I could find very little information on how to configure MKS to use third party tools so I decided to share this information here.  I think it might also be useful to show all this in case anyone wants to repeat the process to configure some other third party tool to integrate with MKS, such as WinDiff or WinMerge.

You can find information about configuring KDiff3 here.

http://kdiff3.sourceforge.net/doc/documentation.html#id2488514

Here is a snippet of the pertinent part:

To see all available command line options type

kdiff3 --help

Example output:

Options:
  -m, --merge               Merge the input.
  -b, --base file           Explicit base file. For compatibility with certain tools.
  -o, --output file         Output file. Implies -m. E.g.: -o newfile.txt
  --out file                Output file, again. (For compatibility with certain tools.)
  --auto                    No GUI if all conflicts are auto-solvable. (Needs -o file)
  --qall                    Don't solve conflicts automatically. (For compatibility...)
  --L1 alias1               Visible name replacement for input file 1 (base).
  --L2 alias2               Visible name replacement for input file 2.
  --L3 alias3               Visible name replacement for input file 3.
  -L, --fname alias         Alternative visible name replacement. Supply this once for every input.
  --cs string               Override a config setting. Use once for every setting. E.g.: --cs "AutoAdvance=1"
  --confighelp              Show list of config settings and current values.
  --config file             Use a different config file.

Given this, you need only know which MKS variables to substitute for each of the KDiff3 parameters from the table above when you construct your command line to the third party tool.  This is the tricky part. 

To specify the command line, open MKS and click File -> Edit preferences, then traverse the navigation tree to the /MKS Source/Diff and Merge Tools node.  On that page, you can specify the command line for your preferred diff tool and your preferred 3-way merge tool.  There are predefined configurations for several popular tools to choose from here (AraxisMerge and Beyond Compare, for example).

The only documentation I found about MKS command-line variables is in the context-sensitive help (click the Help button).  Here is what it says.

You can supply the following arguments for the command to control how the third party tool operates:
♦ {0} to display the title of the common ancestor object of the files being merged.

♦ {1} to display the title of the file being merged from.

♦ {2} to display the title of the file being merged to.

♦ {3} to display the title of the working file.

♦ {4} the path to the common ancestor object of the files being merged.

♦ {5} the path to the file being merged from.

♦ {6} the path to the file being merged to.

♦ {7} the path to the working file.

♦ {8} the path to the output file. You can use this argument to save the merge results in a file other than the working file.

Each argument must be quoted. For example, the command line for the ABC Merge tool could be:
abcmerge.exe "{4}" "{7}" "{5}"

This information raises several questions.  For example, what is the difference between parameters 6 and 8?  Aren't both of them a target file to contain the merge results?  Which one should one use?  The same question arises between 5 and 7. 

To determine which parameters I wanted to use, I had to determine what their values would be and how MKS would behave when writing the merge results to various targets.  To do this, I wrote a simple program to show me the values that are passed to its command line.  I can plug this program in where I would normally use a shelled program such as a diff or merge tool. 

Here is the (Delphi) source for it:

program CommandLineInfo;

{$APPTYPE CONSOLE}

uses
  SysUtils,
  Windows,
  Classes;

var
  j: integer;
  pc: integer;
  output: TStringList;
begin
  output := TStringList.Create;
  try

    pc := ParamCount;
    output.Add(paramstr(0));
    output.Add('');
    for j := 1 to pc do
      output.Add(IntToStr(j) + ': ' + ParamStr(j));

    MessageBox(0, pchar(output.Text), pchar('Command-line info'), MB_OK);

  finally
    output.Free;
  end;
end.

If you're one of the unfortunate souls who does not use Delphi, download the binary of the aforementioned CommandLineInfo application here.  You can run the application without any installer prerequisites. 

When plugged in with this command line:

C:\Archive\Apps\CommandLineInfo.exe "{0}" "{1}" "{2}" "{3}" "{4}" "{5}" "{6}" "{7}" "{8}"

I get these results:

I found that if you do not save the merge result to the working file, MKS assumes that you did not save your changes (it tells you that the working file was not modified).  Hence your merge results must be written to the working file.  You cannot see it in the screen shot above because I have blurred them out, but item 7 and item 8 (seen above as 8: and 9:) have identical values.  They are both pointing to the working file.  This way, the merge result is saved in the working file.  If the blurs above hinder your purposes, you can retrace the steps I've outlined in this article to see the results for yourself. 

Ultimately, these are the command line entries that I constructed. 

Diff:

C:\Program Files\KDiff3\kdiff3.exe "{3}" "{4}" --L1 "{1}" --L2 "{2}"

3-Way Merge:

C:\Program Files\KDiff3\kdiff3.exe "{4}" "{5}" "{7}" -o "{8}" --L1 "{0}" --L2 "{1}" --L3 "{3}"

Phil Gilmore (www.interactiveasp.net)