From 877c6625dcd26b5e527c98f0a3dd66fac1781cab Mon Sep 17 00:00:00 2001 From: Sitaram Chamarty Date: Thu, 13 Oct 2011 17:34:02 +0530 Subject: [PATCH] minor docfixes typos, minor clarifications, removing outdated stuff that got missed, adding some emphasis here and there, re-phrasing some places, etc. --- contrib/adc/README.mkd | 8 +---- doc/2-admin.mkd | 12 ++++---- doc/3-faq-tips-etc.mkd | 4 +-- doc/gitolite.conf-by-example.mkd | 38 +++++++++++++----------- doc/gitolite.conf.mkd | 22 ++++---------- doc/gitolite.rc.mkd | 12 -------- doc/report-output.mkd | 50 ++++++++++++++++---------------- doc/ssh-troubleshooting.mkd | 2 +- doc/wildcard-repositories.mkd | 13 +++++++-- 9 files changed, 72 insertions(+), 89 deletions(-) diff --git a/contrib/adc/README.mkd b/contrib/adc/README.mkd index 9d40555..d4127da 100644 --- a/contrib/adc/README.mkd +++ b/contrib/adc/README.mkd @@ -25,7 +25,7 @@ this ADC are [here][dbsha]; details on RWC/RWD/RWCD etc are [here][rwcd]. sample of how to write an ADC in perl. **git-annex-shell**: allows git-annex to store and retrieve annexed file content in -repositories. To use, install in $GL_ADC_PATH/ua/git-annex-shell +repositories. To use, install in `$GL_ADC_PATH/ua/git-annex-shell` **gl-reflog**: show a fake "reflog" from the server, and allow recovery from deleted branches and bad force pushes; details in source. @@ -45,12 +45,6 @@ itself. This ADC displays site-local help, if the site admin enabled it. [rddoc]: http://sitaramc.github.com/gitolite/contrib/adc/repo-deletion.html -**restrict-admin**: sample program to show how you can allow the admin to run -pre-specified shell commands (without actually having full shell access). -Details [here][ra]. - -[ra]: http://sitaramc.github.com/gitolite/doc/admin-defined-commands.html#_bonus_restricted_admin - **sudo**: allow admin to run ADCs on behalf of a user. Useful in support situations I guess. Details in source. diff --git a/doc/2-admin.mkd b/doc/2-admin.mkd index 293bad9..ed3ff1c 100644 --- a/doc/2-admin.mkd +++ b/doc/2-admin.mkd @@ -413,19 +413,21 @@ permission to the special user "daemon". Similarly, give read permission to This gives you a quick way to offer multiple repos up for gitweb and/or daemon access. -However, setting a description for the project also enables gitweb permissions -so you can do it that way if you want. Of course in this case you have to -deal with each repo separately. Add lines like this to gitolite.conf: +However, **setting a description** for the project also enables gitweb +permissions so you can do it that way if you want. Of course in this case you +have to deal with each repo separately. Add lines like this to gitolite.conf: foo = "some description" bar = "some other description" baz = "yet another description" -You can also specify an owner for gitweb to show, if you like; for example I -might use: +You can also **specify an owner** for gitweb to show, if you like; for example +I might use: gitolite "Sitaram Chamarty" = "fast, secure, fine-grained, access control for git" +These lines are standalone, so you can add them anywhere in the conf file. + Note that gitolite does **not** install or configure gitweb/git-daemon -- that is a one-time setup you must do separately. All gitolite does is: diff --git a/doc/3-faq-tips-etc.mkd b/doc/3-faq-tips-etc.mkd index 9f1e98c..aaa310b 100644 --- a/doc/3-faq-tips-etc.mkd +++ b/doc/3-faq-tips-etc.mkd @@ -430,8 +430,8 @@ Although gitweb is a completely separate program, gitolite can do quite a lot to help you manage gitweb access as well; once the initial setup is complete, you can do it all from within the gitolite config file! -If you just want gitweb to show some repositories, see [gwd] for how to -specify which repos to show. Other advanced uses are described here. +If you just want gitweb to show some repositories, see [here][gwd] for how to +specify which repos to show. [gwd]: http://sitaramc.github.com/gitolite/doc/2-admin.html#gwd diff --git a/doc/gitolite.conf-by-example.mkd b/doc/gitolite.conf-by-example.mkd index b9f54d2..a3e52ea 100644 --- a/doc/gitolite.conf-by-example.mkd +++ b/doc/gitolite.conf-by-example.mkd @@ -63,12 +63,11 @@ end of the string respectively. ^foo$ matches exact string 'foo'. To be precise, the last one is "any string starting and ending with *the same* -'foo'". (Without the italicised phrase, it could mean "foofoo" would also -match, but it doesn't). +'foo'". "foofoo" does not match. -`[0-9]` is an example of a character class; this one matches any single digit. -`[a-z]` matches any lower case alpha. For example, `[0-9a-f]` is the range of -hex characters. You can guess what `[a-zA-Z0-9_]` does, then. +`[0-9]` is an example of a character class; it matches any single digit. +`[a-z]` matches any lower case alpha, and `[0-9a-f]` is the range of hex +characters. You should now guess what `[a-zA-Z0-9_]` does. `.` (the period) is special -- it matches any character. If you want to match an actual period, you need to say `\.`. @@ -107,11 +106,11 @@ branch or tag on it. Wally can only read the repo. Alice and Ashok can push but not rewind; only Sitaram and Dilbert can do that. - R master = wally # MEANINGLESS! WONT DO WHAT YOU THINK IT DOES!! + R master = wally # MEANINGLESS! WILL NOT DO WHAT YOU THINK IT DOES!! -This won't work. You can only restrict "read" access at the repo level not -the branch level. This is a git issue, not a gitolite issue. Go bother them, -or switch to gerrit. +This won't work. You can only restrict "read" access at the repo level, not +at the branch level. This is a git issue, not a gitolite issue. Go bother +them, or switch to gerrit. repo foo RW master$ = dilbert alice @@ -119,9 +118,10 @@ or switch to gerrit. RW refs/heads/master$ = dilbert alice The reason for treating "master$" as "refs/heads/master$" is that matching -branches is the most common use so we made it convenient to use. Anything -*not* starting with `refs/` (or `NAME/`, but that is out of scope of this -document), is implicitly prefixed with `refs/heads/`). +branches is the most common use so the syntax is optimised to make that +simpler to write and easier to read. Anything *not* starting with `refs/` +(or `NAME/`, but that is out of scope for this +document), is implicitly prefixed with `refs/heads/`. The `master$` is called a "refex" (a regex that matches a ref). @@ -129,9 +129,13 @@ Dilbert and Alice can push to the "master" branch. Unless some other rule allows it, they cannot push to, say, "master1", "masterfull" etc., due to the `$` at the end of the refex. -This rule does not match "headmaster"; refexes are treated as if they have a -`^` at the start. (This means `^refs/heads/master` in this case, not -`^master`, in case you forgot!) +Refexes are *prefix matched*; i.e., treated as if they have a `^` at the +start. (This means `^refs/heads/master` in this case, not `^master`, in case +you forgot!) + +This rule therefore does not match "headmaster", or even +"refs/heads/refs/heads/master" (yes, it is possible to +confuse yourself by pushing a branch like that in git). RW+ pu = dilbert # again, remember this is equivalent to: @@ -181,8 +185,8 @@ earlier. * for non-version tags, only the 3rd rule matches, so anyone on staff can push them - * for version tags by bruce, the first rule matches so he can push them - * for version tags by staffers *other than bruce*, the second rule matches + * for version tags by ashok, the first rule matches so he can push them + * for version tags by staffers *other than ashok*, the second rule matches before the third one, and it has a `-` as the permission, so the push fails diff --git a/doc/gitolite.conf.mkd b/doc/gitolite.conf.mkd index 4245d2e..2e4ca7b 100644 --- a/doc/gitolite.conf.mkd +++ b/doc/gitolite.conf.mkd @@ -306,9 +306,9 @@ We'll look at the delete/rewind case in detail first: * if, however, *any* of the rules for a repo contains a `D` (example: `RWD`, `RW+D`, etc) then `RW+` by itself will permit only a rewind, not a delete -The same thing applies to create/push, where if you have a permissions like -`RWC` or `RW+C` anywhere, a simple `RW` or `RW+` can no longer *create* a new -ref. +The same thing applies to create/push, where if you have permissions like +`RWC` or `RW+C` anywhere in that repo, a simple `RW` or `RW+` can no longer +*create* a new ref. You can combine the `C` and `D` also. Thus, the set of permissions you now know about are, in regex syntax: `R|RW+?C?D?`. See a later section for the @@ -596,17 +596,5 @@ later to override the generic settings. #### repo owner/description line for gitweb You can include owner/description information in the conf file, and gitolite -will put it in places where gitweb will pick it up. For example, suppose this -software (gitolite) itself was being hosted on a gitolite server and intended -to be shown on gitweb, I'd use a line like this: - - gitolite "Sitaram Chamarty" = "fast, secure, access control for git" - -The general syntax is very simple, just use one of: - - reponame = "some description string in double quotes" - reponame "owner name" = "some description string in double quotes" - -Note: setting a description also gives gitweb access; you do not have to give -gitweb access explicitly (as described or linked above) if you're specifying a -description. +will put it in places where gitweb will pick it up. See [here][gwd] for more +on this. diff --git a/doc/gitolite.rc.mkd b/doc/gitolite.rc.mkd index ef6f220..8c2f616 100644 --- a/doc/gitolite.rc.mkd +++ b/doc/gitolite.rc.mkd @@ -294,18 +294,6 @@ on feedback from my users to find or fix issues. does *not* include the special users "gitweb" and "daemon". If you want @all to include these two users, set this variable. - * mirroring setup - - These two variables enable mirroring support; see - [doc/mirroring.mkd][mirr] for details. The two variables are - `$GL_SLAVE_MODE`, (boolean, default undef), and `$ENV{GL_SLAVES}`, - (environment variable, string, default undef) - - Note on the second variable above: you must use single quotes to give it - its value, not double quotes, (like `$ENV{GL_SLAVES} = 'gitolite@server2 - gitolite@server3';`). Also note that this is an environment variable, not - a regular perl variable, so mind the syntax if you're not a perl guy :-) - * `$GL_WILDREPOS_PERM_CATS`, string, default "READERS WRITERS" Originally, we only allowed "R" and "RW" in the setperms command. Now we diff --git a/doc/report-output.mkd b/doc/report-output.mkd index 3872a18..7195573 100644 --- a/doc/report-output.mkd +++ b/doc/report-output.mkd @@ -33,21 +33,21 @@ 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.5-24-g2b066fc - 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 W private/sitaram/[\w.-]+ - R W proxy - @C @R W public/sitaram/[\w.-]+ - @R_ @W_ testing - R W vkc + $ ssh git@server info + hello sitaram, this is gitolite v2.1-29-g5a125fa running on git 1.7.4.4 + the gitolite config gives you the following access: + R 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 W private/sitaram/[\w.-]+ + R W proxy + @C @R W public/sitaram/[\w.-]+ + @R_ @W_ testing + R W vkc @@ -80,17 +80,17 @@ to one of the `@all` uses), but no explicit access. Here are a couple of samples with optional patterns: - $ ssh git@server info git - hello sitaram, the gitolite version here is v1.5.5-24-g2b066fc - the gitolite config gives you the following access: - @R W git-notes - @R W gitolite - R W gitolite-admin + $ ssh git@server info git + hello sitaram, this is gitolite v2.1-29-g5a125fa running on git 1.7.4.4 + 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.5-24-g2b066fc - the gitolite config gives you the following access: - R W gitolite-admin + $ ssh git@server info admin + hello sitaram, this is gitolite v2.1-29-g5a125fa running on git 1.7.4.4 + 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 diff --git a/doc/ssh-troubleshooting.mkd b/doc/ssh-troubleshooting.mkd index fc063f9..3373180 100644 --- a/doc/ssh-troubleshooting.mkd +++ b/doc/ssh-troubleshooting.mkd @@ -207,7 +207,7 @@ single key to allow both gitolite access *and* shell access. This is done by copying the pubkey (to which you want to give shell access) to the server and running - gl-tool shell-add ~/foo.pub + gl-tool add-shell-user ~/foo.pub **IMPORTANT UPGRADE NOTE**: previous implementations of this feature were crap. There was no easy/elegant way to ensure that someone who had repo admin diff --git a/doc/wildcard-repositories.mkd b/doc/wildcard-repositories.mkd index 52e33c0..2bb1c91 100644 --- a/doc/wildcard-repositories.mkd +++ b/doc/wildcard-repositories.mkd @@ -87,6 +87,11 @@ Here's an example snippet: RW = WRITERS @TAs R = READERS @prof +Note the "C" permission. This is a standalone "C", which gives the named +users the right to *create a repo*. This is not to be +confused with the "RWC" or its variants described elsewhere, which are about +*branches*, not *repos*. + For now, ignore the special usernames READERS and WRITERS, and just create a new repo, as user "u4" (a student): @@ -204,9 +209,11 @@ use 'getperms' to check: The following points are important: - * note the syntax of the commands; it's not a "git" command, and there's no - `:` like in a repo URL. The first space-separated word is READERS or - WRITERS, and the rest are simple usernames. + * note the syntax of the command; it's not a "git" command, and there's no + `:` like in a repo URL. + * for the actual text being sent in via STDIN, the first space-separated + word is the role (in this example, READERS or WRITERS), and the rest + are simple usernames.