Diff & Merge Tools

Tower comes with integrations for many Diff and Merge tools. If, however, your tool of choice is not included, you can write a custom integration script.

Writing Your Own Integration Script for Other Applications

It might be that your favorite diff or merge tool is not among the applications that Tower supports by default. In that case, you can write your own configuration file named "CompareTools.plist" and put it into "~/Library/Application Support/com.fournova.Tower3/CompareTools/". 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/>
        <key>SupportsDiffChangeset</key>
        <true/>
    </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. You can also overwrite a configuration for a diff tool that comes with Tower by using the same identifier for your configuration.

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 whether or not it supports external launching with arguments and how exactly this is done.

Here are the detailed steps that are necessary:

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 settings.
   • 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: Whether 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.
   • SupportsDiffChangeset: Whether or not the tool supports changesets (i.e. it can show multiple file diffs from a changeset in a single window - instead of opening a new window for each item). If set to true, the "Perform Directory Diff" option is not suggested in Tower's settings when configuring it as the preferred diff tool.
2. Now, 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"
3. Put the .plist file and the launch script into "~/Library/Application Support/com.fournova.Tower3/CompareTools/".
   
   EXAMPLE: If you created a "~/Library/Application Support/com.fournova.Tower3/CompareTools/CompareTools.plist" and (based on the example configuration below) a launch script file named "kaleidoscope.sh", the expected location will be "~/Library/Application Support/com.fournova.Tower3/CompareTools/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 - "$@" 
       
   
       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.
   

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.