diff --git a/doc/hook-propagation.mkd b/doc/hook-propagation.mkd index 290ccf8..0b89539 100644 --- a/doc/hook-propagation.mkd +++ b/doc/hook-propagation.mkd @@ -3,131 +3,132 @@ Some users like to know how hooks propagate, and when, and why there appear to be two places to put them, and so on. I'll try and set out the logic here. -**Note**: This is **not** the document to read if you just want to install a -new custom hook; treat it as more "theory" than "lab". ([Here][customhooks] is the -"lab" version!) +**Note**: You don't need to read all this just to add your own hooks or your +own functionality to a hook that gitolite uses. See [here][customhooks] and +[here][hookchaining]. -## hooks used by gitolite +## what hooks do repos get? -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. + * `update`: all repos have this; it does the write-level access control + (per-branch permissions). -In addition there is a "sentinel file" -- an empty file called -"gitolite-hooked". We'll see later what this does. + * `post-receive`: if you've enabled [mirroring][], all repos have this. -The final objective of all this is that each repo's `hooks/` directory should -get all the hooks that it is meant to get. + * `post-update`: only the special "gitolite-admin" repo has this; it acts + upon the changes you push to the admin repo. -## **where** do I (the admin) put the hooks? + * `gitolite-hooked`: not really a hook, but a special, zero-byte file; see + below. -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`. + * you can add any other hooks you want (see note at the top of this doc), + and gitolite will propagate them into all repos along with the others. -Now we'll discuss the locations of these `hooks/common` and -`hooks/gitolite-admin` directories. This depends on which install method you -used. +## when do repos "get" hooks? -(Please refer to [doc/1-INSTALL.mkd][install] for what these "methods" are). + * When the "compile" script runs, any repo that is named explicitly in the + conf file, and the "gitolite-hooked" file is not present, gets hooks. -### the `GL_PACKAGE_HOOKS` directory + * When someone runs `gl-setup` on the server, then *all* repos physically + present inside `$REPO_BASE` get them. -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). + A repo does not have to be defined in the config for this to happen. + Also, this includes the initial install; if you already had some repos in + `REPO_BASE` they get the hooks. -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`. + * If `GL_WILDREPOS` is set, a repo gets hooks when a user creates a repo or + uses the "fork" command in "contrib/adc". In the + latter case the hooks are explicitly copied from the source repo using the + "cp" command, not using the code internal to gitolite. -So now we know there's a location called `$GL_PACKAGE_HOOKS` where you can -place your hooks. +## what exactly does "get hooks" mean? -### the `$HOME/.gitolite` directory +The "hooks/" directory of the bare repo on the server will *forcibly* have +symlinks created for each of the hooks mentioned in the "what hooks..." +section. -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. +Other files are left alone, so you *can* manually add a hook file to specific +repos, directly on the server, so long as there is no name clash. -So now there are two places you can put your hooks, apparently. +## where do the symlinks point? -### why two places? +There are two places the symlinks can point. -Just think of the "package" and "root" methods for now, even if you're using -the "non-root" method. + * `$GL_PACKAGE_HOOKS/common` contains the "system" hooks. + `GL_PACKAGE_HOOKS` is defined in the rc file. -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`. + * `$HOME/.gitolite/hooks/common` has the "user" 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. +The special "post-update" hook for the equally special +"gitolite-admin" repo is not in either of those places. It's in +`../gitolite-admin` relative to them. Just don't worry about it, and don't +fiddle with it. **There is no spoon**. -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. +`GL_PACKAGE_HOOKS` is "/var/gitolite/hooks" or some such path for RPM/DEB or +"root" method, and "$HOME/share/gitolite/hooks" for the non-root method. +(Basically, it's whatever you gave as the 3rd argument to +'gl-system-install' when you used the root or non-root methods, or whatever +the packager decided if you used the RPM/DEB method). -[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)] +## so where do I put my hooks? -### special case: the "non-root" method +Put them in the "user" location (`~/.gitolite/hooks/common`). -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. +The "system" location hooks override the ones in the "user" location, as you +can see from the picture below. This can be useful to enforce site-wide hooks +when using the RPM/DEB or root install methods. (For the non-root install +it's useless, since both locations are under the control of the user). -## **when** do hooks propagate? + .gv -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 -gets created. **Not doing so is generally a security risk; because the -primary purpose of gitolite is access control, people generally *want* hooks -to run.** + edge [dir=forward color="blue"] + splines = false -Here's how/when hooks are created/propagated: + glph [ shape = none label = < + + + + + + + + +
package/system hooks
$GL_PACKAGE_HOOKS/common
updateyourhook1yourhook2
+ >] -1. anytime you do an install, gitolite trawls through *all* existing repos - (using the unix `find` command) and force-links all the hooks in all the - repos so they all get the latest and greatest hooks. + gladh [ shape = none label = < + + + + + + + + +
user hooks
~/.gitolite/hooks/common
updateyourhook1yourhook3
+ >] -2. anytime you do a "compile" (meaning push changes to the admin repo), - gitolite looks through all the repos named in the config. It first checks - if the repo exists, creating it if needed. It then looks for a sentinel - file called "gitolite-hooked" (an empty file in the hooks directory). If - it doesn't find it, it will assume that hooks need to be propagated. + rh [ shape = none label = < + + + + + + + + + +
individual repo hooks
$REPO_BASE/reponame.git/hooks
updateyourhook1yourhook2yourhook3
+ >] - This is because people often copy a repo from elsewhere, add it to the - config, and expect things to work. Without this step, those repos don't - get the hooks, which is bad -- the access control would have failed - silently! + rh:y3:n .. gladh:y3 + rh:u:n .. glph:u:s + rh:y1:n .. glph:y1 + rh:y2:n .. glph:y2 -3. anytime a new repo is created, the same force-linking of hooks happens. - The 3 places a new repo is created are: - - * the "compile" case mentioned above, where the admin added a normal - repo to the config and pushed - - * the wildrepos case, where you have "C" permissions and the repo does - not already exist - - * the `fork` command in `contrib/adc`. In this case the hooks are - explicitly copied from the source repo using the `cp` command, not - using the code internal to gitolite. - -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. +As you can see, when both locations have the same hook, the symlink points to +the "system" hook. +By default, the only reason you need to touch the "system" location is if you +want to modify the 'update' hook, but why would you fiddle with the most +important part of gitolite, huh? You're a good admin, and will use [hook +chaining][hookchaining] properly, right?