From acff0bd3d04f481aa3ed50bbad33c382bf4e2059 Mon Sep 17 00:00:00 2001 From: Sitaram Chamarty Date: Sun, 20 Jun 2010 08:06:54 +0530 Subject: [PATCH] hook propagation doc much expanded now --- doc/hook-propagation.mkd | 135 ++++++++++++++++++++++++++++++++++++++- 1 file changed, 133 insertions(+), 2 deletions(-) diff --git a/doc/hook-propagation.mkd b/doc/hook-propagation.mkd index cda9100..44ef8da 100644 --- a/doc/hook-propagation.mkd +++ b/doc/hook-propagation.mkd @@ -1,7 +1,135 @@ # hook propagation in gitolite -There have been some questions about how hooks propagate, and when. I'll try -and set out the logic here. +Advanced users need to know how hooks propagate, and when. They also need to +know where to place their hooks, and since there appear to be two places to +put them, what takes precedence. I'll try and set out the logic here. + +In this document: + + * hooks used by gitolite + * **where** do I (the admin) put the hooks? + * the "from-client" method + * the other 3 methods + * the `GL_PACKAGE_HOOKS` directory + * the `$HOME/.gitolite` directory + * why two places? + * special case: the "non-root" method + * **when** do hooks propagate? + + + +### hooks used by gitolite + +Gitolite uses only 2 hooks. **All** repos have an `update` hook, without +which there is no write-level access control (per-branch permissions). The +special **gitolite-admin** repo has a special `post-update` hook, which is +required to do its, umm, special things, like running the "compile" script, +etc. + +In addition there is a "sentinel file" -- an empty file called +"gitolite-hooked". We'll see later what this does. + +The final objective of all this is that each repo's `hooks/` directory should +get all the hooks that it is meant to get. + + + +### **where** do I (the admin) put the hooks? + +In general, **all** hooks go into the `hooks/common` directory. Only the +special `post-update` hook meant for the admin repo goes into +`hooks/gitolite-admin`. + +Now we'll discuss the locations of these `hooks/common` and +`hooks/gitolite-admin` directories. This depends on which install method you +used. + +(Please refer to [doc/0-INSTALL.mkd][0inst] for what these "methods" are). + + + +#### the "from-client" method + +Let's get this out of the way first, because it is simple: if you're using the +"from-client" method, there's only one place: the `hooks` directory in your +gitolite clone on the client side. This is where you run +`src/gl-easy-install` from. Nothing else in this section is relevant to this +method; skip to the next section ("when do hooks propagate") if you installed +using the "from-client" method. + + + +#### the other 3 methods + + + +##### the `GL_PACKAGE_HOOKS` directory + +You might recall that the "root", and "non-root" methods run a command called +`gl-system-install`, the third argument of which is some directory of your +choice (like maybe `/usr/share/gitolite/hooks`). Even though it is not +necessary to know this, internally this becomes the value of the +`$GL_PACKAGE_HOOKS` variable, so in this document we will refer to that +variable instead of the location (because you might choose any location you +like for it). + +The "package" method also has the same property, except that the packager has +already decided what that location is, and the package creation/install +process does the equivalent of `gl-system-install`. + +So now we know there's a location called `$GL_PACKAGE_HOOKS` where you can +place your hooks. + + + +##### the `$HOME/.gitolite` directory + +You might also recall that, in these three methods, each **hosting user** has +to run `gl-setup`. This sets up, among other things, `$HOME/.gitolite` +directory, which also contains a `hooks/` directory. + +So now there are two places you can put your hooks, apparently. + + + +#### why two places? + +Just think of the "package" and "root" methods for now, even if you're using +the "non-root" method. + +In these two methods, it is reasonable to assume that the entire site (or +server) has certain policies that they want to implement using hooks. They +want to enforce these hooks on *each hosting user*. These hooks go into +`$GL_PACKAGE_HOOKS`. + +Each hosting user then has the discretion to add his own hooks (modulo name +clashes, which may necessitate hook chaining, etc., like we already do for the +hooks that gitolite cares about). He adds these hooks to his +`$HOME/.gitolite/hooks` directory. + +When hooks propagate, the ones in `$GL_PACKAGE_HOOKS` override/overwrite the +ones in `$HOME/.gitolite/hooks`. Otherwise it wouldn't make sense; you +wouldn't be able to enforce site-wide hooks. + +[NOTE: due to a minor quirk, the site-wide hooks in `$GL_PACKAGE_HOOKS` also +get copied to `$HOME/.gitolite/hooks` when you "install". I need to fix and +thoroughly test this later; for now, just ignore the extra files you see in +there; they're harmless/redundant (TODO)] + + + +#### special case: the "non-root" method + +This method was created later, just piggy-backing on everything that already +existed to cater to the "package" and "root" methods. In this method, the +`$GL_PACKAGE_HOOKS` is as accessible or under your control as +`$HOME/.gitolite`, so it doesn't matter where you put your hooks. I +*strongly* suggest putting them in `$GL_PACKAGE_HOOKS` and ignoring +`$HOME/.gitolite` completely. + + + +### **when** do hooks propagate? First: realise that gitolite *wants to make sure* that all the hooks in your `hooks/common` directory get copied (symlinked, actually) to *every* repo that @@ -42,3 +170,6 @@ Here's how/when hooks are created/propagated: For people who do not want certain hooks to run for certain repos, one simple solution that will work right now is to check the value of `$GL_REPO` at the start of the hook, and `exit 0` based on what it contains/matches. + +[0inst]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd +