lotsa doca fixa uppa

major changes
  - (src) one error message got more detail
  - long overdue fixup to developer notes doc

plus many minor changes that have been piling up

PS: to dig into the "alliterative animal" comment, check the channel
logs around aug 23rd ;-)

doc/1-INSTALL.mkd

@@ -337,12 +337,12 @@ we mean `conf/gitolite.conf` on your gitolite-admin clone.
 
 ### getting the gitolite software
 
-You can get the latest version of gitolite from github or indefero using the
+You can get the latest version of gitolite from github or google code using
-'git clone' command:
+the 'git clone' command:
 
     git clone git://github.com/sitaramc/gitolite.git
             # (OR)
-    git clone git://sitaramc.indefero.net/sitaramc/gitolite.git
+    git clone https://code.google.com/p/gitolite/
 
 <a name="_getting_a_tar_file_from_a_clone"></a>
 

doc/2-admin.mkd

@@ -391,23 +391,15 @@ you could set your hooks to only work if a certain "gitconfig" variable was
 set.  Which means we now need a way to specify "git config" settings on a per
 repository basis.
 
-[Note: this feature is disabled by default.  Read the comments around a
-variable called `GL_GITCONFIG_KEYS` in the rc file, then set it to some
-appropriate value, to enable this feature.]
-
 Thanks to Teemu (teemu dot matilainen at iki dot fi), gitolite now does this
 very easily.  For security reasons, this can only be done from the master
 config file (i.e., if you're using delegation, the delegated admins cannot
 specify git config settings).
 
-Please see `doc/gitolite.conf.mkd` for syntax.  Note that this only supports the
+Please see `doc/gitolite.conf.mkd` for syntax and limitations.  Also note that
-basic forms of the "git config" command:
+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
-    git config              section.key value   # value may be an empty string
+appropriate value, to enable this feature.
-    git config --unset-all  section.key
-
-It does not (currently) support other options like `--add`, the `value_regex`,
-etc.
 
 [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

doc/developer-notes.mkd

@@ -2,9 +2,6 @@
 
 In this document:
 
-  * <a href="#_current_development_version">current development version</a>
-      * <a href="#_testing_status_of_gitolite_v2_0rc1">testing status of gitolite v2.0rc1</a>
-  * <a href="#_migration_to_gitolite_v2_x">migration to gitolite v2.x</a>
   * <a href="#_general_stuff">general stuff</a>
   * <a href="#_the_rc_file">the rc file</a>
   * <a href="#_modules">modules</a>
@@ -17,46 +14,6 @@ In this document:
 
 ----
 
-<a name="_current_development_version"></a>
-
-### current development version
-
-The current gitolite development version is v2.0rc1.  Unless there is a
-serious security problem, *or* one of my large users [i.e., anyone whose name
-is in doc/who-uses-it.mkd (grin!)] needs it, all future changes will now
-happen here.
-
-The commit looks *huge*, but it's mostly just large chunks of code moving
-around; there's not a whole lot of new code.  However, I do apologise if
-anyone has their local changes conflicted when merging or rebasing against
-this version, and I promise to help as much as I can.
-
-<a name="_testing_status_of_gitolite_v2_0rc1"></a>
-
-#### testing status of gitolite v2.0rc1
-
-Pretty much all the major features have been properly tested using the test
-suite.  The following exceptions exist:
-
-  * basic, manual, testing only
-      * most admin defined commands
-      * smart http
-      * mob branches
-  * not yet tested
-      * mirroring
-  * things which I have no easy way to test
-      * controlling gitweb authentication using gitolite (as described [here][gw])
-      * SVN passthru
-
-<a name="_migration_to_gitolite_v2_x"></a>
-
-### migration to gitolite v2.x
-
-In general, the procedure for migrating described in the install document
-should suffice.  Even the rc file hasn't really changed much from the latest
-versions in v1.x, except that if you add a new variable to it you must also
-add it to the @EXPORT list in `src/gitolite_rc.pm`.
-
 <a name="_general_stuff"></a>
 
 ### general stuff
@@ -108,6 +65,7 @@ gets this from `GL_BINDIR`.
   * for frequently run perl programs, I prefer my method
 
       * gl-auth-command -- this is invoked with a full path
+      * gl-mirror-shell -- same as above
       * gl-time -- same as above
 
   * "their" ideal is "FindBin".  I will use it only on manually or
@@ -123,9 +81,9 @@ gets this from `GL_BINDIR`.
     method, not FindBin).  This is suitable for calling from shell scripts
     as `${0%/*}/gl-query-rc GL_BINDIR`
 
-      * gl-mirror-shell (frequent use)
       * gl-setup
       * gl-tool
+      * gl-mirror-push
 
 <a name="_OUTLIER_"></a>
 

doc/gitolite.conf.mkd

@@ -17,6 +17,7 @@ In this document:
   * <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>
@@ -81,7 +82,7 @@ config file exists.
 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].</gray>
+related to `include`, is documented [here][subconf].</font>
 
 [subconf]: http://sitaramc.github.com/gitolite/doc/delegation.html#_the_subconf_command
 
@@ -118,6 +119,22 @@ tag with a new value.
 
 In a later section you'll see some more advanced permissions.
 
+<font color="gray">
+
+Side note: apparently it needs to be spelled out that "R" permissions can only
+apply to the entire repo and not to individual branches/tags.  Mention was
+made of a certain popular Linux distribution named after animals with
+adjectives, chosen merely for alliterative purposes, prefixed to their names,
+and of their users not being clueful enough to know that this (the "read"
+thing, not the alliterative adjective thing, in case you lost track) is an
+inherent git characteristic.
+
+Meanwhile, people who *desperately* need this are directed to gerrit, which
+can do this because they have their own git stack and dont use the one written
+by Linus and currently maintained by Junio.
+
+</font>
+
 <a name="_how_rules_are_matched"></a>
 
 #### how rules are matched
@@ -389,10 +406,20 @@ found in doc/wildcard-repositories.mkd.]
 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
+branches" section in `doc/3-faq-tips-etc.mkd` for details.
+
 <a name="_splitting_up_rules_into_rulesets"></a>
 
 #### splitting up rules into rulesets

doc/mirroring.mkd

@@ -68,6 +68,9 @@ of setup you need. Here're some advantages:
     for everything. They don't need to know where the master is, so they're
     insulated from any changes you make behind the scenes.
 
+    This is as close to **active-active** mirroring as you can get without
+    worrying about race conditions and similar problems.
+
   * **partial mirroring**: all repos don't have to go all mirrors.  You can
     choose not to mirror a repo at all, or mirror it only to certain servers.
     This could be due to any reason: repo too big/high-traffic for the server,

src/gitolite.pm

@@ -994,6 +994,8 @@ sub setup_authkeys
         if ($pubkey_content =~ /\n./)
         {
             warn "WARNING: a pubkey file can only have one line (key); ignoring $pubkey\n" .
+                 "         Perhaps you're using a key in a different format (like putty/plink)?\n" .
+                 "         If so, please convert it to openssh format using 'ssh-keygen -i'.\n" .
                  "         If you want to add multiple public keys for a single user, use\n" .
                  "         \"user\@host.pub\" file names.  See the \"one user, many keys\"\n" .
                  "         section in doc/3-faq-tips-etc.mkd for details.\n";