document overhaul 2 - mostly migration stuff

doc/cust.mkd

@@ -7,6 +7,12 @@ even mirroring is not in core now!)
 
 (Also, please see the [developer notes][dev-notes] page).
 
+----
+
+[[TOC]]
+
+----
+
 ## types of non-core programs
 
 There are 5 basic types of non-core programs.

doc/dev-status.mkd

@@ -2,13 +2,11 @@
 
 Not yet done (will be tackled in this order unless someone asks):
 
-  * svnserve (someone is testing it)
-  * pulling in documentation for things that are the same in g2
   * smart http
-  * special features (no-create-repos, gl-all-read-all, etc)
+  * svnserve (someone is testing it)
   * mechanism for ADCs using unchecked arguments -- this is not just a matter
     of writing it; I have to think about *how* it will be done.  (AFAIK the
-    only tool affected is git-annexe)
+    only tool affected is git-annexe; if there are more let me know)
 
 Help needed:
 
@@ -22,6 +20,7 @@ anyway!):
 
   * mob branches
   * password access
+  * some of the more arcane rc variables!
   * specific ADCs -- there are too many for me to bother without applying
     Pareto somewhere, so I choose to not do any and wait for people to ask :-)
 
@@ -30,6 +29,7 @@ Done:
   * core code
   * test suite
   * mirroring
-  * most documentation
+  * documentation
+  * migration documentation
   * distro packaging instructions
   * migration advice for common cases

doc/g2alt.mkd

@@ -1,9 +0,0 @@
-## #g2alt alternate implementations for some g2 features
-
-The following g2 features have been dropped but suitable (or better)
-alternatives exist.
-
-### gl-time for performance measurement
-
-Take a look at the 'CpuTime' trigger module shipped.  Comments within, and
-comments in the default rc file that contain the word "cpu", should be useful.

doc/g2dropped.mkd

@@ -1,4 +0,0 @@
-## #g2dropped g2 features dropped
-
-(none yet that are not already covered in the rc section in [this][g2migr]
-page).

doc/g2incompat.mkd

@@ -1,13 +1,9 @@
-## #g2incompat incompatibility with g2
+# #g2incompat incompatibility with g2
 
-(other than in the rc file, which is dealt with [elsewhere][g2rcdiff])
+This page expands on some incompatibilities that were only briefly mentioned
+in the [migration][g2migr] page.
 
-The following incompatibilities exist, in vaguely decreasing order of
+## #g2i-name NAME rules
-severity.  **The ones in the first section are IMPORTANT because they allow
-access that was previously not allowed -- please fix your config before using
-the new gitolite!**
-
-### NAME rules
 
 1.  NAME/ rules must be changed to VREF/NAME/
 
@@ -18,7 +14,7 @@ the new gitolite!**
 
         -   VREF/NAME/       =   @all
 
-### subconf command in admin repo
+## #g2i-subconf subconf command in admin repo
 
 (This is also affected by the previous issue, 'NAME rules'; please read that
 as well).
@@ -42,3 +38,66 @@ line.  As the [vref documentation][vref] says:
 The second part explicitly says when and where to include the subconf files.
 (Before subconf was invented, this used to happen implicitly at the end of the
 main conf file, and was hardcoded to that specific glob.)
+
+## #g2i-gl-time gl-time for performance measurement
+
+If you've been using gl-time for performance measurement, there's a much
+better system available now.
+
+gl-time used to only log elapsed time.  The new 'CpuTime' trigger module
+shipped with gitolite, if enabled in the rc file, can also report CPU times
+using perl's 'times()' function.  See comments within that file and in the
+default rc file that contain the word "cpu", for more details.
+
+Further, you can copy that module with a different name, add your own
+functionality, and invoke *that* from the rc file instead.
+
+## #g2i-mirroring changes in mirroring setup
+
+There are several changes with regard to mirroring:
+
+  * there is no 'post-receive' hook to be installed.  Mirroring is handled by
+    g3's [triggers][] mechanism.  Gitolite triggers are enabled by adding (or
+    uncommenting, in this case) appropriate lines in the rc file.
+
+  * the `GL_HOSTNAME` variable is now `HOSTNAME`.  (Note that the rc file
+    syntax itself has changed quite a bit; to be accurate, HOSTNAME is not a
+    variable but a hash key with an associated value).
+
+  * the `GL_GITCONFIG_KEYS` variable is now `GIT_CONFIG_KEYS`, **but** you no
+    longer need to set it to anything for mirroring to work.
+
+  * the `gl-tool` program does not exist anymore.  Adding keys for peer
+    servers is done just like adding user keys, except that the pubkey file
+    name must start with `server-`.  For example, to add a peer host called
+    frodo, you will acquire its pubkey and add it as `server-frodo.pub`.
+
+  * the config variables are quite different now.  The main ones now look like
+    this:
+
+        option mirror.master        =   sam
+        option mirror.slaves        =   frodo gollum
+
+    The redirectOK looks like this:
+
+        option mirror.redirectOK    =   frodo
+
+    The special value "true" to say that all slaves are trusted is now "all":
+
+        option mirror.redirectOK    =   all
+
+  * there are no more mirroring "keys", (lists of servers named in config keys
+    like 'gitolite.mirror.nightly', etc).  You can certainly add lines like
+
+        option mirror.nightly       =   merry pippin
+
+    but they will not be processed by gitolite.  Your cron jobs should use
+    `gitolite git-config` to query this variable, grab the list of repos, and
+    run `gitolite mirror` on each of them.
+
+  * the external command to resync mirrors is 'mirror', run just like any
+    other [command][commands].  In particular, you can run `gitolite mirror
+    -h` to get help.  It cannot be run from a slave to ask a master to push
+    (unlike in the old system) but what's more convenient is that any user who
+    has any access to the master can run it remotely (if you allow it) to
+    invoke a push.

doc/g2migr.mkd

@@ -1,38 +1,181 @@
-## #g2migr migrating from g2
+# #g2migr migrating from g2
 
-<font color="red">
+<font color="red"> **This document is a *MUST* read if you are currently using
+g2 and want to move to g3.** </font>
 
-**This document is a *MUST* read if you are currently using g2 and want to
+----
-move to g3.**
 
-</font>
+[[TOC]]
 
-First things first: g2 will be supported for a good long time.  My current
+----
-*expert* users do not cause me any load anyway.
 
-Migration should be straightforward, but it is not automatic.  You should run
+First things first: g2 will be supported for a good long time for critical
-the "check-g2-compat" program first, to see any *major* differences that
+bugs, although enhancements and new features won't happen.
-affect you.  The bulk of the changes are in the RC file, which must be
-manually handled (links below).  The conf files have very few changes -- they
-apply only if you use "NAME/" or delegation.
 
-You must first read about [incompatible][g2incompat] features and
+Migration should be straightforward, but it is not automatic.  The biggest
-[dropped][g2dropped] features.  Some features have been replaced with
+differences are in the rc file, mirroring, "NAME/" rules, and delegation.
-[alternatives][g2alt].
 
-Since the majority of changes are in the rc file, they're all listed
+>   ----
-[here][g2rcdiff].
 
-The rest of this page describes the completely standalone "check-g2-compat"
+>   **presetting the rc file**
-script that you can find in the repo root (i.e., not in "src/").
 
-### the "check-g2-compat" program
+>   Some rc settings in the older gitolite are such that you cannot directly
+>   run `gitolite setup` when you're ready to migrate.  Doing that will
+>   **clobber** something important.  See [presetting the rc file][rc-preset]
+>   for details.
+
+>   ----
+
+The `check-g2-compat` program attempts to identify any *big* issues you will
+be facing; run that first.  See [later][cg2c] in this page for what its
+messages mean.  If it does not report any issues, your migrate will probably
+go quickly.  I still suggest you go through the links below in case that
+program missed something.
+
+## incompatible features
+
+Here's a list of incompatible features and what you need to do to migrate.
+Some of them have links where there is more detail than I want to put here.
+
+### high impact
+
+(serious loss of functionality and/or access control compromised)
+
+  * [`NAME/`][g2i-name] rules: thes need to change to `VREF/NAME/`, and you
+    need to add a deny rule at the end because fallthru is "success" for all
+    [VREFs][vref] now, including the "NAME" VREF.
+
+  * [subconf][g2i-subconf]: if you're using [delegation][deleg], there is no
+    implicit "subconf" at the end; you'll have to add it in.
+
+  * there are several important differences in mirroring.  You can start from
+    scratch by reading the new [mirroring][mirroring] doc or
+    [migrate][g2i-mirroring] (carefully!).
+
+  * `ADMIN_POST_UPDATE_CHAINS_TO` -- **dropped**.  Add your script to the
+    `POST_COMPILE` trigger chain.  Your script won't be getting the arguments
+    that *git* sends to the post-update hook, but for the admin repo the only
+    argument that even comes in (or is significant) is "refs/heads/master"
+    anyway.
+
+  * `GL_ALL_INCLUDES_SPECIAL` -- **dropped**, **requires presetting**.
+
+    @all always includes gitweb and daemon now.  Use [deny-rules][] if you
+    want to say `R = @all` but not have the repo(s) be visible to gitweb or
+    daemon.
+
+  * `GL_NO_CREATE_REPOS` -- **dropped**.  If you think you need this, email
+    me.  I know one group who does need this so I will be putting it in
+    eventually but not right away.  It's almost certain to be renamed anyway.
+
+  * `GL_NO_DAEMON_NO_GITWEB` **dropped**, **requires presetting**.  Default
+    will clobber your projects.list file and git-daemon-export-ok files.
+
+    Comment out the appropriate lines in the rc file, in the `POST_COMPILE`
+    *and* the `POST_CREATE` trigger sections.  As a bonus, gitweb and daemon
+    can now be separately disabled, instead of both being tied to the same
+    setting.
+
+  * `GL_NO_SETUP_AUTHKEYS` **dropped**, **requires presetting**.  Default will
+    clobber your authkeys file.
+
+    Comment out all the line(s) that call ssh-authkeys in the rc file.
+
+  * `UPDATE_CHAINS_TO` **dropped**, **requires presetting**.  Default will
+    fail to run this extra check when users push.
+
+    Use a [vref][] instead.  You can directly use any existing chained-to
+    script as a VREF; they'll work.  Don't forget to add a rule that
+    references the new VREF!
+
+  * `GIT_PATH` **dropped**, **requires presetting**.
+
+    If you need its functionality, add these lines to the end of the rc file:
+
+        $ENV{PATH}="...whatever you want...";
+        1;
+
+### medium impact
+
+(important functionality lost, but access control not compromised)
+
+  * `GL_ADMINDIR` -- **dropped**, is now at a fixed location: `~/.gitolite`.
+    If you want it somewhere else go ahead and move it, then place a symlink
+    from the assumed location to the real one.
+
+  * `GL_GET_MEMBERSHIPS_PGM` -- is now `GROUPLIST_PGM`, see
+    [here][ldap].
+
+  * `GL_WILDREPOS_DEFPERMS` -- is now `DEFAULT_ROLE_PERMS`.
+
+  * `REPO_BASE` -- **dropped**, is now at a fixed location: `~/repositories`.
+    If you want it somewhere else go ahead and move it, then place a symlink
+    from the assumed location to the real one.
+
+### low impact
+
+(ancillary, non-core, or minor functionality lost)
+
+  * [gl-time][g2i-gl-time]: the CpuTime module replaces gl-time.
+
+  * `BIG_INFO_CAP` -- **dropped**.  If you think you must have this, try it
+    without and see if there's a difference.  If you *know* you need this,
+    convince me.
+
+  * `GL_ADC_PATH` -- **dropped**.  It is obsolete; use [commands][] or add
+    [your own][dev-notes].
+
+  * `GL_ALL_READ_ALL` -- **dropped**.  If you think you must have this, try it
+    without and see if there's a difference.  If you *know* you need this,
+    convince me.
+
+  * `GL_BIG_CONFIG` -- **dropped**.  This feature is default now.
+
+  * `GL_CONF`, `GL_CONF_COMPILED`, and `GL_KEYDIR` -- **dropped**.  You had no
+    business touching these anyway; if you did, move them into the expected
+    default locations before attempting to run `gitolite setup`
+
+  * `GL_GITCONFIG_KEYS` -- is now `GITCONFIG_KEYS`.
+
+  * `GL_LOGT` -- now has a fixed value; email me if this is a problem.
+
+  * `GL_PACKAGE_CONF` and `GL_PACKAGE_HOOKS` -- **dropped**.  They are not
+    needed anymore, but check if you had any custom hooks set in the latter
+    location and copy them across.
+
+  * `GL_PERFLOGT` -- **dropped**.  See [gl-time][g2i-gl-time].
+
+  * `GL_SITE_INFO` -- is now `SITE_INFO`.
+
+  * `GL_WILDREPOS` -- **dropped**.  This feature is default now.
+
+  * `GL_WILDREPOS_PERM_CATS` -- is now the ROLES hash in the rc file.
+
+  * `HTPASSWD_FILE`, `RSYNC_BASE`, `SVNSERVE` -- need work.  Email me if you
+    are using any of these.
+
+  * `NICE_VALUE` -- **dropped**.  Uncomment the 'renice 10' line in the rc
+    file.  You can also change the 10 to something else if you wish.
+
+  * `PROJECTS_LIST` -- is now `GITWEB_PROJECTS_LIST`.  More importantly, it is
+    only used by update-gitweb-access-list in src/commands/post-compile.  This
+    variable now has nothing to do with gitolite core, and the rc is just
+    helping to store settings for external programs like that one.
+
+  * `REPO_UMASK` -- is now `UMASK`.
+
+  * `WEB_INTERFACE` and `GITWEB_URI_ESCAPE` -- **dropped**.  Patches to the
+    update program to directly do those things are welcome.  Personally, I
+    think people who use spaces and other funky characters in dir/file names
+    should be shot but no one listens to me anyway.
+
+## #cg2c using the "check-g2-compat" program
 
 This program checks a few things only, not everything.  In particular, it
 looks for settings and status that might:
 
   * make g3 unusable for lots of users
-  * make g3 give *more* access than g2 under some conditions.
+  * make g3 give *more* access than g2 under some conditions
 
 It does NOT look for or warn about anything else; you're expected to read (and
 act upon, if needed) the rest of the migration guide links given a few paras
@@ -67,8 +210,9 @@ put that contain the words "see docs":
 
   * `mirroring used`
 
-    There have been quite a few changes to mirroring.  Please see the new
+    There have been quite a few changes to mirroring.  You can start from
-    [mirroring][mirroring] doc for details.
+    scratch by reading the new [mirroring][mirroring] doc or
+    [migrate][g2i-mirroring] (carefully!).
 
   * `found N gl-creater files`
 
@@ -89,24 +233,35 @@ put that contain the words "see docs":
     Setting perms of R and RW will no longer work; you have to say READERS and
     WRITERS now.  Suggested command:
 
-The following variables need to be [preset][rc-preset] in the rc file
+## #rc-preset presetting the rc file
-**before** running `gitolite setup`.  Otherwise the default actions will
-clobber something and require some recovery.
 
-  * `GL_NO_SETUP_AUTHKEYS` (default will clobber your authkeys file)
+Some rc settings in the older gitolite are such that you cannot directly run
+`gitolite setup` when you're ready to migrate.  Doing that will **clobber**
+something important.  You have to create a default rc file, edit it
+appropriately, and *then* run `gitolite setup`.
 
-  * `GL_NO_DAEMON_NO_GITWEB` (default will clobber your projects.list file and
+The most serious example of this is `GL_NO_SETUP_AUTHKEYS`, which tells the
-    git-daemon-export-ok files)
+(old) gitolite that you want to manage `~/.ssh/authorized_keys` yourself and
+it should not fiddle with it.
 
-  * `UPDATE_CHAINS_TO` (default will fail to run this extra check when users
+If you don't preset the rc (in this case, by commenting out the 'ssh-authkeys'
-    push)
+line) **before** running `gitolite setup`, **your `~/.ssh/authorized_keys`
+file will get clobbered**.
 
-  * `ADMIN_POST_UPDATE_CHAINS_TO` (severity depends on what your code is
+The actual rc settings that require presetting are listed in the "high
-    doing; see [g2rcdiff][] for how to fix this)
+impact" section above.  This section tells you how to do the presetting.
 
-  * `GL_ALL_INCLUDES_SPECIAL` (default will allow gitweb and daemon to be able
+  * save your old (g2) rc file somewhere, just in case
-    to read any repos that have `R = @all`)
 
-  * `GIT_PATH` (presumably your git is in some non-std path so unless you
+  * run
-    preset `$ENV{PATH}` per instructions in the [rc file
+
-    differences][g2rcdiff] doc, nothing will work).
+        gitolite print-default-rc > $HOME/.gitolite.rc
+
+  * edit the file
+
+        ${EDITOR:-vim} $HOME/.gitolite.rc
+
+    make appropriate changes as described elsewhere in this migration guide,
+    and save it.
+
+  * *then* you can run [gitolite setup][setup].

doc/g2rcdiff.mkd

@@ -1,125 +0,0 @@
-## #g2rcdiff rc file differences between g2 and g3
-
-The new rc file has far fewer variables; many have been dropped.  You should
-not see much ill effect though, but please read below.
-
-### #rc-preset pre-setting the rc file
-
-Some of these settings are such that you cannot directly run `gitolite setup`
-when you're ready to migrate.  Instead, you need to run
-
-    # (assuming you saved your g2 rc file somewhere)
-    gitolite print-default-rc > $HOME/.gitolite.rc
-    $EDITOR $HOME/.gitolite.rc
-    # make appropriate changes (see below), save
-    gitolite setup
-
-The most serious example of this is `GL_NO_SETUP_AUTHKEYS`.  If you don't
-preset the rc (in this case, by commenting out the 'ssh-authkeys' line)
-**before** running `gitolite setup`, your `~/.ssh/authorized_keys` file will
-get clobbered.
-
-There are several other settings that you may want to look at, with varying
-degrees of severity; **please go through the list below before blindly running
-`gitolite setup`**.  (For example, if you had `GL_NO_DAEMON_NO_GITWEB` in g2
-but forgot to comment out all the gitweb and daemon update lines in the rc
-file, your projects.list and git-daemon-export-ok files might get clobbered.
-Of course this is less severe than ssh authkeys but still...).
-
-### rc file differences
-
-**DROPPED** variables (possible high impact): these could be show-stoppers for
-migration, at least for now.
-
-  * `BIG_INFO_CAP` -- if you think you must have this, try it without and see
-    if there's a difference.  If you *know* you need this, convince me.
-
-  * `GL_ALL_READ_ALL` -- same
-
-  * `GL_NO_CREATE_REPOS` -- if you think you need this, email me.  I know one
-    group who does need this so I will be putting it in eventually but not
-    right away.
-
-  * `HTPASSWD_FILE`, `RSYNC_BASE`, `SVNSERVE` -- need work.  Email me if you
-    are using any of these.
-
-  * `GL_GET_MEMBERSHIPS_PGM` -- is high on my todo list
-
-  * `GL_LOGT` -- is now fixed; you can't change it.  Email me if this is a
-    problem.
-
-**DROPPED** variables (medium impact): these have alternative implementations
-or mechanisms, but you have to do some setup work.
-
-  * `GL_ADMINDIR` -- this is now at a fixed location: `~/.gitolite`.  If you
-    want it somewhere else go ahead and move it, then place a symlink from the
-    assumed location to the real one.
-
-  * `REPO_BASE` -- this is now at a fixed location: `~/repositories`.  If you
-    want it somewhere else go ahead and move it, then place a symlink from the
-    assumed location to the real one.
-
-  * `PROJECTS_LIST` -- it's called `GITWEB_PROJECTS_LIST` now, but more
-    importantly, it is only used by update-gitweb-access-list in
-    src/commands/post-compile.  This variable now has nothing to do with
-    gitolite core, and the rc is just helping to store settings for external
-    programs like that one.
-
-    `WEB_INTERFACE` and `GITWEB_URI_ESCAPE` are also gone; patches to the
-    update program to directly do those things are welcome.  Personally, I
-    think people who use spaces and other funky characters in dir/file names
-    should be shot but luckily no one listens to me :-)
-
-  * `GL_NO_DAEMON_NO_GITWEB` -- uncomment the appropriate lines in the rc
-    file, in both the `POST_COMPILE` and `POST_CREATE` trigger sections.
-
-  * `NICE_VALUE` -- uncomment the 'renice 10' line in the rc file.  You can
-    also change the 10 to something else if you wish.
-
-  * `GIT_PATH` -- gone, not needed.  Just add these lines to the end of the rc
-    file:
-
-        $ENV{PATH}="...whatever you want...";
-        1;
-
-  * `GL_NO_SETUP_AUTHKEYS` -- comment out the lines that call ssh-authkeys, in
-    the rc file.
-
-  * `GL_WILDREPOS_DEFPERMS` -- if you need this, add a `POST_CREATE` script
-    that does it.  Or email me and I will write it for you.
-
-  * `UPDATE_CHAINS_TO` -- use a [vref][] instead.  You can directly use the
-    chained-to script as a VREF; it'll work.
-
-  * `ADMIN_POST_UPDATE_CHAINS_TO` -- add your script to the `POST_COMPILE`
-    trigger chain.  You won't be getting any arguments but for the admin repo
-    the only argument that ever comes in is "refs/heads/master" anyway.
-
-  * `GL_ADC_PATH` -- obsolete; use [commands][] or add [your own][dev-notes].
-
-  * `GL_ALL_INCLUDES_SPECIAL` -- obsolete; @all always includes gitweb and
-    daemon now.  Use [deny-rules][] if you want to say `R = @all` but not have
-    it be visible to gitweb or daemon.
-
-  * `GL_PERFLOGT` -- see the entry for "gl-time" in the [alternative
-    implementations][g2alt] page.
-
-**DROPPED** variables (no impact/low impact): these variables should not
-actually affect anything anyway, so even if you had them set you should not
-feel their loss.
-
-  * `GL_CONF`, `GL_KEYDIR`, and `GL_CONF_COMPILED` -- you had no business
-    touching these anyway; if you did, move them into the expected default
-    locations before attempting to run `gitolite setup`
-  * `GL_PACKAGE_HOOKS` -- not needed anymore, but check if you had any custom
-    hooks set there and copy them across.
-  * `GL_WILDREPOS` -- dropped; this feature is default now.
-  * `GL_BIG_CONFIG` -- dropped; this feature is default now.
-
-**RENAMED** variables (no impact): these are functionally the same but are
-renamed.
-
-  * `REPO_UMASK` is now `UMASK`
-  * `GL_GITCONFIG_KEYS` is now `GITCONFIG_KEYS`
-  * `GL_WILDREPOS_PERM_CATS` is now the ROLES hash in the rc file
-  * `GL_SITE_INFO` is now `SITE_INFO`

doc/install.mkd

@@ -1,9 +1,8 @@
 # installing gitolite
 
-**NOTE**: if you're migrating from g2, there are some settings that MUST be
+<font color="red">**NOTE**: if you're migrating from g2, there are some
-dealt with **before** running `gitolite setup`; please read the [g2
+settings that MUST be dealt with **before** running `gitolite setup`; please
-migration][g2migr] page and linked pages, and especially the one on
+read the [g2 migration][g2migr] page and linked pages.</font>
-[presetting the rc file][rc-preset].
 
 ## notes and naming conventions
 
@@ -138,12 +137,12 @@ Creating a symlink doesn't need a separate program but 'install' also runs
 There are a lot of migration hints and notes; see links at the top of this
 document.
 
-But here's the **bottom line** on migrating:
+But here's the **bottom line** on migrating: nothing in any of the gitolite
+install/setup/etc will ever touch the *data* in any repository except the
+gitolite-admin repo.  The only thing it will normally touch is the `update`
+hook.
 
-Nothing in any of the gitolite install/setup/etc will ever touch the *data* in
+So one fool-proof way of "migrating" from any older gitolite is this:
-any repository except the gitolite-admin repo.  The only thing it will
-normally touch is the `update` hook.  So one fool-proof way of "migrating"
-from any older gitolite is this:
 
 1.  Wipe out the old gitolite, but **carefully**
 
@@ -152,14 +151,18 @@ from any older gitolite is this:
       * rename `~/.gitolite.rc` to something else
       * move the ~/.gitolite/logs` directory somewhere else, then delete `~/.gitolite`
 
-2.  Install gitolite g3; see [quick install and setup][qi] or [install][]
+2.  Read about [presetting][rc-preset] the rc file; if you're using any
+    variables listed as requiring preset, follow those instructions to create
+    your new rc file.
+
+3.  Install gitolite g3; see [quick install and setup][qi] or [install][]
     followed by [setup][].
 
-3.  Make sure your gitolite-admin clone has the correct pubkey for the
+4.  Make sure your gitolite-admin clone has the correct pubkey for the
     administrator in its `keydir` directory, then `git push -f` to the server
     to overwrite the "default" admin repo created by the install.
 
-4.  Handle any errors, look for migration issues, etc., as described in the
+5.  Handle any errors, look for migration issues, etc., as described in the
     links at the top of this page.
 
     This also includes building up your new `~/.gitolite.rc` file.

doc/mirroring.mkd

@@ -1,13 +1,13 @@
 # mirroring using gitolite
 
-**WARNING** existing gitolite mirroring users please note: **there are
+<font color="red">**WARNING** existing gitolite mirroring users please note:
-significant changes** in syntax and usage compared to g2.  The most important
+**there are [significant changes][g2i-mirroring]** in syntax and usage
-change is that `config gitolite.mirror.master` changes to `option
+compared to g2.  If you're not the kind who reads documentation before doing
-mirror.master`, and similarly for 'slaves' and redirectOK.  In addition, the
+serious system admin things, well... good luck!</font>
-special value for 'redirectOK' changes from '1' to 'all'.  The second big
+
-change is the disappearance of the ambiguously named 'keys' (for example
+----
-`gitolite.mirror.hourly` etc., in the old mirroring doc) -- all that
+
-complexity is yours to handle now :-)
+[[TOC]]
 
 ----
 
@@ -46,6 +46,11 @@ Gitolite extends this simple notion in the following ways:
     separately.  Files in the admin directory (like log files) are also not
     mirrored.
 
+  * if you ever do a [bypass push][bypass], mirroring will not work.
+    Mirroring checks also will not work -- for example, you can push to a
+    slave, which is not usually a good idea.  So don't bypass gitolite if the
+    repo is mirrored!
+
 ## setting up mirroring
 
 This is in two parts: the initial setup and the rc file, followed by the conf
@@ -180,7 +185,23 @@ Tip: if you want to do this to all the slaves, try this:
 This command can also be run remotely; run `ssh git@host mirror -h` for
 details.
 
-## appendix A: efficiency versus paranoia
+## #HOSTNAME appendix A: HOSTNAME substitution
+
+Wherever gitolite sees the word `%HOSTNAME`, it will replace it with the
+HOSTNAME supplied in the rc file, if one was supplied.  This lets you maintain
+configurations for all servers in one repo, yet havethem act differently on
+different servers, by saying something like:
+
+    subconf "%HOSTNAME/*.conf"
+
+You can use it in other places also, for example:
+
+    RW+     VREF/NAME/subs/%HOSTNAME/       =   @%HOSTNAME-admins
+
+(you still have to define @mars-admins, @phobos-admins, etc., but the actual
+VREF is now one line instead of one for each server!)
+
+## appendix B: efficiency versus paranoia
 
 If you're paranoid enough to use mirrors, you should be paranoid enough to
 set this on each server, despite the possible CPU overhead:

doc/qi.mkd

@@ -20,6 +20,9 @@ On your workstation:
 
 ## ASSUMPTIONS
 
+  * this is a fresh install, not a migration from the old gitolite (v1.x,
+    v2.x).
+
   * on the server, your `$PATH` contains `$HOME/bin`.  If you don't like that,
     there are [other install methods][install].
 

doc/special.mkd

@@ -1,5 +1,11 @@
 # special features and setups
 
+----
+
+[[TOC]]
+
+----
+
 ## #writable disabling pushes to take backups
 
 The `writable` command allows you to disable pushes to all repos or just the

doc/user.mkd

@@ -7,6 +7,12 @@ 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.
 
+----
+
+[[TOC]]
+
+----
+
 ## accessing gitolite
 
 The most common setup is based on ssh, where your admin asks you to send him