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

[Yuya Nishihara]

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.