Send notification emails for Git pushes
git-multimail is a tool for sending notification emails on pushes to a Git repository. It includes a Python module called git_multimail.py, which can either be used as a hook script directly or can be imported as a Python module into another script.
git-multimail is derived from the Git project’s old contrib/hooks/post-receive-email, and is mostly compatible with that script. See README.migrate-from-post-receive-email for details about the differences and for how to migrate from post-receive-email to git-multimail.
git-multimail, like the rest of the Git project, is licensed under GPLv2 (see the COPYING file for details).
Please note: although, as a convenience, git-multimail may be distributed along with the main Git project, development of git-multimail takes place in its own, separate project. See section “Getting involved” below for more information.
By default, for each push received by the repository, git-multimail:
Outputs one email summarizing each reference that was changed. These “reference change” (called “refchange” below) emails describe the nature of the change (e.g., was the reference created, deleted, fast-forwarded, etc.) and include a one-line summary of each commit that was added to the reference.
Outputs one email for each new commit that was introduced by the reference change. These “commit” emails include a list of the files changed by the commit, followed by the diffs of files modified by the commit. The commit emails are threaded to the corresponding reference change email via “In-Reply-To”. This style (similar to the “git format-patch” style used on the Git mailing list) makes it easy to scan through the emails, jump to patches that need further attention, and write comments about specific commits. Commits are handled in reverse topological order (i.e., parents shown before children). For example:
[git] branch master updated + [git] 01/08: doc: fix xref link from api docs to manual pages + [git] 02/08: api-credentials.txt: show the big picture first + [git] 03/08: api-credentials.txt: mention credential.helper explicitly + [git] 04/08: api-credentials.txt: add "see also" section + [git] 05/08: t3510 (cherry-pick-sequence): add missing '&&' + [git] 06/08: Merge branch 'rr/maint-t3510-cascade-fix' + [git] 07/08: Merge branch 'mm/api-credentials-doc' + [git] 08/08: Git 1.7.11-rc2
By default, each commit appears in exactly one commit email, the
first time that it is pushed to the repository. If a commit is later
merged into another branch, then a one-line summary of the commit
is included in the reference change email (as usual), but no
additional commit email is generated. See
below to configure which branches and tags are watched by the hook.
By default, reference change emails have their “Reply-To” field set to the person who pushed the change, and commit emails have their “Reply-To” field set to the author of the commit.
Output one “announce” mail for each new annotated tag, including information about the tag and optionally a shortlog describing the changes since the previous tag. Such emails might be useful if you use annotated tags to mark releases of your project.
git_multimail.py is designed to be used as a post-receive hook in a Git repository (see githooks(5)). Link or copy it to $GIT_DIR/hooks/post-receive within the repository for which email notifications are desired. Usually it should be installed on the central repository for a project, to which all commits are eventually pushed.
For use on pre-v1.5.1 Git servers, git_multimail.py can also work as an update hook, taking its arguments on the command line. To use this script in this manner, link or copy it to $GIT_DIR/hooks/update. Please note that the script is not completely reliable in this mode .
Alternatively, git_multimail.py can be imported as a Python module into your own Python post-receive script. This method is a bit more work, but allows the behavior of the hook to be customized using arbitrary Python code. For example, you can use a custom environment (perhaps inheriting from GenericEnvironment or GitoliteEnvironment) to
Or you can change how emails are sent by writing your own Mailer class. The post-receive script in this directory demonstrates how to use git_multimail.py as a Python module. (If you make interesting changes of this type, please consider sharing them with the community.)
Please read https://github.com/git-multimail/git-multimail/blob/master/doc/troubleshooting.rst for frequently asked questions and common issues with git-multimail.
By default, git-multimail mostly takes its configuration from the following git config settings:
This describes the general environment of the repository. In most
cases, you do not need to specify a value for this variable:
git-multimail will autodetect which environment to use.
Currently supported values:
Environment to use when git-multimail is ran as a gitolite hook.
The username of the pusher is read from $GL_USER, the repository name is read from $GL_REPO, and the From: header value is optionally read from gitolite.conf (see multimailhook.from).
For more information about gitolite and git-multimail, read https://github.com/git-multimail/git-multimail/blob/master/doc/gitolite.rst
Environment to use when git-multimail is ran as an Atlassian BitBucket Server (formerly known as Atlassian Stash) hook.
Warning: this mode was provided by a third-party contributor and never tested by the git-multimail maintainers. It is provided as-is and may or may not work for you.
This value is automatically assumed when the stash-specific flags (--stash-user and --stash-repo) are specified on the command line. When this environment is active, the username and repo come from these two command line flags, which must be specified.
Environment to use when git-multimail is ran as a ref-updated Gerrit hook.
This value is used when the gerrit-specific command line flags (--oldrev, --newrev, --refname, --project) for gerrit’s ref-updated hook are present. When this environment is active, the username of the pusher is taken from the --submitter argument if that command line option is passed, otherwise ‘Gerrit’ is used. The repository name is taken from the --project option on the command line, which must be passed.
For more information about gerrit and git-multimail, read https://github.com/git-multimail/git-multimail/blob/master/doc/gerrit.rst
If none of these environments is suitable for your setup, then you can implement a Python class that inherits from Environment and instantiate it via a script that looks like the example post-receive script.
The environment value can be specified on the command line using the --environment option. If it is not specified on the command line or by multimailhook.environment, the value is guessed as follows:
The format of email messages for the individual commits, can be “text” or “html”. In the latter case, the emails will include diffs using colorized HTML instead of plain text used by default. Note that this currently the ref change emails are always sent in plain text.
Note that when using “html”, the formatting is done by parsing the output of git log with -p. When using multimailhook.commitLogOpts to specify a --format for git log, one may get false positive (e.g. lines in the body of the message starting with +++ or --- colored in red or green).
By default, all the message is HTML-escaped. See multimailhook.htmlInIntro to change this behavior.
Used to generate a link to an online repository browser in commit emails. This variable must be a string. Format directives like %(<variable>)s will be expanded the same way as template strings. In particular, %(id)s will be replaced by the full Git commit identifier (40-chars hexadecimal).
If the string does not contain any format directive, then %(id)s will be automatically added to the string. If you don’t want %(id)s to be automatically added, use the empty format directive %()s anywhere in the string.
For example, a suitable value for the git-multimail project itself would be https://github.com/git-multimail/git-multimail/commit/%(id)s.
When generating an HTML message, git-multimail escapes any HTML sequence by default. This means that if a template contains HTML like <a href="foo">link</a>, the reader will see the HTML source code and not a proper link.
Set multimailhook.htmlInIntro to true to allow writing HTML formatting in introduction templates. Similarly, set multimailhook.htmlInFooter for HTML in the footer.
Variables expanded in the template are still escaped. For example, if a repository’s path contains a <, it will be rendered as such in the message.
Read https://github.com/git-multimail/git-multimail/blob/master/doc/customizing-emails.rst for more details and examples.
If this option is set to true, then summary emails about reference changes will additionally include:
The log is generated by running git log --graph with the options specified in graphOpts. The default is false.
This option changes the way emails are sent. Accepted values are:
sendmail (the default): use the command /usr/sbin/sendmail or /usr/lib/sendmail (or sendmailCommand, if configured). This mode can be further customized via the following options:
The command used by mailer sendmail to send emails. Shell quoting is allowed in the value of this setting, but remember that Git requires double-quotes to be escaped; e.g.:
git config multimailhook.sendmailcommand '/usr/sbin/sendmail -oi -t -F \"Git Repo\"'
Default is ‘/usr/sbin/sendmail -oi -t’ or ‘/usr/lib/sendmail -oi -t’ (depending on which file is present and executable).
If set then pass this value to sendmail via the -f option to set the envelope sender address.
smtp: use Python’s smtplib. This is useful when the sendmail command is not available on the system. This mode can be further customized via the following options:
The name of the SMTP server to connect to. The value can also include a colon and a port number; e.g., mail.example.com:25. Default is ‘localhost’ using port 25.
Server username and password. Required if smtpEncryption is ‘ssl’. Note that the username and password currently need to be set cleartext in the configuration file, which is not recommended. If you need to use this option, be sure your configuration file is read-only.
The sender address to be passed to the SMTP server. If unset, then the value of multimailhook.from is used.
Timeout in seconds.
Set the security type. Allowed values: none, ssl, tls (starttls). Default is none.
Set the path to a list of trusted CA certificate to verify the server certificate, only supported when smtpEncryption is tls. If unset or empty, the server certificate is not verified. If it targets a file containing a list of trusted CA certificates (PEM format) these CAs will be used to verify the server certificate. For debian, you can set /etc/ssl/certs/ca-certificates.crt for using the system trusted CAs. For self-signed server, you can add your server certificate to the system store:
cd /usr/local/share/ca-certificates/ openssl s_client -starttls smtp \ -connect mail.example.net:587 -showcerts \ </dev/null 2>/dev/null \ | openssl x509 -outform PEM >mail.example.net.crt update-ca-certificates
and used the updated /etc/ssl/certs/ca-certificates.crt. Or directly use your /path/to/mail.example.net.crt. Default is unset.
Integer number. Set to greater than 0 to activate debugging.
If set, use this value in the From: field of generated emails. fromCommit is used for commit emails, fromRefchange is used for refchange emails, and from is used as fall-back in all cases.
The value for these variables can be either:
If config values are unset, the value of the From: header is determined as follows:
(gitolite environment only) Parse gitolite.conf, looking for a block of comments that looks like this:
# BEGIN USER EMAILS # username Firstname Lastname <email@example.com> # END USER EMAILS
If that block exists, and there is a line between the BEGIN USER EMAILS and END USER EMAILS lines where the first field matches the gitolite username ($GL_USER), use the rest of the line for the From: header.
If the user.email configuration setting is set, use its value (and the value of user.name, if set).
Use the value of multimailhook.envelopeSender.
If this boolean option is set to
true, then the main part of the
email body is forced to be valid UTF-8. Any characters that are
not valid UTF-8 are converted to the Unicode replacement
character, U+FFFD. The default is
This option is ineffective with Python 3, where non-UTF-8 characters are unconditionally replaced.
Options passed to git log --graph when generating graphs for the reference change summary emails (used only if refchangeShowGraph is true). The default is ‘–oneline –decorate’.
Shell quoting is allowed; see logOpts for details.
Options passed to git log to generate additional info for reference change emails (used only if refchangeShowLog is set). For example, adding -p will show each commit’s complete diff. The default is empty.
Shell quoting is allowed; for example, a log format that contains spaces can be specified using something like:
git config multimailhook.logopts '--pretty=format:"%h %aN <%aE>%n%s%n%n%b%n"'
If you want to set this by editing your configuration file directly, remember that Git requires double-quotes to be escaped (see git-config(1) for more information):
[multimailhook] logopts = --pretty=format:\"%h %aN <%aE>%n%s%n%n%b%n\"
Addresses to use in the Reply-To: field for commit emails (replyToCommit) and refchange emails (replyToRefchange). multimailhook.replyTo is used as default when replyToCommit or replyToRefchange is not set. The shortcuts pusher and author are allowed with the same semantics as for multimailhook.from. In addition, the value none can be used to omit the Reply-To: field.
The default is pusher for refchange emails, and author for commit emails.
Warning: these options are experimental. They should work, but the user-interface is not stable yet (in particular, the option names may change). If you want to participate in stabilizing the feature, please contact the maintainers and/or send pull-requests. If you are happy with the current shape of the feature, please report it too.
Regular expressions that can be used to limit refs for which email updates will be sent. It is an error to specify both an inclusion and an exclusion regex. If a refFilterInclusionRegex is specified, emails will only be sent for refs which match this regex. If a refFilterExclusionRegex regex is specified, emails will be sent for all refs except those that match this regex (or that match a predefined regex specific to the environment, such as “^refs/notes” for most environments and “^refs/notes|^refs/changes” for the gerrit environment).
The expressions are matched against the complete refname, and is considered to match if any substring matches. For example, to filter-out all tags, set refFilterExclusionRegex to ^refs/tags/ (note the leading ^ but no trailing $). If you set refFilterExclusionRegex to master, then any ref containing master will be excluded (the master branch, but also refs/tags/master or refs/heads/foo-master-bar).
refFilterDoSendRegex and refFilterDontSendRegex are analogous to refFilterInclusionRegex and refFilterExclusionRegex with one difference: with refFilterDoSendRegex and refFilterDontSendRegex, commits introduced by one excluded ref will not be considered as new when they reach an included ref. Typically, if you add a branch foo to refFilterDontSendRegex, push commits to this branch, and later merge branch foo into master, then the notification email for master will contain a commit email only for the merge commit. If you include foo in refFilterExclusionRegex, then at the time of merge, you will receive one commit email per commit in the branch.
These variables can be multi-valued, like:
[multimailhook] refFilterExclusionRegex = ^refs/tags/ refFilterExclusionRegex = ^refs/heads/master$
You can also provide a whitespace-separated list like:
[multimailhook] refFilterExclusionRegex = ^refs/tags/ ^refs/heads/master$
Both examples exclude tags and the master branch, and are equivalent to:
[multimailhook] refFilterExclusionRegex = ^refs/tags/|^refs/heads/master$
refFilterInclusionRegex and refFilterExclusionRegex are strictly stronger than refFilterDoSendRegex and refFilterDontSendRegex. In other words, adding a ref to a DoSend/DontSend regex has no effect if it is already excluded by a Exclusion/Inclusion regex.
multimailhook.logFile, multimailhook.errorLogFile, multimailhook.debugLogFile
When set, these variable designate path to files where git-multimail will log some messages. Normal messages and error messages are sent to logFile, and error messages are also sent to errorLogFile. Debug messages and all other messages are sent to debugLogFile. The recommended way is to set only one of these variables, but it is also possible to set several of them (part of the information is then duplicated in several log files, for example errors are duplicated to all log files).
Relative path are relative to the Git repository where the push is done.
Verbosity level of git-multimail on its standard output. By default, show only error and info messages. If set to true, show also debug messages.
All emails include extra headers to enable fine tuned filtering and give information for debugging. All emails include the headers X-Git-Host, X-Git-Repo, X-Git-Refname, and X-Git-Reftype. ReferenceChange emails also include headers X-Git-Oldrev and X-Git-Newrev; Revision emails also include header X-Git-Rev.
git-multimail mostly generates emails by expanding templates. The templates can be customized. To avoid the need to edit git_multimail.py directly, the preferred way to change the templates is to write a separate Python script that imports git_multimail.py as a module, then replaces the templates in place. See the provided post-receive script for an example of how this is done.
git-multimail is mostly customized via an “environment” that describes the local environment in which Git is running. Two types of environment are built in:
By default, git-multimail assumes GitoliteEnvironment if $GL_USER and
$GL_REPO are set, and otherwise assumes GenericEnvironment.
Alternatively, you can choose one of these two environments explicitly
by setting a multimailhook.environment config setting (which can
have the value
gitolite) or by passing an –environment
option to the script.
If you need to customize the script in ways that are not supported by the existing environments, you can define your own environment class class using arbitrary Python code. To do so, you need to import git_multimail.py as a Python module, as demonstrated by the example post-receive script. Then implement your environment class; it should usually inherit from one of the existing Environment classes and possibly one or more of the EnvironmentMixin classes. Then set the environment variable to an instance of your own environment class and pass it to run_as_post_receive_hook().
The standard environment classes, GenericEnvironment and GitoliteEnvironment, are in fact themselves put together out of a number of mixin classes, each of which handles one aspect of the customization. For the finest control over your configuration, you can specify exactly which mixin classes your own environment class should inherit from, and override individual methods (or even add your own mixin classes) to implement entirely new behaviors. If you implement any mixins that might be useful to other people, please consider sharing them with the community!
Please, read https://github.com/git-multimail/git-multimail/blob/master/CONTRIBUTING.rst for instructions on how to contribute to git-multimail.
|||Because of the way information is passed to update hooks, the script’s method of determining whether a commit has already been seen does not work when it is used as an update script. In particular, no notification email will be generated for a new commit that is added to multiple references in the same push. A workaround is to use –force-send to force sending the emails.|