mirror of
https://github.com/git/git
synced 2024-08-27 19:49:21 +00:00
Merge branch 'js/no-more-multimail'
Remove multimail from contrib/ * js/no-more-multimail: multimail: stop shipping a copy
This commit is contained in:
commit
7e24201365
|
@ -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.
|
|
@ -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
|
|
@ -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.
|
||||
|
|
|
@ -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.
|
|
@ -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
|
|
@ -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.
|
|
@ -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``.
|
|
@ -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``.
|
|
@ -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>``).
|
File diff suppressed because it is too large
Load diff
|
@ -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:])
|
|
@ -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)
|
Loading…
Reference in a new issue