Command-Line Reference

Merge provides several command-line tools that enable you to launch Merge from a variety of applications. See Integrating with Source Control, Configuration Management, and Other Applications for application-specific instructions. The Automation API enables even greater control over Merge.

Compare and ConsoleCompare command-line utilities

The recommended way to use Merge from the command-line is to use one of the Compare.exe or ConsoleCompare.exe command-line utilities. These programs use the Merge Automation API to launch file and folder comparisons within a new or existing instance of Merge.

The difference between Compare and ConsoleCompare

Compare.exe is a graphical Windows application and is typically used to launch Merge from other graphical Windows applications. ConsoleCompare.exe is a console application and is generally used to launch Merge from console-based command-line tools.

Neither the Windows Terminal nor the Windows Command Prompt wait for graphical Windows applications such as Compare.exe to complete before returning control to the user. Consequently, even if you use the /wait command-line argument (see Usage, below) to Compare.exe in a Windows Terminal, control is 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 undesired, Merge is supplied with a console version of Compare.exe, called ConsoleCompare.exe. The Windows Terminal always waits for the ConsoleCompare.exe command to exit before returning control.

Usage

{Compare | ConsoleCompare} [/? | /h]
    [/wait | /noWait] [/aN] [/swap] [/max]
    [/titleN:"<NthFileOrFolderTitle>" …] [/2 | /3]
    {fileArguments | folderArguments}

fileArguments for a file comparison are:

    [/readOnly] [/closeIfNoChanges]
    [/merge [/testConflicts]] [/lineN:<lineNumber> …]
    <firstFile> [<secondFile>] [<thirdFile>] [<mergedOutputFile>]

folderArguments for a folder comparison are:

    <firstFolder> [<secondFolder>] [<thirdFolder>]

General arguments

  • /? or /h

    Display usage summary.

  • /wait (default for ConsoleCompare)

    Wait for user to close the comparison in Merge before exiting.

  • /noWait (default for Compare)

    Do not wait for the user to close the comparison in Merge before exiting.

  • /aN (N is 1, 2, or 3)

    The Nth file/folder argument specifies a common ancestor of the other two files or folders. The common ancestor is shown in the middle comparison panel. Only valid for three-way comparisons.

  • /swap

    Swap the files/folders displayed in the left and right panels.

  • /max

    Maximize the Merge application window.

  • /titleN:"<NthFileOrFolderTitle>" (N is 1, 2 or 3)

    Set an informative title for the comparison panel that displays the Nth file/folder specified on the command-line. This feature enables a version control system to provide meaningful titles for comparison panels. For example, "Djn's Revision v1.1.1", "Common Ancestor", and "Jrs's Revision v1.1.2" could be used as the three comparison panel titles.

    Single or double quotation marks should be used to surround the title; they are required if the title itself contains a space or a quotation mark. A single quotation mark may not occur within a title surrounded by single quotation marks; a double quotation mark may not occur within a title surrounded by double quotation marks.

  • /2 (default, unless four file or folder arguments are specified)

    Perform a two-way comparison, provided that three or fewer file/folder arguments are specified. If four file or folder arguments are specified, a three-way comparison is performed instead.

  • /3

    Perform a three-way comparison, provided that at least three file or folder arguments are specified. With Araxis Merge 2023 and later, a two-way comparison is performed instead if two or fewer file or folder arguments are present.

File comparison arguments

  • /readOnly

    Prevent the compared files from being edited.

  • /closeIfNoChanges

    Close the comparison if there are no changes between the compared files.

  • /merge

    Perform an automatic three-way merge to the common ancestor file. Only valid for three-way comparisons.

  • /testConflicts (requires /merge)

    Perform a merge and give the number of conflicts encountered (if any) as the utility’s exit status. For ConsoleCompare, the number of conflicts is also written to the console as a text message. Only valid for three-way comparisons.

  • /lineN:<lineNumber> (N is 1, 2, or 3)

    Navigate to the given line number within the file in the Nth panel of the comparison. If more than one /lineN argument is specified, the navigation is performed consecutively in ascending order of N.

For two-way comparisons (/2), the files <firstFile> and <secondFile> (if present) are compared. If just one file argument is specified, a comparison is opened with only a single comparison panel populated.

For three-way comparisons (/3), the files <firstFile>, <secondFile>, and <thirdFile> are compared. Note that three-way comparisons require the Professional Edition of Merge.

An optional extra file argument, <mergedOutputFile>, can be specified for both two and three-way file comparisons. If present, this additional argument sets the default save filename if you save changes to any of the files in the file comparison. For example, <mergedOutputFile> is written if you save a file using the ribbon Save button. See Saving Files for further information.

When merging three files, it is easiest to merge changes from the left and right files into the middle one. For this reason, the common ancestor or base file (if any) should be displayed in the middle panel. The common ancestor file can be specified with the /aN command-line option if it is not possible to order the file arguments appropriately so that <secondFile> is the common ancestor. For further information about three-way comparison and merging, please see Three-Way File Comparison and Merging and Automatic File Merging.

Folder comparison arguments

For two-way comparisons (/2), the folders <firstFolder> and <secondFolder> (if present) are compared. If just one folder argument is specified, a comparison is opened with only a single comparison panel populated.

For three-way comparisons (/3), the folders <firstFolder>, <secondFolder>, and <thirdFolder> are compared. Note that three-way comparisons require the Professional Edition of Merge.

When merging three folders, it is easiest to merge changes from the left and right folders into the middle one. For this reason, the common ancestor or base folder (if any) should be displayed in the middle panel. The common ancestor folder can be specified with the /aN command-line option if it is not possible to order the folder arguments appropriately so that <secondFolder> is the common ancestor. For further information about three-way folder comparison and merging, please see Three-Way Folder Comparisons and Automatic Folder Merging.

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 does 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 is used as the default save filename. Compare does 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 does 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 is used as the default save filename. Compare does 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

Using the main Merge executable, Merge.exe, to open file and folder comparisons is not recommended unless you specifically wish to start a new instance of Merge for each comparison. Use ConsoleCompare.exe or Compare.exe instead, as documented above.

Usage

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

The command-line arguments are described below.

  • /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, use them to populate the file/folder path fields but do not start the comparison.
  • <file1 [file2] [file3]> | <folder1 [folder2] [folder3]>
    Optional files or folders. If two or three file are provided, Merge starts with a file comparison of those files. If two or three folders are provided, Merge starts with a folder comparison for those folders.

Information When /Automation or /Embedding is used, Merge sets the working directory to the user’s Documents directory instead of inheriting the working directory from the process that launched it. If the Documents directory cannot be found, the user’s home directory is used instead.

Examples

1.

Merge test1.txt test2.txt test3.txt

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

2.

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

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