- git-multimail
- =============
+git-multimail Version 1.1.1
+===========================
+
+.. 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.)
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
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 -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).
+ 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.
+
+ * 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.
- 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.smtpEncryption
- multimailhook.envelopeSender
+ Set the security type. Allowed values: none, ssl.
+ Default=none.
- The sender address to be passed to the SMTP server. If
- unset, then the value of multimailhook.from is used.
+ * 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
+ 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
+ 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-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".
+``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
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