gitolite internals

This page is for people who may want to hack on core gitolite itself. This is not the page for people who merely want to customise their site (i.e., write their own VREFs, triggers, etc.); for that please start with the non-core page.


This document assumes you're familiar with the material in the how does it work section in the "overview" document, as well as the concepts page. If you're not familiar with ssh, and in particular how programs like gitolite use ssh to simulate many users over one Unix user, the ssh page has useful info.

what is "core"

The core code consists mainly of src/gitolite, src/gitolite-shell, and all the perl modules in src/lib/Gitolite except src/lib/Gitolite/Triggers.

That said, there are parts of non-core that, in a default (ssh) install, are used frequently enough to be important (for example if you are reviewing gitolite):

entry points

gitolite

Most server-side operations that gitolite supports are invoked via the gitolite command. This includes initial setup and maintenance, some built-in commands (run 'gitolite -h' to see them), and finally the commands in src/commands (run 'gitolite help' to get a list).

gitolite-shell

All remote access is via the gitolite-shell command, (invoked, of course, by sshd). This includes both git operations (clone, fetch, push) as well as gitolite commands that have been enabled for remote invocation.

For git operations, gitolite-shell does the initial access check ("is the user even allowed to read/write this repo at all?") and then calls git proper.

Most of the code in this is housekeeping; the real action happens in one of the modules.

the Conf module

The Conf module and its child modules deal with the gitolite.conf file.

Conf is where the 'compile' command lands. The parser for the conf file is also in this module; each "recognised" line is passed to appropriate functions in Conf::Store.

Please note the parser is a very simple line-oriented parser using simple regexes; the DSL for the gitolite.conf file is intentionally very simple.

Conf::Explode

This deals with "exploding" the main gitolite.conf file into a single perl list with all 'include' files recursively expanded.

Conf::Sugar

This calls Conf::Explode to get the full set of conf lines, then applies a series of "syntactic sugar" transformations to them. This keeps the main parser simple, while allowing the administrator to take some shortcuts in writing the rules.

Some transformations are built-in and hardcoded, but a site can add their own site-local transformations if they like.

Conf::Store

Conf::Store is one of the two workhorses of gitolite. It exports functions related to processing parsed lines and storing the parsed output for later use. It also exports functions that deal with creating and setting up new repos.

The output of the compile step is essentially a set of perl hashes in Data::Dumper format. Rules that apply to more than one repo (i.e., the repo name was a regex pattern or a group name) go into a "common" output file (~/.gitolite/conf/gitolite.conf-compiled.pm), while rules that apply to specific repos go into their own files (~/repositories/$REPONAME.git/gl-conf).

From a security perspective, dealing with 'subconf' (see delegation for details) happens in this module.

Conf::Load

Conf::Load is the other of the two workhorses of gitolite.

The most important function it exports is access, which is used by gitolite-shell as well as the update hook code to check for permissions. This code has a few optimisations, including very simple, localised, caching of parsed conf files when needed.

TODO: How the access function does its thing will be written up in more detail as I find time, but TLDR: it calls rules which builds up a list of the rules that apply. Also see this until I manage to write it up in more detail.

Other functions are git_config, which returns a list of config values specified in the conf file.

Finally, this is where all the "list-" commands that 'gitolite -h' shows you (e.g., 'gitolite list-repos') land up.

the Rc module

The rc file (~/.gitolite.rc) is processed here. In addition, it also declares a bunch of constants (like the all-important regex patterns to validate user inputs of various kinds; all ending in _PATT).

The only complicated part of this is how the non_core_expand function takes the $non_core variable (currently 63 lines long!) and converts it into a set of arrays, one for each of the triggers types. You can see the effect of this logic by uncommenting something in the ENABLE list in the rc file, then running gitolite query-rc PRE_GIT, etc.

(From a security point of view this is irrelevant. Any inputs it receives come from totally trusted sources -- either the gitolite source code or the rc file).

Finally, the trigger function is also exported by this module. This is the function that actually runs all the programs tied to each trigger.

the Hooks module

This is where the code for the update hook (all repos) and the post-update hook (gitolite-admin repo only) can be found.

The post-update hook code is fairly straightforward, consisting essentially of three shell commands.

The update hook code has a lot more "action", since this is where all access checking for 'git push' goes. Even that would not be much if it weren't for VREFs, because then it's just one call to the access function (from the Conf::Load module).

The only other thing of note in this module is how the "attempted access" is determined. Externally, we only know it's a "push" (i.e., a "W" in gitolite permission terms). We need to compare the old and the new SHAs in various ways to determine if it's a rewind, or a delete, or a create, etc., which may make a difference to the access.

TODO: expand on VREF handling. For now please read vref to get the general idea of what it does, while I find time to write up the how.

the rest...

...is TBD (to be done). Briefly, the Test module is for testing, the Common module contains a whole bunch of common routines used all over -- many of them not gitolite specific at all, Cache is not to be used for now (sorry, bitrotted by now I think... I may need to take it out behind the woodshed one of these days).