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