--- a/mercurial/commands.py	Sun Jun 27 22:20:47 2010 -0500
+++ b/mercurial/commands.py	Mon Jun 28 15:08:01 2010 +0200
@@ -3019,8 +3019,11 @@
 def revert(ui, repo, *pats, **opts):
     """restore individual files or directories to an earlier state
 
-    (Use update -r to check out earlier revisions, revert does not
-    change the working directory parents.)
+    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.
 
     With no revision specified, revert the named files or directories
     to the contents they had in the parent of the working directory.