Mercurial > hg-stable
comparison 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 |
comparison
equal
deleted
inserted
replaced
29416:30789efb1e5e | 29417:526b027b0130 |
---|---|
806 if first == second and len(revs) == 1 and not _pairspec(revs[0]): | 806 if first == second and len(revs) == 1 and not _pairspec(revs[0]): |
807 return repo.lookup(first), None | 807 return repo.lookup(first), None |
808 | 808 |
809 return repo.lookup(first), repo.lookup(second) | 809 return repo.lookup(first), repo.lookup(second) |
810 | 810 |
811 def revrange(repo, revs): | 811 def revrange(repo, specs): |
812 """Yield revision as strings from a list of revision specifications.""" | 812 """Execute 1 to many revsets and return the union. |
813 | |
814 This is the preferred mechanism for executing revsets using user-specified | |
815 config options, such as revset aliases. | |
816 | |
817 The revsets specified by ``specs`` will be executed via a chained ``OR`` | |
818 expression. If ``specs`` is empty, an empty result is returned. | |
819 | |
820 ``specs`` can contain integers, in which case they are assumed to be | |
821 revision numbers. | |
822 | |
823 It is assumed the revsets are already formatted. If you have arguments | |
824 that need to be expanded in the revset, call ``revset.formatspec()`` | |
825 and pass the result as an element of ``specs``. | |
826 | |
827 Specifying a single revset is allowed. | |
828 | |
829 Returns a ``revset.abstractsmartset`` which is a list-like interface over | |
830 integer revisions. | |
831 """ | |
813 allspecs = [] | 832 allspecs = [] |
814 for spec in revs: | 833 for spec in specs: |
815 if isinstance(spec, int): | 834 if isinstance(spec, int): |
816 spec = revset.formatspec('rev(%d)', spec) | 835 spec = revset.formatspec('rev(%d)', spec) |
817 allspecs.append(spec) | 836 allspecs.append(spec) |
818 m = revset.matchany(repo.ui, allspecs, repo) | 837 m = revset.matchany(repo.ui, allspecs, repo) |
819 return m(repo) | 838 return m(repo) |