help: clarify distinction among `contains`/`file`/`filelog`
For a Mercurial new-comer, the distinction between `contains(x)`,
`file(x)`, and `filelog(x)` in the "revsets" help page may not be
obvious. This commit tries to make things more obvious (text based on
an explanation from Matt in an FB group thread).
--- a/mercurial/revset.py Thu Apr 24 16:47:22 2014 +0200
+++ b/mercurial/revset.py Mon Apr 28 15:09:23 2014 -0700
@@ -585,8 +585,8 @@
def contains(repo, subset, x):
"""``contains(pattern)``
- Revision contains a file matching pattern. See :hg:`help patterns`
- for information about file patterns.
+ The revision's manifest contains a file matching pattern (but might not
+ modify it). 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
@@ -784,9 +784,10 @@
"""``filelog(pattern)``
Changesets connected to the specified filelog.
- 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()``.
+ For performance reasons, visits only revisions mentioned in the file-level
+ filelog, rather than filtering through all changesets (much faster, but
+ doesn't include deletes or duplicate changes). 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