Mercurial > hg
changeset 12809:e5922564ab01 stable
help: improve merge-tools topic, describe --tool and clarify details
This doesn't make it simpler, but it makes it more correct.
With help from erikz, mg and abuehl.
| author | Mads Kiilerich <mads@kiilerich.com> |
|---|---|
| date | Fri, 22 Oct 2010 17:08:15 +0200 |
| parents | 74f6531581e8 |
| children | a68ccfd9c7be |
| files | mercurial/commands.py mercurial/help/merge-tools.txt |
| diffstat | 2 files changed, 56 insertions(+), 33 deletions(-) [+] |
line wrap: on
line diff
--- a/mercurial/commands.py Fri Oct 22 17:05:51 2010 +0200 +++ b/mercurial/commands.py Fri Oct 22 17:08:15 2010 +0200 @@ -2943,7 +2943,7 @@ The resolve command can be used in the following ways: - - :hg:`resolve [--tool] FILE...`: attempt to re-merge the specified + - :hg:`resolve [--tool TOOL] FILE...`: attempt to re-merge the specified files, discarding any previous merge attempts. Re-merging is not performed for files already marked as resolved. Use ``--all/-a`` to selects all unresolved files. ``--tool`` can be used to specify
--- a/mercurial/help/merge-tools.txt Fri Oct 22 17:05:51 2010 +0200 +++ b/mercurial/help/merge-tools.txt Fri Oct 22 17:08:15 2010 +0200 @@ -5,24 +5,38 @@ ancestor of the two file versions, so they can determine the changes made on both branches. -The merge tools are used both for :hg:`resolve` and :hg:`merge`. +Merge tools are used both for :hg:`resolve`, :hg:`merge`, :hg:`update`, +:hg:`backout` and in several extensions. Usually, the merge tool tries to automatically reconcile the files by -combining all the non-overlapping changes that occurred separately in -the two different -evolutions of the same initial base file. Furthermore, some +combining all non-overlapping changes that occurred separately in +the two different evolutions of the same initial base file. Furthermore, some 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 -programs but relies on external tools for that. External merge tools -and their properties and usage is configured in merge-tools section - -see hgrc(5). +programs but relies on external tools for that. + +Available merge tools +""""""""""""""""""""" + +External merge tools and their properties and usage is configured in the +merge-tools configuration section - see hgrc(5) - but they can often also just +be named by their executable. + +A merge tool is generally usable if its executable can be found on the +system and if it can handle the merge. The executable can be found on the +system if it either 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. There are a some internal merge tools which can be used. The internal merge tools are: ``internal:merge`` - Uses the internal non-interactive merge tool for merging files. + Uses the internal non-interactive simple merge algorithm for merging files. + It will fail if there are any conflicts. ``internal:fail`` Rather than attempting to merge files that were modified on both @@ -33,7 +47,7 @@ Uses the local version of files as the merged version. ``internal:other`` - Uses the remote version of files as the merged version. + Uses the other version of files as the merged version. ``internal:prompt`` Asks the user which of the local or the other version to keep as @@ -47,40 +61,49 @@ ``a.txt.other`` and ``a.txt.base`` and they will be placed in the same directory as ``a.txt``. -How Mercurial decides which merge program to use +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 +""""""""""""""""""""" -1. If the ``HGMERGE`` environment variable is present, it is used. If - specified it must be either an executable path or the name of an - application in your executable search path. +Mercurial uses these rules when decing which merge tool to use: + +0. If a tool has been specified with the --tool option to merge or resolve, it + 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. -2. If the filename of the file to be merged matches any of the - patterns in the merge-patterns configuration section, then the - corresponding merge tool is used, unless the file to be merged is a - symlink. Here binary capabilities of the merge tool are not - considered. +1. If the ``HGMERGE`` environment variable is present, its value is used and + must be executable by the shell. + +2. If the filename of the file to be merged matches any of the patterns in the + 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. -3. If ui.merge is set, it is used. +3. If ui.merge is set it will be considered next. If the value is not the name + 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. -4. If any merge tools are present in the merge-tools configuration - section, and any of the tools can be found on the system, the - priority settings are used to determine which one to use. Binary, - symlink and GUI capabilities do also have to match. +4. If any usable merge tools are present in the merge-tools configuration + section, the one with the higest priority is used. -5. If a program named ``hgmerge`` exists on the system, it is used. +5. If a program named ``hgmerge`` can be found on the system, it is used - but + it will by default not be used for symlinks and binary files. 6. If the file to be merged is not binary and is not a symlink, then ``internal:merge`` is used. -7. The merge fails. +7. The merge of the file fails and must be resolved before commit. .. note:: After selecting a merge program, Mercurial will by default attempt - to merge the files using a simple merge algorithm first, to see if - they can be merged without conflicts. Only if there are 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 symlink. + 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. -See the merge-tools and ui sections of hgrc(5) for details on +See the merge-tools and ui sections of hgrc(5) for details on the configuration of merge tools.