gitolite/doc/users.mkd

# what users (not admins) need to know about gitolite

...written for the one guy in the world no one will think of as "just a normal
user" ;-)

This document has some text, and a lot of links.  Most of this info *is*
available in the rest of the documentation, but it's scattered and sparse.
Collecting all of it, or at least links to it, in one place sounds useful.

## accessing gitolite

The most common setup is based on ssh, where your admin asks you to send him
your public key, and uses that to setup your access.

Your actual access is either a git command (like `git clone
git@server:reponame`, and we won't be discussing these any more in this
document), or an ssh command (like `ssh git@server info`).

Note that you do *not* get a shell on the server -- the whole point of
gitolite is to prevent that!

## #info the info command

The only command that is *always* available to every user is the `info`
command (run `ssh git@host info -h` for help), which tells you what version of
gitolite and git are on the server, and what repositories you have access to.
The list of repos is very useful if you have doubts about the spelling of some
new repo that you know was setup.

## digression: two kinds of repos

Gitolite has two kinds of repos.  Normal repos are specified by their full
names in the config file.  "Wildcard" repos are specified by a regex in the
config file.  Try the [`info` command][info] and see if it shows any lines
that look like regex patterns, (with a "C" permission in addition to the "R"
and the "W").

If you see any, it means you are allowed to create brand new repos whose names
fit that pattern.  When you create such a repo, your "ownership" of it (as far
as gitolite is concerned) is *automatically* recorded by gitolite.

## other commands

### #perms set/get additional permissions for repos you created

The gitolite config may have several permissions lines for your repo, like so:

    repo pub/CREATOR/..*
        RW+     =   CREATOR
        RW      =   user1 user2
        R       =   user3

If that's all it had, you really can't do much.  Any changes to access must be
done by the administrator.  (Note that "CREATOR" is a reserved word that gets
expanded to your userid in some way, so the admin can literally add just the
first two lines, and *every* authenticated user now has his own personal repo
namespace, starting with `pub/<username>/`).

To give some flexibility to users, the admin could add rules like this:

        RW      =   WRITERS
        R       =   READERS

(he could also add other roles but then he needs to read the documentation).

Once he does this, you can then use the `perms` command (run `ssh git@host
perms -h` for help) to set permissions for other users by specifying which
users are in the list of "READERS", and which in "WRITERS".

If you think of READERS and WRITERS as "roles", it will help.  You can't
change what access a role has, but you *can* say which users have that role.

**Note**: there isn't a way for you to see the actual rule set unless you're
given read access to the special 'gitolite-admin' repo.  Sorry.  The idea is
that your admin will tell you what "roles" he added into rules for your repos,
and what permissions those roles have.

### #desc adding a description to repos you created

The `desc` command is extremely simple.  Run `ssh git@host desc -h` for help.

## "site-local" commands

The main purpose of gitolite is to prevent you from getting a shell.  But
there are commands that you often need to run on the server (i.e., cannot be
done by pushing something to a repo).

To enable this, gitolite allows the admin to setup scripts in a special
directory that users can then run.  Gitolite comes with a set of working
scripts that your admin may install, or may use as a starting point for his
own, if he chooses.

Think of these commands as equivalent to those in `COMMAND_DIR` in `man
git-shell`.

You can get a list of available commands by running `ssh git@host help`.