[PATCH RFC] revert: improve warning part of help text

[Matt Mackall]

On Mon, 2011-06-06 at 02:23 +0200, Adrian Buehlmann wrote:
> On 2011-06-06 02:02, Adrian Buehlmann wrote:
> > On 2011-06-06 01:42, Matt Mackall wrote:
> >> On Mon, 2011-06-06 at 01:18 +0200, Adrian Buehlmann wrote:
> >>> # HG changeset patch
> >>> # User Adrian Buehlmann <adrian at cadifra.com>
> >>> # Date 1307258994 -7200
> >>> # Node ID a189aee647f462e3eff219413f5903d7fd2f18f8
> >>> # Parent  b88368a3ade4b748c8e01cf0453158f80e558a7a
> >>> revert: improve warning part of help text
> >>>
> >>> Don't make assumptions about the user's intentions.
> >>>
> >>> diff --git a/mercurial/commands.py b/mercurial/commands.py
> >>> --- a/mercurial/commands.py
> >>> +++ b/mercurial/commands.py
> >>> @@ -4088,13 +4088,13 @@
> >>>  def revert(ui, repo, *pats, **opts):
> >>>      """restore individual files or directories to an earlier state
> >>>  
> >>> -    .. note::
> >>> -       This command is most likely not what you are looking for.
> >>> -       Revert will partially overwrite content in the working
> >>> -       directory without changing the working directory parents. Use
> >>> -       :hg:`update -r rev` to check out earlier revisions, or
> >>> -       :hg:`update --clean .` to undo a merge which has added another
> >>> -       parent.
> >>> +    .. warning::
> >>> +       In contrast to the update command, revert never changes the
> >>> +       parent revisions of the working directory. Revert thus cannot
> >>> +       completely set the working directory state back to an earlier
> >>> +       revision, nor can it undo a merge.
> >>> +       Use :hg:`update -r REV` to check out an earlier revision, or
> >>> +       :hg:`update --clean .` to undo a uncommitted merge.
> >>
> >> You're really overestimating new users here. Hang out on IRC more if you
> >> doubt me. New users don't understand working directories, parent
> >> revisions, or how that all connects to what happens when you commit. And
> >> merges are pure magic.
> 
> And I forgot to stress here that I think my wording even better serves
> that purpose (helping new users), because I explicitly say *what* the
> revert command can't do:
> 
> "Revert thus cannot completely set the working directory state back to
> an earlier revision, nor can it undo a merge."

And I've already rejected that as assuming too much knowledge in the
target audience.

I will happily replace said string when you find something that doesn't,
but no sooner.

-- 
Mathematics is the supreme nostalgia of our time.