F=hook_prop hook propagation in gitolite

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: 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].

what hooks do repos get?

update: all repos have this; it does the write-level access control (per-branch permissions).
post-receive: if you've enabled [mirroring][], all repos have this.
post-update: only the special "gitolite-admin" repo has this; it acts upon the changes you push to the admin repo.
gitolite-hooked: not really a hook, but a special, zero-byte file; see below.
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.

when do repos "get" hooks?

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.
When someone runs gl-setup on the server, then all repos physically present inside $REPO_BASE get them.

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.
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.

what exactly does "get hooks" mean?

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.

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.

where do the symlinks point?

There are two places the symlinks can point.

$GL_PACKAGE_HOOKS/common contains the "system" hooks. GL_PACKAGE_HOOKS is defined in the rc file.
$HOME/.gitolite/hooks/common has the "user" hooks.

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.

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).

so where do I put my hooks?

Put them in the "user" location (~/.gitolite/hooks/common).

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).

.gv

edge [dir=forward color="blue"]
splines = false

glph [ shape = none label = <
    <table>
        <tr>
            <td colspan="3" bgcolor="red">package/system hooks<br/>$GL_PACKAGE_HOOKS/common</td>
        </tr><tr>
            <td port="u" bgcolor="lightblue">update</td>
            <td port="y1">yourhook1</td>
            <td port="y2">yourhook2</td>
        </tr>
    </table>
>]

gladh [ shape = none label = <
    <table>
        <tr>
            <td colspan="3" bgcolor="green">user hooks<br/>~/.gitolite/hooks/common</td>
        </tr><tr>
            <td port="u" bgcolor="lightblue">update</td>
            <td port="y1">yourhook1</td>
            <td port="y3">yourhook3</td>
        </tr>
    </table>
>]

rh [ shape = none label = <
    <table>
        <tr>
            <td colspan="4" bgcolor="green">individual repo hooks<br/>$REPO_BASE/reponame.git/hooks</td>
        </tr><tr>
            <td port="u" bgcolor="lightblue">update</td>
            <td port="y1">yourhook1</td>
            <td port="y2">yourhook2</td>
            <td port="y3">yourhook3</td>
        </tr>
    </table>
>]

rh:y3:n .. gladh:y3
rh:u:n .. glph:u:s
rh:y1:n .. glph:y1
rh:y2:n .. glph:y2

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?

why not just push a hook?

A question I often get is, why can't we simply push the hooks using the admin repo, just like we push config changes.

To understand why, realise that in many sites, the "right to push the gitolite-admin repo" is not the same as "right to get a command line on the server and run arbitrary commands".

This means, gitolite tries its best to keep these two rights separated, and to prevent someone who has the former right from trivially acquiring the latter.

And so we don't allow adding hooks by admin push.

That doesn't mean you can't do it yourself. Here's one possible way.

Using the simple instructions [here][customhooks], add a post-update.secondary hook containing this code:

#!/bin/bash
cp $GL_ADMINDIR/local-hooks/* $GL_ADMINDIR/hooks/common
gl-setup

Now create a directory in your gitolite-admin clone called "local-hooks", put all your hooks there, and add/commit/push.

That should do it. Test it and send me a patch for this document when you do :-)

6 KiB Raw Blame History