# HG changeset patch
# User FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
# Date 2014-01-17 14:55:11
# Node ID 96be25f1da459918dcf12ddbbb603792026c4834
# Parent  b61ad01c4e7334e369b0fa6f20983c6bb25c035a

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.

diff --git a/mercurial/revset.py b/mercurial/revset.py
--- a/mercurial/revset.py
+++ b/mercurial/revset.py
@@ -270,6 +270,10 @@ def func(repo, subset, a, b):
 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 @@ def contains(repo, subset, x):
     """``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 @@ def filelog(repo, subset, x):
     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 @@ def hasfile(repo, subset, x):
 
     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 minrev(repo, subset, x):
 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 remote(repo, subset, x):
 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"))