git-multimail 1.1.0-1

Requirements

• Python 2.x, version 2.4 or later. No non-standard Python modules are required. git-multimail does not currently work with Python 3.x.

  The example scripts invoke Python using the following shebang line (following PEP 394 [1]):

  #! /usr/bin/env python2

  If your system’s Python2 interpreter is not in your PATH or is not called python2, you can change the lines accordingly. Or you can invoke the Python interpreter explicitly, for example via a tiny shell script like:

  #! /bin/sh
  /usr/local/bin/python /path/to/git_multimail.py "$@"

• The git command must be in your PATH. git-multimail is known to work with Git versions back to 1.7.1. (Earlier versions have not been tested; if you do so, please report your results.)

• To send emails using the default configuration, a standard sendmail program must be located at ‘/usr/sbin/sendmail’ or ‘/usr/lib/sendmail’ and must be configured correctly to send emails. If this is not the case, set multimailhook.sendmailCommand, or see the multimailhook.mailer configuration variable below for how to configure git-multimail to send emails via an SMTP server.

Invocation

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 [2].

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

• change how the user who did the push is determined

• read users’ email addresses from an LDAP server or from a database

• decide which users should be notified about which commits based on the contents of the commits (e.g., for users who want to be notified only about changes affecting particular files or subdirectories)

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.)

Configuration

By default, git-multimail mostly takes its configuration from the following git config settings:

multimailhook.environment

This describes the general environment of the repository. Currently supported values:

• generic

  the username of the pusher is read from $USER or $USERNAME and the repository name is derived from the repository’s path.

• gitolite

  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 doc/gitolite.rst

If neither 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, then it defaults to gitolite if the environment contains variables $GL_USER and $GL_REPO; otherwise generic.

multimailhook.repoName

A short name of this Git repository, to be used in various places in the notification email text. The default is to use $GL_REPO for gitolite repositories, or otherwise to derive this value from the repository path name.

multimailhook.mailingList

The list of email addresses to which notification emails should be sent, as RFC 2822 email addresses separated by commas. This configuration option can be multivalued. Leave it unset or set it to the empty string to not send emails by default. The next few settings can be used to configure specific address lists for specific types of notification email.

multimailhook.refchangeList

The list of email addresses to which summary emails about reference changes should be sent, as RFC 2822 email addresses separated by commas. This configuration option can be multivalued. The default is the value in multimailhook.mailingList. Set this value to the empty string to prevent reference change emails from being sent even if multimailhook.mailingList is set.

multimailhook.announceList

The list of email addresses to which emails about new annotated tags should be sent, as RFC 2822 email addresses separated by commas. This configuration option can be multivalued. The default is the value in multimailhook.refchangeList or multimailhook.mailingList. Set this value to the empty string to prevent annotated tag announcement emails from being sent even if one of the other values is set.

multimailhook.commitList

The list of email addresses to which emails about individual new commits should be sent, as RFC 2822 email addresses separated by commas. This configuration option can be multivalued. The default is the value in multimailhook.mailingList. Set this value to the empty string to prevent notification emails about individual commits from being sent even if multimailhook.mailingList is set.

multimailhook.announceShortlog

If this option is set to true, then emails about changes to annotated tags include a shortlog of changes since the previous tag. This can be useful if the annotated tags represent releases; then the shortlog will be a kind of rough summary of what has happened since the last release. But if your tagging policy is not so straightforward, then the shortlog might be confusing rather than useful. Default is false.

multimailhook.refchangeShowGraph

If this option is set to true, then summary emails about reference changes will additionally include:

• a graph of the added commits (if any)

• a graph of the discarded commits (if any)

The log is generated by running git log --graph with the options specified in graphOpts. The default is false.

multimailhook.refchangeShowLog

If this option is set to true, then summary emails about reference changes will include a detailed log of the added commits in addition to the one line summary. The log is generated by running git log with the options specified in multimailhook.logOpts. Default is false.

multimailhook.mailer

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:

  • multimailhook.sendmailCommand

    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).

  • multimailhook.envelopeSender

    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:

  • multimailhook.smtpServer

    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.

  • multimailhook.smtpUser

  • multimailhook.smtpPass

    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.

  • multimailhook.envelopeSender

    The sender address to be passed to the SMTP server. If unset, then the value of multimailhook.from is used.

  • multimailhook.smtpServerTimeout

    Timeout in seconds.

  • multimailhook.smtpEncryption

    Set the security type. Allowed values: none, ssl. Default=none.

  • multimailhook.smtpServerDebugLevel

    Integer number. Set to greater than 0 to activate debugging.

multimailhook.from

If set, use this value in the From: field of generated emails. If unset, the value of the From: header is determined as follows:

1. (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.

2. If the user.email configuration setting is set, use its value (and the value of user.name, if set).

3. Use the value of multimailhook.envelopeSender.

multimailhook.administrator

The name and/or email address of the administrator of the Git repository; used in FOOTER_TEMPLATE. Default is multimailhook.envelopesender if it is set; otherwise a generic string is used.

multimailhook.emailPrefix

All emails have this string prepended to their subjects, to aid email filtering (though filtering based on the X-Git-* email headers is probably more robust). Default is the short name of the repository in square brackets; e.g., [myrepo]. Set this value to the empty string to suppress the email prefix.

multimailhook.emailMaxLines

The maximum number of lines that should be included in the body of a generated email. If not specified, there is no limit. Lines beyond the limit are suppressed and counted, and a final line is added indicating the number of suppressed lines.

multimailhook.emailMaxLineLength

The maximum length of a line in the email body. Lines longer than this limit are truncated to this length with a trailing `` […]`` added to indicate the missing text. The default is 500, because (a) diffs with longer lines are probably from binary files, for which a diff is useless, and (b) even if a text file has such long lines, the diffs are probably unreadable anyway. To disable line truncation, set this option to 0.

multimailhook.maxCommitEmails

The maximum number of commit emails to send for a given change. When the number of patches is larger that this value, only the summary refchange email is sent. This can avoid accidental mailbombing, for example on an initial push. To disable commit emails limit, set this option to 0. The default is 500.

multimailhook.emailStrictUTF8

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 true.

multimailhook.diffOpts

Options passed to git diff-tree when generating the summary information for ReferenceChange emails. Default is --stat --summary --find-copies-harder. Add -p to those options to include a unified diff of changes in addition to the usual summary output. Shell quoting is allowed; see multimailhook.logOpts for details.

multimailhook.graphOpts

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.

multimailhook.logOpts

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\"

multimailhook.commitLogOpts

Options passed to git log to generate additional info for revision change emails. For example, adding –ignore-all-spaces will suppress whitespace changes. The default options are -C --stat -p --cc. Shell quoting is allowed; see multimailhook.logOpts for details.

multimailhook.emailDomain

Domain name appended to the username of the person doing the push to convert it into an email address (via "%s@%s" % (username, emaildomain)). More complicated schemes can be implemented by overriding Environment and overriding its get_pusher_email() method.

multimailhook.replyTo multimailhook.replyToCommit multimailhook.replyToRefchange

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 value for these variables can be either:

• An email address, which will be used directly.

• The value pusher, in which case the pusher’s address (if available) will be used. This is the default for refchange emails.

• The value author (meaningful only for replyToCommit), in which case the commit author’s address will be used. This is the default for commit emails.

• The value none, in which case the Reply-To: field will be omitted.

multimailhook.quiet

Do not output the list of email recipients from the hook

multimailhook.stdout

For debugging, send emails to stdout rather than to the mailer. Equivalent to the –stdout command line option

multimailhook.scanCommitForCc

If this option is set to true, than recipients from lines in commit body that starts with CC: will be added to CC list. Default: false

multimailhook.combineWhenSingleCommit

If this option is set to true and a single new commit is pushed to a branch, combine the summary and commit email messages into a single email. Default: true

Email filtering aids

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.

Customizing email contents

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.

Customizing git-multimail for your environment

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:

• GenericEnvironment: a stand-alone Git repository.

• GitoliteEnvironment: a Git repository that is managed by gitolite [3]. For such repositories, the identity of the pusher is read from environment variable $GL_USER, the name of the repository is read from $GL_REPO (if it is not overridden by multimailhook.reponame), and the From: header value is optionally read from gitolite.conf (see multimailhook.from).

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 generic or 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!

Getting involved

git-multimail is an open-source project, built by volunteers. We would welcome your help!

The current maintainers are Michael Haggerty <mhagger@alum.mit.edu> and Matthieu Moy <matthieu.moy@grenoble-inp.fr>.

Please note that although a copy of git-multimail is distributed in the “contrib” section of the main Git project, development takes place in a separate git-multimail repository on GitHub:

https://github.com/git-multimail/git-multimail

Whenever enough changes to git-multimail have accumulated, a new code-drop of git-multimail will be submitted for inclusion in the Git project.

We use the GitHub issue tracker to keep track of bugs and feature requests, and we use GitHub pull requests to exchange patches (though, if you prefer, you can send patches via the Git mailing list with CC to the maintainers). Please sign off your patches as per the Git project practice.

General discussion of git-multimail can take place on the main Git mailing list,

git@vger.kernel.org

Please CC emails regarding git-multimail to the maintainers so that we don’t overlook them.

Footnotes