Mercurial > public > mercurial-scm > hg-stable
diff mercurial/scmutil.py @ 29417:526b027b0130
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.
author | Gregory Szorc <gregory.szorc@gmail.com> |
---|---|
date | Sat, 25 Jun 2016 19:12:20 -0700 |
parents | 98e8313dcd9e |
children | 69109052d9ac |
line wrap: on
line diff
--- a/mercurial/scmutil.py Sat Jun 25 13:52:46 2016 -0700 +++ b/mercurial/scmutil.py Sat Jun 25 19:12:20 2016 -0700 @@ -808,10 +808,29 @@ 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)