next round of doc changes

README.mkd

@@ -6,7 +6,9 @@ instructions.
 
 But if you want to do anything meaningful with gitolite you have to spend some
 time cuddling up to the docs.  **The complete online documentation starts
-[here](http://sitaramc.github.com/gitolite)**.
+[here](http://sitaramc.github.com/gitolite)** -- this is the best starting
+point for general questions about git, such as what it is, why you would need
+it, features, contact/mailing list info, and so on.
 
 For convenience, here is a link to the [master table of
 contents](http://sitaramc.github.com/gitolite/master-toc.html), which is very

doc/1000-words.mkd

@@ -156,7 +156,7 @@ together.  This is particularly useful for an admin to see where his
 site-local hooks fit, how they get called, and what stages of the process they
 affect.
 
-Legend: diamonds are decision boxes whose results can abort the operation.
+**Legend**: diamonds are decision boxes whose results can abort the operation.
 Arrows are calls/invocations.  Dashed lines just point to sub-parts of the
 process on the left side.  Blue processes are external to gitolite.  Green is
 gitolite code.  Yellow is site-local code that you (the admin of your site)

doc/gitolite.conf.mkd

@@ -7,10 +7,48 @@ and users.  There was also, in the author's mind, a desperate need to create
 something as different as possible from the brain-dead, nausea-inducing
 "Windows INI" style syntax that some other popular tools seem to favour.
 
-This document describes the syntax and semantics of the access control rules
+## #confrecap a quick summary of the conf file
-and other configuration directives in the `gitolite.conf` file.
 
-## #syntax syntax
+This is a quick *recap* of the *most common* elements in a typical config
+file.  (In the following description, the angle brackets are not part of the
+syntax).
+
+  * (optional) [group][groups] definitions
+
+        @<groupname> = <list of users and groups>
+
+  * repo access rules
+
+        repo <reponame>
+            # one or more access rules like
+            <permission> <optional refex> = <list of users and groups>
+
+    The [most common][bac] permissions are:
+
+      * R, for read only
+      * RW, for push existing ref or create new ref
+      * RW+, for  "push -f" or ref deletion allowed (i.e., destroy
+        information)
+      * `-` (the minus sign), to [deny][] access
+
+    If no [refex][] is supplied, the access rule applies to all refs.
+
+    Later, gitolite [acquired][rwcd]
+
+      * RWC and RW+C, for ref creation.  Once you use this in a repo, a normal
+        RW/RW+ can no longer create a ref; it can only push existing refs
+        (<font color="gray">Note also that a standalone "C" permission is
+        something [completely different][wild]</font>)
+      * RWD and RW+D, for ref deletion.  Once you use this in a repo, a normal
+        RW+ can no longer delete a ref; it can only rewind
+      * (RWCD and RW+CD, which is just a combination of these two)
+
+The following sections dig deeper into the syntax and semantics of the access
+control rules and other configuration directives in the `gitolite.conf` file.
+If narrative descriptions scare you, or your English is not upto scratch, try
+[gitolite config by example][conf_examples] also.
+
+## F=syntax lexical syntax
 
 In general, everything is **space separated**; there are no commas,
 semicolons, etc., in the syntax.
@@ -39,18 +77,20 @@ include them in the main file for convenience.
 
     include     "foo.conf"
 
-will include the contents of the file "foo.conf" from the same directory as
+will include the contents of the file "foo.conf".
-the main config file.  You can also use an absolute path if you like, although
-in the interests of cloning the admin-repo sanely you should avoid doing this!
 
-You can also use a glob, as in:
+Details:
 
-    include     "*.conf"
+  * You can also use a glob (`include "*.conf"`), or put your include files
+    into subdirectories of "conf" (`include "foo/bar.conf"`), or both
+    (`include "repos/*.conf"`).
 
-which will include all the ".conf" files from the directory in which the main
+  * Included files are always searched from the gitolite-admin repo's "conf/"
-config file exists.
+    directory, unless you supplied an absolute path.  (Note: in the interests
+    of cloning the admin-repo sanely you should avoid absolute paths!)
 
-Files that have been already processed once are skipped, with a warning.
+  * If you ended up recursing, files that have been already processed once are
+    skipped, with a warning.
 
 <font color="gray">Advanced users: `subconf`, a command that is very closely
 related to `include`, is documented [here][subconf].</font>
@@ -105,7 +145,7 @@ Gitolite goes down the list of rules matching the user, repo, and the ref.
 The first matching rule that has the permission you're looking for (`W` or
 `+`), results in success.  A fallthrough results in failure.
 
-### branches, tags, and specifying "refex"es
+### #refex branches, tags, and specifying "refex"es
 
 One of the original goals of gitolite was to allow access control at the
 branch/tag (aka "ref") level.  The git source code contains a sample update
@@ -162,7 +202,7 @@ looks like "refs/heads/foo", while a tag ref looks like "refs/tags/bar")
     "v1.0", "v2.0rc1", all match the criterion specified by `v[0-9]` because
     this is a prefix match only.
 
-### groups
+### #groups groups
 
 Gitolite allows you to define **groups** of repos. users, or even refexes.  A
 group is semantically (but *not* syntactically) like a `#define` in C.  Here
@@ -211,7 +251,8 @@ when used as a username; you've seen examples of it earlier.
 Advanced users: also see the entry for `GL_ALL_INCLUDES_SPECIAL` in the
 documentation for [`~/.gitolite.rc`][rc].
 
-When used as a reponame, it includes all repos.
+When used as a reponame, it includes all repos physically present in
+`~/repositories` (or whatever is the value of `$REPO_BASE`).
 
 ### F=rpr_ side note: "R" permissions for refs
 
@@ -358,7 +399,7 @@ had core.logAllRefUpdates set, which is *not* a default setting).
 
 However, there seem to be cases where it is useful to distinguish these cases.
 Arguments can be made on all sides if you're dealing with new users, so
-gitolite supports that.
+gitolite now supports that (in a backward compatible way).
 
 We'll look at the delete/rewind case in detail first:
 

doc/index.mkd

@@ -24,57 +24,47 @@ manage the server by cloning the special 'gitolite-admin' repo on your
 workstation (`git clone git@server:gitolite-admin`), making changes, and
 pushing them.  Here's how to [add users and repos][add].
 
-## #rtfm what should you read?
+## #rtfm what to read...
 
-The complete online documentation for gitolite is
+Gitolite comes with a *lot* of documentation.  The master TOC (see link above)
-[here](http://sitaramc.github.com/gitolite).  There's a lot of it, so here're
+is the *only* comprehensive list of what is there, but here's an overview.
-some reading suggestions.
-
-If you're a **user** (i.e., not a gitolite admin), you only need [this][user].
-
-Otherwise, the suggested reading order is this:
-
-  * **quick intro**: this document, or at least the "[what is
-    gitolite][gl_what]" section just below this one.
-  * **installation**: if the [quick install][qi] above did not work for you,
-    then read the [INSTALL][install] document.  The "[trouble][insttrouble]"
-    section in it may be useful too.
-  * **basic** administration tasks: [adding users and repos][add].
-
-When you have to use more features, look in the master table of contents
-(there's a link to it at the top of *every* document), and use your browser's
-search function to search for stuff.
-
-### F=other_docs what do the other docs contain
-
-The master TOC (see link above) is really the only *comprehensive* list of
-what is there, but here's an attempt to give you an overview!
 
   * understanding gitolite
+      * [what is gitolite][gl_what], and the rest of this document
       * gitolite install and basic admin in [pictures][]
-      * gitolite.conf by [example][conf_examples]
       * gitolite and [ssh][gl_ssh]
 
+  * explaining gitolite to your *users*
+      * the [user][] document is all they need
+
+  * install and setup
+      * the "[install trouble?][insttrouble]" section, which links, among
+        other things, to arguably the most useful doc for a newbie: [ssh
+        troubleshooting][sts]!
+      * maybe even the complete [install][] document
+
   * normal admin tasks done on the server
-      * [admin][]: adding your own hooks, adding existing repos into gitolite, etc.
+      * [adding users and repos][add]
-      * [rc][]: setting gitolite behaviour options (warning: some of the
+      * [admin][]: add your own hooks, add existing repos into gitolite, etc.
+      * [rc][]: sett gitolite behaviour options (warning: some of the
         variables have a security impact if you're careless)
 
   * normal admin tasks done by changing [gitolite.conf][conf]
       * basic access control
       * advanced access control
       * extras: personal branches, gitweb/git-daemon access, git config settings
+      * [gitolite.conf by example][conf_examples] may also help
 
   * advanced use (experts only; you can shoot yourself in the foot nicely!)
-      * [ADCs][]: allowing users to run specific shell commands (but not give them a shell)
+      * [ADCs][]: allow users to run specific shell commands (but not give them a shell)
       * (also, [sample ADCs][shipped_ADCs] that come with gitolite)
-      * letting [users create][wild] their own repos and assign permissions
+      * let [users create][wild] their own repos and assign permissions
-      * [delegating][deleg] admin rights
+      * [delegate][deleg] admin rights
-      * [mirroring][]
+      * [mirror][mirroring] your servers
 
   * special installation scenarios:
-      * using smart-[http][] instead of ssh
+      * use smart-[http][] instead of ssh
-      * [migrating][migr] from gitolite
+      * [migrate][migr] from gitosis
 
 Finally, [tips][] has a lot of useful information.
 

doc/install.mkd

@@ -150,13 +150,13 @@ On your *workstation*:
 ### #upgrade upgrading
 
 Upgrading is easy; you just re-run some of the same commands used for install.
-These commands are clearly noted in the install instructions below.
+These commands are clearly noted in the install instructions above.
 
 However, if you've added any new hooks, you must also run the next step (the
 `gl-setup` command), although this time you don't need to supply a pubkey
 filename as an argument.
 
-## #insttrouble if you run into trouble...
+## #insttrouble install trouble?
 
 If you run into trouble, please read the following sections.
 
@@ -248,10 +248,10 @@ don't know ssh it'll be a nightmare to support you.
   * any Unix system with a posix compatible "sh".
       * people using "csh" or derivatives please don't ask me for help -- tell
         your admin csh is not posix compatible
-  * git version 1.6.6 or greater
+  * git version 1.6.6 or later
       * can be in a non-PATH location if you are unable to install it
         normally; see the `$GIT_PATH` variable in the "rc" file
-  * perl (but since git requires it anyway, you probably have it)
+  * perl 5.8 or later
   * openssh or any ssh that can understand the `authorized_keys` file format
     (probably optional if you're using the http backend)
   * a Unix userid to be the hosting user, usually "git" but it can be any
@@ -332,74 +332,81 @@ Good luck.
 ### #clean appendix b: cleaning out a botched install
 
 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
+of things manually on the server.  Or sometimes they'll upgrade from one
-here's how to clean the slate.
+install method to another without checking some things over properly.  Or
+they'll follow instructions meant for a much newer version of gitolite and
+make a royal mess of the whole thing.
+
+Here's how to clean up, without losing your actual repositories.
+
+All this is on the server.  Note that the instructions are so long because
+they're generic enough to fit any situation.
+
+  * Clean out the existing install
 
-  * client-side
-      * edit `~/.ssh/config` and delete the paragraph starting with `host
-        gitolite`, if present.
-      * remove `~/gitolite-admin`
-  * server-side
       * edit `~/.ssh/authorized_keys` and delete all lines between `# gitolite
         start` and `# gitolite end` inclusive.
-      * remove `~/.gitolite`, `~/.gitolite.rc` and
-        `~/repositories/gitolite-admin.git`
-      * depending on which install method you used, you may also need to clean
-        out all gitolite files from `/usr/local/bin` or `$HOME/bin`, and then
-        delete `/var/gitolite/conf` and `/var/gitolite/hooks` or
-        `$HOME/share/gitolite/conf` and `$HOME/share/gitolite/hooks`
 
-### F=uninstall_ appendix c: uninstalling gitolite completely
+      * look in `~/.gitolite.rc` for 2 variables starting with `GL_PACKAGE_`.
+        If they are defined (and not just commented out), you need to clean
+        out all gitolite related files and directories from those two paths.
 
-(There's some duplication between this and the previous section).
+        Just for reference, the defaults for a non-root install are 'conf' and
+        'hooks' in `$HOME/share/gitolite`, while for an RPM/DEB or root
+        install they should be in `/var/gitolite/` or some such.
 
-Uninstalling gitolite is fairly easy, although it is manual.  (We'll assume
+        If those variables don't exist or are commented out, ignore this step.
-`$REPO_BASE` in the rc file was left at its default of `~/repositories`; if
-not, adjust accordingly):
 
-**server side tasks**
+      * look in `$PATH` for any gitolite programs and delete them also.  A
+        good way to hunt them down is `which gl-auth-command`, and in the path
+        you find, delete all "gl-*" programs (perhaps after checking the list,
+        if the path you find happens to be /usr/bin or such!!)
 
-  * edit `~/.ssh/authorized_keys` and delete the `# gitolite start` and `#
+        Repeat this step until there are no more.  I know of people who mixed
-    gitolite end` markers and all the lines between them.  This will prevent
+        different install methods and had two, or even three, versions lying
-    any of your users from attempting a push while you are doing this.
+        around.
 
-    If you are the only user, and/or *need* one or more of those keys to
+      * make some temp directory (say "old"), and **move** the following
-    continue to access this account (like if one of them is your laptop or
+        files/directories into it: `~/.gitolite`, `~/.gitolite.rc` and
-    your home desktop etc.) then instead of deleting the line you can just
+        `~/repositories/gitolite-admin.git`.  If there's nothing you need to
-    delete everything upto but not including the words "ssh-rsa" or "ssh-dss".
+        salvage from them you can delete them too.
 
-  * Now remove (or move aside or rename to something else if you're paranoid)
+      * if you used an RPM/DEB install, remove the package also.
-    the following files and directories.
 
-        ~/.gitolite
+  * Now install a fresh copy of gitolite using whatever method you prefer.
-        ~/.gitolite.rc
+    (If you used a different method earlier and did not clean things out
-        ~/repositories/gitolite-admin.git
+    properly per the instructions given above, expect trouble).
 
-  * You can remove all of `~/repositories` if you have not really started
+  * You now have a brand new "rc" file.  If your old rc file had any
-    using gitolite properly yet; that's your choice.
+    non-default settings you should **manually** pull them in to the new one.
+    However, **do NOT** change the two variables starting with `GL_PACKAGE_`
+    in the new rc file; even if the old one had something different leave them
+    alone.
 
-    If you *do* need to preserve the other repos and continue to use them,
+  * You also have a brand new gitolite-admin repo.  Clone this to your
-    remove all the `update` hooks that git installs on each repository.  The
+    workstation, then use the saved copy of the old admin repo to salvage
-    easiest way is:
+    whatever you need (entire revision history, or just the conf/key files,
+    whatever floats your boat).
+
+    Once you've got your admin repo looking how you want it, including 'repo'
+    statements for all your existing repos, just add/commit/push it.
+
+  * Go back to the server and run `gl-setup` once again (no arguments needed).
+
+That should do it.
+
+### #uninstall_ appendix c: uninstalling gitolite completely
+
+To uninstall gitolite completely, first follow the "clean out..." steps in the
+previous section.
+
+If you have not really started using gitolite properly yet, you can remove all
+of `~/repositories` also and be done.
+
+But if you *do* need to preserve the other repos and wish to continue to use
+them, remove all the `update` hooks that gitolite installs in 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.
-
-**client side tasks**
-
-  * Any remote users that still have access must update their clone's 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 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 *nay* 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

doc/ssh-troubleshooting.mkd

@@ -94,15 +94,15 @@ you there again.  Especially the first bullet.
 Done?  OK, read on...
 
 The following problem(s) indicate that pubkey access is not working at all, so
-you should start with appendix 1.  If that doesn't fix the problem, continue
+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
     you for a password.
 
 The following problem(s) indicate that your pubkey is bypassing gitolite and
-going straight to a shell.  You should start with appendix 2 and continue with
+going straight to a shell.  You should start with [appendix 2][stsapp2_] and continue with
-the rest in sequence.  Appendix 5 has some background info.
+the rest in sequence.  [Appendix 5][stsapp5_] has some background info.
 
   * running `ssh git@server info` gets you the output of the GNU 'info'
     command instead of gitolite's version and access info.
@@ -136,16 +136,16 @@ Done?  OK, now the general outline for ssh troubleshooting is this:
   * 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.
+    password, see [appendix 1][stsapp1_].
 
   * 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.
+    has what access.  See [appendix 2][stsapp2_].
 
   * 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 and 4.
+    client, instead of the default key.  See [appendix 3][stsapp3_] and [appendix 4][sshhostaliases].
 
 ## random tips, tricks, and notes
 
@@ -220,7 +220,7 @@ putty/plink, including environment variables, etc., and then try again.
 
 Thankfully, someone contributed [contrib/putty.mkd][contrib_putty].
 
-## appendix 1: ssh daemon asks for a password
+## #stsapp1_ appendix 1: ssh daemon asks for a password
 
 >   **NOTE**: This section should be useful to anyone trying to get
 >   password-less access working.  It is not necessarily specific to gitolite,
@@ -288,7 +288,7 @@ This is a quick checklist:
     this file for messages matching the approximate time of your last attempt
     to login, to see if they tell you what is the problem.
 
-## appendix 2: which key is which -- running sshkeys-lint
+## #stsapp2_ appendix 2: which key is which -- running sshkeys-lint
 
 Follow these steps on the client:
 
@@ -339,7 +339,7 @@ as YourName.pub, then run `gl-setup YourName.pub` on the server.  Remember to
 adjust your agent identities using ssh-add -D and ssh-add if you're using
 ssh-agent, otherwise these new keys may not work.
 
-## appendix 3: ssh client may not be offering the right key
+## #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
     verbose mode and look for the word "Offering", like so:
@@ -348,7 +348,7 @@ ssh-agent, otherwise these new keys may not work.
 
     If some keys *are* being offered, but not the key that was supposed to be
     used, you may be using ssh-agent (next bullet).  You may also need to
-    create some host aliases in `~/.ssh/config` (appendix 4).
+    create some host aliases in `~/.ssh/config` ([appendix 4][sshhostaliases]).
 
   * (ssh-agent issues) If `ssh-add -l` responds with either "The agent has no
     identities." or "Could not open a connection to your authentication
@@ -397,7 +397,7 @@ way to do this, as far as I know.
 
 [tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial
 
-## appendix 5: why bypassing gitolite causes a problem
+## #stsapp5_ appendix 5: why bypassing gitolite causes a problem
 
 When you bypass gitolite, you end up running your normal shell instead of the
 special gitolite entry point script `gl-auth-command`.

doc/support.mkd

@@ -8,14 +8,17 @@ issues.  I often don't bother responding for silly issues that are already in
 the docs.  Seriously, folks, troubleshooting involves reading; do I really
 need to *say* that?
 
-  * For install/setup issues see the [if you run into trouble][insttrouble]
+  * Lost your admin key?  Try [gl-admin-push][adminpush].
-    section of the [install][] document.
 
-    In particular, that section has two links for ssh issues.  I've yet to see
+  * For install/setup issues see the [install trouble?][insttrouble] section
-    a problem that is not already covered by those.
+    of the [install][] document.
 
-  * For usage issues after install, check out the [suggested reading
+    In particular, that section has two links for ssh issues.  **I've yet to
-    list][rtfm] and the [other docs][other_docs] section.
+    see an ssh problem that is not already covered by those** (but please tell
+    me if you find one!)
+
+  * The [suggested reading list][rtfm] section is a quick overview of the
+    documentation.
 
   * If you still can't find what you need, try the [**master index/table of
     contents**](http://sitaramc.github.com/gitolite/master-toc.html) and use

doc/tips-notes.mkd

@@ -259,8 +259,12 @@ will work for all the repos managed by gitolite, **except** for the special
 is also a `post-update` hook that runs here, and this needs additional
 information which is NOT available if you bypass gitolite.
 
-Use the `gl-admin-push` program to make changes to the admin repo directly on
+(Note: If your gitolite is too old to have the `gl-admin-push` program, try
-the server.  Here's how:
+`gl-dont-panic`; run it without arguments for usage info.  If you don't even
+have that, it may be best to [clean][] things out more thoroughly!)
+
+Use the `gl-admin-push` program to make changes to the admin repo *directly on
+the server*.  Here's how:
 
   * clone the repo to some safe location and cd to it:
 
@@ -274,9 +278,7 @@ the server.  Here's how:
     fix up some config problem that may have lost you your access.
 
   * when done, instead of `git push <push arguments>`, use this program
-    instead, like so:
+    instead.  For example, instead of `git push -f`, use `gl-admin-push -f`.
-
-        gl-admin-push <push arguments>
 
 Note that this method will work for *any* repo, not just the special admin
 repo.