Tower Icon

Diff & Merge Tools

Tower offers you integrated diffs when viewing changes. However, you can also use an external application to display diffs. Tower can connect with a couple of different applications for this purpose.

To choose an external diff tool

  • Open Tower's preferences dialog and select the "Git Config" tab.

  • Choose one of the supported applications in the "Preferred Diff Tool" and "Preferred Merge Tool" drop-downs. You must have installed the application on your Mac for this to work.

Add new application as external diff tool

You can customize DiffTools and MergeTools by creating a configuration file named `CompareTools.plist` and put it into Tower's Application Support directory (`~/Library/Application Support/Tower/`). The configuration is in Apple's Property List XML format and looks like this:


                    <?xml version="1.0" encoding="UTF-8"?>
                    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
                    <plist version="1.0">
                    <array>
                    	<dict>
                    		<key>ApplicationIdentifier</key>
                    		<string>com.madebysofa.Kaleidoscope</string>
                    		<key>ApplicationName</key>
                    		<string>Kaleidoscope</string>
                    		<key>DisplayName</key>
                    		<string>Kaleidoscope</string>
                    		<key>LaunchScript</key>
                    		<string>kaleidoscope.sh</string>
                    		<key>Identifier</key>
                    		<string>kaleidoscope</string>
                    		<key>SupportsMergeTool</key>
                    		<false/>
                    	</dict>
                    </array>
                    </plist>
                    
The format supports multiple configurations so you can add as many as you like.
In addition to the configuration, you will have to create a wrapper script that handles launching of the external application and passing on the file arguments.

NOTE: You can also overwrite a configuration for a diff tool that comes with the Tower by using the same identifier for your configuration.

NOTE: In order to use an external application as DiffTool or MergeTool, it needs to offer the capability to be launched externally with given file arguments. Some applications respond to AppleScript, some offer a command line utility. You will have to search the documentation of the application wether or not it supports external launching with arguments and how it is done.

  1. First you have to create a configuration file in Apple's Property List format.

    • `ApplicationIdentifier` and `ApplicationName`: The name and bundle identifer of the diff tool application, respectively. This is used to find the application on your system. You should always provide both values.

    • `DisplayName`: The name as it should appear in the Tower preferences.

    • `LaunchScript`: The file name of the launch script to launch the diff tool application. It acts as a wrapper script as each diff tool accepts parameters differently.
      See below how to create the LaunchScript

    • `Identifier`: A unique identifier for the diff tool.

    • `SupportsMerge`: Wether or not the tool can be used to resolve merge conflicts. If it does not support it, it will not show up in the list of merge tools.
      NOTE: If it supports merge conflict resolution, you will have to switch the call for the number of arguments in the script. A MergeTool call will receive four arguments, a DiffTool call only receive two arguments. See the explanation of the `LaunchScript` property below for more information.

  2. Second you have to create a `LaunchScript´ file.

    • The file name of the launch script to launch the diff tool application.

    • The launch script is called with the following parameters when it is invoked as diff tool: `LAUNCH_SCRIPT $LOCAL $REMOTE`

    • When invoked as merge tool, the call is: `LAUNCH_SCRIPT $LOCAL $REMOTE $BASE $MERGE_RESULT`

    • The launch script file name is relative to the directory where you created the `CompareTools.plist` configuration file and expects a subdirectory called `CompareScripts` to keep things clean.

  3. Put the .plist file into ´~/Library/Application Support/Tower/` and the launch script into `~/Library/Application Support/Tower/CompareScripts/`.

EXAMPLE: If you created a `~/Library/Application Support/Tower/CompareTools.plist` and (based on the example configuration below) a launch script file named `kaleidoscope.sh`, the expected location will be `~/Library/Application Support/Tower/CompareScripts/kaleidoscope.sh`.

The following is an example how the launch script for Kaleidoscope could look like:


                    #!/bin/sh

                    APPLICATION_PATH=/Applications/Kaleidoscope.app
                    CMD="$APPLICATION_PATH/Contents/MacOS/ksdiff"

                    "$CMD" -w "$1" "$2"
                    
This is an example of an AppleScript calling BBEdit:

                       #!/bin/sh

                       /usr/bin/osascript - "$@" << END

                       on run args
                        set fileA to item 1 of args as POSIX file
                        set fileB to item 2 of args as POSIX file

                            tell application "BBEdit"
                    		    activate
                    	        compare fileA against fileB
                            end tell
                        end run

                        END
                    
However, most products provide a command line utility to make the call. You can also look at the compare scripts which are provided by Tower. They can be found in /Applications/Tower.app/Contents/Resources/CompareScripts (assuming you have placed Tower in your Applications folder). These scripts are written in a more robust way, like finding the install location of an application and sanitizing path names as they need to work across different systems and Git versions. NOTE: Please make sure that the launch script is executable! You can write the script in any language that is supported by your system.

NOTE:While all merge tools can also be used as diff tools, not every diff tool also supports merging. Please consult your external tool's manual or support team if you are not sure if it supports merging.


Related Topics

Command Line Tool

Coda Plugin