doc/7 and doc/0: how to clear out a botched install

doc/0-INSTALL.mkd

@@ -259,17 +259,21 @@ 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].  Either way, you'd like to uninstall
+[indefero][g3] or [gitorious][g4].  [Gerrit][g5] is quite nice too, if you
-gitolite.
+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.  Just log on to the server and do the
+Uninstalling gitolite is fairly easy, although it is manual.  (We'll assume
-following (assuming `$REPO_BASE` in the rc file was left at its default of
+`$REPO_BASE` in the rc file was left at its default of `~/repositories`; if
-`~/repositories`; if not, adjust accordingly):
+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
@@ -287,18 +291,34 @@ following (assuming `$REPO_BASE` in the rc file was left at its default of
         ~/.gitolite.rc
         ~/repositories/gitolite-admin.git
 
-  * Then remove all the `update` hooks that git installs on each repository.
+  * You can remove all of `~/repositories` if you have not really started
-    The easiest way is:
+    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.
 
-  * Finally, any remote users that still have access must update their clone's
+**client side tasks**
-    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
+  * Any remote users that still have access must update their clone's remote
-    is because you'll now be accessing it through plain ssh, which means you
+    URLs (edit `.git/config` in the repo) to prefix `repositories/` before the
-    have to give it the full path.
+    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
 
 ### appendix C: NOTE TO PACKAGE MAINTAINERS
 

doc/7-install-transcript.mkd

@@ -17,6 +17,18 @@ transcript is **non**-gitolite stuff :)
 
 ----
 
+### (cleaning out a botched install if needed)
+
+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 if
+you're reading this document as a follow-up to a failed install, please
+**first** clean out the botched install (instructions [here][appB]) and
+**then** continue with this document.
+
+[appB]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd#uninstall
+
+----
+
 ### create userids on server and client (optional)
 
 Client side: add user, give him a password