git-multimail 1.6.0

要求

• Python 2.x，版本2.4或更高版本。不需要任何非标准Python模块。git-multimail对Python 3有初步支持（但已在Python 2上进行了更好的测试）。

• 必须将git命令放在您的PATH中。git-multimail已知与回退到1.7.1版本的Git版本一起工作。（未测试早期版本；如果您这样做，请报告您的结果。）

• 要使用默认配置发送电子邮件，必须在‘/usr/sbin/sendmail’或‘/usr/lib/sendmail’中找到标准sendmail程序，并且必须配置正确以发送电子邮件。如果不是这种情况，设置multimailhook.sendmailCommand，或参阅下文的多mailhook.mailer配置变量，了解如何配置git-multimail通过SMTP服务器发送电子邮件。

• git-multimail目前仅在Linux上进行了测试。它可能在Windows和Mac OS等其他平台上运行或不运行。请参阅https://github.com/git-multimail/git-multimail/blob/master/CONTRIBUTING.rst以改善这种情况。

调用

git_multimail.py设计为用作Git仓库中的post-receive钩子（请参阅githooks(5)）。将其链接或复制到项目仓库中希望接收电子邮件通知的$GIT_DIR/hooks/post-receive。通常，它应该安装在项目的中心仓库中，所有提交最终都会推送到那里。

对于在v1.5.1之前的Git服务器上的使用，git_multimail.py也可以作为update钩子工作，其参数来自命令行。要以这种方式使用此脚本，请将其链接或复制到$GIT_DIR/hooks/update。请注意，在此模式下，脚本并不完全可靠[1]。

或者，可以将 git_multimail.py 导入到您的 Python post-receive 脚本中作为 Python 模块。这种方法需要做更多的工作，但允许使用任意 Python 代码来自定义钩子的行为。例如，您可以使用自定义环境（可能继承自 GenericEnvironment 或 GitoliteEnvironment）来

• 改变确定推送用户的方式

• 从 LDAP 服务器或数据库中读取用户的电子邮件地址

• 根据提交的内容决定哪些用户应该收到哪些提交的通知（例如，对于只想接收影响特定文件或子目录更改的用户）

或者，您可以编写自己的 Mailer 类来改变发送邮件的方式。该目录中的 post-receive 脚本演示了如何将 git_multimail.py 作为 Python 模块使用。（如果您对此类更改很感兴趣，请考虑与社区分享。）

故障排除/常见问题解答

请阅读 https://github.com/git-multimail/git-multimail/blob/master/doc/troubleshooting.rst 了解关于 git-multimail 的常见问题和常见问题。

配置

默认情况下，git-multimail 主要从以下 git config 设置获取其配置

multimailhook.environment

这描述了仓库的一般环境。在大多数情况下，您不需要为此变量指定值：git-multimail 将自动检测要使用哪个环境。目前支持以下值

generic

推送者的用户名从 $USER 或 $USERNAME 读取，而仓库名称从仓库路径派生。

gitolite

当 git-multimail 作为 gitolite 钩子运行时使用的环境。

推送者的用户名从 $GL_USER 读取，仓库名称从 $GL_REPO 读取，From: 标头值可从 gitolite.conf 读取（见 multimailhook.from）。

有关 gitolite 和 git-multimail 的更多信息，请阅读 https://github.com/git-multimail/git-multimail/blob/master/doc/gitolite.rst

stash

当 git-multimail 作为 Atlassian BitBucket Server（以前称为 Atlassian Stash）钩子运行时使用的环境。

警告：此模式由第三方贡献者提供，git-multimail 维护者从未测试过。它按原样提供，可能或可能不会为您工作。

当在命令行上指定了特定于 stash 的标志（--stash-user 和 --stash-repo）时，假定此值。当此环境激活时，用户名和仓库来自这两个命令行标志，必须指定。

gerrit

当 git-multimail 作为 ref-updated Gerrit 钩子运行时使用的环境。

当存在 gerrit 的 ref-updated 钩子特定命令行标志（--oldrev，--newrev，--refname，--project）时，使用此值。当此环境激活时，如果传递了该命令行选项，则从 --submitter 参数获取推送者的用户名，否则使用“Gerrit”。从命令行上的 --project 选项获取仓库名称，必须传递。

有关 gerrit 和 git-multimail 的更多信息，请阅读 https://github.com/git-multimail/git-multimail/blob/master/doc/gerrit.rst

如果这些环境中的任何一个都不适合您的配置，那么您可以通过类似于示例 post-receive 脚本来实现一个从 Environment 继承的 Python 类并实例化它。

可以使用 --environment 选项在命令行中指定环境值。如果未在命令行或 multimailhook.environment 中指定，则按以下方式猜测值

• 如果命令行中存在特定的 (分别对应 gerrit 特定的) 命令标志，则使用 stash (分别对应 gerrit)。

• 如果设置了环境变量 $GL_USER 和 $GL_REPO，则使用 gitolite。

• 如果上述所有情况都不适用，则使用 generic。

multimailhook.repoName

该 Git 仓库的简称，将在通知电子邮件文本的多个位置使用。默认情况下，对于 gitolite 仓库使用 $GL_REPO，否则从仓库路径名推导此值。

multimailhook.mailingList

应将通知电子邮件发送到的电子邮件地址列表，作为用逗号分隔的 RFC 2822 电子邮件地址。此配置选项可以是多值的。留空或不设置为空字符串以默认不发送电子邮件。接下来的一些设置可以用来配置特定类型的通知电子邮件的特定地址列表。

multimailhook.refchangeList

应将关于引用更改的摘要电子邮件发送到的电子邮件地址列表，作为用逗号分隔的 RFC 2822 电子邮件地址。此配置选项可以是多值的。默认值为 multimailhook.mailingList 中的值。将此值设置为“none”（或空字符串）以防止即使设置了 multimailhook.mailingList 也发送引用更改电子邮件。

multimailhook.announceList

应将关于新注解标签的电子邮件发送到的电子邮件地址列表，作为用逗号分隔的 RFC 2822 电子邮件地址。此配置选项可以是多值的。默认值为 multimailhook.refchangeList 或 multimailhook.mailingList。将此值设置为“none”（或空字符串）以防止即使设置了其他值也不发送注解标签公告电子邮件。

multimailhook.commitList

应将关于单个新提交的电子邮件发送到的电子邮件地址列表，作为用逗号分隔的 RFC 2822 电子邮件地址。此配置选项可以是多值的。默认值为 multimailhook.mailingList。将此值设置为“none”（或空字符串）以防止即使设置了 multimailhook.mailingList 也发送单个提交的通知电子邮件。

multimailhook.announceShortlog

如果此选项设置为 true，则关于注解标签更改的电子邮件将包括自上次标签以来的更改简短日志。如果注解标签代表发布，则简短日志将是自上次发布以来发生事件的大致总结。但如果您的打标签策略不是如此直接，则简短日志可能会让人困惑而不是有用。默认为 false。

multimailhook.commitEmailFormat

单个提交的电子邮件消息的格式，可以是“text”或“html”。在后一种情况下，电子邮件将包括使用彩色 HTML 而不是默认的纯文本的 diff。注意，当前引用更改的电子邮件始终以纯文本发送。

注意，当使用“html”时，格式化是通过解析 git log 的输出并使用 -p 来完成的。当使用 multimailhook.commitLogOpts 来指定 git log 的 --format 时，可能会得到假阳性（例如，消息体中以 +++ 或 --- 开头的行以红色或绿色着色）。

默认情况下，所有消息都将进行 HTML 转义。有关更改此行为的信息，请参阅 multimailhook.htmlInIntro。

multimailhook.commitBrowseURL

用于在提交邮件中生成指向在线代码库浏览器的链接。此变量必须为字符串。格式指令（如 %(<variable>)s）的展开方式与模板字符串相同。特别是，%(id)s 将被替换为完整的 Git 提交标识符（40 位十六进制）。

如果字符串不包含任何格式指令，则将自动添加 %(id)s。如果您不希望自动添加 %(id)s，则请在字符串中的任何位置使用空格式指令 %()s。

例如，git-multimail 项目本身的合适值可能是 https://github.com/git-multimail/git-multimail/commit/%(id)s。

multimailhook.htmlInIntro, multimailhook.htmlInFooter

在生成 HTML 消息时，git-multimail 默认会转义任何 HTML 序列。这意味着如果模板包含如 <a href="foo">link</a> 的 HTML，读者将看到 HTML 源代码而不是正确的链接。

将 multimailhook.htmlInIntro 设置为 true，允许在介绍模板中编写 HTML 格式。类似地，将 multimailhook.htmlInFooter 用于页脚中的 HTML。

在模板中展开的变量仍然会被转义。例如，如果代码库的路径包含 <，则在消息中将以这种方式渲染。

有关更多详细信息和方法，请参阅 https://github.com/git-multimail/git-multimail/blob/master/doc/customizing-emails.rst。

multimailhook.refchangeShowGraph

如果此选项设置为 true，则关于引用更改的摘要邮件将包含额外的

• 添加的提交（如果有）的图表

• 丢弃的提交（如果有）的图表

日志是通过运行 git log --graph 并指定在 graphOpts 中的选项生成的。默认为 false。

multimailhook.refchangeShowLog

如果此选项设置为 true，则关于引用更改的摘要邮件将包括除一行摘要外的详细日志。日志是通过运行 git log 并指定在 multimailhook.logOpts 中的选项生成的。默认为 false。

multimailhook.mailer

此选项更改发送邮件的方式。接受的值是

• sendmail（默认）：使用命令 /usr/sbin/sendmail 或 /usr/lib/sendmail（如果已配置，则为 sendmailCommand）。此模式可以通过以下选项进一步自定义

  multimailhook.sendmailCommand

  邮件发送器 sendmail 用于发送电子邮件的命令。允许在设置的值中使用 shell 引用，但请记住，Git 需要转义双引号；例如

  git config multimailhook.sendmailcommand '/usr/sbin/sendmail -oi -t -F \"Git Repo\"'

  默认为 ‘/usr/sbin/sendmail -oi -t’ 或 ‘/usr/lib/sendmail -oi -t’（取决于哪个文件存在且可执行）。

  multimailhook.envelopeSender

  如果设置，则通过 sendmail 的 -f 选项传递此值来设置信封发件人地址。

• smtp：使用 Python 的 smtplib。当系统上没有 sendmail 命令时，这很有用。此模式可以通过以下选项进一步自定义

  multimailhook.smtpServer

  要连接的 SMTP 服务器的名称。值也可以包括冒号和端口号；例如，mail.example.com:25。默认为使用端口 25 的 ‘localhost’。

  multimailhook.smtpUser, multimailhook.smtpPass

  服务器用户名和密码。如果 smtpEncryption 为 ‘ssl’，则必须设置。请注意，当前需要在配置文件中明文设置用户名和密码，这不被推荐。如果您需要使用此选项，请确保您的配置文件是只读的。

  multimailhook.envelopeSender

  要传递给SMTP服务器的发送地址。如果没有设置，则使用multimailhook.from的值。

  multimailhook.smtpServerTimeout

  秒数超时。默认为10。

  multimailhook.smtpEncryption

  设置安全类型。允许的值：none（无），ssl，tls（starttls）。默认为none。

  multimailhook.smtpCACerts

  设置用于验证服务器证书的受信任CA证书列表的路径，仅在smtpEncryption为tls时受支持。如果没有设置或为空，则不验证服务器证书。如果它指向包含受信任CA证书列表（PEM格式）的文件，则这些CA将用于验证服务器证书。对于debian，您可以设置/etc/ssl/certs/ca-certificates.crt以使用系统受信任CA。对于自签名服务器，您可以将其服务器证书添加到系统存储中

  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

  并使用更新的/etc/ssl/certs/ca-certificates.crt。或者直接使用您的/path/to/mail.example.net.crt。默认为未设置。

  multimailhook.smtpServerDebugLevel

  整数。设置为大于0以启用调试。

multimailhook.from, multimailhook.fromCommit, multimailhook.fromRefchange

如果设置，则在生成的邮件的From:字段中使用此值。fromCommit用于提交邮件，fromRefchange用于refchange邮件，from在所有情况下都用作后备。

这些变量的值可以是以下之一

• 一个电子邮件地址，将直接使用。

• 值pusher，在这种情况下，如果可用，将使用pusher的地址。

• 值author（仅对fromCommit有意义），在这种情况下，将使用提交作者的地址。

如果配置值未设置，则From:头部的值按以下方式确定

1. （仅限gitolite环境）1.a) 如果multimailhook.MailaddressMap已设置，并且是现有文件的路径（如果是相对路径，则假定相对于gitolite.conf的位置），则该文件应包含类似以下内容的行

   username Firstname Lastname <email@example.com>

   git-multimail将查找其中$GL_USER与username部分匹配的行，并使用该行其余部分作为From:头部的值。

   1.b) 解析gitolite.conf，查找看起来像这样的注释块

   # BEGIN USER EMAILS
   # username Firstname Lastname <email@example.com>
   # END USER EMAILS

   如果该块存在，并且存在在BEGIN USER EMAILS和END USER EMAILS行之间的行，其中第一字段与gitolite用户名（$GL_USER）匹配，则使用该行其余部分作为From:头部的值。

2. 如果设置了user.email配置设置，则使用其值（以及如果设置的用户名）。

3. 使用multimailhook.envelopeSender的值。

multimailhook.MailaddressMap

（仅限gitolite环境）查找基于执行推送的用户的From:地址的文件。默认为未设置。有关详细信息，请参阅multimailhook.from。

multimailhook.administrator

Git存储库管理员的名称和/或电子邮件地址；用于FOOTER_TEMPLATE。默认为如果已设置multimailhook.envelopesender，则为multimailhook.envelopesender；否则使用通用字符串。

multimailhook.emailPrefix

所有电子邮件的标题都添加了这个字符串，以帮助过滤电子邮件（尽管基于X-Git-*电子邮件头部的过滤可能更稳健）。默认值为方括号中的存储库短名；例如，[myrepo]。将此值设置为空字符串以取消电子邮件前缀。您可以使用占位符%(repo_shortname)s来指定存储库的短名。

multimailhook.emailMaxLines

应包含在生成的电子邮件正文中行数的最大值。如果未指定，则没有限制。超出限制的行将被抑制并计数，并在最后添加一行，指示抑制的行数。

multimailhook.emailMaxLineLength

电子邮件正文中行的最大长度。超过此限制的行将被截断到这个长度，并在末尾添加[...]以指示缺失的文本。默认值是500，因为（a）较长的行可能是二进制文件的diff，对于这种diff是无用的，并且（b）即使文本文件有如此长的行，diff也可能难以阅读。要禁用行截断，将此选项设置为0。

multimailhook.subjectMaxLength

主题行（即在模板中的oneline字段，不包括前缀）的最大长度。超过此限制的行将被截断到这个长度，并在末尾添加[...]以指示缺失的文本。此选项默认使用multimailhook.emailMaxLineLength。此选项可以避免发送过长的主题行电子邮件，但如果提交消息遵循Git约定（一个简短的主题行，然后一个空行，然后是消息正文），则不应需要此选项。要禁用行截断，将此选项设置为0。

multimailhook.maxCommitEmails

对于给定更改发送的提交电子邮件的最大数量。当补丁数量超过此值时，仅发送摘要refchange电子邮件。这可以避免意外邮件炸弹，例如在初始推送时。要禁用提交电子邮件限制，将此选项设置为0。默认值是500。

multimailhook.excludeMergeRevisions

在发送修订电子邮件时，不考虑合并提交（与rev-list –no-merges的功能等效）。默认为false（发送合并提交电子邮件）。

multimailhook.emailStrictUTF8

如果此布尔选项设置为true，则电子邮件正文的主体部分将强制为有效的UTF-8。任何不是有效UTF-8的字符都将转换为Unicode替换字符，U+FFFD。默认值是true。

此选项在Python 3中无效，其中非UTF-8字符无条件地替换。

multimailhook.diffOpts

传递给git diff-tree以生成参考变更电子邮件摘要信息的选项。默认值为--stat --summary --find-copies-harder。将这些选项添加到-p，以包括更改的统一diff以及通常的摘要输出。允许shell引号；有关详细信息，请参阅multimailhook.logOpts。

multimailhook.graphOpts

传递给git log --graph以生成参考变更摘要电子邮件的图的选项（仅当refchangeShowGraph为true时使用）。默认值为‘–oneline –decorate’。

允许shell引号；有关详细信息，请参阅logOpts。

multimailhook.logOpts

传递给git log以生成参考变更电子邮件的附加信息的选项（仅当refchangeShowLog设置为true时使用）。例如，添加-p将显示每个提交的完整diff。默认为空。

允许使用Shell引号；例如，可以使用类似的方法指定包含空格的日志格式：

git config multimailhook.logopts '--pretty=format:"%h %aN <%aE>%n%s%n%n%b%n"'

如果您想通过直接编辑配置文件来设置它，请记住Git要求转义双引号（有关更多信息，请参阅git-config(1)）

[multimailhook]
        logopts = --pretty=format:\"%h %aN <%aE>%n%s%n%n%b%n\"

multimailhook.commitLogOpts

传递给 git log 的选项，用于为修订变化邮件生成附加信息。例如，添加 –ignore-all-spaces 将抑制空白更改。默认选项是 -C --stat -p --cc。允许使用Shell引号；有关详细信息，请参阅multimailhook.logOpts。

multimailhook.dateSubstitute

用于在格式化提交消息时替换 Date: 的字符串。这在避免发出可能被邮件程序解释为引用消息开始的行（尤其是Zimbra网络邮件）时很有用。默认为 CommitDate:。设置为空字符串或 none 以禁用此行为。

multimailhook.emailDomain

将附加到执行推送的人的用户名上以将其转换为电子邮件地址的域名（通过 "%s@%s" % (username, emaildomain)）。可以通过覆盖环境和其get_pusher_email()方法实现更复杂的方案。

multimailhook.replyTo, multimailhook.replyToCommit, multimailhook.replyToRefchange

用于提交邮件（replyToCommit）和refchange邮件（replyToRefchange）的Reply-To:字段的地址。当replyToCommit或replyToRefchange未设置时，使用multimailhook.replyTo作为默认值。允许使用与multimailhook.from相同的语义的快捷键 pusher 和 author。此外，可以使用值 none 来省略Reply-To:字段。

默认情况下，refchange邮件使用 pusher，提交邮件使用 author。

multimailhook.quiet

不要从钩子输出电子邮件收件人列表

multimailhook.stdout

用于调试，将电子邮件发送到stdout而不是发送到邮件程序。等同于 –stdout 命令行选项

multimailhook.scanCommitForCc

如果此选项设置为true，则将来自提交主体中以CC:开头的行的收件人添加到CC列表。默认：false

multimailhook.combineWhenSingleCommit

如果此选项设置为true，并且将单个新提交推送到分支，则将摘要和提交邮件消息合并为单个邮件。默认：true

multimailhook.refFilterInclusionRegex, multimailhook.refFilterExclusionRegex, multimailhook.refFilterDoSendRegex, multimailhook.refFilterDontSendRegex

警告：这些选项是实验性的。它们应该可以正常工作，但用户界面尚不稳定（特别是，选项名称可能会更改）。如果您想参与稳定该功能，请联系维护者并发送pull请求。如果您对当前的功能形状感到满意，也请报告。

可以用于限制将发送电子邮件更新的引用的正则表达式。指定包含和排除正则表达式是错误的。如果指定了 refFilterInclusionRegex，则只有匹配此正则表达式的引用才会发送电子邮件。如果指定了 refFilterExclusionRegex 正则表达式，则除了匹配此正则表达式（或匹配环境特定的预定义正则表达式，例如“^refs/notes”对于大多数环境，“^refs/notes|^refs/changes”对于gerrit环境）的引用之外的所有引用都会发送电子邮件。

表达式与完整的refname进行匹配，如果任何子串匹配则认为是匹配。例如，要过滤掉所有标签，将refFilterExclusionRegex设置为^refs/tags/（注意开头的^，但没有结尾的$）。如果您将refFilterExclusionRegex设置为master，则包含master的任何引用都将被排除（包括master分支、refs/tags/master或refs/heads/foo-master-bar）。

refFilterDoSendRegex和refFilterDontSendRegex与refFilterInclusionRegex和refFilterExclusionRegex类似，只有一个区别：在使用refFilterDoSendRegex和refFilterDontSendRegex时，被排除的引用引入的提交在达到包含的引用时不会被视为新提交。通常，如果您将分支foo添加到refFilterDontSendRegex，然后向该分支推送提交，稍后将分支foo合并到master，则master的通知电子邮件将只包含合并提交的电子邮件。如果您将foo包含在refFilterExclusionRegex中，则在合并时，您将按每个分支中的每个提交接收一个提交电子邮件。

这些变量可以具有多个值，例如

[multimailhook]
        refFilterExclusionRegex = ^refs/tags/
        refFilterExclusionRegex = ^refs/heads/master$

您也可以提供一个空格分隔的列表，例如

[multimailhook]
        refFilterExclusionRegex = ^refs/tags/ ^refs/heads/master$

这两个示例都排除了标签和master分支，并且与refFilterInclusionRegex和refFilterExclusionRegex等价

[multimailhook]
        refFilterExclusionRegex = ^refs/tags/|^refs/heads/master$

refFilterInclusionRegex和refFilterExclusionRegex的约束性比refFilterDoSendRegex和refFilterDontSendRegex更强。换句话说，如果一个引用已经被排除/包含正则表达式排除，则将其添加到DoSend/DontSend正则表达式中没有效果。

multimailhook.logFile, multimailhook.errorLogFile, multimailhook.debugLogFile

当设置时，这些变量指定了git-multimail将记录消息的文件路径。常规消息和错误消息发送到logFile，错误消息也发送到errorLogFile。调试消息和所有其他消息发送到debugLogFile。建议只设置其中一个变量，但也可以设置多个变量（部分信息将在多个日志文件中重复，例如错误将被复制到所有日志文件中）。

相对路径相对于执行推送的Git仓库。

multimailhook.verbose

git-multimail在其标准输出上的详细程度。默认情况下，只显示错误和信息消息。如果设置为true，则还显示调试消息。

电子邮件过滤辅助工具

所有电子邮件都包含额外的头信息，以启用精细的过滤并提供调试信息。所有电子邮件都包含头信息X-Git-Host、X-Git-Repo、X-Git-Refname和X-Git-Reftype。ReferenceChange电子邮件还包括头信息X-Git-Oldrev和X-Git-Newrev；Revision电子邮件还包括头信息X-Git-Rev。

自定义电子邮件内容

git-multimail主要通过扩展模板来生成电子邮件。模板可以自定义。为了避免直接编辑git_multimail.py，首选的修改模板的方式是编写一个单独的Python脚本，将git_multimail.py作为模块导入，然后替换模板。请参考提供的post-receive脚本了解如何操作。

为您的环境定制git-multimail

git-multimail主要通过“环境”来定制，该环境描述了Git运行的本地环境。内置了两种环境类型

GenericEnvironment

一个独立的Git仓库。

GitoliteEnvironment

由gitolite管理的Git仓库。对于此类仓库，推送者的身份从环境变量$GL_USER中读取，仓库的名称从$GL_REPO中读取（如果未由multimailhook.reponame覆盖），并且可以可选地从gitolite.conf中读取From:头部的值（参见multimailhook.from）。

默认情况下，如果设置了$GL_USER和$GL_REPO，git-multimail假定是GitoliteEnvironment，否则假定是GenericEnvironment。或者，您可以通过设置multimailhook.environment配置设置（其值可以是generic或gitolite）或将–environment选项传递给脚本，显式地选择这两个环境之一。

如果您需要以现有环境不支持的方式定制脚本，可以使用任意Python代码定义自己的环境类。为此，您需要将git_multimail.py作为Python模块导入，如示例post-receive脚本所示。然后实现您的环境类；它通常应该继承自现有的Environment类之一，并可能继承一个或多个EnvironmentMixin类。然后设置environment变量为您自己的环境类的一个实例，并将其传递给run_as_post_receive_hook()。

标准环境类，GenericEnvironment和GitoliteEnvironment，实际上是由多个mixin类组合而成的，每个mixin类处理定制的一个方面。为了对您的配置有最精细的控制，您可以指定您的环境类应该继承哪些mixin类，并覆盖个别方法（甚至添加您自己的mixin类）来实现全新的行为。如果您实现了可能对其他人有用的任何mixins，请考虑与社区分享它们！

参与其中

请阅读https://github.com/git-multimail/git-multimail/blob/master/CONTRIBUTING.rst以获取如何为git-multimail做出贡献的说明。

脚注