Merge branch 'jc/hashmap-doc-init' into maint
[git] / contrib / hooks / multimail / doc / gitolite.rst
1 Setting up git-multimail on gitolite
2 ====================================
3
4 ``git-multimail`` supports gitolite 3 natively.
5 The explanations below show an easy way to set up ``git-multimail``,
6 but leave ``git-multimail`` installed and unconfigured for a while. If
7 you run gitolite on a production server, it is advised that you
8 execute the step "Set up the hook" last to avoid confusing your users
9 in the meantime.
10
11 Set up the hook
12 ---------------
13
14 Log in as your gitolite user.
15
16 Create a file ``.gitolite/hooks/common/post-receive`` on your gitolite
17 account containing (adapt the path, obviously)::
18
19   #!/bin/sh
20   exec /path/to/git-multimail/git-multimail/git_multimail.py "$@"
21
22 Make sure it's executable (``chmod +x``). Record the hook in
23 gitolite::
24
25   gitolite setup
26
27 Configuration
28 -------------
29
30 First, you have to allow the admin to set Git configuration variables.
31
32 As gitolite user, edit the line containing ``GIT_CONFIG_KEYS`` in file
33 ``.gitolite.rc``, to make it look like::
34
35   GIT_CONFIG_KEYS                 =>  'multimailhook\..*',
36
37 You can now log out and return to your normal user.
38
39 In the ``gitolite-admin`` clone, edit the file ``conf/gitolite.conf``
40 and add::
41
42   repo @all
43       # Not strictly needed as git_multimail.py will chose gitolite if
44       # $GL_USER is set.
45       config multimailhook.environment = gitolite
46       config multimailhook.mailingList = # Where emails should be sent
47       config multimailhook.from = # From address to use
48
49 Obviously, you can customize all parameters on a per-repository basis by
50 adding these ``config multimailhook.*`` lines in the section
51 corresponding to a repository or set of repositories.
52
53 To activate ``git-multimail`` on a per-repository basis, do not set
54 ``multimailhook.mailingList`` in the ``@all`` section and set it only
55 for repositories for which you want ``git-multimail``.
56
57 Alternatively, you can set up the ``From:`` field on a per-user basis
58 by adding a ``BEGIN USER EMAILS``/``END USER EMAILS`` section (see
59 ``../README``).
60
61 Specificities of Gitolite for Configuration
62 -------------------------------------------
63
64 Empty configuration variables
65 .............................
66
67 With gitolite, the syntax ``config multimailhook.commitList = ""``
68 unsets the variable instead of setting it to an empty string (see
69 `here
70 <http://gitolite.com/gitolite/git-config.html#an-important-warning-about-deleting-a-config-line>`__).
71 As a result, there is no way to set a variable to the empty string.
72 In all most places where an empty value is required, git-multimail
73 now allows to specify special ``"none"`` value (case-sensitive) to
74 mean the same.
75
76 Alternatively, one can use ``" "`` (a single space) instead of ``""``.
77 In most cases (in particular ``multimailhook.*List`` variables), this
78 will be equivalent to an empty string.
79
80 If you have a use-case where ``"none"`` is not an acceptable value and
81 you need ``" "`` or  ``""`` instead, please report it as a bug to
82 git-multimail.
83
84 Allowing Regular Expressions in Configuration
85 .............................................
86
87 gitolite has a mechanism to prevent unsafe configuration variable
88 values, which prevent characters like ``|`` commonly used in regular
89 expressions. If you do not need the safety feature of gitolite and
90 need to use regular expressions in your configuration (e.g. for
91 ``multimailhook.refFilter*`` variables), set
92 `UNSAFE_PATT
93 <http://gitolite.com/gitolite/git-config.html#unsafe-patt>`__ to a
94 less restrictive value.
95
96 Troubleshooting
97 ---------------
98
99 Warning: this will disable ``git-multimail`` during the debug, and
100 could confuse your users. Don't run on a production server.
101
102 To debug configuration issues with ``git-multimail``, you can add the
103 ``--stdout`` option when calling ``git_multimail.py`` like this::
104
105   #!/bin/sh
106   exec /path/to/git-multimail/git-multimail/git_multimail.py --stdout "$@"
107
108 and try pushing from a test repository. You should see the source of
109 the email that would have been sent in the output of ``git push``.