Patchwork help: clarify distinction among `contains`/`file`/`filelog`

login
register
mail settings
Submitter Greg Hurrell
Date April 28, 2014, 10:22 p.m.
Message ID <0636a785b24d45923b50.1398723725@glh-mba1>
Download mbox | patch
Permalink /patch/4444/
State Accepted
Commit e9c2f76be74b3b174c7c75936f5503915b65f97e
Headers show

Comments

Greg Hurrell - April 28, 2014, 10:22 p.m.
# HG changeset patch
# User Greg Hurrell <glh@fb.com>
# Date 1398722963 25200
#      Mon Apr 28 15:09:23 2014 -0700
# Branch stable
# Node ID 0636a785b24d45923b50d694ba2937cddd4d3af5
# Parent  bcfd44abad933390b1b21d7ffcd107fca0023dd2
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).
Matt Mackall - April 29, 2014, 7:48 p.m.
On Mon, 2014-04-28 at 15:22 -0700, Greg Hurrell wrote:
> # HG changeset patch
> # User Greg Hurrell <glh@fb.com>
> # Date 1398722963 25200
> #      Mon Apr 28 15:09:23 2014 -0700
> # Branch stable
> # Node ID 0636a785b24d45923b50d694ba2937cddd4d3af5
> # Parent  bcfd44abad933390b1b21d7ffcd107fca0023dd2
> help: clarify distinction among `contains`/`file`/`filelog`

Queued for stable, thanks. Congratulations on your first Mercurial
patch.

Patch

diff -r bcfd44abad93 -r 0636a785b24d mercurial/revset.py
--- a/mercurial/revset.py	Mon Apr 21 16:13:15 2014 -0700
+++ 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