Documentation/gitdiffcore: fix order in pickaxe description
[git/git.git] / contrib / hooks / post-receive-email
CommitLineData
4557e0de
AP
1#!/bin/sh
2#
3# Copyright (c) 2007 Andy Parkins
4#
15a2f530
GP
5# An example hook script to mail out commit update information. This hook
6# sends emails listing new revisions to the repository introduced by the
7# change being reported. The rule is that (for branch updates) each commit
8# will appear on one email and one email only.
4557e0de 9#
15a2f530
GP
10# This hook is stored in the contrib/hooks directory. Your distribution
11# will have put this somewhere standard. You should make this script
12# executable then link to it in the repository you would like to use it in.
13# For example, on debian the hook is stored in
14# /usr/share/doc/git-core/contrib/hooks/post-receive-email:
4557e0de
AP
15#
16# chmod a+x post-receive-email
17# cd /path/to/your/repository.git
18# ln -sf /usr/share/doc/git-core/contrib/hooks/post-receive-email hooks/post-receive
19#
15a2f530
GP
20# This hook script assumes it is enabled on the central repository of a
21# project, with all users pushing only to it and not between each other. It
22# will still work if you don't operate in that style, but it would become
23# possible for the email to be from someone other than the person doing the
24# push.
4557e0de
AP
25#
26# Config
27# ------
28# hooks.mailinglist
29# This is the list that all pushes will go to; leave it blank to not send
30# emails for every ref update.
31# hooks.announcelist
32# This is the list that all pushes of annotated tags will go to. Leave it
15a2f530
GP
33# blank to default to the mailinglist field. The announce emails lists
34# the short log summary of the changes since the last annotated tag.
b5786c82 35# hooks.envelopesender
15a2f530
GP
36# If set then the -f option is passed to sendmail to allow the envelope
37# sender address to be set
e7509ee3
GP
38# hooks.emailprefix
39# All emails have their subjects prefixed with this prefix, or "[SCM]"
40# if emailprefix is unset, to aid filtering
b0a7d111
PH
41# hooks.showrev
42# The shell command used to format each revision in the email, with
43# "%s" replaced with the commit id. Defaults to "git rev-list -1
44# --pretty %s", displaying the commit id, author, date and log
45# message. To list full patches separated by a blank line, you
46# could set this to "git show -C %s; echo".
5ffd3113
JM
47# To list a gitweb/cgit URL *and* a full patch for each change set, use this:
48# "t=%s; printf 'http://.../?id=%%s' \$t; echo;echo; git show -C \$t; echo"
49# Be careful if "..." contains things that will be expanded by shell "eval"
50# or printf.
4557e0de
AP
51#
52# Notes
53# -----
4557e0de
AP
54# All emails include the headers "X-Git-Refname", "X-Git-Oldrev",
55# "X-Git-Newrev", and "X-Git-Reftype" to enable fine tuned filtering and
56# give information for debugging.
57#
58
59# ---------------------------- Functions
60
61#
62# Top level email generation function. This decides what type of update
63# this is and calls the appropriate body-generation routine after outputting
64# the common header
65#
15a2f530
GP
66# Note this function doesn't actually generate any email output, that is
67# taken care of by the functions it calls:
4557e0de
AP
68# - generate_email_header
69# - generate_create_XXXX_email
70# - generate_update_XXXX_email
71# - generate_delete_XXXX_email
72# - generate_email_footer
73#
74generate_email()
75{
76 # --- Arguments
77 oldrev=$(git rev-parse $1)
78 newrev=$(git rev-parse $2)
79 refname="$3"
80
81 # --- Interpret
82 # 0000->1234 (create)
83 # 1234->2345 (update)
84 # 2345->0000 (delete)
85 if expr "$oldrev" : '0*$' >/dev/null
86 then
87 change_type="create"
88 else
89 if expr "$newrev" : '0*$' >/dev/null
90 then
91 change_type="delete"
92 else
93 change_type="update"
94 fi
95 fi
96
97 # --- Get the revision types
98 newrev_type=$(git cat-file -t $newrev 2> /dev/null)
99 oldrev_type=$(git cat-file -t "$oldrev" 2> /dev/null)
100 case "$change_type" in
101 create|update)
102 rev="$newrev"
103 rev_type="$newrev_type"
104 ;;
105 delete)
106 rev="$oldrev"
107 rev_type="$oldrev_type"
108 ;;
109 esac
110
111 # The revision type tells us what type the commit is, combined with
112 # the location of the ref we can decide between
113 # - working branch
114 # - tracking branch
115 # - unannoted tag
116 # - annotated tag
117 case "$refname","$rev_type" in
118 refs/tags/*,commit)
119 # un-annotated tag
120 refname_type="tag"
121 short_refname=${refname##refs/tags/}
122 ;;
123 refs/tags/*,tag)
124 # annotated tag
125 refname_type="annotated tag"
126 short_refname=${refname##refs/tags/}
127 # change recipients
128 if [ -n "$announcerecipients" ]; then
129 recipients="$announcerecipients"
130 fi
131 ;;
132 refs/heads/*,commit)
133 # branch
134 refname_type="branch"
135 short_refname=${refname##refs/heads/}
136 ;;
137 refs/remotes/*,commit)
138 # tracking branch
139 refname_type="tracking branch"
140 short_refname=${refname##refs/remotes/}
141 echo >&2 "*** Push-update of tracking branch, $refname"
142 echo >&2 "*** - no email generated."
143 exit 0
144 ;;
145 *)
146 # Anything else (is there anything else?)
147 echo >&2 "*** Unknown type of update to $refname ($rev_type)"
148 echo >&2 "*** - no email generated"
149 exit 1
150 ;;
151 esac
152
153 # Check if we've got anyone to send to
154 if [ -z "$recipients" ]; then
fdfeb87c
JM
155 case "$refname_type" in
156 "annotated tag")
157 config_name="hooks.announcelist"
158 ;;
159 *)
160 config_name="hooks.mailinglist"
161 ;;
162 esac
163 echo >&2 "*** $config_name is not set so no email will be sent"
4557e0de
AP
164 echo >&2 "*** for $refname update $oldrev->$newrev"
165 exit 0
166 fi
167
168 # Email parameters
4557e0de
AP
169 # The email subject will contain the best description of the ref
170 # that we can build from the parameters
171 describe=$(git describe $rev 2>/dev/null)
172 if [ -z "$describe" ]; then
173 describe=$rev
174 fi
175
176 generate_email_header
177
178 # Call the correct body generation function
179 fn_name=general
180 case "$refname_type" in
181 "tracking branch"|branch)
182 fn_name=branch
183 ;;
184 "annotated tag")
185 fn_name=atag
186 ;;
187 esac
188 generate_${change_type}_${fn_name}_email
189
190 generate_email_footer
191}
192
193generate_email_header()
194{
195 # --- Email (all stdout will be the email)
196 # Generate header
197 cat <<-EOF
4557e0de 198 To: $recipients
e7509ee3 199 Subject: ${emailprefix}$projectdesc $refname_type, $short_refname, ${change_type}d. $describe
4557e0de
AP
200 X-Git-Refname: $refname
201 X-Git-Reftype: $refname_type
202 X-Git-Oldrev: $oldrev
203 X-Git-Newrev: $newrev
204
205 This is an automated email from the git hooks/post-receive script. It was
206 generated because a ref change was pushed to the repository containing
207 the project "$projectdesc".
208
209 The $refname_type, $short_refname has been ${change_type}d
210 EOF
211}
212
213generate_email_footer()
214{
71bd81ad 215 SPACE=" "
4557e0de
AP
216 cat <<-EOF
217
218
219 hooks/post-receive
71bd81ad 220 --${SPACE}
4557e0de
AP
221 $projectdesc
222 EOF
223}
224
225# --------------- Branches
226
227#
228# Called for the creation of a branch
229#
230generate_create_branch_email()
231{
232 # This is a new branch and so oldrev is not valid
233 echo " at $newrev ($newrev_type)"
234 echo ""
235
236 echo $LOGBEGIN
4471649f 237 show_new_revisions
4557e0de
AP
238 echo $LOGEND
239}
240
241#
242# Called for the change of a pre-existing branch
243#
244generate_update_branch_email()
245{
246 # Consider this:
247 # 1 --- 2 --- O --- X --- 3 --- 4 --- N
248 #
249 # O is $oldrev for $refname
250 # N is $newrev for $refname
251 # X is a revision pointed to by some other ref, for which we may
252 # assume that an email has already been generated.
253 # In this case we want to issue an email containing only revisions
254 # 3, 4, and N. Given (almost) by
255 #
22fa97d4 256 # git rev-list N ^O --not --all
4557e0de
AP
257 #
258 # The reason for the "almost", is that the "--not --all" will take
259 # precedence over the "N", and effectively will translate to
260 #
22fa97d4 261 # git rev-list N ^O ^X ^N
4557e0de 262 #
22fa97d4
DM
263 # So, we need to build up the list more carefully. git rev-parse
264 # will generate a list of revs that may be fed into git rev-list.
15a2f530
GP
265 # We can get it to make the "--not --all" part and then filter out
266 # the "^N" with:
4557e0de 267 #
22fa97d4 268 # git rev-parse --not --all | grep -v N
4557e0de 269 #
22fa97d4 270 # Then, using the --stdin switch to git rev-list we have effectively
4557e0de
AP
271 # manufactured
272 #
22fa97d4 273 # git rev-list N ^O ^X
4557e0de
AP
274 #
275 # This leaves a problem when someone else updates the repository
15a2f530
GP
276 # while this script is running. Their new value of the ref we're
277 # working on would be included in the "--not --all" output; and as
278 # our $newrev would be an ancestor of that commit, it would exclude
279 # all of our commits. What we really want is to exclude the current
280 # value of $refname from the --not list, rather than N itself. So:
4557e0de 281 #
22fa97d4 282 # git rev-parse --not --all | grep -v $(git rev-parse $refname)
4557e0de 283 #
15a2f530 284 # Get's us to something pretty safe (apart from the small time
22fa97d4 285 # between refname being read, and git rev-parse running - for that,
15a2f530 286 # I give up)
4557e0de
AP
287 #
288 #
289 # Next problem, consider this:
290 # * --- B --- * --- O ($oldrev)
291 # \
292 # * --- X --- * --- N ($newrev)
293 #
15a2f530
GP
294 # That is to say, there is no guarantee that oldrev is a strict
295 # subset of newrev (it would have required a --force, but that's
296 # allowed). So, we can't simply say rev-list $oldrev..$newrev.
297 # Instead we find the common base of the two revs and list from
298 # there.
4557e0de 299 #
15a2f530
GP
300 # As above, we need to take into account the presence of X; if
301 # another branch is already in the repository and points at some of
302 # the revisions that we are about to output - we don't want them.
22fa97d4 303 # The solution is as before: git rev-parse output filtered.
4557e0de 304 #
15a2f530 305 # Finally, tags: 1 --- 2 --- O --- T --- 3 --- 4 --- N
4557e0de
AP
306 #
307 # Tags pushed into the repository generate nice shortlog emails that
308 # summarise the commits between them and the previous tag. However,
309 # those emails don't include the full commit messages that we output
310 # for a branch update. Therefore we still want to output revisions
311 # that have been output on a tag email.
312 #
22fa97d4 313 # Luckily, git rev-parse includes just the tool. Instead of using
15a2f530
GP
314 # "--all" we use "--branches"; this has the added benefit that
315 # "remotes/" will be ignored as well.
316
317 # List all of the revisions that were removed by this update, in a
a75d7b54
FC
318 # fast-forward update, this list will be empty, because rev-list O
319 # ^N is empty. For a non-fast-forward, O ^N is the list of removed
15a2f530 320 # revisions
8e404f82 321 fast_forward=""
4557e0de
AP
322 rev=""
323 for rev in $(git rev-list $newrev..$oldrev)
324 do
325 revtype=$(git cat-file -t "$rev")
326 echo " discards $rev ($revtype)"
327 done
328 if [ -z "$rev" ]; then
329 fast_forward=1
330 fi
331
332 # List all the revisions from baserev to newrev in a kind of
15a2f530
GP
333 # "table-of-contents"; note this list can include revisions that
334 # have already had notification emails and is present to show the
335 # full detail of the change from rolling back the old revision to
336 # the base revision and then forward to the new revision
4557e0de
AP
337 for rev in $(git rev-list $oldrev..$newrev)
338 do
339 revtype=$(git cat-file -t "$rev")
340 echo " via $rev ($revtype)"
341 done
342
a2d6b872 343 if [ "$fast_forward" ]; then
4557e0de
AP
344 echo " from $oldrev ($oldrev_type)"
345 else
15a2f530
GP
346 # 1. Existing revisions were removed. In this case newrev
347 # is a subset of oldrev - this is the reverse of a
348 # fast-forward, a rewind
349 # 2. New revisions were added on top of an old revision,
350 # this is a rewind and addition.
024e5b31 351
15a2f530
GP
352 # (1) certainly happened, (2) possibly. When (2) hasn't
353 # happened, we set a flag to indicate that no log printout
354 # is required.
024e5b31 355
4557e0de 356 echo ""
024e5b31 357
15a2f530
GP
358 # Find the common ancestor of the old and new revisions and
359 # compare it with newrev
024e5b31
AP
360 baserev=$(git merge-base $oldrev $newrev)
361 rewind_only=""
362 if [ "$baserev" = "$newrev" ]; then
363 echo "This update discarded existing revisions and left the branch pointing at"
364 echo "a previous point in the repository history."
365 echo ""
366 echo " * -- * -- N ($newrev)"
367 echo " \\"
368 echo " O -- O -- O ($oldrev)"
369 echo ""
370 echo "The removed revisions are not necessarilly gone - if another reference"
371 echo "still refers to them they will stay in the repository."
372 rewind_only=1
373 else
374 echo "This update added new revisions after undoing existing revisions. That is"
375 echo "to say, the old revision is not a strict subset of the new revision. This"
376 echo "situation occurs when you --force push a change and generate a repository"
377 echo "containing something like this:"
378 echo ""
379 echo " * -- * -- B -- O -- O -- O ($oldrev)"
380 echo " \\"
381 echo " N -- N -- N ($newrev)"
382 echo ""
383 echo "When this happens we assume that you've already had alert emails for all"
384 echo "of the O revisions, and so we here report only the revisions in the N"
385 echo "branch from the common base, B."
386 fi
4557e0de
AP
387 fi
388
389 echo ""
024e5b31
AP
390 if [ -z "$rewind_only" ]; then
391 echo "Those revisions listed above that are new to this repository have"
392 echo "not appeared on any other notification email; so we list those"
393 echo "revisions in full, below."
4557e0de 394
024e5b31
AP
395 echo ""
396 echo $LOGBEGIN
4471649f 397 show_new_revisions
4557e0de 398
15a2f530
GP
399 # XXX: Need a way of detecting whether git rev-list actually
400 # outputted anything, so that we can issue a "no new
401 # revisions added by this update" message
4557e0de 402
024e5b31
AP
403 echo $LOGEND
404 else
405 echo "No new revisions were added by this update."
406 fi
4557e0de 407
15a2f530
GP
408 # The diffstat is shown from the old revision to the new revision.
409 # This is to show the truth of what happened in this change.
410 # There's no point showing the stat from the base to the new
411 # revision because the base is effectively a random revision at this
412 # point - the user will be interested in what this revision changed
413 # - including the undoing of previous revisions in the case of
a75d7b54 414 # non-fast-forward updates.
4557e0de
AP
415 echo ""
416 echo "Summary of changes:"
417 git diff-tree --stat --summary --find-copies-harder $oldrev..$newrev
418}
419
420#
421# Called for the deletion of a branch
422#
423generate_delete_branch_email()
424{
425 echo " was $oldrev"
426 echo ""
427 echo $LOGEND
428 git show -s --pretty=oneline $oldrev
429 echo $LOGEND
430}
431
432# --------------- Annotated tags
433
434#
435# Called for the creation of an annotated tag
436#
437generate_create_atag_email()
438{
439 echo " at $newrev ($newrev_type)"
440
441 generate_atag_email
442}
443
444#
445# Called for the update of an annotated tag (this is probably a rare event
446# and may not even be allowed)
447#
448generate_update_atag_email()
449{
450 echo " to $newrev ($newrev_type)"
451 echo " from $oldrev (which is now obsolete)"
452
453 generate_atag_email
454}
455
456#
457# Called when an annotated tag is created or changed
458#
459generate_atag_email()
460{
22fa97d4 461 # Use git for-each-ref to pull out the individual fields from the
15a2f530 462 # tag
4557e0de
AP
463 eval $(git for-each-ref --shell --format='
464 tagobject=%(*objectname)
465 tagtype=%(*objecttype)
466 tagger=%(taggername)
467 tagged=%(taggerdate)' $refname
468 )
469
470 echo " tagging $tagobject ($tagtype)"
471 case "$tagtype" in
472 commit)
15a2f530 473
4557e0de 474 # If the tagged object is a commit, then we assume this is a
15a2f530
GP
475 # release, and so we calculate which tag this tag is
476 # replacing
4557e0de
AP
477 prevtag=$(git describe --abbrev=0 $newrev^ 2>/dev/null)
478
479 if [ -n "$prevtag" ]; then
480 echo " replaces $prevtag"
481 fi
482 ;;
483 *)
484 echo " length $(git cat-file -s $tagobject) bytes"
485 ;;
486 esac
487 echo " tagged by $tagger"
488 echo " on $tagged"
489
490 echo ""
491 echo $LOGBEGIN
492
15a2f530
GP
493 # Show the content of the tag message; this might contain a change
494 # log or release notes so is worth displaying.
4557e0de
AP
495 git cat-file tag $newrev | sed -e '1,/^$/d'
496
497 echo ""
498 case "$tagtype" in
499 commit)
15a2f530
GP
500 # Only commit tags make sense to have rev-list operations
501 # performed on them
4557e0de
AP
502 if [ -n "$prevtag" ]; then
503 # Show changes since the previous release
504 git rev-list --pretty=short "$prevtag..$newrev" | git shortlog
505 else
15a2f530
GP
506 # No previous tag, show all the changes since time
507 # began
4557e0de
AP
508 git rev-list --pretty=short $newrev | git shortlog
509 fi
510 ;;
511 *)
15a2f530
GP
512 # XXX: Is there anything useful we can do for non-commit
513 # objects?
4557e0de
AP
514 ;;
515 esac
516
517 echo $LOGEND
518}
519
520#
521# Called for the deletion of an annotated tag
522#
523generate_delete_atag_email()
524{
525 echo " was $oldrev"
526 echo ""
527 echo $LOGEND
528 git show -s --pretty=oneline $oldrev
529 echo $LOGEND
530}
531
532# --------------- General references
533
534#
535# Called when any other type of reference is created (most likely a
536# non-annotated tag)
537#
538generate_create_general_email()
539{
540 echo " at $newrev ($newrev_type)"
541
542 generate_general_email
543}
544
545#
546# Called when any other type of reference is updated (most likely a
547# non-annotated tag)
548#
549generate_update_general_email()
550{
551 echo " to $newrev ($newrev_type)"
552 echo " from $oldrev"
553
554 generate_general_email
555}
556
557#
558# Called for creation or update of any other type of reference
559#
560generate_general_email()
561{
15a2f530
GP
562 # Unannotated tags are more about marking a point than releasing a
563 # version; therefore we don't do the shortlog summary that we do for
564 # annotated tags above - we simply show that the point has been
565 # marked, and print the log message for the marked point for
566 # reference purposes
4557e0de 567 #
15a2f530
GP
568 # Note this section also catches any other reference type (although
569 # there aren't any) and deals with them in the same way.
4557e0de
AP
570
571 echo ""
572 if [ "$newrev_type" = "commit" ]; then
573 echo $LOGBEGIN
9225d7be 574 git show --no-color --root -s --pretty=medium $newrev
4557e0de
AP
575 echo $LOGEND
576 else
15a2f530
GP
577 # What can we do here? The tag marks an object that is not
578 # a commit, so there is no log for us to display. It's
22fa97d4 579 # probably not wise to output git cat-file as it could be a
15a2f530 580 # binary blob. We'll just say how big it is
4557e0de
AP
581 echo "$newrev is a $newrev_type, and is $(git cat-file -s $newrev) bytes long."
582 fi
583}
584
585#
586# Called for the deletion of any other type of reference
587#
588generate_delete_general_email()
589{
590 echo " was $oldrev"
591 echo ""
592 echo $LOGEND
593 git show -s --pretty=oneline $oldrev
594 echo $LOGEND
595}
596
4471649f
PH
597
598# --------------- Miscellaneous utilities
599
600#
601# Show new revisions as the user would like to see them in the email.
602#
603show_new_revisions()
604{
605 # This shows all log entries that are not already covered by
606 # another ref - i.e. commits that are now accessible from this
607 # ref that were previously not accessible
608 # (see generate_update_branch_email for the explanation of this
609 # command)
610
611 # Revision range passed to rev-list differs for new vs. updated
612 # branches.
613 if [ "$change_type" = create ]
614 then
615 # Show all revisions exclusive to this (new) branch.
616 revspec=$newrev
617 else
618 # Branch update; show revisions not part of $oldrev.
619 revspec=$oldrev..$newrev
620 fi
621
e5f5050e
PN
622 other_branches=$(git for-each-ref --format='%(refname)' refs/heads/ |
623 grep -F -v $refname)
624 git rev-parse --not $other_branches |
b0a7d111
PH
625 if [ -z "$custom_showrev" ]
626 then
627 git rev-list --pretty --stdin $revspec
628 else
629 git rev-list --stdin $revspec |
630 while read onerev
631 do
632 eval $(printf "$custom_showrev" $onerev)
633 done
634 fi
4471649f
PH
635}
636
637
d1637a07
JM
638send_mail()
639{
640 if [ -n "$envelopesender" ]; then
641 /usr/sbin/sendmail -t -f "$envelopesender"
642 else
643 /usr/sbin/sendmail -t
644 fi
645}
646
4557e0de
AP
647# ---------------------------- main()
648
649# --- Constants
4557e0de
AP
650LOGBEGIN="- Log -----------------------------------------------------------------"
651LOGEND="-----------------------------------------------------------------------"
652
653# --- Config
654# Set GIT_DIR either from the working directory, or from the environment
655# variable.
656GIT_DIR=$(git rev-parse --git-dir 2>/dev/null)
657if [ -z "$GIT_DIR" ]; then
658 echo >&2 "fatal: post-receive: GIT_DIR not set"
659 exit 1
660fi
661
c855195c 662projectdesc=$(sed -ne '1p' "$GIT_DIR/description")
15a2f530
GP
663# Check if the description is unchanged from it's default, and shorten it to
664# a more manageable length if it is
4557e0de
AP
665if expr "$projectdesc" : "Unnamed repository.*$" >/dev/null
666then
667 projectdesc="UNNAMED PROJECT"
668fi
669
22fa97d4
DM
670recipients=$(git config hooks.mailinglist)
671announcerecipients=$(git config hooks.announcelist)
672envelopesender=$(git config hooks.envelopesender)
673emailprefix=$(git config hooks.emailprefix || echo '[SCM] ')
b0a7d111 674custom_showrev=$(git config hooks.showrev)
4557e0de
AP
675
676# --- Main loop
15a2f530
GP
677# Allow dual mode: run from the command line just like the update hook, or
678# if no arguments are given then run as a hook script
4557e0de
AP
679if [ -n "$1" -a -n "$2" -a -n "$3" ]; then
680 # Output to the terminal in command line mode - if someone wanted to
15a2f530
GP
681 # resend an email; they could redirect the output to sendmail
682 # themselves
4557e0de
AP
683 PAGER= generate_email $2 $3 $1
684else
4557e0de
AP
685 while read oldrev newrev refname
686 do
d1637a07 687 generate_email $oldrev $newrev $refname | send_mail
4557e0de
AP
688 done
689fi