git-multimail is close to, but not exactly, a plug-in replacement for
the old Git project script contrib/hooks/post-receive-email.  This
document describes the differences and explains how to configure
git-multimail to get behavior closest to that of post-receive-email.

If you are in a hurry
=====================

A script called migrate-mailhook-config is included with
git-multimail.  If you run this script within a Git repository that is
configured to use post-receive-email, it will convert the
configuration settings into the approximate equivalent settings for
git-multimail.  For more information, run

    migrate-mailhook-config --help


Configuration differences
=========================

* The names of the config options for git-multimail are in namespace
  "multimailhook.*" instead of "hooks.*".  (Editorial comment:
  post-receive-email should never have used such a generic top-level
  namespace.)

* In emails about new annotated tags, post-receive-email includes a
  shortlog of all changes since the previous annotated tag.  To get
  this behavior with git-multimail, you need to set
  multimailhook.announceshortlog to true:

      git config multimailhook.announceshortlog true

* multimailhook.commitlist -- This is a new configuration variable.
  Recipients listed here will receive a separate email for each new
  commit.  However, if this variable is *not* set, it defaults to the
  value of multimailhook.mailinglist.  Therefore, if you *don't* want
  the members of multimailhook.mailinglist to receive one email per
  commit, then set this value to the empty string:

      git config multimailhook.commitlist ''

* multimailhook.emailprefix -- If this value is not set, then the
  subjects of generated emails are prefixed with the short name of the
  repository enclosed in square brackets; e.g., "[myrepo]".
  post-receive-email defaults to prefix "[SCM]" if this option is not
  set.  So if you were using the old default and want to retain it
  (for example, to avoid having to change your email filters), set
  this variable explicitly to the old value:

      git config multimailhook.emailprefix "[SCM]"

* The "multimailhook.showrev" configuration option is not supported.
  Its main use is obsoleted by the one-email-per-commit feature of
  git-multimail.


Other differences
=================

This section describes other differences in the behavior of
git-multimail vs. post-receive-email.  For full details, please refer
to the main README file:

* One email per commit.  For each reference change, the script first
  outputs one email summarizing the reference change (including
  one-line summaries of the new commits), then it outputs a separate
  email for each new commit that was introduced, including patches.
  These one-email-per-commit emails go to the addresses listed in
  multimailhook.commitlist.  post-receive-email sends only one email
  for each *reference* that is changed, no matter how many commits
  were added to the reference.

* Better algorithm for detecting new commits.  post-receive-email
  processes one reference change at a time, which causes it to fail to
  describe new commits that were included in multiple branches.  For
  example, if a single push adds the "*" commits in the diagram below,
  then post-receive-email would never include the details of the two
  commits that are common to "master" and "branch" in its
  notifications.

      o---o---o---*---*---*    <-- master
                       \
                        *---*  <-- branch

  git-multimail analyzes all reference modifications to determine
  which commits were not present before the change, therefore avoiding
  that error.

* In reference change emails, git-multimail tells which commits have
  been added to the reference vs. are entirely new to the repository,
  and which commits that have been omitted from the reference
  vs. entirely discarded from the repository.

* The environment in which Git is running can be configured via an
  "Environment" abstraction.

* Built-in support for Gitolite-managed repositories.

* Instead of using full SHA1 object names in emails, git-multimail
  mostly uses abbreviated SHA1s, plus one-line log message summaries
  where appropriate.

* In the schematic diagrams that explain non-fast-forward commits,
  git-multimail shows the names of the branches involved.

* The emails generated by git-multimail include the name of the Git
  repository that was modified; this is convenient for recipients who
  are monitoring multiple repositories.

* git-multimail allows the email "From" addresses to be configured.

* The recipients lists (multimailhook.mailinglist,
  multimailhook.refchangelist, multimailhook.announcelist, and
  multimailhook.commitlist) can be comma-separated values and/or
  multivalued settings in the config file; e.g.,

      [multimailhook]
              mailinglist = mr.brown@example.com, mr.black@example.com
              announcelist = Him <him@example.com>
              announcelist = Jim <jim@example.com>
              announcelist = pop@example.com

  This might make it easier to maintain short recipients lists without
  requiring full-fledged mailing list software.

* By default, git-multimail sets email "Reply-To" headers to reply to
  the pusher (for reference updates) and to the author (for commit
  notifications).  By default, the pusher's email address is
  constructed by appending "multimailhook.emaildomain" to the pusher's
  username.

* The generated emails contain a configurable footer.  By default, it
  lists the name of the administrator who should be contacted to
  unsubscribe from notification emails.

* New option multimailhook.emailmaxlinelength to limit the length of
  lines in the main part of the email body.  The default limit is 500
  characters.

* New option multimailhook.emailstrictutf8 to ensure that the main
  part of the email body is valid UTF-8.  Invalid characters are
  turned into the Unicode replacement character, U+FFFD.  By default
  this option is turned on.

* Written in Python.  Easier to add new features.