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.

29416:30789efb1e5e

    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."""
    allspecs = []
    for spec in revs:
        if isinstance(spec, int):
            spec = revset.formatspec('rev(%d)', spec)
        allspecs.append(spec)
    m = revset.matchany(repo.ui, allspecs, repo)
    return m(repo)

29417:526b027b0130

    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, 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 specs:
        if isinstance(spec, int):
            spec = revset.formatspec('rev(%d)', spec)
        allspecs.append(spec)
    m = revset.matchany(repo.ui, allspecs, repo)
    return m(repo)