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 AppleScript API enables even greater control over Merge.

Compare command-line utility

The recommended way to use Merge from the command-line is to use the compare command-line utility. This program uses the Merge AppleScript API to launch file and folder comparisons within a new or existing instance of Merge.

Before using compare, ensure that the command-line utilities have been installed as described in the Installing the Merge command-line utilities section of the How to Install topic.

Usage

compare [-h] [-wait | -nowait]
    [-aN] [-swap] [-max]
    [-titleN:"<NthFileOrFolderTitle>" …] [-2 | -3]
    {fileArguments | folderArguments}

fileArguments for a file comparison are:

    [-readonly | -readonlyN …] [-merge [-testconflicts]]
    <firstFile> [<secondFile>] [<thirdFile>] [<mergedOutputFile>]

folderArguments for a folder comparison are:

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

General arguments

• -h

  Display usage summary.

• -wait

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

• -nowait (default)

  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 instead performed.

• -3

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

File comparison arguments

• -readonly

  Prevent the compared files from being edited. Available in Araxis Merge 2023 and later.

• -readonlyN (N is 1, 2 or 3)

  Prevent the file in the Nth panel of the comparison from being edited. Available in Araxis Merge 2023 and later.

• -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. Only valid for three-way comparisons.

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 toolbar 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 Comparisons 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 file1.txt file2.txt

Opens a file comparison window comparing the two specified files.

2.

compare -wait file1.txt 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 file1.txt file2.txt /tmp/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, /tmp/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 /tmp/file1.txt /tmp/file2.txt /tmp/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" /tmp/file1.txt /tmp/file2.txt /tmp/file3.txt /tmp/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, /tmp/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.