Description
===========

bzr_hookless_email.py sends commit messages for Bazaar branches to a
given address. Instead of relying on each commiter installing a hook in
their branch, like with the bzr-email plugin, the program is run in the
machine that hosts the branch, so every commit will trigger an email
being sent.

The program can work in two modes:

    * daemon mode: the program stays alive, and branches are watched with
      inotify for new commits. This means that messages are sent immediately
      after commits are pushed to the branch. (This mode is entered if
      the -d/--daemon option is passed.)

    * normal mode: the program starts, looks if there are any new
      commits since the last time it run, and sends those mails. This is
      meant to be run periodically, eg. from cron.

To keep track of the last revision that was mailed, an option in
.bzr/branch/branch.conf is used. On the first run, that is, when that
option is not present, it is set to the last available revision, and no
mail is sent at all. If you need to play with it, the current name of
the variable is 'last_revision_mailed', and its value should be a single
revision id.


Motivation
==========

For some loosely coordinated projects (Debian packaging teams in
particular), it is useful to receive mail with the changes others do, in
orther to keep track of what's being done, and possibly review the
changes.

Subversion and CVS make it easier to have those mails sent automatically
on commit, but with distributed VCS that is not possible.

After migrating some Debian packaging projects from Subversion to
Bazaar, the author (and other developers) sorely missed those commits
mails, thus decided to create this tool.


Usage
=====

The program expects to receive a list of branches from the command line,
the ones to watch; and an email address to send the messages to, given
with the -e/--email option.

If you have a handful of branches under some directory, you can use the
-r/--recurse option instead of having to lists all individual branches.

To limit the max size of the diffs sent, use the -l/--line-limit option,
or set it to 0 to disable attaching of diffs (only the logs will be
sent.)

As mentioned above, -d/--daemon makes the program enter daemon mode.


Requirements
============

The program is written in Python, version 2.4 or later is required. A
Bazaar instalation must be available as well in the standard Python
directories, or $PYTHONPATH; the program is known to work with 0.16 or
later (no claims about previous versions, reports welcome).

In daemon mode, inotify is used to watch the branches for commits, via
the pyinotify bindings [1]. On Debian and Ubuntu systems, these are
available in the python-pyinotify package; both version 0.5 (etch,
feisty) and 0.7 (lenny, gutsy) are supported.

    [1] http://pyinotify.sourceforge.net


Alioth projects
===============

For Alioth projects wanting to use this program, there is a small
convenience script, alioth_helper.sh, which chdir's to the appropriate
directory, and runs the program from there. Also, I keep a checkout of
the program on my home directory, so you probably just need to run:

    % /var/lib/gforge/chroot/home/users/adeodato/bzr-hookless-email/alioth_helper.sh $PROJECT_NAME -d

This assumes that the address to send mails is:

    $PROJECT_NAME-commits@lists.alioth.debian.org


Reporting bugs
==============

To report a bug in the program, please use the Launchpad interface at:

    https://launchpad.net/bzr-hookless-email/+filebug

If you'd rather not create an account to report a bug, direct email to
the author will be also accepted.

If the program dies with a Python traceback, please include it in your
bug report. If the program dies while in daemon mode, there should be a
traceback in the ~/.bzr_hookless_email.traceback file.


Known bugs
==========

The program doesn't like to watch empty branches.


Author and license
==================

Adeodato Simó <dato@net.com.org.es>
Licensed under the terms of the MIT license.