3 # Based on /usr/share/doc/git-core/contrib/hooks/post-receive-email
5 # Copyright (c) 2007 Andy Parkins
7 # An example hook script to mail out commit update information. This hook sends emails
8 # listing new revisions to the repository introduced by the change being reported. The
9 # rule is that (for branch updates) each commit will appear on one email and one email
12 # This hook is stored in the contrib/hooks directory. Your distribution will have put
13 # this somewhere standard. You should make this script executable then link to it in
14 # the repository you would like to use it in. For example, on debian the hook is stored
15 # in /usr/share/doc/git-core/contrib/hooks/post-receive-email:
17 # chmod a+x post-receive-email
18 # cd /path/to/your/repository.git
19 # ln -sf /usr/share/doc/git-core/contrib/hooks/post-receive-email hooks/post-receive
21 # This hook script assumes it is enabled on the central repository of a project, with
22 # all users pushing only to it and not between each other. It will still work if you
23 # don't operate in that style, but it would become possible for the email to be from
24 # someone other than the person doing the push.
29 # This is the list that all pushes will go to; leave it blank to not send
30 # emails for every ref update.
32 # This is the list that all pushes of annotated tags will go to. Leave it
33 # blank to default to the mailinglist field. The announce emails lists the
34 # short log summary of the changes since the last annotated tag.
36 # If set then the -f option is passed to sendmail to allow the envelope sender
41 # All emails have their subjects prefixed with "[SCM]" to aid filtering.
42 # All emails include the headers "X-Git-Refname", "X-Git-Oldrev",
43 # "X-Git-Newrev", and "X-Git-Reftype" to enable fine tuned filtering and
44 # give information for debugging.
47 # ---------------------------- Functions
50 # Top level email generation function. This decides what type of update
51 # this is and calls the appropriate body-generation routine after outputting
54 # Note this function doesn't actually generate any email output, that is taken
55 # care of by the functions it calls:
56 # - generate_email_header
57 # - generate_create_XXXX_email
58 # - generate_update_XXXX_email
59 # - generate_delete_XXXX_email
60 # - generate_email_footer
65 oldrev=$(git rev-parse $1)
66 newrev=$(git rev-parse $2)
73 if expr "$oldrev" : '0*$' >/dev/null
77 if expr "$newrev" : '0*$' >/dev/null
85 # --- Get the revision types
86 newrev_type=$(git cat-file -t $newrev 2> /dev/null)
87 oldrev_type=$(git cat-file -t "$oldrev" 2> /dev/null)
88 case "$change_type" in
91 rev_type="$newrev_type"
95 rev_type="$oldrev_type"
99 # The revision type tells us what type the commit is, combined with
100 # the location of the ref we can decide between
105 case "$refname","$rev_type" in
109 short_refname=${refname##refs/tags/}
113 refname_type="annotated tag"
114 short_refname=${refname##refs/tags/}
116 if [ -n "$announcerecipients" ]; then
117 recipients="$announcerecipients"
122 refname_type="branch"
123 short_refname=${refname##refs/heads/}
125 refs/remotes/*,commit)
127 refname_type="tracking branch"
128 short_refname=${refname##refs/remotes/}
129 echo >&2 "*** Push-update of tracking branch, $refname"
130 echo >&2 "*** - no email generated."
134 # Anything else (is there anything else?)
135 echo >&2 "*** Unknown type of update to $refname ($rev_type)"
136 echo >&2 "*** - no email generated"
141 # Check if we've got anyone to send to
142 if [ -z "$recipients" ]; then
143 echo >&2 "*** hooks.recipients is not set so no email will be sent"
144 echo >&2 "*** for $refname update $oldrev->$newrev"
149 # The committer will be obtained from the latest existing rev; so
150 # for a deletion it will be the oldrev, for the others, then newrev
151 committer=$(git show --pretty=full -s $rev | sed -ne "s/^Commit: //p" |
152 sed -ne 's/\(.*\) </"\1" </p')
153 # The email subject will contain the best description of the ref
154 # that we can build from the parameters
155 describe=$(git describe $rev 2>/dev/null)
156 if [ -z "$describe" ]; then
160 generate_email_header
162 # Call the correct body generation function
164 case "$refname_type" in
165 "tracking branch"|branch)
172 generate_${change_type}_${fn_name}_email
174 generate_email_footer
177 generate_email_header()
179 # --- Email (all stdout will be the email)
185 Subject: ${EMAILPREFIX}$dir $refname_type, $short_refname, ${change_type}d. $describe
186 X-Git-Refname: $refname
187 X-Git-Reftype: $refname_type
188 X-Git-Oldrev: $oldrev
189 X-Git-Newrev: $newrev
191 $dir : "$projectdesc".
193 The $refname_type, $short_refname has been ${change_type}d
197 generate_email_footer()
208 # --------------- Branches
211 # Called for the creation of a branch
213 generate_create_branch_email()
215 # This is a new branch and so oldrev is not valid
216 echo " at $newrev ($newrev_type)"
220 # This shows all log entries that are not already covered by
221 # another ref - i.e. commits that are now accessible from this
222 # ref that were previously not accessible (see generate_update_branch_email
223 # for the explanation of this command)
224 git rev-parse --not --branches | grep -v $(git rev-parse $refname) |
225 git rev-list --pretty --stdin $newrev
230 # Called for the change of a pre-existing branch
232 generate_update_branch_email()
235 # 1 --- 2 --- O --- X --- 3 --- 4 --- N
237 # O is $oldrev for $refname
238 # N is $newrev for $refname
239 # X is a revision pointed to by some other ref, for which we may
240 # assume that an email has already been generated.
241 # In this case we want to issue an email containing only revisions
242 # 3, 4, and N. Given (almost) by
244 # git-rev-list N ^O --not --all
246 # The reason for the "almost", is that the "--not --all" will take
247 # precedence over the "N", and effectively will translate to
249 # git-rev-list N ^O ^X ^N
251 # So, we need to build up the list more carefully. git-rev-parse will
252 # generate a list of revs that may be fed into git-rev-list. We can get
253 # it to make the "--not --all" part and then filter out the "^N" with:
255 # git-rev-parse --not --all | grep -v N
257 # Then, using the --stdin switch to git-rev-list we have effectively
260 # git-rev-list N ^O ^X
262 # This leaves a problem when someone else updates the repository
263 # while this script is running. Their new value of the ref we're working
264 # on would be included in the "--not --all" output; and as our $newrev
265 # would be an ancestor of that commit, it would exclude all of our
266 # commits. What we really want is to exclude the current value of
267 # $refname from the --not list, rather than N itself. So:
269 # git-rev-parse --not --all | grep -v $(git-rev-parse $refname)
271 # Get's us to something pretty safe (apart from the small time between
272 # refname being read, and git-rev-parse running - for that, I give up)
275 # Next problem, consider this:
276 # * --- B --- * --- O ($oldrev)
278 # * --- X --- * --- N ($newrev)
280 # That is to say, there is no guarantee that oldrev is a strict subset of
281 # newrev (it would have required a --force, but that's allowed). So, we
282 # can't simply say rev-list $oldrev..$newrev. Instead we find the common
283 # base of the two revs and list from there.
285 # As above, we need to take into account the presence of X; if another
286 # branch is already in the repository and points at some of the revisions
287 # that we are about to output - we don't want them. The solution is as
288 # before: git-rev-parse output filtered.
291 # 1 --- 2 --- O --- T --- 3 --- 4 --- N
293 # Tags pushed into the repository generate nice shortlog emails that
294 # summarise the commits between them and the previous tag. However,
295 # those emails don't include the full commit messages that we output
296 # for a branch update. Therefore we still want to output revisions
297 # that have been output on a tag email.
299 # Luckily, git-rev-parse includes just the tool. Instead of using "--all"
300 # we use "--branches"; this has the added benefit that "remotes/" will
301 # be ignored as well.
303 # List all of the revisions that were removed by this update, in a fast forward
304 # update, this list will be empty, because rev-list O ^N is empty. For a non
305 # fast forward, O ^N is the list of removed revisions
308 for rev in $(git rev-list $newrev..$oldrev)
310 revtype=$(git cat-file -t "$rev")
311 echo " discards $rev ($revtype)"
313 if [ -z "$rev" ]; then
317 # List all the revisions from baserev to newrev in a kind of
318 # "table-of-contents"; note this list can include revisions that have
319 # already had notification emails and is present to show the full detail
320 # of the change from rolling back the old revision to the base revision and
321 # then forward to the new revision
322 for rev in $(git rev-list $oldrev..$newrev)
324 revtype=$(git cat-file -t "$rev")
325 echo " via $rev ($revtype)"
328 if [ -z "$fastforward" ]; then
329 echo " from $oldrev ($oldrev_type)"
331 # 1. Existing revisions were removed. In this case newrev is a
332 # subset of oldrev - this is the reverse of a fast-forward,
334 # 2. New revisions were added on top of an old revision, this is
335 # a rewind and addition.
337 # (1) certainly happened, (2) possibly. When (2) hasn't happened,
338 # we set a flag to indicate that no log printout is required.
342 # Find the common ancestor of the old and new revisions and compare
344 baserev=$(git merge-base $oldrev $newrev)
346 if [ "$baserev" = "$newrev" ]; then
347 echo "This update discarded existing revisions and left the branch pointing at"
348 echo "a previous point in the repository history."
350 echo " * -- * -- N ($newrev)"
352 echo " O -- O -- O ($oldrev)"
354 echo "The removed revisions are not necessarilly gone - if another reference"
355 echo "still refers to them they will stay in the repository."
358 echo "This update added new revisions after undoing existing revisions. That is"
359 echo "to say, the old revision is not a strict subset of the new revision. This"
360 echo "situation occurs when you --force push a change and generate a repository"
361 echo "containing something like this:"
363 echo " * -- * -- B -- O -- O -- O ($oldrev)"
365 echo " N -- N -- N ($newrev)"
367 echo "When this happens we assume that you've already had alert emails for all"
368 echo "of the O revisions, and so we here report only the revisions in the N"
369 echo "branch from the common base, B."
374 if [ -z "$rewind_only" ]; then
375 echo "Revisions details."
378 git rev-parse --not --branches | grep -v $(git rev-parse $refname) |
379 git rev-list --pretty --stdin $oldrev..$newrev
381 # XXX: Need a way of detecting whether git rev-list actually outputted
382 # anything, so that we can issue a "no new revisions added by this
387 echo "No new revisions were added by this update."
390 # The diffstat is shown from the old revision to the new revision. This
391 # is to show the truth of what happened in this change. There's no point
392 # showing the stat from the base to the new revision because the base
393 # is effectively a random revision at this point - the user will be
394 # interested in what this revision changed - including the undoing of
395 # previous revisions in the case of non-fast forward updates.
397 echo "Summary of changes:"
398 git diff-tree --stat --summary --find-copies-harder $oldrev..$newrev
402 # Called for the deletion of a branch
404 generate_delete_branch_email()
409 git show -s --pretty=oneline $oldrev
413 # --------------- Annotated tags
416 # Called for the creation of an annotated tag
418 generate_create_atag_email()
420 echo " at $newrev ($newrev_type)"
426 # Called for the update of an annotated tag (this is probably a rare event
427 # and may not even be allowed)
429 generate_update_atag_email()
431 echo " to $newrev ($newrev_type)"
432 echo " from $oldrev (which is now obsolete)"
438 # Called when an annotated tag is created or changed
440 generate_atag_email()
442 # Use git-for-each-ref to pull out the individual fields from the tag
443 eval $(git for-each-ref --shell --format='
444 tagobject=%(*objectname)
445 tagtype=%(*objecttype)
447 tagged=%(taggerdate)' $refname
450 echo " tagging $tagobject ($tagtype)"
453 # If the tagged object is a commit, then we assume this is a
454 # release, and so we calculate which tag this tag is replacing
455 prevtag=$(git describe --abbrev=0 $newrev^ 2>/dev/null)
457 if [ -n "$prevtag" ]; then
458 echo " replaces $prevtag"
462 echo " length $(git cat-file -s $tagobject) bytes"
465 echo " tagged by $tagger"
471 # Show the content of the tag message; this might contain a change log
472 # or release notes so is worth displaying.
473 git cat-file tag $newrev | sed -e '1,/^$/d'
478 # Only commit tags make sense to have rev-list operations performed
480 if [ -n "$prevtag" ]; then
481 # Show changes since the previous release
482 git rev-list --pretty=short "$prevtag..$newrev" | git shortlog
484 # No previous tag, show all the changes since time began
485 git rev-list --pretty=short $newrev | git shortlog
489 # XXX: Is there anything useful we can do for non-commit objects?
497 # Called for the deletion of an annotated tag
499 generate_delete_atag_email()
504 git show -s --pretty=oneline $oldrev
508 # --------------- General references
511 # Called when any other type of reference is created (most likely a
514 generate_create_general_email()
516 echo " at $newrev ($newrev_type)"
518 generate_general_email
522 # Called when any other type of reference is updated (most likely a
525 generate_update_general_email()
527 echo " to $newrev ($newrev_type)"
530 generate_general_email
534 # Called for creation or update of any other type of reference
536 generate_general_email()
538 # Unannotated tags are more about marking a point than releasing a version;
539 # therefore we don't do the shortlog summary that we do for annotated tags
540 # above - we simply show that the point has been marked, and print the log
541 # message for the marked point for reference purposes
543 # Note this section also catches any other reference type (although there
544 # aren't any) and deals with them in the same way.
547 if [ "$newrev_type" = "commit" ]; then
549 git show --no-color --root -s $newrev
552 # What can we do here? The tag marks an object that is not a commit,
553 # so there is no log for us to display. It's probably not wise to
554 # output git-cat-file as it could be a binary blob. We'll just say how
556 echo "$newrev is a $newrev_type, and is $(git cat-file -s $newrev) bytes long."
561 # Called for the deletion of any other type of reference
563 generate_delete_general_email()
568 git show -s --pretty=oneline $oldrev
572 # ---------------------------- main()
576 LOGBEGIN="- Log -----------------------------------------------------------------"
577 LOGEND="-----------------------------------------------------------------------"
580 # Set GIT_DIR either from the working directory, or from the environment
582 GIT_DIR=$(git rev-parse --git-dir 2>/dev/null)
583 if [ -z "$GIT_DIR" ]; then
584 echo >&2 "fatal: post-receive: GIT_DIR not set"
588 projectdesc=$(sed -ne '1p' "$GIT_DIR/description")
589 # Check if the description is unchanged from it's default, and shorten it to a
590 # more manageable length if it is
591 if expr "$projectdesc" : "Unnamed repository.*$" >/dev/null
593 projectdesc="UNNAMED PROJECT"
596 recipients=$(git repo-config hooks.mailinglist)
597 announcerecipients=$(git repo-config hooks.announcelist)
598 envelopesender=$(git-repo-config hooks.envelopesender)
601 # Allow dual mode: run from the command line just like the update hook, or if
602 # no arguments are given then run as a hook script
603 if [ -n "$1" -a -n "$2" -a -n "$3" ]; then
604 # Output to the terminal in command line mode - if someone wanted to
605 # resend an email; they could redirect the output to sendmail themselves
606 PAGER= generate_email $2 $3 $1
608 if [ -n "$envelopesender" ]; then
609 envelopesender="-f '$envelopesender'"
612 while read oldrev newrev refname
614 generate_email $oldrev $newrev $refname |
615 /usr/sbin/sendmail -t $envelopesender