assorted tips and notes

common errors and mistakes

adding repositories/ at the start of the repo name in the git clone. This error is typically made by the admin himself -- because he knows what $REPO_BASE is set to and thinks he has to provide that prefix on the client side also :-) In fact gitolite prepends $REPO_BASE internally, so you shouldn't also do the same thing!
being able to clone but getting errors on push. Most likely caused by a combination of:
- you already have shell access to the server, not just "gitolite" access, and
- you cloned using git clone git@server:repositories/repo.git (notice there's an extra "repositories/" in there?)
In other words, you used a key that completely bypassed gitolite and went straight to the shell to do the clone.

Please see doc/ssh-troubleshooting.mkd for what all this means.

other errors, warnings, notes...

cloning an empty repo

Cloning an empty repo is only possible with clients greater than 1.6.2. So at least one of your clients needs to have a recent git. Once at least one commit has been made, older clients can also use it

When you clone an empty repo, git seems to complain about fatal: The remote end hung up unexpectedly. However, you can ignore this, since it doesn't seem to hurt anything. [Update 2009-09-14; this has been fixed in git 1.6.4.3]

`@all` syntax for repos

There is a way to use the @all syntax for repos also, as described in doc/gitolite.conf.mkd. However, there are a couple of minor cautions:

don't use NAME/ or such restrictions on the special @all repo. Due to the potential for defeating a crucial optimisation and slowing down all access, we do not support this.

features

Apart from the big ones listed in the top level README, and subjective ones like "better config file format", gitolite has evolved to have many useful features than the original goal of branch-level access control.

syntax and normal usage

one user, many keys

If you have a user who has more than one pubkey (like from different machines) the simplest way to deal with it is to add subdirectories and add keys there. For example, I might have these files in keydir/:

sitaram.pub
home/sitaram.pub
laptop/sitaram.pub

old style multi keys: Link

security, access control, and auditing: Link

convenience features: Link

INconvenience features

deleting a repo

By design, there is no code in gitolite to delete a repo if the repo was specified by name in the config file. (Wildcard repos can be deleted by the user; see here for details).

If you do want to permanently delete a non-wildcard repo, here's what you do:

remove the repo from the gitolite-admin repo clone's conf/gitolite.conf file. "add" the change, commit, and push.
then remove the repo from ~/repositories on the server (or whatever you set $REPO_BASE to in the ~/.gitolite.rc)

renaming a repo

This is similar; there's no code to do this in gitolite. What you do is:

log on to the server, cd $REPO_BASE (default: cd ~/repositories), and mv old-name.git new-name.git
back on your gitolite-admin clone, edit conf/gitolite.conf and replace all occurrences of old-name with new-name. Then add, commit, and push as usual.

The order of these 2 steps is important; do not reverse them :-)

helping with gitweb

Although gitweb is a completely separate program, gitolite can do quite a lot to help you manage gitweb access as well; once the initial setup is complete, you can do it all from within the gitolite config file!

If you just want gitweb to show some repositories, see here for how to specify which repos to show.

easier to link gitweb authorisation with gitolite

Over and above whether a repo is even shown by gitweb, you may want to further restrict people, allowing them to view only those repos for which they have been given read access by gitolite.

This requires that:

you have to have some sort of HTTP auth on your web server (out of my scope, sorry!)
the HTTP auth should use the same username (like "sitaram") as used in the gitolite config (for the corresponding user)

Normally a superuser sets up passwords for users using the "htpasswd" command, but this is an administrative chore.

Robin Smidsrød had the great idea that, since each user already has pubkey access to git@server, this gives us a very neat way of using gitolite to let the users manage their own HTTP passwords. Here's how:

setup apache so that the htaccess file it looks for is owned by the "git" user
in the ~/.gitolite.rc file, look for the variable $HTPASSWD_FILE and point it to this file
tell your users to type in ssh git@server htpasswd to set or change their HTTP passwords

Of course some other authentication method can be used (e.g. mod_ldap) as long as the usernames match.

Gitweb allows you to specify a subroutine to decide on access. We use that feature and tie it to gitolite. Configuration example can be found in contrib/gitweb/.

umask setting

Gitweb not able to read your repos? You can change the umask for newly created repos to something more relaxed -- see the REPO_UMASK setting in the rc file documentation.

advanced features

There are some really cool features that are now in pretty wide use.

repos named with wildcards is useful when some or most of your repos fit a pattern, avoiding the need to name repos individually in the config file. New repos matching the pattern can be created by any user (if you give them rights to), with a set of permissions assigned to "roles", and the creator can then place users into those roles.
admin defined commands allow controlled access to specific commands and scripts without giving users full shell access.

odds and ends

"poking" the admin repo to force a compile

Sometimes you need to force a compile, as if you pushed the gitolite-admin repo. I have a git alias that looks like this:

[alias]
    poke = !git ls-remote origin | grep -w refs/heads/poke && git push origin :poke || git push origin master:poke

so I just run git poke. This toggles between deleting and creating a dummy branch called "poke". Either operation will trigger the hooks.