[RFC v2] git-multimail: a replacement for post-receive-email

A while ago, I submitted an RFC for adding a new email notification script to "contrib" [1]. The reaction seemed favorable and it was suggested that the new script should replace post-receive-email rather than be added separately, ideally with some kind of migration support.

I've been working on this on and off since then and I think it is time for another iteration. I think I have addressed most of the points raised earlier, including a migration script and specific migration instructions.

Review of main advantages of git-multimail over post-receive-email:

* Can (optionally) send a separate email for each new commit (in
addition to the emails for each reference change).

* More flexible configuration, including out-of-the-box support for
running under gitolite.

* Fixed algorithm for detecting "new" commits.

* More information in emails (e.g., commit log subject lines, telling
when a push discards old commits)j.

* Written in Python rather than shell.  Easier to extend.

Summary of improvements since the first version:

* Rename the project from the cumbersome "post-receive-multimail.py" to
"git-multimail".

* Push the project into a subdirectory and break it into multiple files
(script, docs, etc).

* Vastly improve the documentation and separate it out of the script
into a README file.

* Add a migration script, migrate-mailhook-config, that converts a
post-receive-email configuration into a git-multimail configuration.
Document the migration procedure and differences between the two scripts
in README.migrate-from-post-receive-email.

* Store the configuration options in namespace "multimailhook.*" rather
than "hooks.*".  (The post-receive-email script's use of a too-generic
top-level name was IMHO a bad idea, so fix it now.)

* Allow the feature of sending a separate email for each individual
commit to be turned off via a configuration option (to better support
post-receive-email migrants).

* Re-implement the feature of showing a short log of commits in
announcement emails, configurable via an option.

* Make it possible to import the main code as a Python module to allow
most customization to be done via Python code without the need to edit
the original file.  (Note for existing users: the Environment API has
changed since the original RFC, but I will try to keep it stable from
now on.)

* Allow the config settings that define recipient lists to be multivalued.

* Added some testing infrastructure (though the tests are still very
limited).

* Add "Auto-Submitted" headers to emails (as implemented for
post-receive-email by Chris Hiestand).

* Add option to truncate email lines to a specified length (suggested by
Matthieu Moy).  By default, this option is *on* and set to 500 characters.

* Add option to force the main part of the email body to be valid UTF-8,
with invalid characters turned into the Unicode replacement character,
U+FFFD.  By default, this option is *on* (arguments for turning it off
by default are welcome).

The code is in its own GitHub repository:

    https://github.com/mhagger/git-multimail

The script should work with any Python 2.x starting with 2.4, though I haven't actually tested older Python versions. It does not yet support Python 3.x.

If it is accepted for the git project, then I would prepare a patch that drops the git-multimail project's "git-multimail" subdirectory into the git project as contrib/hooks/git-multimail and optionally deletes the old post-receive-email script. I am flexible about whether future development should occur directly in the git project's repository or in the git-multimail repo with occasional code drops to the git project. I am also flexible about whether the rough little test scripts should be included in the git project or kept separate.

It would be very helpful if people would test this script in their own environments and give me feedback/bug reports. It is rather awkward to simulate all of the possible environment scenarios myself.

Michael

[1] http://thread.gmane.org/gmane.comp.version-control.git/201433