ACCESS_2 gets 2 more arguments, and gets called for each VREF

doc/triggers.mkd

@@ -1,5 +1,7 @@
 # gitolite triggers
 
+[[TOC]]
+
 ## intro and sample rc excerpt
 
 Gitolite fires off external commands at 7 different times.  The [rc][] file
@@ -95,17 +97,33 @@ description of when the trigger runs:
       * user
       * 'R' or 'W'
       * 'any'
-      * result: this is the result of the access() function.  If it contains
+      * result (see notes below)
-        the uppercase word "DENIED", the access was rejected.  Otherwise
-        result contains the refex that caused the access to succeed.
 
-  * `ACCESS_2` runs after the second access check, in the update hook.
+    'result' is the return value of the access() function.  If it contains the
-    Extra arguments:
+    uppercase word "DENIED", the access was rejected.  Otherwise it is the
+    refex that caused the access to succeed.
+
+    *Please note that if access is rejected, gitolite-shell will die as soon
+    as it returns from the trigger*.
+
+  * `ACCESS_2` runs after the second access check, which is invoked by the
+    update hook to check the ref.  Extra arguments:
       * repo
       * user
       * any of W, +, C, D, WM, +M, CM, DM
       * the ref being updated (e.g., 'refs/heads/master')
-      * result (see above)
+      * result
+      * old SHA
+      * new SHA
+
+    `ACCESS_2` also runs on each [VREF][vref] that gets checked.  In this case
+    the "ref" argument will start with "VREF/", and the last two arguments
+    won't be passed.
+
+    'result' is similar to `ACCESS_1`, except that it is the *update hook*
+    which dies as soon as access is rejected for the ref or any of the VREFs.
+    Control then returns to git, and then to gitolite-shell, so the `POST_GIT`
+    trigger *will* run.
 
   * `PRE_GIT` and `POST_GIT` run just before and after the git command.
     Extra arguments:
@@ -130,3 +148,10 @@ description of when the trigger runs:
     file, then all the 'git-config's, gitweb access, and daemon access.
 
     No extra arguments.
+
+## tips
+
+If you have code that latches onto more than one trigger, collecting data
+(such as for logging), then the outputs may be intermixed.  You can record the
+value of the environment variable `GL_TID` to tie together related entries.
+

doc/vref.mkd

@@ -118,7 +118,7 @@ exit.
       * Print the refex itself (plus an optional message), so that it matches
         the line which invoked it.
 
-### arguments passed to the vref code
+### #vref-args arguments passed to the vref code
 
   * Arguments **1, 2, 3**: the 'ref', 'oldsha', and 'newsha' that git passed
     to the update hook (see 'man githooks').

src/lib/Gitolite/Hooks/Update.pm

@@ -29,7 +29,7 @@ sub update {
     trace( 1, 'update', $ENV{GL_REPO}, $ENV{GL_USER}, $aa, @ARGV );
 
     my $ret = access( $ENV{GL_REPO}, $ENV{GL_USER}, $aa, $ref );
-    trigger( 'ACCESS_2', $ENV{GL_REPO}, $ENV{GL_USER}, $aa, $ref, $ret );
+    trigger( 'ACCESS_2', $ENV{GL_REPO}, $ENV{GL_USER}, $aa, $ref, $ret, $oldsha, $newsha );
     _die $ret if $ret =~ /DENIED/;
 
     check_vrefs( $ref, $oldsha, $newsha, $oldtree, $newtree, $aa );
@@ -88,6 +88,7 @@ sub check_vref {
 
     my $ret = access( $ENV{GL_REPO}, $ENV{GL_USER}, $aa, $ref );
     trace( 2, "access($ENV{GL_REPO}, $ENV{GL_USER}, $aa, $ref)", "-> $ret" );
+    trigger( 'ACCESS_2', $ENV{GL_REPO}, $ENV{GL_USER}, $aa, $ref, $ret );
     _die "$ret" . ( $deny_message ? "\n$deny_message" : '' )
       if $ret =~ /DENIED/ and $ret !~ /by fallthru/;
     trace( 2, "remember, fallthru is success here!" ) if $ret =~ /by fallthru/;