git-multimail: update to release 1.2.0

[git.git] / contrib / hooks / multimail / README

git-multimail (version 1.2.0)
=============================

.. image:: https://travis-ci.org/git-multimail/git-multimail.svg?branch=master
    :target: https://travis-ci.org/git-multimail/git-multimail

git-multimail is a tool for sending notification emails on pushes to a
Git repository.  It includes a Python module called git_multimail.py,
which can either be used as a hook script directly or can be imported
as a Python module into another script.

git-multimail is derived from the Git project's old
contrib/hooks/post-receive-email, and is mostly compatible with that
script.  See README.migrate-from-post-receive-email for details about
the differences and for how to migrate from post-receive-email to
git-multimail.

git-multimail, like the rest of the Git project, is licensed under
GPLv2 (see the COPYING file for details).

Please note: although, as a convenience, git-multimail may be
distributed along with the main Git project, development of
git-multimail takes place in its own, separate project.  See section
"Getting involved" below for more information.


By default, for each push received by the repository, git-multimail:

1. Outputs one email summarizing each reference that was changed.
   These "reference change" (called "refchange" below) emails describe
   the nature of the change (e.g., was the reference created, deleted,
   fast-forwarded, etc.) and include a one-line summary of each commit
   that was added to the reference.

2. Outputs one email for each new commit that was introduced by the
   reference change.  These "commit" emails include a list of the
   files changed by the commit, followed by the diffs of files
   modified by the commit.  The commit emails are threaded to the
   corresponding reference change email via "In-Reply-To".  This style
   (similar to the "git format-patch" style used on the Git mailing
   list) makes it easy to scan through the emails, jump to patches
   that need further attention, and write comments about specific
   commits.  Commits are handled in reverse topological order (i.e.,
   parents shown before children).  For example::

     [git] branch master updated
     + [git] 01/08: doc: fix xref link from api docs to manual pages
     + [git] 02/08: api-credentials.txt: show the big picture first
     + [git] 03/08: api-credentials.txt: mention credential.helper explicitly
     + [git] 04/08: api-credentials.txt: add "see also" section
     + [git] 05/08: t3510 (cherry-pick-sequence): add missing '&&'
     + [git] 06/08: Merge branch 'rr/maint-t3510-cascade-fix'
     + [git] 07/08: Merge branch 'mm/api-credentials-doc'
     + [git] 08/08: Git 1.7.11-rc2

   By default, each commit appears in exactly one commit email, the
   first time that it is pushed to the repository.  If a commit is later
   merged into another branch, then a one-line summary of the commit
   is included in the reference change email (as usual), but no
   additional commit email is generated. See
   `multimailhook.refFilter(Inclusion|Exclusion|DoSend|DontSend)Regex`
   below to configure which branches and tags are watched by the hook.

   By default, reference change emails have their "Reply-To" field set
   to the person who pushed the change, and commit emails have their
   "Reply-To" field set to the author of the commit.

3. Output one "announce" mail for each new annotated tag, including
   information about the tag and optionally a shortlog describing the
   changes since the previous tag.  Such emails might be useful if you
   use annotated tags to mark releases of your project.


Requirements
------------

* Python 2.x, version 2.4 or later.  No non-standard Python modules
  are required.  git-multimail has preliminary support for Python 3
  (but it has been better tested with Python 2).

* The ``git`` command must be in your PATH.  git-multimail is known to
  work with Git versions back to 1.7.1.  (Earlier versions have not
  been tested; if you do so, please report your results.)

* To send emails using the default configuration, a standard sendmail
  program must be located at '/usr/sbin/sendmail' or
  '/usr/lib/sendmail' and must be configured correctly to send emails.
  If this is not the case, set multimailhook.sendmailCommand, or see
  the multimailhook.mailer configuration variable below for how to
  configure git-multimail to send emails via an SMTP server.


Invocation
----------

git_multimail.py is designed to be used as a ``post-receive`` hook in a
Git repository (see githooks(5)).  Link or copy it to
$GIT_DIR/hooks/post-receive within the repository for which email
notifications are desired.  Usually it should be installed on the
central repository for a project, to which all commits are eventually
pushed.

For use on pre-v1.5.1 Git servers, git_multimail.py can also work as
an ``update`` hook, taking its arguments on the command line.  To use
this script in this manner, link or copy it to $GIT_DIR/hooks/update.
Please note that the script is not completely reliable in this mode
[2]_.

Alternatively, git_multimail.py can be imported as a Python module
into your own Python post-receive script.  This method is a bit more
work, but allows the behavior of the hook to be customized using
arbitrary Python code.  For example, you can use a custom environment
(perhaps inheriting from GenericEnvironment or GitoliteEnvironment) to

* change how the user who did the push is determined

* read users' email addresses from an LDAP server or from a database

* decide which users should be notified about which commits based on
  the contents of the commits (e.g., for users who want to be notified
  only about changes affecting particular files or subdirectories)

Or you can change how emails are sent by writing your own Mailer
class.  The ``post-receive`` script in this directory demonstrates how
to use git_multimail.py as a Python module.  (If you make interesting
changes of this type, please consider sharing them with the
community.)


Configuration
-------------

By default, git-multimail mostly takes its configuration from the
following ``git config`` settings:

multimailhook.environment

    This describes the general environment of the repository. In most
    cases, you do not need to specify a value for this variable:
    `git-multimail` will autodetect which environment to use.
    Currently supported values:

    * generic

      the username of the pusher is read from $USER or $USERNAME and
      the repository name is derived from the repository's path.

    * gitolite

      the username of the pusher is read from $GL_USER, the repository
      name is read from $GL_REPO, and the From: header value is
      optionally read from gitolite.conf (see multimailhook.from).

      For more information about gitolite and git-multimail, read
      `<doc/gitolite.rst>`__

    * stash

      Environment to use when ``git-multimail`` is ran as an Atlassian
      BitBucket Server (formerly known as Atlassian Stash) hook.

      **Warning:** this mode was provided by a third-party contributor
      and never tested by the git-multimail maintainers. It is
      provided as-is and may or may not work for you.

      This value is automatically assumed when the stash-specific
      flags (``--stash-user`` and ``--stash-repo``) are specified on
      the command line. When this environment is active, the username
      and repo come from these two command line flags, which must be
      specified.

    * gerrit

      Environment to use when ``git-multimail`` is ran as a
      ``ref-updated`` Gerrit hook.

      This value is used when the gerrit-specific command line flags
      (``--oldrev``, ``--newrev``, ``--refname``, ``--project``) for
      gerrit's ref-updated hook are present. When this environment is
      active, the username of the pusher is taken from the
      ``--submitter`` argument if that command line option is passed,
      otherwise 'Gerrit' is used. The repository name is taken from
      the ``--project`` option on the command line, which must be passed.

      For more information about gerrit and git-multimail, read
      `<doc/gerrit.rst>`__

    If none of these environments is suitable for your setup, then you
    can implement a Python class that inherits from Environment and
    instantiate it via a script that looks like the example
    post-receive script.

    The environment value can be specified on the command line using
    the ``--environment`` option. If it is not specified on the
    command line or by ``multimailhook.environment``, the value is
    guessed as follows:

    * If stash-specific (respectively gerrit-specific) command flags
      are present on the command-line, then ``stash`` (respectively
      ``gerrit``) is used.

    * If the environment variables $GL_USER and $GL_REPO are set, then
      ``gitolite`` is used.

    * If none of the above apply, then ``generic`` is used.

multimailhook.repoName

    A short name of this Git repository, to be used in various places
    in the notification email text.  The default is to use $GL_REPO
    for gitolite repositories, or otherwise to derive this value from
    the repository path name.

multimailhook.mailingList

    The list of email addresses to which notification emails should be
    sent, as RFC 2822 email addresses separated by commas.  This
    configuration option can be multivalued.  Leave it unset or set it
    to the empty string to not send emails by default.  The next few
    settings can be used to configure specific address lists for
    specific types of notification email.

multimailhook.refchangeList

    The list of email addresses to which summary emails about
    reference changes should be sent, as RFC 2822 email addresses
    separated by commas.  This configuration option can be
    multivalued.  The default is the value in
    multimailhook.mailingList.  Set this value to "none" (or the empty
    string) to prevent reference change emails from being sent even if
    multimailhook.mailingList is set.

multimailhook.announceList

    The list of email addresses to which emails about new annotated
    tags should be sent, as RFC 2822 email addresses separated by
    commas.  This configuration option can be multivalued.  The
    default is the value in multimailhook.refchangeList or
    multimailhook.mailingList.  Set this value to "none" (or the empty
    string) to prevent annotated tag announcement emails from being sent
    even if one of the other values is set.

multimailhook.commitList

    The list of email addresses to which emails about individual new
    commits should be sent, as RFC 2822 email addresses separated by
    commas.  This configuration option can be multivalued.  The
    default is the value in multimailhook.mailingList.  Set this value
    to "none" (or the empty string) to prevent notification emails about
    individual commits from being sent even if
    multimailhook.mailingList is set.

multimailhook.announceShortlog

    If this option is set to true, then emails about changes to
    annotated tags include a shortlog of changes since the previous
    tag.  This can be useful if the annotated tags represent releases;
    then the shortlog will be a kind of rough summary of what has
    happened since the last release.  But if your tagging policy is
    not so straightforward, then the shortlog might be confusing
    rather than useful.  Default is false.

multimailhook.commitEmailFormat

    The format of email messages for the individual commits, can be "text" or
    "html". In the latter case, the emails will include diffs using colorized
    HTML instead of plain text used by default. Note that this  currently the
    ref change emails are always sent in plain text.

    Note that when using "html", the formatting is done by parsing the
    output of ``git log`` with ``-p``. When using
    ``multimailhook.commitLogOpts`` to specify a ``--format`` for
    ``git log``, one may get false positive (e.g. lines in the body of
    the message starting with ``+++`` or ``---`` colored in red or
    green).

multimailhook.refchangeShowGraph

    If this option is set to true, then summary emails about reference
    changes will additionally include:

    * a graph of the added commits (if any)

    * a graph of the discarded commits (if any)

    The log is generated by running ``git log --graph`` with the options
    specified in graphOpts.  The default is false.

multimailhook.refchangeShowLog

    If this option is set to true, then summary emails about reference
    changes will include a detailed log of the added commits in
    addition to the one line summary.  The log is generated by running
    ``git log`` with the options specified in multimailhook.logOpts.
    Default is false.

multimailhook.mailer

    This option changes the way emails are sent.  Accepted values are:

    - sendmail (the default): use the command ``/usr/sbin/sendmail`` or
      ``/usr/lib/sendmail`` (or sendmailCommand, if configured).  This
      mode can be further customized via the following options:

      * multimailhook.sendmailCommand

        The command used by mailer ``sendmail`` to send emails.  Shell
        quoting is allowed in the value of this setting, but remember that
        Git requires double-quotes to be escaped; e.g.::

             git config multimailhook.sendmailcommand '/usr/sbin/sendmail -oi -t -F \"Git Repo\"'

        Default is '/usr/sbin/sendmail -oi -t' or
        '/usr/lib/sendmail -oi -t' (depending on which file is
        present and executable).

      * multimailhook.envelopeSender

        If set then pass this value to sendmail via the -f option to set
        the envelope sender address.

    - smtp: use Python's smtplib.  This is useful when the sendmail
      command is not available on the system.  This mode can be
      further customized via the following options:

      * multimailhook.smtpServer

        The name of the SMTP server to connect to.  The value can
        also include a colon and a port number; e.g.,
        ``mail.example.com:25``.  Default is 'localhost' using port 25.

      * multimailhook.smtpUser
      * multimailhook.smtpPass

        Server username and password. Required if smtpEncryption is 'ssl'.
        Note that the username and password currently need to be
        set cleartext in the configuration file, which is not
        recommended. If you need to use this option, be sure your
        configuration file is read-only.

      * multimailhook.envelopeSender

        The sender address to be passed to the SMTP server.  If
        unset, then the value of multimailhook.from is used.

      * multimailhook.smtpServerTimeout

        Timeout in seconds.

      * multimailhook.smtpEncryption

        Set the security type. Allowed values: none, ssl, tls.
        Default=none.

      * multimailhook.smtpServerDebugLevel

        Integer number. Set to greater than 0 to activate debugging.

multimailhook.from
multimailhook.fromCommit
multimailhook.fromRefchange

    If set, use this value in the From: field of generated emails.
    ``fromCommit`` is used for commit emails, ``fromRefchange`` is
    used for refchange emails, and ``from`` is used as fall-back in
    all cases.

    The value for these variables can be either:

    - An email address, which will be used directly.

    - The value ``pusher``, in which case the pusher's address (if
      available) will be used.

    - The value ``author`` (meaningful only for replyToCommit), in which
      case the commit author's address will be used.

    If config values are unset, the value of the From: header is
    determined as follows:

    1. (gitolite environment only) Parse gitolite.conf, looking for a
       block of comments that looks like this::

           # BEGIN USER EMAILS
           # username Firstname Lastname <email@example.com>
           # END USER EMAILS

       If that block exists, and there is a line between the BEGIN
       USER EMAILS and END USER EMAILS lines where the first field
       matches the gitolite username ($GL_USER), use the rest of the
       line for the From: header.

    2. If the user.email configuration setting is set, use its value
       (and the value of user.name, if set).

    3. Use the value of multimailhook.envelopeSender.

multimailhook.administrator

    The name and/or email address of the administrator of the Git
    repository; used in FOOTER_TEMPLATE.  Default is
    multimailhook.envelopesender if it is set; otherwise a generic
    string is used.

multimailhook.emailPrefix

    All emails have this string prepended to their subjects, to aid
    email filtering (though filtering based on the X-Git-* email
    headers is probably more robust).  Default is the short name of
    the repository in square brackets; e.g., ``[myrepo]``.  Set this
    value to the empty string to suppress the email prefix.

multimailhook.emailMaxLines

    The maximum number of lines that should be included in the body of
    a generated email.  If not specified, there is no limit.  Lines
    beyond the limit are suppressed and counted, and a final line is
    added indicating the number of suppressed lines.

multimailhook.emailMaxLineLength

    The maximum length of a line in the email body.  Lines longer than
    this limit are truncated to this length with a trailing `` [...]``
    added to indicate the missing text.  The default is 500, because
    (a) diffs with longer lines are probably from binary files, for
    which a diff is useless, and (b) even if a text file has such long
    lines, the diffs are probably unreadable anyway.  To disable line
    truncation, set this option to 0.

multimailhook.maxCommitEmails

    The maximum number of commit emails to send for a given change.
    When the number of patches is larger that this value, only the
    summary refchange email is sent.  This can avoid accidental
    mailbombing, for example on an initial push.  To disable commit
    emails limit, set this option to 0.  The default is 500.

multimailhook.emailStrictUTF8

    If this boolean option is set to `true`, then the main part of the
    email body is forced to be valid UTF-8.  Any characters that are
    not valid UTF-8 are converted to the Unicode replacement
    character, U+FFFD.  The default is `true`.

multimailhook.diffOpts

    Options passed to ``git diff-tree`` when generating the summary
    information for ReferenceChange emails.  Default is ``--stat
    --summary --find-copies-harder``.  Add -p to those options to
    include a unified diff of changes in addition to the usual summary
    output.  Shell quoting is allowed; see multimailhook.logOpts for
    details.

multimailhook.graphOpts

    Options passed to ``git log --graph`` when generating graphs for the
    reference change summary emails (used only if refchangeShowGraph
    is true).  The default is '--oneline --decorate'.

    Shell quoting is allowed; see logOpts for details.

multimailhook.logOpts

    Options passed to ``git log`` to generate additional info for
    reference change emails (used only if refchangeShowLog is set).
    For example, adding -p will show each commit's complete diff.  The
    default is empty.

    Shell quoting is allowed; for example, a log format that contains
    spaces can be specified using something like::

      git config multimailhook.logopts '--pretty=format:"%h %aN <%aE>%n%s%n%n%b%n"'

    If you want to set this by editing your configuration file
    directly, remember that Git requires double-quotes to be escaped
    (see git-config(1) for more information)::

      [multimailhook]
              logopts = --pretty=format:\"%h %aN <%aE>%n%s%n%n%b%n\"

multimailhook.commitLogOpts

    Options passed to ``git log`` to generate additional info for
    revision change emails.  For example, adding --ignore-all-spaces
    will suppress whitespace changes.  The default options are ``-C
    --stat -p --cc``.  Shell quoting is allowed; see
    multimailhook.logOpts for details.

multimailhook.dateSubstitute

    String to use as a substitute for ``Date:`` in the output of ``git
    log`` while formatting commit messages. This is usefull to avoid
    emitting a line that can be interpreted by mailers as the start of
    a cited message (Zimbra webmail in particular). Defaults to
    ``CommitDate: ``. Set to an empty string or ``none`` to deactivate
    the behavior.

multimailhook.emailDomain

    Domain name appended to the username of the person doing the push
    to convert it into an email address
    (via ``"%s@%s" % (username, emaildomain)``). More complicated
    schemes can be implemented by overriding Environment and
    overriding its get_pusher_email() method.

multimailhook.replyTo
multimailhook.replyToCommit
multimailhook.replyToRefchange

    Addresses to use in the Reply-To: field for commit emails
    (replyToCommit) and refchange emails (replyToRefchange).
    multimailhook.replyTo is used as default when replyToCommit or
    replyToRefchange is not set. The shortcuts ``pusher`` and
    ``author`` are allowed with the same semantics as for
    ``multimailhook.from``. In addition, the value ``none`` can be
    used to omit the ``Reply-To:`` field.

    The default is ``pusher`` for refchange emails, and ``author`` for
    commit emails.

multimailhook.quiet

    Do not output the list of email recipients from the hook

multimailhook.stdout

    For debugging, send emails to stdout rather than to the
    mailer.  Equivalent to the --stdout command line option

multimailhook.scanCommitForCc

    If this option is set to true, than recipients from lines in commit body
    that starts with ``CC:`` will be added to CC list.
    Default: false

multimailhook.combineWhenSingleCommit

    If this option is set to true and a single new commit is pushed to
    a branch, combine the summary and commit email messages into a
    single email.
    Default: true

multimailhook.refFilterInclusionRegex
multimailhook.refFilterExclusionRegex
multimailhook.refFilterDoSendRegex
multimailhook.refFilterDontSendRegex

    **Warning:** these options are experimental. They should work, but
    the user-interface is not stable yet (in particular, the option
    names may change). If you want to participate in stabilizing the
    feature, please contact the maintainers and/or send pull-requests.

    Regular expressions that can be used to limit refs for which email
    updates will be sent.  It is an error to specify both an inclusion
    and an exclusion regex.  If a ``refFilterInclusionRegex`` is
    specified, emails will only be sent for refs which match this
    regex.  If a ``refFilterExclusionRegex`` regex is specified,
    emails will be sent for all refs except those that match this
    regex (or that match a predefined regex specific to the
    environment, such as "^refs/notes" for most environments and
    "^refs/notes|^refs/changes" for the gerrit environment).

    The expressions are matched against the complete refname, and is
    considered to match if any substring matches. For example, to
    filter-out all tags, set ``refFilterExclusionRegex`` to
    ``^refs/tags/`` (note the leading ``^`` but no trailing ``$``). If
    you set ``refFilterExclusionRegex`` to ``master``, then any ref
    containing ``master`` will be excluded (the ``master`` branch, but
    also ``refs/tags/master`` or ``refs/heads/foo-master-bar``).

    ``refFilterDoSendRegex`` and ``refFilterDontSendRegex`` are
    analogous to ``refFilterInclusionRegex`` and
    ``refFilterExclusionRegex`` with one difference: with
    ``refFilterDoSendRegex`` and ``refFilterDontSendRegex``, commits
    introduced by one excluded ref will not be considered as new when
    they reach an included ref. Typically, if you add a branch ``foo``
    to  ``refFilterDontSendRegex``, push commits to this branch, and
    later merge branch ``foo`` into ``master``, then the notification
    email for ``master`` will contain a commit email only for the
    merge commit. If you include ``foo`` in
    ``refFilterExclusionRegex``, then at the time of merge, you will
    receive one commit email per commit in the branch.

    These variables can be multi-valued, like::

      [multimailhook]
              refFilterExclusionRegex = ^refs/tags/
              refFilterExclusionRegex = ^refs/heads/master$

    You can also provide a whitespace-separated list like::

      [multimailhook]
              refFilterExclusionRegex = ^refs/tags/ ^refs/heads/master$

    Both examples exclude tags and the master branch, and are
    equivalent to::

      [multimailhook]
              refFilterExclusionRegex = ^refs/tags/|^refs/heads/master$

Email filtering aids
--------------------

All emails include extra headers to enable fine tuned filtering and
give information for debugging.  All emails include the headers
``X-Git-Host``, ``X-Git-Repo``, ``X-Git-Refname``, and ``X-Git-Reftype``.
ReferenceChange emails also include headers ``X-Git-Oldrev`` and ``X-Git-Newrev``;
Revision emails also include header ``X-Git-Rev``.


Customizing email contents
--------------------------

git-multimail mostly generates emails by expanding templates.  The
templates can be customized.  To avoid the need to edit
git_multimail.py directly, the preferred way to change the templates
is to write a separate Python script that imports git_multimail.py as
a module, then replaces the templates in place.  See the provided
post-receive script for an example of how this is done.


Customizing git-multimail for your environment
----------------------------------------------

git-multimail is mostly customized via an "environment" that describes
the local environment in which Git is running.  Two types of
environment are built in:

* GenericEnvironment: a stand-alone Git repository.

* GitoliteEnvironment: a Git repository that is managed by gitolite
  [3]_.  For such repositories, the identity of the pusher is read from
  environment variable $GL_USER, the name of the repository is read
  from $GL_REPO (if it is not overridden by multimailhook.reponame),
  and the From: header value is optionally read from gitolite.conf
  (see multimailhook.from).

By default, git-multimail assumes GitoliteEnvironment if $GL_USER and
$GL_REPO are set, and otherwise assumes GenericEnvironment.
Alternatively, you can choose one of these two environments explicitly
by setting a ``multimailhook.environment`` config setting (which can
have the value `generic` or `gitolite`) or by passing an --environment
option to the script.

If you need to customize the script in ways that are not supported by
the existing environments, you can define your own environment class
class using arbitrary Python code.  To do so, you need to import
git_multimail.py as a Python module, as demonstrated by the example
post-receive script.  Then implement your environment class; it should
usually inherit from one of the existing Environment classes and
possibly one or more of the EnvironmentMixin classes.  Then set the
``environment`` variable to an instance of your own environment class
and pass it to ``run_as_post_receive_hook()``.

The standard environment classes, GenericEnvironment and
GitoliteEnvironment, are in fact themselves put together out of a
number of mixin classes, each of which handles one aspect of the
customization.  For the finest control over your configuration, you
can specify exactly which mixin classes your own environment class
should inherit from, and override individual methods (or even add your
own mixin classes) to implement entirely new behaviors.  If you
implement any mixins that might be useful to other people, please
consider sharing them with the community!


Getting involved
----------------

Please, read `<CONTRIBUTING.rst>`__ for instructions on how to
contribute to git-multimail.


Footnotes
---------

.. [1] http://www.python.org/dev/peps/pep-0394/

.. [2] Because of the way information is passed to update hooks, the
       script's method of determining whether a commit has already
       been seen does not work when it is used as an ``update`` script.
       In particular, no notification email will be generated for a
       new commit that is added to multiple references in the same
       push. A workaround is to use --force-send to force sending the
       emails.

.. [3] https://github.com/sitaramc/gitolite