]>
Commit | Line | Data |
---|---|---|
7c554311 MM |
1 | git-multimail version 1.4.0 |
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 | |
7 | git-multimail is a tool for sending notification emails on pushes to a | |
7c554311 | 8 | Git repository. It includes a Python module called ``git_multimail.py``, |
bc501f69 MH |
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., | |
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 | ||
68 | 3. Output one "announce" mail for each new annotated tag, including | |
69 | information about the tag and optionally a shortlog describing the | |
70 | changes since the previous tag. Such emails might be useful if you | |
71 | use annotated tags to mark releases of your project. | |
72 | ||
73 | ||
74 | Requirements | |
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 | ||
92 | ||
93 | Invocation | |
94 | ---------- | |
95 | ||
7c554311 | 96 | ``git_multimail.py`` is designed to be used as a ``post-receive`` hook in a |
bc501f69 MH |
97 | Git repository (see githooks(5)). Link or copy it to |
98 | $GIT_DIR/hooks/post-receive within the repository for which email | |
99 | notifications are desired. Usually it should be installed on the | |
100 | central repository for a project, to which all commits are eventually | |
101 | pushed. | |
102 | ||
7c554311 | 103 | For use on pre-v1.5.1 Git servers, ``git_multimail.py`` can also work as |
5b1d901c | 104 | an ``update`` hook, taking its arguments on the command line. To use |
bc501f69 MH |
105 | this script in this manner, link or copy it to $GIT_DIR/hooks/update. |
106 | Please note that the script is not completely reliable in this mode | |
7c554311 | 107 | [1]_. |
bc501f69 | 108 | |
7c554311 | 109 | Alternatively, ``git_multimail.py`` can be imported as a Python module |
bc501f69 MH |
110 | into your own Python post-receive script. This method is a bit more |
111 | work, but allows the behavior of the hook to be customized using | |
112 | arbitrary Python code. For example, you can use a custom environment | |
113 | (perhaps inheriting from GenericEnvironment or GitoliteEnvironment) to | |
114 | ||
115 | * change how the user who did the push is determined | |
116 | ||
117 | * read users' email addresses from an LDAP server or from a database | |
118 | ||
119 | * decide which users should be notified about which commits based on | |
120 | the contents of the commits (e.g., for users who want to be notified | |
121 | only about changes affecting particular files or subdirectories) | |
122 | ||
123 | Or you can change how emails are sent by writing your own Mailer | |
5b1d901c | 124 | class. The ``post-receive`` script in this directory demonstrates how |
7c554311 | 125 | to use ``git_multimail.py`` as a Python module. (If you make interesting |
bc501f69 MH |
126 | changes of this type, please consider sharing them with the |
127 | community.) | |
128 | ||
129 | ||
4453d76c MM |
130 | Troubleshooting/FAQ |
131 | ------------------- | |
132 | ||
133 | Please read `<doc/troubleshooting.rst>`__ for frequently asked | |
134 | questions and common issues with git-multimail. | |
135 | ||
136 | ||
bc501f69 MH |
137 | Configuration |
138 | ------------- | |
139 | ||
140 | By default, git-multimail mostly takes its configuration from the | |
5b1d901c | 141 | following ``git config`` settings: |
bc501f69 MH |
142 | |
143 | multimailhook.environment | |
4b1fd356 MM |
144 | This describes the general environment of the repository. In most |
145 | cases, you do not need to specify a value for this variable: | |
146 | `git-multimail` will autodetect which environment to use. | |
bc501f69 MH |
147 | Currently supported values: |
148 | ||
4453d76c | 149 | generic |
5b1d901c MM |
150 | the username of the pusher is read from $USER or $USERNAME and |
151 | the repository name is derived from the repository's path. | |
152 | ||
4453d76c | 153 | gitolite |
7c554311 MM |
154 | Environment to use when ``git-multimail`` is ran as a gitolite_ |
155 | hook. | |
156 | ||
157 | The username of the pusher is read from $GL_USER, the repository | |
5b1d901c MM |
158 | name is read from $GL_REPO, and the From: header value is |
159 | optionally read from gitolite.conf (see multimailhook.from). | |
160 | ||
161 | For more information about gitolite and git-multimail, read | |
4b1fd356 MM |
162 | `<doc/gitolite.rst>`__ |
163 | ||
4453d76c | 164 | stash |
4b1fd356 MM |
165 | Environment to use when ``git-multimail`` is ran as an Atlassian |
166 | BitBucket Server (formerly known as Atlassian Stash) hook. | |
167 | ||
168 | **Warning:** this mode was provided by a third-party contributor | |
169 | and never tested by the git-multimail maintainers. It is | |
170 | provided as-is and may or may not work for you. | |
171 | ||
172 | This value is automatically assumed when the stash-specific | |
173 | flags (``--stash-user`` and ``--stash-repo``) are specified on | |
174 | the command line. When this environment is active, the username | |
175 | and repo come from these two command line flags, which must be | |
176 | specified. | |
177 | ||
4453d76c | 178 | gerrit |
4b1fd356 MM |
179 | Environment to use when ``git-multimail`` is ran as a |
180 | ``ref-updated`` Gerrit hook. | |
181 | ||
182 | This value is used when the gerrit-specific command line flags | |
183 | (``--oldrev``, ``--newrev``, ``--refname``, ``--project``) for | |
184 | gerrit's ref-updated hook are present. When this environment is | |
185 | active, the username of the pusher is taken from the | |
186 | ``--submitter`` argument if that command line option is passed, | |
187 | otherwise 'Gerrit' is used. The repository name is taken from | |
188 | the ``--project`` option on the command line, which must be passed. | |
189 | ||
190 | For more information about gerrit and git-multimail, read | |
191 | `<doc/gerrit.rst>`__ | |
bc501f69 | 192 | |
4b1fd356 MM |
193 | If none of these environments is suitable for your setup, then you |
194 | can implement a Python class that inherits from Environment and | |
195 | instantiate it via a script that looks like the example | |
bc501f69 MH |
196 | post-receive script. |
197 | ||
198 | The environment value can be specified on the command line using | |
4b1fd356 MM |
199 | the ``--environment`` option. If it is not specified on the |
200 | command line or by ``multimailhook.environment``, the value is | |
201 | guessed as follows: | |
202 | ||
203 | * If stash-specific (respectively gerrit-specific) command flags | |
204 | are present on the command-line, then ``stash`` (respectively | |
205 | ``gerrit``) is used. | |
206 | ||
207 | * If the environment variables $GL_USER and $GL_REPO are set, then | |
208 | ``gitolite`` is used. | |
209 | ||
210 | * If none of the above apply, then ``generic`` is used. | |
bc501f69 MH |
211 | |
212 | multimailhook.repoName | |
bc501f69 MH |
213 | A short name of this Git repository, to be used in various places |
214 | in the notification email text. The default is to use $GL_REPO | |
215 | for gitolite repositories, or otherwise to derive this value from | |
216 | the repository path name. | |
217 | ||
b513f71f | 218 | multimailhook.mailingList |
bc501f69 MH |
219 | The list of email addresses to which notification emails should be |
220 | sent, as RFC 2822 email addresses separated by commas. This | |
221 | configuration option can be multivalued. Leave it unset or set it | |
222 | to the empty string to not send emails by default. The next few | |
223 | settings can be used to configure specific address lists for | |
224 | specific types of notification email. | |
225 | ||
226 | multimailhook.refchangeList | |
bc501f69 MH |
227 | The list of email addresses to which summary emails about |
228 | reference changes should be sent, as RFC 2822 email addresses | |
229 | separated by commas. This configuration option can be | |
230 | multivalued. The default is the value in | |
4b1fd356 MM |
231 | multimailhook.mailingList. Set this value to "none" (or the empty |
232 | string) to prevent reference change emails from being sent even if | |
b513f71f | 233 | multimailhook.mailingList is set. |
bc501f69 MH |
234 | |
235 | multimailhook.announceList | |
bc501f69 MH |
236 | The list of email addresses to which emails about new annotated |
237 | tags should be sent, as RFC 2822 email addresses separated by | |
238 | commas. This configuration option can be multivalued. The | |
b513f71f | 239 | default is the value in multimailhook.refchangeList or |
4b1fd356 MM |
240 | multimailhook.mailingList. Set this value to "none" (or the empty |
241 | string) to prevent annotated tag announcement emails from being sent | |
242 | even if one of the other values is set. | |
bc501f69 MH |
243 | |
244 | multimailhook.commitList | |
bc501f69 MH |
245 | The list of email addresses to which emails about individual new |
246 | commits should be sent, as RFC 2822 email addresses separated by | |
247 | commas. This configuration option can be multivalued. The | |
b513f71f | 248 | default is the value in multimailhook.mailingList. Set this value |
4b1fd356 | 249 | to "none" (or the empty string) to prevent notification emails about |
b513f71f MH |
250 | individual commits from being sent even if |
251 | multimailhook.mailingList is set. | |
bc501f69 MH |
252 | |
253 | multimailhook.announceShortlog | |
bc501f69 MH |
254 | If this option is set to true, then emails about changes to |
255 | annotated tags include a shortlog of changes since the previous | |
256 | tag. This can be useful if the annotated tags represent releases; | |
257 | then the shortlog will be a kind of rough summary of what has | |
258 | happened since the last release. But if your tagging policy is | |
259 | not so straightforward, then the shortlog might be confusing | |
260 | rather than useful. Default is false. | |
261 | ||
4b1fd356 | 262 | multimailhook.commitEmailFormat |
4b1fd356 MM |
263 | The format of email messages for the individual commits, can be "text" or |
264 | "html". In the latter case, the emails will include diffs using colorized | |
265 | HTML instead of plain text used by default. Note that this currently the | |
266 | ref change emails are always sent in plain text. | |
267 | ||
268 | Note that when using "html", the formatting is done by parsing the | |
269 | output of ``git log`` with ``-p``. When using | |
270 | ``multimailhook.commitLogOpts`` to specify a ``--format`` for | |
271 | ``git log``, one may get false positive (e.g. lines in the body of | |
272 | the message starting with ``+++`` or ``---`` colored in red or | |
273 | green). | |
274 | ||
4453d76c MM |
275 | By default, all the message is HTML-escaped. See |
276 | ``multimailhook.htmlInIntro`` to change this behavior. | |
277 | ||
278 | multimailhook.commitBrowseURL | |
279 | Used to generate a link to an online repository browser in commit | |
280 | emails. This variable must be a string. Format directives like | |
281 | ``%(<variable>)s`` will be expanded the same way as template | |
282 | strings. In particular, ``%(id)s`` will be replaced by the full | |
283 | Git commit identifier (40-chars hexadecimal). | |
284 | ||
285 | If the string does not contain any format directive, then | |
286 | ``%(id)s`` will be automatically added to the string. If you don't | |
287 | want ``%(id)s`` to be automatically added, use the empty format | |
288 | directive ``%()s`` anywhere in the string. | |
289 | ||
290 | For example, a suitable value for the git-multimail project itself | |
291 | would be | |
292 | ``https://github.com/git-multimail/git-multimail/commit/%(id)s``. | |
293 | ||
294 | multimailhook.htmlInIntro, multimailhook.htmlInFooter | |
295 | When generating an HTML message, git-multimail escapes any HTML | |
296 | sequence by default. This means that if a template contains HTML | |
297 | like ``<a href="foo">link</a>``, the reader will see the HTML | |
298 | source code and not a proper link. | |
299 | ||
2e3a16b2 | 300 | Set ``multimailhook.htmlInIntro`` to true to allow writing HTML |
4453d76c MM |
301 | formatting in introduction templates. Similarly, set |
302 | ``multimailhook.htmlInFooter`` for HTML in the footer. | |
5b1d901c | 303 | |
4453d76c MM |
304 | Variables expanded in the template are still escaped. For example, |
305 | if a repository's path contains a ``<``, it will be rendered as | |
306 | such in the message. | |
307 | ||
308 | Read `<doc/customizing-emails.rst>`__ for more details and | |
309 | examples. | |
310 | ||
311 | multimailhook.refchangeShowGraph | |
5b1d901c MM |
312 | If this option is set to true, then summary emails about reference |
313 | changes will additionally include: | |
314 | ||
315 | * a graph of the added commits (if any) | |
316 | ||
317 | * a graph of the discarded commits (if any) | |
318 | ||
319 | The log is generated by running ``git log --graph`` with the options | |
320 | specified in graphOpts. The default is false. | |
321 | ||
bc501f69 | 322 | multimailhook.refchangeShowLog |
bc501f69 MH |
323 | If this option is set to true, then summary emails about reference |
324 | changes will include a detailed log of the added commits in | |
325 | addition to the one line summary. The log is generated by running | |
5b1d901c | 326 | ``git log`` with the options specified in multimailhook.logOpts. |
bc501f69 MH |
327 | Default is false. |
328 | ||
329 | multimailhook.mailer | |
bc501f69 MH |
330 | This option changes the way emails are sent. Accepted values are: |
331 | ||
4453d76c | 332 | * **sendmail (the default)**: use the command ``/usr/sbin/sendmail`` or |
5b1d901c | 333 | ``/usr/lib/sendmail`` (or sendmailCommand, if configured). This |
bc501f69 MH |
334 | mode can be further customized via the following options: |
335 | ||
4453d76c MM |
336 | multimailhook.sendmailCommand |
337 | The command used by mailer ``sendmail`` to send emails. Shell | |
338 | quoting is allowed in the value of this setting, but remember that | |
339 | Git requires double-quotes to be escaped; e.g.:: | |
bc501f69 | 340 | |
4453d76c | 341 | git config multimailhook.sendmailcommand '/usr/sbin/sendmail -oi -t -F \"Git Repo\"' |
bc501f69 | 342 | |
4453d76c MM |
343 | Default is '/usr/sbin/sendmail -oi -t' or |
344 | '/usr/lib/sendmail -oi -t' (depending on which file is | |
345 | present and executable). | |
bc501f69 | 346 | |
4453d76c MM |
347 | multimailhook.envelopeSender |
348 | If set then pass this value to sendmail via the -f option to set | |
349 | the envelope sender address. | |
bc501f69 | 350 | |
4453d76c | 351 | * **smtp**: use Python's smtplib. This is useful when the sendmail |
bc501f69 MH |
352 | command is not available on the system. This mode can be |
353 | further customized via the following options: | |
354 | ||
4453d76c MM |
355 | multimailhook.smtpServer |
356 | The name of the SMTP server to connect to. The value can | |
357 | also include a colon and a port number; e.g., | |
358 | ``mail.example.com:25``. Default is 'localhost' using port 25. | |
5b1d901c | 359 | |
4453d76c MM |
360 | multimailhook.smtpUser, multimailhook.smtpPass |
361 | Server username and password. Required if smtpEncryption is 'ssl'. | |
362 | Note that the username and password currently need to be | |
363 | set cleartext in the configuration file, which is not | |
364 | recommended. If you need to use this option, be sure your | |
365 | configuration file is read-only. | |
5b1d901c | 366 | |
4453d76c | 367 | multimailhook.envelopeSender |
5b1d901c MM |
368 | The sender address to be passed to the SMTP server. If |
369 | unset, then the value of multimailhook.from is used. | |
370 | ||
4453d76c | 371 | multimailhook.smtpServerTimeout |
5b1d901c | 372 | Timeout in seconds. |
bc501f69 | 373 | |
4453d76c MM |
374 | multimailhook.smtpEncryption |
375 | Set the security type. Allowed values: ``none``, ``ssl``, ``tls`` (starttls). | |
376 | Default is ``none``. | |
377 | ||
378 | multimailhook.smtpCACerts | |
379 | Set the path to a list of trusted CA certificate to verify the | |
380 | server certificate, only supported when ``smtpEncryption`` is | |
381 | ``tls``. If unset or empty, the server certificate is not | |
382 | verified. If it targets a file containing a list of trusted CA | |
383 | certificates (PEM format) these CAs will be used to verify the | |
384 | server certificate. For debian, you can set | |
385 | ``/etc/ssl/certs/ca-certificates.crt`` for using the system | |
386 | trusted CAs. For self-signed server, you can add your server | |
387 | certificate to the system store:: | |
388 | ||
389 | cd /usr/local/share/ca-certificates/ | |
390 | openssl s_client -starttls smtp \ | |
391 | -connect mail.example.net:587 -showcerts \ | |
392 | </dev/null 2>/dev/null \ | |
393 | | openssl x509 -outform PEM >mail.example.net.crt | |
394 | update-ca-certificates | |
395 | ||
396 | and used the updated ``/etc/ssl/certs/ca-certificates.crt``. Or | |
397 | directly use your ``/path/to/mail.example.net.crt``. Default is | |
398 | unset. | |
399 | ||
400 | multimailhook.smtpServerDebugLevel | |
5b1d901c | 401 | Integer number. Set to greater than 0 to activate debugging. |
bc501f69 | 402 | |
4453d76c | 403 | multimailhook.from, multimailhook.fromCommit, multimailhook.fromRefchange |
4b1fd356 MM |
404 | If set, use this value in the From: field of generated emails. |
405 | ``fromCommit`` is used for commit emails, ``fromRefchange`` is | |
406 | used for refchange emails, and ``from`` is used as fall-back in | |
407 | all cases. | |
408 | ||
409 | The value for these variables can be either: | |
410 | ||
411 | - An email address, which will be used directly. | |
412 | ||
413 | - The value ``pusher``, in which case the pusher's address (if | |
414 | available) will be used. | |
bc501f69 | 415 | |
4453d76c | 416 | - The value ``author`` (meaningful only for ``fromCommit``), in which |
4b1fd356 MM |
417 | case the commit author's address will be used. |
418 | ||
419 | If config values are unset, the value of the From: header is | |
420 | determined as follows: | |
5b1d901c MM |
421 | |
422 | 1. (gitolite environment only) Parse gitolite.conf, looking for a | |
423 | block of comments that looks like this:: | |
424 | ||
425 | # BEGIN USER EMAILS | |
426 | # username Firstname Lastname <email@example.com> | |
427 | # END USER EMAILS | |
428 | ||
429 | If that block exists, and there is a line between the BEGIN | |
430 | USER EMAILS and END USER EMAILS lines where the first field | |
431 | matches the gitolite username ($GL_USER), use the rest of the | |
432 | line for the From: header. | |
433 | ||
434 | 2. If the user.email configuration setting is set, use its value | |
435 | (and the value of user.name, if set). | |
436 | ||
437 | 3. Use the value of multimailhook.envelopeSender. | |
bc501f69 MH |
438 | |
439 | multimailhook.administrator | |
bc501f69 MH |
440 | The name and/or email address of the administrator of the Git |
441 | repository; used in FOOTER_TEMPLATE. Default is | |
442 | multimailhook.envelopesender if it is set; otherwise a generic | |
443 | string is used. | |
444 | ||
445 | multimailhook.emailPrefix | |
bc501f69 MH |
446 | All emails have this string prepended to their subjects, to aid |
447 | email filtering (though filtering based on the X-Git-* email | |
448 | headers is probably more robust). Default is the short name of | |
5b1d901c | 449 | the repository in square brackets; e.g., ``[myrepo]``. Set this |
7c554311 MM |
450 | value to the empty string to suppress the email prefix. You may |
451 | use the placeholder ``%(repo_shortname)s`` for the short name of | |
452 | the repository. | |
bc501f69 MH |
453 | |
454 | multimailhook.emailMaxLines | |
bc501f69 MH |
455 | The maximum number of lines that should be included in the body of |
456 | a generated email. If not specified, there is no limit. Lines | |
457 | beyond the limit are suppressed and counted, and a final line is | |
458 | added indicating the number of suppressed lines. | |
459 | ||
460 | multimailhook.emailMaxLineLength | |
bc501f69 | 461 | The maximum length of a line in the email body. Lines longer than |
4453d76c | 462 | this limit are truncated to this length with a trailing ``[...]`` |
bc501f69 MH |
463 | added to indicate the missing text. The default is 500, because |
464 | (a) diffs with longer lines are probably from binary files, for | |
465 | which a diff is useless, and (b) even if a text file has such long | |
466 | lines, the diffs are probably unreadable anyway. To disable line | |
467 | truncation, set this option to 0. | |
468 | ||
7c554311 MM |
469 | multimailhook.subjectMaxLength |
470 | The maximum length of the subject line (i.e. the ``oneline`` field | |
471 | in templates, not including the prefix). Lines longer than this | |
472 | limit are truncated to this length with a trailing ``[...]`` added | |
473 | to indicate the missing text. This option The default is to use | |
474 | ``multimailhook.emailMaxLineLength``. This option avoids sending | |
475 | emails with overly long subject lines, but should not be needed if | |
476 | the commit messages follow the Git convention (one short subject | |
477 | line, then a blank line, then the message body). To disable line | |
478 | truncation, set this option to 0. | |
479 | ||
bc501f69 | 480 | multimailhook.maxCommitEmails |
bc501f69 MH |
481 | The maximum number of commit emails to send for a given change. |
482 | When the number of patches is larger that this value, only the | |
483 | summary refchange email is sent. This can avoid accidental | |
484 | mailbombing, for example on an initial push. To disable commit | |
485 | emails limit, set this option to 0. The default is 500. | |
486 | ||
487 | multimailhook.emailStrictUTF8 | |
5b1d901c | 488 | If this boolean option is set to `true`, then the main part of the |
bc501f69 MH |
489 | email body is forced to be valid UTF-8. Any characters that are |
490 | not valid UTF-8 are converted to the Unicode replacement | |
5b1d901c | 491 | character, U+FFFD. The default is `true`. |
bc501f69 | 492 | |
7c554311 MM |
493 | This option is ineffective with Python 3, where non-UTF-8 |
494 | characters are unconditionally replaced. | |
495 | ||
bc501f69 | 496 | multimailhook.diffOpts |
5b1d901c MM |
497 | Options passed to ``git diff-tree`` when generating the summary |
498 | information for ReferenceChange emails. Default is ``--stat | |
499 | --summary --find-copies-harder``. Add -p to those options to | |
bc501f69 | 500 | include a unified diff of changes in addition to the usual summary |
7c554311 | 501 | output. Shell quoting is allowed; see ``multimailhook.logOpts`` for |
bc501f69 MH |
502 | details. |
503 | ||
5b1d901c | 504 | multimailhook.graphOpts |
5b1d901c MM |
505 | Options passed to ``git log --graph`` when generating graphs for the |
506 | reference change summary emails (used only if refchangeShowGraph | |
507 | is true). The default is '--oneline --decorate'. | |
508 | ||
509 | Shell quoting is allowed; see logOpts for details. | |
510 | ||
bc501f69 | 511 | multimailhook.logOpts |
5b1d901c | 512 | Options passed to ``git log`` to generate additional info for |
bc501f69 | 513 | reference change emails (used only if refchangeShowLog is set). |
5b1d901c MM |
514 | For example, adding -p will show each commit's complete diff. The |
515 | default is empty. | |
bc501f69 MH |
516 | |
517 | Shell quoting is allowed; for example, a log format that contains | |
5b1d901c | 518 | spaces can be specified using something like:: |
bc501f69 MH |
519 | |
520 | git config multimailhook.logopts '--pretty=format:"%h %aN <%aE>%n%s%n%n%b%n"' | |
521 | ||
522 | If you want to set this by editing your configuration file | |
523 | directly, remember that Git requires double-quotes to be escaped | |
5b1d901c | 524 | (see git-config(1) for more information):: |
bc501f69 MH |
525 | |
526 | [multimailhook] | |
527 | logopts = --pretty=format:\"%h %aN <%aE>%n%s%n%n%b%n\" | |
528 | ||
b513f71f | 529 | multimailhook.commitLogOpts |
5b1d901c | 530 | Options passed to ``git log`` to generate additional info for |
b513f71f | 531 | revision change emails. For example, adding --ignore-all-spaces |
5b1d901c MM |
532 | will suppress whitespace changes. The default options are ``-C |
533 | --stat -p --cc``. Shell quoting is allowed; see | |
b513f71f MH |
534 | multimailhook.logOpts for details. |
535 | ||
4b1fd356 | 536 | multimailhook.dateSubstitute |
4b1fd356 | 537 | String to use as a substitute for ``Date:`` in the output of ``git |
2e3a16b2 | 538 | log`` while formatting commit messages. This is useful to avoid |
4b1fd356 MM |
539 | emitting a line that can be interpreted by mailers as the start of |
540 | a cited message (Zimbra webmail in particular). Defaults to | |
4453d76c | 541 | ``CommitDate:``. Set to an empty string or ``none`` to deactivate |
4b1fd356 MM |
542 | the behavior. |
543 | ||
bc501f69 | 544 | multimailhook.emailDomain |
bc501f69 | 545 | Domain name appended to the username of the person doing the push |
5b1d901c MM |
546 | to convert it into an email address |
547 | (via ``"%s@%s" % (username, emaildomain)``). More complicated | |
548 | schemes can be implemented by overriding Environment and | |
549 | overriding its get_pusher_email() method. | |
bc501f69 | 550 | |
4453d76c | 551 | multimailhook.replyTo, multimailhook.replyToCommit, multimailhook.replyToRefchange |
bc501f69 MH |
552 | Addresses to use in the Reply-To: field for commit emails |
553 | (replyToCommit) and refchange emails (replyToRefchange). | |
554 | multimailhook.replyTo is used as default when replyToCommit or | |
4b1fd356 MM |
555 | replyToRefchange is not set. The shortcuts ``pusher`` and |
556 | ``author`` are allowed with the same semantics as for | |
557 | ``multimailhook.from``. In addition, the value ``none`` can be | |
558 | used to omit the ``Reply-To:`` field. | |
bc501f69 | 559 | |
4b1fd356 MM |
560 | The default is ``pusher`` for refchange emails, and ``author`` for |
561 | commit emails. | |
bc501f69 | 562 | |
5b1d901c | 563 | multimailhook.quiet |
5b1d901c MM |
564 | Do not output the list of email recipients from the hook |
565 | ||
566 | multimailhook.stdout | |
5b1d901c MM |
567 | For debugging, send emails to stdout rather than to the |
568 | mailer. Equivalent to the --stdout command line option | |
569 | ||
570 | multimailhook.scanCommitForCc | |
5b1d901c MM |
571 | If this option is set to true, than recipients from lines in commit body |
572 | that starts with ``CC:`` will be added to CC list. | |
573 | Default: false | |
574 | ||
575 | multimailhook.combineWhenSingleCommit | |
5b1d901c MM |
576 | If this option is set to true and a single new commit is pushed to |
577 | a branch, combine the summary and commit email messages into a | |
578 | single email. | |
579 | Default: true | |
580 | ||
4453d76c | 581 | multimailhook.refFilterInclusionRegex, multimailhook.refFilterExclusionRegex, multimailhook.refFilterDoSendRegex, multimailhook.refFilterDontSendRegex |
4b1fd356 MM |
582 | **Warning:** these options are experimental. They should work, but |
583 | the user-interface is not stable yet (in particular, the option | |
584 | names may change). If you want to participate in stabilizing the | |
585 | feature, please contact the maintainers and/or send pull-requests. | |
7c554311 MM |
586 | If you are happy with the current shape of the feature, please |
587 | report it too. | |
4b1fd356 MM |
588 | |
589 | Regular expressions that can be used to limit refs for which email | |
590 | updates will be sent. It is an error to specify both an inclusion | |
591 | and an exclusion regex. If a ``refFilterInclusionRegex`` is | |
592 | specified, emails will only be sent for refs which match this | |
593 | regex. If a ``refFilterExclusionRegex`` regex is specified, | |
594 | emails will be sent for all refs except those that match this | |
595 | regex (or that match a predefined regex specific to the | |
596 | environment, such as "^refs/notes" for most environments and | |
597 | "^refs/notes|^refs/changes" for the gerrit environment). | |
598 | ||
599 | The expressions are matched against the complete refname, and is | |
600 | considered to match if any substring matches. For example, to | |
601 | filter-out all tags, set ``refFilterExclusionRegex`` to | |
602 | ``^refs/tags/`` (note the leading ``^`` but no trailing ``$``). If | |
603 | you set ``refFilterExclusionRegex`` to ``master``, then any ref | |
604 | containing ``master`` will be excluded (the ``master`` branch, but | |
605 | also ``refs/tags/master`` or ``refs/heads/foo-master-bar``). | |
606 | ||
607 | ``refFilterDoSendRegex`` and ``refFilterDontSendRegex`` are | |
608 | analogous to ``refFilterInclusionRegex`` and | |
609 | ``refFilterExclusionRegex`` with one difference: with | |
610 | ``refFilterDoSendRegex`` and ``refFilterDontSendRegex``, commits | |
611 | introduced by one excluded ref will not be considered as new when | |
612 | they reach an included ref. Typically, if you add a branch ``foo`` | |
613 | to ``refFilterDontSendRegex``, push commits to this branch, and | |
614 | later merge branch ``foo`` into ``master``, then the notification | |
615 | email for ``master`` will contain a commit email only for the | |
616 | merge commit. If you include ``foo`` in | |
617 | ``refFilterExclusionRegex``, then at the time of merge, you will | |
618 | receive one commit email per commit in the branch. | |
619 | ||
620 | These variables can be multi-valued, like:: | |
621 | ||
622 | [multimailhook] | |
623 | refFilterExclusionRegex = ^refs/tags/ | |
624 | refFilterExclusionRegex = ^refs/heads/master$ | |
625 | ||
626 | You can also provide a whitespace-separated list like:: | |
627 | ||
628 | [multimailhook] | |
629 | refFilterExclusionRegex = ^refs/tags/ ^refs/heads/master$ | |
630 | ||
631 | Both examples exclude tags and the master branch, and are | |
632 | equivalent to:: | |
633 | ||
634 | [multimailhook] | |
635 | refFilterExclusionRegex = ^refs/tags/|^refs/heads/master$ | |
bc501f69 | 636 | |
7c554311 MM |
637 | ``refFilterInclusionRegex`` and ``refFilterExclusionRegex`` are |
638 | strictly stronger than ``refFilterDoSendRegex`` and | |
639 | ``refFilterDontSendRegex``. In other words, adding a ref to a | |
640 | DoSend/DontSend regex has no effect if it is already excluded by a | |
641 | Exclusion/Inclusion regex. | |
642 | ||
643 | multimailhook.logFile, multimailhook.errorLogFile, multimailhook.debugLogFile | |
644 | ||
645 | When set, these variable designate path to files where | |
646 | git-multimail will log some messages. Normal messages and error | |
647 | messages are sent to ``logFile``, and error messages are also sent | |
648 | to ``errorLogFile``. Debug messages and all other messages are | |
649 | sent to ``debugLogFile``. The recommended way is to set only one | |
650 | of these variables, but it is also possible to set several of them | |
651 | (part of the information is then duplicated in several log files, | |
652 | for example errors are duplicated to all log files). | |
653 | ||
654 | Relative path are relative to the Git repository where the push is | |
655 | done. | |
656 | ||
657 | multimailhook.verbose | |
658 | ||
659 | Verbosity level of git-multimail on its standard output. By | |
660 | default, show only error and info messages. If set to true, show | |
661 | also debug messages. | |
662 | ||
bc501f69 MH |
663 | Email filtering aids |
664 | -------------------- | |
665 | ||
666 | All emails include extra headers to enable fine tuned filtering and | |
667 | give information for debugging. All emails include the headers | |
5b1d901c MM |
668 | ``X-Git-Host``, ``X-Git-Repo``, ``X-Git-Refname``, and ``X-Git-Reftype``. |
669 | ReferenceChange emails also include headers ``X-Git-Oldrev`` and ``X-Git-Newrev``; | |
670 | Revision emails also include header ``X-Git-Rev``. | |
bc501f69 MH |
671 | |
672 | ||
673 | Customizing email contents | |
674 | -------------------------- | |
675 | ||
676 | git-multimail mostly generates emails by expanding templates. The | |
677 | templates can be customized. To avoid the need to edit | |
7c554311 MM |
678 | ``git_multimail.py`` directly, the preferred way to change the templates |
679 | is to write a separate Python script that imports ``git_multimail.py`` as | |
bc501f69 MH |
680 | a module, then replaces the templates in place. See the provided |
681 | post-receive script for an example of how this is done. | |
682 | ||
683 | ||
684 | Customizing git-multimail for your environment | |
685 | ---------------------------------------------- | |
686 | ||
687 | git-multimail is mostly customized via an "environment" that describes | |
688 | the local environment in which Git is running. Two types of | |
689 | environment are built in: | |
690 | ||
4453d76c MM |
691 | GenericEnvironment |
692 | a stand-alone Git repository. | |
bc501f69 | 693 | |
4453d76c | 694 | GitoliteEnvironment |
7c554311 MM |
695 | a Git repository that is managed by gitolite_. For such |
696 | repositories, the identity of the pusher is read from | |
4453d76c MM |
697 | environment variable $GL_USER, the name of the repository is read |
698 | from $GL_REPO (if it is not overridden by multimailhook.reponame), | |
699 | and the From: header value is optionally read from gitolite.conf | |
700 | (see multimailhook.from). | |
bc501f69 MH |
701 | |
702 | By default, git-multimail assumes GitoliteEnvironment if $GL_USER and | |
703 | $GL_REPO are set, and otherwise assumes GenericEnvironment. | |
704 | Alternatively, you can choose one of these two environments explicitly | |
5b1d901c MM |
705 | by setting a ``multimailhook.environment`` config setting (which can |
706 | have the value `generic` or `gitolite`) or by passing an --environment | |
bc501f69 MH |
707 | option to the script. |
708 | ||
709 | If you need to customize the script in ways that are not supported by | |
710 | the existing environments, you can define your own environment class | |
711 | class using arbitrary Python code. To do so, you need to import | |
7c554311 | 712 | ``git_multimail.py`` as a Python module, as demonstrated by the example |
bc501f69 MH |
713 | post-receive script. Then implement your environment class; it should |
714 | usually inherit from one of the existing Environment classes and | |
715 | possibly one or more of the EnvironmentMixin classes. Then set the | |
5b1d901c MM |
716 | ``environment`` variable to an instance of your own environment class |
717 | and pass it to ``run_as_post_receive_hook()``. | |
bc501f69 MH |
718 | |
719 | The standard environment classes, GenericEnvironment and | |
720 | GitoliteEnvironment, are in fact themselves put together out of a | |
721 | number of mixin classes, each of which handles one aspect of the | |
722 | customization. For the finest control over your configuration, you | |
723 | can specify exactly which mixin classes your own environment class | |
724 | should inherit from, and override individual methods (or even add your | |
725 | own mixin classes) to implement entirely new behaviors. If you | |
726 | implement any mixins that might be useful to other people, please | |
727 | consider sharing them with the community! | |
728 | ||
729 | ||
730 | Getting involved | |
731 | ---------------- | |
732 | ||
4b1fd356 MM |
733 | Please, read `<CONTRIBUTING.rst>`__ for instructions on how to |
734 | contribute to git-multimail. | |
bc501f69 MH |
735 | |
736 | ||
737 | Footnotes | |
738 | --------- | |
739 | ||
7c554311 | 740 | .. [1] Because of the way information is passed to update hooks, the |
5b1d901c MM |
741 | script's method of determining whether a commit has already |
742 | been seen does not work when it is used as an ``update`` script. | |
743 | In particular, no notification email will be generated for a | |
744 | new commit that is added to multiple references in the same | |
745 | push. A workaround is to use --force-send to force sending the | |
746 | emails. | |
bc501f69 | 747 | |
7c554311 | 748 | .. _gitolite: https://github.com/sitaramc/gitolite |