[gentoo-commits] proj/gitolite-gentoo:upstream commit in: doc/, conf/

[gentoo-commits] proj/gitolite-gentoo:upstream commit in: doc/, conf/

[Christian Ruppert]

commit:     e0f4bbaf16bee86108e457d72b37f43abe04ffb1
Author:     Sitaram Chamarty <sitaram <AT> atc <DOT> tcs <DOT> com>
AuthorDate: Fri Dec 31 14:21:06 2010 +0000
Commit:     Christian Ruppert <idl0r <AT> gentoo <DOT> org>
CommitDate: Fri Dec 31 14:47:36 2010 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/gitolite-gentoo.git;a=commit;h=e0f4bbaf

(minor) more doc updates, really small ones

---
 conf/example.gitolite.rc    |    1 +
 doc/delegation.mkd          |    2 +-
 doc/install-transcript.mkd  |    2 +-
 doc/progit-article.mkd      |    2 +-
 doc/ssh-troubleshooting.mkd |    2 +-
 5 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/conf/example.gitolite.rc b/conf/example.gitolite.rc
index 8f8653a..8626be1 100644
--- a/conf/example.gitolite.rc
+++ b/conf/example.gitolite.rc
@@ -1,6 +1,7 @@
 # configuration variables for gitolite
 
 # PLEASE READ THE DOCUMENTATION BEFORE EDITING OR ASKING QUESTIONS
+# ( http://github.com/sitaramc/gitolite/blob/pu/doc/gitolite.rc.mkd )
 
 # this file is meant to be pulled into a perl program using "do" or "require".
 # You do NOT need to know perl to edit the paths; it should be fairly

diff --git a/doc/delegation.mkd b/doc/delegation.mkd
index 9fe4293..b450403 100644
--- a/doc/delegation.mkd
+++ b/doc/delegation.mkd
@@ -71,7 +71,7 @@ in charge of malware ;-)
 
 [abe]: http://en.wikipedia.org/wiki/Alice_and_Bob#List_of_characters
 
-You do this by adding branches to the `gitolite-admin` repo:
+You do this by adding files with specific names to the `gitolite-admin` repo:
 
     # the admin repo access was probably like this to start with:
     repo gitolite-admin

diff --git a/doc/install-transcript.mkd b/doc/install-transcript.mkd
index 1a3bcbc..178ba1a 100644
--- a/doc/install-transcript.mkd
+++ b/doc/install-transcript.mkd
@@ -127,7 +127,7 @@ described in the `ssh-copy-id` section in `doc/3-faq-tips-etc.mkd`).
     |  ..             |
     +-----------------+
 
-    sita@sita-lt:~ $ ssh-copy-id -i ~/.ssh/id_rsa git@server
+    sita@sita-lt:~ $ ssh-copy-id -i ~/.ssh/id_rsa.pub git@server
     git@server's password:
     /usr/bin/xauth:  creating new authority file /home/git/.Xauthority
     Now try logging into the machine, with "ssh 'git@server'", and check in:

diff --git a/doc/progit-article.mkd b/doc/progit-article.mkd
index da016d3..2667c9b 100644
--- a/doc/progit-article.mkd
+++ b/doc/progit-article.mkd
@@ -24,7 +24,7 @@ We will describe this last method in this article; for the other methods please
 
 You start by obtaining public key based access to your server, so that you can log in from your workstation to the server without getting a password prompt.  The following method works on Linux; for other workstation OSs you may have to do this manually.  We assume you already had a key pair generated using `ssh-keygen`.
 
-	$ ssh-copy-id -i ~/.ssh/id_rsa gitolite@gitserver
+	$ ssh-copy-id -i ~/.ssh/id_rsa.pub gitolite@gitserver
 
 This will ask you for the password to the gitolite account, and then set up public key access.  This is **essential** for the install script, so check to make sure you can run a command without getting a password prompt:
 

diff --git a/doc/ssh-troubleshooting.mkd b/doc/ssh-troubleshooting.mkd
index 6238cf9..0fa7169 100644
--- a/doc/ssh-troubleshooting.mkd
+++ b/doc/ssh-troubleshooting.mkd
@@ -307,7 +307,7 @@ from scratch:
     `sitaram`, along with corresponding `.pub` files).  Create them if needed.
     Also make sure they are *different* and not a copy of each other :-)
   * install gitolite normally:
-      * run `ssh-copy-id -i ~/.ssh/id_rsa git@server` to get passwordless
+      * run `ssh-copy-id -i ~/.ssh/id_rsa.pub git@server` to get passwordless
         access to the server.  (Mac users may have to do this step manually)
       * make sure `ssh git@server pwd` prints the `$HOME` of `git@server`
         **without** asking for a password.  Do not proceed till this works.

[gentoo-commits] proj/gitolite-gentoo:upstream commit in: doc/, conf/

[Christian Ruppert]

commit:     ffcbc526379c7dab889262595fb1ff6bec3a725b
Author:     Sitaram Chamarty <sitaram <AT> atc <DOT> tcs <DOT> com>
AuthorDate: Fri Dec 31 13:33:48 2010 +0000
Commit:     Christian Ruppert <idl0r <AT> gentoo <DOT> org>
CommitDate: Fri Dec 31 13:33:48 2010 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/gitolite-gentoo.git;a=commit;h=ffcbc526

rc file stripped down, variables categorised, documentation lifted out

the old file was getting too unwieldy...

---
 conf/example.gitolite.rc |  326 ++++++---------------------------------------
 doc/gitolite.rc.mkd      |  325 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 369 insertions(+), 282 deletions(-)

diff --git a/conf/example.gitolite.rc b/conf/example.gitolite.rc
index e4ac0c0..8f8653a 100644
--- a/conf/example.gitolite.rc
+++ b/conf/example.gitolite.rc
@@ -1,313 +1,75 @@
-# paths and configuration variables for gitolite
+# configuration variables for gitolite
 
-# please read comments before editing
+# PLEASE READ THE DOCUMENTATION BEFORE EDITING OR ASKING QUESTIONS
 
 # this file is meant to be pulled into a perl program using "do" or "require".
-
 # You do NOT need to know perl to edit the paths; it should be fairly
 # self-explanatory and easy to maintain perl syntax :-)
 
-# --------------------------------------
-# Do not change the next two lines unless you know what you're doing
-# $GL_PACKAGE_CONF = "";
-# $GL_PACKAGE_HOOKS = "";
-
-# --------------------------------------
-# MIRRORING SUPPORT
-
-# $GL_SLAVE_MODE = 0;
-# $ENV{GL_SLAVES} = 'gitolite@server2 gitolite@server3';
-#       PLEASE USE SINGLE QUOTES ABOVE, NOT DOUBLE QUOTES
-
-# see doc/mirroring.mkd for details
-
-# --------------------------------------
-
-# this is where the repos go.  If you provide a relative path (not starting
-# with "/"), it's relative to your $HOME.  You may want to put in something
-# like "/bigdisk" or whatever if your $HOME is too small for the repos, for
-# example
-
-$REPO_BASE="repositories";
-
-# the default umask for repositories is 0077; change this if you run stuff
-# like gitweb and find it can't read the repos.  Please note the syntax;  the
-# leading 0 is required
-
-$REPO_UMASK = 0077;         # gets you 'rwx------'
-# $REPO_UMASK = 0027;       # gets you 'rwxr-x---'
-# $REPO_UMASK = 0022;       # gets you 'rwxr-xr-x'
-
-# part of the setup of gitweb is a variable called $projects_list (please see
-# gitweb documentation for more on this).  Set this to the same value:
-
-$PROJECTS_LIST = $ENV{HOME} . "/projects.list";
-
-# giving access to @all users (as in "R  =  @all") in the config normally does
-# *not* include the special users "gitweb" and "daemon".  If you want @all to
-# include these two users, set this variable:
-
-# $GL_ALL_INCLUDES_SPECIAL = 0;
-
-# --------------------------------------
-
-# I see no reason anyone may want to change the gitolite admin directory, but
-# feel free to do so.  However, please note that it *must* be an *absolute*
-# path (i.e., starting with a "/" character)
-
-# gitolite admin directory, files, etc
-
+# ------------------------------------------------------------------------------
+# VARIABLES THAT SHOULD NOT BE TOUCHED AT ALL.  EVER.
+# ------------------------------------------------------------------------------
 $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";
-
-# --------------------------------------
-
-# location of the performance log files
-
-# uncomment and set this variable if you want performance logging
-#
-# perf log files are different from access log files; they store different
-# information, are not meant to be as long-lived, and so on
-
-# $GL_PERFLOGT="$GL_ADMINDIR/logs/perf-gitolite-%y-%m.log";
-
-# --------------------------------------
-
-# Please DO NOT change these three paths
-
 $GL_CONF="$GL_ADMINDIR/conf/gitolite.conf";
 $GL_KEYDIR="$GL_ADMINDIR/keydir";
 $GL_CONF_COMPILED="$GL_ADMINDIR/conf/gitolite.conf-compiled.pm";
+# DO NOT CHANGE THE NEXT TWO LINES UNLESS YOU REALLY KNOW WHAT YOU'RE DOING.
+# These variables are set automatically by the install method you choose.
+# $GL_PACKAGE_CONF = "";
+# $GL_PACKAGE_HOOKS = "";
 
-# --------------------------------------
-
-# if git on your server is on a standard path (that is
-#       ssh git@server git --version
-# works), leave this setting as is.  Otherwise, choose one of the
-# alternatives, or write your own
-
-$GIT_PATH="";
-# $GIT_PATH="/opt/bin/";
-
-# --------------------------------------
-
-# ----------------------------------------------------------------------
-#                   BIG CONFIG SETTINGS
-
-# Please read doc/big-config.mkd for details
+# ------------------------------------------------------------------------------
+# most often used/changed variables
+# ------------------------------------------------------------------------------
+$GL_WILDREPOS = 0;
+$PROJECTS_LIST = $ENV{HOME} . "/projects.list";
+$REPO_UMASK = 0077;
 
+# ------------------------------------------------------------------------------
+# variables with an efficiency impact
+# ------------------------------------------------------------------------------
 $GL_BIG_CONFIG = 0;
 $GL_NO_DAEMON_NO_GITWEB = 0;
-$GL_NO_CREATE_REPOS = 0;
-$GL_NO_SETUP_AUTHKEYS = 0;
-
-# ----------------------------------------------------------------------
-#                   SECURITY SENSITIVE SETTINGS
-#
-#       Settings below this point may have security implications.  That
-#       usually means that I have not thought hard enough about all the
-#       possible ways to crack security if these settings are enabled.
-
-#       Please see details on each setting for specifics, if any.
-# ----------------------------------------------------------------------
-
-
-
-# --------------------------------------
-# ALLOW REPO ADMIN TO SET GITCONFIG KEYS
-#
-# Gitolite allows you to set git repo options using the "config" keyword; see
-# conf/example.conf for details and syntax.
-#
-# However, if you are in an installation where the repo admin does not (and
-# should not) have shell access to the server, then allowing him to set
-# arbitrary repo config options *may* be a security risk -- some config
-# settings may allow executing arbitrary commands.
-#
-# You have 3 choices.  By default $GL_GITCONFIG_KEYS is left empty, which
-# completely disables this feature (meaning you cannot set git configs from
-# the repo config).
 
+# ------------------------------------------------------------------------------
+# VARIABLES WITH A SECURITY IMPACT
+# ------------------------------------------------------------------------------
+$GIT_PATH="";
 $GL_GITCONFIG_KEYS = "";
-
-# The second choice is to give it a space separated list of settings you
-# consider safe.  (These are actually treated as a set of regular expression
-# patterns, and any one of them must match).  For example:
-# $GL_GITCONFIG_KEYS = "core\.logAllRefUpdates core\..*compression";
-# allows repo admins to set one of those 3 config keys (yes, that second
-# pattern matches two settings from "man git-config", if you look)
-#
-# The third choice (which you may have guessed already if you're familiar with
-# regular expressions) is to allow anything and everything:
-# $GL_GITCONFIG_KEYS = ".*";
-
-# NOTE that due to some quoting and interpolation issues I have not been able
-# to look at, a literal "." needs to be specified in this string as \\.  (two
-# backslashes and a dot).  So this is how you'd allow any keys in the "foo"
-# category:
-#       $GL_GITCONFIG_KEYS = "foo\\..*";
-
-# --------------------------------------
-# ALLOW GITCONFIG KEYS EVEN FOR WILD REPOS
-#
-# This is an efficiency issue more than a security issue, since this requires
-# trawling through all of $REPO_BASE looking for stuff :)
-
 # $GL_GITCONFIG_WILD = 0;
-
-# --------------------------------------
-# EXTERNAL COMMAND HELPER -- HTPASSWD
-
-# security note: runs an external command (htpasswd) with specific arguments,
-# including a user-chosen "password".
-
-# if you want to enable the "htpasswd" command, give this the absolute path to
-# whatever file apache (etc) expect to find the passwords in.
-
+$GL_NO_CREATE_REPOS = 0;
+$GL_NO_SETUP_AUTHKEYS = 0;
+# $GL_WILDREPOS_DEFPERMS = 'R @all';
 $HTPASSWD_FILE = "";
-
-# Look in doc/3 ("easier to link gitweb authorisation with gitolite" section)
-# for more details on using this feature.
-
-# --------------------------------------
-# EXTERNAL COMMAND HELPER -- RSYNC
-
-# security note: runs an external command (rsync) with specific arguments, all
-# presumably filled in correctly by the client-side rsync.
-
-# base path of all the files that are accessible via rsync.  Must be an
-# absolute path.  Leave it undefined or set to the empty string to disable the
-# rsync helper.
-
 $RSYNC_BASE = "";
-
-# $RSYNC_BASE = "/home/git/up-down";
-# $RSYNC_BASE = "/tmp/up-down";
-
-# --------------------------------------
-# EXTERNAL COMMAND HELPER -- SVNSERVE
-
-# security note: runs an external command (svnserve) with specific arguments,
-# as specified below. %u is substituted with the username.
-
-# This setting allows launching svnserve when requested by the ssh client.
-# This allows using the same SSH setup (hostname/username/public key) for both
-# SVN and git access. Leave it undefined or set to the empty string to disable
-# svnserve access.
-
 $SVNSERVE = "";
-# $SVNSERVE = "/usr/bin/svnserve -r /var/svn/ -t --tunnel-user=%u";
-
-# --------------------------------------
-# ALLOW REPO CONFIG TO USE WILDCARDS
-
-# security note: this used to in a separate "wildrepos" branch.  You can
-# create repositories based on wild cards, give "ownership" to the specific
-# user who created it, allow him/her to hand out R and RW permissions to other
-# users to collaborate, etc.  This is powerful stuff, and I've made it as
-# secure as I can, but it hasn't had the kind of rigorous line-by-line
-# analysis that the old "master" branch had.
-
-# This has now been rolled into master, with all the functionality gated by
-# this variable.  Set this to 1 if you want to enable the wildrepos features.
-# Please see doc/wildcard-repositories.mkd for details.
-
-$GL_WILDREPOS = 0;
-
-# --------------------------------------
-# DEFAULT WILDCARD PERMISSIONS
-
-# If set, this value will be used as the default user-level permission rule of
-# new wildcard repositories. The user can change this value with the setperms command
-# as desired after repository creation; it is only a default. Note that @all can be
-# used here but is special; no other groups can be used in user-level permissions.
-
-# $GL_WILDREPOS_DEFPERMS = 'R @all';
-
-# --------------------------------------
-# WILDREPOS PERMS CATEGORIES
-
-# Originally, we only allowed "R" and "RW" in the setperms command.  Now we
-# allow the admin to define other categories as she wishes (example: MANAGERS,
-# TESTERS, etc).
-
-# This variable is a space-sep list of the allowed categories.
-
-# PLEASE, *PLEASE*, read the section in doc/wildcard-repositories.mkd for
-# caveats and warnings.  This is a VERY powerful feature and if you're not
-# careful you could mess up the ACLs nicely.
-
-# this is the internal default if you don't set it (like if you didn't update
-# your ~/.gitolite.rc with new variables when you upgraded gitolite):
-$GL_WILDREPOS_PERM_CATS = "READERS WRITERS";
-
-# you can use your own categories in addition to the standard ones; I suggest
-# you include READERS and WRITERS for backward compat though:
-# $GL_WILDREPOS_PERM_CATS = "READERS WRITERS MANAGERS";
-# $GL_WILDREPOS_PERM_CATS = "READERS WRITERS MANAGERS TESTERS";
-
-# --------------------------------------
-# HOOK CHAINING
-
-# by default, the update hook in every repo chains to "update.secondary".
-# Similarly, the post-update hook in the admin repo chains to
-# "post-update.secondary".  If you're fine with the defaults, there's no need
-# to do anything here.  However, if you want to use different names or paths,
-# change these variables
-
 # $UPDATE_CHAINS_TO = "hooks/update.secondary";
 # $ADMIN_POST_UPDATE_CHAINS_TO = "hooks/post-update.secondary";
-
-# --------------------------------------
-# ADMIN DEFINED COMMANDS
-
-# WARNING: Use this feature only if (a) you really really know what you're
-# doing or (b) you really don't care too much about security.  Please read
-# doc/admin-defined-commands.mkd for details.
-
 # $GL_ADC_PATH = "";
+# $GL_GET_MEMBERSHIPS_PGM = "/usr/local/bin/expand-ldap-user-to-groups"
 
-# --------------------------------------
-# SITE-SPECIFIC INFORMATION
-
-# Some installations would like to give their users customised information
-# (like a link to their own websites, for example) so that each end user does
-# not have to grok all the gitolite documentation.
-
-# If this variable is defined, the "info" command will print it at the end of
-# the listing.
+# ------------------------------------------------------------------------------
+# less used/changed variables
+# ------------------------------------------------------------------------------
+# $GL_ALL_INCLUDES_SPECIAL = 0;
+# $GL_SLAVE_MODE = 0;
+# $ENV{GL_SLAVES} = 'gitolite@server2 gitolite@server3';
+# PLEASE USE SINGLE QUOTES ABOVE, NOT DOUBLE QUOTES
+$GL_WILDREPOS_PERM_CATS = "READERS WRITERS";
 
-# $GL_SITE_INFO = "";
+# ------------------------------------------------------------------------------
+# rarely changed variables
+# ------------------------------------------------------------------------------
+$GL_LOGT="$GL_ADMINDIR/logs/gitolite-%y-%m.log";
+# $GL_PERFLOGT="$GL_ADMINDIR/logs/perf-gitolite-%y-%m.log";
 # $GL_SITE_INFO = "XYZ.COM DEVELOPERS: PLEASE SEE http://xyz.com/gitolite/help first";
 
-# --------------------------------------
-# USERGROUP HANDLING
-
-# Some sites would like to store group membership outside gitolite, because
-# they already have it in (usually) their LDAP server, and it doesn't make
-# sense to be forced to duplicate this information.
-
-# Set the following variable to the name of a script that, given a username as
-# argument, will return a list of groups that she is a member of.
-
-# $GL_GET_MEMBERSHIPS_PGM = "/usr/local/bin/expand-ldap-user-to-groups"
+# ------------------------------------------------------------------------------
+# variables that should NOT be changed after the install step completes
+# ------------------------------------------------------------------------------
+$REPO_BASE="repositories";
 
-# --------------------------------------
+# ------------------------------------------------------------------------------
 # per perl rules, this should be the last line in such a file:
 1;
 

diff --git a/doc/gitolite.rc.mkd b/doc/gitolite.rc.mkd
new file mode 100644
index 0000000..ecf5758
--- /dev/null
+++ b/doc/gitolite.rc.mkd
@@ -0,0 +1,325 @@
+# configuration variables for gitolite
+
+This is the documentation for the contents of the "rc" file
+(`$HOME/.gitolite.rc`) on the server.  Until now this documentation was
+inline, within the rc file itself, but it has grown too large, too unwieldy,
+and too difficult to grok for people new to gitolite.
+
+The documentation follows approximately the same order as the sample variables
+in the (now reorganised) example "rc" file.
+
+In this document:
+
+  * <a href="#_variables_that_should_not_be_touched_at_all">variables that should not be touched at all</a>
+  * <a href="#_most_often_used_changed_variables">most often used/changed variables</a>
+  * <a href="#_variables_with_an_efficiency_impact">variables with an efficiency impact</a>
+  * <a href="#_variables_with_a_security_impact">variables with a security impact</a>
+  * <a href="#_less_used_changed_variables">less used/changed variables</a>
+  * <a href="#_rarely_changed_variables">rarely changed variables</a>
+
+[Note: in perl, there is no actual boolean.  The undefined value, the number
+'0', and the empty string, are all 'false'.  Everything else is 'true'.  It is
+thus common to use just 0/1 for false/true].
+
+<a name="_variables_that_should_not_be_touched_at_all"></a>
+
+### variables that should not be touched at all
+
+The first section does not need too much elaboration.  Let's just say bad
+things happen if you change them.
+
+<a name="_most_often_used_changed_variables"></a>
+
+### most often used/changed variables
+
+  * `$GL_WILDREPOS`, boolean, default 0
+
+    Setting this variable lets your users create repositories based on wild
+    cards, hand out R and RW permissions to other users to collaborate, etc.
+
+    See [doc/wildcard-repositories.mkd][wild] for lots of info on this.
+
+  * `$PROJECTS_LIST`, filename, default `~/projects.list`
+
+    This is for gitweb users only.  Gitweb setup has a variable called
+    `$projects_list` (please see gitweb docs for more on this).  Set this to
+    the same value as that one.
+
+  * `$REPO_UMASK`, octal, default `0077`
+
+    The default UMASK that gitolite uses makes all the repos and their
+    contents have `rwx------` permissions.  People who want to run gitweb
+    realise that this will not do.  The correct way to deal with this is to
+    change this variable to `0027` (which gets you `rwxr-x---`), then add the
+    apache or httpd user running the webserver as a member of the 'gitolite'
+    group.
+
+    Please note the syntax; the leading 0 is required.  If you change it
+    *after* the install is complete, you'll have to do some chmod's also to
+    adjust permissions of files and directories that have already been
+    created.
+
+<a name="_variables_with_an_efficiency_impact"></a>
+
+### variables with an efficiency impact
+
+  * `$GL_BIG_CONFIG`, boolean, default 0
+
+    This is the most common setting for efficiency in handling large repo/user
+    groups.  This is a very powerful setting; please read
+    [doc/big-config.mkd][bc] for all the details you might need.
+
+    There are 3 other settings related to big configs.  They are changed only
+    in rare cases, however, so are described later.
+
+  * `$GL_NO_DAEMON_NO_GITWEB`, boolean, default 0
+
+    If you have *lots* of repos, and you're *not* using gitweb or daemon, you
+    should probably set this on for efficiency.  Despite the name, it also
+    blocks repo config settings.  Please read [doc/big-config.mkd][bc] for
+    more details.
+
+<a name="_variables_with_a_security_impact"></a>
+
+### variables with a security impact
+
+**IMPORTANT NOTE**
+
+This section describes variables that, if not carefully used, can cause
+security issues.  It also includes variables which I personally do not use and
+do not have the ability to test thoroughly
+
+Using non-default value for these variables voids the security reward in the
+README.  This does *not* mean they are less important or that I will ignore
+problems; it just means *my* ability to catch problems may be limited by my
+test suite, my actual production use, my time, and sometimes (LDAP comes to
+mind) even my skill or resources available to me, and that therefore I depend
+on feedback from my users to find or fix issues.
+
+  * `$GIT_PATH`, string, default empty
+
+    If git on your server is on a standard path (that is `ssh git@server git
+    --version` works), leave this setting as is.  Otherwise, find out where it
+    is and use that value here, for example `GIT_PATH="/opt/bin/";`
+
+  * `$GL_GITCONFIG_KEYS`, string, default empty
+
+    This setting allows the repo admin to define acceptable gitconfig keys.
+
+    Gitolite allows you to set git repo options using the "config" keyword;
+    see conf/example.conf for details and syntax.
+
+    However, if you are in an installation where the repo admin does not (and
+    should not) have shell access to the server, then allowing him to set
+    arbitrary repo config options *may* be a security risk -- some config
+    settings allow executing arbitrary commands!
+
+    You have 3 choices.  By default `$GL_GITCONFIG_KEYS` is left empty, which
+    completely disables this feature (meaning you cannot set git configs via
+    the repo config).
+
+    The second choice is to give it a space separated list of settings you
+    consider safe.  (These are actually treated as a set of perl regular
+    expression patterns, and any one of them must match).  For example:
+    `$GL_GITCONFIG_KEYS = "core\\.logAllRefUpdates core\\..*compression";`
+    allows repo admins to set one of those 3 config keys (yes, that second
+    pattern matches two settings from "man git-config", if you look).
+
+    The third choice (which you may have guessed already if you're familiar
+    with regular expressions) is to allow anything and everything:
+    `$GL_GITCONFIG_KEYS = ".*";`
+
+    NOTE that due to some quoting and interpolation issues I have not been
+    able to look at, a literal "." needs to be specified in this string as
+    `\\.` (two backslashes and a dot).  So this is how you'd allow any keys in
+    the "foo" category: `$GL_GITCONFIG_KEYS = "foo\\..*";`
+
+  * `$GL_GITCONFIG_WILD`, boolean, default 0
+
+    This setting allows gitconfig keys even for wild repos.  This is an
+    efficiency issue more than a security issue, since this requires trawling
+    through all of `$REPO_BASE` looking for stuff :)
+
+  * `$GL_NO_CREATE_REPOS`, boolean, default 0
+
+    DO NOT CHANGE THIS unless you have other means to create repos and
+    correctly populate them with the required hooks.  No hooks, no access
+    control; you have been warned!
+
+  * `$GL_NO_SETUP_AUTHKEYS`, boolean, default 0
+
+    DO NOT CHANGE THIS unless you have other means to setup the authkeys file
+    (`~/.ssh/authorized_keys`).  In an extreme case, if you switch this on
+    without also fixing up the authkeys file, users who you think you deleted
+    may still have access.  All in all, please be careful, as with any change
+    that affects ssh.
+
+  * `$GL_WILDREPOS_DEFPERMS`, string, default undef
+
+    This sets default wildcard permissions for newly created wildcard repos.
+
+    If set, this value will be used as the default user-level permission rule
+    of new wildcard repositories. The user can change this value with the
+    setperms command as desired after repository creation; it is only a
+    default.
+
+    Example: `$GL_WILDREPOS_DEFPERMS = 'R @all';`
+
+  * `$HTPASSWD_FILE`, string, default empty
+
+    Gitolite can help users run the htpasswd command in a secure manner (since
+    gitolite has already identified them by an ssh key).  If you want to
+    enable this, give the variable the absolute path to whatever file apache
+    (etc) expect to find the passwords in.
+
+    Look in [doc/3-faq-tips-etc.mkd][faq] ("easier to link gitweb
+    authorisation with gitolite" section) for more details on using this
+    feature.
+
+  * `$RSYNC_BASE`, string, default empty
+
+    Gitolite can be used to allow fine grained control of the rsync command.
+
+    This setting enables the rsync external command helper, by specifying the
+    base path of all the files that are accessible via rsync.  It must be an
+    absolute path, like `$RSYNC_BASE = "/home/git/up-down";`.  Leave it
+    undefined or set to the empty string to disable the rsync helper.
+
+    When enabled, it runs rsync with specific arguments, all presumably filled
+    in correctly by the client-side rsync. However, I am not an expert on how
+    rsync may be abused, so if it breaks, you get to keep both pieces!
+
+  * `$SVNSERVE`, string, default empty
+
+    Gitolite can also be used to gate access (though not at a fine grained
+    level) to SVN if needed, passing authentication information on to
+    `svnserve`.  This setting allows launching svnserve when requested by the
+    ssh client.  This allows using the same SSH setup for both SVN and git
+    access. Leave it undefined or set to the empty string to disable svnserve
+    access.
+
+    The setting will look something like (where the %u is substituted with the
+    username):
+
+        $SVNSERVE = "/usr/bin/svnserve -r /var/svn/ -t --tunnel-user=%u";
+
+  * hook chaining
+
+      * `$UPDATE_CHAINS_TO`, string, default "hooks/update.secondary"
+      * `$ADMIN_POST_UPDATE_CHAINS_TO`, string, default
+        "hooks/post-update.secondary"
+
+    By default, the update hook in every repo chains to "update.secondary".
+    Similarly, the post-update hook in the admin repo chains to
+    "post-update.secondary".  If you're fine with the defaults, there's no
+    need to do anything here.  However, if you want to use different names or
+    paths, change these variables.
+
+  * `$GL_ADC_PATH`, string, default undef
+
+    This setting enables admin defined commands.
+
+    **WARNING**: Use this feature only if (a) you really know what you're
+    doing and (b) you really, **really**, know what you're doing!  Please read
+    [doc/admin-defined-commands.mkd][adc] for details.  This is an extremely
+    powerful and flexible feature, and naturally anything that flexible can be
+    a security risk!
+
+  * `$GL_GET_MEMBERSHIPS_PGM`, string, default undef
+
+    Some sites would like to store group membership outside gitolite, because
+    they already have it in (usually) their LDAP server, and it doesn't make
+    sense to be forced to duplicate this information.
+
+    Set the following variable to the name of a script that, given a username
+    as argument, will return a list of groups that she is a member of.  See
+    [doc/big-config.mkd][bc] for more details.
+
+    Example: `$GL_GET_MEMBERSHIPS_PGM = "/usr/local/bin/expand-ldap-user-to-groups"`
+
+<a name="_less_used_changed_variables"></a>
+
+### less used/changed variables
+
+  * `$GL_ALL_INCLUDES_SPECIAL`, boolean, default undef
+
+    Giving access to @all users (as in `R  =  @all`) in the config normally
+    does *not* include the special users "gitweb" and "daemon".  If you want
+    @all to include these two users, set this variable.
+
+  * mirroring setup
+
+    These two variables enable mirroring support; see
+    [doc/mirroring.mkd][mirr] for details.  The two variables are
+    `$GL_SLAVE_MODE`, (boolean, default undef), and `$ENV{GL_SLAVES}`,
+    (environment variable, string, default undef)
+
+    Note on the second variable above: you must use single quotes to give it
+    its value, not double quotes, (like `$ENV{GL_SLAVES} = 'gitolite@server2
+    gitolite@server3';`).  Also note that this is an environment variable, not
+    a regular perl variable, so mind the syntax if you're not a perl guy :-)
+
+  * `$GL_WILDREPOS_PERM_CATS`, string, default "READERS WRITERS"
+
+    Originally, we only allowed "R" and "RW" in the setperms command.  Now we
+    allow the admin to define other categories as she wishes (example:
+    MANAGERS, TESTERS, etc).
+
+    This variable is a space-separated list of the allowed categories.
+
+    PLEASE, *PLEASE*, read the section in
+    [doc/wildcard-repositories.mkd][wild] for caveats and warnings.  This is a
+    VERY powerful feature and if you're not careful you could mess up the ACLs
+    nicely.
+
+    This is the internal default if you don't set it (like if you didn't
+    update your ~/.gitolite.rc with new variables when you upgraded gitolite):
+
+        $GL_WILDREPOS_PERM_CATS = "READERS WRITERS";
+
+    You can use your own categories in addition to the standard ones; I
+    suggest you include READERS and WRITERS for backward compatbility though:
+
+        $GL_WILDREPOS_PERM_CATS = "READERS WRITERS MANAGERS TESTERS";
+
+<a name="_rarely_changed_variables"></a>
+
+### rarely changed variables
+
+  * `$GL_LOGT`, string, default `$GL_ADMINDIR/logs/gitolite-%y-%m.log`
+
+    This is the template for location of the log files and format of their
+    names.
+
+    The default produces files like `~/.gitolite/logs/gitolite-2009-09.log`.
+    If you make up your own templates, **PLEASE MAKE SURE** the directory
+    exists and is writable; gitolite won't do that for you unless it is the
+    default, ("$GL_ADMINDIR/logs")
+
+  * `$GL_PERFLOGT`, string, default undef
+
+    This gives the location of the performance log files.  Uncomment and set
+    this variable if you want performance logging.  Performance log files are
+    kept separate from access log files because they store different, usually
+    much shorter term, information.
+
+  * `$GL_SITE_INFO`, string, default undef
+
+    Some installations would like to give their users customised information
+    (like a link to their own websites, for example) so that users have a
+    quick way to find some links or information.
+
+    If this variable is defined, the "info" command will print it at the end
+    of the listing.
+
+  * `$REPO_BASE`, string, default "repositories"
+
+    This is where all the repos go.  If it's not an absolute path, it is
+    considered to be relative to $HOME.  Changing it after the install has
+    completed is doable, but tricky if you don't know how gitolite works.
+
+[wild]: http://github.com/sitaramc/gitolite/blob/pu/doc/wildcard-repositories.mkd
+[bc]: http://github.com/sitaramc/gitolite/blob/pu/doc/big-config.mkd
+[faq]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd
+[adc]: http://github.com/sitaramc/gitolite/blob/pu/doc/admin-defined-commands.mkd
+[mirr]: http://github.com/sitaramc/gitolite/blob/pu/doc/mirroring.mkd