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

[Adrian Buehlmann]

On 2011-06-06 03:06, Matt Mackall wrote:
> 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.

Ok! :-)

I'm starting to wonder what that "newbies shooting in their feet"
scenario exactly is.

IMHO, there definitely isn't much potential for "foot shooting" if I
revert a file to what it was at the current single parent revision --
bread and butter usage, common, and very often used.

But if I "revert" it to a completely different random revision, then
that might not be what I wanted (pretending I adopted the role of a newbie).

So, the potentially problematic cases are probably limited to 'hg
revert' invocations that specify -r/--rev, iff REV is not a parent.

And the culmination of "foot shooting" is probably specifying '-r'
together with '--all', iff REV is not a parent:

  $ hg par -q
  4:8765e19eea07

  $ hg revert --all -r 2
  reverting foo
  reverting x.txt

which truly has the potential to make the newbies believe they got what
they intended.

Perhaps we should ponder implementing something like

  $ hg revert --all -r 2
  abort: revision 2 is not a parent revision!
  (use update to sync with that revision or use revert -f to force)

  (The expert user nods here and reaches for the -f switch. Newbie
  calls his favorite local Mercurial expert and ask him what the
  heck is wrong.)

  $ hg revert -f --all -r 2
  reverting foo
  reverting x.txt