gl-setup changes:

- learns to not run sshkeys-lint when told to be extra quiet
  - gets its own little doc section (appendix d)
  - get a quick help with '-h'

doc/install.mkd

@@ -52,8 +52,7 @@ On your *server*, as *root*:
     # (now as gitolite)
     gl-setup /tmp/YourName.pub
 
-Note: if you're running non-interactively (i.e., cannot tolerate an editor
+Note: please see appendix d for command line options for [gl-setup][].
-popping up), insert a "-q" before the argument to gl-setup.
 
 On your *workstation*:
 
@@ -94,8 +93,7 @@ similar files and add it somehow.  Then:
 
     gl-setup /tmp/YourName.pub
 
-Note: if you're running non-interactively (i.e., cannot tolerate an editor
+Note: please see appendix d for command line options for [gl-setup][].
-popping up), insert a "-q" before the argument to gl-setup.
 
 On your *workstation*:
 
@@ -161,8 +159,7 @@ On your *server*, as *root*:
     # (now as git)
     gl-setup /tmp/YourName.pub
 
-Note: if you're running non-interactively (i.e., cannot tolerate an editor
+Note: please see appendix d for command line options for [gl-setup][].
-popping up), insert a "-q" before the argument to gl-setup.
 
 On your *workstation*:
 
@@ -431,3 +428,28 @@ 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.
+
+### #gl-setup appendix d: command line options for gl-setup
+
+After gl-system-install (or the RPM/DEB) have installed the *code*, gl-setup
+sets up the actual gitolite instance.  (Gitolite in [pictures][] may help
+explain this better.)
+
+In ssh mode, gl-setup expects a pubkey filename the first time it is run, and
+will complain if you don't supply it.  On subsequent runs it is optional; you
+only need to supply it if you want to quickly and easily change the admin's
+(or indeed anyone's!) pubkey without going through all the steps that
+[gl-admin-push][adminpush] requires.
+
+In http mode, gl-setup expects an "admin name" the first time it is run.  On
+subsequent runs, arguments are ignored.
+
+gl-setup accepts the following command line options, which must appear
+*before* the pubkey filename/admin name:
+
+  * `-q` -- quiet mode; suppress the editor that pops up to allow you to
+    change the rc file the first time.  Meaningless/ignored on subseqent runs.
+  * `-q -q` -- extra quiet mode; suppress the editor as well as the
+    sshkeys-lint check at the end of the run.  Old-timers who know ssh so well
+    that they still use protocol 1 keys *must* use this mode, because
+    sshkeys-lint will barf on them.  Equivalent to `-q` in http mode.

src/gl-setup

@@ -18,16 +18,42 @@ GL_PACKAGE_CONF=/tmp/share/gitolite/conf
 # pubkey file if you happen to have lost all gitolite-access to the repos (but
 # do have shell access via some other means)
 
+# ----------------------------------------------------------------------
+#   local functions
+# ----------------------------------------------------------------------
+
 die() { echo "$@" >&2; exit 1; }
 
 get_rc_val() {
     `dirname $0`/gl-query-rc $1
 }
 
+# ----------------------------------------------------------------------
+#   tempdir setup
+# ----------------------------------------------------------------------
+
 TEMPDIR=`mktemp -d -t tmp.XXXXXXXXXX`
 export TEMPDIR
 trap "/bin/rm -rf $TEMPDIR" 0
 
+# ----------------------------------------------------------------------
+#   argument handling
+# ----------------------------------------------------------------------
+
+# save arguments for use in commit message later
+args="$*"
+
+if [ "$1" = "-h" ]
+then
+    echo Usage:
+    echo "  gl-setup [-q] [-q] [YourName.pub]       # ssh mode"
+    echo "  gl-setup [-q] [-q] [YourName]           # http mode"
+    echo
+    echo "Please see 'appendix d' in doc/install.mkd for more.  (Online at"
+    echo "  http://sitaramc.github.com/gitolite/install.html#gl-setup)"
+    exit 1
+fi
+
 # quiet mode; only used to suppress popping up an editor on a new rc file
 if [ "$1" = "-q" ]
 then
@@ -35,6 +61,17 @@ then
     quiet=1
 fi
 
+# extra quiet mode (second '-q'); suppress the lint check at the end
+if [ "$1" = "-q" ]
+then
+    shift
+    nolint=1
+fi
+
+# ----------------------------------------------------------------------
+#   get the admin_name and (usually) the pubkey file name
+# ----------------------------------------------------------------------
+
 if [ -n "$GITOLITE_HTTP_HOME" ]
 then
     HOME=$GITOLITE_HTTP_HOME
@@ -51,6 +88,10 @@ else
     fi
 fi
 
+# ----------------------------------------------------------------------
+#   report changes to rc file (for manual fixing) or setup a new rc file
+# ----------------------------------------------------------------------
+
 export GL_RC
 GL_RC=`get_rc_val GL_RC 2>/dev/null`
 [ -z "$GL_RC" ] && GL_RC=$HOME/.gitolite.rc
@@ -88,6 +129,10 @@ else
     fi
 fi
 
+# ----------------------------------------------------------------------
+#   setup ~/.ssh
+# ----------------------------------------------------------------------
+
 # setup ssh stuff.  We break our normal rule that we will not fiddle with
 # authkeys etc., because in this case it seems appropriate
 (
@@ -98,6 +143,10 @@ fi
     chmod go-w . .ssh .ssh/authorized_keys
 )
 
+# ----------------------------------------------------------------------
+#   setup gitolite's env vars
+# ----------------------------------------------------------------------
+
 export GL_BINDIR
 export REPO_BASE
 export GL_ADMINDIR
@@ -105,7 +154,9 @@ GL_BINDIR=`  get_rc_val GL_BINDIR  `
 REPO_BASE=`  get_rc_val REPO_BASE  `
 GL_ADMINDIR=`get_rc_val GL_ADMINDIR`
 
-# now we get to gitolite itself
+# ----------------------------------------------------------------------
+#   setup hooks, admindir, the admin repo
+# ----------------------------------------------------------------------
 
 gl-install -q
 
@@ -123,24 +174,30 @@ gl-install -q
 touch $HOME/.ssh/authorized_keys
 gl-compile-conf -q
 
-# setup push-to-admin
+# setup the admin repo
 [ -n "$pubkey_file" ] || [ -n "$GITOLITE_HTTP_HOME" ] && (
     cd $HOME; cd $REPO_BASE/gitolite-admin.git
     GIT_WORK_TREE=$GL_ADMINDIR; export GIT_WORK_TREE
     git add conf/gitolite.conf keydir
     git config --get user.email >/dev/null || git config user.email $USER@`hostname`
     git config --get user.name  >/dev/null || git config user.name  "$USER on `hostname`"
-    git diff --cached --quiet 2>/dev/null || git commit -am start
+    git diff --cached --quiet 2>/dev/null || git commit -am "gl-setup $args"
 )
 
 # now that the admin repo is created, you have to set the hooks properly; best
 # do it by running install again
 gl-install -q
 
-# ----
+# ----------------------------------------------------------------------
+#   lint check on ssh keys
+# ----------------------------------------------------------------------
 
+[ -z "$nolint" ] && {
     # the never-ending quest to help with bloody ssh issues...
     cd $GL_ADMINDIR/keydir
     [ -n "$pubkey_file" ] && $GL_BINDIR/sshkeys-lint -q -a $admin_name < $HOME/.ssh/authorized_keys
+}
+
+# ----------------------------------------------------------------------
 
 exit 0