Merge branch 'jk/config-type-color-ends-with-lf'
[git/git.git] / contrib / hooks / multimail / README.rst
CommitLineData
99177b34 1git-multimail version 1.5.0
7c554311 2===========================
5b1d901c
MM
3
4.. image:: https://travis-ci.org/git-multimail/git-multimail.svg?branch=master
5 :target: https://travis-ci.org/git-multimail/git-multimail
bc501f69
MH
6
7git-multimail is a tool for sending notification emails on pushes to a
7c554311 8Git repository. It includes a Python module called ``git_multimail.py``,
bc501f69
MH
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
99177b34
MM
23git-multimail takes place in its own, separate project. Please, read
24`<CONTRIBUTING.rst>`__ for more information.
bc501f69
MH
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.,
5b1d901c
MM
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
bc501f69 55
4b1fd356
MM
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.
bc501f69
MH
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
4b1fd356
MM
78 are required. git-multimail has preliminary support for Python 3
79 (but it has been better tested with Python 2).
bc501f69 80
5b1d901c 81* The ``git`` command must be in your PATH. git-multimail is known to
bc501f69
MH
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
b513f71f
MH
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
bc501f69
MH
90 configure git-multimail to send emails via an SMTP server.
91
99177b34
MM
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
bc501f69
MH
96
97Invocation
98----------
99
7c554311 100``git_multimail.py`` is designed to be used as a ``post-receive`` hook in a
bc501f69
MH
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
7c554311 107For use on pre-v1.5.1 Git servers, ``git_multimail.py`` can also work as
5b1d901c 108an ``update`` hook, taking its arguments on the command line. To use
bc501f69
MH
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
7c554311 111[1]_.
bc501f69 112
7c554311 113Alternatively, ``git_multimail.py`` can be imported as a Python module
bc501f69
MH
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
5b1d901c 128class. The ``post-receive`` script in this directory demonstrates how
7c554311 129to use ``git_multimail.py`` as a Python module. (If you make interesting
bc501f69
MH
130changes of this type, please consider sharing them with the
131community.)
132
133
4453d76c
MM
134Troubleshooting/FAQ
135-------------------
136
137Please read `<doc/troubleshooting.rst>`__ for frequently asked
138questions and common issues with git-multimail.
139
140
bc501f69
MH
141Configuration
142-------------
143
144By default, git-multimail mostly takes its configuration from the
5b1d901c 145following ``git config`` settings:
bc501f69
MH
146
147multimailhook.environment
4b1fd356
MM
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.
bc501f69
MH
151 Currently supported values:
152
4453d76c 153 generic
5b1d901c
MM
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
4453d76c 157 gitolite
7c554311
MM
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
5b1d901c
MM
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
4b1fd356
MM
166 `<doc/gitolite.rst>`__
167
4453d76c 168 stash
4b1fd356
MM
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
4453d76c 182 gerrit
4b1fd356
MM
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>`__
bc501f69 196
4b1fd356
MM
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
bc501f69
MH
200 post-receive script.
201
202 The environment value can be specified on the command line using
4b1fd356
MM
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.
bc501f69
MH
215
216multimailhook.repoName
bc501f69
MH
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
b513f71f 222multimailhook.mailingList
bc501f69
MH
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
bc501f69
MH
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
4b1fd356
MM
235 multimailhook.mailingList. Set this value to "none" (or the empty
236 string) to prevent reference change emails from being sent even if
b513f71f 237 multimailhook.mailingList is set.
bc501f69
MH
238
239multimailhook.announceList
bc501f69
MH
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
b513f71f 243 default is the value in multimailhook.refchangeList or
4b1fd356
MM
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.
bc501f69
MH
247
248multimailhook.commitList
bc501f69
MH
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
b513f71f 252 default is the value in multimailhook.mailingList. Set this value
4b1fd356 253 to "none" (or the empty string) to prevent notification emails about
b513f71f
MH
254 individual commits from being sent even if
255 multimailhook.mailingList is set.
bc501f69
MH
256
257multimailhook.announceShortlog
bc501f69
MH
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
4b1fd356 266multimailhook.commitEmailFormat
4b1fd356
MM
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
4453d76c
MM
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
2e3a16b2 304 Set ``multimailhook.htmlInIntro`` to true to allow writing HTML
4453d76c
MM
305 formatting in introduction templates. Similarly, set
306 ``multimailhook.htmlInFooter`` for HTML in the footer.
5b1d901c 307
4453d76c
MM
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
5b1d901c
MM
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
bc501f69 326multimailhook.refchangeShowLog
bc501f69
MH
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
5b1d901c 330 ``git log`` with the options specified in multimailhook.logOpts.
bc501f69
MH
331 Default is false.
332
333multimailhook.mailer
bc501f69
MH
334 This option changes the way emails are sent. Accepted values are:
335
4453d76c 336 * **sendmail (the default)**: use the command ``/usr/sbin/sendmail`` or
5b1d901c 337 ``/usr/lib/sendmail`` (or sendmailCommand, if configured). This
bc501f69
MH
338 mode can be further customized via the following options:
339
4453d76c
MM
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.::
bc501f69 344
4453d76c 345 git config multimailhook.sendmailcommand '/usr/sbin/sendmail -oi -t -F \"Git Repo\"'
bc501f69 346
4453d76c
MM
347 Default is '/usr/sbin/sendmail -oi -t' or
348 '/usr/lib/sendmail -oi -t' (depending on which file is
349 present and executable).
bc501f69 350
4453d76c
MM
351 multimailhook.envelopeSender
352 If set then pass this value to sendmail via the -f option to set
353 the envelope sender address.
bc501f69 354
4453d76c 355 * **smtp**: use Python's smtplib. This is useful when the sendmail
bc501f69
MH
356 command is not available on the system. This mode can be
357 further customized via the following options:
358
4453d76c
MM
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.
5b1d901c 363
4453d76c
MM
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.
5b1d901c 370
4453d76c 371 multimailhook.envelopeSender
5b1d901c
MM
372 The sender address to be passed to the SMTP server. If
373 unset, then the value of multimailhook.from is used.
374
4453d76c 375 multimailhook.smtpServerTimeout
99177b34 376 Timeout in seconds. Default is 10.
bc501f69 377
4453d76c
MM
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
5b1d901c 405 Integer number. Set to greater than 0 to activate debugging.
bc501f69 406
4453d76c 407multimailhook.from, multimailhook.fromCommit, multimailhook.fromRefchange
4b1fd356
MM
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.
bc501f69 419
4453d76c 420 - The value ``author`` (meaningful only for ``fromCommit``), in which
4b1fd356
MM
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:
5b1d901c 425
99177b34
MM
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::
5b1d901c
MM
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.
bc501f69 454
99177b34
MM
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
bc501f69 460multimailhook.administrator
bc501f69
MH
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
bc501f69
MH
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
5b1d901c 470 the repository in square brackets; e.g., ``[myrepo]``. Set this
7c554311
MM
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.
bc501f69
MH
474
475multimailhook.emailMaxLines
bc501f69
MH
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
bc501f69 482 The maximum length of a line in the email body. Lines longer than
4453d76c 483 this limit are truncated to this length with a trailing ``[...]``
bc501f69
MH
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
7c554311
MM
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
bc501f69 501multimailhook.maxCommitEmails
bc501f69
MH
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
99177b34
MM
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
bc501f69 513multimailhook.emailStrictUTF8
5b1d901c 514 If this boolean option is set to `true`, then the main part of the
bc501f69
MH
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
5b1d901c 517 character, U+FFFD. The default is `true`.
bc501f69 518
7c554311
MM
519 This option is ineffective with Python 3, where non-UTF-8
520 characters are unconditionally replaced.
521
bc501f69 522multimailhook.diffOpts
5b1d901c
MM
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
bc501f69 526 include a unified diff of changes in addition to the usual summary
7c554311 527 output. Shell quoting is allowed; see ``multimailhook.logOpts`` for
bc501f69
MH
528 details.
529
5b1d901c 530multimailhook.graphOpts
5b1d901c
MM
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
bc501f69 537multimailhook.logOpts
5b1d901c 538 Options passed to ``git log`` to generate additional info for
bc501f69 539 reference change emails (used only if refchangeShowLog is set).
5b1d901c
MM
540 For example, adding -p will show each commit's complete diff. The
541 default is empty.
bc501f69
MH
542
543 Shell quoting is allowed; for example, a log format that contains
5b1d901c 544 spaces can be specified using something like::
bc501f69
MH
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
5b1d901c 550 (see git-config(1) for more information)::
bc501f69
MH
551
552 [multimailhook]
553 logopts = --pretty=format:\"%h %aN <%aE>%n%s%n%n%b%n\"
554
b513f71f 555multimailhook.commitLogOpts
5b1d901c 556 Options passed to ``git log`` to generate additional info for
b513f71f 557 revision change emails. For example, adding --ignore-all-spaces
5b1d901c
MM
558 will suppress whitespace changes. The default options are ``-C
559 --stat -p --cc``. Shell quoting is allowed; see
b513f71f
MH
560 multimailhook.logOpts for details.
561
4b1fd356 562multimailhook.dateSubstitute
4b1fd356 563 String to use as a substitute for ``Date:`` in the output of ``git
2e3a16b2 564 log`` while formatting commit messages. This is useful to avoid
4b1fd356
MM
565 emitting a line that can be interpreted by mailers as the start of
566 a cited message (Zimbra webmail in particular). Defaults to
4453d76c 567 ``CommitDate:``. Set to an empty string or ``none`` to deactivate
4b1fd356
MM
568 the behavior.
569
bc501f69 570multimailhook.emailDomain
bc501f69 571 Domain name appended to the username of the person doing the push
5b1d901c
MM
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.
bc501f69 576
4453d76c 577multimailhook.replyTo, multimailhook.replyToCommit, multimailhook.replyToRefchange
bc501f69
MH
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
4b1fd356
MM
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.
bc501f69 585
4b1fd356
MM
586 The default is ``pusher`` for refchange emails, and ``author`` for
587 commit emails.
bc501f69 588
5b1d901c 589multimailhook.quiet
5b1d901c
MM
590 Do not output the list of email recipients from the hook
591
592multimailhook.stdout
5b1d901c
MM
593 For debugging, send emails to stdout rather than to the
594 mailer. Equivalent to the --stdout command line option
595
596multimailhook.scanCommitForCc
5b1d901c
MM
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
5b1d901c
MM
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
4453d76c 607multimailhook.refFilterInclusionRegex, multimailhook.refFilterExclusionRegex, multimailhook.refFilterDoSendRegex, multimailhook.refFilterDontSendRegex
4b1fd356
MM
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.
7c554311
MM
612 If you are happy with the current shape of the feature, please
613 report it too.
4b1fd356
MM
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$
bc501f69 662
7c554311
MM
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
bc501f69
MH
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
5b1d901c
MM
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``.
bc501f69
MH
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
7c554311
MM
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
bc501f69
MH
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
4453d76c
MM
717GenericEnvironment
718 a stand-alone Git repository.
bc501f69 719
4453d76c 720GitoliteEnvironment
7c554311
MM
721 a Git repository that is managed by gitolite_. For such
722 repositories, the identity of the pusher is read from
4453d76c
MM
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).
bc501f69
MH
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
5b1d901c
MM
731by setting a ``multimailhook.environment`` config setting (which can
732have the value `generic` or `gitolite`) or by passing an --environment
bc501f69
MH
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
7c554311 738``git_multimail.py`` as a Python module, as demonstrated by the example
bc501f69
MH
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
5b1d901c
MM
742``environment`` variable to an instance of your own environment class
743and pass it to ``run_as_post_receive_hook()``.
bc501f69
MH
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
4b1fd356
MM
759Please, read `<CONTRIBUTING.rst>`__ for instructions on how to
760contribute to git-multimail.
bc501f69
MH
761
762
763Footnotes
764---------
765
7c554311 766.. [1] Because of the way information is passed to update hooks, the
5b1d901c
MM
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.
bc501f69 773
7c554311 774.. _gitolite: https://github.com/sitaramc/gitolite