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