master TOC | main page | single-page | license | New: Gitolite Essentials book

This is for gitolite "g3"; for older (v2.x) documentation click here

1 gitolite triggers

1.1 intro and sample rc excerpt

Gitolite fires off external commands at several different times. The rc file specifies what commands to run at each trigger point, but for illustration, here's an excerpt. Note that as of v3.4, this is not how the rc file looks like externally. Please see this for more.

%RC = (

    <...several lines later...>

    # comment out or uncomment as needed
    # these will run in sequence after post-update
    POST_COMPILE                =>
        [
            'post-compile/ssh-authkeys',
            'post-compile/update-git-configs',
            'post-compile/update-gitweb-access-list',
            'post-compile/update-git-daemon-access-list',
        ],

    # comment out or uncomment as needed
    # these will run in sequence after a new wild repo is created
    POST_CREATE                 =>
        [
            'post-compile/update-git-configs',
            'post-compile/update-gitweb-access-list',
            'post-compile/update-git-daemon-access-list',
        ],

(As you can see, post-create runs 3 programs that also run from post-compile. This is perfectly fine, by the way)

1.2 types of trigger programs

There are two types of trigger programs. Standalone scripts are placed in src/triggers or its subdirectories. They are invoked by being added to a trigger list (using the path after "src/triggers/", as you can see). Such scripts are quick and easy to write in any language of your choice.

Triggers written as perl modules are placed in src/lib/Gitolite/Triggers. They are invoked by being listed with the package+function name, although even here the 'Gitolite::Triggers' part is skipped. Perl modules have to follow some conventions (see some of the shipped modules to ideas) but the advantage is that they can set environment variables and change the argument list of the gitolite-shell program that invokes them.

If this does not make sense, please examine a default install of gitolite, paying attention to:

1.3 manually firing triggers

...from the server command line is easy. For example:

gitolite trigger POST_COMPILE

However if the triggered code depends on arguments (see next section) this won't work. (The POST_COMPILE trigger programs all just happen to not require any arguments, so it works).

1.4 common arguments

Triggers receive the following arguments:

  1. any arguments mentioned in the rc file (for an example, see the renice command)

  2. the name of the trigger as a string (example, "POST_COMPILE"), so you can call the same program from multiple triggers and it can know where it was called from,

  3. followed by zero or more arguments specific to the trigger, as given in the next section.

1.5 trigger-specific arguments and other details

Here are the rest of the arguments for each trigger, plus a brief description of when the trigger runs:

1.6 adding your own scripts to a trigger

For gitolite v3.3 or less, adding your own scripts to a trigger list was simply a matter of finding the trigger name in the rc file and adding an entry to it. Even for gitolite v3.4 or higher, if your rc file was created before v3.4, it will continue to work, and you can continue to add triggers to it the same way as before.

However, if you installed gitolite v3.4 or higher, you will see a different rc file syntax. This new rc file does not have trigger lists, but a simple list of "features" within a list called "ENABLE" in the rc file; you simply comment out or uncomment appropriate entries, and gitolite will internally create the trigger lists correctly.

...which is fine for triggers that are shipped with gitolite, but now you're wondering how to add your own.

The answer is: same as before.

Here's an example. Let's say you wrote yourself a trigger script called 'foo', to be invoked from the POST_CREATE trigger list. With the old format, you'd find the following lines in the rc file:

POST_CREATE                 =>
    [
        'post-compile/update-git-configs',
        'post-compile/update-gitweb-access-list',
        'post-compile/update-git-daemon-access-list',
    ],

and you'd simply add a line for 'foo' in that list.

With the new format, since there is no POST_CREATE trigger list defined in the rc file, you'll need to add all this:

POST_CREATE                 =>
    [
        'foo'
    ],

instead of just the 'foo' line.

Since the ENABLE list pulls in the rest of the trigger entries, this will be effectively as if you had done this in a v3.3 rc file:

POST_CREATE                 =>
    [
        'foo',
        'post-compile/update-git-configs',
        'post-compile/update-gitweb-access-list',
        'post-compile/update-git-daemon-access-list',
    ],

As you can see, the 'foo' gets added to the top of the list.

1.6.1 displaying the resulting trigger list

You can use the 'gitolite query-rc' command to see what the trigger list actually looks like. For example:

gitolite query-rc POST_CREATE

1.7 tips

If you have code that latches onto more than one trigger, collecting data (such as for logging), then the outputs may be intermixed. You can record the value of the environment variable GL_TID to tie together related entries.