[PATCH 1 of 2] scmutil: improve documentation of revset APIs
Gregory Szorc
gregory.szorc at gmail.com
Sun Jun 26 02:12:48 UTC 2016
# HG changeset patch
# User Gregory Szorc <gregory.szorc at gmail.com>
# Date 1466907140 25200
# Sat Jun 25 19:12:20 2016 -0700
# Node ID 4903c4201049a504ed7ca47557a41a1c02e9391f
# Parent fbe380dc227a0240939aa5a4941eda70d958ea40
scmutil: improve documentation of revset APIs
I can never remember the differences between the various revset
APIs. I can never remember that scmutil.revrange() is the one I
want to use from user-facing commands.
Add some documentation to clarify this.
While we're here, the argument name for revrange() is changed to
"specs" because that's what it actually is.
diff --git a/mercurial/localrepo.py b/mercurial/localrepo.py
--- a/mercurial/localrepo.py
+++ b/mercurial/localrepo.py
@@ -549,28 +549,34 @@ class localrepository(object):
return iter(self.changelog)
def revs(self, expr, *args):
'''Find revisions matching a revset.
The revset is specified as a string ``expr`` that may contain
%-formatting to escape certain types. See ``revset.formatspec``.
- Return a revset.abstractsmartset, which is a list-like interface
+ Revset aliases from the configuration are not expanded. To expand
+ user aliases, consider calling ``scmutil.revrange()``.
+
+ Returns a revset.abstractsmartset, which is a list-like interface
that contains integer revisions.
'''
expr = revset.formatspec(expr, *args)
m = revset.match(None, expr)
return m(self)
def set(self, expr, *args):
'''Find revisions matching a revset and emit changectx instances.
This is a convenience wrapper around ``revs()`` that iterates the
result and is a generator of changectx instances.
+
+ Revset aliases from the configuration are not expanded. To expand
+ user aliases, consider calling ``scmutil.revrange()``.
'''
for r in self.revs(expr, *args):
yield self[r]
def url(self):
return 'file:' + self.root
def hook(self, name, throw=False, **args):
diff --git a/mercurial/scmutil.py b/mercurial/scmutil.py
--- a/mercurial/scmutil.py
+++ b/mercurial/scmutil.py
@@ -803,20 +803,39 @@ def revpair(repo, revs):
raise error.Abort(_('empty revision on one side of range'))
# if top-level is range expression, the result must always be a pair
if first == second and len(revs) == 1 and not _pairspec(revs[0]):
return repo.lookup(first), None
return repo.lookup(first), repo.lookup(second)
-def revrange(repo, revs):
- """Yield revision as strings from a list of revision specifications."""
+def revrange(repo, specs):
+ """Execute 1 to many revsets and return the union.
+
+ This is the preferred mechanism for executing revsets using user-specified
+ config options, such as revset aliases.
+
+ The revsets specified by ``specs`` will be executed via a chained ``OR``
+ expression. If ``specs`` is empty, an empty result is returned.
+
+ ``specs`` can contain integers, in which case they are assumed to be
+ revision numbers.
+
+ It is assumed the revsets are already formatted. If you have arguments
+ that need to be expanded in the revset, call ``revset.formatspec()``
+ and pass the result as an element of ``specs``.
+
+ Specifying a single revset is allowed.
+
+ Returns a ``revset.abstractsmartset`` which is a list-like interface over
+ integer revisions.
+ """
allspecs = []
- for spec in revs:
+ for spec in specs:
if isinstance(spec, int):
spec = revset.formatspec('rev(%d)', spec)
allspecs.append(spec)
m = revset.matchany(repo.ui, allspecs, repo)
return m(repo)
def meaningfulparents(repo, ctx):
"""Return list of meaningful (or all if debug) parentrevs for rev.
More information about the Mercurial-devel
mailing list