Gitolite has a huge bunch of existing features that gradually need to be moved over. Plus you may want to write your own programs to interact with it.

This page is about writing hooks, commands, triggers, VREFS, and sugar scripts. Installing them, including "where and how", is described here.

Note: the non-core page is the starting point for all information about customising gitolite.

1 environment variables and other inputs

In general, the following environment variables should always be available:

GL_BINDIR
GL_REPO_BASE
GL_ADMIN_BASE

GL_BINDIR is loosely equivalent to GIT_EXEC_PATH in git. GL_REPO_BASE is always $HOME/repositories, and GL_ADMIN_BASE is $HOME/.gitolite. (You might ask why, if they're fixed values, do we need those variables. Good question... next!)

In addition, commands invoked by a remote client also have GL_USER, while hooks have GL_USER as well as GL_REPO (which is the logical reponame).

A special form of the option syntax can be used to set repo-specific environment variables.

Finally, note that triggers get a lot of relevant information from gitolite as arguments; see here for details.

2 APIs

2.1 the shell API

The following commands exist to help you write shell scripts that interact easily with gitolite. Each of them responds to -h so please run that for more info.

In addition, you can also look at the comments in src/lib/Gitolite/Easy.pm (the perl API module) for ideas.

2.2 the perl API

...is implemented by Gitolite::Easy; the comments in src/lib/Gitolite/Easy.pm serve as documentation.

Note that some of the perl functions called by Easy.pm will change the current directory to something else, without saving and restoring the directory. Patches (to Easy.pm only) welcome.

3 writing your own...

3.1 ...commands

Commands are standalone programs, in any language you like. They simply receive the arguments you append. In addition, the env var GL_USER is available if it is being run remotely. src/commands/desc is the best example at present.

3.2 ...hooks

3.2.1 anything but the update hook

If you want to add any hook other than the update hook, 'man githooks' is all you need.

3.2.2 update hook

If you want to add additional update hook functionality, do this:

As you probably guessed, you can make your additional update hooks more selective, applying them only to some repos / users / combinations.

Note: a normal update hook expects 3 arguments (ref, old SHA, new SHA). A VREF will get those three, followed by at least 4 more. Your VREF should just ignore the extra args.

3.3 ...trigger programs

Trigger programs run at specific points in gitolite's execution, with specific arguments being passed to them. See the triggers page for details.

You can write programs that are both manually runnable as well as callable by trigger events, especially if they don't need any arguments.

3.4 ..."sugar"

Syntactic sugar helpers are NOT complete, standalone, programs. They must include a perl sub called sugar_script that takes in a listref, and returns a listref. The listrefs point to a list that contains the entire conf file (with all include processing already done). You create a new list with contents modified as you like and return a ref to it.

There are a couple of examples in src/syntactic-sugar.

4 appendix 1: repo-specific environment variables

A special form of the option syntax can be used to set repo-specific environment variables that are visible to gitolite triggers and any git hooks you may install.

For example, let's say you installed a post-update hook that initiates a CI job. By default, of course, this hook will be active for all gitolite-managed repos. However, you only want it to run for some specific repos, say r1, r2, and r4.

To do that, first add this to the gitolite.conf:

repo r1 r2 r4
    option ENV.CI = 1

This creates an environment variable called GL_OPTION_CI with the value 1, before any trigger or hook is invoked.

Note: option names must start with ENV., followed by a seqence of characters composed of alphas, numbers, and the underscore character.

Now the hook running the CI job can easily decide what to do:

# exit if $GL_OPTION_CI is not set
[ -z $GL_OPTION_CI ] && exit

... rest of CI job code as before ...

Of course you can also do the opposite; i.e. decide that the listed repos should not run the CI job but all other repos should:

repo @all
    option ENV.CI = 1

repo r1 r2 r4
    option ENV.CI = ""

(The hook code remains the same as before.)

Before this feature was added, you could still do this, by using the gitolite git-config command inside the hook code to test for options and configs set for the repo, like:

if gitolite git-config -q reponame gitolite-options.option-name
then
    ...

The new method is much more convenient, as you can see.

5 appendix 2: log file format

Here's a brief description of gitolite's log file format. All fields are tab separated.

There are two kinds of lines in the log file:

For all types of log lines, the first two fields are:

The third and later fields are all dependent on what type of log line it is.

The various log line formats are:

6 appendix 3: (v3.6.1+) syslog

Gitolite allows you to send log entries to syslog. To do that, uncomment one of the commented out values for LOG_DEST in the rc file. If your rc file does not have any such lines, add one of the following lines just after the LOG_EXTRA line:

# use this to log only to syslog
LOG_DEST                        => 'syslog',

# use this to log to syslog and the normal gitolite log
LOG_DEST                        => 'syslog,normal',

Please note: