| Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 1 | Subject: [HOWTO] Using post-update hook |
| 2 | Message-ID: <7vy86o6usx.fsf@assigned-by-dhcp.cox.net> |
| Junio C Hamano | 0868a30 | 2008-07-22 09:20:44 | [diff] [blame] | 3 | From: Junio C Hamano <gitster@pobox.com> |
| Junio C Hamano | 1a4e841 | 2005-12-27 08:17:23 | [diff] [blame] | 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 | |
| 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. |
| 15 | |
| 16 | The directories relevant to this how-to are these two: |
| 17 | |
| 18 | /pub/scm/git/git.git/ The public git repository. |
| 19 | /pub/software/scm/git/docs/ The HTML documentation page. |
| 20 | |
| 21 | So I made a repository to generate the documentation under my |
| 22 | home directory over there. |
| 23 | |
| 24 | $ cd |
| 25 | $ mkdir doc-git && cd doc-git |
| 26 | $ git clone /pub/scm/git/git.git/ docgen |
| 27 | |
| 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: |
| 32 | |
| 33 | $ cat >dododoc.sh <<\EOF |
| 34 | #!/bin/sh |
| 35 | cd $HOME/doc-git/docgen || exit |
| 36 | |
| 37 | unset GIT_DIR |
| 38 | |
| 39 | git pull /pub/scm/git/git.git/ master && |
| 40 | cd Documentation && |
| 41 | make install-webdoc |
| 42 | EOF |
| 43 | |
| 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: |
| 48 | |
| 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". |
| 56 | |
| 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 |
| 65 | |
| 66 | There are four things worth mentioning: |
| 67 | |
| 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. |
| 73 | |
| 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. |
| 79 | |
| 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. |
| 83 | |
| 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. |
