(accumulated docfixes) esp a large section on the INPUT trigger

doc/dev-notes.mkd

@@ -115,3 +115,51 @@ contents modified as you like and return a ref to it.
 
 There are a couple of examples in src/syntactic-sugar.
 
+## appendix 1: notes on the INPUT trigger
+
+Note: some of this won't make sense if you haven't read about [triggers][].
+
+The INPUT trigger sequence is designed to set or change environment variables
+or the argument list.  (Side note: this means INPUT triggers have to be
+written as perl modules; they cannot be standalone scripts).  This is a very
+powerful idea so an extended description may be useful.
+
+Sshd invokes gitolite-shell with the SSH\_ORIGINAL\_COMMAND env var containing
+the git/gitolite command and one argument: the gitolite username.
+
+  * see [this][glssh] for details on the latter
+  * the *first* thing gitolite does in smart http mode is to use the
+    REMOTE\_USER and the CGI variables that apache provides to *construct*
+    a fake argument list and a fake SSH\_ORIGINAL\_COMMAND env var, so the
+    rest of the code can stay the same
+
+The INPUT trigger is then run.  The purpose of the input trigger is to ensure
+that the first argument *is* the gitolite username, and that the
+SSH\_ORIGINAL\_COMMAND env var contains the actual command to execute.  It can
+also be used to set up any other environment variables that you may decide you
+need.
+
+Wait... didn't we say that's what gitolite-shell gets anyway, just now?
+
+Well, we lied a bit there; it's not always true!
+
+For example, if [this][giving-shell] feature is used, the first argument *may*
+be "-s", with the username in the *second* argument.  Shell.pm deals with
+that.  <font color="gray">(Order matters.  If you use this feature, put the
+`'Shell::input',` line ahead of the others, since it is the only one prepared
+to deal with username not being the first argument).</font>
+
+If you look at CpuTime.pm, you'll see that it's `input()` function doesn't set
+or change anything, but does set a package variable to record the start time.
+Later, when the same module's `post_git()` function is invoked, it uses this
+variable to determine elapsed time.
+
+*(This is a very nice and simple example of how you can implement features by
+latching onto multiple events and sharing data to do something)*.
+
+You can even change the reponame the user sees, behind his back.  Alias.pm
+handles that.
+
+Finally, as an exercise for the reader, consider how you would create a brand
+new env var that contains the *comment* field of the ssh pubkey that was used
+to gain access, using the information [here][kfn].

doc/extras/sts.mkd

@@ -153,7 +153,7 @@ Done?  OK, now the general outline for ssh troubleshooting is this:
 
 ## random tips, tricks, and notes
 
-### giving shell access to gitolite users
+### #giving-shell giving shell access to gitolite users
 
 Thanks to an idea from Jesse Keating, a single key can allow both gitolite
 access *and* shell access.
@@ -168,7 +168,9 @@ To do this:
 
         SHELL_USERS_LIST        =>  "$ENV{HOME}/.gitolite.shell-users",
 
-  * add the line `'Shell::input',` to the `INPUT` list in the rc file.
+  * add the line `'Shell::input',` to the `INPUT` list in the rc file.  This
+    must be the first item on the list (possibly preceded by CpuTime, if
+    you're using that).
 
   * add the line `'post-compile/ssh-authkeys-shell-users',` to the
     `POST_COMPILE` list, *after* the `'post-compile/ssh-authkeys',` line.
@@ -176,7 +178,7 @@ To do this:
 Then run `gitolite compile; gitolite trigger POST_COMPILE` or push a dummy
 change to the admin repo.
 
-### distinguishing one key from another
+### #kfn distinguishing one key from another
 
 Since a user can have [more than one key][multi-key], it is sometimes useful
 to distinguish one key from another.  Sshd does not tell you even the

doc/locking.mkd

@@ -12,7 +12,12 @@ this situation it should be possible to at least prevent commits from being
 pushed that contains changes to files locked by someone else.
 
 The two "lock" programs (one a command that a user uses, and one a VREF that
-the admin adds to a repo's access rules) together achieve this.
+the admin adds to a repo's access rules) together attempt to achieve this.
+
+Of course, locking by itself is not quite enough.  You may still get into
+merge situations if you make changes in branches.  For best results you should
+actually keep all the binary files in their own branch, separate from the ones
+containing source code.
 
 ----
 
@@ -50,6 +55,8 @@ Here's a summary:
 
 For best results, everyone on the team should:
 
+  * Switch to the branch containing the binary files when wanting to make a
+    change.
   * Run 'git pull' or eqvt, then lock the binary file(s) before editing them.
   * Finish the editing task as quickly as possible, then commit, push, and
     unlock the file(s) so others are not needlessly blocked.

doc/non-core.mkd

@@ -45,16 +45,28 @@ 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.
+
+The `INPUT` triggers are:
+
+  * 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:
 
-  * partial-copy -- this has its own section later in this page.
-
   * 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:
 
-  * CpuTime, which is only a sample because it only prints the CPU times data.
+  * Mirroring -- see [doc/mirroring.mkd][mirroring]
-    In reality you will want to do something else with it.
+  * 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:
 

doc/triggers.mkd

@@ -32,6 +32,27 @@ here's an excerpt:
 (As you can see, post-create runs 3 programs that also run from post-compile.
 This is perfectly fine, by the way)
 
+## types of trigger programs
+
+There are two types of trigger programs.  Standalone scripts are placed in
+src/triggers or its subdirectories.  They are invoked by being added to a
+trigger list (using the path after "src/triggers/", as you can see).  Such
+scripts are quick and easy to write in any language of your choice.
+
+Triggers written as perl modules are placed in src/lib/Gitolite/Triggers.
+They are invoked by being listed with the package+function name, although even
+here the 'Gitolite::Triggers' part is skipped.  Perl modules have to follow
+some conventions (see some of the shipped modules to ideas) but the advantage
+is that they can set environment variables and change the argument list of the
+gitolite-shell program that invokes them.
+
+If this does not make sense, please examine a default install of gitolite,
+paying attention to:
+
+  * the path names in various trigger lists in the rc file
+  * corresponding path names in the src/ directory in gitolite source
+  * and for perl modules, the package names and function names within.
+
 ## manually firing triggers
 
 ...from the server command line is easy.  For example:

src/lib/Gitolite/Rc.pm

@@ -291,6 +291,14 @@ __DATA__
 
 # (Tip: perl allows a comma after the last item in a list also!)
 
+# HELP for commands (see COMMANDS list below) can be had by running the
+# command with "-h" as the sole argument.
+
+# HELP for all the other external programs (the syntactic sugar helpers and
+# the various programs/functions in the 8 trigger lists), can be found in
+# doc/non-core.mkd (http://sitaramc.github.com/gitolite/non-core.html) or in
+# the corresponding source file itself.
+
 %RC = (
     # if you're using mirroring, you need a hostname.  This is *one* simple
     # word, not a full domain name.  See documentation if in doubt
@@ -344,15 +352,16 @@ __DATA__
     SYNTACTIC_SUGAR             =>
         [
             # 'continuation-lines',
+            # 'keysubdirs-as-groups',
         ],
 
     # comment out or uncomment as needed
     # these will run in sequence to modify the input (arguments and environment)
     INPUT                       =>
         [
-            # if you use this, make this the first item in the list
             # 'CpuTime::input',
-
+            # 'Shell::input',
+            # 'Alias::input',
             # 'Mirroring::input',
         ],
 
@@ -366,12 +375,8 @@ __DATA__
     # these will run in sequence just before the actual git command is invoked
     PRE_GIT                     =>
         [
-            # if you use this, make this the first item in the list
             # 'renice 10',
-
             # 'Mirroring::pre_git',
-
-            # see docs ("list of non-core programs shipped") for details
             # 'partial-copy',
         ],
 
@@ -386,8 +391,6 @@ __DATA__
     POST_GIT                    =>
         [
             # 'Mirroring::post_git',
-
-            # if you use this, make this the last item in the list
             # 'CpuTime::post_git',
         ],