(doc) general cleanup of docs

README.mkd

@@ -12,16 +12,15 @@ If you're reading this on the main gitolite page on github, several
     branch, and is now the actively maintained and supported software.  Do NOT
     try to merge this with your old "master" branch!
 
-2.  Versions v2.x is on branch "g2".  It will be supported for security issues
+2.  Versions v2.x are on branch "g2".  It will be supported for security
-    and serious bugs in core functionality, but not for anything less
+    issues and serious bugs in core functionality, but not for anything less
     critical.  Versions v1.x are completely unsupported now.
 
 If you're an existing (v1.x, v2.x) gitolite user please spend some time with
 the documentation for the new version before upgrading.  The [main page][h-mp]
-leads to quick install as well as several other useful starting points.  The
+leads to several useful starting points.  The [table of contents][h-mt] is a
-[table of contents][h-mt] is a much more meaningfully ordered/structured list
+much more meaningfully ordered/structured list of links (instead of putting
-of links (instead of putting them in alphabetical order of the filename, like
+them in alphabetical order of the filename, like in g2!)
-in g2!)
 
 [h-mp]: http://sitaramc.github.com/gitolite/
 [h-mt]: http://sitaramc.github.com/gitolite/master-toc.html

doc/admin.mkd

@@ -2,11 +2,11 @@
 
 ## #server server-side administration
 
-The following activities require command line access to the server
+The following activities require command line access to the server:
 
-  * changing anything in the [rc][] file
+  * Changing anything in the [rc][] file.
-  * installing custom [hooks][], whether to all repos or just some repos
+  * Installing custom [hooks][], whether to all repos or just some repos.
-  * moving [existing][] repos into gitolite control
+  * Moving [existing][] repos into gitolite control.
 
 Please read the [WARNINGS][] page first.
 
@@ -32,11 +32,11 @@ Here is an example of a simple conf/gitolite.conf file.
 
 Use the following links to learn more:
 
-  * the basic [syntax][] -- comments, whitespace, include files, etc.
+  * The basic [syntax][] -- comments, whitespace, include files, etc.
-  * defining [groups][], as in lines 1 and 2
+  * Defining [groups][], as in lines 1 and 2.
-  * adding and removing [users][]
+  * Adding and removing [users][].
-  * adding and removing [repos][], as in line 3
+  * Adding and removing [repos][], as in line 3.
-  * defining access [rules][], as in lines 4, 5, 6, and 7
+  * Defining access [rules][], as in lines 4, 5, 6, and 7.
-  * gitolite [options][]
+  * Gitolite [options][].
-  * [git config][git-config] keys and values, as in line 8
+  * [Git config][git-config] keys and values, as in line 8.
-  * ["wild"][wild] repos -- ad hoc, user-created, repos
+  * ["Wild"][wild] repos -- ad hoc, user-created, repos.

doc/cust.mkd

@@ -17,12 +17,12 @@ even mirroring is not in core now!)
 
 There are 5 basic types of non-core programs.
 
-  * *commands* can be run from the shell command line.  Among those, the ones
+  * *Commands* can be run from the shell command line.  Among those, the ones
     listed in the COMMANDS hash of the rc file can also be run remotely.
-  * *hooks* are standard git hooks; see below.
+  * *Hooks* are standard git hooks; see below.
-  * *sugar scripts* change the conf language for your convenience.  The word
+  * *Sugar scripts* change the conf language for your convenience.  The word
     sugar comes from "syntactic sugar".
-  * *triggers* are to gitolite what hooks are to git.  I just chose a
+  * *Triggers* are to gitolite what hooks are to git.  I just chose a
     different name to avoid confusion and constant disambiguation in the docs.
   * **VREFs** are extensions to the access control check part of gitolite.
 

doc/deleg.mkd

@@ -38,21 +38,22 @@ And that's it.
 
 Subconf is exactly like the include command in syntax:
 
-    subconf "foo/bar.conf"
+    subconf "foo.conf"
 
-but while reading the included file, it sets a "subconf name" of "foo".
+but while reading the included file (as well as anything included from it),
+gitolite sets the "subconf name" to "foo".
 
-When a subconf name is in effect, there are some restrictions on what repos
+A "subconf" imposes some restrictions on what repos can be managed.
-can be managed.
 
-For example, in the include file in the above example, you can only have
+For example, while the subconf name is "foo", as in the above example,
-"repo" lines for:
+gitolite will only process "repo" lines for:
 
-  * a repo called "foo"
+  * A repo called "foo".
-  * a group called "@foo" defined outside the include file
+  * A group called "@foo", as long as the group is defined in the main conf
-  * a member of a group called "@foo" (again, defined outside)
+    file (i.e., *outside* "foo.conf").
-  * a repo that matches a member of a group called "@foo" if that member is a
+  * A member of a group called "@foo" (again, defined outside).
-    regular expression pattern
+  * A repo that matches a member of a group called "@foo" if that member is a
+    regular expression pattern.
 
 Here's an example.  If the main conf file contains
 
@@ -61,6 +62,9 @@ Here's an example.  If the main conf file contains
 then the subconf can only accept repo statements that refer to 'foo', '@foo',
 'aa', 'bb', or any repo whose name starts with 'cc/'.
 
+**Note**: the subconf name "master" is special; it is the default subconf in
+effect for the main conf file and has no restrictions.
+
 ### how the "subconf name" is derived
 
 For subconf lines that look just like include statements, i.e.,

doc/dev-notes.mkd

@@ -29,15 +29,15 @@ easily with gitolite.  Each of them responds to `-h` so please run that for
 more info.
 
   * `gitolite access` to check access rights given repo, user, type of access
-    (R, W, ...) and refname (optional).  Example use: src/commands/desc
+    (R, W, ...) and refname (optional).  Example use: src/commands/desc.
 
   * `gitolite creator` to get/check the creator of a repo.  Example use:
-    src/commands/desc
+    src/commands/desc.
 
   * `gitolite git-config` to check gitolite options or git config variables
     directly from gitolite's "compiled" output, (i.e., without looking at the
     actual `repo.git/config` file or using the `git config` command).  Example
-    use: none yet
+    use: none yet.
 
   * `gitolite query-rc` to check the value of an RC variable.  Example use:
     src/commands/desc.
@@ -65,11 +65,11 @@ The rest is between you and 'man githooks' :-)
 
 If you want to add additional `update` hook functionality, do this:
 
-  * write and test your update hook separately from gitolite
+  * Write and test your update hook separately from gitolite.
 
-  * now add the code to src/VREF.  Let's say it is called "foo".
+  * Now add the code to src/VREF.  Let's say it is called "foo".
 
-  * to call your new update hook to all accesses for all repos, add this to
+  * To call your new update hook to all accesses for all repos, add this to
     the end of your conf file:
 
         repo @all

doc/emergencies.mkd

@@ -46,19 +46,19 @@ just rewind) and push that.  Here's how to do that:
 If you've read the [files involved in gitolite][files] page, you probably know
 the answer, but here's a list of files you should blow away.
 
-  * **gitolite sources** -- can be found by running `which gitolite`.  If it's
+  * **Gitolite sources** -- can be found by running `which gitolite`.  If it's
     a symlink, go to its target directory.
 
-  * **gitolite admin directory** -- `$HOME/.gitolite`.  Save the 'logs'
+  * **Gitolite admin directory** -- `$HOME/.gitolite`.  Save the 'logs'
     directory if you want to preserve them for any reason.
 
-  * **the rc file** -- `$HOME/.gitolite.rc`.  If you made any changes to it
+  * **The rc file** -- `$HOME/.gitolite.rc`.  If you made any changes to it
     you can save it as some other name instead of deleting it.
 
-  * **the gitolite-admin repo** -- `$HOME/repositories/gitolite-admin.git`.
+  * **The gitolite-admin repo** -- `$HOME/repositories/gitolite-admin.git`.
     You can clone it somewhere to save it before blowing it away if you wish.
 
-  * **git repositories** -- `$HOME/repositories`.  The install process will
+  * **Git repositories** -- `$HOME/repositories`.  The install process will
     not touch any existing repos except 'gitolite-admin.git', so you do not
     have to blow away (or move) your work repos to fix a botched install.
 
@@ -66,7 +66,7 @@ the answer, but here's a list of files you should blow away.
     will those repos be touched.  And even then all that happens is that the
     update hook, if any, is replaced with gitolite's own hook.
 
-  * **ssh stuff** -- exercise caution when doing this, but in general it
+  * **Ssh stuff** -- exercise caution when doing this, but in general it
     should be safe to delete all lines between the "gitolite start" and
     "gitolite end" markers in `$HOME/.ssh/authorized_keys`.
 
@@ -103,12 +103,12 @@ the answer, but here's a list of files you should blow away.
 
   * `WARNING: split conf not set, gl-conf present for <repo>`
 
-    (case 1) This can happen if you have a *bare* repo (i.e., some `repo.git`
+    (Case 1) This can happen if you have a *bare* repo (i.e., some `repo.git`
     directory) copied from g2 with `GL_BIG_CONFIG` on, and you pushed a change
     to the conf or ran certain commands *before* adding the newly added repo
     to the conf file.
 
-    (case 2) This can also happen if you changed something like this
+    (Case 2) This can also happen if you changed something like this
 
         repo foo
             ...<some rules>...
@@ -141,7 +141,7 @@ cannot help with most of these (although the good folks on irc or the mailing
 list -- see [contact][] -- might be able to; they certainly appear to have a
 lot more patience than I do, bless 'em!)
 
-  * **client side software**
+  * **Client side software**
 
       * putty/plink
       * jgit/Eclipse
@@ -151,7 +151,7 @@ lot more patience than I do, bless 'em!)
       * ...probably some more I forgot; will update this list as I remember...
       * did I mention putty/plink?
 
-  * **ssh**
+  * **Ssh**
 
     The *superstar* of the "not a gitolite problem" category is actually ssh.
 
@@ -162,7 +162,7 @@ lot more patience than I do, bless 'em!)
     Everything I know is in that latter link.  Please email me about ssh ONLY
     if you find something wrong or missing in those documents.
 
-  * **git**
+  * **Git**
 
     I wish I had a dollar for each time someone did a *first push* on a new
     repo, got an error because there were "no refs in common (etc.)", and

doc/extras/glssh.mkd

@@ -31,18 +31,18 @@ from somewhere, or maybe buy the OReilly ssh book.
     and give the server the public key.  (I need not add that the "private"
     key must be, well, kept *private*!)
 
-  * **generating a key pair on your workstation** is done by running the
+  * **Generating a key pair on your workstation** is done by running the
     command `ssh-keygen -t rsa`.  This produces two files in `~/.ssh`.  One is
     `id_rsa`; this is the **private** key -- ***never*** let it out of your
     machine.  The other is `id_rsa.pub`, which is the corresponding public
     key.  This public key is usually just one long line of text.
 
-    * on Windows machines with msysgit installed, you should do this from
+    * On Windows machines with msysgit installed, you should do this from
       within a "git bash" window.  The command will report the full path where
       the files have been written; make a note of this, and use those files in
-      any of the description that follows
+      any of the description that follows.
 
-  * **adding your public key to the server**'s `~/.ssh/authorized_keys`
+  * **Adding your public key to the server**'s `~/.ssh/authorized_keys`
     file is how ssh uses pubkeys to authenticate users.  Let's say
     sita@work.station is trying to log in as git@serv.er.  What you have to do
     is take the `~/.ssh/id_rsa.pub` file for user sita on work.station and
@@ -62,12 +62,12 @@ from somewhere, or maybe buy the OReilly ssh book.
 
     But in the gitolite case, it's different; we'll get to that in a minute.
 
-    * **troubleshooting pubkey authentication failures**: if you are unable to
+    * **Troubleshooting pubkey authentication failures**: if you are unable to
       get ssh access to the server after doing all this, you'll have to look
       in `/var/log/secure` or `/var/log/auth.log` or some such file on the
       server to see what specific error `sshd` is complaining about.
 
-  * **restricting users to specific commands** is very important for gitolite.
+  * **Restricting users to specific commands** is very important for gitolite.
     If you read `man sshd` and look for `authorized_keys file format`, you'll
     see a lot of options you can add to the public key line, which restrict
     the incoming user in various ways.  In particular, note the `command=`
@@ -89,9 +89,9 @@ from somewhere, or maybe buy the OReilly ssh book.
 
 These are two different questions you ought to be having by now: 
 
-  * how does it distinguish between me and someone else, since we're all
+  * How does it distinguish between me and someone else, since we're all
-    logging in as the same remote user "git"
+    logging in as the same remote user "git".
-  * how does it restrict what I can do within a repository
+  * How does it restrict what I can do within a repository.
 
 #### restricting shell access/distinguishing one user from another
 

doc/extras/sts.mkd

@@ -33,16 +33,16 @@ and accessing gitolite.
   * Your workstation is the **client**.  Your userid on the client does not
     matter, and it has no relation to your gitolite username.
 
-  * the server is called **server** and the "hosting user" is **git**.  If
+  * The server is called **server** and the "hosting user" is **git**.  If
     this is an RPM/DEB install, the hosting user is probably called
     "gitolite", however we will use "git" in this document.
 
 #### taking stock -- relevant files and directories
 
-  * the client has a `~/.ssh` containing a few keypairs.  It may also have a
+  * The client has a `~/.ssh` containing a few keypairs.  It may also have a
     `config` file.
 
-  * the client also has a clone of the "gitolite-admin" repo, which contains a
+  * The client also has a clone of the "gitolite-admin" repo, which contains a
     bunch of `*.pub` files in `keydir`.  We assume this clone is in `$HOME`;
     if it is not, adjust instructions accordingly when needed.
 
@@ -51,29 +51,29 @@ and accessing gitolite.
     **authkeys** to save typing, and it always means the one on the server
     (we're not interested in this file on the client side).
 
-  * the server also has a `~/.gitolite/keydir` which contains a bunch of
+  * The server also has a `~/.gitolite/keydir` which contains a bunch of
     `*.pub` files.
 
 #### normal gitolite key handling
 
 Here's how normal gitolite key handling works:
 
-  * (on client) pub key changes like adding new ones, deleting old ones, etc.,
+  * (On client) pub key changes like adding new ones, deleting old ones, etc.,
     are done in the `keydir` directory in the gitolite-admin repo clone.  Then
     the admin `git add`s and `git commit`s those changes, then `git push`es
     them to the server.
 
-  * (on server) a successful push from the client makes git invoke the
+  * (On server) a successful push from the client makes git invoke the
     post-update hook in the gitolite-admin repo.  This hook is installed by
     gitolite, and it does a bunch of things which are quite transparent to
     the admin, but we'll describe briefly here:
 
-      * the pubkey files from this push are checked-out into
+      * The pubkey files from this push are checked-out into
         `~/.gitolite/keydir` (and similarly the config files into
-        `~/.gitolite/conf`)
+        `~/.gitolite/conf`).
 
-      * the "compile" script then runs, which uses these files to populate
+      * The "compile" script then runs, which uses these files to populate
-        `~/.ssh/authorized_keys` on the server
+        `~/.ssh/authorized_keys` on the server.
 
         The authkeys file may have other, (non-gitolite) keys also.  Those
         lines are preserved.  Gitolite only touches lines that are found
@@ -92,7 +92,7 @@ The following problem(s) indicate that pubkey access is not working at all, so
 you should start with [appendix 1][stsapp1].  If that doesn't fix the problem, continue
 with the other appendices in sequence.
 
-  * running any git clone/fetch/ls-remote or just `ssh git@server info` asks
+  * Running any git clone/fetch/ls-remote or just `ssh git@server info` asks
     you for a password.
 
 The following problem(s) indicate that your pubkey is bypassing gitolite and
@@ -100,23 +100,23 @@ going straight to a shell.  You should start with [appendix 2][sshkeys-lint]
 and continue with the rest in sequence.  [Appendix 5][ybpfail] has some
 background info.
 
-  * running `ssh git@server info` gets you the output of the GNU 'info'
+  * Running `ssh git@server info` gets you the output of the GNU 'info'
     command instead of gitolite's version and access info.
 
-  * running `git clone git@server:repositories/reponame` (note presence of
+  * Running `git clone git@server:repositories/reponame` (note presence of
     `repositories/` in URL) works.
 
     [A proper gitolite key will only let you `git clone git@server:reponame`
     (note absence of `repositories/`)]
 
-  * you are able to clone repositories but are unable to push changes back
+  * You are able to clone repositories but are unable to push changes back
     (the error complains about the `GL_BINDIR` environment variable not being
     set, and the `hooks/update` failing in some way).
 
     [If you run `git remote -v` you will find that your clone URL included the
     `repositories/` described above!]
 
-  * conversely, using the correct syntax, `git clone git@server:reponame`
+  * Conversely, using the correct syntax, `git clone git@server:reponame`
     (note absence of `repositories/` in the URL), gets you `fatal: 'reponame'
     does not appear to be a git repository`, and yet you are sure 'reponame'
     exists, you haven't mis-spelled it, etc.
@@ -129,16 +129,16 @@ you there again.  Especially the first bullet.
 
 Done?  OK, now the general outline for ssh troubleshooting is this:
 
-  * make sure the server's overall setup even *allows* pubkey based login.
+  * Make sure the server's overall setup even *allows* pubkey based login.
     I.e., check that git fetch/clone/ls-remote commands or a plain `ssh
     git@server info` do NOT ask for a password.  If you do get asked for a
     password, see [appendix 1][stsapp1].
 
-  * match client-side pubkeys (`~/.ssh/*.pub`) with the server's authkeys
+  * Match client-side pubkeys (`~/.ssh/*.pub`) with the server's authkeys
     file.  To do this, run `sshkeys-lint`, which tells you in detail what key
     has what access.  See [appendix 2][sshkeys-lint].
 
-  * at this point, we know that we have the right key, and that if sshd
+  * At this point, we know that we have the right key, and that if sshd
     receives that key, things will work.  But we're not done yet.  We still
     need to make sure that this specific key is being offered/sent by the
     client, instead of the default key.  See [appendix 3][stsapp3] and
@@ -172,12 +172,12 @@ 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 copies it to the server as some file.
 
-  * it appends that file to `~/.ssh/authorized_keys` on the server
+  * It appends that file to `~/.ssh/authorized_keys` on the server
-    (creating it if it doesn't already exist)
+    (creating it if it doesn't already exist).
 
-  * it then makes sure that all these files/directories have go-w perms
+  * It then makes sure that all these files/directories have go-w perms
     set (assuming user is "git"):
 
         /home/git/.ssh/authorized_keys
@@ -233,7 +233,7 @@ try, you are being asked for a password.
 
 This is a quick checklist:
 
-  * make sure you're being asked for a password and not a pass*phrase*.  Do
+  * Make sure you're being asked for a password and not a pass*phrase*.  Do
     not confuse or mistake a prompt saying `Enter passphrase for key
     '/home/sitaram/.ssh/id_rsa':` for a password prompt from the remote
     server!
@@ -254,34 +254,34 @@ This is a quick checklist:
     discussing one more potential trouble-spot with ssh-agent (see below),
     further discussion of ssh-agent/keychain is out of scope of this document.
 
-  * ssh is very sensitive to permissions.  An extremely conservative setup is
+  * Ssh is very sensitive to permissions.  An extremely conservative setup is
     given below, but be sure to do this on **both the client and the server**:
 
         cd $HOME
         chmod go-rwx .
         chmod -R go-rwx .ssh
 
-  * actually, every component of the path to `~/.ssh/authorized_keys` all the
+  * Actually, every component of the path to `~/.ssh/authorized_keys` all the
     way upto the root directory must be at least `chmod go-w`.  So be sure to
     check `/` and `/home` also.
 
-  * while you're doing this, make sure the owner and group info for each of
+  * While you're doing this, make sure the owner and group info for each of
     these components are correct.  `ls -ald ~ ~/.ssh ~/.ssh/authorized_keys`
     will tell you what they are.
 
-  * you may also want to check `/etc/ssh/sshd_config` to see if the "git" user
+  * You may also want to check `/etc/ssh/sshd_config` to see if the "git" user
     is allowed to login at all.  For example, if that file contains an
     `AllowUsers` config entry, then only users mentioned in that line are
     allowed to log in!
 
-  * while you're in there, check that file does NOT have a setting for
+  * While you're in there, check that file does NOT have a setting for
     `AuthorizedKeysFile`.  See `man sshd_config` for details.  This setting is
     a show stopper for gitolite to use ssh.
 
-  * some OSs/distributions require that the "git" user should have a password
+  * Some OSs/distributions require that the "git" user should have a password
     and/or not be a locked account.  You may want to check that as well.
 
-  * if all that fails, log onto the server as root, `cd /var/log`, and look
+  * If all that fails, log onto the server as root, `cd /var/log`, and look
     for a file called `auth.log` or `secure` or some such name.  Look inside
     this file for messages matching the approximate time of your last attempt
     to login, to see if they tell you what is the problem.
@@ -298,12 +298,12 @@ especially good at finding duplicate keys and such.
 To run it on the client you have to copy the file src/commands/sshkeys-lint
 from some gitolite clone, then follow these steps:
 
-  * get a copy of `~/.ssh/authorized_keys` from the server and put it in
+  * Get a copy of `~/.ssh/authorized_keys` from the server and put it in
-    `/tmp/foo` or something
+    `/tmp/foo` or something.
 
-  * cd to `~/.ssh`
+  * cd to `~/.ssh`.
 
-  * run `/path/to/sshkeys-lint *.pub < /tmp/foo`
+  * Run `/path/to/sshkeys-lint *.pub < /tmp/foo`.
 
 Note that it is not trying to log in or anything -- it's just comparing
 fingerprints as computed by `ssh-keygen -l`.
@@ -314,12 +314,12 @@ the server, you're done with this step.
 Otherwise you have to rename some keypairs and try again to get the effect you
 need.  Be careful:
 
-  * do not just rename the ".pub" file; you will have to rename the
+  * Do not just rename the ".pub" file; you will have to rename the
     corresponding private key also (the one with the same basename but without
-    an extension)
+    an extension).
 
-  * if you're running ssh-agent, you may have to delete (using `ssh-add -D`)
+  * If you're running ssh-agent, you may have to delete (using `ssh-add -D`)
-    and re-add identities for it to pick up the renamed ones correctly
+    and re-add identities for it to pick up the renamed ones correctly.
 
 #### typical cause(s)
 
@@ -339,7 +339,7 @@ you're using ssh-agent, otherwise these new keys may not work.
 
 ### #stsapp3 appendix 3: ssh client may not be offering the right key
 
-  * make sure the right private key is being offered.  Run ssh in very
+  * Make sure the right private key is being offered.  Run ssh in very
     verbose mode and look for the word "Offering", like so:
 
         ssh -vvv user@host pwd 2> >(grep -i offer)
@@ -413,11 +413,11 @@ the server.  (This is by design.  Don't argue...)
 
 This means that, you get 2 kinds of errors if you bypass gitolite
 
-  * when you use `git@server:reponame` with a key that bypasses gitolite
+  * When you use `git@server:reponame` with a key that bypasses gitolite
     (i.e., gets you a shell), this prefixing does not happen, and so the repo
     is not found.  Neither a clone/fetch nor a push will work.
 
-  * conversely, consider `git@server:repositories/reponame.git`.  The clone
+  * Conversely, consider `git@server:repositories/reponame.git`.  The clone
     operation will work -- you're using the full Unix path, (assuming default
     `$REPO_BASE` setting), and so the shell finds the repo where you said it
     would be.  However, when you push, gitolite's **update hook** kicks in,

doc/files.mkd

@@ -10,8 +10,7 @@ Let's say you start from a totally clean slate:
     $ ls -a
     .  ..  .bash_logout  .bash_profile  .bashrc
 
-You run `git clone -b g3 git://github.com/sitaramc/gitolite` (the '-b' option
+You run `git clone git://github.com/sitaramc/gitolite`.
-does the equivalent of 'git checkout g3' after the clone is done).
 
 Now you have
 

doc/g2incompat.mkd

@@ -56,23 +56,23 @@ functionality, and invoke *that* from the rc file instead.
 
 There are several changes with regard to mirroring:
 
-  * there is no 'post-receive' hook to be installed.  Mirroring is handled by
+  * There is no 'post-receive' hook to be installed.  Mirroring is handled by
     g3's [triggers][] mechanism.  Gitolite triggers are enabled by adding (or
     uncommenting, in this case) appropriate lines in the rc file.
 
-  * the `GL_HOSTNAME` variable is now `HOSTNAME`.  (Note that the rc file
+  * The `GL_HOSTNAME` variable is now `HOSTNAME`.  (Note that the rc file
     syntax itself has changed quite a bit; to be accurate, HOSTNAME is not a
     variable but a hash key with an associated value).
 
-  * the `GL_GITCONFIG_KEYS` variable is now `GIT_CONFIG_KEYS`, **but** you no
+  * The `GL_GITCONFIG_KEYS` variable is now `GIT_CONFIG_KEYS`, **but** you no
     longer need to set it to anything for mirroring to work.
 
-  * the `gl-tool` program does not exist anymore.  Adding keys for peer
+  * The `gl-tool` program does not exist anymore.  Adding keys for peer
     servers is done just like adding user keys, except that the pubkey file
     name must start with `server-`.  For example, to add a peer host called
     frodo, you will acquire its pubkey and add it as `server-frodo.pub`.
 
-  * the config variables are quite different now.  The main ones now look like
+  * The config variables are quite different now.  The main ones now look like
     this:
 
         option mirror.master        =   sam
@@ -86,7 +86,7 @@ There are several changes with regard to mirroring:
 
         option mirror.redirectOK    =   all
 
-  * there are no more mirroring "keys", (lists of servers named in config keys
+  * There are no more mirroring "keys", (lists of servers named in config keys
     like 'gitolite.mirror.nightly', etc).  You can certainly add lines like
 
         option mirror.nightly       =   merry pippin
@@ -95,7 +95,7 @@ There are several changes with regard to mirroring:
     `gitolite git-config` to query this variable, grab the list of repos, and
     run `gitolite mirror` on each of them.
 
-  * the external command to resync mirrors is 'mirror', run just like any
+  * The external command to resync mirrors is 'mirror', run just like any
     other [command][commands].  In particular, you can run `gitolite mirror
     -h` to get help.  It cannot be run from a slave to ask a master to push
     (unlike in the old system) but what's more convenient is that any user who

doc/g2migr.mkd

@@ -17,11 +17,11 @@ differences are in the rc file, mirroring, "NAME/" rules, and delegation.
 
 >   ----
 
->   **presetting the rc file**
+>   **Presetting the rc file**
 
 >   Some rc settings in the older gitolite are such that you cannot directly
->   run `gitolite setup` when you're ready to migrate.  Doing that will
+>   run `gitolite setup` when you're ready to migrate.  **Doing that will
->   **clobber** something important.  See [presetting the rc file][rc-preset]
+>   clobber something important**.  See [presetting the rc file][rc-preset]
 >   for details.
 
 >   ----
@@ -48,7 +48,7 @@ Some of them have links where there is more detail than I want to put here.
   * [subconf][g2i-subconf]: if you're using [delegation][deleg], there is no
     implicit "subconf" at the end; you'll have to add it in.
 
-  * there are several important differences in mirroring.  You can start from
+  * There are several important differences in mirroring.  You can start from
     scratch by reading the new [mirroring][mirroring] doc or
     [migrate][g2i-mirroring] (carefully!).
 
@@ -236,8 +236,8 @@ put that contain the words "see docs":
 ## #rc-preset presetting the rc file
 
 Some rc settings in the older gitolite are such that you cannot directly run
-`gitolite setup` when you're ready to migrate.  Doing that will **clobber**
+`gitolite setup` when you're ready to migrate.  **Doing that will clobber
-something important.  You have to create a default rc file, edit it
+something important**.  You have to create a default rc file, edit it
 appropriately, and *then* run `gitolite setup`.
 
 The most serious example of this is `GL_NO_SETUP_AUTHKEYS`, which tells the

doc/gsmigr.mkd

@@ -44,10 +44,10 @@ Here are the steps on the server:
 Now, log off the server and get back to the client.  All subsequent
 instructions are to be read as "on gitolite admin's workstation".
 
-  * **clone** the new gitolite-admin repo to your workstation.  (You already
+  * **Clone** the new gitolite-admin repo to your workstation.  (You already
     have a clone of the gitosis-admin repo so now you have both).
 
-  * **convert** your gitosis config file and append it to your gitolite config
+  * **Convert** your gitosis config file and append it to your gitolite config
     file.  Substitute the path for your gitosis-admin clone in `$GSAC` below,
     and similarly the path for your gito**lite**-admin clone in `$GLAC`.  (The
     convert-gitosis-conf program is a standalone program that you can bring
@@ -63,7 +63,7 @@ instructions are to be read as "on gitolite admin's workstation".
   * Remove the entry for the 'gitosis-admin' repo.  You do not need it here
     and it may cause confusion.
 
-  * **copy** the keys from gitosis's keydir (same meanings for GSAC and GLAC)
+  * **Copy** the keys from gitosis's keydir (same meanings for GSAC and GLAC)
 
         cp $GSAC/keydir/* $GLAC/keydir
 
@@ -122,5 +122,4 @@ instructions are to be read as "on gitolite admin's workstation".
     "sitaram@laptop.pub" and "sitaram@desktop.pub" or whatever.  *Please check
     the files to make sure this worked properly*
 
-  * Check all your changes to your gitolite-admin clone, commit, and push
+  * Check all your changes to your gitolite-admin clone, commit, and push.
-

doc/http.mkd

@@ -11,34 +11,17 @@ that is the same or even relevant -- that is from 2006 and is quite different
   * Please read [authentication versus authorisation][auth] first, and make
     sure you understand what is gitolite's responsibility and what isn't.
 
-  * The 'gitolite' command (for example, 'gitolite compile', 'gitolite
+  * I have tested this only on stock Fedora 16; YDMV.
-    query-rc', and so on) *can* be run on the server, but it's not
-    straightforward.  Assuming you installed using the exact same values as in
-    this document:
-
-      * get a shell by using, say, `su -s /bin/bash - apache`
-      * run `export HOME=$HOME/gitolite-home`
-      * run `export PATH=$PATH:$HOME/bin`
-
-    Now you can run `gitolite <subcommand>`
-
-  * I have tested only on stock Fedora 16; YDMV
 
   * As before, I have not tried making repos available to both ssh *and* http
     mode clients but it ought to work.  If you managed it, I'd appreciate a
     doc patch describing how you did it.
 
-## additional requirements
-
-  * requires `GIT_PROJECT_ROOT` (see "man git-http-backend" for what this is)
-    set explicitly (i.e., it is no longer optional).  Please set it to some
-    place outside apache's `DOCUMENT_ROOT`.
-
 ## assumptions:
 
-  * apache 2.x and git installed.
+  * Apache 2.x and git installed.
-  * httpd runs under the "apache" userid; adjust instructions below if not.
+  * Httpd runs under the "apache" userid; adjust instructions below if not.
-  * similarly for "/var/www" and other file names/locations.
+  * Similarly for "/var/www" and other file names/locations.
 
 ## instructions
 
@@ -51,8 +34,14 @@ install gitolite in smart http mode.
 Make a copy of the script, go through it carefully, (possibly removing lines
 that delete files etc.), change values per your system, and only then run it.
 
+<font color="gray">Note that the `GIT_PROJECT_ROOT` variable (see "man
+git-http-backend") is no longer optional.  Make sure you set it to some place
+outside apache's `DOCUMENT_ROOT`.</font>
+
 ## usage
 
+### client side
+
 Git URLs look like `http://user:password@server/git/reponame.git`.
 
 The custom commands, like "info", "expand" should be handled as follows.  The
@@ -68,3 +57,16 @@ the arguments, with `+` representing a space.  Here are some examples:
 
 With a few nice shell aliases, you won't even notice the horrible convolutions
 here ;-)  See t/smart-http for a couple of useful ones.
+
+### server side
+
+The 'gitolite' command (for example, 'gitolite compile', 'gitolite query-rc',
+and so on) *can* be run on the server, but it's not straightforward.  Assuming
+you installed exactly as given in this document, you should
+
+  * get a shell by using, say, `su -s /bin/bash - apache`
+  * run `export HOME=$HOME/gitolite-home`
+  * run `export PATH=$PATH:$HOME/bin`
+
+and *then* you can run `gitolite <subcommand>`
+

doc/index.mkd

@@ -19,6 +19,7 @@ For users of gitolite v2.x (call it "g2" for convenience),
 
 ## #ql quick links
 
+  * [Trying][trying] out gitolite.
   * Minimum [requirements][req].
   * Here's how to do a [quick install, setup, and clone][qi].
   * Don't know ssh well enough?  [Learn][ssh].  It's **IMPORTANT**.
@@ -37,12 +38,12 @@ most people see:
 
   * Use a single unix user ("real" user) on the server.
   * Provide access to many gitolite users:
-      * they are not "real" users
+      * they are not "real" users,
-      * they do not get shell access
+      * they do not get shell access.
   * Control access to many git repositories:
-      * read access controlled at the repo level
+      * read access controlled at the repo level,
       * write access controlled at the branch/tag/file/directory level,
-        including who can rewind, create, and delete branches/tags
+        including who can rewind, create, and delete branches/tags.
   * Can be installed without root access, assuming git and perl are already
     installed.
   * Authentication is most commonly done using sshd, but you can also use

doc/install.mkd

@@ -42,11 +42,12 @@ Notes:
 
 ### server
 
-  * any Unix system with a posix compatible "sh".
+  * Any Unix system with a posix compatible "sh".
-  * git version 1.6.6 or later
+  * Git version 1.6.6 or later.
-  * perl 5.8.8 or later
+  * Perl 5.8.8 or later.
-  * openssh (almost any version).  Optional if you're using [smart http][http]
+  * Openssh (almost any version).  Optional if you're using [smart
-  * a dedicated Unix userid to be the hosting user, usually "git" but it can
+    http][http].
+  * A dedicated Unix userid to be the hosting user, usually "git" but it can
     be any user, even your own normal one.  (If you're using an RPM/DEB the
     install probably created one called "gitolite").
 
@@ -55,17 +56,13 @@ side.
 
 ### client
 
-  * openssh client
+  * Openssh client.
-  * git 1.6.6 or later.  Almost any git client will work, as long as it knows
+  * Git 1.6.6 or later.  Almost any git client will work, as long as it knows
     how to use ssh keys and send the right one along.
 
 ## getting the software
 
-    git clone -b g3 git://github.com/sitaramc/gitolite
+    git clone git://github.com/sitaramc/gitolite
-
-The -b g3' is needed until g3 becomes "master".  Current estimates put this
-around June 2012, when the old gitolite (upto v2.x) will be retired and
-supported only for security issues.
 
 ## the actual install
 
@@ -87,7 +84,7 @@ Option 2 is the best for general use.
 There is a program called 'install' that helps you do these easily.  Assuming
 your cloned the repo like this:
 
-    git clone -b g3 git://github.com/sitaramc/gitolite
+    git clone git://github.com/sitaramc/gitolite
 
 you can run the 'install' command in 3 different ways:
 
@@ -168,35 +165,35 @@ will normally touch in normal repos is the `update` hook.
 
 1.  Carefully wipe out the old gitolite
 
-      * the **code**
+      * The **code**
 
-          * delete or move away all the old gitolite scripts.  Check the path
+          * Delete or move away all the old gitolite scripts.  Check the path
             to the gl-auth-command in `~/.ssh/authorized_keys` if you forgot
             where you put them.
 
-          * delete or move away the two directories named in the two variables
+          * Delete or move away the two directories named in the two variables
-            `GL_PACKAGE_CONF` and `GL_PACKAGE_HOOKS` in `~/.gitolite.rc`
+            `GL_PACKAGE_CONF` and `GL_PACKAGE_HOOKS` in `~/.gitolite.rc`.
 
-      * the **rc file**
+      * The **rc file**
 
-          * rename `~/.gitolite.rc` to something else
+          * Rename `~/.gitolite.rc` to something else.
 
-      * the **admin repo**
+      * The **admin repo**
 
           * clone `~/repositories/gitolite-admin.git` to someplace safe
           * then delete `~/repositories/gitolite-admin.git`
 
-        (make sure you do not delete any other repos!)
+        (Make sure you do not delete any other repos!)
 
-      * the **admin directory**
+      * The **admin directory**.
 
-          * if you need to preserve logs, move the ~/.gitolite/logs` directory
+          * If you need to preserve logs, move the ~/.gitolite/logs` directory
-            somewhere else
+            somewhere else.
 
-          * if you added any custom hooks and wish to preserve them, move the
+          * If you added any custom hooks and wish to preserve them, move the
-            ~/.gitolite/hooks` directory somewhere else
+            ~/.gitolite/hooks` directory somewhere else.
 
-          * delete `~/.gitolite`
+          * Delete `~/.gitolite`.
 
 2.  Read about [presetting][rc-preset] the rc file; if you're using any
     variables listed as requiring preset, follow those instructions to create

doc/mirroring.mkd

@@ -17,19 +17,19 @@ world they are at best read-only.
 
 Gitolite extends this simple notion in the following ways:
 
-  * different masters and sets of slaves for different repos
+  * Different masters and sets of slaves for different repos
 
-    This lets you do things like
+    This lets you do things like:
 
-      * use the server closest to *most* of its developers as the master for
+      * Use the server closest to *most* of its developers as the master for
-        that repo
+        that repo.
-      * not mirror a repo at all to some servers
+      * Not mirror a repo at all to some servers.
-      * have repos that are purely local to a server (not mirrored at all)
+      * Have repos that are purely local to a server (not mirrored at all).
-      * negotiate mirroring with servers that are not even under your control
+      * Negotiate mirroring with servers that are not even under your control.
-      * push to a slave on demand or via cron (helps deal with bandwidth or
+      * Push to a slave on demand or via cron (helps deal with bandwidth or
         connectivity constraints).
 
-  * pushes to a slave can be transparently forwarded to the real master
+  * Pushes to a slave can be transparently forwarded to the real master.
 
     Your developers need not worry about where a repo's master is -- they just
     write to their local mirror for *all* repos, even if their local mirror is
@@ -37,16 +37,16 @@ Gitolite extends this simple notion in the following ways:
 
 ## caveats
 
-  * mirroring will never *create* a repo on a slave; it has to exist and be
+  * Mirroring will never *create* a repo on a slave; it has to exist and be
     prepared to receive updates from the master.  (For example, [wild][] repos
     must be created on the slave as well, otherwise they will not propagate).
 
-  * mirroring is only for git repos.  Ancillary files like gl-creator and
+  * Mirroring is only for git repos.  Ancillary files like gl-creator and
     gl-perms in the repo directory are not mirrored; you must do that
     separately.  Files in the admin directory (like log files) are also not
     mirrored.
 
-  * if you ever do a [bypass push][bypass], mirroring will not work.
+  * If you ever do a [bypass push][bypass], mirroring will not work.
     Mirroring checks also will not work -- for example, you can push to a
     slave, which is not usually a good idea.  So don't bypass gitolite if the
     repo is mirrored!
@@ -60,24 +60,24 @@ file settings and syntax.
 
 On **each** server:
 
-  * install gitolite normally.  Make clones of the server's 'gitolite-admin'
+  * Install gitolite normally.  Make clones of the server's 'gitolite-admin'
     repo on your workstation so you can admin them all from one place.
 
-  * give the server a short, simple, "hostname" and set the HOSTNAME in the
+  * Give the server a short, simple, "hostname" and set the HOSTNAME in the
     rc file to this name, for example 'mars'.
 
-  * run ssh-keygen if needed and get an ssh key pair for the server.  Copy the
+  * Run ssh-keygen if needed and get an ssh key pair for the server.  Copy the
     public key to a common area and name it after the host, but with 'server-'
     prefixed.  So the pubkey for server 'mars' would be stored as
     'server-mars.pub'.
 
-  * copy all keys to all the admin repo clones on your workstation and and add
+  * Copy all keys to all the admin repo clones on your workstation and and add
     them as usual.  This is an `O(N^2)` operation ;-)
 
     You may have guessed that the prefix 'server-' is special, and
     distinguishes a human user from a mirroring peer.
 
-  * create "host" aliases to refer to all other machines.  See [here][ssh-ha]
+  * Create "host" aliases to refer to all other machines.  See [here][ssh-ha]
     for what/how.
 
     The host alias for a host (in all other machines' `~/.ssh/config` files)
@@ -88,7 +88,7 @@ On **each** server:
     Normally you should be able to build one common file and append it to all
     the servers' `~/.ssh/config` files.
 
-  * the following **MUST** work for **each pair** of servers that must talk to
+  * The following **MUST** work for **each pair** of servers that must talk to
     each other:
 
         # on server mars
@@ -101,7 +101,7 @@ On **each** server:
     Check this command from *everywhere to everywhere else*, and make sure you
     get expected results.  **Do NOT proceed otherwise.**
 
-  * setup the gitolite.conf file on all the servers.  If the slaves are to be
+  * Setup the gitolite.conf file on all the servers.  If the slaves are to be
     exact copies of the master, you need to do the complete configuration only
     on the master; the slaves can have just this:
 
@@ -114,7 +114,7 @@ On **each** server:
     because on the first push to the master it will update all the slaves
     anyway.
 
-  * when that is all done and tested, **enable mirroring** by going through
+  * When that is all done and tested, **enable mirroring** by going through
     the rc file and uncommenting all the lines mentioning `Mirroring`.
 
 ### conf file settings and syntax

doc/non-core.mkd

@@ -29,11 +29,11 @@ Here's a list of remote commands that are shipped:
 
 The following "sugar" programs are available:
 
-  * continuation-lines -- allow the use of C-style backslash escaped
+  * Continuation-lines -- allow the use of C-style backslash escaped
     continuation lines in the conf file.  I don't like it but some people do,
     and now I can support them without bulking up the "core" conf parser!
 
-  * keysubdirs-as-groups -- someone wanted the sub-directory name (of
+  * Keysubdirs-as-groups -- someone wanted the sub-directory name (of
     "keydir/") in which the pubkey was placed to be a group to which the user
     automatically belonged.  A very unusual requirement, and one which would
     *never* have seen the light of day in g2, but in g3 it's easy, and doesn't
@@ -46,9 +46,9 @@ The following "sugar" programs are available:
 
 The `PRE_GIT` triggers are:
 
-  * partial-copy -- this has its own section later in this page
+  * partial-copy -- this has its own section later in this page.
 
-  * renice -- this renices the entire job to whatever value you specify
+  * renice -- this renices the entire job to whatever value you specify.
 
 The `POST_GIT` triggers are:
 
@@ -79,7 +79,7 @@ The `POST_COMPILE` triggers are:
 
 The `POST_CREATE` triggers are:
 
-  * the last 3 in the `POST_COMPILE` list also run from `POST_CREATE`, for
+  * The last 3 in the `POST_COMPILE` list also run from `POST_CREATE`, for
     obvious reasons.
 
 ## VREFs
@@ -124,10 +124,10 @@ And that should be it.  **Please test it and let me know if it doesn't work!**
 
 WARNINGS:
 
-  * if you change the config to disallow something that used to be allowed,
+  * If you change the config to disallow something that used to be allowed,
     you should delete the partial repo on the server and then run 'gitolite
     compile' to let it build again.  See t/partial-copy.t for details.
 
-  * not tested with smart http; probably won't work
+  * Not tested with smart http; probably won't work.
 
-  * also not tested with mirroring, or with wild card repos.
+  * Also not tested with mirroring, or with wild card repos.

doc/progit.mkd

@@ -18,13 +18,11 @@ Gitolite is somewhat unusual as far as "server" software goes -- access is via s
 
 To begin, create a user called `git` on your server and login to this user.  Copy your ssh pubkey (a file called `~/.ssh/id_rsa.pub` if you did a plain `ssh-keygen` with all the defaults) from your workstation, renaming it to `YourName.pub`.  Then run these commands:
 
-    git clone -b g3 git://github.com/sitaramc/gitolite
+    git clone git://github.com/sitaramc/gitolite
     gitolite/install -ln
     gitolite setup -pk $HOME/YourName.pub
         # for example, I would run 'gitolite setup -pk $HOME/sitaram.pub'
 
-(Note: the "-b g3" will not be needed once gitolite v3 becomes the "master" version.)
-
 Finally, back on your workstation, run `git clone git@server:gitolite-admin`.
 
 And you're done!  Gitolite has now been installed on the server, and you now have a brand new repository called `gitolite-admin` in your workstation.  You administer your gitolite setup by making changes to this repository and pushing.  See adding [users][] and [repos][] to start with.

doc/qi.mkd

@@ -5,7 +5,7 @@
 On the server:
 
     # get the software
-    git clone -b g3 git://github.com/sitaramc/gitolite
+    git clone git://github.com/sitaramc/gitolite
 
     # install it
     gitolite/install -ln
@@ -20,18 +20,18 @@ On your workstation:
 
 ## ASSUMPTIONS
 
-  * this is a fresh install, not a migration from the old gitolite (v1.x,
+  * This is a fresh install, not a migration from the old gitolite (v1.x,
     v2.x).
 
-  * on the server, your `$PATH` contains `$HOME/bin`.  If you don't like that,
+  * On the server, your `$PATH` contains `$HOME/bin`.  If you don't like that,
     there are [other install methods][install].
 
   * "your-name.pub" is your public key from your workstation.
-      * also, this key does not already have shell access to this gitolite
+      * Also, this key does not already have shell access to this gitolite
-        hosting user
+        hosting user.
 
-  * the setup command does not generate any warnings.
+  * The setup command does not generate any warnings.
-      * if it does, please see [common errors][ce] and fix things before
+      * If it does, please see [common errors][ce] and fix things before
         continuing, or read the more complete [setup][] page.
 
 ## Notes

doc/rare.mkd

@@ -4,21 +4,21 @@
 
 On the server:
 
-  * move the repos to `$HOME/repositories`.
+  * Move the repos to `$HOME/repositories`.
 
-  * make sure that:
+  * Make sure that:
 
-      * they are all *bare* repos
+      * They are all *bare* repos.
-      * all the repo names end in ".git"
+      * All the repo names end in ".git".
-      * all the files and directories are owned and writable by the gitolite
+      * All the files and directories are owned and writable by the gitolite
-        hosting user (especially true if you copied them as root)
+        hosting user (especially true if you copied them as root).
 
-  * run `gitolite setup`.  **If you forget this step, you can also forget
+  * Run `gitolite setup`.  **If you forget this step, you can also forget
     about write access control!**
 
 Back on your workstation:
 
-  * [add them][repos] to conf/gitolite.conf in your clone of the admin repo,
+  * [Add them][repos] to conf/gitolite.conf in your clone of the admin repo,
     then commit and push the change.
 
     If the repos are already covered by some [wild][] pattern, this is
@@ -42,11 +42,11 @@ servers is this (untested but should work; feedback appreciated):
 3.  [Disable][writable] the old server so people won't push to it.
 
 4.  Copy all the repos over from the old server, including gitolite-admin.
-    Make sure the files end up with right ownership and permissions; if not,
+    Make sure the files end up with the right ownership and permissions; if
-    chown/chmod them.
+    not, chown/chmod them.
 
-5.  On a clone of the old gitolite-admin, add a new remote (or change an
+5.  Run `gitolite setup`.
+
+6.  On a clone of the old gitolite-admin, add a new remote (or change an
     existing one) to point to the new server.  Then `git push -f` to this
     remote.
-
-6.  On the server, run `gitolite setup`.

doc/rc.mkd

@@ -20,7 +20,7 @@ sure the brackets and braces stay matched up!
 Please look at the `~/.gitolite.rc` file that gets installed when you setup
 gitolite.  As you can see there are 3 types of variables in it:
 
-  * simple variables (like UMASK)
+  * simple variables (like `UMASK`)
   * lists (like `POST_COMPILE`, `POST_CREATE`)
   * hashes (like `ROLES`, `COMMANDS`)
 

doc/refex.mkd

@@ -5,12 +5,12 @@ A refex is a word I made up to mean "a regex that matches a ref".  If you know
 
 In addition:
 
-  * if no refex is supplied, it defaults to `refs/.*`, for example in a rule
+  * If no refex is supplied, it defaults to `refs/.*`, for example in a rule
     like this:
 
         RW              =   alice
 
-  * a refex not starting with `refs/` is assumed to start with `refs/heads/`.
+  * A refex not starting with `refs/` is assumed to start with `refs/heads/`.
     This means normal branches can be conveniently written like this:
 
         RW  master      =   alice
@@ -20,7 +20,7 @@ In addition:
 
         RW  refs/tags/v[0-9]    =   bob
 
-  * a refex is implicitly anchored at the start, but not at the end.  In
+  * A refex is implicitly anchored at the start, but not at the end.  In
     regular expression lingo, a `^` is assumed at the start (but no `$` at the
     end is assumed).  So a refex of `master` will match all these:
 

doc/repos.mkd

@@ -52,5 +52,5 @@ server and do what you need to.
 **Renaming** a repo is also not automatic.  Here's what you do (and the order
 is important):
 
-  * go to the server and rename the repo at the Unix command line
+  * Go to the server and rename the repo at the Unix command line.
-  * change the name in the conf/gitolite.conf file and add/commit/push.
+  * Change the name in the conf/gitolite.conf file and add/commit/push.

doc/rules.mkd

@@ -58,35 +58,35 @@ example will pass the pre-git check.
 
 For the **update check**, git gives us all the information we need.  Then:
 
-  * all the rules for a repo are [accumulated][rule-accum]
+  * All the rules for a repo are [accumulated][rule-accum].
 
-  * the rules pertaining to this repo *and* this user (or to a group to which
+  * The rules pertaining to this repo *and* this user (or to a group to which
-    they belong, respectively) are kept; the rest are ignored
+    they belong, respectively) are kept; the rest are ignored.
 
-  * these rules are examined *in the sequence they appeared in the conf file*.
+  * These rules are examined *in the sequence they appeared in the conf file*.
     For each rule:
 
-      * if the ref does not match the [refex][], the rule is skipped
+      * If the ref does not match the [refex][], the rule is skipped.
-      * if it's a deny rule (the permissions field is a `-`), access is
+      * If it's a deny rule (the permissions field is a `-`), access is
-        **rejected** and the matching stops
+        **rejected** and the matching stops.
-      * if the permission field matches the specific [type of
+      * If the permission field matches the specific [type of
         write][write-types] operation, access is **allowed** and the matching
-        stops
+        stops.
 
-  * if no rule ends with a decision, ("fallthru"), access is **rejected**.
+  * If no rule ends with a decision, ("fallthru"), access is **rejected**.
 
 Now you need to understand how [refex][] matching happens and how the
 permissions match the various [types of write operations][write-types].
 
 Using these, you can see, in our example, that:
 
-  * everyone, even wally, can read the repo.
+  * Everyone, even wally, can read the repo.
-  * dilbert can push, rewind, or delete any ref.
+  * Dilbert can push, rewind, or delete any ref.
-  * alice can push, rewind, or delete any ref whose name starts with 'dev';
+  * Alice can push, rewind, or delete any ref whose name starts with 'dev';
     see [refex][] for details.
-  * alice can also push (but not rewind or delete) any ref whose name starts
+  * Alice can also push (but not rewind or delete) any ref whose name starts
     with 'temp/'.  This applies to bob also.
-  * if it weren't for line 3, the previous statement would apply to wally
+  * If it weren't for line 3, the previous statement would apply to wally
     also.
 
 Interestingly, wally can get past the pre-git check because gitolite ignores
@@ -94,7 +94,7 @@ deny rules for pre-git, but having got past it, he can't actually do anything.
 That's by design, and as I said if you don't like it you can ask gitolite to
 [deny at pre-git][deny-rules].
 
-### #perms summary of permissions
+### #permsum summary of permissions
 
 The full set of permissions, in regex syntax: `-|R|RW+?C?D?M?`.  This expands
 to one of `-`, `R`, `RW`, `RW+`, `RWC`, `RW+C`, `RWD`, `RW+D`, `RWCD`, or

doc/setup.mkd

@@ -31,13 +31,13 @@ server.  That won't work.
 The 'setup' command has other uses, so you will be running it at other times
 after the install as well:
 
-  * to setup the update hook when you move [existing][] repos to gitolite.
+  * To setup the update hook when you move [existing][] repos to gitolite.
     This also applies if someone has been fiddling with the hooks on some
     repos and you want to put them all right quickly.
 
-  * to replace a [lost admin key][lost-key].
+  * To replace a [lost admin key][lost-key].
 
-  * to setup gitolite for http mode (run 'gitolite setup -h' for more info)
+  * To setup gitolite for http mode (run 'gitolite setup -h' for more info).
 
 When in doubt, run 'gitolite setup' anyway; it doesn't do any harm, though it
 may take a minute or so if you have more than a few thousand repos!

doc/special.mkd

@@ -34,13 +34,13 @@ A user "alice" (if she's in the userlist) can then push any branches inside
 (Background: at runtime the "USER" component will be replaced by the name of
 the invoking user.  Access is determined by the right hand side, as usual).
 
-Compared to using arbitrary branch names on the same server, this
+Compared to using arbitrary branch names on the same server, this:
 
-  * reduces namespace pollution by corralling all these ad hoc branches into
+  * Reduces namespace pollution by corralling all these ad hoc branches into
     the "personal/" namespace.
-  * reduces branch name collision by giving each developer her own
+  * Reduces branch name collision by giving each developer her own
     sub-hierarchy within that.
-  * removes the need to think about access control, because a user can push
+  * Removes the need to think about access control, because a user can push
     only to his own sub-hierarchy.
 
 ## delegating access control responsibilities

doc/sskm.mkd

@@ -223,12 +223,12 @@ Listing the keys shows that that new key is now marked active again:
 
 These are the things that can break if you allows your users to use this command:
 
-  * if you, as the gitolite admin, are in the habit of force-pushing changes
+  * If you, as the gitolite admin, are in the habit of force-pushing changes
     to the admin repo instead of doing a `git pull` (or, even better, a `git
     pull --rebase`) then you had better not enable this command.  Your users
     will eventually come after you with pitchforks ;-)
 
-  * there is no way to distinguish `foo/alice.pub` from `bar/alice.pub` using
+  * There is no way to distinguish `foo/alice.pub` from `bar/alice.pub` using
     this command.  You can distinguish `foo/alice.pub` from
     `bar/alice@home.pub`, but that's not because of the foo and bar, it's
     because the two files have different keyids.
@@ -236,7 +236,7 @@ These are the things that can break if you allows your users to use this command
     In other words, sskm only works with the older style, not with the
     "subdirectory" style of [multi-key][] management.
 
-  * keys placed in specific folders (for whatever reasons), will probably not
+  * Keys placed in specific folders (for whatever reasons), will probably not
     stay in those folders if this command is used.  Even a key delete, followed
     by undoing the delete, will cause the key to effectively move to the root
     of the key store (i.e., the `keydir` directory in the gitolite-admin repo).

doc/testing.mkd

@@ -7,9 +7,11 @@ so be sure to use a throwaway userid**.</font>
 
     git clone git://github.com/sitaramc/gitolite
     cd gitolite
-    git checkout -f g3
     prove
 
+(Make sure sshd allows incoming ssh to this userid at least from localhost.
+Out of scope for this document: sshd config, 'AllowUsers', etc...)
+
 Gitolite's test suite is mostly written using [tsh][] -- the "testing shell".
 Take a look at some of the scripts and you will see what it looks like.  It
 has a few quirks and nuances; if you really care, email me.
@@ -23,3 +25,24 @@ would otherwise take.
 
 If you think that defeats the purpose of the testing, you haven't read
 [this][auth] yet.
+
+## #trying trying out gitolite
+
+It's easy to take gitolite for a trial run, in ssh mode, and play with all of
+its features (except mirroring).
+
+Create a **throw-away userid**, log in to it, then do what the "testing
+gitolite" section above says, except instead of running `prove`, you run
+`prove t/ssh*`.
+
+When this is done, you get a gitolite installation with 7 gitolite users
+("admin", and "u1" through "u6").
+
+Don't forget that the client and the server are all on the same user on the
+same machine; we're *simulating* 7 gitolite users using ssh keys!  (How?
+Maybe `~/.ssh/config` will give you a hint).
+
+URLs look like `user:repo`, so for example you can clone the admin repo by
+`git clone admin:gitolite-admin`.  Remote commands look like `ssh u1 info`.
+
+So start by cloning the admin repo, and try out whatever you want!

doc/user.mkd

@@ -3,10 +3,6 @@
 ...written for the one guy in the world no one will think of as "just a normal
 user" ;-)
 
-This document has some text, and a lot of links.  Most of this info *is*
-available in the rest of the documentation, but it's scattered and sparse.
-Collecting all of it, or at least links to it, in one place sounds useful.
-
 ----
 
 [[TOC]]
@@ -42,7 +38,7 @@ that look like regex patterns, (with a "C" permission).
 
 If you see any, it means you are allowed to create brand new repos whose names
 fit that pattern.  When you create such a repo, your "ownership" of it (as far
-as gitolite is concerned) is *automatically* recorded by gitolite.
+as gitolite is concerned) is automatically recorded by gitolite.
 
 ## other commands
 

doc/vref.mkd

@@ -82,14 +82,14 @@ exit.
 
 ## how it works -- details
 
-  * the VREF code is only called if there are any VREF rules for the user,
+  * The VREF code is only called if there are any VREF rules for the user,
     which means when the lead developer pushes, the VREF is not called at all.
 
     Side note: this is enormously more efficient than adding additional
     `update` hooks, which will get executed whether they are needed or not,
     for every repo and every user!
 
-  * when dev2 or dev3 push, gitolite first checks the real ref
+  * When dev2 or dev3 push, gitolite first checks the real ref
     (`ref/heads/master` or whatever).  After this it looks at VREF rules, and
     calls an external program for every one it finds.  Specifically, in a line
     like
@@ -102,29 +102,29 @@ exit.
     The program is passed **nine arguments** in this case (see next section
     for details).
 
-  * the script can print anything it wants to STDOUT; the first word in each
+  * The script can print anything it wants to STDOUT; the first word in each
     such line will be treated as a virtual ref to be matched against all the
     rules, while the rest, if any, is a message to be added to the standard
     "...DENIED..." message that gitolite prints if that refex matches.
 
     Usually it only makes sense to either
 
-      * print nothing -- if you don't want the rule that triggered it to match
+      * Print nothing -- if you don't want the rule that triggered it to match
         (ie., whatever condition being tested was not violated; like if the
-        count of changed files did not exceed 9, in our earlier example)
+        count of changed files did not exceed 9, in our earlier example).
-      * print the refex itself (plus an optional message), so that it matches
+      * Print the refex itself (plus an optional message), so that it matches
-        the line which invoked it
+        the line which invoked it.
 
 ### arguments passed to the vref code
 
-  * arguments **1, 2, 3**: the 'ref', 'oldsha', and 'newsha' that git passed
+  * Arguments **1, 2, 3**: the 'ref', 'oldsha', and 'newsha' that git passed
-    to the update hook (see 'man githooks')
+    to the update hook (see 'man githooks').
 
     This, combined with the fact that non-zero exits are detected, mean that
     you can simply use an existing update.secondary as a new VREF as-is, no
     changes needed.
 
-  * arguments **4 and 5**: the 'oldtree' and 'newtree' SHAs.  These are the
+  * Arguments **4 and 5**: the 'oldtree' and 'newtree' SHAs.  These are the
     same as the oldsha and newsha values, except if one of them is all-0.
     (indicating a ref creation or deletion).  In that case the corresponding
     'tree' SHA is set (by gitolite, as a courtesy) to the special SHA
@@ -134,15 +134,15 @@ exit.
     (None of these shenanigans would have been needed if `git diff $oldsha
     $newsha` would not error out when passed an all-0 SHA.)
 
-  * argument **6**: the attempted access flag.  Typically `W` or `+`, but
+  * Argument **6**: the attempted access flag.  Typically `W` or `+`, but
     could also be `C`, `D`, or any of these 4 followed by `M`.  If you have to
     ask what they mean, you haven't read enough gitolite documentation to be
     able to make virtual refs work.
 
-  * argument **7**: is the entire refex; in our example
+  * Argument **7**: is the entire refex; in our example
     `VREF/COUNT/3/NEWFILES`.
 
-  * arguments **8 onward**: are the split out (by `/`) portions of the refex,
+  * Arguments **8 onward**: are the split out (by `/`) portions of the refex,
     excluding the first two components.  In our example they would be `3`
     followed by `NEWFILES`.
 
@@ -288,14 +288,14 @@ quite different.
 
 Here are some more ideas:
 
-  * number of commits (`git rev-list --count $old $new`)
+  * Number of commits (`git rev-list --count $old $new`).
-  * number of binary files in commit (currently I only know to count
+  * Number of binary files in commit (currently I only know to count
-    occurrences of ` Bin ` in the output of `git diff --stat`
+    occurrences of ` Bin ` in the output of `git diff --stat`.
-  * number of *new* binary files (count ` Bin 0 ->` in `git diff --stat`
+  * Number of *new* binary files (count ` Bin 0 ->` in `git diff --stat`
-    output)
+    output).
-  * time of day/day of week (see example snippet somewhere above)
+  * Time of day/day of week (see example snippet somewhere above).
-  * IP address
+  * IP address.
-  * phase of the moon
+  * Phase of the moon.
 
 Note that pretty much anything that involves `$oldsha..$newsha` will have to
 deal with the issue that when you push a new tag or branch, the "old" part

doc/why.mkd

@@ -1,47 +1,97 @@
 # why might you need gitolite
 
-Gitolite is separate from git, and needs to be installed and configured.  So...
+[[TOC]]
-why do we bother?
+
+----
+
+## basic use case
 
 Gitolite is useful in any server that is going to host multiple git
-repositories, each with many developers, where some sort of access control is
+repositories, each with many developers, where "anyone can do anything to any
-required.
+repo" is not a good idea.  Here're two examples to illustrate.
 
-In theory, this can be done with plain old Unix permissions: each user is a
+Example 1, 3 repos, 3 developers with different levels of access to each repo:
-member of one or more groups, each group "owns" one or more repositories, and
-using unix permissions (especially the setgid bit -- `chmod g+s`) you can
-allow/disallow users access to repos.
 
-But there are several disadvantages here:
+    repo foo
+        RW+     =   alice
+        R       =   bob
 
-  * Every user needs a userid and password on the server.  This is usually a
+    repo bar
-    killer, especially in tightly controlled environments.
+        RW+     =   bob
-  * Adding/removing access rights involves complex `usermod -G ...` mumblings
+        R       =   alice
-    which most admins would rather not deal with.
-  * *Viewing* (aka auditing) the current set of permissions requires running
-    multiple commands to list directories and their permissions/ownerships,
-    users and their group memberships, and then correlating all these
-    manually.
-  * Auditing historical permissions or permission changes is pretty much
-    impossible without extraneous tools.
-  * Errors or omissions in setting the permissions exactly can cause problems
-    of either kind: false accepts or false rejects.
-  * Without going into ACLs it is not possible to give some people read-only
-    access while some others have read-write access to a repo (unless you make
-    it world-readable).  Group access just doesn't have enough granularity.
-  * It is absolutely impossible to restrict pushing by branch name or tag
-    name.
 
-Gitolite does away with all this:
+    repo baz
+        RW+     =   carol
+        R       =   alice bob
 
-  * It uses ssh magic to remove the need to give actual unix userids to
+Example 2, one repo, but different levels of access to different branches and
-    developers.
+tags for different developers:
-  * It uses a simple but powerful config file format to specify access rights.
-  * Access control changes are affected by modifying this file, adding or
-    removing user's public keys, and "compiling" the configuration.
-  * This also makes auditing trivial -- all the data is in one place, and
-    changes to the configuration are also logged, so you can audit them.
-  * Finally, the config file allows distinguishing between read-only and
-    read-write access, not only at the repository level, but at the branch
-    level within repositories.
 
+    repo foo
+        RW+ master                  =   alice
+        RW+ dev/                    =   bob
+        RW  refs/heads/tags/v[0-9]  =   ashok
+
+## #alt alternatives
+
+### unix permissions and ACLs
+
+If you're a masochist, you could probably do example 1 with Unix permissions
+and facls.  But you can't do example 2 -- git is not designed to allow that!
+
+Here are some other disadvantages of the Unix ACL method:
+
+  * Every user needs a userid and password on the server.
+  * Changing access rights involves complex `usermod -G ...` mumblings
+    (I.e., the "pain" mentioned above is not a one-time pain!)
+  * *Viewing* the current set of permissions requires running multiple
+    commands to list directories and their permissions/ownerships, users and
+    their group memberships, and then correlating all these manually.
+  * Auditing historical permissions or permission changes is impossible.
+
+### #gcr Gerrit Code Review
+
+The best real alternative to gitolite is Gerrit Code Review.  If code review
+is an essential part of your workflow, you should use Gerrit.
+
+Here're some high level differences between gitolite and Gerrit:
+
+**Size**: 3000+ lines of perl versus of 56,000+ lines of Java
+
+**Architecture**: Gitolite sits on top of "standard" git and openssh, which
+are assumed to already be installed.  Gerrit includes its own git stack (jgit)
+and sshd (Apache Mina).  In Java tradition, they all come bundled together.
+
+(Corollary: As far as I know jgit does not support the same hooks that 'man
+githooks' talks about).
+
+Gitolite uses a plain text config file; gerrit uses a database.
+
+**User view**: Gitolite is invisible to users except when access is denied.  I
+think Gerrit is much more visible to devs.
+
+On a related note, gitolite does not do anything special with signed or
+annotated tags, nor does it check author/committer identity.  However, it is
+trivial to add your own code to do either (or if someone contributes it, to
+just "enable" what ships with gitolite in a disabled state).
+
+### gitorious
+
+Anecdotally, gitorious is very hard to install.  Comparison with gitolite may
+be useless because I believe it doesn't have branch/tag level access control.
+However, I can't confirm or deny this because I can't find any documentation
+on the website.
+
+In addition, the main website hides the source code very well, so you already
+have a challenge!  [The only link I could find was tucked away at the bottom
+of the About page, in the License section].
+
+### gitlab
+
+Gitlab is built on top of gitolite, but I don't know more than that as yet.
+Patches welcome.
+
+### others
+
+Please send in patches to this doc if you know of other open source git
+hosting solutions that do access control.

doc/wild.mkd

@@ -90,9 +90,11 @@ But you may be surprised to find that it does not match even
 `^assignments/S[0-9]+/A[0-9]+$` -- notice the line beginning and ending
 metacharacters.
 
-Side-note: contrast with refexes
+>   ----
 
->   Just for interest, note that this is in contrast to the refexes for the >
+>   *Side-note: contrast with refexes*
+
+>   Just for interest, note that this is in contrast to the refexes for the
 >   normal "branch" permissions, as described in `doc/gitolite.conf.mkd` and
 >   elsewhere.  These "refexes" are only anchored at the start; a pattern like
 >   `refs/heads/master` actually can match `refs/heads/master01/bar` as well,
@@ -100,11 +102,13 @@ Side-note: contrast with refexes
 >   sides if you really care, by using `master$` instead of `master`, but that
 >   is *not* the default for refexes.
 
+>   ----
+
 ## roles
 
-The tokens READERS and WRITERS are called "role" names.  The access rules that
+The tokens READERS and WRITERS are called "role" names.  The access rules in
-the admin specifies say what permissions these roles have, but they don't say
+the conf file decide what permissions these roles have, but they don't say
-what users are in these roles.
+what users are in each of these roles.
 
 That needs to be done by the creator of the repo, using the `perms` command.
 You can run `ssh git@host perms -h` for detailed help, but in brief, that
@@ -146,4 +150,8 @@ command.  Try `ssh git@host info -h` to get help on the info command.
 
 ## deleting a wild repo
 
-TBD
+Run the whimsically named "D" command -- try `ssh git@host D -h` for more info
+on how to delete a wild repo.  (Yes the command is "D"; it's meant to be a
+counterpart to the "C" permission that allowed you to create the repo in the
+first place).  Of course this only works if your admin has enabled the command
+(gitolite ships with the command disabled for remote use).

doc/write-types.mkd

@@ -11,14 +11,14 @@ The most common are:
 Sometimes you want to allow people to push, but not *create* a ref.  Or
 rewind, but not *delete* a ref.  The `C` and `D` qualifiers help here.
 
-  * when a rule specifies `RWC` or `RW+C`, then *rules that do NOT have the C
+  * When a rule specifies `RWC` or `RW+C`, then *rules that do NOT have the C
-    qualifier will no longer permit **creating** a ref*
+    qualifier will no longer permit **creating** a ref*.
 
     <font color="gray">Please do not confuse this with the standalone `C`
     permission that allows someone to [create][] a **repo**</font>
 
-  * when a rule specifies `RWD` or `RW+D`, then *rules that do NOT have the C
+  * When a rule specifies `RWD` or `RW+D`, then *rules that do NOT have the C
-    qualifier will no longer permit **deleting** a ref*
+    qualifier will no longer permit **deleting** a ref*.
 
 Note: These two can be combined, so you can have `RWCD` and `RW+CD` as well.