Merge branch 'ls/p4-lfs'
[git] / contrib / hooks / multimail / README
1 git-multimail version 1.4.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 [1]_.
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 Troubleshooting/FAQ
131 -------------------
132
133 Please read `<doc/troubleshooting.rst>`__ for frequently asked
134 questions and common issues with git-multimail.
135
136
137 Configuration
138 -------------
139
140 By default, git-multimail mostly takes its configuration from the
141 following ``git config`` settings:
142
143 multimailhook.environment
144     This describes the general environment of the repository. In most
145     cases, you do not need to specify a value for this variable:
146     `git-multimail` will autodetect which environment to use.
147     Currently supported values:
148
149     generic
150       the username of the pusher is read from $USER or $USERNAME and
151       the repository name is derived from the repository's path.
152
153     gitolite
154       Environment to use when ``git-multimail`` is ran as a gitolite_
155       hook.
156
157       The username of the pusher is read from $GL_USER, the repository
158       name is read from $GL_REPO, and the From: header value is
159       optionally read from gitolite.conf (see multimailhook.from).
160
161       For more information about gitolite and git-multimail, read
162       `<doc/gitolite.rst>`__
163
164     stash
165       Environment to use when ``git-multimail`` is ran as an Atlassian
166       BitBucket Server (formerly known as Atlassian Stash) hook.
167
168       **Warning:** this mode was provided by a third-party contributor
169       and never tested by the git-multimail maintainers. It is
170       provided as-is and may or may not work for you.
171
172       This value is automatically assumed when the stash-specific
173       flags (``--stash-user`` and ``--stash-repo``) are specified on
174       the command line. When this environment is active, the username
175       and repo come from these two command line flags, which must be
176       specified.
177
178     gerrit
179       Environment to use when ``git-multimail`` is ran as a
180       ``ref-updated`` Gerrit hook.
181
182       This value is used when the gerrit-specific command line flags
183       (``--oldrev``, ``--newrev``, ``--refname``, ``--project``) for
184       gerrit's ref-updated hook are present. When this environment is
185       active, the username of the pusher is taken from the
186       ``--submitter`` argument if that command line option is passed,
187       otherwise 'Gerrit' is used. The repository name is taken from
188       the ``--project`` option on the command line, which must be passed.
189
190       For more information about gerrit and git-multimail, read
191       `<doc/gerrit.rst>`__
192
193     If none of these environments is suitable for your setup, then you
194     can implement a Python class that inherits from Environment and
195     instantiate it via a script that looks like the example
196     post-receive script.
197
198     The environment value can be specified on the command line using
199     the ``--environment`` option. If it is not specified on the
200     command line or by ``multimailhook.environment``, the value is
201     guessed as follows:
202
203     * If stash-specific (respectively gerrit-specific) command flags
204       are present on the command-line, then ``stash`` (respectively
205       ``gerrit``) is used.
206
207     * If the environment variables $GL_USER and $GL_REPO are set, then
208       ``gitolite`` is used.
209
210     * If none of the above apply, then ``generic`` is used.
211
212 multimailhook.repoName
213     A short name of this Git repository, to be used in various places
214     in the notification email text.  The default is to use $GL_REPO
215     for gitolite repositories, or otherwise to derive this value from
216     the repository path name.
217
218 multimailhook.mailingList
219     The list of email addresses to which notification emails should be
220     sent, as RFC 2822 email addresses separated by commas.  This
221     configuration option can be multivalued.  Leave it unset or set it
222     to the empty string to not send emails by default.  The next few
223     settings can be used to configure specific address lists for
224     specific types of notification email.
225
226 multimailhook.refchangeList
227     The list of email addresses to which summary emails about
228     reference changes should be sent, as RFC 2822 email addresses
229     separated by commas.  This configuration option can be
230     multivalued.  The default is the value in
231     multimailhook.mailingList.  Set this value to "none" (or the empty
232     string) to prevent reference change emails from being sent even if
233     multimailhook.mailingList is set.
234
235 multimailhook.announceList
236     The list of email addresses to which emails about new annotated
237     tags should be sent, as RFC 2822 email addresses separated by
238     commas.  This configuration option can be multivalued.  The
239     default is the value in multimailhook.refchangeList or
240     multimailhook.mailingList.  Set this value to "none" (or the empty
241     string) to prevent annotated tag announcement emails from being sent
242     even if one of the other values is set.
243
244 multimailhook.commitList
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     If this option is set to true, then emails about changes to
255     annotated tags include a shortlog of changes since the previous
256     tag.  This can be useful if the annotated tags represent releases;
257     then the shortlog will be a kind of rough summary of what has
258     happened since the last release.  But if your tagging policy is
259     not so straightforward, then the shortlog might be confusing
260     rather than useful.  Default is false.
261
262 multimailhook.commitEmailFormat
263     The format of email messages for the individual commits, can be "text" or
264     "html". In the latter case, the emails will include diffs using colorized
265     HTML instead of plain text used by default. Note that this  currently the
266     ref change emails are always sent in plain text.
267
268     Note that when using "html", the formatting is done by parsing the
269     output of ``git log`` with ``-p``. When using
270     ``multimailhook.commitLogOpts`` to specify a ``--format`` for
271     ``git log``, one may get false positive (e.g. lines in the body of
272     the message starting with ``+++`` or ``---`` colored in red or
273     green).
274
275     By default, all the message is HTML-escaped. See
276     ``multimailhook.htmlInIntro`` to change this behavior.
277
278 multimailhook.commitBrowseURL
279     Used to generate a link to an online repository browser in commit
280     emails. This variable must be a string. Format directives like
281     ``%(<variable>)s`` will be expanded the same way as template
282     strings. In particular, ``%(id)s`` will be replaced by the full
283     Git commit identifier (40-chars hexadecimal).
284
285     If the string does not contain any format directive, then
286     ``%(id)s`` will be automatically added to the string. If you don't
287     want ``%(id)s`` to be automatically added, use the empty format
288     directive ``%()s`` anywhere in the string.
289
290     For example, a suitable value for the git-multimail project itself
291     would be
292     ``https://github.com/git-multimail/git-multimail/commit/%(id)s``.
293
294 multimailhook.htmlInIntro, multimailhook.htmlInFooter
295     When generating an HTML message, git-multimail escapes any HTML
296     sequence by default. This means that if a template contains HTML
297     like ``<a href="foo">link</a>``, the reader will see the HTML
298     source code and not a proper link.
299
300     Set ``multimailhook.htmlInIntro`` to true to allow writing HTML
301     formatting in introduction templates. Similarly, set
302     ``multimailhook.htmlInFooter`` for HTML in the footer.
303
304     Variables expanded in the template are still escaped. For example,
305     if a repository's path contains a ``<``, it will be rendered as
306     such in the message.
307
308     Read `<doc/customizing-emails.rst>`__ for more details and
309     examples.
310
311 multimailhook.refchangeShowGraph
312     If this option is set to true, then summary emails about reference
313     changes will additionally include:
314
315     * a graph of the added commits (if any)
316
317     * a graph of the discarded commits (if any)
318
319     The log is generated by running ``git log --graph`` with the options
320     specified in graphOpts.  The default is false.
321
322 multimailhook.refchangeShowLog
323     If this option is set to true, then summary emails about reference
324     changes will include a detailed log of the added commits in
325     addition to the one line summary.  The log is generated by running
326     ``git log`` with the options specified in multimailhook.logOpts.
327     Default is false.
328
329 multimailhook.mailer
330     This option changes the way emails are sent.  Accepted values are:
331
332     * **sendmail (the default)**: use the command ``/usr/sbin/sendmail`` or
333       ``/usr/lib/sendmail`` (or sendmailCommand, if configured).  This
334       mode can be further customized via the following options:
335
336       multimailhook.sendmailCommand
337           The command used by mailer ``sendmail`` to send emails.  Shell
338           quoting is allowed in the value of this setting, but remember that
339           Git requires double-quotes to be escaped; e.g.::
340
341               git config multimailhook.sendmailcommand '/usr/sbin/sendmail -oi -t -F \"Git Repo\"'
342
343           Default is '/usr/sbin/sendmail -oi -t' or
344           '/usr/lib/sendmail -oi -t' (depending on which file is
345           present and executable).
346
347       multimailhook.envelopeSender
348           If set then pass this value to sendmail via the -f option to set
349           the envelope sender address.
350
351     * **smtp**: use Python's smtplib.  This is useful when the sendmail
352       command is not available on the system.  This mode can be
353       further customized via the following options:
354
355       multimailhook.smtpServer
356           The name of the SMTP server to connect to.  The value can
357           also include a colon and a port number; e.g.,
358           ``mail.example.com:25``.  Default is 'localhost' using port 25.
359
360       multimailhook.smtpUser, multimailhook.smtpPass
361           Server username and password. Required if smtpEncryption is 'ssl'.
362           Note that the username and password currently need to be
363           set cleartext in the configuration file, which is not
364           recommended. If you need to use this option, be sure your
365           configuration file is read-only.
366
367       multimailhook.envelopeSender
368         The sender address to be passed to the SMTP server.  If
369         unset, then the value of multimailhook.from is used.
370
371       multimailhook.smtpServerTimeout
372         Timeout in seconds.
373
374       multimailhook.smtpEncryption
375         Set the security type. Allowed values: ``none``, ``ssl``, ``tls`` (starttls).
376         Default is ``none``.
377
378       multimailhook.smtpCACerts
379         Set the path to a list of trusted CA certificate to verify the
380         server certificate, only supported when ``smtpEncryption`` is
381         ``tls``. If unset or empty, the server certificate is not
382         verified. If it targets a file containing a list of trusted CA
383         certificates (PEM format) these CAs will be used to verify the
384         server certificate. For debian, you can set
385         ``/etc/ssl/certs/ca-certificates.crt`` for using the system
386         trusted CAs. For self-signed server, you can add your server
387         certificate to the system store::
388
389             cd /usr/local/share/ca-certificates/
390             openssl s_client -starttls smtp \
391                    -connect mail.example.net:587 -showcerts \
392                    </dev/null 2>/dev/null \
393                  | openssl x509 -outform PEM >mail.example.net.crt
394             update-ca-certificates
395
396         and used the updated ``/etc/ssl/certs/ca-certificates.crt``. Or
397         directly use your ``/path/to/mail.example.net.crt``. Default is
398         unset.
399
400       multimailhook.smtpServerDebugLevel
401         Integer number. Set to greater than 0 to activate debugging.
402
403 multimailhook.from, multimailhook.fromCommit, multimailhook.fromRefchange
404     If set, use this value in the From: field of generated emails.
405     ``fromCommit`` is used for commit emails, ``fromRefchange`` is
406     used for refchange emails, and ``from`` is used as fall-back in
407     all cases.
408
409     The value for these variables can be either:
410
411     - An email address, which will be used directly.
412
413     - The value ``pusher``, in which case the pusher's address (if
414       available) will be used.
415
416     - The value ``author`` (meaningful only for ``fromCommit``), in which
417       case the commit author's address will be used.
418
419     If config values are unset, the value of the From: header is
420     determined as follows:
421
422     1. (gitolite environment only) Parse gitolite.conf, looking for a
423        block of comments that looks like this::
424
425            # BEGIN USER EMAILS
426            # username Firstname Lastname <email@example.com>
427            # END USER EMAILS
428
429        If that block exists, and there is a line between the BEGIN
430        USER EMAILS and END USER EMAILS lines where the first field
431        matches the gitolite username ($GL_USER), use the rest of the
432        line for the From: header.
433
434     2. If the user.email configuration setting is set, use its value
435        (and the value of user.name, if set).
436
437     3. Use the value of multimailhook.envelopeSender.
438
439 multimailhook.administrator
440     The name and/or email address of the administrator of the Git
441     repository; used in FOOTER_TEMPLATE.  Default is
442     multimailhook.envelopesender if it is set; otherwise a generic
443     string is used.
444
445 multimailhook.emailPrefix
446     All emails have this string prepended to their subjects, to aid
447     email filtering (though filtering based on the X-Git-* email
448     headers is probably more robust).  Default is the short name of
449     the repository in square brackets; e.g., ``[myrepo]``.  Set this
450     value to the empty string to suppress the email prefix. You may
451     use the placeholder ``%(repo_shortname)s`` for the short name of
452     the repository.
453
454 multimailhook.emailMaxLines
455     The maximum number of lines that should be included in the body of
456     a generated email.  If not specified, there is no limit.  Lines
457     beyond the limit are suppressed and counted, and a final line is
458     added indicating the number of suppressed lines.
459
460 multimailhook.emailMaxLineLength
461     The maximum length of a line in the email body.  Lines longer than
462     this limit are truncated to this length with a trailing ``[...]``
463     added to indicate the missing text.  The default is 500, because
464     (a) diffs with longer lines are probably from binary files, for
465     which a diff is useless, and (b) even if a text file has such long
466     lines, the diffs are probably unreadable anyway.  To disable line
467     truncation, set this option to 0.
468
469 multimailhook.subjectMaxLength
470     The maximum length of the subject line (i.e. the ``oneline`` field
471     in templates, not including the prefix). Lines longer than this
472     limit are truncated to this length with a trailing ``[...]`` added
473     to indicate the missing text. This option The default is to use
474     ``multimailhook.emailMaxLineLength``. This option avoids sending
475     emails with overly long subject lines, but should not be needed if
476     the commit messages follow the Git convention (one short subject
477     line, then a blank line, then the message body). To disable line
478     truncation, set this option to 0.
479
480 multimailhook.maxCommitEmails
481     The maximum number of commit emails to send for a given change.
482     When the number of patches is larger that this value, only the
483     summary refchange email is sent.  This can avoid accidental
484     mailbombing, for example on an initial push.  To disable commit
485     emails limit, set this option to 0.  The default is 500.
486
487 multimailhook.emailStrictUTF8
488     If this boolean option is set to `true`, then the main part of the
489     email body is forced to be valid UTF-8.  Any characters that are
490     not valid UTF-8 are converted to the Unicode replacement
491     character, U+FFFD.  The default is `true`.
492
493     This option is ineffective with Python 3, where non-UTF-8
494     characters are unconditionally replaced.
495
496 multimailhook.diffOpts
497     Options passed to ``git diff-tree`` when generating the summary
498     information for ReferenceChange emails.  Default is ``--stat
499     --summary --find-copies-harder``.  Add -p to those options to
500     include a unified diff of changes in addition to the usual summary
501     output.  Shell quoting is allowed; see ``multimailhook.logOpts`` for
502     details.
503
504 multimailhook.graphOpts
505     Options passed to ``git log --graph`` when generating graphs for the
506     reference change summary emails (used only if refchangeShowGraph
507     is true).  The default is '--oneline --decorate'.
508
509     Shell quoting is allowed; see logOpts for details.
510
511 multimailhook.logOpts
512     Options passed to ``git log`` to generate additional info for
513     reference change emails (used only if refchangeShowLog is set).
514     For example, adding -p will show each commit's complete diff.  The
515     default is empty.
516
517     Shell quoting is allowed; for example, a log format that contains
518     spaces can be specified using something like::
519
520       git config multimailhook.logopts '--pretty=format:"%h %aN <%aE>%n%s%n%n%b%n"'
521
522     If you want to set this by editing your configuration file
523     directly, remember that Git requires double-quotes to be escaped
524     (see git-config(1) for more information)::
525
526       [multimailhook]
527               logopts = --pretty=format:\"%h %aN <%aE>%n%s%n%n%b%n\"
528
529 multimailhook.commitLogOpts
530     Options passed to ``git log`` to generate additional info for
531     revision change emails.  For example, adding --ignore-all-spaces
532     will suppress whitespace changes.  The default options are ``-C
533     --stat -p --cc``.  Shell quoting is allowed; see
534     multimailhook.logOpts for details.
535
536 multimailhook.dateSubstitute
537     String to use as a substitute for ``Date:`` in the output of ``git
538     log`` while formatting commit messages. This is useful to avoid
539     emitting a line that can be interpreted by mailers as the start of
540     a cited message (Zimbra webmail in particular). Defaults to
541     ``CommitDate:``. Set to an empty string or ``none`` to deactivate
542     the behavior.
543
544 multimailhook.emailDomain
545     Domain name appended to the username of the person doing the push
546     to convert it into an email address
547     (via ``"%s@%s" % (username, emaildomain)``). More complicated
548     schemes can be implemented by overriding Environment and
549     overriding its get_pusher_email() method.
550
551 multimailhook.replyTo, multimailhook.replyToCommit, multimailhook.replyToRefchange
552     Addresses to use in the Reply-To: field for commit emails
553     (replyToCommit) and refchange emails (replyToRefchange).
554     multimailhook.replyTo is used as default when replyToCommit or
555     replyToRefchange is not set. The shortcuts ``pusher`` and
556     ``author`` are allowed with the same semantics as for
557     ``multimailhook.from``. In addition, the value ``none`` can be
558     used to omit the ``Reply-To:`` field.
559
560     The default is ``pusher`` for refchange emails, and ``author`` for
561     commit emails.
562
563 multimailhook.quiet
564     Do not output the list of email recipients from the hook
565
566 multimailhook.stdout
567     For debugging, send emails to stdout rather than to the
568     mailer.  Equivalent to the --stdout command line option
569
570 multimailhook.scanCommitForCc
571     If this option is set to true, than recipients from lines in commit body
572     that starts with ``CC:`` will be added to CC list.
573     Default: false
574
575 multimailhook.combineWhenSingleCommit
576     If this option is set to true and a single new commit is pushed to
577     a branch, combine the summary and commit email messages into a
578     single email.
579     Default: true
580
581 multimailhook.refFilterInclusionRegex, multimailhook.refFilterExclusionRegex, multimailhook.refFilterDoSendRegex, multimailhook.refFilterDontSendRegex
582     **Warning:** these options are experimental. They should work, but
583     the user-interface is not stable yet (in particular, the option
584     names may change). If you want to participate in stabilizing the
585     feature, please contact the maintainers and/or send pull-requests.
586     If you are happy with the current shape of the feature, please
587     report it too.
588
589     Regular expressions that can be used to limit refs for which email
590     updates will be sent.  It is an error to specify both an inclusion
591     and an exclusion regex.  If a ``refFilterInclusionRegex`` is
592     specified, emails will only be sent for refs which match this
593     regex.  If a ``refFilterExclusionRegex`` regex is specified,
594     emails will be sent for all refs except those that match this
595     regex (or that match a predefined regex specific to the
596     environment, such as "^refs/notes" for most environments and
597     "^refs/notes|^refs/changes" for the gerrit environment).
598
599     The expressions are matched against the complete refname, and is
600     considered to match if any substring matches. For example, to
601     filter-out all tags, set ``refFilterExclusionRegex`` to
602     ``^refs/tags/`` (note the leading ``^`` but no trailing ``$``). If
603     you set ``refFilterExclusionRegex`` to ``master``, then any ref
604     containing ``master`` will be excluded (the ``master`` branch, but
605     also ``refs/tags/master`` or ``refs/heads/foo-master-bar``).
606
607     ``refFilterDoSendRegex`` and ``refFilterDontSendRegex`` are
608     analogous to ``refFilterInclusionRegex`` and
609     ``refFilterExclusionRegex`` with one difference: with
610     ``refFilterDoSendRegex`` and ``refFilterDontSendRegex``, commits
611     introduced by one excluded ref will not be considered as new when
612     they reach an included ref. Typically, if you add a branch ``foo``
613     to  ``refFilterDontSendRegex``, push commits to this branch, and
614     later merge branch ``foo`` into ``master``, then the notification
615     email for ``master`` will contain a commit email only for the
616     merge commit. If you include ``foo`` in
617     ``refFilterExclusionRegex``, then at the time of merge, you will
618     receive one commit email per commit in the branch.
619
620     These variables can be multi-valued, like::
621
622       [multimailhook]
623               refFilterExclusionRegex = ^refs/tags/
624               refFilterExclusionRegex = ^refs/heads/master$
625
626     You can also provide a whitespace-separated list like::
627
628       [multimailhook]
629               refFilterExclusionRegex = ^refs/tags/ ^refs/heads/master$
630
631     Both examples exclude tags and the master branch, and are
632     equivalent to::
633
634       [multimailhook]
635               refFilterExclusionRegex = ^refs/tags/|^refs/heads/master$
636
637     ``refFilterInclusionRegex`` and ``refFilterExclusionRegex`` are
638     strictly stronger than ``refFilterDoSendRegex`` and
639     ``refFilterDontSendRegex``. In other words, adding a ref to a
640     DoSend/DontSend regex has no effect if it is already excluded by a
641     Exclusion/Inclusion regex.
642
643 multimailhook.logFile, multimailhook.errorLogFile, multimailhook.debugLogFile
644
645     When set, these variable designate path to files where
646     git-multimail will log some messages. Normal messages and error
647     messages are sent to ``logFile``, and error messages are also sent
648     to ``errorLogFile``. Debug messages and all other messages are
649     sent to ``debugLogFile``. The recommended way is to set only one
650     of these variables, but it is also possible to set several of them
651     (part of the information is then duplicated in several log files,
652     for example errors are duplicated to all log files).
653
654     Relative path are relative to the Git repository where the push is
655     done.
656
657 multimailhook.verbose
658
659     Verbosity level of git-multimail on its standard output. By
660     default, show only error and info messages. If set to true, show
661     also debug messages.
662
663 Email filtering aids
664 --------------------
665
666 All emails include extra headers to enable fine tuned filtering and
667 give information for debugging.  All emails include the headers
668 ``X-Git-Host``, ``X-Git-Repo``, ``X-Git-Refname``, and ``X-Git-Reftype``.
669 ReferenceChange emails also include headers ``X-Git-Oldrev`` and ``X-Git-Newrev``;
670 Revision emails also include header ``X-Git-Rev``.
671
672
673 Customizing email contents
674 --------------------------
675
676 git-multimail mostly generates emails by expanding templates.  The
677 templates can be customized.  To avoid the need to edit
678 ``git_multimail.py`` directly, the preferred way to change the templates
679 is to write a separate Python script that imports ``git_multimail.py`` as
680 a module, then replaces the templates in place.  See the provided
681 post-receive script for an example of how this is done.
682
683
684 Customizing git-multimail for your environment
685 ----------------------------------------------
686
687 git-multimail is mostly customized via an "environment" that describes
688 the local environment in which Git is running.  Two types of
689 environment are built in:
690
691 GenericEnvironment
692     a stand-alone Git repository.
693
694 GitoliteEnvironment
695     a Git repository that is managed by gitolite_.  For such
696     repositories, the identity of the pusher is read from
697     environment variable $GL_USER, the name of the repository is read
698     from $GL_REPO (if it is not overridden by multimailhook.reponame),
699     and the From: header value is optionally read from gitolite.conf
700     (see multimailhook.from).
701
702 By default, git-multimail assumes GitoliteEnvironment if $GL_USER and
703 $GL_REPO are set, and otherwise assumes GenericEnvironment.
704 Alternatively, you can choose one of these two environments explicitly
705 by setting a ``multimailhook.environment`` config setting (which can
706 have the value `generic` or `gitolite`) or by passing an --environment
707 option to the script.
708
709 If you need to customize the script in ways that are not supported by
710 the existing environments, you can define your own environment class
711 class using arbitrary Python code.  To do so, you need to import
712 ``git_multimail.py`` as a Python module, as demonstrated by the example
713 post-receive script.  Then implement your environment class; it should
714 usually inherit from one of the existing Environment classes and
715 possibly one or more of the EnvironmentMixin classes.  Then set the
716 ``environment`` variable to an instance of your own environment class
717 and pass it to ``run_as_post_receive_hook()``.
718
719 The standard environment classes, GenericEnvironment and
720 GitoliteEnvironment, are in fact themselves put together out of a
721 number of mixin classes, each of which handles one aspect of the
722 customization.  For the finest control over your configuration, you
723 can specify exactly which mixin classes your own environment class
724 should inherit from, and override individual methods (or even add your
725 own mixin classes) to implement entirely new behaviors.  If you
726 implement any mixins that might be useful to other people, please
727 consider sharing them with the community!
728
729
730 Getting involved
731 ----------------
732
733 Please, read `<CONTRIBUTING.rst>`__ for instructions on how to
734 contribute to git-multimail.
735
736
737 Footnotes
738 ---------
739
740 .. [1] Because of the way information is passed to update hooks, the
741        script's method of determining whether a commit has already
742        been seen does not work when it is used as an ``update`` script.
743        In particular, no notification email will be generated for a
744        new commit that is added to multiple references in the same
745        push. A workaround is to use --force-send to force sending the
746        emails.
747
748 .. _gitolite: https://github.com/sitaramc/gitolite