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

Jonathan Nieder jrnieder at gmail.com
Thu Feb 3 00:15:28 CST 2011


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


More information about the Mercurial-devel mailing list