← 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: Ian Clatworthy
  • Date: 2009-12-03 23:21:16 UTC
  • mfrom: (4852.4.1 RCStoVCS)
  • mto: This revision was merged to the branch mainline in revision 4860.
  • Revision ID: ian.clatworthy@canonical.com-20091203232116-f8igfvc6muqrn4yx
Revision Control -> Version Control in docs

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/user-guide/hooks.txt
8
8
perform actions before or after certain Bazaar operations.  The operations
9
9
include ``commit``, ``push``, ``pull``, and ``uncommit``.
10
10
For a complete list of hooks and their parameters, see `Hooks
11
 
<../user-reference/index.html#hooks>`_ in the User Reference.
 
11
<../user-reference/bzr_man.html#hooks>`_ in the User Reference.
12
12
 
13
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
 
14
see the `bzr-push-and-update`_ plugin that handles one special case of
15
15
server-side operations.)
16
16
 
17
 
.. _push-and-update plugin: http://doc.bazaar.canonical.com/plugins/en/push-and-update-plugin.html
 
17
.. _bzr-push-and-update: https://launchpad.net/bzr-push-and-update/
18
18
 
19
19
Using hooks
20
20
-----------
21
21
 
22
 
To use a hook, you should `write a plugin`_.  Instead of
 
22
To use a hook, you should `write a plugin <#writing-a-plugin>`_.  Instead of
23
23
creating a new command, this plugin will define and install the hook.  Here's
24
24
an example::
25
25
 
33
33
    branch.Branch.hooks.install_named_hook('post_push', post_push_hook,
34
34
                                     'My post_push hook')
35
35
 
36
 
.. _write a plugin: http://doc.bazaar.canonical.com/plugins/en/plugin-development.html
37
 
 
38
36
To use this example, create a file named ``push_hook.py``, and stick it in
39
37
``plugins`` subdirectory of your configuration directory.  (If you have never
40
38
installed any plugins, you may need to create the ``plugins`` directory).
54
52
itself.  The third argument is a name ``'My post_push hook'``, which can be
55
53
used in progress messages and error messages.
56
54
 
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')
70
 
 
71
55
Debugging hooks
72
56
---------------
73
57
 
74
 
To get a list of installed hooks (and available hook points), use the hidden
75
 
``hooks`` command::
 
58
To get a list of installed hooks, use the hidden ``hooks`` command::
76
59
 
77
60
    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