1git-multimail is close to, but not exactly, a plug-in replacement for
2the old Git project script contrib/hooks/post-receive-email. This
3document describes the differences and explains how to configure
4git-multimail to get behavior closest to that of post-receive-email.
5
6If you are in a hurry
7=====================
8
9A script called migrate-mailhook-config is included with
10git-multimail. If you run this script within a Git repository that is
11configured to use post-receive-email, it will convert the
12configuration settings into the approximate equivalent settings for
13git-multimail. For more information, run
14
15 migrate-mailhook-config --help
16
17
18Configuration differences
19=========================
20
21* The names of the config options for git-multimail are in namespace
22 "multimailhook.*" instead of "hooks.*". (Editorial comment:
23 post-receive-email should never have used such a generic top-level
24 namespace.)
25
26* In emails about new annotated tags, post-receive-email includes a
27 shortlog of all changes since the previous annotated tag. To get
28 this behavior with git-multimail, you need to set
29 multimailhook.announceshortlog to true:
30
31 git config multimailhook.announceshortlog true
32
33* multimailhook.commitlist -- This is a new configuration variable.
34 Recipients listed here will receive a separate email for each new
35 commit. However, if this variable is *not* set, it defaults to the
36 value of multimailhook.mailinglist. Therefore, if you *don't* want
37 the members of multimailhook.mailinglist to receive one email per
38 commit, then set this value to the empty string:
39
40 git config multimailhook.commitlist ''
41
42* multimailhook.emailprefix -- If this value is not set, then the
43 subjects of generated emails are prefixed with the short name of the
44 repository enclosed in square brackets; e.g., "[myrepo]".
45 post-receive-email defaults to prefix "[SCM]" if this option is not
46 set. So if you were using the old default and want to retain it
47 (for example, to avoid having to change your email filters), set
48 this variable explicitly to the old value:
49
50 git config multimailhook.emailprefix "[SCM]"
51
52* The "multimailhook.showrev" configuration option is not supported.
53 Its main use is obsoleted by the one-email-per-commit feature of
54 git-multimail.
55
56
57Other differences
58=================
59
60This section describes other differences in the behavior of
61git-multimail vs. post-receive-email. For full details, please refer
62to the main README file:
63
64* One email per commit. For each reference change, the script first
65 outputs one email summarizing the reference change (including
66 one-line summaries of the new commits), then it outputs a separate
67 email for each new commit that was introduced, including patches.
68 These one-email-per-commit emails go to the addresses listed in
69 multimailhook.commitlist. post-receive-email sends only one email
70 for each *reference* that is changed, no matter how many commits
71 were added to the reference.
72
73* Better algorithm for detecting new commits. post-receive-email
74 processes one reference change at a time, which causes it to fail to
75 describe new commits that were included in multiple branches. For
76 example, if a single push adds the "*" commits in the diagram below,
77 then post-receive-email would never include the details of the two
78 commits that are common to "master" and "branch" in its
79 notifications.
80
81 o---o---o---*---*---* <-- master
82 \
83 *---* <-- branch
84
85 git-multimail analyzes all reference modifications to determine
86 which commits were not present before the change, therefore avoiding
87 that error.
88
89* In reference change emails, git-multimail tells which commits have
90 been added to the reference vs. are entirely new to the repository,
91 and which commits that have been omitted from the reference
92 vs. entirely discarded from the repository.
93
94* The environment in which Git is running can be configured via an
95 "Environment" abstraction.
96
97* Built-in support for Gitolite-managed repositories.
98
99* Instead of using full SHA1 object names in emails, git-multimail
100 mostly uses abbreviated SHA1s, plus one-line log message summaries
101 where appropriate.
102
103* In the schematic diagrams that explain non-fast-forward commits,
104 git-multimail shows the names of the branches involved.
105
106* The emails generated by git-multimail include the name of the Git
107 repository that was modified; this is convenient for recipients who
108 are monitoring multiple repositories.
109
110* git-multimail allows the email "From" addresses to be configured.
111
112* The recipients lists (multimailhook.mailinglist,
113 multimailhook.refchangelist, multimailhook.announcelist, and
114 multimailhook.commitlist) can be comma-separated values and/or
115 multivalued settings in the config file; e.g.,
116
117 [multimailhook]
118 mailinglist = mr.brown@example.com, mr.black@example.com
119 announcelist = Him <him@example.com>
120 announcelist = Jim <jim@example.com>
121 announcelist = pop@example.com
122
123 This might make it easier to maintain short recipients lists without
124 requiring full-fledged mailing list software.
125
126* By default, git-multimail sets email "Reply-To" headers to reply to
127 the pusher (for reference updates) and to the author (for commit
128 notifications). By default, the pusher's email address is
129 constructed by appending "multimailhook.emaildomain" to the pusher's
130 username.
131
132* The generated emails contain a configurable footer. By default, it
133 lists the name of the administrator who should be contacted to
134 unsubscribe from notification emails.
135
136* New option multimailhook.emailmaxlinelength to limit the length of
137 lines in the main part of the email body. The default limit is 500
138 characters.
139
140* New option multimailhook.emailstrictutf8 to ensure that the main
141 part of the email body is valid UTF-8. Invalid characters are
142 turned into the Unicode replacement character, U+FFFD. By default
143 this option is turned on.
144
145* Written in Python. Easier to add new features.
146
1git-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
7git-multimail is a tool for sending notification emails on pushes to a
8Git repository. It includes a Python module called ``git_multimail.py``,
9which can either be used as a hook script directly or can be imported
10as a Python module into another script.
11
12git-multimail is derived from the Git project's old
13contrib/hooks/post-receive-email, and is mostly compatible with that
14script. See README.migrate-from-post-receive-email for details about
15the differences and for how to migrate from post-receive-email to
16git-multimail.
17
18git-multimail, like the rest of the Git project, is licensed under
19GPLv2 (see the COPYING file for details).
20
21Please note: although, as a convenience, git-multimail may be
22distributed along with the main Git project, development of
23git-multimail takes place in its own, separate project. Please, read
24`<CONTRIBUTING.rst>`__ for more information.
25
26
27By default, for each push received by the repository, git-multimail:
28
291. 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
352. 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
683. 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
74Requirements
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
97Invocation
98----------
99
100``git_multimail.py`` is designed to be used as a ``post-receive`` hook in a
101Git repository (see githooks(5)). Link or copy it to
102$GIT_DIR/hooks/post-receive within the repository for which email
103notifications are desired. Usually it should be installed on the
104central repository for a project, to which all commits are eventually
105pushed.
106
107For use on pre-v1.5.1 Git servers, ``git_multimail.py`` can also work as
108an ``update`` hook, taking its arguments on the command line. To use
109this script in this manner, link or copy it to $GIT_DIR/hooks/update.
110Please note that the script is not completely reliable in this mode
111[1]_.
112
113Alternatively, ``git_multimail.py`` can be imported as a Python module
114into your own Python post-receive script. This method is a bit more
115work, but allows the behavior of the hook to be customized using
116arbitrary 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
127Or you can change how emails are sent by writing your own Mailer
128class. The ``post-receive`` script in this directory demonstrates how
129to use ``git_multimail.py`` as a Python module. (If you make interesting
130changes of this type, please consider sharing them with the
131community.)
132
133
134Troubleshooting/FAQ
135-------------------
136
137Please read `<doc/troubleshooting.rst>`__ for frequently asked
138questions and common issues with git-multimail.
139
140
141Configuration
142-------------
143
144By default, git-multimail mostly takes its configuration from the
145following ``git config`` settings:
146
147multimailhook.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
216multimailhook.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
222multimailhook.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
230multimailhook.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
239multimailhook.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
248multimailhook.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
257multimailhook.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
266multimailhook.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
282multimailhook.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
298multimailhook.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
315multimailhook.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
326multimailhook.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
333multimailhook.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
407multimailhook.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
455multimailhook.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
460multimailhook.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
466multimailhook.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
475multimailhook.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
481multimailhook.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
490multimailhook.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
501multimailhook.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
508multimailhook.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
513multimailhook.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
522multimailhook.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
530multimailhook.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
537multimailhook.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
555multimailhook.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
562multimailhook.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
570multimailhook.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
577multimailhook.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
589multimailhook.quiet
590 Do not output the list of email recipients from the hook
591
592multimailhook.stdout
593 For debugging, send emails to stdout rather than to the
594 mailer. Equivalent to the --stdout command line option
595
596multimailhook.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
601multimailhook.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
607multimailhook.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
669multimailhook.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
683multimailhook.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
689Email filtering aids
690--------------------
691
692All emails include extra headers to enable fine tuned filtering and
693give information for debugging. All emails include the headers
694``X-Git-Host``, ``X-Git-Repo``, ``X-Git-Refname``, and ``X-Git-Reftype``.
695ReferenceChange emails also include headers ``X-Git-Oldrev`` and ``X-Git-Newrev``;
696Revision emails also include header ``X-Git-Rev``.
697
698
699Customizing email contents
700--------------------------
701
702git-multimail mostly generates emails by expanding templates. The
703templates can be customized. To avoid the need to edit
704``git_multimail.py`` directly, the preferred way to change the templates
705is to write a separate Python script that imports ``git_multimail.py`` as
706a module, then replaces the templates in place. See the provided
707post-receive script for an example of how this is done.
708
709
710Customizing git-multimail for your environment
711----------------------------------------------
712
713git-multimail is mostly customized via an "environment" that describes
714the local environment in which Git is running. Two types of
715environment are built in:
716
717GenericEnvironment
718 a stand-alone Git repository.
719
720GitoliteEnvironment
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
728By default, git-multimail assumes GitoliteEnvironment if $GL_USER and
729$GL_REPO are set, and otherwise assumes GenericEnvironment.
730Alternatively, you can choose one of these two environments explicitly
731by setting a ``multimailhook.environment`` config setting (which can
732have the value `generic` or `gitolite`) or by passing an --environment
733option to the script.
734
735If you need to customize the script in ways that are not supported by
736the existing environments, you can define your own environment class
737class using arbitrary Python code. To do so, you need to import
738``git_multimail.py`` as a Python module, as demonstrated by the example
739post-receive script. Then implement your environment class; it should
740usually inherit from one of the existing Environment classes and
741possibly one or more of the EnvironmentMixin classes. Then set the
742``environment`` variable to an instance of your own environment class
743and pass it to ``run_as_post_receive_hook()``.
744
745The standard environment classes, GenericEnvironment and
746GitoliteEnvironment, are in fact themselves put together out of a
747number of mixin classes, each of which handles one aspect of the
748customization. For the finest control over your configuration, you
749can specify exactly which mixin classes your own environment class
750should inherit from, and override individual methods (or even add your
751own mixin classes) to implement entirely new behaviors. If you
752implement any mixins that might be useful to other people, please
753consider sharing them with the community!
754
755
756Getting involved
757----------------
758
759Please, read `<CONTRIBUTING.rst>`__ for instructions on how to
760contribute to git-multimail.
761
762
763Footnotes
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
775
