(collected docfixes)

doc/admin.mkd

@@ -2,7 +2,8 @@
 
 ## #server server-side administration
 
-The following activities require command line access to the server:
+The following activities require command line access to the server.  They are
+usually one-time or rarely done activities.
 
   * Changing anything in the [rc][] file.
   * Installing custom [hooks][], whether to all repos or just some repos.
@@ -10,12 +11,19 @@ The following activities require command line access to the server:
 
 Please read the [WARNINGS][] page first.
 
-## #conf access control (the gitolite.conf file)
+## #adminrepo access control via the gitolite-admin repo
+
+Most day-to-day administration of a gitolite site happens like this:
+
+  * [clone][] the gitolite-admin repo to your workstation
+  * make appropriate changes
+  * add, commit, and push
+
+### #conf the conf/gitolite.conf file
 
 Most of gitolite's power is in the conf/gitolite.conf file, which specifies
-detailed access control for repos.
-
-### #confex example of a conf file
+detailed access control for repos.  Everything except [adding users][users]
+happens from this file.
 
 Here is an example of a simple conf/gitolite.conf file.
 

doc/clone.mkd

@@ -0,0 +1,19 @@
+# cloning the admin repo
+
+This is the third step in using gitolite, after [install][] and [setup][].
+
+To clone the admin repo, go to the workstation where the public key used in
+'setup' came from, and run this:
+
+    git clone git@host:gitolite-admin
+
+NOTE that (1) you must not include the `repositories/` part (gitolite handles
+that internally), and (2) you may include the ".git" at the end but it is
+optional.
+
+If this step succeeds, you can add [users][], [repos][], or anything else
+described [here][adminrepo].
+
+If this step fails, be sure to look at the [ssh][] documentation before asking
+for help.  (A very basic first step is to run `ssh git@host info`;
+[this][info] page tells you what to expect).

doc/extras/ssh.mkd

@@ -1,5 +1,10 @@
 # ssh
 
+If you're installing gitolite, you're a "system admin", like it or not.  If
+you're using the default ssh mode (i.e., not [http][] mode), ssh is a
+necessary skill.  Please take the time to learn at least enough to get
+passwordless access working.
+
 There are two documents you need to read, in order:
 
   * [Gitolite and ssh][glssh] explains how gitolite uses openssh features to

doc/install.mkd

@@ -6,6 +6,11 @@ start [here][migr].  RTFM is *mandatory* for migrations.</font>
 
 ----
 
+This is the first step in using gitolite, and happens on the server.  It is
+followed by [setup][], then [clone][].
+
+----
+
 [[TOC]]
 
 ----
@@ -20,6 +25,9 @@ The real user used is called the **hosting user**.  Typically this user is
 RPMs and DEBs create a user called *gitolite* for this, so adjust instructions
 and examples accordingly.
 
+**Unless otherwise stated, everything in this page is to be done by logging in
+as this "hosting user"**.
+
 Notes:
 
   * Any unix user can be a hosting user.
@@ -72,6 +80,9 @@ side.
 
 ## the actual install
 
+**Note**: This section describes installing an ssh-based setup.  For smart
+http setup click [here][http].
+
 Gitolite has only one server side "command" now, much like git itself.  This
 command is `gitolite`.  You don't need to place it anywhere special; worst
 case you run it with the full path.

doc/master-toc.mkd

@@ -14,7 +14,7 @@
   * [lost][lost-key] admin key/access
   * [bypass][]ing gitolite
   * [clean][]ing out a botched install
-  * [common][ce] errors (TBD)
+  * [common][ce] errors
   * [uncommon][ue] errors
   * things that are [not gitolite problems][ngp]
 
@@ -43,16 +43,18 @@
 ## [setup][]
 
 
+## [clone][]
+
+
 ## gitolite [admin][]istration
 
-  * [server][]-side
+  * ([server-side][server]) settings, hooks, etc.
       * ([link][WARNINGS]: important cautions on server side activity)
       * changing settings in the [rc][] file
       * installing custom [hooks][]
       * ([link][existing]: moving existing repos into gitolite)
-  * [access control][conf] (the gitolite.conf file)
-      * [example][confex] of a conf file
-      * basic [syntax][]
+  * ([client-side][adminrepo]) access control via the gitolite-admin repo
+      * basic [syntax][] of the [conf][] file
           * include files
           * ([link][sugar]: syntactic sugar)
       * [groups][] (of users and repos)
@@ -93,6 +95,7 @@
 
   * [disabling pushes][writable] to take backups
   * [personal][pers] branches
+  * ([link][votes]: voting on commits)
   * [delegating][deleg] access control responsibilities
       * ([link][NAME]: the NAME VREF)
       * the [subconf][] command

doc/qi.mkd

@@ -1,25 +1,9 @@
 # quick install, setup, and clone
 
-(Please do not ignore the "assumptions" list below).
-
-On the server:
-
-    # get the software
-    git clone git://github.com/sitaramc/gitolite
-
-    # install it
-    gitolite/install -ln
-
-    # setup the initial repos with your key
-    gitolite setup -pk your-name.pub
-
-On your workstation:
-
-    # clone the admin repo so you can start adding stuff
-    git clone git@host:gitolite-admin.git
-
 ## ASSUMPTIONS
 
+  * This is an ssh-based setup.  For smart http setup click [here][http].
+
   * This is a fresh install, not a migration from the old gitolite (v1.x,
     v2.x).
 
@@ -34,15 +18,31 @@ On your workstation:
       * If it does, please see [common errors][ce] and fix things before
         continuing, or read the more complete [setup][] page.
 
-## Notes
+## instructions
 
-Note that the clone path is NOT "repositories/gitolite-admin.git".  If you
-clone with a path that includes "repositories/", the clone should fail.  If
-the clone *does* succeed, a subsequent push should fail :-)  See
-[this][ybpfail] for some details.  If that doesn't make enough sense read all
-of [ssh][].
+On the server, as the hosting user (e.g., 'git'):
+
+    # get the software
+    git clone git://github.com/sitaramc/gitolite
+
+    # install it
+    gitolite/install -ln
+
+    # setup the initial repos with your key
+    gitolite setup -pk your-name.pub
+
+On your workstation:
+
+    # clone the admin repo so you can start adding stuff
+    git clone git@host:gitolite-admin.git
+    # Note 1: clone path must not include "repositories/"
+    # Note 2: it may include the ".git" at the end but it is optional
 
 ## next steps
 
-Next steps are usually adding [users][] and [repos][] and learning about
-[access control][conf].
+If this step succeeds, you can add [users][], [repos][], or anything else
+described [here][adminrepo].
+
+If this step fails, be sure to look at the [ssh][] documentation before asking
+for help.  (A very basic first step is to run `ssh git@host info`;
+[this][info] page tells you what to expect).

doc/setup.mkd

@@ -1,11 +1,16 @@
 # setting up gitolite
 
+This is the second step in using gitolite, after [install][].  This also
+happens on the server,  (The next step is [clone][]).
+
+----
+
 Installing the software gets you ready to use it, but the first "use" of it is
 always the "setup" command.
 
-The first time you run it, you need to have a public key file ready.  If the
-main gitolite admin's username is "alice", this file should be named
-"alice.pub".  Then run
+The first time you run it, you need to have a public key file (usually from
+the admin's workstation) ready.  If the main gitolite admin's username is
+"alice", this file should be named "alice.pub".  Then run
 
     gitolite setup -pk alice.pub
 

doc/vref.mkd

@@ -6,6 +6,10 @@ who stop reading halfway!
 
 ----
 
+[[TOC]]
+
+----
+
 Here's an example to start you off.
 
     repo    r1
@@ -262,12 +266,13 @@ copied to `src/VREF/EMAIL-CHECK` and it works, because VREFs get
 the same first 3 arguments and those are all that it cares about.  (Note: you
 have to change one subroutine in that script if you want to use it)
 
-### catching duplicate pubkeys
+### #votes voting on commits
 
-This checks keydir/ for duplicate keys and aborts the push if it finds any.
-You should use this only on the gitolite-admin repo.
-
-We covered this as a teaser example at the start.
+Although gitolite can't/won't do the whole "code review + workflow
+enforcement" thing that Gerrit Code Review does, a basic implementation of
+voting on a commit is surprisingly easy.  See src/VREF/VOTES for details (and
+note that the actual *code* is just 2-3 lines; the rest is inline
+documentation).
 
 ## other ideas -- code welcome!