help: improve merge-tools topic, describe --tool and clarify details stable
authorMads Kiilerich <mads@kiilerich.com>
Fri, 22 Oct 2010 17:08:15 +0200
branchstable
changeset 12809 e5922564ab01
parent 12808 74f6531581e8
child 12810 a68ccfd9c7be
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.
mercurial/commands.py
mercurial/help/merge-tools.txt
--- 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.