next round of doc changes

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

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
 

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
+(using [this][NAME] gitolite feature) that a sub-admin can make changes only
-files) that a sub-admin can make changes only to her subconf file and nothing
+to her subconf file and nothing else.
-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]

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.  (<font
+    color="gray">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</font>).
 
   * but since they're coming through gl-auth, branch-level acls are in effect
 

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

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

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 :-)

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
 
 ----