← 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: Patch Queue Manager
  • Date: 2012-03-28 16:13:49 UTC
  • mfrom: (6499.2.3 948339-config-caching)
  • Revision ID: pqm@pqm.ubuntu.com-20120328161349-2gsc0g11fcu43hlc
(vila) Properly share mutable config sections and save the branch config
 only during the final unlock (Vincent Ladeuil)

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/hooks-help.html>`_ in the User Reference.
 
11
<../user-reference/index.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
14
see the `push-and-update plugin`_ that handles one special case of
54
54
itself.  The third argument is a name ``'My post_push hook'``, which can be
55
55
used in progress messages and error messages.
56
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')
 
70
 
57
71
Debugging hooks
58
72
---------------
59
73
 
60
 
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::
61
76
 
62
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