doc/src: major doc/help text revampv0.80

also removed some dead code from compile (pre PTA days)

11 files changed, 82 insertions, 348 deletions

diff --git a/README.mkd b/README.mkd
index 81075cb..660e8f2 100644
--- a/README.mkd
+++ b/README.mkd
@@ -1,10 +1,8 @@
 # gitolite
 
->   [IMPORTANT: There is now an "upgrade" document in the "doc" directory;
->   please read if upgrading gitolite]
-
->   [Update 2009-10-10: apart from all the nifty new features, there's now an
->   "easy install" script in the src directory.  Please see the INSTALL
+>   [Update 2009-10-28: apart from all the nifty new features, there's now an
+>   "easy install" script in the src directory.  This script can be used to
+>   install as well as upgrade a gitolite install.  Please see the INSTALL
 >   document in the doc directory for details]
 
 ----
@@ -64,8 +62,10 @@ deleting a branch (which is really just an extreme form of rewind).  I needed
 something in between allowing anyone to do it (the default) and disabling it
 completely (`receive.denyNonFastForwards` or `receive.denyDeletes`).
 
-Here're **some more features**.  All of them are documented in detail
-somewhere in the `doc/` subdirectory.
+Here're **some more features**.  All of them, and more, are documented in
+detail [here][gsdiff].
+
+[gsdiff]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#diff
 
   * simpler, yet far more powerful, config file syntax, including specifying
     gitweb/daemon access.  You'll need this power if you manage lots of
@@ -73,6 +73,8 @@ somewhere in the `doc/` subdirectory.
   * config file syntax gets checked upfront, and much more thoroughly
   * if your requirements are still too complex, you can split up the config
     file and delegate authority over parts of it
+  * easier to specify gitweb/daemon access, and easier to link gitweb
+    authorisation with gitolite
   * more comprehensive logging [aka: management does not think "blame" is just
     a synonym for "annotate" :-)]
   * "personal namespace" prefix for each dev
@@ -85,8 +87,8 @@ somewhere in the `doc/` subdirectory.
 Due to the environment in which this was created and the need it fills, I
 consider this a "security" program, albeit a very modest one.  The code is
 very small and easily reviewable -- the 2 programs that actually control
-access when a user logs in total about 200 lines of code (about
-80 lines according to "sloccount").
+access when a user logs in total about 220 lines of code (about 90 lines
+according to "sloccount").
 
 For the first person to find a security hole in it, defined as allowing a
 normal user (not the gitolite admin) to read a repo, or write/rewind a ref,
diff --git a/conf/example.gitolite.rc b/conf/example.gitolite.rc
index 16bab4d..4cda90b 100644
--- a/conf/example.gitolite.rc
+++ b/conf/example.gitolite.rc
@@ -57,12 +57,7 @@ $GL_LOGT="$GL_ADMINDIR/logs/gitolite-%y-%m.log";
 
 # --------------------------------------
 
-# Please DO NOT change the following paths unless you really know what you're
-# doing.  It'll work for now but it's officially deprecated to have them
-# elsewhere from now on, and may break some future features.
-
-# Anyway, the conf files and keydirs don't grow constantly, (like the logs and
-# the repositories do), so I don't think this is a major problem for anyone.
+# Please DO NOT change these three paths
 
 $GL_CONF="$GL_ADMINDIR/conf/gitolite.conf";
 $GL_KEYDIR="$GL_ADMINDIR/keydir";
diff --git a/doc/0-INSTALL.mkd b/doc/0-INSTALL.mkd
index e6bfff5..c25a69e 100644
--- a/doc/0-INSTALL.mkd
+++ b/doc/0-INSTALL.mkd
@@ -1,9 +1,12 @@
 # installing gitolite
 
 This document tells you how to install gitolite.  After the install is done,
-you may want to see the "admin" document for adding users, repos, etc.
+you may want to see the [admin document][admin] for adding users, repos, etc.
 
-There's an easy install script for Linux, and for other Unixes there's a
+[admin]: http://github.com/sitaramc/gitolite/blob/pu/doc/2-admin.mkd
+
+There's an easy install script that requires bash (**strongly** recommended),
+but if you have no bash or you're on one of the legacy Unixes there's a
 slightly more manual process.  Both are explained here.
 
 In this document:
@@ -25,12 +28,12 @@ case.  **This script is meant to be run on your workstation, not on the
 server!**  It will take care of all the server side work, *and* get you
 "push-to-admin" too :-)  In short, it does **everything**!
 
-Assumptions:
+Assumptions/pre-requisites:
 
   * you have a server to host gitolite
   * git is installed on that server (and so is perl)
   * you have a userid on that server
-  * you have ssh-pubkey (password-less) login to that userid
+  * you have ssh-pubkey (**password-less**) login to that userid
       * (if you have only password access, run `ssh-keygen -t rsa` to create a
         new keypair if needed, then run `ssh-copy-id user@host`)
   * you have a clone or an archive of gitolite somewhere on your workstation
@@ -64,26 +67,24 @@ actually doing, I suggest you skip the `-q`.
 
 #### disadvantages
 
-  * has been tested only with Linux
+  * need a recent bash
 
 ### manual install
 
-If for some reason you cannot use the easy-install method, (for example,
-you're on a non-Linux machine), it's not very complicated.  Just open the file
-`src/00-easy-install.sh` in a nice, syntax coloring, text editor, and follow
-the instructions marked "MANUAL" :-)
+If you don't have bash, it's not very complicated to do it manually.  Just
+open the file `src/00-easy-install.sh` in a nice, syntax coloring, text
+editor, and follow the instructions marked "MANUAL" :-)
 
 ### other notes
 
-  * If you edit `~/.gitolite.rc` and change any paths, be sure to keep the
-    perl syntax -- you *don't* have to know perl to do so, it's fairly easy to
-    guess in this limited case
-
-  * the config file is (by default) at `~/.gitolite/conf/gitolite.conf`,
-    though you can change its location in the "rc" file.  Edit the file as you
-    wish.  The comments in the example file (`conf/example.conf`) ought to be
-    clear enough but let me know if not
+  * if you run `src/00-easy-install.sh` without the `-q` option, you will be
+    given a chance to edit `~/.gitolite.rc`.  You can change any options (such
+    as paths, for instance), but be sure to keep the perl syntax -- you
+    *don't* have to know perl to do so, it's fairly easy to guess in this
+    limited case.
 
 ### next steps
 
-See the "admin" document for how to add users, etc.
+The last message produced by the easy install script should tell you how to
+add users, repos, etc., and you will find more details in the [admin][admin]
+document.
diff --git a/doc/0-UPGRADE.mkd b/doc/0-UPGRADE.mkd
deleted file mode 100644
index 5e242f6..0000000
--- a/doc/0-UPGRADE.mkd
+++ /dev/null
@@ -1,107 +0,0 @@
-# upgrading gitolite atomically
-
-Upgrading is done **manually, on the server** (except the last step, which is
-on your admin repo clone), even if you installed it using the easy install
-script on the client.  First, it's not as difficult as an install so you don't
-really need a script.  Second, you may have customised the "rc" file
-(`~/.gitolite.rc` on the server) and I'm reluctant to mess with that in an
-automated way.
-
-### general upgrade notes
-
-If you follow the steps below, you can make the upgrade "atomic", so you don't
-have to do it at a "quiet" time or something.
-
-1.  copy a tar file containing the new version to the server, untar it to some
-    temp directory and `cd` to it
-
-2.  *prepare* the new version of `~/.gitolite.rc`.  It **must** have **all**
-    the variables defined in `conf/example.gitolite.rc` (the "new" rc file),
-    because the new versions of the programs will be depending on seeing these
-    variables.
-
-    However, it must also retain any customisations you made to the **old**
-    variables.
-
-    So this is what you do:
-
-      * make a copy of `conf/example.gitolite.rc` as `~/glrc.new`
-      * if your current `~/.gitolite.rc` had any customisations (where you
-        changed the defaults in some way), edit `~/glrc.new` and make those
-        same changes there
-
-3.  upgrade the rc file first
-
-        cp ~/glrc.new ~/.gitolite.rc
-
-4.  upgrade the software
-
-        src/install.pl
-
-5.  compile the config once again, in case the *internal* format of the
-    compiled config file (`$GL_CONF_COMPILED`) has changed.
-
-    To do this, you have to do a "git push" on the client side.  That might
-    require a dummy change (maybe add a blank line somewhere) because
-    otherwise the push will not happen.
-
-And you're done.
-
-### upgrade notes for specific versions
-
-If any extra steps beyond the generic ones above are needed, they will be
-listed here, newest first.
-
-#### upgrading from 410c9ba
-
-Between 410c9ba and this version, gitolite managed to make "push to admin" the
-default for new installs, but in a much more painless way.  If you're
-upgrading, you're not forced to use "push to admin", but I'd suggest you:
-
-  * make sure you have password-less (pubkey) login to a command line on your
-    server
-  * save your `~/.gitolite.rc`, `keydir/*.pub` and your `conf/gitolite.conf`
-    files from the server, bring them to your workstation
-  * then run `src/00-easy-install.sh` on the workstation, as if it were a
-    fresh install
-      * when the editor pops up to edit the rc file, delete all the lines in
-        it and copy them from the saved `~/.gitolite.rc`
-      * at the end of the script, after the gitolite-admin repo has been
-        cloned successfully, copy the saved `conf/gitolite.conf` and
-        `keydir/*.pub` to the clone, then add, commit, and push
-
-Gitolite also learnt to delegate parts of the config to other users.  See
-`doc/5-delegation.mkd` for details.
-
-#### upgrading from 8217ef9
-
-Between 8217ef9 and this version, gitolite learnt to handle gitweb/daemon
-access.  As a result, the rc file acquired a new variable, `$PROJECTS_LIST`,
-which you have to set to whatever your gitweb installation requires.
-
-#### upgrading from 86faae4
-
-Between 86faae4 and this version, gitolite had a *major* change in the
-*internal* format of the compiled config file.  Please do not omit step 5 in
-the generic instructions above.
-
-#### upgrading from 5758f69
-
-Between 5758f69 and this version, gitolite learnt to allow "groupnames" for
-repos as well.  The `conf/example.conf` has been recommented to explain the
-syntax but it's really a no-brainer: what you could previously do only for
-usernames, you can now do for reponames also.
-
-#### upgrading from abb4580
-
-Two new features (personal branches, and customisable logfile names/locations)
-have been added between abb4580 and this version.
-
-  * if you want to enable the personal branches feature, choose one of the
-    alternative values given for `$PERSONAL` or change it to something you
-    like; by default it is empty, which disables the feature
-
-  * if you want the log files named or grouped differently, choose one of the
-    alternative values for `$GL_LOGT`.  **Note** that if you choose to put
-    them in some other directory than the default, you **must** create that
-    directory (`mkdir`) yourself; gitolite will not do that for you
diff --git a/doc/1-migrate.mkd b/doc/1-migrate.mkd
index fb0491f..aba1002 100644
--- a/doc/1-migrate.mkd
+++ b/doc/1-migrate.mkd
@@ -36,8 +36,11 @@ Here's how we migrated my work repos:
 
 Now, log off the server and get back to the client:
 
-1.  follow instructions to install gitolite; see install document.  Make sure
-    that you **don't** change the default path for `$REPO_BASE`!
+[inst]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd
+
+1.  follow instructions to install gitolite; see the [install document][inst].
+    Make sure that you **don't** change the default path for `$REPO_BASE` if
+    you edit the config file!
 
 2.  **convert** your gitosis config file.  Substitute the path for your
     gitosis-admin clone in `$GSAC` below, and similarly the path for your
@@ -51,10 +54,11 @@ Now, log off the server and get back to the client:
 
         cp $GSAC/keydir/* $GLAC/keydir
 
-4.  **Important: expand any multi-key files you may have**.  See the "faq,
-    tips, etc" document in the doc directory for an explanation of what
-    multi-keys are, how gitosis does them and how gitolite does it
-    differently.
+4.  **Important: expand any multi-key files you may have**.  [Here][mk]'s an
+    explanation of what multi-keys are, how gitosis does them and how gitolite
+    does it differently.
+
+[mk]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#multikeys
 
     You can split the keys manually, or use the following code (just
     copy-paste it into your xterm after "cd"-ing to your gitolite-admin repo
diff --git a/doc/2-admin.mkd b/doc/2-admin.mkd
index 133455a..ed1d361 100644
--- a/doc/2-admin.mkd
+++ b/doc/2-admin.mkd
@@ -14,9 +14,9 @@ Please read on to see how to do this correctly.
 #### adding users and repos
 
   * ask each user who will get access to send you a public key.  See other
-    sources (for example
-    [here](http://sitaramc.github.com/0-installing/2-access-gitolite.html#generating_a_public_key))
-    for how to do this
+    sources (for example [here][genpub]) for how to do this
+
+[genpub]: http://sitaramc.github.com/0-installing/2-access-gitolite.html#generating_a_public_key
 
   * rename each public key according to the user's name, with a `.pub`
     extension, like `sitaram.pub` or `john-smith.pub`.  You can also use
@@ -40,8 +40,11 @@ so here goes.
 
 There's **no special syntax** for this -- just give read permission to a user
 called `gitweb` or `daemon`!  (This also means you can't have a normal user
-with either of those two names, but I doubt that's a problem!).  See the "faq,
-tips, etc" document for easy ways to specify access for multiple repositories.
+with either of those two names, but I doubt that's a problem!).  See the [faq,
+tips, etc][ss] document for easy ways to specify access for multiple
+repositories.
+
+[ss]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#gwd
 
 Note that this does **not** install or configure gitweb/daemon -- that is a
 one-time setup you must do separately.  All this does is:
diff --git a/doc/3-faq-tips-etc.mkd b/doc/3-faq-tips-etc.mkd
index 0dc851a..64997b1 100644
--- a/doc/3-faq-tips-etc.mkd
+++ b/doc/3-faq-tips-etc.mkd
@@ -101,6 +101,8 @@ Apart from the big ones listed in the top level README, and subjective ones
 like "better config file format", there are some small, but significant and
 concrete, differences from gitosis.
 
+<a name="simpler_syntax"></a>
+
 #### simpler syntax
 
 The basic syntax is simpler and cleaner but it goes beyond that: **you can
@@ -192,6 +194,8 @@ access control for their own pieces.  See
 [doc/5-delegation.mkd](http://github.com/sitaramc/gitolite/blob/pu/doc/5-delegation.mkd)
 for details.
 
+<a name="gwd"></a>
+
 #### easier to specify gitweb/daemon access
 
 Which of your repos should be accessible via plain HTTP or the `git://`
@@ -308,6 +312,8 @@ The other parts of the log line are the name of the repo, the refname being
 updated, the user updating it, and the refex pattern (from the config file)
 that matched, in case you need to debug the config file itself.
 
+<a name="multikeys"></a>
+
 #### one user, many keys
 
 I have a laptop and a desktop I need to access the server from.  I have
diff --git a/doc/4-push-to-admin.mkd b/doc/4-push-to-admin.mkd
deleted file mode 100644
index 7e5fc77..0000000
--- a/doc/4-push-to-admin.mkd
+++ /dev/null
@@ -1,105 +0,0 @@
-# "push to admin" in gitolite
-
-**WARNING: THIS DOCUMENT IS OBSOLETE.  DO NOT USE.  IT IS RETAINED ONLY FOR
-HISTORICAL PURPOSES**.  Gitolite now does "push-to-admin" by default, and does
-it very easily and simply by front-loading the ssh problem.  See the install
-doc for details.
-
-----
-
-Gitosis's default mode of admin is by cloning and pushing the `gitosis-admin`
-repo.  I call this "push to admin".  It's a very cool/cute feature, and I
-loved it at first.
-
-But it's a ***support nightmare***.  Half the gitosis angst on `#git` is
-because of this feature.  Gitolite does not use or endorse this method for
-people new to git, or ssh or (worse) both.
-
-However, ***if*** you know git and ssh really, *really*, well and you know
-what you're doing, this is a pretty nice thing to have -- does make life
-easier, I admit.  So, here is how to make PTA (hey nice acronym, just missing
-an "I") work on gitolite as well.
-
-Note:
-
-  * unlike the rest of gitolite, I can't help you with this unless you
-    convince me very quickly it's not a layer 8 problem :-)
-
-  * here's a test to see if you should use this feature: after reading this
-    document, think about how you would switch back and forth between the
-    normal method and push-to-admin.  If you can't immediately see what you
-    would need to do, please don't use it :-)
-
-The instructions are presented as shell commands; they should be fairly
-obvious.  All paths are from the default `~/.gitolite.rc`; if you changed any,
-make the same changes below.
-
-----
-
->   **WARNING**: the "compilation" runs via a `post-update` hook.  Which, by
->   definition, runs *after* the push has successfully completed.  As a
->   result, a *compilation error* will be visible to the admin doing the `git
->   push` but will not otherwise look like an error to client-side git (in
->   terms of return codes, scripting, etc., or even the "git gui" if you
->   happen to use that for pushing).  So be sure to watch out for compile
->   error messages on push when you do this.
-
-----
-
-#### server side setup
-
-1.  First, on the server, log on to the `git` userid, add a new repo called
-    `gitolite-admin` to the config file, give yourself `RW` or `RW+` rights to it,
-    and "compile":
-
-        cd ~/.gitolite
-        vim conf/gitolite.conf      # add gitolite-admin repo, etc
-        src/gl-compile-conf
-
-2.  Now, if you look at the "compile" script, it has an *automatic* local commit
-    inside, just for safety, which kicks in every time you compile.  This only
-    works if it finds a ".git" directory, and it was designed as an "automatic
-    backup/safety net" type of thing, in case I accidentally deleted the whole
-    config file or something.
-
-    We need to disable this, because now we have a *better* repo, one that is
-    manually pushed, and presumably has proper commit messages!
-
-        mv .git .disable.git        # yeah it's a hack, sue me
-
-3.  Now the compile command created an empty, bare, "gitolite-admin" repo, so we
-    seed it with the current contents of the config and keys.  (A note on the
-    `GIT_WORK_TREE` variable: I avoid setting these variables in the normal way
-    because I always forget to unset them later, and then when I `cd` to other
-    repos they play havoc with my git commands, so this is how I do it)
-
-        cd ~/repositories/gitolite-admin.git
-        GIT_WORK_TREE=$HOME/.gitolite git add conf/gitolite.conf keydir
-        GIT_WORK_TREE=$HOME/.gitolite git commit -am start
-
-4.  Now we have to setup the post-update hook for push-to-admin to work.  The hook
-    should (1) make a forced checkout in the "live" config directory (which is
-    `~/.gitolite`), and (2) run the compile script.
-
-    `src/pta-hook.sh` has the code you need; just copy it to the right place with
-    the right name, change the first line if needed, and make it executable:
-
-        # (assuming pwd is still ~/repositories/gitolite-admin.git)
-        cp ~/.gitolite/src/pta-hook.sh hooks/post-update
-
-        # if you changed $GL_ADMINDIR in ~/.gitolite.conf, then edit the hooks
-        # and change the first line:
-        vim hooks/post-update
-
-        chmod +x hooks/post-update
-
-----
-
-#### client side setup
-
-1.  Now get to your workstation, and
-
-        git clone git@server:gitolite-admin.git
-
-    That's it, we're done.  You're in gitosis land as far as this is concerned
-    now.  So knock yourself out.  Or lock yourself out... :-)
diff --git a/doc/5-delegation.mkd b/doc/5-delegation.mkd
index 863268f..af73b81 100644
--- a/doc/5-delegation.mkd
+++ b/doc/5-delegation.mkd
@@ -5,14 +5,13 @@
 ### lots of repos, lots of users
 
 Gitolite tries to make it easy to manage access to lots of users and repos,
-exploiting commonalities wherever possible.  (The example in the section
-"simpler syntax" in [this page][ml] should give you an idea).  As you can see,
-it lets you specify bits and pieces of the access control separately -- i.e.,
-*all* the access specs for a certain repo need not be together; they can be
-scattered, which makes it easier to manage the sort of slice and dice needed
-in that example.
+exploiting commonalities wherever possible.  (The example in [this
+section][ss] should give you an idea).  As you can see, it lets you specify
+bits and pieces of the access control separately -- i.e., *all* the access
+specs for a certain repo need not be together; they can be scattered, which
+makes it easier to manage the sort of slice and dice needed in that example.
 
-[ml]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd
+[ss]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#simpler_syntax
 
 But eventually the config file will become too big.  If you let only one
 person have control, he could become a bottleneck.  If you give it to multiple
@@ -30,14 +29,16 @@ Delegation offers a way to do all that.  Note that delegated admins cannot
 create or remove users, not can they define new repos.  They can only define
 access control rules for a set of repos they have been given authority for.
 
-### splitting up the config file into fragments
+----
 
 It's easier to show how it all works with an example instead of long
 descriptions.
 
+### splitting up the set of repos into groups
+
 To start with, recall that gitolite allows you to specify **groups** (of users
 or repos, same syntax).  So the basic idea is that the main config file
-(`~/.gitolite/conf/gitolite.conf` by default) will specify some repo groups:
+(`conf/gitolite.conf` in your admin repo clone) will specify some repo groups:
 
     # group your projects/repos however you want
     @webbrowser_repos           = firefox lynx
@@ -47,71 +48,25 @@ or repos, same syntax).  So the basic idea is that the main config file
     # any other config as usual, including access control lines for any of the
     # above projects or groups
 
-Now just create these files (assuming default `$GL_ADMINDIR` location):
-
-    ~/.gitolite/conf/fragments/webbrowser_repos.conf
-    ~/.gitolite/conf/fragments/webserver_repos.conf
-    ~/.gitolite/conf/fragments/malware_repos.conf
-
-Within each of those files put in whatever access control rules you want for
-the repos that are members of that group.  Notice that the basenames of the
-files must be exactly the same as the name of the corresponding repo group in
-the main config file.
-
-For instance, `~/.gitolite/conf/fragments/webbrowser_repos.conf` would only
-contain access control for firefox and lynx.  If it referenced any other repo
-(say "storm") those lines would be ignored (and a warning message generated).
-
-When you run the compile script (`src/gl-compile-conf`), the **net effect is
-as if you appended the contents of all the "fragment" files, in alphabetical
-order, to the bottom of the main file**.
-
-(Except of course, while processing a fragment, it will ignore attempts to set
-permissions for repos that are not members of the same-named "repo group").
-
-And that's basically it, in the simplest usage.
-
-["But WAIT, there's MORE!"][bwtm]
-
-[bwtm]: http://en.wikipedia.org/wiki/Ed_Valenti#But_Wait.21_There.27s_More
-
-### delegating ownership of fragments
-
-Splitting up the file does help, but there's also that little security issue
--- anyone can make any change to any "fragment", unless you (once again) go
-back to Unix permissions to keep them separate.
+### delegating ownership of groups of repos
 
-Fixing that requires using "push-to-admin", which is the default (and only)
-method to make config changes in gitosis.
-
-For a long time, I refused to make "push to admin" the default because it's a
-support nightmare.  Don't get me wrong -- it's a great feature, and I use it
-myself, but the learning curve was too steep to make it *required*.
-
-But eventually I figured out a way to front-load the darn ssh problem that
-everyone on #git seemed to run up against, created a nice "easy install"
-script, and made "push to admin" the default.
-
-So now, you just add these lines to the main config file, assuming Alice is in
-charge of all web browser development projects, Bob takes care of web servers,
-and Mallory, as [tradition][abe] dictates, is in charge of malware ;-)
+Once the repos are grouped, give each person charge of one or more groups.
+For example, Alice may be in charge of all web browser development projects,
+Bob takes care of web servers, and Mallory, as [tradition][abe] dictates, is
+in charge of malware ;-)
 
 [abe]: http://en.wikipedia.org/wiki/Alice_and_Bob#List_of_characters
 
-    # these 2 lines were probably present already
+You do this by adding branches to the `gitolite-admin` repo:
+
+    # the admin repo access was probably like this to start with:
     repo gitolite-admin
         RW+                     = sitaram
-    # now add these 3 lines
+    # now add these lines to the config for the admin repo
         RW  webbrowser_repos    = alice
         RW  webserver_repos     = bob
         RW  malware_repos       = mallory
 
-    # you need these lines too -- they define what repos alice/bob/mallory are
-    # allowed to control
-    @webbrowser_repos           = firefox lynx
-    @webserver_repos            = apache nginx
-    @malware_repos              = conficker storm
-
 As you can see, **for each repo group** you want to delegate authority over,
 there's a **branch with the same name** in the `gitolite-admin` repo.  If you
 have write access to that branch, you are allowed to define rules for repos in
@@ -136,14 +91,7 @@ Here's how to use this in practice:
 
   * Alice then commits and pushes this branch to the `gitolite-admin` repo
 
-Naturally, a successful push invokes the post-update hook that you installed
-(while setting up [push-to-admin][ptd]).  Here's what it does:
-
-  * for each branch, say `br`, of the `gitolite-admin` repo, it checks if
-    there is a file called `conf/fragments/br.conf`
-
-  * if there is, it extracts it and copies it with the exact same name and
-    path, into the `$GL_ADMINDIR` directory (`~/.gitolite` by default)
-
-After that, it runs the compile script, and things work the same as described
-in the previous section.
+Naturally, a successful push invokes the post-update hook that the admin repo
+has, which eventually runs the compile script.  The **net effect** is as if
+you appended the contents of all the "fragment" files, in alphabetical order,
+to the bottom of the main file.
diff --git a/src/00-easy-install.sh b/src/00-easy-install.sh
index db097a7..b8ad9fe 100755
--- a/src/00-easy-install.sh
+++ b/src/00-easy-install.sh
@@ -283,6 +283,10 @@ then
     then
         [[ $quiet == -q ]] || ${VISUAL:-${EDITOR:-vi}} $tmpgli/.gitolite.rc
     else
+        # MANUAL: if you're upgrading, read the instructions below and
+        # manually make sure your final ~/.gitolite.rc has both your existing
+        # customisations as well as any new variables that the new version of
+        # gitolite has introduced
         prompt "" \
         "    looks like you're upgrading, and there are some new rc variables
         that this version is expecting that your old rc file doesn't have.
diff --git a/src/gl-compile-conf b/src/gl-compile-conf
index 665d1d0..629bded 100755
--- a/src/gl-compile-conf
+++ b/src/gl-compile-conf
@@ -434,20 +434,3 @@ close $newkeys_fh or die "$ATTN close newkeys failed: $!\n";
 system("cat $ENV{HOME}/.ssh/authorized_keys > $ENV{HOME}/.ssh/old_authkeys");
 system("cat $ENV{HOME}/.ssh/new_authkeys > $ENV{HOME}/.ssh/authorized_keys");
 system("rm  $ENV{HOME}/.ssh/new_authkeys");
-
-# if the gl admin directory (~/.gitolite) is itself a git repo, do an
-# autocheckin.  nothing fancy; this is a "just in case" type of thing.
-wrap_chdir($GL_ADMINDIR);
-if (-d ".git")
-{
-    system("git add -A conf keydir");       # stage all operational data
-    # and if there are any
-    if (system("git diff --cached --quiet") )
-    {
-        open my $commit_ph, "|-", "git commit -F -"
-            or die "$ATTN open commit failed: $!\n";
-        print $commit_ph "keydir changed\n\n";
-        print $commit_ph `git diff --cached --name-status`;
-        close $commit_ph or die "$ATTN close commit failed: $!\n";
-    }
-}