about summary refs log tree commit diff
path: root/third_party/git/contrib/hooks/multimail/doc/gitolite.rst
diff options
context:
space:
mode:
Diffstat (limited to 'third_party/git/contrib/hooks/multimail/doc/gitolite.rst')
-rw-r--r--third_party/git/contrib/hooks/multimail/doc/gitolite.rst118
1 files changed, 0 insertions, 118 deletions
diff --git a/third_party/git/contrib/hooks/multimail/doc/gitolite.rst b/third_party/git/contrib/hooks/multimail/doc/gitolite.rst
deleted file mode 100644
index 505483310552..000000000000
--- a/third_party/git/contrib/hooks/multimail/doc/gitolite.rst
+++ /dev/null
@@ -1,118 +0,0 @@
-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/git_multimail.py "$@"
-
-Make sure it's executable (``chmod +x``). Record the hook in
-gitolite::
-
-  gitolite setup
-
-Configuration
--------------
-
-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 git_multimail.py 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
-
-Note that by default, gitolite forbids ``<`` and ``>`` in variable
-values (for security/paranoia reasons, see
-`compensating for UNSAFE_PATT
-<http://gitolite.com/gitolite/git-config/index.html#compensating-for-unsafe95patt>`__
-in gitolite's documentation for explanations and a way to disable
-this). As a consequence, you will not be able to use ``First Last
-<First.Last@example.com>`` as recipient email, but specifying
-``First.Last@example.com`` alone works.
-
-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
-``../README``).
-
-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
-`here
-<http://gitolite.com/gitolite/git-config.html#an-important-warning-about-deleting-a-config-line>`__).
-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
-git-multimail.
-
-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
-`UNSAFE_PATT
-<http://gitolite.com/gitolite/git-config.html#unsafe-patt>`__ to a
-less restrictive value.
-
-Troubleshooting
----------------
-
-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 ``git_multimail.py`` like this::
-
-  #!/bin/sh
-  exec /path/to/git-multimail/git-multimail/git_multimail.py --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``.