From 29b2c2fdce33a09cc36be254a02f0626934f6503 Mon Sep 17 00:00:00 2001 From: Sitaram Chamarty Date: Mon, 9 Jan 2012 23:27:01 +0530 Subject: [PATCH] next round of doc changes --- Makefile | 2 -- doc/1000-words.mkd | 2 +- doc/delegation.mkd | 5 ++--- doc/developer-notes.mkd | 5 ++++- doc/gitolite.conf.mkd | 2 +- doc/gitolite.rc.mkd | 6 +++++- doc/hook-propagation.mkd | 29 +++++++++++++++++++++++++++++ doc/who-uses-it.mkd | 4 +++- 8 files changed, 45 insertions(+), 10 deletions(-) diff --git a/Makefile b/Makefile index 1108b82..230f6bc 100644 --- a/Makefile +++ b/Makefile @@ -4,8 +4,6 @@ # the "git describe" output for that refname to the tar. This lets you say # "cat .GITOLITE-VERSION" to find out which ref produced this tar -# Note: I'm not sure if that "-r" is a GNU tar extension... - branch := $(shell git rev-parse --abbrev-ref HEAD) $(branch): $(branch).tar diff --git a/doc/1000-words.mkd b/doc/1000-words.mkd index 9fec921..321cc2e 100644 --- a/doc/1000-words.mkd +++ b/doc/1000-words.mkd @@ -147,7 +147,7 @@ lines for whatever repo you want too add. 3. `git add conf/gitolite.conf`, then `git commit`, then `git push` You do NOT add the repos directly anywhere on the server; you do it by -cloning, adding keys, and pushing. +cloning, adding repo and access lines, and pushing. ## #flow gitolite flow diff --git a/doc/delegation.mkd b/doc/delegation.mkd index 243e247..e62c990 100644 --- a/doc/delegation.mkd +++ b/doc/delegation.mkd @@ -42,9 +42,8 @@ well as *any* repo inside the `browsers` subdirectory, as members of the Each of these groups is called a **subconf** from here on. Then you designate a **sub-admin** to manage each subconf, and you ensure -(using the standard gitolite feature of restricting pushes by names of changed -files) that a sub-admin can make changes only to her subconf file and nothing -else. +(using [this][NAME] gitolite feature) that a sub-admin can make changes only +to her subconf file and nothing else. For example, Alice is in charge of all web browser development projects. Similarly, Bob takes care of web servers, and Mallory, as [tradition][abe] diff --git a/doc/developer-notes.mkd b/doc/developer-notes.mkd index 54c9665..29ae96f 100644 --- a/doc/developer-notes.mkd +++ b/doc/developer-notes.mkd @@ -79,7 +79,10 @@ Fedora has a very special setup, as follows: they want to * actual git repos are under "git" (or some such), and include the chmod g+s - (git init --shared) unix perms tricks for shared access + (git init --shared) unix perms tricks for shared access. (Starting with git 1.7.something, you would also need to + explicitly delete the new receive.denyNonFastForwards setting that git + seems to default to when you use --shared). * but since they're coming through gl-auth, branch-level acls are in effect diff --git a/doc/gitolite.conf.mkd b/doc/gitolite.conf.mkd index c46b2f2..eaefde9 100644 --- a/doc/gitolite.conf.mkd +++ b/doc/gitolite.conf.mkd @@ -290,7 +290,7 @@ allowing the secret branches into it). The previous section is sufficient for most common needs, but gitolite can go a lot further than that. -### restricting pushes by dir/file name using NAME/ +### #NAME restricting pushes by dir/file name using NAME/ Here's a hopefully self-explanatory example. Assume the project has the following contents at the top level: a README, a "doc/" directory, and an diff --git a/doc/gitolite.rc.mkd b/doc/gitolite.rc.mkd index 26da3a7..2395af4 100644 --- a/doc/gitolite.rc.mkd +++ b/doc/gitolite.rc.mkd @@ -312,7 +312,9 @@ on feedback from my users to find or fix issues. The default produces files like `~/.gitolite/logs/gitolite-2009-09.log`. If you make up your own templates, **PLEASE MAKE SURE** the directory exists and is writable; gitolite won't do that for you unless it is the - default, ("$GL_ADMINDIR/logs") + default, ("$GL_ADMINDIR/logs"). + + Note that `%d` is also available if you want. * `$GL_PERFLOGT`, string, default undef @@ -321,6 +323,8 @@ on feedback from my users to find or fix issues. kept separate from access log files because they store different, usually much shorter term, information. + See the previous variable (`GL_LOGT`) for template related info. + * `$GL_SITE_INFO`, string, default undef Some installations would like to give their users customised information diff --git a/doc/hook-propagation.mkd b/doc/hook-propagation.mkd index 0b89539..3e261c4 100644 --- a/doc/hook-propagation.mkd +++ b/doc/hook-propagation.mkd @@ -132,3 +132,32 @@ By default, the only reason you need to touch the "system" location is if you want to modify the 'update' hook, but why would you fiddle with the most important part of gitolite, huh? You're a good admin, and will use [hook chaining][hookchaining] properly, right? + +## why not just push a hook? + +A question I often get is, why can't we simply push the hooks using the admin +repo, just like we push config changes. + +To understand why, realise that in many sites, the "right to push the +gitolite-admin repo" is **not** the same as "right to get a command line on +the server and run arbitrary commands". + +This means, gitolite tries its best to keep these two rights separated, and to +prevent someone who has the former right from trivially acquiring the latter. + +And so we don't allow adding hooks by admin push. + +That doesn't mean you can't do it yourself. Here's one possible way. + +Using the simple instructions [here][customhooks], add a +`post-update.secondary` hook containing this code: + + #!/bin/bash + cp $GL_ADMINDIR/local-hooks/* $GL_ADMINDIR/hooks/common + gl-setup + +Now create a directory in your gitolite-admin clone called "local-hooks", put +all your hooks there, and add/commit/push. + +That *should* do it. Test it and send me a patch for this document when you +do :-) diff --git a/doc/who-uses-it.mkd b/doc/who-uses-it.mkd index b719c0a..59e15fb 100644 --- a/doc/who-uses-it.mkd +++ b/doc/who-uses-it.mkd @@ -59,7 +59,8 @@ specific code (see [contrib/ldap][ldap] directory for details). **kernel.org**, the official distribution point for the Linux kernel, is the latest (as of 2011-10) high-visibility installation. According to [this email][ko-ann] to the lkml, kernel.org decided to use gitolite for access -controlling their git repos. +controlling their git repos. Their [FAQ entry][ko-why] describes at a high +level why they chose gitolite. This move also prompted the first ever security audit of gitolite by an outside party. Gitolite did great; see [here][audit] for details. @@ -69,6 +70,7 @@ edges in gitolite, and smoothing them out was fun (the "playing with gitolite" stuff, making the test suite simpler, "deny" rules for the entire repo). [ko-ann]: http://lkml.org/lkml/2011/9/23/357 +[ko-why]: http://www.kernel.org/faq/#whygitolite [audit]: http://groups.google.com/group/gitolite/browse_thread/thread/8dc5242052b16d0f ----