← 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

(jelmer) Support upgrading between the 2a and development-colo formats.
 (Jelmer Vernooij)

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/user-guide/hooks.txt
7
7
One way to customize Bazaar's behaviour is with *hooks*.  Hooks allow you to
8
8
perform actions before or after certain Bazaar operations.  The operations
9
9
include ``commit``, ``push``, ``pull``, and ``uncommit``.
 
10
For a complete list of hooks and their parameters, see `Hooks
 
11
<../user-reference/index.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 `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
10
18
 
11
19
Using hooks
12
20
-----------
13
21
 
14
 
To use a hook, you should `write a plugin <#writing-a-plugin>`_.  Instead of
 
22
To use a hook, you should `write a plugin`_.  Instead of
15
23
creating a new command, this plugin will define and install the hook.  Here's
16
24
an example::
17
25
 
22
30
        print "The new revno is %d" % push_result.new_revno
23
31
 
24
32
 
25
 
    branch.Branch.hooks.install_hook('post_push', post_push_hook)
26
 
    branch.Branch.hooks.name_hook(post_push_hook, 'My post_push hook')
 
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
27
37
 
28
38
To use this example, create a file named ``push_hook.py``, and stick it in
29
39
``plugins`` subdirectory of your configuration directory.  (If you have never
30
40
installed any plugins, you may need to create the ``plugins`` directory).
31
41
 
32
 
First, we define a function that will be run after ``push`` completes.  We
33
 
could also use an instance method or a callable object.  All push hooks take a
34
 
single argument, the ``push_result``.
35
 
 
36
 
Next, we install the hook.  ``'post_push'`` identifies where we want to install
37
 
the hook, and the second parameter is the hook itself.
38
 
 
39
 
Finally, we name the hook.  This is optional, but it means the hook name can
40
 
be used in progress messages and error messages.
41
 
 
42
42
That's it!  The next time you push, it should show "The new revno is...".
43
43
Of course, hooks can be much more elaborate than this, because you have the
44
44
full power of Python at your disposal.  Now that you know how to use hooks,
45
45
what you do with them is up to you.
46
46
 
47
 
Standard hooks
48
 
--------------
49
 
 
50
 
For a complete list of hooks and their parameters, see `Hooks
51
 
<../user-reference/bzr_man.html#hooks>`_ in the User Reference.
 
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
To reduce the start-up time of Bazaar it is also possible to "lazily" install hooks,
 
58
using the ``bzrlib.hooks.install_lazy_named_hook`` function. This removes the need
 
59
to load the module that contains the hook point just to install the hook. Here's lazy
 
60
version of the example above::
 
61
 
 
62
    from bzrlib import hooks
 
63
 
 
64
    def post_push_hook(push_result):
 
65
        print "The new revno is %d" % push_result.new_revno
 
66
 
 
67
 
 
68
    hooks.install_lazy_named_hook('bzrlib.branch', 'Branch.hooks',
 
69
        'post_push', post_push_hook, 'My post_push hook')
52
70
 
53
71
Debugging hooks
54
72
---------------
55
73
 
56
 
To get a list of installed hooks, use the hidden ``hooks`` command::
 
74
To get a list of installed hooks (and available hook points), use the hidden
 
75
``hooks`` command::
57
76
 
58
77
    bzr hooks
 
78
 
 
79
 
 
80
Example: a merge plugin
 
81
-----------------------
 
82
 
 
83
Here's a complete plugin that demonstrates the ``Merger.merge_file_content``
 
84
hook.  It installs a hook that forces any merge of a file named ``*.xml``
 
85
to be a conflict, even if Bazaar thinks it can merge it cleanly.
 
86
 
 
87
``merge_xml.py``::
 
88
 
 
89
  """Custom 'merge' logic for *.xml files.
 
90
  
 
91
  Always conflicts if both branches have changed the file.
 
92
  """
 
93
  
 
94
  from bzrlib.merge import PerFileMerger, Merger
 
95
  
 
96
  def merge_xml_files_hook(merger):
 
97
      """Hook to merge *.xml files"""
 
98
      return AlwaysConflictXMLMerger(merger)
 
99
  
 
100
  class AlwaysConflictXMLMerger(PerFileMerger):
 
101
  
 
102
      def file_matches(self, params):
 
103
          filename = self.get_filename(params, self.merger.this_tree)
 
104
          return filename.endswith('.xml')
 
105
  
 
106
      def merge_matching(self, params):
 
107
          return 'conflicted', params.this_lines
 
108
  
 
109
  Merger.hooks.install_named_hook(
 
110
      'merge_file_content', merge_xml_files_hook, '*.xml file merge')
 
111
 
 
112
``merge_file_content`` hooks are executed for each file to be merged.  For
 
113
a more a complex example look at the ``news_merge`` plugin that's bundled with
 
114
Bazaar in the ``bzrlib/plugins`` directory.
 
115