Merge branch 'ma/doc-diff-usage-fix'
[git/git.git] / contrib / hooks / multimail / README.rst
1 git-multimail version 1.5.0
2 ===========================
4 .. image::
5 :target:
7 git-multimail is a tool for sending notification emails on pushes to a
8 Git repository. It includes a Python module called ````,
9 which can either be used as a hook script directly or can be imported
10 as a Python module into another script.
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.
18 git-multimail, like the rest of the Git project, is licensed under
19 GPLv2 (see the COPYING file for details).
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.
27 By default, for each push received by the repository, git-multimail:
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.
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::
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
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.
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.
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.
74 Requirements
75 ------------
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).
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.)
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.
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.
97 Invocation
98 ----------
100 ```` 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.
107 For use on pre-v1.5.1 Git servers, ```` 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]_.
113 Alternatively, ```` 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
119 * change how the user who did the push is determined
121 * read users' email addresses from an LDAP server or from a database
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)
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 ```` as a Python module. (If you make interesting
130 changes of this type, please consider sharing them with the
131 community.)
134 Troubleshooting/FAQ
135 -------------------
137 Please read `<doc/troubleshooting.rst>`__ for frequently asked
138 questions and common issues with git-multimail.
141 Configuration
142 -------------
144 By default, git-multimail mostly takes its configuration from the
145 following ``git config`` settings:
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:
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.
157 gitolite
158 Environment to use when ``git-multimail`` is ran as a gitolite_
159 hook.
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).
165 For more information about gitolite and git-multimail, read
166 `<doc/gitolite.rst>`__
168 stash
169 Environment to use when ``git-multimail`` is ran as an Atlassian
170 BitBucket Server (formerly known as Atlassian Stash) hook.
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.
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.
182 gerrit
183 Environment to use when ``git-multimail`` is ran as a
184 ``ref-updated`` Gerrit hook.
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.
194 For more information about gerrit and git-multimail, read
195 `<doc/gerrit.rst>`__
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.
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:
207 * If stash-specific (respectively gerrit-specific) command flags
208 are present on the command-line, then ``stash`` (respectively
209 ``gerrit``) is used.
211 * If the environment variables $GL_USER and $GL_REPO are set, then
212 ``gitolite`` is used.
214 * If none of the above apply, then ``generic`` is used.
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.
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.
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.
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.
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.
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.
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.
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).
279 By default, all the message is HTML-escaped. See
280 ``multimailhook.htmlInIntro`` to change this behavior.
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).
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.
294 For example, a suitable value for the git-multimail project itself
295 would be
296 ````.
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.
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.
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.
312 Read `<doc/customizing-emails.rst>`__ for more details and
313 examples.
315 multimailhook.refchangeShowGraph
316 If this option is set to true, then summary emails about reference
317 changes will additionally include:
319 * a graph of the added commits (if any)
321 * a graph of the discarded commits (if any)
323 The log is generated by running ``git log --graph`` with the options
324 specified in graphOpts. The default is false.
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.
333 multimailhook.mailer
334 This option changes the way emails are sent. Accepted values are:
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:
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.::
345 git config multimailhook.sendmailcommand '/usr/sbin/sendmail -oi -t -F \"Git Repo\"'
347 Default is '/usr/sbin/sendmail -oi -t' or
348 '/usr/lib/sendmail -oi -t' (depending on which file is
349 present and executable).
351 multimailhook.envelopeSender
352 If set then pass this value to sendmail via the -f option to set
353 the envelope sender address.
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:
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 ````. Default is 'localhost' using port 25.
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.
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.
375 multimailhook.smtpServerTimeout
376 Timeout in seconds. Default is 10.
378 multimailhook.smtpEncryption
379 Set the security type. Allowed values: ``none``, ``ssl``, ``tls`` (starttls).
380 Default is ``none``.
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::
393 cd /usr/local/share/ca-certificates/
394 openssl s_client -starttls smtp \
395 -connect -showcerts \
396 </dev/null 2>/dev/null \
397 | openssl x509 -outform PEM >
398 update-ca-certificates
400 and used the updated ``/etc/ssl/certs/ca-certificates.crt``. Or
401 directly use your ``/path/to/``. Default is
402 unset.
404 multimailhook.smtpServerDebugLevel
405 Integer number. Set to greater than 0 to activate debugging.
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.
413 The value for these variables can be either:
415 - An email address, which will be used directly.
417 - The value ``pusher``, in which case the pusher's address (if
418 available) will be used.
420 - The value ``author`` (meaningful only for ``fromCommit``), in which
421 case the commit author's address will be used.
423 If config values are unset, the value of the From: header is
424 determined as follows:
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::
432 username Firstname Lastname <>
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.
438 1.b) Parse gitolite.conf, looking for a block of comments that
439 looks like this::
442 # username Firstname Lastname <>
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.
450 2. If the configuration setting is set, use its value
451 (and the value of, if set).
453 3. Use the value of multimailhook.envelopeSender.
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.
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.
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.
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.
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.
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.
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.
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).
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`.
519 This option is ineffective with Python 3, where non-UTF-8
520 characters are unconditionally replaced.
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.
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'.
535 Shell quoting is allowed; see logOpts for details.
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.
543 Shell quoting is allowed; for example, a log format that contains
544 spaces can be specified using something like::
546 git config multimailhook.logopts '--pretty=format:"%h %aN <%aE>%n%s%n%n%b%n"'
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)::
552 [multimailhook]
553 logopts = --pretty=format:\"%h %aN <%aE>%n%s%n%n%b%n\"
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.
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.
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.
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.
586 The default is ``pusher`` for refchange emails, and ``author`` for
587 commit emails.
589 multimailhook.quiet
590 Do not output the list of email recipients from the hook
592 multimailhook.stdout
593 For debugging, send emails to stdout rather than to the
594 mailer. Equivalent to the --stdout command line option
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
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
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.
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).
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``).
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.
646 These variables can be multi-valued, like::
648 [multimailhook]
649 refFilterExclusionRegex = ^refs/tags/
650 refFilterExclusionRegex = ^refs/heads/master$
652 You can also provide a whitespace-separated list like::
654 [multimailhook]
655 refFilterExclusionRegex = ^refs/tags/ ^refs/heads/master$
657 Both examples exclude tags and the master branch, and are
658 equivalent to::
660 [multimailhook]
661 refFilterExclusionRegex = ^refs/tags/|^refs/heads/master$
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.
669 multimailhook.logFile, multimailhook.errorLogFile, multimailhook.debugLogFile
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).
680 Relative path are relative to the Git repository where the push is
681 done.
683 multimailhook.verbose
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.
689 Email filtering aids
690 --------------------
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``.
699 Customizing email contents
700 --------------------------
702 git-multimail mostly generates emails by expanding templates. The
703 templates can be customized. To avoid the need to edit
704 ```` directly, the preferred way to change the templates
705 is to write a separate Python script that imports ```` 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.
710 Customizing git-multimail for your environment
711 ----------------------------------------------
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:
717 GenericEnvironment
718 a stand-alone Git repository.
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).
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.
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 ```` 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()``.
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!
756 Getting involved
757 ----------------
759 Please, read `<CONTRIBUTING.rst>`__ for instructions on how to
760 contribute to git-multimail.
763 Footnotes
764 ---------
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.
774 .. _gitolite: