200db6e486
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...
161 lines
6.5 KiB
Markdown
161 lines
6.5 KiB
Markdown
# 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
|