[PATCH] help: help topic for merge tools

Tue Oct 19 01:38:32 CDT 2010

Okay. I will then try to update the help topic based on your comments.

2010/10/19 Steve Borho <steve at borho.org>

> 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://selenic.com/pipermail/mercurial-devel/attachments/20101019/3991bed6/attachment.htm>