diff --git a/README.mkd b/README.mkd index 0f9e9a5..e659d5e 100644 --- a/README.mkd +++ b/README.mkd @@ -11,6 +11,7 @@ In this document: * quick install * what + * documentation * why * main features * security @@ -69,8 +70,15 @@ summary": * several other neat features described below and elsewhere in the [doc/][docs] directory. -Gitolite comes with a **huge** amount of documentation. If you're absolutely -new, the suggested reading order is this: + + +#### documentation + +Gitolite comes with a **huge** amount of documentation. Almost all of it is +for the *administrator* of a gitolite server. If you're a *user*, you only +need [this][user]. + +Otherwise, the suggested reading order is this: * the README (this document) for a quick intro * the [INSTALL][install] document @@ -210,3 +218,4 @@ Gitolite is released under GPL v2. See COPYING for details. [who]: http://sitaramc.github.com/gitolite/doc/who-uses-it.html [tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial [docs]: http://sitaramc.github.com/gitolite +[user]: http://sitaramc.github.com/gitolite/doc/user-manual.html diff --git a/contrib/adc/README.mkd b/contrib/adc/README.mkd index 6061d2e..9d40555 100644 --- a/contrib/adc/README.mkd +++ b/contrib/adc/README.mkd @@ -5,7 +5,8 @@ ---- **able**: enable/disable push access temporarily (such as for taking backups -or other admin chores); details [here][able]. +or other admin chores); details [here][able]. This ADC is meant only for +admins. [able]: http://sitaramc.github.com/gitolite/doc/admin-defined-commands.html#_enable_disable_push_access_temporarily diff --git a/doc/user-manual.mkd b/doc/user-manual.mkd new file mode 100644 index 0000000..00a215d --- /dev/null +++ b/doc/user-manual.mkd @@ -0,0 +1,160 @@ +# 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. + +In this document: + + * accessing gitolite + * always available commands + * digression: two kinds of repos + * commands only available with "wildrepos" on + * listing repos you created + * set/get additional permissions for repos you created + * adding a description to repos you created + * "site-local" commands + +---- + + + +### 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. + +[info]: http://sitaramc.github.com/gitolite/doc/report-output.html#_the_info_command + + + +### 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. If you look at the documentation on the [`info` command][info] +you will see there are a couple of lines that look like regex patterns, +against which you see an additional "C" permission not available with the +others. + +This 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 noted by creating a 1-line file called "gl-creater" +(note spelling!) in the repo directory, with just your gitolite userid in it. + +This happens automatically. But for repos that were migrated into gitolite +and whose names fit a pattern, the admin has to manually create those files, +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 "turn +on". + + + +### 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]. + +[expand]: http://sitaramc.github.com/gitolite/doc/report-output.html#_the_expand_command + + + +#### 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//`). + +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. + +[setperms]: http://sitaramc.github.com/gitolite/doc/wildcard-repositories.html#_handing_out_rights_to_wildcard_matched_repos + + + +#### 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// + +and if you want to check you just say + + ssh git@server getdesc pub// + + + +### "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][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! + +[ADCs]: http://sitaramc.github.com/gitolite/contrib/adc/README.html