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

[Adrian Buehlmann]

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.

But then we might as well slap the sentence "Read the mercurial book"
into every command's help.

If you (as a user) don't know or don't want to know what the working
directory is, then you have to read about the basic concepts first.

> All they know is "huh, revert sounds like going backwards (even though I
> don't understand this jargon in the warning or even why it's a warning),
> I want to go backwards, let's see what happens, oh it wants --all
> (annoying!), now it looks like it worked, yay!"
> 
> In fact, most of them probably don't even get as far as reading the
> warning, as the summary line is too suggestive of what they want.
> 
> Also note that apparently git revert ~= hg backout.
> 
> SVN's revert command apparently works like ours:
> 
> http://svnbook.red-bean.com/en/1.5/svn.ref.svn.c.revert.html
> 
> ..but they've got the warning at the bottom where it won't help the
> fingers-faster-than-brain crowd.

I'm still convinced that "This command is most likely not what you are
looking for." is unsuitable for the help text of a professional product
like Mercurial is.

If I would exaggerate, I would say it's basically an insult.

One of the reasons why Mercurial could potentially make users angry.

(That's the point where I think I agree with Rupert on the first hunk of
his patch).