path: root/contrib/hooks/multimail/doc/gitolite.rst
diff options
Diffstat (limited to 'contrib/hooks/multimail/doc/gitolite.rst')
1 files changed, 109 insertions, 0 deletions
diff --git a/contrib/hooks/multimail/doc/gitolite.rst b/contrib/hooks/multimail/doc/gitolite.rst
new file mode 100644
index 0000000..00aedd9
--- /dev/null
+++ b/contrib/hooks/multimail/doc/gitolite.rst
@@ -0,0 +1,109 @@
+Setting up git-multimail on gitolite
+``git-multimail`` supports gitolite 3 natively.
+The explanations below show an easy way to set up ``git-multimail``,
+but leave ``git-multimail`` installed and unconfigured for a while. If
+you run gitolite on a production server, it is advised that you
+execute the step "Set up the hook" last to avoid confusing your users
+in the meantime.
+Set up the hook
+Log in as your gitolite user.
+Create a file ``.gitolite/hooks/common/post-receive`` on your gitolite
+account containing (adapt the path, obviously)::
+ #!/bin/sh
+ exec /path/to/git-multimail/git-multimail/ "$@"
+Make sure it's executable (``chmod +x``). Record the hook in
+ gitolite setup
+First, you have to allow the admin to set Git configuration variables.
+As gitolite user, edit the line containing ``GIT_CONFIG_KEYS`` in file
+``.gitolite.rc``, to make it look like::
+ GIT_CONFIG_KEYS => 'multimailhook\..*',
+You can now log out and return to your normal user.
+In the ``gitolite-admin`` clone, edit the file ``conf/gitolite.conf``
+and add::
+ repo @all
+ # Not strictly needed as will chose gitolite if
+ # $GL_USER is set.
+ config multimailhook.environment = gitolite
+ config multimailhook.mailingList = # Where emails should be sent
+ config multimailhook.from = # From address to use
+Obviously, you can customize all parameters on a per-repository basis by
+adding these ``config multimailhook.*`` lines in the section
+corresponding to a repository or set of repositories.
+To activate ``git-multimail`` on a per-repository basis, do not set
+``multimailhook.mailingList`` in the ``@all`` section and set it only
+for repositories for which you want ``git-multimail``.
+Alternatively, you can set up the ``From:`` field on a per-user basis
+by adding a ``BEGIN USER EMAILS``/``END USER EMAILS`` section (see
+Specificities of Gitolite for Configuration
+Empty configuration variables
+With gitolite, the syntax ``config multimailhook.commitList = ""``
+unsets the variable instead of setting it to an empty string (see
+As a result, there is no way to set a variable to the empty string.
+In all most places where an empty value is required, git-multimail
+now allows to specify special ``"none"`` value (case-sensitive) to
+mean the same.
+Alternatively, one can use ``" "`` (a single space) instead of ``""``.
+In most cases (in particular ``multimailhook.*List`` variables), this
+will be equivalent to an empty string.
+If you have a use-case where ``"none"`` is not an acceptable value and
+you need ``" "`` or ``""`` instead, please report it as a bug to
+Allowing Regular Expressions in Configuration
+gitolite has a mechanism to prevent unsafe configuration variable
+values, which prevent characters like ``|`` commonly used in regular
+expressions. If you do not need the safety feature of gitolite and
+need to use regular expressions in your configuration (e.g. for
+``multimailhook.refFilter*`` variables), set
+<>`__ to a
+less restrictive value.
+Warning: this will disable ``git-multimail`` during the debug, and
+could confuse your users. Don't run on a production server.
+To debug configuration issues with ``git-multimail``, you can add the
+``--stdout`` option when calling ```` like this::
+ #!/bin/sh
+ exec /path/to/git-multimail/git-multimail/ --stdout "$@"
+and try pushing from a test repository. You should see the source of
+the email that would have been sent in the output of ``git push``.