145 lines
6 KiB
Text
145 lines
6 KiB
Text
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.
|