{"thread":{"id":"42154","subject":"[RFC/PATCH] git-multimail: update to release 1.3.0-rc1","startedAt":"2016-04-27T14:59:52Z","lastAt":"2016-04-27T14:59:52Z","messageCount":1,"participants":["Matthieu Moy"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"284648","messageId":"20160427145952.9032-1-Matthieu.Moy@imag.fr","threadId":"42154","inReplyTo":null,"subject":"[RFC/PATCH] git-multimail: update to release 1.3.0-rc1","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@imag.fr","sentAt":"2016-04-27T14:59:52Z","receivedAt":"2016-04-27T14:59:52Z","isPatch":true,"sender":{"key":"git@matthieu-moy.fr","avatar":"https://avatars.githubusercontent.com/u/14709?v=4"},"body":"The changes are described in CHANGES.\n\nContributions-by: Matthieu Moy \nContributions-by: Stefan Tatschner \nContributions-by: Simon P \nContributions-by: Leander Hasty \nSigned-off-by: Matthieu Moy \n---\nNot for inclusion, but tests and reviews welcome.\n\n contrib/hooks/multimail/CHANGES | 33 +++\n contrib/hooks/multimail/CONTRIBUTING.rst | 17 +-\n contrib/hooks/multimail/README | 215 +++++++++---------\n contrib/hooks/multimail/README.Git | 4 +-\n contrib/hooks/multimail/doc/customizing-emails.rst | 56 +++++\n contrib/hooks/multimail/doc/troubleshooting.rst | 44 ++++\n contrib/hooks/multimail/git_multimail.py | 242 ++++++++++++++++++---\n contrib/hooks/multimail/post-receive.example | 6 +\n 8 files changed, 474 insertions(+), 143 deletions(-)\n create mode 100644 contrib/hooks/multimail/doc/customizing-emails.rst\n create mode 100644 contrib/hooks/multimail/doc/troubleshooting.rst\n\ndiff --git a/contrib/hooks/multimail/CHANGES b/contrib/hooks/multimail/CHANGES\nindex bc77e66..ecbdb4e 100644\n--- a/contrib/hooks/multimail/CHANGES\n+++ b/contrib/hooks/multimail/CHANGES\n@@ -1,3 +1,36 @@\n+Release 1.3 RC1\n+===============\n+\n+* New options multimailhook.htmlInIntro and multimailhook.htmlInFooter\n+ now allow using HTML in the introduction and footer of emails (e.g.\n+ for a more pleasant formatting or to insert a link to the commit on\n+ a web interface).\n+\n+* A new option multimailhook.commitBrowseURL gives a simpler (and less\n+ flexible) way to add a link to a web interface for commit emails\n+ than multimailhook.htmlInIntro and multimailhook.htmlInFooter.\n+\n+* A new public function config.add_config_parameters was added to\n+ allow custom hooks to set specific Git configuration variables\n+ without modifying the configuration files. See an example in\n+ post-receive.example.\n+\n+* Error handling for SMTP has been improved (we used to print Python\n+ backtraces for legitimate errors).\n+\n+* The SMTP mailer can now check TLS certificates when the newly added\n+ configuration variable multimailhook.smtpCACerts.\n+\n+* Python 3 portability has been improved.\n+\n+* The documentation's formatting has been improved.\n+\n+* The testsuite has been improved (we now use pyflakes to check for\n+ errors in the code).\n+\n+This version has been tested with Python 2.4 and 2.6 to 3.5, and Git\n+v1.7.10-406-gdc801e7, 2.1.4 and 2.8.1.339.g3ad15fd.\n+\n Release 1.2.0\n =============\n \ndiff --git a/contrib/hooks/multimail/CONTRIBUTING.rst b/contrib/hooks/multimail/CONTRIBUTING.rst\nindex 09efdb0..530ecbf 100644\n--- a/contrib/hooks/multimail/CONTRIBUTING.rst\n+++ b/contrib/hooks/multimail/CONTRIBUTING.rst\n@@ -1,3 +1,6 @@\n+Contributing\n+============\n+\n git-multimail is an open-source project, built by volunteers. We would\n welcome your help!\n \n@@ -6,9 +9,7 @@ and Matthieu Moy .\n \n Please note that although a copy of git-multimail is distributed in\n the \"contrib\" section of the main Git project, development takes place\n-in a separate git-multimail repository on GitHub:\n-\n- https://github.com/git-multimail/git-multimail\n+in a separate `git-multimail repository on GitHub`_.\n \n Whenever enough changes to git-multimail have accumulated, a new\n code-drop of git-multimail will be submitted for inclusion in the Git\n@@ -21,10 +22,12 @@ to the maintainers). Please sign off your patches as per the `Git\n project practice\n `__.\n \n-General discussion of git-multimail can take place on the main Git\n-mailing list,\n-\n- git@vger.kernel.org\n+General discussion of git-multimail can take place on the main `Git\n+mailing list`_.\n \n Please CC emails regarding git-multimail to the maintainers so that we\n don't overlook them.\n+\n+\n+.. _`git-multimail repository on GitHub`: https://github.com/git-multimail/git-multimail\n+.. _`Git mailing list`: git@vger.kernel.org\ndiff --git a/contrib/hooks/multimail/README b/contrib/hooks/multimail/README\nindex 5512068..26b3a0a 100644\n--- a/contrib/hooks/multimail/README\n+++ b/contrib/hooks/multimail/README\n@@ -1,5 +1,5 @@\n-git-multimail (version 1.2.0)\n-=============================\n+git-multimail 1.3rc1\n+====================\n \n .. image:: https://travis-ci.org/git-multimail/git-multimail.svg?branch=master\n :target: https://travis-ci.org/git-multimail/git-multimail\n@@ -127,6 +127,13 @@ changes of this type, please consider sharing them with the\n community.)\n \n \n+Troubleshooting/FAQ\n+-------------------\n+\n+Please read ``__ for frequently asked\n+questions and common issues with git-multimail.\n+\n+\n Configuration\n -------------\n \n@@ -134,19 +141,16 @@ By default, git-multimail mostly takes its configuration from the\n following ``git config`` settings:\n \n multimailhook.environment\n-\n This describes the general environment of the repository. In most\n cases, you do not need to specify a value for this variable:\n `git-multimail` will autodetect which environment to use.\n Currently supported values:\n \n- * generic\n-\n+ generic\n the username of the pusher is read from $USER or $USERNAME and\n the repository name is derived from the repository's path.\n \n- * gitolite\n-\n+ gitolite\n the username of the pusher is read from $GL_USER, the repository\n name is read from $GL_REPO, and the From: header value is\n optionally read from gitolite.conf (see multimailhook.from).\n@@ -154,8 +158,7 @@ multimailhook.environment\n For more information about gitolite and git-multimail, read\n ``__\n \n- * stash\n-\n+ stash\n Environment to use when ``git-multimail`` is ran as an Atlassian\n BitBucket Server (formerly known as Atlassian Stash) hook.\n \n@@ -169,8 +172,7 @@ multimailhook.environment\n and repo come from these two command line flags, which must be\n specified.\n \n- * gerrit\n-\n+ gerrit\n Environment to use when ``git-multimail`` is ran as a\n ``ref-updated`` Gerrit hook.\n \n@@ -205,14 +207,12 @@ multimailhook.environment\n * If none of the above apply, then ``generic`` is used.\n \n multimailhook.repoName\n-\n A short name of this Git repository, to be used in various places\n in the notification email text. The default is to use $GL_REPO\n for gitolite repositories, or otherwise to derive this value from\n the repository path name.\n \n multimailhook.mailingList\n-\n The list of email addresses to which notification emails should be\n sent, as RFC 2822 email addresses separated by commas. This\n configuration option can be multivalued. Leave it unset or set it\n@@ -221,7 +221,6 @@ multimailhook.mailingList\n specific types of notification email.\n \n multimailhook.refchangeList\n-\n The list of email addresses to which summary emails about\n reference changes should be sent, as RFC 2822 email addresses\n separated by commas. This configuration option can be\n@@ -231,7 +230,6 @@ multimailhook.refchangeList\n multimailhook.mailingList is set.\n \n multimailhook.announceList\n-\n The list of email addresses to which emails about new annotated\n tags should be sent, as RFC 2822 email addresses separated by\n commas. This configuration option can be multivalued. The\n@@ -241,7 +239,6 @@ multimailhook.announceList\n even if one of the other values is set.\n \n multimailhook.commitList\n-\n The list of email addresses to which emails about individual new\n commits should be sent, as RFC 2822 email addresses separated by\n commas. This configuration option can be multivalued. The\n@@ -251,7 +248,6 @@ multimailhook.commitList\n multimailhook.mailingList is set.\n \n multimailhook.announceShortlog\n-\n If this option is set to true, then emails about changes to\n annotated tags include a shortlog of changes since the previous\n tag. This can be useful if the annotated tags represent releases;\n@@ -261,7 +257,6 @@ multimailhook.announceShortlog\n rather than useful. Default is false.\n \n multimailhook.commitEmailFormat\n-\n The format of email messages for the individual commits, can be \"text\" or\n \"html\". In the latter case, the emails will include diffs using colorized\n HTML instead of plain text used by default. Note that this currently the\n@@ -274,8 +269,43 @@ multimailhook.commitEmailFormat\n the message starting with ``+++`` or ``---`` colored in red or\n green).\n \n-multimailhook.refchangeShowGraph\n+ By default, all the message is HTML-escaped. See\n+ ``multimailhook.htmlInIntro`` to change this behavior.\n+\n+multimailhook.commitBrowseURL\n+ Used to generate a link to an online repository browser in commit\n+ emails. This variable must be a string. Format directives like\n+ ``%()s`` will be expanded the same way as template\n+ strings. In particular, ``%(id)s`` will be replaced by the full\n+ Git commit identifier (40-chars hexadecimal).\n+\n+ If the string does not contain any format directive, then\n+ ``%(id)s`` will be automatically added to the string. If you don't\n+ want ``%(id)s`` to be automatically added, use the empty format\n+ directive ``%()s`` anywhere in the string.\n+\n+ For example, a suitable value for the git-multimail project itself\n+ would be\n+ ``https://github.com/git-multimail/git-multimail/commit/%(id)s``.\n+\n+multimailhook.htmlInIntro, multimailhook.htmlInFooter\n+ When generating an HTML message, git-multimail escapes any HTML\n+ sequence by default. This means that if a template contains HTML\n+ like ``link``, the reader will see the HTML\n+ source code and not a proper link.\n+\n+ Set ``multimailhook.htmlInIntro`` to true to allow writting HTML\n+ formatting in introduction templates. Similarly, set\n+ ``multimailhook.htmlInFooter`` for HTML in the footer.\n \n+ Variables expanded in the template are still escaped. For example,\n+ if a repository's path contains a ``<``, it will be rendered as\n+ such in the message.\n+\n+ Read ``__ for more details and\n+ examples.\n+\n+multimailhook.refchangeShowGraph\n If this option is set to true, then summary emails about reference\n changes will additionally include:\n \n@@ -287,7 +317,6 @@ multimailhook.refchangeShowGraph\n specified in graphOpts. The default is false.\n \n multimailhook.refchangeShowLog\n-\n If this option is set to true, then summary emails about reference\n changes will include a detailed log of the added commits in\n addition to the one line summary. The log is generated by running\n@@ -295,71 +324,80 @@ multimailhook.refchangeShowLog\n Default is false.\n \n multimailhook.mailer\n-\n This option changes the way emails are sent. Accepted values are:\n \n- - sendmail (the default): use the command ``/usr/sbin/sendmail`` or\n+ * **sendmail (the default)**: use the command ``/usr/sbin/sendmail`` or\n ``/usr/lib/sendmail`` (or sendmailCommand, if configured). This\n mode can be further customized via the following options:\n \n- * multimailhook.sendmailCommand\n-\n- The command used by mailer ``sendmail`` to send emails. Shell\n- quoting is allowed in the value of this setting, but remember that\n- Git requires double-quotes to be escaped; e.g.::\n+ multimailhook.sendmailCommand\n+ The command used by mailer ``sendmail`` to send emails. Shell\n+ quoting is allowed in the value of this setting, but remember that\n+ Git requires double-quotes to be escaped; e.g.::\n \n- git config multimailhook.sendmailcommand '/usr/sbin/sendmail -oi -t -F \\\"Git Repo\\\"'\n+ git config multimailhook.sendmailcommand '/usr/sbin/sendmail -oi -t -F \\\"Git Repo\\\"'\n \n- Default is '/usr/sbin/sendmail -oi -t' or\n- '/usr/lib/sendmail -oi -t' (depending on which file is\n- present and executable).\n+ Default is '/usr/sbin/sendmail -oi -t' or\n+ '/usr/lib/sendmail -oi -t' (depending on which file is\n+ present and executable).\n \n- * multimailhook.envelopeSender\n+ multimailhook.envelopeSender\n+ If set then pass this value to sendmail via the -f option to set\n+ the envelope sender address.\n \n- If set then pass this value to sendmail via the -f option to set\n- the envelope sender address.\n-\n- - smtp: use Python's smtplib. This is useful when the sendmail\n+ * **smtp**: use Python's smtplib. This is useful when the sendmail\n command is not available on the system. This mode can be\n further customized via the following options:\n \n- * multimailhook.smtpServer\n-\n- The name of the SMTP server to connect to. The value can\n- also include a colon and a port number; e.g.,\n- ``mail.example.com:25``. Default is 'localhost' using port 25.\n-\n- * multimailhook.smtpUser\n- * multimailhook.smtpPass\n-\n- Server username and password. Required if smtpEncryption is 'ssl'.\n- Note that the username and password currently need to be\n- set cleartext in the configuration file, which is not\n- recommended. If you need to use this option, be sure your\n- configuration file is read-only.\n+ multimailhook.smtpServer\n+ The name of the SMTP server to connect to. The value can\n+ also include a colon and a port number; e.g.,\n+ ``mail.example.com:25``. Default is 'localhost' using port 25.\n \n- * multimailhook.envelopeSender\n+ multimailhook.smtpUser, multimailhook.smtpPass\n+ Server username and password. Required if smtpEncryption is 'ssl'.\n+ Note that the username and password currently need to be\n+ set cleartext in the configuration file, which is not\n+ recommended. If you need to use this option, be sure your\n+ configuration file is read-only.\n \n+ multimailhook.envelopeSender\n The sender address to be passed to the SMTP server. If\n unset, then the value of multimailhook.from is used.\n \n- * multimailhook.smtpServerTimeout\n-\n+ multimailhook.smtpServerTimeout\n Timeout in seconds.\n \n- * multimailhook.smtpEncryption\n-\n- Set the security type. Allowed values: none, ssl, tls.\n- Default=none.\n-\n- * multimailhook.smtpServerDebugLevel\n-\n+ multimailhook.smtpEncryption\n+ Set the security type. Allowed values: ``none``, ``ssl``, ``tls`` (starttls).\n+ Default is ``none``.\n+\n+ multimailhook.smtpCACerts\n+ Set the path to a list of trusted CA certificate to verify the\n+ server certificate, only supported when ``smtpEncryption`` is\n+ ``tls``. If unset or empty, the server certificate is not\n+ verified. If it targets a file containing a list of trusted CA\n+ certificates (PEM format) these CAs will be used to verify the\n+ server certificate. For debian, you can set\n+ ``/etc/ssl/certs/ca-certificates.crt`` for using the system\n+ trusted CAs. For self-signed server, you can add your server\n+ certificate to the system store::\n+\n+ cd /usr/local/share/ca-certificates/\n+ openssl s_client -starttls smtp \\\n+ -connect mail.example.net:587 -showcerts \\\n+ /dev/null \\\n+ | openssl x509 -outform PEM >mail.example.net.crt\n+ update-ca-certificates\n+\n+ and used the updated ``/etc/ssl/certs/ca-certificates.crt``. Or\n+ directly use your ``/path/to/mail.example.net.crt``. Default is\n+ unset.\n+\n+ multimailhook.smtpServerDebugLevel\n Integer number. Set to greater than 0 to activate debugging.\n \n-multimailhook.from\n-multimailhook.fromCommit\n-multimailhook.fromRefchange\n-\n+multimailhook.from, multimailhook.fromCommit, multimailhook.fromRefchange\n If set, use this value in the From: field of generated emails.\n ``fromCommit`` is used for commit emails, ``fromRefchange`` is\n used for refchange emails, and ``from`` is used as fall-back in\n@@ -372,7 +410,7 @@ multimailhook.fromRefchange\n - The value ``pusher``, in which case the pusher's address (if\n available) will be used.\n \n- - The value ``author`` (meaningful only for replyToCommit), in which\n+ - The value ``author`` (meaningful only for ``fromCommit``), in which\n case the commit author's address will be used.\n \n If config values are unset, the value of the From: header is\n@@ -396,14 +434,12 @@ multimailhook.fromRefchange\n 3. Use the value of multimailhook.envelopeSender.\n \n multimailhook.administrator\n-\n The name and/or email address of the administrator of the Git\n repository; used in FOOTER_TEMPLATE. Default is\n multimailhook.envelopesender if it is set; otherwise a generic\n string is used.\n \n multimailhook.emailPrefix\n-\n All emails have this string prepended to their subjects, to aid\n email filtering (though filtering based on the X-Git-* email\n headers is probably more robust). Default is the short name of\n@@ -411,16 +447,14 @@ multimailhook.emailPrefix\n value to the empty string to suppress the email prefix.\n \n multimailhook.emailMaxLines\n-\n The maximum number of lines that should be included in the body of\n a generated email. If not specified, there is no limit. Lines\n beyond the limit are suppressed and counted, and a final line is\n added indicating the number of suppressed lines.\n \n multimailhook.emailMaxLineLength\n-\n The maximum length of a line in the email body. Lines longer than\n- this limit are truncated to this length with a trailing `` [...]``\n+ this limit are truncated to this length with a trailing ``[...]``\n added to indicate the missing text. The default is 500, because\n (a) diffs with longer lines are probably from binary files, for\n which a diff is useless, and (b) even if a text file has such long\n@@ -428,7 +462,6 @@ multimailhook.emailMaxLineLength\n truncation, set this option to 0.\n \n multimailhook.maxCommitEmails\n-\n The maximum number of commit emails to send for a given change.\n When the number of patches is larger that this value, only the\n summary refchange email is sent. This can avoid accidental\n@@ -436,14 +469,12 @@ multimailhook.maxCommitEmails\n emails limit, set this option to 0. The default is 500.\n \n multimailhook.emailStrictUTF8\n-\n If this boolean option is set to `true`, then the main part of the\n email body is forced to be valid UTF-8. Any characters that are\n not valid UTF-8 are converted to the Unicode replacement\n character, U+FFFD. The default is `true`.\n \n multimailhook.diffOpts\n-\n Options passed to ``git diff-tree`` when generating the summary\n information for ReferenceChange emails. Default is ``--stat\n --summary --find-copies-harder``. Add -p to those options to\n@@ -452,7 +483,6 @@ multimailhook.diffOpts\n details.\n \n multimailhook.graphOpts\n-\n Options passed to ``git log --graph`` when generating graphs for the\n reference change summary emails (used only if refchangeShowGraph\n is true). The default is '--oneline --decorate'.\n@@ -460,7 +490,6 @@ multimailhook.graphOpts\n Shell quoting is allowed; see logOpts for details.\n \n multimailhook.logOpts\n-\n Options passed to ``git log`` to generate additional info for\n reference change emails (used only if refchangeShowLog is set).\n For example, adding -p will show each commit's complete diff. The\n@@ -479,7 +508,6 @@ multimailhook.logOpts\n logopts = --pretty=format:\\\"%h %aN <%aE>%n%s%n%n%b%n\\\"\n \n multimailhook.commitLogOpts\n-\n Options passed to ``git log`` to generate additional info for\n revision change emails. For example, adding --ignore-all-spaces\n will suppress whitespace changes. The default options are ``-C\n@@ -487,26 +515,21 @@ multimailhook.commitLogOpts\n multimailhook.logOpts for details.\n \n multimailhook.dateSubstitute\n-\n String to use as a substitute for ``Date:`` in the output of ``git\n log`` while formatting commit messages. This is usefull to avoid\n emitting a line that can be interpreted by mailers as the start of\n a cited message (Zimbra webmail in particular). Defaults to\n- ``CommitDate: ``. Set to an empty string or ``none`` to deactivate\n+ ``CommitDate:``. Set to an empty string or ``none`` to deactivate\n the behavior.\n \n multimailhook.emailDomain\n-\n Domain name appended to the username of the person doing the push\n to convert it into an email address\n (via ``\"%s@%s\" % (username, emaildomain)``). More complicated\n schemes can be implemented by overriding Environment and\n overriding its get_pusher_email() method.\n \n-multimailhook.replyTo\n-multimailhook.replyToCommit\n-multimailhook.replyToRefchange\n-\n+multimailhook.replyTo, multimailhook.replyToCommit, multimailhook.replyToRefchange\n Addresses to use in the Reply-To: field for commit emails\n (replyToCommit) and refchange emails (replyToRefchange).\n multimailhook.replyTo is used as default when replyToCommit or\n@@ -519,32 +542,24 @@ multimailhook.replyToRefchange\n commit emails.\n \n multimailhook.quiet\n-\n Do not output the list of email recipients from the hook\n \n multimailhook.stdout\n-\n For debugging, send emails to stdout rather than to the\n mailer. Equivalent to the --stdout command line option\n \n multimailhook.scanCommitForCc\n-\n If this option is set to true, than recipients from lines in commit body\n that starts with ``CC:`` will be added to CC list.\n Default: false\n \n multimailhook.combineWhenSingleCommit\n-\n If this option is set to true and a single new commit is pushed to\n a branch, combine the summary and commit email messages into a\n single email.\n Default: true\n \n-multimailhook.refFilterInclusionRegex\n-multimailhook.refFilterExclusionRegex\n-multimailhook.refFilterDoSendRegex\n-multimailhook.refFilterDontSendRegex\n-\n+multimailhook.refFilterInclusionRegex, multimailhook.refFilterExclusionRegex, multimailhook.refFilterDoSendRegex, multimailhook.refFilterDontSendRegex\n **Warning:** these options are experimental. They should work, but\n the user-interface is not stable yet (in particular, the option\n names may change). If you want to participate in stabilizing the\n@@ -626,14 +641,16 @@ git-multimail is mostly customized via an \"environment\" that describes\n the local environment in which Git is running. Two types of\n environment are built in:\n \n-* GenericEnvironment: a stand-alone Git repository.\n+GenericEnvironment\n+ a stand-alone Git repository.\n \n-* GitoliteEnvironment: a Git repository that is managed by gitolite\n- [3]_. For such repositories, the identity of the pusher is read from\n- environment variable $GL_USER, the name of the repository is read\n- from $GL_REPO (if it is not overridden by multimailhook.reponame),\n- and the From: header value is optionally read from gitolite.conf\n- (see multimailhook.from).\n+GitoliteEnvironment\n+ a Git repository that is managed by gitolite\n+ [3]_. For such repositories, the identity of the pusher is read from\n+ environment variable $GL_USER, the name of the repository is read\n+ from $GL_REPO (if it is not overridden by multimailhook.reponame),\n+ and the From: header value is optionally read from gitolite.conf\n+ (see multimailhook.from).\n \n By default, git-multimail assumes GitoliteEnvironment if $GL_USER and\n $GL_REPO are set, and otherwise assumes GenericEnvironment.\ndiff --git a/contrib/hooks/multimail/README.Git b/contrib/hooks/multimail/README.Git\nindex 300a2a4..6c4faf5 100644\n--- a/contrib/hooks/multimail/README.Git\n+++ b/contrib/hooks/multimail/README.Git\n@@ -6,10 +6,10 @@ website:\n https://github.com/git-multimail/git-multimail\n \n The version in this directory was obtained from the upstream project\n-on October 11 2015 and consists of the \"git-multimail\" subdirectory from\n+on April 27 2016 and consists of the \"git-multimail\" subdirectory from\n revision\n \n- c0791b9ef5821a746fc3475c25765e640452eaae refs/tags/1.2.0\n+ b512b8ea5fdc625a6b800da6c7354bd366312857 refs/tags/1.3.0-rc1\n \n Please see the README file in this directory for information about how\n to report bugs or contribute to git-multimail.\ndiff --git a/contrib/hooks/multimail/doc/customizing-emails.rst b/contrib/hooks/multimail/doc/customizing-emails.rst\nnew file mode 100644\nindex 0000000..3f5b67f\n--- /dev/null\n+++ b/contrib/hooks/multimail/doc/customizing-emails.rst\n@@ -0,0 +1,56 @@\n+Customizing the content and formatting of emails\n+================================================\n+\n+Overloading template strings\n+----------------------------\n+\n+The content of emails is generated based on template strings defined\n+in ``git_multimail.py``. You can customize these template strings\n+without changing the script itself, by defining a Python wrapper\n+around it. The python wrapper should ``import git_multimail`` and then\n+override the ``git_multimail.*`` strings like this::\n+\n+ import sys # needed for sys.argv\n+\n+ # Import and customize git_multimail:\n+ import git_multimail\n+ git_multimail.REVISION_INTRO_TEMPLATE = \"\"\"...\"\"\"\n+ git_multimail.COMBINED_INTRO_TEMPLATE = git_multimail.REVISION_INTRO_TEMPLATE\n+\n+ # start git_multimail itself:\n+ git_multimail.main(sys.argv[1:])\n+\n+The template strings can use any value already used in the existing\n+templates (read the source code).\n+\n+Using HTML in template strings\n+------------------------------\n+\n+If ``multimailhook.commitEmailFormat`` is set to HTML, then\n+git-multimail will generate HTML emails for commit notifications. The\n+log and diff will be formatted automatically by git-multimail. By\n+default, any HTML special character in the templates will be escaped.\n+\n+To use HTML formatting in the introduction of the email, set\n+``multimailhook.htmlInIntro`` to ``true``. Then, the template can\n+contain any HTML tags, that will be sent as-is in the email. For\n+example, to add some formatting and a link to the online commit, use\n+a format like::\n+\n+ git_multimail.REVISION_INTRO_TEMPLATE = \"\"\"\\\n+ This is an automated email from the git hooks/post-receive script.

\n+\n+ %(pusher)s pushed a commit to %(refname_type)s %(short_refname)s\n+ in repository %(repo_shortname)s.
\n+\n+ View on GitHub.\n+ \"\"\"\n+\n+Note that the values expanded from ``%(variable)s`` in the format\n+strings will still be escaped.\n+\n+For a less flexible but easier to set up way to add a link to commit\n+emails, see ``multimailhook.commitBrowseURL``.\n+\n+Similarly, one can set ``multimailhook.htmlInFooter`` and override any\n+of the ``*_FOOTER*`` template strings.\ndiff --git a/contrib/hooks/multimail/doc/troubleshooting.rst b/contrib/hooks/multimail/doc/troubleshooting.rst\nnew file mode 100644\nindex 0000000..542d30e\n--- /dev/null\n+++ b/contrib/hooks/multimail/doc/troubleshooting.rst\n@@ -0,0 +1,44 @@\n+Troubleshooting issues with git-multimail: a FAQ\n+================================================\n+\n+Git is not using the right address in the From/To/Reply-To field\n+----------------------------------------------------------------\n+\n+First, make sure that git-multimail actually uses what you think it is\n+using. A lot happens to your email (especially when posting to a\n+mailing-list) between the time `git_multimail.py` sends it and the\n+time it reaches your inbox.\n+\n+A simple test (to do on a test repository, do not use in production as\n+it would disable email sending): change your post-receive hook to call\n+`git_multimail.py` with the `--stdout` option, and try to push to the\n+repository. You should see something like::\n+\n+ Counting objects: 3, done.\n+ Writing objects: 100% (3/3), 263 bytes | 0 bytes/s, done.\n+ Total 3 (delta 0), reused 0 (delta 0)\n+ remote: Sending notification emails to: foo.bar@example.com\n+ remote: ===========================================================================\n+ remote: Date: Mon, 25 Apr 2016 18:39:59 +0200\n+ remote: To: foo.bar@example.com\n+ remote: Subject: [git] branch master updated: foo\n+ remote: MIME-Version: 1.0\n+ remote: Content-Type: text/plain; charset=utf-8\n+ remote: Content-Transfer-Encoding: 8bit\n+ remote: Message-ID: <20160425163959.2311.20498@anie>\n+ remote: From: Auth Or \n+ remote: Reply-To: Auth Or \n+ remote: X-Git-Host: example\n+ ...\n+ remote: -- \n+ remote: To stop receiving notification emails like this one, please contact\n+ remote: the administrator of this repository.\n+ remote: ===========================================================================\n+ To /path/to/repo\n+ 6278f04..e173f20 master -> master\n+ \n+Note: this does not include the sender (Return-Path: header), as it is\n+not part of the message content but passed to the mailer. Some mailer\n+show the ``Sender:`` field instead of the ``From:`` field (for\n+example, Zimbra Webmail shows ``From: on behalf of\n+``).\ndiff --git a/contrib/hooks/multimail/git_multimail.py b/contrib/hooks/multimail/git_multimail.py\nindex 0180dba..a486f33 100755\n--- a/contrib/hooks/multimail/git_multimail.py\n+++ b/contrib/hooks/multimail/git_multimail.py\n@@ -1,6 +1,6 @@\n #! /usr/bin/env python\n \n-__version__ = '1.2.0'\n+__version__ = '1.3.rc1'\n \n # Copyright (c) 2015 Matthieu Moy and others\n # Copyright (c) 2012-2014 Michael Haggerty and others\n@@ -57,6 +57,11 @@ import subprocess\n import shlex\n import optparse\n import smtplib\n+try:\n+ import ssl\n+except ImportError:\n+ # Python < 2.6 do not have ssl, but that's OK if we don't use it.\n+ pass\n import time\n import cgi\n \n@@ -75,6 +80,9 @@ def is_ascii(s):\n \n \n if PYTHON3:\n+ def is_string(s):\n+ return isinstance(s, str)\n+\n def str_to_bytes(s):\n return s.encode(ENCODING)\n \n@@ -91,6 +99,12 @@ if PYTHON3:\n except UnicodeEncodeError:\n f.buffer.write(msg.encode(ENCODING))\n else:\n+ def is_string(s):\n+ try:\n+ return isinstance(s, basestring)\n+ except NameError: # Silence Pyflakes warning\n+ raise\n+\n def str_to_bytes(s):\n return s\n \n@@ -313,6 +327,16 @@ in repository %(repo_shortname)s.\n \n \"\"\"\n \n+LINK_TEXT_TEMPLATE = \"\"\"\\\n+View the commit online:\n+%(browse_url)s\n+\n+\"\"\"\n+\n+LINK_HTML_TEMPLATE = \"\"\"\\\n+

View the commit online.

\n+\"\"\"\n+\n \n REVISION_FOOTER_TEMPLATE = FOOTER_TEMPLATE\n \n@@ -532,6 +556,28 @@ class Config(object):\n assert words[-1] == ''\n return words[:-1]\n \n+ @staticmethod\n+ def add_config_parameters(c):\n+ \"\"\"Add configuration parameters to Git.\n+\n+ c is either an str or a list of str, each element being of the\n+ form 'var=val' or 'var', with the same syntax and meaning as\n+ the argument of 'git -c var=val'.\n+ \"\"\"\n+ if isinstance(c, str):\n+ c = (c,)\n+ parameters = os.environ.get('GIT_CONFIG_PARAMETERS', '')\n+ if parameters:\n+ parameters += ' '\n+ # git expects GIT_CONFIG_PARAMETERS to be of the form\n+ # \"'name1=value1' 'name2=value2' 'name3=value3'\"\n+ # including everything inside the double quotes (but not the double\n+ # quotes themselves). Spacing is critical. Also, if a value contains\n+ # a literal single quote that quote must be represented using the\n+ # four character sequence: '\\''\n+ parameters += ' '.join(\"'\" + x.replace(\"'\", \"'\\\\''\") + \"'\" for x in c)\n+ os.environ['GIT_CONFIG_PARAMETERS'] = parameters\n+\n def get(self, name, default=None):\n try:\n values = self._split(read_git_output(\n@@ -745,6 +791,12 @@ class Change(object):\n values['multimail_version'] = get_version()\n return values\n \n+ # Aliases usable in template strings. Tuple of pairs (destination,\n+ # source).\n+ VALUES_ALIAS = (\n+ (\"id\", \"newrev\"),\n+ )\n+\n def get_values(self, **extra_values):\n \"\"\"Return a dictionary {keyword: expansion} for this Change.\n \n@@ -760,6 +812,9 @@ class Change(object):\n values = self._values.copy()\n if extra_values:\n values.update(extra_values)\n+\n+ for alias, val in self.VALUES_ALIAS:\n+ values[alias] = values[val]\n return values\n \n def expand(self, template, **extra_values):\n@@ -772,10 +827,14 @@ class Change(object):\n \n return template % self.get_values(**extra_values)\n \n- def expand_lines(self, template, **extra_values):\n+ def expand_lines(self, template, html_escape_val=False, **extra_values):\n \"\"\"Break template into lines and expand each line.\"\"\"\n \n values = self.get_values(**extra_values)\n+ if html_escape_val:\n+ for k in values:\n+ if is_string(values[k]):\n+ values[k] = cgi.escape(values[k], True)\n for line in template.splitlines(True):\n yield line % values\n \n@@ -787,9 +846,10 @@ class Change(object):\n \n values = self.get_values(**extra_values)\n if self._contains_html_diff:\n- values['contenttype'] = 'html'\n+ self._content_type = 'html'\n else:\n- values['contenttype'] = 'plain'\n+ self._content_type = 'plain'\n+ values['contenttype'] = self._content_type\n \n for line in template.splitlines():\n (name, value) = line.split(': ', 1)\n@@ -819,7 +879,11 @@ class Change(object):\n \n raise NotImplementedError()\n \n- def generate_email_intro(self):\n+ def generate_browse_link(self, base_url):\n+ \"\"\"Generate a link to an online repository browser.\"\"\"\n+ return iter(())\n+\n+ def generate_email_intro(self, html_escape_val=False):\n \"\"\"Generate the email intro for this Change, a line at a time.\n \n The output will be used as the standard boilerplate at the top\n@@ -835,7 +899,7 @@ class Change(object):\n \n raise NotImplementedError()\n \n- def generate_email_footer(self):\n+ def generate_email_footer(self, html_escape_val):\n \"\"\"Generate the footer of the email, a line at a time.\n \n The footer is always included, irrespective of\n@@ -876,9 +940,18 @@ class Change(object):\n for line in self.generate_email_header(**extra_header_values):\n yield line\n yield '\\n'\n- for line in self._wrap_for_html(self.generate_email_intro()):\n+ html_escape_val = (self.environment.html_in_intro and\n+ self._contains_html_diff)\n+ intro = self.generate_email_intro(html_escape_val)\n+ if not self.environment.html_in_intro:\n+ intro = self._wrap_for_html(intro)\n+ for line in intro:\n yield line\n \n+ if self.environment.commitBrowseURL:\n+ for line in self.generate_browse_link(self.environment.commitBrowseURL):\n+ yield line\n+\n body = self.generate_email_body(push)\n if body_filter is not None:\n body = body_filter(body)\n@@ -939,8 +1012,12 @@ class Change(object):\n yield line\n if self._contains_html_diff:\n yield ''\n-\n- for line in self._wrap_for_html(self.generate_email_footer()):\n+ html_escape_val = (self.environment.html_in_footer and\n+ self._contains_html_diff)\n+ footer = self.generate_email_footer(html_escape_val)\n+ if not self.environment.html_in_footer:\n+ footer = self._wrap_for_html(footer)\n+ for line in footer:\n yield line\n \n def get_alt_fromaddr(self):\n@@ -992,6 +1069,7 @@ class Revision(Change):\n values['rev_short'] = self.rev.short\n values['change_type'] = self.change_type\n values['refname'] = self.refname\n+ values['newrev'] = self.rev.sha1\n values['short_refname'] = self.reference_change.short_refname\n values['refname_type'] = self.reference_change.refname_type\n values['reply_to_msgid'] = self.reference_change.msgid\n@@ -1015,8 +1093,26 @@ class Revision(Change):\n ):\n yield line\n \n- def generate_email_intro(self):\n- for line in self.expand_lines(REVISION_INTRO_TEMPLATE):\n+ def generate_browse_link(self, base_url):\n+ if '%(' not in base_url:\n+ base_url += '%(id)s'\n+ url = \"\".join(self.expand_lines(base_url))\n+ if self._content_type == 'html':\n+ for line in self.expand_lines(LINK_HTML_TEMPLATE,\n+ html_escape_val=True,\n+ browse_url=url):\n+ yield line\n+ elif self._content_type == 'plain':\n+ for line in self.expand_lines(LINK_TEXT_TEMPLATE,\n+ html_escape_val=False,\n+ browse_url=url):\n+ yield line\n+ else:\n+ raise NotImplementedError(\"Content-type %s unsupported. Please report it as a bug.\")\n+\n+ def generate_email_intro(self, html_escape_val=False):\n+ for line in self.expand_lines(REVISION_INTRO_TEMPLATE,\n+ html_escape_val=html_escape_val):\n yield line\n \n def generate_email_body(self, push):\n@@ -1031,8 +1127,9 @@ class Revision(Change):\n else:\n yield line\n \n- def generate_email_footer(self):\n- return self.expand_lines(REVISION_FOOTER_TEMPLATE)\n+ def generate_email_footer(self, html_escape_val):\n+ return self.expand_lines(REVISION_FOOTER_TEMPLATE,\n+ html_escape_val=html_escape_val)\n \n def generate_email(self, push, body_filter=None, extra_header_values={}):\n self._contains_diff()\n@@ -1217,8 +1314,9 @@ class ReferenceChange(Change):\n ):\n yield line\n \n- def generate_email_intro(self):\n- for line in self.expand_lines(self.intro_template):\n+ def generate_email_intro(self, html_escape_val=False):\n+ for line in self.expand_lines(self.intro_template,\n+ html_escape_val=html_escape_val):\n yield line\n \n def generate_email_body(self, push):\n@@ -1238,8 +1336,9 @@ class ReferenceChange(Change):\n for line in self.generate_revision_change_summary(push):\n yield line\n \n- def generate_email_footer(self):\n- return self.expand_lines(self.footer_template)\n+ def generate_email_footer(self, html_escape_val):\n+ return self.expand_lines(self.footer_template,\n+ html_escape_val=html_escape_val)\n \n def generate_revision_change_graph(self, push):\n if self.showgraph:\n@@ -1896,6 +1995,7 @@ class SMTPMailer(Mailer):\n smtpservertimeout=10.0, smtpserverdebuglevel=0,\n smtpencryption='none',\n smtpuser='', smtppass='',\n+ smtpcacerts=''\n ):\n if not envelopesender:\n sys.stderr.write(\n@@ -1915,6 +2015,7 @@ class SMTPMailer(Mailer):\n self.security = smtpencryption\n self.username = smtpuser\n self.password = smtppass\n+ self.smtpcacerts = smtpcacerts\n try:\n def call(klass, server, timeout):\n try:\n@@ -1925,13 +2026,56 @@ class SMTPMailer(Mailer):\n if self.security == 'none':\n self.smtp = call(smtplib.SMTP, self.smtpserver, timeout=self.smtpservertimeout)\n elif self.security == 'ssl':\n+ if self.smtpcacerts:\n+ raise smtplib.SMTPException(\n+ \"Checking certificate is not supported for ssl, prefer starttls\"\n+ )\n self.smtp = call(smtplib.SMTP_SSL, self.smtpserver, timeout=self.smtpservertimeout)\n elif self.security == 'tls':\n+ if 'ssl' not in sys.modules:\n+ sys.stderr.write(\n+ '*** Your Python version does not have the ssl library installed\\n'\n+ '*** smtpEncryption=tls is not available.\\n'\n+ '*** Either upgrade Python to 2.6 or later\\n'\n+ ' or use git_multimail.py version 1.2.\\n')\n if ':' not in self.smtpserver:\n self.smtpserver += ':587' # default port for TLS\n self.smtp = call(smtplib.SMTP, self.smtpserver, timeout=self.smtpservertimeout)\n+ # start: ehlo + starttls\n+ # equivalent to\n+ # self.smtp.ehlo()\n+ # self.smtp.starttls()\n+ # with acces to the ssl layer\n self.smtp.ehlo()\n- self.smtp.starttls()\n+ if not self.smtp.has_extn(\"starttls\"):\n+ raise smtplib.SMTPException(\"STARTTLS extension not supported by server\")\n+ resp, reply = self.smtp.docmd(\"STARTTLS\")\n+ if resp != 220:\n+ raise smtplib.SMTPException(\"Wrong answer to the STARTTLS command\")\n+ if self.smtpcacerts:\n+ self.smtp.sock = ssl.wrap_socket(\n+ self.smtp.sock,\n+ ca_certs=self.smtpcacerts,\n+ cert_reqs=ssl.CERT_REQUIRED\n+ )\n+ else:\n+ self.smtp.sock = ssl.wrap_socket(\n+ self.smtp.sock,\n+ cert_reqs=ssl.CERT_NONE\n+ )\n+ sys.stderr.write(\n+ '*** Warning, the server certificat is not verified (smtp) ***\\n'\n+ '*** set the option smtpCACerts ***\\n'\n+ )\n+ if not hasattr(self.smtp.sock, \"read\"):\n+ # using httplib.FakeSocket with Python 2.5.x or earlier\n+ self.smtp.sock.read = self.smtp.sock.recv\n+ self.smtp.file = smtplib.SSLFakeFile(self.smtp.sock)\n+ self.smtp.helo_resp = None\n+ self.smtp.ehlo_resp = None\n+ self.smtp.esmtp_features = {}\n+ self.smtp.does_esmtp = 0\n+ # end: ehlo + starttls\n self.smtp.ehlo()\n else:\n sys.stdout.write('*** Error: Control reached an invalid option. ***')\n@@ -1951,6 +2095,7 @@ class SMTPMailer(Mailer):\n def __del__(self):\n if hasattr(self, 'smtp'):\n self.smtp.quit()\n+ del self.smtp\n \n def send(self, lines, to_addrs):\n try:\n@@ -1958,13 +2103,24 @@ class SMTPMailer(Mailer):\n self.smtp.login(self.username, self.password)\n msg = ''.join(lines)\n # turn comma-separated list into Python list if needed.\n- if isinstance(to_addrs, basestring):\n+ if is_string(to_addrs):\n to_addrs = [email for (name, email) in getaddresses([to_addrs])]\n self.smtp.sendmail(self.envelopesender, to_addrs, msg)\n- except Exception:\n+ except smtplib.SMTPResponseException:\n sys.stderr.write('*** Error sending email ***\\n')\n- sys.stderr.write('*** %s\\n' % sys.exc_info()[1])\n- self.smtp.quit()\n+ err = sys.exc_info()[1]\n+ sys.stderr.write('*** Error %d: %s\\n' % (err.smtp_code,\n+ bytes_to_str(err.smtp_error)))\n+ try:\n+ smtp = self.smtp\n+ # delete the field before quit() so that in case of\n+ # error, self.smtp is deleted anyway.\n+ del self.smtp\n+ smtp.quit()\n+ except:\n+ sys.stderr.write('*** Error closing the SMTP connection ***\\n')\n+ sys.stderr.write('*** Exiting anyway ... ***\\n')\n+ sys.stderr.write('*** %s\\n' % sys.exc_info()[1])\n sys.exit(1)\n \n \n@@ -2097,6 +2253,14 @@ class Environment(object):\n If \"html\", generate commit emails in HTML instead of plain text\n used by default.\n \n+ html_in_intro (bool)\n+ html_in_footer (bool)\n+\n+ When generating HTML emails, the introduction (respectively,\n+ the footer) will be HTML-escaped iff html_in_intro (respectively,\n+ the footer) is true. When false, only the values used to expand\n+ the template are escaped.\n+\n refchange_showgraph (bool)\n \n True iff refchanges emails should include a detailed graph.\n@@ -2160,6 +2324,9 @@ class Environment(object):\n self.osenv = osenv or os.environ\n self.announce_show_shortlog = False\n self.commit_email_format = \"text\"\n+ self.html_in_intro = False\n+ self.html_in_footer = False\n+ self.commitBrowseURL = None\n self.maxcommitemails = 500\n self.diffopts = ['--stat', '--summary', '--find-copies-harder']\n self.graphopts = ['--oneline', '--decorate']\n@@ -2236,7 +2403,7 @@ class Environment(object):\n The return value is always a new dictionary.\"\"\"\n \n if self._values is None:\n- values = {}\n+ values = {'': ''} # %()s expands to the empty string.\n \n for key in self.COMPUTED_KEYS:\n value = getattr(self, 'get_%s' % (key,))()\n@@ -2375,6 +2542,16 @@ class ConfigOptionsEnvironmentMixin(ConfigEnvironmentMixin):\n else:\n self.commit_email_format = commit_email_format\n \n+ html_in_intro = config.get_bool('htmlInIntro')\n+ if html_in_intro is not None:\n+ self.html_in_intro = html_in_intro\n+\n+ html_in_footer = config.get_bool('htmlInFooter')\n+ if html_in_footer is not None:\n+ self.html_in_footer = html_in_footer\n+\n+ self.commitBrowseURL = config.get('commitBrowseURL')\n+\n maxcommitemails = config.get('maxcommitemails')\n if maxcommitemails is not None:\n try:\n@@ -2415,7 +2592,6 @@ class ConfigOptionsEnvironmentMixin(ConfigEnvironmentMixin):\n ['author'])\n self.__reply_to_commit = config.get('replyToCommit', default=reply_to)\n \n- from_addr = self.config.get('from')\n self.from_refchange = config.get('fromRefchange')\n self.forbid_field_values('fromRefchange',\n self.from_refchange,\n@@ -3390,6 +3566,8 @@ def run_as_post_receive_hook(environment, mailer):\n if changes:\n push = Push(environment, changes)\n push.send_emails(mailer, body_filter=environment.filter_body)\n+ if hasattr(mailer, '__del__'):\n+ mailer.__del__()\n \n \n def run_as_update_hook(environment, mailer, refname, oldrev, newrev, force_send=False):\n@@ -3406,6 +3584,8 @@ def run_as_update_hook(environment, mailer, refname, oldrev, newrev, force_send=\n ]\n push = Push(environment, changes, force_send)\n push.send_emails(mailer, body_filter=environment.filter_body)\n+ if hasattr(mailer, '__del__'):\n+ mailer.__del__()\n \n \n def choose_mailer(config, environment):\n@@ -3418,6 +3598,7 @@ def choose_mailer(config, environment):\n smtpencryption = config.get('smtpencryption', default='none')\n smtpuser = config.get('smtpuser', default='')\n smtppass = config.get('smtppass', default='')\n+ smtpcacerts = config.get('smtpcacerts', default='')\n mailer = SMTPMailer(\n envelopesender=(environment.get_sender() or environment.get_fromaddr()),\n smtpserver=smtpserver, smtpservertimeout=smtpservertimeout,\n@@ -3425,6 +3606,7 @@ def choose_mailer(config, environment):\n smtpencryption=smtpencryption,\n smtpuser=smtpuser,\n smtppass=smtppass,\n+ smtpcacerts=smtpcacerts\n )\n elif mailer == 'sendmail':\n command = config.get('sendmailcommand')\n@@ -3691,17 +3873,7 @@ def main(args):\n return\n \n if options.c:\n- parameters = os.environ.get('GIT_CONFIG_PARAMETERS', '')\n- if parameters:\n- parameters += ' '\n- # git expects GIT_CONFIG_PARAMETERS to be of the form\n- # \"'name1=value1' 'name2=value2' 'name3=value3'\"\n- # including everything inside the double quotes (but not the double\n- # quotes themselves). Spacing is critical. Also, if a value contains\n- # a literal single quote that quote must be represented using the\n- # four character sequence: '\\''\n- parameters += ' '.join(\"'\" + x.replace(\"'\", \"'\\\\''\") + \"'\" for x in options.c)\n- os.environ['GIT_CONFIG_PARAMETERS'] = parameters\n+ Config.add_config_parameters(options.c)\n \n config = Config('multimailhook')\n \ndiff --git a/contrib/hooks/multimail/post-receive.example b/contrib/hooks/multimail/post-receive.example\nindex 9975df7..1ea113d 100755\n--- a/contrib/hooks/multimail/post-receive.example\n+++ b/contrib/hooks/multimail/post-receive.example\n@@ -55,6 +55,12 @@ import git_multimail\n # git-multimail:\n config = git_multimail.Config('multimailhook')\n \n+# Set some Git configuration variables. Equivalent to passing var=val\n+# to \"git -c var=val\" each time git is called, or to adding the\n+# configuration in .git/config (must come before instanciating the\n+# environment) :\n+#git_multimail.Config.add_config_parameters('multimailhook.commitEmailFormat=html')\n+#git_multimail.Config.add_config_parameters(('user.name=foo', 'user.email=foo@example.com'))\n \n # Select the type of environment:\n try:\n-- \n2.8.1.339.g3ad15fd\n"}]}