view contrib/python-hook-examples.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.

'''
Examples of useful python hooks for Mercurial.
'''
from __future__ import absolute_import
from mercurial import (
    patch,
    util,
)

def diffstat(ui, repo, **kwargs):
    '''Example usage:

    [hooks]
    commit.diffstat = python:/path/to/this/file.py:diffstat
    changegroup.diffstat = python:/path/to/this/file.py:diffstat
    '''
    if kwargs.get('parent2'):
        return
    node = kwargs['node']
    first = repo[node].p1().node()
    if 'url' in kwargs:
        last = repo['tip'].node()
    else:
        last = node
    diff = patch.diff(repo, first, last)
    ui.write(patch.diffstat(util.iterlines(diff)))