[PATCH] help: help topic for merge tools

Erik Zielke ez at aragost.com
Tue Oct 19 04:49:35 CDT 2010


# HG changeset patch
# User Erik Zielke <ez at aragost.com>
# Date 1287478804 -7200
# Node ID 90ca8e5d9b8f370605964fde0b727f848cebd378
# Parent  d10369fefd01f165f76263d9b92423ae018b84bc
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 d10369fefd01 -r 90ca8e5d9b8f doc/hgrc.5.txt
--- a/doc/hgrc.5.txt	Sun Oct 17 13:24:37 2010 -0400
+++ b/doc/hgrc.5.txt	Tue Oct 19 11:00:04 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.
-
+    For more information on merge tools see :hg:`help merge-tools`.
+    For configuring merge tools see the merge-tools_ section.
 ``patch``
     command to use to apply patches. Look for ``gpatch`` or ``patch`` in
     PATH if unset.
diff -r d10369fefd01 -r 90ca8e5d9b8f mercurial/help.py
--- a/mercurial/help.py	Sun Oct 17 13:24:37 2010 -0400
+++ b/mercurial/help.py	Tue Oct 19 11:00:04 2010 +0200
@@ -94,6 +94,7 @@
      loaddoc('multirevs')),
     (['revsets'], _("Specifying Revision Sets"), loaddoc('revsets')),
     (['diffs'], _('Diff Formats'), loaddoc('diffs')),
+    (['merge-tools'], _('Merge Tools'), loaddoc('merge-tools')),
     (['templating', 'templates'], _('Template Usage'),
      loaddoc('templates')),
     (['urls'], _('URL Paths'), loaddoc('urls')),
diff -r d10369fefd01 -r 90ca8e5d9b8f mercurial/help/merge-tools.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mercurial/help/merge-tools.txt	Tue Oct 19 11:00:04 2010 +0200
@@ -0,0 +1,88 @@
+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 greasest common
+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``.
+
+Usually, the merge tool tries to 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. Mercurial do 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(1).
+
+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``
+   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 resolve conflicting changes.
+
+``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 to be kept 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 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. If
+  specified it must be either an executable path or the name of an
+  application in your executable search path.
+
+- 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, unless the file to be merged is a
+  symlink. Here binary capabilities of the merge tool is not considered.
+
+- 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. Binary and symlink capabilities of the merge tool do also have
+  to match with the file to select it. Furthermore the gui capability also
+  have to match with whether gui output is possible.
+
+- 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, hg 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 will hg actually execute the merge program. Whether to use the
+simple merge algorithm first can be controlled be the premerge
+setting for the merge tool, which is enabled by default unless the
+file is binary or symlink.
+
+See merge tools and ui section of configuration help on setting the
+merge tools.
+
+See the merge-tools and ui sections of |hgrc(5)|_ for details
+on configuration of merge tools.


More information about the Mercurial-devel mailing list