6.1.8 External Merge Tools

These hooks allow the user to use their favorite tools when resolving File Content Conflicts.

The Default hooks include helper functions used by the hooks below to invoke a number of external merge tools known to monotone, and you can override or extend these hooks if you have a preferred tool, or if you have a tool specific to certain file types.

merge3 (ancestor_path, left_path, right_path, merged_path, ancestor_text, left_text, right_text)

Called by mtn conflicts resolve_first when interactive is given; by mtn merge, mtn explicit_merge when --resolve-conflicts is not specified and the internal merger fails for a file content conflict; and by mtn update or any command that accepts --update for workspace file content conflicts.

The actual ancestor, left, and right contents of the file are passed in the ancestor_text, left_text, and right_text strings. In addition, the hook is given the names that this file had in the ancestor (ancestor_path), left (left_path), and right (right_path) trees, and the name it will end up having in the merged tree (merged_path). These paths are useful for merge tools that can display the names of files in their GUI, since the actual path names are likely more meaningful than the temporary file names the merge tool will actually be working on.

On success, merge3 returns a string, which should be the new file contents, the result of merging the given texts. If nil is returned, the merge command fails; this is how the user can abort a merge.

The default definition of this hook writes the texts to temporary files, then delegates the actual merge to the result of get_preferred_merge3_command. The default definition of get_preferred_merge3_command checks to see if the MTN_MERGE environment variable, or the Lua variable merger are set to the name of a merge tool that it recognizes, and if not, then simply searches for several popular tools that might be installed on the local system.

The default hook then invokes the merge tool, waits for it to return, and checks to see if merged_path was written. If not, it returns nil, and the merge command fails.

For details, see the code in Default hooks.

By redefining this hook the user can choose a preferred merge tool, or select different merge tools for different file types. For example, gimp for .png files, OpenOffice.org for .doc, and so on.

get_preferred_merge3_command(tbl)

Returns a table command, mkey telling merge3 what external merge tool to run.

tbl wraps up the various arguments for each merge command and is always provided by merge3. If there is a particular editor that you would like to use to perform merge3 operations, override this hook to specify it.