Third-Party Merge Tools

Using third-party merge tools with Perforce

Info & Tags

Article #:
47
Created:
04/27/07
Modified:
10/29/08
Tags:
merge, p4, p4v, p4win, third party software

Related Articles

  1. Third Party Defect Tracking Integration with Perforce
  2. Integrations - Third Party
  3. P4Merge
  4. Command line P4Merge on Mac OS X
  5. Integrations - Perforce

SUMMARY

This article describes how to use third-party merge tools with Perforce.


DETAILS

Using Third-Party Merge Tools with P4V

Perforce's cross-platform GUI contains not only its own powerful merging capabilities, but also the built-in ability to use an external merge program. You can configure this by choosing Tools->Preferences, then clicking the Merge tab, clicking the radio button Use external application, and entering the filename there. Note that this tool should be a graphical utility that opens its own windows even on platforms such as Linux. An xterm can be used to run shell script merges if desired.

Using Third-Party Merge Tools with the Command-Line P4

When resolving files and selecting the merge option, Perforce outputs four files. The four files, in order of presentation, are:

  1. the base file
  2. the source file (also known as "theirs")
  3. the target file (also known as "yours")
  4. the merge file.

These four files can then be used as input to a third-party diff/merge program during the resolve process.

For example, if you were integrating into a file named "foo.c", Perforce passes the following arguments to an external merge program. 

txxxt(n).tmp	= base		read-only temp file

txxxt(n+1).tmp	= theirs 	read-only temp file

foo.c		= yours		local copy of target file open for integrate

txxxt(n+2).tmp	= merge		writable temp file

(Here, the "xxx" and (n) would be replaced by a unique file number sequence.)

To specify a third-party diff/merge, set the P4MERGE environment variable. For example: 

set P4MERGE=merge.exe

If you need to specify command line options to the diff/merge program, then you can wrap these in a batch file and provide the batch file name to P4MERGE. For example: 

set P4MERGE=merge.bat

The general form of a Windows-style batch file is: 

::merge.bat
::
merge.exe %1 %2 %3 %4

More examples

AraxisMerge serves as a good case study of the generic process of integrating third-party merge tools. AraxisMerge is a popular merge tool for Windows platforms available from Araxis Ltd.

Important Note: Araxis Merge Professional is needed if you require three-way merging. If you are only able to bring up a two-window merge, you most likely have the "Standard" version and you will need to upgrade in order to have a three-way merge.

AraxisMerge 5.0

During a three-way merge, the preferred display order of AraxisMerge is to put the Base file in the middle of the display, between the Source and Target files. Since Perforce outputs the Base file first, the file arguments have to be inverted in order to preserve the preferred AraxisMerge display order. This can be done by calling AraxisMerge from a batch file and explicitly changing the file argument order. 

::araxis.bat
::
compare.exe /wait /3 %2 %1 %3 %4

Because the Base file output from Perforce is read-only (which prohibits AraxisMerge from editing it), you must begin by checking the AraxisMerge option to "Allow editing in read-only files" (View > Options > File Comparisons > Editing).

The critical issue in integrating with Perforce is properly saving the merge file. By default, when context-clicking on any file and selecting Save, AraxisMerge saves the file contents to the specified merge file (%4). Also, when selecting "Save As..." on any file, AraxisMerge provides the merge file (txxxtn+2.tmp = %4) as the default argument to the "Save As..." command.

There is no requirement to use the Base file as the merge location. Many users prefer to use the target file ("Theirs") as the merge location. Whatever your preference, the command line argument sequence should be arranged appropriately.

In summary:

  1. Make changes in AraxisMerge to any file
  2. From the main or context-click menus choose "Save" (or "Save As..." and accept the default).
    Then, quit AraxisMerge.
  3. After quitting AraxisMerge, program control returns to Perforce. The Merge file is now properly recognized. Verify that contents of the Merge file are as expected by selecting "Edit Merged File".

AraxisMerge 5.5

In AraxisMerge version 5.5, you can additionally set options for the display headers. For example, if you wanted the title bars above the files to display the perforce terminology for "yours" and "theirs", you could modify the "araxis.bat" file to the following: 

::araxis.bat
::
:: (the following command should all be on one line)
::
compare.exe /wait /a1 /title1:"Base (Merge here)" /title2:"Theirs" /title3:
"Yours %3" /3 %1 %2 %3 %4

Note the use of the /aN in the above "araxis.bat" example. The /aN switch specifies the Base file (the common ancestor) and where it is displayed. By using the /aN option, AraxisMerge automatically swaps the display order of the first two file arguments.

Again, to use this batch file from the command line, set the appropriate environment variable, either using the DOS set command or the Perforce p4 set command. For example: 

p4 set P4MERGE=araxis.bat

If you want to use the "araxis.bat" batch file in P4Win, the Perforce Windows Client, choose Settings > Options > Diff/Merge > ... from the P4Win menu and set the merge program to "araxis.bat". If the batch file location is not in your default PATH, then you have to specify the full path to "araxis.bat".

AraxisMerge 6.0 And Up

Araxis Merge v6.0 supports an enhanced integration with Perforce. There is an update available for existing Araxis Merge v6.0 customers through their website at the following URL:

http://www.araxis.com/updates/

The procedure for taking advantage of the integration has changed, also. New instructions are available at their website at the following URL:

http://www.araxis.com/merge/scm_integration.html (Scroll down)

P4Merge

As of release 2005.1, the Perforce Windows Installer includes P4V's built-in graphical merge utility, P4Merge.

P4Win and the P4MERGE Environment Variable

P4Win reads the P4MERGE value from the P4Win registry settings, not the user's environment. If you want to use an external merge program in both the command line and P4Win, then you have to set the P4MERGE value in both places. Again, for P4Win, use the P4Win Settings menu. For P4, use either the set or p4 set commands. For more information on Perforce environment variables, see the Perforce Command Reference.

External Merge Programs and the SCC Plug-In

Programs that use the Perforce SCC plug-in interface (Microsoft Visual C++, for example) do not recognize the P4MERGE environment variable. The Microsoft SCC API provides no methods for merging files and therefore the P4SCC plug-in cannot do so. If you need to resolve file conflicts, use P4, P4Win, P4Web, or P4V.