- git-multimail
- =============
+git-multimail Version 1.1.0
+===========================
+
+.. image:: https://travis-ci.org/git-multimail/git-multimail.svg?branch=master
+ :target: https://travis-ci.org/git-multimail/git-multimail
git-multimail is a tool for sending notification emails on pushes to a
Git repository. It includes a Python module called git_multimail.py,
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
+ 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
Each commit appears in exactly one commit email, the first time
that it is pushed to the repository. If a commit is later merged
3.x.
The example scripts invoke Python using the following shebang line
- (following PEP 394 [1]):
+ (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
+ called ``python2``, you can change the lines accordingly. Or you can
invoke the Python interpreter explicitly, for example via a tiny
- shell script like
+ 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
+* 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' and configured
- correctly to send emails. If this is not the case, see the
- multimailhook.mailer configuration variable below for how to
+ 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_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
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
+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].
+[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
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
+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.)
-------------
By default, git-multimail mostly takes its configuration from the
-following "git config" settings:
+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 and the
- repository name is derived from the repository's path.
+ * generic
+
+ the username of the pusher is read from $USER or $USERNAME and
+ the repository name is derived from the repository's path.
+
+ * gitolite
- "gitolite" -- the username of the pusher is read from $GL_USER and
- the repository name from $GL_REPO.
+ 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
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".
+ ``gitolite`` if the environment contains variables $GL_USER and
+ $GL_REPO; otherwise ``generic``.
multimailhook.repoName
for gitolite repositories, or otherwise to derive this value from
the repository path name.
-multimailhook.mailinglist
+multimailhook.mailingList
The list of email addresses to which notification emails should be
sent, as RFC 2822 email addresses separated by commas. This
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.
+ 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.
+ 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
+ default is the value in multimailhook.mailingList. Set this value
to the empty string to prevent notification emails about
- individual commits from being sent.
+ individual commits from being sent even if
+ multimailhook.mailingList is set.
multimailhook.announceShortlog
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.
+ ``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
+ - 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
+ * 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.,
+ 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 -t -F \"Git Repo\"'
+ git config multimailhook.sendmailcommand '/usr/sbin/sendmail -oi -t -F \"Git Repo\"'
- Default is '/usr/sbin/sendmail -t' or '/usr/lib/sendmail
- -t' (depending on which file is present and executable).
+ Default is '/usr/sbin/sendmail -oi -t' or
+ '/usr/lib/sendmail -oi -t' (depending on which file is
+ present and executable).
- multimailhook.envelopeSender
+ * multimailhook.envelopeSender
- If set then pass this value to sendmail via the -f option to set
- the envelope sender address.
+ 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
+ * 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.
- 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
- multimailhook.envelopeSender
+ 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.
+ * 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 then use this value in the From: field of generated emails.
- If unset, then use the repository's user configuration (user.name
- and user.email). If user.email is also unset, then use
- multimailhook.envelopeSender.
+ 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
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]".
+ the repository in square brackets; e.g., ``[myrepo]``. Set this
+ value to the empty string to suppress the email prefix.
multimailhook.emailMaxLines
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 " [...]"
+ 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
multimailhook.emailStrictUTF8
- If this boolean option is set to "true", then the main part of the
+ 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".
+ 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
+ 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
+ Options passed to ``git log`` to generate additional info for
reference change emails (used only if refchangeShowLog is set).
- For example, adding --graph will show the graph of revisions, -p
- will show the complete diff, etc. The default is empty.
+ 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:
+ 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):
+ (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.
+ 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
- An email address, which will be used directly.
- - The value "pusher", in which case the pusher's address (if
+ - 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
+ - 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
+ - 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-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".
+``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
* 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, and the name of the repository is
- read from $GL_REPO (if it is not overridden by
- multimailhook.reponame).
+ [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
+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
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().
+``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
Getting involved
----------------
-git-multimail is an open-source project, built by volunteers. We
-would welcome your help!
+git-multimail is an open-source project, built by volunteers. We would
+welcome your help!
-The current maintainer is Michael Haggerty <mhagger@alum.mit.edu>.
+The current maintainers are Michael Haggerty <mhagger@alum.mit.edu>
+and Matthieu Moy <matthieu.moy@grenoble-inp.fr>.
-General discussion of git-multimail takes place on the main Git
-mailing list,
+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:
- git@vger.kernel.org
+ https://github.com/git-multimail/git-multimail
-Please CC emails regarding git-multimail to me so that I don't
-overlook them.
+Whenever enough changes to git-multimail have accumulated, a new
+code-drop of git-multimail will be submitted for inclusion in the Git
+project.
-The git-multimail project itself is currently hosted on GitHub:
+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.
- https://github.com/mhagger/git-multimail
+General discussion of git-multimail can take place on the main Git
+mailing list,
-We use the GitHub issue tracker to keep track of bugs and feature
-requests, and GitHub pull requests to exchange patches (though, if you
-prefer, you can send patches via the Git mailing list with cc to me).
+ git@vger.kernel.org
-Please note that although a copy of git-multimail will probably be
-distributed in the "contrib" section of the main Git project,
-development takes place in the separate git-multimail repository on
-GitHub! (Whenever enough changes to git-multimail have accumulated, a
-new code-drop of git-multimail will be submitted for inclusion in the
-Git project.)
+Please CC emails regarding git-multimail to the maintainers so that we
+don't overlook them.
Footnotes
---------
-[1] http://www.python.org/dev/peps/pep-0394/
+.. [1] http://www.python.org/dev/peps/pep-0394/
-[2] 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.
+.. [2] 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.
-[3] https://github.com/sitaramc/gitolite
+.. [3] https://github.com/sitaramc/gitolite