changeset 20289:96be25f1da45

revset: add explanation about the pattern without explicit kind

Before this patch, online help of "adds()", "contains()", "filelog()",
"file()", "modifies()" and "removes()" predicates doesn't explain
about how the pattern without explicit kind like "glob:" is treated,
even though each predicates treat it differently:

  - as "relpath:" by "adds()", "modifies()" and "removes()"

  - as "glob:" by "file()"

  - as special by "contains()" and "filelog()"
    - be relative to cwd, and
    - match against a file exactly
      ("relpath:" matches also against a directory)

This may confuse users.

This patch adds explanation about the pattern without explicit kind
to these predicates.

--- a/mercurial/revset.py	Fri Jan 17 23:55:03 2014 +0900
+++ b/mercurial/revset.py	Fri Jan 17 23:55:11 2014 +0900
@@ -270,6 +270,10 @@
 def adds(repo, subset, x):
     """``adds(pattern)``
     Changesets that add a file matching pattern.
+
+    The pattern without explicit kind like ``glob:`` is expected to be
+    relative to the current directory and match against a file or a
+    directory.
     """
     # i18n: "adds" is a keyword
     pat = getstring(x, _("adds requires a pattern"))
@@ -526,6 +530,10 @@
     """``contains(pattern)``
     Revision contains a file matching pattern. See :hg:`help patterns`
     for information about file patterns.
+
+    The pattern without explicit kind like ``glob:`` is expected to be
+    relative to the current directory and match against a file exactly
+    for efficiency.
     """
     # i18n: "contains" is a keyword
     pat = getstring(x, _("contains requires a pattern"))
@@ -713,6 +721,10 @@
     For performance reasons, ``filelog()`` does not show every changeset
     that affects the requested file(s). See :hg:`help log` for details. For
     a slower, more accurate result, use ``file()``.
+
+    The pattern without explicit kind like ``glob:`` is expected to be
+    relative to the current directory and match against a file exactly
+    for efficiency.
     """
 
     # i18n: "filelog" is a keyword
@@ -868,6 +880,8 @@
 
     For a faster but less accurate result, consider using ``filelog()``
     instead.
+
+    This predicate uses ``glob:`` as the default kind of pattern.
     """
     # i18n: "file" is a keyword
     pat = getstring(x, _("file requires a pattern"))
@@ -1003,6 +1017,10 @@
 def modifies(repo, subset, x):
     """``modifies(pattern)``
     Changesets modifying files matched by pattern.
+
+    The pattern without explicit kind like ``glob:`` is expected to be
+    relative to the current directory and match against a file or a
+    directory.
     """
     # i18n: "modifies" is a keyword
     pat = getstring(x, _("modifies requires a pattern"))
@@ -1216,6 +1234,10 @@
 def removes(repo, subset, x):
     """``removes(pattern)``
     Changesets which remove files matching pattern.
+
+    The pattern without explicit kind like ``glob:`` is expected to be
+    relative to the current directory and match against a file or a
+    directory.
     """
     # i18n: "removes" is a keyword
     pat = getstring(x, _("removes requires a pattern"))