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