← 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: 2008-08-14 17:25:43 UTC
  • mfrom: (3620.2.2 rules.disable)
  • Revision ID: pqm@pqm.ubuntu.com-20080814172543-nl22gdcodusa8rt0
(robertc) Disable .bzrrules from being read from the WT

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/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
10
 
19
11
Using hooks
20
12
-----------
21
13
 
22
 
To use a hook, you should `write a plugin`_.  Instead of
 
14
To use a hook, you should `write a plugin <#writing-a-plugin>`_.  Instead of
23
15
creating a new command, this plugin will define and install the hook.  Here's
24
16
an example::
25
17
 
33
25
    branch.Branch.hooks.install_named_hook('post_push', post_push_hook,
34
26
                                     'My post_push hook')
35
27
 
36
 
.. _write a plugin: http://doc.bazaar.canonical.com/plugins/en/plugin-development.html
37
 
 
38
28
To use this example, create a file named ``push_hook.py``, and stick it in
39
29
``plugins`` subdirectory of your configuration directory.  (If you have never
40
30
installed any plugins, you may need to create the ``plugins`` directory).
41
31
 
 
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.  We also give the hook a
 
38
name 'My post_push hook', which can be used in progress messages and error
 
39
messages.
 
40
 
42
41
That's it!  The next time you push, it should show "The new revno is...".
43
42
Of course, hooks can be much more elaborate than this, because you have the
44
43
full power of Python at your disposal.  Now that you know how to use hooks,
45
44
what you do with them is up to you.
46
45
 
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``.
 
46
Standard hooks
 
47
--------------
51
48
 
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.
 
49
For a complete list of hooks and their parameters, see `Hooks
 
50
<../user-reference/bzr_man.html#hooks>`_ in the User Reference.
56
51
 
57
52
Debugging hooks
58
53
---------------
59
54
 
60
 
To get a list of installed hooks (and available hook points), use the hidden
61
 
``hooks`` command::
 
55
To get a list of installed hooks, use the hidden ``hooks`` command::
62
56
 
63
57
    bzr hooks
64
 
 
65
 
 
66
 
Example: a merge plugin
67
 
-----------------------
68
 
 
69
 
Here's a complete plugin that demonstrates the ``Merger.merge_file_content``
70
 
hook.  It installs a hook that forces any merge of a file named ``*.xml``
71
 
to be a conflict, even if Bazaar thinks it can merge it cleanly.
72
 
 
73
 
``merge_xml.py``::
74
 
 
75
 
  """Custom 'merge' logic for *.xml files.
76
 
  
77
 
  Always conflicts if both branches have changed the file.
78
 
  """
79
 
  
80
 
  from bzrlib.merge import PerFileMerger, Merger
81
 
  
82
 
  def merge_xml_files_hook(merger):
83
 
      """Hook to merge *.xml files"""
84
 
      return MergeXMLFiles(merger)
85
 
  
86
 
  class AlwaysConflictXMLMerger(PerFileMerger):
87
 
  
88
 
      def file_matches(self, params):
89
 
          filename = self.get_filename(params, self.merger.this_tree)
90
 
          return filename.endswith('.xml')
91
 
  
92
 
      def merge_matching(self, params):
93
 
          return 'conflicted', params.this_lines
94
 
  
95
 
  Merger.hooks.install_named_hook(
96
 
      'merge_file_content', merge_xml_files_hook, '*.xml file merge')
97
 
 
98
 
``merge_file_content`` hooks are executed for each file to be merged.  For
99
 
a more a complex example look at the ``news_merge`` plugin that's bundled with
100
 
Bazaar in the ``bzrlib/plugins`` directory.
101