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

Browse source 
The changes are described in CHANGES.

Contributions-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Contributions-by: Richard Hansen <rhansen@rhansen.org>
Contributions-by: Michael Haggerty <mhagger@alum.mit.edu>
Contributions-by: Elijah Newren <newren@gmail.com>
Contributions-by: Luke Mewburn <luke@mewburn.net>
Contributions-by: Dave Boutcher <daveboutcher@gmail.com>
Contributions-by: Azat Khuzhin <a3at.mail@gmail.com>
Contributions-by: Sebastian Schuberth <sschuberth@gmail.com>
Contributions-by: Mikko Johannes Koivunalho <mikko.koivunalho@iki.fi>
Contributions-by: Elijah Newren <newren@palantir.com>
Contributions-by: Benoît Ryder <benoit@ryder.fr>
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-06-18 10:46:04 +02:00 committed by Junio C Hamano
parent 16da57c7c6
commit 5b1d901c01
6 changed files with 1020 additions and 329 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

48
contrib/hooks/multimail/CHANGES
View file

@ -1,3 +1,51 @@
Release 1.1.0
=============
* When a single commit is pushed, omit the reference changed email.
Set multimailhook.combineWhenSingleCommit to false to disable this
new feature.
* In gitolite environments, the pusher's email address can be used as
the From address by creating a specially formatted comment block in
gitolite.conf (see multimailhook.from in README).
* Support for SMTP authentication and SSL/TLS encryption was added,
see smtpUser, smtpPass, smtpEncryption in README.
* A new option scanCommitForCc was added to allow git-multimail to
search the commit message for 'Cc: ...' lines, and add the
corresponding emails in Cc.
* If $USER is not set, use the variable $USERNAME. This is needed on
Windows platform to recognize the pusher.
* The emailPrefix variable can now be set to an empty string to remove
the prefix.
* A short tutorial was added in doc/gitolite.rst to set up
git-multimail with gitolite.
* The post-receive file was renamed to post-receive.example. It has
always been an example (the standard way to call git-multimail is to
call git_multimail.py), but it was unclear to many users.
* A new refchangeShowGraph option was added to make it possible to
include both a graph and a log in the summary emails. The options
to control the graph formatting can be set via the new graphOpts
option.
* New option --force-send was added to disable new commit detection
for update hook. One use-case is to run git_multimail.py after
running "git fetch" to send emails about commits that have just been
fetched (the detection of new commits was unreliable in this mode).
* The testing infrastructure was considerably improved (continuous
integration with travis-ci, automatic check of PEP8 and RST syntax,
many improvements to the test scripts).
This version has been tested with Python 2.4 to 2.7, and Git 1.7.1 to
2.4.
Release 1.0.0
=============

277
contrib/hooks/multimail/README
View file

@ -1,5 +1,8 @@
git-multimail
=============
git-multimail Version 1.1.0
===========================
.. image:: https://travis-ci.org/git-multimail/git-multimail.svg?branch=master
:target: https://travis-ci.org/git-multimail/git-multimail
git-multimail is a tool for sending notification emails on pushes to a
Git repository. It includes a Python module called git_multimail.py,
@ -38,17 +41,17 @@ By default, for each push received by the repository, git-multimail:
list) makes it easy to scan through the emails, jump to patches
that need further attention, and write comments about specific
commits. Commits are handled in reverse topological order (i.e.,
parents shown before children). For example,
parents shown before children). For example::
[git] branch master updated
+ [git] 01/08: doc: fix xref link from api docs to manual pages
+ [git] 02/08: api-credentials.txt: show the big picture first
+ [git] 03/08: api-credentials.txt: mention credential.helper explicitly
+ [git] 04/08: api-credentials.txt: add "see also" section
+ [git] 05/08: t3510 (cherry-pick-sequence): add missing '&&'
+ [git] 06/08: Merge branch 'rr/maint-t3510-cascade-fix'
+ [git] 07/08: Merge branch 'mm/api-credentials-doc'
+ [git] 08/08: Git 1.7.11-rc2
[git] branch master updated
+ [git] 01/08: doc: fix xref link from api docs to manual pages
+ [git] 02/08: api-credentials.txt: show the big picture first
+ [git] 03/08: api-credentials.txt: mention credential.helper explicitly
+ [git] 04/08: api-credentials.txt: add "see also" section
+ [git] 05/08: t3510 (cherry-pick-sequence): add missing '&&'
+ [git] 06/08: Merge branch 'rr/maint-t3510-cascade-fix'
+ [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
@ -74,19 +77,19 @@ Requirements
3.x.
The example scripts invoke Python using the following shebang line
(following PEP 394 [1]):
(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
called ``python2``, you can change the lines accordingly. Or you can
invoke the Python interpreter explicitly, for example via a tiny
shell script like
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
been tested; if you do so, please report your results.)
@ -101,7 +104,7 @@ Requirements
Invocation
----------
git_multimail.py is designed to be used as a "post-receive" hook in a
git_multimail.py is designed to be used as a ``post-receive`` hook in a
Git repository (see githooks(5)). Link or copy it to
$GIT_DIR/hooks/post-receive within the repository for which email
notifications are desired. Usually it should be installed on the
@ -109,10 +112,10 @@ central repository for a project, to which all commits are eventually
pushed.
For use on pre-v1.5.1 Git servers, git_multimail.py can also work as
an "update" hook, taking its arguments on the command line. To use
an ``update`` hook, taking its arguments on the command line. To use
this script in this manner, link or copy it to $GIT_DIR/hooks/update.
Please note that the script is not completely reliable in this mode
[2].
[2]_.
Alternatively, git_multimail.py can be imported as a Python module
into your own Python post-receive script. This method is a bit more
@ -129,7 +132,7 @@ arbitrary Python code. For example, you can use a custom environment
only about changes affecting particular files or subdirectories)
Or you can change how emails are sent by writing your own Mailer
class. The "post-receive" script in this directory demonstrates how
class. The ``post-receive`` script in this directory demonstrates how
to use git_multimail.py as a Python module. (If you make interesting
changes of this type, please consider sharing them with the
community.)
@ -139,18 +142,26 @@ Configuration
-------------
By default, git-multimail mostly takes its configuration from the
following "git config" settings:
following ``git config`` settings:
multimailhook.environment
This describes the general environment of the repository.
Currently supported values:
"generic" -- the username of the pusher is read from $USER and the
repository name is derived from the repository's path.
* generic
"gitolite" -- the username of the pusher is read from $GL_USER and
the repository name from $GL_REPO.
the username of the pusher is read from $USER or $USERNAME and
the repository name is derived from the repository's path.
* gitolite
the username of the pusher is read from $GL_USER, the repository
name is read from $GL_REPO, and the From: header value is
optionally read from gitolite.conf (see multimailhook.from).
For more information about gitolite and git-multimail, read
doc/gitolite.rst
If neither of these environments is suitable for your setup, then
you can implement a Python class that inherits from Environment
@ -160,8 +171,8 @@ multimailhook.environment
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".
``gitolite`` if the environment contains variables $GL_USER and
$GL_REPO; otherwise ``generic``.
multimailhook.repoName
@ -219,61 +230,109 @@ multimailhook.announceShortlog
not so straightforward, then the shortlog might be confusing
rather than useful. Default is false.
multimailhook.refchangeShowGraph
If this option is set to true, then summary emails about reference
changes will additionally include:
* a graph of the added commits (if any)
* a graph of the discarded commits (if any)
The log is generated by running ``git log --graph`` with the options
specified in graphOpts. The default is false.
multimailhook.refchangeShowLog
If this option is set to true, then summary emails about reference
changes will include a detailed log of the added commits in
addition to the one line summary. The log is generated by running
"git log" with the options specified in multimailhook.logOpts.
``git log`` with the options specified in multimailhook.logOpts.
Default is false.
multimailhook.mailer
This option changes the way emails are sent. Accepted values are:
- sendmail (the default): use the command /usr/sbin/sendmail or
/usr/lib/sendmail (or sendmailCommand, if configured). This
- sendmail (the default): use the command ``/usr/sbin/sendmail`` or
``/usr/lib/sendmail`` (or sendmailCommand, if configured). This
mode can be further customized via the following options:
multimailhook.sendmailCommand
* multimailhook.sendmailCommand
The command used by mailer "sendmail" to send emails. Shell
quoting is allowed in the value of this setting, but remember that
Git requires double-quotes to be escaped; e.g.,
The command used by mailer ``sendmail`` to send emails. Shell
quoting is allowed in the value of this setting, but remember that
Git requires double-quotes to be escaped; e.g.::
git config multimailhook.sendmailcommand '/usr/sbin/sendmail -oi -t -F \"Git Repo\"'
Default is '/usr/sbin/sendmail -oi -t' or
'/usr/lib/sendmail -oi -t' (depending on which file is
present and executable).
Default is '/usr/sbin/sendmail -oi -t' or
'/usr/lib/sendmail -oi -t' (depending on which file is
present and executable).
multimailhook.envelopeSender
* multimailhook.envelopeSender
If set then pass this value to sendmail via the -f option to set
the envelope sender address.
If set then pass this value to sendmail via the -f option to set
the envelope sender address.
- smtp: use Python's smtplib. This is useful when the sendmail
command is not available on the system. This mode can be
further customized via the following options:
multimailhook.smtpServer
* multimailhook.smtpServer
The name of the SMTP server to connect to. The value can
also include a colon and a port number; e.g.,
"mail.example.com:25". Default is 'localhost' using port
25.
The name of the SMTP server to connect to. The value can
also include a colon and a port number; e.g.,
``mail.example.com:25``. Default is 'localhost' using port 25.
multimailhook.envelopeSender
* multimailhook.smtpUser
* multimailhook.smtpPass
The sender address to be passed to the SMTP server. If
unset, then the value of multimailhook.from is used.
Server username and password. Required if smtpEncryption is 'ssl'.
Note that the username and password currently need to be
set cleartext in the configuration file, which is not
recommended. If you need to use this option, be sure your
configuration file is read-only.
* multimailhook.envelopeSender
The sender address to be passed to the SMTP server. If
unset, then the value of multimailhook.from is used.
* multimailhook.smtpServerTimeout
Timeout in seconds.
* multimailhook.smtpEncryption
Set the security type. Allowed values: none, ssl.
Default=none.
* multimailhook.smtpServerDebugLevel
Integer number. Set to greater than 0 to activate debugging.
multimailhook.from
If set then use this value in the From: field of generated emails.
If unset, then use the repository's user configuration (user.name
and user.email). If user.email is also unset, then use
multimailhook.envelopeSender.
If set, use this value in the From: field of generated emails. If
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::
# BEGIN USER EMAILS
# username Firstname Lastname <email@example.com>
# END USER EMAILS
If that block exists, and there is a line between the BEGIN
USER EMAILS and END USER EMAILS lines where the first field
matches the gitolite username ($GL_USER), use the rest of the
line for the From: header.
2. If the user.email configuration setting is set, use its value
(and the value of user.name, if set).
3. Use the value of multimailhook.envelopeSender.
multimailhook.administrator
@ -287,7 +346,8 @@ multimailhook.emailPrefix
All emails have this string prepended to their subjects, to aid
email filtering (though filtering based on the X-Git-* email
headers is probably more robust). Default is the short name of
the repository in square brackets; e.g., "[myrepo]".
the repository in square brackets; e.g., ``[myrepo]``. Set this
value to the empty string to suppress the email prefix.
multimailhook.emailMaxLines
@ -299,7 +359,7 @@ multimailhook.emailMaxLines
multimailhook.emailMaxLineLength
The maximum length of a line in the email body. Lines longer than
this limit are truncated to this length with a trailing " [...]"
this limit are truncated to this length with a trailing `` [...]``
added to indicate the missing text. The default is 500, because
(a) diffs with longer lines are probably from binary files, for
which a diff is useless, and (b) even if a text file has such long
@ -316,54 +376,62 @@ multimailhook.maxCommitEmails
multimailhook.emailStrictUTF8
If this boolean option is set to "true", then the main part of the
If this boolean option is set to `true`, then the main part of the
email body is forced to be valid UTF-8. Any characters that are
not valid UTF-8 are converted to the Unicode replacement
character, U+FFFD. The default is "true".
character, U+FFFD. The default is `true`.
multimailhook.diffOpts
Options passed to "git diff-tree" when generating the summary
information for ReferenceChange emails. Default is "--stat
--summary --find-copies-harder". Add -p to those options to
Options passed to ``git diff-tree`` when generating the summary
information for ReferenceChange emails. Default is ``--stat
--summary --find-copies-harder``. Add -p to those options to
include a unified diff of changes in addition to the usual summary
output. Shell quoting is allowed; see multimailhook.logOpts for
details.
multimailhook.graphOpts
Options passed to ``git log --graph`` when generating graphs for the
reference change summary emails (used only if refchangeShowGraph
is true). The default is '--oneline --decorate'.
Shell quoting is allowed; see logOpts for details.
multimailhook.logOpts
Options passed to "git log" to generate additional info for
Options passed to ``git log`` to generate additional info for
reference change emails (used only if refchangeShowLog is set).
For example, adding --graph will show the graph of revisions, -p
will show the complete diff, etc. The default is empty.
For example, adding -p will show each commit's complete diff. The
default is empty.
Shell quoting is allowed; for example, a log format that contains
spaces can be specified using something like:
spaces can be specified using something like::
git config multimailhook.logopts '--pretty=format:"%h %aN <%aE>%n%s%n%n%b%n"'
If you want to set this by editing your configuration file
directly, remember that Git requires double-quotes to be escaped
(see git-config(1) for more information):
(see git-config(1) for more information)::
[multimailhook]
logopts = --pretty=format:\"%h %aN <%aE>%n%s%n%n%b%n\"
multimailhook.commitLogOpts
Options passed to "git log" to generate additional info for
Options passed to ``git log`` to generate additional info for
revision change emails. For example, adding --ignore-all-spaces
will suppress whitespace changes. The default options are "-C
--stat -p --cc". Shell quoting is allowed; see
will suppress whitespace changes. The default options are ``-C
--stat -p --cc``. Shell quoting is allowed; see
multimailhook.logOpts for details.
multimailhook.emailDomain
Domain name appended to the username of the person doing the push
to convert it into an email address (via "%s@%s" % (username,
emaildomain)). More complicated schemes can be implemented by
overriding Environment and overriding its get_pusher_email()
method.
to convert it into an email address
(via ``"%s@%s" % (username, emaildomain)``). More complicated
schemes can be implemented by overriding Environment and
overriding its get_pusher_email() method.
multimailhook.replyTo
multimailhook.replyToCommit
@ -377,26 +445,48 @@ multimailhook.replyToRefchange
- An email address, which will be used directly.
- The value "pusher", in which case the pusher's address (if
- 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
- 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
- The value `none`, in which case the Reply-To: field will be
omitted.
multimailhook.quiet
Do not output the list of email recipients from the hook
multimailhook.stdout
For debugging, send emails to stdout rather than to the
mailer. Equivalent to the --stdout command line option
multimailhook.scanCommitForCc
If this option is set to true, than recipients from lines in commit body
that starts with ``CC:`` will be added to CC list.
Default: false
multimailhook.combineWhenSingleCommit
If this option is set to true and a single new commit is pushed to
a branch, combine the summary and commit email messages into a
single email.
Default: true
Email filtering aids
--------------------
All emails include extra headers to enable fine tuned filtering and
give information for debugging. All emails include the headers
"X-Git-Host", "X-Git-Repo", "X-Git-Refname", and "X-Git-Reftype".
ReferenceChange emails also include headers "X-Git-Oldrev" and "X-Git-Newrev";
Revision emails also include header "X-Git-Rev".
``X-Git-Host``, ``X-Git-Repo``, ``X-Git-Refname``, and ``X-Git-Reftype``.
ReferenceChange emails also include headers ``X-Git-Oldrev`` and ``X-Git-Newrev``;
Revision emails also include header ``X-Git-Rev``.
Customizing email contents
@ -420,16 +510,17 @@ environment are built in:
* GenericEnvironment: a stand-alone Git repository.
* GitoliteEnvironment: a Git repository that is managed by gitolite
[3]. For such repositories, the identity of the pusher is read from
environment variable $GL_USER, and the name of the repository is
read from $GL_REPO (if it is not overridden by
multimailhook.reponame).
[3]_. For such repositories, the identity of the pusher is read from
environment variable $GL_USER, the name of the repository is read
from $GL_REPO (if it is not overridden by multimailhook.reponame),
and the From: header value is optionally read from gitolite.conf
(see multimailhook.from).
By default, git-multimail assumes GitoliteEnvironment if $GL_USER and
$GL_REPO are set, and otherwise assumes GenericEnvironment.
Alternatively, you can choose one of these two environments explicitly
by setting a "multimailhook.environment" config setting (which can
have the value "generic" or "gitolite") or by passing an --environment
by setting a ``multimailhook.environment`` config setting (which can
have the value `generic` or `gitolite`) or by passing an --environment
option to the script.
If you need to customize the script in ways that are not supported by
@ -439,8 +530,8 @@ git_multimail.py as a Python module, as demonstrated by the example
post-receive script. Then implement your environment class; it should
usually inherit from one of the existing Environment classes and
possibly one or more of the EnvironmentMixin classes. Then set the
"environment" variable to an instance of your own environment class
and pass it to run_as_post_receive_hook().
``environment`` variable to an instance of your own environment class
and pass it to ``run_as_post_receive_hook()``.
The standard environment classes, GenericEnvironment and
GitoliteEnvironment, are in fact themselves put together out of a
@ -490,12 +581,14 @@ don't overlook them.
Footnotes
---------
[1] http://www.python.org/dev/peps/pep-0394/
.. [1] http://www.python.org/dev/peps/pep-0394/
[2] Because of the way information is passed to update hooks, the
script's method of determining whether a commit has already been
seen does not work when it is used as an "update" script. In
particular, no notification email will be generated for a new
commit that is added to multiple references in the same push.
.. [2] Because of the way information is passed to update hooks, the
script's method of determining whether a commit has already
been seen does not work when it is used as an ``update`` script.
In particular, no notification email will be generated for a
new commit that is added to multiple references in the same
push. A workaround is to use --force-send to force sending the
emails.
[3] https://github.com/sitaramc/gitolite
.. [3] https://github.com/sitaramc/gitolite

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 2015-04-27 and consists of the "git-multimail" subdirectory from
on Jun 18 2015 and consists of the "git-multimail" subdirectory from
revision
8c3aaafa873bf10de8dddf1d202c449b3eff3b42 refs/tags/1.0.2
1f0dbb3b60035767889b913df16d9231ecdb8709 refs/tags/1.1.0
Please see the README file in this directory for information about how
to report bugs or contribute to git-multimail.

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

File diff suppressed because it is too large Load diff

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

@ -22,6 +22,7 @@ OLD_NAMES = [
'showrev',
'emailmaxlines',
'diffopts',
'scancommitforcc',
]
NEW_NAMES = [
@ -38,6 +39,7 @@ NEW_NAMES = [
'emailmaxlines',
'diffopts',
'emaildomain',
'scancommitforcc',
]
@ -61,7 +63,7 @@ def _check_old_config_exists(old):
"""Check that at least one old configuration value is set."""
for name in OLD_NAMES:
if old.has_key(name):
if name in old:
return True
return False
@ -72,7 +74,7 @@ def _check_new_config_clear(new):
retval = True
for name in NEW_NAMES:
if new.has_key(name):
if name in new:
if retval:
sys.stderr.write('INFO: The following configuration values already exist:\n\n')
sys.stderr.write(' "%s.%s"\n' % (new.section, name))
@ -83,7 +85,7 @@ def _check_new_config_clear(new):
def erase_values(config, names):
for name in names:
if config.has_key(name):
if name in config:
try:
sys.stderr.write('...unsetting "%s.%s"\n' % (config.section, name))
config.unset_all(name)
@ -170,7 +172,7 @@ def migrate_config(strict=False, retain=False, overwrite=False):
)
name = 'showrev'
if old.has_key(name):
if name in old:
msg = 'git-multimail does not support "%s.%s"' % (old.section, name,)
if strict:
sys.exit(
@ -182,7 +184,7 @@ def migrate_config(strict=False, retain=False, overwrite=False):
sys.stderr.write('\nWARNING: %s (ignoring).\n\n' % (msg,))
for name in ['mailinglist', 'announcelist']:
if old.has_key(name):
if name in old:
sys.stderr.write(
'...copying "%s.%s" to "%s.%s"\n' % (old.section, name, new.section, name)
)
@ -198,15 +200,15 @@ def migrate_config(strict=False, retain=False, overwrite=False):
)
new.set('announceshortlog', 'true')
for name in ['envelopesender', 'emailmaxlines', 'diffopts']:
if old.has_key(name):
for name in ['envelopesender', 'emailmaxlines', 'diffopts', 'scancommitforcc']:
if name in old:
sys.stderr.write(
'...copying "%s.%s" to "%s.%s"\n' % (old.section, name, new.section, name)
)
new.set(name, old.get(name))
name = 'emailprefix'
if old.has_key(name):
if name in old:
sys.stderr.write(
'...copying "%s.%s" to "%s.%s"\n' % (old.section, name, new.section, name)
)

27
contrib/hooks/multimail/post-receive → contrib/hooks/multimail/post-receive.example
View file

@ -2,16 +2,18 @@
"""Example post-receive hook based on git-multimail.
This script is a simple example of a post-receive hook implemented
using git_multimail.py as a Python module. It is intended to be
customized before use; see the comments in the script to help you get
started.
The simplest way to use git-multimail is to use the script
git_multimail.py directly as a post-receive hook, and to configure it
using Git's configuration files and command-line parameters. You can
also write your own Python wrapper for more advanced configurability,
using git_multimail.py as a Python module.
It is possible to use git_multimail.py itself as a post-receive or
update hook, configured via git config settings and/or command-line
parameters. But for more flexibility, it can also be imported as a
Python module by a custom post-receive script as done here. The
latter has the following advantages:
This script is a simple example of such a post-receive hook. It is
intended to be customized before use; see the comments in the script
to help you get started.
Using git-multimail as a Python module as done here provides more
flexibility. It has the following advantages:
* The tool's behavior can be customized using arbitrary Python code,
without having to edit git_multimail.py.
@ -56,8 +58,11 @@ config = git_multimail.Config('multimailhook')
# Select the type of environment:
environment = git_multimail.GenericEnvironment(config=config)
#environment = git_multimail.GitoliteEnvironment(config=config)
try:
environment = git_multimail.GenericEnvironment(config=config)
#environment = git_multimail.GitoliteEnvironment(config=config)
except git_multimail.ConfigurationException, e:
sys.exit(str(e))
# Choose the method of sending emails based on the git config: