1git-multimail is close to, but not exactly, a plug-in replacement for 2the old Git project script contrib/hooks/post-receive-email. This 3document describes the differences and explains how to configure 4git-multimail to get behavior closest to that of post-receive-email. 5 6If you are in a hurry 7===================== 8 9A script called migrate-mailhook-config is included with 10git-multimail. If you run this script within a Git repository that is 11configured to use post-receive-email, it will convert the 12configuration settings into the approximate equivalent settings for 13git-multimail. For more information, run 14 15 migrate-mailhook-config --help 16 17 18Configuration 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 57Other differences 58================= 59 60This section describes other differences in the behavior of 61git-multimail vs. post-receive-email. For full details, please refer 62to 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.