~bzr-pqm/bzr/bzr.dev : revision 4893

1

Extending Bazaar with Hooks and Plugins

2

=======================================

3

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.

10

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.

23

24

Information on the whole range of Bazaar plugins is available at

25

http://doc.bazaar-vcs.org/en/plugin-guide. 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

31

of plugins.

32

33

4

34

Email Notification

5

35

------------------

6

36

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.

40

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.

45

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

48

branches.

49

50

email

51

~~~~~

52

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-vcs.org/plugins/en/email-plugin.html. As examples, consider

63

the following two possible configurations. A minimal one (uses

64

``/usr/bin/mail``)

65

66

::

67

68

[DEFAULT]

69

post_commit_to = projectx-commits@example.com

70

71

and a more complicated one (using all of the options)

72

73

::

74

75

[DEFAULT]

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

81

smtp_username = bob

82

# smtp_password = 'not specified, will prompt'

83

84

85

hookless-email

86

~~~~~~~~~~~~~~

87

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``.)

96

97

::

98

99

$ bzr_hookless_email.py --email=projectx-commits@example.com \

100

--recurse /srv/bzr

101

102

email-notifier

103

~~~~~~~~~~~~~~

104

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

113

114

::

115

116

[smtp]

117

118

server=smtp.example.com

119

# If user is not provided then no authentication will be performed.

120

user=bob

121

password=pAssW0rd

122

123

[commits]

124

125

# The address to send commit emails to.

126

to=projctx-commits@example.com

127

from=$revision.committer

128

129

# A Cheetah template used to construct the subject of the email message.

130

subject=$relative_path: $revision_number $summary

131

132

[new-branches]

133

to=projectx-commits@example.com

134

from=donotreply@example.com

135

subject=$relative_path: New branch created

136

137

[removed-branches]

138

to=projectx-commits@example.com

139

from=donotreply@example.com

140

subject=$relative_path: Branch removed

141

142

If this file is stored as ``/srv/bzr/email-notifier.conf``, then the command

143

144

::

145

146

$ bzr-email-notifier.py --config=/srv/bzr/email-notifier.conf /srv/bzr/projectx

147

148

will watch all branches under the given directory for commits, branch

149

creations and branch deletions.

150

151

7

152

Feed Generation

8

153

---------------

9

154

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.

158

159

branchfeed

160

~~~~~~~~~~

161

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.

167

168

In addition, there are other tools that are not plugins for creating news

169

feeds from Bazaar branches. See http://bazaar-vcs.org/FeedGenerators for more

170

on those tools.

171

10

172

Mirroring

11

173

---------

12

174

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.

185

186

push_and_update

187

~~~~~~~~~~~~~~~

188

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.

194

195

automirror

196

~~~~~~~~~~

197

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

207

208

::

209

210

[DEFAULT]

211

post_commit_mirror = sftp://www.example.com/var/www/branches/trunk

212

213

in the file ``/srv/bzr/projectx/trunk/.bzr/branch/branch.conf``.

214

215

13

216

Other Useful Plugins

14

217

--------------------

218

219

pqm (plugin)

220

~~~~~~~~~~~~

221

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

226

trunk branch.

227

228

testrunner

229

~~~~~~~~~~

230

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

236

can set

237

238

::

239

240

[DEFAULT]

241

pre_change_branch_tip_test_command = nosetests

242

243

in ``.bzr/branch/branch.conf``.

244

245

checkeol

246

~~~~~~~~

247

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

256

257

::

258

259

[LF]

260

*.py

261

*.[ch]

262

263

[CRLF]

264

*.txt

265

*.ini

266

267

[CR]

268

foo.mac

269

270

or if you simply want to enforce a single line ending convention on the branch

271

you can use

272

273

::

274

275

[LF]

276

*

277

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.)

283

284

text_checker

285

~~~~~~~~~~~~

286

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

293

294

::

295

296

[name NEWS README]

297

trailing_whitespace=fail

298

long_lines=warn

299

newline_at_eof=ignore

300

301

[name *.py]

302

tabs=fail

303

long_line_length=78

304

long_lines=fail

305

trailing_whitespace=fail

306

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.