Browse files

user-manual added ("user" as opposed to "admin")

Normally, I use the word "user" in gitolite to mean *my* users, who are
actually admins on their setups.  All my documentation has been geared
to that class of person.

Last night my most famous "user" (not "admin", a real gitolite user)
mentioned that he found it very hard to find info on what a *user* could
do, and he was right.  So here goes...
  • Loading branch information...
sitaramc committed Oct 29, 2011
1 parent 57b3ac3 commit 200db6e486c680a6be37a145ef1930449af79acb
Showing with 173 additions and 3 deletions.
  1. +11 −2 README.mkd
  2. +2 −1 contrib/adc/README.mkd
  3. +160 −0 doc/user-manual.mkd
@@ -11,6 +11,7 @@ In this document:
* <a href="#_quick_install">quick install</a>
* <a href="#_what">what</a>
+ * <a href="#_documentation">documentation</a>
* <a href="#_why">why</a>
* <a href="#_main_features">main features</a>
* <a href="#_security">security</a>
@@ -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:
+<a name="_documentation"></a>
+#### 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.
@@ -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
@@ -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:
+ * <a href="#_accessing_gitolite">accessing gitolite</a>
+ * <a href="#_always_available_commands">always available commands</a>
+ * <a href="#_digression_two_kinds_of_repos">digression: two kinds of repos</a>
+ * <a href="#_commands_only_available_with_wildrepos_on">commands only available with "wildrepos" on</a>
+ * <a href="#_listing_repos_you_created">listing repos you created</a>
+ * <a href="#_set_get_additional_permissions_for_repos_you_created">set/get additional permissions for repos you created</a>
+ * <a href="#_adding_a_description_to_repos_you_created">adding a description to repos you created</a>
+ * <a href="#_site_local_commands">"site-local" commands</a>
+<a name="_accessing_gitolite"></a>
+### 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!
+<a name="_always_available_commands"></a>
+### 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.
+<a name="_digression_two_kinds_of_repos"></a>
+### 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
+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
+<a name="_commands_only_available_with_wildrepos_on"></a>
+### commands only available with "wildrepos" on
+<a name="_listing_repos_you_created"></a>
+#### listing repos you created
+The info command will not show you your own wildcard repos. To get that list,
+try the [`expand` command][expand].
+<a name="_set_get_additional_permissions_for_repos_you_created"></a>
+#### 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 = 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:
+(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.
+<a name="_adding_a_description_to_repos_you_created"></a>
+#### 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>
+<a name="_site_local_commands"></a>
+### "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
+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!

0 comments on commit 200db6e

Please sign in to comment.