mirror of
https://github.com/git/git
synced 2024-08-28 20:20:07 +00:00
git-multimail: update to release 1.2.0
The changes are described in CHANGES. Contributions-by: Matthieu Moy <Matthieu.Moy@imag.fr> Contributions-by: Elijah Newren <newren@palantir.com> Contributions-by: Edward d'Auvergne <edward@nmr-relax.com> Contributions-by: Vadim Zeitlin <vadim@zeitlins.org> Contributions-by: Paul Sokolovsky <paul.sokolovsky@linaro.org> Contributions-by: Michael Haggerty <mhagger@alum.mit.edu> Contributions-by: Elijah Newren <newren@gmail.com> Contributions-by: Richard Hansen <rhansen@rhansen.org> Contributions-by: Job Snijders <job@instituut.net> Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
parent
f5b6079871
commit
4b1fd356b8
|
@ -1,3 +1,44 @@
|
||||||
|
Release 1.2.0
|
||||||
|
=============
|
||||||
|
|
||||||
|
* It is now possible to exclude some refs (e.g. exclude some branches
|
||||||
|
or tags). See refFilterDoSendRegex, refFilterDontSendRegex,
|
||||||
|
refFilterInclusionRegex and refFilterExclusionRegex.
|
||||||
|
|
||||||
|
* New commitEmailFormat option which can be set to "html" to generate
|
||||||
|
simple colorized diffs using HTML for the commit emails.
|
||||||
|
|
||||||
|
* git-multimail can now be ran as a Gerrit ref-updated hook, or from
|
||||||
|
Atlassian BitBucket Server (formerly known as Atlassian Stash).
|
||||||
|
|
||||||
|
* The From: field is now more customizeable. It can be set
|
||||||
|
independently for refchange emails and commit emails (see
|
||||||
|
fromCommit, fromRefChange). The special values pusher and author can
|
||||||
|
be used in these configuration variable.
|
||||||
|
|
||||||
|
* A new command-line option, --version, was added. The version is also
|
||||||
|
available in the X-Git-Multimail-Version header of sent emails.
|
||||||
|
|
||||||
|
* Set X-Git-NotificationType header to differentiate the various types
|
||||||
|
of notifications. Current values are: diff, ref_changed_plus_diff,
|
||||||
|
ref_changed.
|
||||||
|
|
||||||
|
* Preliminary support for Python 3. The testsuite passes with Python 3,
|
||||||
|
but it has not received as much testing as the Python 2 version yet.
|
||||||
|
|
||||||
|
* Several encoding-related fixes. UTF-8 characters work in more
|
||||||
|
situations (but non-ascii characters in email address are still not
|
||||||
|
supported).
|
||||||
|
|
||||||
|
* The testsuite and its documentation has been greatly improved.
|
||||||
|
|
||||||
|
Plus all the bugfixes from version 1.1.1.
|
||||||
|
|
||||||
|
This version has been tested with Python 2.4 and 2.6 to 3.5, and Git
|
||||||
|
v1.7.10-406-gdc801e7, git-1.8.2.3 and 2.6.0. Git versions prior to
|
||||||
|
v1.7.10-406-gdc801e7 probably work, but cannot run the testsuite
|
||||||
|
properly.
|
||||||
|
|
||||||
Release 1.1.1 (bugfix-only release)
|
Release 1.1.1 (bugfix-only release)
|
||||||
===================================
|
===================================
|
||||||
|
|
||||||
|
|
30
contrib/hooks/multimail/CONTRIBUTING.rst
Normal file
30
contrib/hooks/multimail/CONTRIBUTING.rst
Normal file
|
@ -0,0 +1,30 @@
|
||||||
|
git-multimail is an open-source project, built by volunteers. We would
|
||||||
|
welcome your help!
|
||||||
|
|
||||||
|
The current maintainers are Michael Haggerty <mhagger@alum.mit.edu>
|
||||||
|
and Matthieu Moy <matthieu.moy@grenoble-inp.fr>.
|
||||||
|
|
||||||
|
Please note that although a copy of git-multimail is distributed in
|
||||||
|
the "contrib" section of the main Git project, development takes place
|
||||||
|
in a separate git-multimail repository on GitHub:
|
||||||
|
|
||||||
|
https://github.com/git-multimail/git-multimail
|
||||||
|
|
||||||
|
Whenever enough changes to git-multimail have accumulated, a new
|
||||||
|
code-drop of git-multimail will be submitted for inclusion in the Git
|
||||||
|
project.
|
||||||
|
|
||||||
|
We use the GitHub issue tracker to keep track of bugs and feature
|
||||||
|
requests, and we use GitHub pull requests to exchange patches (though,
|
||||||
|
if you prefer, you can send patches via the Git mailing list with CC
|
||||||
|
to the maintainers). Please sign off your patches as per the `Git
|
||||||
|
project practice
|
||||||
|
<https://github.com/git/git/blob/master/Documentation/SubmittingPatches#L234>`__.
|
||||||
|
|
||||||
|
General discussion of git-multimail can take place on the main Git
|
||||||
|
mailing list,
|
||||||
|
|
||||||
|
git@vger.kernel.org
|
||||||
|
|
||||||
|
Please CC emails regarding git-multimail to the maintainers so that we
|
||||||
|
don't overlook them.
|
|
@ -1,5 +1,5 @@
|
||||||
git-multimail Version 1.1.1
|
git-multimail (version 1.2.0)
|
||||||
===========================
|
=============================
|
||||||
|
|
||||||
.. image:: https://travis-ci.org/git-multimail/git-multimail.svg?branch=master
|
.. image:: https://travis-ci.org/git-multimail/git-multimail.svg?branch=master
|
||||||
:target: https://travis-ci.org/git-multimail/git-multimail
|
:target: https://travis-ci.org/git-multimail/git-multimail
|
||||||
|
@ -53,11 +53,13 @@ By default, for each push received by the repository, git-multimail:
|
||||||
+ [git] 07/08: Merge branch 'mm/api-credentials-doc'
|
+ [git] 07/08: Merge branch 'mm/api-credentials-doc'
|
||||||
+ [git] 08/08: Git 1.7.11-rc2
|
+ [git] 08/08: Git 1.7.11-rc2
|
||||||
|
|
||||||
Each commit appears in exactly one commit email, the first time
|
By default, each commit appears in exactly one commit email, the
|
||||||
that it is pushed to the repository. If a commit is later merged
|
first time that it is pushed to the repository. If a commit is later
|
||||||
into another branch, then a one-line summary of the commit is
|
merged into another branch, then a one-line summary of the commit
|
||||||
included in the reference change email (as usual), but no
|
is included in the reference change email (as usual), but no
|
||||||
additional commit email is generated.
|
additional commit email is generated. See
|
||||||
|
`multimailhook.refFilter(Inclusion|Exclusion|DoSend|DontSend)Regex`
|
||||||
|
below to configure which branches and tags are watched by the hook.
|
||||||
|
|
||||||
By default, reference change emails have their "Reply-To" field set
|
By default, reference change emails have their "Reply-To" field set
|
||||||
to the person who pushed the change, and commit emails have their
|
to the person who pushed the change, and commit emails have their
|
||||||
|
@ -73,21 +75,8 @@ Requirements
|
||||||
------------
|
------------
|
||||||
|
|
||||||
* Python 2.x, version 2.4 or later. No non-standard Python modules
|
* Python 2.x, version 2.4 or later. No non-standard Python modules
|
||||||
are required. git-multimail does *not* currently work with Python
|
are required. git-multimail has preliminary support for Python 3
|
||||||
3.x.
|
(but it has been better tested with Python 2).
|
||||||
|
|
||||||
The example scripts invoke Python using the following shebang line
|
|
||||||
(following PEP 394 [1]_)::
|
|
||||||
|
|
||||||
#! /usr/bin/env python2
|
|
||||||
|
|
||||||
If your system's Python2 interpreter is not in your PATH or is not
|
|
||||||
called ``python2``, you can change the lines accordingly. Or you can
|
|
||||||
invoke the Python interpreter explicitly, for example via a tiny
|
|
||||||
shell script like::
|
|
||||||
|
|
||||||
#! /bin/sh
|
|
||||||
/usr/local/bin/python /path/to/git_multimail.py "$@"
|
|
||||||
|
|
||||||
* The ``git`` command must be in your PATH. git-multimail is known to
|
* The ``git`` command must be in your PATH. git-multimail is known to
|
||||||
work with Git versions back to 1.7.1. (Earlier versions have not
|
work with Git versions back to 1.7.1. (Earlier versions have not
|
||||||
|
@ -146,7 +135,9 @@ following ``git config`` settings:
|
||||||
|
|
||||||
multimailhook.environment
|
multimailhook.environment
|
||||||
|
|
||||||
This describes the general environment of the repository.
|
This describes the general environment of the repository. In most
|
||||||
|
cases, you do not need to specify a value for this variable:
|
||||||
|
`git-multimail` will autodetect which environment to use.
|
||||||
Currently supported values:
|
Currently supported values:
|
||||||
|
|
||||||
* generic
|
* generic
|
||||||
|
@ -161,18 +152,57 @@ multimailhook.environment
|
||||||
optionally read from gitolite.conf (see multimailhook.from).
|
optionally read from gitolite.conf (see multimailhook.from).
|
||||||
|
|
||||||
For more information about gitolite and git-multimail, read
|
For more information about gitolite and git-multimail, read
|
||||||
doc/gitolite.rst
|
`<doc/gitolite.rst>`__
|
||||||
|
|
||||||
If neither of these environments is suitable for your setup, then
|
* stash
|
||||||
you can implement a Python class that inherits from Environment
|
|
||||||
and instantiate it via a script that looks like the example
|
Environment to use when ``git-multimail`` is ran as an Atlassian
|
||||||
|
BitBucket Server (formerly known as Atlassian Stash) hook.
|
||||||
|
|
||||||
|
**Warning:** this mode was provided by a third-party contributor
|
||||||
|
and never tested by the git-multimail maintainers. It is
|
||||||
|
provided as-is and may or may not work for you.
|
||||||
|
|
||||||
|
This value is automatically assumed when the stash-specific
|
||||||
|
flags (``--stash-user`` and ``--stash-repo``) are specified on
|
||||||
|
the command line. When this environment is active, the username
|
||||||
|
and repo come from these two command line flags, which must be
|
||||||
|
specified.
|
||||||
|
|
||||||
|
* gerrit
|
||||||
|
|
||||||
|
Environment to use when ``git-multimail`` is ran as a
|
||||||
|
``ref-updated`` Gerrit hook.
|
||||||
|
|
||||||
|
This value is used when the gerrit-specific command line flags
|
||||||
|
(``--oldrev``, ``--newrev``, ``--refname``, ``--project``) for
|
||||||
|
gerrit's ref-updated hook are present. When this environment is
|
||||||
|
active, the username of the pusher is taken from the
|
||||||
|
``--submitter`` argument if that command line option is passed,
|
||||||
|
otherwise 'Gerrit' is used. The repository name is taken from
|
||||||
|
the ``--project`` option on the command line, which must be passed.
|
||||||
|
|
||||||
|
For more information about gerrit and git-multimail, read
|
||||||
|
`<doc/gerrit.rst>`__
|
||||||
|
|
||||||
|
If none of these environments is suitable for your setup, then you
|
||||||
|
can implement a Python class that inherits from Environment and
|
||||||
|
instantiate it via a script that looks like the example
|
||||||
post-receive script.
|
post-receive script.
|
||||||
|
|
||||||
The environment value can be specified on the command line using
|
The environment value can be specified on the command line using
|
||||||
the --environment option. If it is not specified on the command
|
the ``--environment`` option. If it is not specified on the
|
||||||
line or by multimailhook.environment, then it defaults to
|
command line or by ``multimailhook.environment``, the value is
|
||||||
``gitolite`` if the environment contains variables $GL_USER and
|
guessed as follows:
|
||||||
$GL_REPO; otherwise ``generic``.
|
|
||||||
|
* If stash-specific (respectively gerrit-specific) command flags
|
||||||
|
are present on the command-line, then ``stash`` (respectively
|
||||||
|
``gerrit``) is used.
|
||||||
|
|
||||||
|
* If the environment variables $GL_USER and $GL_REPO are set, then
|
||||||
|
``gitolite`` is used.
|
||||||
|
|
||||||
|
* If none of the above apply, then ``generic`` is used.
|
||||||
|
|
||||||
multimailhook.repoName
|
multimailhook.repoName
|
||||||
|
|
||||||
|
@ -196,8 +226,8 @@ multimailhook.refchangeList
|
||||||
reference changes should be sent, as RFC 2822 email addresses
|
reference changes should be sent, as RFC 2822 email addresses
|
||||||
separated by commas. This configuration option can be
|
separated by commas. This configuration option can be
|
||||||
multivalued. The default is the value in
|
multivalued. The default is the value in
|
||||||
multimailhook.mailingList. Set this value to the empty string to
|
multimailhook.mailingList. Set this value to "none" (or the empty
|
||||||
prevent reference change emails from being sent even if
|
string) to prevent reference change emails from being sent even if
|
||||||
multimailhook.mailingList is set.
|
multimailhook.mailingList is set.
|
||||||
|
|
||||||
multimailhook.announceList
|
multimailhook.announceList
|
||||||
|
@ -206,9 +236,9 @@ multimailhook.announceList
|
||||||
tags should be sent, as RFC 2822 email addresses separated by
|
tags should be sent, as RFC 2822 email addresses separated by
|
||||||
commas. This configuration option can be multivalued. The
|
commas. This configuration option can be multivalued. The
|
||||||
default is the value in multimailhook.refchangeList or
|
default is the value in multimailhook.refchangeList or
|
||||||
multimailhook.mailingList. Set this value to the empty string to
|
multimailhook.mailingList. Set this value to "none" (or the empty
|
||||||
prevent annotated tag announcement emails from being sent even if
|
string) to prevent annotated tag announcement emails from being sent
|
||||||
one of the other values is set.
|
even if one of the other values is set.
|
||||||
|
|
||||||
multimailhook.commitList
|
multimailhook.commitList
|
||||||
|
|
||||||
|
@ -216,7 +246,7 @@ multimailhook.commitList
|
||||||
commits should be sent, as RFC 2822 email addresses separated by
|
commits should be sent, as RFC 2822 email addresses separated by
|
||||||
commas. This configuration option can be multivalued. The
|
commas. This configuration option can be multivalued. The
|
||||||
default is the value in multimailhook.mailingList. Set this value
|
default is the value in multimailhook.mailingList. Set this value
|
||||||
to the empty string to prevent notification emails about
|
to "none" (or the empty string) to prevent notification emails about
|
||||||
individual commits from being sent even if
|
individual commits from being sent even if
|
||||||
multimailhook.mailingList is set.
|
multimailhook.mailingList is set.
|
||||||
|
|
||||||
|
@ -230,6 +260,20 @@ multimailhook.announceShortlog
|
||||||
not so straightforward, then the shortlog might be confusing
|
not so straightforward, then the shortlog might be confusing
|
||||||
rather than useful. Default is false.
|
rather than useful. Default is false.
|
||||||
|
|
||||||
|
multimailhook.commitEmailFormat
|
||||||
|
|
||||||
|
The format of email messages for the individual commits, can be "text" or
|
||||||
|
"html". In the latter case, the emails will include diffs using colorized
|
||||||
|
HTML instead of plain text used by default. Note that this currently the
|
||||||
|
ref change emails are always sent in plain text.
|
||||||
|
|
||||||
|
Note that when using "html", the formatting is done by parsing the
|
||||||
|
output of ``git log`` with ``-p``. When using
|
||||||
|
``multimailhook.commitLogOpts`` to specify a ``--format`` for
|
||||||
|
``git log``, one may get false positive (e.g. lines in the body of
|
||||||
|
the message starting with ``+++`` or ``---`` colored in red or
|
||||||
|
green).
|
||||||
|
|
||||||
multimailhook.refchangeShowGraph
|
multimailhook.refchangeShowGraph
|
||||||
|
|
||||||
If this option is set to true, then summary emails about reference
|
If this option is set to true, then summary emails about reference
|
||||||
|
@ -305,7 +349,7 @@ multimailhook.mailer
|
||||||
|
|
||||||
* multimailhook.smtpEncryption
|
* multimailhook.smtpEncryption
|
||||||
|
|
||||||
Set the security type. Allowed values: none, ssl.
|
Set the security type. Allowed values: none, ssl, tls.
|
||||||
Default=none.
|
Default=none.
|
||||||
|
|
||||||
* multimailhook.smtpServerDebugLevel
|
* multimailhook.smtpServerDebugLevel
|
||||||
|
@ -313,9 +357,26 @@ multimailhook.mailer
|
||||||
Integer number. Set to greater than 0 to activate debugging.
|
Integer number. Set to greater than 0 to activate debugging.
|
||||||
|
|
||||||
multimailhook.from
|
multimailhook.from
|
||||||
|
multimailhook.fromCommit
|
||||||
|
multimailhook.fromRefchange
|
||||||
|
|
||||||
If set, use this value in the From: field of generated emails. If
|
If set, use this value in the From: field of generated emails.
|
||||||
unset, the value of the From: header is determined as follows:
|
``fromCommit`` is used for commit emails, ``fromRefchange`` is
|
||||||
|
used for refchange emails, and ``from`` is used as fall-back in
|
||||||
|
all cases.
|
||||||
|
|
||||||
|
The value for these variables can be either:
|
||||||
|
|
||||||
|
- An email address, which will be used directly.
|
||||||
|
|
||||||
|
- The value ``pusher``, in which case the pusher's address (if
|
||||||
|
available) will be used.
|
||||||
|
|
||||||
|
- The value ``author`` (meaningful only for replyToCommit), in which
|
||||||
|
case the commit author's address will be used.
|
||||||
|
|
||||||
|
If config values are unset, the value of the From: header is
|
||||||
|
determined as follows:
|
||||||
|
|
||||||
1. (gitolite environment only) Parse gitolite.conf, looking for a
|
1. (gitolite environment only) Parse gitolite.conf, looking for a
|
||||||
block of comments that looks like this::
|
block of comments that looks like this::
|
||||||
|
@ -425,6 +486,15 @@ multimailhook.commitLogOpts
|
||||||
--stat -p --cc``. Shell quoting is allowed; see
|
--stat -p --cc``. Shell quoting is allowed; see
|
||||||
multimailhook.logOpts for details.
|
multimailhook.logOpts for details.
|
||||||
|
|
||||||
|
multimailhook.dateSubstitute
|
||||||
|
|
||||||
|
String to use as a substitute for ``Date:`` in the output of ``git
|
||||||
|
log`` while formatting commit messages. This is usefull to avoid
|
||||||
|
emitting a line that can be interpreted by mailers as the start of
|
||||||
|
a cited message (Zimbra webmail in particular). Defaults to
|
||||||
|
``CommitDate: ``. Set to an empty string or ``none`` to deactivate
|
||||||
|
the behavior.
|
||||||
|
|
||||||
multimailhook.emailDomain
|
multimailhook.emailDomain
|
||||||
|
|
||||||
Domain name appended to the username of the person doing the push
|
Domain name appended to the username of the person doing the push
|
||||||
|
@ -440,21 +510,13 @@ multimailhook.replyToRefchange
|
||||||
Addresses to use in the Reply-To: field for commit emails
|
Addresses to use in the Reply-To: field for commit emails
|
||||||
(replyToCommit) and refchange emails (replyToRefchange).
|
(replyToCommit) and refchange emails (replyToRefchange).
|
||||||
multimailhook.replyTo is used as default when replyToCommit or
|
multimailhook.replyTo is used as default when replyToCommit or
|
||||||
replyToRefchange is not set. The value for these variables can be
|
replyToRefchange is not set. The shortcuts ``pusher`` and
|
||||||
either:
|
``author`` are allowed with the same semantics as for
|
||||||
|
``multimailhook.from``. In addition, the value ``none`` can be
|
||||||
|
used to omit the ``Reply-To:`` field.
|
||||||
|
|
||||||
- An email address, which will be used directly.
|
The default is ``pusher`` for refchange emails, and ``author`` for
|
||||||
|
commit emails.
|
||||||
- The value `pusher`, in which case the pusher's address (if
|
|
||||||
available) will be used. This is the default for refchange
|
|
||||||
emails.
|
|
||||||
|
|
||||||
- The value `author` (meaningful only for replyToCommit), in which
|
|
||||||
case the commit author's address will be used. This is the
|
|
||||||
default for commit emails.
|
|
||||||
|
|
||||||
- The value `none`, in which case the Reply-To: field will be
|
|
||||||
omitted.
|
|
||||||
|
|
||||||
multimailhook.quiet
|
multimailhook.quiet
|
||||||
|
|
||||||
|
@ -478,6 +540,63 @@ multimailhook.combineWhenSingleCommit
|
||||||
single email.
|
single email.
|
||||||
Default: true
|
Default: true
|
||||||
|
|
||||||
|
multimailhook.refFilterInclusionRegex
|
||||||
|
multimailhook.refFilterExclusionRegex
|
||||||
|
multimailhook.refFilterDoSendRegex
|
||||||
|
multimailhook.refFilterDontSendRegex
|
||||||
|
|
||||||
|
**Warning:** these options are experimental. They should work, but
|
||||||
|
the user-interface is not stable yet (in particular, the option
|
||||||
|
names may change). If you want to participate in stabilizing the
|
||||||
|
feature, please contact the maintainers and/or send pull-requests.
|
||||||
|
|
||||||
|
Regular expressions that can be used to limit refs for which email
|
||||||
|
updates will be sent. It is an error to specify both an inclusion
|
||||||
|
and an exclusion regex. If a ``refFilterInclusionRegex`` is
|
||||||
|
specified, emails will only be sent for refs which match this
|
||||||
|
regex. If a ``refFilterExclusionRegex`` regex is specified,
|
||||||
|
emails will be sent for all refs except those that match this
|
||||||
|
regex (or that match a predefined regex specific to the
|
||||||
|
environment, such as "^refs/notes" for most environments and
|
||||||
|
"^refs/notes|^refs/changes" for the gerrit environment).
|
||||||
|
|
||||||
|
The expressions are matched against the complete refname, and is
|
||||||
|
considered to match if any substring matches. For example, to
|
||||||
|
filter-out all tags, set ``refFilterExclusionRegex`` to
|
||||||
|
``^refs/tags/`` (note the leading ``^`` but no trailing ``$``). If
|
||||||
|
you set ``refFilterExclusionRegex`` to ``master``, then any ref
|
||||||
|
containing ``master`` will be excluded (the ``master`` branch, but
|
||||||
|
also ``refs/tags/master`` or ``refs/heads/foo-master-bar``).
|
||||||
|
|
||||||
|
``refFilterDoSendRegex`` and ``refFilterDontSendRegex`` are
|
||||||
|
analogous to ``refFilterInclusionRegex`` and
|
||||||
|
``refFilterExclusionRegex`` with one difference: with
|
||||||
|
``refFilterDoSendRegex`` and ``refFilterDontSendRegex``, commits
|
||||||
|
introduced by one excluded ref will not be considered as new when
|
||||||
|
they reach an included ref. Typically, if you add a branch ``foo``
|
||||||
|
to ``refFilterDontSendRegex``, push commits to this branch, and
|
||||||
|
later merge branch ``foo`` into ``master``, then the notification
|
||||||
|
email for ``master`` will contain a commit email only for the
|
||||||
|
merge commit. If you include ``foo`` in
|
||||||
|
``refFilterExclusionRegex``, then at the time of merge, you will
|
||||||
|
receive one commit email per commit in the branch.
|
||||||
|
|
||||||
|
These variables can be multi-valued, like::
|
||||||
|
|
||||||
|
[multimailhook]
|
||||||
|
refFilterExclusionRegex = ^refs/tags/
|
||||||
|
refFilterExclusionRegex = ^refs/heads/master$
|
||||||
|
|
||||||
|
You can also provide a whitespace-separated list like::
|
||||||
|
|
||||||
|
[multimailhook]
|
||||||
|
refFilterExclusionRegex = ^refs/tags/ ^refs/heads/master$
|
||||||
|
|
||||||
|
Both examples exclude tags and the master branch, and are
|
||||||
|
equivalent to::
|
||||||
|
|
||||||
|
[multimailhook]
|
||||||
|
refFilterExclusionRegex = ^refs/tags/|^refs/heads/master$
|
||||||
|
|
||||||
Email filtering aids
|
Email filtering aids
|
||||||
--------------------
|
--------------------
|
||||||
|
@ -547,35 +666,8 @@ consider sharing them with the community!
|
||||||
Getting involved
|
Getting involved
|
||||||
----------------
|
----------------
|
||||||
|
|
||||||
git-multimail is an open-source project, built by volunteers. We would
|
Please, read `<CONTRIBUTING.rst>`__ for instructions on how to
|
||||||
welcome your help!
|
contribute to git-multimail.
|
||||||
|
|
||||||
The current maintainers are Michael Haggerty <mhagger@alum.mit.edu>
|
|
||||||
and Matthieu Moy <matthieu.moy@grenoble-inp.fr>.
|
|
||||||
|
|
||||||
Please note that although a copy of git-multimail is distributed in
|
|
||||||
the "contrib" section of the main Git project, development takes place
|
|
||||||
in a separate git-multimail repository on GitHub:
|
|
||||||
|
|
||||||
https://github.com/git-multimail/git-multimail
|
|
||||||
|
|
||||||
Whenever enough changes to git-multimail have accumulated, a new
|
|
||||||
code-drop of git-multimail will be submitted for inclusion in the Git
|
|
||||||
project.
|
|
||||||
|
|
||||||
We use the GitHub issue tracker to keep track of bugs and feature
|
|
||||||
requests, and we use GitHub pull requests to exchange patches (though,
|
|
||||||
if you prefer, you can send patches via the Git mailing list with CC
|
|
||||||
to the maintainers). Please sign off your patches as per the Git
|
|
||||||
project practice.
|
|
||||||
|
|
||||||
General discussion of git-multimail can take place on the main Git
|
|
||||||
mailing list,
|
|
||||||
|
|
||||||
git@vger.kernel.org
|
|
||||||
|
|
||||||
Please CC emails regarding git-multimail to the maintainers so that we
|
|
||||||
don't overlook them.
|
|
||||||
|
|
||||||
|
|
||||||
Footnotes
|
Footnotes
|
||||||
|
|
|
@ -6,10 +6,10 @@ website:
|
||||||
https://github.com/git-multimail/git-multimail
|
https://github.com/git-multimail/git-multimail
|
||||||
|
|
||||||
The version in this directory was obtained from the upstream project
|
The version in this directory was obtained from the upstream project
|
||||||
on July 03 2015 and consists of the "git-multimail" subdirectory from
|
on October 11 2015 and consists of the "git-multimail" subdirectory from
|
||||||
revision
|
revision
|
||||||
|
|
||||||
6d6c9eb62a054143322cfaecde3949189c065b46 refs/tags/1.1.1
|
c0791b9ef5821a746fc3475c25765e640452eaae refs/tags/1.2.0
|
||||||
|
|
||||||
Please see the README file in this directory for information about how
|
Please see the README file in this directory for information about how
|
||||||
to report bugs or contribute to git-multimail.
|
to report bugs or contribute to git-multimail.
|
||||||
|
|
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``.
|
109
contrib/hooks/multimail/doc/gitolite.rst
Normal file
109
contrib/hooks/multimail/doc/gitolite.rst
Normal file
|
@ -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/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
|
||||||
|
|
||||||
|
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``.
|
File diff suppressed because it is too large
Load diff
|
@ -1,4 +1,4 @@
|
||||||
#! /usr/bin/env python2
|
#! /usr/bin/env python
|
||||||
|
|
||||||
"""Migrate a post-receive-email configuration to be usable with git_multimail.py.
|
"""Migrate a post-receive-email configuration to be usable with git_multimail.py.
|
||||||
|
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
#! /usr/bin/env python2
|
#! /usr/bin/env python
|
||||||
|
|
||||||
"""Example post-receive hook based on git-multimail.
|
"""Example post-receive hook based on git-multimail.
|
||||||
|
|
||||||
|
@ -42,7 +42,6 @@ import os
|
||||||
|
|
||||||
import git_multimail
|
import git_multimail
|
||||||
|
|
||||||
|
|
||||||
# It is possible to modify the output templates here; e.g.:
|
# It is possible to modify the output templates here; e.g.:
|
||||||
|
|
||||||
#git_multimail.FOOTER_TEMPLATE = """\
|
#git_multimail.FOOTER_TEMPLATE = """\
|
||||||
|
@ -61,8 +60,9 @@ config = git_multimail.Config('multimailhook')
|
||||||
try:
|
try:
|
||||||
environment = git_multimail.GenericEnvironment(config=config)
|
environment = git_multimail.GenericEnvironment(config=config)
|
||||||
#environment = git_multimail.GitoliteEnvironment(config=config)
|
#environment = git_multimail.GitoliteEnvironment(config=config)
|
||||||
except git_multimail.ConfigurationException, e:
|
except git_multimail.ConfigurationException:
|
||||||
sys.exit(str(e))
|
sys.stderr.write('*** %s\n' % sys.exc_info()[1])
|
||||||
|
sys.exit(1)
|
||||||
|
|
||||||
|
|
||||||
# Choose the method of sending emails based on the git config:
|
# Choose the method of sending emails based on the git config:
|
||||||
|
|
Loading…
Reference in a new issue