(doc) ADCs now have an overview doc, plus...

- repo-deletion is now a proper doc
  - other doc enhancements and clarifications

README.mkd

@@ -2,8 +2,13 @@
 
 <a name="start"></a>
 
-***IMPORTANT NOTE: v2.0rc1 is out; all development will be on that now.
+***IMPORTANT NOTE: There is a [master table of contents of all gitolite
-Please see new doc/developer-notes.mkd***
+documentation][docs] that can help if you're looking for stuff.  Just click
+the link and use your browser's search function (Ctrl-F, usually) to look for
+likely sounding words.  All documents are listed, as well as links to section
+headers in some of the longer documents***
+
+[docs]: http://sitaramc.github.com/gitolite
 
 ----
 
@@ -196,7 +201,6 @@ Gitolite is released under GPL v2.  See COPYING for details.
 [install]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html
 [admin]: http://sitaramc.github.com/gitolite/doc/2-admin.html
 [migr]: http://sitaramc.github.com/gitolite/doc/migrate.html
-[docs]: http://sitaramc.github.com/gitolite
 [doc9gas]: http://sitaramc.github.com/gitolite/doc/gitolite-and-ssh.html
 [doc6sts]: http://sitaramc.github.com/gitolite/doc/ssh-troubleshooting.html
 [who]: http://sitaramc.github.com/gitolite/doc/who-uses-it.html

contrib/adc/README.mkd

@@ -0,0 +1,63 @@
+# brief descriptions of the shipped ADCs (admin-defined commands)
+
+(...with pointers to further information where needed)
+
+----
+
+**able**: enable/disable push access temporarily (such as for taking backups
+or other admin chores); details [here][able].
+
+[able]: http://sitaramc.github.com/gitolite/doc/admin-defined-commands.html#_enable_disable_push_access_temporarily
+
+**delete-branch**: allow someone to delete a branch that they themselves
+created. (i.e., when the user had RWC, but not RWCD, permissions).  Details on
+this ADC are [here][dbsha]; details on RWC/RWD/RWCD etc are [here][rwcd].
+
+[dbsha]: https://github.com/sitaramc/gitolite/commit/89b68bf5ca99508caaa768c60ce910d7e0a29ccf
+[rwcd]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html#_creating_and_deleting_branches
+
+**fork**: Think of it as a server-side clone; details [here][fork].
+
+[fork]: http://sitaramc.github.com/gitolite/doc/admin-defined-commands.html#_fork
+
+**get-rights-and-owner.in-perl**:  Most of the ADCs are in shell, so this is a
+sample of how to write an ADC in perl.
+
+**gl-reflog**: show a fake "reflog" from the server, and allow recovery from
+deleted branches and bad force pushes; details in source.
+
+**help**: not all shipped ADCs may be enabled by the site admin.  Conversely
+the admin may create and install his own ADCs that dont ship with gitolite
+itself.  This ADC displays site-local help, if the site admin enabled it.
+
+**hub**: allow "pull requests" a la github; details [here][hub].
+
+[hub]: http://sitaramc.github.com/gitolite/contrib/adc/hub.html
+
+**rm**, **lock**, and **unlock**:<br>
+**trash**, **list-trash**, and **restore**:
+
+>   two families of repo deletion commands; details [here][rddoc]
+
+[rddoc]: http://sitaramc.github.com/gitolite/contrib/adc/repo-deletion.html
+
+**restrict-admin**: sample program to show how you can allow the admin to run
+pre-specified shell commands (without actually having full shell access).
+Details [here][ra].
+
+[ra]: http://sitaramc.github.com/gitolite/doc/admin-defined-commands.html#_bonus_restricted_admin
+
+**sudo**: allow admin to run ADCs on behalf of a user.  Useful in support
+situations I guess.  Details in source.
+
+Note: the Unix "sudo" and "su" programs are most often used to acquire
+*higher* privileges, although they're actually designed to go the other way
+also.  In gitolite we do not do the former, only the latter (i.e., a normal
+gitolite user cannot do admin-stuff using this ADC).
+
+**su-expand**, **su-getperms**, **su-setperms**: as above, but for the
+internal commands 'expand', 'getperms', and 'setperms'.  (These commands are
+not ADCs so you cannot simply use the 'sudo' ADC described above).
+
+**who-pushed**: find the last person to push a given commit; details in
+source.

contrib/adc/repo-deletion.mkd

@@ -1,6 +1,8 @@
 # deleting repos safely
 
-(see http://groups.google.com/group/gitolite/browse_thread/thread/fb9cf5a464b6dfee )
+(see [this thread][thr] on the gitolite mailing list)
+
+[thr]: http://groups.google.com/group/gitolite/browse_thread/thread/fb9cf5a464b6dfee
 
 By default, the old 'rmrepo' ADC (admin-defined command) just went and deleted
 the repo -- no questions asked!  Sometimes, that could be a disaster -- you
@@ -13,12 +15,13 @@ either, both, or neither family of commands.
 Local settings for these ADCs can be found in the common settings file
 "adc.common-functions".
 
-1.  'rm' will remove the repo.  If USE_LOCK_UNLOCK is set, rm will refuse to
+1.  'rm' will remove the repo.  If `USE_LOCK_UNLOCK` is set, rm will refuse to
     remove a locked repo.  All repos are locked by default, and you have to
     explicitly 'unlock' a repo to remove it.  You can also 'lock' it again
     instead of removing it of course.
 
-    There's also ARE_YOU_SURE, for situations where a simple warning suffices.
+    There's also `ARE_YOU_SURE`, for situations where a simple warning
+    suffices.
 
     You can also use both these flags if you wish.
 

doc/1-INSTALL.mkd

@@ -8,11 +8,11 @@ In this document:
           * <a href="#_client_workstation">client/workstation</a>
           * <a href="#_server">server</a>
           * <a href="#_technical_skills">technical skills</a>
+      * <a href="#_naming_conventions_used">naming conventions used</a>
   * <a href="#_getting_the_gitolite_software">getting the gitolite software</a>
       * <a href="#_getting_a_tar_file_from_a_clone">getting a tar file from a clone</a>
   * <a href="#_installation_and_setup">installation and setup</a>
       * <a href="#_install_methods_and_deciding_which_one_to_use">install methods and deciding which one to use</a>
-      * <a href="#_conventions_used">conventions used</a>
       * <a href="#_package_method_directly_on_the_server_using_RPM_DEB">(package method) directly on the server, using RPM/DEB</a>
       * <a href="#_root_method_directly_on_the_server_manually_with_root_access">(root method) directly on the server, manually, with root access</a>
       * <a href="#_non_root_method_directly_on_the_server_manually_without_root_access">(non-root method) directly on the server, manually, without root access</a>
@@ -131,6 +131,22 @@ don't know ssh it'll be a nightmare to support you.
   * regular expressions are a big part of gitolite in many places but
     familiarity is not necessary to do basic access control.
 
+<a name="_naming_conventions_used"></a>
+
+#### naming conventions used
+
+Throughout the documentation, we use "YourName" as the admin user, and his
+workstation is called "client".  The hosting user is "git", and the server is
+called "server".  **Please substitute your values as needed**.
+
+**If you're using DEB or RPM**, the installer creates a user called
+"gitolite", so substitute that for "git" anywhere in the docs where the
+"hosting user" is mentioned as "git".
+
+Also, we often say "the rc file".  This means `~/.gitolite.rc` on the server.
+And when we say the "access control rules", or "conf file", or "config file",
+we mean `conf/gitolite.conf` on your gitolite-admin clone.
+
 <a name="_getting_the_gitolite_software"></a>
 
 ### getting the gitolite software
@@ -184,22 +200,6 @@ Gitolite has 4 install methods:
 Here's how you install using these 3 methods.  Future upgrades are equally
 easy -- the steps required for upgrading are marked "(U)".
 
-<a name="_conventions_used"></a>
-
-#### conventions used
-
-Throughout the documentation, we use "YourName" as the admin user, and his
-workstation is called "client".  The hosting user is "git", and the server is
-called "server".  **Please substitute your values as needed**.
-
-**If you're using DEB or RPM**, the installer creates a user called
-"gitolite", so substitute that for "git" anywhere in the docs where the
-"hosting user" is mentioned as "git".
-
-Also, we often say "the rc file".  This means `~/.gitolite.rc` on the server.
-And when we say the "access control rules", or "conf file", or "config file",
-we mean `conf/gitolite.conf` on your gitolite-admin clone.
-
 <a name="_package_method_directly_on_the_server_using_RPM_DEB"></a>
 
 #### (package method) directly on the server, using RPM/DEB
@@ -253,6 +253,9 @@ possible, you should (a) know the password in case you screw up the keys AND
 (b) know how to force ssh to ask for a password if required, AND (c) know how
 to handle multiple keys in ssh.**
 
+***NOTE: if this is still confusing, try the [tutorial][tut].  That was
+written for this specific method of install.***
+
   * from your workstation, copy your `~/.ssh/id_rsa.pub` file to the server.
     Put it in `/tmp/YourName.pub`.
 
@@ -429,3 +432,4 @@ uninstalling gitolite is described in great detail in
 [transcript]: http://sitaramc.github.com/gitolite/doc/install-transcript.html
 [mgs]: http://sitaramc.github.com/gitolite/doc/1-INSTALL.html#_special_cases_multiple_gitolite_servers
 [gash]: http://sitaramc.github.com/gitolite/doc/gitolite-and-ssh.html
+[tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial