| 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, |
| 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: |
| |
| 1. 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. |
| |
| 2. 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 |
| |
| 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. |
| |
| 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. |
| |
| 3. 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. |
| |
| |
| 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 |
| --------- |
| |
| .. [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. A workaround is to use --force-send to force sending the |
| emails. |
| |
| .. [3] https://github.com/sitaramc/gitolite |