deac/gitolite
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

hook propagation document redone; should flow much easier now

Browse source
This commit is contained in:
Sitaram Chamarty 2011-11-13 07:53:39 +05:30
parent f19a9cf480
commit 9b66643f3a
1 changed files with 98 additions and 97 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

195
doc/hook-propagation.mkd
View file

@ -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". <font color="gray">In the
latter case the hooks are explicitly copied from the source repo using the
"cp" command, not using the code internal to gitolite</font>.
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.
<font color="gray">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**.</font>
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.
(<font color="gray">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</font>).
[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 = <
<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>
>]
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 = <
<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>
>]
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 = <
<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>
>]
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?