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

[Matt Mackall]

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.

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.


-- 
Mathematics is the supreme nostalgia of our time.