accumulated docfixes...

- non-core documentation reduced to be easier to maintain
  - much reduced progit section submitted to scott chacon, necessitating
    some changes to this copy
  - other minor stuff
  - the "idiot-proof setup" :)

(plus get rid of that silly "dot.pl"; it's not needed any more, if it
ever was!)

doc/dev-notes.mkd

@@ -55,6 +55,10 @@ In addition, you can also look at the comments in src/lib/Gitolite/Easy.pm
 ...is implemented by Gitolite::Easy; the comments in src/lib/Gitolite/Easy.pm
 serve as documentation.
 
+Note that some of the perl functions called by Easy.pm will change the current
+directory to something else, without saving and restoring the directory.
+Patches (to Easy.pm *only*) welcome.
+
 ## writing your own...
 
 ### ...commands

doc/ips.mkd

@@ -0,0 +1,104 @@
+## idiot-proof setup for gitolite
+
+WARNING 1: this document uses my new, Linus-inspired, motto: people who get
+offended, *should* be offended.
+
+WARNING 2: contains more words in ALL CAPS than all my other documents put
+together.
+
+WARNING 3: this document will work for any Linux on which git has already been
+installed.  BSDs, or legacy systems like Solaris, also should work but I can't
+guarantee it or test it.
+
+----
+
+Some people seem to get terribly, **terribly** confused by ssh.  If you've
+read through all the [documentation on ssh][ssh] that came with gitolite, yet
+you *still* cannot get things to work, you have two choices:
+
+1.  exchange your "developer" badge for a "manager" badge and then hire
+    someone to do this.
+
+2.  start over with the instructions below.  They include some DRASTIC
+    measures, requirements, and restrictions, almost NONE of which are
+    normally necessary, but it's either that or a suit and tie from tomorrow
+    so play along.
+
+**IMPORTANT**: Do NOT ask for help on these instructions unless you have kept
+a detailed log of every command you typed, and the complete response you got.
+I do not ask for this information to help you -- that's only a front.  I
+*know* these instructions work (at least on any Linux that already has git
+installed), so the real reason is to find where you mistyped something and
+mock you for that,
+
+### Assumptions
+
+  * your name is Ron.  Substitute accordingly in the instructions below.
+
+  * you have a workstation.
+
+  * you have a server called `server`.
+
+  * you have root access on this server.
+
+### Tasks
+
+1.  Create a new userid on the server, say `git`.  This will be the **hosting
+    user**.  ("hosting user" means when you're done installing, your users
+    will use URLs like `git@server:reponame` or `ssh://git@server/reponame`).
+
+    **Make sure this is a NEW userid**.
+
+    If the name you want already exists, then:
+
+      * log in as root
+      * if you have any data on that user's HOME directory save it somewhere
+        else
+      * delete the userid
+      * obliterate the home directory of the user (since on most systems
+        merely deleting the user does not remove the home directory).
+      * re-create the userid again
+
+2.  If you don't already have one, make yourself an ssh keypair **on your
+    workstation**.
+
+    Do NOT, in a fit of inspiration and energy, add this public key to the
+    authorised keys file on the newly created hosting user!
+
+    Your ONLY access to the new (`git`) userid should be by logging onto the
+    server as root, then running `su - git`.
+
+3.  Now copy the pubkey from your workstation (`~/.ssh/id_rsa.pub`) to the
+    server as `/tmp/ron.pub`.  (Your name is Ron, remember?)
+
+4.  Log on to the server as root.
+
+5.  Switch to the `git` user:
+
+        su - git
+
+6.  Clone the gitolite source code
+
+        git clone git://github.com/sitaramc/gitolite
+
+7.  Install it
+
+        cd $HOME
+        mkdir -p bin
+        gitolite/install -to $HOME/bin
+
+8.  Set it up
+
+        cd $HOME
+        $HOME/bin/gitolite setup -pk /tmp/ron.pub
+
+9.  Now go to your workstation and type in
+
+        git ls-remote git@server:gitolite-admin
+
+    This should return something like
+
+        9dd8aab60bac5e54ccf887a87b4f3d35c96b05e4    HEAD
+        9dd8aab60bac5e54ccf887a87b4f3d35c96b05e4    refs/heads/master
+
+    (do I have to mention that your SHAs will be different?)

doc/master-toc.mkd

@@ -2,7 +2,7 @@
 
 ## [Introduction][index]
 
-  * (for [current][g2] gitolite (v2) users)
+  * (for [older][g2] gitolite (v1 or v2) users)
   * [quick links][ql]
   * [what][] is gitolite
   * [why][] might you need it

doc/non-core.mkd

@@ -15,16 +15,17 @@ remote user running `ssh git@host help`.
 All the commands that ship with gitolite will respond to `-h`; please report a
 bug to me if they don't.
 
-Here's a list of remote commands that are shipped:
+A particularly interesting command is the 'sudo' command, which allows an
+admin to run any remote command as some other user (though not the other way
+round!)
 
-  * 'desc' -- get/set the 'description' file for a repo
-  * 'fork' -- fork a repo
-  * 'info' -- already documented [here][info]
+Here's a list of some commands where additional information is available
+elsewhere:
+
+  * 'info' -- documented [here][info]
   * 'mirror' -- documented [here][sync]
   * 'perms' -- get/set the gl-perms file; see [perms][] for more
   * 'sskm' -- self-service key management, see [sskm][] for more
-  * 'writable' -- disabling pushes to take backups etc
-  * 'D' -- deleting user-created repos
 
 ## syntactic sugar
 
@@ -45,56 +46,31 @@ The following "sugar" programs are available:
 
 ## triggers
 
-Note that some features need to be enabled in more than one trigger.
-Mirroring is probably the best example -- it needs to hook into the `INPUT`,
-`PRE_GIT`, and the `POST_GIT` triggers to work.
+Most triggers need to be enabled by adding or uncommenting an appropriate line
+in the [rc][] file.  There are enough examples in there for the syntax to not
+need explanation.
 
-The `INPUT` triggers are:
+Some features need to be enabled in more than one trigger.  Mirroring is
+probably the best example -- it needs to hook into the `INPUT`, `PRE_GIT`, and
+the `POST_GIT` triggers to work.
+
+In general, the source code for each trigger will tell you what it is doing
+and which trigger list you should add it to.  Please note that there are two
+types of [triggers][]; the perl triggers usually have subroutine names that
+reflect what trigger sections they should go into.  (Using mirroring as an
+example again, the Mirroring.pm perl module has sub's named 'input',
+'pre\_git', and 'post\_git').
+
+Please report a bug to me if you could not find the information you wanted on
+any specific trigger.
+
+Here's a list of some triggers where additional information is available
+elsewhere:
 
-  * CpuTime -- see the `POST_GIT` section below
   * Shell -- see "giving shell access to gitolite users" in [this][sts] page.
-  * Alias -- documentation is within the source file Alias.pm
-  * Mirroring -- see [doc/mirroring.mkd][mirroring]
-
-The `PRE_GIT` triggers are:
-
-  * renice -- this renices the entire job to whatever value you specify.
   * Mirroring -- see [doc/mirroring.mkd][mirroring]
   * partial-copy -- this has its own section later in this page.
 
-The `POST_GIT` triggers are:
-
-  * Mirroring -- see [doc/mirroring.mkd][mirroring]
-  * CpuTime -- this is only a sample because it only prints the CPU times
-    data.  In reality you will want to do something else with it.
-
-The `POST_COMPILE` triggers are:
-
-  * post-compile/ssh-authkeys -- takes the pubkeys in keydir and populates
-    `~/.ssh/authorized_keys`.
-
-  * post-compile/update-git-configs -- updates individual 'repo.git/config'
-    files (using the 'git config ...' command) from settings supplied in the
-    conf file.  All sections except 'gitolite-options' are processed.  (The
-    'gitolite-options' section is considered internal to gitolite).
-
-  * post-compile/update-git-daemon-access-list -- create/delete
-    'git-daemon-export-ok' files in each repo based on whether the conf says
-    'daemon' can read the repo or not.
-
-  * post-compile/update-gitweb-access-list -- populates the file named in
-    `GITWEB_PROJECTS_LIST` in the rc file (default: `$HOME/projects.list`)
-    with the list of repos that gitweb is allowed to access.  This could be
-    more than just "R = gitweb"; any repo that has any config setting with the
-    section name 'gitweb' (like 'gitweb.owner', 'gitweb.description', etc) is
-    considered readable by gitweb, so the final list is a union of these two
-    methods.
-
-The `POST_CREATE` triggers are:
-
-  * The last 3 in the `POST_COMPILE` list also run from `POST_CREATE`, for
-    obvious reasons.
-
 ## VREFs
 
 VREFs have their [own page][vref].

doc/progit.mkd

@@ -1,9 +1,7 @@
-# (master copy of progit chapter on gitolite)
+# (expanded version of the gitolite chapter in the progit book)
 
 ## Gitolite ##
 
-Note: the latest copy of this section of the ProGit book is always available within the [gitolite documentation][progit].  The author would also like to humbly state that, while this section is accurate, and *can* (and often *has*) been used to install gitolite without reading any other documentation, it is of necessity not complete, and cannot completely replace the enormous amount of documentation that gitolite comes with.
-
 [Update 2012-04-10]: This page has been completely rewritten for gitolite version 3, informally called "g3".  G3 is a *total* rewrite of gitolite to push a lot more features away from "core", give the core a bunch of extension mechanisms, and finally have much better shell and perl APIs to bring all this together.
 
 Git has become very popular in corporate environments, which tend to have some additional requirements in terms of access control.  Gitolite was originally created to help with those requirements, but it turns out that it's equally useful in the open source world: the Fedora Project controls access to their package management repositories (over 10,000 of them!) using gitolite, and this is probably the largest gitolite installation anywhere too.  KDE, and kernel.org, are other very high-profile users of gitolite.

doc/repos.mkd

@@ -5,10 +5,10 @@ repos into gitolite control, click [here][existing].
 
 >   ----
 
->   *WARNING: Do NOT add new repos directly on the server.  Clone the
->   'gitolite-admin' repo to your workstation, make changes to it, then add,
->   commit, and push.  When the push hits the server, the server "acts" upon
->   your changes.*
+>   *WARNING: Do NOT add new repos or users manually on the server.  Gitolite
+>   users, repos, and access rules are maintained by making changes to a
+>   special repo called 'gitolite-admin' and pushing those changes to the
+>   server.*
 
 >   ----
 

doc/users.mkd

@@ -6,10 +6,10 @@ authentication, so here's some info on adding and removing users.
 
 >   ----
 
->   *WARNING: Do NOT add users directly on the server.  Clone the
->   'gitolite-admin' repo to your workstation, make changes to it, then add,
->   commit, and push.  When the push hits the server, the server "acts" upon
->   your changes.*
+>   *WARNING: Do NOT add new repos or users manually on the server.  Gitolite
+>   users, repos, and access rules are maintained by making changes to a
+>   special repo called 'gitolite-admin' and pushing those changes to the
+>   server.*
 
 >   ----
 

doc/vref.mkd

@@ -181,7 +181,8 @@ first rule, it might pass back (to gitolite) a virtual ref saying
 ### #NAME restricting pushes by dir/file name
 
 The "NAME" VREF allows you to restrict pushes by the names of dirs and files
-changed.
+changed.  (Side note: the NAME VREF is the only one directly implemented
+within the update hook, so you won't find it in the VREF directory).
 
 Here's an example.  Say you don't want junior developers pushing changes to
 the Makefile, because it's quite complex:

dot.pl

@@ -1,31 +0,0 @@
-#!/usr/bin/perl
-use strict;
-use warnings;
-
-my @a = `grep -r use.Gitolite . | grep -i '^./gitolite'`;
-
-# chomp(@a);
-open( my $fh, "|-", "tee module-tree.gv | dot -Tpng | tee module-tree.png | display" );
-
-@a = map {
-    print $fh "#$_";
-    s/^\.\/gitolite\///i;
-    s/-/_/g;
-    s/\.\///;
-    s/\//_/g;
-    s/\.pm:/ -> /;
-    s/use Gitolite:://;
-    s/::/_/g;
-    s/:/ -> /;
-    s/;//;
-    s/^(\S+) -> \1$//;
-    s/.* -> Rc//;
-    s/.* -> Common//;
-    $_;
-} @a;
-
-# open(my $fh, "|-", "cat > /tmp/junkg3");
-print $fh "digraph G {\n";
-print $fh $_ for @a;
-print $fh "}\n";
-close $fh;