Command-Line Reference

Merge provides several command-line tools that enable you to launch Merge from a variety of applications. The Automation API enables even greater control over Merge.

Compare command-line utility

The primary (and recommended) way to use Merge from the command-line is to use the Compare command-line utility (Compare.exe). This utility program uses the Merge Automation API to launch file comparisons within a new or existing instance of Merge.

ConsoleCompare command-line utility

Compare.exe is a Windows subsystem (that is, graphical) application, because it is typically used to launch Merge from other Windows subsystem applications. The Windows Command Prompt doesn’t wait for Windows subsystem applications such as this to complete before returning. Consequently, even if you use the /wait command-line argument (see Usage, below) to Compare.exe in a Windows Command Prompt, control will be returned to the prompt as soon as the command is launched, even though Compare.exe is still running and waiting for Merge to be closed. As this behaviour is sometimes unhelpful, Merge is supplied with a console subsystem version of Compare.exe, called ConsoleCompare.exe. The Windows Command Prompt will always wait for this command to exit before returning control.

Usage

{compare | consolecompare} [/? | /h] [/[no]wait] [/merge] [/testconflicts] [/readonly] 
    [/closeIfNoChanges] [/aN] [/swap] [/max] [[/titleN:"<NthFileTitle>"]…] [/2 | /3]
    <firstFile> <secondFile> [<thirdFile>] [<mergedOutputFile>]

For two-way comparisons, two filename arguments should be specified. These are the files that will be displayed within the file comparison window. An optional third filename argument can also be specified. This third argument is used as the default save filename if you save changes to either of the files in the file comparison window (for example, by choosing Save or Save As… from the context menu that appears when a file panel is right-clicked).

For three-way comparisons, three filename arguments should be specified. It is important that the common ancestor or base file (if any) is displayed in the middle file panel. This can be specified with the /aN command-line option. As with two-way comparisons, a further optional argument can be specified to set the default filename name used if a file is saved.

When merging three files, it is easiest to merge changes from the left and right files into the middle file. This is why the common ancestor file should be displayed in the middle file panel. Once the changes have been merged into the common ancestor file, right click the middle file panel and choose Save or Save As… to save the merged file.

The command-line arguments are described below.

  • /? or /h Displays usage summary.
  • /wait Wait for user to close the compared files in Merge before exiting.
  • /nowait Prevents compare from waiting for a comparison to be closed.
  • /merge Performs an automatic three-way merge to the common ancestor file after comparing three files.
  • /testconflicts When combined with /merge, checks whether an automatic three-way merge would cause merging conflicts. The program’s return code is the number of conflicts encountered.
  • /readonly Prevents the compared files from being edited.
  • /closeIfNoChanges Closes the launched comparison if there are no changes between the compared files.
  • /aN (N is 1, 2 or 3) The Nth filename argument specifies a common ancestor of the other two files. The common ancestor is shown in the middle file panel. Only valid for three-way comparisons.
  • /swap Swaps the files displayed in the left and right panels.
  • /max Maximizes the Merge application window.
  • /titleN:"<NthFileTitle>" (N is 1, 2 or 3) Sets a friendly title for the file panel that displays the Nth file specified on the command-line. Single or double quotes must be used to surround the title. This feature enables a VC or SCM system to provide meaningful names for file panel titles. For example, "Djn's Revision v1.1.1", "Common Ancestor" and "Jrs's Revision v1.1.2" could be used as the three file panel titles.
  • /2 Performs a two-way comparison (default). The files <firstFile> and <secondFile> are compared. If present, <mergedOutputFile> is used as the default save filename for the results of any merge.
  • /3 Performs a three-way comparison (only available in the Professional Edition of Merge). The files <firstFile>, <secondFile> and <thirdFile> are compared. If present, <mergedOutputFile> is used as the default save filename for the results of any merge.

Examples

1.

compare c:\temp\file1.txt c:\temp\file2.txt

Opens a file comparison window comparing the two specified files.

2.

compare /wait c:\temp\file1.txt c:\temp\file2.txt

Opens a file comparison window comparing the two specified files. Compare will not exit until the user closes the file comparison window.

3.

compare /wait c:\temp\file1.txt c:\temp\file2.txt c:\temp\merged.txt

Opens a file comparison window comparing the first two specified files. If the user attempts to save changes to either of the two files, c:\temp\merged.txt will be used as the default save file name. Compare will not exit until the user closes the file comparison window.

4.

compare /wait /a1 /3 c:\temp\file1.txt c:\temp\file2.txt c:\temp\file3.txt

Opens a file comparison window comparing the three specified files. Compare will not exit until the user closes the file comparison window. The first file specified is treated as the common ancestor of the other two and is therefore displayed in the middle file panel.

5.

compare /wait /a3 /3 /title1:"Djn's Revision" /title2:"Jrs's Revision" /title3:"Common Ancestor" c:\temp\file1.txt c:\temp\file2.txt c:\temp\file3.txt c:\temp\merged.txt

Opens a file comparison window comparing the first three specified files. If the user attempts to save changes to either of the three files, c:\temp\merged.txt will be used as the default save file name. Compare will not exit until the user closes the file comparison window. The third file specified is treated as the common ancestor of the other two and is therefore displayed in the middle file panel. The file panels are given meaningful names.

Merge command-line

The main Merge executable itself (merge.exe) also provides several command-line options. Using merge.exe to start file and folder comparisons is not recommended, unless you really do want a new instance of Merge for each comparison.

The merge.exe executable enables you to specify the names of files or folders on the command-line. If you provide two or three file paths, Merge will start with a file comparison for those files. If you provide two or three folder paths then Merge will start with a folder comparison for those folders.

Usage

Merge [</RegServer>] [</UnregServer>] [</Automation>]
    [</Embedding>] [</Options>] [</SetEditFieldsOnly>]
    [<file1 [file2] [file3]> | <folder1 [folder2]>]

The command-line arguments are described below.

  • /RegServer Forces Merge to re-register all its automation capabilities.
  • /UnregServer Forces Merge to unregister all its automation capabilities.
  • /Automation Used when Merge is started as an automation server. Not generally useful.
  • /Embedding Used when Merge is started as an automation server. Not generally useful.
  • /Options Displays the Merge Options dialog.
  • /SetEditFieldsOnly When file and folder arguments are specified on the command-line, they are used to populate the filename/foldername fields, but a comparison is not automatically started.
  • <file> | <folder> An optional file or folder name. The file comparison window is opened for files and the folder comparison window is opened for folders.

Examples

merge test1.txt test2.txt test3.txt

Starts Merge and opens a file comparison comparing the three specified files.

merge c:\temp\first-folder c:\temp\second-folder

Starts Merge and opens a folder comparison window comparing the two specified folders.