Documentation/howto/rebuild-from-update-hook.txt

   1 Subject: [HOWTO] Using post-update hook
   2 Message-ID: <7vy86o6usx.fsf@assigned-by-dhcp.cox.net>
   3 From: Junio C Hamano <gitster@pobox.com>
   4 Date: Fri, 26 Aug 2005 18:19:10 -0700
   5 Abstract: In this how-to article, JC talks about how he
   6  uses the post-update hook to automate git documentation page
   7  shown at http://www.kernel.org/pub/software/scm/git/docs/.
   8 Content-type: text/asciidoc
   9
  10 How to rebuild from update hook
  11 ===============================
  12
  13 The pages under http://www.kernel.org/pub/software/scm/git/docs/
  14 are built from Documentation/ directory of the git.git project
  15 and needed to be kept up-to-date.  The www.kernel.org/ servers
  16 are mirrored and I was told that the origin of the mirror is on
  17 the machine $some.kernel.org, on which I was given an account
  18 when I took over git maintainership from Linus.
  19
  20 The directories relevant to this how-to are these two:
  21
  22     /pub/scm/git/git.git/       The public git repository.
  23     /pub/software/scm/git/docs/ The HTML documentation page.
  24
  25 So I made a repository to generate the documentation under my
  26 home directory over there.
  27
  28     $ cd
  29     $ mkdir doc-git && cd doc-git
  30     $ git clone /pub/scm/git/git.git/ docgen
  31
  32 What needs to happen is to update the $HOME/doc-git/docgen/
  33 working tree, build HTML docs there and install the result in
  34 /pub/software/scm/git/docs/ directory.  So I wrote a little
  35 script:
  36
  37     $ cat >dododoc.sh <<\EOF
  38     #!/bin/sh
  39     cd $HOME/doc-git/docgen || exit
  40
  41     unset GIT_DIR
  42
  43     git pull /pub/scm/git/git.git/ master &&
  44     cd Documentation &&
  45     make install-webdoc
  46     EOF
  47
  48 Initially I used to run this by hand whenever I push into the
  49 public git repository.  Then I did a cron job that ran twice a
  50 day.  The current round uses the post-update hook mechanism,
  51 like this:
  52
  53     $ cat >/pub/scm/git/git.git/hooks/post-update <<\EOF
  54     #!/bin/sh
  55     #
  56     # An example hook script to prepare a packed repository for use over
  57     # dumb transports.
  58     #
  59     # To enable this hook, make this file executable by "chmod +x post-update".
  60
  61     case " $* " in
  62     *' refs/heads/master '*)
  63             echo $HOME/doc-git/dododoc.sh | at now
  64             ;;
  65     esac
  66     exec git-update-server-info
  67     EOF
  68     $ chmod +x /pub/scm/git/git.git/hooks/post-update
  69
  70 There are four things worth mentioning:
  71
  72  - The update-hook is run after the repository accepts a "git
  73    push", under my user privilege.  It is given the full names
  74    of refs that have been updated as arguments.  My post-update
  75    runs the dododoc.sh script only when the master head is
  76    updated.
  77
  78  - When update-hook is run, GIT_DIR is set to '.' by the calling
  79    receive-pack.  This is inherited by the dododoc.sh run via
  80    the "at" command, and needs to be unset; otherwise, "git
  81    pull" it does into $HOME/doc-git/docgen/ repository would not
  82    work correctly.
  83
  84  - The stdout of update hook script is not connected to git
  85    push; I run the heavy part of the command inside "at", to
  86    receive the execution report via e-mail.
  87
  88  - This is still crude and does not protect against simultaneous
  89    make invocations stomping on each other.  I would need to add
  90    some locking mechanism for this.