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

[Adrian Buehlmann]

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

which I think is far more precise than the nebulous "This command is
most likely not what you are looking for." (which just says - I'm
exaggerating -- "don't use this command, but we don't tell you why,
stupid user!")

Arguing that we shouldn't build on concepts like "Revision", "Working
directory" or "merge" in help texts is a red herring.

Help texts are not a replacement for a Tutorial. You can't explain
commands without using the the basic concepts.