merge-tools.txt
109 lines
| 4.6 KiB
| text/plain
|
TextLexer
|
r12771 | To merge files Mercurial uses merge tools. | ||
A merge tool combines two different versions of a file into a merged | ||||
file. Merge tools are given the two files and the greatest common | ||||
ancestor of the two file versions, so they can determine the changes | ||||
made on both branches. | ||||
|
r12809 | Merge tools are used both for :hg:`resolve`, :hg:`merge`, :hg:`update`, | ||
:hg:`backout` and in several extensions. | ||||
|
r12771 | |||
|
r12804 | Usually, the merge tool tries to automatically reconcile the files by | ||
|
r12809 | combining all non-overlapping changes that occurred separately in | ||
the two different evolutions of the same initial base file. Furthermore, some | ||||
|
r12771 | interactive merge programs make it easier to manually resolve | ||
conflicting merges, either in a graphical way, or by inserting some | ||||
conflict markers. Mercurial does not include any interactive merge | ||||
|
r12809 | programs but relies on external tools for that. | ||
Available merge tools | ||||
""""""""""""""""""""" | ||||
|
r12824 | External merge tools and their properties are configured in the | ||
merge-tools configuration section - see hgrc(5) - but they can often just | ||||
|
r12809 | be named by their executable. | ||
A merge tool is generally usable if its executable can be found on the | ||||
|
r12824 | system and if it can handle the merge. The executable is found if it | ||
is an absolute or relative executable path or the name of an | ||||
application in the executable search path. The tool is assumed to be | ||||
able to handle the merge if it can handle symlinks if the file is a | ||||
symlink, if it can handle binary files if the file is binary, and if a | ||||
GUI is available if the tool requires a GUI. | ||||
|
r12771 | |||
There are a some internal merge tools which can be used. The internal | ||||
merge tools are: | ||||
``internal:merge`` | ||||
|
r12809 | Uses the internal non-interactive simple merge algorithm for merging files. | ||
It will fail if there are any conflicts. | ||||
|
r12771 | |||
``internal:fail`` | ||||
Rather than attempting to merge files that were modified on both | ||||
branches, it marks these files as unresolved. Then the resolve | ||||
command must be used to mark files resolved. | ||||
``internal:local`` | ||||
Uses the local version of files as the merged version. | ||||
``internal:other`` | ||||
|
r12809 | Uses the other version of files as the merged version. | ||
|
r12771 | |||
``internal:prompt`` | ||||
Asks the user which of the local or the other version to keep as | ||||
the merged version. | ||||
``internal:dump`` | ||||
Creates three versions of the files to merge, containing the | ||||
contents of local, other and base. These files can then be used to | ||||
|
r12804 | perform a merge manually. If the file to be merged is named | ||
``a.txt``, these files will accordingly be named ``a.txt.local``, | ||||
|
r12771 | ``a.txt.other`` and ``a.txt.base`` and they will be placed in the | ||
|
r12804 | same directory as ``a.txt``. | ||
|
r12771 | |||
|
r12809 | Internal tools are always available and do not require a GUI but will by default | ||
not handle symlinks or binary files. | ||||
Choosing a merge tool | ||||
""""""""""""""""""""" | ||||
|
r12771 | |||
|
r12824 | Mercurial uses these rules when deciding which merge tool to use: | ||
|
r12809 | |||
|
r12824 | 1. If a tool has been specified with the --tool option to merge or resolve, it | ||
|
r12809 | is used. If it is the name of a tool in the merge-tools configuration, its | ||
configuration is used. Otherwise the specified tool must be executable by | ||||
the shell. | ||||
|
r12771 | |||
|
r12824 | 2. If the ``HGMERGE`` environment variable is present, its value is used and | ||
|
r12809 | must be executable by the shell. | ||
|
r12824 | 3. If the filename of the file to be merged matches any of the patterns in the | ||
|
r12809 | merge-patterns configuration section, the first usable merge tool | ||
corresponding to a matching pattern is used. Here, binary capabilities of the | ||||
merge tool are not considered. | ||||
|
r12771 | |||
|
r12824 | 4. If ui.merge is set it will be considered next. If the value is not the name | ||
|
r12809 | of a configured tool, the specified value is used and must be executable by | ||
the shell. Otherwise the named tool is used if it is usable. | ||||
|
r12771 | |||
|
r12824 | 5. If any usable merge tools are present in the merge-tools configuration | ||
section, the one with the highest priority is used. | ||||
|
r12771 | |||
|
r12826 | 6. If a program named ``hgmerge`` can be found on the system, it is used - but | ||
|
r12809 | it will by default not be used for symlinks and binary files. | ||
|
r12771 | |||
|
r12824 | 7. If the file to be merged is not binary and is not a symlink, then | ||
|
r12771 | ``internal:merge`` is used. | ||
|
r12824 | 8. The merge of the file fails and must be resolved before commit. | ||
|
r12771 | |||
.. note:: | ||||
After selecting a merge program, Mercurial will by default attempt | ||||
|
r12809 | to merge the files using a simple merge algorithm first. Only if it doesn't | ||
succeed because of conflicting changes Mercurial will actually execute the | ||||
merge program. Whether to use the simple merge algorithm first can be | ||||
controlled by the premerge setting of the merge tool. Premerge is enabled by | ||||
default unless the file is binary or a symlink. | ||||
|
r12771 | |||
|
r12809 | See the merge-tools and ui sections of hgrc(5) for details on the | ||
|
r12771 | configuration of merge tools. | ||