[PATCH] help: help topic for merge tools
Steve Borho
steve at borho.org
Tue Oct 19 04:41:36 UTC 2010
On Mon, Oct 18, 2010 at 11:00 AM, Mads Kiilerich <mads at kiilerich.com> wrote:
> On 10/18/2010 04:51 PM, Erik Zielke wrote:
I think I'll pile onto Mads's comments.
>> # 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`
>
> "hg help mergetools"?
>
> But I think we can keep the reference to the merge-tools section.
>
>> to see internally available merge tools
>> + and further information on merge tools.
>
> Does it really matter here that some of the tools are internal?
>
>> ``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.
>
> Perhaps it should be mentioned that this applies to both "merge" and
> "resolve".
I would mention that merge programs are also given the greatest common
ancestor of the two file versions, so they can determine the changes
made on both branches.
>> +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.
>
> Perhaps it should be noted that "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)."
>
>> +By default, Mercurial will attempt to do a classic 3-way merge on text
>> +files internally before trying to use an external tool.
>
> I think this is covered by the note below and can be removed here.
And is a configurable property of the merge 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.
>
> spelchek
>
> Perhaps it should be described what this means - and how this can be useful
> for a resolve-based workflow.
A better phrasing:
Rather than attempting to merge files that were modified on both branches,
it marks these files as unresolved. The the resolve command must be used to
resolve these conflicting files.
>> +
>> +``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.
>
> a "which" too much?
I would substitute 'used' with 'kept'.
>
>> +``internal:dump``
>> + Creates three versions of the files to merge, containg the contents
>
> spelchek
>
>> + 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.
I just tonight re-learned that HGMERGE has different semantics than
ui.merge. 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 it is a symlink, but not considering binary capabilities.
>
>> +- 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.
>
> - and if binary and symlink and gui capabilities matches
>
>> +- 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.
>
> s/hg/Mercurial/
>
> I think it should be noted here that this is controlled by setting .premerge
> for the merge tool. "usually" indicates some kind of non-determinism.
>
> (If
>>
>> +the file to be merged is binary or a symlink, then hg doesn't bother
>> +with the simple merge algorithm.
>
> Not exactly; premerge is just enabled by default unless the file is binary
> or symlink.
>
> If the selected merge tool is
>>
>> +internal:fail, internal:local, or internal:other,
>
> or internal:prompt
>
> then hg skips the
>>
>> +simple merge algorithm, as the user has specifically requested that no
>> +merging take place.)
>
> Is that relevant? Isn't that obvious?
>
>> +See merge tools and ui section of configuration help on setting the merge
>> +tools.
>
> "See the _merge-tools_ and ui sections of configuration help for details on
> _configuration_ of merge tools."
>
>
> I don't know how the split between "the man page" and this help topic should
> be, but the exact semantics of some of the config settings only makes sense
> in the context of this fine help topic (especially premerge, symlink, binary
> and gui). Perhaps the merge-tools section should reference this text too.
>
> /Mads
> _______________________________________________
> Mercurial-devel mailing list
> Mercurial-devel at selenic.com
> http://selenic.com/mailman/listinfo/mercurial-devel
>
--
Steve Borho
More information about the Mercurial-devel
mailing list