multimail: stop shipping a copy

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>

12 files changed, 2 insertions, 6303 deletions

diff --git a/contrib/hooks/multimail/CHANGES b/contrib/hooks/multimail/CHANGES
deleted file mode 100644
index 35791fd02c..0000000000
--- a/contrib/hooks/multimail/CHANGES
+++ /dev/null
@@ -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.
diff --git a/contrib/hooks/multimail/CONTRIBUTING.rst b/contrib/hooks/multimail/CONTRIBUTING.rst
deleted file mode 100644
index de20a54287..0000000000
--- a/contrib/hooks/multimail/CONTRIBUTING.rst
+++ /dev/null
@@ -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
diff --git a/contrib/hooks/multimail/README.Git b/contrib/hooks/multimail/README.Git
index 044444245d..c427efc7bd 100644
--- a/contrib/hooks/multimail/README.Git
+++ b/contrib/hooks/multimail/README.Git
@@ -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.
diff --git a/contrib/hooks/multimail/README.migrate-from-post-receive-email b/contrib/hooks/multimail/README.migrate-from-post-receive-email
deleted file mode 100644
index 1e6a976699..0000000000
--- a/contrib/hooks/multimail/README.migrate-from-post-receive-email
+++ /dev/null
@@ -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.
diff --git a/contrib/hooks/multimail/README.rst b/contrib/hooks/multimail/README.rst
deleted file mode 100644
index 7c0fc4a6ef..0000000000
--- a/contrib/hooks/multimail/README.rst
+++ /dev/null
@@ -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