(Note: git servers are most commonly used with ssh URLs, and this document describes installing gitolite to support such usage. If your users prefer http URLs, read this to install gitolite to support "smart http").
In this document:
This top section is for the impatient. You might qualify if you can understand the following:
A bare minimum gitolite setup has:
- a server
- a "hosting user" on the server (a real Unix userid; we use "git" in this document, although RPM/DEB installs use "gitolite")
- a virtual "admin user" -- the user who sets up gitolite and configures it
- the admin user's client or workstation, from which he does all his work
If you didn't get all that, or thought you did then ran into problems, beg/borrow some patience and read the rest of this document before trying it again.
Gitolite allows 3 methods of install:
These install methods are described in detail below. (Once you finish the install, read the admin document to administer your gitolite installation).
Upgrading is easy; you just re-run some of the same commands used for install. These commands are clearly noted in the install instructions below.
However, if you've added any new hooks, you must also run the next step (the
gl-setup
command), although this time you don't need to supply a pubkey
filename as an argument.
(Unlike the rest of this document, this specific method uses "gitolite" as the "hosting user" instead of "git", because that is what the RPM/DEB creates).
On your workstation:
~/.ssh/id_rsa.pub
file to /tmp/YourName.pub
on the serverOn your server, as root:
yum install gitolite # or 'apt-get install gitolite', or whatever
# this is the only step you need to repeat when upgrading gitolite
# current RPM/DEB create a hosting user called "gitolite"
su - gitolite
# (now as gitolite)
gl-setup /tmp/YourName.pub
On your workstation:
git clone gitolite@server:gitolite-admin
On your workstation:
~/.ssh/id_rsa.pub
file to /tmp/YourName.pub
on the serverOn your server, as root:
git clone git://github.com/sitaramc/gitolite
cd gitolite
src/gl-system-install
# defaults to being the same as:
# src/gl-system-install /usr/local/bin /usr/local/share/gitolite/conf /usr/local/share/gitolite/hooks
# to upgrade gitolite, repeat the above commands. Make sure you use the
# same arguments for the last command each time.
# now create your "hosting user" ('git' in our examples) using whatever
# command your distro expects you to use
# switch to the hosting user
su - git
# (now as git)
gl-setup /tmp/YourName.pub
On your workstation:
git clone git@server:gitolite-admin
IMPORTANT WARNING -- IGNORE AT YOUR PERIL: if you want to use this method you had better know the password to the hosting user on the server, just in case you manage to lock yourself out by messing with the keys.
NOTE: This method is exhaustively described in the tutorial, if you're interested. (That tutorial is by someone else but it's nice enough for me to link it here).
On your workstation:
~/.ssh/id_rsa.pub
file to /tmp/YourName.pub
on the serverOn your server, as git (the "hosting user"), first check if $HOME/bin
is
on the default PATH. If not, fiddle with the .bashrc
or .bash_profile
or
similar files and add it somehow. Then:
git clone git://github.com/sitaramc/gitolite
cd gitolite
src/gl-system-install
# defaults to being the same as:
# src/gl-system-install $HOME/bin $HOME/share/gitolite/conf $HOME/share/gitolite/hooks
# to upgrade gitolite, repeat the above commands. Make sure you use the
# same arguments for the last command each time.
gl-setup /tmp/YourName.pub
On your workstation:
git clone git@server:gitolite-admin
Since the from-client method is now deprecated for reasons explained elsewhere, some folks may want to do their next upgrade using the non-root method.
There are many, many ways to skin this cat; here's one way:
follow non-root install but stop after the gl-system-install step
temporarily rename your ~/.gitolite.rc
file to something else
now run the gl-setup step
(background: this will create a default rc file with default values, but crucially, it will give you the correct values for two very critical variables that are not used in the old from-client install method)
edit ~/.gitolite.rc
and bring in any non-default settings you may have
had in your old rc file.
When you're done, the only difference between your old and current rc
files should be that the $GL_PACKAGE_CONF
and the $GL_PACKAGE_HOOKS
variables are no longer commented out and look somewhat like this:
$GL_PACKAGE_CONF = '/home/git/share/gitolite/conf';
$GL_PACKAGE_HOOKS = '/home/git/share/gitolite/hooks';
Now save the file.
The most common thing that goes wrong in an install is something to do with ssh.
Here are three facts of ssh:
Please read how gitolite uses ssh and the ssh troubleshooting documents before asking for help.
If you've tried multiple methods of install, you may have multiple copies of the sources lying around. This could be a problem; see appendix b for how to detect and deal with this.
If none of this works read the rest of this document, understand it as much as you can, then ask for help.
gitolite runs as a single (real) user on a server, and is invoked via ssh.
Traditionally, this "hosting user" is "git", and thus all git URLs start
with ssh://git@server
(or the equivalent shorter form git@server:
).
RPM/DEB create and use "gitolite" as the hosting user
there is usually only one hosting user per server (machine), but gitolite makes it trivial to have as many as you want. In fact, every user on the server is a potential hosting user. Advanced users can look here!)
using this single user and sshd (or httpd) authentication, gitolite allows you to create any number of "virtual" users. Virtual user names only mean something to gitolite, and they need not be the same as any real userid on the server or any of the clients accessing it.
gitolite depends heavily on ssh pubkey (passwordless) access. Do not assume you know all about ssh -- most people don't. If in doubt, use a dedicated userid on both client and server for installation and administration of gitolite.
To make matters worse, ssh problems in gitolite don't always look like ssh problems. See doc/ssh-troubleshooting.mkd for help.
gitolite does NOT like it when people with shell access to the server fiddle with files and directories it controls.
Apparently this was not obvious to some people.
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.
Throughout the documentation, we use "YourName" 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.
If you're using DEB or RPM, the installer creates a user called "gitolite", so substitute that for "git" anywhere in the docs where the "hosting user" is mentioned as "git".
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.
$GIT_PATH
variable in the "rc" fileauthorized_keys
file format
(probably optional if you're using the http backend)if you're installing gitolite, you're a "system admin", like it or not. Ssh is therefore a necessary skill. Please take the time to learn at least enough to get passwordless access working.
you also need to be somewhat familiar with git itself. You cannot administer a whole bunch of git repositories if you don't know the basics of git.
some familiarity with Unix and shells is probably required
regular expressions are a big part of gitolite in many places but familiarity is not necessary to do basic access control.
You can get the latest version of gitolite from github or indefero using the 'git clone' command:
git clone git://github.com/sitaramc/gitolite.git
# (OR)
git clone git://sitaramc.indefero.net/sitaramc/gitolite.git
If you are on an internal network and cannot clone the gitolite repo, you can do the clone on some other machine and create a tar file from it to use on the internal network. Here's how:
git clone git://github.com/sitaramc/gitolite.git
# (OR)
git clone git://sitaramc.indefero.net/sitaramc/gitolite.git
cd gitolite
make master.tar
# or maybe "make pu.tar"
Please use the make command as shown, not a plain "git archive", because the
Makefile adds a file called .GITOLITE-VERSION
that will help you identify
which version you are using.
(Advanced users only, please!)
There is no gitolite "daemon"; it gets invoked via sshd which calls "gl-auth-command" via the "command=" option in the authkeys file (see gitolite and ssh for more).
If you think about it, this means every real (unix) user on the system can host her own gitolite server!
Of course, one doesn't normally do that in the interests of sanity, but let's say you want to create one gitolite instance for each department on some company-wide mega-server.
Using one of the first two methods of installation, it's trivial to create
multiple gitolite instances -- essentially any Unix user can then run
gl-setup
with some pubkey filename as an argument and that user is now a
gitolite host.
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:
webbrowser_repos
and webserver_repos
su - webbrowser_repos
, then gl-setup alice.pub
webserver_repos
and bob.pub
, and so on for others)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.
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.
~/.ssh/config
and delete the paragraph starting with host
gitolite
, if present.~/gitolite-admin
~/.ssh/authorized_keys
and delete all lines between # gitolite
start
and # gitolite end
inclusive.~/.gitolite
, ~/.gitolite.rc
and
~/repositories/gitolite-admin.git
/usr/local/bin
or $HOME/bin
, and then
delete /var/gitolite/conf
and /var/gitolite/hooks
or
$HOME/share/gitolite/conf
and $HOME/share/gitolite/hooks
There's some duplication between this and the previous section, but uninstalling gitolite is described in great detail in doc/uninstall.mkd
This method was the only install mode at one time, but the newer ones are much better, so it's kinda legacy now (Wow -- fancy something being "legacy" in software that is not yet 2 years old!)
The only advantage of this method is that it forces you to solve the ssh pubkey problem before attempting to install.
But I'm not sure if that is worth the hassle of supporting an install scheme that ends up with the admin user having two keys, though. And this in turn 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.
All in all, I plan to obsolete it eventually. Meanwhile, it is verbosely documented in this transcript, including outputs of the commands concerned.
If you've tried multiple methods of install, you may have multiple copies of
the sources lying around, and when you ran gl-setup
it picked up the wrong
one. This might also happen if the directory you supplied as the first
argument to src/gl-system-install
is not even in the $PATH
.
Run su - git
then which gl-setup
to see which it picked up. This is what
it should be for each method:
/usr/bin
src/gl-system-install
command (or
/usr/local/bin
by default)src/gl-system-install
command
(or $HOME/bin
by default)If this is not what you get, remove the partially installed or extraneous
sources, if any, and try again. Or fix your $PATH
.
One situation that is not easy to solve is if the system admin installed
gitolite using the RPM/DEB or root methods, and you want to install a later
version using the non-root method. Since /usr/bin
and /usr/local/bin
are
usually earlier than $HOME/bin
in the $PATH
, you'll have to get creative.
Good luck.