contrib/hooks/multimail/doc/gerrit.rst

   1 Setting up git-multimail on Gerrit
   2 ==================================
   3
   4 Gerrit has its own email-sending system, but you may prefer using
   5 ``git-multimail`` instead. It supports Gerrit natively as a Gerrit
   6 ``ref-updated`` hook (Warning: `Gerrit hooks
   7 <https://gerrit-review.googlesource.com/Documentation/config-hooks.html>`__
   8 are distinct from Git hooks). Setting up ``git-multimail`` on a Gerrit
   9 installation can be done following the instructions below.
  10
  11 The explanations show an easy way to set up ``git-multimail``,
  12 but leave ``git-multimail`` installed and unconfigured for a while. If
  13 you run Gerrit on a production server, it is advised that you
  14 execute the step "Set up the hook" last to avoid confusing your users
  15 in the meantime.
  16
  17 Set up the hook
  18 ---------------
  19
  20 Create a directory ``$site_path/hooks/`` if it does not exist (if you
  21 don't know what ``$site_path`` is, run ``gerrit.sh status`` and look
  22 for a ``GERRIT_SITE`` line). Either copy ``git_multimail.py`` to
  23 ``$site_path/hooks/ref-updated`` or create a wrapper script like
  24 this::
  25
  26   #! /bin/sh
  27   exec /path/to/git_multimail.py "$@"
  28
  29 In both cases, make sure the file is named exactly
  30 ``$site_path/hooks/ref-updated`` and is executable.
  31
  32 (Alternatively, you may configure the ``[hooks]`` section of
  33 gerrit.config)
  34
  35 Configuration
  36 -------------
  37
  38 Log on the gerrit server and edit ``$site_path/git/$project/config``
  39 to configure ``git-multimail``.
  40
  41 Troubleshooting
  42 ---------------
  43
  44 Warning: this will disable ``git-multimail`` during the debug, and
  45 could confuse your users. Don't run on a production server.
  46
  47 To debug configuration issues with ``git-multimail``, you can add the
  48 ``--stdout`` option when calling ``git_multimail.py`` like this::
  49
  50   #!/bin/sh
  51   exec /path/to/git-multimail/git-multimail/git_multimail.py \
  52     --stdout "$@" >> /tmp/log.txt
  53
  54 and try pushing from a test repository. You should see the source of
  55 the email that would have been sent in the output of ``git push`` in
  56 the file ``/tmp/log.txt``.