contrib/hooks/multimail/README.migrate-from-post-receive-email

   1 git-multimail is close to, but not exactly, a plug-in replacement for
   2 the old Git project script contrib/hooks/post-receive-email.  This
   3 document describes the differences and explains how to configure
   4 git-multimail to get behavior closest to that of post-receive-email.
   5
   6 If you are in a hurry
   7 =====================
   8
   9 A script called migrate-mailhook-config is included with
  10 git-multimail.  If you run this script within a Git repository that is
  11 configured to use post-receive-email, it will convert the
  12 configuration settings into the approximate equivalent settings for
  13 git-multimail.  For more information, run
  14
  15     migrate-mailhook-config --help
  16
  17
  18 Configuration differences
  19 =========================
  20
  21 * The names of the config options for git-multimail are in namespace
  22   "multimailhook.*" instead of "hooks.*".  (Editorial comment:
  23   post-receive-email should never have used such a generic top-level
  24   namespace.)
  25
  26 * In emails about new annotated tags, post-receive-email includes a
  27   shortlog of all changes since the previous annotated tag.  To get
  28   this behavior with git-multimail, you need to set
  29   multimailhook.announceshortlog to true:
  30
  31       git config multimailhook.announceshortlog true
  32
  33 * multimailhook.commitlist -- This is a new configuration variable.
  34   Recipients listed here will receive a separate email for each new
  35   commit.  However, if this variable is *not* set, it defaults to the
  36   value of multimailhook.mailinglist.  Therefore, if you *don't* want
  37   the members of multimailhook.mailinglist to receive one email per
  38   commit, then set this value to the empty string:
  39
  40       git config multimailhook.commitlist ''
  41
  42 * multimailhook.emailprefix -- If this value is not set, then the
  43   subjects of generated emails are prefixed with the short name of the
  44   repository enclosed in square brackets; e.g., "[myrepo]".
  45   post-receive-email defaults to prefix "[SCM]" if this option is not
  46   set.  So if you were using the old default and want to retain it
  47   (for example, to avoid having to change your email filters), set
  48   this variable explicitly to the old value:
  49
  50       git config multimailhook.emailprefix "[SCM]"
  51
  52 * The "multimailhook.showrev" configuration option is not supported.
  53   Its main use is obsoleted by the one-email-per-commit feature of
  54   git-multimail.
  55
  56
  57 Other differences
  58 =================
  59
  60 This section describes other differences in the behavior of
  61 git-multimail vs. post-receive-email.  For full details, please refer
  62 to the main README file:
  63
  64 * One email per commit.  For each reference change, the script first
  65   outputs one email summarizing the reference change (including
  66   one-line summaries of the new commits), then it outputs a separate
  67   email for each new commit that was introduced, including patches.
  68   These one-email-per-commit emails go to the addresses listed in
  69   multimailhook.commitlist.  post-receive-email sends only one email
  70   for each *reference* that is changed, no matter how many commits
  71   were added to the reference.
  72
  73 * Better algorithm for detecting new commits.  post-receive-email
  74   processes one reference change at a time, which causes it to fail to
  75   describe new commits that were included in multiple branches.  For
  76   example, if a single push adds the "*" commits in the diagram below,
  77   then post-receive-email would never include the details of the two
  78   commits that are common to "master" and "branch" in its
  79   notifications.
  80
  81       o---o---o---*---*---*    <-- master
  82                        \
  83                         *---*  <-- branch
  84
  85   git-multimail analyzes all reference modifications to determine
  86   which commits were not present before the change, therefore avoiding
  87   that error.
  88
  89 * In reference change emails, git-multimail tells which commits have
  90   been added to the reference vs. are entirely new to the repository,
  91   and which commits that have been omitted from the reference
  92   vs. entirely discarded from the repository.
  93
  94 * The environment in which Git is running can be configured via an
  95   "Environment" abstraction.
  96
  97 * Built-in support for Gitolite-managed repositories.
  98
  99 * Instead of using full SHA1 object names in emails, git-multimail
 100   mostly uses abbreviated SHA1s, plus one-line log message summaries
 101   where appropriate.
 102
 103 * In the schematic diagrams that explain non-fast-forward commits,
 104   git-multimail shows the names of the branches involved.
 105
 106 * The emails generated by git-multimail include the name of the Git
 107   repository that was modified; this is convenient for recipients who
 108   are monitoring multiple repositories.
 109
 110 * git-multimail allows the email "From" addresses to be configured.
 111
 112 * The recipients lists (multimailhook.mailinglist,
 113   multimailhook.refchangelist, multimailhook.announcelist, and
 114   multimailhook.commitlist) can be comma-separated values and/or
 115   multivalued settings in the config file; e.g.,
 116
 117       [multimailhook]
 118               mailinglist = mr.brown@example.com, mr.black@example.com
 119               announcelist = Him <him@example.com>
 120               announcelist = Jim <jim@example.com>
 121               announcelist = pop@example.com
 122
 123   This might make it easier to maintain short recipients lists without
 124   requiring full-fledged mailing list software.
 125
 126 * By default, git-multimail sets email "Reply-To" headers to reply to
 127   the pusher (for reference updates) and to the author (for commit
 128   notifications).  By default, the pusher's email address is
 129   constructed by appending "multimailhook.emaildomain" to the pusher's
 130   username.
 131
 132 * The generated emails contain a configurable footer.  By default, it
 133   lists the name of the administrator who should be contacted to
 134   unsubscribe from notification emails.
 135
 136 * New option multimailhook.emailmaxlinelength to limit the length of
 137   lines in the main part of the email body.  The default limit is 500
 138   characters.
 139
 140 * New option multimailhook.emailstrictutf8 to ensure that the main
 141   part of the email body is valid UTF-8.  Invalid characters are
 142   turned into the Unicode replacement character, U+FFFD.  By default
 143   this option is turned on.
 144
 145 * Written in Python.  Easier to add new features.