[PATCH v2] backout: make help more explicit about what backout does

[Jonathan Nieder]

Kevin Bullock wrote:
> On 2 Feb 2011, at 6:24 PM, Jonathan Nieder wrote:

>> def backout(ui, repo, node=None, rev=None, **opts):
>>     '''reverse effect of earlier changeset
[...]
>> +    Prepare a new changeset with the effect of REV undone in the
>> +    current working directory.
>> +
>> +    If REV is the tip, then this changeset is committed automatically.
>
> Is this accurate? Isn't the backout automatically committed if REV is a branch head, but -not- tip?

I screwed up.  For "tip" please read "the parent of the working
directory"[1].

>> +
>> +    Otherwise, hg needs to merge the changes and you can inspect
>> +    them before committing.
>> +    By default, the pending changeset will have one parent,
>> +    maintaining a linear history.
>
> Just a nit: the line-breaking here is weird. Are you starting a new
> paragraph or not?

Not. :)  Sorry about that.

> Maybe something like this:
>
> --
> If REV is the tip [a branch head?], then this changeset is committed automatically.
> Otherwise, the backout changes are merged with tip, and the result is
> left in the working directory so that it can be inspected before
> committing.
> 
> By default, the backout changeset will have just one parent, maintaining
> a linear history. With the --merge option, first a new changeset is
> committed as a child of REV that undoes its changes. This backout
> changeset is then merged as normal with the working directory parent.
> --

What is the goal of this rewording?  In my opinion it focuses
more on the details of the algorithm and less on the user-visible
result.  I find it harder to understand.

Thanks for the catches.
Jonathan

[1] Details, based on the code:

 - if REV is the parent of the working directory:

    1. make the working directory match REV's parent
    2. commit

 - otherwise, if --merge is not present:

    1. make the working directory match REV's parent
    2. perform a 3-way merge (hg update) to carry the change forward
       on top of the (old) parent of the working directory.

 - otherwise, --merge is present and REV is not the 

    1. make the working directory match REV's parent
    2. commit
    3. go to the (old) parent of the working directory.
    4. merge