contrib / hooks / multimail / READMEon commit Merge branch 'ak/lazy-prereq-mktemp' (eb60086)
   1git-multimail version 1.4.0
   2===========================
   3
   4.. image:: https://travis-ci.org/git-multimail/git-multimail.svg?branch=master
   5    :target: https://travis-ci.org/git-multimail/git-multimail
   6
   7git-multimail is a tool for sending notification emails on pushes to a
   8Git repository.  It includes a Python module called ``git_multimail.py``,
   9which can either be used as a hook script directly or can be imported
  10as a Python module into another script.
  11
  12git-multimail is derived from the Git project's old
  13contrib/hooks/post-receive-email, and is mostly compatible with that
  14script.  See README.migrate-from-post-receive-email for details about
  15the differences and for how to migrate from post-receive-email to
  16git-multimail.
  17
  18git-multimail, like the rest of the Git project, is licensed under
  19GPLv2 (see the COPYING file for details).
  20
  21Please note: although, as a convenience, git-multimail may be
  22distributed along with the main Git project, development of
  23git-multimail takes place in its own, separate project.  See section
  24"Getting involved" below for more information.
  25
  26
  27By default, for each push received by the repository, git-multimail:
  28
  291. Outputs one email summarizing each reference that was changed.
  30   These "reference change" (called "refchange" below) emails describe
  31   the nature of the change (e.g., was the reference created, deleted,
  32   fast-forwarded, etc.) and include a one-line summary of each commit
  33   that was added to the reference.
  34
  352. Outputs one email for each new commit that was introduced by the
  36   reference change.  These "commit" emails include a list of the
  37   files changed by the commit, followed by the diffs of files
  38   modified by the commit.  The commit emails are threaded to the
  39   corresponding reference change email via "In-Reply-To".  This style
  40   (similar to the "git format-patch" style used on the Git mailing
  41   list) makes it easy to scan through the emails, jump to patches
  42   that need further attention, and write comments about specific
  43   commits.  Commits are handled in reverse topological order (i.e.,
  44   parents shown before children).  For example::
  45
  46     [git] branch master updated
  47     + [git] 01/08: doc: fix xref link from api docs to manual pages
  48     + [git] 02/08: api-credentials.txt: show the big picture first
  49     + [git] 03/08: api-credentials.txt: mention credential.helper explicitly
  50     + [git] 04/08: api-credentials.txt: add "see also" section
  51     + [git] 05/08: t3510 (cherry-pick-sequence): add missing '&&'
  52     + [git] 06/08: Merge branch 'rr/maint-t3510-cascade-fix'
  53     + [git] 07/08: Merge branch 'mm/api-credentials-doc'
  54     + [git] 08/08: Git 1.7.11-rc2
  55
  56   By default, each commit appears in exactly one commit email, the
  57   first time that it is pushed to the repository.  If a commit is later
  58   merged into another branch, then a one-line summary of the commit
  59   is included in the reference change email (as usual), but no
  60   additional commit email is generated. See
  61   `multimailhook.refFilter(Inclusion|Exclusion|DoSend|DontSend)Regex`
  62   below to configure which branches and tags are watched by the hook.
  63
  64   By default, reference change emails have their "Reply-To" field set
  65   to the person who pushed the change, and commit emails have their
  66   "Reply-To" field set to the author of the commit.
  67
  683. Output one "announce" mail for each new annotated tag, including
  69   information about the tag and optionally a shortlog describing the
  70   changes since the previous tag.  Such emails might be useful if you
  71   use annotated tags to mark releases of your project.
  72
  73
  74Requirements
  75------------
  76
  77* Python 2.x, version 2.4 or later.  No non-standard Python modules
  78  are required.  git-multimail has preliminary support for Python 3
  79  (but it has been better tested with Python 2).
  80
  81* The ``git`` command must be in your PATH.  git-multimail is known to
  82  work with Git versions back to 1.7.1.  (Earlier versions have not
  83  been tested; if you do so, please report your results.)
  84
  85* To send emails using the default configuration, a standard sendmail
  86  program must be located at '/usr/sbin/sendmail' or
  87  '/usr/lib/sendmail' and must be configured correctly to send emails.
  88  If this is not the case, set multimailhook.sendmailCommand, or see
  89  the multimailhook.mailer configuration variable below for how to
  90  configure git-multimail to send emails via an SMTP server.
  91
  92
  93Invocation
  94----------
  95
  96``git_multimail.py`` is designed to be used as a ``post-receive`` hook in a
  97Git repository (see githooks(5)).  Link or copy it to
  98$GIT_DIR/hooks/post-receive within the repository for which email
  99notifications are desired.  Usually it should be installed on the
 100central repository for a project, to which all commits are eventually
 101pushed.
 102
 103For use on pre-v1.5.1 Git servers, ``git_multimail.py`` can also work as
 104an ``update`` hook, taking its arguments on the command line.  To use
 105this script in this manner, link or copy it to $GIT_DIR/hooks/update.
 106Please note that the script is not completely reliable in this mode
 107[1]_.
 108
 109Alternatively, ``git_multimail.py`` can be imported as a Python module
 110into your own Python post-receive script.  This method is a bit more
 111work, but allows the behavior of the hook to be customized using
 112arbitrary 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
 123Or you can change how emails are sent by writing your own Mailer
 124class.  The ``post-receive`` script in this directory demonstrates how
 125to use ``git_multimail.py`` as a Python module.  (If you make interesting
 126changes of this type, please consider sharing them with the
 127community.)
 128
 129
 130Troubleshooting/FAQ
 131-------------------
 132
 133Please read `<doc/troubleshooting.rst>`__ for frequently asked
 134questions and common issues with git-multimail.
 135
 136
 137Configuration
 138-------------
 139
 140By default, git-multimail mostly takes its configuration from the
 141following ``git config`` settings:
 142
 143multimailhook.environment
 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.
 147    Currently supported values:
 148
 149    generic
 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
 153    gitolite
 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
 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
 162      `<doc/gitolite.rst>`__
 163
 164    stash
 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
 178    gerrit
 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>`__
 192
 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
 196    post-receive script.
 197
 198    The environment value can be specified on the command line using
 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.
 211
 212multimailhook.repoName
 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
 218multimailhook.mailingList
 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
 226multimailhook.refchangeList
 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
 231    multimailhook.mailingList.  Set this value to "none" (or the empty
 232    string) to prevent reference change emails from being sent even if
 233    multimailhook.mailingList is set.
 234
 235multimailhook.announceList
 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
 239    default is the value in multimailhook.refchangeList or
 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.
 243
 244multimailhook.commitList
 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
 248    default is the value in multimailhook.mailingList.  Set this value
 249    to "none" (or the empty string) to prevent notification emails about
 250    individual commits from being sent even if
 251    multimailhook.mailingList is set.
 252
 253multimailhook.announceShortlog
 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
 262multimailhook.commitEmailFormat
 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
 275    By default, all the message is HTML-escaped. See
 276    ``multimailhook.htmlInIntro`` to change this behavior.
 277
 278multimailhook.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
 294multimailhook.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
 300    Set ``multimailhook.htmlInIntro`` to true to allow writing HTML
 301    formatting in introduction templates. Similarly, set
 302    ``multimailhook.htmlInFooter`` for HTML in the footer.
 303
 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
 311multimailhook.refchangeShowGraph
 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
 322multimailhook.refchangeShowLog
 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
 326    ``git log`` with the options specified in multimailhook.logOpts.
 327    Default is false.
 328
 329multimailhook.mailer
 330    This option changes the way emails are sent.  Accepted values are:
 331
 332    * **sendmail (the default)**: use the command ``/usr/sbin/sendmail`` or
 333      ``/usr/lib/sendmail`` (or sendmailCommand, if configured).  This
 334      mode can be further customized via the following options:
 335
 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.::
 340
 341              git config multimailhook.sendmailcommand '/usr/sbin/sendmail -oi -t -F \"Git Repo\"'
 342
 343          Default is '/usr/sbin/sendmail -oi -t' or
 344          '/usr/lib/sendmail -oi -t' (depending on which file is
 345          present and executable).
 346
 347      multimailhook.envelopeSender
 348          If set then pass this value to sendmail via the -f option to set
 349          the envelope sender address.
 350
 351    * **smtp**: use Python's smtplib.  This is useful when the sendmail
 352      command is not available on the system.  This mode can be
 353      further customized via the following options:
 354
 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.
 359
 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.
 366
 367      multimailhook.envelopeSender
 368        The sender address to be passed to the SMTP server.  If
 369        unset, then the value of multimailhook.from is used.
 370
 371      multimailhook.smtpServerTimeout
 372        Timeout in seconds.
 373
 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
 401        Integer number. Set to greater than 0 to activate debugging.
 402
 403multimailhook.from, multimailhook.fromCommit, multimailhook.fromRefchange
 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.
 415
 416    - The value ``author`` (meaningful only for ``fromCommit``), in which
 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:
 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.
 438
 439multimailhook.administrator
 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
 445multimailhook.emailPrefix
 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
 449    the repository in square brackets; e.g., ``[myrepo]``.  Set this
 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.
 453
 454multimailhook.emailMaxLines
 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
 460multimailhook.emailMaxLineLength
 461    The maximum length of a line in the email body.  Lines longer than
 462    this limit are truncated to this length with a trailing ``[...]``
 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
 469multimailhook.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
 480multimailhook.maxCommitEmails
 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
 487multimailhook.emailStrictUTF8
 488    If this boolean option is set to `true`, then the main part of the
 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
 491    character, U+FFFD.  The default is `true`.
 492
 493    This option is ineffective with Python 3, where non-UTF-8
 494    characters are unconditionally replaced.
 495
 496multimailhook.diffOpts
 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
 500    include a unified diff of changes in addition to the usual summary
 501    output.  Shell quoting is allowed; see ``multimailhook.logOpts`` for
 502    details.
 503
 504multimailhook.graphOpts
 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
 511multimailhook.logOpts
 512    Options passed to ``git log`` to generate additional info for
 513    reference change emails (used only if refchangeShowLog is set).
 514    For example, adding -p will show each commit's complete diff.  The
 515    default is empty.
 516
 517    Shell quoting is allowed; for example, a log format that contains
 518    spaces can be specified using something like::
 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
 524    (see git-config(1) for more information)::
 525
 526      [multimailhook]
 527              logopts = --pretty=format:\"%h %aN <%aE>%n%s%n%n%b%n\"
 528
 529multimailhook.commitLogOpts
 530    Options passed to ``git log`` to generate additional info for
 531    revision change emails.  For example, adding --ignore-all-spaces
 532    will suppress whitespace changes.  The default options are ``-C
 533    --stat -p --cc``.  Shell quoting is allowed; see
 534    multimailhook.logOpts for details.
 535
 536multimailhook.dateSubstitute
 537    String to use as a substitute for ``Date:`` in the output of ``git
 538    log`` while formatting commit messages. This is useful to avoid
 539    emitting a line that can be interpreted by mailers as the start of
 540    a cited message (Zimbra webmail in particular). Defaults to
 541    ``CommitDate:``. Set to an empty string or ``none`` to deactivate
 542    the behavior.
 543
 544multimailhook.emailDomain
 545    Domain name appended to the username of the person doing the push
 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.
 550
 551multimailhook.replyTo, multimailhook.replyToCommit, multimailhook.replyToRefchange
 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
 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.
 559
 560    The default is ``pusher`` for refchange emails, and ``author`` for
 561    commit emails.
 562
 563multimailhook.quiet
 564    Do not output the list of email recipients from the hook
 565
 566multimailhook.stdout
 567    For debugging, send emails to stdout rather than to the
 568    mailer.  Equivalent to the --stdout command line option
 569
 570multimailhook.scanCommitForCc
 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
 575multimailhook.combineWhenSingleCommit
 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
 581multimailhook.refFilterInclusionRegex, multimailhook.refFilterExclusionRegex, multimailhook.refFilterDoSendRegex, multimailhook.refFilterDontSendRegex
 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.
 586    If you are happy with the current shape of the feature, please
 587    report it too.
 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$
 636
 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
 643multimailhook.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
 657multimailhook.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
 663Email filtering aids
 664--------------------
 665
 666All emails include extra headers to enable fine tuned filtering and
 667give information for debugging.  All emails include the headers
 668``X-Git-Host``, ``X-Git-Repo``, ``X-Git-Refname``, and ``X-Git-Reftype``.
 669ReferenceChange emails also include headers ``X-Git-Oldrev`` and ``X-Git-Newrev``;
 670Revision emails also include header ``X-Git-Rev``.
 671
 672
 673Customizing email contents
 674--------------------------
 675
 676git-multimail mostly generates emails by expanding templates.  The
 677templates can be customized.  To avoid the need to edit
 678``git_multimail.py`` directly, the preferred way to change the templates
 679is to write a separate Python script that imports ``git_multimail.py`` as
 680a module, then replaces the templates in place.  See the provided
 681post-receive script for an example of how this is done.
 682
 683
 684Customizing git-multimail for your environment
 685----------------------------------------------
 686
 687git-multimail is mostly customized via an "environment" that describes
 688the local environment in which Git is running.  Two types of
 689environment are built in:
 690
 691GenericEnvironment
 692    a stand-alone Git repository.
 693
 694GitoliteEnvironment
 695    a Git repository that is managed by gitolite_.  For such
 696    repositories, the identity of the pusher is read from
 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).
 701
 702By default, git-multimail assumes GitoliteEnvironment if $GL_USER and
 703$GL_REPO are set, and otherwise assumes GenericEnvironment.
 704Alternatively, you can choose one of these two environments explicitly
 705by setting a ``multimailhook.environment`` config setting (which can
 706have the value `generic` or `gitolite`) or by passing an --environment
 707option to the script.
 708
 709If you need to customize the script in ways that are not supported by
 710the existing environments, you can define your own environment class
 711class using arbitrary Python code.  To do so, you need to import
 712``git_multimail.py`` as a Python module, as demonstrated by the example
 713post-receive script.  Then implement your environment class; it should
 714usually inherit from one of the existing Environment classes and
 715possibly one or more of the EnvironmentMixin classes.  Then set the
 716``environment`` variable to an instance of your own environment class
 717and pass it to ``run_as_post_receive_hook()``.
 718
 719The standard environment classes, GenericEnvironment and
 720GitoliteEnvironment, are in fact themselves put together out of a
 721number of mixin classes, each of which handles one aspect of the
 722customization.  For the finest control over your configuration, you
 723can specify exactly which mixin classes your own environment class
 724should inherit from, and override individual methods (or even add your
 725own mixin classes) to implement entirely new behaviors.  If you
 726implement any mixins that might be useful to other people, please
 727consider sharing them with the community!
 728
 729
 730Getting involved
 731----------------
 732
 733Please, read `<CONTRIBUTING.rst>`__ for instructions on how to
 734contribute to git-multimail.
 735
 736
 737Footnotes
 738---------
 739
 740.. [1] Because of the way information is passed to update hooks, the
 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.
 747
 748.. _gitolite: https://github.com/sitaramc/gitolite