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-shell, and all
the perl modules in
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):
- commands in
src/commands: access, git-config, info, mirror, option, owns, perms
- triggers in
src/lib/Gitolite/Triggers: Mirroring.pm, Shell.pm
- triggers in
src/triggers/post-compile: ssh-authkeys, ssh-authkeys-shell-users, update-git-configs, set-default-roles,
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).
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
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
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.
This deals with "exploding" the main gitolite.conf file into a single perl list with all 'include' files recursively expanded.
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 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
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
~/.gitolite/conf/gitolite.conf-compiled.pm), while rules that
apply to specific repos go into their own files
From a security perspective, dealing with 'subconf' (see delegation for details) happens in this module.
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
The only complicated part of this is how the
non_core_expand function takes
$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
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
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.
...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).