add warning to repo-specific hooks doc

[gitolite-doc.git] / non-core.mkd

<!-- options: toc -->

% "non-core" gitolite

include sidebar-toc

Much of gitolite'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 site without too much fuss.

Documentation for non-core gitolite is organised as follows:

  * This page describes the types of non-core programs and how/where to
    install code that is specific to your site.

  * The [developer notes][dev-notes] page tells you how to write your own
    non-core programs.

  * The [list of non-core programs][list-non-core] talks about what's already
    shipped with gitolite, with a brief description of each.

----

# core versus non-core {#ncintro}

Gitolite has five types of non-core code:

  * *Commands* can be run from the shell command line.  Among those, the ones
    in the ENABLE list in 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.

# locations... {#ncloc}

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

.#d

`gitolite query-rc GL_BINDIR` will tell you where gitolite's code has been
installed.  That directory should look like this.  Among these, the
directories in green are considered "non-core", while the ones in red are
considered "core".  In addition, the two files "gitolite" and "gitolite-shell"
in src are also considered "core"

You might notice that there are two locations for [triggers][]; that is simply
because there are two types of them.  You might also notice that there is no
place for hooks -- gitolite doesn't *ship* with any hooks that are non-core.

.#d

<pre style="font-family: 'Andale mono',monospace; margin-top: 0; font-weight: bold; padding: 4px; color: #ffffff; background-color: #000000;">

.
├── <span style="color: #00ff00">commands</span>
├── lib
│   └── Gitolite
│       ├── <span style="color: #ff0000">Conf</span>
│       ├── <span style="color: #ff0000">Hooks</span>
│       ├── <span style="color: #ff0000">Test</span>
│       └── <span style="color: #00ff00">Triggers</span>
├── <span style="color: #00ff00">syntactic-sugar</span>
├── <span style="color: #00ff00">triggers</span>
└── <span style="color: #00ff00">VREF</span>

</pre>

.#t

## ...for *your* non-core programs {#localcode}

.#d

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.  (You'll find the rc file already has examples lines, commented
out, so it's easy to know where to put it and what syntax to use).

Within that directory, you can use any or all of the subdirectories shown
here.

If you add a program in your local code directory with the same name as a
shipped program, gitolite uses your version.

@@gray(Notice that there are two directories related to hooks here, neither of
which exist in the shipped non-core code.  Also, the `hooks/common` directory
is a bit special.  If you add new hooks to this, you must run `gitolite
setup`, or at least `gitolite setup --hooks-only`.)@@

.#d

<pre style="float: right; font-family: 'Andale mono',monospace; margin-top: 0; font-weight: bold; padding: 4px; color: #ffffff; background-color: #000000;">

.
├── <span style="color: #00ff00">commands</span>
├── hooks
│   └── <span style="color: #00ff00">common</span>
│   └── <span style="color: #00ff00">repo-specific</span>
├── lib
│   └── Gitolite
│       └── <span style="color: #00ff00">Triggers</span>
├── <span style="color: #00ff00">syntactic-sugar</span>
├── <span style="color: #00ff00">triggers</span>
└── <span style="color: #00ff00">VREF</span>

</pre>

.#t

## using the gitolite-admin repo to manage non-core code {#pushcode}

<div class="box-r" style="margin-left:4px; width: 33%">

@@red(**IMPORTANT SECURITY NOTE**)@@

**In this mode, anyone who can push changes to the admin repo will effectively
be able to run any arbitrary command on the server.**  See [gitolite admin and
shell access][privesc] for more background.

</div>

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` in
the rc file.  I **strongly** suggest:

    LOCAL_CODE  =>  "$rc{GL_ADMIN_BASE}/local",

Then you create a directory called "local" in your gitolite clone, and create
the directory structure (shown in the previous section) within that directory.
Thus, when you push the admin repo, the files will land up, with the correct
paths, in the location pointed to by LOCAL\_CODE.

(Note: when you do this, gitolite takes care of running `gitolite setup
--hooks-only` when you change any hooks and push).

# types of non-core programs {#nctypes}

## gitolite "commands" {#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.

## hooks and gitolite {#hooks}

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, then run `gitolite setup`.

### repo-specific hooks {#rsh}

@@red(**WARNING**: If your site makes a distinction between "right to push the
admin repo" and "right to run arbitrary commands on the server" (i.e., if not
all of your "admins" have shell access to the server), this is a security
risk. If that is the case, **do not enable this feature**.)@@

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.

  * Create a directory called `hooks/repo-specific` in whatever location you
    decided to use for your non-core code (i.e., direct on the server, or
    within the gitolite-admin repo).

  * Add your hooks here, with descriptive names (i.e., not "post-receive",
    etc., but maybe "jenkins" or "deploy" or whatever).

  * Uncomment the 'repo-specific-hooks' line in the rc file or add it to the
    ENABLE list if it doesn't exist.

    If your rc file does not have an ENABLE list, you need to add this to the
    POST_COMPILE and the POST_CREATE lists.  Click [here][addtrig] for more on
    all this.

  * Now add lines like this to your conf file:
.#! conf/vim-color
        repo    foo
            option hook.post-receive    =   deploy
.end

    The syntax should be fairly obvious, but just to be clear, in this case a
    symlink called "post-receive" will be placed in foo.git/hooks, pointing to
    the executable called "deploy" in hooks/repo-specific in the local-code
    area.

    **WARNING**: if the hook already exists, it is silently overwritten.

    **WARNING**: @@gray((v3.5.x or below))@@ once the hook is placed, you can't remove it through
    gitolite.  That is, removing the option line won't do anything.  You'll
    have to go to the server and remove it manually.

  * @@gray((v3.6+))@@ You can assign multiple targets for each hook.  For
    example, you could say
.#! conf/vim-color
        repo    foo
            option hook.post-receive    =   deploy mail-admins
.end

    where "deploy" and "mail-admins" are pieces of code that do whatever their
    names suggest, and both are, independently, candidates for being run from
    a post-receive hook.

    When you do this, gitolite does whatever is needed to run each of them as
    independent post-receive hooks (including sending them info over their
    STDIN as documented in 'man githooks').

  * @@gray((v3.6+))@@ You can change these hooks by saying:
.#! conf/vim-color
        repo    foo
            option hook.post-receive    =   deploy mail-admins
.end

    or delete all of them by saying:
.#! conf/vim-color
        repo    foo
            option hook.post-receive    =   ""
.end

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

## triggers

Triggers have their own [page][triggers].

## VREFs

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