path: root/contrib/hooks/multimail/README

git-multimail version 1.4.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
[1]_.

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.)


Troubleshooting/FAQ
-------------------

Please read `<doc/troubleshooting.rst>`__ for frequently asked
questions and common issues with git-multimail.


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
      Environment to use when ``git-multimail`` is ran as a gitolite_
      hook.

      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