Merge branch 'maint-2.4' into maint-2.5
[git] / contrib / hooks / multimail / README
1 git-multimail Version 1.1.1
2 ===========================
3
4 .. image:: https://travis-ci.org/git-multimail/git-multimail.svg?branch=master
5     :target: https://travis-ci.org/git-multimail/git-multimail
6
7 git-multimail is a tool for sending notification emails on pushes to a
8 Git repository.  It includes a Python module called git_multimail.py,
9 which can either be used as a hook script directly or can be imported
10 as a Python module into another script.
11
12 git-multimail is derived from the Git project's old
13 contrib/hooks/post-receive-email, and is mostly compatible with that
14 script.  See README.migrate-from-post-receive-email for details about
15 the differences and for how to migrate from post-receive-email to
16 git-multimail.
17
18 git-multimail, like the rest of the Git project, is licensed under
19 GPLv2 (see the COPYING file for details).
20
21 Please note: although, as a convenience, git-multimail may be
22 distributed along with the main Git project, development of
23 git-multimail takes place in its own, separate project.  See section
24 "Getting involved" below for more information.
25
26
27 By default, for each push received by the repository, git-multimail:
28
29 1. Outputs one email summarizing each reference that was changed.
30    These "reference change" (called "refchange" below) emails describe
31    the nature of the change (e.g., was the reference created, deleted,
32    fast-forwarded, etc.) and include a one-line summary of each commit
33    that was added to the reference.
34
35 2. Outputs one email for each new commit that was introduced by the
36    reference change.  These "commit" emails include a list of the
37    files changed by the commit, followed by the diffs of files
38    modified by the commit.  The commit emails are threaded to the
39    corresponding reference change email via "In-Reply-To".  This style
40    (similar to the "git format-patch" style used on the Git mailing
41    list) makes it easy to scan through the emails, jump to patches
42    that need further attention, and write comments about specific
43    commits.  Commits are handled in reverse topological order (i.e.,
44    parents shown before children).  For example::
45
46      [git] branch master updated
47      + [git] 01/08: doc: fix xref link from api docs to manual pages
48      + [git] 02/08: api-credentials.txt: show the big picture first
49      + [git] 03/08: api-credentials.txt: mention credential.helper explicitly
50      + [git] 04/08: api-credentials.txt: add "see also" section
51      + [git] 05/08: t3510 (cherry-pick-sequence): add missing '&&'
52      + [git] 06/08: Merge branch 'rr/maint-t3510-cascade-fix'
53      + [git] 07/08: Merge branch 'mm/api-credentials-doc'
54      + [git] 08/08: Git 1.7.11-rc2
55
56    Each commit appears in exactly one commit email, the first time
57    that it is pushed to the repository.  If a commit is later merged
58    into another branch, then a one-line summary of the commit is
59    included in the reference change email (as usual), but no
60    additional commit email is generated.
61
62    By default, reference change emails have their "Reply-To" field set
63    to the person who pushed the change, and commit emails have their
64    "Reply-To" field set to the author of the commit.
65
66 3. Output one "announce" mail for each new annotated tag, including
67    information about the tag and optionally a shortlog describing the
68    changes since the previous tag.  Such emails might be useful if you
69    use annotated tags to mark releases of your project.
70
71
72 Requirements
73 ------------
74
75 * Python 2.x, version 2.4 or later.  No non-standard Python modules
76   are required.  git-multimail does *not* currently work with Python
77   3.x.
78
79   The example scripts invoke Python using the following shebang line
80   (following PEP 394 [1]_)::
81
82       #! /usr/bin/env python2
83
84   If your system's Python2 interpreter is not in your PATH or is not
85   called ``python2``, you can change the lines accordingly.  Or you can
86   invoke the Python interpreter explicitly, for example via a tiny
87   shell script like::
88
89       #! /bin/sh
90       /usr/local/bin/python /path/to/git_multimail.py "$@"
91
92 * The ``git`` command must be in your PATH.  git-multimail is known to
93   work with Git versions back to 1.7.1.  (Earlier versions have not
94   been tested; if you do so, please report your results.)
95
96 * To send emails using the default configuration, a standard sendmail
97   program must be located at '/usr/sbin/sendmail' or
98   '/usr/lib/sendmail' and must be configured correctly to send emails.
99   If this is not the case, set multimailhook.sendmailCommand, or see
100   the multimailhook.mailer configuration variable below for how to
101   configure git-multimail to send emails via an SMTP server.
102
103
104 Invocation
105 ----------
106
107 git_multimail.py is designed to be used as a ``post-receive`` hook in a
108 Git repository (see githooks(5)).  Link or copy it to
109 $GIT_DIR/hooks/post-receive within the repository for which email
110 notifications are desired.  Usually it should be installed on the
111 central repository for a project, to which all commits are eventually
112 pushed.
113
114 For use on pre-v1.5.1 Git servers, git_multimail.py can also work as
115 an ``update`` hook, taking its arguments on the command line.  To use
116 this script in this manner, link or copy it to $GIT_DIR/hooks/update.
117 Please note that the script is not completely reliable in this mode
118 [2]_.
119
120 Alternatively, git_multimail.py can be imported as a Python module
121 into your own Python post-receive script.  This method is a bit more
122 work, but allows the behavior of the hook to be customized using
123 arbitrary Python code.  For example, you can use a custom environment
124 (perhaps inheriting from GenericEnvironment or GitoliteEnvironment) to
125
126 * change how the user who did the push is determined
127
128 * read users' email addresses from an LDAP server or from a database
129
130 * decide which users should be notified about which commits based on
131   the contents of the commits (e.g., for users who want to be notified
132   only about changes affecting particular files or subdirectories)
133
134 Or you can change how emails are sent by writing your own Mailer
135 class.  The ``post-receive`` script in this directory demonstrates how
136 to use git_multimail.py as a Python module.  (If you make interesting
137 changes of this type, please consider sharing them with the
138 community.)
139
140
141 Configuration
142 -------------
143
144 By default, git-multimail mostly takes its configuration from the
145 following ``git config`` settings:
146
147 multimailhook.environment
148
149     This describes the general environment of the repository.
150     Currently supported values:
151
152     * generic
153
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
159       the username of the pusher is read from $GL_USER, the repository
160       name is read from $GL_REPO, and the From: header value is
161       optionally read from gitolite.conf (see multimailhook.from).
162
163       For more information about gitolite and git-multimail, read
164       doc/gitolite.rst
165
166     If neither of these environments is suitable for your setup, then
167     you can implement a Python class that inherits from Environment
168     and instantiate it via a script that looks like the example
169     post-receive script.
170
171     The environment value can be specified on the command line using
172     the --environment option.  If it is not specified on the command
173     line or by multimailhook.environment, then it defaults to
174     ``gitolite`` if the environment contains variables $GL_USER and
175     $GL_REPO; otherwise ``generic``.
176
177 multimailhook.repoName
178
179     A short name of this Git repository, to be used in various places
180     in the notification email text.  The default is to use $GL_REPO
181     for gitolite repositories, or otherwise to derive this value from
182     the repository path name.
183
184 multimailhook.mailingList
185
186     The list of email addresses to which notification emails should be
187     sent, as RFC 2822 email addresses separated by commas.  This
188     configuration option can be multivalued.  Leave it unset or set it
189     to the empty string to not send emails by default.  The next few
190     settings can be used to configure specific address lists for
191     specific types of notification email.
192
193 multimailhook.refchangeList
194
195     The list of email addresses to which summary emails about
196     reference changes should be sent, as RFC 2822 email addresses
197     separated by commas.  This configuration option can be
198     multivalued.  The default is the value in
199     multimailhook.mailingList.  Set this value to the empty string to
200     prevent reference change emails from being sent even if
201     multimailhook.mailingList is set.
202
203 multimailhook.announceList
204
205     The list of email addresses to which emails about new annotated
206     tags should be sent, as RFC 2822 email addresses separated by
207     commas.  This configuration option can be multivalued.  The
208     default is the value in multimailhook.refchangeList or
209     multimailhook.mailingList.  Set this value to the empty string to
210     prevent annotated tag announcement emails from being sent even if
211     one of the other values is set.
212
213 multimailhook.commitList
214
215     The list of email addresses to which emails about individual new
216     commits should be sent, as RFC 2822 email addresses separated by
217     commas.  This configuration option can be multivalued.  The
218     default is the value in multimailhook.mailingList.  Set this value
219     to the empty string to prevent notification emails about
220     individual commits from being sent even if
221     multimailhook.mailingList is set.
222
223 multimailhook.announceShortlog
224
225     If this option is set to true, then emails about changes to
226     annotated tags include a shortlog of changes since the previous
227     tag.  This can be useful if the annotated tags represent releases;
228     then the shortlog will be a kind of rough summary of what has
229     happened since the last release.  But if your tagging policy is
230     not so straightforward, then the shortlog might be confusing
231     rather than useful.  Default is false.
232
233 multimailhook.refchangeShowGraph
234
235     If this option is set to true, then summary emails about reference
236     changes will additionally include:
237
238     * a graph of the added commits (if any)
239
240     * a graph of the discarded commits (if any)
241
242     The log is generated by running ``git log --graph`` with the options
243     specified in graphOpts.  The default is false.
244
245 multimailhook.refchangeShowLog
246
247     If this option is set to true, then summary emails about reference
248     changes will include a detailed log of the added commits in
249     addition to the one line summary.  The log is generated by running
250     ``git log`` with the options specified in multimailhook.logOpts.
251     Default is false.
252
253 multimailhook.mailer
254
255     This option changes the way emails are sent.  Accepted values are:
256
257     - sendmail (the default): use the command ``/usr/sbin/sendmail`` or
258       ``/usr/lib/sendmail`` (or sendmailCommand, if configured).  This
259       mode can be further customized via the following options:
260
261       * multimailhook.sendmailCommand
262
263         The command used by mailer ``sendmail`` to send emails.  Shell
264         quoting is allowed in the value of this setting, but remember that
265         Git requires double-quotes to be escaped; e.g.::
266
267              git config multimailhook.sendmailcommand '/usr/sbin/sendmail -oi -t -F \"Git Repo\"'
268
269         Default is '/usr/sbin/sendmail -oi -t' or
270         '/usr/lib/sendmail -oi -t' (depending on which file is
271         present and executable).
272
273       * multimailhook.envelopeSender
274
275         If set then pass this value to sendmail via the -f option to set
276         the envelope sender address.
277
278     - smtp: use Python's smtplib.  This is useful when the sendmail
279       command is not available on the system.  This mode can be
280       further customized via the following options:
281
282       * multimailhook.smtpServer
283
284         The name of the SMTP server to connect to.  The value can
285         also include a colon and a port number; e.g.,
286         ``mail.example.com:25``.  Default is 'localhost' using port 25.
287
288       * multimailhook.smtpUser
289       * multimailhook.smtpPass
290
291         Server username and password. Required if smtpEncryption is 'ssl'.
292         Note that the username and password currently need to be
293         set cleartext in the configuration file, which is not
294         recommended. If you need to use this option, be sure your
295         configuration file is read-only.
296
297       * multimailhook.envelopeSender
298
299         The sender address to be passed to the SMTP server.  If
300         unset, then the value of multimailhook.from is used.
301
302       * multimailhook.smtpServerTimeout
303
304         Timeout in seconds.
305
306       * multimailhook.smtpEncryption
307
308         Set the security type. Allowed values: none, ssl.
309         Default=none.
310
311       * multimailhook.smtpServerDebugLevel
312
313         Integer number. Set to greater than 0 to activate debugging.
314
315 multimailhook.from
316
317     If set, use this value in the From: field of generated emails.  If
318     unset, the value of the From: header is determined as follows:
319
320     1. (gitolite environment only) Parse gitolite.conf, looking for a
321        block of comments that looks like this::
322
323            # BEGIN USER EMAILS
324            # username Firstname Lastname <email@example.com>
325            # END USER EMAILS
326
327        If that block exists, and there is a line between the BEGIN
328        USER EMAILS and END USER EMAILS lines where the first field
329        matches the gitolite username ($GL_USER), use the rest of the
330        line for the From: header.
331
332     2. If the user.email configuration setting is set, use its value
333        (and the value of user.name, if set).
334
335     3. Use the value of multimailhook.envelopeSender.
336
337 multimailhook.administrator
338
339     The name and/or email address of the administrator of the Git
340     repository; used in FOOTER_TEMPLATE.  Default is
341     multimailhook.envelopesender if it is set; otherwise a generic
342     string is used.
343
344 multimailhook.emailPrefix
345
346     All emails have this string prepended to their subjects, to aid
347     email filtering (though filtering based on the X-Git-* email
348     headers is probably more robust).  Default is the short name of
349     the repository in square brackets; e.g., ``[myrepo]``.  Set this
350     value to the empty string to suppress the email prefix.
351
352 multimailhook.emailMaxLines
353
354     The maximum number of lines that should be included in the body of
355     a generated email.  If not specified, there is no limit.  Lines
356     beyond the limit are suppressed and counted, and a final line is
357     added indicating the number of suppressed lines.
358
359 multimailhook.emailMaxLineLength
360
361     The maximum length of a line in the email body.  Lines longer than
362     this limit are truncated to this length with a trailing `` [...]``
363     added to indicate the missing text.  The default is 500, because
364     (a) diffs with longer lines are probably from binary files, for
365     which a diff is useless, and (b) even if a text file has such long
366     lines, the diffs are probably unreadable anyway.  To disable line
367     truncation, set this option to 0.
368
369 multimailhook.maxCommitEmails
370
371     The maximum number of commit emails to send for a given change.
372     When the number of patches is larger that this value, only the
373     summary refchange email is sent.  This can avoid accidental
374     mailbombing, for example on an initial push.  To disable commit
375     emails limit, set this option to 0.  The default is 500.
376
377 multimailhook.emailStrictUTF8
378
379     If this boolean option is set to `true`, then the main part of the
380     email body is forced to be valid UTF-8.  Any characters that are
381     not valid UTF-8 are converted to the Unicode replacement
382     character, U+FFFD.  The default is `true`.
383
384 multimailhook.diffOpts
385
386     Options passed to ``git diff-tree`` when generating the summary
387     information for ReferenceChange emails.  Default is ``--stat
388     --summary --find-copies-harder``.  Add -p to those options to
389     include a unified diff of changes in addition to the usual summary
390     output.  Shell quoting is allowed; see multimailhook.logOpts for
391     details.
392
393 multimailhook.graphOpts
394
395     Options passed to ``git log --graph`` when generating graphs for the
396     reference change summary emails (used only if refchangeShowGraph
397     is true).  The default is '--oneline --decorate'.
398
399     Shell quoting is allowed; see logOpts for details.
400
401 multimailhook.logOpts
402
403     Options passed to ``git log`` to generate additional info for
404     reference change emails (used only if refchangeShowLog is set).
405     For example, adding -p will show each commit's complete diff.  The
406     default is empty.
407
408     Shell quoting is allowed; for example, a log format that contains
409     spaces can be specified using something like::
410
411       git config multimailhook.logopts '--pretty=format:"%h %aN <%aE>%n%s%n%n%b%n"'
412
413     If you want to set this by editing your configuration file
414     directly, remember that Git requires double-quotes to be escaped
415     (see git-config(1) for more information)::
416
417       [multimailhook]
418               logopts = --pretty=format:\"%h %aN <%aE>%n%s%n%n%b%n\"
419
420 multimailhook.commitLogOpts
421
422     Options passed to ``git log`` to generate additional info for
423     revision change emails.  For example, adding --ignore-all-spaces
424     will suppress whitespace changes.  The default options are ``-C
425     --stat -p --cc``.  Shell quoting is allowed; see
426     multimailhook.logOpts for details.
427
428 multimailhook.emailDomain
429
430     Domain name appended to the username of the person doing the push
431     to convert it into an email address
432     (via ``"%s@%s" % (username, emaildomain)``). More complicated
433     schemes can be implemented by overriding Environment and
434     overriding its get_pusher_email() method.
435
436 multimailhook.replyTo
437 multimailhook.replyToCommit
438 multimailhook.replyToRefchange
439
440     Addresses to use in the Reply-To: field for commit emails
441     (replyToCommit) and refchange emails (replyToRefchange).
442     multimailhook.replyTo is used as default when replyToCommit or
443     replyToRefchange is not set.  The value for these variables can be
444     either:
445
446     - An email address, which will be used directly.
447
448     - The value `pusher`, in which case the pusher's address (if
449       available) will be used.  This is the default for refchange
450       emails.
451
452     - The value `author` (meaningful only for replyToCommit), in which
453       case the commit author's address will be used.  This is the
454       default for commit emails.
455
456     - The value `none`, in which case the Reply-To: field will be
457       omitted.
458
459 multimailhook.quiet
460
461     Do not output the list of email recipients from the hook
462
463 multimailhook.stdout
464
465     For debugging, send emails to stdout rather than to the
466     mailer.  Equivalent to the --stdout command line option
467
468 multimailhook.scanCommitForCc
469
470     If this option is set to true, than recipients from lines in commit body
471     that starts with ``CC:`` will be added to CC list.
472     Default: false
473
474 multimailhook.combineWhenSingleCommit
475
476     If this option is set to true and a single new commit is pushed to
477     a branch, combine the summary and commit email messages into a
478     single email.
479     Default: true
480
481
482 Email filtering aids
483 --------------------
484
485 All emails include extra headers to enable fine tuned filtering and
486 give information for debugging.  All emails include the headers
487 ``X-Git-Host``, ``X-Git-Repo``, ``X-Git-Refname``, and ``X-Git-Reftype``.
488 ReferenceChange emails also include headers ``X-Git-Oldrev`` and ``X-Git-Newrev``;
489 Revision emails also include header ``X-Git-Rev``.
490
491
492 Customizing email contents
493 --------------------------
494
495 git-multimail mostly generates emails by expanding templates.  The
496 templates can be customized.  To avoid the need to edit
497 git_multimail.py directly, the preferred way to change the templates
498 is to write a separate Python script that imports git_multimail.py as
499 a module, then replaces the templates in place.  See the provided
500 post-receive script for an example of how this is done.
501
502
503 Customizing git-multimail for your environment
504 ----------------------------------------------
505
506 git-multimail is mostly customized via an "environment" that describes
507 the local environment in which Git is running.  Two types of
508 environment are built in:
509
510 * GenericEnvironment: a stand-alone Git repository.
511
512 * GitoliteEnvironment: a Git repository that is managed by gitolite
513   [3]_.  For such repositories, the identity of the pusher is read from
514   environment variable $GL_USER, the name of the repository is read
515   from $GL_REPO (if it is not overridden by multimailhook.reponame),
516   and the From: header value is optionally read from gitolite.conf
517   (see multimailhook.from).
518
519 By default, git-multimail assumes GitoliteEnvironment if $GL_USER and
520 $GL_REPO are set, and otherwise assumes GenericEnvironment.
521 Alternatively, you can choose one of these two environments explicitly
522 by setting a ``multimailhook.environment`` config setting (which can
523 have the value `generic` or `gitolite`) or by passing an --environment
524 option to the script.
525
526 If you need to customize the script in ways that are not supported by
527 the existing environments, you can define your own environment class
528 class using arbitrary Python code.  To do so, you need to import
529 git_multimail.py as a Python module, as demonstrated by the example
530 post-receive script.  Then implement your environment class; it should
531 usually inherit from one of the existing Environment classes and
532 possibly one or more of the EnvironmentMixin classes.  Then set the
533 ``environment`` variable to an instance of your own environment class
534 and pass it to ``run_as_post_receive_hook()``.
535
536 The standard environment classes, GenericEnvironment and
537 GitoliteEnvironment, are in fact themselves put together out of a
538 number of mixin classes, each of which handles one aspect of the
539 customization.  For the finest control over your configuration, you
540 can specify exactly which mixin classes your own environment class
541 should inherit from, and override individual methods (or even add your
542 own mixin classes) to implement entirely new behaviors.  If you
543 implement any mixins that might be useful to other people, please
544 consider sharing them with the community!
545
546
547 Getting involved
548 ----------------
549
550 git-multimail is an open-source project, built by volunteers. We would
551 welcome your help!
552
553 The current maintainers are Michael Haggerty <mhagger@alum.mit.edu>
554 and Matthieu Moy <matthieu.moy@grenoble-inp.fr>.
555
556 Please note that although a copy of git-multimail is distributed in
557 the "contrib" section of the main Git project, development takes place
558 in a separate git-multimail repository on GitHub:
559
560     https://github.com/git-multimail/git-multimail
561
562 Whenever enough changes to git-multimail have accumulated, a new
563 code-drop of git-multimail will be submitted for inclusion in the Git
564 project.
565
566 We use the GitHub issue tracker to keep track of bugs and feature
567 requests, and we use GitHub pull requests to exchange patches (though,
568 if you prefer, you can send patches via the Git mailing list with CC
569 to the maintainers). Please sign off your patches as per the Git
570 project practice.
571
572 General discussion of git-multimail can take place on the main Git
573 mailing list,
574
575     git@vger.kernel.org
576
577 Please CC emails regarding git-multimail to the maintainers so that we
578 don't overlook them.
579
580
581 Footnotes
582 ---------
583
584 .. [1] http://www.python.org/dev/peps/pep-0394/
585
586 .. [2] Because of the way information is passed to update hooks, the
587        script's method of determining whether a commit has already
588        been seen does not work when it is used as an ``update`` script.
589        In particular, no notification email will be generated for a
590        new commit that is added to multiple references in the same
591        push. A workaround is to use --force-send to force sending the
592        emails.
593
594 .. [3] https://github.com/sitaramc/gitolite