From 5f3344025ce0abc4590f156d41aa93a71da1e12c Mon Sep 17 00:00:00 2001 From: Sitaram Chamarty Date: Fri, 24 Dec 2010 11:01:28 +0530 Subject: [PATCH] (minor) doc updates --- README.mkd | 4 ++-- conf/example.conf | 2 +- doc/3-faq-tips-etc.mkd | 1 - doc/big-config.mkd | 43 +++++++++++++++++++++++++++++++++++ doc/ssh-troubleshooting.mkd | 9 +++++--- doc/wildcard-repositories.mkd | 9 ++++++++ 6 files changed, 61 insertions(+), 7 deletions(-) diff --git a/README.mkd b/README.mkd index b93c28d..f3355a1 100644 --- a/README.mkd +++ b/README.mkd @@ -143,7 +143,7 @@ detail somewhere in gitolite's [doc/][docs] subdirectory. Most installation problems are caused by not knowing ssh. Take a look at this [transcript][] to see how simple it actually is, if your server's ssh daemon -is behaving itself. +is behaving itself. Someone also wrote a tutorial, see [here][tut]. If I suspect your problem is an ssh issue, I will probably ignore it. Please learn how [gitolite uses ssh][doc9gas] and then methodically go through the @@ -194,4 +194,4 @@ Gitolite is released under GPL v2. See COPYING for details. [doc9gas]: http://github.com/sitaramc/gitolite/blob/pu/doc/gitolite-and-ssh.mkd [doc6sts]: http://github.com/sitaramc/gitolite/blob/pu/doc/ssh-troubleshooting.mkd [who]: http://github.com/sitaramc/gitolite/blob/pu/doc/who-uses-it.mkd - +[tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial diff --git a/conf/example.conf b/conf/example.conf index 1c976e6..99ba483 100644 --- a/conf/example.conf +++ b/conf/example.conf @@ -155,7 +155,7 @@ repo git # ***IMPORTANT NOTES ABOUT "DENY" RULES***: -# - deny rules do NOT affect read access. They only apply to `W` and `+`. +# - deny rules do NOT affect read access. They only apply to write access. # # - when using deny rules, the order of your rules starts to matter, where # earlier it did not. The first matching rule applies, where "matching" is diff --git a/doc/3-faq-tips-etc.mkd b/doc/3-faq-tips-etc.mkd index 1f86bd6..588d40c 100644 --- a/doc/3-faq-tips-etc.mkd +++ b/doc/3-faq-tips-etc.mkd @@ -101,7 +101,6 @@ There *is* a way to use the `@all` syntax for repos also, as described in * don't use `NAME/` or such restrictions on the special `@all` repo. Due to the potential for defeating a crucial optimisation and slowing down *all* access, we do not support this. - * don't try giving `@all` users some permission for `@all` repos diff --git a/doc/big-config.mkd b/doc/big-config.mkd index 9bbe29b..440288b 100644 --- a/doc/big-config.mkd +++ b/doc/big-config.mkd @@ -11,6 +11,7 @@ In this document: * storing usergroup information outside gitolite (like in LDAP) * why * how + * implementation notes @@ -292,3 +293,45 @@ Then set the `$GL_GET_MEMBERSHIPS_PGM` variable in the rc file to the full path to this program, set `$GL_BIG_CONFIG` to 1, and that will be that. [gwd]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#gwd + + + +### implementation notes + +To understand how big-config works, we'll first look at how it works without +this setting. Think back to the example at the top, and assume 'alice' is +accessing the 'lynx' repo. The various rights are governed by the following +hash elements: + + # for the first level checks + $repos{'lynx'}{'R'}{'alice'} = 1 + $repos{'lynx'}{'W'}{'alice'} = 1 + + # for the second level checks + $repos{'lynx'}{'alice'}{'refs/heads/master'} = 'RW'; + $repos{'lynx'}{'alice'}{'refs/heads/next'} = 'RW+'; + +Those elements are explicitly specified in the compiled hash, as you can see +(you don't need to know perl too much to read a hash; just make some educated +guesses if needed!) + +Now look at the compiled hash produced when `GL_BIG_CONFIG` is set. In place +of both 'firefox' and 'lynx' you have '@wbr', and similarly '@devs' for both +'alice' and 'bob'. In addition, there is a group hash at the bottom that +lists each group and its members. + +When 'alice' tries to access the 'lynx' repo, gitolite collects all the group +names that these names belong to, so '@devs' is added to the list of 'user' +names that 'alice' inherits permissions from, and '@wbr' is added to the list +of 'repo' names that 'lynx' inherits from. This means that the final access +inherits all permissions pertaining to the following combinations: + + alice, lynx + alice, @wbr + @devs, lynx + @devs, @wbr + +(Actually there are 3 more... try and guess what they may be!) + +Anyway, all ACL rules for these combinations are clubbed together to make the +composite set of rules that 'alice' accessing 'lynx' is subject to. diff --git a/doc/ssh-troubleshooting.mkd b/doc/ssh-troubleshooting.mkd index 3fe7e64..6238cf9 100644 --- a/doc/ssh-troubleshooting.mkd +++ b/doc/ssh-troubleshooting.mkd @@ -39,6 +39,8 @@ Other resources: * people who think this is too hard should take a look at this [transcript][] to **see how simple it *actually* is**. + * someone also wrote a tutorial, see [here][tut]. + * I **strongly** recommend reading [doc/gitolite-and-ssh.mkd][doc9gas], which is a very detailed look at how gitolite uses ssh's features on the server side. Most people don't know ssh as well as they *think* they do; @@ -421,9 +423,9 @@ or gl-tool shell-add ~/foo.pub -The first method is to be used if you used the **user-install** mode, while -the second method is for the **system-install followed by user-setup** mode -(see doc/1-INSTALL.mkd, section on "install methods", for more on this) +The first method is applicable if you installed using the **from-client** +method, while the second method is for any of the other three (see +doc/1-INSTALL.mkd, section on "install methods", for more on this) **IMPORTANT UPGRADE NOTE**: previous implementations of this feature were crap. There was no easy/elegant way to ensure that someone who had repo admin @@ -474,3 +476,4 @@ bigger problems than gitolite install not working!)] [repout]: http://github.com/sitaramc/gitolite/blob/pu/doc/report-output.mkd [transcript]: http://github.com/sitaramc/gitolite/blob/pu/doc/install-transcript.mkd [openssh56]: http://www.openssh.org/txt/release-5.6 +[tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial diff --git a/doc/wildcard-repositories.mkd b/doc/wildcard-repositories.mkd index 4d73150..acd8905 100644 --- a/doc/wildcard-repositories.mkd +++ b/doc/wildcard-repositories.mkd @@ -264,6 +264,15 @@ commands, thanks to Teemu. In order to see what repositories were created from a wildcard, use the "expand" command, described briefly in [doc/report-output.mkd][repout]. +### deleting a wild repo + +See [repo deletion][rmr] for more on this. Note that this requires you to +install/setup "adc"s (admin defined commands). See +[doc/admin-defined-commands.mkd][adc] for how to do that. + +[adc]: http://github.com/sitaramc/gitolite/blob/pu/doc/admin-defined-commands.mkd +[rmr]: http://github.com/sitaramc/gitolite/blob/pu/contrib/adc/repo-deletion.README + ### how it actually works