Using External Compare Tools

Cornerstone provides support for the use of the following external tools for the comparison of files:

Installing Support for Compare Tools

To install support for a compare tool:

  1. Select Cornerstone > Compare Tools… and select the compare tool to install.
  2. Install support by dragging the compare tool’s icon to Cornerstone’s scripts folder. You can open the scripts folder by clicking the Open Scripts Folder button.
  3. A check mark appears over the compare tool’s icon indicating that installation was successful.

Selecting a Compare Tool

  1. Open the app’s preferences by selecting Cornerstone > Preferences… (key equivalent ⌘,) and activating the General pane.
  2. Select the tool to use from the External compare tool popup menu.

Custom Compare Scripts

If you wish to use a compare tool that is not directly supported by Cornerstone, then you can also select a custom Unix shell script or AppleScript file. Custom scripts are required to take two arguments which describe the paths to the files being compared.

Custom scripts are executed as:

/path/to/script original modified

Unix Shell Scripts

The following example Bash shell script uses the opendiff tool provided with macOS to compare the files specified as the script’s two arguments:

#!/bin/bash

original_path="$1"
modified_path="$3"

/usr/bin/opendiff "$original_path" "$modified_path"

AppleScript

AppleScript files must implement the run handler, which takes a single argv argument which is a list that contains two POSIX paths: the path to the original and modified files. The following AppleScript is functionally equivalent to the above Unix shell script, which uses the opendiff tool to compare the specified files:

on run argv
  set original_path to (item 1 of argv)
  set modified_path to (item 3 of argv)
  do shell script "/usr/bin/opendiff \"" & original_path & "\" \"" & modified_path & "\""
end run

Installing Custom Compare Scripts

To install a custom script:

  1. Choose Cornerstone > Preferences… then click General.

  2. Click the “External compare tool” pop-up menu and choose Open Scripts Folder.

  3. Copy your script into the selected directory.

Selecting a Custom Compare Script

To select a custom compare script:

  1. Choose Cornerstone > Preferences… then click General.

  2. Click the “External compare tool” pop-up menu and select your script.

Comparing WORKING Against BASE

When comparing BASE against the working version, BASE is treated as the original (or old) version and the working version as the modified (or new) version (the two file paths are specified in this order to custom scripts as well).

As a result, most comparison tools will display the BASE version on the left and the working version on the right (BBEdit and TextWrangler behave somewhat differently, displaying the newer file on the left).

The BASE file is locked before launching the external compare tool and should not be modified.

Compare WORKING Against HEAD

When comparing the working version against HEAD, the working version is treated as the original (or old) version and HEAD as the modified (or new) version in a manner consistent with Cornerstone’s integrated comparison view.

Once again, this is also the order in which the files are specified to custom scripts. As with BASE files, the HEAD file is locked and should not be modified.

Resolving Conflicts with External Merge Tools

Cornerstone also provides support for using the following external merge tools to resolve conflicts:

To select a different merge tool:

  1. Open the app’s preferences by selecting Cornerstone > Preferences… (key equivalent ⌘,) and activating the General pane.
  2. Select the tool to use from the External merge tool popup menu. If the tool is not listed select Add Compare Tools… and follow the same steps for installing support for compare tools, as described above.

Four files are involved when resolving conflicts:

When resolving conflicts using an external tool, My Changes is treated as the original file (normally displayed on the left) and Latest in Repository is treated as the modified file (displayed on the right). The Last Update file is treated as the common ancestor (displayed between or underneath the other files) and the results of the merge are saved to the Working Version.

To resolve conflicts using an external merge tool:

  1. Select a conflicted file in Cornerstone’s working copy browser.
  2. Select the Resolve Conflicts Using Tool command from the Working Copy menu.
  3. The external compare tool will be launched.
  4. Differences between the original and modified files are automatically merged into the common ancestor (with the exception of DeltaWalker that does not support this feature).
  5. Use the external merge tool to merge sections from the original and modified versions into the common ancestor.
  6. When you are happy that the conflict has been resolved, save the results. They are automatically written to the file’s working version.
  7. In Cornerstone, mark the file’s conflicts as resolved by selecting the Resolve Conflicts command from the Working Copy menu.

Once resolved, the file is marked as modified and the changes can be committed like any other modification.