[PATCH] help: help topic for merge tools

Erik Zielke ez at aragost.com
Mon Oct 18 09:51:14 CDT 2010


# HG changeset patch
# User Erik Zielke <ez at aragost.com>
# Date 1287413138 -7200
# Node ID 9e3df9485d1331c28443ea5d663e202b11475c73
# Parent  22a4f798e2e51870fc28ae6fa90d4828bdfb4d57
help: help topic for merge tools

I have made a help topic for merge tools. The text in the topic is
based on the http://mercurial.selenic.com/wiki/MergeProgram page from
the wiki, along with some extra information on the internal merge tools.

diff -r 22a4f798e2e5 -r 9e3df9485d13 doc/hgrc.5.txt
--- a/doc/hgrc.5.txt	Fri Oct 15 23:00:45 2010 -0500
+++ b/doc/hgrc.5.txt	Mon Oct 18 16:45:38 2010 +0200
@@ -856,20 +856,8 @@
     Template string for commands that print changesets.
 ``merge``
     The conflict resolution program to use during a manual merge.
-    There are some internal tools available:
-
-    ``internal:local``
-        keep the local version
-    ``internal:other``
-        use the other version
-    ``internal:merge``
-        use the internal non-interactive merge tool
-    ``internal:fail``
-        fail to merge
-
-For more information on configuring merge tools see the
-merge-tools_ section.
-
+    See :hg:`merge-tools` to see internally available merge tools
+    and further information on merge tools.
 ``patch``
     command to use to apply patches. Look for ``gpatch`` or ``patch`` in
     PATH if unset.
diff -r 22a4f798e2e5 -r 9e3df9485d13 mercurial/help.py
--- a/mercurial/help.py	Fri Oct 15 23:00:45 2010 -0500
+++ b/mercurial/help.py	Mon Oct 18 16:45:38 2010 +0200
@@ -94,6 +94,7 @@
      loaddoc('multirevs')),
     (['revsets'], _("Specifying Revision Sets"), loaddoc('revsets')),
     (['diffs'], _('Diff Formats'), loaddoc('diffs')),
+    (['mergetools'], _('Merge Tools'), loaddoc('mergetools')),
     (['templating', 'templates'], _('Template Usage'),
      loaddoc('templates')),
     (['urls'], _('URL Paths'), loaddoc('urls')),
diff -r 22a4f798e2e5 -r 9e3df9485d13 mercurial/help/mergetools.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mercurial/help/mergetools.txt	Mon Oct 18 16:45:38 2010 +0200
@@ -0,0 +1,73 @@
+To merge files Mercurial uses a merge program.
+
+A merge program combines two different versions of a file into a merged file.
+
+Usually, the program tries to do so automatically, by combining all
+the 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.
+
+By default, Mercurial will attempt to do a classic 3-way merge on text
+files internally before trying to use an external tool.
+
+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.
+
+``internal:fail``
+   Makes the merge fail no matter if the merge is trvial to do.
+
+``internal:local``
+   Uses the local version of files as the merged version.
+
+``internal:other``
+   Uses the remote version of files as the merged version.
+
+``internal:prompt``
+   Asks the user if the local or the other version
+   of the files which should be used as the merged version.
+
+``internal:dump``
+   Creates three versions of the files to merge, containg the contents
+   of local, other and base. These files can then be used for manually
+   merging. If the file merged is name a.txt, these files will accordingly
+   be named a.txt.local, a.txt.other and a.txt.base and they will be
+   placed in the same directory as the file to merge.
+
+How Mercurial decides which merge program to use
+
+- If the HGMERGE environment variable is present, it is used.
+
+- Otherwise, 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.
+
+- Otherwise, if the ui.merge config setting is set, that is used.
+
+- Otherwise, 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.
+
+- Otherwise, if a program named hgmerge exists on the system, that is used.
+
+- Otherwise, if the file to be merged is not binary and is not a symlink,
+  then internal:merge is used.
+
+- Otherwise, the merge fails.
+
+However: after selecting a merge program, Mercurial will usually
+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 will hg actually execute the merge program. (If
+the file to be merged is binary or a symlink, then hg doesn't bother
+with the simple merge algorithm. If the selected merge tool is
+internal:fail, internal:local, or internal:other, then hg skips the
+simple merge algorithm, as the user has specifically requested that no
+merging take place.)
+
+See merge tools and ui section of configuration help on setting the merge
+tools.


More information about the Mercurial-devel mailing list