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