Differences between revisions 13 and 21 (spanning 8 versions)
Revision 13 as of 2012-05-17 21:30:45
Size: 4983
Editor: mpm
Comment:
Revision 21 as of 2019-08-07 17:58:24
Size: 4453
Editor: GregTatum
Comment: This statement feels wrong to me, VS code provided a much better experience here than the default merge resolution tools on Mac. https://code.visualstudio.com/docs/editor/versioncontrol#_merge-conflic
Deletions are marked like this. Additions are marked like this.
Line 2: Line 2:

<<Include(A:style)>>
Line 27: Line 25:
For each file changed in both parents Mercurial chooses a merge tool. The merge tool is chosen from the list of file pattern matches in the {{{[merge-patterns]}}} section followed by all tools sorted by decreasing {{{priority}}} order. The list is filtered for whether the {{{executable}}} (defaulting to ''mymergetool'') can be found, whether it supports {{{symlinks}}} or {{{binary}}} files, and whether {{{gui}}} is available. To bypass the priority scheme and set the default tool directly, specify the merge tool in {{{[ui]}}} sections {{{merge}}} option. For backwards compatibility the tool {{{hgmerge}}} is implicitly added with lowest priority. For each file changed in both parents Mercurial chooses a merge tool. The merge tool is chosen from the list of file pattern matches in the `[merge-patterns]` section followed by all tools sorted by decreasing `priority` order. The list is filtered for whether the `executable` (defaulting to ''mymergetool'') can be found, whether it supports symlinks or binary files, and whether a GUI is available. To bypass the priority scheme and set the default tool directly, specify the merge tool in `[ui]` section `merge` option. For backwards compatibility, the tool `hgmerge` is implicitly added with lowest priority.
Line 29: Line 27:
If the chosen merge tools {{{premerge}}} is True then an internal merge is attempted, and if it seems successful then the result it will silently be used without running the actual merge tool. If the chosen merge tool's `premerge` setting is True then an internal merge is attempted. If the premerge reports no conflicts, then the result will silently be used without running the actual merge tool.
Line 31: Line 29:
The merge tool is run with an argument list of {{{args}}} with the following variables expanded:
 * {{{$output}}} expands to the existing ''file'' which already contains the version from the first parent - and this is also where the result of the merge ends up / must end up
 * {{{$local}}} expands to ''file.orig'' which is created as a copy of ''file'' in the working directory version - it thus contains the unmerged version from the first parent
 * {{{$base}}} expands to ''/tmp/file~base.*'' which is created with the version from the common ancestor revision (see {{{hg debugancestor}}})
 * {{{$other}}} expands to ''/tmp/file~other.*'' which is created with the version from the new second parent revision which the first parent is merged with
The merge tool is run with an argument list from `args` with the following variables expanded:
 * `$output` expands to the existing ''file'' which already contains the version from the first parent - and this is also where the result of the merge ends up / must end up
 * `$local` expands to ''file.orig'' which is created as a copy of ''file'' in the working directory version - it thus contains the unmerged version from the first parent
 * `$base` expands to a temporary file which is created with the version from the merge ancestor
 
* `$other` expands to a temporary file which is created with the version from the new second parent revision which the first parent is merged with
Line 39: Line 37:
 [merge-tools]
 mymergetool.priority = 100
 mymergetool.premerge = False
 mymergetool.args = $local $other $base -o $output
 myimgmerge =
 [merge-patterns]
 **.jpg = myimgmerge
 **.exe = internal:fail
[merge-tools]
mymergetool.priority = 100
mymergetool.premerge = False
mymergetool.args = $local $other $base -o $output
myimgmerge =

[merge-patterns]
**.jpg = myimgmerge
**.exe = internal:fail
Line 49: Line 48:
Further tool options include: Tool options include:

 * args - the arguments to pass (defaults to $local $base $other)
 * premerge - whether to attempt internal merge first (defaults to True)
 * executable - executable name or path (defaults to <tool>)
 * binary - supports binary files (False)
 * symlink - supports symlinks (False)
 * gui - requires a GUI (False)
 * priority - priority of this tool (0)

executable can also be specified using a python script and function.

example:
Line 51: Line 62:
 <tool>.args - the arguments to pass (defaults to $local $base $other)
 <tool>.executable - executable name or path (defaults to <tool>)
 <tool>.binary - supports binary files (False)
 <tool>.symlinks - supports symlinks (False)
 <tool>.gui - requires a GUI (False)
 <tool>.priority - priority of this tool (0)
mymergetool.executable=python:c:\somepython.py:mergefn
Line 58: Line 64:

where somepython.py contains a function with signature:
{{{
def mergefn(ui, repo, args, **kwargs):
}}}

where args is list of args passed to merge tool. (by default, expanded: $local $base $other)
Line 61: Line 74:
Mercurial has a selection of "internal" tools for various purposes (ee [[Topic:merge-tools]] for full details). The most interesting of these is `internal:merge`, which provides a traditional merge with conflict markers. To set this as your default tool, simply add the following to you config: Mercurial has a selection of "internal" tools for various purposes (see [[Topic:merge-tools]] for full details). The most interesting of these is `internal:merge3`, which provides a traditional merge with conflict markers. To set this as your default tool, add the following to you config:
Line 65: Line 78:
merge = internal:merge merge = internal:merge3
Line 68: Line 81:
This is not generally recommended as Mercurial gets no direct feedback when merges are successfully completed, and it's not terribly user-friendly compared to modern tools. Rather than relying on a dedicated merge tool, care will be needed to manually edit the text. The good news is that many code editors provide hints and UI support for fixing conflicts. After manually resolving the conflict, follow the instructions from hg [[Cmd:status]] and use the [[Cmd:resolve]] command to keep the manually resolve the conflicts.
Line 70: Line 83:
(!) When using `internal:merge`, you'll want to carefully read the help for the [[Cmd:resolve]] command to avoid losing your merge work.

=== See also ===
== See also ==
 * [[Cmd:merge]] and [[Cmd:update]] - command that may merge files
 * [[Cmd:resolve]] - reattempting file merges and making manual merges
Line 74: Line 87:
 * [[MergeProgram]]

=== Notes ===

In February 2008, [[mpm|Matt Mackall]] contributed this new [[Merge|merge]] tool configuration feature. This feature is available in version 1.0 (see [[WhatsNew]]).

 * "[[http://selenic.com/repo/hg/rev/5af5f0f9d724|merge: allow smarter tool configuration]]" in [[http://selenic.com/repo/hg/shortlog|main Mercurial repository]] (changesets starting with 5af5f0f9d724)
 * "[[http://selenic.com/pipermail/mercurial/2008-February/016923.html|New merge tool system in mainline]]", posting by Matt Mackall, Feb 3, 2008, [[http://selenic.com/pipermail/mercurial/|Mercurial mailing list]]

==== Choosing internal merge with conflict markers ====
To have the internal merge with the conflict markers for example in [[TortoiseHg]] set
{{{
[ui]
merge = internal:merge
}}}
in Mercurial.ini.

==== Overriding merge.ui configuration from the command line ====
See [[TipsAndTricks#mergemineortheir|How to keep "My" or "Their" files when doing merge]] for an example on how you can override merge configuration on the command line.
 * [[TipsAndTricks#mergemineortheir|How to keep "My" or "Their" files when doing merge]]
 * [[Topic:config]]

Merge Tool Configuration

How to customize which merge tools Mercurial chooses.

1. Introduction

Mercurial delegates most non-trivial file-level merging operations to an external program, called a merge tool. In most installations, Mercurial will automatically search your system for the 'best' available tool, based on a set of known tools in its global configuration.

This tool choice can be extensively customized based on various properties like filename, binary data, running in a GUI, etc.

2. Defining a merge tool

To define a merge tool, add something like the following in .hgrc:

 [merge-tools]
 mymergetool.something = something

which will define mymergetool (the left hand side until the first dot). The option values defines the behaviour of the tool.

For each file changed in both parents Mercurial chooses a merge tool. The merge tool is chosen from the list of file pattern matches in the [merge-patterns] section followed by all tools sorted by decreasing priority order. The list is filtered for whether the executable (defaulting to mymergetool) can be found, whether it supports symlinks or binary files, and whether a GUI is available. To bypass the priority scheme and set the default tool directly, specify the merge tool in [ui] section merge option. For backwards compatibility, the tool hgmerge is implicitly added with lowest priority.

If the chosen merge tool's premerge setting is True then an internal merge is attempted. If the premerge reports no conflicts, then the result will silently be used without running the actual merge tool.

The merge tool is run with an argument list from args with the following variables expanded:

  • $output expands to the existing file which already contains the version from the first parent - and this is also where the result of the merge ends up / must end up

  • $local expands to file.orig which is created as a copy of file in the working directory version - it thus contains the unmerged version from the first parent

  • $base expands to a temporary file which is created with the version from the merge ancestor

  • $other expands to a temporary file which is created with the version from the new second parent revision which the first parent is merged with

Example configuration:

[merge-tools]
mymergetool.priority = 100
mymergetool.premerge = False
mymergetool.args = $local $other $base -o $output
myimgmerge =

[merge-patterns]
**.jpg = myimgmerge
**.exe = internal:fail

Tool options include:

  • args - the arguments to pass (defaults to $local $base $other)
  • premerge - whether to attempt internal merge first (defaults to True)
  • executable - executable name or path (defaults to <tool>)

  • binary - supports binary files (False)
  • symlink - supports symlinks (False)
  • gui - requires a GUI (False)
  • priority - priority of this tool (0)

executable can also be specified using a python script and function.

example:

mymergetool.executable=python:c:\somepython.py:mergefn

where somepython.py contains a function with signature:

def mergefn(ui, repo, args, **kwargs):

where args is list of args passed to merge tool. (by default, expanded: $local $base $other)

3. Internal merge with conflict markers

Mercurial has a selection of "internal" tools for various purposes (see merge-tools for full details). The most interesting of these is internal:merge3, which provides a traditional merge with conflict markers. To set this as your default tool, add the following to you config:

[ui]
merge = internal:merge3

Rather than relying on a dedicated merge tool, care will be needed to manually edit the text. The good news is that many code editors provide hints and UI support for fixing conflicts. After manually resolving the conflict, follow the instructions from hg status and use the resolve command to keep the manually resolve the conflicts.

4. See also


CategoryHowTo

MergeToolConfiguration (last edited 2019-08-07 17:58:24 by GregTatum)