Using External Compare Tools

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

Apple FileMerge
Araxis Merge
BareBones BBEdit
BareBones TextWrangler
Black Pixel Kaleidoscope
Connected Flow’s Changes
Deltopia DeltaWalker
Macromates TextMate
Microsoft Word
Perforce P4Merge
SourceGear DiffMerge

Installing Support for Compare Tools

To install support for a compare tool:

Select Cornerstone > Compare Tools… and select the compare tool to install.
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.
A check mark appears over the compare tool’s icon indicating that installation was successful.

Selecting a Compare Tool

Open the app’s preferences by selecting Cornerstone > Preferences… (key equivalent ⌘,) and activating the General pane.
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:

Choose Cornerstone > Preferences… then click General.
Click the “External compare tool” pop-up menu and choose Open Scripts Folder.
Copy your script into the selected directory.

Selecting a Custom Compare Script

To select a custom compare script:

Choose Cornerstone > Preferences… then click General.
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:

Apple FileMerge
Araxis Merge
Deltopia DeltaWalker
Perforce P4Merge
SourceGear DiffMerge

To select a different merge tool:

Open the app’s preferences by selecting Cornerstone > Preferences… (key equivalent ⌘,) and activating the General pane.
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:

My Changes

This file contains the uncommitted changes made before the conflict occurred.
Latest in Repository (HEAD)

This file contains the latest version from the repository at the time the conflict occurred.
Last Update (BASE)

This file is the pristine version (i.e. BASE revision) at the time the last update was made before the conflict occurred.
Working Version

This is the file visible in the Cornerstone working copy browser. It is decorated with markers that indicate conflicting regions and can be edited by hand if necessary.

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:

Select a conflicted file in Cornerstone’s working copy browser.
Select the Resolve Conflicts Using Tool command from the Working Copy menu.
The external compare tool will be launched.
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).
Use the external merge tool to merge sections from the original and modified versions into the common ancestor.
When you are happy that the conflict has been resolved, save the results. They are automatically written to the file’s working version.
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.