| 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 https://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 https://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. |