MASSIVE set of changes to documents!

I got tired of being told "TL;DR". Now the online versions of most documents fit on a page or two, or at least most of them do. The rest has been split out (and you can see the links to the split out sections right where the text is in the raw Markdown). This is much more pleasant to read, and I've improved the linking so it's much less effort for me to keep the links correct.
2011-11-01 10:33:20 +05:30 · 2011-11-01 10:33:20 +05:30 · 6e29365316
parent 3f87430c5a
commit 6e29365316
45 changed files with 1194 additions and 2706 deletions
--- a/README.mkd
+++ b/README.mkd
@ -1,221 +1,9 @@
-# Hosting git repositories
+# Gitolite README
-<a name="start"></a>
+If you're really impatient, and you're familiar with Unix and ssh, follow the
 [quick install](http://sitaramc.github.com/gitolite/index.html#qi)
 instructions.
-Gitolite allows you to setup git hosting on a central server, with
+But if you want to do anything meaningful with gitolite you have to spend some
-fine-grained access control and many (many!) more powerful features.
+time cuddling up to the docs.  **The complete online documentation starts
-
+[here](http://sitaramc.github.com/gitolite)**.
 ----
 In this document:
  * <a href="#_quick_install">quick install</a>
  * <a href="#_what">what</a>
      * <a href="#_documentation">documentation</a>
  * <a href="#_why">why</a>
  * <a href="#_main_features">main features</a>
  * <a href="#_security">security</a>
  * <a href="#_contact_and_license">contact and license</a>
 ----
 <a name="_quick_install"></a>
 ### quick install
 If you're comfortable with Unix and ssh, the following steps should work.
 <font color="gray">(However, gitolite has lots and lots of useful features;
 don't miss out on them by skipping the excellent
 [documentation][docs]!)</font>
  * create a user called `git`.  Login to this user.
  * copy your ssh pubkey from your workstation.  Rename it to `YourName.pub`.
  * now run these commands:
        git clone git://github.com/sitaramc/gitolite
        cd gitolite
        src/gl-system-install
        gl-setup ~/YourName.pub
 You're done.
 A word of caution: do **NOT** add repos or users directly on the server!  You
 MUST manage the server by cloning the special 'gitolite-admin' repo on your
 workstation (`git clone git@server:gitolite-admin`), making changes, and
 pushing them.  See [here][aur] for how to add users and repos.
 [aur]: http://sitaramc.github.com/gitolite/doc/2-admin.html#_adding_users_and_repos
 <a name="_what"></a>
 ### what
 Gitolite is an access control layer on top of git.  Here's an "executive
 summary":
  * use a single unix user ("real" user) on the server
  * provide access to many gitolite users
      * they are not "real" users
      * they do not get shell access
  * control access to many git repositories
      * read access controlled at the repo level
      * write access controlled at the branch/tag/file/directory level,
        including who can rewind, create, and delete branches/tags
  * can be installed without root access, assuming git and perl are already
    installed
  * authentication is most commonly done using sshd, but you can also use
    httpd if you prefer (this may require root access).
  * several other neat features described below and elsewhere in the
    [doc/][docs] directory.
 <a name="_documentation"></a>
 #### documentation
 Gitolite comes with a **huge** amount of documentation.  Almost all of it is
 for the *administrator* of a gitolite server.  If you're a *user*, you only
 need [this][user].
 Otherwise, the suggested reading order is this:
  * the README (this document) for a quick intro
  * the [INSTALL][install] document
      * the most common installation issues are caused by ssh.  Here's how
        [gitolite uses ssh][doc9gas].  And here's an [ssh trouble
        shooting][doc6sts] document
  * the [ADMIN][admin] document
  * (if you're migrating from gitosis, read [this][migr])
 There is also a **[master TOC of all gitolite documentation][docs]**; use your
 browser's search function to look for likely sounding words or just browse
 around -- you never know what you'll find!
 [Here][who]'s some information on some of the projects and
 people using gitolite (and who, in turn, have helped shape its features).
 <a name="_why"></a>
 ### why
 Gitolite is separate from git, and needs to be installed and configured.  So...
 why do we bother?
 Gitolite is useful in any server that is going to host multiple git
 repositories, each with many developers, where some sort of access control is
 required.
 In theory, this can be done with plain old Unix permissions: each user is a
 member of one or more groups, each group "owns" one or more repositories, and
 using unix permissions (especially the setgid bit -- `chmod g+s`) you can
 allow/disallow users access to repos.
 But there are several disadvantages here:
  * every user needs a userid and password on the server.  This is usually a
    killer, especially in tightly controlled environments
  * adding/removing access rights involves complex `usermod -G ...` mumblings
    which most admins would rather not deal with
  * *viewing* (aka auditing) the current set of permissions requires running
    multiple commands to list directories and their permissions/ownerships,
    users and their group memberships, and then correlating all these manually
  * auditing historical permissions or permission changes is pretty much
    impossible without extraneous tools
  * errors or omissions in setting the permissions exactly can cause problems
    of either kind: false accepts or false rejects
  * without going into ACLs it is not possible to give some people read-only
    access while some others have read-write access to a repo (unless you make
    it world-readable).  Group access just doesn't have enough granularity
  * it is absolutely impossible to restrict pushing by branch name or tag
    name.
 Gitolite does away with all this:
  * it uses ssh magic to remove the need to give actual unix userids to
    developers
  * it uses a simple but powerful config file format to specify access rights
  * access control changes are affected by modifying this file, adding or
    removing user's public keys, and "compiling" the configuration
  * this also makes auditing trivial -- all the data is in one place, and
    changes to the configuration are also logged, so you can audit them.
  * finally, the config file allows distinguishing between read-only and
    read-write access, not only at the repository level, but at the branch
    level within repositories.
 <a name="_main_features"></a>
 ### main features
 The most important feature I needed was **per-branch permissions**.  This is
 pretty much mandatory in a corporate environment, and is almost the single
 reason I started *thinking* about writing gitolite.
 It's not just "read-only" versus "read-write".  Rewinding a branch (aka "non
 fast forward push") is potentially dangerous, but sometimes needed.  So is
 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, and more, are documented in
 detail somewhere in gitolite's [doc/][docs] subdirectory.
  * simple, yet powerful, config file syntax, including specifying
    gitweb/daemon access.  You'll need this power if you manage lots of
    users+repos+combinations of access
  * apart from branch-name based restrictions, you can also restrict by
    file/dir name changed (i.e., output of `git diff --name-only`)
  * if your requirements are still too complex, you can split up the config
    file and delegate authority over parts of it
  * easy to specify gitweb owner, description and gitweb/daemon access
  * easy to sync gitweb (http) authorisation with gitolite's access config
  * comprehensive logging [aka: management does not think "blame" is just a
    synonym for "annotate" :-)]
  * "personal namespace" prefix for each dev
  * migration guide and simple converter for gitosis conf file
  * "exclude" (or "deny") rights at the branch/tag level
  * specify repos using patterns (patterns may include creator's name)
  * define powerful operations on the server side, even github-like forking
 <a name="_security"></a>
 ### security
 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.
 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,
 that the config file says he shouldn't, and caused by a bug in *code* that is
 in the "master" branch, (not in the other branches, or the configuration file
 or in Unix, perl, shell, etc.)...  well I can't afford 1000 USD rewards like
 djb, so you'll have to settle for 5000 INR (Indian Rupees) as a "token" prize
 :-)
 However, there are a few optional features (which must be explicitly enabled
 in the RC file) where I just haven't had the time to reason about security
 thoroughly enough.  Please read the comments in `conf/example.gitolite.rc` for
 details, looking for the word "security".
 ----
 <a name="_contact_and_license"></a>
 ### contact and license
 Gitolite is released under GPL v2.  See COPYING for details.
  * author: sitaramc@gmail.com, sitaram@atc.tcs.com
  * mailing list: gitolite@googlegroups.com
  * list subscribe address : gitolite+subscribe@googlegroups.com
 [transcript]: http://sitaramc.github.com/gitolite/doc/install-transcript.html
 [install]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html
 [admin]: http://sitaramc.github.com/gitolite/doc/2-admin.html
 [migr]: http://sitaramc.github.com/gitolite/doc/migrate.html
 [doc9gas]: http://sitaramc.github.com/gitolite/doc/gitolite-and-ssh.html
 [doc6sts]: http://sitaramc.github.com/gitolite/doc/ssh-troubleshooting.html
 [who]: http://sitaramc.github.com/gitolite/doc/who-uses-it.html
 [tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial
 [docs]: http://sitaramc.github.com/gitolite
 [user]: http://sitaramc.github.com/gitolite/doc/user-manual.html
--- a/contrib/adc/README-adc.mkd
+++ b/contrib/adc/README-adc.mkd
@ -1,4 +1,4 @@
-## brief descriptions of the shipped ADCs (admin-defined commands)
+# F=shipped_ADCs brief descriptions of the shipped ADCs (admin-defined commands)
 (...with pointers to further information where needed)
@ -8,19 +8,14 @@
 or other admin chores); details [here][able].  This ADC is meant only for
 admins.
 [able]: http://sitaramc.github.com/gitolite/doc/admin-defined-commands.html#_enable_disable_push_access_temporarily
 **delete-branch**: allow someone to delete a branch that they themselves
 created. (i.e., when the user had RWC, but not RWCD, permissions).  Details on
 this ADC are [here][dbsha]; details on RWC/RWD/RWCD etc are [here][rwcd].
 [dbsha]: https://github.com/sitaramc/gitolite/commit/89b68bf5ca99508caaa768c60ce910d7e0a29ccf
 [rwcd]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html#_creating_and_deleting_branches
 **fork**: Think of it as a server-side clone; details [here][fork].
 [fork]: http://sitaramc.github.com/gitolite/doc/admin-defined-commands.html#_fork
 **get-rights-and-owner.in-perl**:  Most of the ADCs are in shell, so this is a
 sample of how to write an ADC in perl.
@ -36,14 +31,10 @@ itself.  This ADC displays site-local help, if the site admin enabled it.
 **hub**: allow "pull requests" a la github; details [here][hub].
 [hub]: http://sitaramc.github.com/gitolite/contrib/adc/hub.html
 **rm**, **lock**, and **unlock**:<br>
 **trash**, **list-trash**, and **restore**:
->   two families of repo deletion commands; details [here][rddoc]
+>   two families of repo deletion commands; details [here][wild_repodel]
 [rddoc]: http://sitaramc.github.com/gitolite/contrib/adc/repo-deletion.html
 **sudo**: allow admin to run ADCs on behalf of a user.  Useful in support
 situations I guess.  Details in source.
--- a/contrib/adc/hub.mkd
+++ b/contrib/adc/hub.mkd
@ -1,18 +1,6 @@
-## the 'hub' ADC
+# F=hub the 'hub' ADC
-In this document:
+## a home grown 'hub' for git repos
  * <a href="#_a_home_grown_hub_for_git_repos">a home grown 'hub' for git repos</a>
  * <a href="#_general_syntax">general syntax</a>
      * <a href="#_Bob_s_commands">Bob's commands</a>
      * <a href="#_Alice_s_just_looking_commands">Alice's "just looking" commands</a>
      * <a href="#_Alice_s_action_commands">Alice's "action" commands</a>
  * <a href="#_what_next_">what next?</a>
  * <a href="#_note_to_the_admin_configuration_variables">note to the admin: configuration variables</a>
 <a name="_a_home_grown_hub_for_git_repos"></a>
 ### a home grown 'hub' for git repos
 This ADC (admin-defined command) helps collaboration among repos.  The name is
 in honor of github, which is the primary host for gitolite itself.
@ -51,17 +39,13 @@ do a normal `git fetch [origin]` to get it to her workstation.  This has the
 added advantage that other people, who may be watching her repo but not Bob's,
 now get to see what Bob sent her and send comments etc.
-<a name="_general_syntax"></a>
+## general syntax
 ### general syntax
 The general syntax is
    ssh git@server hub <hub-command> <args>
-<a name="_Bob_s_commands"></a>
+### Bob's commands
 #### Bob's commands
 The following commands do not cause a fetch, and should be quite fast:
@ -92,9 +76,7 @@ The following commands do not cause a fetch, and should be quite fast:
        ssh git@server hub request-status child [parent] request-number
-<a name="_Alice_s_just_looking_commands"></a>
+### Alice's "just looking" commands
 #### Alice's "just looking" commands
  * Alice lists requests waiting for her to check and possibly pull into
    parent.  For each waiting pull request, she will see a serial number, the
@ -140,9 +122,7 @@ The following commands do not cause a fetch, and should be quite fast:
    to ADCs, you probably can't do things like `pu^` or `master~3`, and have
    to use SHAs instead.
-<a name="_Alice_s_action_commands"></a>
+### Alice's "action" commands
 #### Alice's "action" commands
  * Alice doesn't like what she sees and decides to reject it.  This command
    expects some text on STDIN as the rejection message:
@ -179,9 +159,7 @@ The following commands do not cause a fetch, and should be quite fast:
 Notice the sequence of Alice's action commands: it's either 'reject', or a
 'fetch' then 'accept'.
-<a name="_what_next_"></a>
+## what next?
 ### what next?
 At this point, you're done with the `hub` ADC.  However, all this is on the
 bare `parent.git` on the server, and nothing has hit Alice's workstation yet!
@ -195,9 +173,7 @@ Finally, note that Alice does not actually need to use the `fetch` subcommand.
 She can do the traditional thing and fetch Bob's repo/branch directly to her
 *workstation*.
-<a name="_note_to_the_admin_configuration_variables"></a>
+## note to the admin: configuration variables
 ### note to the admin: configuration variables
 There are 2 configuration variables.  `BASE_FETCH_URL` should be set to a
 simple "read" URL (so it doesn't even have to be ssh) that almost anyone using
--- a/contrib/adc/repo-deletion.mkd
+++ b/contrib/adc/repo-deletion.mkd
@ -1,11 +1,8 @@
-## deleting repos safely
+# F=wild_repodel deleting repos safely
-**NOTE**: this page is about deleting [user-created repos][wcr].  It is
+**NOTE**: this page is about deleting [user-created repos][wild].  It is
 **not** about deleting "normal" repos (the kind that are specified in the
-gitolite.conf file itself) -- to delete those read [here][dnr].
+gitolite.conf file itself) -- to delete those read [here][repodel].
 [wcr]: http://sitaramc.github.com/gitolite/doc/wildcard-repositories.html
 [dnr]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html#_deleting_a_repo
 (see [this thread][thr] on the gitolite mailing list)
--- a/contrib/adc/sskm.mkd
+++ b/contrib/adc/sskm.mkd
@ -1,38 +1,16 @@
-## changing keys -- self service key management
+# F=sskm changing keys -- self service key management
 Follow this guide to add keys to or remove keys from your account. Note that you cannot use this method to add your *first* key to the account; you must still email your initial key to your admin.
 The key management is done using an ADC (admin-defined command) called `sskm`.
 In this document:
  * <a href="#_Important_">Important!</a>
      * <a href="#_Key_fingerprints">Key fingerprints</a>
      * <a href="#_Active_keys">Active keys</a>
      * <a href="#_Selecting_which_key_to_use">Selecting which key to use</a>
      * <a href="#_Public_vs_private_keys">Public vs. private keys</a>
  * <a href="#_Listing_your_existing_keys">Listing your existing keys</a>
  * <a href="#_Adding_or_Replacing_a_key">Adding or Replacing a key</a>
      * <a href="#_Step_1_Adding_the_Key">Step 1: Adding the Key</a>
      * <a href="#_Step_2_Confirming_the_addition">Step 2: Confirming the addition</a>
      * <a href="#_Optional_Undoing_a_mistaken_add_before_confirmation_">Optional: Undoing a mistaken add (before confirmation)</a>
  * <a href="#_Removing_a_key">Removing a key</a>
      * <a href="#_Step_1_Mark_the_key_for_deletion">Step 1: Mark the key for deletion</a>
      * <a href="#_Step_2_Confirming_the_deletion">Step 2: Confirming the deletion</a>
      * <a href="#_Optional_Undoing_a_mistaken_delete_before_confirmation_">Optional: Undoing a mistaken delete (before confirmation)</a>
  * <a href="#_important_notes_for_the_admin">important notes for the admin</a>
 ----
-<a name="_Important_"></a>
+## Important!
 ### Important!
 There are a few things that you should know before using the key management system. Please do not ignore this section!
-<a name="_Key_fingerprints"></a>
+### Key fingerprints
 #### Key fingerprints
 Keys are identified in some of these subcommands by their fingerprints. To see the fingerprint for a public key on your computer, use the following syntax:
@ -43,18 +21,13 @@ You'll get output like:
    jeff@baklava ~  $  ssh-keygen -l -f .ssh/jeffskey.pub 
    2048 2d:78:d4:2c:b1:6d:9a:dc:d9:0d:94:3c:d8:c2:65:44 .ssh/jeffskey.pub (RSA)
-
+### Active keys
 <a name="_Active_keys"></a>
 #### Active keys
 Any keys that you can use to interact with the system are active keys. (Inactive keys are keys that are, for instance, scheduled to be added or removed.) Keys are identified with their `keyid`; see the section below on listing keys.
 If you have no current active keys, you will be locked out of the system (in which case email your admin for help). Therefore, be sure that you are never removing your only active key!
-<a name="_Selecting_which_key_to_use"></a>
+### Selecting which key to use
 #### Selecting which key to use
 Although you can identify yourself to the Gitolite system with any of your active keys on the server, at times it is necessary to specifically pick which key you are identifying with. To pick the key to use, pass the `-i` flag into `ssh`:
@ -75,15 +48,11 @@ disable the agent, using one of these commands:
 * If using `keychain`, run `keychain --clear` to remove identities
 * Unset the `SSH_AUTH_SOCK` and `SSH_AGENT_PID` variables in the current shell
-<a name="_Public_vs_private_keys"></a>
+### Public vs. private keys
 #### Public vs. private keys
 In this guide, all keys are using their full suffix. In other words, if you see a `.pub` at the end of a key, it's the public key; if you don't, it's the private key. For instance, when using the `-i` flag with `ssh`, you are specifying private keys to use. When you are submitting a key for addition to the system, you are using the public key.
-<a name="_Listing_your_existing_keys"></a>
+## Listing your existing keys
 ### Listing your existing keys
 To see a list of your existing keys, use the `list` argument to `sskm`:
@ -103,13 +72,9 @@ use any keyid you wish when adding keys (like `@home`, `@laptop`, ...); the
 only rules are that it must start with the `@` character and after that
 contain only digits, letters, or underscores.
-<a name="_Adding_or_Replacing_a_key"></a>
+## Adding or Replacing a key
-### Adding or Replacing a key
+### Step 1: Adding the Key
 <a name="_Step_1_Adding_the_Key"></a>
 #### Step 1: Adding the Key
 Adding and replacing a key is the same process. What matters is the `keyid`. When adding a new key, use a new `keyid`; when replacing a key, pass in the `keyid` of the key you want to replace, as found by using the `list` subcommand. Pretty simple!
@ -132,9 +97,7 @@ If you now run the `list` command you'll see that it's scheduled for addition:
    == keys marked for addition/replacement ==
    1: ff:92:a2:20:6d:42:6b:cf:20:e8:a2:4a:3b:b0:32:3a  : jeff@key4.pub
-<a name="_Step_2_Confirming_the_addition"></a>
+### Step 2: Confirming the addition
 #### Step 2: Confirming the addition
 Gitolite uses Git internally to store the keys. Just like with Git, where you commit locally before `push`-ing up to the server, you need to confirm the key addition (see the next section if you made a mistake). We use the `confirm-add` subcommand to do this, *but*: to verify that you truly have ownership of the corresponding private key, you *must* use the key you are adding itself to do the confirmation! (Inconvenient like most security, but very necessary from a security perspective.) This is where using the `-i` flag of `ssh` comes in handy:
@ -152,9 +115,7 @@ Listing keys again shows that all four keys are now active:
    3: 2d:78:d4:2c:b1:6d:9a:dc:d9:0d:94:3c:d8:c2:65:44  : jeff@key3.pub
    4: ff:92:a2:20:6d:42:6b:cf:20:e8:a2:4a:3b:b0:32:3a  : jeff@key4.pub
-<a name="_Optional_Undoing_a_mistaken_add_before_confirmation_"></a>
+### Optional: Undoing a mistaken add (before confirmation)
 #### Optional: Undoing a mistaken add (before confirmation)
 Another advantage of Gitolite using Git internally is that that if we mistakenly add the wrong key, we can undo it before it's confirmed by passing in the `keyid` we want to remove into the `undo-add` subcommand:
@ -171,13 +132,9 @@ Listing the keys shows that that new key has been removed:
    2: 61:38:a7:9f:ba:cb:99:81:4f:49:2c:8b:c8:63:8e:33  : jeff@key2.pub
    3: 2d:78:d4:2c:b1:6d:9a:dc:d9:0d:94:3c:d8:c2:65:44  : jeff@key3.pub
-<a name="_Removing_a_key"></a>
+## Removing a key
-### Removing a key
+### Step 1: Mark the key for deletion
 <a name="_Step_1_Mark_the_key_for_deletion"></a>
 #### Step 1: Mark the key for deletion
 Deleting a key works very similarly to adding a key, with `del` substituted for `add`.
@ -211,9 +168,7 @@ Listing the keys now shows that it is marked for deletion:
    == keys marked for deletion ==
    1: ff:92:a2:20:6d:42:6b:cf:20:e8:a2:4a:3b:b0:32:3a  : jeff@key4.pub
-<a name="_Step_2_Confirming_the_deletion"></a>
+### Step 2: Confirming the deletion
 #### Step 2: Confirming the deletion
 Just like with Git, where you commit locally before `push`-ing up to the server, you need to confirm the key addition (see the next section if you made a mistake). We use the `confirm-del` subcommand to do this, *but*: unlike the `confirm-add` subcommand, you *must* use a *different* key than the key you are deleting to do the confirmation! This prevents you from accidentally locking yourself out of the system by removing all active keys:
@ -230,9 +185,7 @@ Listing keys again shows that the fourth key has been removed:
    2: 61:38:a7:9f:ba:cb:99:81:4f:49:2c:8b:c8:63:8e:33  : jeff@key2.pub
    3: 2d:78:d4:2c:b1:6d:9a:dc:d9:0d:94:3c:d8:c2:65:44  : jeff@key3.pub
-<a name="_Optional_Undoing_a_mistaken_delete_before_confirmation_"></a>
+### Optional: Undoing a mistaken delete (before confirmation)
 #### Optional: Undoing a mistaken delete (before confirmation)
 Another advantage of Gitolite using Git internally is that that if we mistakenly delete the wrong key, we can undo it before it's confirmed by passing in the `keyid` we want to keep into the `undo-del` subcommand. Note that this operation *must* be performed using the private key that corresponds to the key you are trying to keep! (Security reasons, similar to the reason that you must confirm an addition this way; it prevents anyone from undoing a deletion, and therefore keeping in the system, a key that they cannot prove (by having the corresponding private key) should stay in the system):
@ -260,9 +213,7 @@ Listing the keys shows that that new key is now marked active again:
 ----
-<a name="_important_notes_for_the_admin"></a>
+## important notes for the admin
 ### important notes for the admin
 These are the things that can break if you enable this ADC for your users:
@ -279,10 +230,8 @@ These are the things that can break if you enable this ADC for your users:
    So, if you have the same *filename* in different subdirectories of
    `keydir`, you can't use this tool.
-  * keys placed in specific folders (perhaps to do [this][optak], or for
+  * keys placed in specific folders (perhaps to do [this][authkeyopt], or for
    whatever other reasons), will probably not stay in those folders if this
    ADC is used.  Even a key delete, followed by undoing the delete, will
    cause the key to effectively move to the root of the key store (i.e., the
    `keydir` directory in the gitolite-admin repo).
 [optak]: http://sitaramc.github.com/gitolite/doc/big-config.html#_optimising_the_authkeys_file
--- a/contrib/gerrit.mkd
+++ b/contrib/gerrit.mkd
@ -1,4 +1,4 @@
-## comparing gerrit and gitolite
+# F=gerrit comparing gerrit and gitolite
 Gerrit and gitolite have too many high level differences.  Size is most
 visible of course: 56000 lines of Java versus 1300 lines of perl+shell,
--- a/contrib/gitolite-tools.mkd
+++ b/contrib/gitolite-tools.mkd
@ -1,4 +1,4 @@
-## gitolite-tools
+# F=_gitolite_tools gitolite-tools
 gitolite-tools is a collection of external git commands to work with
 gitolite server and repositories:
--- a/contrib/ldap/README-ldap.mkd
+++ b/contrib/ldap/README-ldap.mkd
@ -1,20 +1,17 @@
-## ldap helper programs
+# F=ldap_helpers ldap helper programs
 These programs were contributed by the Nokia MeeGo folks.
 The first 2 are perl and shell verisions of programs meant to be used as
 `$GL_GET_MEMBERSHIPS_PGM` (see [this][ldap] for more).
  * ldap-query-example.pl
  * ldap-query-example.sh
 The third program is meant to be installed as an adc (admin-defined command,
-see [here][adc]), and helps users change their LDAP passwords.
+see [here][ADCs]), and helps users change their LDAP passwords.
  * passwd
 Enjoy!
 [ldap]: http://sitaramc.github.com/gitolite/doc/big-config.html#_storing_usergroup_information_outside_gitolite_like_in_LDAP_
 [adc]: http://sitaramc.github.com/gitolite/doc/admin-defined-commands.html
--- a/contrib/mirroring-complex-example.mkd
+++ b/contrib/mirroring-complex-example.mkd
@ -1,33 +1,9 @@
-## semi-autonomous mirroring setup example
+# F=mirr_complex_example semi-autonomous mirroring setup example
 [deldoc]: http://sitaramc.github.com/gitolite/doc/delegation.html
 [sc]: http://sitaramc.github.com/gitolite/doc/delegation.html#_the_subconf_command
 This document describes one way to do this.  Gitolite is powerful so you can
 probably find other ways to suit you.
-In this document:
+## overview of problem
  * <a href="#_overview_of_problem">overview of problem</a>
  * <a href="#_overview_of_setup">overview of setup</a>
      * <a href="#_gitolite_feature_recap">gitolite feature recap</a>
  * <a href="#_pre_requisites">pre-requisites</a>
  * <a href="#_quick_setup">quick setup</a>
  * <a href="#_step_by_step">step by step</a>
      * <a href="#_1_gitolite_conf_">(1) `gitolite.conf`</a>
      * <a href="#_2_master_sam_conf_">(2) `master/sam.conf`</a>
      * <a href="#_3_host_admins_only_master_sam_p1_conf_">(3) host admins only -- `master/sam/p1.conf`</a>
      * <a href="#_4_mirrors_sam_p1_conf_">(4) `mirrors/sam/p1.conf`</a>
      * <a href="#_5_slave_frodo_sam_conf_">(5) `slave/frodo/sam.conf`</a>
      * <a href="#_6_manual_sync">(6) manual sync</a>
  * <a href="#_next_steps">next steps</a>
  * <a href="#_appendix_A_delegation_helper_files">appendix A: delegation helper files</a>
 ----
 <a name="_overview_of_problem"></a>
 ### overview of problem
 The example is from real life, with the following characteristics:
@ -55,9 +31,7 @@ The following can only be done by the master admins:
  * mirroring setup -- who's the master and who're the slaves for any repo
  * allowing redirected pushes from slaves
-<a name="_overview_of_setup"></a>
+## overview of setup
 ### overview of setup
 We will use p1 as the product, with sam as the master and frodo as a slave.
 Assume equivalent text/code for other product/master/slave combos.
@ -67,22 +41,18 @@ name; either a product name or, for local repos, a hostname.  In our example,
 these directory names would be p1 or sam on the host sam, and frodo on the
 host frodo.
-<a name="_gitolite_feature_recap"></a>
+### gitolite feature recap
-#### gitolite feature recap
+We use [delegation][deleg], to ensure that admins for sam can only write
 We use [delegation][deldoc], to ensure that admins for sam can only write
 files whose names start with `master/sam/`.  The actual files they will write
 are `master/sam/p1.conf` etc., one for each product that is mastered on their
 server.
-We use [subconf][sc].  When you say `subconf "path/to/foo.conf`, then within
+We use [subconf][].  When you say `subconf "path/to/foo.conf`, then within
 that file (and anything included from it), access can only be defined for
 repos that regex-match one of the elements of `@foo`.
-<a name="_pre_requisites"></a>
+## pre-requisites
 ### pre-requisites
 First, install mirroring on all servers according to the main mirroring
 document.  Set it up so that the gitolite-admin repo is mastered at one server
@ -91,9 +61,7 @@ and everyone else slaves it.
 Also, after (or during) the normal mirroring install, edit `~/.gitolite.rc` on
 all servers and set `$GL_WILDREPOS` to 1 (from its default of 0).
-<a name="_quick_setup"></a>
+## quick setup
 ### quick setup
  * edit your `gitolite.conf` file as given in step 1 below
      * ignore all the comments, even the ones that tell you to do something :-)
@ -126,9 +94,7 @@ A typical sequence with that script is:
 You can then treat the detailed steps described below as extra information or
 "background reading" ;-)
-<a name="_step_by_step"></a>
+## F=_mirrexsteps step by step
 ### step by step
 If the script is not cutting it for you and want to vary the technique for
 some reason, or you simply want to gain a better understanding of what is
@ -139,9 +105,7 @@ script.
 only place where you have to explicitly state this is in the delegation code
 in the appendix.  The rest of the time, "conf/" is assumed.
-<a name="_1_gitolite_conf_"></a>
+### (1) `gitolite.conf`
 #### (1) `gitolite.conf`
 The main config file has these items in it.  **Please add them in this
 order**.
@ -209,9 +173,7 @@ Here's what it looks like:
 You'll get some warnings about missing include files; ignore them.
-<a name="_2_master_sam_conf_"></a>
+### (2) `master/sam.conf`
 #### (2) `master/sam.conf`
 For each host sam, one file called `master/sam.conf` is needed.  This file
 contains just one line:
@ -223,9 +185,7 @@ contains just one line:
 "master/sam.conf"`.  The only purpose of this is to setup the subconf
 restriction on the combined contents of `master/sam/*.conf`.</font>
-<a name="_3_host_admins_only_master_sam_p1_conf_"></a>
+### (3) host admins only -- `master/sam/p1.conf`
 #### (3) host admins only -- `master/sam/p1.conf`
 (recap: the host admins for sam can only write files in `master/sam`).
@ -240,9 +200,7 @@ product.conf files.
 By default, everything is local to their server.  (Mirroring can only be setup
 by the master admins).
-<a name="_4_mirrors_sam_p1_conf_"></a>
+### (4) `mirrors/sam/p1.conf`
 #### (4) `mirrors/sam/p1.conf`
 For each product p1 mastered on host sam, a file called `mirrors/sam/p1.conf`
 will be created, containing mirror config lines for all repos of product p1.
@ -254,9 +212,7 @@ In this case, it could be
 If this file does not exist, p1 is local to sam and not mirrored.
-<a name="_5_slave_frodo_sam_conf_"></a>
+### (5) `slave/frodo/sam.conf`
 #### (5) `slave/frodo/sam.conf`
 For each product that slave frodo gets from master sam, this file has the
 following lines
@ -278,18 +234,14 @@ restriction of "sam"*.  This is important to prevent sam's admins from writing
 rules for repos they don't own and having them processed on other
 servers!</font>
-<a name="_6_manual_sync"></a>
+### (6) manual sync
 #### (6) manual sync
 The new repo(s) you just created would not have been synced up to frodo.  You
 can either make an empty commit and push, or log on to sam and run
     gl-mirror-shell request-push p1/reponame
-<a name="_next_steps"></a>
+## next steps
 ### next steps
 Once you've done the initial setup, here's what ongoing additions will
 require.
@ -302,9 +254,7 @@ require.
    hostname in the slaves list for the admin repo (this is in the main
    gitolite.conf file)
-<a name="_appendix_A_delegation_helper_files"></a>
+## F=_mirrappA appendix A: delegation helper files
 ### appendix A: delegation helper files
 These two files were briefly mentioned in the delegation setup.
--- a/contrib/monkeysphere.mkd
+++ b/contrib/monkeysphere.mkd
@ -1,4 +1,4 @@
-## (contributed doc: integrating gitolite with monkeysphere)
+# F=monkeysphere (contributed doc: integrating gitolite with monkeysphere)
 This document attempts to describe one way to integrate
 [Monkeysphere](http://web.monkeysphere.info/) authentication
--- a/contrib/putty.mkd
+++ b/contrib/putty.mkd
@ -1,21 +1,4 @@
-## putty and msysgit
+# F=contrib_putty putty and msysgit
 In this document:
  * <a href="#_msysgit_setup">msysgit setup</a>
  * <a href="#_Going_back_to_OpenSSH">Going back to OpenSSH</a>
  * <a href="#_Putty_keys">Putty keys</a>
      * <a href="#_Creating_a_new_key">Creating a new key</a>
      * <a href="#_Importing_an_existing_key">Importing an existing key</a>
      * <a href="#_Loading_an_existing_key">Loading an existing key</a>
      * <a href="#_Public_key">Public key</a>
      * <a href="#_Putty_ageant">Putty ageant</a>
  * <a href="#_Sessionless_or_raw_hostname_usage">Sessionless or raw hostname usage</a>
  * <a href="#_Putty_sessions">Putty sessions</a>
  * <a href="#_Host_key_authentication">Host key authentication</a>
  * <a href="#_Debugging_multiple_putty_ageant_keys">Debugging multiple putty ageant keys</a>
  * <a href="#_Setperms_and_other_commands">Setperms and other commands</a>
  * <a href="#_About_this_document">About this document</a>
 This document is intended for those who wish to use Putty/Plink with msysgit.
@ -27,9 +10,7 @@ If you need more help with putty or component programs I suggest looking at [the
 <a name="msysgit_setup"/>
-<a name="_msysgit_setup"></a>
+## msysgit setup
 ### msysgit setup
 Provided you have putty sessions msysgit should give you the option of specifying a location to plink. If it did not then you will need to add an environment variable named "GIT\_SSH" to point at plink.exe, wherever you have that sitting.
@ -51,17 +32,13 @@ If instead you get a "command not found" type error you likely have a typo in yo
 <a name="Going_back_to_OpenSSH"/>
-<a name="_Going_back_to_OpenSSH"></a>
+## Going back to OpenSSH
 ### Going back to OpenSSH
 If you wish to go back to OpenSSH all you need to do is delete the GIT\_SSH environment variable. This will vary by your version of windows and thus is not covered here.
 <a name="Putty_keys"/>
-<a name="_Putty_keys"></a>
+## Putty keys
 ### Putty keys
 If you do not already have putty private key files (.ppk) you will need to make at least one. You can either make a new one or convert an existing key to putty private key format.
@ -69,9 +46,7 @@ Either way, you will want to use puttygen. Note that you can go the other way if
 <a name="Creating_a_new_key"/>
-<a name="_Creating_a_new_key"></a>
+### Creating a new key
 #### Creating a new key
 To make it simple, I suggest SSH-2 RSA and a bit size of at least 1024. Larger keys will take longer to generate and will take longer to authenticate you on most systems. Making the key is as simple at hitting "Generate".
@ -79,9 +54,7 @@ It is recommended to give the key a meaningful comment.
 <a name="Importing_an_existing_key"/>
-<a name="_Importing_an_existing_key"></a>
+### Importing an existing key
 #### Importing an existing key
 If you already have an OpenSSH or ssh.com key you can import it using the "Import" option on the "Conversions" menu.
@ -89,41 +62,31 @@ If the key does not have a meaningful comment I would suggest adding one at this
 <a name="Loading_an_existing_key"/>
-<a name="_Loading_an_existing_key"></a>
+### Loading an existing key
 #### Loading an existing key
 If you need to load an existing key to edit or view it you can do so from the File menu.
 <a name="Public_key"/>
-<a name="_Public_key"></a>
+### Public key
 #### Public key
 To get your public key for use with gitolite, load (or generate, or import) your key into puttygen. There is a box labeled "Public key for pasting into OpenSSH `authorized_keys` file" there. Copy the text into your preferred text editor and save.
 <a name="Putty_ageant"/>
-<a name="_Putty_ageant"></a>
+### Putty ageant
 #### Putty ageant
 Though not required in all cases you may wish to use the putty ageant, pageant, to load your key(s). This will allow for your key(s) to be passphrase protected but not have to enter the passphrase when you go to use them, provided you have already loaded the key into the ageant.
 <a name="Sessionless_or_raw_hostname_usage"/>
-<a name="_Sessionless_or_raw_hostname_usage"></a>
+## Sessionless or raw hostname usage
 ### Sessionless or raw hostname usage
 When using plink without a putty session you pretty much have to load your keys with putty ageant, if only so that plink can find them.
 <a name="Putty_sessions"/>
-<a name="_Putty_sessions"></a>
+## Putty sessions
 ### Putty sessions
 In addition to hostnames msysgit can, when using putty, use putty sessions. This works in a manner similar to definitions in OpenSSH's `ssh_config` file. All settings in the session that apply to plink usage will be loaded, including the key file to use and even the username to connect to. Thus, instead of:
@ -135,9 +98,7 @@ You can use:
 <a name="Host_key_authentication"/>
-<a name="_Host_key_authentication"></a>
+## Host key authentication
 ### Host key authentication
 Whether you are using hostnames or sessions you still run into one potential problem. Plink currently wants to validate the server's SSH host key before allowing you to connect, and when git calls plink there is no way to tell it yes. Thus, you may get something like this:
@ -204,9 +165,7 @@ In either case hit y and the key will be stored.
 <a name="Debugging_multiple_putty_ageant_keys"/>
-<a name="_Debugging_multiple_putty_ageant_keys"></a>
+## Debugging multiple putty ageant keys
 ### Debugging multiple putty ageant keys
 In the event you are using putty ageant with multiple keys loaded you may see the wrong key being used. In general, pageant keys are tried in the order they were loaded into the ageant. If you have descriptive comment on each of your keys you can try connecting with plink in verbose mode to see what keys are being tried. Simply open the Git bash shell and run:
@ -225,9 +184,7 @@ The first says which (numerical) key the ageant is trying. The second tells you
 <a name="Setperms_and_other_commands"/>
-<a name="_Setperms_and_other_commands"></a>
+## Setperms and other commands
 ### Setperms and other commands
 When using wildcard repos the setperms command is very important, and other commands can come in handy as well. See their documentation for how to use them, but where they use:
@ -241,8 +198,6 @@ Otherwise everything should be identical.
 <a name="About_this_document"/>
-<a name="_About_this_document"></a>
+## About this document
 ### About this document
 This document was written by Thomas Berezansky (tsbere (at) mvlc (dot) org) in the hopes that it would be useful to those using putty on windows and wishing to use git/gitolite with their putty keys and sessions.
--- a/contrib/real-users/password-access.mkd
+++ b/contrib/real-users/password-access.mkd
@ -1,10 +1,8 @@
-# password access to gitolite
+# F=password_access password access to gitolite
-## (a.k.a: turning real users into gitolite users)
+(a.k.a: turning real users into gitolite users)
-<a name="_problems"></a>
+## problems
 ### problems
 *Problem 1*: Here's one type of problem some admins have:
@ -33,9 +31,7 @@ pesky password problem, and do not wish them to actually have shell access or
 be able to do anything else on the server, don't worry -- that's easy to
 handle too.</font>
-<a name="_solution"></a>
+## solution
 ### solution
 Briefly, the Unix userid is made to act like a "gitolite proxy".
@ -73,17 +69,13 @@ This second connection *does* require ssh keys, but since they're all on the
 server, it's scriptable and automatable so the user doesn't have to deal with
 these pesky ssh keys.
-<a name="_some_hints_notes_and_caveats"></a>
+## some hints, notes and caveats
 ### some hints, notes and caveats
  * This doesn't mean all your users have to be like this.  You can have
    normal users also.  In fact, you can have users who give you a pub key
    from their workstation the normal way, as well as use this method.
-<a name="_what_the_2_scripts_actually_do"></a>
+## what the 2 scripts actually do
 ### what the 2 scripts actually do
  * `gl-shell` will become the new login shell for these users.  This shell
    will forward git clone/fetch/push requests to the gitolite server.
@ -99,12 +91,11 @@ these pesky ssh keys.
    example) `alice@localhost.pub` in keydir of the admin repo, which is then
    pushed.
-    Notice the use of [this trick][oumk] to allow Alice to allow users to have
+    Notice the use of [this trick][oldmultikeys] to allow Alice to allow users
-    other (gitolite normal) keys as well, such as perhaps from a laptop.
+    to have other (gitolite normal) keys as well, such as perhaps from a
    laptop.
-<a name="_setting_it_up"></a>
+## setting up password access
 ### setting it up
 Here's how to set this up.  First, the **one-time** tasks:
@ -131,5 +122,3 @@ Now, for each user 'alice' that has her own real (unix) userid, and also needs
 to access gitolite *via* her own id, run the command `gl-shell-setup alice`.
 And that's really all there is to it.
 [oumk]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html#_one_user_many_keys
--- a/contrib/vim/README-vim.mkd
+++ b/contrib/vim/README-vim.mkd
@ -1,11 +1,10 @@
-## Vim Syntax Highlight
+# F=_vimsyntax Vim Syntax Highlight
 [Vim][] Syntax highlight for `gitolite.conf` can be found from:
 - [vim.org script page][vim.org] (Releases)
 - [GitHub][] (Sources)
 [Vim]: http://www.vim.org/
 [vim.org]: http://www.vim.org/scripts/script.php?script_id=2900
 [GitHub]: http://github.com/tmatilai/gitolite.vim
--- a/doc/1000-words.mkd
+++ b/doc/1000-words.mkd
@ -1,4 +1,4 @@
-# gitolite in pictures
+# F=pictures gitolite in pictures
 Well, they say a picture speaks a thousand words, so here're a few!
@ -9,9 +9,7 @@ had to use Unicode 2010 for it.  I expect that I will have to resort to
 similar tricks for colon, equals, and many others like it if and when I need
 those in text within a ditaa diagram.
-<a name="_installation_and_setup"></a>
+## installation and setup
 ### installation and setup
 Here's a picture showing the "non-root" install.  We assume Alice is the
 gitolite admin, and "git" is the hosting user on the server.
@ -56,9 +54,7 @@ Note also that you only need ONE real user on the server.  In our example it
 is git.  In particular, you do NOT create Unix userids for your gitolite
 users.
-<a name="_adding_users_to_gitolite"></a>
+## adding users to gitolite
 ### adding users to gitolite
 Once you've done the install, here's how you add users.
@ -103,7 +99,7 @@ You do NOT need to add Carol or Bob as *real* (Unix) users.  You do NOT add
 their keys directly anywhere on the server; you do it by cloning, adding keys,
 and pushing.
-### adding repos to gitolite
+## adding repos to gitolite
 Adding a repo is even easier.  It's so easy that you don't really need a
 picture.  OK maybe a small one:
--- a/doc/admin-defined-commands.mkd
+++ b/doc/admin-defined-commands.mkd
@ -1,29 +1,6 @@
-## admin defined commands
+# F=ADCs admin defined commands
----
+## ADC background
 In this document:
  * <a href="#_background">background</a>
  * <a href="#_details">details</a>
      * <a href="#_installing_ADCs">installing ADCs</a>
      * <a href="#_user_invocation">user invocation</a>
      * <a href="#_checking_authorisation">checking authorisation</a>
      * <a href="#_checking_arguments">checking arguments</a>
      * <a href="#_passing_unchecked_arguments">passing unchecked arguments</a>
  * <a href="#_fake_repos_and_access_control_for_non_git_programs">"fake" repos and access control for non-git programs</a>
  * <a href="#_anatomy_of_a_command">anatomy of a command</a>
  * <a href="#_example_uses_and_sample_commands_in_contrib_adc_">example uses and sample commands in `contrib/adc`</a>
      * <a href="#_fork">fork</a>
      * <a href="#_deleting_trashing_repos">deleting/trashing repos</a>
      * <a href="#_enable_disable_push_access_temporarily">enable/disable push access temporarily</a>
  * <a href="#_how_this_feature_came_about">how this feature came about</a>
 ----
 <a name="_background"></a>
 ### background
 The admin-defined commands (ADCs) feature allows controlled access to
 specific, "safe", programs or scripts, without giving users full shell access.
@ -36,17 +13,11 @@ but an extra pair of eyes never hurt, so please review before use.
 <font color="gray">Although this is a generic way to allow pretty much any
 command to be run, most of the examples and sample ADCs pertain to allowing
 users to manage their "own" repos.  If that's your use case, please read
-[doc/wildcard-repositories.mkd][wild] before you continue here.</font>
+the [wildcard repositories][wild] doc before you continue here.</font>
-[wild]: http://sitaramc.github.com/gitolite/doc/wildcard-repositories.html
+## ADC details
-<a name="_details"></a>
+### installing ADCs
 ### details
 <a name="_installing_ADCs"></a>
 #### installing ADCs
 ADCs can only be installed by someone with shell access to the server; merely
 having push rights to the admin repo is not enough.
@ -63,18 +34,14 @@ This is by design.  So be careful what you name your scripts.
 However, it is perfectly ok, and may even be necessary in some cases, to name
 them after system executables (like 'rsync').
-<a name="_user_invocation"></a>
+### user invocation
 #### user invocation
 If you have a command called "foo" in that directory, then a user can invoke
 it by saying:
    ssh git@server foo argument list
-<a name="_checking_authorisation"></a>
+### checking authorisation inside an ADC
 #### checking authorisation
 Once an ADC is installed, *all* users can run it.  But sometimes you want only
 some people to be able to do so.
@ -87,17 +54,13 @@ repo, which is an easy way of making sure an ADC is only run by admins.
 See the section on "the anatomy of a command" later for this and many more
 details.
-<a name="_checking_arguments"></a>
+### checking arguments
 #### checking arguments
 Gitolite will call an ADC only if the arguments passed to it match a very
 strict pattern (see `$ADC_CMD_ARGS_PATT` in `src/gitolite_rc.pm`).  This
 reduces the risk of various kinds of shell-meta related compromises.
-<a name="_passing_unchecked_arguments"></a>
+### passing unchecked arguments
 #### passing unchecked arguments
 Some commands need arguments with a broader range of characters than
 `$ADC_CMD_ARGS_PATT` will allow.  As long as you are sure those commands are
@ -107,9 +70,7 @@ arguments**.
 The "ua" stand for "unchecked arguments".  Consider this your last warning ;-)
-<a name="_fake_repos_and_access_control_for_non_git_programs"></a>
+## "fake" repos and access control for non-git programs
 ### "fake" repos and access control for non-git programs
 A "fake" repo is a repo that exists in the config file but is specially named
 (starts with "EXTCMD/") so that gitolite will not create an actual repo on
@ -126,9 +87,7 @@ server has sufficient information to decide.  Protocols where the command line
 is just one word and everything else happens in the conversation later cannot
 be helped by this mechanism.</font>
-<a name="_anatomy_of_a_command"></a>
+## anatomy of a command
 ### anatomy of a command
 You can do whatever you want in an ADC!  It's upto you to check the
 permissions of *each* repo that the user is manipulating using your ADC --
@ -176,13 +135,9 @@ convenient.  See any of the other samples for how to use it.
 If you prefer perl, there is a nicely commented example in
 `contrib/adc/get-rights-and-owner.in-perl`.
-<a name="_example_uses_and_sample_commands_in_contrib_adc_"></a>
+## example uses and sample commands in `contrib/adc`
-### example uses and sample commands in `contrib/adc`
+### #fork the 'fork' ADC
 <a name="_fork"></a>
 #### fork
 A user would use the fork command like this:
@ -206,19 +161,11 @@ the client side:
 or some such incantation.
-<a name="rmrepo"></a>
+### deleting/trashing repos
-<a name="_deleting_trashing_repos"></a>
+See the [repo-deletion document][wild_repodel] for details about this.
-#### deleting/trashing repos
+### #able enable/disable push access temporarily
 See the [repo-deletion document][rdR] for details about this.
 [rdR]: http://sitaramc.github.com/gitolite/contrib/adc/repo-deletion.html
 <a name="_enable_disable_push_access_temporarily"></a>
 #### enable/disable push access temporarily
 If you want to disable push access to gitolite temporarily (maybe for
 maintenance), anyone with write access to the gitolite-admin repo can do this:
@ -233,15 +180,9 @@ You can also do this for one or more individual repos; in place of `@all`,
 just use a space separated list of reponames (exactly as they would appear in
 the config file).  Wildcards are not supported; patches welcome ;-)
-Note: please see [this][diswr] for more on this.
+Note: please see [this][disable] for more on this.
-[diswr]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html#_disabling_write_access_to_take_backups
+## how the ADC feature came about
 ----
 <a name="_how_this_feature_came_about"></a>
 ### how this feature came about
 <font color="gray">
--- a/doc/2-admin.mkd
+++ b/doc/2-admin.mkd
@ -1,26 +1,6 @@
-# administering and running gitolite
+# F=admin administering and running gitolite
-In this document:
+## please read this first
  * <a href="#_please_read_this_first">please read this first</a>
  * <a href="#_adding_users_and_repos">adding users and repos</a>
  * <a href="#_using_hooks">using hooks</a>
      * <a href="#_custom_hooks">custom hooks</a>
      * <a href="#_gl_post_init_hook">"gl-post-init" hook</a>
      * <a href="#_gl_pre_git_hook">"gl-pre-git" hook</a>
      * <a href="#_hook_chaining">hook chaining</a>
      * <a href="#_environment_variables_available_to_hooks">environment variables available to hooks</a>
  * <a href="#_other_features">other features</a>
      * <a href="#_moving_pre_existing_repos_into_gitolite">moving pre-existing repos into gitolite</a>
      * <a href="#_moving_the_whole_thing_from_one_server_to_another">moving the whole thing from one server to another</a>
      * <a href="#_specifying_gitweb_and_daemon_access">specifying gitweb and daemon access</a>
      * <a href="#_custom_git_config">custom git config</a>
 ----
 <a name="_please_read_this_first"></a>
 ### please read this first
 Unless you know what you're doing, do not do **anything** manually on the
 server (except when the documentation says you should, for example to add
@ -46,9 +26,7 @@ Either way, make sure you `cd` into this clone first.
 Once you've cloned it, you're ready to add users and repos.
-<a name="_adding_users_and_repos"></a>
+## F=add adding users and repos
 ### adding users and repos
 Do **NOT** add repos or users directly on the server!  You MUST manage the
 server by cloning the special 'gitolite-admin' repo on your workstation (`git
@ -67,23 +45,20 @@ section tells you how to add users and repos.
    if you wish, since the entire tree is searched.
  * edit the config file (`conf/gitolite.conf` in your admin repo clone).  See
-    [doc/gitolite.conf.mkd][confmkd] in the gitolite source for details on
+    the [gitolite.conf][conf] documentation for details on what goes in that
-    what goes in that file, syntax, etc.  Just add new repos as needed, and
+    file, syntax, etc.  Just add new repos as needed, and add new users and
-    add new users and give them permissions as required.  The users names
+    give them permissions as required.  The users names should be exactly the
-    should be exactly the same as their keyfile names, but without the `.pub`
+    same as their keyfile names, but without the `.pub` extension
    extension
  * when done, commit your changes and push.  Any new repos you specified will
    automatically be created (empty, but clonable) and users' access will be
    updated as needed.
-<a name="_using_hooks"></a>
+[genpub]: http://sitaramc.github.com/0-installing/2-access-gitolite.html#generating_a_public_key
-### using hooks
+## F=hooks using hooks
-<a name="_custom_hooks"></a>
+### #customhooks custom hooks
 #### custom hooks
 You can supply your own, custom, hook scripts if you wish.  Install gitolite
 as usual, then:
@ -104,37 +79,7 @@ that you had previously installed.
  * Do not under any conditions put anything in `hooks/gitolite-admin` --
    nothing in gitolite requires you to do anything here.  Leave it alone!
-<a name="_gl_post_init_hook"></a>
+### #hookchaining hook chaining
 #### "gl-post-init" hook
 Sometimes it is necessary to do something whenever a new repo is created.  If
 you need this functionality, just supply a hook called "gl-post-init" with
 whatever code you want in it.
 <a name="_gl_pre_git_hook"></a>
 #### "gl-pre-git" hook
 Although git has lots of nice hooks you can tap into, they all run only on a
 push.  There's nothing that runs on a fetch or a clone, and there's no way to
 run something *before* git-receive-pack or git-upload-pack, (as the case may
 be) are invoked.
 That's what the `gl-pre-git` hook is for.  If an executable hook called
 `gl-pre-git` is present, it will be invoked with the current directory set to
 `repo.git`, and with a single argument which will be either `R` or `W`
 depending on what the client is trying to do.  The environment variables
 `GL_USER` and `GL_REPO` are available.  STDOUT will be forced to STDERR before
 it is called, to avoid confusing the client.
 If the code returns anything other than 0, gitolite will terminate the
 operation (i.e., not run git at all), just like many git hooks do, so make
 sure you end with `exit 0` or equivalent.
 <a name="_hook_chaining"></a>
 #### hook chaining
 Sometimes you need to use git hooks for your own purposes (site-local
 validations, CI integration, email notifications, or the ever popular "live
@ -183,9 +128,7 @@ Finally, these names ('update.secondary' and 'post-update.secondary') are
 merely the defaults.  You can change them to anything you want; look in
 conf/example.gitolite.rc for details.
-<a name="_environment_variables_available_to_hooks"></a>
+### environment variables available to hooks
 #### environment variables available to hooks
 The following environment variables are set, and may be useful for any custom
 processing you wish to do in your hook code:
@ -199,13 +142,33 @@ The following variables are also set, but are generally less useful:
  * `GL_BINDIR` -- where all the binaries live
  * `GL_ADMINDIR` -- common directory for many gitolite things
-<a name="_other_features"></a>
+### "gl-post-init" hook
-### other features
+Sometimes it is necessary to do something whenever a new repo is created.  If
 you need this functionality, just supply a hook called "gl-post-init" with
 whatever code you want in it.
-<a name="_moving_pre_existing_repos_into_gitolite"></a>
+### "gl-pre-git" hook
-#### moving pre-existing repos into gitolite
+Although git has lots of nice hooks you can tap into, they all run only on a
 push.  There's nothing that runs on a fetch or a clone, and there's no way to
 run something *before* git-receive-pack or git-upload-pack, (as the case may
 be) are invoked.
 That's what the `gl-pre-git` hook is for.  If an executable hook called
 `gl-pre-git` is present, it will be invoked with the current directory set to
 `repo.git`, and with a single argument which will be either `R` or `W`
 depending on what the client is trying to do.  The environment variables
 `GL_USER` and `GL_REPO` are available.  STDOUT will be forced to STDERR before
 it is called, to avoid confusing the client.
 If the code returns anything other than 0, gitolite will terminate the
 operation (i.e., not run git at all), just like many git hooks do, so make
 sure you end with `exit 0` or equivalent.
 ## other features
 ### F=moverepos moving pre-existing repos into gitolite
 It's best to split this into different use cases.
@ -254,10 +217,8 @@ Assuming you can group your repo names into various patterns, and can use
 similar access control lines within each such group, you can use gitolite's
 "wildcard repos" feature.
-[wild]: http://sitaramc.github.com/gitolite/doc/wildcard-repositories.html
+First read the [wildcard repositories][wild] document, or at least skim
-
+through it, to understand the basic concept.  Then do this:
 First read [doc/wildcard-repositories.mkd][wild], or at least skim through it,
 to understand the basic concept.  Then do this:
  * do step 1 just like step 1 in Case 2 above
@ -294,7 +255,7 @@ to understand the basic concept.  Then do this:
  * what's with the `gl-creater` file in case 3?
-    What [doc/wildcard-repositories.mkd][wild] does not explain is how
+    What the [wildcard repositories][wild] document does not explain is how
    ownership is *recorded* in gitolite: the `gl-creater` file contains the
    owner name.  If you want to "pretend" these repos were created by some
    user, you need to add that in.  That user then gets whatever access you
@ -313,9 +274,7 @@ In the end, it all boils down to (a) making sure the `update` hook is correct
 on all repos, wild or normal, and (b) making sure `gl-creater` contains the
 owner name for wild repos.  The rest of the setup is in the conf file.
-<a name="_moving_the_whole_thing_from_one_server_to_another"></a>
+### F=moveserver moving the whole thing from one server to another
 #### moving the whole thing from one server to another
 [**NOTE**: I would appreciate help testing these instructions]
@ -391,83 +350,12 @@ if things are not clear -- you can help me fine tune this document :-)
 And that should be that!
-<a name="gwd"></a>
+### custom git config
 <a name="_specifying_gitweb_and_daemon_access"></a>
 #### specifying gitweb and daemon access
 This is a feature that I personally do not use (corporate environments don't
 like unauthenticated access of any kind to any repo!), but someone wanted it,
 so here goes.
 Gitolite has two pre-defined, "special", usernames: `daemon` and `gitweb`.
 To make a repo or repo group accessible via "git daemon", just give read
 permission to the special user "daemon".  Similarly, give read permission to
 `gitweb` to allow the gitweb CGI to show the repo.  Something like this:
    repo    foo bar baz
        R   =   gitweb daemon
 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:
    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:
    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:
  * for daemon, create the file `git-daemon-export-ok` in the repository
  * for gitweb, add the repo (plus owner name, if given) to the list of
    projects to be served by gitweb (see the config file variable
    `$PROJECTS_LIST`, which should have the same value you specified for
    `$projects_list` when setting up gitweb)
  * put the description, if given, in `$repo/description`
 The "compile" script will keep these files consistent with the config settings
 -- this includes removing such settings/files if you remove "read" permissions
 for the special usernames or remove the description line.
 Please **note** that giving permissions to these special users via `@all`
 (that is, using either `repo @all` or `R = @all`), will not work unless you
 set the rc-file variable `$GL_ALL_INCLUDES_SPECIAL` to `1`.  Also, **NOTE**
 that giving them read access to `repo @all` means the `gitolite-admin` repo is
 also accessible.  **It is upto you to decide if that is OK in your
 environment**.
 <a name="_custom_git_config"></a>
 #### custom git config
 The custom hooks feature is a blunt instrument -- all repos get the hook you
-specified and will run it.  In order to make it a little more fine-grained,
+specified and will run it.  You can of course install hooks manually on the
-you could set your hooks to only work if a certain "gitconfig" variable was
+server, but sometimes that's cumbersome.
 set.  Which means we now need a way to specify "git config" settings on a per
 repository basis.
-Thanks to Teemu (teemu dot matilainen at iki dot fi), gitolite now does this
+Instead, you could set your hooks to only work if a certain "gitconfig"
-very easily.  For security reasons, this can only be done from the master
+variable was set.  See [this][rsgc] for a way to specify "git config"
-config file (i.e., if you're using delegation, the delegated admins cannot
+settings on a per repository basis.
 specify git config settings).
 Please see `doc/gitolite.conf.mkd` for syntax and limitations.  Also note that
 this feature is disabled by default.  Read the comments on a variable called
 `GL_GITCONFIG_KEYS` in the rc file documentation, then set it to some
 appropriate value, to enable this feature.
 [genpub]: http://sitaramc.github.com/0-installing/2-access-gitolite.html#generating_a_public_key
 [confmkd]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html
--- a/doc/authentication-vs-authorisation.mkd
+++ b/doc/authentication-vs-authorisation.mkd
@ -1,13 +1,9 @@
-# authentication versus authorisation
+# F=auth authentication versus authorisation
 This document will explain why an "ssh issue" is almost never a "gitolite
 issue", and, indirectly, why I dont get too excited about the former.
-Note: for actual ssh troubleshooting see [this][glsts].
+Note: for actual ssh troubleshooting see [this][sts].
 [glsts]: http://sitaramc.github.com/gitolite/doc/ssh-troubleshooting.html
 ----
 Here is a fundamental point: <font color="red">**Gitolite does not do
 authentication.  It only does authorisation**.</font>
@ -22,7 +18,7 @@ So first, let's loosely define these words:
 >   **Authorisation** is the process of asking what you want to do and
 >   deciding if you're allowed to do it or not.
-Now, if you managed to read [doc/gitolite-and-ssh.mkd][gas], you know that
+Now, if you managed to read about [gitolite and ssh][gl_ssh], you know that
 gitolite is meant to be invoked as:
    /full/path/to/gl-auth-command some-authenticated-gitolite-username
@ -32,26 +28,18 @@ be, and usually *isn't*, an actual *unix* username).
 As you can see, authentication happens before gitolite is called.
-[gas]: http://sitaramc.github.com/gitolite/doc/gitolite-and-ssh.html
+## but... but... you have all that ssh stuff in there!
 <a name="_but_but_you_have_all_that_ssh_stuff_in_there_"></a>
 ### but... but... you have all that ssh stuff in there!
 The default mode of using gitolite does use ssh keys, but all it's doing is
 helping you **setup** ssh-based authentication **as a convenience to you**.
 You don't have to use it, though.  And many people don't.  The examples I know
-are [smart http][sh], and ldap-backed sshd.  In both cases, gitolite has no
+are [smart http][http], and ldap-backed sshd.  In both cases, gitolite has no
 role to play in creating users, setting up their passwords/keys, etc.  There's
 even a `GL_NO_SETUP_AUTHKEYS` option to make sure gitolite doesn't meddle with
 the authkeys file in such installations.
-[sh]: http://sitaramc.github.com/gitolite/doc/http-backend.html
+## so you're basically saying you won't support "X"
 <a name="_so_you_re_basically_saying_you_won_t_support_X_"></a>
 ### so you're basically saying you won't support "X"
 (where "X" is some ssh related behaviour change or feature)
@ -64,9 +52,7 @@ Even if you locked yourself (the admin) out, the docs tell you how to recover
 from such errors.  You do need some password based method to get a shell
 command line on the server, of course.
-<a name="_appendix_how_to_use_other_authentication_systems_with_gitolite"></a>
+## appendix: how to use other authentication systems with gitolite
 ### appendix: how to use other authentication systems with gitolite
 The bottom line in terms of how to invoke gitolite has been described above,
 and as long as you manage to do that gitolite won't even know how the
@ -75,7 +61,7 @@ authentication scheme you want.
 It also expects the `SSH_ORIGINAL_COMMAND` environment variable to contain the
 full command (typically starting with git-receive-pack or git-upload-pack)
-that the client sent.  Also, when using [smart http][sh], things are somewhat
+that the client sent.  Also, when using [smart http][http], things are somewhat
 different: gitolite uses certain environment variables that it expects httpd
 to have set up.  Even the user name comes from the `REMOTE_USER` environment
 variable instead of as a command line argument in this case.
@ -101,4 +87,3 @@ which can be useful.
 Finally, gitolite allows you to store *group* information externally too.  See
 [here][ldap] for more on this.
 [ldap]: http://sitaramc.github.com/gitolite/doc/big-config.html#_storing_usergroup_information_outside_gitolite_like_in_LDAP_
--- a/doc/big-config.mkd
+++ b/doc/big-config.mkd
@ -1,27 +1,22 @@
-## what is a "big-config"
+# F=bc what is a "big-config"
-In this document:
+This document is just background info; you don't actually need to read the
 whole thing if you don't care.  All you need to do is set `BIG_CONFIG` to 1 in
 the rc file and you're done.  If you have no use for gitweb and daemon, you
 can save even more time by setting `GL_NO_DAEMON_NO_GITWEB`.
-  * <a href="#_when_why_do_we_need_it_">when/why do we need it?</a>
+Finally, if you're *really* an expert (or your initials are "JK"), you can
-  * <a href="#_how_do_we_use_it_">how do we use it?</a>
+even set `GL_NO_CREATE_REPOS` and `GL_NO_SETUP_AUTHKEYS`.  However, be warned
-      * <a href="#_access_rules_for_groups">access rules for groups</a>
+that if you're not sufficiently clueful, those last 2 variables could have a
-      * <a href="#_access_rules_for_individual_repos_split_config_">access rules for individual repos (split config)</a>
+[security impact][rcsecurity].
  * <a href="#_other_optimisations">other optimisations</a>
      * <a href="#_disabling_various_defaults">disabling various defaults</a>
      * <a href="#_optimising_the_authkeys_file">optimising the authkeys file</a>
  * <a href="#_what_are_the_downsides_">what are the downsides?</a>
  * <a href="#_storing_usergroup_information_outside_gitolite_like_in_LDAP_">storing usergroup information outside gitolite (like in LDAP)</a>
      * <a href="#_why">why</a>
      * <a href="#_how">how</a>
  * <a href="#_implementation_notes">implementation notes</a>
-<a name="_when_why_do_we_need_it_"></a>
+## when/why do we need it?
 ### when/why do we need it?
 A "big config" is anything that has a few thousand users and a few thousand
 repos, resulting in a very large 'compiled' config file.
 ### the problem
 To understand the problem, consider what happens if you have something like
 this in your gitolite conf file:
@ -40,7 +35,259 @@ Without the 'big config' setting, gitolite internally translates this to:
 and then generates the actual config rules once for each user-repo-ref
 combination (there are 8 combinations above); the compiled config file looks
-somewhat like this:
+somewhat like [this][_bigno].
 Of course, the output is the same whether you used groups (like `@wbr` and
 `@devs` in the example above) or listed the repos directly on the 'repo'
 lines.
 Anyway, you can imagine what that does when you have 10,000 users and 10,000
 repos.  Let's just say it's not pretty :)
 ## how do we use it?
 Just set
    $GL_BIG_CONFIG = 1;
 in the `~/.gitolite.rc` file on the server (see next section for more
 variables).  When you do that, and push this configuration, one of two things
 happens.
 ### access rules for groups
 If you used group names in the 'repo' lines (as in `repo @wbr`), then the
 compiled config looks like [this][_bigyes].
 That's a lot smaller, and allows orders of magintude more repos and groups to
 be supported.
 ### access rules for individual repos (split config)
 If, on the other hand, you had the repos listed individually, (as in `repo
 lynx firefox`), then the main config file would now look like this:
    %repos = ();
    %split_conf = (
      'firefox' => 1,
      'lynx' => 1
    );
 And each individual repo's configuration would go its own directory.  For
 instance, `~/repositories/lynx.git/gl-conf` would look like this:
    %one_repo = (
      'lynx' => {
        'R' => {
          'alice' => 1,
          'bob' => 1
        },
        'W' => {
          'alice' => 1,
          'bob' => 1
        },
        'alice' => [
          [
            0,
            'refs/heads/next',
            'RW+'
          ],
          [
            4,
            'refs/heads/master',
            'RW'
          ]
        ],
        'bob' => [
          [
            1,
            'refs/heads/next',
            'RW+'
          ],
          [
            5,
            'refs/heads/master',
            'RW'
          ]
        ]
      }
    );
 That does not reduce the overall size of the repo config (because you did not
 group the repos), but the main repo config is now even smaller!
 ## what are the downsides?
 There are some downsides.
 The following apply if individual ("split") conf files are written, which in
 turn only happens if you used repo names instead of group names on the `repo`
 lines:
  * the compile (gitolite-admin push) is now slower, because it potentially
    has to write a few thousand small files instead of one large one.  Since
    the compile should be relatively infrequent compared to developer access,
    this is ok -- the main config file is parsed much faster now, so every hit
    to the server will benefit.
  * we can no longer distinguish 'repo not found on disk' from 'you dont have
    access'.  They both now look like 'you dont have access'.
 ## other optimisations
 ### disabling various defaults
 The default RC file contains the following lines (we've already discussed the
 first one):
    $GL_BIG_CONFIG = 0;
    $GL_NO_DAEMON_NO_GITWEB = 0;
    $GL_NO_CREATE_REPOS = 0;
    $GL_NO_SETUP_AUTHKEYS = 0;
 `GL_NO_DAEMON_NO_GITWEB` is a very useful optimisation that you *must* enable
 if you *do* have a large number of repositories, and do *not* use gitolite's
 support for gitweb or git-daemon access (see "[this][gwd]" for details).  This will save a
 lot of time when you push the gitolite-admin repo with changes.  This variable
 also controls whether "git config" lines (such as `config hooks.emailprefix =
 "[gitolite]"`) will be processed or not.
 You should be a lot more careful with `GL_NO_CREATE_REPOS` and
 `GL_NO_SETUP_AUTHKEYS`.  These are meant for installations where some backend
 system already exists that does all the actual repo creation, (including
 setting up the proper hooks -- very important for access control), and all the
 authentication setup (ssh auth keys), respectively.
 Summary: Please **leave those two variables alone** unless you're initials are
 "JK" ;-)
 ### #authkeyopt optimising the authkeys file
 Sshd does a linear scan of the `~/.ssh/authorized_keys` file when an incoming
 connection shows up.  This means that keys found near the top get served
 faster than keys near the bottom.  On my laptop, it takes about 2500 keys
 before I notice the delay; on a typical server it could be double that, so
 don't worry about all this unless your user-count is in that range.
 One way to deal with 5000+ keys is to use customised, database-backed ssh
 daemons, but many people are uncomfortable with taking non-standard versions
 of such a critical piece of the security infrastructure.  In addition, most
 distributions do not make it painless to use them.
 So what do you do?
 The following trick uses the Pareto principle (a.k.a the "80-20 rule")
 to get an immediate boost in response for the most frequent or prolific
 developers.  It can allow you to ignore the problem until the next big
 increase in your user counts!
 Here's how:
  * create subdirectories of keydir/ called 0, 1, (maybe 2, 3, etc., also),
    and 9.
  * in 0/, put in the pubkeys of the most frequent users
  * in 1/, add the next most important set of users, and so on for 2, 3, etc.
  * finally, put all the rest in 9/
 Make sure "9" contains at least 70-90% of the total number of pubkeys,
 otherwise this doesn't really help.
 You can easily determine who your top users are by runnning something like
 this (note the clever date command that always gets you last months log file!)
    cat .gitolite/logs/gitolite-`date +%Y-%m -d -30days`.log |
        cut -f2 | sort | uniq -c | sort -n -r
 ## F=ldap storing usergroup information outside gitolite (like in LDAP)
 [Please NOTE: this is all about *user* groups, not *repo* groups]
 [WARNING: the earlier method of doing this has been discontinued; please see
 the commit message for details]
 Gitolite now allows usergroup information to be stored outside its own config
 file.  We'll see "why" first, then the "how".
 ### #_ldapwhy why
 Large sites often have LDAP servers that already contain user and group
 information, including group membership details.  Such sites may prefer that
 gitolite just pick up that info instead of having to redundantly put it in
 gitolite's config file.
 Consider this example config for one repo:
    repo foo
        RW+ =   @lead_devs
        RW  =   @devs
        R   =   @interns
 Normally, you would also need to specify:
    @lead_devs  =   dilbert alice
    @devs       =   wally
    @interns    =   ashok
 However, if the corporate LDAP server already tags these people correctly, and
 if there is some way of getting that information out **at run time**, that
 would be cool.
 ### #_ldaphow how
 All you need is a script that, given a username, queries your LDAP or similar
 server, and returns a space-separated list of all the groups she is a member
 of.  If an invalid user name is sent in, or the user is valid but is not part
 of any groups, it should print nothing.
 This script will probably be specific to your site.  (See contrib/ldap for some
 example scripts that were contributed by the Nokia MeeGo team.)
 Then set the `$GL_GET_MEMBERSHIPS_PGM` variable in the rc file to the full
 path of this program, set `$GL_BIG_CONFIG` to 1, and that will be that.
 ## implementation notes
 To understand how big-config works (at least when you're using grouped repos),
 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.
 ## config listings
 ### F=_bigno compiled config with big-config disabled
    %repos = (
      'firefox' => {
@ -115,31 +362,7 @@ somewhat like this:
 Phew!
-Of course, the output is the same whether you used groups (like `@wbr` and
+### F=_bigyes compiled config with big-config enabled
 `@devs` in the example above) or listed the repos directly on the 'repo'
 lines.
 Anyway, you can imagine what that does when you have 10,000 users and 10,000
 repos.  Let's just say it's not pretty :)
 <a name="_how_do_we_use_it_"></a>
 ### how do we use it?
 Just set
    $GL_BIG_CONFIG = 1;
 in the `~/.gitolite.rc` file on the server (see next section for more
 variables).  When you do that, and push this configuration, one of two things
 happens.
 <a name="_access_rules_for_groups"></a>
 #### access rules for groups
 If you used group names in the 'repo' lines (as in `repo @wbr`), then the
 compiled config looks like this:
    %repos = (
      '@wbr' => {
@ -173,249 +396,3 @@ compiled config looks like this:
        'lynx' => 'master'
      }
    );
 That's a lot smaller, and allows orders of magintude more repos and groups to
 be supported.
 <a name="_access_rules_for_individual_repos_split_config_"></a>
 #### access rules for individual repos (split config)
 If, on the other hand, you had the repos listed individually, (as in `repo
 lynx firefox`), then the main config file would now look like this:
    %repos = ();
    %split_conf = (
      'firefox' => 1,
      'lynx' => 1
    );
 And each individual repo's configuration would go its own directory.  For
 instance, `~/repositories/lynx.git/gl-conf` would look like this:
    %one_repo = (
      'lynx' => {
        'R' => {
          'alice' => 1,
          'bob' => 1
        },
        'W' => {
          'alice' => 1,
          'bob' => 1
        },
        'alice' => [
          [
            0,
            'refs/heads/next',
            'RW+'
          ],
          [
            4,
            'refs/heads/master',
            'RW'
          ]
        ],
        'bob' => [
          [
            1,
            'refs/heads/next',
            'RW+'
          ],
          [
            5,
            'refs/heads/master',
            'RW'
          ]
        ]
      }
    );
 That does not reduce the overall size of the repo config (because you did not
 group the repos), but the main repo config is now even smaller!
 <a name="_other_optimisations"></a>
 ### other optimisations
 <a name="_disabling_various_defaults"></a>
 #### disabling various defaults
 The default RC file contains the following lines (we've already discussed the
 first one):
    $GL_BIG_CONFIG = 0;
    $GL_NO_DAEMON_NO_GITWEB = 0;
    $GL_NO_CREATE_REPOS = 0;
    $GL_NO_SETUP_AUTHKEYS = 0;
 `GL_NO_DAEMON_NO_GITWEB` is a very useful optimisation that you *must* enable
 if you *do* have a large number of repositories, and do *not* use gitolite's
 support for gitweb or git-daemon access (see "[this][gwd]" for details).  This will save a
 lot of time when you push the gitolite-admin repo with changes.  This variable
 also controls whether "git config" lines (such as `config hooks.emailprefix =
 "[gitolite]"`) will be processed or not.
 You should be a lot more careful with `GL_NO_CREATE_REPOS` and
 `GL_NO_SETUP_AUTHKEYS`.  These are meant for installations where some backend
 system already exists that does all the actual repo creation, (including
 setting up the proper hooks -- very important for access control), and all the
 authentication setup (ssh auth keys), respectively.
 Summary: Please **leave those two variables alone** unless you're initials are
 "JK" ;-)
 <a name="_optimising_the_authkeys_file"></a>
 #### optimising the authkeys file
 Sshd does a linear scan of the `~/.ssh/authorized_keys` file when an incoming
 connection shows up.  This means that keys found near the top get served
 faster than keys near the bottom.  On my laptop, it takes about 2500 keys
 before I notice the delay; on a typical server it could be double that, so
 don't worry about all this unless your user-count is in that range.
 One way to deal with 5000+ keys is to use customised, database-backed ssh
 daemons, but many people are uncomfortable with taking non-standard versions
 of such a critical piece of the security infrastructure.  In addition, most
 distributions do not make it painless to use them.
 So what do you do?
 The following trick uses the Pareto principle (a.k.a the "80-20 rule")
 to get an immediate boost in response for the most frequent or prolific
 developers.  It can allow you to ignore the problem until the next big
 increase in your user counts!
 Here's how:
  * create subdirectories of keydir/ called 0, 1, (maybe 2, 3, etc., also),
    and 9.
  * in 0/, put in the pubkeys of the most frequent users
  * in 1/, add the next most important set of users, and so on for 2, 3, etc.
  * finally, put all the rest in 9/
 Make sure "9" contains at least 70-90% of the total number of pubkeys,
 otherwise this doesn't really help.
 You can easily determine who your top users are by runnning something like
 this (note the clever date command that always gets you last months log file!)
    cat .gitolite/logs/gitolite-`date +%Y-%m -d -30days`.log |
        cut -f2 | sort | uniq -c | sort -n -r
 <a name="_what_are_the_downsides_"></a>
 ### what are the downsides?
 There are some downsides.
 The following apply if individual ("split") conf files are written, which in
 turn only happens if you used repo names instead of group names on the `repo`
 lines:
  * the compile (gitolite-admin push) is now slower, because it potentially
    has to write a few thousand small files instead of one large one.  Since
    the compile should be relatively infrequent compared to developer access,
    this is ok -- the main config file is parsed much faster now, so every hit
    to the server will benefit.
  * we can no longer distinguish 'repo not found on disk' from 'you dont have
    access'.  They both now look like 'you dont have access'.
 <a name="_storing_usergroup_information_outside_gitolite_like_in_LDAP_"></a>
 ### storing usergroup information outside gitolite (like in LDAP)
 [Please NOTE: this is all about *user* groups, not *repo* groups]
 [WARNING: the earlier method of doing this has been discontinued; please see
 the commit message for details]
 Gitolite now allows usergroup information to be stored outside its own config
 file.  We'll see "why" first, then the "how".
 <a name="_why"></a>
 #### why
 Large sites often have LDAP servers that already contain user and group
 information, including group membership details.  Such sites may prefer that
 gitolite just pick up that info instead of having to redundantly put it in
 gitolite's config file.
 Consider this example config for one repo:
    repo foo
        RW+ =   @lead_devs
        RW  =   @devs
        R   =   @interns
 Normally, you would also need to specify:
    @lead_devs  =   dilbert alice
    @devs       =   wally
    @interns    =   ashok
 However, if the corporate LDAP server already tags these people correctly, and
 if there is some way of getting that information out **at run time**, that
 would be cool.
 <a name="_how"></a>
 #### how
 All you need is a script that, given a username, queries your LDAP or similar
 server, and returns a space-separated list of all the groups she is a member
 of.  If an invalid user name is sent in, or the user is valid but is not part
 of any groups, it should print nothing.
 This script will probably be specific to your site.  (See contrib/ldap for some
 example scripts that were contributed by the Nokia MeeGo team.)
 Then set the `$GL_GET_MEMBERSHIPS_PGM` variable in the rc file to the full
 path of this program, set `$GL_BIG_CONFIG` to 1, and that will be that.
 [gwd]: http://sitaramc.github.com/gitolite/doc/2-admin.html#gwd
 <a name="_implementation_notes"></a>
 ### implementation notes
 To understand how big-config works (at least when you're using grouped repos),
 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.
--- a/doc/delegation.mkd
+++ b/doc/delegation.mkd
@ -1,20 +1,8 @@
-## delegating access control responsibilities
+# F=deleg delegating access control responsibilities
 In this document:
  * <a href="#_lots_of_repos_lots_of_users">lots of repos, lots of users</a>
  * <a href="#_how_to_use_delegation">how to use delegation</a>
      * <a href="#_the_subconf_command">the subconf command</a>
      * <a href="#_backward_compatibility">backward compatibility</a>
  * <a href="#_security_notes">security notes</a>
      * <a href="#_group_names">group names</a>
      * <a href="#_delegating_pubkeys">delegating pubkeys</a>
 ----
-<a name="_lots_of_repos_lots_of_users"></a>
+## lots of repos, lots of users
 ### 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.  It lets you specify bits and
@ -39,9 +27,7 @@ for a set of repos to be specified in a **subconf** file and allow someone (a
 **sub-admin**) to make changes within that file.  (Note: sub-admins cannot
 create or remove users).
-<a name="_how_to_use_delegation"></a>
+## how to use delegation
 ### how to use delegation
 First, you group your repos however you want.  In the example below, I'm
 considering firefox and lynx (projects at the root of the gitolite server) as
@ -89,9 +75,7 @@ commit and push.
 And that's really all there is to it.
-<a name="_the_subconf_command"></a>
+### #subconf the subconf command
 #### the subconf command
 This command is much like the "include" command, but in addition it checks
 that a subconf does not contain ACL rules for repos that are outside its
@ -112,9 +96,7 @@ In more precise terms:
 (Additional notes: it can also contain lines for an actual repo called
 `webbrowsers`, or, in big-config mode, for a group called `@webbrowsers`).
-<a name="_backward_compatibility"></a>
+### backward compatibility
 #### backward compatibility
 For backward compatibility, if no `subconf` commands have been seen at the end
 of processing the main config file, gitolite pretends you appended
@ -123,13 +105,9 @@ of processing the main config file, gitolite pretends you appended
 to the end of the file.
-<a name="_security_notes"></a>
+## security notes
-### security notes
+### group names
 <a name="_group_names"></a>
 #### group names
 You can use "@group"s defined in the main config file but do not attempt to
 redefine or extend them in your own subconf file.  If you must extend a group
@ -141,9 +119,7 @@ redefine or extend them in your own subconf file.  If you must extend a group
 Group names you define in your subconf will not clash even if the exact same
 name is used in another subconf file, so you need not worry about that.
-<a name="_delegating_pubkeys"></a>
+### delegating pubkeys
 #### delegating pubkeys
 Short answer: not gonna happen.
--- a/doc/developer-notes.mkd
+++ b/doc/developer-notes.mkd
@ -1,22 +1,6 @@
-## developer/patch maintainer notes
+# F=dev_notes developer/patch maintainer notes
-In this document:
+## general stuff
  * <a href="#_general_stuff">general stuff</a>
  * <a href="#_the_rc_file">the rc file</a>
  * <a href="#_modules">modules</a>
  * <a href="#_that_bindir_thing">that 'bindir' thing</a>
      * <a href="#_from_perl">from perl</a>
      * <a href="#_from_shell">from shell</a>
      * <a href="#_OUTLIER_">OUTLIER!</a>
  * <a href="#_special_types_of_setups">special types of setups</a>
      * <a href="#_Fedora">Fedora</a>
 ----
 <a name="_general_stuff"></a>
 ### general stuff
  * all scripts and libraries must be in the same directory.  However, RPM/DEB
    packagers can put the libraries where they want, as long as they can be
@ -36,31 +20,23 @@ In this document:
    much all of them are run via gl-auth-command or from something that was
    forked from it so the variables *will* exist during normal operation.
-<a name="_the_rc_file"></a>
+## the rc file
 ### the rc file
 The 'rc' file has one major change from v1: any new values in the rc file need
 to be added to the @EXPORT list in `src/gitolite_rc.pm`.
-<a name="_modules"></a>
+## modules
 ### modules
 There are 3 "modules" (`gitolite_rc`, `gitolite_env`, and `gitolite` itself).
 Their purposes should be fairly obvious.
-<a name="_that_bindir_thing"></a>
+## that 'bindir' thing
 ### that 'bindir' thing
 The importance of `GL_BINDIR` is that the command= argument in
 `~/.ssh/authorized_keys` must be a full path, ideally, and the compile script
 gets this from `GL_BINDIR`.
-<a name="_from_perl"></a>
+### from perl
 #### from perl
  * for frequently run perl programs, I prefer my method
@ -73,9 +49,7 @@ gets this from `GL_BINDIR`.
      * gl-setup-authkeys (external shim to compile keys separately from PTA)
-<a name="_from_shell"></a>
+### from shell
 #### from shell
  * a perl program called gl-query-rc finds its own BINDIR (using my perl
    method, not FindBin).  This is suitable for calling from shell scripts
@ -85,22 +59,16 @@ gets this from `GL_BINDIR`.
      * gl-tool
      * gl-mirror-push
-<a name="_OUTLIER_"></a>
+### OUTLIER!
 #### OUTLIER!
  * gl-admin-push is an outlier.  For some silly reason I have the notion that
    even if it runs from /tmp it should get the right values, so it is the
    only one that interrogates `~/.ssh/authorized_keys` to get the actual
    BINDIR in use!
-<a name="_special_types_of_setups"></a>
+## special types of setups
-### special types of setups
+### Fedora
 <a name="_Fedora"></a>
 #### Fedora
 Fedora has a very special setup, as follows:
@ -138,8 +106,6 @@ fails, and you now have new code trying to work with old format data.
 The solution is to explicitly run a compile, from a properly privileged
 userid, as soon as you do an RPM upgrade.
 ----
 # **Why v2?**
 I went onto `#perl` to ask some question about setpriority() and got yelled at
--- a/doc/gitolite-and-ssh.mkd
+++ b/doc/gitolite-and-ssh.mkd
@ -1,14 +1,12 @@
-# how gitolite uses ssh
+# F=gl_ssh how gitolite uses ssh
-Although other forms of authentications exist (see
+Although other forms of authentications exist (see the document on
-[doc/authentication-vs-authorisation.mkd][ws]), ssh is the one that most git
+[authentication versus authorisation][auth]), ssh is the one that most git
 users use.
 ***Therefore, gitolite is (usually) heavily dependent on ssh***.
-[ws]: http://sitaramc.github.com/gitolite/doc/authentication-vs-authorisation.html
+Most people didn't realise this, and even if they did they don't know ssh
 Most people didn't realise this, and even if they did they didn't know ssh
 well enough to help themselves.  If you don't understand how ssh public key
 authentication works, or how the `~/.ssh/authorized_keys` file can be used to
 restrict users, etc., you will have endless amounts of trouble getting
@ -17,18 +15,7 @@ gitolite to work, because you'll be attacking the wrong problem.
 So please please please understand this before tearing your hair out and
 blaming ***git/gitolite*** for whatever is going wrong with your setup :-)
-In this document:
+## ssh basics
  * <a href="#_ssh_basics">ssh basics</a>
  * <a href="#_how_does_gitolite_use_all_this_ssh_magic_">how does gitolite use all this ssh magic?</a>
      * <a href="#_restricting_shell_access_distinguishing_one_user_from_another">restricting shell access/distinguishing one user from another</a>
      * <a href="#_restricting_branch_level_actions">restricting branch level actions</a>
 ----
 <a name="_ssh_basics"></a>
 ### ssh basics
 Let's start with some basics, focusing *only* on the pieces relevant to
 `gitolite`.  If this is not detailed enough, please use google and learn more
@ -98,9 +85,7 @@ from somewhere, or maybe buy the OReilly ssh book.
    **This is the backbone of what makes gitolite work; please make sure you
    understand this**.
-<a name="_how_does_gitolite_use_all_this_ssh_magic_"></a>
+## how does gitolite use all this ssh magic?
 ### how does gitolite use all this ssh magic?
 These are two different questions you ought to be having by now: 
@ -108,9 +93,7 @@ These are two different questions you ought to be having by now:
    logging in as the same remote user "git"
  * how does it restrict what I can do within a repository
-<a name="_restricting_shell_access_distinguishing_one_user_from_another"></a>
+### restricting shell access/distinguishing one user from another
 #### restricting shell access/distinguishing one user from another
 The answer to the first question is the `command=` we talked about before.  If
 you look in the `authorized_keys` file, you'll see entries like this (I chopped
@ -141,9 +124,7 @@ at its config file, and either allows or rejects the request.
 But this cannot differentiate between different branches within a repo; that
 has to be done separately.
-<a name="_restricting_branch_level_actions"></a>
+### restricting branch level actions
 #### restricting branch level actions
 [If you look inside the git source tree, there's a file among the "howto"s in
 there called `update-hook-example.txt`, which was the inspiration for this
--- a/doc/gitolite-gitweb-http-backend.mkd
+++ b/doc/gitolite-gitweb-http-backend.mkd
@ -1,30 +1,10 @@
-## how to set up gitolite+gitweb+ssh+http-backend
+# F=ggshb how to set up gitolite+gitweb+ssh+http-backend
-In this document:
+## NAME
  * <a href="#_NAME">NAME</a>
  * <a href="#_DESCRIPTION">DESCRIPTION</a>
  * <a href="#_EXAMPLE_ENVIRONMENT">EXAMPLE ENVIRONMENT</a>
  * <a href="#_GITOLITE_SETUP">GITOLITE SETUP</a>
      * <a href="#_gitolite_rc">gitolite.rc</a>
      * <a href="#_gitolite_conf">gitolite.conf</a>
  * <a href="#_APACHE_SETUP">APACHE SETUP</a>
      * <a href="#_suexec">suexec</a>
      * <a href="#_Gitweb">Gitweb</a>
      * <a href="#_Virtual_Host">Virtual Host</a>
  * <a href="#_VALIDATION">VALIDATION</a>
  * <a href="#_ADDITIONAL_RESOURCES">ADDITIONAL RESOURCES</a>
  * <a href="#_AUTHOR">AUTHOR</a>
 <a name="_NAME"></a>
 ### NAME
 gitolite-gitweb-http-backend
-<a name="_DESCRIPTION"></a>
+## DESCRIPTION
 ### DESCRIPTION
 You've been tasked with rolling out gitolite and git-web in your
 corporate environment and your requirements are as follows:
@ -37,9 +17,7 @@ corporate environment and your requirements are as follows:
 Note that these instructions are geared toward OpenSuSE 11.4.  Feel
 free to modify the examples below to your environment.
-<a name="_EXAMPLE_ENVIRONMENT"></a>
+## EXAMPLE ENVIRONMENT
 ### EXAMPLE ENVIRONMENT
 The following assumptions are made for the purposes of example:
@ -59,19 +37,13 @@ The following assumptions are made for the purposes of example:
      * engineering
      * operations
-<a name="_GITOLITE_SETUP"></a>
+## GITOLITE SETUP
 ### GITOLITE SETUP
 Install gitolite via your package management tools.  Under OpenSuSE, this will
-install repositories in `/srv/git`.  Follow the instructions found [here][1in]
+install repositories in `/srv/git`.  Follow the instructions found
-for initial set up.
+[here][install] for initial set up.
-[1in]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html
+### gitolite.rc
 <a name="_gitolite_rc"></a>
 #### gitolite.rc
 You will need to tell gitolite.rc about some additional keys that will
 be needed for each repository.  Make sure the following config option
@ -83,9 +55,7 @@ These options tell gitolite to allow the user to set these values in
 `gitolite.conf`, which in turn will be propagated to each
 repositories git config.
-<a name="_gitolite_conf"></a>
+### gitolite.conf
 #### gitolite.conf
 For the purposes of example, we assume that we have two groups accessing each repository: engineering and operations.  So, our `gitolite.conf` file will look something like this:
@ -131,17 +101,11 @@ For the purposes of example, we assume that we have two groups accessing each re
 Save, commit, and push your changes to the gitolite-admin repo as
 described [here][conf].
-[conf]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html
+## APACHE SETUP
 <a name="_APACHE_SETUP"></a>
 ### APACHE SETUP
 Under OpenSuSE 11.4, Apache runs as user `wwwrun` group `www` (see `/etc/apache2/uid.conf`).  But wait!  How can Apache running as `wwwrun` commit to git repositories, which are owned by `git`?
-<a name="_suexec"></a>
+### suexec
 #### suexec
 Enter SuExec.  This is an apache module that allows apache to run
 under the auspicious of a different user.  For this to work, we need
@ -195,9 +159,7 @@ Finally, make sure Apache loads the suexec module.  Under OpenSuSE,
 this would mean adding "suexec" to `APACHE_MODULES` in
 `/etc/sysconfig/apache2`.
-<a name="_Gitweb"></a>
+### Gitweb
 #### Gitweb
 As gitweb will now be run under the `git` user, all files must be
 under `/srv/www` as well.
@ -209,9 +171,7 @@ under `/srv/www` as well.
 Do not forget to point `$projectroot` in `/etc/gitweb.conf` to
 `/srv/git/projects`!
-<a name="_Virtual_Host"></a>
+### Virtual Host
 #### Virtual Host
 Configure your virtual host as follows:
@ -273,9 +233,7 @@ Configure your virtual host as follows:
    </VirtualHost>
-<a name="_VALIDATION"></a>
+## VALIDATION
 ### VALIDATION
 Once apache has been restarted, verify your configuration:
@ -285,9 +243,7 @@ Once apache has been restarted, verify your configuration:
 - Commit over ssh git@git.example.com
 - Commit over http
-<a name="_ADDITIONAL_RESOURCES"></a>
+## ADDITIONAL RESOURCES
 ### ADDITIONAL RESOURCES
 - [http://httpd.apache.org/docs/2.2/suexec.html](http://httpd.apache.org/docs/2.2/suexec.html) Apache suexec
 documentation
@ -296,8 +252,6 @@ git-http-backend(1) documentation
 - [https://git.wiki.kernel.org/index.php/Gitweb](https://git.wiki.kernel.org/index.php/Gitweb) git-web documentaiton
 - [http://sitaramc.github.com/gitolite/doc/http-backend.html](http://sitaramc.github.com/gitolite/doc/http-backend.html) gitolite http backend documentation
-<a name="_AUTHOR"></a>
+## AUTHOR
 ### AUTHOR
 Christopher M. Fuhrman << cfuhrman at panix dot com >>
--- a/doc/gitolite.conf-by-example.mkd
+++ b/doc/gitolite.conf-by-example.mkd
@ -1,4 +1,4 @@
-# gitolite.conf -- by example
+# F=conf_examples gitolite.conf -- by example
 I hate people who make statements like "I dont have time to learn".  People
 with that sort of attitude shouldn't use gitolite at all, and I refuse to
@ -23,15 +23,7 @@ asking me.
 that "rewind" actually means any of 3 different things so I'll say it only
 once.  It's upto you to have read that part also.
-[conf]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html
+## general notes
 ----
 [[TOC]]
 ----
 ### general notes
 Git branch/tag name **recap**: branches look like refs/heads/something, tags
 look like refs/tags/something.  When there is no ambiguity, we leave out the
@ -48,7 +40,7 @@ not going to discuss things like what characters are allowed in a username or
 reponame, how to write a comment line, how to write continuation lines (you
 can't), include files, and all such *lexical* issues.
-### extremely brief regex overview
+## F=regexov extremely brief regex overview
 Regexes are powerful.  Gitolite uses that power as much as it can.  If you
 can't handle that power, hire someone who can and become a manager.
@ -82,7 +74,7 @@ The previous token need not be a single character; you can use parens to make
 it longer.  `(foo)+` matches one or more "foo", (like "foo", "foofoo",
 "foofoofoo", etc.)
-### basic access control
+## F=exbac basic access control
    repo    gitolite-admin
            RW+                 =   sitaram
@ -160,9 +152,9 @@ Ashok is allowed to push version tags.  He can push any tag whose name starts
 with a "v", then a digit, like "v1", "v1.0", "v2.0rc1", etc., but not "v-1",
 "ver1".
-### advanced access control
+## F=exaac advanced access control
-#### "deny" rules
+### "deny" rules
 **Warning**: When using deny rules, the order of your rules matters, where
 earlier it did not.
@ -190,18 +182,7 @@ earlier.
    before the third one, and it has a `-` as the permission, so the push
    fails
-#### personal branches
+### #ruleaccum2 rule accumulation
 Personal branches exist **in a namespace** of their own.  The syntax is
        RW  personal/USER/  =   @staff
 where the "personal" can be anything you like (but cannot be empty), and the
 "/USER/" part is **necessary**.  A user "alice" can then push any branches
 inside `personal/alice/`.  Which means she can push `personal/alice/foo` and
 `personal/alice/bar`, but NOT `personal/alice`.
 #### splitting up rules into rulesets
 Rules accumulate.  Even when separated by rules for other repos.  They
 accumulate intuitively.  For example:
@ -225,12 +206,10 @@ has the **effective** ruleset, for repo foo, of
        RW  dev/USER/   =   @staff
        RW+ tmp/        =   @staff
-Just remember that if you use [deny rules][dr] anywhere then the *order of the
+Just remember that if you use [deny rules][deny] anywhere then the *order of the
 rules matters*!
-[dr]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html#_deny_rules
+### gitweb and daemon
 #### gitweb and daemon
 Gitolite does NOT do anything for gitweb and daemon access **except**
--- a/doc/gitolite.conf.mkd
+++ b/doc/gitolite.conf.mkd
@ -1,29 +1,4 @@
-# the access control file `gitolite.conf`
+# F=conf the access control file `gitolite.conf`
 In this document:
  * <a href="#_syntax">syntax</a>
      * <a href="#_continuation_lines">continuation lines</a>
      * <a href="#_include_files">include files</a>
  * <a href="#_basic_access_control">basic access control</a>
      * <a href="#_how_rules_are_matched">how rules are matched</a>
      * <a href="#_branches_tags_and_specifying_refex_es">branches, tags, and specifying "refex"es</a>
      * <a href="#_groups">groups</a>
          * <a href="#_the_special_all_group">the special `@all` group</a>
  * <a href="#_advanced_access_control">advanced access control</a>
      * <a href="#_creating_and_deleting_branches">creating and deleting branches</a>
      * <a href="#_deny_rules">"deny" rules</a>
          * <a href="#_warnings_and_required_reading">warnings and required reading</a>
          * <a href="#_deny_rules_for_refs_in_a_repo">"deny" rules for refs in a repo</a>
          * <a href="#_deny_rules_for_the_entire_repo">"deny" rules for the entire repo</a>
  * <a href="#_summary_permissions">summary: permissions</a>
  * <a href="#_virtual_ref_types">virtual "ref"-types</a>
  * <a href="#_other_tips">other tips</a>
      * <a href="#_personal_branches">personal branches</a>
      * <a href="#_splitting_up_rules_into_rulesets">splitting up rules into rulesets</a>
      * <a href="#_gitweb_and_daemon">gitweb and daemon</a>
      * <a href="#_repo_specific_git_config_commands">repo specific `git config` commands</a>
      * <a href="#_repo_owner_description_line_for_gitweb">repo owner/description line for gitweb</a>
 Gitolite has an advanced access control language that is designed to be
 powerful but easy to use.  Other objectives were that it should be even easier
@ -35,9 +10,7 @@ something as different as possible from the brain-dead, nausea-inducing
 This document describes the syntax and semantics of the access control rules
 and other configuration directives in the `gitolite.conf` file.
-<a name="_syntax"></a>
+## #syntax syntax
 ### syntax
 In general, everything is **space separated**; there are no commas,
 semicolons, etc., in the syntax.
@ -52,18 +25,14 @@ least one `.` (this allows you to use an email address as someone's username).
 Reponames can contain `/` characters (this allows you to put your repos in a
 tree-structure for convenience)
-<a name="_continuation_lines"></a>
+### continuation lines
 #### continuation lines
 There are no continuation lines -- gitolite does not process C-style
 backslash-escaped newlines as anything special.  However, the section on
 "groups" will tell you how you can break up large lists of names in a group
 definition into multiple lines.
-<a name="_include_files"></a>
+### include files
 #### include files
 Gitolite allows you to break up the configuration into multiple files and
 include them in the main file for convenience.
@ -86,11 +55,7 @@ Files that have been already processed once are skipped, with a warning.
 <font color="gray">Advanced users: `subconf`, a command that is very closely
 related to `include`, is documented [here][subconf].</font>
-[subconf]: http://sitaramc.github.com/gitolite/doc/delegation.html#_the_subconf_command
+## F=bac basic access control
 <a name="_basic_access_control"></a>
 ### basic access control
 Here's a very basic set of rules:
@ -137,18 +102,14 @@ by Linus and currently maintained by Junio.
 </font>
-<a name="_how_rules_are_matched"></a>
+### how rules are matched
 #### how rules are matched
 It's important to understand that there're two levels at which access control
-happens.  Please see [this][l2] for details, especially about the first level
+happens.  Please see [this][2levels] for details, especially about the first level
 check.  Much of the complexity applies only to the second level check, so that
 is all we will be discussing here.  This check is done by the update hook, and
 determines whether the push succeeds or fails.
 [l2]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html#_two_levels_of_access_rights_checking
 For basic permissions like this, matching is simple.  Gitolite already knows:
  * the user
@ -160,9 +121,7 @@ Gitolite goes down the list of rules matching the user, repo, and the ref.
 The first matching rule that has the permission you're looking for (`W` or
 `+`), results in success.  A fallthrough results in failure.
-<a name="_branches_tags_and_specifying_refex_es"></a>
+### branches, tags, and specifying "refex"es
 #### branches, tags, and specifying "refex"es
 One of the original goals of gitolite was to allow access control at the
 branch/tag (aka "ref") level.  The git source code contains a sample update
@ -219,9 +178,7 @@ looks like "refs/heads/foo", while a tag ref looks like "refs/tags/bar")
    "v1.0", "v2.0rc1", all match the criterion specified by `v[0-9]` because
    this is a prefix match only.
-<a name="_groups"></a>
+### groups
 #### groups
 Gitolite allows you to define **groups** of repos. users, or even refexes.  A
 group is semantically (but *not* syntactically) like a `#define` in C.  Here
@ -262,97 +219,37 @@ parsed in a single-pass, so later *additions* to a group name cannot affect
 earlier *uses* of it.  If you moved line 2 to the end, "@alldevs" would only
 have 6 names in it.
-<a name="_the_special_all_group"></a>
+#### the special `@all` group
 ##### the special `@all` group
 There's a special group called `@all` that includes all authenticated users
 when used as a username; you've seen examples of it earlier.
-[Advanced users: also see the entry for `GL_ALL_INCLUDES_SPECIAL` in
+Advanced users: also see the entry for `GL_ALL_INCLUDES_SPECIAL` in the
-[doc/gitolite.rc.mkd][rcdoc].]
+documentation for [`~/.gitolite.rc`][rc].
 When used as a reponame, it includes all repos.
-<a name="_advanced_access_control"></a>
+## F=aac advanced access control
 ### advanced access control
 The previous section is sufficient for most common needs, but gitolite can go
 a lot further than that.
-<a name="_creating_and_deleting_branches"></a>
+### #deny "deny" rules
-#### creating and deleting branches
+#### warnings and required reading
 Since the beginning of gitolite, `RW` gave the ability, not only to update,
 but to *create* a branch (that matched the refex).  Similarly, `RW+` meant
 being able to not only rewind, but also delete a ref.  Conceptually, a rewind
 is almost the same as a delete+push (the only difference I can see is if you
 had core.logAllRefUpdates set, which is *not* a default setting).
 However, there seem to be cases where it is useful to distinguish these cases.
 Arguments can be made on all sides if you're dealing with new users, so
 gitolite supports that.
 We'll look at the delete/rewind case in detail first:
  * if the rules for a repo do not contain a `D` anywhere, then `RW+` will
    allow both rewind and delete operations.  Apart from being more convenient
    if you don't need this separation, this also ensures backward
    compatibility for setups created before this separation feature was added
    to gitolite).
  * 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 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
 full set of permissions possible.
 Some usage hints:
  * if you find that `RW+` no longer allows creation/deletion but you can't
    see a `C`/`D` permission in the rules, remember that gitolite allows a
    repo config to be specified in multiple places for convenience, included
    delegated or included files.  Be sure to search everywhere :)
  * a quick way to make this the default for *all* your repos is:
        repo @all
            RWCD    dummy-branch    =   foo
    where foo can be either the administrator, or if you can ignore the
    warning message when you push, a non-existant user.
 <a name="_deny_rules"></a>
 #### "deny" rules
 <a name="_warnings_and_required_reading"></a>
 ##### warnings and required reading
 Gitolite performs access checks at 2 levels.  The first check is performed for
 both read *and* write operations, while the second one happens only for write
 operations.
-**Required reading**: [this section][two_l] of the documentation.
+**Required reading**: [this section][2levels] of the documentation.
 [two_l]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html#_two_levels_of_access_rights_checking
 **Warning**: When using deny rules, the order of your rules matters, where
 earlier it did not.  If you're just starting to add a deny rule to an existing
 ruleset, it's a good idea to review the entire ruleset once, to make sure
 you're doing it right.
-<a name="_deny_rules_for_refs_in_a_repo"></a>
+#### "deny" rules for refs in a repo
 ##### "deny" rules for refs in a repo
 You can use "deny" rules for the second check, to prevent people pushing
 branches or tags that they should not be allowed to.
@ -403,9 +300,7 @@ And here's how it works:
    before the third one, and it has a `-` as the permission, so the push
    fails
-<a name="_deny_rules_for_the_entire_repo"></a>
+#### "deny" rules for the entire repo
 ##### "deny" rules for the entire repo
 The previous section described deny rules for the second check, which is a
 fairly common need.  However, gitolite does not process deny rules for the
@ -441,9 +336,53 @@ Here are some notes on how/why this works:
    gitolite just ignores the refexes, and simply looks at the permission (R,
    RW, "-", etc) and the user list.
-<a name="_summary_permissions"></a>
+### #rwcd creating and deleting branches
-### summary: permissions
+Since the beginning of gitolite, `RW` gave the ability, not only to update,
 but to *create* a branch (that matched the refex).  Similarly, `RW+` meant
 being able to not only rewind, but also delete a ref.  Conceptually, a rewind
 is almost the same as a delete+push (the only difference I can see is if you
 had core.logAllRefUpdates set, which is *not* a default setting).
 However, there seem to be cases where it is useful to distinguish these cases.
 Arguments can be made on all sides if you're dealing with new users, so
 gitolite supports that.
 We'll look at the delete/rewind case in detail first:
  * if the rules for a repo do not contain a `D` anywhere, then `RW+` will
    allow both rewind and delete operations.  Apart from being more convenient
    if you don't need this separation, this also ensures backward
    compatibility for setups created before this separation feature was added
    to gitolite).
  * 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 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
 full set of permissions possible.
 Some usage hints:
  * if you find that `RW+` no longer allows creation/deletion but you can't
    see a `C`/`D` permission in the rules, remember that gitolite allows a
    repo config to be specified in multiple places for convenience, included
    delegated or included files.  Be sure to search everywhere :)
  * a quick way to make this the default for *all* your repos is:
        repo @all
            RWCD    dummy-branch    =   foo
    where foo can be either the administrator, or if you can ignore the
    warning message when you push, a non-existant user.
 ## summary: permissions
 The full set of permissions, in regex syntax: `-|R|RW+?C?D?`.  This expands to
 one of `-`, `R`, `RW`, `RW+`, `RWC`, `RW+C`, `RWD`, `RW+D`, `RWCD`, or
@ -453,36 +392,24 @@ one of `-`, `R`, `RW`, `RW+`, `RWC`, `RW+C`, `RWD`, `RW+D`, `RWCD`, or
 the standalone `C`, which is not really a "ref" level permission and can be
 found in doc/wildcard-repositories.mkd.]
-<a name="_virtual_ref_types"></a>
+## F=_confother other tips
-### virtual "ref"-types
+### personal branches
 This is a highly advanced topic; see [doc/virtualrefs-and-scoring.mkd][vs] for
 details.
 [vs]: http://sitaramc.github.com/gitolite/doc/virtualrefs-and-scoring.html
 <a name="_other_tips"></a>
 ### other tips
 <a name="_personal_branches"></a>
 #### personal branches
 Gitolite lets you define a "personal" or "scratch" namespace prefix for each
-developer (for example, `refs/personal/<devname>/*`); see the "personal
+developer.  See [here][pers] for details.
 branches" section in `doc/3-faq-tips-etc.mkd` for details.
-<a name="_splitting_up_rules_into_rulesets"></a>
+### #ruleaccum rule accumulation
-#### splitting up rules into rulesets
+(Also see [this][ruleaccum2] for a different example that may be more
 intuitive for some people).
-Gitolite lets you specify access rules for a repo in bits and pieces.  This
+Gitolite lets you specify access rules for a repo in bits and pieces, and
-can be very convenient sometimes.  Let's say you have a mix of open source and
+accumulates them in the same sequence they were given.  This is very
-closed source projects, and "bosses" should have read access to all projects,
+convenient.  Let's say you have a mix of open source and closed source
-and everyone should have read access to open source projects.  Assuming the
+projects, and "bosses" should have read access to all projects, and everyone
-appropriate group definitions, this would work:
+should have read access to open source projects.  Assuming the appropriate
 group definitions, this would work:
    # all bosses have read access to all projects
    repo @open @closed @topsecret
@ -503,35 +430,77 @@ And although this example used groups, you can use reponames as well, or mix
 and match them.  You can even distribute rulesets across multiple "include"
 files if you wish.
-Just remember that if you use [deny rules][dr] anywhere then the *order of the
+Just remember that if you use [deny rules][deny] anywhere then the *order of the
 rules matters*!
 [dr]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html#_deny_rules
 This feature also helps people who generate their gitolite.conf itself from
 some *other* database -- it allows them much more flexibility in how they
 generate rules.
-<a name="_gitweb_and_daemon"></a>
+### #gwd specifying gitweb and daemon access
-#### gitweb and daemon
+Gitolite allows you to specify access for git-daemon and gitweb.  This is a
 feature that I personally do not use (corporate environments don't like
 unauthenticated access of any kind to any repo!), but someone wanted it, so
 here goes.
-Gitolite allows you to specify access for git-daemon and gitweb.  See
+Gitolite has two pre-defined, "special", usernames: `daemon` and `gitweb`.
 [this][gwd] for more on this.
-[gwd]: http://sitaramc.github.com/gitolite/doc/2-admin.html#gwd
+To make a repo or repo group accessible via "git daemon", just give read
 permission to the special user "daemon".  Similarly, give read permission to
 `gitweb` to allow the gitweb CGI to show the repo.  Something like this:
-<a name="_repo_specific_git_config_commands"></a>
+    repo    foo bar baz
        R   =   gitweb daemon
-#### repo specific `git config` commands
+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:
    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:
    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:
  * for daemon, create the file `git-daemon-export-ok` in the repository
  * for gitweb, add the repo (plus owner name, if given) to the list of
    projects to be served by gitweb (see the config file variable
    `$PROJECTS_LIST`, which should have the same value you specified for
    `$projects_list` when setting up gitweb)
  * put the description, if given, in `$repo/description`
 The "compile" script will keep these files consistent with the config settings
 -- this includes removing such settings/files if you remove "read" permissions
 for the special usernames or remove the description line.
 Please **note** that giving permissions to these special users via `@all`
 (that is, using either `repo @all` or `R = @all`), will not work unless you
 set the rc-file variable `$GL_ALL_INCLUDES_SPECIAL` to `1`.  Also, **NOTE**
 that giving them read access to `repo @all` means the `gitolite-admin` repo is
 also accessible.  **It is upto you to decide if that is OK in your
 environment**.
 ### #rsgc repo specific `git config` commands
 (Thanks to teemu dot matilainen at iki dot fi)
 >   ----
 >   **Note**: this won't work unless the rc file has the right settings;
->   please see `$GL_GITCONFIG_KEYS` in [doc/gitolite.rc.mkd][rcdoc] for
+>   please see `$GL_GITCONFIG_KEYS` in the [rc file doc][rc] for details and
->   details and security information.
+>   security information.
 >   ----
@ -588,13 +557,3 @@ The "delete config variable" syntax can also be used, if you wish:
 As you can see, the general idea is to place the most generic ones (`repo
@all`, or repo patterns like `repo foo.*`) first, and place more specific ones
 later to override the generic settings.
 [rcdoc]: http://sitaramc.github.com/gitolite/doc/gitolite.rc.html
 <a name="_repo_owner_description_line_for_gitweb"></a>
 #### 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.  See [here][gwd] for more
 on this.
--- a/doc/gitolite.rc.mkd
+++ b/doc/gitolite.rc.mkd
@ -1,4 +1,4 @@
-# configuring gitolite's advanced features -- the `.gitolite.rc` file
+# F=rc configuring gitolite's advanced features -- the `.gitolite.rc` file
 This is the documentation for the contents of the "rc" file
 (`$HOME/.gitolite.rc`) on the server.  Until now this documentation was
@ -8,37 +8,23 @@ and too difficult to grok for people new to gitolite.
 The documentation follows approximately the same order as the sample variables
 in the (now reorganised) example "rc" file.
 In this document:
  * <a href="#_variables_that_should_not_be_touched_at_all">variables that should not be touched at all</a>
  * <a href="#_most_often_used_changed_variables">most often used/changed variables</a>
  * <a href="#_variables_with_an_efficiency_performance_impact">variables with an efficiency/performance impact</a>
  * <a href="#_variables_with_a_security_impact">variables with a security impact</a>
  * <a href="#_less_used_changed_variables">less used/changed variables</a>
  * <a href="#_rarely_changed_variables">rarely changed variables</a>
  * <a href="#_constants_that_aren_t_">constants that aren't!</a>
 [Note: in perl, there is no actual boolean.  The undefined value, the number
 '0', and the empty string, are all 'false'.  Everything else is 'true'.  It is
 thus common to use just 0/1 for false/true].
-<a name="_variables_that_should_not_be_touched_at_all"></a>
+## variables that should not be touched at all
 ### variables that should not be touched at all
 The first section does not need too much elaboration.  Let's just say bad
 things happen if you change them.
-<a name="_most_often_used_changed_variables"></a>
+## most often used/changed variables
 ### most often used/changed variables
  * `$GL_WILDREPOS`, boolean, default 0
    Setting this variable lets your users create repositories based on wild
    cards, hand out R and RW permissions to other users to collaborate, etc.
-    See [doc/wildcard-repositories.mkd][wild] for lots of info on this.
+    See [this][wild] for lots of info on this.
  * `$PROJECTS_LIST`, filename, default `~/projects.list`
@ -68,15 +54,13 @@ things happen if you change them.
    This is because umask only affects permissions on newly created files, not
    existing ones.
-<a name="_variables_with_an_efficiency_performance_impact"></a>
+## variables with an efficiency/performance impact
 ### variables with an efficiency/performance impact
  * `$GL_BIG_CONFIG`, boolean, default 0
    This is the most common setting for efficiency in handling large repo/user
-    groups.  This is a very powerful setting; please read
+    groups.  This is a very powerful setting; please read [this][bc] if you
-    [doc/big-config.mkd][bc] for all the details you might need.
+    need details.
    There are 3 other settings related to big configs.  They are changed only
    in rare cases, however, so are described later.
@ -85,8 +69,7 @@ things happen if you change them.
    If you have *lots* of repos, and you're *not* using gitweb or daemon, you
    should probably set this on for efficiency.  Despite the name, it also
-    blocks repo config settings.  Please read [doc/big-config.mkd][bc] for
+    blocks repo config settings.  Please read [this][bc] for more details.
    more details.
    **WARNING**: if your description files are maintained by some other means
    than via the gitolite config file, make sure you set this variable to 1.
@ -99,11 +82,9 @@ things happen if you change them.
  * `$BIG_INFO_CAP`, number, default 20
-    See [using patterns to limit output][limit] for details.
+    See [using patterns to limit output][limitoutput] for details.
-<a name="_variables_with_a_security_impact"></a>
+## #rcsecurity variables with a security impact
 ### variables with a security impact
 **IMPORTANT NOTE**
@ -136,8 +117,8 @@ on feedback from my users to find or fix issues.
    This setting allows the repo admin to define acceptable gitconfig keys.
    Gitolite allows you to set git repo options using the "config" keyword;
-    see the section on "repo specific git config commands" in
+    see the section on "repo specific git config commands" in the
-    [doc/gitolite.conf.mkd][gitconf] for details and syntax.
+    [gitolite.conf][conf] documentation for details and syntax.
    However, if you are in an installation where the repo admin does not (and
    should not) have shell access to the server, then allowing him to set
@ -196,9 +177,8 @@ on feedback from my users to find or fix issues.
    enable this, give the variable the absolute path to whatever file apache
    (etc) expect to find the passwords in.
-    Look in [doc/3-faq-tips-etc.mkd][faq] ("easier to link gitweb
+    Look in the docs for [linking gitweb authorisation with
-    authorisation with gitolite" section) for more details on using this
+    gitolite][gitwebauth] for more details on using this feature.
    feature.
  * `$RSYNC_BASE`, string, default empty
@ -245,9 +225,9 @@ on feedback from my users to find or fix issues.
    **WARNING**: Use this feature only if (a) you really know what you're
    doing and (b) you really, **really**, know what you're doing!  Please read
-    [doc/admin-defined-commands.mkd][adc] for details.  This is an extremely
+    the [admin defined commands][ADCs] document for details.  This is an
-    powerful and flexible feature, and naturally anything that flexible can be
+    extremely powerful and flexible feature, and naturally anything that
-    a security risk!
+    flexible can be a security risk!
  * `$GL_GET_MEMBERSHIPS_PGM`, string, default undef
@ -257,17 +237,16 @@ on feedback from my users to find or fix issues.
    Set the following variable to the name of a script that, given a username
    as argument, will return a list of groups that she is a member of.  See
-    [doc/big-config.mkd][bc] for more details.
+    the [big config][bc] doc for more details.
    Example: `$GL_GET_MEMBERSHIPS_PGM = "/usr/local/bin/expand-ldap-user-to-groups"`
  * `$GL_HTTP_ANON_USER`, string, default undef
-    Analogous to running mob branches over ssh (as described in
+    Analogous to running mob branches over ssh (as described in the [mob
-    [doc/mob-branches.mkd][mob], this variable -- combined with appropriate
+    branches][mob]), this variable -- combined with appropriate setup
-    setup described in [doc/http-backend.mkd][smart] -- lets you pretend to
+    described in [doc/http-backend.mkd][http] -- lets you pretend to gitolite
-    gitolite that unauthenticated HTTP users are actually authenticated as
+    that unauthenticated HTTP users are actually authenticated as this user.
    this user.
  * `$GL_REF_OR_FILENAME_PATT`, string
@ -284,9 +263,7 @@ on feedback from my users to find or fix issues.
    it, if you really need to.  If you do, at least avoid backquotes and the
    dollar sign!
-<a name="_less_used_changed_variables"></a>
+## less used/changed variables
 ### less used/changed variables
  * `$GL_ALL_INCLUDES_SPECIAL`, boolean, default undef
@ -302,10 +279,9 @@ on feedback from my users to find or fix issues.
    This variable is a space-separated list of the allowed roles.
-    PLEASE, *PLEASE*, read the section in
+    Please read the **[warning][rolenamewarn]** in the [wild][] document
-    [doc/wildcard-repositories.mkd][wild] for caveats and warnings.  This is a
+    before using this feature.  This is a VERY powerful feature and if you're
-    VERY powerful feature and if you're not careful you could mess up the ACLs
+    not careful you could mess up the ACLs nicely.
    nicely.
    This is the internal default if you don't set it (like if you didn't
    update your ~/.gitolite.rc with new variables when you upgraded gitolite):
@ -317,9 +293,7 @@ on feedback from my users to find or fix issues.
        $GL_WILDREPOS_PERM_CATS = "READERS WRITERS MANAGERS TESTERS";
-<a name="_rarely_changed_variables"></a>
+## rarely changed variables
 ### rarely changed variables
  * `$GL_LOGT`, string, default `$GL_ADMINDIR/logs/gitolite-%y-%m.log`
@ -351,12 +325,10 @@ on feedback from my users to find or fix issues.
    This is where all the repos go.  If it's not an absolute path, it is
    considered to be relative to $HOME.  Moving all the repositories after the
-    install has completed is doable: just [disable writes][dwr] to gitolite,
+    install has completed is doable: just [disable writes][disable] to gitolite,
    move `~/repositories/*`, change this variable, then re-enable writes.
-<a name="_constants_that_aren_t_"></a>
+## constants that aren't!
 ### constants that aren't!
 The source file `src/gitolite_rc.pm` defines a few "constants", for example:
@ -371,13 +343,6 @@ defining a new value for any or all of them in your `~/.gitolite.rc` file.
 If you use this to relax some of the patterns involved (for example, the value
 of `ADC_CMD_ARGS_PATT`), please be sure you know what you're doing.
 [wild]: http://sitaramc.github.com/gitolite/doc/wildcard-repositories.html
 [bc]: http://sitaramc.github.com/gitolite/doc/big-config.html
 [faq]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html
 [adc]: http://sitaramc.github.com/gitolite/doc/admin-defined-commands.html
 [mirr]: http://sitaramc.github.com/gitolite/doc/mirroring.html
 [mob]: http://sitaramc.github.com/gitolite/doc/mob-branches.html
 [smart]: http://sitaramc.github.com/gitolite/doc/http-backend.html
 [dwr]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html#_disabling_write_access_to_take_backups
 [limit]: http://sitaramc.github.com/gitolite/doc/report-output.html#_using_patterns_to_limit_output
 [gitconf]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html#_repo_specific_git_config_commands
--- a/doc/hook-propagation.mkd
+++ b/doc/hook-propagation.mkd
@ -1,27 +1,13 @@
-## hook propagation in gitolite
+# F=hook_prop hook propagation in gitolite
 Some users like to know how hooks propagate, and when, and why there appear to
 be two places to put them, and so on.  I'll try and set out the logic here.
 **Note**: This is **not** the document to read if you just want to install a
-new custom hook; treat it as more "theory" than "lab".  ([Here][ch] is the
+new custom hook; treat it as more "theory" than "lab".  ([Here][customhooks] is the
 "lab" version!)
-[ch]: http://sitaramc.github.com/gitolite/doc/2-admin.html#_custom_hooks
+## hooks used by gitolite
 In this document:
  * <a href="#_hooks_used_by_gitolite">hooks used by gitolite</a>
  * <a href="#_where_do_I_the_admin_put_the_hooks_">**where** do I (the admin) put the hooks?</a>
      * <a href="#_the_GL_PACKAGE_HOOKS_directory">the `GL_PACKAGE_HOOKS` directory</a>
      * <a href="#_the_HOME_gitolite_directory">the `$HOME/.gitolite` directory</a>
      * <a href="#_why_two_places_">why two places?</a>
      * <a href="#_special_case_the_non_root_method">special case: the "non-root" method</a>
  * <a href="#_when_do_hooks_propagate_">**when** do hooks propagate?</a>
 <a name="_hooks_used_by_gitolite"></a>
 ### hooks used by gitolite
 Gitolite uses only 2 hooks.  **All** repos have an `update` hook, without
 which there is no write-level access control (per-branch permissions).  The
@ -35,9 +21,7 @@ In addition there is a "sentinel file" -- an empty file called
 The final objective of all this is that each repo's `hooks/` directory should
 get all the hooks that it is meant to get.
-<a name="_where_do_I_the_admin_put_the_hooks_"></a>
+## **where** do I (the admin) put the hooks?
 ### **where** do I (the admin) put the hooks?
 In general, **all** hooks go into the `hooks/common` directory.  Only the
 special `post-update` hook meant for the admin repo goes into
@ -47,11 +31,9 @@ Now we'll discuss the locations of these `hooks/common` and
 `hooks/gitolite-admin` directories.  This depends on which install method you
 used.
-(Please refer to [doc/1-INSTALL.mkd][0inst] for what these "methods" are).
+(Please refer to [doc/1-INSTALL.mkd][install] for what these "methods" are).
-<a name="_the_GL_PACKAGE_HOOKS_directory"></a>
+### the `GL_PACKAGE_HOOKS` directory
 #### the `GL_PACKAGE_HOOKS` directory
 You might recall that the "root", and "non-root" methods run a command called
 `gl-system-install`, the third argument of which is some directory of your
@ -68,9 +50,7 @@ process does the equivalent of `gl-system-install`.
 So now we know there's a location called `$GL_PACKAGE_HOOKS` where you can
 place your hooks.
-<a name="_the_HOME_gitolite_directory"></a>
+### the `$HOME/.gitolite` directory
 #### the `$HOME/.gitolite` directory
 You might also recall that, in these three methods, each **hosting user** has
 to run `gl-setup`.  This sets up, among other things, `$HOME/.gitolite`
@ -78,9 +58,7 @@ directory, which also contains a `hooks/` directory.
 So now there are two places you can put your hooks, apparently.
-<a name="_why_two_places_"></a>
+### why two places?
 #### why two places?
 Just think of the "package" and "root" methods for now, even if you're using
 the "non-root" method.
@ -104,18 +82,14 @@ get copied to `$HOME/.gitolite/hooks` when you "install".  I need to fix and
 thoroughly test this later; for now, just ignore the extra files you see in
 there; they're harmless/redundant (TODO)]
-<a name="_special_case_the_non_root_method"></a>
+### special case: the "non-root" method
 #### special case: the "non-root" method
 This method was created later, just piggy-backing on everything that already
 existed to cater to the "package" and "root" methods.  In this method, the
 `$GL_PACKAGE_HOOKS` is as accessible or under your control as
 `$HOME/.gitolite`, so it doesn't matter where you put your hooks.
-<a name="_when_do_hooks_propagate_"></a>
+## **when** do hooks propagate?
 ### **when** do hooks propagate?
 First: realise that gitolite *wants to make sure* that all the hooks in your
 `hooks/common` directory get copied (symlinked, actually) to *every* repo that
@ -157,5 +131,3 @@ For people who do not want certain hooks to run for certain repos, one simple
 solution that will work right now is to check the value of `$GL_REPO` at the
 start of the hook, and `exit 0` based on what it contains/matches.
 [0inst]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html
--- a/doc/http-backend.mkd
+++ b/doc/http-backend.mkd
@ -1,4 +1,4 @@
-# how to setup gitolite to use smart http mode
+# F=http how to setup gitolite to use smart http mode
 **Note**: "smart http" refers to the feature that came with git 1.6.6, late
 2009 or so.  The base documentation for this is `man git-http-backend`.  Do
@ -6,22 +6,7 @@
 that is the same or even relevant -- that is from 2006 and is quite different
 (and arguably obsolete).
-In this document:
+## WARNINGS, plus stuff I need help with
  * <a href="#_WARNINGS_plus_stuff_I_need_help_with">WARNINGS, plus stuff I need help with</a>
  * <a href="#_additional_requirements">additional requirements</a>
  * <a href="#_detailed_instructions">detailed instructions</a>
      * <a href="#_install_gitolite_under_apache_">install gitolite under "apache"</a>
      * <a href="#_setup_apache">setup apache</a>
  * <a href="#_usage">usage</a>
  * <a href="#_allowing_anonymous_access">allowing anonymous access</a>
  * <a href="#_ssh_http_access_and_the_GIT_HTTP_EXPORT_ALL_variable">ssh + http access and the `GIT_HTTP_EXPORT_ALL` variable</a>
 ----
 <a name="_WARNINGS_plus_stuff_I_need_help_with"></a>
 ### WARNINGS, plus stuff I need help with
  * I have NOT converted the test suite to use this mode.  Volunteers to
    convert it to http access are welcome :-)
@ -47,32 +32,24 @@ In this document:
    and given a proper $HOME and `~/.ssh/authorized_keys` and all that).  If
    anyone has the energy to try that please let me know how that went.
-<a name="_additional_requirements"></a>
+## additional requirements
 ### additional requirements
  * requires `GIT_PROJECT_ROOT` (see "man git-http-backend" for what this is)
    set explicitly (i.e., it is no longer optional).  Please set it to some
    place outside apache's `DOCUMENT_ROOT`.
-<a name="_detailed_instructions"></a>
+## detailed instructions
 ### detailed instructions
 I assume you've installed apache 2.x and git on the server.
 I assume your httpd runs under the "apache" userid; adjust instructions below
 if it does not.  Similarly for "/var/www" and other file names/locations.
-I assume you have read the "[please read this first][1rtf]" section of the
+I assume you have read the "[please read this first][insttrouble]" section of the
 main install document to get an idea of the general concepts and terminology
 (just ignore anything that is specific to ssh).
-[1rtf]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html#_please_read_this_first
+### install gitolite under "apache"
 <a name="_install_gitolite_under_apache_"></a>
 #### install gitolite under "apache"
 Follow the "non-root" method, but since you can't even "su - apache", make the
 following variations when doing this as root:
@ -116,9 +93,7 @@ following variations when doing this as root:
        chown -R apache.apache $GITOLITE_HTTP_HOME
-<a name="_setup_apache"></a>
+### setup apache
 #### setup apache
 You will need to setup certain values in the httpd conf, as given in `man
 git-http-backend`.  You can put all them into, for instance,
@ -144,9 +119,7 @@ from those in the manpage cited above, plus we have one extra variable:
 Now create/update the password file in `/path/to/some/passwdfile` using the
 `htpasswd` command, and you're all done for the setup!
-<a name="_usage"></a>
+## usage
 ### usage
 Git URLs look like `http://user:password@server/git/reponame.git`.
@ -171,9 +144,7 @@ following works and I'm leaving it at that:
 With a few nice shell aliases, you won't even notice the horrible convolutions
 here ;-)
-<a name="_allowing_anonymous_access"></a>
+## allowing anonymous access
 ### allowing anonymous access
 Like [mob branches][mob] with ssh, you can allow completely
 **un**-authenticated users to still have some rights specified in gitolite.
@ -192,9 +163,7 @@ Briefly, here's how:
 URLs (in this example) will then look like `http://server/gitmob/reponame.git`
 -- we lose the userid:passwd part and change 'git' to 'gitmob'.
-<a name="_ssh_http_access_and_the_GIT_HTTP_EXPORT_ALL_variable"></a>
+## ssh + http access and the `GIT_HTTP_EXPORT_ALL` variable
 ### ssh + http access and the `GIT_HTTP_EXPORT_ALL` variable
 This document only talks about setting up access to a set of git repositories
 purely via smart http.  The `GIT_HTTP_EXPORT_ALL` variable must be set for
@ -222,6 +191,3 @@ repo.
 ----
 Enjoy!
 [mob]: http://sitaramc.github.com/gitolite/doc/mob-branches.html
--- a/doc/index.mkd
+++ b/doc/index.mkd
@ -0,0 +1,205 @@
 # F=index Hosting git repositories
 Gitolite allows you to setup git hosting on a central server, with
 fine-grained access control and many (many!) more powerful features.
 ## #qi quick install
 If you're comfortable with Unix and ssh, the following steps should work.
  * create a user called `git`.  Login to this user.
  * copy your ssh pubkey from your workstation.  Rename it to `YourName.pub`.
  * now run these commands:
        git clone git://github.com/sitaramc/gitolite
        gitolite/src/gl-system-install
        gl-setup ~/YourName.pub
 You're done.
 **WARNING**: do **NOT** add repos or users directly on the server!  You MUST
 manage the server by cloning the special 'gitolite-admin' repo on your
 workstation (`git clone git@server:gitolite-admin`), making changes, and
 pushing them.  Here's how to [add users and repos][add].
 ## #rtfm what should you read?
 The complete online documentation for gitolite is
 [here](http://sitaramc.github.com/gitolite).  There's a lot of it, so here're
 some reading suggestions.
 If you're a **user** (i.e., not a gitolite admin), you only need [this][user].
 Otherwise, the suggested reading order is this:
  * **quick intro**: this document, or at least the "[what is
    gitolite][gl_what]" section just below this one.
  * **installation**: if the [quick install][qi] above did not work for you,
    then read the [INSTALL][install] document.  The "[trouble][insttrouble]"
    section in it may be useful too.
  * **basic** administration tasks: [adding users and repos][add].
 When you have to use more features, look in the master table of contents
 (there's a link to it at the top of *every* document), and use your browser's
 search function to search for stuff.
 ### F=other_docs what do the other docs contain
 The master TOC (see link above) is really the only *comprehensive* list of
 what is there, but here's an attempt to give you an overview!
  * understanding gitolite
      * gitolite install and basic admin in [pictures][]
      * gitolite.conf by [example][conf_examples]
      * gitolite and [ssh][gl_ssh]
  * normal admin tasks done on the server
      * [admin][]: adding your own hooks, adding existing repos into gitolite, etc.
      * [rc][]: setting gitolite behaviour options (warning: some of the
        variables have a security impact if you're careless)
  * normal admin tasks done by changing [gitolite.conf][conf]
      * basic access control
      * advanced access control
      * extras: personal branches, gitweb/git-daemon access, git config settings
  * advanced use (experts only; you can shoot yourself in the foot nicely!)
      * [ADCs][]: allowing users to run specific shell commands (but not give them a shell)
      * (also, [sample ADCs][shipped_ADCs] that come with gitolite)
      * letting [users create][wild] their own repos and assign permissions
      * [delegating][deleg] admin rights
      * [mirroring][]
  * special installation scenarios:
      * using smart-[http][] instead of ssh
      * [migrating][migr] from gitolite
 Finally, [tips][] has a lot of useful information.
 ## #gl_what what is gitolite?
 Gitolite is an access control layer on top of git.  Here's an "executive
 summary":
  * use a single unix user ("real" user) on the server
  * provide access to many gitolite users
      * they are not "real" users
      * they do not get shell access
  * control access to many git repositories
      * read access controlled at the repo level
      * write access controlled at the branch/tag/file/directory level,
        including who can rewind, create, and delete branches/tags
  * can be installed without root access, assuming git and perl are already
    installed
  * authentication is most commonly done using sshd, but you can also use
    httpd if you prefer (this may require root access).
  * several other neat features, too many to list here
 ## F=_need why is gitolite needed?
 Gitolite is separate from git, and needs to be installed and configured.  So...
 why do we bother?
 Gitolite is useful in any server that is going to host multiple git
 repositories, each with many developers, where some sort of access control is
 required.
 In theory, this can be done with plain old Unix permissions: each user is a
 member of one or more groups, each group "owns" one or more repositories, and
 using unix permissions (especially the setgid bit -- `chmod g+s`) you can
 allow/disallow users access to repos.
 But there are several disadvantages here:
  * every user needs a userid and password on the server.  This is usually a
    killer, especially in tightly controlled environments
  * adding/removing access rights involves complex `usermod -G ...` mumblings
    which most admins would rather not deal with
  * *viewing* (aka auditing) the current set of permissions requires running
    multiple commands to list directories and their permissions/ownerships,
    users and their group memberships, and then correlating all these manually
  * auditing historical permissions or permission changes is pretty much
    impossible without extraneous tools
  * errors or omissions in setting the permissions exactly can cause problems
    of either kind: false accepts or false rejects
  * without going into ACLs it is not possible to give some people read-only
    access while some others have read-write access to a repo (unless you make
    it world-readable).  Group access just doesn't have enough granularity
  * it is absolutely impossible to restrict pushing by branch name or tag
    name.
 Gitolite does away with all this:
  * it uses ssh magic to remove the need to give actual unix userids to
    developers
  * it uses a simple but powerful config file format to specify access rights
  * access control changes are affected by modifying this file, adding or
    removing user's public keys, and "compiling" the configuration
  * this also makes auditing trivial -- all the data is in one place, and
    changes to the configuration are also logged, so you can audit them.
  * finally, the config file allows distinguishing between read-only and
    read-write access, not only at the repository level, but at the branch
    level within repositories.
 ## why did I write it?
 The most important feature I needed was **per-branch permissions**.  This is
 pretty much mandatory in a corporate environment, and is almost the single
 reason I started *thinking* about writing gitolite.
 It's not just "read-only" versus "read-write".  Rewinding a branch (aka "non
 fast forward push") is potentially dangerous, but sometimes needed.  So is
 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`).
 ### F=_morefeatures some more features
 Here're some more features.
  * simple, yet powerful, config file syntax, including specifying
    gitweb/daemon access.  You'll need this power if you manage lots of
    users+repos+combinations of access
  * apart from branch-name based restrictions, you can also restrict by
    file/dir name changed (i.e., output of `git diff --name-only`)
  * if your requirements are still too complex, you can split up the config
    file and delegate authority over parts of it
  * easy to specify gitweb owner, description and gitweb/daemon access
  * easy to sync gitweb (http) authorisation with gitolite's access config
  * comprehensive logging [aka: management does not think "blame" is just a
    synonym for "annotate" :-)]
  * "personal namespace" prefix for each dev
  * migration guide and simple converter for gitosis conf file
  * "exclude" (or "deny") rights at the branch/tag level
  * specify repos using patterns (patterns may include creator's name)
  * define powerful operations on the server side, even github-like forking
 ## security
 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 first person to find a hole that allows a non-admin user to push a change
 to a repository that he is not allowed to, will get a modest reward of 5000
 INR.  The hole should not require enabling any of the options listed as having
 a [security impact][rcsecurity] in the rc file, nor obvious things like setting
 the umask too loose, etc.
 ## contact and license
 Gitolite is released under GPL v2.  See COPYING for details.
  * author: sitaramc@gmail.com, sitaram@atc.tcs.com
  * mailing list: gitolite@googlegroups.com
  * list subscribe address : gitolite+subscribe@googlegroups.com
--- a/doc/1-INSTALL.mkd
+++ b/doc/1-INSTALL.mkd
@ -1,38 +1,10 @@
-# gitolite installation
+# F=install gitolite installation
 (Note: git servers are most commonly used with ssh URLs, and this document
 describes installing gitolite to support such usage.  If your users prefer
 http URLs, read [this][http] to install gitolite to support "smart http").
-In this document:
+## installing and upgrading gitolite
  * <a href="#_installing_and_upgrading_gitolite">installing and upgrading gitolite</a>
      * <a href="#_side_note_upgrading">(side note) upgrading</a>
      * <a href="#_package_method">package method</a>
      * <a href="#_non_root_method">non-root method</a>
          * <a href="#_upgrading_from_from_client_method_to_non_root_method">upgrading from from-client method to non-root method</a>
      * <a href="#_root_method">root method</a>
  * <a href="#_troubleshooting">troubleshooting</a>
  * <a href="#_important_points_to_note">important points to note</a>
  * <a href="#_naming_conventions_used">naming conventions used</a>
  * <a href="#_requirements">requirements</a>
      * <a href="#_client_workstation">client/workstation</a>
      * <a href="#_server">server</a>
      * <a href="#_technical_skills">technical skills</a>
  * <a href="#_getting_the_gitolite_software">getting the gitolite software</a>
      * <a href="#_getting_a_tar_file_from_a_clone">getting a tar file from a clone</a>
  * <a href="#_special_cases_multiple_gitolite_servers">special cases -- multiple gitolite servers</a>
  * <a href="#_uninstalling">uninstalling</a>
      * <a href="#_cleaning_out_a_botched_install">cleaning out a botched install</a>
      * <a href="#_uninstalling_gitolite_completely">uninstalling gitolite completely</a>
  * <a href="#_appendix_a_the_from_client_method">appendix a: the from-client method</a>
  * <a href="#_appendix_b_PATH_issues_for_gl_setup">appendix b: PATH issues for gl-setup</a>
 ----
 <a name="_installing_and_upgrading_gitolite"></a>
 ### installing and upgrading gitolite
 This section tells you how to install/upgrade gitolite, without too much
 background.  Later sections have more details and troubleshooting info; please
@ -56,23 +28,7 @@ These install methods are described in detail below.  (*Once you finish the
 install, read the [admin document][admin] to administer your gitolite
 installation*).
-<a name="_side_note_upgrading"></a>
+### F=rpmdeb package method
 #### (side note) upgrading
 Upgrading is easy; you just re-run some of the same commands used for install.
 These commands are clearly noted in the install instructions below.
 However, if you've added any new hooks, you must also run the next step (the
 `gl-setup` command), although this time you don't need to supply a pubkey
 filename as an argument.
 [admin]: http://sitaramc.github.com/gitolite/doc/2-admin.html
 [http]: http://sitaramc.github.com/gitolite/doc/http-backend.html
 <a name="_package_method"></a>
 #### package method
 (Unlike in the rest of this document, we use "gitolite" as the "hosting user"
 instead of "git" here, because that is the user that both the Fedora and
@ -97,9 +53,7 @@ On your *workstation*:
    git clone gitolite@server:gitolite-admin
-<a name="_non_root_method"></a>
+### F=nonroot non-root method
 #### non-root method
 **IMPORTANT WARNING -- IGNORE AT YOUR PERIL**: if you want to use this method
 you had better know the password to the hosting user on the server, or be able
@ -110,6 +64,8 @@ messing with the keys.
 you're interested.  (That tutorial is by someone else but it's nice enough for
 me to link it here).
 [tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial
 On your *workstation*:
  * copy your `~/.ssh/id_rsa.pub` file to `/tmp/YourName.pub` on the server
@ -119,10 +75,9 @@ on the default PATH.  If not, fiddle with the `.bashrc` or `.bash_profile` or
 similar files and add it somehow.  Then:
    git clone git://github.com/sitaramc/gitolite
-    cd gitolite
+    gitolite/src/gl-system-install
    src/gl-system-install
    # defaults to being the same as:
-    # src/gl-system-install $HOME/bin $HOME/share/gitolite/conf $HOME/share/gitolite/hooks
+    # gitolite/src/gl-system-install $HOME/bin $HOME/share/gitolite/conf $HOME/share/gitolite/hooks
    # to upgrade gitolite, repeat the above commands.  Make sure you use the
    # same arguments for the last command each time.
@ -133,9 +88,7 @@ On your *workstation*:
    git clone git@server:gitolite-admin
-<a name="_upgrading_from_from_client_method_to_non_root_method"></a>
+#### F=upgrfromclient upgrading from from-client method to non-root method
 ##### upgrading from from-client method to non-root method
 Since the from-client method is now deprecated for reasons explained
 elsewhere, some folks may want to do their next upgrade using the non-root
@ -165,9 +118,7 @@ There are many, many ways to skin this cat; here's one way:
    Now save the file.
-<a name="_root_method"></a>
+### F=root root method
 #### root method
 On your *workstation*:
@ -176,10 +127,9 @@ On your *workstation*:
 On your *server*, as *root*:
    git clone git://github.com/sitaramc/gitolite
-    cd gitolite
+    gitolite/src/gl-system-install
    src/gl-system-install
    # defaults to being the same as:
-    # src/gl-system-install /usr/local/bin /usr/local/share/gitolite/conf /usr/local/share/gitolite/hooks
+    # gitolite/src/gl-system-install /usr/local/bin /usr/local/share/gitolite/conf /usr/local/share/gitolite/hooks
    # to upgrade gitolite, repeat the above commands.  Make sure you use the
    # same arguments for the last command each time.
@ -197,34 +147,54 @@ On your *workstation*:
    git clone git@server:gitolite-admin
----
+### #upgrade upgrading
-<a name="_troubleshooting"></a>
+Upgrading is easy; you just re-run some of the same commands used for install.
 These commands are clearly noted in the install instructions below.
-### troubleshooting
+However, if you've added any new hooks, you must also run the next step (the
 `gl-setup` command), although this time you don't need to supply a pubkey
 filename as an argument.
-  * The most common thing that goes wrong in an install is something to do
+## #insttrouble if you run into trouble...
    with ssh.
-    Here are three facts of ssh:
+If you run into trouble, please read the following sections.  They have
 background information that may help you, or additional steps you can take to
 troubleshoot or fix the problem.
 ### common install problems
 The most common problem is usually ssh.  Here are three facts of ssh:
  * ssh is a pain
  * most people don't know ssh well enough
  * even people who think they do, don't
-    Please read how [gitolite uses ssh][glgas] and the [ssh
+Please read how [gitolite uses ssh][gl_ssh] and the [ssh
-    troubleshooting][glsts] documents before asking for help.
+troubleshooting][sts] documents before asking for help.
-  * If you've tried multiple methods of install, you may have multiple copies
+If you've tried multiple methods of install, you may have multiple copies of
-    of the sources lying around.  This could be a problem; see appendix b for
+the sources lying around.  This could be a problem; see [appendix a][instpath]
-    how to detect and deal with this.
+for how to detect and deal with this.
 If none of this works read the rest of this document, understand it as much as
 you can, then ask for help.
-<a name="_important_points_to_note"></a>
+### #instnameconv naming conventions used
-### important points to note
+Throughout the documentation, we use "YourName" as the admin user, and his
 workstation is called "client".  The hosting user is "git", and the server is
 called "server".  **Please substitute your values as needed**.
 **If you're using DEB or RPM**, the installer creates a user called
 "gitolite", so substitute that for "git" anywhere in the docs where the
 "hosting user" is mentioned as "git".
 Also, we often say "the rc file".  This means `~/.gitolite.rc` on the server.
 And when we say the "access control rules", or "conf file", or "config file",
 we mean `conf/gitolite.conf` on your gitolite-admin clone.
 ### F=instbg helpful background information
  * gitolite runs as a single (real) user on a server, and is invoked via ssh.
    Traditionally, this "hosting user" is "git", and thus all git URLs start
@ -234,8 +204,7 @@ you can, then ask for help.
      * there is *usually* only one hosting user per server (machine), but
        gitolite makes it trivial to have as many as you want.  In fact, every
-        user on the server is a potential hosting user.  Advanced users can
+        user on the server is a potential hosting user.
        look [here][mgs]!)
  * using this single user and sshd (or httpd) authentication, gitolite allows
    you to create any number of "virtual" users.  Virtual user names only mean
@ -251,7 +220,7 @@ you can, then ask for help.
    administration of gitolite.
    To make matters worse, ssh problems in gitolite don't always look like ssh
-    problems.  See [doc/ssh-troubleshooting.mkd][glsts] for help.
+    problems.  See the [ssh troubleshooting][sts] document for help.
  * gitolite **does NOT** like it when people with shell access to the server
    fiddle with files and directories it controls.
@ -267,27 +236,7 @@ emergency use.  However, I will not be documenting it because (a) if you know
 ssh you'll know how to extrapolate my instructions to do this and (b) if you
 don't know ssh it'll be a nightmare to support you.
-<a name="_naming_conventions_used"></a>
+### F=instrequire requirements
 ### naming conventions used
 Throughout the documentation, we use "YourName" as the admin user, and his
 workstation is called "client".  The hosting user is "git", and the server is
 called "server".  **Please substitute your values as needed**.
 **If you're using DEB or RPM**, the installer creates a user called
 "gitolite", so substitute that for "git" anywhere in the docs where the
 "hosting user" is mentioned as "git".
 Also, we often say "the rc file".  This means `~/.gitolite.rc` on the server.
 And when we say the "access control rules", or "conf file", or "config file",
 we mean `conf/gitolite.conf` on your gitolite-admin clone.
 <a name="_requirements"></a>
 ### requirements
 <a name="_client_workstation"></a>
 #### client/workstation
@ -296,8 +245,6 @@ we mean `conf/gitolite.conf` on your gitolite-admin clone.
        you're using putty, plink, puttygen, etc., for ssh; I recommend
        msysgit for Windows and the openssh that comes with it
 <a name="_server"></a>
 #### server
  * any Unix system with a posix compatible "sh".
@ -313,8 +260,6 @@ we mean `conf/gitolite.conf` on your gitolite-admin clone.
    user, even your own normal one.  (If you're using an RPM/DEB the install
    probably created one called "gitolite").
 <a name="_technical_skills"></a>
 #### technical skills
  * if you're installing gitolite, you're a "system admin", like it or not.
@ -330,9 +275,7 @@ we mean `conf/gitolite.conf` on your gitolite-admin clone.
  * regular expressions are a big part of gitolite in many places but
    familiarity is not necessary to do basic access control.
-<a name="_getting_the_gitolite_software"></a>
+### F=_getgl getting the gitolite software
 ### getting the gitolite software
 You can get the latest version of gitolite from github or google code using
 the 'git clone' command:
@ -341,8 +284,6 @@ the 'git clone' command:
            # (OR)
    git clone https://code.google.com/p/gitolite/
 <a name="_getting_a_tar_file_from_a_clone"></a>
 #### getting a tar file from a clone
 If you are on an internal network and cannot clone the gitolite repo, you can
@ -360,55 +301,37 @@ Please use the make command as shown, not a plain "git archive", because the
 Makefile adds a file called `.GITOLITE-VERSION` that will help you identify
 which version you are using.
--------------------------------------------------------
+## #_instappendices appendixes
-<a name="_special_cases_multiple_gitolite_servers"></a>
+The following sections have some miscellaneous information that does not
 cleanly to fit anywhere else.
-### special cases -- multiple gitolite servers
+### #instpath appendix a: PATH issues for gl-setup
-(**Advanced users only, please!**)
+If you've tried multiple methods of install, you may have multiple copies of
 the sources lying around, and when you ran `gl-setup` it picked up the wrong
 one.  This might also happen if the directory you supplied as the first
 argument to `gitolite/src/gl-system-install` is not even in the `$PATH`.
-There is no gitolite "daemon"; it gets invoked via sshd which calls
+Run `su - git` then `which gl-setup` to see which it picked up.  This is what
-"gl-auth-command" via the "command=" option in the authkeys file (see
+it should be for each method:
 [gitolite and ssh][glgas] for more).
-If you think about it, this means every real (unix) user on the system can
+  * RPM/DEB method: probably `/usr/bin`
-host her own gitolite server!
+  * root method: the first argument to the `gitolite/src/gl-system-install` command (or
    `/usr/local/bin` by default)
  * non-root method: the first argument to the `gitolite/src/gl-system-install` command
    (or `$HOME/bin` by default)
-Of course, one doesn't normally do that in the interests of sanity, but let's
+If this is not what you get, remove the partially installed or extraneous
-say you want to create one gitolite instance for each department on some
+sources, if any, and try again.  Or fix your `$PATH`.
 company-wide mega-server.
-Using one of the first two methods of installation, it's trivial to create
+One situation that is not easy to solve is if the system admin installed
-multiple gitolite instances -- essentially any Unix user can then run
+gitolite using the RPM/DEB or root methods, and you want to install a later
-`gl-setup` with some pubkey filename as an argument and that user is now a
+version using the non-root method.  Since `/usr/bin` and `/usr/local/bin` are
-gitolite host.
+usually earlier than `$HOME/bin` in the `$PATH`, you'll have to get creative.
 Good luck.
-You can even do this without giving shell access to the admins.  Here's an
+### #clean appendix b: cleaning out a botched install
 example with just two "departments", and their admins Alice and Bob:
  * create userids `webbrowser_repos` and `webserver_repos`
  * ask Alice and Bob for their pubkeys; copy them to the respective home
    directories for convenience
  * run `su - webbrowser_repos`, then `gl-setup alice.pub`
  * (similarly with `webserver_repos` and `bob.pub`, and so on for others)
 That's it.  The URL for all web browser projects is now something like
 `webbrowser_repos@server:reponame`, and similarly for the others.
 Notice that you only have to do this once for each "department", and it's
 really just one command after creating the userid.  None of these admins need
 to have a command line on the server, so don't give them the passwords if you
 don't need to -- the pubkey will allow them to be gitolite admins on their
 domain, and that's quite enough for normal operations.
 <a name="_uninstalling"></a>
 ### uninstalling
 <a name="_cleaning_out_a_botched_install"></a>
 #### cleaning out a botched install
 When people have trouble installing gitolite, they often try to change a bunch
 of things manually on the server.  This usually makes things worse ;-) so
@ -428,65 +351,57 @@ here's how to clean the slate.
        delete `/var/gitolite/conf` and `/var/gitolite/hooks` or
        `$HOME/share/gitolite/conf` and `$HOME/share/gitolite/hooks`
-<a name="_uninstalling_gitolite_completely"></a>
+### F=_uninstall appendix c: uninstalling gitolite completely
-#### uninstalling gitolite completely
+(There's some duplication between this and the previous section).
-There's some duplication between this and the previous section, but
+Uninstalling gitolite is fairly easy, although it is manual.  (We'll assume
-uninstalling gitolite is described in great detail in
+`$REPO_BASE` in the rc file was left at its default of `~/repositories`; if
-[doc/uninstall.mkd][doc9unin]
+not, adjust accordingly):
----
+**server side tasks**
-<a name="_appendix_a_the_from_client_method"></a>
+  * edit `~/.ssh/authorized_keys` and delete the `# gitolite start` and `#
    gitolite end` markers and all the lines between them.  This will prevent
    any of your users from attempting a push while you are doing this.
-### appendix a: the from-client method
+    If you are the only user, and/or *need* one or more of those keys to
    continue to access this account (like if one of them is your laptop or
    your home desktop etc.) then instead of deleting the line you can just
    delete everything upto but not including the words "ssh-rsa" or "ssh-dss".
-This method was the only install mode at one time, but the newer ones are much
+  * Now remove (or move aside or rename to something else if you're paranoid)
-better, so it's gone now, to reduce confusion and support/documentation load.
+    the following files and directories.
-The only advantage of this method was that it forced you to solve the ssh
+        ~/.gitolite
-pubkey problem **before** attempting to install.
+        ~/.gitolite.rc
        ~/repositories/gitolite-admin.git
-But it turned out not to be worth the hassle of supporting an install scheme
+  * You can remove all of `~/repositories` if you have not really started
-that ends up with the admin user having [two keys][twokeys], though.  And this
+    using gitolite properly yet; that's your choice.
 in turn forced the admin to use a different URL to access gitolite repos than
 normal users, which seemed to confuse a heck of a lot of people who don't read
 the prominently displayed messages and/or the documentation.
-All in all, it wasn't one of my best ideas.
+    If you *do* need to preserve the other repos and continue to use them,
    remove all the `update` hooks that git installs on each repository.  The
    easiest way is:
-<a name="_appendix_b_PATH_issues_for_gl_setup"></a>
+        find ~/repositories -wholename "*.git/hooks/update" | xargs rm -f
-### appendix b: PATH issues for gl-setup
+    but you can do it manually if you want to be careful.
-If you've tried multiple methods of install, you may have multiple copies of
+**client side tasks**
 the sources lying around, and when you ran `gl-setup` it picked up the wrong
 one.  This might also happen if the directory you supplied as the first
 argument to `src/gl-system-install` is not even in the `$PATH`.
-Run `su - git` then `which gl-setup` to see which it picked up.  This is what
+  * Any remote users that still have access must update their clone's remote
-it should be for each method:
+    URLs (edit `.git/config` in the repo) to prefix `repositories/` before the
    actual path used, in order for the remote to still work.  This is because
    you'll now be accessing it through plain ssh, which means you have to give
    it the full path.
-  * RPM/DEB method: probably `/usr/bin`
+  * Finally, you as the gitolite admin *nay* have a host stanza for "gitolite"
-  * root method: the first argument to the `src/gl-system-install` command (or
+    in your *client*'s `~/.ssh/config`.  Find and delete lines that look like
-    `/usr/local/bin` by default)
+    this:
  * non-root method: the first argument to the `src/gl-system-install` command
    (or `$HOME/bin` by default)
-If this is not what you get, remove the partially installed or extraneous
+        host gitolite
-sources, if any, and try again.  Or fix your `$PATH`.
+            user git
-
+            hostname your.server
-One situation that is not easy to solve is if the system admin installed
+            port 22
-gitolite using the RPM/DEB or root methods, and you want to install a later
+            identityfile ~/.ssh/your-gitolite-admin-username
 version using the non-root method.  Since `/usr/bin` and `/usr/local/bin` are
 usually earlier than `$HOME/bin` in the `$PATH`, you'll have to get creative.
 Good luck.
 [glsts]: http://sitaramc.github.com/gitolite/doc/ssh-troubleshooting.html
 [doc9unin]: http://sitaramc.github.com/gitolite/doc/uninstall.html
 [twokeys]: http://sitaramc.github.com/gitolite/doc/ssh-troubleshooting.html#twokeys
 [transcript]: http://sitaramc.github.com/gitolite/doc/install-transcript.html
 [mgs]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html#_special_cases_multiple_gitolite_servers
 [glgas]: http://sitaramc.github.com/gitolite/doc/gitolite-and-ssh.html
 [tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial
--- a/doc/migrate.mkd
+++ b/doc/migrate.mkd
@ -1,4 +1,4 @@
-# migrating from gitosis to gitolite
+# F=migr migrating from gitosis to gitolite
 HELP WANTED: these instructions have been revamped a bit recently
 [2011-07-18], so if something doesn't work let me know.
@ -39,7 +39,7 @@ Here are the steps on the server:
        chown -R git.git /home/git/repositories
  * (as 'root' and/or 'git' on the server) Follow instructions to install
-    gitolite; see the [install document][inst].  Make sure that you **don't**
+    gitolite; see the [install document][install].  Make sure that you **don't**
    change the default path for `$REPO_BASE` if you edit the config file!
    This will give you a gitolite config that has the required entries for the
@ -80,7 +80,7 @@ instructions are to be read as "on gitolite admin's workstation".
  * **IMPORTANT**: if you have any users with names like `user@foo`, where the
    part after the `@` does *not* have a `.` in it (i.e., does not look like
    an email address), you need to change them, because gitolite uses that
-    syntax for enabling multi keys.
+    syntax for [enabling multi keys][oldmultikeys].
    You have two choices in how to fix this.  You can change the gitolite
    config so that all mention of `user@foo` is changed to just `user`.
@ -92,9 +92,10 @@ instructions are to be read as "on gitolite admin's workstation".
    `user@foo.bar`, i.e., the part after the `@` had a `.` in it, because then
    it looks like an email address.
-    [This][mk] will tell you more about these nuances.
+    [This][multikey] will tell you more about these nuances.  If you can
    understand it.
-  * **IMPORTANT: expand any multi-key files you may have**.  [Here][mk]'s an
+  * **IMPORTANT: expand any multi-key files you may have**.  [Here][multikey]'s an
    explanation of what multi-keys are, how gitosis does them and how gitolite
    does it differently.
@ -123,5 +124,3 @@ instructions are to be read as "on gitolite admin's workstation".
  * Check all your changes to your gitolite-admin clone, commit, and push
 [mk]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html#multikeys
 [inst]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html
--- a/doc/mirroring.mkd
+++ b/doc/mirroring.mkd
@ -1,4 +1,4 @@
-## mirroring gitolite servers
+# F=mirroring mirroring gitolite servers
 Mirroring a repo is simple in git; you just need code like this in a
 `post-receive` hook in each repo:
@ -11,37 +11,7 @@ Mirroring a repo is simple in git; you just need code like this in a
 For a lot of people, though, mirroring is more than just 'backup', and their
 needs are complex enough that setup is hard.
----
+## #_mirrwhy why
 In this document:
  * <a href="#_why">why</a>
  * <a href="#_RULE_NUMBER_ONE_">RULE NUMBER ONE!</a>
  * <a href="#_IMPORTANT_cautions">IMPORTANT cautions</a>
  * <a href="#_concepts_and_terminology">concepts and terminology</a>
  * <a href="#_setup_and_usage">setup and usage</a>
      * <a href="#_server_level_setup">server level setup</a>
      * <a href="#_repository_level_setup">repository level setup</a>
      * <a href="#_commands_to_re_sync_mirrors">commands to (re-)sync mirrors</a>
  * <a href="#_details">details</a>
      * <a href="#_the_conf_gitolite_conf_file">the `conf/gitolite.conf` file</a>
  * <a href="#_redirecting_pushes">redirecting pushes</a>
  * <a href="#_example_setups">example setups</a>
      * <a href="#_non_autonomous">non-autonomous</a>
      * <a href="#_non_autonomous_with_local_repos">non-autonomous with local repos</a>
      * <a href="#_semi_autonomous">semi-autonomous</a>
      * <a href="#_autonomous">autonomous</a>
  * <a href="#_discussion">discussion</a>
      * <a href="#_problems_with_the_old_mirroring_model">problems with the old mirroring model</a>
      * <a href="#_the_new_mirroring_model">the new mirroring model</a>
  * <a href="#_appendix_A_example_cronjob_based_mirroring">appendix A: example cronjob based mirroring</a>
  * <a href="#_appendix_B_efficiency_versus_paranoia">appendix B: efficiency versus paranoia</a>
 ----
 <a name="_why"></a>
 ### why
 Gitolite's mirroring used to be very rigid -- one master, any number of
 slaves, but the slaves are identical copies of the master. No variations
@ -88,9 +58,7 @@ of setup you need. Here're some advantages:
 As you can see, this is a bit more than a backup solution ;-)
-<a name="_RULE_NUMBER_ONE_"></a>
+## RULE NUMBER ONE!
 ### RULE NUMBER ONE!
 **RULE OF GIT MIRRORING: users should push directly to only one server**!  All
 the other machines (the slaves) should be updated by the master server.
@ -105,9 +73,22 @@ recovers.
 **Getting around rule number one**: see the section on "redirecting pushes"
 later.
-<a name="_IMPORTANT_cautions"></a>
+## concepts and terminology
-### IMPORTANT cautions
+Servers can host 3 kinds of repos: master, slave, and local.
  * A repo can be a **master** on one and only one server.  A repo on its
    "master" server is a **native** repo, on slaves it is "non-native".
  * A **slave** repo cannot be pushed to by a user.  It will only accept
    pushes from a master server. (Exception: see the "redirecting pushes"
    section later)
  * A **local** repo is not involved in mirroring at all, in either direction.
 ## setting up mirroring
 ### F=mirrcautions IMPORTANT cautions
  * For reasons given in the 'discussion' section later, the mirroring process
    will never *create* a repo on the receiving side.  It has to exist, and be
@ -151,28 +132,7 @@ later.
    documentation on [git config commands][rsgc] if you wish to **delete** one
    of those lines.
-[rsgc]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html#_repo_specific_git_config_commands
+### F=mirrsetup setup and usage
 <a name="_concepts_and_terminology"></a>
 ### concepts and terminology
 Servers can host 3 kinds of repos: master, slave, and local.
  * A repo can be a **master** on one and only one server.  A repo on its
    "master" server is a **native** repo, on slaves it is "non-native".
  * A **slave** repo cannot be pushed to by a user.  It will only accept
    pushes from a master server. (Exception: see the "redirecting pushes"
    section later)
  * A **local** repo is not involved in mirroring at all, in either direction.
 <a name="_setup_and_usage"></a>
 ### setup and usage
 <a name="_server_level_setup"></a>
 #### server level setup
@ -198,15 +158,15 @@ and 'gollum' as examples here.
    trusting gollum?)
 3.  Now copy `hooks/common/post-receive.mirrorpush` from the gitolite source,
-    and install it as a custom hook called `post-receive`; see [here][ch] for
+    and install it as a custom hook called `post-receive`; see
-    instructions.
+    [here][customhooks] for instructions.
 4.  Edit `~/.gitolite.rc` on each machine and add/edit the following lines.
    The `GL_HOSTNAME` variable **must** have the correct name for that host
    (frodo, sam, or gollum), so that will definitely be different on each
    server.  The other line can be the same, or may have additional patterns
    for other `git config` keys you have previously enabled.  See [here][rsgc]
-    and the description for `GL_GITCONFIG_KEYS` in [this][vsi] for details.
+    and the description for `GL_GITCONFIG_KEYS` in [this][rcsecurity] for details.
        $GL_HOSTNAME = 'frodo';     # will be different on each server!
        $GL_GITCONFIG_KEYS = "gitolite.mirror.*";
@ -232,7 +192,7 @@ and 'gollum' as examples here.
        gl-tool add-mirroring-peer gollum.pub
 6.  Create "host" aliases on each machine to refer to all other machines.  See
-    [here][ha] for what/why/how.
+    [here][sshhostaliases] for what/why/how.
    The host alias for a host (in other machines' `~/.ssh/config` files) MUST
    be the same as the `GL_HOSTNAME` in the referred host's `~/.gitolite.rc`.
@ -255,8 +215,6 @@ should get you
 Check this command from *everywhere to everywhere else*, and make sure you get
 expected results.  **Do NOT proceed otherwise.**
 <a name="_repository_level_setup"></a>
 #### repository level setup
 Setting up mirroring at the repository level instead of at the "entire server"
@ -342,9 +300,7 @@ So here's how our example would go:
    Also, send the same lines to gollum's administrator and ask him to add
    them into his conf/gitolite.conf file, commit, and push.
-<a name="_commands_to_re_sync_mirrors"></a>
+### F=mirrsync commands to (re-)sync mirrors
 #### commands to (re-)sync mirrors
 You don't have to put all the slaves in `gitolite.mirror.slaves`.  For
 example, let's say you have some repos that are very active, and two of your
@ -450,13 +406,9 @@ are ways to do that:
    want to know why their push errored out or didn't work last time or
    whatever.
-<a name="_details"></a>
+## #ad/m-dtls details
-### details
+### F=mirrconf the `conf/gitolite.conf` file
 <a name="_the_conf_gitolite_conf_file"></a>
 #### the `conf/gitolite.conf` file
 One goal I have is to minimise the code changes to "core" gitolite due to
 this, so all repo-specific mirror settings are stored as `git config`
@ -491,9 +443,7 @@ config file right?).  These are:
    except they have to start with `gitolite.mirror.`.  The section on
    "commands to (re-)sync mirrors" has some examples.
-<a name="_redirecting_pushes"></a>
+### F=mirrredirect redirecting pushes
 ### redirecting pushes
 **Please read carefully; there are security implications if you enable this
 for mirrors NOT under your control**.
@ -550,15 +500,11 @@ There are some potential issues that you MUST consider before enabling this:
    Ideally, I recommend that ad hoc repos not be mirrored at all.  Keep
    mirroring for "blessed" repos only.
-<a name="_example_setups"></a>
+## example setups
-### example setups
+Here are some samples of what is possible.
-Here is a sample of what is possible.
+### F=mirrnonauto non-autonomous
 <a name="_non_autonomous"></a>
 #### non-autonomous
 In this setup, the slave server is under the same "management" as the master.
 All repos, including gitolite-admin are mirrored, and *each slave is an exact
@ -585,9 +531,7 @@ redirected pushing if you wish:
    repo @all
        config gitolite.mirror.redirectOK = "true"
-<a name="_non_autonomous_with_local_repos"></a>
+### F=mirrnonautolocal non-autonomous with local repos
 #### non-autonomous with local repos
 As above, but you want to allow each slave server to have some repos be
 "local" to the server (not be mirrored), for whatever reason. Different slaves
@ -613,9 +557,7 @@ That's it. When this config is pushed, each machine will have an effective
 config that consists of the main file, with the correct HOSTNAME.conf included
 (and all the others ignored) when the include statement is reached.
-<a name="_semi_autonomous"></a>
+### F=mirrsemiauto semi-autonomous
 #### semi-autonomous
 So far, the "central" admin still has control over the gitolite.conf file and
 all repos created.  Sometimes it's easier to give control over parts of the
@ -623,12 +565,10 @@ configuration to people at the mirror sites.  To keep it simple, each admin
 will be able to do whatever they want to directories within a subdirectory of
 the same name as the hostname.
-You can combine the "HOSTNAME" feature above with [delegation][deldoc]. Let's
+You can combine the "HOSTNAME" feature above with [delegation][deleg]. Let's
 say the admin for sam is a user called "gamgee", and the admin for gollum is
 "smeagol".
 [deldoc]: http://sitaramc.github.com/gitolite/doc/delegation.html
 Add this to your conf file:
    @sam    =   sam/..*
@ -641,9 +581,7 @@ Now in the main config file, at the end (or wherever you wish), add one line:
    subconf "HOSTNAME.conf"
-<a name="_autonomous"></a>
+### F=mirrauto autonomous
 #### autonomous
 In many ways this is the simplest setup.
@ -659,13 +597,9 @@ etc.)
 Best for open source projects with heavy "fetch" load compared to "push".
-<a name="_discussion"></a>
+## F=mirrdisc discussion
-### discussion
+### problems with the old mirroring model
 <a name="_problems_with_the_old_mirroring_model"></a>
 #### problems with the old mirroring model
 The old mirroring model had a single server as the master for *all*
 repositories.  Slaves were effectively only for load-balancing reads, or for
@ -689,9 +623,7 @@ as such:
  * it implicitly assumed all the mirrors were under the same admin, and that
    the gitolite-admin repo was itself mirrored too.
-<a name="_the_new_mirroring_model"></a>
+### the new mirroring model
 #### the new mirroring model
 In the new model, servers can be much more independent and autonomous than in
 the old model.  (Don't miss the side note in the 'repository level setup'
@ -736,11 +668,9 @@ repo).
    in the side note somewhere up above, and just forget this feature exists
    :-)
----
+## appendices
-<a name="_appendix_A_example_cronjob_based_mirroring"></a>
+### F=mirrcron appendix A: example cronjob based mirroring
 ### appendix A: example cronjob based mirroring
 Let's say you have some repos that are very active.  You're pushing halfway
 across the world every few seconds, but those slaves do not need to be that closely
@ -774,9 +704,7 @@ Then write a cron job that looks like this (untested).
        sleep 10
    done
-<a name="_appendix_B_efficiency_versus_paranoia"></a>
+### F=mirrparanoia appendix B: efficiency versus paranoia
 ### appendix B: efficiency versus paranoia
 If you're paranoid enough to use mirrors, you should be paranoid enough to
 use the `receive.fsckObjects` setting.  However, informal tests indicate a
@ -790,9 +718,3 @@ gitolite.conf file:
 Personally, I just set `git config --global receive.fsckObjects true`, since
 those servers aren't doing anything else anyway, and are idle for long
 stretches of time.  It's upto you what you want to do here.
 [ch]: http://sitaramc.github.com/gitolite/doc/2-admin.html#_custom_hooks
 [ha]: http://sitaramc.github.com/gitolite/doc/ssh-troubleshooting.html#_appendix_4_host_aliases
 [rsgc]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html#_repo_specific_git_config_commands
 [vsi]: http://sitaramc.github.com/gitolite/doc/gitolite.rc.html#_variables_with_a_security_impact
--- a/doc/mob-branches.mkd
+++ b/doc/mob-branches.mkd
@ -1,4 +1,4 @@
-## mob branches in gitolite
+# F=mob mob branches in gitolite
 WARNING: This is hairy stuff.  But what's life without a little danger?
--- a/doc/nagp.mkd
+++ b/doc/nagp.mkd
@ -1,29 +1,10 @@
-# ...not a gitolite problem!
+# F=nagp ...not a gitolite problem!
 Subtitle: Unix, ssh, git, and gitolite -- recognising the boundaries
 **Warning**: Most of this is technical, but some of it is definitely
 subjective opinion.
 ----
 In this document:
  * <a href="#_background">background</a>
  * <a href="#_ssh">ssh</a>
  * <a href="#_git">git</a>
  * <a href="#_windows">windows</a>
  * <a href="#_apple">apple</a>
  * <a href="#_just_say_NO_">just say NO!</a>
      * <a href="#_behind_my_back">behind my back</a>
  * <a href="#_that_s_outrageous">that's outrageous</a>
 ----
 <a name="_background"></a>
 ### background
 More and more people are being tasked with creating a "server" environment for
 git, (and thus being forcibly introduced to gitolite), before they've had a
 chance to know git (or even Unix) well enough.  As a result, I often get
@ -51,24 +32,16 @@ That might help with some of the problems described in this document.
 [bare]: http://sitaramc.github.com/concepts/0-terminology.html#working_tree_repository_bare_repository
 [sgs]: http://sitaramc.github.com/1-basic-usage/simple-git-session.html
-<a name="_ssh"></a>
+## ssh
 ### ssh
 Let's get this out of the way first.  The *superstar* of the "not a gitolite
 problem" category is actually ssh.
-Surprised?  It is so common that it has [its own document][aa] to tell you why
+Surprised?  It is so common that it has [its own document][auth] to tell
-it is *not* a gitolite problem, while [another one][sts] tries to help you
+you why it is *not* a gitolite problem, while [another one][sts] tries to
-anyway!
+help you anyway!
-[aa]: http://sitaramc.github.com/gitolite/doc/authentication-vs-authorisation.html
+## git
 [sts]: http://sitaramc.github.com/gitolite/doc/ssh-troubleshooting.html
 [hc]: http://sitaramc.github.com/gitolite/doc/2-admin.html#_hook_chaining
 <a name="_git"></a>
 ### git
  * first push to a new repo
@ -110,14 +83,13 @@ anyway!
    I don't know much about CI systems, but I'm pretty sure they run off of
    some hook or other, but gitolite may already be using those hooks.  The
-    section on hook chaining [here][hc] shows you how to run your own hooks.
+    section on hook chaining [here][hookchaining] shows you how to run your own
    hooks.
    In short, CI integration is no more a gitolite problem than any other
    purpose for which git's hooks can be used.
-<a name="_windows"></a>
+## windows
 ### windows
 I'm *interested* in making sure it works fine with Windows, simply because I
 have colleagues at work who use it.  But that doesn't mean I can help you; I
@ -129,9 +101,7 @@ God alone knows what else, so I know it *can* (be made to) work.
 So, hang in there... it'll all work out eventually.
-<a name="_apple"></a>
+## apple
 ### apple
 Weirdly enough, this is the one thing that Steve Ballmer and I probably agree
 on, so I won't elaborate on that ;-)
@ -139,9 +109,7 @@ on, so I won't elaborate on that ;-)
 It seems to me though, that many recent reports of "weird" behaviour reported
 have come from Macs.  Yet another reason for me to back off with an apology.
-<a name="_just_say_NO_"></a>
+## just say NO!
 ### just say NO!
 These are the things I won't do, for various reasons, mostly technical, with a
 smattering of some subjective stuff.  If you've been hit by one of these, and
@ -200,9 +168,7 @@ the GPL, you can simply "fork off" ;-)
    workable solution, I still would not do it.  A server repo should be bare.
    Period.
-<a name="_behind_my_back"></a>
+### behind my back
 #### behind my back
 Some of the "Just say NO" items are from situations where someone or something
 changes stuff behind gitolite's back.  I am particularly unsympathetic to this
@ -254,9 +220,7 @@ sort of thing.
    </font>
-<a name="_that_s_outrageous"></a>
+## that's outrageous
 ### that's outrageous
 This section is for really outrageous stuff.
--- a/doc/overkill.mkd
+++ b/doc/overkill.mkd
@ -1,57 +0,0 @@
 ## when gitolite is overkill
 Note: I wrote this to help people for whom gitolite is genuinely overkill.  I
 believe it will all work, but YMMV.
 ----
 You don't always need something like gitolite.  If you have a fixed (or very
 rarely changing) number of users, and all of them have full access to all your
 repos, you can use plain Unix permissions to get a lot of this done:
  * dedicate a userid (say "git") to host all your repos.  This user will also
    have a group (normally called "git" on most distros I think)
  * create a directory that is accessible (at least "r" and "x" permissions)
    to the group "git", all the way upto the root.  (That is, if the directory
    you chose is /home/git/repos, then /, /home, /home/git, and
    /home/git/repos must all be "g+rx").
  * create all repos in this directory, as the "git" user, using the following
    command:
        git init --bare --shared reponame.git
  * For each user who needs access to the repos, add them as members to the
    "git" group also.  On Fedora this is:
        usermod -a -G git username
 And that's basically it.  The "init --shared" will create the repos with
 "chmod -R g+s".  If you have existing repos where you forgot (or didn't know)
 the "--shared" argument, do this on each of them:
        cd reponame.git
        git init --shared --bare
        chmod -R g+w .
        chmod g+s `find . -type d`
 I think that should do it.
 Once you've setup the Unix level permissions, you may consider setting the
 shell of some of the less experienced users to "git-shell" (using its full
 path) if they don't really need a shell on the server.  This will let them
 access git remotely but not do anything else.
 Combining this with settings like `receive.denyDeletes` and
 `receive.denyNonFastForwards`, or at least `core.logAllRefUpdates`, can go a
 long way toward preventing accidents or at least making it feasible to recover
 from them.
 ----
 You can do more complex things using Unix acls.  If you do, and feel like
 writing it up, send it to me and I will add it here (with credit given of
 course).  Personally, I can't be bothered -- once you have differing needs for
 different people, you really need gitolite anyway, because you probably need
 different rights for branches as well and Unix ACLs can't do that.
--- a/doc/packaging.mkd
+++ b/doc/packaging.mkd
@ -1,4 +1,4 @@
-## packaging gitolite
+# F=packaging packaging gitolite
 Here's how you'd package gitolite.  In the following description, location "X"
 can be, say, `/usr/share/gitolite/conf` or some such, and similarly location
--- a/doc/progit-article.mkd
+++ b/doc/progit-article.mkd
@ -1,17 +1,13 @@
-# (master copy of progit chapter on gitolite)
+# F=progit (master copy of progit chapter on gitolite)
 ## Gitolite ##
-Note: the latest copy of this section of the ProGit book is always available within the [gitolite documentation][gldpg].  The author would also like to humbly state that, while this section is accurate, and *can* (and often *has*) been used to install gitolite without reading any other documentation, it is of necessity not complete, and cannot completely replace the enormous amount of documentation that gitolite comes with.
+Note: the latest copy of this section of the ProGit book is always available within the [gitolite documentation][progit].  The author would also like to humbly state that, while this section is accurate, and *can* (and often *has*) been used to install gitolite without reading any other documentation, it is of necessity not complete, and cannot completely replace the enormous amount of documentation that gitolite comes with.
 [gldpg]: http://sitaramc.github.com/gitolite/doc/progit-article.html
 Git has started to become very popular in corporate environments, which tend to have some additional requirements in terms of access control.  Gitolite was originally created to help with those requirements, but it turns out that it's equally useful in the open source world: the Fedora Project controls access to their package management repositories (over 10,000 of them!) using gitolite, and this is probably the largest gitolite installation anywhere too.
 Gitolite allows you to specify permissions not just by repository, but also by branch or tag names within each repository.  That is, you can specify that certain people (or groups of people) can only push certain "refs" (branches or tags) but not others.
 <a name="_Installing_"></a>
 ### Installing ###
 Installing Gitolite is very easy, even if you don't read the extensive documentation that comes with it.  You need an account on a Unix server of some kind; various Linux flavours, and Solaris 10, have been tested.  You do not need root access, assuming git, perl, and an openssh compatible ssh server are already installed.  In the examples below, we will use the `gitolite` account on a host called `gitserver`.
@ -25,24 +21,17 @@ We will describe this last method in this article; for the other methods please
 To begin, create a user called `git` on your server and login to this user.  Copy your ssh pubkey (a file called `~/.ssh/id_rsa.pub` if you did a plain `ssh-keygen` with all the defaults) from your workstation, renaiming it to `YourName.pub`.  Then run these commands:
    git clone git://github.com/sitaramc/gitolite
-    cd gitolite
+    gitolite/src/gl-system-install
    src/gl-system-install
    gl-setup -q ~/YourName.pub
        # for example, I would run 'gl-setup -q ~/sitaram.pub'
 Finally, back on your workstation, run `git clone git@server:gitolite-admin`.
-And you're done!  Gitolite has now been installed on the server, and you now have a brand new repository called `gitolite-admin` in your workstation.  You administer your gitolite setup by making changes to this repository and pushing.  See [adding users and repos][aur] to start with.
+And you're done!  Gitolite has now been installed on the server, and you now have a brand new repository called `gitolite-admin` in your workstation.  You administer your gitolite setup by making changes to this repository and pushing.  See [adding users and repos][add] to start with.
 [aur]: http://sitaramc.github.com/gitolite/doc/2-admin.html#_adding_users_and_repos
 <a name="_Customising_the_Install_"></a>
 ### Customising the Install ###
-While the default, quick, install works for most people, there are some ways to customise the install if you need to.  If you omit the `-q` argument, an editor pops up with a file for you to edit, so you can change certain server-side parameters, such as the location of the actual repositories.  This "rc" file is documented in [doc/gitolite.rc.mkd][rcdoc] so you should be able to make any changes you need quite easily, save it, and continue.
+While the default, quick, install works for most people, there are some ways to customise the install if you need to.  If you omit the `-q` argument, an editor pops up with a file for you to edit, so you can change certain server-side parameters, such as the location of the actual repositories.  This "rc" file is documented in [doc/gitolite.rc.mkd][rc] so you should be able to make any changes you need quite easily, save it, and continue.
 <a name="_Config_File_and_Access_Control_Rules_"></a>
 ### Config File and Access Control Rules ###
@ -58,7 +47,6 @@ Once the install is done, you switch to the `gitolite-admin` repository (placed
 	#gitolite conf
 	# please see doc/gitolite.conf.mkd for details on syntax and features
 	repo gitolite-admin
 	    RW+                 = sitaram
@ -67,7 +55,7 @@ Once the install is done, you switch to the `gitolite-admin` repository (placed
 Notice that "sitaram" (the name of the pubkey in the gl-setup command you used earlier) has read-write permissions on the `gitolite-admin` repository as well as a public key file of the same name.
-The config file syntax for gitolite is documented in [doc/gitolite.conf.mkd][confdoc] so we'll only mention some highlights here.
+The config file syntax for gitolite is documented in [doc/gitolite.conf.mkd][conf] so we'll only mention some highlights here.
 You can group users or repos for convenience.  The group names are just like macros; when defining them, it doesn't even matter whether they are projects or users; that distinction is only made when you *use* the "macro".
@ -104,8 +92,6 @@ There are two levels of access control in gitolite.  The first is at the reposit
 The second level, applicable only to "write" access, is by branch or tag within a repository.  The username, the access being attempted (`W` or `+`), and the refname being updated are known.  The access rules are checked in order of appearance in the config file, looking for a match for this combination (but remember that the refname is regex-matched, not merely string-matched).  If a match is found, the push succeeds.  A fallthrough results in access being denied.
 <a name="_Advanced_Access_Control_with_deny_rules_"></a>
 ### Advanced Access Control with "deny" rules ###
 So far, we've only seen permissions to be one or `R`, `RW`, or `RW+`.  However, gitolite allows another permission: `-`, standing for "deny".  This gives you a lot more power, at the expense of some complexity, because now fallthrough is not the *only* way for access to be denied, so the *order of the rules now matters*!
@ -130,8 +116,6 @@ You can also use deny rules to hide specific repos from people (or gitweb, or gi
 See the documentation for more on this.
 <a name="_Restricting_pushes_by_files_changed_"></a>
 ### Restricting pushes by files changed ###
 In addition to restricting what branches a user can push changes to, you can also restrict what files they are allowed to touch.  For example, perhaps the Makefile (or some other program) is really not supposed to be changed by just anyone, because a lot of things depend on it or would break if the changes are not done *just right*.  You can tell gitolite:
@ -145,8 +129,6 @@ In addition to restricting what branches a user can push changes to, you can als
 This powerful feature is documented in `conf/example.conf`.
 <a name="_Personal_Branches_"></a>
 ### Personal Branches ###
 Gitolite also has a feature called "personal branches" (or rather, "personal branch namespace") that can be very useful in a corporate environment.
@ -157,14 +139,10 @@ This would normally cause the same branch name clutter as in a centralised VCS,
 Gitolite lets you define a "personal" or "scratch" namespace prefix for each developer (for example, `refs/personal/<devname>/*`); see the "personal branches" section in `doc/3-faq-tips-etc.mkd` for details.
 <a name="_Wildcard_repositories_"></a>
 ### "Wildcard" repositories ###
 Gitolite allows you to specify repositories with wildcards (actually perl regexes), like, for example `assignments/s[0-9][0-9]/a[0-9][0-9]`, to pick a random example.  This is a *very* powerful feature, which has to be enabled by setting `$GL_WILDREPOS = 1;` in the rc file.  It allows you to assign a new permission mode ("C") which allows users to create repositories based on such wild cards, automatically assigns ownership to the specific user who created it, allows him/her to hand out R and RW permissions to other users to collaborate, etc.  This feature is documented in `doc/wildcard-repositories.mkd`.
 <a name="_Other_Features_"></a>
 ### Other Features ###
 We'll round off this discussion with a sampling of other features, all of which, and many more, are described in great detail in the "faqs, tips, etc" and other documents.
--- a/doc/report-output.mkd
+++ b/doc/report-output.mkd
@ -1,22 +1,10 @@
-# output of the "info" and "expand" commands
+# F=info_expand output of the "info" and "expand" commands
 Running "ssh git@server info" or "ssh git@server expand" gives you certain
 output.  This doclet describes the output; you're welcome to help me make it
 clearer :)
-In this document:
+## #info the "info" command
  * <a href="#_the_info_command">the "info" command</a>
      * <a href="#_interpreting_the_output">interpreting the output</a>
      * <a href="#_using_patterns_to_limit_output">using patterns to limit output</a>
      * <a href="#_side_note_openssh_5_6">side note: openssh 5.6</a>
  * <a href="#_the_expand_command">the "expand" command</a>
 ----
 <a name="_the_info_command"></a>
 ### the "info" command
 Usage:
@ -49,9 +37,7 @@ is often blank.
        @R_ @W_	testing
         R   W 	vkc
-<a name="_interpreting_the_output"></a>
+### interpreting the output
 #### interpreting the output
 The meaning of C, R, and W are self-explanatory, but they may be prefixed or
 suffixed by a symbol:
@ -74,9 +60,7 @@ suffixed by a symbol:
 The `_` suffix is special.  This says the user has only implicit access (due
 to one of the `@all` uses), but no explicit access.
-<a name="_using_patterns_to_limit_output"></a>
+### #limitoutput using patterns to limit output
 #### using patterns to limit output
 Here are a couple of samples with optional patterns:
@ -95,17 +79,14 @@ Here are a couple of samples with optional patterns:
 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
 gitolite truncates the output after 20 results to prevent a DOS.  (This limit
-can be changed; see `$BIG_INFO_CAP` in [doc/gitolite.rc.mkd][rcdoc]).
+can be changed; see `$BIG_INFO_CAP` in the documentation for
-
+[`~/.gitolite.rc`][rc]).
 [rcdoc]: http://sitaramc.github.com/gitolite/doc/gitolite.rc.html
 The pattern is also mandatory when an admin wants to find out what access some
 *other* user has, which you may have guessed from the syntax in the "usage"
 line above.
-<a name="_side_note_openssh_5_6"></a>
+### #openssh5.6 side note: openssh 5.6
 #### side note: openssh 5.6
 It used to be that the gitolite documentation would say "just use `ssh
 git@server`" in the past, because gitolite defaults to the "info" command if
@ -121,9 +102,7 @@ add the `-T` option to ssh (`ssh -T git@server`).
 [openssh56]: http://www.openssh.org/txt/release-5.6
-<a name="_the_expand_command"></a>
+## #expand the "expand" command
 ### the "expand" command
 Usage:
--- a/doc/shell-games.mkd
+++ b/doc/shell-games.mkd
@ -1,86 +0,0 @@
 ## avoiding the shell on the server
 Gitolite now tries to prevent gitolite-admin push privileges from being used
 to obtain a shell on the server.  This was not always the case (older gitolite
 did not make this distinction), but I've been moving towards this for a while
 now, and, while there could still be holes in that separation, they will be
 fixed as and when found.
 Thus, settings that have security implications can be set only from the rc
 file, which needs to be edited directly on the server.  And adding a new hook
 requires shell access anyway.
 While this is great for my main target (corporate environments), some people
 don't like it.  They want to do all of this from the *gitolite-admin* repo,
 because the security concern mentioned above does not bother them.  They don't
 want to log on to the server to make a change in the rc file or don't want to
 run gl-setup to propagate a new set of hooks.  In addition, they may want all
 of these animals versioned in the "gitolite-admin" repo itself, which
 certainly makes sense.
 So here's how you might do that.
 First, arrange to have all your special files added to the gitolite-admin
 repo.  The best option is to keep all of this in a single subdirectory (let's
 call it "local" in our example).  So your `~/.gitolite.rc` might go into
 `local/gitolite.rc`, and all your local hooks into `local/hooks` etc.  Add
 them, commit, and push.
 Note: do not create any top level directory called "conf", "contrib", "doc",
 "hooks", or "src" -- those names are used by gitolite itself.
 Second, create a `post-update.secondary` hook and place it in the *gitolite*
 clone's `hooks/common` directory, containing the following code:
    #!/bin/bash
    [ "$GL_REPO" = "gitolite-admin" ] || exit 0
    [ -z "$GL_RC" ] && { echo "ENV GL_RC not set"; exit 1; }
    GL_ADMINDIR=`$GL_BINDIR/gl-query-rc GL_ADMINDIR`
    cp    $GL_ADMINDIR/local/gitolite.rc    $HOME/.gitolite.rc
    cp -a $GL_ADMINDIR/local/hooks/*        $GL_ADMINDIR/hooks/common
    /Full/Path/To/gl-install -q
        # the path should be the same as that for gl-auth-command in the
        # "command=" parameter of ~/.ssh/authorized_keys on the server
 Don't forget to make it executable!
 After this, run the upgrade instructions for the install method you used (just
 as if the `post-update.secondary` file you just created came from a gitolite
 software update).
 All future changes to the rc file can be done via local/gitolite.rc in the
 admin repo, and hooks can be added to local/hooks.
 **Note**: One quirk of how gitolite [propagates hooks][hpd] is that now this
 `post-update.secondary` exists in all normal repos also.  Just ignore it; it's
 not doing any harm.
 [hpd]: http://sitaramc.github.com/gitolite/doc/hook-propagation.html
 **Warning**: Nothing in gitolite *removes* hooks, so if you delete (or even
 rename) a script, it still stays on the server -- you'll have to delete them
 manually from the server.
 ----
 So what's this actually doing?
 Well, first, note that `$GL_ADMINDIR` contains files from both gitolite
 itself, as well as from the gitolite-admin repo.  "conf/VERSION", "src",
 "doc", and "hooks" come from gitolite itself, while the other 2 files in
 "conf", and all of "keydir" come from the gitolite-admin repo.  ("logs"
 doesn't come from anywhere).
 In addition, any other files in the "master" branch of the gitolite-admin repo
 get checked out here, which in this case would mean the entire "local/"
 hierarchy you created above.
 Now, since the "hooks/common" directory is coming from gitolite itself,
 clearly this is where the internal "install" routine expects to find new or
 updated hooks to propagate.  So you just copy your local hooks (in the
 "local/hooks" directory) to "hooks/common" and run the installer again.  Done!
--- a/doc/ssh-troubleshooting.mkd
+++ b/doc/ssh-troubleshooting.mkd
@ -1,52 +1,20 @@
-# ssh troubleshooting
+# F=sts ssh troubleshooting
 ----
 **This document must be read in full the first time.  If you start from some
 nice looking section in the middle it may not help you unless you're already
 an expert at ssh**.
 In this document:
  * <a href="#_IMPORTANT_READ_THIS_FIRST">IMPORTANT -- READ THIS FIRST</a>
      * <a href="#_caveats">caveats</a>
      * <a href="#_naming_conventions_used">naming conventions used</a>
      * <a href="#_taking_stock_relevant_files_and_directories">taking stock -- relevant files and directories</a>
      * <a href="#_normal_gitolite_key_handling">normal gitolite key handling</a>
  * <a href="#_Other_resources_">(Other resources)</a>
  * <a href="#_common_problems">common problems</a>
  * <a href="#_step_by_step">step by step</a>
  * <a href="#_random_tips_tricks_and_notes">random tips, tricks, and notes</a>
      * <a href="#_giving_shell_access_to_gitolite_users">giving shell access to gitolite users</a>
      * <a href="#_losing_your_admin_key">losing your admin key</a>
      * <a href="#_simulating_ssh_copy_id">simulating ssh-copy-id</a>
      * <a href="#_problems_with_using_non_openssh_public_keys">problems with using non-openssh public keys</a>
      * <a href="#_windows_issues">windows issues</a>
  * <a href="#_appendix_1_ssh_daemon_asks_for_a_password">appendix 1: ssh daemon asks for a password</a>
  * <a href="#_appendix_2_which_key_is_which_running_sshkeys_lint">appendix 2: which key is which -- running sshkeys-lint</a>
      * <a href="#_typical_cause_s_">typical cause(s)</a>
  * <a href="#_appendix_3_ssh_client_may_not_be_offering_the_right_key">appendix 3: ssh client may not be offering the right key</a>
  * <a href="#_appendix_4_host_aliases">appendix 4: host aliases</a>
  * <a href="#_appendix_5_why_bypassing_gitolite_causes_a_problem">appendix 5: why bypassing gitolite causes a problem</a>
 ----
 This document should help you troubleshoot ssh-related problems in installing
 and accessing gitolite.
-<a name="_IMPORTANT_READ_THIS_FIRST"></a>
+## IMPORTANT -- READ THIS FIRST
-### IMPORTANT -- READ THIS FIRST
+### caveats
 <a name="_caveats"></a>
 #### caveats
  * Before reading this document, it is **mandatory** to read and **completely
-    understand** [doc/gitolite-and-ssh.mkd][doc9gas], which is a very detailed
+    understand** [this][gl_ssh], which is a very detailed look at how gitolite
-    look at how gitolite uses ssh's features on the server side.  Don't assume
+    uses ssh's features on the server side.  Don't assume you know all that;
-    you know all that; if you knew it, you wouldn't be needing *this* document
+    if you knew it, you wouldn't be needing *this* document either!
    either!
  * This document, and others linked from this, together comprise all the help
    I can give you in terms of the ssh aspect of using gitolite.  If you're
@ -58,13 +26,9 @@ and accessing gitolite.
    rather spend time on actual gitolite features, code, and documentation
    than authentication (i.e., ssh, in the common case).
-    Surprised?  [This][wo] might help explain better.
+    Surprised?  [This][auth] might help explain better.
----
+### naming conventions used
 <a name="_naming_conventions_used"></a>
 #### naming conventions used
  * Your workstation is the **client**.  Your userid on the client does not
    matter, and it has no relation to your gitolite username.
@ -73,9 +37,7 @@ and accessing gitolite.
    this is an RPM/DEB install, the hosting user is probably called
    "gitolite", however we will use "git" in this document.
-<a name="_taking_stock_relevant_files_and_directories"></a>
+### taking stock -- relevant files and directories
 #### taking stock -- relevant files and directories
  * the client has a `~/.ssh` containing a few keypairs.  It may also have a
    `config` file.
@ -92,9 +54,7 @@ and accessing gitolite.
  * the server also has a `~/.gitolite/keydir` which contains a bunch of
    `*.pub` files.
-<a name="_normal_gitolite_key_handling"></a>
+### normal gitolite key handling
 #### normal gitolite key handling
 Here's how normal gitolite key handling works:
@ -120,16 +80,12 @@ Here's how normal gitolite key handling works:
        between gitolite's "marker" lines (`# gitolite start` and `# gitolite
        end`).
-<a name="_Other_resources_"></a>
+## (Other resources)
 ### (Other resources)
 People who think installing gitolite is too hard should take a look at this
 [tutorial][tut] to **see how simple it *actually* is**.
-<a name="_common_problems"></a>
+## common ssh problems
 ### common problems
 Since I'm pretty sure at least some of you didn't bother to read the
 "IMPORTANT: PLEASE READ FIRST" section above, let me take a minute to point
@ -169,9 +125,7 @@ the rest in sequence.  Appendix 5 has some background info.
    does not appear to be a git repository`, and yet you are sure 'reponame'
    exists, you haven't mis-spelled it, etc.
-<a name="_step_by_step"></a>
+## step by step
 ### step by step
 Since I'm pretty sure at least some of you didn't bother to read the
 "IMPORTANT: PLEASE READ FIRST" section above, let me take a minute to point
@ -193,13 +147,9 @@ Done?  OK, now the general outline for ssh troubleshooting is this:
    need to make sure that this specific key is being offered/sent by the
    client, instead of the default key.  See appendix 3 and 4.
-<a name="_random_tips_tricks_and_notes"></a>
+## random tips, tricks, and notes
-### random tips, tricks, and notes
+### giving shell access to gitolite users
 <a name="_giving_shell_access_to_gitolite_users"></a>
 #### giving shell access to gitolite users
 We've managed (thanks to an idea from Jesse Keating) to make it possible for a
 single key to allow both gitolite access *and* shell access.
@ -216,20 +166,14 @@ access would not manage to get himself shell access.
 Giving someone shell access requires that you should have shell access in the
 first place, so the simplest way is to enable it from the server side only.
-<a name="_losing_your_admin_key"></a>
+### losing your admin key
 #### losing your admin key
 If you lost the admin key, and need to re-establish ownership of the
 gitolite-admin repository with a fresh key, get a shell on the server and use
 the program called `gl-admin-push` that comes with gitolite.  See instructions
-[here][gssp].
+[here][adminpush].
-[gssp]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html#_gl_admin_push_bypassing_gitolite_for_the_gitolite_admin_repo
+### simulating ssh-copy-id
 <a name="_simulating_ssh_copy_id"></a>
 #### simulating ssh-copy-id
 don't have `ssh-copy-id`?  This is broadly what that command does, if you want
 to replicate it manually.  The input is your pubkey, typically
@ -252,9 +196,7 @@ typically) also must be `go-w`, but that needs root.  And typically
 they're already set that way anyway.  (Or if they're not, you've got
 bigger problems than gitolite install not working!)]
-<a name="_problems_with_using_non_openssh_public_keys"></a>
+### problems with using non-openssh public keys
 #### problems with using non-openssh public keys
 Gitolite accepts public keys only in openssh format.  Trying to use an "ssh2"
 key (used by proprietary SSH software) results in:
@ -267,9 +209,7 @@ To convert ssh2-compatible keys to openssh run:
 then use the resulting pubkey as you normally would in gitolite.
-<a name="_windows_issues"></a>
+### windows issues
 #### windows issues
 On windows, I have only used msysgit, and the openssh that comes with it.
 Over time, I have grown to distrust putty/plink due to the number of people
@ -278,13 +218,9 @@ used them for any kind of git access).  If you have unusual ssh problems that
 just don't seem to have any explanation, try removing all traces of
 putty/plink, including environment variables, etc., and then try again.
-Thankfully, someone contributed [contrib/putty.mkd][putty].
+Thankfully, someone contributed [contrib/putty.mkd][contrib_putty].
----
+## appendix 1: ssh daemon asks for a password
 <a name="_appendix_1_ssh_daemon_asks_for_a_password"></a>
 ### appendix 1: ssh daemon asks for a password
 >   **NOTE**: This section should be useful to anyone trying to get
 >   password-less access working.  It is not necessarily specific to gitolite,
@ -352,9 +288,7 @@ This is a quick checklist:
    this file for messages matching the approximate time of your last attempt
    to login, to see if they tell you what is the problem.
-<a name="_appendix_2_which_key_is_which_running_sshkeys_lint"></a>
+## appendix 2: which key is which -- running sshkeys-lint
 ### appendix 2: which key is which -- running sshkeys-lint
 Follow these steps on the client:
@ -389,9 +323,7 @@ need.  Be careful:
  * if you're running ssh-agent, you may have to delete (using `ssh-add -D`)
    and re-add identities for it to pick up the renamed ones correctly
-<a name="_typical_cause_s_"></a>
+### typical cause(s)
 #### typical cause(s)
 The admin often has passwordless shell access to `git@server` already, and
 then used that same key to get access to gitolite (i.e., copied that same
@ -407,9 +339,7 @@ as YourName.pub, then run `gl-setup YourName.pub` on the server.  Remember to
 adjust your agent identities using ssh-add -D and ssh-add if you're using
 ssh-agent, otherwise these new keys may not work.
-<a name="_appendix_3_ssh_client_may_not_be_offering_the_right_key"></a>
+## appendix 3: ssh client may not be offering the right key
 ### appendix 3: ssh client may not be offering the right key
  * make sure the right private key is being offered.  Run ssh in very
    verbose mode and look for the word "Offering", like so:
@ -431,9 +361,7 @@ ssh-agent, otherwise these new keys may not work.
    In that case, add the key you want using `ssh-add ~/.ssh/YourName` and try
    the access again.
-<a name="_appendix_4_host_aliases"></a>
+## F=sshhostaliases appendix 4: host aliases
 ### appendix 4: host aliases
 (or "making git use the right options for ssh")
@ -467,23 +395,9 @@ If you have *more than one* pubkey with access to the *same* server, you
 **must** use this method to make git pick up the right key.  There is no other
 way to do this, as far as I know.
 ----
 [doc9gas]: http://sitaramc.github.com/gitolite/doc/gitolite-and-ssh.html
 [install]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html
 [o3]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html#methods
 [fc]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html#fc
 [urls]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html#URLs_for_gitolite_managed_repos
 [repout]: http://sitaramc.github.com/gitolite/doc/report-output.html
 [transcript]: http://sitaramc.github.com/gitolite/doc/install-transcript.html
 [openssh56]: http://www.openssh.org/txt/release-5.6
 [tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial
 [wo]: http://sitaramc.github.com/gitolite/doc/authentication-vs-authorisation.html
 [putty]: http://sitaramc.github.com/gitolite/contrib/putty.html
-<a name="_appendix_5_why_bypassing_gitolite_causes_a_problem"></a>
+## appendix 5: why bypassing gitolite causes a problem
 ### appendix 5: why bypassing gitolite causes a problem
 When you bypass gitolite, you end up running your normal shell instead of the
 special gitolite entry point script `gl-auth-command`.
--- a/doc/3-faq-tips-etc.mkd
+++ b/doc/3-faq-tips-etc.mkd
@ -1,47 +1,6 @@
-# assorted faqs, tips, and notes on gitolite
+# F=tips assorted tips and notes
-In this document:
+## common errors and mistakes
  * <a href="#_common_errors_and_mistakes">common errors and mistakes</a>
  * <a href="#_other_errors_warnings_notes_">other errors, warnings, notes...</a>
      * <a href="#_cloning_an_empty_repo">cloning an empty repo</a>
      * <a href="#_all_syntax_for_repos">`@all` syntax for repos</a>
  * <a href="#_features">features</a>
      * <a href="#_syntax_and_normal_usage">syntax and normal usage</a>
          * <a href="#_one_user_many_keys">one user, many keys</a>
      * <a href="#_security_access_control_and_auditing">security, access control, and auditing</a>
          * <a href="#_two_levels_of_access_rights_checking">two levels of access rights checking</a>
          * <a href="#_better_logging">better logging</a>
          * <a href="#_delegating_parts_of_the_config_file">delegating parts of the config file</a>
      * <a href="#_convenience_features">convenience features</a>
          * <a href="#_what_repos_do_I_have_access_to_">what repos do I have access to?</a>
          * <a href="#_support_for_git_installed_outside_default_PATH">support for git installed outside default PATH</a>
          * <a href="#_personal_branches">"personal" branches</a>
          * <a href="#_custom_hooks_and_custom_git_config">custom hooks and custom git config</a>
          * <a href="#_bypassing_gitolite">bypassing gitolite</a>
          * <a href="#_gl_admin_push_bypassing_gitolite_for_the_gitolite_admin_repo">gl-admin-push: bypassing gitolite for the gitolite-admin repo</a>
          * <a href="#_disabling_write_access_to_take_backups">disabling write access to take backups</a>
      * <a href="#_INconvenience_features">INconvenience features</a>
          * <a href="#_deleting_a_repo">deleting a repo</a>
          * <a href="#_renaming_a_repo">renaming a repo</a>
      * <a href="#_helping_with_gitweb">helping with gitweb</a>
          * <a href="#_easier_to_link_gitweb_authorisation_with_gitolite">easier to link gitweb authorisation with gitolite</a>
          * <a href="#_umask_setting">umask setting</a>
      * <a href="#_advanced_features">advanced features</a>
          * <a href="#_repos_named_with_wildcards">repos named with wildcards</a>
          * <a href="#_admin_defined_commands">admin defined commands</a>
          * <a href="#_access_control_for_external_commands">access control for external commands</a>
              * <a href="#_svnserve">svnserve</a>
  * <a href="#_odds_and_ends">odds and ends</a>
      * <a href="#_poking_the_admin_repo_to_force_a_compile">"poking" the admin repo to force a compile</a>
  * <a href="#_design_choices">design choices</a>
      * <a href="#_keeping_the_parser_and_the_access_control_separate">keeping the parser and the access control separate</a>
 ----
 <a name="_common_errors_and_mistakes"></a>
 ### common errors and mistakes
  * adding `repositories/` at the start of the repo name in the `git clone`.
    This error is typically made by the *admin* himself -- because he knows
@ -63,13 +22,9 @@ In this document:
    Please see doc/ssh-troubleshooting.mkd for what all this means.
-<a name="_other_errors_warnings_notes_"></a>
+## other errors, warnings, notes...
-### other errors, warnings, notes...
+### cloning an empty repo
 <a name="_cloning_an_empty_repo"></a>
 #### cloning an empty repo
 Cloning an empty repo is only possible with clients greater than 1.6.2.  So at
 least one of your clients needs to have a recent git.  Once at least one
@ -80,9 +35,7 @@ end hung up unexpectedly`.  However, you can ignore this, since it doesn't
 seem to hurt anything.  [Update 2009-09-14; this has been fixed in git
 1.6.4.3]
-<a name="_all_syntax_for_repos"></a>
+### `@all` syntax for repos
 #### `@all` syntax for repos
 There *is* a way to use the `@all` syntax for repos also, as described in
 `doc/gitolite.conf.mkd`.  However, there are a couple of minor cautions:
@ -91,23 +44,15 @@ There *is* a way to use the `@all` syntax for repos also, as described in
    the potential for defeating a crucial optimisation and slowing down *all*
    access, we do not support this.
-<a name="_features"></a>
+## features
 ### features
 Apart from the big ones listed in the top level README, and subjective ones
 like "better config file format", gitolite has evolved to have many useful
 features than the original goal of branch-level access control.
-<a name="_syntax_and_normal_usage"></a>
+### syntax and normal usage
-#### syntax and normal usage
+#### #multikey one user, many keys
 <a name="multikeys"></a>
 <a name="_one_user_many_keys"></a>
 ##### one user, many keys
 If you have a user who has more than one pubkey (like from different machines)
 the simplest way to deal with it is to add subdirectories and add keys there.
@ -117,13 +62,14 @@ For example, I might have these files in `keydir/`:
    home/sitaram.pub
    laptop/sitaram.pub
-<font color="gray">
+##### F=oldmultikeys old style multi keys
-The older method will continue to work, simply because I prefer it.  But I am
+This is an older method of enabling multi-keys.  It will continue to work and
-not going to document it except for the example below, nor am I going to
+be supported in *code*, simply because I prefer it.  But I am not going to
-support it in terms of questions.  Sorry.  Apparently it was too complex to
+document it except for the example below, nor am I going to support it in
-understand, even for some smart folks I know.  This tells me it was probably
+terms of questions.  Sorry.  Apparently it was too complex to understand, even
-ill thought out and should have been obsoleted as soon as e0fe73a was pushed.
+for some smart folks I know.  This tells me it was probably ill thought out
 and should have been obsoleted as soon as e0fe73a was pushed.
 Anyway, here's *all* the documentation for it -- some sample pubkey filenames
 and the corresponding derived usernames:
@ -146,15 +92,9 @@ and the corresponding derived usernames:
        sitaramc@gmail.com@laptop.pub           sitaramc@gmail.com
        sitaramc@gmail.com@desktop.pub          sitaramc@gmail.com
-</font>
+### F=_tipssec security, access control, and auditing
-<a name="_security_access_control_and_auditing"></a>
+#### #2levels two levels of access rights checking
 #### security, access control, and auditing
 <a name="_two_levels_of_access_rights_checking"></a>
 ##### two levels of access rights checking
 Gitolite has two levels of access checks.  The **first check** is what I will
 call the **pre-git** level.  At this stage, the `gl-auth-command` has been
@ -189,9 +129,7 @@ any of the refexes match, the push succeeds.  If none of them match, it fails.
 Gitolite also allows "exclude" or "deny" rules.  See later in this document
 for details.
-<a name="_better_logging"></a>
+#### better logging
 ##### better logging
 If you have been too liberal with the permission to rewind, it has built-in
 logging as an emergency fallback if someone goes too far, or for audit
@ -217,31 +155,23 @@ 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="_delegating_parts_of_the_config_file"></a>
+#### delegating parts of the config file
 ##### delegating parts of the config file
 You can now split up the config file and delegate the authority to specify
-access control for their own pieces.  See [delegation][] for details.
+access control for their own pieces.  See [delegation][deleg] for details.
-<a name="_convenience_features"></a>
+### F=_tnconv convenience features
-#### convenience features
+#### what repos do I have access to?
 <a name="_what_repos_do_I_have_access_to_"></a>
 ##### what repos do I have access to?
 Sometimes there are too many repos, maybe even named similarly, or with the
 potential for typos, confusion about hyphens/underscores or upper/lower case,
 etc.  You'd just like a simple way to know what repos you have access to.
-Gitolite provides two commands (`info` and `expand`) to help you find this
+Gitolite provides two commands ([`info`][info] and [`expand`][expand])
-information; please check [doc/report-output.mkd][repout] for details.
+to help you find this information.
-<a name="_support_for_git_installed_outside_default_PATH"></a>
+#### support for git installed outside default PATH
 ##### support for git installed outside default PATH
 The normal solution is to add to the system default PATH somehow, either by
 munging `/etc/profile` or by enabling `PermitUserEnvironment` in
@ -273,9 +203,7 @@ the full PATH in the rc file, like so:
    $ENV{PATH} = "/home/sitaram/bin:$ENV{PATH}";
-<a name="_personal_branches"></a>
+#### #pers "personal" branches
 ##### "personal" branches
 "personal" branches are great for corporate environments, where
 unauthenticated pull/clone is a no-no.  Since a dev workstation cannot do
@ -283,31 +211,26 @@ authentication, even work shared just between 2 devs has to go *via* the
 server.  This causes the same branch name clutter as in a centralised VCS,
 plus setting up permissions for this becomes a chore for the admin.
-gitolite lets you define a "personal" or "scratch" namespace prefix for each
+Personal branches exist **in a namespace** of their own.  The syntax is
 developer (e.g., `refs/personal/<devname>/*`).  Just add a line like:
        RW+ personal/USER/  =   @userlist
-This means I (user "sitaram") can do anything to any branch whose name starts
+where the "personal" can be anything you like (but cannot be empty), and the
-with `personal/sitaram/` assuming I'm in "userlist".
+"/USER/" part is **necessary (including both slashes)**.  A user "alice" (if
 she's in the userlist) can then push any branches inside `personal/alice/`.
 Which means she can push `personal/alice/foo` and `personal/alice/bar`, but
 NOT `personal/alice`.
-You can have any number of such lines with different prefixes (for example,
+(Background: at runtime the "USER" component will be replaced by the name of
-using topic names instead of "personal") or even suffixes if you like.  The
+the invoking user.  Access is determined by the right hand side, as usual).
 important thing is that the "branch" name should contain `/USER/` (including
 the slashes).  At runtime this will match whoever is the current user.  Access
 is still determined by the right hand side of course.
-<a name="_custom_hooks_and_custom_git_config"></a>
+#### custom hooks and custom git config
 ##### custom hooks and custom git config
 You can specify hooks that you want to propagate to all repos, as well as
 per-repo "gitconfig" settings.  Please see `doc/2-admin.mkd` and
 `doc/gitolite.conf.mkd` for details.
-<a name="_bypassing_gitolite"></a>
+#### bypassing gitolite
 ##### bypassing gitolite
 Sometimes you'll need to access one of the gitolite-managed repos directly on
 the server, without going through gitolite.  Reasons may be some automatic
@ -328,9 +251,7 @@ to set that variable permanently, preferring this mode instead:
    GL_BYPASS_UPDATE_HOOK=1 git push
-<a name="_gl_admin_push_bypassing_gitolite_for_the_gitolite_admin_repo"></a>
+#### F=adminpush gl-admin-push: bypassing gitolite for the gitolite-admin repo
 ##### gl-admin-push: bypassing gitolite for the gitolite-admin repo
 The method described in the previous section (setting `GL_BYPASS_UPDATE_HOOK`)
 will work for all the repos managed by gitolite, **except** for the special
@ -360,9 +281,7 @@ the server.  Here's how:
 Note that this method will work for *any* repo, not just the special admin
 repo.
-<a name="_disabling_write_access_to_take_backups"></a>
+#### #disable disabling write access to take backups
 ##### disabling write access to take backups
 If you want to take normal, OS-level, backups of the system, you might want
 git to be quiescent during that time, so that the backup is clean.  The best
@ -387,17 +306,13 @@ I leave it to you to
    that no push is *in progress* by checking for any `git-receive-pack`
    processes in a `ps` output.
-<a name="_INconvenience_features"></a>
+### INconvenience features
-#### INconvenience features
+#### #repodel deleting a repo
 <a name="_deleting_a_repo"></a>
 ##### deleting a repo
 By design, there is no code in gitolite to *delete* a repo if the repo was
 specified by name in the config file.  (Wildcard repos *can* be deleted by the
-user; see [here][rmrepo] for details).
+user; see [here][wild_repodel] for details).
 If you *do* want to permanently delete a *non*-wildcard repo, here's what you
 do:
@ -408,9 +323,7 @@ do:
  * *then* remove the repo from `~/repositories` on the server (or whatever
    you set `$REPO_BASE` to in the `~/.gitolite.rc`)
-<a name="_renaming_a_repo"></a>
+#### renaming a repo
 ##### renaming a repo
 This is similar; there's no code to do this in gitolite.  What you do is:
@ -422,9 +335,7 @@ This is similar; there's no code to do this in gitolite.  What you do is:
 The order of these 2 steps is important; do not reverse them :-)
-<a name="_helping_with_gitweb"></a>
+### helping with gitweb
 #### helping with gitweb
 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
@ -433,11 +344,7 @@ complete, you can do it all from within the gitolite config file!
 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
+#### #gitwebauth easier to link gitweb authorisation with gitolite
 <a name="_easier_to_link_gitweb_authorisation_with_gitolite"></a>
 ##### easier to link gitweb authorisation with gitolite
 Over and above whether a repo is even *shown* by gitweb, you may want to
 further restrict people, allowing them to view *only* those repos for which
@ -471,74 +378,27 @@ Gitweb allows you to specify a subroutine to decide on access.  We use that
 feature and tie it to gitolite.  Configuration example can be found in
 `contrib/gitweb/`.
-<a name="_umask_setting"></a>
+#### #umask umask setting
 ##### umask setting
 Gitweb not able to read your repos?  You can change the umask for newly
-created repos to something more relaxed -- see the `REPO_UMASK` setting in the [`~/.gitolite.rc`][rc] file.
+created repos to something more relaxed -- see the `REPO_UMASK` setting in the
 [rc file documentation][rc].
-[rc]: http://sitaramc.github.com/gitolite/doc/gitolite.rc.html
+### advanced features
-<a name="_advanced_features"></a>
+There are some really cool features that are now in pretty wide use.
-#### advanced features
+  * **[repos named with wildcards][wild]** is useful when some or most of your
    repos fit a pattern, avoiding the need to name repos individually in the
    config file.  New repos matching the pattern can be created by any user
    (if you give them rights to), with a set of permissions assigned to
    "roles", and the creator can then place users into those roles.
-<a name="_repos_named_with_wildcards"></a>
+  * **[admin defined commands][ADCs]** allow controlled access to specific
-
+    commands and scripts without giving users full shell access.
 ##### repos named with wildcards
 Please see `doc/wildcard-repositories.mkd` for all the details.
 <a name="_admin_defined_commands"></a>
 ##### admin defined commands
 This requires the wildcards feature to be enabled, but is then an extremely
 powerful feature.  See `doc/admin-defined-commands.mkd`.
 <a name="_access_control_for_external_commands"></a>
 ##### access control for external commands
 Gitolite now has a mechanism for allowing access control for arbitrary
 external commands, as long as they are invoked via ssh and present a
 server-side command that contains enough information to make an access control
 decision.
 Note that this is incompatible with giving people shell access as described in
 `doc/ssh-troubleshooting.mkd` -- people who have shell access are not
 subject to this mechanism (it wouldn't make sense to try and control someone
 who has shell access anyway).
 In general, external commands require changes in one or both the config files;
 the sample files in `conf/` double as documentation, so you should look there
 for examples and usage.
 Commands implemented so far are:
  * rsync
  * svnserve (see next section for a brief description; this has been
    contributed by Simon and Vladimir)
 <a name="_svnserve"></a>
 ###### svnserve
 If you are transitioning from SVN to gitolite, and have a lot of users using
 public-key authentication with SVN, this feature may be useful to you. Once
 you migrate all users' public keys into gitolite, you can set the `$SVNSERVE`
 variable in `~/.gitolite.rc` to tie `svnserve` with gitolite's authentication
 system. Assuming you installed gitolite to the same user as the one you used
 for SVN, SVN connectivity will be retained, and users will be able to use
 both SVN and git using the same SSH configuration.
 <a name="_odds_and_ends"></a>
 ### odds and ends
 <a name="_poking_the_admin_repo_to_force_a_compile"></a>
 #### "poking" the admin repo to force a compile
 Sometimes you need to force a compile, as if you pushed the gitolite-admin
@ -549,29 +409,3 @@ repo.  I have a git alias that looks like this:
 so I just run `git poke`.  This toggles between deleting and creating a dummy
 branch called "poke".  Either operation will trigger the hooks.
 <a name="_design_choices"></a>
 ### design choices
 <a name="_keeping_the_parser_and_the_access_control_separate"></a>
 #### keeping the parser and the access control separate
 There are two programs concerned with access control:
  * `gl-auth-command`, the program that is run via `~/.ssh/authorized_keys`;
    this decides whether git should even be allowed to run (basic R/W/no
    access).  (This one cannot decide on the branch-level access; it is not
    known at this point what branch is being accessed)
  * the update-hook on each repo, which decides the per-branch permissions
 I have chosen to keep the relatively complex task of parsing the config file
 out of them to keep them simpler (and faster).  So any changes to the config
 have to be first "compiled", and the access control programs use this
 "compiled" version of the config.  (The compile step also refreshes
 `~/.ssh/authorized_keys`).
 [repout]: http://sitaramc.github.com/gitolite/doc/report-output.html
 [delegation]: http://sitaramc.github.com/gitolite/doc/delegation.html
 [rmrepo]: http://sitaramc.github.com/gitolite/doc/admin-defined-commands.html#rmrepo
--- a/doc/uninstall.mkd
+++ b/doc/uninstall.mkd
@ -1,67 +0,0 @@
 ## uninstalling gitolite
 Sometimes you might find gitolite is overkill -- you have only one user
 (yourself) pushing maybe.  Or maybe gitolite is just not enough -- you want a
 web-based front end that users can use to manage their keys themselves, etc.,
 in which case you'd probably switch to [github][g1], [girocco][g2],
 [indefero][g3] or [gitorious][g4].  [Gerrit][g5] is quite nice too, if you
 want collaborative code review there's nothing like it.  Either way, you'd
 like to uninstall gitolite.
 [g1]: http://github.com
 [g2]: http://repo.or.cz/w/girocco.git
 [g3]: http://www.indefero.net/
 [g4]: http://gitorious.com/
 [g5]: http://code.google.com/p/gerrit/
 Uninstalling gitolite is fairly easy, although it is manual.  (We'll assume
 `$REPO_BASE` in the rc file was left at its default of `~/repositories`; if
 not, adjust accordingly):
 **server side tasks**
  * edit `~/.ssh/authorized_keys` and delete the `# gitolite start` and `#
    gitolite end` markers and all the lines between them.  This will prevent
    any of your users from attempting a push while you are doing this.
    If you are the only user, and/or *need* one or more of those keys to
    continue to access this account (like if one of them is your laptop or
    your home desktop etc.) then instead of deleting the line you can just
    delete everything upto but not including the words "ssh-rsa" or "ssh-dss".
  * Now remove (or move aside or rename to something else if you're paranoid)
    the following files and directories.
        ~/.gitolite
        ~/.gitolite.rc
        ~/repositories/gitolite-admin.git
  * You can remove all of `~/repositories` if you have not really started
    using gitolite properly yet; that's your choice.
    If you *do* need to preserve the other repos and continue to use them,
    remove all the `update` hooks that git installs on each repository.  The
    easiest way is:
        find ~/repositories -wholename "*.git/hooks/update" | xargs rm -f
    but you can do it manually if you want to be careful.
 **client side tasks**
  * Any remote users that still have access must update their clone's remote
    URLs (edit `.git/config` in the repo) to prefix `repositories/` before the
    actual path used, in order for the remote to still work.  This is because
    you'll now be accessing it through plain ssh, which means you have to give
    it the full path.
  * Finally, you as the gitolite admin will probably have a host stanza for
    "gitolite" in your *client*'s `~/.ssh/config`.  Find and delete lines that
    look like this:
        host gitolite
            user git
            hostname your.server
            port 22
            identityfile ~/.ssh/your-gitolite-admin-username
--- a/doc/user-manual.mkd
+++ b/doc/user-manual.mkd
@ -1,4 +1,4 @@
-# what users (not admins) need to know about gitolite
+# F=user what users (not admins) need to know about gitolite
 ...written for the one guy in the world no one will think of as "just a normal
 user" ;-)
@ -7,22 +7,7 @@ This document has some text, and a lot of links.  Most of this info *is*
 available in the rest of the documentation, but it's scattered and sparse.
 Collecting all of it, or at least links to it, in one place sounds useful.
-In this document:
+## accessing gitolite
  * <a href="#_accessing_gitolite">accessing gitolite</a>
  * <a href="#_always_available_commands">always available commands</a>
  * <a href="#_digression_two_kinds_of_repos">digression: two kinds of repos</a>
  * <a href="#_commands_only_available_with_wildrepos_on">commands only available with "wildrepos" on</a>
      * <a href="#_listing_repos_you_created">listing repos you created</a>
      * <a href="#_set_get_additional_permissions_for_repos_you_created">set/get additional permissions for repos you created</a>
      * <a href="#_adding_a_description_to_repos_you_created">adding a description to repos you created</a>
  * <a href="#_site_local_commands">"site-local" commands</a>
 ----
 <a name="_accessing_gitolite"></a>
 ### accessing gitolite
 The most common setup is based on ssh, where your admin asks you to send him
 your public key, and uses that to setup your access.
@ -34,9 +19,7 @@ document), or an ssh command (like `ssh git@server info`).
 Note that you do *not* get a shell on the server -- the whole point of
 gitolite is to prevent that!
-<a name="_always_available_commands"></a>
+## always available commands
 ### always available commands
 The only command that is *always* available to every user is the [`info`
 command][info], which tells you what version of gitolite and git are on the
@ -44,48 +27,36 @@ server, and what repositories you have access to.  The list of repos is very
 useful if you have doubts about the spelling of some new repo that you know
 was setup.
-[info]: http://sitaramc.github.com/gitolite/doc/report-output.html#_the_info_command
+## digression: two kinds of repos
 <a name="_digression_two_kinds_of_repos"></a>
 ### digression: two kinds of repos
 Gitolite has two kinds of repos.  Normal repos are specified by their full
 names in the config file.  "Wildcard" repos are specified by a regex in the
-config file.  If you look at the documentation on the [`info` command][info]
+config file.  Try the [`info` command][info] and see if it shows any lines
-you will see there are a couple of lines that look like regex patterns,
+that look like regex patterns, (with a "C" permission in addition to the "R"
-against which you see an additional "C" permission not available with the
+and the "W").
 others.
-This means you are allowed to create brand new repos whose names fit that
+If you see any, it means you are allowed to create brand new repos whose names
-pattern.  When you create such a repo, your "ownership" of it (as far as
+fit that pattern.  When you create such a repo, your "ownership" of it (as far
-gitolite is concerned) is noted by creating a 1-line file called "gl-creater"
+as gitolite is concerned) is *automatically* recorded by creating a 1-line
-(note spelling!) in the repo directory, with just your gitolite userid in it.
+file called "gl-creater" (note spelling!) in the repo directory, with just
 your gitolite userid in it.
-This happens automatically.  But for repos that were migrated into gitolite
+This is for new repos you create.  But for repos that already existed and were
-and whose names fit a pattern, the admin has to manually create those files,
+migrated into gitolite by the admin, the admin has to manually create that
-otherwise you won't be able to execute certain commands that you otherwise
+"gl-creater" file, otherwise you won't be able to execute certain commands
-might have access to.
+that you otherwise might have access to.
-"Wildrepos" is an optional feature of gitolite that the admin has to "turn
+"Wildrepos" is an optional feature of gitolite that the admin has to
-on".
+explicitly enable.
-<a name="_commands_only_available_with_wildrepos_on"></a>
+## commands only available with "wildrepos" on
-### commands only available with "wildrepos" on
+### listing repos you created
 <a name="_listing_repos_you_created"></a>
 #### listing repos you created
 The info command will not show you your own wildcard repos.  To get that list,
 try the [`expand` command][expand].
-[expand]: http://sitaramc.github.com/gitolite/doc/report-output.html#_the_expand_command
+### set/get additional permissions for repos you created
 <a name="_set_get_additional_permissions_for_repos_you_created"></a>
 #### set/get additional permissions for repos you created
 The gitolite config may have several permissions lines for your repo, like so:
@ -120,11 +91,7 @@ given read access to the special 'gitolite-admin' repo.  Sorry.  The idea is
 that your admin will tell you what "roles" he added into rules for your repos,
 and what permissions those roles have.
-[setperms]: http://sitaramc.github.com/gitolite/doc/wildcard-repositories.html#_handing_out_rights_to_wildcard_matched_repos
+### #setdesc adding a description to repos you created
 <a name="_adding_a_description_to_repos_you_created"></a>
 #### adding a description to repos you created
 The `setdesc` and `getdesc` commands work similarly to the `setperms` and
 `getperms` commands.  You just say
@ -135,9 +102,7 @@ and if you want to check you just say
    ssh git@server getdesc pub/<yourname>/<your_reponame>
-<a name="_site_local_commands"></a>
+## "site-local" commands
 ### "site-local" commands
 The main purpose of gitolite is to prevent you from getting a shell.  But
 there are commands that you often need to run on the server (i.e., cannot be
@ -151,10 +116,9 @@ starting point for his own, if he chooses.
 Think of these commands as equivalent to those in `COMMAND_DIR` in `man
 git-shell`.
-Most of the shipped ADCs are briefly described [here][ADCs], with links to
+Most of the shipped ADCs are briefly described [here][shipped_ADCs], with links
-more details if available.  However, **please understand** that these commands
+to more details if available.  However, **please understand** that these
-may not be available, or their behaviour may have been changed to suit local
+commands may not be available, or their behaviour may have been changed to
-requirements, and of course new ones may have been added.  You'll have to ask
+suit local requirements, and of course new ones may have been added.  You'll
-your local admin for answers, not me!
+have to ask your local admin for answers, not me!
 [ADCs]: http://sitaramc.github.com/gitolite/contrib/adc/README.html
--- a/doc/who-uses-it.mkd
+++ b/doc/who-uses-it.mkd
@ -1,4 +1,4 @@
-# who uses gitolite
+# F=who who uses gitolite
 >   >   If you're using gitolite and find it very useful in some way, I would
 >   >   love to describe your use of it or add a link to your own description
@ -12,7 +12,6 @@ for them (their config file was so big that without the big-config changes
 gitolite would just run out of memory and die!).
 [fedora]: http://lists.fedoraproject.org/pipermail/devel-announce/2010-July/000647.html
 [bc]: http://sitaramc.github.com/gitolite/doc/big-config.html
 The **KDE project** [uses][kde] gitolite (in combination with redmine for
 issue tracking and reviewboard for code review).  Apart from the usual access
@ -39,7 +38,6 @@ little one-man show!
 He explains his use of it [here][hiren].
 [wild]: http://sitaramc.github.com/gitolite/doc/wildcard-repositories.html
 [hiren]: http://ece.uwaterloo.ca/~hdpatel/uwhtml/wildrepos-in-gitolite/
 **Gentoo Linux** has [just moved][gentoo1] their git repositories from gitosis
--- a/doc/wildcard-repositories.mkd
+++ b/doc/wildcard-repositories.mkd
@ -1,4 +1,4 @@
-## repositories named with wildcards
+# F=wild repositories named with wildcards
 ***IMPORTANT NOTE***:
@ -10,33 +10,11 @@ I haven't found any yet, but that doesn't mean there aren't any.
 ----
 In this document:
  * <a href="#_quick_introduction">quick introduction</a>
  * <a href="#_rc_file_setting_required">rc file setting required</a>
  * <a href="#_examples_of_wildcard_repos">examples of wildcard repos</a>
      * <a href="#_wildcard_repos_with_creator_name_in_them">wildcard repos with creator name in them</a>
      * <a href="#_wildcard_repos_without_creator_name_in_them">wildcard repos without creator name in them</a>
  * <a href="#_side_note_valid_regexes">side-note: valid regexes</a>
  * <a href="#_side_note_line_anchored_regexes">side-note: line-anchored regexes</a>
      * <a href="#_contrast_with_refexes">contrast with refexes</a>
  * <a href="#_handing_out_rights_to_wildcard_matched_repos">handing out rights to wildcard-matched repos</a>
  * <a href="#_admin_adding_other_roles_than_READERS_and_WRITERS">(admin) adding other roles than READERS and WRITERS</a>
      * <a href="#_IMPORTANT_WARNING_ABOUT_THIS_FEATURE_">**IMPORTANT WARNING ABOUT THIS FEATURE**</a>
  * <a href="#_setting_a_gitweb_description_for_a_wildcard_matched_repo">setting a gitweb description for a wildcard-matched repo</a>
  * <a href="#_reporting">reporting</a>
  * <a href="#_deleting_a_wild_repo">deleting a wild repo</a>
  * <a href="#_how_it_actually_works">how it actually works</a>
 ----
 This document is mostly "by example".
 ----
-<a name="_quick_introduction"></a>
+## quick introduction
 ### quick introduction
 The wildrepos feature allows you to specify access control rules using regular
 expression patterns, so you can have many actual repos being served by a
@ -44,17 +22,13 @@ single set of rules in the config file.  The regex pattern can also include
 the word `CREATOR` in it, allowing you to parametrise the name of the user
 creating the repo.  The examples below will make this clearer.
-<a name="_rc_file_setting_required"></a>
+## rc file setting required
 ### rc file setting required
 This feature requires that you set `$GL_WILDREPOS` to "1" in `~/.gitolite.rc`
 on the server.  Please search for that variable in `doc/gitolite.rc.mkd`
 for more information on this.
-<a name="_examples_of_wildcard_repos"></a>
+## examples of wildcard repos
 ### examples of wildcard repos
 As the introduction said, you can include the word `CREATOR` in the regex
 pattern, though it is not mandatory.  We'll look at examples of both types of
@ -71,9 +45,7 @@ keep track of who actually created the repo (except for granting access), but
 needs more communication / co-operation among the users to avoid repo name
 clashes.
-<a name="_wildcard_repos_with_creator_name_in_them"></a>
+### wildcard repos with creator name in them
 #### wildcard repos with creator name in them
 Here's an example snippet:
@ -102,9 +74,7 @@ new repo, as user "u4" (a student):
 Notice the *two* empty repo inits, and the order in which they occur ;-)
-<a name="_wildcard_repos_without_creator_name_in_them"></a>
+### wildcard repos without creator name in them
 #### wildcard repos without creator name in them
 Here's how the same example would look if you did not want the CREATOR's name
 to be part of the actual repo name.
@ -129,7 +99,7 @@ and have a TA create the repos in advance.
 In either case, they could then use the `setperms` feature to specify which
 users are "READERS" and which are "WRITERS".  See later for details.
-<a name="_side_note_valid_regexes"></a>
+## F=wildregex valid regexes and how they are used
 ### side-note: valid regexes
@ -140,8 +110,6 @@ look like a regex to gitolite.  Use `foo/..*` if you want that.
 Also, `..*` by itself is not considered a valid repo pattern.  Try
 `[a-zA-Z0-9].*`.
 <a name="_side_note_line_anchored_regexes"></a>
 ### side-note: line-anchored regexes
 A regex like
@ -157,8 +125,6 @@ But you may be surprised to find that it does not match even
 `^assignments/S[0-9]+/A[0-9]+$` -- notice the line beginning and ending
 metacharacters.
 <a name="_contrast_with_refexes"></a>
 #### contrast with refexes
 Just for interest, note that this is in contrast to the refexes for the normal
@ -169,9 +135,7 @@ if no one will actually push such a branch!  You can anchor both sides if you
 really care, by using `master$` instead of `master`, but that is *not* the
 default for refexes.
-<a name="_handing_out_rights_to_wildcard_matched_repos"></a>
+## F=setperms handing out rights to wildcard-matched repos
 ### handing out rights to wildcard-matched repos
 In the examples above, we saw two special "user" names: READERS and WRITERS.
 The permissions they have are controlled by the config file, but ***who is
@ -193,7 +157,7 @@ Create a small text file that contains the permissions you desire:
    WRITERS u6
    (hit ctrl-d here)
-...and use the new "setperms" command to set permissions for your repo:
+...and use the new **setperms** command to set permissions for your repo:
    $ ssh git@server setperms assignments/u4/a12 < myperms
    New perms are:
@ -201,7 +165,7 @@ Create a small text file that contains the permissions you desire:
    WRITERS u6
 'setperms' will helpfully print what the new permissions are but you can also
-use 'getperms' to check:
+use **getperms** to check:
    $ ssh git@server getperms assignments/u4/a12
    READERS u5
@ -215,8 +179,6 @@ The following points are important:
    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>
 ### (admin) adding other roles than READERS and WRITERS
 Let's say your needs are more complex and you need more roles.  For example,
@ -244,9 +206,7 @@ people, say by sending something like this to `setperms`:
 You can enable this by setting the `GL_WILDREPOS_PERM_CATS` variable in the rc
 file.  The rc file documentation (`doc/gitolite.rc.mkd`) explains how.
-<a name="_IMPORTANT_WARNING_ABOUT_THIS_FEATURE_"></a>
+#### #rolenamewarn **IMPORTANT WARNING ABOUT THIS FEATURE**
 #### **IMPORTANT WARNING ABOUT THIS FEATURE**
 Please make sure that none of the role names conflict with any of the
 **usernames** in the system.  For example, if you have a user called "foo",
@ -256,34 +216,28 @@ make sure you do not include "foo" as a valid role in
 You can keep things sane by using UPPERCASE names for roles, while keeping all
 your usernames lowercase; then you don't have to worry about this problem.
-<a name="_setting_a_gitweb_description_for_a_wildcard_matched_repo"></a>
+## setting a gitweb description for a wildcard-matched repo
-### setting a gitweb description for a wildcard-matched repo
+Similar to the getperms/setperms commands, there are the
 [getdesc/setdesc][setdesc] commands, thanks to Teemu.
-Similar to the getperms/setperms commands, there are the getdesc/setdesc
+## reporting
 commands, thanks to Teemu.
 <a name="_reporting"></a>
 ### reporting
 In order to see what repositories were created from a wildcard, use the
-"expand" command, described briefly in [doc/report-output.mkd][repout].
+["expand"][expand] command.
-<a name="_deleting_a_wild_repo"></a>
+## deleting a wild repo
-### deleting a wild repo
+See [repo deletion][wild_repodel] for more on this.  Note that this requires you
 to install/setup "adc"s (admin defined commands).  See
 [admin-defined-commands][ADCs] for how to do that.
-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://sitaramc.github.com/gitolite/doc/admin-defined-commands.html
+Enjoy, and please use with care.  This is pretty powerful stuff.  As they say:
-[rmr]: http://sitaramc.github.com/gitolite/contrib/adc/repo-deletion.html
+if you break it, you get to keep both pieces :)
-<a name="_how_it_actually_works"></a>
+## F=_wildhow how it actually works
 ### how it actually works
 This section tells you what is happening inside gitolite so you can understand
 this feature better.  Let's use the config example at the beginning of this
@ -347,9 +301,3 @@ that repo, the ruleset looks like:
 I hope that helps.
 ----
 Enjoy, and please use with care.  This is pretty powerful stuff.  As they say:
 if you break it, you get to keep both pieces :)
 [repout]: http://sitaramc.github.com/gitolite/doc/report-output.html
--- a/t/README-t.mkd
+++ b/t/README-t.mkd
@ -1,26 +1,14 @@
-## notes on the testing setup
+# F=_t notes on the testing setup
 **WARNING: PLEASE use a dedicated user for doing this**.  Various files and
 directories get overwritten and it's much simpler this way.
-In this document:
+## terminology
  * <a href="#_terminology">terminology</a>
  * <a href="#_notes_and_background">notes and background</a>
  * <a href="#_playing_with_gitolite">playing with gitolite</a>
  * <a href="#_testing_gitolite">testing gitolite</a>
  * <a href="#_instructions_for_adding_new_tests">instructions for adding new tests</a>
 <a name="_terminology"></a>
 ### terminology
    #define PW "patches welcome!"
    #define TODO PW
-<a name="_notes_and_background"></a>
+## notes and background
 ### notes and background
 All testing is done on one **brand new** userid.  We use ssh host alias tricks
 to simulate multiple gitolite users within this, so `ssh gitolite info` gets
@ -34,9 +22,7 @@ mirroring, smart http, and password-based access.
 Note that the test driver has evolved as new scripts were added; you will see
 that older scripts are a little less sophisticated.
-<a name="_playing_with_gitolite"></a>
+## playing with gitolite
 ### playing with gitolite
 (Please heed the warning at the top of this document and use a dedicated user
 for this).
@ -85,9 +71,7 @@ access simply using a different URL.  For example, `git clone u1:testing` and
 `git clone u2:testing` may give you different results depending on what rights
 you gave users "u1" and "u2" in your config.
-<a name="_testing_gitolite"></a>
+## testing gitolite
 ### testing gitolite
 First, do what the "playing with gitolite" section says.  That is a
 pre-requisite.
@ -100,9 +84,7 @@ Once that is done, run this command (still in `$HOME` of the gl-test userid):
 numbers be the actual test numbers, making it look like I have over 2000
 tests, when in reality I have about 600)
-<a name="_instructions_for_adding_new_tests"></a>
+## instructions for adding new tests
 ### instructions for adding new tests
 (TODO)
`@ -1,4 +1,4 @@`
	`## mob branches in gitolite`	`# F=mob mob branches in gitolite`

	`WARNING: This is hairy stuff. But what's life without a little danger?`	`WARNING: This is hairy stuff. But what's life without a little danger?`