Integrating with Source Control, Configuration Management and Other Applications

AccuRev

The AccuRev  OS X client can be configured to use Araxis Merge for file comparison and merge operations.

These steps have been tested with AccuRev 5.2.

To configure the AccuRev client to use Merge for file comparison:

• In the AccuRev client, choose Preferences… from the Tools menu.
• Select the Diff/Merge tab.

• In the Diff entry field, enter the following:

  /usr/local/bin/compare -wait -2 %1% %2%

  Note: If necessary, replace /usr/local/bin with the full path to the Araxis Merge compare utility on your machine.

• Close the Preferences window.

To configure the AccuRev client to use Merge for file merging:

• The Araxis Merge compare utility cannot be used directly for file merging by the AccuRev client, which passes quoted filenames and expects a particular return code on success. To work around this, create a file ac-merge-shim.sh in /usr/local/bin/ (or another location of your choosing) with the following content:

  #!/bin/sh
  eval "$*"
  if [ "$?" = "-1" ]; then
      exit 1;
  fi
  exit 0;
  

• Make the ac-merge-shim.sh script executable. For example, run the following command in the OS X Terminal (replacing /usr/local/bin with the full path to the shim file as necessary):

  chmod a+x /usr/local/bin/ac-merge-shim.sh

• In the AccuRev client, choose Preferences… from the Tools menu.
• Select the Diff/Merge tab.

• In the Merge entry field, enter the following:

  /usr/local/bin/ac-merge-shim.sh /usr/local/bin/compare -wait -a3 -3 %1% %2% %a% %o%

  Note: If necessary, replace the two instances of /usr/local/bin/ with the full path to the ac-merge-shim.sh script and the Araxis Merge command-line compare utility respectively.

• Close the Preferences window.

Dreamweaver

Adobe (Macromedia) Dreamweaver  CS3 integrates with Araxis Merge and can launch a two-way file comparison. Consequently, the Standard Edition of Merge is sufficient if you will be using it only with Dreamweaver.

To configure Dreamweaver CS3 to use Merge as the file comparison tool:

• Ensure that the command-line utilities have been installed as described in the Installing the Merge command-line utilities section of the Installing from the Araxis Website page.
• Choose Dreamweaver > Preferences....
• Select the File Compare category.
• Click the Browse... button to bring up the Select External Editor dialog.
• Locate and select the Merge compare command-line utility from the folder in which you have installed it.
• Click the Open button. The full path to the Merge compare command-line utility should now be shown in the Choose application to compare files entry field.
• Click OK to dismiss the Preferences dialog.

Eclipse

For Eclipse , see the entry for Subclipse.

Git

Merge integrates tightly with Git . Araxis provides a Git File System Plugin to enable Merge to access files in Git depots directly. Merge is also able to populate the button drop-down versions menu with other revisions of each file being compared. For more information, see Comparing Text Files (or Typed/Pasted Text).

Git can also be configured to use Merge for file comparison and merge operations.

Newer Git versions

As of v1.6.4, Git includes support for Araxis Merge. The following configuration steps have been tested with Git v1.7.1.

To use Araxis Merge for file comparison and file merging with Git v1.6.4 or later:

• Ensure that the command-line utilities have been installed as described in the Installing the Merge command-line utilities section of the Installing from the Araxis Website page.

• Update the Git configuration file  by adding the following diff and merge tool configurations:

  [diff] 
  tool = araxis
  
  [merge] 
  tool = araxis

• To compare files, use the git difftool  command. To resolve conflicting changes after merging files from a branch or remote repository, use git mergetool .

Legacy Git versions

Versions of Git prior to v1.6.4 can be configured to use Merge with the instructions below (tested with Git v1.6.1).

To use Araxis merge for file comparison with older versions of Git:

• Ensure that the command-line utilities have been installed as described in the Installing the Merge command-line utilities section of the Installing from the Araxis Website page.

• Update the Git configuration file  by adding the following diff tool configuration:

  [diff] 
  external = /Users/<userid>/bin/araxisgitdiff
  renames = true

  Note: in the above path, replace /Users/<userid>/bin/araxisgitdiff with the full path to the Merge araxisgitdiff command-line utility that you have installed on your machine.

• To compare files using older versions of Git, use the git diff  command.

To use Araxis Merge for file merging with older versions of Git:

• Ensure that the command-line utilities have been installed as described in the Installing the Merge command-line utilities section of the Installing from the Araxis Website page.

• Update the Git configuration file  by adding the following merge tool configuration:

  [mergetool "araxis"] 
  cmd = /Users/<userid>/bin/araxisgitmerge "$PWD/$REMOTE" "$PWD/$BASE" "$PWD/$LOCAL" "$PWD/$MERGED"
  trustExitCode = false
  
  [mergetool]
  keepBackup = false
  
  [merge] 
  tool = araxis

  Note: in the above path, replace /Users/<userid>/bin/araxisgitmerge with the full path to the Merge araxisgitmerge command-line utility that you have installed on your machine.

• To resolve conflicting changes after merging files from a branch or remote repository, use git mergetool .

Interface Builder

Apple’s Interface Builder  has a menu option Write Class Files... that will generate source files for the classes you create in the Inspector. Interface Builder will ask you whether you wish to replace or merge the newly generated class files with those that already exist in the project. If you choose to merge it will open the files with FileMerge (invoked via the opendiff command). However, it is possible to use Araxis Merge in place of FileMerge.

To configure Merge as the Interface Builder comparison tool:

• Ensure that the command-line utilities have been installed as described in the Installing the Merge command-line utilities section of the Installing from the Araxis Website page.

• From a Terminal window, perform the following commands:

  cd /Developer/usr/bin
  sudo mv opendiff opendiff-old
  sudo ln -s /Users/<userid>/bin/araxisopendiff opendiff

  Note: in the above path, replace /Users/<userid>/bin/araxisopendiff with the full path to the Merge araxisopendiff command-line utility that you have installed on your machine.

  Note: if other people use your machine, ensure that they have permission to access the araxisopendiff command.

Please note that this change will also affect any other application (including Xcode) that endeavours to run the opendiff command.

MacHg

MacHg  is a fully featured free Mercurial client for OS X. MacHg provides built-in support for Araxis Merge.

To configure MacHg to use Merge:

• Open the MacHg Preferences window.
• Select the Mercurial page.
• In the Merge and Diff Tool section, choose AraxisMerge for both the For Diffs use and For Merges use fields.

Mercurial

Merge integrates tightly with Mercurial . Araxis provides a Mercurial File System Plugin to enable Merge to access files in Mercurial depots directly. Merge is also able to populate the button drop-down versions menu with other revisions of each file being compared. For more information, see Comparing Text Files (or Typed/Pasted Text).

Mercurial can also be configured to use Merge for file/folder comparison and file merge operations. The comparison integration uses the Extdiff extension , which is supplied with Mercurial.

The following integration instructions have been tested with Mercurial v1.8.4.

To configure Mercurial to use Araxis Merge for file merging:

• Ensure that the command-line utilities have been installed as described in the Installing the Merge command-line utilities section of the Installing from the Araxis Website page.

• Update the appropriate Mercurial configuration file  to add the following merge program  configuration:

  [merge-tools]
  araxismergetool.premerge = False
  araxismergetool.args = $other $base $local $output
  araxismergetool.executable = /Users/<userid>/bin/araxishgmerge
  araxismergetool.checkconflict = True
  araxismergetool.binary = True
  araxismergetool.gui =  True

  Note: in the above path, replace /Users/<userid>/bin/araxishgmerge with the full path to the Merge araxishgmerge command-line utility that you have installed on your machine.

To configure Mercurial to use Araxis Merge for file comparison:

• Ensure that the command-line utilities have been installed as described in the Installing the Merge command-line utilities section of the Installing from the Araxis Website page.

• Update the appropriate Mercurial configuration file  to create a new hg sub-command, arxdiff:

  [extensions]
  extdiff = 
  
  [extdiff]
  cmd.arxdiff = /Users/<userid>/bin/compare
  opts.arxdiff = -2 -wait

  Note: in the above path, replace /Users/<userid>/bin/compare with the full path to the Merge compare command-line utility that you have installed on your machine.

  The -wait argument to the compare utility is required to enable file comparisons to be recompared as a different type (text, binary or image) from within Merge and, in the case when Mercurial launches a folder comparison, to enable file comparisons to be launched from that folder comparison.

Examples of using hg arxdiff:

• Launch a two-way file comparison showing the changes to a modified file myfile.c:

  hg arxdiff myfile.c

• Launch a two-way file comparison of revisions 1 and 2 of myfile.c:

  hg arxdiff -r1 -r2 myfile.c

• Launch a two-way file or folder comparison (as appropriate, depending upon the number of files modified) to show all the changes within the current working directory:

  hg arxdiff

• Launch a two-way file or folder comparison (as appropriate, depending upon the number of files modified) to show all the changes applied by the changeset with id 0bc544fad9e6:

  hg arxdiff -c 0bc544fad9e6

Perforce

Merge integrates tightly with Perforce . Araxis provides a Perforce File System Plugin to enable Merge to browse Perforce depots directly. This means that, for example, you can compare branches of source code directly within a depot without syncing them to the client workspace. Merge is also able to populate the button drop-down versions menu with other revisions of each file being compared. For more information, see Comparing Text Files (or Typed/Pasted Text).

To browse Perforce repositories directly from Merge:

• See the instructions on the Perforce File System Plugin page.

To configure P4V (2007.2 release or later) to use Merge for file comparison and merging:

• Ensure that the command-line utilities have been installed as described in the Installing the Merge command-line utilities section of the Installing from the Araxis Website page.
• Choose Preferences... from the P4V menu.
• Select the Diff tab.
• Select the Other application radio button (or Use external application in older versions of P4V).
• For the Location field, click the Browse button for the user supplied diff application, and select the file araxisp4diff from the folder in which you have installed it.
• Ensure that the Arguments field reads %1 %2. This step can be ignored for older versions of P4V, which do not have this field.
• Select the Merge tab.
• Select the Other application radio button (or Use external application in older versions of P4V).
• For the Location field, click the Browse button and select the file araxisp4winmrg from the folder in which you have installed it.
• Ensure that the Arguments field reads %b %1 %2 %r. This step can be ignored for older versions of P4V, which do not have this field.
• Click the OK button to dismiss the Preferences dialog.
• P4V should now open Merge for its comparison and interactive merging operations.

To configure the Perforce command-line tool (p4) to use Merge:

• Ensure that the command-line utilities have been installed as described in the Installing the Merge command-line utilities section of the Installing from the Araxis Website page.

• Set the P4DIFF environment variable to the full path of the araxisp4diff utility. Also, set the P4MERGE environment variable to the full path to araxisp4winmrg.

  For example, if you have placed the Merge command-line utilities in ~/bin, you might add the following to your .bash_profile:

  export P4DIFF=$HOME/bin/araxisp4diff
export P4MERGE=$HOME/bin/araxisp4winmrg

• When you open a new command shell, Merge should now be invoked as appropriate by the Perforce command-line tools. For example,

  p4 diff -t

  will open up a two-way comparison for each of the files that you have opened for edit (including any binary or image files) in your default changelist.

SmartSVN/SmartCVS

SmartSVN  and SmartCVS  clients can be configured to use Araxis Merge for file comparison and merge operations.

Note that the ability to use an external tool for solving conflicts is not available  in the Foundation version of SmartCVS.

To configure SmartSVN/SmartCVS to use Araxis Merge for file comparison:

• Choose Preferences... from the SmartSVN or SmartCVS menu.
• Select File Compare in the tree on the left (File Comparators in SmartCVS).
• Select the * pattern in the table and click the Edit... button.
• Select the External Comparator radio button.

• In the Command entry field, enter the following:

  /usr/local/bin/compare

  Note: in the above path, replace /usr/local/bin with the location of the full path to the Araxis Merge compare utility on your machine.

• In the Arguments entry field, enter the following:

  -wait -2 "${leftFile}" "${rightFile}

• Click OK to apply the changes and exit the Edit dialog.

To configure SmartSVN/SmartCVS to use Araxis Merge for file merging:

• Choose Preferences... from the SmartSVN or SmartCVS menu.
• Select Conflict Solver under Actions in the tree on the left.
• Select the External Conflict Solver radio button.

• In the Command entry field, enter the following:

  /usr/local/bin/compare

  Note: in the above path, replace /usr/local/bin with the location of the full path to the Araxis Merge compare utility on your machine.

• In the Arguments entry field, enter the following:

  -3 -wait -a3 "${leftFile}" "${rightFile}" "${baseFile}" "${mergedFile}"

  Note: The "${baseFile}" template is not required when using SmartCVS.

• Click OK to apply the changes and exit the Preferences dialog.

SourceTree

Atlassian SourceTree  is a client for Git and Mercurial featuring built-in support for Araxis Merge.

To configure SourceTree to use Merge:

• Ensure that the command-line utilities have been installed as described in the Installing the Merge command-line utilities section of the Installing from the Araxis Website page. The directory containing the utilities must be on the command-line shell’s search path.
• Open the SourceTree Preferences dialog and choose the Diff tab.
• Select Araxis Merge as the Visual Diff Tool and Merge Tool.

Subclipse

Subclipse  is an Eclipse plugin providing support for Subversion within the Eclipse IDE. It can be configured to use Merge as its merging tool. Merge will then be used whenever you choose Edit Conflicts from a Team menu in Eclipse.

Merge can also integrate directly with Subversion. Please see Subversion section for more information.

The following steps have been tested with Subclipse 1.6.13, Eclipse 3.6.0 and Subversion 1.6.

To configure Merge as the Subclipse file merging tool:

• Ensure that the command-line utilities have been installed as described in the Installing the Merge command-line utilities section of the Installing from the Araxis Website page.

• Unfortunately, the compare utility cannot be used directly to launch Merge, since Subclipse does not appropriately divide the user-specified list of ‘external conflict program’ parameters. It is therefore necessary to create a shell script that will divide the list of parameters appropriately.

  Create a file /Users/<userid>/bin/subclipse-shim.sh with the following content:

  #!/bin/sh
  eval "$*"

  Note: the above path is a suggested location for the shell script file, where /Users/<userid> is the full path to your home directory.

• In the Eclipse Preferences window, select the Team > SVN > Diff/Merge page.
• Select the External radio button.

• In the adjacent entry field, enter the following:

  /bin/sh

• In the Parameters field, enter the following:

  /Users/<userid>/bin/subclipse-shim.sh /Users/<userid>/bin/compare -wait -merge -a1 -3 -title1:"Common Ancestor" -title2:"Theirs" -title3:"Yours" "${base}" "${theirs}" "${yours}" "${merged}"

  Note: in the above path, replace /Users/<userid>/bin/subclipse-shim.sh with the full path to your shell script and replace /Users/<userid>/bin/compare with the full path to the Merge compare command-line utility that you have installed on your machine.

• Click the Apply button.

Subversion

Merge integrates well with Subversion . Araxis provides a Subversion File System Plugin to enable Merge to browse Subversion repositories directly. This means that, for example, you can compare branches of source code directly within a repository without syncing them to the client workspace. Merge is also able to populate the button drop-down versions menu with other revisions of each file being compared. For more information, see Comparing Text Files (or Typed/Pasted Text).

See also the entries for Subversive, svnX and Subclipse.

To browse Subversion repositories directly from Merge:

• See the instructions on the Subversion File System Plugin page.

To configure the Subversion command-line tool (svn) to use Merge:

• Ensure that the command-line utilities have been installed as described in the Installing the Merge command-line utilities section of the Installing from the Araxis Website page.
• Open your ‘SVN configuration area’ configuration file in a text editor. The default location for this file is ~/.subversion.

• Uncomment the line that specifies the diff-cmd and set its value to the path of the Merge araxissvndiff executable that you have installed on your machine:

  diff-cmd = /Users/<userid>/bin/araxissvndiff

  Note: in the above path, replace /Users/<userid>/bin/araxissvndiff with the full path to the Merge Merge araxissvndiff command-line utility that you have installed on your machine.

• The Subversion command-line client versions 1.5 and later can be configured to merge non-conflicting changes automatically, but to launch Merge interactively to resolve conflicting changes.

  If you wish to have Subversion merge non-conflicting changes itself, and use Merge only for conflicting changes, add a merge-tool-cmd line to set the path of the Merge araxissvnmerge executable:

  merge-tool-cmd = /Users/<userid>/bin/araxissvnmerge

  Note: in the above path, replace /Users/<userid>/bin/araxissvnmerge with the full path to the Merge araxissvnmerge command-line utility that you have installed on your machine.

  The merge-tool-cmd option is ignored when the value of the diff3-cmd option is defined. Ensure that the value of the diff3-cmd option has not been defined.

• Alternatively, if you would rather use Merge to resolve all changes, you can define the diff3-cmd configuration option instead of merge-tool-cmd. (Note that diff3-cmd is the only option for Subversion versions prior to v1.5.)

  If defined, diff3-cmd should be set to the path of the Merge araxissvndiff3 command-line utility:

  diff3-cmd = /Users/<userid>/bin/araxissvndiff3

  Note: in the above path, replace /Users/<userid>/bin/araxissvndiff3 with the full path to the Merge Merge araxissvndiff3 command-line utility that you have installed on your machine.

• Save the modified configuration file and exit the text editor.
• Merge will now be launched when performing Subversion commands (e.g. svn diff, svn update and svn merge) that require a two or three-way comparison.

Subversive

Subversive , the official Eclipse plugin can be configured to use Merge as its merging tool. It provides support for Subversion within the Eclipse IDE. Merge will then be used for file comparisons, and for merging whenever you choose Edit Conflicts from a Team menu in Eclipse.

Merge can also integrate directly with Subversion. Please see Subversion section for more information.

The following steps have been tested with Subversive 0.7.9, Eclipse 3.6.0 and Subversion 1.6.

To configure Merge as the Subversive file comparison and merging tool:

• Ensure that the command-line utilities have been installed as described in the Installing the Merge command-line utilities section of the Installing from the Araxis Website page.

• Unfortunately, the compare utility cannot be used directly to launch Merge, since Subversive does not divide the user-specified lists of program arguments appropriately. It is therefore necessary to create a shell script that will divide the parameter list appropriately.

  Create a new shell script /Users/<userid>/bin/subversive-shim.sh with the following content:

  #!/bin/sh
  eval "$*"

  Note: the above path is a suggested location for the shell script file, where /Users/<userid> is the full path to your home directory.

• To configure Subversive to use an external tool for file comparisons, the user specifies the location of the tool and a list of arguments that are to be sent to it. When configuring this list of arguments, the tokens ${mine}, ${base} and ${theirs} are used to represent the location of the files to be compared. When a file comparison is invoked, tokens in the list of arguments are replaced with paths to the files to be compared. Unfortunately, Subversive is inconsistent in which tokens it replaces with paths, depending on how the file comparison is invoked in Eclipse. The remote file is sometimes passed using ${base} and at other times ${theirs}. Fortunately, when ${base} is used, ${theirs} is replaced with no text, and it is therefore possible to create a script that will launch Merge using the paths from ${mine} and ${theirs}, unless ${theirs} is empty text, in which case the paths in ${mine} and ${base} are compared instead.

  Create a file /Users/<userid>/bin/araxissubversivediff.osa with the following content:

  #!/usr/bin/osascript
  on run args
    tell application "Araxis Merge"
      launch
  
      set _left to (POSIX path of ((item 1 of args as POSIX file) as alias))
      if not item 2 of args equals ""
        set _right to (POSIX path of ((item 2 of args as POSIX file) as alias))
      else
        set _right to (POSIX path of ((item 3 of args as POSIX file) as alias))
      end if
  
      set _document to compare {_left, _right}
  
      tell _document
        activate
      end tell
  
      try
        repeat while exists _document
          delay 1
        end repeat
      on error
      end try
  
    end tell
  end run
  

  Note: the above path is a suggested location for the osascript file, where /Users/<userid> is the full path to your home directory.

• In the Eclipse Preferences window, select the Team > SVN > Diff Viewer page.
• Click the Add… button.

• In the Extension or mime–type field, enter the following:

  *

• Within the Diff program arguments box, enter the following into the Program Path field:

  /bin/sh

• In the larger field beneath, enter the following:

  /Users/<userid>/bin/subversive-shim.sh /usr/bin/osascript /Users/<userid>/bin/araxissubversivediff.osa "${mine}" "${theirs}" "${base}"

  Note: in the above path, replace /Users/<userid>/bin/subversive-shim.sh with the full path to your shell script and replace /Users/<userid>/bin/araxissubversivediff.osa with the full path to your osascript.

• Within the Merge program arguments box, enter the following into the Program Path field:

  /bin/sh

• In the larger field beneath, enter the following:

  /Users/<userid>/bin/subversive-shim.sh /Users/<userid>/bin/compare -wait -merge -a1 -3 -title1:"Common Ancestor" -title2:"Yours" -title3:"Theirs" "${base}" "${mine}" "${theirs}" "${merged}"

  Note: in the above path, replace /Users/<userid>/bin/subversive-shim.sh with the full path to your shell script and replace /Users/<userid>/bin/compare with the full path to the Merge compare command-line utility that you have installed on your machine.

• Click the OK button.
• Review the new settings in the Diff Viewer table.
• Click the Apply button.

Surround SCM

Seapine  Surround SCM 2009 has built-in support for Araxis Merge. To set Araxis Merge as the default application for file comparison and merging:

• Choose User Options... from the Tools menu.
• Select the Diff/Merge tab.
• Edit the settings for a selected file type.
• Select Araxis Merge from the comparison application drop-down list.

Please see the Seapine website  for more details.

svnX

svnX  is an open source GUI for most features of the Subversion client. It has built-in support for Merge.

To configure svnX to use Merge:

• Choose Araxis Merge as the Diff application in the svnX Preferences window.
• Please be sure to read the svnX online help for information about setting-up svnX to work with Merge. At the time of writing, svnX requires the araxissvndiff command to be installed in a particular location. (See ‘Installing the Merge command-line utilities’ on the Installing from the Araxis Website page for more information about araxissvndiff.)

Versions

The Versions  client for Subversion can be easily configured to use Araxis Merge.

To configure Merge as the Versions comparison tool:

• Open the Preferences window within Versions.
• Choose Araxis Merge from the File Comparison drop-down field.

Xcode

Apple’s Xcode  enables third-party tools, including Merge, to be used for performing comparisons.

To configure Merge as the Xcode comparison tool:

• Ensure that the command-line utilities have been installed as described in the Installing the Merge command-line utilities section of the Installing from the Araxis Website page.
• Open the Preferences window within Xcode.
• Select the SCM preferences page.
• Select the Options tab.
• In the Comparison Handling section, select Other... for the View comparisons using setting.
• From the file chooser that appears, locate and select the araxisp4diff Merge command-utility from the location in which you installed it.