git-multimail: update to release 1.2.0
[git] / 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``.