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