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...
This commit is contained in:
Sitaram Chamarty
parent
57b3ac3a91
commit
200db6e486
13
README.mkd
13
README.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.
|
|||
[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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
160
doc/user-manual.mkd
Normal file
160
doc/user-manual.mkd
Normal file
|
|
@ -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.
|
||||
|
||||
[info]: http://sitaramc.github.com/gitolite/doc/report-output.html#_the_info_command
|
||||
|
||||
<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
|
||||
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".
|
||||
|
||||
<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].
|
||||
|
||||
[expand]: http://sitaramc.github.com/gitolite/doc/report-output.html#_the_expand_command
|
||||
|
||||
<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+ = 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.
|
||||
|
||||
[setperms]: http://sitaramc.github.com/gitolite/doc/wildcard-repositories.html#_handing_out_rights_to_wildcard_matched_repos
|
||||
|
||||
<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
|
||||
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
|
||||
Loading…
Reference in a new issue