~bzr-pqm/bzr/bzr.dev

Using hooks

===========

What is a hook?

---------------

One way to customize Bazaar's behaviour is with *hooks*.  Hooks allow you to

perform actions before or after certain Bazaar operations.  The operations

include ``commit``, ``push``, ``pull``, and ``uncommit``.

Using hooks

-----------

To use a hook, you should `write a plugin <#writing-a-plugin>`_.  Instead of

creating a new command, this plugin will define and install the hook.  Here's

an example::

    from bzrlib import branch

    def post_push_hook(push_result):

        print "The new revno is %d" % push_result.new_revno

    branch.Branch.hooks.install_named_hook('post_push', post_push_hook,

                                     'My post_push hook')

To use this example, create a file named ``push_hook.py``, and stick it in

``plugins`` subdirectory of your configuration directory.  (If you have never

installed any plugins, you may need to create the ``plugins`` directory).

First, we define a function that will be run after ``push`` completes.  We

could also use an instance method or a callable object.  All push hooks take a

single argument, the ``push_result``.

Next, we install the hook.  ``'post_push'`` identifies where we want to install

the hook, and the second parameter is the hook itself.  We also give the hook a

name 'My post_push hook', which can be used in progress messages and error

messages.

That's it!  The next time you push, it should show "The new revno is...".

Of course, hooks can be much more elaborate than this, because you have the

full power of Python at your disposal.  Now that you know how to use hooks,

what you do with them is up to you.

Standard hooks

--------------

For a complete list of hooks and their parameters, see `Hooks

<../user-reference/bzr_man.html#hooks>`_ in the User Reference.

Debugging hooks

---------------

To get a list of installed hooks, use the hidden ``hooks`` command::

    bzr hooks