[PATCH 1 of 3 v2] backout: add examples to clarify basic usage

[Pierre-Yves David]

On 10/11/2015 07:13 AM, Yuya Nishihara wrote:
> On Fri, 9 Oct 2015 18:38:17 +0200, Mathias De Maré wrote:
>> On Mon, Oct 5, 2015 at 7:14 AM, Mathias De Maré <mathias.demare at gmail.com>
>> wrote:
>>
>>> # HG changeset patch
>>> # User Mathias De Maré <mathias.demare at gmail.com>
>>> # Date 1443764903 -7200
>>> #      Fri Oct 02 07:48:23 2015 +0200
>>> # Node ID 1a73cad7ebc4dd778c72f6d64efb8235cae2faad
>>> # Parent  97dc6ab42aad232c73180dee648685c26662230b
>>> backout: add examples to clarify basic usage
>>>
>>
>> This one appears to have gotten dropped from patchwork. Can someone have a
>> look?
>>
>>>
>>> diff --git a/mercurial/commands.py b/mercurial/commands.py
>>> --- a/mercurial/commands.py
>>> +++ b/mercurial/commands.py
>>> @@ -485,6 +485,56 @@
>>>
>>>       .. container:: verbose
>>>
>>> +      Some examples:
>>> +
>>> +      - Reverse the effect of the parent of the working directory.
>>> +        This backout will be committed immediately::
>
> It seems we generally write bullet list in all lowercase.
>
>>> +        hg backout -r .
>>> +
>>> +      - reverse the effect of previous bad revision 23::
>>> +
>>> +          hg backout -r 23
>>> +          hg commit -m "Backout revision 23"
>>> +
>>> +      - reverse the effect of previous bad revision 23 and
>>> +        commit the backout immediately::
>>> +
>>> +          hg backout -r 23 --commit
>>> +
>>> +      - Reverse the effect of a previous change
>>> +        and add the backout in the history as a merge.
>>> +        This clearly shows the link to the backed out
>>> +        changeset.
>>> +
>>> +        Before the backout::
>>> +
>>> +          @  2
>>> +          |
>>> +          |
>>> +          o  1
>>> +          |
>>> +          |
>>> +          o  0
>>> +
>>> +        Backout command::
>>> +
>>> +          hg backout -r 1 --merge
>>> +
>>> +        After the backout, we have a merge that still needs
>>> +        to be committed::
>>> +
>>> +          @  3 Backed out revision 1
>>> +          |
>>> +          |
>>> +          | @  2
>>> +          |/
>>> +          |
>>> +          o  1
>>> +          |
>>> +          |
>>> +          o  0
>
> I'm not sure if we should advertise the --merge option. I think --merge
> exists mainly for backward compatibility.

If we do not want to advertise it, we should make it a deprecated?

(I've no opinion about advertising it, just pointing at consistency)

-- 
Pierre-Yves David