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 Note that by default, gitolite forbids ``<`` and ``>`` in variable
  50 values (for security/paranoia reasons, see
  51 `compensating for UNSAFE_PATT
  52 <http://gitolite.com/gitolite/git-config/index.html#compensating-for-unsafe95patt>`__
  53 in gitolite's documentation for explanations and a way to disable
  54 this). As a consequence, you will not be able to use ``First Last
  55 <First.Last@example.com>`` as recipient email, but specifying
  56 ``First.Last@example.com`` alone works.
  57
  58 Obviously, you can customize all parameters on a per-repository basis by
  59 adding these ``config multimailhook.*`` lines in the section
  60 corresponding to a repository or set of repositories.
  61
  62 To activate ``git-multimail`` on a per-repository basis, do not set
  63 ``multimailhook.mailingList`` in the ``@all`` section and set it only
  64 for repositories for which you want ``git-multimail``.
  65
  66 Alternatively, you can set up the ``From:`` field on a per-user basis
  67 by adding a ``BEGIN USER EMAILS``/``END USER EMAILS`` section (see
  68 ``../README``).
  69
  70 Specificities of Gitolite for Configuration
  71 -------------------------------------------
  72
  73 Empty configuration variables
  74 .............................
  75
  76 With gitolite, the syntax ``config multimailhook.commitList = ""``
  77 unsets the variable instead of setting it to an empty string (see
  78 `here
  79 <http://gitolite.com/gitolite/git-config.html#an-important-warning-about-deleting-a-config-line>`__).
  80 As a result, there is no way to set a variable to the empty string.
  81 In all most places where an empty value is required, git-multimail
  82 now allows to specify special ``"none"`` value (case-sensitive) to
  83 mean the same.
  84
  85 Alternatively, one can use ``" "`` (a single space) instead of ``""``.
  86 In most cases (in particular ``multimailhook.*List`` variables), this
  87 will be equivalent to an empty string.
  88
  89 If you have a use-case where ``"none"`` is not an acceptable value and
  90 you need ``" "`` or  ``""`` instead, please report it as a bug to
  91 git-multimail.
  92
  93 Allowing Regular Expressions in Configuration
  94 .............................................
  95
  96 gitolite has a mechanism to prevent unsafe configuration variable
  97 values, which prevent characters like ``|`` commonly used in regular
  98 expressions. If you do not need the safety feature of gitolite and
  99 need to use regular expressions in your configuration (e.g. for
 100 ``multimailhook.refFilter*`` variables), set
 101 `UNSAFE_PATT
 102 <http://gitolite.com/gitolite/git-config.html#unsafe-patt>`__ to a
 103 less restrictive value.
 104
 105 Troubleshooting
 106 ---------------
 107
 108 Warning: this will disable ``git-multimail`` during the debug, and
 109 could confuse your users. Don't run on a production server.
 110
 111 To debug configuration issues with ``git-multimail``, you can add the
 112 ``--stdout`` option when calling ``git_multimail.py`` like this::
 113
 114   #!/bin/sh
 115   exec /path/to/git-multimail/git-multimail/git_multimail.py --stdout "$@"
 116
 117 and try pushing from a test repository. You should see the source of
 118 the email that would have been sent in the output of ``git push``.