document the info and expand commands

doc/3-faq-tips-etc.mkd

@@ -430,28 +430,30 @@ 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.
 
-Easy!  Just use ssh and try to log in as if you were attempting to get a
-shell:
+Easy!  Just use ssh to give the "info" command to the gitolite server:
 
-    $ ssh gitolite info
-    PTY allocation request failed on channel 0
-    hello sitaram, the gitolite version here is v0.6-17-g94ed189
-    you have the following permissions:
-      R  W  Anu-WSD
-      R     ROtest
-      R  W  SecureBrowse
-      R  W  entrans
-      R  W  git-notes
-      R  W  gitolite
-      R  W  gitolite-admin
-      R  W  indic_web_input
-      R  W  proxy
-      @  @  testing
-      R  W  vkc
+    $ ssh git@server info
+    hello sitaram, the gitolite version here is v1.4-9-g34aad34
+    the gitolite config gives you the following access:
+       R W  SecureBrowse
+       R W  anu-wsd
+       R W  entrans
+       @ W  git-notes
+       @ W  gitolite
+       R W  gitolite-admin
+       R W  indic_web_input
+     @ R    private/CREATER/[\w.-]+
+       R W  proxy
+     @ @ W  public/CREATER/[\w.-]+
+       @ @  testing
+       R W  vkc
 
-Note that until this version, we used to put out an ugly `need
-SSH_ORIGINAL_COMMAND` error, just like gitosis used to.  All we did is put
-that code path to better use :-)
+To understand what these symbols mean, please see doc/report-output.mkd.  The
+administrator can also say things like:
+
+    ssh gitolite info u1 u2 u3
+
+to get this info for other user(s).
 
 #### error checking the config file
 

doc/report-output.mkd

@@ -0,0 +1,61 @@
+# 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 :)
+
+There are 3 columns of permissions (create, read, and write) in the output,
+although the first column is often blank.
+
+Here is the output of the 2 commands (info and expand):
+
+### the "info" command
+
+Usage:
+
+    ssh git@server info
+    ssh git@server info [list of users]
+
+The "info" command shows you all the repos (and repo patterns) in the config
+file that you have been given any kind of access to.  If you're an admin you
+can append a list of users to see their permissions instead of your own.
+(Side note: if you installed using easy-install that would probably be `ssh
+gitolite info`, by the way).
+
+  * col 1 (exists only if the "repo" name is actually a pattern)
+      * `@`: `@all` users have permission to create repos matching this
+        pattern
+      * `C`: this user has permission to create repos matching this pattern
+
+  * col 2
+      * `@`: `@all` users have read access to this repo
+      * `r`: this user has read access to `@all` repos
+      * `R`: this user has read access to this repo
+
+  * col 3: same as col 2, but for write access instead of read
+
+### the "expand" command
+
+Usage:
+
+    ssh git@server expand [optional pattern]
+
+The "expand" command trawls through all the repositories on the server,
+limiting to repos matching the pattern you provide (default is all repos
+found).
+
+For each repo found, it searches for it in the config -- either the actual
+repo entry (when the repo is not a wildcard repo), or an entry for the
+wildcard that matches it -- and reports permissions.  It also takes into
+account extra permissions enabled by the `setperms` command (see
+doc/4-wildcard-repositories.mkd).  It shows you the "creater" of the repo as
+an additional column, defaulting to `<gitolite>` if it was not a wildcard
+repo.
+
+  * col 1: not used
+
+  * col 2: same as col 2 for info, except substitute "repo" with "repo or
+    wildcard matching this repo"
+
+  * col 3: same as col 2, but for write access instead of read
+