Merge branch 'ep/trace-doc-sample-fix' into maint
[git] / contrib / hooks / multimail / README
1 git-multimail (version 1.2.0)
2 =============================
3
4 .. image:: https://travis-ci.org/git-multimail/git-multimail.svg?branch=master
5     :target: https://travis-ci.org/git-multimail/git-multimail
6
7 git-multimail is a tool for sending notification emails on pushes to a
8 Git repository.  It includes a Python module called git_multimail.py,
9 which can either be used as a hook script directly or can be imported
10 as a Python module into another script.
11
12 git-multimail is derived from the Git project's old
13 contrib/hooks/post-receive-email, and is mostly compatible with that
14 script.  See README.migrate-from-post-receive-email for details about
15 the differences and for how to migrate from post-receive-email to
16 git-multimail.
17
18 git-multimail, like the rest of the Git project, is licensed under
19 GPLv2 (see the COPYING file for details).
20
21 Please note: although, as a convenience, git-multimail may be
22 distributed along with the main Git project, development of
23 git-multimail takes place in its own, separate project.  See section
24 "Getting involved" below for more information.
25
26
27 By default, for each push received by the repository, git-multimail:
28
29 1. Outputs one email summarizing each reference that was changed.
30    These "reference change" (called "refchange" below) emails describe
31    the nature of the change (e.g., was the reference created, deleted,
32    fast-forwarded, etc.) and include a one-line summary of each commit
33    that was added to the reference.
34
35 2. Outputs one email for each new commit that was introduced by the
36    reference change.  These "commit" emails include a list of the
37    files changed by the commit, followed by the diffs of files
38    modified by the commit.  The commit emails are threaded to the
39    corresponding reference change email via "In-Reply-To".  This style
40    (similar to the "git format-patch" style used on the Git mailing
41    list) makes it easy to scan through the emails, jump to patches
42    that need further attention, and write comments about specific
43    commits.  Commits are handled in reverse topological order (i.e.,
44    parents shown before children).  For example::
45
46      [git] branch master updated
47      + [git] 01/08: doc: fix xref link from api docs to manual pages
48      + [git] 02/08: api-credentials.txt: show the big picture first
49      + [git] 03/08: api-credentials.txt: mention credential.helper explicitly
50      + [git] 04/08: api-credentials.txt: add "see also" section
51      + [git] 05/08: t3510 (cherry-pick-sequence): add missing '&&'
52      + [git] 06/08: Merge branch 'rr/maint-t3510-cascade-fix'
53      + [git] 07/08: Merge branch 'mm/api-credentials-doc'
54      + [git] 08/08: Git 1.7.11-rc2
55
56    By default, each commit appears in exactly one commit email, the
57    first time that it is pushed to the repository.  If a commit is later
58    merged into another branch, then a one-line summary of the commit
59    is included in the reference change email (as usual), but no
60    additional commit email is generated. See
61    `multimailhook.refFilter(Inclusion|Exclusion|DoSend|DontSend)Regex`
62    below to configure which branches and tags are watched by the hook.
63
64    By default, reference change emails have their "Reply-To" field set
65    to the person who pushed the change, and commit emails have their
66    "Reply-To" field set to the author of the commit.
67
68 3. Output one "announce" mail for each new annotated tag, including
69    information about the tag and optionally a shortlog describing the
70    changes since the previous tag.  Such emails might be useful if you
71    use annotated tags to mark releases of your project.
72
73
74 Requirements
75 ------------
76
77 * Python 2.x, version 2.4 or later.  No non-standard Python modules
78   are required.  git-multimail has preliminary support for Python 3
79   (but it has been better tested with Python 2).
80
81 * The ``git`` command must be in your PATH.  git-multimail is known to
82   work with Git versions back to 1.7.1.  (Earlier versions have not
83   been tested; if you do so, please report your results.)
84
85 * To send emails using the default configuration, a standard sendmail
86   program must be located at '/usr/sbin/sendmail' or
87   '/usr/lib/sendmail' and must be configured correctly to send emails.
88   If this is not the case, set multimailhook.sendmailCommand, or see
89   the multimailhook.mailer configuration variable below for how to
90   configure git-multimail to send emails via an SMTP server.
91
92
93 Invocation
94 ----------
95
96 git_multimail.py is designed to be used as a ``post-receive`` hook in a
97 Git repository (see githooks(5)).  Link or copy it to
98 $GIT_DIR/hooks/post-receive within the repository for which email
99 notifications are desired.  Usually it should be installed on the
100 central repository for a project, to which all commits are eventually
101 pushed.
102
103 For use on pre-v1.5.1 Git servers, git_multimail.py can also work as
104 an ``update`` hook, taking its arguments on the command line.  To use
105 this script in this manner, link or copy it to $GIT_DIR/hooks/update.
106 Please note that the script is not completely reliable in this mode
107 [2]_.
108
109 Alternatively, git_multimail.py can be imported as a Python module
110 into your own Python post-receive script.  This method is a bit more
111 work, but allows the behavior of the hook to be customized using
112 arbitrary Python code.  For example, you can use a custom environment
113 (perhaps inheriting from GenericEnvironment or GitoliteEnvironment) to
114
115 * change how the user who did the push is determined
116
117 * read users' email addresses from an LDAP server or from a database
118
119 * decide which users should be notified about which commits based on
120   the contents of the commits (e.g., for users who want to be notified
121   only about changes affecting particular files or subdirectories)
122
123 Or you can change how emails are sent by writing your own Mailer
124 class.  The ``post-receive`` script in this directory demonstrates how
125 to use git_multimail.py as a Python module.  (If you make interesting
126 changes of this type, please consider sharing them with the
127 community.)
128
129
130 Configuration
131 -------------
132
133 By default, git-multimail mostly takes its configuration from the
134 following ``git config`` settings:
135
136 multimailhook.environment
137
138     This describes the general environment of the repository. In most
139     cases, you do not need to specify a value for this variable:
140     `git-multimail` will autodetect which environment to use.
141     Currently supported values:
142
143     * generic
144
145       the username of the pusher is read from $USER or $USERNAME and
146       the repository name is derived from the repository's path.
147
148     * gitolite
149
150       the username of the pusher is read from $GL_USER, the repository
151       name is read from $GL_REPO, and the From: header value is
152       optionally read from gitolite.conf (see multimailhook.from).
153
154       For more information about gitolite and git-multimail, read
155       `<doc/gitolite.rst>`__
156
157     * stash
158
159       Environment to use when ``git-multimail`` is ran as an Atlassian
160       BitBucket Server (formerly known as Atlassian Stash) hook.
161
162       **Warning:** this mode was provided by a third-party contributor
163       and never tested by the git-multimail maintainers. It is
164       provided as-is and may or may not work for you.
165
166       This value is automatically assumed when the stash-specific
167       flags (``--stash-user`` and ``--stash-repo``) are specified on
168       the command line. When this environment is active, the username
169       and repo come from these two command line flags, which must be
170       specified.
171
172     * gerrit
173
174       Environment to use when ``git-multimail`` is ran as a
175       ``ref-updated`` Gerrit hook.
176
177       This value is used when the gerrit-specific command line flags
178       (``--oldrev``, ``--newrev``, ``--refname``, ``--project``) for
179       gerrit's ref-updated hook are present. When this environment is
180       active, the username of the pusher is taken from the
181       ``--submitter`` argument if that command line option is passed,
182       otherwise 'Gerrit' is used. The repository name is taken from
183       the ``--project`` option on the command line, which must be passed.
184
185       For more information about gerrit and git-multimail, read
186       `<doc/gerrit.rst>`__
187
188     If none of these environments is suitable for your setup, then you
189     can implement a Python class that inherits from Environment and
190     instantiate it via a script that looks like the example
191     post-receive script.
192
193     The environment value can be specified on the command line using
194     the ``--environment`` option. If it is not specified on the
195     command line or by ``multimailhook.environment``, the value is
196     guessed as follows:
197
198     * If stash-specific (respectively gerrit-specific) command flags
199       are present on the command-line, then ``stash`` (respectively
200       ``gerrit``) is used.
201
202     * If the environment variables $GL_USER and $GL_REPO are set, then
203       ``gitolite`` is used.
204
205     * If none of the above apply, then ``generic`` is used.
206
207 multimailhook.repoName
208
209     A short name of this Git repository, to be used in various places
210     in the notification email text.  The default is to use $GL_REPO
211     for gitolite repositories, or otherwise to derive this value from
212     the repository path name.
213
214 multimailhook.mailingList
215
216     The list of email addresses to which notification emails should be
217     sent, as RFC 2822 email addresses separated by commas.  This
218     configuration option can be multivalued.  Leave it unset or set it
219     to the empty string to not send emails by default.  The next few
220     settings can be used to configure specific address lists for
221     specific types of notification email.
222
223 multimailhook.refchangeList
224
225     The list of email addresses to which summary emails about
226     reference changes should be sent, as RFC 2822 email addresses
227     separated by commas.  This configuration option can be
228     multivalued.  The default is the value in
229     multimailhook.mailingList.  Set this value to "none" (or the empty
230     string) to prevent reference change emails from being sent even if
231     multimailhook.mailingList is set.
232
233 multimailhook.announceList
234
235     The list of email addresses to which emails about new annotated
236     tags should be sent, as RFC 2822 email addresses separated by
237     commas.  This configuration option can be multivalued.  The
238     default is the value in multimailhook.refchangeList or
239     multimailhook.mailingList.  Set this value to "none" (or the empty
240     string) to prevent annotated tag announcement emails from being sent
241     even if one of the other values is set.
242
243 multimailhook.commitList
244
245     The list of email addresses to which emails about individual new
246     commits should be sent, as RFC 2822 email addresses separated by
247     commas.  This configuration option can be multivalued.  The
248     default is the value in multimailhook.mailingList.  Set this value
249     to "none" (or the empty string) to prevent notification emails about
250     individual commits from being sent even if
251     multimailhook.mailingList is set.
252
253 multimailhook.announceShortlog
254
255     If this option is set to true, then emails about changes to
256     annotated tags include a shortlog of changes since the previous
257     tag.  This can be useful if the annotated tags represent releases;
258     then the shortlog will be a kind of rough summary of what has
259     happened since the last release.  But if your tagging policy is
260     not so straightforward, then the shortlog might be confusing
261     rather than useful.  Default is false.
262
263 multimailhook.commitEmailFormat
264
265     The format of email messages for the individual commits, can be "text" or
266     "html". In the latter case, the emails will include diffs using colorized
267     HTML instead of plain text used by default. Note that this  currently the
268     ref change emails are always sent in plain text.
269
270     Note that when using "html", the formatting is done by parsing the
271     output of ``git log`` with ``-p``. When using
272     ``multimailhook.commitLogOpts`` to specify a ``--format`` for
273     ``git log``, one may get false positive (e.g. lines in the body of
274     the message starting with ``+++`` or ``---`` colored in red or
275     green).
276
277 multimailhook.refchangeShowGraph
278
279     If this option is set to true, then summary emails about reference
280     changes will additionally include:
281
282     * a graph of the added commits (if any)
283
284     * a graph of the discarded commits (if any)
285
286     The log is generated by running ``git log --graph`` with the options
287     specified in graphOpts.  The default is false.
288
289 multimailhook.refchangeShowLog
290
291     If this option is set to true, then summary emails about reference
292     changes will include a detailed log of the added commits in
293     addition to the one line summary.  The log is generated by running
294     ``git log`` with the options specified in multimailhook.logOpts.
295     Default is false.
296
297 multimailhook.mailer
298
299     This option changes the way emails are sent.  Accepted values are:
300
301     - sendmail (the default): use the command ``/usr/sbin/sendmail`` or
302       ``/usr/lib/sendmail`` (or sendmailCommand, if configured).  This
303       mode can be further customized via the following options:
304
305       * multimailhook.sendmailCommand
306
307         The command used by mailer ``sendmail`` to send emails.  Shell
308         quoting is allowed in the value of this setting, but remember that
309         Git requires double-quotes to be escaped; e.g.::
310
311              git config multimailhook.sendmailcommand '/usr/sbin/sendmail -oi -t -F \"Git Repo\"'
312
313         Default is '/usr/sbin/sendmail -oi -t' or
314         '/usr/lib/sendmail -oi -t' (depending on which file is
315         present and executable).
316
317       * multimailhook.envelopeSender
318
319         If set then pass this value to sendmail via the -f option to set
320         the envelope sender address.
321
322     - smtp: use Python's smtplib.  This is useful when the sendmail
323       command is not available on the system.  This mode can be
324       further customized via the following options:
325
326       * multimailhook.smtpServer
327
328         The name of the SMTP server to connect to.  The value can
329         also include a colon and a port number; e.g.,
330         ``mail.example.com:25``.  Default is 'localhost' using port 25.
331
332       * multimailhook.smtpUser
333       * multimailhook.smtpPass
334
335         Server username and password. Required if smtpEncryption is 'ssl'.
336         Note that the username and password currently need to be
337         set cleartext in the configuration file, which is not
338         recommended. If you need to use this option, be sure your
339         configuration file is read-only.
340
341       * multimailhook.envelopeSender
342
343         The sender address to be passed to the SMTP server.  If
344         unset, then the value of multimailhook.from is used.
345
346       * multimailhook.smtpServerTimeout
347
348         Timeout in seconds.
349
350       * multimailhook.smtpEncryption
351
352         Set the security type. Allowed values: none, ssl, tls.
353         Default=none.
354
355       * multimailhook.smtpServerDebugLevel
356
357         Integer number. Set to greater than 0 to activate debugging.
358
359 multimailhook.from
360 multimailhook.fromCommit
361 multimailhook.fromRefchange
362
363     If set, use this value in the From: field of generated emails.
364     ``fromCommit`` is used for commit emails, ``fromRefchange`` is
365     used for refchange emails, and ``from`` is used as fall-back in
366     all cases.
367
368     The value for these variables can be either:
369
370     - An email address, which will be used directly.
371
372     - The value ``pusher``, in which case the pusher's address (if
373       available) will be used.
374
375     - The value ``author`` (meaningful only for replyToCommit), in which
376       case the commit author's address will be used.
377
378     If config values are unset, the value of the From: header is
379     determined as follows:
380
381     1. (gitolite environment only) Parse gitolite.conf, looking for a
382        block of comments that looks like this::
383
384            # BEGIN USER EMAILS
385            # username Firstname Lastname <email@example.com>
386            # END USER EMAILS
387
388        If that block exists, and there is a line between the BEGIN
389        USER EMAILS and END USER EMAILS lines where the first field
390        matches the gitolite username ($GL_USER), use the rest of the
391        line for the From: header.
392
393     2. If the user.email configuration setting is set, use its value
394        (and the value of user.name, if set).
395
396     3. Use the value of multimailhook.envelopeSender.
397
398 multimailhook.administrator
399
400     The name and/or email address of the administrator of the Git
401     repository; used in FOOTER_TEMPLATE.  Default is
402     multimailhook.envelopesender if it is set; otherwise a generic
403     string is used.
404
405 multimailhook.emailPrefix
406
407     All emails have this string prepended to their subjects, to aid
408     email filtering (though filtering based on the X-Git-* email
409     headers is probably more robust).  Default is the short name of
410     the repository in square brackets; e.g., ``[myrepo]``.  Set this
411     value to the empty string to suppress the email prefix.
412
413 multimailhook.emailMaxLines
414
415     The maximum number of lines that should be included in the body of
416     a generated email.  If not specified, there is no limit.  Lines
417     beyond the limit are suppressed and counted, and a final line is
418     added indicating the number of suppressed lines.
419
420 multimailhook.emailMaxLineLength
421
422     The maximum length of a line in the email body.  Lines longer than
423     this limit are truncated to this length with a trailing `` [...]``
424     added to indicate the missing text.  The default is 500, because
425     (a) diffs with longer lines are probably from binary files, for
426     which a diff is useless, and (b) even if a text file has such long
427     lines, the diffs are probably unreadable anyway.  To disable line
428     truncation, set this option to 0.
429
430 multimailhook.maxCommitEmails
431
432     The maximum number of commit emails to send for a given change.
433     When the number of patches is larger that this value, only the
434     summary refchange email is sent.  This can avoid accidental
435     mailbombing, for example on an initial push.  To disable commit
436     emails limit, set this option to 0.  The default is 500.
437
438 multimailhook.emailStrictUTF8
439
440     If this boolean option is set to `true`, then the main part of the
441     email body is forced to be valid UTF-8.  Any characters that are
442     not valid UTF-8 are converted to the Unicode replacement
443     character, U+FFFD.  The default is `true`.
444
445 multimailhook.diffOpts
446
447     Options passed to ``git diff-tree`` when generating the summary
448     information for ReferenceChange emails.  Default is ``--stat
449     --summary --find-copies-harder``.  Add -p to those options to
450     include a unified diff of changes in addition to the usual summary
451     output.  Shell quoting is allowed; see multimailhook.logOpts for
452     details.
453
454 multimailhook.graphOpts
455
456     Options passed to ``git log --graph`` when generating graphs for the
457     reference change summary emails (used only if refchangeShowGraph
458     is true).  The default is '--oneline --decorate'.
459
460     Shell quoting is allowed; see logOpts for details.
461
462 multimailhook.logOpts
463
464     Options passed to ``git log`` to generate additional info for
465     reference change emails (used only if refchangeShowLog is set).
466     For example, adding -p will show each commit's complete diff.  The
467     default is empty.
468
469     Shell quoting is allowed; for example, a log format that contains
470     spaces can be specified using something like::
471
472       git config multimailhook.logopts '--pretty=format:"%h %aN <%aE>%n%s%n%n%b%n"'
473
474     If you want to set this by editing your configuration file
475     directly, remember that Git requires double-quotes to be escaped
476     (see git-config(1) for more information)::
477
478       [multimailhook]
479               logopts = --pretty=format:\"%h %aN <%aE>%n%s%n%n%b%n\"
480
481 multimailhook.commitLogOpts
482
483     Options passed to ``git log`` to generate additional info for
484     revision change emails.  For example, adding --ignore-all-spaces
485     will suppress whitespace changes.  The default options are ``-C
486     --stat -p --cc``.  Shell quoting is allowed; see
487     multimailhook.logOpts for details.
488
489 multimailhook.dateSubstitute
490
491     String to use as a substitute for ``Date:`` in the output of ``git
492     log`` while formatting commit messages. This is usefull to avoid
493     emitting a line that can be interpreted by mailers as the start of
494     a cited message (Zimbra webmail in particular). Defaults to
495     ``CommitDate: ``. Set to an empty string or ``none`` to deactivate
496     the behavior.
497
498 multimailhook.emailDomain
499
500     Domain name appended to the username of the person doing the push
501     to convert it into an email address
502     (via ``"%s@%s" % (username, emaildomain)``). More complicated
503     schemes can be implemented by overriding Environment and
504     overriding its get_pusher_email() method.
505
506 multimailhook.replyTo
507 multimailhook.replyToCommit
508 multimailhook.replyToRefchange
509
510     Addresses to use in the Reply-To: field for commit emails
511     (replyToCommit) and refchange emails (replyToRefchange).
512     multimailhook.replyTo is used as default when replyToCommit or
513     replyToRefchange is not set. The shortcuts ``pusher`` and
514     ``author`` are allowed with the same semantics as for
515     ``multimailhook.from``. In addition, the value ``none`` can be
516     used to omit the ``Reply-To:`` field.
517
518     The default is ``pusher`` for refchange emails, and ``author`` for
519     commit emails.
520
521 multimailhook.quiet
522
523     Do not output the list of email recipients from the hook
524
525 multimailhook.stdout
526
527     For debugging, send emails to stdout rather than to the
528     mailer.  Equivalent to the --stdout command line option
529
530 multimailhook.scanCommitForCc
531
532     If this option is set to true, than recipients from lines in commit body
533     that starts with ``CC:`` will be added to CC list.
534     Default: false
535
536 multimailhook.combineWhenSingleCommit
537
538     If this option is set to true and a single new commit is pushed to
539     a branch, combine the summary and commit email messages into a
540     single email.
541     Default: true
542
543 multimailhook.refFilterInclusionRegex
544 multimailhook.refFilterExclusionRegex
545 multimailhook.refFilterDoSendRegex
546 multimailhook.refFilterDontSendRegex
547
548     **Warning:** these options are experimental. They should work, but
549     the user-interface is not stable yet (in particular, the option
550     names may change). If you want to participate in stabilizing the
551     feature, please contact the maintainers and/or send pull-requests.
552
553     Regular expressions that can be used to limit refs for which email
554     updates will be sent.  It is an error to specify both an inclusion
555     and an exclusion regex.  If a ``refFilterInclusionRegex`` is
556     specified, emails will only be sent for refs which match this
557     regex.  If a ``refFilterExclusionRegex`` regex is specified,
558     emails will be sent for all refs except those that match this
559     regex (or that match a predefined regex specific to the
560     environment, such as "^refs/notes" for most environments and
561     "^refs/notes|^refs/changes" for the gerrit environment).
562
563     The expressions are matched against the complete refname, and is
564     considered to match if any substring matches. For example, to
565     filter-out all tags, set ``refFilterExclusionRegex`` to
566     ``^refs/tags/`` (note the leading ``^`` but no trailing ``$``). If
567     you set ``refFilterExclusionRegex`` to ``master``, then any ref
568     containing ``master`` will be excluded (the ``master`` branch, but
569     also ``refs/tags/master`` or ``refs/heads/foo-master-bar``).
570
571     ``refFilterDoSendRegex`` and ``refFilterDontSendRegex`` are
572     analogous to ``refFilterInclusionRegex`` and
573     ``refFilterExclusionRegex`` with one difference: with
574     ``refFilterDoSendRegex`` and ``refFilterDontSendRegex``, commits
575     introduced by one excluded ref will not be considered as new when
576     they reach an included ref. Typically, if you add a branch ``foo``
577     to  ``refFilterDontSendRegex``, push commits to this branch, and
578     later merge branch ``foo`` into ``master``, then the notification
579     email for ``master`` will contain a commit email only for the
580     merge commit. If you include ``foo`` in
581     ``refFilterExclusionRegex``, then at the time of merge, you will
582     receive one commit email per commit in the branch.
583
584     These variables can be multi-valued, like::
585
586       [multimailhook]
587               refFilterExclusionRegex = ^refs/tags/
588               refFilterExclusionRegex = ^refs/heads/master$
589
590     You can also provide a whitespace-separated list like::
591
592       [multimailhook]
593               refFilterExclusionRegex = ^refs/tags/ ^refs/heads/master$
594
595     Both examples exclude tags and the master branch, and are
596     equivalent to::
597
598       [multimailhook]
599               refFilterExclusionRegex = ^refs/tags/|^refs/heads/master$
600
601 Email filtering aids
602 --------------------
603
604 All emails include extra headers to enable fine tuned filtering and
605 give information for debugging.  All emails include the headers
606 ``X-Git-Host``, ``X-Git-Repo``, ``X-Git-Refname``, and ``X-Git-Reftype``.
607 ReferenceChange emails also include headers ``X-Git-Oldrev`` and ``X-Git-Newrev``;
608 Revision emails also include header ``X-Git-Rev``.
609
610
611 Customizing email contents
612 --------------------------
613
614 git-multimail mostly generates emails by expanding templates.  The
615 templates can be customized.  To avoid the need to edit
616 git_multimail.py directly, the preferred way to change the templates
617 is to write a separate Python script that imports git_multimail.py as
618 a module, then replaces the templates in place.  See the provided
619 post-receive script for an example of how this is done.
620
621
622 Customizing git-multimail for your environment
623 ----------------------------------------------
624
625 git-multimail is mostly customized via an "environment" that describes
626 the local environment in which Git is running.  Two types of
627 environment are built in:
628
629 * GenericEnvironment: a stand-alone Git repository.
630
631 * GitoliteEnvironment: a Git repository that is managed by gitolite
632   [3]_.  For such repositories, the identity of the pusher is read from
633   environment variable $GL_USER, the name of the repository is read
634   from $GL_REPO (if it is not overridden by multimailhook.reponame),
635   and the From: header value is optionally read from gitolite.conf
636   (see multimailhook.from).
637
638 By default, git-multimail assumes GitoliteEnvironment if $GL_USER and
639 $GL_REPO are set, and otherwise assumes GenericEnvironment.
640 Alternatively, you can choose one of these two environments explicitly
641 by setting a ``multimailhook.environment`` config setting (which can
642 have the value `generic` or `gitolite`) or by passing an --environment
643 option to the script.
644
645 If you need to customize the script in ways that are not supported by
646 the existing environments, you can define your own environment class
647 class using arbitrary Python code.  To do so, you need to import
648 git_multimail.py as a Python module, as demonstrated by the example
649 post-receive script.  Then implement your environment class; it should
650 usually inherit from one of the existing Environment classes and
651 possibly one or more of the EnvironmentMixin classes.  Then set the
652 ``environment`` variable to an instance of your own environment class
653 and pass it to ``run_as_post_receive_hook()``.
654
655 The standard environment classes, GenericEnvironment and
656 GitoliteEnvironment, are in fact themselves put together out of a
657 number of mixin classes, each of which handles one aspect of the
658 customization.  For the finest control over your configuration, you
659 can specify exactly which mixin classes your own environment class
660 should inherit from, and override individual methods (or even add your
661 own mixin classes) to implement entirely new behaviors.  If you
662 implement any mixins that might be useful to other people, please
663 consider sharing them with the community!
664
665
666 Getting involved
667 ----------------
668
669 Please, read `<CONTRIBUTING.rst>`__ for instructions on how to
670 contribute to git-multimail.
671
672
673 Footnotes
674 ---------
675
676 .. [1] http://www.python.org/dev/peps/pep-0394/
677
678 .. [2] Because of the way information is passed to update hooks, the
679        script's method of determining whether a commit has already
680        been seen does not work when it is used as an ``update`` script.
681        In particular, no notification email will be generated for a
682        new commit that is added to multiple references in the same
683        push. A workaround is to use --force-send to force sending the
684        emails.
685
686 .. [3] https://github.com/sitaramc/gitolite