F=admin administering and running gitolite

please read this first

Unless you know what you're doing, do not do anything manually on the server (except when the documentation says you should, for example to add custom hooks). In particular, adding new repositories or users or changing the access control rules should not be done directly on the server. Things will break. For example, if you manually create a repo on the server, it will not have the required "update" hook, without which there is no access control for pushes.

Most normal (day-to-day) gitolite admin work is done by cloning the gitolite-admin repo from the server to your workstation, making changes to the clone, and pushing those changes back.

The installation steps in the previous section include the steps to do this clone, so you should already have one on your workstation, in ~/gitolite-admin. You can of course clone it anywhere else you want and use that clone.

Either way, make sure you cd into this clone first.

Note: some of the paths in this document use variable names. Just refer to ~/.gitolite.rc for the correct values for your installation.

Once you've cloned it, you're ready to add users and repos.

F=add adding users and repos

Do NOT add repos or users directly on the server! You MUST manage the server by cloning the special 'gitolite-admin' repo on your workstation (git clone git@server:gitolite-admin), making changes, and pushing them. This section tells you how to add users and repos.

F=hooks using hooks

#customhooks custom hooks

You can supply your own, custom, hook scripts if you wish. Install gitolite as usual, then:

You can use this procedure to install new hooks as well as to update hooks that you had previously installed.

IMPORTANT WARNINGS

#hookchaining hook chaining

Sometimes you need to use git hooks for your own purposes (site-local validations, CI integration, email notifications, or the ever popular "live website update"!). However, the hooks you want to use may already be in use by gitolite.

This section will tell you what to do in such cases. First, let's list the hooks that gitolite uses:

To run your own 'update' hook, just put it in a file called update.secondary and install it as a hook. Gitolite's update hook will automatically chain to it, taking care to pass it the same 3 arguments the original update hook received from git.

Also see the document on [virtual refs][vref] for a way to add additional checks that you might need.

For post-receive, (if using mirroring) do the opposite. You're normally expected to rename the shipped 'post-receive.mirrorpush' to 'post-receive', but don't do this. Instead, simply run hooks/post-receive.mirrorpush at the end of your hook code. Do not worry about replicating STDIN (the documented way in which a post-receive hook receives its input) because the mirroring code does not use it.

To run your own post-update hook on normal repos, just install a hook called 'post-update' the usual way. It'll be installed on all normal repos but not on the special gitolite-admin repo. If you need that for the gitolite-admin repo, you'll have to call it post-update.secondary.

Finally, these names ('update.secondary' and 'post-update.secondary') are merely the defaults. You can change them to anything you want; look in conf/example.gitolite.rc for details.

environment variables available to hooks

The following environment variables are set, and may be useful for any custom processing you wish to do in your hook code:

The following variables are also set, but are generally less useful:

"gl-post-init" hook

Sometimes it is necessary to do something whenever a new repo is created. If you need this functionality, just supply a hook called "gl-post-init" with whatever code you want in it.

#pre-git "gl-pre-git" hook

Although git has lots of nice hooks you can tap into, they all run only on a push. There's nothing that runs on a fetch or a clone, and there's no way to run something before git-receive-pack or git-upload-pack, (as the case may be) are invoked.

That's what the gl-pre-git hook is for. If an executable hook called gl-pre-git is present, it will be invoked with the current directory set to repo.git, and with a single argument which will be either R or W depending on what the client is trying to do. The environment variables GL_USER and GL_REPO are available. STDOUT will be forced to STDERR before it is called, to avoid confusing the client.

If the code returns anything other than 0, gitolite will terminate the operation (i.e., not run git at all), just like many git hooks do, so make sure you end with exit 0 or equivalent.

other features

F=moverepos moving pre-existing repos into gitolite

It's best to split this into different use cases.

Case 1 -- few repos: This is for moving one or two repos at a time, when you have a copy of the repo on your workstation. It is also the only way if you have push rights to the admin repo but no shell privileges on the server.

Case 2 -- many repos: This is when you have many existing repos to add, and they're all bare (as good little server repos should be) and you have shell access on the server. Here's how to do it; please note the order is important here:

Case 3 -- far too many repos (or your initials are JH ;-): This is when you're like Case 2, except you have so many repos that step 3 becomes too cumbersome (even with a script doing it for you).

Assuming you can group your repo names into various patterns, and can use similar access control lines within each such group, you can use gitolite's "wildcard repos" feature.

First read the [wildcard repositories][wild] document, or at least skim through it, to understand the basic concept. Then do this:

Details

In the end, it all boils down to (a) making sure the update hook is correct on all repos, wild or normal, and (b) making sure gl-creater contains the owner name for wild repos. The rest of the setup is in the conf file.

F=moveserver moving the whole thing from one server to another

[NOTE: I would appreciate help testing these instructions]

Here's the simplest set of instructions, assuming the destination is a recent gitolite (has the 'gl-admin-push' command). Unless specified, all steps are on the new server.

Done.

custom git config

The custom hooks feature is a blunt instrument -- all repos get the hook you specified and will run it. You can of course install hooks manually on the server, but sometimes that's cumbersome.

Instead, you could set your hooks to only work if a certain "gitconfig" variable was set. See [this][rsgc] for a way to specify "git config" settings on a per repository basis.