@matheusbsbs / matheus-bagliano / commits / f74d11471f

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>

Johannes Schindelin committed Jun 10, 2021 at 08:29 UTC f74d11471fa8870d4bcbe7dbff2f3ddac6783e7f

12 files changed +2 -6302

contrib/hooks/multimail/CHANGES deleted

-285

@@ -1,285 +0,0 @@

1 -Release 1.5.0

2 -=============

3 -

4 -Backward-incompatible change

5 -----------------------------

6 -

7 -The name of classes for environment was misnamed as `*Environement`.

8 -It is now `*Environment`.

9 -

10 -New features

11 -------------

12 -

13 -* A Thread-Index header is now added to each email sent (except for

14 - combined emails where it would not make sense), so that MS Outlook

15 - properly groups messages by threads even though they have a

16 - different subject line. Unfortunately, even adding this header the

17 - threading still seems to be unreliable, but it is unclear whether

18 - this is an issue on our side or on MS Outlook's side (see discussion

19 - here: https://github.com/git-multimail/git-multimail/pull/194).

20 -

21 -* A new variable multimailhook.ExcludeMergeRevisions was added to send

22 - notification emails only for non-merge commits.

23 -

24 -* For gitolite environment, it is now possible to specify the mail map

25 - in a separate file in addition to gitolite.conf, using the variable

26 - multimailhook.MailaddressMap.

27 -

28 -Internal changes

29 -----------------

30 -

31 -* The testsuite now uses GIT_PRINT_SHA1_ELLIPSIS where needed for

32 - compatibility with recent Git versions. Only tests are affected.

33 -

34 -* We don't try to install pyflakes in the continuous integration job

35 - for old Python versions where it's no longer available.

36 -

37 -* Stop using the deprecated cgi.escape in Python 3.

38 -

39 -* New flake8 warnings have been fixed.

40 -

41 -* Python 3.6 is now tested against on Travis-CI.

42 -

43 -* A bunch of lgtm.com warnings have been fixed.

44 -

45 -Bug fixes

46 ----------

47 -

48 -* SMTPMailer logs in only once now. It used to re-login for each email

49 - sent which triggered errors for some SMTP servers.

50 -

51 -* migrate-mailhook-config was broken by internal refactoring, it

52 - should now work again.

53 -

54 -This version was tested with Python 2.6 to 3.7. It was tested with Git

55 -1.7.10.406.gdc801, 2.15.1 and 2.20.1.98.gecbdaf0.

56 -

57 -Release 1.4.0

58 -=============

59 -

60 -New features to troubleshoot a git-multimail installation

61 ----------------------------------------------------------

62 -

63 -* One can now perform a basic check of git-multimail's setup by

64 - running the hook with the environment variable

65 - GIT_MULTIMAIL_CHECK_SETUP set to a non-empty string. See

66 - doc/troubleshooting.rst for details.

67 -

68 -* A new log files system was added. See the multimailhook.logFile,

69 - multimailhook.errorLogFile and multimailhook.debugLogFile variables.

70 -

71 -* git_multimail.py can now be made more verbose using

72 - multimailhook.verbose.

73 -

74 -* A new option --check-ref-filter is now available to help debugging

75 - the refFilter* options.

76 -

77 -Formatting emails

78 ------------------

79 -

80 -* Formatting of emails was made slightly more compact, to reduce the

81 - odds of having long subject lines truncated or wrapped in short list

82 - of commits.

83 -

84 -* multimailhook.emailPrefix may now use the '%(repo_shortname)s'

85 - placeholder for the repository's short name.

86 -

87 -* A new option multimailhook.subjectMaxLength is available to truncate

88 - overly long subject lines.

89 -

90 -Bug fixes and minor changes

91 ----------------------------

92 -

93 -* Options refFilterDoSendRegex and refFilterDontSendRegex were

94 - essentially broken. They should work now.

95 -

96 -* The behavior when both refFilter{Do,Dont}SendRegex and

97 - refFilter{Exclusion,Inclusion}Regex are set have been slightly

98 - changed. Exclusion/Inclusion is now strictly stronger than

99 - DoSend/DontSend.

100 -

101 -* The management of precedence when a setting can be computed in

102 - multiple ways has been considerably refactored and modified.

103 - multimailhook.from and multimailhook.reponame now have precedence

104 - over the environment-specific settings ($GL_REPO/$GL_USER for

105 - gitolite, --stash-user/repo for Stash, --submitter/--project for

106 - Gerrit).

107 -

108 -* The coverage of the testsuite has been considerably improved. All

109 - configuration variables now appear at least once in the testsuite.

110 -

111 -This version was tested with Python 2.6 to 3.5. It also mostly works

112 -with Python 2.4, but there is one known breakage in the testsuite

113 -related to non-ascii characters. It was tested with Git

114 -1.7.10.406.gdc801, 1.8.5.6, 2.1.4, and 2.10.0.rc0.1.g07c9292.

115 -

116 -Release 1.3.1 (bugfix-only release)

117 -===================================

118 -

119 -* Generate links to commits in combined emails (it was done only for

120 - commit emails in 1.3.0).

121 -

122 -* Fix broken links on PyPi.

123 -

124 -Release 1.3.0

125 -=============

126 -

127 -* New options multimailhook.htmlInIntro and multimailhook.htmlInFooter

128 - now allow using HTML in the introduction and footer of emails (e.g.

129 - for a more pleasant formatting or to insert a link to the commit on

130 - a web interface).

131 -

132 -* A new option multimailhook.commitBrowseURL gives a simpler (and less

133 - flexible) way to add a link to a web interface for commit emails

134 - than multimailhook.htmlInIntro and multimailhook.htmlInFooter.

135 -

136 -* A new public function config.add_config_parameters was added to

137 - allow custom hooks to set specific Git configuration variables

138 - without modifying the configuration files. See an example in

139 - post-receive.example.

140 -

141 -* Error handling for SMTP has been improved (we used to print Python

142 - backtraces for legitimate errors).

143 -

144 -* The SMTP mailer can now check TLS certificates when the newly added

145 - configuration variable multimailhook.smtpCACerts.

146 -

147 -* Python 3 portability has been improved.

148 -

149 -* The documentation's formatting has been improved.

150 -

151 -* The testsuite has been improved (we now use pyflakes to check for

152 - errors in the code).

153 -

154 -This version has been tested with Python 2.4 and 2.6 to 3.5, and Git

155 -v1.7.10-406-gdc801e7, 2.1.4 and 2.8.1.339.g3ad15fd.

156 -

157 -No change since 1.3 RC1.

158 -

159 -Release 1.2.0

160 -=============

161 -

162 -* It is now possible to exclude some refs (e.g. exclude some branches

163 - or tags). See refFilterDoSendRegex, refFilterDontSendRegex,

164 - refFilterInclusionRegex and refFilterExclusionRegex.

165 -

166 -* New commitEmailFormat option which can be set to "html" to generate

167 - simple colorized diffs using HTML for the commit emails.

168 -

169 -* git-multimail can now be ran as a Gerrit ref-updated hook, or from

170 - Atlassian BitBucket Server (formerly known as Atlassian Stash).

171 -

172 -* The From: field is now more customizeable. It can be set

173 - independently for refchange emails and commit emails (see

174 - fromCommit, fromRefChange). The special values pusher and author can

175 - be used in these configuration variable.

176 -

177 -* A new command-line option, --version, was added. The version is also

178 - available in the X-Git-Multimail-Version header of sent emails.

179 -

180 -* Set X-Git-NotificationType header to differentiate the various types

181 - of notifications. Current values are: diff, ref_changed_plus_diff,

182 - ref_changed.

183 -

184 -* Preliminary support for Python 3. The testsuite passes with Python 3,

185 - but it has not received as much testing as the Python 2 version yet.

186 -

187 -* Several encoding-related fixes. UTF-8 characters work in more

188 - situations (but non-ascii characters in email address are still not

189 - supported).

190 -

191 -* The testsuite and its documentation has been greatly improved.

192 -

193 -Plus all the bugfixes from version 1.1.1.

194 -

195 -This version has been tested with Python 2.4 and 2.6 to 3.5, and Git

196 -v1.7.10-406-gdc801e7, git-1.8.2.3 and 2.6.0. Git versions prior to

197 -v1.7.10-406-gdc801e7 probably work, but cannot run the testsuite

198 -properly.

199 -

200 -Release 1.1.1 (bugfix-only release)

201 -===================================

202 -

203 -* The SMTP mailer was not working with Python 2.4.

204 -

205 -Release 1.1.0

206 -=============

207 -

208 -* When a single commit is pushed, omit the reference changed email.

209 - Set multimailhook.combineWhenSingleCommit to false to disable this

210 - new feature.

211 -

212 -* In gitolite environments, the pusher's email address can be used as

213 - the From address by creating a specially formatted comment block in

214 - gitolite.conf (see multimailhook.from in README).

215 -

216 -* Support for SMTP authentication and SSL/TLS encryption was added,

217 - see smtpUser, smtpPass, smtpEncryption in README.

218 -

219 -* A new option scanCommitForCc was added to allow git-multimail to

220 - search the commit message for 'Cc: ...' lines, and add the

221 - corresponding emails in Cc.

222 -

223 -* If $USER is not set, use the variable $USERNAME. This is needed on

224 - Windows platform to recognize the pusher.

225 -

226 -* The emailPrefix variable can now be set to an empty string to remove

227 - the prefix.

228 -

229 -* A short tutorial was added in doc/gitolite.rst to set up

230 - git-multimail with gitolite.

231 -

232 -* The post-receive file was renamed to post-receive.example. It has

233 - always been an example (the standard way to call git-multimail is to

234 - call git_multimail.py), but it was unclear to many users.

235 -

236 -* A new refchangeShowGraph option was added to make it possible to

237 - include both a graph and a log in the summary emails. The options

238 - to control the graph formatting can be set via the new graphOpts

239 - option.

240 -

241 -* New option --force-send was added to disable new commit detection

242 - for update hook. One use-case is to run git_multimail.py after

243 - running "git fetch" to send emails about commits that have just been

244 - fetched (the detection of new commits was unreliable in this mode).

245 -

246 -* The testing infrastructure was considerably improved (continuous

247 - integration with travis-ci, automatic check of PEP8 and RST syntax,

248 - many improvements to the test scripts).

249 -

250 -This version has been tested with Python 2.4 to 2.7, and Git 1.7.1 to

251 -2.4.

252 -

253 -Release 1.0.0

254 -=============

255 -

256 -* Fix encoding of non-ASCII email addresses in email headers.

257 -

258 -* Fix backwards-compatibility bugs for older Python 2.x versions.

259 -

260 -* Fix a backwards-compatibility bug for Git 1.7.1.

261 -

262 -* Add an option commitDiffOpts to customize logs for revisions.

263 -

264 -* Pass "-oi" to sendmail by default to prevent premature termination

265 - on a line containing only ".".

266 -

267 -* Stagger email "Date:" values in an attempt to help mail clients

268 - thread the emails in the right order.

269 -

270 -* If a mailing list setting is missing, just skip sending the

271 - corresponding email (with a warning) instead of failing.

272 -

273 -* Add a X-Git-Host header that can be used for email filtering.

274 -

275 -* Allow the sender's fully-qualified domain name to be configured.

276 -

277 -* Minor documentation improvements.

278 -

279 -* Add this CHANGES file.

280 -

281 -

282 -Release 0.9.0

283 -=============

284 -

285 -* Initial release.

contrib/hooks/multimail/CONTRIBUTING.rst deleted

-60

@@ -1,60 +0,0 @@

1 -Contributing

2 -============

3 -

4 -git-multimail is an open-source project, built by volunteers. We would

5 -welcome your help!

6 -

7 -The current maintainers are `Matthieu Moy <http://matthieu-moy.fr>`__ and

8 -`Michael Haggerty <https://github.com/mhagger>`__.

9 -

10 -Please note that although a copy of git-multimail is distributed in

11 -the "contrib" section of the main Git project, development takes place

12 -in a separate `git-multimail repository on GitHub`_.

13 -

14 -Whenever enough changes to git-multimail have accumulated, a new

15 -code-drop of git-multimail will be submitted for inclusion in the Git

16 -project.

17 -

18 -We use the GitHub issue tracker to keep track of bugs and feature

19 -requests, and we use GitHub pull requests to exchange patches (though,

20 -if you prefer, you can send patches via the Git mailing list with CC

21 -to the maintainers). Please sign off your patches as per the `Git

22 -project practice

23 -<https://github.com/git/git/blob/master/Documentation/SubmittingPatches#L234>`__.

24 -

25 -Please vote for issues you would like to be addressed in priority

26 -(click "add your reaction" and then the "+1" thumbs-up button on the

27 -GitHub issue).

28 -

29 -General discussion of git-multimail can take place on the main `Git

30 -mailing list`_.

31 -

32 -Please CC emails regarding git-multimail to the maintainers so that we

33 -don't overlook them.

34 -

35 -Help needed: testers/maintainer for specific environments/OS

36 -------------------------------------------------------------

37 -

38 -The current maintainer uses and tests git-multimail on Linux with the

39 -Generic environment. More testers, or better contributors are needed

40 -to test git-multimail on other real-life setups:

41 -

42 -* Mac OS X, Windows: git-multimail is currently not supported on these

43 - platforms. But since we have no external dependencies and try to

44 - write code as portable as possible, it is possible that

45 - git-multimail already runs there and if not, it is likely that it

46 - could be ported easily.

47 -

48 - Patches to improve support for Windows and OS X are welcome.

49 - Ideally, there would be a sub-maintainer for each OS who would test

50 - at least once before each release (around twice a year).

51 -

52 -* Gerrit, Stash, Gitolite environments: although the testsuite

53 - contains tests for these environments, a tester/maintainer for each

54 - environment would be welcome to test and report failure (or success)

55 - on real-life environments periodically (here also, feedback before

56 - each release would be highly appreciated).

57 -

58 -

59 -.. _`git-multimail repository on GitHub`: https://github.com/git-multimail/git-multimail

60 -.. _`Git mailing list`: git@vger.kernel.org

contrib/hooks/multimail/README.Git

+2 -10

@@ -1,15 +1,7 @@

1 -This copy of git-multimail is distributed as part of the "contrib"

2 -section of the Git project as a convenience to Git users.

1 git-multimail is developed as an independent project at the following

2 website:

4 https://github.com/git-multimail/git-multimail

8 -The version in this directory was obtained from the upstream project

9 -on January 07 2019 and consists of the "git-multimail" subdirectory from

10 -revision

11 -

12 - 04e80e6c40be465cc62b6c246f0fcb8fd2cfd454 refs/tags/1.5.0

13 -

14 -Please see the README file in this directory for information about how

15 -to report bugs or contribute to git-multimail.

6 +Please refer to that project page for information about how to report

7 +bugs or contribute to git-multimail.

contrib/hooks/multimail/README.migrate-from-post-receive-email deleted

-145

@@ -1,145 +0,0 @@

1 -git-multimail is close to, but not exactly, a plug-in replacement for

2 -the old Git project script contrib/hooks/post-receive-email. This

3 -document describes the differences and explains how to configure

4 -git-multimail to get behavior closest to that of post-receive-email.

5 -

6 -If you are in a hurry

7 -=====================

8 -

9 -A script called migrate-mailhook-config is included with

10 -git-multimail. If you run this script within a Git repository that is

11 -configured to use post-receive-email, it will convert the

12 -configuration settings into the approximate equivalent settings for

13 -git-multimail. For more information, run

14 -

15 - migrate-mailhook-config --help

16 -

17 -

18 -Configuration differences

19 -=========================

20 -

21 -* The names of the config options for git-multimail are in namespace

22 - "multimailhook.*" instead of "hooks.*". (Editorial comment:

23 - post-receive-email should never have used such a generic top-level

24 - namespace.)

25 -

26 -* In emails about new annotated tags, post-receive-email includes a

27 - shortlog of all changes since the previous annotated tag. To get

28 - this behavior with git-multimail, you need to set

29 - multimailhook.announceshortlog to true:

30 -

31 - git config multimailhook.announceshortlog true

32 -

33 -* multimailhook.commitlist -- This is a new configuration variable.

34 - Recipients listed here will receive a separate email for each new

35 - commit. However, if this variable is *not* set, it defaults to the

36 - value of multimailhook.mailinglist. Therefore, if you *don't* want

37 - the members of multimailhook.mailinglist to receive one email per

38 - commit, then set this value to the empty string:

39 -

40 - git config multimailhook.commitlist ''

41 -

42 -* multimailhook.emailprefix -- If this value is not set, then the

43 - subjects of generated emails are prefixed with the short name of the

44 - repository enclosed in square brackets; e.g., "[myrepo]".

45 - post-receive-email defaults to prefix "[SCM]" if this option is not

46 - set. So if you were using the old default and want to retain it

47 - (for example, to avoid having to change your email filters), set

48 - this variable explicitly to the old value:

49 -

50 - git config multimailhook.emailprefix "[SCM]"

51 -

52 -* The "multimailhook.showrev" configuration option is not supported.

53 - Its main use is obsoleted by the one-email-per-commit feature of

54 - git-multimail.

55 -

56 -

57 -Other differences

58 -=================

59 -

60 -This section describes other differences in the behavior of

61 -git-multimail vs. post-receive-email. For full details, please refer

62 -to the main README file:

63 -

64 -* One email per commit. For each reference change, the script first

65 - outputs one email summarizing the reference change (including

66 - one-line summaries of the new commits), then it outputs a separate

67 - email for each new commit that was introduced, including patches.

68 - These one-email-per-commit emails go to the addresses listed in

69 - multimailhook.commitlist. post-receive-email sends only one email

70 - for each *reference* that is changed, no matter how many commits

71 - were added to the reference.

72 -

73 -* Better algorithm for detecting new commits. post-receive-email

74 - processes one reference change at a time, which causes it to fail to

75 - describe new commits that were included in multiple branches. For

76 - example, if a single push adds the "*" commits in the diagram below,

77 - then post-receive-email would never include the details of the two

78 - commits that are common to "master" and "branch" in its

79 - notifications.

80 -

81 - o---o---o---*---*---* <-- master

82 - \

83 - *---* <-- branch

84 -

85 - git-multimail analyzes all reference modifications to determine

86 - which commits were not present before the change, therefore avoiding

87 - that error.

88 -

89 -* In reference change emails, git-multimail tells which commits have

90 - been added to the reference vs. are entirely new to the repository,

91 - and which commits that have been omitted from the reference

92 - vs. entirely discarded from the repository.

93 -

94 -* The environment in which Git is running can be configured via an

95 - "Environment" abstraction.

96 -

97 -* Built-in support for Gitolite-managed repositories.

98 -

99 -* Instead of using full SHA1 object names in emails, git-multimail

100 - mostly uses abbreviated SHA1s, plus one-line log message summaries

101 - where appropriate.

102 -

103 -* In the schematic diagrams that explain non-fast-forward commits,

104 - git-multimail shows the names of the branches involved.

105 -

106 -* The emails generated by git-multimail include the name of the Git

107 - repository that was modified; this is convenient for recipients who

108 - are monitoring multiple repositories.

109 -

110 -* git-multimail allows the email "From" addresses to be configured.

111 -

112 -* The recipients lists (multimailhook.mailinglist,

113 - multimailhook.refchangelist, multimailhook.announcelist, and

114 - multimailhook.commitlist) can be comma-separated values and/or

115 - multivalued settings in the config file; e.g.,

116 -

117 - [multimailhook]

118 - mailinglist = mr.brown@example.com, mr.black@example.com

119 - announcelist = Him <him@example.com>

120 - announcelist = Jim <jim@example.com>

121 - announcelist = pop@example.com

122 -

123 - This might make it easier to maintain short recipients lists without

124 - requiring full-fledged mailing list software.

125 -

126 -* By default, git-multimail sets email "Reply-To" headers to reply to

127 - the pusher (for reference updates) and to the author (for commit

128 - notifications). By default, the pusher's email address is

129 - constructed by appending "multimailhook.emaildomain" to the pusher's

130 - username.

131 -

132 -* The generated emails contain a configurable footer. By default, it

133 - lists the name of the administrator who should be contacted to

134 - unsubscribe from notification emails.

135 -

136 -* New option multimailhook.emailmaxlinelength to limit the length of

137 - lines in the main part of the email body. The default limit is 500

138 - characters.

139 -

140 -* New option multimailhook.emailstrictutf8 to ensure that the main

141 - part of the email body is valid UTF-8. Invalid characters are

142 - turned into the Unicode replacement character, U+FFFD. By default

143 - this option is turned on.

144 -

145 -* Written in Python. Easier to add new features.

contrib/hooks/multimail/README.rst deleted

-774

@@ -1,774 +0,0 @@

1 -git-multimail version 1.5.0

2 -===========================

3 -

4 -.. image:: https://travis-ci.org/git-multimail/git-multimail.svg?branch=master

5 - :target: https://travis-ci.org/git-multimail/git-multimail

6 -

7 -git-multimail is a tool for sending notification emails on pushes to a

8 -Git repository. It includes a Python module called ``git_multimail.py``,

9 -which can either be used as a hook script directly or can be imported

10 -as a Python module into another script.

11 -

12 -git-multimail is derived from the Git project's old

13 -contrib/hooks/post-receive-email, and is mostly compatible with that

14 -script. See README.migrate-from-post-receive-email for details about

15 -the differences and for how to migrate from post-receive-email to

16 -git-multimail.

17 -

18 -git-multimail, like the rest of the Git project, is licensed under

19 -GPLv2 (see the COPYING file for details).

20 -

21 -Please note: although, as a convenience, git-multimail may be

22 -distributed along with the main Git project, development of

23 -git-multimail takes place in its own, separate project. Please, read

24 -`<CONTRIBUTING.rst>`__ for more information.

25 -

26 -

27 -By default, for each push received by the repository, git-multimail:

28 -

29 -1. Outputs one email summarizing each reference that was changed.

30 - These "reference change" (called "refchange" below) emails describe

31 - the nature of the change (e.g., was the reference created, deleted,

32 - fast-forwarded, etc.) and include a one-line summary of each commit

33 - that was added to the reference.

34 -

35 -2. Outputs one email for each new commit that was introduced by the

36 - reference change. These "commit" emails include a list of the

37 - files changed by the commit, followed by the diffs of files

38 - modified by the commit. The commit emails are threaded to the

39 - corresponding reference change email via "In-Reply-To". This style

40 - (similar to the "git format-patch" style used on the Git mailing

41 - list) makes it easy to scan through the emails, jump to patches

42 - that need further attention, and write comments about specific

43 - commits. Commits are handled in reverse topological order (i.e.,

44 - parents shown before children). For example::

45 -

46 - [git] branch master updated

47 - + [git] 01/08: doc: fix xref link from api docs to manual pages

48 - + [git] 02/08: api-credentials.txt: show the big picture first

49 - + [git] 03/08: api-credentials.txt: mention credential.helper explicitly

50 - + [git] 04/08: api-credentials.txt: add "see also" section

51 - + [git] 05/08: t3510 (cherry-pick-sequence): add missing '&&'

52 - + [git] 06/08: Merge branch 'rr/maint-t3510-cascade-fix'

53 - + [git] 07/08: Merge branch 'mm/api-credentials-doc'

54 - + [git] 08/08: Git 1.7.11-rc2

55 -

56 - By default, each commit appears in exactly one commit email, the

57 - first time that it is pushed to the repository. If a commit is later

58 - merged into another branch, then a one-line summary of the commit

59 - is included in the reference change email (as usual), but no

60 - additional commit email is generated. See

61 - `multimailhook.refFilter(Inclusion|Exclusion|DoSend|DontSend)Regex`

62 - below to configure which branches and tags are watched by the hook.

63 -

64 - By default, reference change emails have their "Reply-To" field set

65 - to the person who pushed the change, and commit emails have their

66 - "Reply-To" field set to the author of the commit.

67 -

68 -3. Output one "announce" mail for each new annotated tag, including

69 - information about the tag and optionally a shortlog describing the

70 - changes since the previous tag. Such emails might be useful if you

71 - use annotated tags to mark releases of your project.

72 -

73 -

74 -Requirements

75 -------------

76 -

77 -* Python 2.x, version 2.4 or later. No non-standard Python modules

78 - are required. git-multimail has preliminary support for Python 3

79 - (but it has been better tested with Python 2).

80 -

81 -* The ``git`` command must be in your PATH. git-multimail is known to

82 - work with Git versions back to 1.7.1. (Earlier versions have not

83 - been tested; if you do so, please report your results.)

84 -

85 -* To send emails using the default configuration, a standard sendmail

86 - program must be located at '/usr/sbin/sendmail' or

87 - '/usr/lib/sendmail' and must be configured correctly to send emails.

88 - If this is not the case, set multimailhook.sendmailCommand, or see

89 - the multimailhook.mailer configuration variable below for how to

90 - configure git-multimail to send emails via an SMTP server.

91 -

92 -* git-multimail is currently tested only on Linux. It may or may not

93 - work on other platforms such as Windows and Mac OS. See

94 - `<CONTRIBUTING.rst>`__ to improve the situation.

95 -

96 -

97 -Invocation

98 -----------

99 -

100 -``git_multimail.py`` is designed to be used as a ``post-receive`` hook in a

101 -Git repository (see githooks(5)). Link or copy it to

102 -$GIT_DIR/hooks/post-receive within the repository for which email

103 -notifications are desired. Usually it should be installed on the

104 -central repository for a project, to which all commits are eventually

105 -pushed.

106 -

107 -For use on pre-v1.5.1 Git servers, ``git_multimail.py`` can also work as

108 -an ``update`` hook, taking its arguments on the command line. To use

109 -this script in this manner, link or copy it to $GIT_DIR/hooks/update.

110 -Please note that the script is not completely reliable in this mode

111 -[1]_.

112 -

113 -Alternatively, ``git_multimail.py`` can be imported as a Python module

114 -into your own Python post-receive script. This method is a bit more

115 -work, but allows the behavior of the hook to be customized using

116 -arbitrary Python code. For example, you can use a custom environment

117 -(perhaps inheriting from GenericEnvironment or GitoliteEnvironment) to

118 -

119 -* change how the user who did the push is determined

120 -

121 -* read users' email addresses from an LDAP server or from a database

122 -

123 -* decide which users should be notified about which commits based on

124 - the contents of the commits (e.g., for users who want to be notified

125 - only about changes affecting particular files or subdirectories)

126 -

127 -Or you can change how emails are sent by writing your own Mailer

128 -class. The ``post-receive`` script in this directory demonstrates how

129 -to use ``git_multimail.py`` as a Python module. (If you make interesting

130 -changes of this type, please consider sharing them with the

131 -community.)

132 -

133 -

134 -Troubleshooting/FAQ

135 --------------------

136 -

137 -Please read `<doc/troubleshooting.rst>`__ for frequently asked

138 -questions and common issues with git-multimail.

139 -

140 -

141 -Configuration

142 --------------

143 -

144 -By default, git-multimail mostly takes its configuration from the

145 -following ``git config`` settings:

146 -

147 -multimailhook.environment

148 - This describes the general environment of the repository. In most

149 - cases, you do not need to specify a value for this variable:

150 - `git-multimail` will autodetect which environment to use.

151 - Currently supported values:

152 -

153 - generic

154 - the username of the pusher is read from $USER or $USERNAME and

155 - the repository name is derived from the repository's path.

156 -

157 - gitolite

158 - Environment to use when ``git-multimail`` is ran as a gitolite_

159 - hook.

160 -

161 - The username of the pusher is read from $GL_USER, the repository

162 - name is read from $GL_REPO, and the From: header value is

163 - optionally read from gitolite.conf (see multimailhook.from).

164 -

165 - For more information about gitolite and git-multimail, read

166 - `<doc/gitolite.rst>`__

167 -

168 - stash

169 - Environment to use when ``git-multimail`` is ran as an Atlassian

170 - BitBucket Server (formerly known as Atlassian Stash) hook.

171 -

172 - **Warning:** this mode was provided by a third-party contributor

173 - and never tested by the git-multimail maintainers. It is

174 - provided as-is and may or may not work for you.

175 -

176 - This value is automatically assumed when the stash-specific

177 - flags (``--stash-user`` and ``--stash-repo``) are specified on

178 - the command line. When this environment is active, the username

179 - and repo come from these two command line flags, which must be

180 - specified.

181 -

182 - gerrit

183 - Environment to use when ``git-multimail`` is ran as a

184 - ``ref-updated`` Gerrit hook.

185 -

186 - This value is used when the gerrit-specific command line flags

187 - (``--oldrev``, ``--newrev``, ``--refname``, ``--project``) for

188 - gerrit's ref-updated hook are present. When this environment is

189 - active, the username of the pusher is taken from the

190 - ``--submitter`` argument if that command line option is passed,

191 - otherwise 'Gerrit' is used. The repository name is taken from

192 - the ``--project`` option on the command line, which must be passed.

193 -

194 - For more information about gerrit and git-multimail, read

195 - `<doc/gerrit.rst>`__

196 -

197 - If none of these environments is suitable for your setup, then you

198 - can implement a Python class that inherits from Environment and

199 - instantiate it via a script that looks like the example

200 - post-receive script.

201 -

202 - The environment value can be specified on the command line using

203 - the ``--environment`` option. If it is not specified on the

204 - command line or by ``multimailhook.environment``, the value is

205 - guessed as follows:

206 -

207 - * If stash-specific (respectively gerrit-specific) command flags

208 - are present on the command-line, then ``stash`` (respectively

209 - ``gerrit``) is used.

210 -

211 - * If the environment variables $GL_USER and $GL_REPO are set, then

212 - ``gitolite`` is used.

213 -

214 - * If none of the above apply, then ``generic`` is used.

215 -

216 -multimailhook.repoName

217 - A short name of this Git repository, to be used in various places

218 - in the notification email text. The default is to use $GL_REPO

219 - for gitolite repositories, or otherwise to derive this value from

220 - the repository path name.

221 -

222 -multimailhook.mailingList

223 - The list of email addresses to which notification emails should be

224 - sent, as RFC 2822 email addresses separated by commas. This

225 - configuration option can be multivalued. Leave it unset or set it

226 - to the empty string to not send emails by default. The next few

227 - settings can be used to configure specific address lists for

228 - specific types of notification email.

229 -

230 -multimailhook.refchangeList

231 - The list of email addresses to which summary emails about

232 - reference changes should be sent, as RFC 2822 email addresses

233 - separated by commas. This configuration option can be

234 - multivalued. The default is the value in

235 - multimailhook.mailingList. Set this value to "none" (or the empty

236 - string) to prevent reference change emails from being sent even if

237 - multimailhook.mailingList is set.

238 -

239 -multimailhook.announceList

240 - The list of email addresses to which emails about new annotated

241 - tags should be sent, as RFC 2822 email addresses separated by

242 - commas. This configuration option can be multivalued. The

243 - default is the value in multimailhook.refchangeList or

244 - multimailhook.mailingList. Set this value to "none" (or the empty

245 - string) to prevent annotated tag announcement emails from being sent

246 - even if one of the other values is set.

247 -

248 -multimailhook.commitList

249 - The list of email addresses to which emails about individual new

250 - commits should be sent, as RFC 2822 email addresses separated by

251 - commas. This configuration option can be multivalued. The

252 - default is the value in multimailhook.mailingList. Set this value

253 - to "none" (or the empty string) to prevent notification emails about

254 - individual commits from being sent even if

255 - multimailhook.mailingList is set.

256 -

257 -multimailhook.announceShortlog

258 - If this option is set to true, then emails about changes to

259 - annotated tags include a shortlog of changes since the previous

260 - tag. This can be useful if the annotated tags represent releases;

261 - then the shortlog will be a kind of rough summary of what has

262 - happened since the last release. But if your tagging policy is

263 - not so straightforward, then the shortlog might be confusing

264 - rather than useful. Default is false.

265 -

266 -multimailhook.commitEmailFormat

267 - The format of email messages for the individual commits, can be "text" or

268 - "html". In the latter case, the emails will include diffs using colorized

269 - HTML instead of plain text used by default. Note that this currently the

270 - ref change emails are always sent in plain text.

271 -

272 - Note that when using "html", the formatting is done by parsing the

273 - output of ``git log`` with ``-p``. When using

274 - ``multimailhook.commitLogOpts`` to specify a ``--format`` for

275 - ``git log``, one may get false positive (e.g. lines in the body of

276 - the message starting with ``+++`` or ``---`` colored in red or

277 - green).

278 -

279 - By default, all the message is HTML-escaped. See

280 - ``multimailhook.htmlInIntro`` to change this behavior.

281 -

282 -multimailhook.commitBrowseURL

283 - Used to generate a link to an online repository browser in commit

284 - emails. This variable must be a string. Format directives like

285 - ``%(<variable>)s`` will be expanded the same way as template

286 - strings. In particular, ``%(id)s`` will be replaced by the full

287 - Git commit identifier (40-chars hexadecimal).

288 -

289 - If the string does not contain any format directive, then

290 - ``%(id)s`` will be automatically added to the string. If you don't

291 - want ``%(id)s`` to be automatically added, use the empty format

292 - directive ``%()s`` anywhere in the string.

293 -

294 - For example, a suitable value for the git-multimail project itself

295 - would be

296 - ``https://github.com/git-multimail/git-multimail/commit/%(id)s``.

297 -

298 -multimailhook.htmlInIntro, multimailhook.htmlInFooter

299 - When generating an HTML message, git-multimail escapes any HTML

300 - sequence by default. This means that if a template contains HTML

301 - like ``<a href="foo">link</a>``, the reader will see the HTML

302 - source code and not a proper link.

303 -

304 - Set ``multimailhook.htmlInIntro`` to true to allow writing HTML

305 - formatting in introduction templates. Similarly, set

306 - ``multimailhook.htmlInFooter`` for HTML in the footer.

307 -

308 - Variables expanded in the template are still escaped. For example,

309 - if a repository's path contains a ``<``, it will be rendered as

310 - such in the message.

311 -

312 - Read `<doc/customizing-emails.rst>`__ for more details and

313 - examples.

314 -

315 -multimailhook.refchangeShowGraph

316 - If this option is set to true, then summary emails about reference

317 - changes will additionally include:

318 -

319 - * a graph of the added commits (if any)

320 -

321 - * a graph of the discarded commits (if any)

322 -

323 - The log is generated by running ``git log --graph`` with the options

324 - specified in graphOpts. The default is false.

325 -

326 -multimailhook.refchangeShowLog

327 - If this option is set to true, then summary emails about reference

328 - changes will include a detailed log of the added commits in

329 - addition to the one line summary. The log is generated by running

330 - ``git log`` with the options specified in multimailhook.logOpts.

331 - Default is false.

332 -

333 -multimailhook.mailer

334 - This option changes the way emails are sent. Accepted values are:

335 -

336 - * **sendmail (the default)**: use the command ``/usr/sbin/sendmail`` or

337 - ``/usr/lib/sendmail`` (or sendmailCommand, if configured). This

338 - mode can be further customized via the following options:

339 -

340 - multimailhook.sendmailCommand

341 - The command used by mailer ``sendmail`` to send emails. Shell

342 - quoting is allowed in the value of this setting, but remember that

343 - Git requires double-quotes to be escaped; e.g.::

344 -

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

346 -

347 - Default is '/usr/sbin/sendmail -oi -t' or

348 - '/usr/lib/sendmail -oi -t' (depending on which file is

349 - present and executable).

350 -

351 - multimailhook.envelopeSender

352 - If set then pass this value to sendmail via the -f option to set

353 - the envelope sender address.

354 -

355 - * **smtp**: use Python's smtplib. This is useful when the sendmail

356 - command is not available on the system. This mode can be

357 - further customized via the following options:

358 -

359 - multimailhook.smtpServer

360 - The name of the SMTP server to connect to. The value can

361 - also include a colon and a port number; e.g.,

362 - ``mail.example.com:25``. Default is 'localhost' using port 25.

363 -

364 - multimailhook.smtpUser, multimailhook.smtpPass

365 - Server username and password. Required if smtpEncryption is 'ssl'.

366 - Note that the username and password currently need to be

367 - set cleartext in the configuration file, which is not

368 - recommended. If you need to use this option, be sure your

369 - configuration file is read-only.

370 -

371 - multimailhook.envelopeSender

372 - The sender address to be passed to the SMTP server. If

373 - unset, then the value of multimailhook.from is used.

374 -

375 - multimailhook.smtpServerTimeout

376 - Timeout in seconds. Default is 10.

377 -

378 - multimailhook.smtpEncryption

379 - Set the security type. Allowed values: ``none``, ``ssl``, ``tls`` (starttls).

380 - Default is ``none``.

381 -

382 - multimailhook.smtpCACerts

383 - Set the path to a list of trusted CA certificate to verify the

384 - server certificate, only supported when ``smtpEncryption`` is

385 - ``tls``. If unset or empty, the server certificate is not

386 - verified. If it targets a file containing a list of trusted CA

387 - certificates (PEM format) these CAs will be used to verify the

388 - server certificate. For debian, you can set

389 - ``/etc/ssl/certs/ca-certificates.crt`` for using the system

390 - trusted CAs. For self-signed server, you can add your server

391 - certificate to the system store::

392 -

393 - cd /usr/local/share/ca-certificates/

394 - openssl s_client -starttls smtp \

395 - -connect mail.example.net:587 -showcerts \

396 - </dev/null 2>/dev/null \

397 - | openssl x509 -outform PEM >mail.example.net.crt

398 - update-ca-certificates

399 -

400 - and used the updated ``/etc/ssl/certs/ca-certificates.crt``. Or

401 - directly use your ``/path/to/mail.example.net.crt``. Default is

402 - unset.

403 -

404 - multimailhook.smtpServerDebugLevel

405 - Integer number. Set to greater than 0 to activate debugging.

406 -

407 -multimailhook.from, multimailhook.fromCommit, multimailhook.fromRefchange

408 - If set, use this value in the From: field of generated emails.

409 - ``fromCommit`` is used for commit emails, ``fromRefchange`` is

410 - used for refchange emails, and ``from`` is used as fall-back in

411 - all cases.

412 -

413 - The value for these variables can be either:

414 -

415 - - An email address, which will be used directly.

416 -

417 - - The value ``pusher``, in which case the pusher's address (if

418 - available) will be used.

419 -

420 - - The value ``author`` (meaningful only for ``fromCommit``), in which

421 - case the commit author's address will be used.

422 -

423 - If config values are unset, the value of the From: header is

424 - determined as follows:

425 -

426 - 1. (gitolite environment only)

427 - 1.a) If ``multimailhook.MailaddressMap`` is set, and is a path

428 - to an existing file (if relative, it is considered relative to

429 - the place where ``gitolite.conf`` is located), then this file

430 - should contain lines like::

431 -

432 - username Firstname Lastname <email@example.com>

433 -

434 - git-multimail will then look for a line where ``$GL_USER``

435 - matches the ``username`` part, and use the rest of the line for

436 - the ``From:`` header.

437 -

438 - 1.b) Parse gitolite.conf, looking for a block of comments that

439 - looks like this::

440 -

441 - # BEGIN USER EMAILS

442 - # username Firstname Lastname <email@example.com>

443 - # END USER EMAILS

444 -

445 - If that block exists, and there is a line between the BEGIN

446 - USER EMAILS and END USER EMAILS lines where the first field

447 - matches the gitolite username ($GL_USER), use the rest of the

448 - line for the From: header.

449 -

450 - 2. If the user.email configuration setting is set, use its value

451 - (and the value of user.name, if set).

452 -

453 - 3. Use the value of multimailhook.envelopeSender.

454 -

455 -multimailhook.MailaddressMap

456 - (gitolite environment only)

457 - File to look for a ``From:`` address based on the user doing the

458 - push. Defaults to unset. See ``multimailhook.from`` for details.

459 -

460 -multimailhook.administrator

461 - The name and/or email address of the administrator of the Git

462 - repository; used in FOOTER_TEMPLATE. Default is

463 - multimailhook.envelopesender if it is set; otherwise a generic

464 - string is used.

465 -

466 -multimailhook.emailPrefix

467 - All emails have this string prepended to their subjects, to aid

468 - email filtering (though filtering based on the X-Git-* email

469 - headers is probably more robust). Default is the short name of

470 - the repository in square brackets; e.g., ``[myrepo]``. Set this

471 - value to the empty string to suppress the email prefix. You may

472 - use the placeholder ``%(repo_shortname)s`` for the short name of

473 - the repository.

474 -

475 -multimailhook.emailMaxLines

476 - The maximum number of lines that should be included in the body of

477 - a generated email. If not specified, there is no limit. Lines

478 - beyond the limit are suppressed and counted, and a final line is

479 - added indicating the number of suppressed lines.

480 -

481 -multimailhook.emailMaxLineLength

482 - The maximum length of a line in the email body. Lines longer than

483 - this limit are truncated to this length with a trailing ``[...]``

484 - added to indicate the missing text. The default is 500, because

485 - (a) diffs with longer lines are probably from binary files, for

486 - which a diff is useless, and (b) even if a text file has such long

487 - lines, the diffs are probably unreadable anyway. To disable line

488 - truncation, set this option to 0.

489 -

490 -multimailhook.subjectMaxLength

491 - The maximum length of the subject line (i.e. the ``oneline`` field

492 - in templates, not including the prefix). Lines longer than this

493 - limit are truncated to this length with a trailing ``[...]`` added

494 - to indicate the missing text. This option The default is to use

495 - ``multimailhook.emailMaxLineLength``. This option avoids sending

496 - emails with overly long subject lines, but should not be needed if

497 - the commit messages follow the Git convention (one short subject

498 - line, then a blank line, then the message body). To disable line

499 - truncation, set this option to 0.

500 -

501 -multimailhook.maxCommitEmails

502 - The maximum number of commit emails to send for a given change.

503 - When the number of patches is larger that this value, only the

504 - summary refchange email is sent. This can avoid accidental

505 - mailbombing, for example on an initial push. To disable commit

506 - emails limit, set this option to 0. The default is 500.

507 -

508 -multimailhook.excludeMergeRevisions

509 - When sending out revision emails, do not consider merge commits (the

510 - functional equivalent of `rev-list --no-merges`).

511 - The default is `false` (send merge commit emails).

512 -

513 -multimailhook.emailStrictUTF8

514 - If this boolean option is set to `true`, then the main part of the

515 - email body is forced to be valid UTF-8. Any characters that are

516 - not valid UTF-8 are converted to the Unicode replacement

517 - character, U+FFFD. The default is `true`.

518 -

519 - This option is ineffective with Python 3, where non-UTF-8

520 - characters are unconditionally replaced.

521 -

522 -multimailhook.diffOpts

523 - Options passed to ``git diff-tree`` when generating the summary

524 - information for ReferenceChange emails. Default is ``--stat

525 - --summary --find-copies-harder``. Add -p to those options to

526 - include a unified diff of changes in addition to the usual summary

527 - output. Shell quoting is allowed; see ``multimailhook.logOpts`` for

528 - details.

529 -

530 -multimailhook.graphOpts

531 - Options passed to ``git log --graph`` when generating graphs for the

532 - reference change summary emails (used only if refchangeShowGraph

533 - is true). The default is '--oneline --decorate'.

534 -

535 - Shell quoting is allowed; see logOpts for details.

536 -

537 -multimailhook.logOpts

538 - Options passed to ``git log`` to generate additional info for

539 - reference change emails (used only if refchangeShowLog is set).

540 - For example, adding -p will show each commit's complete diff. The

541 - default is empty.

542 -

543 - Shell quoting is allowed; for example, a log format that contains

544 - spaces can be specified using something like::

545 -

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

547 -

548 - If you want to set this by editing your configuration file

549 - directly, remember that Git requires double-quotes to be escaped

550 - (see git-config(1) for more information)::

551 -

552 - [multimailhook]

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

554 -

555 -multimailhook.commitLogOpts

556 - Options passed to ``git log`` to generate additional info for

557 - revision change emails. For example, adding --ignore-all-spaces

558 - will suppress whitespace changes. The default options are ``-C

559 - --stat -p --cc``. Shell quoting is allowed; see

560 - multimailhook.logOpts for details.

561 -

562 -multimailhook.dateSubstitute

563 - String to use as a substitute for ``Date:`` in the output of ``git

564 - log`` while formatting commit messages. This is useful to avoid

565 - emitting a line that can be interpreted by mailers as the start of

566 - a cited message (Zimbra webmail in particular). Defaults to

567 - ``CommitDate:``. Set to an empty string or ``none`` to deactivate

568 - the behavior.

569 -

570 -multimailhook.emailDomain

571 - Domain name appended to the username of the person doing the push

572 - to convert it into an email address

573 - (via ``"%s@%s" % (username, emaildomain)``). More complicated

574 - schemes can be implemented by overriding Environment and

575 - overriding its get_pusher_email() method.

576 -

577 -multimailhook.replyTo, multimailhook.replyToCommit, multimailhook.replyToRefchange

578 - Addresses to use in the Reply-To: field for commit emails

579 - (replyToCommit) and refchange emails (replyToRefchange).

580 - multimailhook.replyTo is used as default when replyToCommit or

581 - replyToRefchange is not set. The shortcuts ``pusher`` and

582 - ``author`` are allowed with the same semantics as for

583 - ``multimailhook.from``. In addition, the value ``none`` can be

584 - used to omit the ``Reply-To:`` field.

585 -

586 - The default is ``pusher`` for refchange emails, and ``author`` for

587 - commit emails.

588 -

589 -multimailhook.quiet

590 - Do not output the list of email recipients from the hook

591 -

592 -multimailhook.stdout

593 - For debugging, send emails to stdout rather than to the

594 - mailer. Equivalent to the --stdout command line option

595 -

596 -multimailhook.scanCommitForCc

597 - If this option is set to true, than recipients from lines in commit body

598 - that starts with ``CC:`` will be added to CC list.

599 - Default: false

600 -

601 -multimailhook.combineWhenSingleCommit

602 - If this option is set to true and a single new commit is pushed to

603 - a branch, combine the summary and commit email messages into a

604 - single email.

605 - Default: true

606 -

607 -multimailhook.refFilterInclusionRegex, multimailhook.refFilterExclusionRegex, multimailhook.refFilterDoSendRegex, multimailhook.refFilterDontSendRegex

608 - **Warning:** these options are experimental. They should work, but

609 - the user-interface is not stable yet (in particular, the option

610 - names may change). If you want to participate in stabilizing the

611 - feature, please contact the maintainers and/or send pull-requests.

612 - If you are happy with the current shape of the feature, please

613 - report it too.

614 -

615 - Regular expressions that can be used to limit refs for which email

616 - updates will be sent. It is an error to specify both an inclusion

617 - and an exclusion regex. If a ``refFilterInclusionRegex`` is

618 - specified, emails will only be sent for refs which match this

619 - regex. If a ``refFilterExclusionRegex`` regex is specified,

620 - emails will be sent for all refs except those that match this

621 - regex (or that match a predefined regex specific to the

622 - environment, such as "^refs/notes" for most environments and

623 - "^refs/notes|^refs/changes" for the gerrit environment).

624 -

625 - The expressions are matched against the complete refname, and is

626 - considered to match if any substring matches. For example, to

627 - filter-out all tags, set ``refFilterExclusionRegex`` to

628 - ``^refs/tags/`` (note the leading ``^`` but no trailing ``$``). If

629 - you set ``refFilterExclusionRegex`` to ``master``, then any ref

630 - containing ``master`` will be excluded (the ``master`` branch, but

631 - also ``refs/tags/master`` or ``refs/heads/foo-master-bar``).

632 -

633 - ``refFilterDoSendRegex`` and ``refFilterDontSendRegex`` are

634 - analogous to ``refFilterInclusionRegex`` and

635 - ``refFilterExclusionRegex`` with one difference: with

636 - ``refFilterDoSendRegex`` and ``refFilterDontSendRegex``, commits

637 - introduced by one excluded ref will not be considered as new when

638 - they reach an included ref. Typically, if you add a branch ``foo``

639 - to ``refFilterDontSendRegex``, push commits to this branch, and

640 - later merge branch ``foo`` into ``master``, then the notification

641 - email for ``master`` will contain a commit email only for the

642 - merge commit. If you include ``foo`` in

643 - ``refFilterExclusionRegex``, then at the time of merge, you will

644 - receive one commit email per commit in the branch.

645 -

646 - These variables can be multi-valued, like::

647 -

648 - [multimailhook]

649 - refFilterExclusionRegex = ^refs/tags/

650 - refFilterExclusionRegex = ^refs/heads/master$

651 -

652 - You can also provide a whitespace-separated list like::

653 -

654 - [multimailhook]

655 - refFilterExclusionRegex = ^refs/tags/ ^refs/heads/master$

656 -

657 - Both examples exclude tags and the master branch, and are

658 - equivalent to::

659 -

660 - [multimailhook]

661 - refFilterExclusionRegex = ^refs/tags/|^refs/heads/master$

662 -

663 - ``refFilterInclusionRegex`` and ``refFilterExclusionRegex`` are

664 - strictly stronger than ``refFilterDoSendRegex`` and

665 - ``refFilterDontSendRegex``. In other words, adding a ref to a

666 - DoSend/DontSend regex has no effect if it is already excluded by a

667 - Exclusion/Inclusion regex.

668 -

669 -multimailhook.logFile, multimailhook.errorLogFile, multimailhook.debugLogFile

670 -

671 - When set, these variable designate path to files where

672 - git-multimail will log some messages. Normal messages and error

673 - messages are sent to ``logFile``, and error messages are also sent

674 - to ``errorLogFile``. Debug messages and all other messages are

675 - sent to ``debugLogFile``. The recommended way is to set only one

676 - of these variables, but it is also possible to set several of them

677 - (part of the information is then duplicated in several log files,

678 - for example errors are duplicated to all log files).

679 -

680 - Relative path are relative to the Git repository where the push is

681 - done.

682 -

683 -multimailhook.verbose

684 -

685 - Verbosity level of git-multimail on its standard output. By

686 - default, show only error and info messages. If set to true, show

687 - also debug messages.

688 -

689 -Email filtering aids

690 ---------------------

691 -

692 -All emails include extra headers to enable fine tuned filtering and

693 -give information for debugging. All emails include the headers

694 -``X-Git-Host``, ``X-Git-Repo``, ``X-Git-Refname``, and ``X-Git-Reftype``.

695 -ReferenceChange emails also include headers ``X-Git-Oldrev`` and ``X-Git-Newrev``;

696 -Revision emails also include header ``X-Git-Rev``.

697 -

698 -

699 -Customizing email contents

700 ---------------------------

701 -

702 -git-multimail mostly generates emails by expanding templates. The

703 -templates can be customized. To avoid the need to edit

704 -``git_multimail.py`` directly, the preferred way to change the templates

705 -is to write a separate Python script that imports ``git_multimail.py`` as

706 -a module, then replaces the templates in place. See the provided

707 -post-receive script for an example of how this is done.

708 -

709 -

710 -Customizing git-multimail for your environment

711 -----------------------------------------------

712 -

713 -git-multimail is mostly customized via an "environment" that describes

714 -the local environment in which Git is running. Two types of

715 -environment are built in:

716 -

717 -GenericEnvironment

718 - a stand-alone Git repository.

719 -

720 -GitoliteEnvironment

721 - a Git repository that is managed by gitolite_. For such

722 - repositories, the identity of the pusher is read from

723 - environment variable $GL_USER, the name of the repository is read

724 - from $GL_REPO (if it is not overridden by multimailhook.reponame),

725 - and the From: header value is optionally read from gitolite.conf

726 - (see multimailhook.from).

727 -

728 -By default, git-multimail assumes GitoliteEnvironment if $GL_USER and

729 -$GL_REPO are set, and otherwise assumes GenericEnvironment.

730 -Alternatively, you can choose one of these two environments explicitly

731 -by setting a ``multimailhook.environment`` config setting (which can

732 -have the value `generic` or `gitolite`) or by passing an --environment

733 -option to the script.

734 -

735 -If you need to customize the script in ways that are not supported by

736 -the existing environments, you can define your own environment class

737 -class using arbitrary Python code. To do so, you need to import

738 -``git_multimail.py`` as a Python module, as demonstrated by the example

739 -post-receive script. Then implement your environment class; it should

740 -usually inherit from one of the existing Environment classes and

741 -possibly one or more of the EnvironmentMixin classes. Then set the

742 -``environment`` variable to an instance of your own environment class

743 -and pass it to ``run_as_post_receive_hook()``.

744 -

745 -The standard environment classes, GenericEnvironment and

746 -GitoliteEnvironment, are in fact themselves put together out of a

747 -number of mixin classes, each of which handles one aspect of the

748 -customization. For the finest control over your configuration, you

749 -can specify exactly which mixin classes your own environment class

750 -should inherit from, and override individual methods (or even add your

751 -own mixin classes) to implement entirely new behaviors. If you

752 -implement any mixins that might be useful to other people, please

753 -consider sharing them with the community!

754 -

755 -

756 -Getting involved

757 -----------------

758 -

759 -Please, read `<CONTRIBUTING.rst>`__ for instructions on how to

760 -contribute to git-multimail.

761 -

762 -

763 -Footnotes

764 ----------

765 -

766 -.. [1] Because of the way information is passed to update hooks, the

767 - script's method of determining whether a commit has already

768 - been seen does not work when it is used as an ``update`` script.

769 - In particular, no notification email will be generated for a

770 - new commit that is added to multiple references in the same

771 - push. A workaround is to use --force-send to force sending the

772 - emails.

773 -

774 -.. _gitolite: https://github.com/sitaramc/gitolite

contrib/hooks/multimail/doc/customizing-emails.rst deleted

-56

@@ -1,56 +0,0 @@

1 -Customizing the content and formatting of emails

2 -================================================

3 -

4 -Overloading template strings

5 -----------------------------

6 -

7 -The content of emails is generated based on template strings defined

8 -in ``git_multimail.py``. You can customize these template strings

9 -without changing the script itself, by defining a Python wrapper

10 -around it. The python wrapper should ``import git_multimail`` and then

11 -override the ``git_multimail.*`` strings like this::

12 -

13 - import sys # needed for sys.argv

14 -

15 - # Import and customize git_multimail:

16 - import git_multimail

17 - git_multimail.REVISION_INTRO_TEMPLATE = """..."""

18 - git_multimail.COMBINED_INTRO_TEMPLATE = git_multimail.REVISION_INTRO_TEMPLATE

19 -

20 - # start git_multimail itself:

21 - git_multimail.main(sys.argv[1:])

22 -

23 -The template strings can use any value already used in the existing

24 -templates (read the source code).

25 -

26 -Using HTML in template strings

27 -------------------------------

28 -

29 -If ``multimailhook.commitEmailFormat`` is set to HTML, then

30 -git-multimail will generate HTML emails for commit notifications. The

31 -log and diff will be formatted automatically by git-multimail. By

32 -default, any HTML special character in the templates will be escaped.

33 -

34 -To use HTML formatting in the introduction of the email, set

35 -``multimailhook.htmlInIntro`` to ``true``. Then, the template can

36 -contain any HTML tags, that will be sent as-is in the email. For

37 -example, to add some formatting and a link to the online commit, use

38 -a format like::

39 -

40 - git_multimail.REVISION_INTRO_TEMPLATE = """\

41 - This is an automated email from the git hooks/post-receive script.

42 -

43 - %(pusher)s pushed a commit to %(refname_type)s %(short_refname)s

44 - in repository %(repo_shortname)s.

45 -

46 - <a href="https://github.com/git-multimail/git-multimail/commit/%(newrev)s">View on GitHub</a>.

47 - """

48 -

49 -Note that the values expanded from ``%(variable)s`` in the format

50 -strings will still be escaped.

51 -

52 -For a less flexible but easier to set up way to add a link to commit

53 -emails, see ``multimailhook.commitBrowseURL``.

54 -

55 -Similarly, one can set ``multimailhook.htmlInFooter`` and override any

56 -of the ``*_FOOTER*`` template strings.

contrib/hooks/multimail/doc/gerrit.rst deleted

-56

@@ -1,56 +0,0 @@

1 -Setting up git-multimail on Gerrit

2 -==================================

3 -

4 -Gerrit has its own email-sending system, but you may prefer using

5 -``git-multimail`` instead. It supports Gerrit natively as a Gerrit

6 -``ref-updated`` hook (Warning: `Gerrit hooks

7 -<https://gerrit-review.googlesource.com/Documentation/config-hooks.html>`__

8 -are distinct from Git hooks). Setting up ``git-multimail`` on a Gerrit

9 -installation can be done following the instructions below.

10 -

11 -The explanations show an easy way to set up ``git-multimail``,

12 -but leave ``git-multimail`` installed and unconfigured for a while. If

13 -you run Gerrit on a production server, it is advised that you

14 -execute the step "Set up the hook" last to avoid confusing your users

15 -in the meantime.

16 -

17 -Set up the hook

18 ----------------

19 -

20 -Create a directory ``$site_path/hooks/`` if it does not exist (if you

21 -don't know what ``$site_path`` is, run ``gerrit.sh status`` and look

22 -for a ``GERRIT_SITE`` line). Either copy ``git_multimail.py`` to

23 -``$site_path/hooks/ref-updated`` or create a wrapper script like

24 -this::

25 -

26 - #! /bin/sh

27 - exec /path/to/git_multimail.py "$@"

28 -

29 -In both cases, make sure the file is named exactly

30 -``$site_path/hooks/ref-updated`` and is executable.

31 -

32 -(Alternatively, you may configure the ``[hooks]`` section of

33 -gerrit.config)

34 -

35 -Configuration

36 --------------

37 -

38 -Log on the gerrit server and edit ``$site_path/git/$project/config``

39 -to configure ``git-multimail``.

40 -

41 -Troubleshooting

42 ----------------

43 -

44 -Warning: this will disable ``git-multimail`` during the debug, and

45 -could confuse your users. Don't run on a production server.

46 -

47 -To debug configuration issues with ``git-multimail``, you can add the

48 -``--stdout`` option when calling ``git_multimail.py`` like this::

49 -

50 - #!/bin/sh

51 - exec /path/to/git-multimail/git-multimail/git_multimail.py \

52 - --stdout "$@" >> /tmp/log.txt

53 -

54 -and try pushing from a test repository. You should see the source of

55 -the email that would have been sent in the output of ``git push`` in

56 -the file ``/tmp/log.txt``.

contrib/hooks/multimail/doc/gitolite.rst deleted

-118

@@ -1,118 +0,0 @@

1 -Setting up git-multimail on gitolite

2 -====================================

3 -

4 -``git-multimail`` supports gitolite 3 natively.

5 -The explanations below show an easy way to set up ``git-multimail``,

6 -but leave ``git-multimail`` installed and unconfigured for a while. If

7 -you run gitolite on a production server, it is advised that you

8 -execute the step "Set up the hook" last to avoid confusing your users

9 -in the meantime.

10 -

11 -Set up the hook

12 ----------------

13 -

14 -Log in as your gitolite user.

15 -

16 -Create a file ``.gitolite/hooks/common/post-receive`` on your gitolite

17 -account containing (adapt the path, obviously)::

18 -

19 - #!/bin/sh

20 - exec /path/to/git-multimail/git-multimail/git_multimail.py "$@"

21 -

22 -Make sure it's executable (``chmod +x``). Record the hook in

23 -gitolite::

24 -

25 - gitolite setup

26 -

27 -Configuration

28 --------------

29 -

30 -First, you have to allow the admin to set Git configuration variables.

31 -

32 -As gitolite user, edit the line containing ``GIT_CONFIG_KEYS`` in file

33 -``.gitolite.rc``, to make it look like::

34 -

35 - GIT_CONFIG_KEYS => 'multimailhook\..*',

36 -

37 -You can now log out and return to your normal user.

38 -

39 -In the ``gitolite-admin`` clone, edit the file ``conf/gitolite.conf``

40 -and add::

41 -

42 - repo @all

43 - # Not strictly needed as git_multimail.py will chose gitolite if

44 - # $GL_USER is set.

45 - config multimailhook.environment = gitolite

46 - config multimailhook.mailingList = # Where emails should be sent

47 - config multimailhook.from = # From address to use

48 -

49 -Note that by default, gitolite forbids ``<`` and ``>`` in variable

50 -values (for security/paranoia reasons, see

51 -`compensating for UNSAFE_PATT

52 -<http://gitolite.com/gitolite/git-config/index.html#compensating-for-unsafe95patt>`__

53 -in gitolite's documentation for explanations and a way to disable

54 -this). As a consequence, you will not be able to use ``First Last

55 -<First.Last@example.com>`` as recipient email, but specifying

56 -``First.Last@example.com`` alone works.

57 -

58 -Obviously, you can customize all parameters on a per-repository basis by

59 -adding these ``config multimailhook.*`` lines in the section

60 -corresponding to a repository or set of repositories.

61 -

62 -To activate ``git-multimail`` on a per-repository basis, do not set

63 -``multimailhook.mailingList`` in the ``@all`` section and set it only

64 -for repositories for which you want ``git-multimail``.

65 -

66 -Alternatively, you can set up the ``From:`` field on a per-user basis

67 -by adding a ``BEGIN USER EMAILS``/``END USER EMAILS`` section (see

68 -``../README``).

69 -

70 -Specificities of Gitolite for Configuration

71 --------------------------------------------

72 -

73 -Empty configuration variables

74 -.............................

75 -

76 -With gitolite, the syntax ``config multimailhook.commitList = ""``

77 -unsets the variable instead of setting it to an empty string (see

78 -`here

79 -<http://gitolite.com/gitolite/git-config.html#an-important-warning-about-deleting-a-config-line>`__).

80 -As a result, there is no way to set a variable to the empty string.

81 -In all most places where an empty value is required, git-multimail

82 -now allows to specify special ``"none"`` value (case-sensitive) to

83 -mean the same.

84 -

85 -Alternatively, one can use ``" "`` (a single space) instead of ``""``.

86 -In most cases (in particular ``multimailhook.*List`` variables), this

87 -will be equivalent to an empty string.

88 -

89 -If you have a use-case where ``"none"`` is not an acceptable value and

90 -you need ``" "`` or ``""`` instead, please report it as a bug to

91 -git-multimail.

92 -

93 -Allowing Regular Expressions in Configuration

94 -.............................................

95 -

96 -gitolite has a mechanism to prevent unsafe configuration variable

97 -values, which prevent characters like ``|`` commonly used in regular

98 -expressions. If you do not need the safety feature of gitolite and

99 -need to use regular expressions in your configuration (e.g. for

100 -``multimailhook.refFilter*`` variables), set

101 -`UNSAFE_PATT

102 -<http://gitolite.com/gitolite/git-config.html#unsafe-patt>`__ to a

103 -less restrictive value.

104 -

105 -Troubleshooting

106 ----------------

107 -

108 -Warning: this will disable ``git-multimail`` during the debug, and

109 -could confuse your users. Don't run on a production server.

110 -

111 -To debug configuration issues with ``git-multimail``, you can add the

112 -``--stdout`` option when calling ``git_multimail.py`` like this::

113 -

114 - #!/bin/sh

115 - exec /path/to/git-multimail/git-multimail/git_multimail.py --stdout "$@"

116 -

117 -and try pushing from a test repository. You should see the source of

118 -the email that would have been sent in the output of ``git push``.

contrib/hooks/multimail/doc/troubleshooting.rst deleted

-78

@@ -1,78 +0,0 @@

1 -Troubleshooting issues with git-multimail: a FAQ

2 -================================================

3 -

4 -How to check that git-multimail is properly set up?

5 ----------------------------------------------------

6 -

7 -Since version 1.4.0, git-multimail allows a simple self-checking of

8 -its configuration: run it with the environment variable

9 -``GIT_MULTIMAIL_CHECK_SETUP`` set to a non-empty string. You should

10 -get something like this::

11 -

12 - $ GIT_MULTIMAIL_CHECK_SETUP=true /home/moy/dev/git-multimail/git-multimail/git_multimail.py

13 - Environment values:

14 - administrator : 'the administrator of this repository'

15 - charset : 'utf-8'

16 - emailprefix : '[git-multimail] '

17 - fqdn : 'anie'

18 - projectdesc : 'UNNAMED PROJECT'

19 - pusher : 'moy'

20 - repo_path : '/home/moy/dev/git-multimail'

21 - repo_shortname : 'git-multimail'

22 -

23 - Now, checking that git-multimail's standard input is properly set ...

24 - Please type some text and then press Return

25 - foo

26 - You have just entered:

27 - foo

28 - git-multimail seems properly set up.

29 -

30 -If you forgot to set an important variable, you may get instead::

31 -

32 - $ GIT_MULTIMAIL_CHECK_SETUP=true /home/moy/dev/git-multimail/git-multimail/git_multimail.py

33 - No email recipients configured!

34 -

35 -Do not set ``$GIT_MULTIMAIL_CHECK_SETUP`` other than for testing your

36 -configuration: it would disable the hook completely.

37 -

38 -Git is not using the right address in the From/To/Reply-To field

39 -----------------------------------------------------------------

40 -

41 -First, make sure that git-multimail actually uses what you think it is

42 -using. A lot happens to your email (especially when posting to a

43 -mailing-list) between the time `git_multimail.py` sends it and the

44 -time it reaches your inbox.

45 -

46 -A simple test (to do on a test repository, do not use in production as

47 -it would disable email sending): change your post-receive hook to call

48 -`git_multimail.py` with the `--stdout` option, and try to push to the

49 -repository. You should see something like::

50 -

51 - Counting objects: 3, done.

52 - Writing objects: 100% (3/3), 263 bytes | 0 bytes/s, done.

53 - Total 3 (delta 0), reused 0 (delta 0)

54 - remote: Sending notification emails to: foo.bar@example.com

55 - remote: ===========================================================================

56 - remote: Date: Mon, 25 Apr 2016 18:39:59 +0200

57 - remote: To: foo.bar@example.com

58 - remote: Subject: [git] branch master updated: foo

59 - remote: MIME-Version: 1.0

60 - remote: Content-Type: text/plain; charset=utf-8

61 - remote: Content-Transfer-Encoding: 8bit

62 - remote: Message-ID: <20160425163959.2311.20498@anie>

63 - remote: From: Auth Or <Foo.Bar@example.com>

64 - remote: Reply-To: Auth Or <Foo.Bar@example.com>

65 - remote: X-Git-Host: example

66 - ...

67 - remote: --

68 - remote: To stop receiving notification emails like this one, please contact

69 - remote: the administrator of this repository.

70 - remote: ===========================================================================

71 - To /path/to/repo

72 - 6278f04..e173f20 master -> master

73 -

74 -Note: this does not include the sender (Return-Path: header), as it is

75 -not part of the message content but passed to the mailer. Some mailer

76 -show the ``Sender:`` field instead of the ``From:`` field (for

77 -example, Zimbra Webmail shows ``From: <sender-field> on behalf of

78 -<from-field>``).

contrib/hooks/multimail/git_multimail.py deleted

-4345

@@ -1,4346 +0,0 @@

1 -#! /usr/bin/env python

2 -

3 -__version__ = '1.5.0'

4 -

7 -# Derived from contrib/hooks/post-receive-email, which is

9 -# and also includes contributions by other authors.

10 -#

11 -# This file is part of git-multimail.

12 -#

13 -# git-multimail is free software: you can redistribute it and/or

14 -# modify it under the terms of the GNU General Public License version

15 -# 2 as published by the Free Software Foundation.

16 -#

17 -# This program is distributed in the hope that it will be useful, but

18 -# WITHOUT ANY WARRANTY; without even the implied warranty of

19 -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU

20 -# General Public License for more details.

21 -#

22 -# You should have received a copy of the GNU General Public License

23 -# along with this program. If not, see

24 -# <http://www.gnu.org/licenses/>.

25 -

26 -"""Generate notification emails for pushes to a git repository.

27 -

28 -This hook sends emails describing changes introduced by pushes to a

29 -git repository. For each reference that was changed, it emits one

30 -ReferenceChange email summarizing how the reference was changed,

31 -followed by one Revision email for each new commit that was introduced

32 -by the reference change.

33 -

34 -Each commit is announced in exactly one Revision email. If the same

35 -commit is merged into another branch in the same or a later push, then

36 -the ReferenceChange email will list the commit's SHA1 and its one-line

37 -summary, but no new Revision email will be generated.

38 -

39 -This script is designed to be used as a "post-receive" hook in a git

40 -repository (see githooks(5)). It can also be used as an "update"

41 -script, but this usage is not completely reliable and is deprecated.

42 -

43 -To help with debugging, this script accepts a --stdout option, which

44 -causes the emails to be written to standard output rather than sent

45 -using sendmail.

46 -

47 -See the accompanying README file for the complete documentation.

48 -

49 -"""

50 -

51 -import sys

52 -import os

53 -import re

54 -import bisect

55 -import socket

56 -import subprocess

57 -import shlex

58 -import optparse

59 -import logging

60 -import smtplib

61 -try:

62 - import ssl

63 -except ImportError:

64 - # Python < 2.6 do not have ssl, but that's OK if we don't use it.

65 - pass

66 -import time

67 -

68 -import uuid

69 -import base64

70 -

71 -PYTHON3 = sys.version_info >= (3, 0)

72 -

73 -if sys.version_info <= (2, 5):

74 - def all(iterable):

75 - for element in iterable:

76 - if not element:

77 - return False

78 - return True

79 -

80 -

81 -def is_ascii(s):

82 - return all(ord(c) < 128 and ord(c) > 0 for c in s)

83 -

84 -

85 -if PYTHON3:

86 - def is_string(s):

87 - return isinstance(s, str)

88 -

89 - def str_to_bytes(s):

90 - return s.encode(ENCODING)

91 -

92 - def bytes_to_str(s, errors='strict'):

93 - return s.decode(ENCODING, errors)

94 -

95 - unicode = str

96 -

97 - def write_str(f, msg):

98 - # Try outputting with the default encoding. If it fails,

99 - # try UTF-8.

100 - try:

101 - f.buffer.write(msg.encode(sys.getdefaultencoding()))

102 - except UnicodeEncodeError:

103 - f.buffer.write(msg.encode(ENCODING))

104 -

105 - def read_line(f):

106 - # Try reading with the default encoding. If it fails,

107 - # try UTF-8.

108 - out = f.buffer.readline()

109 - try:

110 - return out.decode(sys.getdefaultencoding())

111 - except UnicodeEncodeError:

112 - return out.decode(ENCODING)

113 -

114 - import html

115 -

116 - def html_escape(s):

117 - return html.escape(s)

118 -

119 -else:

120 - def is_string(s):

121 - try:

122 - return isinstance(s, basestring)

123 - except NameError: # Silence Pyflakes warning

124 - raise

125 -

126 - def str_to_bytes(s):

127 - return s

128 -

129 - def bytes_to_str(s, errors='strict'):

130 - return s

131 -

132 - def write_str(f, msg):

133 - f.write(msg)

134 -

135 - def read_line(f):

136 - return f.readline()

137 -

138 - def next(it):

139 - return it.next()

140 -

141 - import cgi

142 -

143 - def html_escape(s):

144 - return cgi.escape(s, True)

145 -

146 -try:

147 - from email.charset import Charset

148 - from email.utils import make_msgid

149 - from email.utils import getaddresses

150 - from email.utils import formataddr

151 - from email.utils import formatdate

152 - from email.header import Header

153 -except ImportError:

154 - # Prior to Python 2.5, the email module used different names:

155 - from email.Charset import Charset

156 - from email.Utils import make_msgid

157 - from email.Utils import getaddresses

158 - from email.Utils import formataddr

159 - from email.Utils import formatdate

160 - from email.Header import Header

161 -

162 -

163 -DEBUG = False

164 -

165 -ZEROS = '0' * 40

166 -LOGBEGIN = '- Log -----------------------------------------------------------------\n'

167 -LOGEND = '-----------------------------------------------------------------------\n'

168 -

169 -ADDR_HEADERS = set(['from', 'to', 'cc', 'bcc', 'reply-to', 'sender'])

170 -

171 -# It is assumed in many places that the encoding is uniformly UTF-8,

172 -# so changing these constants is unsupported. But define them here

173 -# anyway, to make it easier to find (at least most of) the places

174 -# where the encoding is important.

175 -(ENCODING, CHARSET) = ('UTF-8', 'utf-8')

176 -

177 -

178 -REF_CREATED_SUBJECT_TEMPLATE = (

179 - '%(emailprefix)s%(refname_type)s %(short_refname)s created'

180 - ' (now %(newrev_short)s)'

181 - )

182 -REF_UPDATED_SUBJECT_TEMPLATE = (

183 - '%(emailprefix)s%(refname_type)s %(short_refname)s updated'

184 - ' (%(oldrev_short)s -> %(newrev_short)s)'

185 - )

186 -REF_DELETED_SUBJECT_TEMPLATE = (

187 - '%(emailprefix)s%(refname_type)s %(short_refname)s deleted'

188 - ' (was %(oldrev_short)s)'

189 - )

190 -

191 -COMBINED_REFCHANGE_REVISION_SUBJECT_TEMPLATE = (

192 - '%(emailprefix)s%(refname_type)s %(short_refname)s updated: %(oneline)s'

193 - )

194 -

195 -REFCHANGE_HEADER_TEMPLATE = """\

196 -Date: %(send_date)s

197 -To: %(recipients)s

198 -Subject: %(subject)s

199 -MIME-Version: 1.0

200 -Content-Type: text/%(contenttype)s; charset=%(charset)s

201 -Content-Transfer-Encoding: 8bit

202 -Message-ID: %(msgid)s

203 -From: %(fromaddr)s

204 -Reply-To: %(reply_to)s

205 -Thread-Index: %(thread_index)s

206 -X-Git-Host: %(fqdn)s

207 -X-Git-Repo: %(repo_shortname)s

208 -X-Git-Refname: %(refname)s

209 -X-Git-Reftype: %(refname_type)s

210 -X-Git-Oldrev: %(oldrev)s

211 -X-Git-Newrev: %(newrev)s

212 -X-Git-NotificationType: ref_changed

213 -X-Git-Multimail-Version: %(multimail_version)s

214 -Auto-Submitted: auto-generated

215 -"""

216 -

217 -REFCHANGE_INTRO_TEMPLATE = """\

218 -This is an automated email from the git hooks/post-receive script.

219 -

220 -%(pusher)s pushed a change to %(refname_type)s %(short_refname)s

221 -in repository %(repo_shortname)s.

222 -

223 -"""

224 -

225 -

226 -FOOTER_TEMPLATE = """\

227 -

228 -To stop receiving notification emails like this one, please contact

229 -%(administrator)s.

230 -"""

231 -

232 -

233 -REWIND_ONLY_TEMPLATE = """\

234 -This update removed existing revisions from the reference, leaving the

235 -reference pointing at a previous point in the repository history.

236 -

237 - * -- * -- N %(refname)s (%(newrev_short)s)

238 - \\

239 - O -- O -- O (%(oldrev_short)s)

240 -

241 -Any revisions marked "omit" are not gone; other references still

242 -refer to them. Any revisions marked "discard" are gone forever.

243 -"""

244 -

245 -

246 -NON_FF_TEMPLATE = """\

247 -This update added new revisions after undoing existing revisions.

248 -That is to say, some revisions that were in the old version of the

249 -%(refname_type)s are not in the new version. This situation occurs

250 -when a user --force pushes a change and generates a repository

251 -containing something like this:

252 -

253 - * -- * -- B -- O -- O -- O (%(oldrev_short)s)

254 - \\

255 - N -- N -- N %(refname)s (%(newrev_short)s)

256 -

257 -You should already have received notification emails for all of the O

258 -revisions, and so the following emails describe only the N revisions

259 -from the common base, B.

260 -

261 -Any revisions marked "omit" are not gone; other references still

262 -refer to them. Any revisions marked "discard" are gone forever.

263 -"""

264 -

265 -

266 -NO_NEW_REVISIONS_TEMPLATE = """\

267 -No new revisions were added by this update.

268 -"""

269 -

270 -

271 -DISCARDED_REVISIONS_TEMPLATE = """\

272 -This change permanently discards the following revisions:

273 -"""

274 -

275 -

276 -NO_DISCARDED_REVISIONS_TEMPLATE = """\

277 -The revisions that were on this %(refname_type)s are still contained in

278 -other references; therefore, this change does not discard any commits

279 -from the repository.

280 -"""

281 -

282 -

283 -NEW_REVISIONS_TEMPLATE = """\

284 -The %(tot)s revisions listed above as "new" are entirely new to this

285 -repository and will be described in separate emails. The revisions

286 -listed as "add" were already present in the repository and have only

287 -been added to this reference.

288 -

289 -"""

290 -

291 -

292 -TAG_CREATED_TEMPLATE = """\

293 - at %(newrev_short)-8s (%(newrev_type)s)

294 -"""

295 -

296 -

297 -TAG_UPDATED_TEMPLATE = """\

298 -*** WARNING: tag %(short_refname)s was modified! ***

299 -

300 - from %(oldrev_short)-8s (%(oldrev_type)s)

301 - to %(newrev_short)-8s (%(newrev_type)s)

302 -"""

303 -

304 -

305 -TAG_DELETED_TEMPLATE = """\

306 -*** WARNING: tag %(short_refname)s was deleted! ***

307 -

308 -"""

309 -

310 -

311 -# The template used in summary tables. It looks best if this uses the

312 -# same alignment as TAG_CREATED_TEMPLATE and TAG_UPDATED_TEMPLATE.

313 -BRIEF_SUMMARY_TEMPLATE = """\

314 -%(action)8s %(rev_short)-8s %(text)s

315 -"""

316 -

317 -

318 -NON_COMMIT_UPDATE_TEMPLATE = """\

319 -This is an unusual reference change because the reference did not

320 -refer to a commit either before or after the change. We do not know

321 -how to provide full information about this reference change.

322 -"""

323 -

324 -

325 -REVISION_HEADER_TEMPLATE = """\

326 -Date: %(send_date)s

327 -To: %(recipients)s

328 -Cc: %(cc_recipients)s

329 -Subject: %(emailprefix)s%(num)02d/%(tot)02d: %(oneline)s

330 -MIME-Version: 1.0

331 -Content-Type: text/%(contenttype)s; charset=%(charset)s

332 -Content-Transfer-Encoding: 8bit

333 -From: %(fromaddr)s

334 -Reply-To: %(reply_to)s

335 -In-Reply-To: %(reply_to_msgid)s

336 -References: %(reply_to_msgid)s

337 -Thread-Index: %(thread_index)s

338 -X-Git-Host: %(fqdn)s

339 -X-Git-Repo: %(repo_shortname)s

340 -X-Git-Refname: %(refname)s

341 -X-Git-Reftype: %(refname_type)s

342 -X-Git-Rev: %(rev)s

343 -X-Git-NotificationType: diff

344 -X-Git-Multimail-Version: %(multimail_version)s

345 -Auto-Submitted: auto-generated

346 -"""

347 -

348 -REVISION_INTRO_TEMPLATE = """\

349 -This is an automated email from the git hooks/post-receive script.

350 -

351 -%(pusher)s pushed a commit to %(refname_type)s %(short_refname)s

352 -in repository %(repo_shortname)s.

353 -

354 -"""

355 -

356 -LINK_TEXT_TEMPLATE = """\

357 -View the commit online:

358 -%(browse_url)s

359 -

360 -"""

361 -

362 -LINK_HTML_TEMPLATE = """\

363 -<a href="%(browse_url)s">View the commit online</a>.

364 -"""

365 -

366 -

367 -REVISION_FOOTER_TEMPLATE = FOOTER_TEMPLATE

368 -

369 -

370 -# Combined, meaning refchange+revision email (for single-commit additions)

371 -COMBINED_HEADER_TEMPLATE = """\

372 -Date: %(send_date)s

373 -To: %(recipients)s

374 -Subject: %(subject)s

375 -MIME-Version: 1.0

376 -Content-Type: text/%(contenttype)s; charset=%(charset)s

377 -Content-Transfer-Encoding: 8bit

378 -Message-ID: %(msgid)s

379 -From: %(fromaddr)s

380 -Reply-To: %(reply_to)s

381 -X-Git-Host: %(fqdn)s

382 -X-Git-Repo: %(repo_shortname)s

383 -X-Git-Refname: %(refname)s

384 -X-Git-Reftype: %(refname_type)s

385 -X-Git-Oldrev: %(oldrev)s

386 -X-Git-Newrev: %(newrev)s

387 -X-Git-Rev: %(rev)s

388 -X-Git-NotificationType: ref_changed_plus_diff

389 -X-Git-Multimail-Version: %(multimail_version)s

390 -Auto-Submitted: auto-generated

391 -"""

392 -

393 -COMBINED_INTRO_TEMPLATE = """\

394 -This is an automated email from the git hooks/post-receive script.

395 -

396 -%(pusher)s pushed a commit to %(refname_type)s %(short_refname)s

397 -in repository %(repo_shortname)s.

398 -

399 -"""

400 -

401 -COMBINED_FOOTER_TEMPLATE = FOOTER_TEMPLATE

402 -

403 -

404 -class CommandError(Exception):

405 - def __init__(self, cmd, retcode):

406 - self.cmd = cmd

407 - self.retcode = retcode

408 - Exception.__init__(

409 - self,

410 - 'Command "%s" failed with retcode %s' % (' '.join(cmd), retcode,)

411 - )

412 -

413 -

414 -class ConfigurationException(Exception):

415 - pass

416 -

417 -

418 -# The "git" program (this could be changed to include a full path):

419 -GIT_EXECUTABLE = 'git'

420 -

421 -

422 -# How "git" should be invoked (including global arguments), as a list

423 -# of words. This variable is usually initialized automatically by

424 -# read_git_output() via choose_git_command(), but if a value is set

425 -# here then it will be used unconditionally.

426 -GIT_CMD = None

427 -

428 -

429 -def choose_git_command():

430 - """Decide how to invoke git, and record the choice in GIT_CMD."""

431 -

432 - global GIT_CMD

433 -

434 - if GIT_CMD is None:

435 - try:

436 - # Check to see whether the "-c" option is accepted (it was

437 - # only added in Git 1.7.2). We don't actually use the

438 - # output of "git --version", though if we needed more

439 - # specific version information this would be the place to

440 - # do it.

441 - cmd = [GIT_EXECUTABLE, '-c', 'foo.bar=baz', '--version']

442 - read_output(cmd)

443 - GIT_CMD = [GIT_EXECUTABLE, '-c', 'i18n.logoutputencoding=%s' % (ENCODING,)]

444 - except CommandError:

445 - GIT_CMD = [GIT_EXECUTABLE]

446 -

447 -

448 -def read_git_output(args, input=None, keepends=False, **kw):

449 - """Read the output of a Git command."""

450 -

451 - if GIT_CMD is None:

452 - choose_git_command()

453 -

454 - return read_output(GIT_CMD + args, input=input, keepends=keepends, **kw)

455 -

456 -

457 -def read_output(cmd, input=None, keepends=False, **kw):

458 - if input:

459 - stdin = subprocess.PIPE

460 - input = str_to_bytes(input)

461 - else:

462 - stdin = None

463 - errors = 'strict'

464 - if 'errors' in kw:

465 - errors = kw['errors']

466 - del kw['errors']

467 - p = subprocess.Popen(

468 - tuple(str_to_bytes(w) for w in cmd),

469 - stdin=stdin, stdout=subprocess.PIPE, stderr=subprocess.PIPE, **kw

470 - )

471 - (out, err) = p.communicate(input)

472 - out = bytes_to_str(out, errors=errors)

473 - retcode = p.wait()

474 - if retcode:

475 - raise CommandError(cmd, retcode)

476 - if not keepends:

477 - out = out.rstrip('\n\r')

478 - return out

479 -

480 -

481 -def read_git_lines(args, keepends=False, **kw):

482 - """Return the lines output by Git command.

483 -

484 - Return as single lines, with newlines stripped off."""

485 -

486 - return read_git_output(args, keepends=True, **kw).splitlines(keepends)

487 -

488 -

489 -def git_rev_list_ish(cmd, spec, args=None, **kw):

490 - """Common functionality for invoking a 'git rev-list'-like command.

491 -

492 - Parameters:

493 - * cmd is the Git command to run, e.g., 'rev-list' or 'log'.

494 - * spec is a list of revision arguments to pass to the named

495 - command. If None, this function returns an empty list.

496 - * args is a list of extra arguments passed to the named command.

497 - * All other keyword arguments (if any) are passed to the

498 - underlying read_git_lines() function.

499 -

500 - Return the output of the Git command in the form of a list, one

501 - entry per output line.

502 - """

503 - if spec is None:

504 - return []

505 - if args is None:

506 - args = []

507 - args = [cmd, '--stdin'] + args

508 - spec_stdin = ''.join(s + '\n' for s in spec)

509 - return read_git_lines(args, input=spec_stdin, **kw)

510 -

511 -

512 -def git_rev_list(spec, **kw):

513 - """Run 'git rev-list' with the given list of revision arguments.

514 -

515 - See git_rev_list_ish() for parameter and return value

516 - documentation.

517 - """

518 - return git_rev_list_ish('rev-list', spec, **kw)

519 -

520 -

521 -def git_log(spec, **kw):

522 - """Run 'git log' with the given list of revision arguments.

523 -

524 - See git_rev_list_ish() for parameter and return value

525 - documentation.

526 - """

527 - return git_rev_list_ish('log', spec, **kw)

528 -

529 -

530 -def header_encode(text, header_name=None):

531 - """Encode and line-wrap the value of an email header field."""

532 -

533 - # Convert to unicode, if required.

534 - if not isinstance(text, unicode):

535 - text = unicode(text, 'utf-8')

536 -

537 - if is_ascii(text):

538 - charset = 'ascii'

539 - else:

540 - charset = 'utf-8'

541 -

542 - return Header(text, header_name=header_name, charset=Charset(charset)).encode()

543 -

544 -

545 -def addr_header_encode(text, header_name=None):

546 - """Encode and line-wrap the value of an email header field containing

547 - email addresses."""

548 -

549 - # Convert to unicode, if required.

550 - if not isinstance(text, unicode):

551 - text = unicode(text, 'utf-8')

552 -

553 - text = ', '.join(

554 - formataddr((header_encode(name), emailaddr))

555 - for name, emailaddr in getaddresses([text])

556 - )

557 -

558 - if is_ascii(text):

559 - charset = 'ascii'

560 - else:

561 - charset = 'utf-8'

562 -

563 - return Header(text, header_name=header_name, charset=Charset(charset)).encode()

564 -

565 -

566 -class Config(object):

567 - def __init__(self, section, git_config=None):

568 - """Represent a section of the git configuration.

569 -

570 - If git_config is specified, it is passed to "git config" in

571 - the GIT_CONFIG environment variable, meaning that "git config"

572 - will read the specified path rather than the Git default

573 - config paths."""

574 -

575 - self.section = section

576 - if git_config:

577 - self.env = os.environ.copy()

578 - self.env['GIT_CONFIG'] = git_config

579 - else:

580 - self.env = None

581 -

582 - @staticmethod

583 - def _split(s):

584 - """Split NUL-terminated values."""

585 -

586 - words = s.split('\0')

587 - assert words[-1] == ''

588 - return words[:-1]

589 -

590 - @staticmethod

591 - def add_config_parameters(c):

592 - """Add configuration parameters to Git.

593 -

594 - c is either an str or a list of str, each element being of the

595 - form 'var=val' or 'var', with the same syntax and meaning as

596 - the argument of 'git -c var=val'.

597 - """

598 - if isinstance(c, str):

599 - c = (c,)

600 - parameters = os.environ.get('GIT_CONFIG_PARAMETERS', '')

601 - if parameters:

602 - parameters += ' '

603 - # git expects GIT_CONFIG_PARAMETERS to be of the form

604 - # "'name1=value1' 'name2=value2' 'name3=value3'"

605 - # including everything inside the double quotes (but not the double

606 - # quotes themselves). Spacing is critical. Also, if a value contains

607 - # a literal single quote that quote must be represented using the

608 - # four character sequence: '\''

609 - parameters += ' '.join("'" + x.replace("'", "'\\''") + "'" for x in c)

610 - os.environ['GIT_CONFIG_PARAMETERS'] = parameters

611 -

612 - def get(self, name, default=None):

613 - try:

614 - values = self._split(read_git_output(

615 - ['config', '--get', '--null', '%s.%s' % (self.section, name)],

616 - env=self.env, keepends=True,

617 - ))

618 - assert len(values) == 1

619 - return values[0]

620 - except CommandError:

621 - return default

622 -

623 - def get_bool(self, name, default=None):

624 - try:

625 - value = read_git_output(

626 - ['config', '--get', '--bool', '%s.%s' % (self.section, name)],

627 - env=self.env,

628 - )

629 - except CommandError:

630 - return default

631 - return value == 'true'

632 -

633 - def get_all(self, name, default=None):

634 - """Read a (possibly multivalued) setting from the configuration.

635 -

636 - Return the result as a list of values, or default if the name

637 - is unset."""

638 -

639 - try:

640 - return self._split(read_git_output(

641 - ['config', '--get-all', '--null', '%s.%s' % (self.section, name)],

642 - env=self.env, keepends=True,

643 - ))

644 - except CommandError:

645 - t, e, traceback = sys.exc_info()

646 - if e.retcode == 1:

647 - # "the section or key is invalid"; i.e., there is no

648 - # value for the specified key.

649 - return default

650 - else:

651 - raise

652 -

653 - def set(self, name, value):

654 - read_git_output(

655 - ['config', '%s.%s' % (self.section, name), value],

656 - env=self.env,

657 - )

658 -

659 - def add(self, name, value):

660 - read_git_output(

661 - ['config', '--add', '%s.%s' % (self.section, name), value],

662 - env=self.env,

663 - )

664 -

665 - def __contains__(self, name):

666 - return self.get_all(name, default=None) is not None

667 -

668 - # We don't use this method anymore internally, but keep it here in

669 - # case somebody is calling it from their own code:

670 - def has_key(self, name):

671 - return name in self

672 -

673 - def unset_all(self, name):

674 - try:

675 - read_git_output(

676 - ['config', '--unset-all', '%s.%s' % (self.section, name)],

677 - env=self.env,

678 - )

679 - except CommandError:

680 - t, e, traceback = sys.exc_info()

681 - if e.retcode == 5:

682 - # The name doesn't exist, which is what we wanted anyway...

683 - pass

684 - else:

685 - raise

686 -

687 - def set_recipients(self, name, value):

688 - self.unset_all(name)

689 - for pair in getaddresses([value]):

690 - self.add(name, formataddr(pair))

691 -

692 -

693 -def generate_summaries(*log_args):

694 - """Generate a brief summary for each revision requested.

695 -

696 - log_args are strings that will be passed directly to "git log" as

697 - revision selectors. Iterate over (sha1_short, subject) for each

698 - commit specified by log_args (subject is the first line of the

699 - commit message as a string without EOLs)."""

700 -

701 - cmd = [

702 - 'log', '--abbrev', '--format=%h %s',

703 - ] + list(log_args) + ['--']

704 - for line in read_git_lines(cmd):

705 - yield tuple(line.split(' ', 1))

706 -

707 -

708 -def limit_lines(lines, max_lines):

709 - for (index, line) in enumerate(lines):

710 - if index < max_lines:

711 - yield line

712 -

713 - if index >= max_lines:

714 - yield '... %d lines suppressed ...\n' % (index + 1 - max_lines,)

715 -

716 -

717 -def limit_linelength(lines, max_linelength):

718 - for line in lines:

719 - # Don't forget that lines always include a trailing newline.

720 - if len(line) > max_linelength + 1:

721 - line = line[:max_linelength - 7] + ' [...]\n'

722 - yield line

723 -

724 -

725 -class CommitSet(object):

726 - """A (constant) set of object names.

727 -

728 - The set should be initialized with full SHA1 object names. The

729 - __contains__() method returns True iff its argument is an

730 - abbreviation of any the names in the set."""

731 -

732 - def __init__(self, names):

733 - self._names = sorted(names)

734 -

735 - def __len__(self):

736 - return len(self._names)

737 -

738 - def __contains__(self, sha1_abbrev):

739 - """Return True iff this set contains sha1_abbrev (which might be abbreviated)."""

740 -

741 - i = bisect.bisect_left(self._names, sha1_abbrev)

742 - return i < len(self) and self._names[i].startswith(sha1_abbrev)

743 -

744 -

745 -class GitObject(object):

746 - def __init__(self, sha1, type=None):

747 - if sha1 == ZEROS:

748 - self.sha1 = self.type = self.commit_sha1 = None

749 - else:

750 - self.sha1 = sha1

751 - self.type = type or read_git_output(['cat-file', '-t', self.sha1])

752 -

753 - if self.type == 'commit':

754 - self.commit_sha1 = self.sha1

755 - elif self.type == 'tag':

756 - try:

757 - self.commit_sha1 = read_git_output(

758 - ['rev-parse', '--verify', '%s^0' % (self.sha1,)]

759 - )

760 - except CommandError:

761 - # Cannot deref tag to determine commit_sha1

762 - self.commit_sha1 = None

763 - else:

764 - self.commit_sha1 = None

765 -

766 - self.short = read_git_output(['rev-parse', '--short', sha1])

767 -

768 - def get_summary(self):

769 - """Return (sha1_short, subject) for this commit."""

770 -

771 - if not self.sha1:

772 - raise ValueError('Empty commit has no summary')

773 -

774 - return next(iter(generate_summaries('--no-walk', self.sha1)))

775 -

776 - def __eq__(self, other):

777 - return isinstance(other, GitObject) and self.sha1 == other.sha1

778 -

779 - def __ne__(self, other):

780 - return not self == other

781 -

782 - def __hash__(self):

783 - return hash(self.sha1)

784 -

785 - def __nonzero__(self):

786 - return bool(self.sha1)

787 -

788 - def __bool__(self):

789 - """Python 2 backward compatibility"""

790 - return self.__nonzero__()

791 -

792 - def __str__(self):

793 - return self.sha1 or ZEROS

794 -

795 -

796 -class Change(object):

797 - """A Change that has been made to the Git repository.

798 -

799 - Abstract class from which both Revisions and ReferenceChanges are

800 - derived. A Change knows how to generate a notification email

801 - describing itself."""

802 -

803 - def __init__(self, environment):

804 - self.environment = environment

805 - self._values = None

806 - self._contains_html_diff = False

807 -

808 - def _contains_diff(self):

809 - # We do contain a diff, should it be rendered in HTML?

810 - if self.environment.commit_email_format == "html":

811 - self._contains_html_diff = True

812 -

813 - def _compute_values(self):

814 - """Return a dictionary {keyword: expansion} for this Change.

815 -

816 - Derived classes overload this method to add more entries to

817 - the return value. This method is used internally by

818 - get_values(). The return value should always be a new

819 - dictionary."""

820 -

821 - values = self.environment.get_values()

822 - fromaddr = self.environment.get_fromaddr(change=self)

823 - if fromaddr is not None:

824 - values['fromaddr'] = fromaddr

825 - values['multimail_version'] = get_version()

826 - return values

827 -

828 - # Aliases usable in template strings. Tuple of pairs (destination,

829 - # source).

830 - VALUES_ALIAS = (

831 - ("id", "newrev"),

832 - )

833 -

834 - def get_values(self, **extra_values):

835 - """Return a dictionary {keyword: expansion} for this Change.

836 -

837 - Return a dictionary mapping keywords to the values that they

838 - should be expanded to for this Change (used when interpolating

839 - template strings). If any keyword arguments are supplied, add

840 - those to the return value as well. The return value is always

841 - a new dictionary."""

842 -

843 - if self._values is None:

844 - self._values = self._compute_values()

845 -

846 - values = self._values.copy()

847 - if extra_values:

848 - values.update(extra_values)

849 -

850 - for alias, val in self.VALUES_ALIAS:

851 - values[alias] = values[val]

852 - return values

853 -

854 - def expand(self, template, **extra_values):

855 - """Expand template.

856 -

857 - Expand the template (which should be a string) using string

858 - interpolation of the values for this Change. If any keyword

859 - arguments are provided, also include those in the keywords

860 - available for interpolation."""

861 -

862 - return template % self.get_values(**extra_values)

863 -

864 - def expand_lines(self, template, html_escape_val=False, **extra_values):

865 - """Break template into lines and expand each line."""

866 -

867 - values = self.get_values(**extra_values)

868 - if html_escape_val:

869 - for k in values:

870 - if is_string(values[k]):

871 - values[k] = html_escape(values[k])

872 - for line in template.splitlines(True):

873 - yield line % values

874 -

875 - def expand_header_lines(self, template, **extra_values):

876 - """Break template into lines and expand each line as an RFC 2822 header.

877 -

878 - Encode values and split up lines that are too long. Silently

879 - skip lines that contain references to unknown variables."""

880 -

881 - values = self.get_values(**extra_values)

882 - if self._contains_html_diff:

883 - self._content_type = 'html'

884 - else:

885 - self._content_type = 'plain'

886 - values['contenttype'] = self._content_type

887 -

888 - for line in template.splitlines():

889 - (name, value) = line.split(': ', 1)

890 -

891 - try:

892 - value = value % values

893 - except KeyError:

894 - t, e, traceback = sys.exc_info()

895 - if DEBUG:

896 - self.environment.log_warning(

897 - 'Warning: unknown variable %r in the following line; line skipped:\n'

898 - ' %s\n'

899 - % (e.args[0], line,)

900 - )

901 - else:

902 - if name.lower() in ADDR_HEADERS:

903 - value = addr_header_encode(value, name)

904 - else:

905 - value = header_encode(value, name)

906 - for splitline in ('%s: %s\n' % (name, value)).splitlines(True):

907 - yield splitline

908 -

909 - def generate_email_header(self):

910 - """Generate the RFC 2822 email headers for this Change, a line at a time.

911 -

912 - The output should not include the trailing blank line."""

913 -

914 - raise NotImplementedError()

915 -

916 - def generate_browse_link(self, base_url):

917 - """Generate a link to an online repository browser."""

918 - return iter(())

919 -

920 - def generate_email_intro(self, html_escape_val=False):

921 - """Generate the email intro for this Change, a line at a time.

922 -

923 - The output will be used as the standard boilerplate at the top

924 - of the email body."""

925 -

926 - raise NotImplementedError()

927 -

928 - def generate_email_body(self, push):

929 - """Generate the main part of the email body, a line at a time.

930 -

931 - The text in the body might be truncated after a specified

932 - number of lines (see multimailhook.emailmaxlines)."""

933 -

934 - raise NotImplementedError()

935 -

936 - def generate_email_footer(self, html_escape_val):

937 - """Generate the footer of the email, a line at a time.

938 -

939 - The footer is always included, irrespective of

940 - multimailhook.emailmaxlines."""

941 -

942 - raise NotImplementedError()

943 -

944 - def _wrap_for_html(self, lines):

945 - """Wrap the lines in HTML <pre> tag when using HTML format.

946 -

947 - Escape special HTML characters and add <pre> and </pre> tags around

948 - the given lines if we should be generating HTML as indicated by

949 - self._contains_html_diff being set to true.

950 - """

951 - if self._contains_html_diff:

952 - yield "<pre style='margin:0'>\n"

953 -

954 - for line in lines:

955 - yield html_escape(line)

956 -

957 - yield '</pre>\n'

958 - else:

959 - for line in lines:

960 - yield line

961 -

962 - def generate_email(self, push, body_filter=None, extra_header_values={}):

963 - """Generate an email describing this change.

964 -

965 - Iterate over the lines (including the header lines) of an

966 - email describing this change. If body_filter is not None,

967 - then use it to filter the lines that are intended for the

968 - email body.

969 -

970 - The extra_header_values field is received as a dict and not as

971 - **kwargs, to allow passing other keyword arguments in the

972 - future (e.g. passing extra values to generate_email_intro()"""

973 -

974 - for line in self.generate_email_header(**extra_header_values):

975 - yield line

976 - yield '\n'

977 - html_escape_val = (self.environment.html_in_intro and

978 - self._contains_html_diff)

979 - intro = self.generate_email_intro(html_escape_val)

980 - if not self.environment.html_in_intro:

981 - intro = self._wrap_for_html(intro)

982 - for line in intro:

983 - yield line

984 -

985 - if self.environment.commitBrowseURL:

986 - for line in self.generate_browse_link(self.environment.commitBrowseURL):

987 - yield line

988 -

989 - body = self.generate_email_body(push)

990 - if body_filter is not None:

991 - body = body_filter(body)

992 -

993 - diff_started = False

994 - if self._contains_html_diff:

995 - # "white-space: pre" is the default, but we need to

996 - # specify it again in case the message is viewed in a

997 - # webmail which wraps it in an element setting white-space

998 - # to something else (Zimbra does this and sets

999 - # white-space: pre-line).

1000 - yield '<pre style="white-space: pre; background: #F8F8F8">'

1001 - for line in body:

1002 - if self._contains_html_diff:

1003 - # This is very, very naive. It would be much better to really

1004 - # parse the diff, i.e. look at how many lines do we have in

1005 - # the hunk headers instead of blindly highlighting everything

1006 - # that looks like it might be part of a diff.

1007 - bgcolor = ''

1008 - fgcolor = ''

1009 - if line.startswith('--- a/'):

1010 - diff_started = True

1011 - bgcolor = 'e0e0ff'

1012 - elif line.startswith('diff ') or line.startswith('index '):

1013 - diff_started = True

1014 - fgcolor = '808080'

1015 - elif diff_started:

1016 - if line.startswith('+++ '):

1017 - bgcolor = 'e0e0ff'

1018 - elif line.startswith('@@'):

1019 - bgcolor = 'e0e0e0'

1020 - elif line.startswith('+'):

1021 - bgcolor = 'e0ffe0'

1022 - elif line.startswith('-'):

1023 - bgcolor = 'ffe0e0'

1024 - elif line.startswith('commit '):

1025 - fgcolor = '808000'

1026 - elif line.startswith(' '):

1027 - fgcolor = '404040'

1028 -

1029 - # Chop the trailing LF, we don't want it inside <pre>.

1030 - line = html_escape(line[:-1])

1031 -

1032 - if bgcolor or fgcolor:

1033 - style = 'display:block; white-space:pre;'

1034 - if bgcolor:

1035 - style += 'background:#' + bgcolor + ';'

1036 - if fgcolor:

1037 - style += 'color:#' + fgcolor + ';'

1038 - # Use a to color the

1039 - # whole line. The newline must be inside the span

1040 - # to display properly both in Firefox and in

1041 - # text-based browser.

1042 - line = "%s\n" % (style, line)

1043 - else:

1044 - line = line + '\n'

1045 -

1046 - yield line

1047 - if self._contains_html_diff:

1048 - yield '</pre>'

1049 - html_escape_val = (self.environment.html_in_footer and

1050 - self._contains_html_diff)

1051 - footer = self.generate_email_footer(html_escape_val)

1052 - if not self.environment.html_in_footer:

1053 - footer = self._wrap_for_html(footer)

1054 - for line in footer:

1055 - yield line

1056 -

1057 - def get_specific_fromaddr(self):

1058 - """For kinds of Changes which specify it, return the kind-specific

1059 - From address to use."""

1060 - return None

1061 -

1062 -

1063 -class Revision(Change):

1064 - """A Change consisting of a single git commit."""

1065 -

1066 - CC_RE = re.compile(r'^\s*C[Cc]:\s*(?P<to>[^#]+@[^\s#]*)\s*(#.*)?$')

1067 -

1068 - def __init__(self, reference_change, rev, num, tot):

1069 - Change.__init__(self, reference_change.environment)

1070 - self.reference_change = reference_change

1071 - self.rev = rev

1072 - self.change_type = self.reference_change.change_type

1073 - self.refname = self.reference_change.refname

1074 - self.num = num

1075 - self.tot = tot

1076 - self.author = read_git_output(['log', '--no-walk', '--format=%aN <%aE>', self.rev.sha1])

1077 - self.recipients = self.environment.get_revision_recipients(self)

1078 -

1079 - # -s is short for --no-patch, but -s works on older git's (e.g. 1.7)

1080 - self.parents = read_git_lines(['show', '-s', '--format=%P',

1081 - self.rev.sha1])[0].split()

1082 -

1083 - self.cc_recipients = ''

1084 - if self.environment.get_scancommitforcc():

1085 - self.cc_recipients = ', '.join(to.strip() for to in self._cc_recipients())

1086 - if self.cc_recipients:

1087 - self.environment.log_msg(

1088 - 'Add %s to CC for %s' % (self.cc_recipients, self.rev.sha1))

1089 -

1090 - def _cc_recipients(self):

1091 - cc_recipients = []

1092 - message = read_git_output(['log', '--no-walk', '--format=%b', self.rev.sha1])

1093 - lines = message.strip().split('\n')

1094 - for line in lines:

1095 - m = re.match(self.CC_RE, line)

1096 - if m:

1097 - cc_recipients.append(m.group('to'))

1098 -

1099 - return cc_recipients

1100 -

1101 - def _compute_values(self):

1102 - values = Change._compute_values(self)

1103 -

1104 - oneline = read_git_output(

1105 - ['log', '--format=%s', '--no-walk', self.rev.sha1]

1106 - )

1107 -

1108 - max_subject_length = self.environment.get_max_subject_length()

1109 - if max_subject_length > 0 and len(oneline) > max_subject_length:

1110 - oneline = oneline[:max_subject_length - 6] + ' [...]'

1111 -

1112 - values['rev'] = self.rev.sha1

1113 - values['parents'] = ' '.join(self.parents)

1114 - values['rev_short'] = self.rev.short

1115 - values['change_type'] = self.change_type

1116 - values['refname'] = self.refname

1117 - values['newrev'] = self.rev.sha1

1118 - values['short_refname'] = self.reference_change.short_refname

1119 - values['refname_type'] = self.reference_change.refname_type

1120 - values['reply_to_msgid'] = self.reference_change.msgid

1121 - values['thread_index'] = self.reference_change.thread_index

1122 - values['num'] = self.num

1123 - values['tot'] = self.tot

1124 - values['recipients'] = self.recipients

1125 - if self.cc_recipients:

1126 - values['cc_recipients'] = self.cc_recipients

1127 - values['oneline'] = oneline

1128 - values['author'] = self.author

1129 -

1130 - reply_to = self.environment.get_reply_to_commit(self)

1131 - if reply_to:

1132 - values['reply_to'] = reply_to

1133 -

1134 - return values

1135 -

1136 - def generate_email_header(self, **extra_values):

1137 - for line in self.expand_header_lines(

1138 - REVISION_HEADER_TEMPLATE, **extra_values

1139 - ):

1140 - yield line

1141 -

1142 - def generate_browse_link(self, base_url):

1143 - if '%(' not in base_url:

1144 - base_url += '%(id)s'

1145 - url = "".join(self.expand_lines(base_url))

1146 - if self._content_type == 'html':

1147 - for line in self.expand_lines(LINK_HTML_TEMPLATE,

1148 - html_escape_val=True,

1149 - browse_url=url):

1150 - yield line

1151 - elif self._content_type == 'plain':

1152 - for line in self.expand_lines(LINK_TEXT_TEMPLATE,

1153 - html_escape_val=False,

1154 - browse_url=url):

1155 - yield line

1156 - else:

1157 - raise NotImplementedError("Content-type %s unsupported. Please report it as a bug.")

1158 -

1159 - def generate_email_intro(self, html_escape_val=False):

1160 - for line in self.expand_lines(REVISION_INTRO_TEMPLATE,

1161 - html_escape_val=html_escape_val):

1162 - yield line

1163 -

1164 - def generate_email_body(self, push):

1165 - """Show this revision."""

1166 -

1167 - for line in read_git_lines(

1168 - ['log'] + self.environment.commitlogopts + ['-1', self.rev.sha1],

1169 - keepends=True,

1170 - errors='replace'):

1171 - if line.startswith('Date: ') and self.environment.date_substitute:

1172 - yield self.environment.date_substitute + line[len('Date: '):]

1173 - else:

1174 - yield line

1175 -

1176 - def generate_email_footer(self, html_escape_val):

1177 - return self.expand_lines(REVISION_FOOTER_TEMPLATE,

1178 - html_escape_val=html_escape_val)

1179 -

1180 - def generate_email(self, push, body_filter=None, extra_header_values={}):

1181 - self._contains_diff()

1182 - return Change.generate_email(self, push, body_filter, extra_header_values)

1183 -

1184 - def get_specific_fromaddr(self):

1185 - return self.environment.from_commit

1186 -

1187 -

1188 -class ReferenceChange(Change):

1189 - """A Change to a Git reference.

1190 -

1191 - An abstract class representing a create, update, or delete of a

1192 - Git reference. Derived classes handle specific types of reference

1193 - (e.g., tags vs. branches). These classes generate the main

1194 - reference change email summarizing the reference change and

1195 - whether it caused any any commits to be added or removed.

1196 -

1197 - ReferenceChange objects are usually created using the static

1198 - create() method, which has the logic to decide which derived class

1199 - to instantiate."""

1200 -

1201 - REF_RE = re.compile(r'^refs\/(?P<area>[^\/]+)\/(?P<shortname>.*)$')

1202 -

1203 - @staticmethod

1204 - def create(environment, oldrev, newrev, refname):

1205 - """Return a ReferenceChange object representing the change.

1206 -

1207 - Return an object that represents the type of change that is being

1208 - made. oldrev and newrev should be SHA1s or ZEROS."""

1209 -

1210 - old = GitObject(oldrev)

1211 - new = GitObject(newrev)

1212 - rev = new or old

1213 -

1214 - # The revision type tells us what type the commit is, combined with

1215 - # the location of the ref we can decide between

1216 - # - working branch

1217 - # - tracking branch

1218 - # - unannotated tag

1219 - # - annotated tag

1220 - m = ReferenceChange.REF_RE.match(refname)

1221 - if m:

1222 - area = m.group('area')

1223 - short_refname = m.group('shortname')

1224 - else:

1225 - area = ''

1226 - short_refname = refname

1227 -

1228 - if rev.type == 'tag':

1229 - # Annotated tag:

1230 - klass = AnnotatedTagChange

1231 - elif rev.type == 'commit':

1232 - if area == 'tags':

1233 - # Non-annotated tag:

1234 - klass = NonAnnotatedTagChange

1235 - elif area == 'heads':

1236 - # Branch:

1237 - klass = BranchChange

1238 - elif area == 'remotes':

1239 - # Tracking branch:

1240 - environment.log_warning(

1241 - '*** Push-update of tracking branch %r\n'

1242 - '*** - incomplete email generated.'

1243 - % (refname,)

1244 - )

1245 - klass = OtherReferenceChange

1246 - else:

1247 - # Some other reference namespace:

1248 - environment.log_warning(

1249 - '*** Push-update of strange reference %r\n'

1250 - '*** - incomplete email generated.'

1251 - % (refname,)

1252 - )

1253 - klass = OtherReferenceChange

1254 - else:

1255 - # Anything else (is there anything else?)

1256 - environment.log_warning(

1257 - '*** Unknown type of update to %r (%s)\n'

1258 - '*** - incomplete email generated.'

1259 - % (refname, rev.type,)

1260 - )

1261 - klass = OtherReferenceChange

1262 -

1263 - return klass(

1264 - environment,

1265 - refname=refname, short_refname=short_refname,

1266 - old=old, new=new, rev=rev,

1267 - )

1268 -

1269 - @staticmethod

1270 - def make_thread_index():

1271 - """Return a string appropriate for the Thread-Index header,

1272 - needed by MS Outlook to get threading right.

1273 -

1274 - The format is (base64-encoded):

1275 - - 1 byte must be 1

1276 - - 5 bytes encode a date (hardcoded here)

1277 - - 16 bytes for a globally unique identifier

1278 -

1279 - FIXME: Unfortunately, even with the Thread-Index field, MS

1280 - Outlook doesn't seem to do the threading reliably (see

1281 - https://github.com/git-multimail/git-multimail/pull/194).

1282 - """

1283 - thread_index = b'\x01\x00\x00\x12\x34\x56' + uuid.uuid4().bytes

1284 - return base64.standard_b64encode(thread_index).decode('ascii')

1285 -

1286 - def __init__(self, environment, refname, short_refname, old, new, rev):

1287 - Change.__init__(self, environment)

1288 - self.change_type = {

1289 - (False, True): 'create',

1290 - (True, True): 'update',

1291 - (True, False): 'delete',

1292 - }[bool(old), bool(new)]

1293 - self.refname = refname

1294 - self.short_refname = short_refname

1295 - self.old = old

1296 - self.new = new

1297 - self.rev = rev

1298 - self.msgid = make_msgid()

1299 - self.thread_index = self.make_thread_index()

1300 - self.diffopts = environment.diffopts

1301 - self.graphopts = environment.graphopts

1302 - self.logopts = environment.logopts

1303 - self.commitlogopts = environment.commitlogopts

1304 - self.showgraph = environment.refchange_showgraph

1305 - self.showlog = environment.refchange_showlog

1306 -

1307 - self.header_template = REFCHANGE_HEADER_TEMPLATE

1308 - self.intro_template = REFCHANGE_INTRO_TEMPLATE

1309 - self.footer_template = FOOTER_TEMPLATE

1310 -

1311 - def _compute_values(self):

1312 - values = Change._compute_values(self)

1313 -

1314 - values['change_type'] = self.change_type

1315 - values['refname_type'] = self.refname_type

1316 - values['refname'] = self.refname

1317 - values['short_refname'] = self.short_refname

1318 - values['msgid'] = self.msgid

1319 - values['thread_index'] = self.thread_index

1320 - values['recipients'] = self.recipients

1321 - values['oldrev'] = str(self.old)

1322 - values['oldrev_short'] = self.old.short

1323 - values['newrev'] = str(self.new)

1324 - values['newrev_short'] = self.new.short

1325 -

1326 - if self.old:

1327 - values['oldrev_type'] = self.old.type

1328 - if self.new:

1329 - values['newrev_type'] = self.new.type

1330 -

1331 - reply_to = self.environment.get_reply_to_refchange(self)

1332 - if reply_to:

1333 - values['reply_to'] = reply_to

1334 -

1335 - return values

1336 -

1337 - def send_single_combined_email(self, known_added_sha1s):

1338 - """Determine if a combined refchange/revision email should be sent

1339 -

1340 - If there is only a single new (non-merge) commit added by a

1341 - change, it is useful to combine the ReferenceChange and

1342 - Revision emails into one. In such a case, return the single

1343 - revision; otherwise, return None.

1344 -

1345 - This method is overridden in BranchChange."""

1346 -

1347 - return None

1348 -

1349 - def generate_combined_email(self, push, revision, body_filter=None, extra_header_values={}):

1350 - """Generate an email describing this change AND specified revision.

1351 -

1352 - Iterate over the lines (including the header lines) of an

1353 - email describing this change. If body_filter is not None,

1354 - then use it to filter the lines that are intended for the

1355 - email body.

1356 -

1357 - The extra_header_values field is received as a dict and not as

1358 - **kwargs, to allow passing other keyword arguments in the

1359 - future (e.g. passing extra values to generate_email_intro()

1360 -

1361 - This method is overridden in BranchChange."""

1362 -

1363 - raise NotImplementedError

1364 -

1365 - def get_subject(self):

1366 - template = {

1367 - 'create': REF_CREATED_SUBJECT_TEMPLATE,

1368 - 'update': REF_UPDATED_SUBJECT_TEMPLATE,

1369 - 'delete': REF_DELETED_SUBJECT_TEMPLATE,

1370 - }[self.change_type]

1371 - return self.expand(template)

1372 -

1373 - def generate_email_header(self, **extra_values):

1374 - if 'subject' not in extra_values:

1375 - extra_values['subject'] = self.get_subject()

1376 -

1377 - for line in self.expand_header_lines(

1378 - self.header_template, **extra_values

1379 - ):

1380 - yield line

1381 -

1382 - def generate_email_intro(self, html_escape_val=False):

1383 - for line in self.expand_lines(self.intro_template,

1384 - html_escape_val=html_escape_val):

1385 - yield line

1386 -

1387 - def generate_email_body(self, push):

1388 - """Call the appropriate body-generation routine.

1389 -

1390 - Call one of generate_create_summary() /

1391 - generate_update_summary() / generate_delete_summary()."""

1392 -

1393 - change_summary = {

1394 - 'create': self.generate_create_summary,

1395 - 'delete': self.generate_delete_summary,

1396 - 'update': self.generate_update_summary,

1397 - }[self.change_type](push)

1398 - for line in change_summary:

1399 - yield line

1400 -

1401 - for line in self.generate_revision_change_summary(push):

1402 - yield line

1403 -

1404 - def generate_email_footer(self, html_escape_val):

1405 - return self.expand_lines(self.footer_template,

1406 - html_escape_val=html_escape_val)

1407 -

1408 - def generate_revision_change_graph(self, push):

1409 - if self.showgraph:

1410 - args = ['--graph'] + self.graphopts

1411 - for newold in ('new', 'old'):

1412 - has_newold = False

1413 - spec = push.get_commits_spec(newold, self)

1414 - for line in git_log(spec, args=args, keepends=True):

1415 - if not has_newold:

1416 - has_newold = True

1417 - yield '\n'

1418 - yield 'Graph of %s commits:\n\n' % (

1419 - {'new': 'new', 'old': 'discarded'}[newold],)

1420 - yield ' ' + line

1421 - if has_newold:

1422 - yield '\n'

1423 -

1424 - def generate_revision_change_log(self, new_commits_list):

1425 - if self.showlog:

1426 - yield '\n'

1427 - yield 'Detailed log of new commits:\n\n'

1428 - for line in read_git_lines(

1429 - ['log', '--no-walk'] +

1430 - self.logopts +

1431 - new_commits_list +

1432 - ['--'],

1433 - keepends=True,

1434 - ):

1435 - yield line

1436 -

1437 - def generate_new_revision_summary(self, tot, new_commits_list, push):

1438 - for line in self.expand_lines(NEW_REVISIONS_TEMPLATE, tot=tot):

1439 - yield line

1440 - for line in self.generate_revision_change_graph(push):

1441 - yield line

1442 - for line in self.generate_revision_change_log(new_commits_list):

1443 - yield line

1444 -

1445 - def generate_revision_change_summary(self, push):

1446 - """Generate a summary of the revisions added/removed by this change."""

1447 -

1448 - if self.new.commit_sha1 and not self.old.commit_sha1:

1449 - # A new reference was created. List the new revisions

1450 - # brought by the new reference (i.e., those revisions that

1451 - # were not in the repository before this reference

1452 - # change).

1453 - sha1s = list(push.get_new_commits(self))

1454 - sha1s.reverse()

1455 - tot = len(sha1s)

1456 - new_revisions = [

1457 - Revision(self, GitObject(sha1), num=i + 1, tot=tot)

1458 - for (i, sha1) in enumerate(sha1s)

1459 - ]

1460 -

1461 - if new_revisions:

1462 - yield self.expand('This %(refname_type)s includes the following new commits:\n')

1463 - yield '\n'

1464 - for r in new_revisions:

1465 - (sha1, subject) = r.rev.get_summary()

1466 - yield r.expand(

1467 - BRIEF_SUMMARY_TEMPLATE, action='new', text=subject,

1468 - )

1469 - yield '\n'

1470 - for line in self.generate_new_revision_summary(

1471 - tot, [r.rev.sha1 for r in new_revisions], push):

1472 - yield line

1473 - else:

1474 - for line in self.expand_lines(NO_NEW_REVISIONS_TEMPLATE):

1475 - yield line

1476 -

1477 - elif self.new.commit_sha1 and self.old.commit_sha1:

1478 - # A reference was changed to point at a different commit.

1479 - # List the revisions that were removed and/or added *from

1480 - # that reference* by this reference change, along with a

1481 - # diff between the trees for its old and new values.

1482 -

1483 - # List of the revisions that were added to the branch by

1484 - # this update. Note this list can include revisions that

1485 - # have already had notification emails; we want such

1486 - # revisions in the summary even though we will not send

1487 - # new notification emails for them.

1488 - adds = list(generate_summaries(

1489 - '--topo-order', '--reverse', '%s..%s'

1490 - % (self.old.commit_sha1, self.new.commit_sha1,)

1491 - ))

1492 -

1493 - # List of the revisions that were removed from the branch

1494 - # by this update. This will be empty except for

1495 - # non-fast-forward updates.

1496 - discards = list(generate_summaries(

1497 - '%s..%s' % (self.new.commit_sha1, self.old.commit_sha1,)

1498 - ))

1499 -

1500 - if adds:

1501 - new_commits_list = push.get_new_commits(self)

1502 - else:

1503 - new_commits_list = []

1504 - new_commits = CommitSet(new_commits_list)

1505 -

1506 - if discards:

1507 - discarded_commits = CommitSet(push.get_discarded_commits(self))

1508 - else:

1509 - discarded_commits = CommitSet([])

1510 -

1511 - if discards and adds:

1512 - for (sha1, subject) in discards:

1513 - if sha1 in discarded_commits:

1514 - action = 'discard'

1515 - else:

1516 - action = 'omit'

1517 - yield self.expand(

1518 - BRIEF_SUMMARY_TEMPLATE, action=action,

1519 - rev_short=sha1, text=subject,

1520 - )

1521 - for (sha1, subject) in adds:

1522 - if sha1 in new_commits:

1523 - action = 'new'

1524 - else:

1525 - action = 'add'

1526 - yield self.expand(

1527 - BRIEF_SUMMARY_TEMPLATE, action=action,

1528 - rev_short=sha1, text=subject,

1529 - )

1530 - yield '\n'

1531 - for line in self.expand_lines(NON_FF_TEMPLATE):

1532 - yield line

1533 -

1534 - elif discards:

1535 - for (sha1, subject) in discards:

1536 - if sha1 in discarded_commits:

1537 - action = 'discard'

1538 - else:

1539 - action = 'omit'

1540 - yield self.expand(

1541 - BRIEF_SUMMARY_TEMPLATE, action=action,

1542 - rev_short=sha1, text=subject,

1543 - )

1544 - yield '\n'

1545 - for line in self.expand_lines(REWIND_ONLY_TEMPLATE):

1546 - yield line

1547 -

1548 - elif adds:

1549 - (sha1, subject) = self.old.get_summary()

1550 - yield self.expand(

1551 - BRIEF_SUMMARY_TEMPLATE, action='from',

1552 - rev_short=sha1, text=subject,

1553 - )

1554 - for (sha1, subject) in adds:

1555 - if sha1 in new_commits:

1556 - action = 'new'

1557 - else:

1558 - action = 'add'

1559 - yield self.expand(

1560 - BRIEF_SUMMARY_TEMPLATE, action=action,

1561 - rev_short=sha1, text=subject,

1562 - )

1563 -

1564 - yield '\n'

1565 -

1566 - if new_commits:

1567 - for line in self.generate_new_revision_summary(

1568 - len(new_commits), new_commits_list, push):

1569 - yield line

1570 - else:

1571 - for line in self.expand_lines(NO_NEW_REVISIONS_TEMPLATE):

1572 - yield line

1573 - for line in self.generate_revision_change_graph(push):

1574 - yield line

1575 -

1576 - # The diffstat is shown from the old revision to the new

1577 - # revision. This is to show the truth of what happened in

1578 - # this change. There's no point showing the stat from the

1579 - # base to the new revision because the base is effectively a

1580 - # random revision at this point - the user will be interested

1581 - # in what this revision changed - including the undoing of

1582 - # previous revisions in the case of non-fast-forward updates.

1583 - yield '\n'

1584 - yield 'Summary of changes:\n'

1585 - for line in read_git_lines(

1586 - ['diff-tree'] +

1587 - self.diffopts +

1588 - ['%s..%s' % (self.old.commit_sha1, self.new.commit_sha1,)],

1589 - keepends=True,

1590 - ):

1591 - yield line

1592 -

1593 - elif self.old.commit_sha1 and not self.new.commit_sha1:

1594 - # A reference was deleted. List the revisions that were

1595 - # removed from the repository by this reference change.

1596 -

1597 - sha1s = list(push.get_discarded_commits(self))

1598 - tot = len(sha1s)

1599 - discarded_revisions = [

1600 - Revision(self, GitObject(sha1), num=i + 1, tot=tot)

1601 - for (i, sha1) in enumerate(sha1s)

1602 - ]

1603 -

1604 - if discarded_revisions:

1605 - for line in self.expand_lines(DISCARDED_REVISIONS_TEMPLATE):

1606 - yield line

1607 - yield '\n'

1608 - for r in discarded_revisions:

1609 - (sha1, subject) = r.rev.get_summary()

1610 - yield r.expand(

1611 - BRIEF_SUMMARY_TEMPLATE, action='discard', text=subject,

1612 - )

1613 - for line in self.generate_revision_change_graph(push):

1614 - yield line

1615 - else:

1616 - for line in self.expand_lines(NO_DISCARDED_REVISIONS_TEMPLATE):

1617 - yield line

1618 -

1619 - elif not self.old.commit_sha1 and not self.new.commit_sha1:

1620 - for line in self.expand_lines(NON_COMMIT_UPDATE_TEMPLATE):

1621 - yield line

1622 -

1623 - def generate_create_summary(self, push):

1624 - """Called for the creation of a reference."""

1625 -

1626 - # This is a new reference and so oldrev is not valid

1627 - (sha1, subject) = self.new.get_summary()

1628 - yield self.expand(

1629 - BRIEF_SUMMARY_TEMPLATE, action='at',

1630 - rev_short=sha1, text=subject,

1631 - )

1632 - yield '\n'

1633 -

1634 - def generate_update_summary(self, push):

1635 - """Called for the change of a pre-existing branch."""

1636 -

1637 - return iter([])

1638 -

1639 - def generate_delete_summary(self, push):

1640 - """Called for the deletion of any type of reference."""

1641 -

1642 - (sha1, subject) = self.old.get_summary()

1643 - yield self.expand(

1644 - BRIEF_SUMMARY_TEMPLATE, action='was',

1645 - rev_short=sha1, text=subject,

1646 - )

1647 - yield '\n'

1648 -

1649 - def get_specific_fromaddr(self):

1650 - return self.environment.from_refchange

1651 -

1652 -

1653 -class BranchChange(ReferenceChange):

1654 - refname_type = 'branch'

1655 -

1656 - def __init__(self, environment, refname, short_refname, old, new, rev):

1657 - ReferenceChange.__init__(

1658 - self, environment,

1659 - refname=refname, short_refname=short_refname,

1660 - old=old, new=new, rev=rev,

1661 - )

1662 - self.recipients = environment.get_refchange_recipients(self)

1663 - self._single_revision = None

1664 -

1665 - def send_single_combined_email(self, known_added_sha1s):

1666 - if not self.environment.combine_when_single_commit:

1667 - return None

1668 -

1669 - # In the sadly-all-too-frequent usecase of people pushing only

1670 - # one of their commits at a time to a repository, users feel

1671 - # the reference change summary emails are noise rather than

1672 - # important signal. This is because, in this particular

1673 - # usecase, there is a reference change summary email for each

1674 - # new commit, and all these summaries do is point out that

1675 - # there is one new commit (which can readily be inferred by

1676 - # the existence of the individual revision email that is also

1677 - # sent). In such cases, our users prefer there to be a combined

1678 - # reference change summary/new revision email.

1679 - #

1680 - # So, if the change is an update and it doesn't discard any

1681 - # commits, and it adds exactly one non-merge commit (gerrit

1682 - # forces a workflow where every commit is individually merged

1683 - # and the git-multimail hook fired off for just this one

1684 - # change), then we send a combined refchange/revision email.

1685 - try:

1686 - # If this change is a reference update that doesn't discard

1687 - # any commits...

1688 - if self.change_type != 'update':

1689 - return None

1690 -

1691 - if read_git_lines(

1692 - ['merge-base', self.old.sha1, self.new.sha1]

1693 - ) != [self.old.sha1]:

1694 - return None

1695 -

1696 - # Check if this update introduced exactly one non-merge

1697 - # commit:

1698 -

1699 - def split_line(line):

1700 - """Split line into (sha1, [parent,...])."""

1701 -

1702 - words = line.split()

1703 - return (words[0], words[1:])

1704 -

1705 - # Get the new commits introduced by the push as a list of

1706 - # (sha1, [parent,...])

1707 - new_commits = [

1708 - split_line(line)

1709 - for line in read_git_lines(

1710 - [

1711 - 'log', '-3', '--format=%H %P',

1712 - '%s..%s' % (self.old.sha1, self.new.sha1),

1713 - ]

1714 - )

1715 - ]

1716 -

1717 - if not new_commits:

1718 - return None

1719 -

1720 - # If the newest commit is a merge, save it for a later check

1721 - # but otherwise ignore it

1722 - merge = None

1723 - tot = len(new_commits)

1724 - if len(new_commits[0][1]) > 1:

1725 - merge = new_commits[0][0]

1726 - del new_commits[0]

1727 -

1728 - # Our primary check: we can't combine if more than one commit

1729 - # is introduced. We also currently only combine if the new

1730 - # commit is a non-merge commit, though it may make sense to

1731 - # combine if it is a merge as well.

1732 - if not (

1733 - len(new_commits) == 1 and

1734 - len(new_commits[0][1]) == 1 and

1735 - new_commits[0][0] in known_added_sha1s

1736 - ):

1737 - return None

1738 -

1739 - # We do not want to combine revision and refchange emails if

1740 - # those go to separate locations.

1741 - rev = Revision(self, GitObject(new_commits[0][0]), 1, tot)

1742 - if rev.recipients != self.recipients:

1743 - return None

1744 -

1745 - # We ignored the newest commit if it was just a merge of the one

1746 - # commit being introduced. But we don't want to ignore that

1747 - # merge commit it it involved conflict resolutions. Check that.

1748 - if merge and merge != read_git_output(['diff-tree', '--cc', merge]):

1749 - return None

1750 -

1751 - # We can combine the refchange and one new revision emails

1752 - # into one. Return the Revision that a combined email should

1753 - # be sent about.

1754 - return rev

1755 - except CommandError:

1756 - # Cannot determine number of commits in old..new or new..old;

1757 - # don't combine reference/revision emails:

1758 - return None

1759 -

1760 - def generate_combined_email(self, push, revision, body_filter=None, extra_header_values={}):

1761 - values = revision.get_values()

1762 - if extra_header_values:

1763 - values.update(extra_header_values)

1764 - if 'subject' not in extra_header_values:

1765 - values['subject'] = self.expand(COMBINED_REFCHANGE_REVISION_SUBJECT_TEMPLATE, **values)

1766 -

1767 - self._single_revision = revision

1768 - self._contains_diff()

1769 - self.header_template = COMBINED_HEADER_TEMPLATE

1770 - self.intro_template = COMBINED_INTRO_TEMPLATE

1771 - self.footer_template = COMBINED_FOOTER_TEMPLATE

1772 -

1773 - def revision_gen_link(base_url):

1774 - # revision is used only to generate the body, and

1775 - # _content_type is set while generating headers. Get it

1776 - # from the BranchChange object.

1777 - revision._content_type = self._content_type

1778 - return revision.generate_browse_link(base_url)

1779 - self.generate_browse_link = revision_gen_link

1780 - for line in self.generate_email(push, body_filter, values):

1781 - yield line

1782 -

1783 - def generate_email_body(self, push):

1784 - '''Call the appropriate body generation routine.

1785 -

1786 - If this is a combined refchange/revision email, the special logic

1787 - for handling this combined email comes from this function. For

1788 - other cases, we just use the normal handling.'''

1789 -

1790 - # If self._single_revision isn't set; don't override

1791 - if not self._single_revision:

1792 - for line in super(BranchChange, self).generate_email_body(push):

1793 - yield line

1794 - return

1795 -

1796 - # This is a combined refchange/revision email; we first provide

1797 - # some info from the refchange portion, and then call the revision

1798 - # generate_email_body function to handle the revision portion.

1799 - adds = list(generate_summaries(

1800 - '--topo-order', '--reverse', '%s..%s'

1801 - % (self.old.commit_sha1, self.new.commit_sha1,)

1802 - ))

1803 -

1804 - yield self.expand("The following commit(s) were added to %(refname)s by this push:\n")

1805 - for (sha1, subject) in adds:

1806 - yield self.expand(

1807 - BRIEF_SUMMARY_TEMPLATE, action='new',

1808 - rev_short=sha1, text=subject,

1809 - )

1810 -

1811 - yield self._single_revision.rev.short + " is described below\n"

1812 - yield '\n'

1813 -

1814 - for line in self._single_revision.generate_email_body(push):

1815 - yield line

1816 -

1817 -

1818 -class AnnotatedTagChange(ReferenceChange):

1819 - refname_type = 'annotated tag'

1820 -

1821 - def __init__(self, environment, refname, short_refname, old, new, rev):

1822 - ReferenceChange.__init__(

1823 - self, environment,

1824 - refname=refname, short_refname=short_refname,

1825 - old=old, new=new, rev=rev,

1826 - )

1827 - self.recipients = environment.get_announce_recipients(self)

1828 - self.show_shortlog = environment.announce_show_shortlog

1829 -

1830 - ANNOTATED_TAG_FORMAT = (

1831 - '%(*objectname)\n'

1832 - '%(*objecttype)\n'

1833 - '%(taggername)\n'

1834 - '%(taggerdate)'

1835 - )

1836 -

1837 - def describe_tag(self, push):

1838 - """Describe the new value of an annotated tag."""

1839 -

1840 - # Use git for-each-ref to pull out the individual fields from

1841 - # the tag

1842 - [tagobject, tagtype, tagger, tagged] = read_git_lines(

1843 - ['for-each-ref', '--format=%s' % (self.ANNOTATED_TAG_FORMAT,), self.refname],

1844 - )

1845 -

1846 - yield self.expand(

1847 - BRIEF_SUMMARY_TEMPLATE, action='tagging',

1848 - rev_short=tagobject, text='(%s)' % (tagtype,),

1849 - )

1850 - if tagtype == 'commit':

1851 - # If the tagged object is a commit, then we assume this is a

1852 - # release, and so we calculate which tag this tag is

1853 - # replacing

1854 - try:

1855 - prevtag = read_git_output(['describe', '--abbrev=0', '%s^' % (self.new,)])

1856 - except CommandError:

1857 - prevtag = None

1858 - if prevtag:

1859 - yield ' replaces %s\n' % (prevtag,)

1860 - else:

1861 - prevtag = None

1862 - yield ' length %s bytes\n' % (read_git_output(['cat-file', '-s', tagobject]),)

1863 -

1864 - yield ' by %s\n' % (tagger,)

1865 - yield ' on %s\n' % (tagged,)

1866 - yield '\n'

1867 -

1868 - # Show the content of the tag message; this might contain a

1869 - # change log or release notes so is worth displaying.

1870 - yield LOGBEGIN

1871 - contents = list(read_git_lines(['cat-file', 'tag', self.new.sha1], keepends=True))

1872 - contents = contents[contents.index('\n') + 1:]

1873 - if contents and contents[-1][-1:] != '\n':

1874 - contents.append('\n')

1875 - for line in contents:

1876 - yield line

1877 -

1878 - if self.show_shortlog and tagtype == 'commit':

1879 - # Only commit tags make sense to have rev-list operations

1880 - # performed on them

1881 - yield '\n'

1882 - if prevtag:

1883 - # Show changes since the previous release

1884 - revlist = read_git_output(

1885 - ['rev-list', '--pretty=short', '%s..%s' % (prevtag, self.new,)],

1886 - keepends=True,

1887 - )

1888 - else:

1889 - # No previous tag, show all the changes since time

1890 - # began

1891 - revlist = read_git_output(

1892 - ['rev-list', '--pretty=short', '%s' % (self.new,)],

1893 - keepends=True,

1894 - )

1895 - for line in read_git_lines(['shortlog'], input=revlist, keepends=True):

1896 - yield line

1897 -

1898 - yield LOGEND

1899 - yield '\n'

1900 -

1901 - def generate_create_summary(self, push):

1902 - """Called for the creation of an annotated tag."""

1903 -

1904 - for line in self.expand_lines(TAG_CREATED_TEMPLATE):

1905 - yield line

1906 -

1907 - for line in self.describe_tag(push):

1908 - yield line

1909 -

1910 - def generate_update_summary(self, push):

1911 - """Called for the update of an annotated tag.

1912 -

1913 - This is probably a rare event and may not even be allowed."""

1914 -

1915 - for line in self.expand_lines(TAG_UPDATED_TEMPLATE):

1916 - yield line

1917 -

1918 - for line in self.describe_tag(push):

1919 - yield line

1920 -

1921 - def generate_delete_summary(self, push):

1922 - """Called when a non-annotated reference is updated."""

1923 -

1924 - for line in self.expand_lines(TAG_DELETED_TEMPLATE):

1925 - yield line

1926 -

1927 - yield self.expand(' tag was %(oldrev_short)s\n')

1928 - yield '\n'

1929 -

1930 -

1931 -class NonAnnotatedTagChange(ReferenceChange):

1932 - refname_type = 'tag'

1933 -

1934 - def __init__(self, environment, refname, short_refname, old, new, rev):

1935 - ReferenceChange.__init__(

1936 - self, environment,

1937 - refname=refname, short_refname=short_refname,

1938 - old=old, new=new, rev=rev,

1939 - )

1940 - self.recipients = environment.get_refchange_recipients(self)

1941 -

1942 - def generate_create_summary(self, push):

1943 - """Called for the creation of an annotated tag."""

1944 -

1945 - for line in self.expand_lines(TAG_CREATED_TEMPLATE):

1946 - yield line

1947 -

1948 - def generate_update_summary(self, push):

1949 - """Called when a non-annotated reference is updated."""

1950 -

1951 - for line in self.expand_lines(TAG_UPDATED_TEMPLATE):

1952 - yield line

1953 -

1954 - def generate_delete_summary(self, push):

1955 - """Called when a non-annotated reference is updated."""

1956 -

1957 - for line in self.expand_lines(TAG_DELETED_TEMPLATE):

1958 - yield line

1959 -

1960 - for line in ReferenceChange.generate_delete_summary(self, push):

1961 - yield line

1962 -

1963 -

1964 -class OtherReferenceChange(ReferenceChange):

1965 - refname_type = 'reference'

1966 -

1967 - def __init__(self, environment, refname, short_refname, old, new, rev):

1968 - # We use the full refname as short_refname, because otherwise

1969 - # the full name of the reference would not be obvious from the

1970 - # text of the email.

1971 - ReferenceChange.__init__(

1972 - self, environment,

1973 - refname=refname, short_refname=refname,

1974 - old=old, new=new, rev=rev,

1975 - )

1976 - self.recipients = environment.get_refchange_recipients(self)

1977 -

1978 -

1979 -class Mailer(object):

1980 - """An object that can send emails."""

1981 -

1982 - def __init__(self, environment):

1983 - self.environment = environment

1984 -

1985 - def close(self):

1986 - pass

1987 -

1988 - def send(self, lines, to_addrs):

1989 - """Send an email consisting of lines.

1990 -

1991 - lines must be an iterable over the lines constituting the

1992 - header and body of the email. to_addrs is a list of recipient

1993 - addresses (can be needed even if lines already contains a

1994 - "To:" field). It can be either a string (comma-separated list

1995 - of email addresses) or a Python list of individual email

1996 - addresses.

1997 -

1998 - """

1999 -

2000 - raise NotImplementedError()

2001 -

2002 -

2003 -class SendMailer(Mailer):

2004 - """Send emails using 'sendmail -oi -t'."""

2005 -

2006 - SENDMAIL_CANDIDATES = [

2007 - '/usr/sbin/sendmail',

2008 - '/usr/lib/sendmail',

2009 - ]

2010 -

2011 - @staticmethod

2012 - def find_sendmail():

2013 - for path in SendMailer.SENDMAIL_CANDIDATES:

2014 - if os.access(path, os.X_OK):

2015 - return path

2016 - else:

2017 - raise ConfigurationException(

2018 - 'No sendmail executable found. '

2019 - 'Try setting multimailhook.sendmailCommand.'

2020 - )

2021 -

2022 - def __init__(self, environment, command=None, envelopesender=None):

2023 - """Construct a SendMailer instance.

2024 -

2025 - command should be the command and arguments used to invoke

2026 - sendmail, as a list of strings. If an envelopesender is

2027 - provided, it will also be passed to the command, via '-f

2028 - envelopesender'."""

2029 - super(SendMailer, self).__init__(environment)

2030 - if command:

2031 - self.command = command[:]

2032 - else:

2033 - self.command = [self.find_sendmail(), '-oi', '-t']

2034 -

2035 - if envelopesender:

2036 - self.command.extend(['-f', envelopesender])

2037 -

2038 - def send(self, lines, to_addrs):

2039 - try:

2040 - p = subprocess.Popen(self.command, stdin=subprocess.PIPE)

2041 - except OSError:

2042 - self.environment.get_logger().error(

2043 - '*** Cannot execute command: %s\n' % ' '.join(self.command) +

2044 - '*** %s\n' % sys.exc_info()[1] +

2045 - '*** Try setting multimailhook.mailer to "smtp"\n' +

2046 - '*** to send emails without using the sendmail command.\n'

2047 - )

2048 - sys.exit(1)

2049 - try:

2050 - lines = (str_to_bytes(line) for line in lines)

2051 - p.stdin.writelines(lines)

2052 - except Exception:

2053 - self.environment.get_logger().error(

2054 - '*** Error while generating commit email\n'

2055 - '*** - mail sending aborted.\n'

2056 - )

2057 - if hasattr(p, 'terminate'):

2058 - # subprocess.terminate() is not available in Python 2.4

2059 - p.terminate()

2060 - else:

2061 - import signal

2062 - os.kill(p.pid, signal.SIGTERM)

2063 - raise

2064 - else:

2065 - p.stdin.close()

2066 - retcode = p.wait()

2067 - if retcode:

2068 - raise CommandError(self.command, retcode)

2069 -

2070 -

2071 -class SMTPMailer(Mailer):

2072 - """Send emails using Python's smtplib."""

2073 -

2074 - def __init__(self, environment,

2075 - envelopesender, smtpserver,

2076 - smtpservertimeout=10.0, smtpserverdebuglevel=0,

2077 - smtpencryption='none',

2078 - smtpuser='', smtppass='',

2079 - smtpcacerts=''

2080 - ):

2081 - super(SMTPMailer, self).__init__(environment)

2082 - if not envelopesender:

2083 - self.environment.get_logger().error(

2084 - 'fatal: git_multimail: cannot use SMTPMailer without a sender address.\n'

2085 - 'please set either multimailhook.envelopeSender or user.email\n'

2086 - )

2087 - sys.exit(1)

2088 - if smtpencryption == 'ssl' and not (smtpuser and smtppass):

2089 - raise ConfigurationException(

2090 - 'Cannot use SMTPMailer with security option ssl '

2091 - 'without options username and password.'

2092 - )

2093 - self.envelopesender = envelopesender

2094 - self.smtpserver = smtpserver

2095 - self.smtpservertimeout = smtpservertimeout

2096 - self.smtpserverdebuglevel = smtpserverdebuglevel

2097 - self.security = smtpencryption

2098 - self.username = smtpuser

2099 - self.password = smtppass

2100 - self.smtpcacerts = smtpcacerts

2101 - self.loggedin = False

2102 - try:

2103 - def call(klass, server, timeout):

2104 - try:

2105 - return klass(server, timeout=timeout)

2106 - except TypeError:

2107 - # Old Python versions do not have timeout= argument.

2108 - return klass(server)

2109 - if self.security == 'none':

2110 - self.smtp = call(smtplib.SMTP, self.smtpserver, timeout=self.smtpservertimeout)

2111 - elif self.security == 'ssl':

2112 - if self.smtpcacerts:

2113 - raise smtplib.SMTPException(

2114 - "Checking certificate is not supported for ssl, prefer starttls"

2115 - )

2116 - self.smtp = call(smtplib.SMTP_SSL, self.smtpserver, timeout=self.smtpservertimeout)

2117 - elif self.security == 'tls':

2118 - if 'ssl' not in sys.modules:

2119 - self.environment.get_logger().error(

2120 - '*** Your Python version does not have the ssl library installed\n'

2121 - '*** smtpEncryption=tls is not available.\n'

2122 - '*** Either upgrade Python to 2.6 or later\n'

2123 - ' or use git_multimail.py version 1.2.\n')

2124 - if ':' not in self.smtpserver:

2125 - self.smtpserver += ':587' # default port for TLS

2126 - self.smtp = call(smtplib.SMTP, self.smtpserver, timeout=self.smtpservertimeout)

2127 - # start: ehlo + starttls

2128 - # equivalent to

2129 - # self.smtp.ehlo()

2130 - # self.smtp.starttls()

2131 - # with access to the ssl layer

2132 - self.smtp.ehlo()

2133 - if not self.smtp.has_extn("starttls"):

2134 - raise smtplib.SMTPException("STARTTLS extension not supported by server")

2135 - resp, reply = self.smtp.docmd("STARTTLS")

2136 - if resp != 220:

2137 - raise smtplib.SMTPException("Wrong answer to the STARTTLS command")

2138 - if self.smtpcacerts:

2139 - self.smtp.sock = ssl.wrap_socket(

2140 - self.smtp.sock,

2141 - ca_certs=self.smtpcacerts,

2142 - cert_reqs=ssl.CERT_REQUIRED

2143 - )

2144 - else:

2145 - self.smtp.sock = ssl.wrap_socket(

2146 - self.smtp.sock,

2147 - cert_reqs=ssl.CERT_NONE

2148 - )

2149 - self.environment.get_logger().error(

2150 - '*** Warning, the server certificate is not verified (smtp) ***\n'

2151 - '*** set the option smtpCACerts ***\n'

2152 - )

2153 - if not hasattr(self.smtp.sock, "read"):

2154 - # using httplib.FakeSocket with Python 2.5.x or earlier

2155 - self.smtp.sock.read = self.smtp.sock.recv

2156 - self.smtp.file = smtplib.SSLFakeFile(self.smtp.sock)

2157 - self.smtp.helo_resp = None

2158 - self.smtp.ehlo_resp = None

2159 - self.smtp.esmtp_features = {}

2160 - self.smtp.does_esmtp = 0

2161 - # end: ehlo + starttls

2162 - self.smtp.ehlo()

2163 - else:

2164 - sys.stdout.write('*** Error: Control reached an invalid option. ***')

2165 - sys.exit(1)

2166 - if self.smtpserverdebuglevel > 0:

2167 - sys.stdout.write(

2168 - "*** Setting debug on for SMTP server connection (%s) ***\n"

2169 - % self.smtpserverdebuglevel)

2170 - self.smtp.set_debuglevel(self.smtpserverdebuglevel)

2171 - except Exception:

2172 - self.environment.get_logger().error(

2173 - '*** Error establishing SMTP connection to %s ***\n'

2174 - '*** %s\n'

2175 - % (self.smtpserver, sys.exc_info()[1]))

2176 - sys.exit(1)

2177 -

2178 - def close(self):

2179 - if hasattr(self, 'smtp'):

2180 - self.smtp.quit()

2181 - del self.smtp

2182 -

2183 - def __del__(self):

2184 - self.close()

2185 -

2186 - def send(self, lines, to_addrs):

2187 - try:

2188 - if self.username or self.password:

2189 - if not self.loggedin:

2190 - self.smtp.login(self.username, self.password)

2191 - self.loggedin = True

2192 - msg = ''.join(lines)

2193 - # turn comma-separated list into Python list if needed.

2194 - if is_string(to_addrs):

2195 - to_addrs = [email for (name, email) in getaddresses([to_addrs])]

2196 - self.smtp.sendmail(self.envelopesender, to_addrs, msg)

2197 - except socket.timeout:

2198 - self.environment.get_logger().error(

2199 - '*** Error sending email ***\n'

2200 - '*** SMTP server timed out (timeout is %s)\n'

2201 - % self.smtpservertimeout)

2202 - except smtplib.SMTPResponseException:

2203 - err = sys.exc_info()[1]

2204 - self.environment.get_logger().error(

2205 - '*** Error sending email ***\n'

2206 - '*** Error %d: %s\n'

2207 - % (err.smtp_code, bytes_to_str(err.smtp_error)))

2208 - try:

2209 - smtp = self.smtp

2210 - # delete the field before quit() so that in case of

2211 - # error, self.smtp is deleted anyway.

2212 - del self.smtp

2213 - smtp.quit()

2214 - except:

2215 - self.environment.get_logger().error(

2216 - '*** Error closing the SMTP connection ***\n'

2217 - '*** Exiting anyway ... ***\n'

2218 - '*** %s\n' % sys.exc_info()[1])

2219 - sys.exit(1)

2220 -

2221 -

2222 -class OutputMailer(Mailer):

2223 - """Write emails to an output stream, bracketed by lines of '=' characters.

2224 -

2225 - This is intended for debugging purposes."""

2226 -

2227 - SEPARATOR = '=' * 75 + '\n'

2228 -

2229 - def __init__(self, f, environment=None):

2230 - super(OutputMailer, self).__init__(environment=environment)

2231 - self.f = f

2232 -

2233 - def send(self, lines, to_addrs):

2234 - write_str(self.f, self.SEPARATOR)

2235 - for line in lines:

2236 - write_str(self.f, line)

2237 - write_str(self.f, self.SEPARATOR)

2238 -

2239 -

2240 -def get_git_dir():

2241 - """Determine GIT_DIR.

2242 -

2243 - Determine GIT_DIR either from the GIT_DIR environment variable or

2244 - from the working directory, using Git's usual rules."""

2245 -

2246 - try:

2247 - return read_git_output(['rev-parse', '--git-dir'])

2248 - except CommandError:

2249 - sys.stderr.write('fatal: git_multimail: not in a git directory\n')

2250 - sys.exit(1)

2251 -

2252 -

2253 -class Environment(object):

2254 - """Describes the environment in which the push is occurring.

2255 -

2256 - An Environment object encapsulates information about the local

2257 - environment. For example, it knows how to determine:

2258 -

2259 - * the name of the repository to which the push occurred

2260 -

2261 - * what user did the push

2262 -

2263 - * what users want to be informed about various types of changes.

2264 -

2265 - An Environment object is expected to have the following methods:

2266 -

2267 - get_repo_shortname()

2268 -

2269 - Return a short name for the repository, for display

2270 - purposes.

2271 -

2272 - get_repo_path()

2273 -

2274 - Return the absolute path to the Git repository.

2275 -

2276 - get_emailprefix()

2277 -

2278 - Return a string that will be prefixed to every email's

2279 - subject.

2280 -

2281 - get_pusher()

2282 -

2283 - Return the username of the person who pushed the changes.

2284 - This value is used in the email body to indicate who

2285 - pushed the change.

2286 -

2287 - get_pusher_email() (may return None)

2288 -

2289 - Return the email address of the person who pushed the

2290 - changes. The value should be a single RFC 2822 email

2291 - address as a string; e.g., "Joe User <user@example.com>"

2292 - if available, otherwise "user@example.com". If set, the

2293 - value is used as the Reply-To address for refchange

2294 - emails. If it is impossible to determine the pusher's

2295 - email, this attribute should be set to None (in which case

2296 - no Reply-To header will be output).

2297 -

2298 - get_sender()

2299 -

2300 - Return the address to be used as the 'From' email address

2301 - in the email envelope.

2302 -

2303 - get_fromaddr(change=None)

2304 -

2305 - Return the 'From' email address used in the email 'From:'

2306 - headers. If the change is known when this function is

2307 - called, it is passed in as the 'change' parameter. (May

2308 - be a full RFC 2822 email address like 'Joe User

2309 - <user@example.com>'.)

2310 -

2311 - get_administrator()

2312 -

2313 - Return the name and/or email of the repository

2314 - administrator. This value is used in the footer as the

2315 - person to whom requests to be removed from the

2316 - notification list should be sent. Ideally, it should

2317 - include a valid email address.

2318 -

2319 - get_reply_to_refchange()

2320 - get_reply_to_commit()

2321 -

2322 - Return the address to use in the email "Reply-To" header,

2323 - as a string. These can be an RFC 2822 email address, or

2324 - None to omit the "Reply-To" header.

2325 - get_reply_to_refchange() is used for refchange emails;

2326 - get_reply_to_commit() is used for individual commit

2327 - emails.

2328 -

2329 - get_ref_filter_regex()

2330 -

2331 - Return a tuple -- a compiled regex, and a boolean indicating

2332 - whether the regex picks refs to include (if False, the regex

2333 - matches on refs to exclude).

2334 -

2335 - get_default_ref_ignore_regex()

2336 -

2337 - Return a regex that should be ignored for both what emails

2338 - to send and when computing what commits are considered new

2339 - to the repository. Default is "^refs/notes/".

2340 -

2341 - get_max_subject_length()

2342 -

2343 - Return an int giving the maximal length for the subject

2344 - (git log --oneline).

2345 -

2346 - They should also define the following attributes:

2347 -

2348 - announce_show_shortlog (bool)

2349 -

2350 - True iff announce emails should include a shortlog.

2351 -

2352 - commit_email_format (string)

2353 -

2354 - If "html", generate commit emails in HTML instead of plain text

2355 - used by default.

2356 -

2357 - html_in_intro (bool)

2358 - html_in_footer (bool)

2359 -

2360 - When generating HTML emails, the introduction (respectively,

2361 - the footer) will be HTML-escaped iff html_in_intro (respectively,

2362 - the footer) is true. When false, only the values used to expand

2363 - the template are escaped.

2364 -

2365 - refchange_showgraph (bool)

2366 -

2367 - True iff refchanges emails should include a detailed graph.

2368 -

2369 - refchange_showlog (bool)

2370 -

2371 - True iff refchanges emails should include a detailed log.

2372 -

2373 - diffopts (list of strings)

2374 -

2375 - The options that should be passed to 'git diff' for the

2376 - summary email. The value should be a list of strings

2377 - representing words to be passed to the command.

2378 -

2379 - graphopts (list of strings)

2380 -

2381 - Analogous to diffopts, but contains options passed to

2382 - 'git log --graph' when generating the detailed graph for

2383 - a set of commits (see refchange_showgraph)

2384 -

2385 - logopts (list of strings)

2386 -

2387 - Analogous to diffopts, but contains options passed to

2388 - 'git log' when generating the detailed log for a set of

2389 - commits (see refchange_showlog)

2390 -

2391 - commitlogopts (list of strings)

2392 -

2393 - The options that should be passed to 'git log' for each

2394 - commit mail. The value should be a list of strings

2395 - representing words to be passed to the command.

2396 -

2397 - date_substitute (string)

2398 -

2399 - String to be used in substitution for 'Date:' at start of

2400 - line in the output of 'git log'.

2401 -

2402 - quiet (bool)

2403 - On success do not write to stderr

2404 -

2405 - stdout (bool)

2406 - Write email to stdout rather than emailing. Useful for debugging

2407 -

2408 - combine_when_single_commit (bool)

2409 -

2410 - True if a combined email should be produced when a single

2411 - new commit is pushed to a branch, False otherwise.

2412 -

2413 - from_refchange, from_commit (strings)

2414 -

2415 - Addresses to use for the From: field for refchange emails

2416 - and commit emails respectively. Set from

2417 - multimailhook.fromRefchange and multimailhook.fromCommit

2418 - by ConfigEnvironmentMixin.

2419 -

2420 - log_file, error_log_file, debug_log_file (string)

2421 -

2422 - Name of a file to which logs should be sent.

2423 -

2424 - verbose (int)

2425 -

2426 - How verbose the system should be.

2427 - - 0 (default): show info, errors, ...

2428 - - 1 : show basic debug info

2429 - """

2430 -

2431 - REPO_NAME_RE = re.compile(r'^(?P<name>.+?)(?:\.git)$')

2432 -

2433 - def __init__(self, osenv=None):

2434 - self.osenv = osenv or os.environ

2435 - self.announce_show_shortlog = False

2436 - self.commit_email_format = "text"

2437 - self.html_in_intro = False

2438 - self.html_in_footer = False

2439 - self.commitBrowseURL = None

2440 - self.maxcommitemails = 500

2441 - self.excludemergerevisions = False

2442 - self.diffopts = ['--stat', '--summary', '--find-copies-harder']

2443 - self.graphopts = ['--oneline', '--decorate']

2444 - self.logopts = []

2445 - self.refchange_showgraph = False

2446 - self.refchange_showlog = False

2447 - self.commitlogopts = ['-C', '--stat', '-p', '--cc']

2448 - self.date_substitute = 'AuthorDate: '

2449 - self.quiet = False

2450 - self.stdout = False

2451 - self.combine_when_single_commit = True

2452 - self.logger = None

2453 -

2454 - self.COMPUTED_KEYS = [

2455 - 'administrator',

2456 - 'charset',

2457 - 'emailprefix',

2458 - 'pusher',

2459 - 'pusher_email',

2460 - 'repo_path',

2461 - 'repo_shortname',

2462 - 'sender',

2463 - ]

2464 -

2465 - self._values = None

2466 -

2467 - def get_logger(self):

2468 - """Get (possibly creates) the logger associated to this environment."""

2469 - if self.logger is None:

2470 - self.logger = Logger(self)

2471 - return self.logger

2472 -

2473 - def get_repo_shortname(self):

2474 - """Use the last part of the repo path, with ".git" stripped off if present."""

2475 -

2476 - basename = os.path.basename(os.path.abspath(self.get_repo_path()))

2477 - m = self.REPO_NAME_RE.match(basename)

2478 - if m:

2479 - return m.group('name')

2480 - else:

2481 - return basename

2482 -

2483 - def get_pusher(self):

2484 - raise NotImplementedError()

2485 -

2486 - def get_pusher_email(self):

2487 - return None

2488 -

2489 - def get_fromaddr(self, change=None):

2490 - config = Config('user')

2491 - fromname = config.get('name', default='')

2492 - fromemail = config.get('email', default='')

2493 - if fromemail:

2494 - return formataddr([fromname, fromemail])

2495 - return self.get_sender()

2496 -

2497 - def get_administrator(self):

2498 - return 'the administrator of this repository'

2499 -

2500 - def get_emailprefix(self):

2501 - return ''

2502 -

2503 - def get_repo_path(self):

2504 - if read_git_output(['rev-parse', '--is-bare-repository']) == 'true':

2505 - path = get_git_dir()

2506 - else:

2507 - path = read_git_output(['rev-parse', '--show-toplevel'])

2508 - return os.path.abspath(path)

2509 -

2510 - def get_charset(self):

2511 - return CHARSET

2512 -

2513 - def get_values(self):

2514 - """Return a dictionary {keyword: expansion} for this Environment.

2515 -

2516 - This method is called by Change._compute_values(). The keys

2517 - in the returned dictionary are available to be used in any of

2518 - the templates. The dictionary is created by calling

2519 - self.get_NAME() for each of the attributes named in

2520 - COMPUTED_KEYS and recording those that do not return None.

2521 - The return value is always a new dictionary."""

2522 -

2523 - if self._values is None:

2524 - values = {'': ''} # %()s expands to the empty string.

2525 -

2526 - for key in self.COMPUTED_KEYS:

2527 - value = getattr(self, 'get_%s' % (key,))()

2528 - if value is not None:

2529 - values[key] = value

2530 -

2531 - self._values = values

2532 -

2533 - return self._values.copy()

2534 -

2535 - def get_refchange_recipients(self, refchange):

2536 - """Return the recipients for notifications about refchange.

2537 -

2538 - Return the list of email addresses to which notifications

2539 - about the specified ReferenceChange should be sent."""

2540 -

2541 - raise NotImplementedError()

2542 -

2543 - def get_announce_recipients(self, annotated_tag_change):

2544 - """Return the recipients for notifications about annotated_tag_change.

2545 -

2546 - Return the list of email addresses to which notifications

2547 - about the specified AnnotatedTagChange should be sent."""

2548 -

2549 - raise NotImplementedError()

2550 -

2551 - def get_reply_to_refchange(self, refchange):

2552 - return self.get_pusher_email()

2553 -

2554 - def get_revision_recipients(self, revision):

2555 - """Return the recipients for messages about revision.

2556 -

2557 - Return the list of email addresses to which notifications

2558 - about the specified Revision should be sent. This method

2559 - could be overridden, for example, to take into account the

2560 - contents of the revision when deciding whom to notify about

2561 - it. For example, there could be a scheme for users to express

2562 - interest in particular files or subdirectories, and only

2563 - receive notification emails for revisions that affecting those

2564 - files."""

2565 -

2566 - raise NotImplementedError()

2567 -

2568 - def get_reply_to_commit(self, revision):

2569 - return revision.author

2570 -

2571 - def get_default_ref_ignore_regex(self):

2572 - # The commit messages of git notes are essentially meaningless

2573 - # and "filenames" in git notes commits are an implementational

2574 - # detail that might surprise users at first. As such, we

2575 - # would need a completely different method for handling emails

2576 - # of git notes in order for them to be of benefit for users,

2577 - # which we simply do not have right now.

2578 - return "^refs/notes/"

2579 -

2580 - def get_max_subject_length(self):

2581 - """Return the maximal subject line (git log --oneline) length.

2582 - Longer subject lines will be truncated."""

2583 - raise NotImplementedError()

2584 -

2585 - def filter_body(self, lines):

2586 - """Filter the lines intended for an email body.

2587 -

2588 - lines is an iterable over the lines that would go into the

2589 - email body. Filter it (e.g., limit the number of lines, the

2590 - line length, character set, etc.), returning another iterable.

2591 - See FilterLinesEnvironmentMixin and MaxlinesEnvironmentMixin

2592 - for classes implementing this functionality."""

2593 -

2594 - return lines

2595 -

2596 - def log_msg(self, msg):

2597 - """Write the string msg on a log file or on stderr.

2598 -

2599 - Sends the text to stderr by default, override to change the behavior."""

2600 - self.get_logger().info(msg)

2601 -

2602 - def log_warning(self, msg):

2603 - """Write the string msg on a log file or on stderr.

2604 -

2605 - Sends the text to stderr by default, override to change the behavior."""

2606 - self.get_logger().warning(msg)

2607 -

2608 - def log_error(self, msg):

2609 - """Write the string msg on a log file or on stderr.

2610 -

2611 - Sends the text to stderr by default, override to change the behavior."""

2612 - self.get_logger().error(msg)

2613 -

2614 - def check(self):

2615 - pass

2616 -

2617 -

2618 -class ConfigEnvironmentMixin(Environment):

2619 - """A mixin that sets self.config to its constructor's config argument.

2620 -

2621 - This class's constructor consumes the "config" argument.

2622 -

2623 - Mixins that need to inspect the config should inherit from this

2624 - class (1) to make sure that "config" is still in the constructor

2625 - arguments with its own constructor runs and/or (2) to be sure that

2626 - self.config is set after construction."""

2627 -

2628 - def __init__(self, config, **kw):

2629 - super(ConfigEnvironmentMixin, self).__init__(**kw)

2630 - self.config = config

2631 -

2632 -

2633 -class ConfigOptionsEnvironmentMixin(ConfigEnvironmentMixin):

2634 - """An Environment that reads most of its information from "git config"."""

2635 -

2636 - @staticmethod

2637 - def forbid_field_values(name, value, forbidden):

2638 - for forbidden_val in forbidden:

2639 - if value is not None and value.lower() == forbidden:

2640 - raise ConfigurationException(

2641 - '"%s" is not an allowed setting for %s' % (value, name)

2642 - )

2643 -

2644 - def __init__(self, config, **kw):

2645 - super(ConfigOptionsEnvironmentMixin, self).__init__(

2646 - config=config, **kw

2647 - )

2648 -

2649 - for var, cfg in (

2650 - ('announce_show_shortlog', 'announceshortlog'),

2651 - ('refchange_showgraph', 'refchangeShowGraph'),

2652 - ('refchange_showlog', 'refchangeshowlog'),

2653 - ('quiet', 'quiet'),

2654 - ('stdout', 'stdout'),

2655 - ):

2656 - val = config.get_bool(cfg)

2657 - if val is not None:

2658 - setattr(self, var, val)

2659 -

2660 - commit_email_format = config.get('commitEmailFormat')

2661 - if commit_email_format is not None:

2662 - if commit_email_format != "html" and commit_email_format != "text":

2663 - self.log_warning(

2664 - '*** Unknown value for multimailhook.commitEmailFormat: %s\n' %

2665 - commit_email_format +

2666 - '*** Expected either "text" or "html". Ignoring.\n'

2667 - )

2668 - else:

2669 - self.commit_email_format = commit_email_format

2670 -

2671 - html_in_intro = config.get_bool('htmlInIntro')

2672 - if html_in_intro is not None:

2673 - self.html_in_intro = html_in_intro

2674 -

2675 - html_in_footer = config.get_bool('htmlInFooter')

2676 - if html_in_footer is not None:

2677 - self.html_in_footer = html_in_footer

2678 -

2679 - self.commitBrowseURL = config.get('commitBrowseURL')

2680 -

2681 - self.excludemergerevisions = config.get('excludeMergeRevisions')

2682 -

2683 - maxcommitemails = config.get('maxcommitemails')

2684 - if maxcommitemails is not None:

2685 - try:

2686 - self.maxcommitemails = int(maxcommitemails)

2687 - except ValueError:

2688 - self.log_warning(

2689 - '*** Malformed value for multimailhook.maxCommitEmails: %s\n'

2690 - % maxcommitemails +

2691 - '*** Expected a number. Ignoring.\n'

2692 - )

2693 -

2694 - diffopts = config.get('diffopts')

2695 - if diffopts is not None:

2696 - self.diffopts = shlex.split(diffopts)

2697 -

2698 - graphopts = config.get('graphOpts')

2699 - if graphopts is not None:

2700 - self.graphopts = shlex.split(graphopts)

2701 -

2702 - logopts = config.get('logopts')

2703 - if logopts is not None:

2704 - self.logopts = shlex.split(logopts)

2705 -

2706 - commitlogopts = config.get('commitlogopts')

2707 - if commitlogopts is not None:

2708 - self.commitlogopts = shlex.split(commitlogopts)

2709 -

2710 - date_substitute = config.get('dateSubstitute')

2711 - if date_substitute == 'none':

2712 - self.date_substitute = None

2713 - elif date_substitute is not None:

2714 - self.date_substitute = date_substitute

2715 -

2716 - reply_to = config.get('replyTo')

2717 - self.__reply_to_refchange = config.get('replyToRefchange', default=reply_to)

2718 - self.forbid_field_values('replyToRefchange',

2719 - self.__reply_to_refchange,

2720 - ['author'])

2721 - self.__reply_to_commit = config.get('replyToCommit', default=reply_to)

2722 -

2723 - self.from_refchange = config.get('fromRefchange')

2724 - self.forbid_field_values('fromRefchange',

2725 - self.from_refchange,

2726 - ['author', 'none'])

2727 - self.from_commit = config.get('fromCommit')

2728 - self.forbid_field_values('fromCommit',

2729 - self.from_commit,

2730 - ['none'])

2731 -

2732 - combine = config.get_bool('combineWhenSingleCommit')

2733 - if combine is not None:

2734 - self.combine_when_single_commit = combine

2735 -

2736 - self.log_file = config.get('logFile', default=None)

2737 - self.error_log_file = config.get('errorLogFile', default=None)

2738 - self.debug_log_file = config.get('debugLogFile', default=None)

2739 - if config.get_bool('Verbose', default=False):

2740 - self.verbose = 1

2741 - else:

2742 - self.verbose = 0

2743 -

2744 - def get_administrator(self):

2745 - return (

2746 - self.config.get('administrator') or

2747 - self.get_sender() or

2748 - super(ConfigOptionsEnvironmentMixin, self).get_administrator()

2749 - )

2750 -

2751 - def get_repo_shortname(self):

2752 - return (

2753 - self.config.get('reponame') or

2754 - super(ConfigOptionsEnvironmentMixin, self).get_repo_shortname()

2755 - )

2756 -

2757 - def get_emailprefix(self):

2758 - emailprefix = self.config.get('emailprefix')

2759 - if emailprefix is not None:

2760 - emailprefix = emailprefix.strip()

2761 - if emailprefix:

2762 - emailprefix += ' '

2763 - else:

2764 - emailprefix = '[%(repo_shortname)s] '

2765 - short_name = self.get_repo_shortname()

2766 - try:

2767 - return emailprefix % {'repo_shortname': short_name}

2768 - except:

2769 - self.get_logger().error(

2770 - '*** Invalid multimailhook.emailPrefix: %s\n' % emailprefix +

2771 - '*** %s\n' % sys.exc_info()[1] +

2772 - "*** Only the '%(repo_shortname)s' placeholder is allowed\n"

2773 - )

2774 - raise ConfigurationException(

2775 - '"%s" is not an allowed setting for emailPrefix' % emailprefix

2776 - )

2777 -

2778 - def get_sender(self):

2779 - return self.config.get('envelopesender')

2780 -

2781 - def process_addr(self, addr, change):

2782 - if addr.lower() == 'author':

2783 - if hasattr(change, 'author'):

2784 - return change.author

2785 - else:

2786 - return None

2787 - elif addr.lower() == 'pusher':

2788 - return self.get_pusher_email()

2789 - elif addr.lower() == 'none':

2790 - return None

2791 - else:

2792 - return addr

2793 -

2794 - def get_fromaddr(self, change=None):

2795 - fromaddr = self.config.get('from')

2796 - if change:

2797 - specific_fromaddr = change.get_specific_fromaddr()

2798 - if specific_fromaddr:

2799 - fromaddr = specific_fromaddr

2800 - if fromaddr:

2801 - fromaddr = self.process_addr(fromaddr, change)

2802 - if fromaddr:

2803 - return fromaddr

2804 - return super(ConfigOptionsEnvironmentMixin, self).get_fromaddr(change)

2805 -

2806 - def get_reply_to_refchange(self, refchange):

2807 - if self.__reply_to_refchange is None:

2808 - return super(ConfigOptionsEnvironmentMixin, self).get_reply_to_refchange(refchange)

2809 - else:

2810 - return self.process_addr(self.__reply_to_refchange, refchange)

2811 -

2812 - def get_reply_to_commit(self, revision):

2813 - if self.__reply_to_commit is None:

2814 - return super(ConfigOptionsEnvironmentMixin, self).get_reply_to_commit(revision)

2815 - else:

2816 - return self.process_addr(self.__reply_to_commit, revision)

2817 -

2818 - def get_scancommitforcc(self):

2819 - return self.config.get('scancommitforcc')

2820 -

2821 -

2822 -class FilterLinesEnvironmentMixin(Environment):

2823 - """Handle encoding and maximum line length of body lines.

2824 -

2825 - email_max_line_length (int or None)

2826 -

2827 - The maximum length of any single line in the email body.

2828 - Longer lines are truncated at that length with ' [...]'

2829 - appended.

2830 -

2831 - strict_utf8 (bool)

2832 -

2833 - If this field is set to True, then the email body text is

2834 - expected to be UTF-8. Any invalid characters are

2835 - converted to U+FFFD, the Unicode replacement character

2836 - (encoded as UTF-8, of course).

2837 -

2838 - """

2839 -

2840 - def __init__(self, strict_utf8=True,

2841 - email_max_line_length=500, max_subject_length=500,

2842 - **kw):

2843 - super(FilterLinesEnvironmentMixin, self).__init__(**kw)

2844 - self.__strict_utf8 = strict_utf8

2845 - self.__email_max_line_length = email_max_line_length

2846 - self.__max_subject_length = max_subject_length

2847 -

2848 - def filter_body(self, lines):

2849 - lines = super(FilterLinesEnvironmentMixin, self).filter_body(lines)

2850 - if self.__strict_utf8:

2851 - if not PYTHON3:

2852 - lines = (line.decode(ENCODING, 'replace') for line in lines)

2853 - # Limit the line length in Unicode-space to avoid

2854 - # splitting characters:

2855 - if self.__email_max_line_length > 0:

2856 - lines = limit_linelength(lines, self.__email_max_line_length)

2857 - if not PYTHON3:

2858 - lines = (line.encode(ENCODING, 'replace') for line in lines)

2859 - elif self.__email_max_line_length:

2860 - lines = limit_linelength(lines, self.__email_max_line_length)

2861 -

2862 - return lines

2863 -

2864 - def get_max_subject_length(self):

2865 - return self.__max_subject_length

2866 -

2867 -

2868 -class ConfigFilterLinesEnvironmentMixin(

2869 - ConfigEnvironmentMixin,

2870 - FilterLinesEnvironmentMixin,

2871 - ):

2872 - """Handle encoding and maximum line length based on config."""

2873 -

2874 - def __init__(self, config, **kw):

2875 - strict_utf8 = config.get_bool('emailstrictutf8', default=None)

2876 - if strict_utf8 is not None:

2877 - kw['strict_utf8'] = strict_utf8

2878 -

2879 - email_max_line_length = config.get('emailmaxlinelength')

2880 - if email_max_line_length is not None:

2881 - kw['email_max_line_length'] = int(email_max_line_length)

2882 -

2883 - max_subject_length = config.get('subjectMaxLength', default=email_max_line_length)

2884 - if max_subject_length is not None:

2885 - kw['max_subject_length'] = int(max_subject_length)

2886 -

2887 - super(ConfigFilterLinesEnvironmentMixin, self).__init__(

2888 - config=config, **kw

2889 - )

2890 -

2891 -

2892 -class MaxlinesEnvironmentMixin(Environment):

2893 - """Limit the email body to a specified number of lines."""

2894 -

2895 - def __init__(self, emailmaxlines, **kw):

2896 - super(MaxlinesEnvironmentMixin, self).__init__(**kw)

2897 - self.__emailmaxlines = emailmaxlines

2898 -

2899 - def filter_body(self, lines):

2900 - lines = super(MaxlinesEnvironmentMixin, self).filter_body(lines)

2901 - if self.__emailmaxlines > 0:

2902 - lines = limit_lines(lines, self.__emailmaxlines)

2903 - return lines

2904 -

2905 -

2906 -class ConfigMaxlinesEnvironmentMixin(

2907 - ConfigEnvironmentMixin,

2908 - MaxlinesEnvironmentMixin,

2909 - ):

2910 - """Limit the email body to the number of lines specified in config."""

2911 -

2912 - def __init__(self, config, **kw):

2913 - emailmaxlines = int(config.get('emailmaxlines', default='0'))

2914 - super(ConfigMaxlinesEnvironmentMixin, self).__init__(

2915 - config=config,

2916 - emailmaxlines=emailmaxlines,

2917 - **kw

2918 - )

2919 -

2920 -

2921 -class FQDNEnvironmentMixin(Environment):

2922 - """A mixin that sets the host's FQDN to its constructor argument."""

2923 -

2924 - def __init__(self, fqdn, **kw):

2925 - super(FQDNEnvironmentMixin, self).__init__(**kw)

2926 - self.COMPUTED_KEYS += ['fqdn']

2927 - self.__fqdn = fqdn

2928 -

2929 - def get_fqdn(self):

2930 - """Return the fully-qualified domain name for this host.

2931 -

2932 - Return None if it is unavailable or unwanted."""

2933 -

2934 - return self.__fqdn

2935 -

2936 -

2937 -class ConfigFQDNEnvironmentMixin(

2938 - ConfigEnvironmentMixin,

2939 - FQDNEnvironmentMixin,

2940 - ):

2941 - """Read the FQDN from the config."""

2942 -

2943 - def __init__(self, config, **kw):

2944 - fqdn = config.get('fqdn')

2945 - super(ConfigFQDNEnvironmentMixin, self).__init__(

2946 - config=config,

2947 - fqdn=fqdn,

2948 - **kw

2949 - )

2950 -

2951 -

2952 -class ComputeFQDNEnvironmentMixin(FQDNEnvironmentMixin):

2953 - """Get the FQDN by calling socket.getfqdn()."""

2954 -

2955 - def __init__(self, **kw):

2956 - super(ComputeFQDNEnvironmentMixin, self).__init__(

2957 - fqdn=socket.getfqdn(),

2958 - **kw

2959 - )

2960 -

2961 -

2962 -class PusherDomainEnvironmentMixin(ConfigEnvironmentMixin):

2963 - """Deduce pusher_email from pusher by appending an emaildomain."""

2964 -

2965 - def __init__(self, **kw):

2966 - super(PusherDomainEnvironmentMixin, self).__init__(**kw)

2967 - self.__emaildomain = self.config.get('emaildomain')

2968 -

2969 - def get_pusher_email(self):

2970 - if self.__emaildomain:

2971 - # Derive the pusher's full email address in the default way:

2972 - return '%s@%s' % (self.get_pusher(), self.__emaildomain)

2973 - else:

2974 - return super(PusherDomainEnvironmentMixin, self).get_pusher_email()

2975 -

2976 -

2977 -class StaticRecipientsEnvironmentMixin(Environment):

2978 - """Set recipients statically based on constructor parameters."""

2979 -

2980 - def __init__(

2981 - self,

2982 - refchange_recipients, announce_recipients, revision_recipients, scancommitforcc,

2983 - **kw

2984 - ):

2985 - super(StaticRecipientsEnvironmentMixin, self).__init__(**kw)

2986 -

2987 - # The recipients for various types of notification emails, as

2988 - # RFC 2822 email addresses separated by commas (or the empty

2989 - # string if no recipients are configured). Although there is

2990 - # a mechanism to choose the recipient lists based on on the

2991 - # actual *contents* of the change being reported, we only

2992 - # choose based on the *type* of the change. Therefore we can

2993 - # compute them once and for all:

2994 - self.__refchange_recipients = refchange_recipients

2995 - self.__announce_recipients = announce_recipients

2996 - self.__revision_recipients = revision_recipients

2997 -

2998 - def check(self):

2999 - if not (self.get_refchange_recipients(None) or

3000 - self.get_announce_recipients(None) or

3001 - self.get_revision_recipients(None) or

3002 - self.get_scancommitforcc()):

3003 - raise ConfigurationException('No email recipients configured!')

3004 - super(StaticRecipientsEnvironmentMixin, self).check()

3005 -

3006 - def get_refchange_recipients(self, refchange):

3007 - if self.__refchange_recipients is None:

3008 - return super(StaticRecipientsEnvironmentMixin,

3009 - self).get_refchange_recipients(refchange)

3010 - return self.__refchange_recipients

3011 -

3012 - def get_announce_recipients(self, annotated_tag_change):

3013 - if self.__announce_recipients is None:

3014 - return super(StaticRecipientsEnvironmentMixin,

3015 - self).get_refchange_recipients(annotated_tag_change)

3016 - return self.__announce_recipients

3017 -

3018 - def get_revision_recipients(self, revision):

3019 - if self.__revision_recipients is None:

3020 - return super(StaticRecipientsEnvironmentMixin,

3021 - self).get_refchange_recipients(revision)

3022 - return self.__revision_recipients

3023 -

3024 -

3025 -class CLIRecipientsEnvironmentMixin(Environment):

3026 - """Mixin storing recipients information coming from the

3027 - command-line."""

3028 -

3029 - def __init__(self, cli_recipients=None, **kw):

3030 - super(CLIRecipientsEnvironmentMixin, self).__init__(**kw)

3031 - self.__cli_recipients = cli_recipients

3032 -

3033 - def get_refchange_recipients(self, refchange):

3034 - if self.__cli_recipients is None:

3035 - return super(CLIRecipientsEnvironmentMixin,

3036 - self).get_refchange_recipients(refchange)

3037 - return self.__cli_recipients

3038 -

3039 - def get_announce_recipients(self, annotated_tag_change):

3040 - if self.__cli_recipients is None:

3041 - return super(CLIRecipientsEnvironmentMixin,

3042 - self).get_announce_recipients(annotated_tag_change)

3043 - return self.__cli_recipients

3044 -

3045 - def get_revision_recipients(self, revision):

3046 - if self.__cli_recipients is None:

3047 - return super(CLIRecipientsEnvironmentMixin,

3048 - self).get_revision_recipients(revision)

3049 - return self.__cli_recipients

3050 -

3051 -

3052 -class ConfigRecipientsEnvironmentMixin(

3053 - ConfigEnvironmentMixin,

3054 - StaticRecipientsEnvironmentMixin

3055 - ):

3056 - """Determine recipients statically based on config."""

3057 -

3058 - def __init__(self, config, **kw):

3059 - super(ConfigRecipientsEnvironmentMixin, self).__init__(

3060 - config=config,

3061 - refchange_recipients=self._get_recipients(

3062 - config, 'refchangelist', 'mailinglist',

3063 - ),

3064 - announce_recipients=self._get_recipients(

3065 - config, 'announcelist', 'refchangelist', 'mailinglist',

3066 - ),

3067 - revision_recipients=self._get_recipients(

3068 - config, 'commitlist', 'mailinglist',

3069 - ),

3070 - scancommitforcc=config.get('scancommitforcc'),

3071 - **kw

3072 - )

3073 -

3074 - def _get_recipients(self, config, *names):

3075 - """Return the recipients for a particular type of message.

3076 -

3077 - Return the list of email addresses to which a particular type

3078 - of notification email should be sent, by looking at the config

3079 - value for "multimailhook.$name" for each of names. Use the

3080 - value from the first name that is configured. The return

3081 - value is a (possibly empty) string containing RFC 2822 email

3082 - addresses separated by commas. If no configuration could be

3083 - found, raise a ConfigurationException."""

3084 -

3085 - for name in names:

3086 - lines = config.get_all(name)

3087 - if lines is not None:

3088 - lines = [line.strip() for line in lines]

3089 - # Single "none" is a special value equivalen to empty string.

3090 - if lines == ['none']:

3091 - lines = ['']

3092 - return ', '.join(lines)

3093 - else:

3094 - return ''

3095 -

3096 -

3097 -class StaticRefFilterEnvironmentMixin(Environment):

3098 - """Set branch filter statically based on constructor parameters."""

3099 -

3100 - def __init__(self, ref_filter_incl_regex, ref_filter_excl_regex,

3101 - ref_filter_do_send_regex, ref_filter_dont_send_regex,

3102 - **kw):

3103 - super(StaticRefFilterEnvironmentMixin, self).__init__(**kw)

3104 -

3105 - if ref_filter_incl_regex and ref_filter_excl_regex:

3106 - raise ConfigurationException(

3107 - "Cannot specify both a ref inclusion and exclusion regex.")

3108 - self.__is_inclusion_filter = bool(ref_filter_incl_regex)

3109 - default_exclude = self.get_default_ref_ignore_regex()

3110 - if ref_filter_incl_regex:

3111 - ref_filter_regex = ref_filter_incl_regex

3112 - elif ref_filter_excl_regex:

3113 - ref_filter_regex = ref_filter_excl_regex + '|' + default_exclude

3114 - else:

3115 - ref_filter_regex = default_exclude

3116 - try:

3117 - self.__compiled_regex = re.compile(ref_filter_regex)

3118 - except Exception:

3119 - raise ConfigurationException(

3120 - 'Invalid Ref Filter Regex "%s": %s' % (ref_filter_regex, sys.exc_info()[1]))

3121 -

3122 - if ref_filter_do_send_regex and ref_filter_dont_send_regex:

3123 - raise ConfigurationException(

3124 - "Cannot specify both a ref doSend and dontSend regex.")

3125 - self.__is_do_send_filter = bool(ref_filter_do_send_regex)

3126 - if ref_filter_do_send_regex:

3127 - ref_filter_send_regex = ref_filter_do_send_regex

3128 - elif ref_filter_dont_send_regex:

3129 - ref_filter_send_regex = ref_filter_dont_send_regex

3130 - else:

3131 - ref_filter_send_regex = '.*'

3132 - self.__is_do_send_filter = True

3133 - try:

3134 - self.__send_compiled_regex = re.compile(ref_filter_send_regex)

3135 - except Exception:

3136 - raise ConfigurationException(

3137 - 'Invalid Ref Filter Regex "%s": %s' %

3138 - (ref_filter_send_regex, sys.exc_info()[1]))

3139 -

3140 - def get_ref_filter_regex(self, send_filter=False):

3141 - if send_filter:

3142 - return self.__send_compiled_regex, self.__is_do_send_filter

3143 - else:

3144 - return self.__compiled_regex, self.__is_inclusion_filter

3145 -

3146 -

3147 -class ConfigRefFilterEnvironmentMixin(

3148 - ConfigEnvironmentMixin,

3149 - StaticRefFilterEnvironmentMixin

3150 - ):

3151 - """Determine branch filtering statically based on config."""

3152 -

3153 - def _get_regex(self, config, key):

3154 - """Get a list of whitespace-separated regex. The refFilter* config

3155 - variables are multivalued (hence the use of get_all), and we

3156 - allow each entry to be a whitespace-separated list (hence the

3157 - split on each line). The whole thing is glued into a single regex."""

3158 - values = config.get_all(key)

3159 - if values is None:

3160 - return values

3161 - items = []

3162 - for line in values:

3163 - for i in line.split():

3164 - items.append(i)

3165 - if items == []:

3166 - return None

3167 - return '|'.join(items)

3168 -

3169 - def __init__(self, config, **kw):

3170 - super(ConfigRefFilterEnvironmentMixin, self).__init__(

3171 - config=config,

3172 - ref_filter_incl_regex=self._get_regex(config, 'refFilterInclusionRegex'),

3173 - ref_filter_excl_regex=self._get_regex(config, 'refFilterExclusionRegex'),

3174 - ref_filter_do_send_regex=self._get_regex(config, 'refFilterDoSendRegex'),

3175 - ref_filter_dont_send_regex=self._get_regex(config, 'refFilterDontSendRegex'),

3176 - **kw

3177 - )

3178 -

3179 -

3180 -class ProjectdescEnvironmentMixin(Environment):

3181 - """Make a "projectdesc" value available for templates.

3182 -

3183 - By default, it is set to the first line of $GIT_DIR/description

3184 - (if that file is present and appears to be set meaningfully)."""

3185 -

3186 - def __init__(self, **kw):

3187 - super(ProjectdescEnvironmentMixin, self).__init__(**kw)

3188 - self.COMPUTED_KEYS += ['projectdesc']

3189 -

3190 - def get_projectdesc(self):

3191 - """Return a one-line description of the project."""

3192 -

3193 - git_dir = get_git_dir()

3194 - try:

3195 - projectdesc = open(os.path.join(git_dir, 'description')).readline().strip()

3196 - if projectdesc and not projectdesc.startswith('Unnamed repository'):

3197 - return projectdesc

3198 - except IOError:

3199 - pass

3200 -

3201 - return 'UNNAMED PROJECT'

3202 -

3203 -

3204 -class GenericEnvironmentMixin(Environment):

3205 - def get_pusher(self):

3206 - return self.osenv.get('USER', self.osenv.get('USERNAME', 'unknown user'))

3207 -

3208 -

3209 -class GitoliteEnvironmentHighPrecMixin(Environment):

3210 - def get_pusher(self):

3211 - return self.osenv.get('GL_USER', 'unknown user')

3212 -

3213 -

3214 -class GitoliteEnvironmentLowPrecMixin(

3215 - ConfigEnvironmentMixin,

3216 - Environment):

3217 -

3218 - def get_repo_shortname(self):

3219 - # The gitolite environment variable $GL_REPO is a pretty good

3220 - # repo_shortname (though it's probably not as good as a value

3221 - # the user might have explicitly put in his config).

3222 - return (

3223 - self.osenv.get('GL_REPO', None) or

3224 - super(GitoliteEnvironmentLowPrecMixin, self).get_repo_shortname()

3225 - )

3226 -

3227 - @staticmethod

3228 - def _compile_regex(re_template):

3229 - return (

3230 - re.compile(re_template % x)

3231 - for x in (

3232 - r'BEGIN\s+USER\s+EMAILS',

3233 - r'([^\s]+)\s+(.*)',

3234 - r'END\s+USER\s+EMAILS',

3235 - ))

3236 -

3237 - def get_fromaddr(self, change=None):

3238 - GL_USER = self.osenv.get('GL_USER')

3239 - if GL_USER is not None:

3240 - # Find the path to gitolite.conf. Note that gitolite v3

3241 - # did away with the GL_ADMINDIR and GL_CONF environment

3242 - # variables (they are now hard-coded).

3243 - GL_ADMINDIR = self.osenv.get(

3244 - 'GL_ADMINDIR',

3245 - os.path.expanduser(os.path.join('~', '.gitolite')))

3246 - GL_CONF = self.osenv.get(

3247 - 'GL_CONF',

3248 - os.path.join(GL_ADMINDIR, 'conf', 'gitolite.conf'))

3249 -

3250 - mailaddress_map = self.config.get('MailaddressMap')

3251 - # If relative, consider relative to GL_CONF:

3252 - if mailaddress_map:

3253 - mailaddress_map = os.path.join(os.path.dirname(GL_CONF),

3254 - mailaddress_map)

3255 - if os.path.isfile(mailaddress_map):

3256 - f = open(mailaddress_map, 'rU')

3257 - try:

3258 - # Leading '#' is optional

3259 - re_begin, re_user, re_end = self._compile_regex(

3260 - r'^(?:\s*#)?\s*%s\s*$')

3261 - for l in f:

3262 - l = l.rstrip('\n')

3263 - if re_begin.match(l) or re_end.match(l):

3264 - continue # Ignore these lines

3265 - m = re_user.match(l)

3266 - if m:

3267 - if m.group(1) == GL_USER:

3268 - return m.group(2)

3269 - else:

3270 - continue # Not this user, but not an error

3271 - raise ConfigurationException(

3272 - "Syntax error in mail address map.\n"

3273 - "Check file {}.\n"

3274 - "Line: {}".format(mailaddress_map, l))

3275 -

3276 - finally:

3277 - f.close()

3278 -

3279 - if os.path.isfile(GL_CONF):

3280 - f = open(GL_CONF, 'rU')

3281 - try:

3282 - in_user_emails_section = False

3283 - re_begin, re_user, re_end = self._compile_regex(

3284 - r'^\s*#\s*%s\s*$')

3285 - for l in f:

3286 - l = l.rstrip('\n')

3287 - if not in_user_emails_section:

3288 - if re_begin.match(l):

3289 - in_user_emails_section = True

3290 - continue

3291 - if re_end.match(l):

3292 - break

3293 - m = re_user.match(l)

3294 - if m and m.group(1) == GL_USER:

3295 - return m.group(2)

3296 - finally:

3297 - f.close()

3298 - return super(GitoliteEnvironmentLowPrecMixin, self).get_fromaddr(change)

3299 -

3300 -

3301 -class IncrementalDateTime(object):

3302 - """Simple wrapper to give incremental date/times.

3303 -

3304 - Each call will result in a date/time a second later than the

3305 - previous call. This can be used to falsify email headers, to

3306 - increase the likelihood that email clients sort the emails

3307 - correctly."""

3308 -

3309 - def __init__(self):

3310 - self.time = time.time()

3311 - self.next = self.__next__ # Python 2 backward compatibility

3312 -

3313 - def __next__(self):

3314 - formatted = formatdate(self.time, True)

3315 - self.time += 1

3316 - return formatted

3317 -

3318 -

3319 -class StashEnvironmentHighPrecMixin(Environment):

3320 - def __init__(self, user=None, repo=None, **kw):

3321 - super(StashEnvironmentHighPrecMixin,

3322 - self).__init__(user=user, repo=repo, **kw)

3323 - self.__user = user

3324 - self.__repo = repo

3325 -

3326 - def get_pusher(self):

3327 - return re.match(r'(.*?)\s*<', self.__user).group(1)

3328 -

3329 - def get_pusher_email(self):

3330 - return self.__user

3331 -

3332 -

3333 -class StashEnvironmentLowPrecMixin(Environment):

3334 - def __init__(self, user=None, repo=None, **kw):

3335 - super(StashEnvironmentLowPrecMixin, self).__init__(**kw)

3336 - self.__repo = repo

3337 - self.__user = user

3338 -

3339 - def get_repo_shortname(self):

3340 - return self.__repo

3341 -

3342 - def get_fromaddr(self, change=None):

3343 - return self.__user

3344 -

3345 -

3346 -class GerritEnvironmentHighPrecMixin(Environment):

3347 - def __init__(self, project=None, submitter=None, update_method=None, **kw):

3348 - super(GerritEnvironmentHighPrecMixin,

3349 - self).__init__(submitter=submitter, project=project, **kw)

3350 - self.__project = project

3351 - self.__submitter = submitter

3352 - self.__update_method = update_method

3353 - "Make an 'update_method' value available for templates."

3354 - self.COMPUTED_KEYS += ['update_method']

3355 -

3356 - def get_pusher(self):

3357 - if self.__submitter:

3358 - if self.__submitter.find('<') != -1:

3359 - # Submitter has a configured email, we transformed

3360 - # __submitter into an RFC 2822 string already.

3361 - return re.match(r'(.*?)\s*<', self.__submitter).group(1)

3362 - else:

3363 - # Submitter has no configured email, it's just his name.

3364 - return self.__submitter

3365 - else:

3366 - # If we arrive here, this means someone pushed "Submit" from

3367 - # the gerrit web UI for the CR (or used one of the programmatic

3368 - # APIs to do the same, such as gerrit review) and the

3369 - # merge/push was done by the Gerrit user. It was technically

3370 - # triggered by someone else, but sadly we have no way of

3371 - # determining who that someone else is at this point.

3372 - return 'Gerrit' # 'unknown user'?

3373 -

3374 - def get_pusher_email(self):

3375 - if self.__submitter:

3376 - return self.__submitter

3377 - else:

3378 - return super(GerritEnvironmentHighPrecMixin, self).get_pusher_email()

3379 -

3380 - def get_default_ref_ignore_regex(self):

3381 - default = super(GerritEnvironmentHighPrecMixin, self).get_default_ref_ignore_regex()

3382 - return default + '|^refs/changes/|^refs/cache-automerge/|^refs/meta/'

3383 -

3384 - def get_revision_recipients(self, revision):

3385 - # Merge commits created by Gerrit when users hit "Submit this patchset"

3386 - # in the Web UI (or do equivalently with REST APIs or the gerrit review

3387 - # command) are not something users want to see an individual email for.

3388 - # Filter them out.

3389 - committer = read_git_output(['log', '--no-walk', '--format=%cN',

3390 - revision.rev.sha1])

3391 - if committer == 'Gerrit Code Review':

3392 - return []

3393 - else:

3394 - return super(GerritEnvironmentHighPrecMixin, self).get_revision_recipients(revision)

3395 -

3396 - def get_update_method(self):

3397 - return self.__update_method

3398 -

3399 -

3400 -class GerritEnvironmentLowPrecMixin(Environment):

3401 - def __init__(self, project=None, submitter=None, **kw):

3402 - super(GerritEnvironmentLowPrecMixin, self).__init__(**kw)

3403 - self.__project = project

3404 - self.__submitter = submitter

3405 -

3406 - def get_repo_shortname(self):

3407 - return self.__project

3408 -

3409 - def get_fromaddr(self, change=None):

3410 - if self.__submitter and self.__submitter.find('<') != -1:

3411 - return self.__submitter

3412 - else:

3413 - return super(GerritEnvironmentLowPrecMixin, self).get_fromaddr(change)

3414 -

3415 -

3416 -class Push(object):

3417 - """Represent an entire push (i.e., a group of ReferenceChanges).

3418 -

3419 - It is easy to figure out what commits were added to a *branch* by

3420 - a Reference change:

3421 -

3422 - git rev-list change.old..change.new

3423 -

3424 - or removed from a *branch*:

3425 -

3426 - git rev-list change.new..change.old

3427 -

3428 - But it is not quite so trivial to determine which entirely new

3429 - commits were added to the *repository* by a push and which old

3430 - commits were discarded by a push. A big part of the job of this

3431 - class is to figure out these things, and to make sure that new

3432 - commits are only detailed once even if they were added to multiple

3433 - references.

3434 -

3435 - The first step is to determine the "other" references--those

3436 - unaffected by the current push. They are computed by listing all

3437 - references then removing any affected by this push. The results

3438 - are stored in Push._other_ref_sha1s.

3439 -

3440 - The commits contained in the repository before this push were

3441 -

3442 - git rev-list other1 other2 other3 ... change1.old change2.old ...

3443 -

3444 - Where "changeN.old" is the old value of one of the references

3445 - affected by this push.

3446 -

3447 - The commits contained in the repository after this push are

3448 -

3449 - git rev-list other1 other2 other3 ... change1.new change2.new ...

3450 -

3451 - The commits added by this push are the difference between these

3452 - two sets, which can be written

3453 -

3454 - git rev-list \

3455 - ^other1 ^other2 ... \

3456 - ^change1.old ^change2.old ... \

3457 - change1.new change2.new ...

3458 -

3459 - The commits removed by this push can be computed by

3460 -

3461 - git rev-list \

3462 - ^other1 ^other2 ... \

3463 - ^change1.new ^change2.new ... \

3464 - change1.old change2.old ...

3465 -

3466 - The last point is that it is possible that other pushes are

3467 - occurring simultaneously to this one, so reference values can

3468 - change at any time. It is impossible to eliminate all race

3469 - conditions, but we reduce the window of time during which problems

3470 - can occur by translating reference names to SHA1s as soon as

3471 - possible and working with SHA1s thereafter (because SHA1s are

3472 - immutable)."""

3473 -

3474 - # A map {(changeclass, changetype): integer} specifying the order

3475 - # that reference changes will be processed if multiple reference

3476 - # changes are included in a single push. The order is significant

3477 - # mostly because new commit notifications are threaded together

3478 - # with the first reference change that includes the commit. The

3479 - # following order thus causes commits to be grouped with branch

3480 - # changes (as opposed to tag changes) if possible.

3481 - SORT_ORDER = dict(

3482 - (value, i) for (i, value) in enumerate([

3483 - (BranchChange, 'update'),

3484 - (BranchChange, 'create'),

3485 - (AnnotatedTagChange, 'update'),

3486 - (AnnotatedTagChange, 'create'),

3487 - (NonAnnotatedTagChange, 'update'),

3488 - (NonAnnotatedTagChange, 'create'),

3489 - (BranchChange, 'delete'),

3490 - (AnnotatedTagChange, 'delete'),

3491 - (NonAnnotatedTagChange, 'delete'),

3492 - (OtherReferenceChange, 'update'),

3493 - (OtherReferenceChange, 'create'),

3494 - (OtherReferenceChange, 'delete'),

3495 - ])

3496 - )

3497 -

3498 - def __init__(self, environment, changes, ignore_other_refs=False):

3499 - self.changes = sorted(changes, key=self._sort_key)

3500 - self.__other_ref_sha1s = None

3501 - self.__cached_commits_spec = {}

3502 - self.environment = environment

3503 -

3504 - if ignore_other_refs:

3505 - self.__other_ref_sha1s = set()

3506 -

3507 - @classmethod

3508 - def _sort_key(klass, change):

3509 - return (klass.SORT_ORDER[change.__class__, change.change_type], change.refname,)

3510 -

3511 - @property

3512 - def _other_ref_sha1s(self):

3513 - """The GitObjects referred to by references unaffected by this push.

3514 - """

3515 - if self.__other_ref_sha1s is None:

3516 - # The refnames being changed by this push:

3517 - updated_refs = set(

3518 - change.refname

3519 - for change in self.changes

3520 - )

3521 -

3522 - # The SHA-1s of commits referred to by all references in this

3523 - # repository *except* updated_refs:

3524 - sha1s = set()

3525 - fmt = (

3526 - '%(objectname) %(objecttype) %(refname)\n'

3527 - '%(*objectname) %(*objecttype) %(refname)'

3528 - )

3529 - ref_filter_regex, is_inclusion_filter = \

3530 - self.environment.get_ref_filter_regex()

3531 - for line in read_git_lines(

3532 - ['for-each-ref', '--format=%s' % (fmt,)]):

3533 - (sha1, type, name) = line.split(' ', 2)

3534 - if (sha1 and type == 'commit' and

3535 - name not in updated_refs and

3536 - include_ref(name, ref_filter_regex, is_inclusion_filter)):

3537 - sha1s.add(sha1)

3538 -

3539 - self.__other_ref_sha1s = sha1s

3540 -

3541 - return self.__other_ref_sha1s

3542 -

3543 - def _get_commits_spec_incl(self, new_or_old, reference_change=None):

3544 - """Get new or old SHA-1 from one or each of the changed refs.

3545 -

3546 - Return a list of SHA-1 commit identifier strings suitable as

3547 - arguments to 'git rev-list' (or 'git log' or ...). The

3548 - returned identifiers are either the old or new values from one

3549 - or all of the changed references, depending on the values of

3550 - new_or_old and reference_change.

3551 -

3552 - new_or_old is either the string 'new' or the string 'old'. If

3553 - 'new', the returned SHA-1 identifiers are the new values from

3554 - each changed reference. If 'old', the SHA-1 identifiers are

3555 - the old values from each changed reference.

3556 -

3557 - If reference_change is specified and not None, only the new or

3558 - old reference from the specified reference is included in the

3559 - return value.

3560 -

3561 - This function returns None if there are no matching revisions

3562 - (e.g., because a branch was deleted and new_or_old is 'new').

3563 - """

3564 -

3565 - if not reference_change:

3566 - incl_spec = sorted(

3567 - getattr(change, new_or_old).sha1

3568 - for change in self.changes

3569 - if getattr(change, new_or_old)

3570 - )

3571 - if not incl_spec:

3572 - incl_spec = None

3573 - elif not getattr(reference_change, new_or_old).commit_sha1:

3574 - incl_spec = None

3575 - else:

3576 - incl_spec = [getattr(reference_change, new_or_old).commit_sha1]

3577 - return incl_spec

3578 -

3579 - def _get_commits_spec_excl(self, new_or_old):

3580 - """Get exclusion revisions for determining new or discarded commits.

3581 -

3582 - Return a list of strings suitable as arguments to 'git

3583 - rev-list' (or 'git log' or ...) that will exclude all

3584 - commits that, depending on the value of new_or_old, were

3585 - either previously in the repository (useful for determining

3586 - which commits are new to the repository) or currently in the

3587 - repository (useful for determining which commits were

3588 - discarded from the repository).

3589 -

3590 - new_or_old is either the string 'new' or the string 'old'. If

3591 - 'new', the commits to be excluded are those that were in the

3592 - repository before the push. If 'old', the commits to be

3593 - excluded are those that are currently in the repository. """

3594 -

3595 - old_or_new = {'old': 'new', 'new': 'old'}[new_or_old]

3596 - excl_revs = self._other_ref_sha1s.union(

3597 - getattr(change, old_or_new).sha1

3598 - for change in self.changes

3599 - if getattr(change, old_or_new).type in ['commit', 'tag']

3600 - )

3601 - return ['^' + sha1 for sha1 in sorted(excl_revs)]

3602 -

3603 - def get_commits_spec(self, new_or_old, reference_change=None):

3604 - """Get rev-list arguments for added or discarded commits.

3605 -

3606 - Return a list of strings suitable as arguments to 'git

3607 - rev-list' (or 'git log' or ...) that select those commits

3608 - that, depending on the value of new_or_old, are either new to

3609 - the repository or were discarded from the repository.

3610 -

3611 - new_or_old is either the string 'new' or the string 'old'. If

3612 - 'new', the returned list is used to select commits that are

3613 - new to the repository. If 'old', the returned value is used

3614 - to select the commits that have been discarded from the

3615 - repository.

3616 -

3617 - If reference_change is specified and not None, the new or

3618 - discarded commits are limited to those that are reachable from

3619 - the new or old value of the specified reference.

3620 -

3621 - This function returns None if there are no added (or discarded)

3622 - revisions.

3623 - """

3624 - key = (new_or_old, reference_change)

3625 - if key not in self.__cached_commits_spec:

3626 - ret = self._get_commits_spec_incl(new_or_old, reference_change)

3627 - if ret is not None:

3628 - ret.extend(self._get_commits_spec_excl(new_or_old))

3629 - self.__cached_commits_spec[key] = ret

3630 - return self.__cached_commits_spec[key]

3631 -

3632 - def get_new_commits(self, reference_change=None):

3633 - """Return a list of commits added by this push.

3634 -

3635 - Return a list of the object names of commits that were added

3636 - by the part of this push represented by reference_change. If

3637 - reference_change is None, then return a list of *all* commits

3638 - added by this push."""

3639 -

3640 - spec = self.get_commits_spec('new', reference_change)

3641 - return git_rev_list(spec)

3642 -

3643 - def get_discarded_commits(self, reference_change):

3644 - """Return a list of commits discarded by this push.

3645 -

3646 - Return a list of the object names of commits that were

3647 - entirely discarded from the repository by the part of this

3648 - push represented by reference_change."""

3649 -

3650 - spec = self.get_commits_spec('old', reference_change)

3651 - return git_rev_list(spec)

3652 -

3653 - def send_emails(self, mailer, body_filter=None):

3654 - """Use send all of the notification emails needed for this push.

3655 -

3656 - Use send all of the notification emails (including reference

3657 - change emails and commit emails) needed for this push. Send

3658 - the emails using mailer. If body_filter is not None, then use

3659 - it to filter the lines that are intended for the email

3660 - body."""

3661 -

3662 - # The sha1s of commits that were introduced by this push.

3663 - # They will be removed from this set as they are processed, to

3664 - # guarantee that one (and only one) email is generated for

3665 - # each new commit.

3666 - unhandled_sha1s = set(self.get_new_commits())

3667 - send_date = IncrementalDateTime()

3668 - for change in self.changes:

3669 - sha1s = []

3670 - for sha1 in reversed(list(self.get_new_commits(change))):

3671 - if sha1 in unhandled_sha1s:

3672 - sha1s.append(sha1)

3673 - unhandled_sha1s.remove(sha1)

3674 -

3675 - # Check if we've got anyone to send to

3676 - if not change.recipients:

3677 - change.environment.log_warning(

3678 - '*** no recipients configured so no email will be sent\n'

3679 - '*** for %r update %s->%s'

3680 - % (change.refname, change.old.sha1, change.new.sha1,)

3681 - )

3682 - else:

3683 - if not change.environment.quiet:

3684 - change.environment.log_msg(

3685 - 'Sending notification emails to: %s' % (change.recipients,))

3686 - extra_values = {'send_date': next(send_date)}

3687 -

3688 - rev = change.send_single_combined_email(sha1s)

3689 - if rev:

3690 - mailer.send(

3691 - change.generate_combined_email(self, rev, body_filter, extra_values),

3692 - rev.recipients,

3693 - )

3694 - # This change is now fully handled; no need to handle

3695 - # individual revisions any further.

3696 - continue

3697 - else:

3698 - mailer.send(

3699 - change.generate_email(self, body_filter, extra_values),

3700 - change.recipients,

3701 - )

3702 -

3703 - max_emails = change.environment.maxcommitemails

3704 - if max_emails and len(sha1s) > max_emails:

3705 - change.environment.log_warning(

3706 - '*** Too many new commits (%d), not sending commit emails.\n' % len(sha1s) +

3707 - '*** Try setting multimailhook.maxCommitEmails to a greater value\n' +

3708 - '*** Currently, multimailhook.maxCommitEmails=%d' % max_emails

3709 - )

3710 - return

3711 -

3712 - for (num, sha1) in enumerate(sha1s):

3713 - rev = Revision(change, GitObject(sha1), num=num + 1, tot=len(sha1s))

3714 - if len(rev.parents) > 1 and change.environment.excludemergerevisions:

3715 - # skipping a merge commit

3716 - continue

3717 - if not rev.recipients and rev.cc_recipients:

3718 - change.environment.log_msg('*** Replacing Cc: with To:')

3719 - rev.recipients = rev.cc_recipients

3720 - rev.cc_recipients = None

3721 - if rev.recipients:

3722 - extra_values = {'send_date': next(send_date)}

3723 - mailer.send(

3724 - rev.generate_email(self, body_filter, extra_values),

3725 - rev.recipients,

3726 - )

3727 -

3728 - # Consistency check:

3729 - if unhandled_sha1s:

3730 - change.environment.log_error(

3731 - 'ERROR: No emails were sent for the following new commits:\n'

3732 - ' %s'

3733 - % ('\n '.join(sorted(unhandled_sha1s)),)

3734 - )

3735 -

3736 -

3737 -def include_ref(refname, ref_filter_regex, is_inclusion_filter):

3738 - does_match = bool(ref_filter_regex.search(refname))

3739 - if is_inclusion_filter:

3740 - return does_match

3741 - else: # exclusion filter -- we include the ref if the regex doesn't match

3742 - return not does_match

3743 -

3744 -

3745 -def run_as_post_receive_hook(environment, mailer):

3746 - environment.check()

3747 - send_filter_regex, send_is_inclusion_filter = environment.get_ref_filter_regex(True)

3748 - ref_filter_regex, is_inclusion_filter = environment.get_ref_filter_regex(False)

3749 - changes = []

3750 - while True:

3751 - line = read_line(sys.stdin)

3752 - if line == '':

3753 - break

3754 - (oldrev, newrev, refname) = line.strip().split(' ', 2)

3755 - environment.get_logger().debug(

3756 - "run_as_post_receive_hook: oldrev=%s, newrev=%s, refname=%s" %

3757 - (oldrev, newrev, refname))

3758 -

3759 - if not include_ref(refname, ref_filter_regex, is_inclusion_filter):

3760 - continue

3761 - if not include_ref(refname, send_filter_regex, send_is_inclusion_filter):

3762 - continue

3763 - changes.append(

3764 - ReferenceChange.create(environment, oldrev, newrev, refname)

3765 - )

3766 - if not changes:

3767 - mailer.close()

3768 - return

3769 - push = Push(environment, changes)

3770 - try:

3771 - push.send_emails(mailer, body_filter=environment.filter_body)

3772 - finally:

3773 - mailer.close()

3774 -

3775 -

3776 -def run_as_update_hook(environment, mailer, refname, oldrev, newrev, force_send=False):

3777 - environment.check()

3778 - send_filter_regex, send_is_inclusion_filter = environment.get_ref_filter_regex(True)

3779 - ref_filter_regex, is_inclusion_filter = environment.get_ref_filter_regex(False)

3780 - if not include_ref(refname, ref_filter_regex, is_inclusion_filter):

3781 - return

3782 - if not include_ref(refname, send_filter_regex, send_is_inclusion_filter):

3783 - return

3784 - changes = [

3785 - ReferenceChange.create(

3786 - environment,

3787 - read_git_output(['rev-parse', '--verify', oldrev]),

3788 - read_git_output(['rev-parse', '--verify', newrev]),

3789 - refname,

3790 - ),

3791 - ]

3792 - if not changes:

3793 - mailer.close()

3794 - return

3795 - push = Push(environment, changes, force_send)

3796 - try:

3797 - push.send_emails(mailer, body_filter=environment.filter_body)

3798 - finally:

3799 - mailer.close()

3800 -

3801 -

3802 -def check_ref_filter(environment):

3803 - send_filter_regex, send_is_inclusion = environment.get_ref_filter_regex(True)

3804 - ref_filter_regex, ref_is_inclusion = environment.get_ref_filter_regex(False)

3805 -

3806 - def inc_exc_lusion(b):

3807 - if b:

3808 - return 'inclusion'

3809 - else:

3810 - return 'exclusion'

3811 -

3812 - if send_filter_regex:

3813 - sys.stdout.write("DoSend/DontSend filter regex (" +

3814 - (inc_exc_lusion(send_is_inclusion)) +

3815 - '): ' + send_filter_regex.pattern +

3816 - '\n')

3817 - if send_filter_regex:

3818 - sys.stdout.write("Include/Exclude filter regex (" +

3819 - (inc_exc_lusion(ref_is_inclusion)) +

3820 - '): ' + ref_filter_regex.pattern +

3821 - '\n')

3822 - sys.stdout.write(os.linesep)

3823 -

3824 - sys.stdout.write(

3825 - "Refs marked as EXCLUDE are excluded by either refFilterInclusionRegex\n"

3826 - "or refFilterExclusionRegex. No emails will be sent for commits included\n"

3827 - "in these refs.\n"

3828 - "Refs marked as DONT-SEND are excluded by either refFilterDoSendRegex or\n"

3829 - "refFilterDontSendRegex, but not by either refFilterInclusionRegex or\n"

3830 - "refFilterExclusionRegex. Emails will be sent for commits included in these\n"

3831 - "refs only when the commit reaches a ref which isn't excluded.\n"

3832 - "Refs marked as DO-SEND are not excluded by any filter. Emails will\n"

3833 - "be sent normally for commits included in these refs.\n")

3834 -

3835 - sys.stdout.write(os.linesep)

3836 -

3837 - for refname in read_git_lines(['for-each-ref', '--format', '%(refname)']):

3838 - sys.stdout.write(refname)

3839 - if not include_ref(refname, ref_filter_regex, ref_is_inclusion):

3840 - sys.stdout.write(' EXCLUDE')

3841 - elif not include_ref(refname, send_filter_regex, send_is_inclusion):

3842 - sys.stdout.write(' DONT-SEND')

3843 - else:

3844 - sys.stdout.write(' DO-SEND')

3845 -

3846 - sys.stdout.write(os.linesep)

3847 -

3848 -

3849 -def show_env(environment, out):

3850 - out.write('Environment values:\n')

3851 - for (k, v) in sorted(environment.get_values().items()):

3852 - if k: # Don't show the {'' : ''} pair.

3853 - out.write(' %s : %r\n' % (k, v))

3854 - out.write('\n')

3855 - # Flush to avoid interleaving with further log output

3856 - out.flush()

3857 -

3858 -

3859 -def check_setup(environment):

3860 - environment.check()

3861 - show_env(environment, sys.stdout)

3862 - sys.stdout.write("Now, checking that git-multimail's standard input "

3863 - "is properly set ..." + os.linesep)

3864 - sys.stdout.write("Please type some text and then press Return" + os.linesep)

3865 - stdin = sys.stdin.readline()

3866 - sys.stdout.write("You have just entered:" + os.linesep)

3867 - sys.stdout.write(stdin)

3868 - sys.stdout.write("git-multimail seems properly set up." + os.linesep)

3869 -

3870 -

3871 -def choose_mailer(config, environment):

3872 - mailer = config.get('mailer', default='sendmail')

3873 -

3874 - if mailer == 'smtp':

3875 - smtpserver = config.get('smtpserver', default='localhost')

3876 - smtpservertimeout = float(config.get('smtpservertimeout', default=10.0))

3877 - smtpserverdebuglevel = int(config.get('smtpserverdebuglevel', default=0))

3878 - smtpencryption = config.get('smtpencryption', default='none')

3879 - smtpuser = config.get('smtpuser', default='')

3880 - smtppass = config.get('smtppass', default='')

3881 - smtpcacerts = config.get('smtpcacerts', default='')

3882 - mailer = SMTPMailer(

3883 - environment,

3884 - envelopesender=(environment.get_sender() or environment.get_fromaddr()),

3885 - smtpserver=smtpserver, smtpservertimeout=smtpservertimeout,

3886 - smtpserverdebuglevel=smtpserverdebuglevel,

3887 - smtpencryption=smtpencryption,

3888 - smtpuser=smtpuser,

3889 - smtppass=smtppass,

3890 - smtpcacerts=smtpcacerts

3891 - )

3892 - elif mailer == 'sendmail':

3893 - command = config.get('sendmailcommand')

3894 - if command:

3895 - command = shlex.split(command)

3896 - mailer = SendMailer(environment,

3897 - command=command, envelopesender=environment.get_sender())

3898 - else:

3899 - environment.log_error(

3900 - 'fatal: multimailhook.mailer is set to an incorrect value: "%s"\n' % mailer +

3901 - 'please use one of "smtp" or "sendmail".'

3902 - )

3903 - sys.exit(1)

3904 - return mailer

3905 -

3906 -

3907 -KNOWN_ENVIRONMENTS = {

3908 - 'generic': {'highprec': GenericEnvironmentMixin},

3909 - 'gitolite': {'highprec': GitoliteEnvironmentHighPrecMixin,

3910 - 'lowprec': GitoliteEnvironmentLowPrecMixin},

3911 - 'stash': {'highprec': StashEnvironmentHighPrecMixin,

3912 - 'lowprec': StashEnvironmentLowPrecMixin},

3913 - 'gerrit': {'highprec': GerritEnvironmentHighPrecMixin,

3914 - 'lowprec': GerritEnvironmentLowPrecMixin},

3915 - }

3916 -

3917 -

3918 -def choose_environment(config, osenv=None, env=None, recipients=None,

3919 - hook_info=None):

3920 - env_name = choose_environment_name(config, env, osenv)

3921 - environment_klass = build_environment_klass(env_name)

3922 - env = build_environment(environment_klass, env_name, config,

3923 - osenv, recipients, hook_info)

3924 - return env

3925 -

3926 -

3927 -def choose_environment_name(config, env, osenv):

3928 - if not osenv:

3929 - osenv = os.environ

3930 -

3931 - if not env:

3932 - env = config.get('environment')

3933 -

3934 - if not env:

3935 - if 'GL_USER' in osenv and 'GL_REPO' in osenv:

3936 - env = 'gitolite'

3937 - else:

3938 - env = 'generic'

3939 - return env

3940 -

3941 -

3942 -COMMON_ENVIRONMENT_MIXINS = [

3943 - ConfigRecipientsEnvironmentMixin,

3944 - CLIRecipientsEnvironmentMixin,

3945 - ConfigRefFilterEnvironmentMixin,

3946 - ProjectdescEnvironmentMixin,

3947 - ConfigMaxlinesEnvironmentMixin,

3948 - ComputeFQDNEnvironmentMixin,

3949 - ConfigFilterLinesEnvironmentMixin,

3950 - PusherDomainEnvironmentMixin,

3951 - ConfigOptionsEnvironmentMixin,

3952 - ]

3953 -

3954 -

3955 -def build_environment_klass(env_name):

3956 - if 'class' in KNOWN_ENVIRONMENTS[env_name]:

3957 - return KNOWN_ENVIRONMENTS[env_name]['class']

3958 -

3959 - environment_mixins = []

3960 - known_env = KNOWN_ENVIRONMENTS[env_name]

3961 - if 'highprec' in known_env:

3962 - high_prec_mixin = known_env['highprec']

3963 - environment_mixins.append(high_prec_mixin)

3964 - environment_mixins = environment_mixins + COMMON_ENVIRONMENT_MIXINS

3965 - if 'lowprec' in known_env:

3966 - low_prec_mixin = known_env['lowprec']

3967 - environment_mixins.append(low_prec_mixin)

3968 - environment_mixins.append(Environment)

3969 - klass_name = env_name.capitalize() + 'Environment'

3970 - environment_klass = type(

3971 - klass_name,

3972 - tuple(environment_mixins),

3973 - {},

3974 - )

3975 - KNOWN_ENVIRONMENTS[env_name]['class'] = environment_klass

3976 - return environment_klass

3977 -

3978 -

3979 -GerritEnvironment = build_environment_klass('gerrit')

3980 -StashEnvironment = build_environment_klass('stash')

3981 -GitoliteEnvironment = build_environment_klass('gitolite')

3982 -GenericEnvironment = build_environment_klass('generic')

3983 -

3984 -

3985 -def build_environment(environment_klass, env, config,

3986 - osenv, recipients, hook_info):

3987 - environment_kw = {

3988 - 'osenv': osenv,

3989 - 'config': config,

3990 - }

3991 -

3992 - if env == 'stash':

3993 - environment_kw['user'] = hook_info['stash_user']

3994 - environment_kw['repo'] = hook_info['stash_repo']

3995 - elif env == 'gerrit':

3996 - environment_kw['project'] = hook_info['project']

3997 - environment_kw['submitter'] = hook_info['submitter']

3998 - environment_kw['update_method'] = hook_info['update_method']

3999 -

4000 - environment_kw['cli_recipients'] = recipients

4001 -

4002 - return environment_klass(**environment_kw)

4003 -

4004 -

4005 -def get_version():

4006 - oldcwd = os.getcwd()

4007 - try:

4008 - try:

4009 - os.chdir(os.path.dirname(os.path.realpath(__file__)))

4010 - git_version = read_git_output(['describe', '--tags', 'HEAD'])

4011 - if git_version == __version__:

4012 - return git_version

4013 - else:

4014 - return '%s (%s)' % (__version__, git_version)

4015 - except:

4016 - pass

4017 - finally:

4018 - os.chdir(oldcwd)

4019 - return __version__

4020 -

4021 -

4022 -def compute_gerrit_options(options, args, required_gerrit_options,

4023 - raw_refname):

4024 - if None in required_gerrit_options:

4025 - raise SystemExit("Error: Specify all of --oldrev, --newrev, --refname, "

4026 - "and --project; or none of them.")

4027 -

4028 - if options.environment not in (None, 'gerrit'):

4029 - raise SystemExit("Non-gerrit environments incompatible with --oldrev, "

4030 - "--newrev, --refname, and --project")

4031 - options.environment = 'gerrit'

4032 -

4033 - if args:

4034 - raise SystemExit("Error: Positional parameters not allowed with "

4035 - "--oldrev, --newrev, and --refname.")

4036 -

4037 - # Gerrit oddly omits 'refs/heads/' in the refname when calling

4038 - # ref-updated hook; put it back.

4039 - git_dir = get_git_dir()

4040 - if (not os.path.exists(os.path.join(git_dir, raw_refname)) and

4041 - os.path.exists(os.path.join(git_dir, 'refs', 'heads',

4042 - raw_refname))):

4043 - options.refname = 'refs/heads/' + options.refname

4044 -

4045 - # New revisions can appear in a gerrit repository either due to someone

4046 - # pushing directly (in which case options.submitter will be set), or they

4047 - # can press "Submit this patchset" in the web UI for some CR (in which

4048 - # case options.submitter will not be set and gerrit will not have provided

4049 - # us the information about who pressed the button).

4050 - #

4051 - # Note for the nit-picky: I'm lumping in REST API calls and the ssh

4052 - # gerrit review command in with "Submit this patchset" button, since they

4053 - # have the same effect.

4054 - if options.submitter:

4055 - update_method = 'pushed'

4056 - # The submitter argument is almost an RFC 2822 email address; change it

4057 - # from 'User Name (email@domain)' to 'User Name <email@domain>' so it is

4058 - options.submitter = options.submitter.replace('(', '<').replace(')', '>')

4059 - else:

4060 - update_method = 'submitted'

4061 - # Gerrit knew who submitted this patchset, but threw that information

4062 - # away when it invoked this hook. However, *IF* Gerrit created a

4063 - # merge to bring the patchset in (project 'Submit Type' is either

4064 - # "Always Merge", or is "Merge if Necessary" and happens to be

4065 - # necessary for this particular CR), then it will have the committer

4066 - # of that merge be 'Gerrit Code Review' and the author will be the

4067 - # person who requested the submission of the CR. Since this is fairly

4068 - # likely for most gerrit installations (of a reasonable size), it's

4069 - # worth the extra effort to try to determine the actual submitter.

4070 - rev_info = read_git_lines(['log', '--no-walk', '--merges',

4071 - '--format=%cN%n%aN <%aE>', options.newrev])

4072 - if rev_info and rev_info[0] == 'Gerrit Code Review':

4073 - options.submitter = rev_info[1]

4074 -

4075 - # We pass back refname, oldrev, newrev as args because then the

4076 - # gerrit ref-updated hook is much like the git update hook

4077 - return (options,

4078 - [options.refname, options.oldrev, options.newrev],

4079 - {'project': options.project, 'submitter': options.submitter,

4080 - 'update_method': update_method})

4081 -

4082 -

4083 -def check_hook_specific_args(options, args):

4084 - raw_refname = options.refname

4085 - # Convert each string option unicode for Python3.

4086 - if PYTHON3:

4087 - opts = ['environment', 'recipients', 'oldrev', 'newrev', 'refname',

4088 - 'project', 'submitter', 'stash_user', 'stash_repo']

4089 - for opt in opts:

4090 - if not hasattr(options, opt):

4091 - continue

4092 - obj = getattr(options, opt)

4093 - if obj:

4094 - enc = obj.encode('utf-8', 'surrogateescape')

4095 - dec = enc.decode('utf-8', 'replace')

4096 - setattr(options, opt, dec)

4097 -

4098 - # First check for stash arguments

4099 - if (options.stash_user is None) != (options.stash_repo is None):

4100 - raise SystemExit("Error: Specify both of --stash-user and "

4101 - "--stash-repo or neither.")

4102 - if options.stash_user:

4103 - options.environment = 'stash'

4104 - return options, args, {'stash_user': options.stash_user,

4105 - 'stash_repo': options.stash_repo}

4106 -

4107 - # Finally, check for gerrit specific arguments

4108 - required_gerrit_options = (options.oldrev, options.newrev, options.refname,

4109 - options.project)

4110 - if required_gerrit_options != (None,) * 4:

4111 - return compute_gerrit_options(options, args, required_gerrit_options,

4112 - raw_refname)

4113 -

4114 - # No special options in use, just return what we started with

4115 - return options, args, {}

4116 -

4117 -

4118 -class Logger(object):

4119 - def parse_verbose(self, verbose):

4120 - if verbose > 0:

4121 - return logging.DEBUG

4122 - else:

4123 - return logging.INFO

4124 -

4125 - def create_log_file(self, environment, name, path, verbosity):

4126 - log_file = logging.getLogger(name)

4127 - file_handler = logging.FileHandler(path)

4128 - log_fmt = logging.Formatter("%(asctime)s [%(levelname)-5.5s] %(message)s")

4129 - file_handler.setFormatter(log_fmt)

4130 - log_file.addHandler(file_handler)

4131 - log_file.setLevel(verbosity)

4132 - return log_file

4133 -

4134 - def __init__(self, environment):

4135 - self.environment = environment

4136 - self.loggers = []

4137 - stderr_log = logging.getLogger('git_multimail.stderr')

4138 -

4139 - class EncodedStderr(object):

4140 - def write(self, x):

4141 - write_str(sys.stderr, x)

4142 -

4143 - def flush(self):

4144 - sys.stderr.flush()

4145 -

4146 - stderr_handler = logging.StreamHandler(EncodedStderr())

4147 - stderr_log.addHandler(stderr_handler)

4148 - stderr_log.setLevel(self.parse_verbose(environment.verbose))

4149 - self.loggers.append(stderr_log)

4150 -

4151 - if environment.debug_log_file is not None:

4152 - debug_log_file = self.create_log_file(

4153 - environment, 'git_multimail.debug', environment.debug_log_file, logging.DEBUG)

4154 - self.loggers.append(debug_log_file)

4155 -

4156 - if environment.log_file is not None:

4157 - log_file = self.create_log_file(

4158 - environment, 'git_multimail.file', environment.log_file, logging.INFO)

4159 - self.loggers.append(log_file)

4160 -

4161 - if environment.error_log_file is not None:

4162 - error_log_file = self.create_log_file(

4163 - environment, 'git_multimail.error', environment.error_log_file, logging.ERROR)

4164 - self.loggers.append(error_log_file)

4165 -

4166 - def info(self, msg, *args, **kwargs):

4167 - for l in self.loggers:

4168 - l.info(msg, *args, **kwargs)

4169 -

4170 - def debug(self, msg, *args, **kwargs):

4171 - for l in self.loggers:

4172 - l.debug(msg, *args, **kwargs)

4173 -

4174 - def warning(self, msg, *args, **kwargs):

4175 - for l in self.loggers:

4176 - l.warning(msg, *args, **kwargs)

4177 -

4178 - def error(self, msg, *args, **kwargs):

4179 - for l in self.loggers:

4180 - l.error(msg, *args, **kwargs)

4181 -

4182 -

4183 -def main(args):

4184 - parser = optparse.OptionParser(

4185 - description=__doc__,

4186 - usage='%prog [OPTIONS]\n or: %prog [OPTIONS] REFNAME OLDREV NEWREV',

4187 - )

4188 -

4189 - parser.add_option(

4190 - '--environment', '--env', action='store', type='choice',

4191 - choices=list(KNOWN_ENVIRONMENTS.keys()), default=None,

4192 - help=(

4193 - 'Choose type of environment is in use. Default is taken from '

4194 - 'multimailhook.environment if set; otherwise "generic".'

4195 - ),

4196 - )

4197 - parser.add_option(

4198 - '--stdout', action='store_true', default=False,

4199 - help='Output emails to stdout rather than sending them.',

4200 - )

4201 - parser.add_option(

4202 - '--recipients', action='store', default=None,

4203 - help='Set list of email recipients for all types of emails.',

4204 - )

4205 - parser.add_option(

4206 - '--show-env', action='store_true', default=False,

4207 - help=(

4208 - 'Write to stderr the values determined for the environment '

4209 - '(intended for debugging purposes), then proceed normally.'

4210 - ),

4211 - )

4212 - parser.add_option(

4213 - '--force-send', action='store_true', default=False,

4214 - help=(

4215 - 'Force sending refchange email when using as an update hook. '

4216 - 'This is useful to work around the unreliable new commits '

4217 - 'detection in this mode.'

4218 - ),

4219 - )

4220 - parser.add_option(

4221 - '-c', metavar="<name>=<value>", action='append',

4222 - help=(

4223 - 'Pass a configuration parameter through to git. The value given '

4224 - 'will override values from configuration files. See the -c option '

4225 - 'of git(1) for more details. (Only works with git >= 1.7.3)'

4226 - ),

4227 - )

4228 - parser.add_option(

4229 - '--version', '-v', action='store_true', default=False,

4230 - help=(

4231 - "Display git-multimail's version"

4232 - ),

4233 - )

4234 -

4235 - parser.add_option(

4236 - '--python-version', action='store_true', default=False,

4237 - help=(

4238 - "Display the version of Python used by git-multimail"

4239 - ),

4240 - )

4241 -

4242 - parser.add_option(

4243 - '--check-ref-filter', action='store_true', default=False,

4244 - help=(

4245 - 'List refs and show information on how git-multimail '

4246 - 'will process them.'

4247 - )

4248 - )

4249 -

4250 - # The following options permit this script to be run as a gerrit

4251 - # ref-updated hook. See e.g.

4252 - # code.google.com/p/gerrit/source/browse/Documentation/config-hooks.txt

4253 - # We suppress help for these items, since these are specific to gerrit,

4254 - # and we don't want users directly using them any way other than how the

4255 - # gerrit ref-updated hook is called.

4256 - parser.add_option('--oldrev', action='store', help=optparse.SUPPRESS_HELP)

4257 - parser.add_option('--newrev', action='store', help=optparse.SUPPRESS_HELP)

4258 - parser.add_option('--refname', action='store', help=optparse.SUPPRESS_HELP)

4259 - parser.add_option('--project', action='store', help=optparse.SUPPRESS_HELP)

4260 - parser.add_option('--submitter', action='store', help=optparse.SUPPRESS_HELP)

4261 -

4262 - # The following allow this to be run as a stash asynchronous post-receive

4263 - # hook (almost identical to a git post-receive hook but triggered also for

4264 - # merges of pull requests from the UI). We suppress help for these items,

4265 - # since these are specific to stash.

4266 - parser.add_option('--stash-user', action='store', help=optparse.SUPPRESS_HELP)

4267 - parser.add_option('--stash-repo', action='store', help=optparse.SUPPRESS_HELP)

4268 -

4269 - (options, args) = parser.parse_args(args)

4270 - (options, args, hook_info) = check_hook_specific_args(options, args)

4271 -

4272 - if options.version:

4273 - sys.stdout.write('git-multimail version ' + get_version() + '\n')

4274 - return

4275 -

4276 - if options.python_version:

4277 - sys.stdout.write('Python version ' + sys.version + '\n')

4278 - return

4279 -

4280 - if options.c:

4281 - Config.add_config_parameters(options.c)

4282 -

4283 - config = Config('multimailhook')

4284 -

4285 - environment = None

4286 - try:

4287 - environment = choose_environment(

4288 - config, osenv=os.environ,

4289 - env=options.environment,

4290 - recipients=options.recipients,

4291 - hook_info=hook_info,

4292 - )

4293 -

4294 - if options.show_env:

4295 - show_env(environment, sys.stderr)

4296 -

4297 - if options.stdout or environment.stdout:

4298 - mailer = OutputMailer(sys.stdout, environment)

4299 - else:

4300 - mailer = choose_mailer(config, environment)

4301 -

4302 - must_check_setup = os.environ.get('GIT_MULTIMAIL_CHECK_SETUP')

4303 - if must_check_setup == '':

4304 - must_check_setup = False

4305 - if options.check_ref_filter:

4306 - check_ref_filter(environment)

4307 - elif must_check_setup:

4308 - check_setup(environment)

4309 - # Dual mode: if arguments were specified on the command line, run

4310 - # like an update hook; otherwise, run as a post-receive hook.

4311 - elif args:

4312 - if len(args) != 3:

4313 - parser.error('Need zero or three non-option arguments')

4314 - (refname, oldrev, newrev) = args

4315 - environment.get_logger().debug(

4316 - "run_as_update_hook: refname=%s, oldrev=%s, newrev=%s, force_send=%s" %

4317 - (refname, oldrev, newrev, options.force_send))

4318 - run_as_update_hook(environment, mailer, refname, oldrev, newrev, options.force_send)

4319 - else:

4320 - run_as_post_receive_hook(environment, mailer)

4321 - except ConfigurationException:

4322 - sys.exit(sys.exc_info()[1])

4323 - except SystemExit:

4324 - raise

4325 - except Exception:

4326 - t, e, tb = sys.exc_info()

4327 - import traceback

4328 - sys.stderr.write('\n') # Avoid mixing message with previous output

4329 - msg = (

4330 - 'Exception \'' + t.__name__ +

4331 - '\' raised. Please report this as a bug to\n'

4332 - 'https://github.com/git-multimail/git-multimail/issues\n'

4333 - 'with the information below:\n\n'

4334 - 'git-multimail version ' + get_version() + '\n'

4335 - 'Python version ' + sys.version + '\n' +

4336 - traceback.format_exc())

4337 - try:

4338 - environment.get_logger().error(msg)

4339 - except:

4340 - sys.stderr.write(msg)

4341 - sys.exit(1)

4342 -

4343 -

4344 -if __name__ == '__main__':

4345 - main(sys.argv[1:])

contrib/hooks/multimail/migrate-mailhook-config deleted

-274

@@ -1,274 +0,0 @@

1 -#! /usr/bin/env python

2 -

3 -"""Migrate a post-receive-email configuration to be usable with git_multimail.py.

4 -

5 -See README.migrate-from-post-receive-email for more information.

6 -

7 -"""

8 -

9 -import sys

10 -import optparse

11 -

12 -from git_multimail import CommandError

13 -from git_multimail import Config

14 -from git_multimail import read_output

15 -

16 -

17 -OLD_NAMES = [

18 - 'mailinglist',

19 - 'announcelist',

20 - 'envelopesender',

21 - 'emailprefix',

22 - 'showrev',

23 - 'emailmaxlines',

24 - 'diffopts',

25 - 'scancommitforcc',

26 - ]

27 -

28 -NEW_NAMES = [

29 - 'environment',

30 - 'reponame',

31 - 'mailinglist',

32 - 'refchangelist',

33 - 'commitlist',

34 - 'announcelist',

35 - 'announceshortlog',

36 - 'envelopesender',

37 - 'administrator',

38 - 'emailprefix',

39 - 'emailmaxlines',

40 - 'diffopts',

41 - 'emaildomain',

42 - 'scancommitforcc',

43 - ]

44 -

45 -

46 -INFO = """\

47 -

48 -SUCCESS!

49 -

50 -Your post-receive-email configuration has been converted to

51 -git-multimail format. Please see README and

52 -README.migrate-from-post-receive-email to learn about other

53 -git-multimail configuration possibilities.

54 -

55 -For example, git-multimail has the following new options with no

56 -equivalent in post-receive-email. You might want to read about them

57 -to see if they would be useful in your situation:

58 -

59 -"""

60 -

61 -

62 -def _check_old_config_exists(old):

63 - """Check that at least one old configuration value is set."""

64 -

65 - for name in OLD_NAMES:

66 - if name in old:

67 - return True

68 -

69 - return False

70 -

71 -

72 -def _check_new_config_clear(new):

73 - """Check that none of the new configuration names are set."""

74 -

75 - retval = True

76 - for name in NEW_NAMES:

77 - if name in new:

78 - if retval:

79 - sys.stderr.write('INFO: The following configuration values already exist:\n\n')

80 - sys.stderr.write(' "%s.%s"\n' % (new.section, name))

81 - retval = False

82 -

83 - return retval

84 -

85 -

86 -def erase_values(config, names):

87 - for name in names:

88 - if name in config:

89 - try:

90 - sys.stderr.write('...unsetting "%s.%s"\n' % (config.section, name))

91 - config.unset_all(name)

92 - except CommandError:

93 - sys.stderr.write(

94 - '\nWARNING: could not unset "%s.%s". '

95 - 'Perhaps it is not set at the --local level?\n\n'

96 - % (config.section, name)

97 - )

98 -

99 -

100 -def is_section_empty(section, local):

101 - """Return True iff the specified configuration section is empty.

102 -

103 - Iff local is True, use the --local option when invoking 'git

104 - config'."""

105 -

106 - if local:

107 - local_option = ['--local']

108 - else:

109 - local_option = []

110 -

111 - try:

112 - read_output(

113 - ['git', 'config'] +

114 - local_option +

115 - ['--get-regexp', '^%s\.' % (section,)]

116 - )

117 - except CommandError:

118 - t, e, traceback = sys.exc_info()

119 - if e.retcode == 1:

120 - # This means that no settings were found.

121 - return True

122 - else:

123 - raise

124 - else:

125 - return False

126 -

127 -

128 -def remove_section_if_empty(section):

129 - """If the specified configuration section is empty, delete it."""

130 -

131 - try:

132 - empty = is_section_empty(section, local=True)

133 - except CommandError:

134 - # Older versions of git do not support the --local option, so

135 - # if the first attempt fails, try without --local.

136 - try:

137 - empty = is_section_empty(section, local=False)

138 - except CommandError:

139 - sys.stderr.write(

140 - '\nINFO: If configuration section "%s.*" is empty, you might want '

141 - 'to delete it.\n\n'

142 - % (section,)

143 - )

144 - return

145 -

146 - if empty:

147 - sys.stderr.write('...removing section "%s.*"\n' % (section,))

148 - read_output(['git', 'config', '--remove-section', section])

149 - else:

150 - sys.stderr.write(

151 - '\nINFO: Configuration section "%s.*" still has contents. '

152 - 'It will not be deleted.\n\n'

153 - % (section,)

154 - )

155 -

156 -

157 -def migrate_config(strict=False, retain=False, overwrite=False):

158 - old = Config('hooks')

159 - new = Config('multimailhook')

160 - if not _check_old_config_exists(old):

161 - sys.exit(

162 - 'Your repository has no post-receive-email configuration. '

163 - 'Nothing to do.'

164 - )

165 - if not _check_new_config_clear(new):

166 - if overwrite:

167 - sys.stderr.write('\nWARNING: Erasing the above values...\n\n')

168 - erase_values(new, NEW_NAMES)

169 - else:

170 - sys.exit(

171 - '\nERROR: Refusing to overwrite existing values. Use the --overwrite\n'

172 - 'option to continue anyway.'

173 - )

174 -

175 - name = 'showrev'

176 - if name in old:

177 - msg = 'git-multimail does not support "%s.%s"' % (old.section, name,)

178 - if strict:

179 - sys.exit(

180 - 'ERROR: %s.\n'

181 - 'Please unset that value then try again, or run without --strict.'

182 - % (msg,)

183 - )

184 - else:

185 - sys.stderr.write('\nWARNING: %s (ignoring).\n\n' % (msg,))

186 -

187 - for name in ['mailinglist', 'announcelist']:

188 - if name in old:

189 - sys.stderr.write(

190 - '...copying "%s.%s" to "%s.%s"\n' % (old.section, name, new.section, name)

191 - )

192 - old_recipients = old.get_all(name, default=None)

193 - old_recipients = ', '.join(o.strip() for o in old_recipients)

194 - new.set_recipients(name, old_recipients)

195 -

196 - if strict:

197 - sys.stderr.write(

198 - '...setting "%s.commitlist" to the empty string\n' % (new.section,)

199 - )

200 - new.set_recipients('commitlist', '')

201 - sys.stderr.write(

202 - '...setting "%s.announceshortlog" to "true"\n' % (new.section,)

203 - )

204 - new.set('announceshortlog', 'true')

205 -

206 - for name in ['envelopesender', 'emailmaxlines', 'diffopts', 'scancommitforcc']:

207 - if name in old:

208 - sys.stderr.write(

209 - '...copying "%s.%s" to "%s.%s"\n' % (old.section, name, new.section, name)

210 - )

211 - new.set(name, old.get(name))

212 -

213 - name = 'emailprefix'

214 - if name in old:

215 - sys.stderr.write(

216 - '...copying "%s.%s" to "%s.%s"\n' % (old.section, name, new.section, name)

217 - )

218 - new.set(name, old.get(name))

219 - elif strict:

220 - sys.stderr.write(

221 - '...setting "%s.%s" to "[SCM]" to preserve old subject lines\n'

222 - % (new.section, name)

223 - )

224 - new.set(name, '[SCM]')

225 -

226 - if not retain:

227 - erase_values(old, OLD_NAMES)

228 - remove_section_if_empty(old.section)

229 -

230 - sys.stderr.write(INFO)

231 - for name in NEW_NAMES:

232 - if name not in OLD_NAMES:

233 - sys.stderr.write(' "%s.%s"\n' % (new.section, name,))

234 - sys.stderr.write('\n')

235 -

236 -

237 -def main(args):

238 - parser = optparse.OptionParser(

239 - description=__doc__,

240 - usage='%prog [OPTIONS]',

241 - )

242 -

243 - parser.add_option(

244 - '--strict', action='store_true', default=False,

245 - help=(

246 - 'Slavishly configure git-multimail as closely as possible to '

247 - 'the post-receive-email configuration. Default is to turn '

248 - 'on some new features that have no equivalent in post-receive-email.'

249 - ),

250 - )

251 - parser.add_option(

252 - '--retain', action='store_true', default=False,

253 - help=(

254 - 'Retain the post-receive-email configuration values. '

255 - 'Default is to delete them after the new values are set.'

256 - ),

257 - )

258 - parser.add_option(

259 - '--overwrite', action='store_true', default=False,

260 - help=(

261 - 'Overwrite any existing git-multimail configuration settings. '

262 - 'Default is to abort if such settings already exist.'

263 - ),

264 - )

265 -

266 - (options, args) = parser.parse_args(args)

267 -

268 - if args:

269 - parser.error('Unexpected arguments: %s' % (' '.join(args),))

270 -

271 - migrate_config(strict=options.strict, retain=options.retain, overwrite=options.overwrite)

272 -

273 -

274 -main(sys.argv[1:])

contrib/hooks/multimail/post-receive.example deleted

-101

@@ -1,101 +0,0 @@

1 -#! /usr/bin/env python

2 -

3 -"""Example post-receive hook based on git-multimail.

4 -

5 -The simplest way to use git-multimail is to use the script

6 -git_multimail.py directly as a post-receive hook, and to configure it

7 -using Git's configuration files and command-line parameters. You can

8 -also write your own Python wrapper for more advanced configurability,

9 -using git_multimail.py as a Python module.

10 -

11 -This script is a simple example of such a post-receive hook. It is

12 -intended to be customized before use; see the comments in the script

13 -to help you get started.

14 -

15 -Using git-multimail as a Python module as done here provides more

16 -flexibility. It has the following advantages:

17 -

18 -* The tool's behavior can be customized using arbitrary Python code,

19 - without having to edit git_multimail.py.

20 -

21 -* Configuration settings can be read from other sources; for example,

22 - user names and email addresses could be read from LDAP or from a

23 - database. Or the settings can even be hardcoded in the importing

24 - Python script, if this is preferred.

25 -

26 -This script is a very basic example of how to use git_multimail.py as

27 -a module. The comments below explain some of the points at which the

28 -script's behavior could be changed or customized.

29 -

30 -"""

31 -

32 -import sys

33 -

34 -# If necessary, add the path to the directory containing

35 -# git_multimail.py to the Python path as follows. (This is not

36 -# necessary if git_multimail.py is in the same directory as this

37 -# script):

38 -

39 -#LIBDIR = 'path/to/directory/containing/module'

40 -#sys.path.insert(0, LIBDIR)

41 -

42 -import git_multimail

43 -

44 -# It is possible to modify the output templates here; e.g.:

45 -

46 -#git_multimail.FOOTER_TEMPLATE = """\

47 -#

48 -#-- \n\

49 -#This email was generated by the wonderful git-multimail tool.

50 -#"""

51 -

52 -

53 -# Specify which "git config" section contains the configuration for

54 -# git-multimail:

55 -config = git_multimail.Config('multimailhook')

56 -

57 -# Set some Git configuration variables. Equivalent to passing var=val

58 -# to "git -c var=val" each time git is called, or to adding the

59 -# configuration in .git/config (must come before instantiating the

60 -# environment) :

61 -#git_multimail.Config.add_config_parameters('multimailhook.commitEmailFormat=html')

62 -#git_multimail.Config.add_config_parameters(('user.name=foo', 'user.email=foo@example.com'))

63 -

64 -# Select the type of environment:

65 -try:

66 - environment = git_multimail.GenericEnvironment(config=config)

67 - #environment = git_multimail.GitoliteEnvironment(config=config)

68 -except git_multimail.ConfigurationException:

69 - sys.stderr.write('*** %s\n' % sys.exc_info()[1])

70 - sys.exit(1)

71 -

72 -

73 -# Choose the method of sending emails based on the git config:

74 -mailer = git_multimail.choose_mailer(config, environment)

75 -

76 -# Alternatively, you may hardcode the mailer using code like one of

77 -# the following:

78 -

79 -# Use "/usr/sbin/sendmail -oi -t" to send emails. The envelopesender

80 -# argument is optional:

81 -#mailer = git_multimail.SendMailer(

82 -# command=['/usr/sbin/sendmail', '-oi', '-t'],

83 -# envelopesender='git-repo@example.com',

84 -# )

85 -

86 -# Use Python's smtplib to send emails. Both arguments are required.

87 -#mailer = git_multimail.SMTPMailer(

88 -# environment=environment,

89 -# envelopesender='git-repo@example.com',

90 -# # The smtpserver argument can also include a port number; e.g.,

91 -# # smtpserver='mail.example.com:25'

92 -# smtpserver='mail.example.com',

93 -# )

94 -

95 -# OutputMailer is intended only for testing; it writes the emails to

96 -# the specified file stream.

97 -#mailer = git_multimail.OutputMailer(sys.stdout)

98 -

99 -

100 -# Read changes from stdin and send notification emails:

101 -git_multimail.run_as_post_receive_hook(environment, mailer)