gitolite/doc/cust.mkd

# 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!)

This document will tell you about the types of non-core programs, and
how/where to install your own.  (Actually *writing* the code is described in
the [developer notes][dev-notes] page).

----

[[TOC]]

----

## introduction

There are 5 basic types of non-core programs.

  * *Commands* can be run from the shell command line.  Among those, the ones
    listed in the COMMANDS hash of the rc file can also be run remotely.
  * *Hooks* are standard git hooks.
  * *Sugar scripts* change the conf language for your convenience.  The word
    sugar comes from "syntactic sugar".
  * *Triggers* are to gitolite what hooks are to git.  I just chose a
    different name to avoid confusion and constant disambiguation in the docs.
  * **VREFs** are extensions to the access control check part of gitolite.

[Here][non-core] is a list of non-core programs shipped with gitolite, with
some description of each.

## locations

### default/primary location of non-core programs

Regardless of how you installed gitolite, `gitolite query-rc GL_BINDIR` will
tell you where the programs reside.  Within that directory, the locations of
non-core programs are:

  * `commands` for commands.
  * `syntactic-sugar` for sugar scripts.
  * `triggers` and `lib/Gitolite/Triggers` for triggers ([this][triggers] will
    explain the difference).
  * `VREF` for [VREFs][vref].

### #localcode alternate location -- the `LOCAL_CODE` rc variable

If you want to add new non-core programs to your installation, or override the
shipped non-core programs with your own versions, it's easy enough to simply
copy your programs to the appropriate directory above, but then they'd get
wiped out on the next upgrade.

A simple, "git-ish", method is to maintain a "local" branch in your clone of
the gitolite source repo and make your changes there.  Maintain them using
rebase or merge when you 'git pull' gitolite itself, then use the rebased or
merged "local" as the source for your gitolite upgrades.  Works very nicely,
and uses nothing but your git knowledge.

Sadly, it doesn't work for people installing from RPMs/DEBs; their "primary
location" has already been setup, so any site-local customisations have to be
done elsewhere.

This is where `LOCAL_CODE` comes in.  If you define the `LOCAL_CODE` rc
variable, then its value (**please use a FULL path**) describes a location
where you can have any or all of these subdirectories:

  * `commands`
  * `hooks/common`
  * `syntactic-sugar`
  * `triggers` and `lib/Gitolite/Triggers`
  * `VREF`

You might have noticed there's a new `hooks/common` directory here so you can
add hooks also using this mechanism.  Unlike the rest of the directories,
adding new hooks to `hooks/common` requires that you follow up with `gitolite
setup`, or at least `gitolite setup --hooks-only`.

### #pushcode managing custom code via the gitolite-admin repo

The location given in `LOCAL_CODE` could be anywhere on disk.

However, if you point it to someplace inside `$GL_ADMIN_BASE` (i.e.,
`$HOME/.gitolite`), then you can version those programs using the
gitolite-admin repo.

I suggest using a directory called "local-code" within the gitolite-admin repo
that contains as much of the above directory structure you need.  If you do
that, then this is what you'd have in the rc file:

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

When you do this, gitolite takes care of everything automatically, including
running `gitolite setup --hooks-only` when you change any hooks and push.
**However, if you do this, anyone who can push changes to the admin repo will
effectively be able to run any arbitrary command on the server.**

## types of non-core programs

### #commands 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`.

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 COMMANDS hash in
the [rc][] file.

### #hooks hooks and gitolite

You can install any hooks except these:

  * (all repos) gitolite reserves the `update` hook.  See the "update hook"
    section in [dev-notes][] if you want additional update hook functionality.

  * (gitolite-admin repo only) gitolite reserves the `post-update` hook.

How/where to install them is described in detail in the "locations" section
above, especially [this][localcode] and [this][pushcode].  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.

### #sugar 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.

### triggers

Triggers have their own [document][triggers].

### VREFs

VREFs also have their own [document][vref].