Hooks provide a great way to customize the behavior of Bazaar. They can be programmed to perform some action before or after certain Bazaar operations.
We will cover the details of hooks in Chapter 10, Programming Bazaar. Here, we only explain how to use a very commonly used hook to send an e-mail report on every commit. Such e-mail reports are very practical in a team, to let all the team members know of the latest changes, and to facilitate the good practice of peer reviews within the team.
In Bazaar, hooks are implemented as plugins. There is a list of defined Bazaar operations named hook points that we can hook into and perform some action. To send e-mails with the summary of changes, we will use the email plugin, triggered by the post_commit hook point.
For configuring and testing the e-mail sending, we just need a very simple repository with a few files for making simple changes and dummy commits. You can create a new repository with bzr init and make some random commits in it, or grab the following sample repository:
$ bzr branch lp:~bzrbook/bzrbook-examples/common-two-features /tmp/emailing Branched 3 revisions.
Depending upon your operating system and mode of installation, the email plugin may already be installed. We can confirm this by looking at the list of plugins:
$ bzr plugins | grep email email Sending emails for commits and branch changes.
If the plugin is not installed, try to get it by using the package manager of your operating system. Alternatively, it is quite easy to install from source:
$ bzr branch lp:bzr-email $ cd bzr-email $ python setup.py install --user
The email plugin is pre-configured to respond to two hook points:
By default, the email plugin doesn't do anything. To enable sending e-mail messages, you must set the configuration post_commit_to to an e-mail address. Although you can add this to your global configuration file ~/.bazaar/bazaar.conf, it probably makes more sense to add it in each branch for which you want to receive e-mail notifications. Let's try this in our sample branch:
$ bzr config [email protected]
Once post_commit_to is set to an e-mail address, all commits will trigger an e-mail report. Let's make some changes and commit:
$ bzr rm hello.py deleted hello.py $ bzr commit -m 'deleted a file' Committing to: /tmp/emailing/ deleted hello.py Committed revision 4.
If you check your e-mails, you should receive an e-mail with the subject as Rev 4: deleted a file in file:///sandbox/emailing/. That is, the subject includes the revision number, the message of the commit, and the URL of the repository. The message body includes more details, such as the summary of changes, and the diffs of content changes in plaintext files.
At file:///sandbox/emailing/ ------------------------------------------------------------ revno: 4 revision-id: [email protected] parent: [email protected] committer: Janos Gyerik <[email protected]> branch nick: emailing timestamp: Wed 2012-11-07 22:34:51 -0800 message: deleted a file === removed file 'hello.py' --- a/hello.py 2012-08-05 09:59:39 +0000 +++ b/hello.py 1970-01-01 00:00:00 +0000 @@ -1,3 +0,0 @@ -#!/usr/bin/env python - -print 'hello world!'
The email plugin can be customized by setting more branch configuration options.
The branch URL used in the subject and message body of the e-mail is the public_branch URL or the path of the branch in the file:/// format. If the branch has a public URL, you should make sure to configure it. For example:
$ bzr config public_branch=https://repos.example.com/project1
By default, the plugin sends e-mails only on commits, not on push and pull operations. To enable e-mails on push and pull too, set the post_commit_push_pull option:
$ bzr config post_commit_push_pull=1
Finally, you may also want to customize the sender address. By default, it is the same as defined with bzr whoami, but you can override it with the post_commit_sender option:
$ bzr config post_commit_sender='Janos <[email protected]>'
If you need even more customization, then you might want to write your own hook. See Chapter 10, Programming Bazaar, for more details.