6e29365316
I got tired of being told "TL;DR". Now the online versions of most documents fit on a page or two, or at least most of them do. The rest has been split out (and you can see the links to the split out sections right where the text is in the raw Markdown). This is much more pleasant to read, and I've improved the linking so it's much less effort for me to keep the links correct.
125 lines
5.1 KiB
Markdown
125 lines
5.1 KiB
Markdown
# F=user 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!
|
|
|
|
## always available commands
|
|
|
|
The only command that is *always* available to every user is the [`info`
|
|
command][info], 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 creating a 1-line
|
|
file called "gl-creater" (note spelling!) in the repo directory, with just
|
|
your gitolite userid in it.
|
|
|
|
This is for new repos you create. But for repos that already existed and were
|
|
migrated into gitolite by the admin, the admin has to manually create that
|
|
"gl-creater" file, otherwise you won't be able to execute certain commands
|
|
that you otherwise might have access to.
|
|
|
|
"Wildrepos" is an optional feature of gitolite that the admin has to
|
|
explicitly enable.
|
|
|
|
## commands only available with "wildrepos" on
|
|
|
|
### listing repos you created
|
|
|
|
The info command will not show you your own wildcard repos. To get that list,
|
|
try the [`expand` command][expand].
|
|
|
|
### 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 [`setperms` command][setperms] to set
|
|
permissions for other users by specifying which users are in the list of
|
|
"READERS", and which in "WRITERS". That same section also talks about the
|
|
`getperms` command as well.
|
|
|
|
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.
|
|
|
|
### #setdesc adding a description to repos you created
|
|
|
|
The `setdesc` and `getdesc` commands work similarly to the `setperms` and
|
|
`getperms` commands. You just say
|
|
|
|
echo "some description here" | ssh git@server setdesc pub/<yourname>/<your_reponame>
|
|
|
|
and if you want to check you just say
|
|
|
|
ssh git@server getdesc pub/<yourname>/<your_reponame>
|
|
|
|
## "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 (in "contrib/adc") 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`.
|
|
|
|
Most of the shipped ADCs are briefly described [here][shipped_ADCs], with links
|
|
to more details if available. However, **please understand** that these
|
|
commands may not be available, or their behaviour may have been changed to
|
|
suit local requirements, and of course new ones may have been added. You'll
|
|
have to ask your local admin for answers, not me!
|
|
|