[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