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.
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.)
17
.. _push-and-update plugin: http://doc.bazaar.canonical.com/plugins/en/push-and-update-plugin.html
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
26
from bzrlib import branch
29
def post_push_hook(push_result):
30
print "The new revno is %d" % push_result.new_revno
33
branch.Branch.hooks.install_named_hook('post_push', post_push_hook,
36
.. _write a plugin: http://doc.bazaar.canonical.com/plugins/en/plugin-development.html
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).
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.
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
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.
60
To get a list of installed hooks (and available hook points), use the hidden
66
Example: a merge plugin
67
-----------------------
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.
75
"""Custom 'merge' logic for *.xml files.
77
Always conflicts if both branches have changed the file.
80
from bzrlib.merge import AbstractPerFileMerger, Merger
82
def merge_xml_files_hook(merger):
83
"""Hook to merge *.xml files"""
84
return MergeXMLFiles(merger)
86
class MergeXMLFiles(AbstractPerFileMerger):
88
def filename_matches(self, params):
89
inventory = self.merger.this_tree.inventory
90
filename = inventory[params.file_id].name
91
if filename.endswith('.xml'):
94
def merge_contents(self, params):
95
"""Merge the contents of a single file."""
96
# First, check whether this custom merge logic should be used. We
97
# expect most files should not be merged by this handler.
99
# OTHER is a straight winner, rely on default merge.
100
params.winner == 'other' or
101
# THIS and OTHER aren't both files.
102
not params.is_file_merge() or
103
# The filename doesn't match *.xml
104
not self.filename_matches(params)):
105
return 'not_applicable', None
106
return 'conflicted', params.this_lines
108
Merger.hooks.install_named_hook(
109
'merge_file_content', merge_xml_files_hook, '*.xml file merge')
111
``merge_file_content`` hooks are executed for each file to be merged. For
112
a more a complex example look at the ``news_merge`` plugin that's bundled with
113
Bazaar in the ``bzrlib/plugins`` directory.