minor docfixes

typos, minor clarifications, removing outdated stuff that got missed,
adding some emphasis here and there, re-phrasing some places, etc.
This commit is contained in:
Sitaram Chamarty 2011-10-13 17:34:02 +05:30
parent 200db6e486
commit 877c6625dc
9 changed files with 72 additions and 89 deletions

View file

@ -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. sample of how to write an ADC in perl.
**git-annex-shell**: allows git-annex to store and retrieve annexed file content in **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 **gl-reflog**: show a fake "reflog" from the server, and allow recovery from
deleted branches and bad force pushes; details in source. 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 [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 **sudo**: allow admin to run ADCs on behalf of a user. Useful in support
situations I guess. Details in source. situations I guess. Details in source.

View file

@ -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 This gives you a quick way to offer multiple repos up for gitweb and/or daemon
access. access.
However, setting a description for the project also enables gitweb permissions However, **setting a description** for the project also enables gitweb
so you can do it that way if you want. Of course in this case you have to permissions so you can do it that way if you want. Of course in this case you
deal with each repo separately. Add lines like this to gitolite.conf: have to deal with each repo separately. Add lines like this to gitolite.conf:
foo = "some description" foo = "some description"
bar = "some other description" bar = "some other description"
baz = "yet another description" baz = "yet another description"
You can also specify an owner for gitweb to show, if you like; for example I You can also **specify an owner** for gitweb to show, if you like; for example
might use: I might use:
gitolite "Sitaram Chamarty" = "fast, secure, fine-grained, access control for git" 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 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: is a one-time setup you must do separately. All gitolite does is:

View file

@ -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 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! 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 If you just want gitweb to show some repositories, see [here][gwd] for how to
specify which repos to show. Other advanced uses are described here. specify which repos to show.
[gwd]: http://sitaramc.github.com/gitolite/doc/2-admin.html#gwd [gwd]: http://sitaramc.github.com/gitolite/doc/2-admin.html#gwd

View file

@ -63,12 +63,11 @@ end of the string respectively.
^foo$ matches exact string 'foo'. ^foo$ matches exact string 'foo'.
To be precise, the last one is "any string starting and ending with *the same* 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 'foo'". "foofoo" does not match.
match, but it doesn't).
`[0-9]` is an example of a character class; this one matches any single digit. `[0-9]` is an example of a character class; it matches any single digit.
`[a-z]` matches any lower case alpha. For example, `[0-9a-f]` is the range of `[a-z]` matches any lower case alpha, and `[0-9a-f]` is the range of hex
hex characters. You can guess what `[a-zA-Z0-9_]` does, then. characters. You should now guess what `[a-zA-Z0-9_]` does.
`.` (the period) is special -- it matches any character. If you want to match `.` (the period) is special -- it matches any character. If you want to match
an actual period, you need to say `\.`. 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 Wally can only read the repo. Alice and Ashok can push but not rewind; only
Sitaram and Dilbert can do that. 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 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, at the branch level. This is a git issue, not a gitolite issue. Go bother
or switch to gerrit. them, or switch to gerrit.
repo foo repo foo
RW master$ = dilbert alice RW master$ = dilbert alice
@ -119,9 +118,10 @@ or switch to gerrit.
RW refs/heads/master$ = dilbert alice RW refs/heads/master$ = dilbert alice
The reason for treating "master$" as "refs/heads/master$" is that matching 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 branches is the most common use so the syntax is optimised to make that
*not* starting with `refs/` (or `NAME/`, but that is out of scope of this simpler to write and easier to read. Anything *not* starting with `refs/`
document), is implicitly prefixed with `refs/heads/`). (<font color="gray">or `NAME/`, but that is out of scope for this
document</font>), is implicitly prefixed with `refs/heads/`.
The `master$` is called a "refex" (a regex that matches a ref). 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 allows it, they cannot push to, say, "master1", "masterfull" etc., due to the
`$` at the end of the refex. `$` at the end of the refex.
This rule does not match "headmaster"; refexes are treated as if they have a Refexes are *prefix matched*; i.e., treated as if they have a `^` at the
`^` at the start. (This means `^refs/heads/master` in this case, not start. (This means `^refs/heads/master` in this case, not `^master`, in case
`^master`, in case you forgot!) you forgot!)
This rule therefore does not match "headmaster", or even
"refs/heads/refs/heads/master" (<font color="gray">yes, it is possible to
confuse yourself by pushing a branch like that in git</font>).
RW+ pu = dilbert RW+ pu = dilbert
# again, remember this is equivalent to: # 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 * for non-version tags, only the 3rd rule matches, so anyone on staff can
push them push them
* for version tags by bruce, the first rule matches so he can push them * for version tags by ashok, 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 staffers *other than ashok*, the second rule matches
before the third one, and it has a `-` as the permission, so the push before the third one, and it has a `-` as the permission, so the push
fails fails

View file

@ -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`, * 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 `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 The same thing applies to create/push, where if you have permissions like
`RWC` or `RW+C` anywhere, a simple `RW` or `RW+` can no longer *create* a new `RWC` or `RW+C` anywhere in that repo, a simple `RW` or `RW+` can no longer
ref. *create* a new ref.
You can combine the `C` and `D` also. Thus, the set of permissions you now 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 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 #### repo owner/description line for gitweb
You can include owner/description information in the conf file, and gitolite 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 will put it in places where gitweb will pick it up. See [here][gwd] for more
software (gitolite) itself was being hosted on a gitolite server and intended on this.
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.

View file

@ -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 does *not* include the special users "gitweb" and "daemon". If you want
@all to include these two users, set this variable. @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" * `$GL_WILDREPOS_PERM_CATS`, string, default "READERS WRITERS"
Originally, we only allowed "R" and "RW" in the setperms command. Now we Originally, we only allowed "R" and "RW" in the setperms command. Now we

View file

@ -34,9 +34,9 @@ permissions (create, read, and write) in the output, although the first column
is often blank. is often blank.
$ ssh git@server info $ ssh git@server info
hello sitaram, the gitolite version here is v1.5.5-24-g2b066fc hello sitaram, this is gitolite v2.1-29-g5a125fa running on git 1.7.4.4
the gitolite config gives you the following access: the gitolite config gives you the following access:
R W SecureBrowse R SecureBrowse
R W anu-wsd R W anu-wsd
R W entrans R W entrans
@R W git-notes @R W git-notes
@ -81,14 +81,14 @@ to one of the `@all` uses), but no explicit access.
Here are a couple of samples with optional patterns: Here are a couple of samples with optional patterns:
$ ssh git@server info git $ ssh git@server info git
hello sitaram, the gitolite version here is v1.5.5-24-g2b066fc hello sitaram, this is gitolite v2.1-29-g5a125fa running on git 1.7.4.4
the gitolite config gives you the following access: the gitolite config gives you the following access:
@R W git-notes @R W git-notes
@R W gitolite @R W gitolite
R W gitolite-admin R W gitolite-admin
$ ssh git@server info admin $ ssh git@server info admin
hello sitaram, the gitolite version here is v1.5.5-24-g2b066fc hello sitaram, this is gitolite v2.1-29-g5a125fa running on git 1.7.4.4
the gitolite config gives you the following access: the gitolite config gives you the following access:
R W gitolite-admin R W gitolite-admin

View file

@ -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 This is done by copying the pubkey (to which you want to give shell access) to
the server and running 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 **IMPORTANT UPGRADE NOTE**: previous implementations of this feature were
crap. There was no easy/elegant way to ensure that someone who had repo admin crap. There was no easy/elegant way to ensure that someone who had repo admin

View file

@ -87,6 +87,11 @@ Here's an example snippet:
RW = WRITERS @TAs RW = WRITERS @TAs
R = READERS @prof R = READERS @prof
Note the "C" permission. This is a standalone "C", which gives the named
users the right to *create a repo*. <font color="gray">This is not to be
confused with the "RWC" or its variants described elsewhere, which are about
*branches*, not *repos*.</font>
For now, ignore the special usernames READERS and WRITERS, and just create a For now, ignore the special usernames READERS and WRITERS, and just create a
new repo, as user "u4" (a student): new repo, as user "u4" (a student):
@ -204,9 +209,11 @@ use 'getperms' to check:
The following points are important: The following points are important:
* note the syntax of the commands; it's not a "git" command, and there's no * note the syntax of the command; it's not a "git" command, and there's no
`:` like in a repo URL. The first space-separated word is READERS or `:` like in a repo URL.
WRITERS, and the rest are simple usernames. * 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.
<a name="_admin_adding_other_roles_than_READERS_and_WRITERS"></a> <a name="_admin_adding_other_roles_than_READERS_and_WRITERS"></a>