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

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

1 customising gitolite

Much of gitolite (g3)'s functionality comes from programs and scripts that are not considered "core". This keeps the core simpler, and allows you to enhance gitolite for your own purposes without too much fuss. (As an extreme example, even mirroring is not in core now!)

Here's how to find out more:

1.1 introduction

There are 5 basic types of non-core programs.

1.2 locations...

1.2.1 ...for non-core programs shipped with gitolite

gitolite query-rc GL_BINDIR will tell you where shipped non-core programs reside. Within that directory, the subdirectories of interest are:

1.2.2 ...for your non-core programs

If you want to add your own non-core programs, or even override the shipped ones with your own, you can.

Put your programs in some convenient directory and use the LOCAL_CODE rc variable to tell gitolite where that is. Please supply the FULL path to this variable.

Within that directory, you can use any or all of these subdirectories:

Note: the hooks/common directory is a bit special. If you add new hooks to this, you must run either gitolite setup, or at least gitolite setup --hooks-only.

1.2.3 using the gitolite-admin repo to manage non-core code

The location given in LOCAL_CODE could be anywhere on disk, like say $ENV{HOME}/local.

However, some administrators find it convenient to use the admin repo to manage this code as well, getting the benefits of versioning them as well as making changes to them without having to log on to the server.

To do this, simply point LOCAL_CODE to someplace inside $GL_ADMIN_BASE (i.e., $HOME/.gitolite) in the rc file.

If you want to do this, I strongly suggest:

LOCAL_CODE                  =>  "$ENV{HOME}/.gitolite/local",

Then you create a directory called "local" in your gitolite clone, and put stuff there (e.g., VREFs go in local/VREF, and commands in local/commands).

(Note: when you do this, gitolite takes care of running gitolite setup --hooks-only when you change any hooks and push). SECURITY note on this mode of managing non-core code

In this mode, anyone who can push changes to the admin repo will effectively be able to run any arbitrary command on the server.

This may not matter to many (small) sites, but a large site with lots of administrators may want to keep the two rights (i.e., "right to push to the gitolite-admin repo" and "right to run arbitrary programs on the server") separate.

1.3 types of non-core programs

1.3.1 gitolite "commands"

Gitolite comes with several commands that users can run. Remote users run commands by saying:

ssh git@host command-name [args...]

while on the server you can run

gitolite command [args...]

Very few commands are designed to be run both ways, but it can be done, by checking for the presence of env var GL_USER.

All commands respond to a single -h option with a suitable message.

You can get a list of available commands by using the help command. Naturally, a remote user will see a much smaller list than the server user.

You allow a command to be run from remote clients by adding its name to (or uncommenting it if it's already added but commented out) the ENABLE list in the rc file.

1.3.2 hooks and gitolite

You can install any hooks except these:

How/where to install them is described in detail in the "locations" section above, especially this and this. The summary is that you put them in the "hooks/common" sub-directory within the directory whose name is given in the LOCAL_CODE rc variable, then run gitolite setup. repo-specific hooks

If you want to add hooks only to specific repos, you can just do it manually if you wish -- just log on to the server and add hooks (except update hook and, for the special gitolite-admin repo, the post-update hook -- touch these and all bets on gitolite's functionality are off).

However, if you want to do that from within gitolite, and thus keep everything together, you can do that also. Here's how.

1.3.3 syntactic sugar

Sugar scripts help you change the perceived syntax of the conf language. The base syntax of the language is very simple, so sugar scripts take something else and convert it into that.

That way, the admin sees additional features (like allowing continuation lines), while the parser in the core gitolite engine does not change.

If you want to write your own sugar scripts, please read the "your own sugar" section in dev-notes first then email me.

You enable a sugar script by uncommenting the feature name in the ENABLE list in the rc file.

1.3.4 triggers

Triggers have their own document.

1.3.5 VREFs

VREFs also have their own document.