[HOWTO] Using post-update hook

The pages under http://www.kernel.org/pub/software/scm/git/docs/ are built from Documentation/ directory of the git.git project and needed to be kept up-to-date. The www.kernel.org/ servers are mirrored and I was told that the origin of the mirror is on the machine master.kernel.org, on which I was given an account when I took over git maintainership from Linus.

The directories relevant to this how-to are these two:

    /pub/scm/git/git.git/	The public git repository.
    /pub/software/scm/git/docs/	The HTML documentation page.

So I made a repository to generate the documentation under my home directory over there.

    $ cd
    $ mkdir doc-git && cd doc-git
    $ git clone /pub/scm/git/git.git/ docgen

What needs to happen is to update the $HOME/doc-git/docgen/ working tree, build HTML docs there and install the result in /pub/software/scm/git/docs/ directory. So I wrote a little script:

    $ cat >dododoc.sh <<\EOF
    #!/bin/sh
    cd $HOME/doc-git/docgen || exit

    unset GIT_DIR

    git pull /pub/scm/git/git.git/ master &&
    cd Documentation &&
    make install-webdoc
    EOF

Initially I used to run this by hand whenever I push into the public git repository. Then I did a cron job that ran twice a day. The current round uses the post-update hook mechanism, like this:

    $ cat >/pub/scm/git/git.git/hooks/post-update <<\EOF
    #!/bin/sh
    #
    # An example hook script to prepare a packed repository for use over
    # dumb transports.
    #
    # To enable this hook, make this file executable by "chmod +x post-update".

    case " $* " in
    *' refs/heads/master '*)
            echo $HOME/doc-git/dododoc.sh | at now
            ;;
    esac
    exec git-update-server-info
    EOF
    $ chmod +x /pub/scm/git/git.git/hooks/post-update

There are three things worth mentioning:

 - The update-hook is run after the repository accepts a "git
   push", under my user privilege.  It is given the full names
   of refs that have been updated as arguments.  My post-update
   runs the dododoc.sh script only when the master head is
   updated.

 - When update-hook is run, GIT_DIR is set to '.' by the calling
   receive-pack.  This is inherited by the dododoc.sh run via
   the "at" command, and needs to be unset; otherwise, "git
   pull" it does into $HOME/doc-git/docgen/ repository would not
   work correctly.

 - This is still crude and does not protect against simultaneous
   make invocations stomping on each other.  I would need to add
   some locking mechanism for this.