1
Extending Bazaar with Hooks and Plugins
2
=======================================
4
Bazaar offers a powerful extension mechanism for adding capabilities. In
5
addition to offering full library API access to all of its structures, which
6
can be useful for outside programs that would like to interact with Bazaar
7
branches, Bazaar can also load *plugins* that perform specific tasks. These
8
specific tasks are specified by *hooks* that run during certain steps of the
9
version control process.
11
For full documentation on the available hooks, see ``bzr help hooks``. Among
12
those, some of the most significant hooks from an administration
13
standpoint are `pre_commit`, `post_commit` and `post_change_branch_tip`.
14
A `pre_commit` hook can inspect a commit before it happens and cancel it if
15
some criteria are not met. This can be useful for enforcing policies about
16
the code, such as line-endings or whitespace conventions. A
17
`post_commit` hook can take actions based on the commit that just happened,
18
such as providing various types of notifications. Finally, a
19
`post_change_branch_tip` hook is a more general form of a `post_commit`
20
hook which is used whenever the tip of a branch changes (which can happen in
21
more ways than just committing). This too can be used for notification
22
purposes, as well as for backups and mirroring.
24
Information on the whole range of Bazaar plugins is available at
25
http://doc.bazaar.canonical.com/plugins/en/. For purposes of installation,
26
plugins are simply python packages. They can be installed alongside Bazaar in
27
the ``bzrlib.plugins`` package using each plugin's ``setup.py``. They can
28
also be installed in the plugin path which is the user's ``~/.bazaar/plugins``
29
directory or can be specified with the ``BZR_PLUGIN_PATH`` environment
30
variable. See ``bzr help configuration`` for more on specifying the location
37
A common need is for every change made on a branch to send an email message to
38
some address, most often a mailing list. These plugins provide that capability
39
in a number of different ways.
41
The `email` plugin sends email from each individual developer's computer. This
42
can be useful for situations that want to track what each individual developer
43
is working on. On the downside, it requires that every developer's branches be
44
configured individually to use the same plugin.
46
The next two plugins `hookless-email` and `email-notifier` address this concern
47
by running on a central server whenever changes happen on centrally stored
53
To configure this plugin, simply install the plugin and configure the
54
``post_commit_to`` option for each branch. This configuration can be done
55
in the ``locations.conf`` file or individually in each branch's
56
``branch.conf`` file. The sender's email address can be specified as
57
``post_commit_sender`` if it is different than the email address reported by
58
``bzr whoami``. The ``post_commit_mailer`` option specifies how the
59
mail should be sent. If it isn't set, email is sent via ``/usr/bin/mail``.
60
It can also be configured to communicate directly with an SMTP server.
61
For more details on configuring this plugin, see
62
http://doc.bazaar.canonical.com/plugins/en/email-plugin.html. As examples,
63
consider the following two possible configurations. A minimal one (uses
69
post_commit_to = projectx-commits@example.com
71
and a more complicated one (using all of the options)
76
post_commit_url = http://www.example.com/code/projectx/trunk
77
post_commit_to = projectx-commits@example.com
78
post_commit_sender = donotreply@example.com
79
post_commit_mailer = smtplib
80
smtp_server = mail.example.com:587
82
# smtp_password = 'not specified, will prompt'
88
This plugin is basically a server-side version of the `email` plugin. It is
89
a program that runs either from the command line or as a daemon that monitors
90
the branches specified on the command line for any changes. When a change
91
occurs to any of the monitored branches, it will send an email to the
92
specified address. Using our simple example, the following command would send
93
an email to ``projectx-commits@example.com`` on any of the branches under
94
``/srv/bzr`` since the last time the command was run. (This command could be
95
set up to run at regular intervals, for example from ``cron``.)
99
$ bzr_hookless_email.py --email=projectx-commits@example.com \
105
This is a more elaborate version of the `hookless-email` plugin that can send
106
templated HTML emails, render wiki-style markup in commit messages and update
107
working copies on the server (similar to `push_and_update`_). It can also
108
send emails reporting the creation of new branches or the removal of branches
109
under a specified directory (here ``/srv/bzr/projectx``). As it is more
110
complicated, its configuration is also more complicated and we won't repeat
111
its documentation here, but a simple configuration that will send emails on
112
commits and creation/deletion of branches is
118
server=smtp.example.com
119
# If user is not provided then no authentication will be performed.
125
# The address to send commit emails to.
126
to=projctx-commits@example.com
127
from=$revision.committer
129
# A Cheetah template used to construct the subject of the email message.
130
subject=$relative_path: $revision_number $summary
133
to=projectx-commits@example.com
134
from=donotreply@example.com
135
subject=$relative_path: New branch created
138
to=projectx-commits@example.com
139
from=donotreply@example.com
140
subject=$relative_path: Branch removed
142
If this file is stored as ``/srv/bzr/email-notifier.conf``, then the command
146
$ bzr-email-notifier.py --config=/srv/bzr/email-notifier.conf /srv/bzr/projectx
148
will watch all branches under the given directory for commits, branch
149
creations and branch deletions.
155
A related concept to sending out emails when branches change is the generation
156
of news feeds from changes on each branch. Interested parties can then choose
157
to follow those news feeds in order to see what is happening on a branch.
162
This plugin creates an ATOM feed for every branch on every branch change
163
(commit, etc.). It stores these files as ``.bzr/branch/branch.atom`` inside
164
each branch. Currently, it includes the 20 most recent changes in each feed.
165
To use it, simply install the plugin and set your feed reader to follow the
166
``branch.atom`` files.
168
In addition, there are other tools that are not plugins for creating news
169
feeds from Bazaar branches. See
170
http://wiki.bazaar.canonical.com/FeedGenerators for more on those tools.
175
Sometimes it is useful to ensure that one branch exists as an exact copy of
176
another. This can be used to provide simple backup facilities or redundancy
177
(see `Back-up and restore <backup.html>`_ for more details on backups). One
178
way to do this using Bazaar's workflows is to make the branch where changes
179
happen into a bound branch of the mirror branch. Then, when commits happen on
180
the working branch, they will also happen on the mirror branch. Note that
181
commits to bound branches do *not* update the mirror branch's working copy, so
182
if the mirror branch is more than just a backup of the complete history of the
183
branch, for example if it is being served as a web page, then additional
184
plugins are necessary.
189
This plugin updates Bazaar's ``push`` command to also update the remote
190
working copy. It can only work over connections that imply filesystem or SSH
191
access to the remote working copy (``bzr+ssh://``, ``sftp://`` and
192
``file://``). Also, it is only useful when the remote branch is updated with
193
an explicit ``push`` command.
198
This plugin is similar to `push_and_update` in that it updates the working
199
copy of a remote branch. The difference is that this plugin is designed to
200
update the remote branch on every change to the working branch. To configure
201
this, set the ``post_commit_mirror = URL`` option on a branch. This option
202
can include multiple branch URLs separated by commas to create multiple
203
mirrors. For example, if we want to mirror our ``/srv/bzr/projectx/trunk``
204
branch to the URL ``sftp://www.example.com/var/www/projectx`` (for example if
205
ProjectX were a web project that we wanted to access at
206
``http://www.example.com/projectx``), then we could include
211
post_commit_mirror = sftp://www.example.com/var/www/branches/trunk
213
in the file ``/srv/bzr/projectx/trunk/.bzr/branch/branch.conf``.
222
Facilitating interaction with `PQM
223
<integration.html#patch-queue-manager-pqm>`_, this plugin provides support for
224
submitting merge requests to a remote Patch Queue Manager. PQM provides
225
a way to automatically run the test suite before merging changes to the
231
Sometimes referred to as the poor man's PQM, this plugin runs a single command
232
on the updated revision (in a temporary directory) and if the command returns
233
0, then the revision can be committed to that branch. For example, if the
234
testsuite is run with the command ``nosetests`` in the root of the branch
235
(which returns 0 if the test suite passes and 1 if it doesn't pass), then one
241
pre_change_branch_tip_test_command = nosetests
243
in ``.bzr/branch/branch.conf``.
248
This plugin is an example of a `pre_commit` hook that checks the revision
249
being committed for meeting some policy. In this case, it checks that all of
250
the files have the specified line endings. It uses a configuration file
251
``.bzreol`` in the root of the working tree (similar to the ``.bzrignore``
252
file). This configuration file has sections for line feed endings (LF),
253
carriage return/line-feed endings (CRLF) and carriage return endings (CR).
254
For an unusual example that specifies different line endings for different
255
files, that file might look like
270
or if you simply want to enforce a single line ending convention on the branch
278
This plugin needs to be installed on the server where the branch updates will
279
happen, and the ``.bzreol`` file must be in each branch where line ending
280
policies will be enforced. (Adding it to the branch with ``bzr add .bzreol``
281
is an easy way to ensure this, although it means that branches on the server
282
must have working trees.)
287
This plugin is a more advanced version of `checkeol` that can check such
288
coding style guidelines such as trailing whitespace, long lines and files that
289
don't end with a newline. It is configured using Bazaar's built in rules
290
specification in ``BZR_HOME/rules`` (see ``bzr help rules`` for more
291
information. For different types of undesired changes, you can specify
292
different types of actions. For example
297
trailing_whitespace=fail
299
newline_at_eof=ignore
305
trailing_whitespace=fail
307
will prevent changes from adding new trailing whitespace to the specified
308
files and keep all python source files free of tabs and lines over 78
309
characters. To commit while violating these rules, one can pass the
310
``--text-check-warn-only`` option to commit.
added
removed
doc/en/admin-guide/hooks-plugins.txt
