a slew of adc changes; details below:

- get_rights_and_owner normalises its arg1 by stripping .git if
    supplied, then sets the variable "repo" to the result as a side
    effect
  - new "help" adc with some default text but main purpose is to allow
    site local help text
  - other adc's refer to 'help' adc when appropriate
  - 'undelete' renamed to 'restore'; that's what the KDE "trashcan"
    program calls that operation
  - minor typo in sample script in documentation
  - main adc doc points to contrib/adc/repo-deletion.README now

contrib/adc/adc.common-functions

@@ -26,9 +26,8 @@ opt() {
 
 valid_owned_repo() {
     # check that an arg passed is a valid repo and the current user owns it
-    repo=$1
     [ -z "$1" ] && die need a repo name
-    get_rights_and_owner $repo
+    get_rights_and_owner $1
     [ "$owner" = "$GL_USER" ] || die "$repo does not exist or is not yours!"
 
     # and we sneak this in too, quietly :)
@@ -37,9 +36,11 @@ valid_owned_repo() {
 
 die() { echo "$@"; exit 1; }
 
+# NOTE: this also sets $repo to the normalised (without .git suffix) reponame
 get_rights_and_owner() {
     local ans
-    ans=$(perl -I$GL_BINDIR -Mgitolite -e 'cli_repo_rights("'$1'")')
+    repo=${1%.git}
+    ans=$(perl -I$GL_BINDIR -Mgitolite -e 'cli_repo_rights("'$repo'")')
 
     # set shell variables as needed
     owner=${ans#* }

contrib/adc/fork

@@ -1,14 +1,12 @@
 #!/bin/sh
 
-from=$1
-to=$2
-
 . $(dirname $0)/adc.common-functions
 
-get_rights_and_owner $from
+# get_rights_and_owner now also sets $repo; see comments in common functions
+get_rights_and_owner $1; from=$repo
 [ -z "$perm_read" ] && die "no read permissions on $from"
 
-get_rights_and_owner $to
+get_rights_and_owner $2; to=$repo
 [ -z "$perm_create" ] && die "no create permissions on $to"
 
 # clone $from to $to

contrib/adc/help

@@ -0,0 +1,44 @@
+#!/bin/sh
+
+. $(dirname $0)/adc.common-functions
+
+# the local site can have a file called gl-adc-help.txt, which will be used as
+# the *entire* help text for this site...
+
+[ -f $HOME/gl-adc-help.txt ] && {
+    cat $HOME/gl-adc-help.txt
+    exit 0
+}
+
+# or the local site will use the default help text in this file, with an
+# optional pre- and post- text that is site local (like maybe the admin's
+# contact details)
+
+# pre
+[ -f $HOME/gl-adc-pre-help.txt ] && cat $HOME/gl-adc-pre-help.txt
+
+# default help text
+cat <<EOF
+
+The following adc's (admin-defined commands) are available at this site.
+
+creating a "fork" of a repo:
+    the 'fork' adc forks a repo that you have read access to, to a repo that
+    you have create rights to
+
+deleting/trashing repos:
+    You can permanently remove a repo using 'rm'.  By default, repos are
+    protected ('lock'ed) from being 'rm'-ed.  You have to first 'unlock' a
+    repo before you can 'rm' it.
+
+    A different scheme of handling this is to use 'trash' to move the repo to
+    a "trashcan" area.  You can then 'list-trash' to see what you have, and
+    you can then 'restore' whichever repo you need to bring back.
+
+    More details can be found at:
+    http://github.com/sitaramc/gitolite/blob/pu/contrib/adc/repo-deletion.README
+
+EOF
+
+# post
+[ -f $HOME/gl-adc-post-help.txt ] && cat $HOME/gl-adc-post-help.txt

contrib/adc/lock

@@ -9,4 +9,4 @@ valid_owned_repo $1
 
 rm -f $repo.git/gl-rm-ok
 
-echo "$repo has been locked"
+echo "$repo has been locked.  Please run the 'help' adc for more info."

contrib/adc/repo-deletion.README

@@ -24,7 +24,7 @@ Local settings for these ADCs can be found in the common settings file
 
 2.  'trash' will move the repo to a safe location.  There are settings for
     where this location is and what suffix is added to the repo name.  You can
-    'list-trash' to see what trash you have collected, and you can 'undelete'
+    'list-trash' to see what trash you have collected, and you can 'restore'
     one of the listed repos.
 
     It's easy to automatically clean out the trash occasionally.  By default,
@@ -42,7 +42,7 @@ Local settings for these ADCs can be found in the common settings file
         find $TRASH_CAN -type d -name "20??-??-??_*" | while read r
         do
             d=`basename $r`
-            [[ $d < $cutoff ]] && rm -rf $d
+            [[ $d < $cutoff ]] && rm -rf $r
         done
 
     Put this in cron to run once a day and that should be it.

contrib/adc/rm

@@ -18,7 +18,7 @@ opt $USE_LOCK_UNLOCK && {
     then
         :
     else
-        die "$repo is locked! To 'rm' this repository, first 'unlock' it."
+        die "$repo is locked! Please run the 'help' adc for more info."
     fi
 }
 

contrib/adc/rmrepo

@@ -1,4 +1,4 @@
 #!/bin/bash
 
-echo this command has been superceded by the \"rm\" and \"trash\" commands
+echo "this command no longer exists.  Please run the 'help' adc for more info."
 exit 1

contrib/adc/trash

@@ -9,7 +9,7 @@
 #   TRASH_SUFFIX -- a timestamp, (ideally and by default), to be
 #       suffixed to the moved repo
 
-# helper ADCs: list-trash, undelete
+# helper ADCs: list-trash, restore
 
 # NOTE: although I would NOT advise it in the interests of keeping things
 # simple, it *is* possible to have even deleted repos be *directly* accessible
@@ -26,4 +26,4 @@ valid_owned_repo $1
 mkdir -p $TRASH_CAN/$repo 2>/dev/null || die "failed creating directory in trashcan"
 [ -d $TRASH_CAN/$repo/$TRASH_SUFFIX ] && die try again in a few seconds
 mv $repo.git $TRASH_CAN/$repo/$TRASH_SUFFIX
-echo $repo moved to trashcan
+echo "$repo moved to trashcan.  Please run the 'help' adc for more info."

contrib/adc/unlock

@@ -9,4 +9,4 @@ valid_owned_repo $1
 
 touch $repo.git/gl-rm-ok
 
-echo "$repo has been unlocked and can be 'rm'ed or 'lock'ed once again"
+echo "$repo has been unlocked.  Please run the 'help' command for more info."

contrib/adc/who-pushed

@@ -7,11 +7,11 @@
 
 . $(dirname $0)/adc.common-functions
 
-repo=$1
 sha=$2
 [ -n "$sha" ] || die Usage: ssh ... who-pushed reponame SHA \# at least first few hex digits
 
-get_rights_and_owner $repo
+# get_rights_and_owner now also sets $repo; see comments in common functions
+get_rights_and_owner $1
 [ -z "$perm_read" ] && die "no read permissions on $repo"
 
 cd $GL_REPO_BASE_ABS/$repo.git

doc/admin-defined-commands.mkd

@@ -16,7 +16,7 @@ In this document:
   * <a href="#_anatomy_of_a_command">anatomy of a command</a>
   * <a href="#_example_uses_and_sample_commands_in_contrib">example uses and sample commands in contrib</a>
       * <a href="#_fork">fork</a>
-      * <a href="#_rmrepo">rmrepo</a>
+      * <a href="#_deleting_trashing_repos">deleting/trashing repos</a>
       * <a href="#_enable_disable_push_access_temporarily">enable/disable push access temporarily</a>
       * <a href="#_bonus_restricted_admin">(bonus) restricted admin</a>
 
@@ -164,17 +164,13 @@ or some such incantation.
 
 <a name="rmrepo"></a>
 
-<a name="_rmrepo"></a>
+<a name="_deleting_trashing_repos"></a>
 
-#### rmrepo
+#### deleting/trashing repos
 
-This is one thing that you really could not do before this setup was created.
+See [contrib/adc/repo-deletion.README][rdR] for details about this.
-Use it like this:
 
-    ssh git@server rmrepo reponame
+[rdR]: http://github.com/sitaramc/gitolite/blob/pu/contrib/adc/repo-deletion.README
-
-The script checks to make sure that the repo being deleted was *created* by
-the user invoking it.
 
 <a name="_enable_disable_push_access_temporarily"></a>