~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

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

• browse files at revision 5020.1.1
• compare with another revision
• download diff
• download tarball
• view history from revision 5020.1.1

• reverse the comparison (5020.1.1 to 1717)
• stop comparing with revision 1717

Show diffs side-by-side

added

removed

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/hooks-help.html>`_ 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 `push-and-update plugin`_ that handles one special case of

 

15

server-side operations.)

 

16

 

 

17

.. _push-and-update plugin: http://doc.bazaar.canonical.com/plugins/en/push-and-update-plugin.html

 

18

 

 

19

Using hooks

 

20

-----------

 

21

 

 

22

To use a hook, you should `write 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

.. _write a plugin: http://doc.bazaar.canonical.com/plugins/en/plugin-development.html

 

37

 

 

38

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

 

39

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

 

40

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

 

41

 

 

42

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

 

43

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

 

44

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

 

45

what you do with them is up to you.

 

46

 

 

47

The plugin code does two things.  First, it defines a function that will be

 

48

run after ``push`` completes.  (It could instead use an instance method or

 

49

a callable object.)  All push hooks take a single argument, the

 

50

``push_result``.

 

51

 

 

52

Second, the plugin installs the hook.  The first argument ``'post_push'``

 

53

identifies where to install the hook.  The second argument is the hook

 

54

itself.  The third argument is a name ``'My post_push hook'``, which can be

 

55

used in progress messages and error messages.

 

56

 

 

57

Debugging hooks

 

58

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

 

59

 

 

60

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

 

61

 

 

62

    bzr hooks

• Older »

Loggerhead is a web-based interface for Breezy
Version: 2.0.1