git-multimail: an improved replacement for post-receive-email

Add git-multimail, a tool for generating notification emails for
pushes to a Git repository.  It is largely plug-in compatible with
post-receive-email, and is proposed to eventually replace that script.
The advantages of git-multimail relative to post-receive-email are
described in README.migrate-from-post-receive-email.

git-multimail is organized in a directory contrib/hooks/multimail.
The directory contains:

* git_multimail.py -- a Python module that can generate notification
  emails for pushes to a Git repository.  The file can be used
  directly as a post-receive script (configured via git config
  settings), or it can be imported as a Python module and configured
  via arbitrary Python code.

* README -- user-level documentation for configuring and using
  git-multimail.

* post-receive -- an example of building a post-receive script that
  imports git_multimail.py as a Python module, with an example of how
  to change the email templates.

* README.migrate-from-post-receive-email -- documentation targeted at
  current users of post-receive-email, explaining the differences and
  how to migrate a post-receive-email configuration to git-multimail.

* migrate-mailhook-config -- a script that can migrate a user's
  post-receive-email configuration options to the equivalent
  git-multimail options.

* README.Git -- a short explanation of the relationship between
  git-multimail and the rest of the Git project, plus the exact date
  and revision when this version was taken from the upstream project.

All but the last file are taken verbatim from the upstream
git-multimail project.

git-multimail is originally derived from post-receive-email and also
incorporates suggestions from the mailing list as well as patches by
the people listed below.

Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
Contributions-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Contributions-by: Ramkumar Ramachandra <artagnon@gmail.com>
Contributions-by: Chris Hiestand <chrishiestand@gmail.com>
Contributions-by: Michiel Holtkamp <git@elfstone.nl>
Contributions-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

1 files changed, 90 insertions, 0 deletions

diff --git a/contrib/hooks/multimail/post-receive b/contrib/hooks/multimail/post-receive
new file mode 100755
index 0000000000..93ebb437d1
--- /dev/null
+++ b/contrib/hooks/multimail/post-receive
@@ -0,0 +1,90 @@
+#! /usr/bin/env python2
+
+"""Example post-receive hook based on git-multimail.
+
+This script is a simple example of a post-receive hook implemented
+using git_multimail.py as a Python module.  It is intended to be
+customized before use; see the comments in the script to help you get
+started.
+
+It is possible to use git_multimail.py itself as a post-receive or
+update hook, configured via git config settings and/or command-line
+parameters.  But for more flexibility, it can also be imported as a
+Python module by a custom post-receive script as done here.  The
+latter has the following advantages:
+
+* The tool's behavior can be customized using arbitrary Python code,
+  without having to edit git_multimail.py.
+
+* Configuration settings can be read from other sources; for example,
+  user names and email addresses could be read from LDAP or from a
+  database.  Or the settings can even be hardcoded in the importing
+  Python script, if this is preferred.
+
+This script is a very basic example of how to use git_multimail.py as
+a module.  The comments below explain some of the points at which the
+script's behavior could be changed or customized.
+
+"""
+
+import sys
+import os
+
+# If necessary, add the path to the directory containing
+# git_multimail.py to the Python path as follows.  (This is not
+# necessary if git_multimail.py is in the same directory as this
+# script):
+
+#LIBDIR = 'path/to/directory/containing/module'
+#sys.path.insert(0, LIBDIR)
+
+import git_multimail
+
+
+# It is possible to modify the output templates here; e.g.:
+
+#git_multimail.FOOTER_TEMPLATE = """\
+#
+#-- \n\
+#This email was generated by the wonderful git-multimail tool.
+#"""
+
+
+# Specify which "git config" section contains the configuration for
+# git-multimail:
+config = git_multimail.Config('multimailhook')
+
+
+# Select the type of environment:
+environment = git_multimail.GenericEnvironment(config=config)
+#environment = git_multimail.GitoliteEnvironment(config=config)
+
+
+# Choose the method of sending emails based on the git config:
+mailer = git_multimail.choose_mailer(config, environment)
+
+# Alternatively, you may hardcode the mailer using code like one of
+# the following:
+
+# Use "/usr/sbin/sendmail -t" to send emails.  The envelopesender
+# argument is optional:
+#mailer = git_multimail.SendMailer(
+#    command=['/usr/sbin/sendmail', '-t'],
+#    envelopesender='git-repo@example.com',
+#    )
+
+# Use Python's smtplib to send emails.  Both arguments are required.
+#mailer = git_multimail.SMTPMailer(
+#    envelopesender='git-repo@example.com',
+#    # The smtpserver argument can also include a port number; e.g.,
+#    #     smtpserver='mail.example.com:25'
+#    smtpserver='mail.example.com',
+#    )
+
+# OutputMailer is intended only for testing; it writes the emails to
+# the specified file stream.
+#mailer = git_multimail.OutputMailer(sys.stdout)
+
+
+# Read changes from stdin and send notification emails:
+git_multimail.run_as_post_receive_hook(environment, mailer)