Squashed 'third_party/git/' content from commit cb71568594
git-subtree-dir: third_party/git git-subtree-split: cb715685942260375e1eb8153b0768a376e4ece7
This commit is contained in:
Vincent Ambo
commit
1b593e1ea4
3629 changed files with 1139935 additions and 0 deletions
56
contrib/hooks/multimail/doc/customizing-emails.rst
Normal file
56
contrib/hooks/multimail/doc/customizing-emails.rst
Normal file
|
|
@ -0,0 +1,56 @@
|
|||
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.
|
||||
56
contrib/hooks/multimail/doc/gerrit.rst
Normal file
56
contrib/hooks/multimail/doc/gerrit.rst
Normal file
|
|
@ -0,0 +1,56 @@
|
|||
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``.
|
||||
118
contrib/hooks/multimail/doc/gitolite.rst
Normal file
118
contrib/hooks/multimail/doc/gitolite.rst
Normal file
|
|
@ -0,0 +1,118 @@
|
|||
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``.
|
||||
78
contrib/hooks/multimail/doc/troubleshooting.rst
Normal file
78
contrib/hooks/multimail/doc/troubleshooting.rst
Normal file
|
|
@ -0,0 +1,78 @@
|
|||
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>``).
|
||||
Loading…
Add table
Add a link
Reference in a new issue