development/git
development/git
1
0
Fork 0
mirror of https://github.com/git/git synced 2024-07-17 11:07:55 +00:00
Code Issues Actions 9 Packages Projects Releases Wiki Activity

git-multimail: update to release 1.2.0

Browse source 
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:
Matthieu Moy 2015-10-11 20:43:20 +02:00 committed by Junio C Hamano
parent f5b6079871
commit 4b1fd356b8
9 changed files with 1219 additions and 227 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

41
contrib/hooks/multimail/CHANGES
View file

@ -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)
===================================

30
contrib/hooks/multimail/CONTRIBUTING.rst Normal file
View 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.

258
contrib/hooks/multimail/README
View file

@ -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
: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] 08/08: Git 1.7.11-rc2
Each commit appears in exactly one commit email, the first time
that it is pushed to the repository. If a commit is later merged
into another branch, then a one-line summary of the commit is
included in the reference change email (as usual), but no
additional commit email is generated.
By default, each commit appears in exactly one commit email, the
first time that it is pushed to the repository. If a commit is later
merged into another branch, then a one-line summary of the commit
is included in the reference change email (as usual), but no
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
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
are required. git-multimail does *not* currently work with Python
3.x.
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 "$@"
are required. git-multimail has preliminary support for Python 3
(but it has been better tested with Python 2).
* 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
@ -146,7 +135,9 @@ following ``git config`` settings:
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:
* generic
@ -161,18 +152,57 @@ multimailhook.environment
optionally read from gitolite.conf (see multimailhook.from).
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
you can implement a Python class that inherits from Environment
and instantiate it via a script that looks like the example
* stash
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.
The environment value can be specified on the command line using
the --environment option. If it is not specified on the command
line or by multimailhook.environment, then it defaults to
``gitolite`` if the environment contains variables $GL_USER and
$GL_REPO; otherwise ``generic``.
the ``--environment`` option. If it is not specified on the
command line or by ``multimailhook.environment``, the value is
guessed as follows:
* 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
@ -196,8 +226,8 @@ multimailhook.refchangeList
reference changes should be sent, as RFC 2822 email addresses
separated by commas. This configuration option can be
multivalued. The default is the value in
multimailhook.mailingList. Set this value to the empty string to
prevent reference change emails from being sent even if
multimailhook.mailingList. Set this value to "none" (or the empty
string) to prevent reference change emails from being sent even if
multimailhook.mailingList is set.
multimailhook.announceList
@ -206,9 +236,9 @@ multimailhook.announceList
tags should be sent, as RFC 2822 email addresses separated by
commas. This configuration option can be multivalued. The
default is the value in multimailhook.refchangeList or
multimailhook.mailingList. Set this value to the empty string to
prevent annotated tag announcement emails from being sent even if
one of the other values is set.
multimailhook.mailingList. Set this value to "none" (or the empty
string) to prevent annotated tag announcement emails from being sent
even if one of the other values is set.
multimailhook.commitList
@ -216,7 +246,7 @@ multimailhook.commitList
commits should be sent, as RFC 2822 email addresses separated by
commas. This configuration option can be multivalued. The
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
multimailhook.mailingList is set.
@ -230,6 +260,20 @@ multimailhook.announceShortlog
not so straightforward, then the shortlog might be confusing
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
If this option is set to true, then summary emails about reference
@ -305,7 +349,7 @@ multimailhook.mailer
* multimailhook.smtpEncryption
Set the security type. Allowed values: none, ssl.
Set the security type. Allowed values: none, ssl, tls.
Default=none.
* multimailhook.smtpServerDebugLevel
@ -313,9 +357,26 @@ multimailhook.mailer
Integer number. Set to greater than 0 to activate debugging.
multimailhook.from
multimailhook.fromCommit
multimailhook.fromRefchange
If set, use this value in the From: field of generated emails. If
unset, the value of the From: header is determined as follows:
If set, use this value in the From: field of generated emails.
``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
block of comments that looks like this::
@ -425,6 +486,15 @@ multimailhook.commitLogOpts
--stat -p --cc``. Shell quoting is allowed; see
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
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
(replyToCommit) and refchange emails (replyToRefchange).
multimailhook.replyTo is used as default when replyToCommit or
replyToRefchange is not set. The value for these variables can be
either:
replyToRefchange is not set. The shortcuts ``pusher`` and
``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 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.
The default is ``pusher`` for refchange emails, and ``author`` for
commit emails.
multimailhook.quiet
@ -478,6 +540,63 @@ multimailhook.combineWhenSingleCommit
single email.
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
--------------------
@ -547,35 +666,8 @@ consider sharing them with the community!
Getting involved
----------------
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.
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.
Please, read `<CONTRIBUTING.rst>`__ for instructions on how to
contribute to git-multimail.
Footnotes

4
contrib/hooks/multimail/README.Git
View file

@ -6,10 +6,10 @@ website:
https://github.com/git-multimail/git-multimail
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
6d6c9eb62a054143322cfaecde3949189c065b46 refs/tags/1.1.1
c0791b9ef5821a746fc3475c25765e640452eaae refs/tags/1.2.0
Please see the README file in this directory for information about how
to report bugs or contribute to git-multimail.

56
contrib/hooks/multimail/doc/gerrit.rst Normal file
View 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
View 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``.

938
contrib/hooks/multimail/git_multimail.py
View file

File diff suppressed because it is too large Load diff

2
contrib/hooks/multimail/migrate-mailhook-config
View file

@ -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.

8
contrib/hooks/multimail/post-receive.example
View file

@ -1,4 +1,4 @@
#! /usr/bin/env python2
#! /usr/bin/env python
"""Example post-receive hook based on git-multimail.
@ -42,7 +42,6 @@ import os
import git_multimail
# It is possible to modify the output templates here; e.g.:
#git_multimail.FOOTER_TEMPLATE = """\
@ -61,8 +60,9 @@ config = git_multimail.Config('multimailhook')
try:
environment = git_multimail.GenericEnvironment(config=config)
#environment = git_multimail.GitoliteEnvironment(config=config)
except git_multimail.ConfigurationException, e:
sys.exit(str(e))
except git_multimail.ConfigurationException:
sys.stderr.write('*** %s\n' % sys.exc_info()[1])
sys.exit(1)
# Choose the method of sending emails based on the git config: