contrib / hooks / multimail / doc / gerrit.rston commit Merge branch 'cc/fetch-error-message-fix' (61c51ac)
   1Setting up git-multimail on Gerrit
   2==================================
   3
   4Gerrit 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>`__
   8are distinct from Git hooks). Setting up ``git-multimail`` on a Gerrit
   9installation can be done following the instructions below.
  10
  11The explanations show an easy way to set up ``git-multimail``,
  12but leave ``git-multimail`` installed and unconfigured for a while. If
  13you run Gerrit on a production server, it is advised that you
  14execute the step "Set up the hook" last to avoid confusing your users
  15in the meantime.
  16
  17Set up the hook
  18---------------
  19
  20Create a directory ``$site_path/hooks/`` if it does not exist (if you
  21don't know what ``$site_path`` is, run ``gerrit.sh status`` and look
  22for a ``GERRIT_SITE`` line). Either copy ``git_multimail.py`` to
  23``$site_path/hooks/ref-updated`` or create a wrapper script like
  24this::
  25
  26  #! /bin/sh
  27  exec /path/to/git_multimail.py "$@"
  28
  29In 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
  33gerrit.config)
  34
  35Configuration
  36-------------
  37
  38Log on the gerrit server and edit ``$site_path/git/$project/config``
  39to configure ``git-multimail``.
  40
  41Troubleshooting
  42---------------
  43
  44Warning: this will disable ``git-multimail`` during the debug, and
  45could confuse your users. Don't run on a production server.
  46
  47To 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
  54and try pushing from a test repository. You should see the source of
  55the email that would have been sent in the output of ``git push`` in
  56the file ``/tmp/log.txt``.