April 17, 2012: The gitolite author and the author of this site decided that it is best to make these changes: step 5 changed to reflect new gitolite.
My name is Sena Wario and this is my gitolite tutorial. Gitolite sets up a central "server" to host many git repositories for many users.
I initially wrote this because someone on #git said "people always assume the official
documentation is crap; that's why they look for tutorials". But a better reason is that gitolite comes with an enormous amount of documentation, (just the
master TOC/index has more than 300 entries!) so the sheer size can be overwhelming for a rank newbie. Also, a lot of people start using gitolite before
they have acquired enough knowledge of git, which makes things worse.
My tutorial uses words and phrases borrowed from the
official gitolite documentation, so don't be surprised if it sounds
similar in places!
Also, since everyone's environment will not be exactly the same, you can expect some errors while following this on your machine. Let me know about them (firstname.lastname@example.org) so I can add tips if needed.
Anything you have to type is in bold. System responses (when shown) are in normal font.
For this tutorial I will be using Fedora 15, but it should work with any Linux. Probably any Unix even. (The only non-portable command in this whole tutorial is the "useradd" command; see below for details. The rest should work fine anywhere).
As the gitolite documentation says, gitolite is
invoked by ssh, so actually any "unix user" on the server
can become a "gitolite server". In this tutorial we will create a user called "gitolite" to host our gitolite server. (This means developers will access repos with URLs that look like email@example.com:repo (or maybe ssh://firstname.lastname@example.org:port-number/repo if you need to use a port number other than 22).
According to the official install document, gitolite has 3 different methods of installation -- "package", "root", and "non-root". The "non-root" method, is the least intrusive of these (you just have to create one userid and everything else happens within that userid, without touching the rest of the system), so this is what this tutorial is about. [Note: a fourth method, "from-client", exists but is now deprecated].
Step 1: SET UP/CHECK PREREQUISITES
Server IP/name and OS:
You will need some flavour of Unix for the server. I've only tested with Fedora 16, though.
In this tutorial we will pretend the server is called glh (stands for "gitolite host").
You will need a POSIX compatible shell, perl, and git (at least version 1.6.6). I believe that installing git using your package manager will get you the others also so just do that!
You will need an account on the server for which you have the
password. This account will become the "gitolite hosting user".
In this tutorial we will create a new user called gitolite
and use that as the hosting user. (The following commands work on Fedora; your distro/OS may be different. For instance, I am told Debian uses "adduser" instead of "useradd").
Server Account Environment: $HOME/bin should be part of the default $PATH for this user. If it isn't, fiddle with the .bashrc or .bash_profile or similar files and add it somehow.
Administrator: You :-)
Administrator's Workstation OS: Shouldn't really matter...
Administrator's Workstation Software:
You only need git and some ssh client. If you're using Windows, msysgit is the best. YMMV. (This tutorial is not about getting ssh to work so please do not ask me for help on that. The gitolite documentation has lots of info on ssh).
Step 2: MAKING YOUR PUBKEY
On your workstation, run the following command
You don't have to create a new key. If you already have a keypair, it will ask you if you want to overwrite it, like this:
Just say "n" and use your existing keypair for the next step.
If you're on Windows under "msysgit"'s bash
shell, the commands are pretty much the same. The location of the
files will be different, but the command will print very clearly
where the two files (private key:
Step 3: COPYING YOUR PUBKEY TO THE SERVER
We need to copy your pubkey (
Step 4: GETTING THE GITOLITE SOFTWARE TO YOUR SERVER
The rest of the installation is done from the server,
so log on to the server
somehow. For example, you could log on as some other user and then "su - gitolite".
Note: Ssh-ing in directly may not work after the initial install succeeds, because your pubkey now gets sent, and on the other side, gitolite kicks in instead of giving you a shell. If that happens, you will need to force password authentication to get a shell: try ssh -o preferredauthentications=password gitolite@glh
Once you've logged in to the gitolite user on server glh you must download the gitolite software. If your server has direct internet connectivity, this is pretty easy:
If your server does not have direct internet connectivity, find some machine that does, and use it as an intermediary, like this:
Step 5: THE ACTUAL INSTALL
On the server still, as user "gitolite", do this:
Step 6: CLONING THE ADMIN REPO TO THE WORKSTATION
Now you have to get back to your workstation, and do this:
This means you have successfully installed gitolite and you are now ready to start using it.
However, if this does not work, or if it works only if you use "git clone gitolite@glh:repositories/gitolite-admin" (note the extra "repositories/") or something like that, then your ssh setup is not working. See the main gitolite project documents for an ssh-troubleshooting guide, or online here.
Step 7: ADDING NEW USERS AND REPOS
First, obtain pubkeys for your users. We will start with the example users 'alice" and "bob".
Ask both of them to generate a keypair just as you
did in "step 2" of your tutorial, and send you their keys
somehow. Save them with their respective names (alice.pub and
Now you have your two users, let us assume that your two new repos are "foo" and "bar". The "foo" repo must be writable by alice, but read-only to bob. The "bar" repo is the other way around -- writable by bob, read-only to alice.
Now, on your workstation, do this:
Of course, instead of vim you can use whatever editor you like. Anyway, when the editor pops up, you will see lines like this:
Now add these lines:
Save the file and quit.
Now type in the following commands. Note: If the commit command fails with an error saying *** Please tell me who you are., you should read what it says, run the commands it suggests, and retry the commit command.
And you're done!