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