[PATCH] rebase: clarify --source and --base documentation so it's less ambiguous

[Mads Kiilerich]

On 10/08/2014 08:28 PM, Sean Farley wrote:
> Mads Kiilerich writes:
>
>> On 10/08/2014 07:43 PM, Augie Fackler wrote:
>>> # HG changeset patch
>>> # User Augie Fackler <raf at durin42.com>
>>> # Date 1412026314 14400
>>> #      Mon Sep 29 17:31:54 2014 -0400
>>> # Node ID 205bd6e5778956a22663ec1d81542c6bcdd40522
>>> # Parent  a1eb21f5caea4366310e32aa85248791d5bbfa0c
>>> rebase: clarify --source and --base documentation so it's less ambiguous
>>>
>>> I've been burned by these descriptions before, and others have as
>>> well. Hopefully this is more universally understandable.
>>>
>>> diff --git a/hgext/rebase.py b/hgext/rebase.py
>>> --- a/hgext/rebase.py
>>> +++ b/hgext/rebase.py
>>> @@ -50,10 +50,10 @@
>>>    
>>>    @command('rebase',
>>>        [('s', 'source', '',
>>> -     _('rebase from the specified changeset'), _('REV')),
>>> +     _('rebase the specified changeset and its descendants'), _('REV')),
>> +1
> +1
>
>>>        ('b', 'base', '',
>>> -     _('rebase the tree around the specified changeset without '
>>> -       'ancestors of dest'),
>>> +     _('rebase specified changeset and all ancestors which are not already'
>>> +       ' ancestors of the destination'),
>> I agree it is more clear, but it also leaves essential facts out so it
>> is more clearly incorrect.
> For once, I actually might agree with Mads ;-) Though, I'm not a
> strongly opinionated as him on this phrasing. We could emphasize the
> 'finding' aspect of this:
>
> 'find the base of the specified changeset and rebase all descendants'
>
> which is under 80 characters! We could also use 'branchpoint' (and maybe
> other keywords from revsets?) to clarify what 'base' means:
>
> 'find the base (branchpoint) of the specified changeset and rebase all
> descendants'
>
> A little longer, but just a thought.

My problem with "base" is that it doesn't have a clear definition. 
"Branchpoint" might be better - it gives a hint that it pretty much is 
the common ancestor (or one of multiple common ancestor heads?) ... but 
actually it is one of the children of the ancestor. "Tree around" is 
also very vague ... by design. +1 for anything that is better than that ;-)

/Mads