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

minor docfixes

Browse source 
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
Show stats Download patch file Download diff file Expand all files Collapse all files

8
contrib/adc/README.mkd
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.
**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.

12
doc/2-admin.mkd
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
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:

4
doc/3-faq-tips-etc.mkd
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
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

38
doc/gitolite.conf-by-example.mkd
View file

@ -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/`
(<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).
@ -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" (<font color="gray">yes, it is possible to
confuse yourself by pushing a branch like that in git</font>).
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

22
doc/gitolite.conf.mkd
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`,
`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.

12
doc/gitolite.rc.mkd
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
@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

50
doc/report-output.mkd
View file

@ -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
<a name="_interpreting_the_output"></a>
@ -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

2
doc/ssh-troubleshooting.mkd
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
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

13
doc/wildcard-repositories.mkd
View file

@ -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*. <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
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.
<a name="_admin_adding_other_roles_than_READERS_and_WRITERS"></a>