almost all src/conf: logging totally redone, upgrade doc added

- logs go into $GL_ADMINDIR/logs by default, named by year-month
  - logfile name template (including dir prefix) now in $GL_LOGT
  - two new env vars passed down: GL_TS and GL_LOG (timestamp, logfilename)
  - log messages timestamps more compact, fields tab-delimited
  - old and new SHAs cut to 14 characters

README.mkd

@@ -1,5 +1,10 @@
 # gitolite
 
+>   [IMPORTANT: There is now an "upgrade" document in the "doc" directory;
+>   please read if upgrading gitolite]
+
+----
+
 Gitolite is the bare essentials of gitosis, with a completely different
 config file that allows (at last!) access control down to the branch level,
 including specifying who can and cannot *rewind* a given branch.  It is

conf/example.gitolite.rc

@@ -1,4 +1,4 @@
-# default paths for gitolite
+# paths and configuration variables for gitolite
 
 # please read comments before editing
 
@@ -23,10 +23,27 @@ $REPO_BASE="repositories";
 # path (i.e., starting with a "/" character)
 
 # gitolite admin directory, files, etc
+
 $GL_ADMINDIR=$ENV{HOME} . "/.gitolite";
 
 # --------------------------------------
 
+# templates for location of the log files and format of their names
+
+# I prefer this template (note the %y and %m placeholders)
+# it produces files like `~/.gitolite/logs/gitolite-2009-09.log`
+
+$GL_LOGT="$GL_ADMINDIR/logs/gitolite-%y-%m.log";
+
+# other choices are below, or you can make your own -- but PLEASE MAKE SURE
+# the directory exists and is writable; gitolite won't do that for you (unless
+# it is the default, which is "$GL_ADMINDIR/logs")
+
+# $GL_LOGT="$GL_ADMINDIR/logs/gitolite-%y-%m-%d.log";
+# $GL_LOGT="$GL_ADMINDIR/logs/gitolite-%y.log";
+
+# --------------------------------------
+
 # I see even less reason to change these, since they're all relative to the
 # gitolite admin directory above, but hey it's *your* system...
 
@@ -35,15 +52,24 @@ $GL_KEYDIR="$GL_ADMINDIR/keydir";
 $GL_CONF_COMPILED="$GL_ADMINDIR/conf/gitolite.conf-compiled.pm";
 
 # --------------------------------------
+
 # personal branch prefix; leave it as is (empty) if you don't want to use the
 # feature (see the "developer-specific branches" section in the "faq, tips,
 # etc" document)
+
 $PERSONAL="";
+
 # uncomment one of these if you do want it.  I recommend this:
 # $PERSONAL="refs/personal";
+
 # but if you want something more visible/noisy, use this:
 # $PERSONAL="refs/heads/personal";
 
+# NOTE: whatever value you choose, for security reasons it is better to make
+# it fully qualified -- that is, starting with "refs/"
+
 # --------------------------------------
 # per perl rules, this should be the last line in such a file:
 1;
+
+# vim: set syn=perl:

doc/0-UPGRADE.mkd

@@ -0,0 +1,52 @@
+# upgrading gitolite atomically
+
+### general upgrade notes
+
+If you follow the steps below, you can make the upgrade "atomic", so you don't
+have to do it at a "quiet" time or something.
+
+1.  untar the new version to some temp directory and `cd` to it
+
+2.  *prepare* the new version of `~/.gitolite.rc`.  It **must** have **all**
+    the variables defined in `conf/example.gitolite.rc` (the "new" rc file),
+    because the new versions of the programs will be depending on seeing these
+    variables.
+
+    However, it must also retain any customisations you made to the **old**
+    variables.
+
+    So this is what you do:
+
+      * make a copy of `conf/example.gitolite.rc` as `~/glrc.new`
+      * if your current `~/.gitolite.rc` had any customisations (where you
+        changed the defaults in some way), edit `~/glrc.new` and make those
+        same changes there
+
+3.  upgrade the rc file first
+
+        cp ~/glrc.new ~/.gitolite.rc
+
+4.  upgrade the software
+
+        src/install.pl
+
+And you're done.
+
+### upgrade notes for specific versions
+
+If any extra steps beyond the generic ones above are needed, they will be
+listed here, newest first.
+
+#### upgrading from abb4580
+
+Two new features (personal branches, and customisable logfile names/locations)
+have been added between abb4580 and this version.
+
+  * if you want to enable the personal branches feature, choose one of the
+    alternative values given for `$PERSONAL` or change it to something you
+    like; by default it is empty, which disables the feature
+
+  * if you want the log files named or grouped differently, choose one of the
+    alternative values for `$GL_LOGT`.  **Note** that if you choose to put
+    them in some other directory than the default, you **must** create that
+    directory (`mkdir`) yourself; gitolite will not do that for you

src/gl-auth-command

@@ -23,9 +23,8 @@ use warnings;
 #       common definitions
 # ----------------------------------------------------------------------------
 
-our $GL_ADMINDIR;
-our $GL_CONF_COMPILED;
-our $REPO_BASE;
+
+our ($GL_LOGT, $GL_CONF_COMPILED, $REPO_BASE);
 our %repos;
 
 my $glrc = $ENV{HOME} . "/.gitolite.rc";
@@ -89,18 +88,36 @@ die "$perm access for $repo denied to $user"
         or $repos{$repo}{$perm}{'@all'};
 
 # ----------------------------------------------------------------------------
-#       over to git now
+#       logging, timestamp.  also setup env vars for later
 # ----------------------------------------------------------------------------
 
-# ( but first save the reponame; we can save some time later in the hook )
+# reponame
 $ENV{GL_REPO}=$repo;
 
+# timestamp
+my ($s, $min, $h, $d, $m, $y) = (localtime)[0..5];
+$y += 1900; $m++;               # usual adjustments
+for ($s, $min, $h, $d, $m) {
+    $_ = "0$_" if $_ < 10;
+}
+$ENV{GL_TS} = "$y-$m-$d.$h:$min:$s";
+
+# substitute template parameters and set the logfile name 
+$GL_LOGT =~ s/%y/$y/g;
+$GL_LOGT =~ s/%m/$m/g;
+$GL_LOGT =~ s/%d/$d/g;
+$ENV{GL_LOG} = $GL_LOGT;
+
 # if log failure isn't important enough to block access, get rid of all the
 # error checking
-open my $log_fh, ">>", "$GL_ADMINDIR/log"
+open my $log_fh, ">>", $ENV{GL_LOG}
     or die "open log failed: $!";
-print $log_fh "\n", scalar(localtime), " $ENV{SSH_ORIGINAL_COMMAND} $user\n";
+print $log_fh "$ENV{GL_TS}\t$ENV{SSH_ORIGINAL_COMMAND}\t$user\n";
 close $log_fh or die "close log failed: $!";
 
+# ----------------------------------------------------------------------------
+#       over to git now
+# ----------------------------------------------------------------------------
+
 $repo = "'$REPO_BASE/$repo.git'";
 exec("git", "shell", "-c", "$verb $repo");

src/gl-compile-conf

@@ -41,11 +41,7 @@ use Data::Dumper;
 #       common definitions
 # ----------------------------------------------------------------------------
 
-our $GL_ADMINDIR;
-our $GL_CONF;
-our $GL_KEYDIR;
-our $GL_CONF_COMPILED;
-our $REPO_BASE;
+our ($GL_ADMINDIR, $GL_CONF, $GL_KEYDIR, $GL_CONF_COMPILED, $REPO_BASE);
 
 my $glrc = $ENV{HOME} . "/.gitolite.rc";
 die "parse $glrc failed: " . ($! or $@) unless do $glrc;

src/install.pl

@@ -3,9 +3,7 @@
 use strict;
 use warnings;
 
-our $REPO_BASE;
-our $GL_ADMINDIR;
-our $GL_CONF;
+our ($REPO_BASE, $GL_ADMINDIR, $GL_CONF);
 
 # wrapper around mkdir; it's not an error if the directory exists, but it is
 # an error if it doesn't exist and we can't create it
@@ -31,10 +29,11 @@ unless (-f $glrc) {
 die "parse $glrc failed: " . ($! or $@) unless do $glrc;
 
 # mkdir $REPO_BASE, $GL_ADMINDIR if they don't already exist
-wrap_mkdir( $REPO_BASE =~ m(^/) ? $REPO_BASE : "$ENV{HOME}/$REPO_BASE" );
+my $repo_base_abs = ( $REPO_BASE =~ m(^/) ? $REPO_BASE : "$ENV{HOME}/$REPO_BASE" );
+wrap_mkdir($repo_base_abs);
 wrap_mkdir($GL_ADMINDIR);
 # mkdir $GL_ADMINDIR's subdirs
-for my $dir qw(conf doc keydir src) {
+for my $dir qw(conf doc keydir logs src) {
     wrap_mkdir("$GL_ADMINDIR/$dir");
 }
 
@@ -54,13 +53,9 @@ EOF
 
 # finally, any potential changes to src/update-hook.pl must be propagated to
 # all the repos' hook directories
-my $repo_base_abs = ( $REPO_BASE =~ m(^/) ? $REPO_BASE : "$ENV{HOME}/$REPO_BASE" );
-# err, no need to get all worked up if you can't CD there -- this may be the
-# very first run and it hasn't been created yet
-if (chdir("$repo_base_abs")) {
-    for my $repo (`find . -type d -name "*.git"`) {
-        chomp ($repo);
-        system("cp $GL_ADMINDIR/src/update-hook.pl $repo/hooks/update");
-        chmod 0755, "$repo/hooks/update";
-    }
+chdir("$repo_base_abs") or die "chdir $repo_base_abs failed: $!\n";
+for my $repo (`find . -type d -name "*.git"`) {
+    chomp ($repo);
+    system("cp $GL_ADMINDIR/src/update-hook.pl $repo/hooks/update");
+    chmod 0755, "$repo/hooks/update";
 }

src/update-hook.pl

@@ -25,9 +25,7 @@ use warnings;
 #       common definitions
 # ----------------------------------------------------------------------------
 
-our $GL_ADMINDIR;
-our $GL_CONF_COMPILED;
-our $PERSONAL;
+our ($GL_CONF_COMPILED, $PERSONAL);
 our %repos;
 
 my $glrc = $ENV{HOME} . "/.gitolite.rc";
@@ -70,9 +68,11 @@ for my $refex (@allowed_refs)
     {
         # if log failure isn't important enough to block pushes, get rid of
         # all the error checking
-        open my $log_fh, ">>", "$GL_ADMINDIR/log"
+        open my $log_fh, ">>", $ENV{GL_LOG}
             or die "open log failed: $!";
-        print $log_fh "$perm: $ENV{GL_USER} $ENV{GL_REPO} $ref $oldsha $newsha\n";
+        print $log_fh "$ENV{GL_TS}  $perm\t" .
+            substr($oldsha, 0, 14) . "\t" . substr($newsha, 0, 14) .
+            "\t$ENV{GL_REPO}\t$ref\t$ENV{GL_USER}\n";
         close $log_fh or die "close log failed: $!";
         exit 0;
     }