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