[PATCH 09 of 11] debugrebuildstate: clarify that rev can't be specified without -r

[Mads Kiilerich]

# HG changeset patch
# User Mads Kiilerich <madski at unity3d.com>
# Date 1365982742 -7200
# Node ID f651e07fc203b86af84d82416a09431c763c84a6
# Parent  04d7d14de104157b3d1440c9a001c49e984b030d
debugrebuildstate: clarify that rev can't be specified without -r

-r has a default value of '' in the command line. The function default value of
'tip' is thus never used and any attempt at specifying revisions without -r
will fail.

It seems like then intended behavior was that 'hg debugrebuildstate' without
any parameters should set the parents to tip. That would be very confusing now
when the command primarily is used to recover from incorrect stat info.

It is apparently undocumented that '' is the same as '.' ... unless it is
passed in a place where revsets are used.

diff --git a/mercurial/commands.py b/mercurial/commands.py
--- a/mercurial/commands.py
+++ b/mercurial/commands.py
@@ -2248,9 +2248,19 @@ def debugpvec(ui, repo, a, b=None):
 
 @command('debugrebuildstate',
     [('r', 'rev', '', _('revision to rebuild to'), _('REV'))],
-    _('[-r REV] [REV]'))
-def debugrebuildstate(ui, repo, rev="tip"):
-    """rebuild the dirstate as it would look like for the given revision"""
+    _('[-r REV]'))
+def debugrebuildstate(ui, repo, rev):
+    """rebuild the dirstate as it would look like for the given revision
+
+    If no revision is specified the first current parent will be used.
+
+    The dirstate will be set to the files of the given revision.
+    The actual working directory content or existing dirstate
+    information such as adds or removes is not considered.
+
+    One use of this command is to make the next :hg:`status` invocation
+    check the actual file content.
+    """
     ctx = scmutil.revsingle(repo, rev)
     wlock = repo.wlock()
     try: