diff options
Diffstat (limited to 'contrib/hooks/multimail/doc')
| -rw-r--r-- | contrib/hooks/multimail/doc/customizing-emails.rst | 56 | ||||
| -rw-r--r-- | contrib/hooks/multimail/doc/gerrit.rst | 56 | ||||
| -rw-r--r-- | contrib/hooks/multimail/doc/gitolite.rst | 118 | ||||
| -rw-r--r-- | contrib/hooks/multimail/doc/troubleshooting.rst | 78 |
4 files changed, 0 insertions, 308 deletions
diff --git a/contrib/hooks/multimail/doc/customizing-emails.rst b/contrib/hooks/multimail/doc/customizing-emails.rst deleted file mode 100644 index 3f5b67f768..0000000000 --- a/contrib/hooks/multimail/doc/customizing-emails.rst +++ /dev/null @@ -1,56 +0,0 @@ -Customizing the content and formatting of emails -================================================ - -Overloading template strings ----------------------------- - -The content of emails is generated based on template strings defined -in ``git_multimail.py``. You can customize these template strings -without changing the script itself, by defining a Python wrapper -around it. The python wrapper should ``import git_multimail`` and then -override the ``git_multimail.*`` strings like this:: - - import sys # needed for sys.argv - - # Import and customize git_multimail: - import git_multimail - git_multimail.REVISION_INTRO_TEMPLATE = """...""" - git_multimail.COMBINED_INTRO_TEMPLATE = git_multimail.REVISION_INTRO_TEMPLATE - - # start git_multimail itself: - git_multimail.main(sys.argv[1:]) - -The template strings can use any value already used in the existing -templates (read the source code). - -Using HTML in template strings ------------------------------- - -If ``multimailhook.commitEmailFormat`` is set to HTML, then -git-multimail will generate HTML emails for commit notifications. The -log and diff will be formatted automatically by git-multimail. By -default, any HTML special character in the templates will be escaped. - -To use HTML formatting in the introduction of the email, set -``multimailhook.htmlInIntro`` to ``true``. Then, the template can -contain any HTML tags, that will be sent as-is in the email. For -example, to add some formatting and a link to the online commit, use -a format like:: - - git_multimail.REVISION_INTRO_TEMPLATE = """\ - <span style="color:#808080">This is an automated email from the git hooks/post-receive script.</span><br /><br /> - - <strong>%(pusher)s</strong> pushed a commit to %(refname_type)s %(short_refname)s - in repository %(repo_shortname)s.<br /> - - <a href="https://github.com/git-multimail/git-multimail/commit/%(newrev)s">View on GitHub</a>. - """ - -Note that the values expanded from ``%(variable)s`` in the format -strings will still be escaped. - -For a less flexible but easier to set up way to add a link to commit -emails, see ``multimailhook.commitBrowseURL``. - -Similarly, one can set ``multimailhook.htmlInFooter`` and override any -of the ``*_FOOTER*`` template strings. diff --git a/contrib/hooks/multimail/doc/gerrit.rst b/contrib/hooks/multimail/doc/gerrit.rst deleted file mode 100644 index 8011d05dec..0000000000 --- a/contrib/hooks/multimail/doc/gerrit.rst +++ /dev/null @@ -1,56 +0,0 @@ -Setting up git-multimail on Gerrit -================================== - -Gerrit has its own email-sending system, but you may prefer using -``git-multimail`` instead. It supports Gerrit natively as a Gerrit -``ref-updated`` hook (Warning: `Gerrit hooks -<https://gerrit-review.googlesource.com/Documentation/config-hooks.html>`__ -are distinct from Git hooks). Setting up ``git-multimail`` on a Gerrit -installation can be done following the instructions below. - -The explanations show an easy way to set up ``git-multimail``, -but leave ``git-multimail`` installed and unconfigured for a while. If -you run Gerrit 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 ---------------- - -Create a directory ``$site_path/hooks/`` if it does not exist (if you -don't know what ``$site_path`` is, run ``gerrit.sh status`` and look -for a ``GERRIT_SITE`` line). Either copy ``git_multimail.py`` to -``$site_path/hooks/ref-updated`` or create a wrapper script like -this:: - - #! /bin/sh - exec /path/to/git_multimail.py "$@" - -In both cases, make sure the file is named exactly -``$site_path/hooks/ref-updated`` and is executable. - -(Alternatively, you may configure the ``[hooks]`` section of -gerrit.config) - -Configuration -------------- - -Log on the gerrit server and edit ``$site_path/git/$project/config`` -to configure ``git-multimail``. - -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 "$@" >> /tmp/log.txt - -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`` in -the file ``/tmp/log.txt``. diff --git a/contrib/hooks/multimail/doc/gitolite.rst b/contrib/hooks/multimail/doc/gitolite.rst deleted file mode 100644 index 5054833105..0000000000 --- a/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``. diff --git a/contrib/hooks/multimail/doc/troubleshooting.rst b/contrib/hooks/multimail/doc/troubleshooting.rst deleted file mode 100644 index 651b509ee6..0000000000 --- a/contrib/hooks/multimail/doc/troubleshooting.rst +++ /dev/null @@ -1,78 +0,0 @@ -Troubleshooting issues with git-multimail: a FAQ -================================================ - -How to check that git-multimail is properly set up? ---------------------------------------------------- - -Since version 1.4.0, git-multimail allows a simple self-checking of -its configuration: run it with the environment variable -``GIT_MULTIMAIL_CHECK_SETUP`` set to a non-empty string. You should -get something like this:: - - $ GIT_MULTIMAIL_CHECK_SETUP=true /home/moy/dev/git-multimail/git-multimail/git_multimail.py - Environment values: - administrator : 'the administrator of this repository' - charset : 'utf-8' - emailprefix : '[git-multimail] ' - fqdn : 'anie' - projectdesc : 'UNNAMED PROJECT' - pusher : 'moy' - repo_path : '/home/moy/dev/git-multimail' - repo_shortname : 'git-multimail' - - Now, checking that git-multimail's standard input is properly set ... - Please type some text and then press Return - foo - You have just entered: - foo - git-multimail seems properly set up. - -If you forgot to set an important variable, you may get instead:: - - $ GIT_MULTIMAIL_CHECK_SETUP=true /home/moy/dev/git-multimail/git-multimail/git_multimail.py - No email recipients configured! - -Do not set ``$GIT_MULTIMAIL_CHECK_SETUP`` other than for testing your -configuration: it would disable the hook completely. - -Git is not using the right address in the From/To/Reply-To field ----------------------------------------------------------------- - -First, make sure that git-multimail actually uses what you think it is -using. A lot happens to your email (especially when posting to a -mailing-list) between the time `git_multimail.py` sends it and the -time it reaches your inbox. - -A simple test (to do on a test repository, do not use in production as -it would disable email sending): change your post-receive hook to call -`git_multimail.py` with the `--stdout` option, and try to push to the -repository. You should see something like:: - - Counting objects: 3, done. - Writing objects: 100% (3/3), 263 bytes | 0 bytes/s, done. - Total 3 (delta 0), reused 0 (delta 0) - remote: Sending notification emails to: foo.bar@example.com - remote: =========================================================================== - remote: Date: Mon, 25 Apr 2016 18:39:59 +0200 - remote: To: foo.bar@example.com - remote: Subject: [git] branch master updated: foo - remote: MIME-Version: 1.0 - remote: Content-Type: text/plain; charset=utf-8 - remote: Content-Transfer-Encoding: 8bit - remote: Message-ID: <20160425163959.2311.20498@anie> - remote: From: Auth Or <Foo.Bar@example.com> - remote: Reply-To: Auth Or <Foo.Bar@example.com> - remote: X-Git-Host: example - ... - remote: -- - remote: To stop receiving notification emails like this one, please contact - remote: the administrator of this repository. - remote: =========================================================================== - To /path/to/repo - 6278f04..e173f20 master -> master - -Note: this does not include the sender (Return-Path: header), as it is -not part of the message content but passed to the mailer. Some mailer -show the ``Sender:`` field instead of the ``From:`` field (for -example, Zimbra Webmail shows ``From: <sender-field> on behalf of -<from-field>``). |