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

[Kevin Bullock]

On Feb 3, 2011, at 12:15 AM, Jonathan Nieder wrote:

> 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.

Fair enough, it was totally off-the-cuff. But I found your original rewording a little confusing as to the actual changesets one ends up with. Without --merge, when all is said, done and committed, you end up with -one- new changeset, which you might have to manually inspect before committing. With --merge, you end up (IIUC) with -two- new changesets: a simple backout changeset, and a merge with the working dir parent (which you have to inspect and manually commit).

I was trying to strike a balance between clarity of describing the results and clarity of high-level description. There's probably a better way to do it :)

pacem in terris / mir / shanti / salaam / heiwa
Kevin R. Bullock