tvl-depot/contrib/hooks/multimail/doc/gitolite.rst

Setting up git-multimail on gitolite
====================================

``git-multimail`` supports gitolite 3 natively.
The explanations below show an easy way to set up ``git-multimail``,
but leave ``git-multimail`` installed and unconfigured for a while. If
you run gitolite on a production server, it is advised that you
execute the step "Set up the hook" last to avoid confusing your users
in the meantime.

Set up the hook
---------------

Log in as your gitolite user.

Create a file ``.gitolite/hooks/common/post-receive`` on your gitolite
account containing (adapt the path, obviously)::

  #!/bin/sh
  exec /path/to/git-multimail/git-multimail/git_multimail.py "$@"

Make sure it's executable (``chmod +x``). Record the hook in
gitolite::

  gitolite setup

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

First, you have to allow the admin to set Git configuration variables.

As gitolite user, edit the line containing ``GIT_CONFIG_KEYS`` in file
``.gitolite.rc``, to make it look like::

  GIT_CONFIG_KEYS                 =>  'multimailhook\..*',

You can now log out and return to your normal user.

In the ``gitolite-admin`` clone, edit the file ``conf/gitolite.conf``
and add::

  repo @all
      # Not strictly needed as git_multimail.py will chose gitolite if
      # $GL_USER is set.
      config multimailhook.environment = gitolite
      config multimailhook.mailingList = # Where emails should be sent
      config multimailhook.from = # From address to use

Note that by default, gitolite forbids ``<`` and ``>`` in variable
values (for security/paranoia reasons, see
`compensating for UNSAFE_PATT
<http://gitolite.com/gitolite/git-config/index.html#compensating-for-unsafe95patt>`__
in gitolite's documentation for explanations and a way to disable
this). As a consequence, you will not be able to use ``First Last
<First.Last@example.com>`` as recipient email, but specifying
``First.Last@example.com`` alone works.

Obviously, you can customize all parameters on a per-repository basis by
adding these ``config multimailhook.*`` lines in the section
corresponding to a repository or set of repositories.

To activate ``git-multimail`` on a per-repository basis, do not set
``multimailhook.mailingList`` in the ``@all`` section and set it only
for repositories for which you want ``git-multimail``.

Alternatively, you can set up the ``From:`` field on a per-user basis
by adding a ``BEGIN USER EMAILS``/``END USER EMAILS`` section (see
``../README``).

Specificities of Gitolite for Configuration
-------------------------------------------

Empty configuration variables
.............................

With gitolite, the syntax ``config multimailhook.commitList = ""``
unsets the variable instead of setting it to an empty string (see
`here
<http://gitolite.com/gitolite/git-config.html#an-important-warning-about-deleting-a-config-line>`__).
As a result, there is no way to set a variable to the empty string.
In all most places where an empty value is required, git-multimail
now allows to specify special ``"none"`` value (case-sensitive) to
mean the same.

Alternatively, one can use ``" "`` (a single space) instead of ``""``.
In most cases (in particular ``multimailhook.*List`` variables), this
will be equivalent to an empty string.

If you have a use-case where ``"none"`` is not an acceptable value and
you need ``" "`` or  ``""`` instead, please report it as a bug to
git-multimail.

Allowing Regular Expressions in Configuration
.............................................

gitolite has a mechanism to prevent unsafe configuration variable
values, which prevent characters like ``|`` commonly used in regular
expressions. If you do not need the safety feature of gitolite and
need to use regular expressions in your configuration (e.g. for
``multimailhook.refFilter*`` variables), set
`UNSAFE_PATT
<http://gitolite.com/gitolite/git-config.html#unsafe-patt>`__ to a
less restrictive value.

Troubleshooting
---------------

Warning: this will disable ``git-multimail`` during the debug, and
could confuse your users. Don't run on a production server.

To debug configuration issues with ``git-multimail``, you can add the
``--stdout`` option when calling ``git_multimail.py`` like this::

  #!/bin/sh
  exec /path/to/git-multimail/git-multimail/git_multimail.py --stdout "$@"

and try pushing from a test repository. You should see the source of
the email that would have been sent in the output of ``git push``.