← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/en/user-guide/hooks.txt

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2009-10-21 16:30:17 UTC
  • mfrom: (4759.2.12 2.1-st-concat)
  • Revision ID: pqm@pqm.ubuntu.com-20091021163017-itbys2a178vt5605
(jam, andrew) Allow StaticTuple to hold more types,
        and implement the + operator.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/user-guide/hooks.txt
 
1
Using hooks
 
2
===========
 
3
 
 
4
What is a hook?
 
5
---------------
 
6
 
 
7
One way to customize Bazaar's behaviour is with *hooks*.  Hooks allow you to
 
8
perform actions before or after certain Bazaar operations.  The operations
 
9
include ``commit``, ``push``, ``pull``, and ``uncommit``.
 
10
For a complete list of hooks and their parameters, see `Hooks
 
11
<../user-reference/bzr_man.html#hooks>`_ in the User Reference.
 
12
 
 
13
Most hooks are run on the client, but a few are run on the server.  (Also
 
14
see the `bzr-push-and-update`_ plugin that handles one special case of
 
15
server-side operations.)
 
16
 
 
17
.. _bzr-push-and-update: https://launchpad.net/bzr-push-and-update/
 
18
 
 
19
Using hooks
 
20
-----------
 
21
 
 
22
To use a hook, you should `write a plugin <#writing-a-plugin>`_.  Instead of
 
23
creating a new command, this plugin will define and install the hook.  Here's
 
24
an example::
 
25
 
 
26
    from bzrlib import branch
 
27
 
 
28
 
 
29
    def post_push_hook(push_result):
 
30
        print "The new revno is %d" % push_result.new_revno
 
31
 
 
32
 
 
33
    branch.Branch.hooks.install_named_hook('post_push', post_push_hook,
 
34
                                     'My post_push hook')
 
35
 
 
36
To use this example, create a file named ``push_hook.py``, and stick it in
 
37
``plugins`` subdirectory of your configuration directory.  (If you have never
 
38
installed any plugins, you may need to create the ``plugins`` directory).
 
39
 
 
40
That's it!  The next time you push, it should show "The new revno is...".
 
41
Of course, hooks can be much more elaborate than this, because you have the
 
42
full power of Python at your disposal.  Now that you know how to use hooks,
 
43
what you do with them is up to you.
 
44
 
 
45
The plugin code does two things.  First, it defines a function that will be
 
46
run after ``push`` completes.  (It could instead use an instance method or
 
47
a callable object.)  All push hooks take a single argument, the
 
48
``push_result``.
 
49
 
 
50
Second, the plugin installs the hook.  The first argument ``'post_push'``
 
51
identifies where to install the hook.  The second argument is the hook
 
52
itself.  The third argument is a name ``'My post_push hook'``, which can be
 
53
used in progress messages and error messages.
 
54
 
 
55
Debugging hooks
 
56
---------------
 
57
 
 
58
To get a list of installed hooks, use the hidden ``hooks`` command::
 
59
 
 
60
    bzr hooks