179 lines
7.4 KiB
Markdown
179 lines
7.4 KiB
Markdown
## 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**: 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][ch] is the
|
|
"lab" version!)
|
|
|
|
[ch]: http://sitaramc.github.com/gitolite/doc/2-admin.html#_custom_hooks
|
|
|
|
In this document:
|
|
|
|
* <a href="#_hooks_used_by_gitolite">hooks used by gitolite</a>
|
|
* <a href="#_where_do_I_the_admin_put_the_hooks_">**where** do I (the admin) put the hooks?</a>
|
|
* <a href="#_the_from_client_method">the "from-client" method</a>
|
|
* <a href="#_the_other_3_methods">the other 3 methods</a>
|
|
* <a href="#_the_GL_PACKAGE_HOOKS_directory">the `GL_PACKAGE_HOOKS` directory</a>
|
|
* <a href="#_the_HOME_gitolite_directory">the `$HOME/.gitolite` directory</a>
|
|
* <a href="#_why_two_places_">why two places?</a>
|
|
* <a href="#_special_case_the_non_root_method">special case: the "non-root" method</a>
|
|
* <a href="#_when_do_hooks_propagate_">**when** do hooks propagate?</a>
|
|
|
|
<a name="_hooks_used_by_gitolite"></a>
|
|
|
|
### 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.
|
|
|
|
<a name="_where_do_I_the_admin_put_the_hooks_"></a>
|
|
|
|
### **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/1-INSTALL.mkd][0inst] for what these "methods" are).
|
|
|
|
<a name="_the_from_client_method"></a>
|
|
|
|
#### 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.
|
|
|
|
<a name="_the_other_3_methods"></a>
|
|
|
|
#### the other 3 methods
|
|
|
|
<a name="_the_GL_PACKAGE_HOOKS_directory"></a>
|
|
|
|
##### 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.
|
|
|
|
<a name="_the_HOME_gitolite_directory"></a>
|
|
|
|
##### 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.
|
|
|
|
<a name="_why_two_places_"></a>
|
|
|
|
#### 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)]
|
|
|
|
<a name="_special_case_the_non_root_method"></a>
|
|
|
|
#### 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.
|
|
|
|
<a name="_when_do_hooks_propagate_"></a>
|
|
|
|
### **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
|
|
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.**
|
|
|
|
Here's how/when hooks are created/propagated:
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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!
|
|
|
|
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.
|
|
|
|
[0inst]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html
|
|
|