ssh-copy-id workaround detail plus a couple other doc fixes

doc/0-INSTALL.mkd

@@ -37,13 +37,16 @@ Assumptions/pre-requisites:
   * git is installed on that server (and so is perl)
   * you have a userid on that server
   * you have ssh-pubkey (**password-less**) login to that userid
-      * (if you have only password access, run `ssh-keygen -t rsa` to create a
+      * if you have only password access, run `ssh-keygen -t rsa` to create a
-        new keypair if needed, then run `ssh-copy-id user@host`)
+        new keypair if needed, then run `ssh-copy-id user@host`.  If you do
+        not have `ssh-copy-id`, read doc/3-faq-tips-etc.mkd and look for
+        `ssh-copy-id` in that file for instructions
   * you have a clone or an archive of gitolite somewhere on your workstation
+      * if you don't have one, just run `git clone git://github.com/sitaramc/gitolite`
 
-If so, just `cd` to that clone and run `src/gl-easy-install` and follow the
+Once you have all this, just `cd` to that clone and run `src/gl-easy-install`
-prompts!  (Running it without any arguments shows you usage plus other useful
+and follow the prompts!  (Running it without any arguments shows you usage
-info).
+plus other useful info).
 
 #### typical example run
 

doc/3-faq-tips-etc.mkd

@@ -25,16 +25,25 @@ In this document:
 
 ### common errors and mistakes
 
-  * forgetting to suffix `.git` to the end of the reponame in the `git clone`.
-    This suffix is *not* used in the gitolite config file for the sake of
-    clarity and cleaner syntax, but don't let that fool you.  It's a
-    convention in the git world that **bare repos** end with `.git`.
-
   * 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
     what `$REPO_BASE` is set to and thinks he has to provide that prefix on
-    the client side also :-)  In fact gitolite prepends `$REPO_BASE` when it
+    the client side also :-)  In fact gitolite prepends `$REPO_BASE`
-    is required anyway, so you shouldn't do the same thing!
+    internally, so you shouldn't also do the same thing!
+
+  * being able to clone but getting errors on push.  Most likely caused by a
+    combination of:
+
+      * you already have shell access to the server, not just "gitolite"
+        access, *and*
+
+      * you cloned using `git clone git@server:repositories/repo.git` (notice
+        there's an extra "repositories/" in there?)
+
+    In other words, you used a key that completely bypassed gitolite and went
+    straight to the shell to do the clone.
+
+    Please see doc/6-ssh-troubleshooting.mkd for what all this means.
 
 ### git version dependency
 
@@ -67,6 +76,27 @@ normal way, since it's not empty anymore.
 
 ### other errors, warnings, notes...
 
+  * 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
+    `~/.ssh/id_rsa.pub` from your client/workstation.
+
+      * it copies it to the server as some file
+
+      * it appends that file to `~/.ssh/authorized_keys` on the server
+        (creating it if it doesn't already exist)
+
+      * it then makes sure that all these files/directories have go-w perms
+        set (assuming user is "git"):
+
+            /home/git/.ssh/authorized_keys
+            /home/git/.ssh
+            /home/git
+
+    [Actually, sshd requires that even directories *above* ~ (/, /home,
+    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!)]
+
   * 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 commit has been made, older clients can also use it