deac/gitolite
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

doc cleanup on info and expand command

Browse source 
jefferai pointed out that some of the links about this were broken, and
a quick look showed that it was described in multiple places too.
Brought it all together...
This commit is contained in:
Sitaram Chamarty 2010-08-21 17:02:12 +05:30
parent 6e2db12302
commit d6704d052a
4 changed files with 86 additions and 105 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

50
doc/3-faq-tips-etc.mkd
View file

@ -438,54 +438,10 @@ Sometimes there are too many repos, maybe even named similarly, or with the
potential for typos, confusion about hyphens/underscores or upper/lower case, potential for typos, confusion about hyphens/underscores or upper/lower case,
etc. You'd just like a simple way to know what repos you have access to. etc. You'd just like a simple way to know what repos you have access to.
Easy! Just use ssh to give the "info" command to the gitolite server: Gitolite provides two commands (`info` and `expand`) to help you find this
information; please check [doc/report-output.mkd][repout] for details.
$ ssh git@server info [repout]: http://github.com/sitaramc/gitolite/blob/pu/doc/report-output.mkd
hello sitaram, the gitolite version here is v1.4.2-4-g40cbecd
the gitolite config gives you the following access:
#R W SecureBrowse
#R W anu-wsd
#R W entrans
@R W git-notes
@R W gitolite
#R W gitolite-admin
#R W indic_web_input
@C #R private/CREATOR/[\w.-]+
#R W proxy
@C @R W public/CREATOR/[\w.-]+
@R @W testing
#R W vkc
To understand what these symbols mean, please see doc/report-output.mkd.
You can also pass an extra argument to subset the listing; it's treated as a
regex pattern that can match anywhere in the reponame.
In "big-config" mode (i.e., when `GL_BIG_CONFIG` is set) this argument is
**mandatory**. You can try and cheat the system by passing in a "." but
gitolite truncates the output after 5 results to prevent a DOS.
$ ssh git@server info git
hello sitaram, the gitolite version here is v1.4.2-4-g40cbecd
the gitolite config gives you the following access:
@R W git-notes
@R W gitolite
#R W gitolite-admin
$ ssh git@server info admin
hello sitaram, the gitolite version here is v1.4.2-4-g40cbecd
the gitolite config gives you the following access:
#R W gitolite-admin
The administrator can also say things like:
# if you installed using the "from-client" method
ssh gitolite info foo u1 u2 u3
# for the other 3 install methods
ssh git@server info foo u1 u2 u3
to get this info for other user(s). The "foo" is a partial reponame or a
regex pattern; see above for details.
<a name="including_config_lines_from_other_files"></a> <a name="including_config_lines_from_other_files"></a>

62
doc/4-wildcard-repositories.mkd
View file

@ -20,12 +20,12 @@ workarounds I may not have the time to code it right away.
In this document: In this document:
* <a href="#rc_file_setting_required">rc file setting required</a> * <a href="#rc_file_setting_required">rc file setting required</a>
* <a href="#Wildcard_repos">Wildcard repos</a> * <a href="#wildcard_repos">wildcard repos</a>
* <a href="#Wildcard_repos_with_creator_name_in_them">Wildcard repos with creator name in them</a> * <a href="#wildcard_repos_with_creator_name_in_them">wildcard repos with creator name in them</a>
* <a href="#Wildcard_repos_without_creator_name_in_them">Wildcard repos without creator name in them</a> * <a href="#wildcard_repos_without_creator_name_in_them">wildcard repos without creator name in them</a>
* <a href="#Side_note_Line_anchored_regexes">Side-note: Line-anchored regexes</a> * <a href="#side_note_line_anchored_regexes">side-note: line-anchored regexes</a>
* <a href="#Contrast_with_refexes">Contrast with refexes</a> * <a href="#contrast_with_refexes">contrast with refexes</a>
* <a href="#Handing_out_rights_to_wildcard_matched_repos">Handing out rights to wildcard-matched repos</a> * <a href="#handing_out_rights_to_wildcard_matched_repos">handing out rights to wildcard-matched repos</a>
* <a href="#setting_a_gitweb_description_for_a_wildcard_matched_repo">setting a gitweb description for a wildcard-matched repo</a> * <a href="#setting_a_gitweb_description_for_a_wildcard_matched_repo">setting a gitweb description for a wildcard-matched repo</a>
* <a href="#reporting">reporting</a> * <a href="#reporting">reporting</a>
* <a href="#other_issues_and_discussion">other issues and discussion</a> * <a href="#other_issues_and_discussion">other issues and discussion</a>
@ -45,17 +45,17 @@ This feature requires that you set `$GL_WILDREPOS` to "1" in `~/.gitolite.rc`
on the server. Please search for that variable and see comments around it in on the server. Please search for that variable and see comments around it in
`conf/example.gitolite.rc` for more information on this. `conf/example.gitolite.rc` for more information on this.
<a name="Wildcard_repos"></a> <a name="wildcard_repos"></a>
### Wildcard repos ### wildcard repos
Which of these alternatives you choose depends on your needs, and the social Which of these alternatives you choose depends on your needs, and the social
aspects of your environment. The first one is a little more rigid, making it aspects of your environment. The first one is a little more rigid, making it
harder to make mistakes, and the second is more flexible and trusting. harder to make mistakes, and the second is more flexible and trusting.
<a name="Wildcard_repos_with_creator_name_in_them"></a> <a name="wildcard_repos_with_creator_name_in_them"></a>
#### Wildcard repos with creator name in them #### wildcard repos with creator name in them
Here's an example snippet: Here's an example snippet:
@ -79,9 +79,9 @@ new repo, as user "u4" (a student):
Notice the *two* empty repo inits, and the order in which they occur ;-) Notice the *two* empty repo inits, and the order in which they occur ;-)
<a name="Wildcard_repos_without_creator_name_in_them"></a> <a name="wildcard_repos_without_creator_name_in_them"></a>
#### Wildcard repos without creator name in them #### wildcard repos without creator name in them
Here's how the same example would look if you did not want the CREATOR's name Here's how the same example would look if you did not want the CREATOR's name
to be part of the actual repo name. to be part of the actual repo name.
@ -106,9 +106,9 @@ and have a TA create the repos in advance.
In either case, they could then use the `setperms` feature to specify which In either case, they could then use the `setperms` feature to specify which
users are "READERS" and which are "WRITERS". See later for details. users are "READERS" and which are "WRITERS". See later for details.
<a name="Side_note_Line_anchored_regexes"></a> <a name="side_note_line_anchored_regexes"></a>
### Side-note: Line-anchored regexes ### side-note: line-anchored regexes
A regex like A regex like
@ -123,9 +123,9 @@ But you may be surprised to find that it does not match even
`^assignments/S[0-9]+/A[0-9]+$` -- notice the line beginning and ending `^assignments/S[0-9]+/A[0-9]+$` -- notice the line beginning and ending
metacharacters. metacharacters.
<a name="Contrast_with_refexes"></a> <a name="contrast_with_refexes"></a>
#### Contrast with refexes #### contrast with refexes
Just for interest, note that this is in contrast to the refexes for the normal Just for interest, note that this is in contrast to the refexes for the normal
"branch" permissions, as described in `conf/example.conf` and elsewhere. "branch" permissions, as described in `conf/example.conf` and elsewhere.
@ -135,9 +135,9 @@ if no one will actually push such a branch! You can anchor both sides if you
really care, by using `master$` instead of `master`, but that is *not* the really care, by using `master$` instead of `master`, but that is *not* the
default for refexes. default for refexes.
<a name="Handing_out_rights_to_wildcard_matched_repos"></a> <a name="handing_out_rights_to_wildcard_matched_repos"></a>
### Handing out rights to wildcard-matched repos ### handing out rights to wildcard-matched repos
In the examples above, we saw two special "user" names: READERS and WRITERS. In the examples above, we saw two special "user" names: READERS and WRITERS.
The permissions they have are controlled by the config file, but ***who is The permissions they have are controlled by the config file, but ***who is
@ -193,30 +193,10 @@ commands, thanks to Teemu.
### reporting ### reporting
Remember the cool stuff you see when you just do `ssh git@server` (grep for In order to see what repositories were created from a wildcard, use the
"myrights" in `doc/3-faq-tips-etc.mkd` if you forgot, or go [here][mr]). "expand" command, described briefly in [doc/report-output.mkd][repout].
[mr]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#myrights [repout]: http://github.com/sitaramc/gitolite/blob/pu/doc/report-output.mkd
This still works, except the format is a little more compressed to accommodate
a new column (at the start) for "C" permissions, which indicate that you are
allowed to *create* repos matching that pattern.
In addition, there is also the "expand" command, which takes any regex pattern
and returns you a list of all wildcard-created repos that you have access to
which fit that pattern. And if, as an administrator, you wish to list out
*every single* repo that your users have created, add this to your config
file:
repo @all
R = sitaram # or whoever you are
Push the config, then try
# if you installed using the "from-client" method
ssh gitolite expand
# for the other 3 install methods
ssh git@server expand
<a name="other_issues_and_discussion"></a> <a name="other_issues_and_discussion"></a>

21
doc/6-ssh-troubleshooting.mkd
View file

@ -184,14 +184,14 @@ Otherwise, run these checks:
you ran the easy install, or someone fiddled with the you ran the easy install, or someone fiddled with the
`~/.ssh/authorized_keys` file on the server. `~/.ssh/authorized_keys` file on the server.
If it prints [gitolite version and access info][myrights], you managed to If it prints the gitolite version and access info (see
overwrite the `id_rsa` keypair with the `sitaram` keypair, or something [doc/report-output.mkd][repout]), you managed to overwrite the `id_rsa`
equally weird. keypair with the `sitaram` keypair, or something equally weird.
2. `ssh gitolite info` should print some [gitolite version and access 2. `ssh gitolite info` should print some gitolite version and access info.
info][myrights]. If you get the output of the GNU info command instead, If you get the output of the GNU info command instead, you probably reused
you probably reused your `id_rsa` keypair as your `sitaram` keypair, or your `id_rsa` keypair as your `sitaram` keypair, or overwrote the
overwrote the `sitaram` keypair with the `id_rsa` keypair. `sitaram` keypair with the `id_rsa` keypair.
There are many ways to fix this, depending on where and what the damage is. There are many ways to fix this, depending on where and what the damage is.
The most generic way (and therefore time-taking) is to re-install gitolite The most generic way (and therefore time-taking) is to re-install gitolite
@ -229,10 +229,8 @@ which was previously sent to the gitolite admin to add into the admin repo's
`keydir` as "user.pub", and then "user" given permissions to some repo. `keydir` as "user.pub", and then "user" given permissions to some repo.
`ssh git@server info` should get you [gitolite version and access `ssh git@server info` should get you [gitolite version and access
info][myrights]. If it asks you for a password, your pubkey was not sent to info][repout]. If it asks you for a password, your pubkey was not sent to the
the server properly. Check with your admin. server properly. Check with your admin.
[myrights]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#myrights
If it gets you the GNU info command output, you have shell access. This means If it gets you the GNU info command output, you have shell access. This means
you had command line access to the server *before* you were added as a you had command line access to the server *before* you were added as a
@ -462,3 +460,4 @@ bigger problems than gitolite install not working!)]
[o3]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd#installation_and_setup [o3]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd#installation_and_setup
[fc]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd#from_client_method_install_from_the_client_to_the_server [fc]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd#from_client_method_install_from_the_client_to_the_server
[urls]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd#URLs_for_gitolite_managed_repos [urls]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd#URLs_for_gitolite_managed_repos
[repout]: http://github.com/sitaramc/gitolite/blob/pu/doc/report-output.mkd

56
doc/report-output.mkd
View file

@ -4,10 +4,13 @@ Running "ssh git@server info" or "ssh git@server expand" gives you certain
output. This doclet describes the output; you're welcome to help me make it output. This doclet describes the output; you're welcome to help me make it
clearer :) clearer :)
There are 3 columns of permissions (create, read, and write) in the output, (Side note: if you installed using the "from-client" method, and you're the
although the first column is often blank. administrator, please replace `ssh git@server` with `ssh gitolite`, all
through this document).
Here is the output of the 2 commands (info and expand): ----
<a name="the_info_command"></a>
### the "info" command ### the "info" command
@ -20,14 +23,57 @@ file that you have been given any kind of access to. If you supply an
optional pattern the output will be limited to repos matching that pattern. optional pattern the output will be limited to repos matching that pattern.
If you're an admin you can append a list of users to see their permissions If you're an admin you can append a list of users to see their permissions
instead of your own; in this mode the pattern is mandatory, even if you just instead of your own; in this mode the pattern is mandatory, even if you just
use `.` to cheat. (Side note: if you installed using easy-install that would use `.` to cheat.
probably be `ssh gitolite info`, by the way).
Here is a sample output of the info command. There are 3 columns of
permissions (create, read, and write) in the output, although the first column
is often blank.
$ ssh git@server info
hello sitaram, the gitolite version here is v1.5.4-19-ga3397d4
the gitolite config gives you the following access:
#R W SecureBrowse
#R W anu-wsd
#R W entrans
@R W git-notes
@R W gitolite
#R W gitolite-admin
#R W indic_web_input
@C #R private/CREATOR/[\w.-]+
#R W proxy
@C @R W public/CREATOR/[\w.-]+
@R @W testing
#R W vkc
The meaning of C, R, and W are self-explanatory, but they might sometimes be The meaning of C, R, and W are self-explanatory, but they might sometimes be
prefixed by a symbol. For example, `@R` means that `@all` users have prefixed by a symbol. For example, `@R` means that `@all` users have
been given this access, and `#R` means that this user is a "superuser" (think been given this access, and `#R` means that this user is a "superuser" (think
root's shell prompt) and so has access to `@all` repos. root's shell prompt) and so has access to `@all` repos.
Here are a couple of samples with optional patterns:
$ ssh git@server info git
hello sitaram, the gitolite version here is v1.5.4-19-ga3397d4
the gitolite config gives you the following access:
@R W git-notes
@R W gitolite
#R W gitolite-admin
$ ssh git@server info admin
hello sitaram, the gitolite version here is v1.5.4-19-ga3397d4
the gitolite config gives you the following access:
#R W gitolite-admin
In "big-config" mode (i.e., when `GL_BIG_CONFIG` is set) the pattern is
**mandatory**. You can try and cheat the system by passing in a "." but
gitolite truncates the output after 20 results to prevent a DOS.
The pattern is also mandatory when an admin wants to find out what access some
*other* user has, which you may have guessed from the syntax in the "usage"
line above.
<a name="the_expand_command"></a>
### the "expand" command ### the "expand" command
Usage: Usage: