refs.c: fix fread error handling
[git.git] / Documentation / howto / rebuild-from-update-hook.txt
blob48c67568d3418b2d6608f362f4b76e02ec450abc
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/.
9 The pages under http://www.kernel.org/pub/software/scm/git/docs/
10 are built from Documentation/ directory of the git.git project
11 and needed to be kept up-to-date.  The www.kernel.org/ servers
12 are mirrored and I was told that the origin of the mirror is on
13 the machine $some.kernel.org, on which I was given an account
14 when I took over git maintainership from Linus.
16 The directories relevant to this how-to are these two:
18     /pub/scm/git/git.git/       The public git repository.
19     /pub/software/scm/git/docs/ The HTML documentation page.
21 So I made a repository to generate the documentation under my
22 home directory over there.
24     $ cd
25     $ mkdir doc-git && cd doc-git
26     $ git clone /pub/scm/git/git.git/ docgen
28 What needs to happen is to update the $HOME/doc-git/docgen/
29 working tree, build HTML docs there and install the result in
30 /pub/software/scm/git/docs/ directory.  So I wrote a little
31 script:
33     $ cat >dododoc.sh <<\EOF
34     #!/bin/sh
35     cd $HOME/doc-git/docgen || exit
37     unset GIT_DIR
39     git pull /pub/scm/git/git.git/ master &&
40     cd Documentation &&
41     make install-webdoc
42     EOF
44 Initially I used to run this by hand whenever I push into the
45 public git repository.  Then I did a cron job that ran twice a
46 day.  The current round uses the post-update hook mechanism,
47 like this:
49     $ cat >/pub/scm/git/git.git/hooks/post-update <<\EOF
50     #!/bin/sh
51     #
52     # An example hook script to prepare a packed repository for use over
53     # dumb transports.
54     #
55     # To enable this hook, make this file executable by "chmod +x post-update".
57     case " $* " in
58     *' refs/heads/master '*)
59             echo $HOME/doc-git/dododoc.sh | at now
60             ;;
61     esac
62     exec git-update-server-info
63     EOF
64     $ chmod +x /pub/scm/git/git.git/hooks/post-update
66 There are four things worth mentioning:
68  - The update-hook is run after the repository accepts a "git
69    push", under my user privilege.  It is given the full names
70    of refs that have been updated as arguments.  My post-update
71    runs the dododoc.sh script only when the master head is
72    updated.
74  - When update-hook is run, GIT_DIR is set to '.' by the calling
75    receive-pack.  This is inherited by the dododoc.sh run via
76    the "at" command, and needs to be unset; otherwise, "git
77    pull" it does into $HOME/doc-git/docgen/ repository would not
78    work correctly.
80  - The stdout of update hook script is not connected to git
81    push; I run the heavy part of the command inside "at", to
82    receive the execution report via e-mail.
84  - This is still crude and does not protect against simultaneous
85    make invocations stomping on each other.  I would need to add
86    some locking mechanism for this.