gitolite installatation

In this document:


please read this first

important notes

Please make sure you understand the following points first.

A gitolite setup has:

It is possible to have the server and the client be the same machine, and even the admin user be also the hosting user, (i.e., sitaram@server can install and administer a gitolite setup running under sitaram@server, a situation that is common with some hosting services). It's actually fairly easy and safe to do, as long as you have password access to the server for emergency use. However, I will not be documenting it because (a) if you know ssh you'll know how to extrapolate my instructions to do this and (b) if you don't know ssh it'll be a nightmare to support you.

conventions used

Throughout the documentation, we use "sitaram" as the admin user, and his workstation is called "client". The hosting user is "git", and the server is called "server". Please substitute your values as needed.

Also, we often say "the rc file". This means ~/.gitolite.rc on the server. And when we say the "access control rules", or "conf file", or "config file", we mean conf/gitolite.conf on your gitolite-admin clone.

requirements

client/workstation

server

technical skills

installation and setup

install methods and deciding which one to use

Gitolite has 4 install methods:

Here's how you install using these 3 methods. Future upgrades are equally easy -- the steps required for upgrading are marked "(U)".

(package method) directly on the server, using RPM/DEB

(root method) directly on the server, manually, with root access

(non-root method) directly on the server, manually, without root access

WARNING: if you use this method you'd better know enough about ssh to be able to keep your keys straight, and you'd also better have password access to the server so that if you screw up the keys you can still get on, or be able to "su - git" from some other user on the server.

(from-client method) install from the client to the server

The advantage of this method is that it forces you to solve the ssh pubkey problem before attempting to install. It works best if you have dedicated userids, one on the server for installing gitolite, and one the client for administering it.

Sadly, it also forces the admin to use a different URL to access gitolite repos than normal users, which seems to confuse a heck of a lot of people who don't read the prominently displayed messages and/or the documentation.

This method is verbosely documented in this transcript, including outputs of the commands concerned.

URLs for gitolite-managed repos

The URL for normal users (i.e., users other than the admin) is always of the form "git@server:reponame". So, for instance, git clone git@server:testing gets any valid user a copy of the "testing" repo.

In the first 3 install methods, the admin user will also use the same URL format, like git clone git@server:gitolite-admin.

However, in the fourth ("from-client") method, the admin user needs a different URL (gitolite:reponame) to gain access to the gitolite repositories. Check here for why.

special cases -- multiple gitolite servers

package method and root method

With the first two methods of installation, it's trivial to create multiple gitolite instances (say one for each department, on some mega company-wide server). You can even do this without giving shell access to the admins. Here's an example with just two "departments", and their admins Alice and Bob:

That's it. The URL for all web browser projects is now something like webbrowser_repos@server:reponame, and similarly for the others.

Notice that you only have to do this once for each "department", and it's really just one command after creating the userid. None of these admins need to have a command line on the server, so don't give them the passwords if you don't need to -- the pubkey will allow them to be gitolite admins on their domain, and that's quite enough for normal operations.

from-client method

Thanks to Matt Perzel, the easy-install command now takes an optional 4th parameter, which is the "nickname" of the gitolite server. It gets defined in ~/.ssh/config, and if not used it defaults to "gitolite".

So if you used the following command to install gitolite to 2 different servers:

./src/gl-easy-install -q git my.1st.git.server admin_user1 gitolite_server_1
./src/gl-easy-install -q git my.2nd.git.server admin_user1 gitolite_server_2

you will find that ~/gitolite_server_1-admin and ~/gitolite_server_2-admin have been created as respective clones. Or you can re-clone elsewhere:

cd ~/admin1; git clone gitolite_server_1:gitolite-admin.git
cd ~/admin2; git clone gitolite_server_2:gitolite-admin.git

upgrading

Upgrading gitolite is easy. In each method above, just re-do the step that is marked "(U)". Also, if you're using either of the two methods that use the src/gl-system-install command, please make sure you give it the same arguments!

If you've added any new hooks, please also run the next step (gl-setup) also.

Also, remember that some new features may require additional settings in your ~/.gitolite.rc file.

uninstalling

cleaning out a botched install

When people have trouble installing gitolite, they often try to change a bunch of things manually on the server. This usually makes things worse ;-) so here's how to clean the slate.

uninstalling gitolite completely

There's some duplication between this and the previous section, but uninstalling gitolite is described in great detail in doc/uninstall.mkd