mirrors/git
0
0
Fork 0
mirror of https://github.com/git/git.git synced 2024-11-27 03:53:55 +08:00
Code Issues Packages Projects Releases Wiki Activity

multimail: stop shipping a copy

Browse Source 
The multimail project is developed independently and has its own project
page. Traditionally, we shipped a copy in contrib/.

However, such a copy is prone to become stale, and users are much better
served to be directed to the actual project instead.

Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Johannes Schindelin 2021-06-10 08:29:24 +00:00 committed by Junio C Hamano
parent ebf3c04b26
commit f74d11471f
12 changed files with 2 additions and 6303 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

285
contrib/hooks/multimail/CHANGES
View File

@ -1,285 +0,0 @@
Release 1.5.0
=============
Backward-incompatible change
----------------------------
The name of classes for environment was misnamed as `*Environement`.
It is now `*Environment`.
New features
------------
* A Thread-Index header is now added to each email sent (except for
combined emails where it would not make sense), so that MS Outlook
properly groups messages by threads even though they have a
different subject line. Unfortunately, even adding this header the
threading still seems to be unreliable, but it is unclear whether
this is an issue on our side or on MS Outlook's side (see discussion
here: https://github.com/git-multimail/git-multimail/pull/194).
* A new variable multimailhook.ExcludeMergeRevisions was added to send
notification emails only for non-merge commits.
* For gitolite environment, it is now possible to specify the mail map
in a separate file in addition to gitolite.conf, using the variable
multimailhook.MailaddressMap.
Internal changes
----------------
* The testsuite now uses GIT_PRINT_SHA1_ELLIPSIS where needed for
compatibility with recent Git versions. Only tests are affected.
* We don't try to install pyflakes in the continuous integration job
for old Python versions where it's no longer available.
* Stop using the deprecated cgi.escape in Python 3.
* New flake8 warnings have been fixed.
* Python 3.6 is now tested against on Travis-CI.
* A bunch of lgtm.com warnings have been fixed.
Bug fixes
---------
* SMTPMailer logs in only once now. It used to re-login for each email
sent which triggered errors for some SMTP servers.
* migrate-mailhook-config was broken by internal refactoring, it
should now work again.
This version was tested with Python 2.6 to 3.7. It was tested with Git
1.7.10.406.gdc801, 2.15.1 and 2.20.1.98.gecbdaf0.
Release 1.4.0
=============
New features to troubleshoot a git-multimail installation
---------------------------------------------------------
* One can now perform a basic check of git-multimail's setup by
running the hook with the environment variable
GIT_MULTIMAIL_CHECK_SETUP set to a non-empty string. See
doc/troubleshooting.rst for details.
* A new log files system was added. See the multimailhook.logFile,
multimailhook.errorLogFile and multimailhook.debugLogFile variables.
* git_multimail.py can now be made more verbose using
multimailhook.verbose.
* A new option --check-ref-filter is now available to help debugging
the refFilter* options.
Formatting emails
-----------------
* Formatting of emails was made slightly more compact, to reduce the
odds of having long subject lines truncated or wrapped in short list
of commits.
* multimailhook.emailPrefix may now use the '%(repo_shortname)s'
placeholder for the repository's short name.
* A new option multimailhook.subjectMaxLength is available to truncate
overly long subject lines.
Bug fixes and minor changes
---------------------------
* Options refFilterDoSendRegex and refFilterDontSendRegex were
essentially broken. They should work now.
* The behavior when both refFilter{Do,Dont}SendRegex and
refFilter{Exclusion,Inclusion}Regex are set have been slightly
changed. Exclusion/Inclusion is now strictly stronger than
DoSend/DontSend.
* The management of precedence when a setting can be computed in
multiple ways has been considerably refactored and modified.
multimailhook.from and multimailhook.reponame now have precedence
over the environment-specific settings ($GL_REPO/$GL_USER for
gitolite, --stash-user/repo for Stash, --submitter/--project for
Gerrit).
* The coverage of the testsuite has been considerably improved. All
configuration variables now appear at least once in the testsuite.
This version was tested with Python 2.6 to 3.5. It also mostly works
with Python 2.4, but there is one known breakage in the testsuite
related to non-ascii characters. It was tested with Git
1.7.10.406.gdc801, 1.8.5.6, 2.1.4, and 2.10.0.rc0.1.g07c9292.
Release 1.3.1 (bugfix-only release)
===================================
* Generate links to commits in combined emails (it was done only for
commit emails in 1.3.0).
* Fix broken links on PyPi.
Release 1.3.0
=============
* New options multimailhook.htmlInIntro and multimailhook.htmlInFooter
now allow using HTML in the introduction and footer of emails (e.g.
for a more pleasant formatting or to insert a link to the commit on
a web interface).
* A new option multimailhook.commitBrowseURL gives a simpler (and less
flexible) way to add a link to a web interface for commit emails
than multimailhook.htmlInIntro and multimailhook.htmlInFooter.
* A new public function config.add_config_parameters was added to
allow custom hooks to set specific Git configuration variables
without modifying the configuration files. See an example in
post-receive.example.
* Error handling for SMTP has been improved (we used to print Python
backtraces for legitimate errors).
* The SMTP mailer can now check TLS certificates when the newly added
configuration variable multimailhook.smtpCACerts.
* Python 3 portability has been improved.
* The documentation's formatting has been improved.
* The testsuite has been improved (we now use pyflakes to check for
errors in the code).
This version has been tested with Python 2.4 and 2.6 to 3.5, and Git
v1.7.10-406-gdc801e7, 2.1.4 and 2.8.1.339.g3ad15fd.
No change since 1.3 RC1.
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)
===================================
* The SMTP mailer was not working with Python 2.4.
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
=============
* Fix encoding of non-ASCII email addresses in email headers.
* Fix backwards-compatibility bugs for older Python 2.x versions.
* Fix a backwards-compatibility bug for Git 1.7.1.
* Add an option commitDiffOpts to customize logs for revisions.
* Pass "-oi" to sendmail by default to prevent premature termination
on a line containing only ".".
* Stagger email "Date:" values in an attempt to help mail clients
thread the emails in the right order.
* If a mailing list setting is missing, just skip sending the
corresponding email (with a warning) instead of failing.
* Add a X-Git-Host header that can be used for email filtering.
* Allow the sender's fully-qualified domain name to be configured.
* Minor documentation improvements.
* Add this CHANGES file.
Release 0.9.0
=============
* Initial release.

60
contrib/hooks/multimail/CONTRIBUTING.rst
View File

@ -1,60 +0,0 @@
Contributing
============
git-multimail is an open-source project, built by volunteers. We would
welcome your help!
The current maintainers are `Matthieu Moy <http://matthieu-moy.fr>`__ and
`Michael Haggerty <https://github.com/mhagger>`__.
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`_.
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>`__.
Please vote for issues you would like to be addressed in priority
(click "add your reaction" and then the "+1" thumbs-up button on the
GitHub issue).
General discussion of git-multimail can take place on the main `Git
mailing list`_.
Please CC emails regarding git-multimail to the maintainers so that we
don't overlook them.
Help needed: testers/maintainer for specific environments/OS
------------------------------------------------------------
The current maintainer uses and tests git-multimail on Linux with the
Generic environment. More testers, or better contributors are needed
to test git-multimail on other real-life setups:
* Mac OS X, Windows: git-multimail is currently not supported on these
platforms. But since we have no external dependencies and try to
write code as portable as possible, it is possible that
git-multimail already runs there and if not, it is likely that it
could be ported easily.
Patches to improve support for Windows and OS X are welcome.
Ideally, there would be a sub-maintainer for each OS who would test
at least once before each release (around twice a year).
* Gerrit, Stash, Gitolite environments: although the testsuite
contains tests for these environments, a tester/maintainer for each
environment would be welcome to test and report failure (or success)
on real-life environments periodically (here also, feedback before
each release would be highly appreciated).
.. _`git-multimail repository on GitHub`: https://github.com/git-multimail/git-multimail
.. _`Git mailing list`: git@vger.kernel.org

12
contrib/hooks/multimail/README.Git
View File

@ -1,15 +1,7 @@
This copy of git-multimail is distributed as part of the "contrib"
section of the Git project as a convenience to Git users.
git-multimail is developed as an independent project at the following
website:
https://github.com/git-multimail/git-multimail
The version in this directory was obtained from the upstream project
on January 07 2019 and consists of the "git-multimail" subdirectory from
revision
04e80e6c40be465cc62b6c246f0fcb8fd2cfd454 refs/tags/1.5.0
Please see the README file in this directory for information about how
to report bugs or contribute to git-multimail.
Please refer to that project page for information about how to report
bugs or contribute to git-multimail.

145
contrib/hooks/multimail/README.migrate-from-post-receive-email
View File

@ -1,145 +0,0 @@
git-multimail is close to, but not exactly, a plug-in replacement for
the old Git project script contrib/hooks/post-receive-email. This
document describes the differences and explains how to configure
git-multimail to get behavior closest to that of post-receive-email.
If you are in a hurry
=====================
A script called migrate-mailhook-config is included with
git-multimail. If you run this script within a Git repository that is
configured to use post-receive-email, it will convert the
configuration settings into the approximate equivalent settings for
git-multimail. For more information, run
migrate-mailhook-config --help
Configuration differences
=========================
* The names of the config options for git-multimail are in namespace
"multimailhook.*" instead of "hooks.*". (Editorial comment:
post-receive-email should never have used such a generic top-level
namespace.)
* In emails about new annotated tags, post-receive-email includes a
shortlog of all changes since the previous annotated tag. To get
this behavior with git-multimail, you need to set
multimailhook.announceshortlog to true:
git config multimailhook.announceshortlog true
* multimailhook.commitlist -- This is a new configuration variable.
Recipients listed here will receive a separate email for each new
commit. However, if this variable is *not* set, it defaults to the
value of multimailhook.mailinglist. Therefore, if you *don't* want
the members of multimailhook.mailinglist to receive one email per
commit, then set this value to the empty string:
git config multimailhook.commitlist ''
* multimailhook.emailprefix -- If this value is not set, then the
subjects of generated emails are prefixed with the short name of the
repository enclosed in square brackets; e.g., "[myrepo]".
post-receive-email defaults to prefix "[SCM]" if this option is not
set. So if you were using the old default and want to retain it
(for example, to avoid having to change your email filters), set
this variable explicitly to the old value:
git config multimailhook.emailprefix "[SCM]"
* The "multimailhook.showrev" configuration option is not supported.
Its main use is obsoleted by the one-email-per-commit feature of
git-multimail.
Other differences
=================
This section describes other differences in the behavior of
git-multimail vs. post-receive-email. For full details, please refer
to the main README file:
* One email per commit. For each reference change, the script first
outputs one email summarizing the reference change (including
one-line summaries of the new commits), then it outputs a separate
email for each new commit that was introduced, including patches.
These one-email-per-commit emails go to the addresses listed in
multimailhook.commitlist. post-receive-email sends only one email
for each *reference* that is changed, no matter how many commits
were added to the reference.
* Better algorithm for detecting new commits. post-receive-email
processes one reference change at a time, which causes it to fail to
describe new commits that were included in multiple branches. For
example, if a single push adds the "*" commits in the diagram below,
then post-receive-email would never include the details of the two
commits that are common to "master" and "branch" in its
notifications.
o---o---o---*---*---* <-- master
\
*---* <-- branch
git-multimail analyzes all reference modifications to determine
which commits were not present before the change, therefore avoiding
that error.
* In reference change emails, git-multimail tells which commits have
been added to the reference vs. are entirely new to the repository,
and which commits that have been omitted from the reference
vs. entirely discarded from the repository.
* The environment in which Git is running can be configured via an
"Environment" abstraction.
* Built-in support for Gitolite-managed repositories.
* Instead of using full SHA1 object names in emails, git-multimail
mostly uses abbreviated SHA1s, plus one-line log message summaries
where appropriate.
* In the schematic diagrams that explain non-fast-forward commits,
git-multimail shows the names of the branches involved.
* The emails generated by git-multimail include the name of the Git
repository that was modified; this is convenient for recipients who
are monitoring multiple repositories.
* git-multimail allows the email "From" addresses to be configured.
* The recipients lists (multimailhook.mailinglist,
multimailhook.refchangelist, multimailhook.announcelist, and
multimailhook.commitlist) can be comma-separated values and/or
multivalued settings in the config file; e.g.,
[multimailhook]
mailinglist = mr.brown@example.com, mr.black@example.com
announcelist = Him <him@example.com>
announcelist = Jim <jim@example.com>
announcelist = pop@example.com
This might make it easier to maintain short recipients lists without
requiring full-fledged mailing list software.
* By default, git-multimail sets email "Reply-To" headers to reply to
the pusher (for reference updates) and to the author (for commit
notifications). By default, the pusher's email address is
constructed by appending "multimailhook.emaildomain" to the pusher's
username.
* The generated emails contain a configurable footer. By default, it
lists the name of the administrator who should be contacted to
unsubscribe from notification emails.
* New option multimailhook.emailmaxlinelength to limit the length of
lines in the main part of the email body. The default limit is 500
characters.
* New option multimailhook.emailstrictutf8 to ensure that the main
part of the email body is valid UTF-8. Invalid characters are
turned into the Unicode replacement character, U+FFFD. By default
this option is turned on.
* Written in Python. Easier to add new features.

774
contrib/hooks/multimail/README.rst
View File

@ -1,774 +0,0 @@
git-multimail version 1.5.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``,
which can either be used as a hook script directly or can be imported
as a Python module into another script.
git-multimail is derived from the Git project's old
contrib/hooks/post-receive-email, and is mostly compatible with that
script. See README.migrate-from-post-receive-email for details about
the differences and for how to migrate from post-receive-email to
git-multimail.
git-multimail, like the rest of the Git project, is licensed under
GPLv2 (see the COPYING file for details).
Please note: although, as a convenience, git-multimail may be
distributed along with the main Git project, development of
git-multimail takes place in its own, separate project. Please, read
`<CONTRIBUTING.rst>`__ for more information.
By default, for each push received by the repository, git-multimail:
1. Outputs one email summarizing each reference that was changed.
These "reference change" (called "refchange" below) emails describe
the nature of the change (e.g., was the reference created, deleted,
fast-forwarded, etc.) and include a one-line summary of each commit
that was added to the reference.
2. Outputs one email for each new commit that was introduced by the
reference change. These "commit" emails include a list of the
files changed by the commit, followed by the diffs of files
modified by the commit. The commit emails are threaded to the
corresponding reference change email via "In-Reply-To". This style
(similar to the "git format-patch" style used on the Git mailing
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::
[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
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
"Reply-To" field set to the author of the commit.
3. Output one "announce" mail for each new annotated tag, including
information about the tag and optionally a shortlog describing the
changes since the previous tag. Such emails might be useful if you
use annotated tags to mark releases of your project.
Requirements
------------
* Python 2.x, version 2.4 or later. No non-standard Python modules
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
been tested; if you do so, please report your results.)
* To send emails using the default configuration, a standard sendmail
program must be located at '/usr/sbin/sendmail' or
'/usr/lib/sendmail' and must be configured correctly to send emails.
If this is not the case, set multimailhook.sendmailCommand, or see
the multimailhook.mailer configuration variable below for how to
configure git-multimail to send emails via an SMTP server.
* git-multimail is currently tested only on Linux. It may or may not
work on other platforms such as Windows and Mac OS. See
`<CONTRIBUTING.rst>`__ to improve the situation.
Invocation
----------
``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
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
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
[1]_.
Alternatively, ``git_multimail.py`` can be imported as a Python module
into your own Python post-receive script. This method is a bit more
work, but allows the behavior of the hook to be customized using
arbitrary Python code. For example, you can use a custom environment
(perhaps inheriting from GenericEnvironment or GitoliteEnvironment) to
* change how the user who did the push is determined
* read users' email addresses from an LDAP server or from a database
* decide which users should be notified about which commits based on
the contents of the commits (e.g., for users who want to be notified
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
to use ``git_multimail.py`` as a Python module. (If you make interesting
changes of this type, please consider sharing them with the
community.)
Troubleshooting/FAQ
-------------------
Please read `<doc/troubleshooting.rst>`__ for frequently asked
questions and common issues with git-multimail.
Configuration
-------------
By default, git-multimail mostly takes its configuration from the
following ``git config`` settings:
multimailhook.environment
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
the username of the pusher is read from $USER or $USERNAME and
the repository name is derived from the repository's path.
gitolite
Environment to use when ``git-multimail`` is ran as a gitolite_
hook.
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>`__
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``, 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
A short name of this Git repository, to be used in various places
in the notification email text. The default is to use $GL_REPO
for gitolite repositories, or otherwise to derive this value from
the repository path name.
multimailhook.mailingList
The list of email addresses to which notification emails should be
sent, as RFC 2822 email addresses separated by commas. This
configuration option can be multivalued. Leave it unset or set it
to the empty string to not send emails by default. The next few
settings can be used to configure specific address lists for
specific types of notification email.
multimailhook.refchangeList
The list of email addresses to which summary emails about
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 "none" (or the empty
string) to prevent reference change emails from being sent even if
multimailhook.mailingList is set.
multimailhook.announceList
The list of email addresses to which emails about new annotated
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 "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
The list of email addresses to which emails about individual new
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 "none" (or the empty string) to prevent notification emails about
individual commits from being sent even if
multimailhook.mailingList is set.
multimailhook.announceShortlog
If this option is set to true, then emails about changes to
annotated tags include a shortlog of changes since the previous
tag. This can be useful if the annotated tags represent releases;
then the shortlog will be a kind of rough summary of what has
happened since the last release. But if your tagging policy is
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).
By default, all the message is HTML-escaped. See
``multimailhook.htmlInIntro`` to change this behavior.
multimailhook.commitBrowseURL
Used to generate a link to an online repository browser in commit
emails. This variable must be a string. Format directives like
``%(<variable>)s`` will be expanded the same way as template
strings. In particular, ``%(id)s`` will be replaced by the full
Git commit identifier (40-chars hexadecimal).
If the string does not contain any format directive, then
``%(id)s`` will be automatically added to the string. If you don't
want ``%(id)s`` to be automatically added, use the empty format
directive ``%()s`` anywhere in the string.
For example, a suitable value for the git-multimail project itself
would be
``https://github.com/git-multimail/git-multimail/commit/%(id)s``.
multimailhook.htmlInIntro, multimailhook.htmlInFooter
When generating an HTML message, git-multimail escapes any HTML
sequence by default. This means that if a template contains HTML
like ``<a href="foo">link</a>``, the reader will see the HTML
source code and not a proper link.
Set ``multimailhook.htmlInIntro`` to true to allow writing HTML
formatting in introduction templates. Similarly, set
``multimailhook.htmlInFooter`` for HTML in the footer.
Variables expanded in the template are still escaped. For example,
if a repository's path contains a ``<``, it will be rendered as
such in the message.
Read `<doc/customizing-emails.rst>`__ for more details and
examples.
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.
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
mode can be further customized via the following options:
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.::
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).
multimailhook.envelopeSender
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
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.smtpUser, multimailhook.smtpPass
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. Default is 10.
multimailhook.smtpEncryption
Set the security type. Allowed values: ``none``, ``ssl``, ``tls`` (starttls).
Default is ``none``.
multimailhook.smtpCACerts
Set the path to a list of trusted CA certificate to verify the
server certificate, only supported when ``smtpEncryption`` is
``tls``. If unset or empty, the server certificate is not
verified. If it targets a file containing a list of trusted CA
certificates (PEM format) these CAs will be used to verify the
server certificate. For debian, you can set
``/etc/ssl/certs/ca-certificates.crt`` for using the system
trusted CAs. For self-signed server, you can add your server
certificate to the system store::
cd /usr/local/share/ca-certificates/
openssl s_client -starttls smtp \
-connect mail.example.net:587 -showcerts \
</dev/null 2>/dev/null \
| openssl x509 -outform PEM >mail.example.net.crt
update-ca-certificates
and used the updated ``/etc/ssl/certs/ca-certificates.crt``. Or
directly use your ``/path/to/mail.example.net.crt``. Default is
unset.
multimailhook.smtpServerDebugLevel
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.
``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 ``fromCommit``), 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)
1.a) If ``multimailhook.MailaddressMap`` is set, and is a path
to an existing file (if relative, it is considered relative to
the place where ``gitolite.conf`` is located), then this file
should contain lines like::
username Firstname Lastname <email@example.com>
git-multimail will then look for a line where ``$GL_USER``
matches the ``username`` part, and use the rest of the line for
the ``From:`` header.
1.b) 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.MailaddressMap
(gitolite environment only)
File to look for a ``From:`` address based on the user doing the
push. Defaults to unset. See ``multimailhook.from`` for details.
multimailhook.administrator
The name and/or email address of the administrator of the Git
repository; used in FOOTER_TEMPLATE. Default is
multimailhook.envelopesender if it is set; otherwise a generic
string is used.
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]``. Set this
value to the empty string to suppress the email prefix. You may
use the placeholder ``%(repo_shortname)s`` for the short name of
the repository.
multimailhook.emailMaxLines
The maximum number of lines that should be included in the body of
a generated email. If not specified, there is no limit. Lines
beyond the limit are suppressed and counted, and a final line is
added indicating the number of suppressed lines.
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 ``[...]``
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
lines, the diffs are probably unreadable anyway. To disable line
truncation, set this option to 0.
multimailhook.subjectMaxLength
The maximum length of the subject line (i.e. the ``oneline`` field
in templates, not including the prefix). Lines longer than this
limit are truncated to this length with a trailing ``[...]`` added
to indicate the missing text. This option The default is to use
``multimailhook.emailMaxLineLength``. This option avoids sending
emails with overly long subject lines, but should not be needed if
the commit messages follow the Git convention (one short subject
line, then a blank line, then the message body). To disable line
truncation, set this option to 0.
multimailhook.maxCommitEmails
The maximum number of commit emails to send for a given change.
When the number of patches is larger that this value, only the
summary refchange email is sent. This can avoid accidental
mailbombing, for example on an initial push. To disable commit
emails limit, set this option to 0. The default is 500.
multimailhook.excludeMergeRevisions
When sending out revision emails, do not consider merge commits (the
functional equivalent of `rev-list --no-merges`).
The default is `false` (send merge commit emails).
multimailhook.emailStrictUTF8
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`.
This option is ineffective with Python 3, where non-UTF-8
characters are unconditionally replaced.
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
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
reference change emails (used only if refchangeShowLog is set).
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::
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)::
[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
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
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 useful 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
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, 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 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.
The default is ``pusher`` for refchange emails, and ``author`` for
commit emails.
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
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.
If you are happy with the current shape of the feature, please
report it too.
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$
``refFilterInclusionRegex`` and ``refFilterExclusionRegex`` are
strictly stronger than ``refFilterDoSendRegex`` and
``refFilterDontSendRegex``. In other words, adding a ref to a
DoSend/DontSend regex has no effect if it is already excluded by a
Exclusion/Inclusion regex.
multimailhook.logFile, multimailhook.errorLogFile, multimailhook.debugLogFile
When set, these variable designate path to files where
git-multimail will log some messages. Normal messages and error
messages are sent to ``logFile``, and error messages are also sent
to ``errorLogFile``. Debug messages and all other messages are
sent to ``debugLogFile``. The recommended way is to set only one
of these variables, but it is also possible to set several of them
(part of the information is then duplicated in several log files,
for example errors are duplicated to all log files).
Relative path are relative to the Git repository where the push is
done.
multimailhook.verbose
Verbosity level of git-multimail on its standard output. By
default, show only error and info messages. If set to true, show
also debug messages.
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``.
Customizing email contents
--------------------------
git-multimail mostly generates emails by expanding templates. The
templates can be customized. To avoid the need to edit
``git_multimail.py`` directly, the preferred way to change the templates
is to write a separate Python script that imports ``git_multimail.py`` as
a module, then replaces the templates in place. See the provided
post-receive script for an example of how this is done.
Customizing git-multimail for your environment
----------------------------------------------
git-multimail is mostly customized via an "environment" that describes
the local environment in which Git is running. Two types of
environment are built in:
GenericEnvironment
a stand-alone Git repository.
GitoliteEnvironment
a Git repository that is managed by gitolite_. 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
option to the script.
If you need to customize the script in ways that are not supported by
the existing environments, you can define your own environment class
class using arbitrary Python code. To do so, you need to import
``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()``.
The standard environment classes, GenericEnvironment and
GitoliteEnvironment, are in fact themselves put together out of a
number of mixin classes, each of which handles one aspect of the
customization. For the finest control over your configuration, you
can specify exactly which mixin classes your own environment class
should inherit from, and override individual methods (or even add your
own mixin classes) to implement entirely new behaviors. If you
implement any mixins that might be useful to other people, please
consider sharing them with the community!
Getting involved
----------------
Please, read `<CONTRIBUTING.rst>`__ for instructions on how to
contribute to git-multimail.
Footnotes
---------
.. [1] 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.
.. _gitolite: https://github.com/sitaramc/gitolite

56
contrib/hooks/multimail/doc/customizing-emails.rst
View File

@ -1,56 +0,0 @@
Customizing the content and formatting of emails
================================================
Overloading template strings
----------------------------
The content of emails is generated based on template strings defined
in ``git_multimail.py``. You can customize these template strings
without changing the script itself, by defining a Python wrapper
around it. The python wrapper should ``import git_multimail`` and then
override the ``git_multimail.*`` strings like this::
import sys # needed for sys.argv
# Import and customize git_multimail:
import git_multimail
git_multimail.REVISION_INTRO_TEMPLATE = """..."""
git_multimail.COMBINED_INTRO_TEMPLATE = git_multimail.REVISION_INTRO_TEMPLATE
# start git_multimail itself:
git_multimail.main(sys.argv[1:])
The template strings can use any value already used in the existing
templates (read the source code).
Using HTML in template strings
------------------------------
If ``multimailhook.commitEmailFormat`` is set to HTML, then
git-multimail will generate HTML emails for commit notifications. The
log and diff will be formatted automatically by git-multimail. By
default, any HTML special character in the templates will be escaped.
To use HTML formatting in the introduction of the email, set
``multimailhook.htmlInIntro`` to ``true``. Then, the template can
contain any HTML tags, that will be sent as-is in the email. For
example, to add some formatting and a link to the online commit, use
a format like::
git_multimail.REVISION_INTRO_TEMPLATE = """\
<span style="color:#808080">This is an automated email from the git hooks/post-receive script.</span><br /><br />
<strong>%(pusher)s</strong> pushed a commit to %(refname_type)s %(short_refname)s
in repository %(repo_shortname)s.<br />
<a href="https://github.com/git-multimail/git-multimail/commit/%(newrev)s">View on GitHub</a>.
"""
Note that the values expanded from ``%(variable)s`` in the format
strings will still be escaped.
For a less flexible but easier to set up way to add a link to commit
emails, see ``multimailhook.commitBrowseURL``.
Similarly, one can set ``multimailhook.htmlInFooter`` and override any
of the ``*_FOOTER*`` template strings.

56
contrib/hooks/multimail/doc/gerrit.rst
View File

@ -1,56 +0,0 @@
Setting up git-multimail on Gerrit
==================================
Gerrit has its own email-sending system, but you may prefer using
``git-multimail`` instead. It supports Gerrit natively as a Gerrit
``ref-updated`` hook (Warning: `Gerrit hooks
<https://gerrit-review.googlesource.com/Documentation/config-hooks.html>`__
are distinct from Git hooks). Setting up ``git-multimail`` on a Gerrit
installation can be done following the instructions below.
The explanations show an easy way to set up ``git-multimail``,
but leave ``git-multimail`` installed and unconfigured for a while. If
you run Gerrit on a production server, it is advised that you
execute the step "Set up the hook" last to avoid confusing your users
in the meantime.
Set up the hook
---------------
Create a directory ``$site_path/hooks/`` if it does not exist (if you
don't know what ``$site_path`` is, run ``gerrit.sh status`` and look
for a ``GERRIT_SITE`` line). Either copy ``git_multimail.py`` to
``$site_path/hooks/ref-updated`` or create a wrapper script like
this::
#! /bin/sh
exec /path/to/git_multimail.py "$@"
In both cases, make sure the file is named exactly
``$site_path/hooks/ref-updated`` and is executable.
(Alternatively, you may configure the ``[hooks]`` section of
gerrit.config)
Configuration
-------------
Log on the gerrit server and edit ``$site_path/git/$project/config``
to configure ``git-multimail``.
Troubleshooting
---------------
Warning: this will disable ``git-multimail`` during the debug, and
could confuse your users. Don't run on a production server.
To debug configuration issues with ``git-multimail``, you can add the
``--stdout`` option when calling ``git_multimail.py`` like this::
#!/bin/sh
exec /path/to/git-multimail/git-multimail/git_multimail.py \
--stdout "$@" >> /tmp/log.txt
and try pushing from a test repository. You should see the source of
the email that would have been sent in the output of ``git push`` in
the file ``/tmp/log.txt``.

118
contrib/hooks/multimail/doc/gitolite.rst
View File

@ -1,118 +0,0 @@
Setting up git-multimail on gitolite
====================================
``git-multimail`` supports gitolite 3 natively.
The explanations below show an easy way to set up ``git-multimail``,
but leave ``git-multimail`` installed and unconfigured for a while. If
you run gitolite on a production server, it is advised that you
execute the step "Set up the hook" last to avoid confusing your users
in the meantime.
Set up the hook
---------------
Log in as your gitolite user.
Create a file ``.gitolite/hooks/common/post-receive`` on your gitolite
account containing (adapt the path, obviously)::
#!/bin/sh
exec /path/to/git-multimail/git-multimail/git_multimail.py "$@"
Make sure it's executable (``chmod +x``). Record the hook in
gitolite::
gitolite setup
Configuration
-------------
First, you have to allow the admin to set Git configuration variables.
As gitolite user, edit the line containing ``GIT_CONFIG_KEYS`` in file
``.gitolite.rc``, to make it look like::
GIT_CONFIG_KEYS => 'multimailhook\..*',
You can now log out and return to your normal user.
In the ``gitolite-admin`` clone, edit the file ``conf/gitolite.conf``
and add::
repo @all
# Not strictly needed as git_multimail.py will chose gitolite if
# $GL_USER is set.
config multimailhook.environment = gitolite
config multimailhook.mailingList = # Where emails should be sent
config multimailhook.from = # From address to use
Note that by default, gitolite forbids ``<`` and ``>`` in variable
values (for security/paranoia reasons, see
`compensating for UNSAFE_PATT
<http://gitolite.com/gitolite/git-config/index.html#compensating-for-unsafe95patt>`__
in gitolite's documentation for explanations and a way to disable
this). As a consequence, you will not be able to use ``First Last
<First.Last@example.com>`` as recipient email, but specifying
``First.Last@example.com`` alone works.
Obviously, you can customize all parameters on a per-repository basis by
adding these ``config multimailhook.*`` lines in the section
corresponding to a repository or set of repositories.
To activate ``git-multimail`` on a per-repository basis, do not set
``multimailhook.mailingList`` in the ``@all`` section and set it only
for repositories for which you want ``git-multimail``.
Alternatively, you can set up the ``From:`` field on a per-user basis
by adding a ``BEGIN USER EMAILS``/``END USER EMAILS`` section (see
``../README``).
Specificities of Gitolite for Configuration
-------------------------------------------
Empty configuration variables
.............................
With gitolite, the syntax ``config multimailhook.commitList = ""``
unsets the variable instead of setting it to an empty string (see
`here
<http://gitolite.com/gitolite/git-config.html#an-important-warning-about-deleting-a-config-line>`__).
As a result, there is no way to set a variable to the empty string.
In all most places where an empty value is required, git-multimail
now allows to specify special ``"none"`` value (case-sensitive) to
mean the same.
Alternatively, one can use ``" "`` (a single space) instead of ``""``.
In most cases (in particular ``multimailhook.*List`` variables), this
will be equivalent to an empty string.
If you have a use-case where ``"none"`` is not an acceptable value and
you need ``" "`` or ``""`` instead, please report it as a bug to
git-multimail.
Allowing Regular Expressions in Configuration
.............................................
gitolite has a mechanism to prevent unsafe configuration variable
values, which prevent characters like ``|`` commonly used in regular
expressions. If you do not need the safety feature of gitolite and
need to use regular expressions in your configuration (e.g. for
``multimailhook.refFilter*`` variables), set
`UNSAFE_PATT
<http://gitolite.com/gitolite/git-config.html#unsafe-patt>`__ to a
less restrictive value.
Troubleshooting
---------------
Warning: this will disable ``git-multimail`` during the debug, and
could confuse your users. Don't run on a production server.
To debug configuration issues with ``git-multimail``, you can add the
``--stdout`` option when calling ``git_multimail.py`` like this::
#!/bin/sh
exec /path/to/git-multimail/git-multimail/git_multimail.py --stdout "$@"
and try pushing from a test repository. You should see the source of
the email that would have been sent in the output of ``git push``.

78
contrib/hooks/multimail/doc/troubleshooting.rst
View File

@ -1,78 +0,0 @@
Troubleshooting issues with git-multimail: a FAQ
================================================
How to check that git-multimail is properly set up?
---------------------------------------------------
Since version 1.4.0, git-multimail allows a simple self-checking of
its configuration: run it with the environment variable
``GIT_MULTIMAIL_CHECK_SETUP`` set to a non-empty string. You should
get something like this::
$ GIT_MULTIMAIL_CHECK_SETUP=true /home/moy/dev/git-multimail/git-multimail/git_multimail.py
Environment values:
administrator : 'the administrator of this repository'
charset : 'utf-8'
emailprefix : '[git-multimail] '
fqdn : 'anie'
projectdesc : 'UNNAMED PROJECT'
pusher : 'moy'
repo_path : '/home/moy/dev/git-multimail'
repo_shortname : 'git-multimail'
Now, checking that git-multimail's standard input is properly set ...
Please type some text and then press Return
foo
You have just entered:
foo
git-multimail seems properly set up.
If you forgot to set an important variable, you may get instead::
$ GIT_MULTIMAIL_CHECK_SETUP=true /home/moy/dev/git-multimail/git-multimail/git_multimail.py
No email recipients configured!
Do not set ``$GIT_MULTIMAIL_CHECK_SETUP`` other than for testing your
configuration: it would disable the hook completely.
Git is not using the right address in the From/To/Reply-To field
----------------------------------------------------------------
First, make sure that git-multimail actually uses what you think it is
using. A lot happens to your email (especially when posting to a
mailing-list) between the time `git_multimail.py` sends it and the
time it reaches your inbox.
A simple test (to do on a test repository, do not use in production as
it would disable email sending): change your post-receive hook to call
`git_multimail.py` with the `--stdout` option, and try to push to the
repository. You should see something like::
Counting objects: 3, done.
Writing objects: 100% (3/3), 263 bytes | 0 bytes/s, done.
Total 3 (delta 0), reused 0 (delta 0)
remote: Sending notification emails to: foo.bar@example.com
remote: ===========================================================================
remote: Date: Mon, 25 Apr 2016 18:39:59 +0200
remote: To: foo.bar@example.com
remote: Subject: [git] branch master updated: foo
remote: MIME-Version: 1.0
remote: Content-Type: text/plain; charset=utf-8
remote: Content-Transfer-Encoding: 8bit
remote: Message-ID: <20160425163959.2311.20498@anie>
remote: From: Auth Or <Foo.Bar@example.com>
remote: Reply-To: Auth Or <Foo.Bar@example.com>
remote: X-Git-Host: example
...
remote: --
remote: To stop receiving notification emails like this one, please contact
remote: the administrator of this repository.
remote: ===========================================================================
To /path/to/repo
6278f04..e173f20 master -> master
Note: this does not include the sender (Return-Path: header), as it is
not part of the message content but passed to the mailer. Some mailer
show the ``Sender:`` field instead of the ``From:`` field (for
example, Zimbra Webmail shows ``From: <sender-field> on behalf of
<from-field>``).

4346
contrib/hooks/multimail/git_multimail.py
View File

File diff suppressed because it is too large Load Diff

274
contrib/hooks/multimail/migrate-mailhook-config
View File

@ -1,274 +0,0 @@
#! /usr/bin/env python
"""Migrate a post-receive-email configuration to be usable with git_multimail.py.
See README.migrate-from-post-receive-email for more information.
"""
import sys
import optparse
from git_multimail import CommandError
from git_multimail import Config
from git_multimail import read_output
OLD_NAMES = [
'mailinglist',
'announcelist',
'envelopesender',
'emailprefix',
'showrev',
'emailmaxlines',
'diffopts',
'scancommitforcc',
]
NEW_NAMES = [
'environment',
'reponame',
'mailinglist',
'refchangelist',
'commitlist',
'announcelist',
'announceshortlog',
'envelopesender',
'administrator',
'emailprefix',
'emailmaxlines',
'diffopts',
'emaildomain',
'scancommitforcc',
]
INFO = """\
SUCCESS!
Your post-receive-email configuration has been converted to
git-multimail format. Please see README and
README.migrate-from-post-receive-email to learn about other
git-multimail configuration possibilities.
For example, git-multimail has the following new options with no
equivalent in post-receive-email. You might want to read about them
to see if they would be useful in your situation:
"""
def _check_old_config_exists(old):
"""Check that at least one old configuration value is set."""
for name in OLD_NAMES:
if name in old:
return True
return False
def _check_new_config_clear(new):
"""Check that none of the new configuration names are set."""
retval = True
for name in NEW_NAMES:
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))
retval = False
return retval
def erase_values(config, names):
for name in names:
if name in config:
try:
sys.stderr.write('...unsetting "%s.%s"\n' % (config.section, name))
config.unset_all(name)
except CommandError:
sys.stderr.write(
'\nWARNING: could not unset "%s.%s". '
'Perhaps it is not set at the --local level?\n\n'
% (config.section, name)
)
def is_section_empty(section, local):
"""Return True iff the specified configuration section is empty.
Iff local is True, use the --local option when invoking 'git
config'."""
if local:
local_option = ['--local']
else:
local_option = []
try:
read_output(
['git', 'config'] +
local_option +
['--get-regexp', '^%s\.' % (section,)]
)
except CommandError:
t, e, traceback = sys.exc_info()
if e.retcode == 1:
# This means that no settings were found.
return True
else:
raise
else:
return False
def remove_section_if_empty(section):
"""If the specified configuration section is empty, delete it."""
try:
empty = is_section_empty(section, local=True)
except CommandError:
# Older versions of git do not support the --local option, so
# if the first attempt fails, try without --local.
try:
empty = is_section_empty(section, local=False)
except CommandError:
sys.stderr.write(
'\nINFO: If configuration section "%s.*" is empty, you might want '
'to delete it.\n\n'
% (section,)
)
return
if empty:
sys.stderr.write('...removing section "%s.*"\n' % (section,))
read_output(['git', 'config', '--remove-section', section])
else:
sys.stderr.write(
'\nINFO: Configuration section "%s.*" still has contents. '
'It will not be deleted.\n\n'
% (section,)
)
def migrate_config(strict=False, retain=False, overwrite=False):
old = Config('hooks')
new = Config('multimailhook')
if not _check_old_config_exists(old):
sys.exit(
'Your repository has no post-receive-email configuration. '
'Nothing to do.'
)
if not _check_new_config_clear(new):
if overwrite:
sys.stderr.write('\nWARNING: Erasing the above values...\n\n')
erase_values(new, NEW_NAMES)
else:
sys.exit(
'\nERROR: Refusing to overwrite existing values. Use the --overwrite\n'
'option to continue anyway.'
)
name = 'showrev'
if name in old:
msg = 'git-multimail does not support "%s.%s"' % (old.section, name,)
if strict:
sys.exit(
'ERROR: %s.\n'
'Please unset that value then try again, or run without --strict.'
% (msg,)
)
else:
sys.stderr.write('\nWARNING: %s (ignoring).\n\n' % (msg,))
for name in ['mailinglist', 'announcelist']:
if name in old:
sys.stderr.write(
'...copying "%s.%s" to "%s.%s"\n' % (old.section, name, new.section, name)
)
old_recipients = old.get_all(name, default=None)
old_recipients = ', '.join(o.strip() for o in old_recipients)
new.set_recipients(name, old_recipients)
if strict:
sys.stderr.write(
'...setting "%s.commitlist" to the empty string\n' % (new.section,)
)
new.set_recipients('commitlist', '')
sys.stderr.write(
'...setting "%s.announceshortlog" to "true"\n' % (new.section,)
)
new.set('announceshortlog', 'true')
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 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))
elif strict:
sys.stderr.write(
'...setting "%s.%s" to "[SCM]" to preserve old subject lines\n'
% (new.section, name)
)
new.set(name, '[SCM]')
if not retain:
erase_values(old, OLD_NAMES)
remove_section_if_empty(old.section)
sys.stderr.write(INFO)
for name in NEW_NAMES:
if name not in OLD_NAMES:
sys.stderr.write(' "%s.%s"\n' % (new.section, name,))
sys.stderr.write('\n')
def main(args):
parser = optparse.OptionParser(
description=__doc__,
usage='%prog [OPTIONS]',
)
parser.add_option(
'--strict', action='store_true', default=False,
help=(
'Slavishly configure git-multimail as closely as possible to '
'the post-receive-email configuration. Default is to turn '
'on some new features that have no equivalent in post-receive-email.'
),
)
parser.add_option(
'--retain', action='store_true', default=False,
help=(
'Retain the post-receive-email configuration values. '
'Default is to delete them after the new values are set.'
),
)
parser.add_option(
'--overwrite', action='store_true', default=False,
help=(
'Overwrite any existing git-multimail configuration settings. '
'Default is to abort if such settings already exist.'
),
)
(options, args) = parser.parse_args(args)
if args:
parser.error('Unexpected arguments: %s' % (' '.join(args),))
migrate_config(strict=options.strict, retain=options.retain, overwrite=options.overwrite)
main(sys.argv[1:])

101
contrib/hooks/multimail/post-receive.example
View File

@ -1,101 +0,0 @@
#! /usr/bin/env python
"""Example post-receive hook based on git-multimail.
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.
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.
* Configuration settings can be read from other sources; for example,
user names and email addresses could be read from LDAP or from a
database. Or the settings can even be hardcoded in the importing
Python script, if this is preferred.
This script is a very basic example of how to use git_multimail.py as
a module. The comments below explain some of the points at which the
script's behavior could be changed or customized.
"""
import sys
# If necessary, add the path to the directory containing
# git_multimail.py to the Python path as follows. (This is not
# necessary if git_multimail.py is in the same directory as this
# script):
#LIBDIR = 'path/to/directory/containing/module'
#sys.path.insert(0, LIBDIR)
import git_multimail
# It is possible to modify the output templates here; e.g.:
#git_multimail.FOOTER_TEMPLATE = """\
#
#-- \n\
#This email was generated by the wonderful git-multimail tool.
#"""
# Specify which "git config" section contains the configuration for
# git-multimail:
config = git_multimail.Config('multimailhook')
# Set some Git configuration variables. Equivalent to passing var=val
# to "git -c var=val" each time git is called, or to adding the
# configuration in .git/config (must come before instantiating the
# environment) :
#git_multimail.Config.add_config_parameters('multimailhook.commitEmailFormat=html')
#git_multimail.Config.add_config_parameters(('user.name=foo', 'user.email=foo@example.com'))
# Select the type of environment:
try:
environment = git_multimail.GenericEnvironment(config=config)
#environment = git_multimail.GitoliteEnvironment(config=config)
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:
mailer = git_multimail.choose_mailer(config, environment)
# Alternatively, you may hardcode the mailer using code like one of
# the following:
# Use "/usr/sbin/sendmail -oi -t" to send emails. The envelopesender
# argument is optional:
#mailer = git_multimail.SendMailer(
# command=['/usr/sbin/sendmail', '-oi', '-t'],
# envelopesender='git-repo@example.com',
# )
# Use Python's smtplib to send emails. Both arguments are required.
#mailer = git_multimail.SMTPMailer(
# environment=environment,
# envelopesender='git-repo@example.com',
# # The smtpserver argument can also include a port number; e.g.,
# # smtpserver='mail.example.com:25'
# smtpserver='mail.example.com',
# )
# OutputMailer is intended only for testing; it writes the emails to
# the specified file stream.
#mailer = git_multimail.OutputMailer(sys.stdout)
# Read changes from stdin and send notification emails:
git_multimail.run_as_post_receive_hook(environment, mailer)