master TOC | chapter TOC | support

using hooks

custom hooks

You can supply your own, custom, hook scripts if you wish. Install gitolite as usual, then:

• go to ~/.gitolite/hooks/common on the server and put your new hook there
• now run "gl-setup" again

You can use this procedure to install new hooks as well as to update hooks that you had previously installed.

IMPORTANT WARNINGS

• The update hook in hooks/common is what implements all the branch-level permissions in gitolite. If you fiddle with the hooks directory, please make sure you do not mess with this file accidentally, or all your fancy per-branch permissions will stop working.

• Do not under any conditions put anything in hooks/gitolite-admin -- nothing in gitolite requires you to do anything here. Leave it alone!

hook chaining

Sometimes you need to use git hooks for your own purposes (site-local validations, CI integration, email notifications, or the ever popular "live website update"!). However, the hooks you want to use may already be in use by gitolite.

This section will tell you what to do in such cases. First, let's list the hooks that gitolite uses:

• The update hook is used in all repos and is critical to gitolite's access control!

• The post-receive hook is used in all repos but only if mirroring has been enabled. Shipped as post-receive.mirrorpush, it is renamed to 'post-receive' and installed as part of the mirroring setup.

• The post-update hook is used in the gitolite-admin repo only, to "compile" the configuration and so on.

To run your own 'update' hook, just put it in a file called update.secondary and install it as a hook. Gitolite's update hook will automatically chain to it, taking care to pass it the same 3 arguments the original update hook received from git.

For post-receive, (if using mirroring) do the opposite. You're normally expected to rename the shipped 'post-receive.mirrorpush' to 'post-receive', but don't do this. Instead, simply run hooks/post-receive.mirrorpush at the end of your hook code. Do not worry about replicating STDIN (the documented way in which a post-receive hook receives its input) because the mirroring code does not use it.

To run your own post-update hook on normal repos, just install a hook called 'post-update' the usual way. It'll be installed on all normal repos but not on the special gitolite-admin repo. If you need that for the gitolite-admin repo, you'll have to call it post-update.secondary.

Finally, these names ('update.secondary' and 'post-update.secondary') are merely the defaults. You can change them to anything you want; look in conf/example.gitolite.rc for details.

environment variables available to hooks

The following environment variables are set, and may be useful for any custom processing you wish to do in your hook code:

• GL_USER -- the user doing the push
• GL_REPO -- the reponame
• GL_REPO_BASE_ABS -- the absolute base path where all the repos are kept

The following variables are also set, but are generally less useful:

• GL_BINDIR -- where all the binaries live
• GL_ADMINDIR -- common directory for many gitolite things

"gl-post-init" hook

Sometimes it is necessary to do something whenever a new repo is created. If you need this functionality, just supply a hook called "gl-post-init" with whatever code you want in it.

"gl-pre-git" hook

Although git has lots of nice hooks you can tap into, they all run only on a push. There's nothing that runs on a fetch or a clone, and there's no way to run something before git-receive-pack or git-upload-pack, (as the case may be) are invoked.

That's what the gl-pre-git hook is for. If an executable hook called gl-pre-git is present, it will be invoked with the current directory set to repo.git, and with a single argument which will be either R or W depending on what the client is trying to do. The environment variables GL_USER and GL_REPO are available. STDOUT will be forced to STDERR before it is called, to avoid confusing the client.

If the code returns anything other than 0, gitolite will terminate the operation (i.e., not run git at all), just like many git hooks do, so make sure you end with exit 0 or equivalent.