PatchViewer Help

Configuring a graphical file comparison tool

Tool selection

By default, PatchViewer uses Xcode's FileMerge application to display file differences. You can use a graphical file comparison tool of your choice by configuring it in the General panel of the PatchViewer Preferences.

Use the popup menu to select the binary of your file comparison tool.

Important notes regarding application sandboxing

You can ignore this section if you purchased PatchViewer outside of the Mac App Store. If you purchased PatchViewer from the Mac App Store, then there are sandboxing limitations you need to be aware of.

Applications purchased from the Mac App Store are run by OS X inside a 'sandbox' which restricts the operations an application can perform to order to improve security. These restrictions include limiting the processes (such as file comparison tools) that an application may launch.

PatchViewer may launch two kinds of third-party tools/scripts subject to either of these sandboxing constraints:

  • Any tool/script within /Applications/ or its subfolders may be launched. (Any child processes spawned by these tools are are also subject to the same constraint, so there is no convenient back door access to /usr/bin/ for example!)
     
  • Executable scripts/tools that you put it in ~/Library/Application Scripts/au.com.appledeveloper.PatchViewer.appstore/ may be launched. (These scripts may spawn any other tools, including tools in /usr/bin/.)

The second option is the more powerful and typically you would use it to create a wrapper script to launch another tool that would otherwise be inaccessible from the sandbox. Here is an example to launch Kaleidoscope's diff tool:

#!/bin/sh
# Launch Kaleidoscope
/usr/bin/ksdiff "$1" "$2"
 
Unfortunately PatchViewer itself can't automatically create this script for you (again due to sandboxing limitations).

 

Command-line arguments

When PatchViewer launches the tool, it passes the arguments specified in the Arguments text field to the tool:

%1 is replaced with the path to the original file being compared.
%2 is replaced with the path to the modified file being compared.

For most file comparison tools other than FileMerge, the Standard Arguments selection will be appropriate. If you want to pass different arguments to your tool, select Custom from the Arguments popup menu and the edit the Arguments text field as necessary.

Araxis Merge

PatchViewer can be configured to use Araxis Merge by specifying the path to the compare tool, which is typically found at:

/Applications/Araxis Merge.app/Contents/Utilities/compare

and by specifying the following Custom arguments:

-wait -2 %1 %2

 

Successful status values

Most command-line tools return zero upon successful execution. If you are using a tool such as Kdiff3, which does not*, then you may need to specify a list of custom exit values to prevent PatchViewer from displaying an error message when it gets a non-zero exit status returned by the tool.

* Kdiff3 returns zero when you save a merge, but it returns 1 when you do not (which will be the typical usage when you are using it with PatchViewer).

FileMerge versus opendiff

FileMerge and opendiff are almost equivalent. When you run opendiff from the command-line it ends up launching FileMerge.

The man page for opendiff states that successive calls to it will open new windows in the same instance of the FileMerge app if it is already running. However, there is a bug (Radar 12843337) in Xcode 4.5.2/Mountain Lion 10.8.2 which prevents opendiff from fulfilling this goal when it is run in a sandboxed environment.

When you run opendiff, there is often also an unpredictable delay (up to seconds long) before the FileMerge app is launched. Running FileMerge directly does not suffer from this problem.

For the above two reasons, PatchViewer configures FileMerge as its default file comparison tool in preference to opendiff.

FileMerge is typically located at:

/Applications/Xcode.app/Contents/Applications/FileMerge.app/Contents/MacOS/FileMerge

If you do wish to configure opendiff, the preference settings you would use are:

opendiff is typically located at:

/Applications/Xcode.app/Contents/Developer/usr/bin/opendiff

Note: Prefer to use the opendiff binary directly inside the Xcode.app bundle at Xcode.app/Contents/Developer/usr/bin/opendiff, rather than the symbolic link in /usr/bin/.