← 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: mbp at sourcefrog
  • Date: 2005-04-11 02:53:57 UTC
  • Revision ID: mbp@sourcefrog.net-20050411025357-af577721308648ae
- remove profiler temporary file when done

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/user-guide/hooks.txt
1
 
###########
2
 
Using hooks
3
 
###########
4
 
 
5
 
One way to customize Bazaar's behaviour is with *hooks*.  Hooks allow you to
6
 
perform actions before or after certain Bazaar operations.  The operations
7
 
include ``commit``, ``push``, ``pull``, and ``uncommit``.
8
 
 
9
 
Using Hooks
10
 
###########
11
 
To use a hook, you should write a `plugin <plugins.html>`_.  Instead of
12
 
creating a new command, this plugin will define and install the hook.  Here's
13
 
an example::
14
 
 
15
 
    from bzrlib import branch
16
 
 
17
 
 
18
 
    def post_push_hook(push_result):
19
 
        print "The new revno is %d" % push_result.new_revno
20
 
 
21
 
 
22
 
    branch.Branch.hooks.install_hook('post_push', post_push_hook)
23
 
    branch.Branch.hooks.name_hook(post_push_hook, 'My post_push hook')
24
 
 
25
 
To use this example, create a file named ``push_hook.py``, and stick it in
26
 
``plugins`` subdirectory of your configuration directory.  (If you have never
27
 
installed any plugins, you may need to create the ``plugins`` directory).
28
 
 
29
 
First, we define a function that will be run after ``push`` completes.  We
30
 
could also use an instance method or a callable object.  All push hooks take a
31
 
single argument, the ``push_result``.
32
 
 
33
 
Next, we install the hook.  ``'post_push'`` identifies where we want to install
34
 
the hook, and the second parameter is the hook itself.
35
 
 
36
 
Finally, we name the hook.  This is optional, but it means the hook name can
37
 
be used in progress messages and error messages.
38
 
 
39
 
That's it!  The next time you push, it should show "The new revno is...".
40
 
Of course, hooks can be much more elaborate than this, because you have the
41
 
full power of Python at your disposal.  Now that you know how to use hooks,
42
 
what you do with them is up to you.
43
 
 
44
 
For a complete list of hooks and their parameters, see the `Hooks Reference
45
 
<../user-reference/hooks.html>`_.