(doc) assorted docfixes

README.mkd

@@ -28,7 +28,9 @@ don't miss out on them by skipping the excellent
 [documentation][docs]!)</font>
 
   * create a user called `git`.  Login to this user.
+
   * copy your ssh pubkey from your workstation.  Rename it to `YourName.pub`.
+
   * now run these commands:
 
         git clone git://github.com/sitaramc/gitolite
@@ -36,8 +38,12 @@ don't miss out on them by skipping the excellent
         src/gl-system-install
         gl-setup ~/YourName.pub
 
-You're done.  Now run `git clone git@server:gitolite-admin` on your
+You're done.
-workstation and [add users and repos][aur].
+
+A word of caution: do **NOT** add repos or users directly on the server!  You
+MUST manage the server by cloning the special 'gitolite-admin' repo on your
+workstation (`git clone git@server:gitolite-admin`), making changes, and
+pushing them.  See [here][aur] for how to add users and repos.
 
 [aur]: http://sitaramc.github.com/gitolite/doc/2-admin.html#_adding_users_and_repos
 

contrib/adc/README.mkd

@@ -1,4 +1,4 @@
-# brief descriptions of the shipped ADCs (admin-defined commands)
+## brief descriptions of the shipped ADCs (admin-defined commands)
 
 (...with pointers to further information where needed)
 

contrib/adc/hub.mkd

@@ -1,4 +1,4 @@
-# the 'hub' ADC
+## the 'hub' ADC
 
 In this document:
 

contrib/adc/repo-deletion.mkd

@@ -1,4 +1,11 @@
-# deleting repos safely
+## deleting repos safely
+
+**NOTE**: this page is about deleting [user-created repos][wcr].  It is
+**not** about deleting "normal" repos (the kind that are specified in the
+gitolite.conf file itself) -- to delete those read [here][dnr].
+
+[wcr]: http://sitaramc.github.com/gitolite/doc/wildcard-repositories.html
+[dnr]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html#_deleting_a_repo
 
 (see [this thread][thr] on the gitolite mailing list)
 

contrib/mirroring-complex-example.mkd

@@ -1,4 +1,4 @@
-# semi-autonomous mirroring setup example
+## semi-autonomous mirroring setup example
 
 [deldoc]: http://sitaramc.github.com/gitolite/doc/delegation.html
 [sc]: http://sitaramc.github.com/gitolite/doc/delegation.html#_the_subconf_command

doc/2-admin.mkd

@@ -50,6 +50,11 @@ Once you've cloned it, you're ready to add users and repos.
 
 ### adding users and repos
 
+Do **NOT** add repos or users directly on the server!  You MUST manage the
+server by cloning the special 'gitolite-admin' repo on your workstation (`git
+clone git@server:gitolite-admin`), making changes, and pushing them.  This
+section tells you how to add users and repos.
+
   * ask each user who will get access to send you a public key.  See other
     sources (for example [here][genpub]) for how to do this
 
@@ -245,8 +250,9 @@ important here:
     `~/repositories`), making sure that the directory names end in ".git".
 
   * back on your workstation, add each repo (without the `.git` suffix) to
-    `conf/gitolite.conf` in your gitolite-admin repo clone.  Then add, commit,
+    `conf/gitolite.conf` in your gitolite-admin repo clone.  Give *some* user
-    push.
+    (even a non-existent one like "DUMMY" is fine) at least "R" access to
+    these repos.  Then add, commit, push.
 
 **Case 3 -- far too many repos** (or your initials are JH ;-): This is when
 you're like Case 2, except you have *so many* repos that step 3 becomes too

doc/3-faq-tips-etc.mkd

@@ -32,6 +32,8 @@ In this document:
           * <a href="#_admin_defined_commands">admin defined commands</a>
           * <a href="#_access_control_for_external_commands">access control for external commands</a>
               * <a href="#_svnserve">svnserve</a>
+  * <a href="#_odds_and_ends">odds and ends</a>
+      * <a href="#_poking_the_admin_repo_to_force_a_compile">"poking" the admin repo to force a compile</a>
   * <a href="#_design_choices">design choices</a>
       * <a href="#_keeping_the_parser_and_the_access_control_separate">keeping the parser and the access control separate</a>
 
@@ -107,47 +109,45 @@ features than the original goal of branch-level access control.
 
 ##### one user, many keys
 
-I have a laptop and a desktop I need to access the server from.  I have
+If you have a user who has more than one pubkey (like from different machines)
-different private keys on them, but as far as gitolite is concerned both of
+the simplest way to deal with it is to add subdirectories and add keys there.
-them should be treated as "sitaram".  How does this work?
+For example, I might have these files in `keydir/`:
 
-The way it works is that you copy one pubkey as "sitaram@laptop.pub" and the
+    sitaram.pub
-other as "sitaram@desktop.pub".  The part before the "@" is the username, so
+    home/sitaram.pub
-gitolite knows these two keys belong to the same person.  The part after the
+    laptop/sitaram.pub
-"@" can be anything you like, of course; gitolite doesn't care.
 
-Note that you don't say "sitaram@laptop" and so on in the **config** file --
+<font color="gray">
-as far as the config file is concerned there's just **one** user called
-"sitaram" -- so you only say "sitaram" there.
 
-I think this is easier to maintain if you have to delete or change one of
+The older method will continue to work, simply because I prefer it.  But I am
-those keys.
+not going to document it except for the example below, nor am I going to
+support it in terms of questions.  Sorry.  Apparently it was too complex to
+understand, even for some smart folks I know.  This tells me it was probably
+ill thought out and should have been obsoleted as soon as e0fe73a was pushed.
 
-However, now that `sitaramc@gmail.com` is also a valid username, we need to
+Anyway, here's *all* the documentation for it -- some sample pubkey filenames
-distinguish between `sitaramc@gmail.com.pub` and `sitaramc@desktop.pub`.  We
+and the corresponding derived usernames:
-do that by requiring that the multi-key suffix you use (like "desktop" and
-"laptop") should not have a `"."` in it.  If it does, it looks like an email
-address.  The following table lists sample pubkey filenames and the
-corresponding derived usernames (which is what goes into the
-`conf/gitolite.conf` file):
 
-  * old style multikeys; not mistaken for emails because there is no "." in
+  * plain username, no multikey
-    hostname part
 
         sitaramc.pub                            sitaramc
+
+  * plain username, with multikeys
+
         sitaramc@laptop.pub                     sitaramc
         sitaramc@desktop.pub                    sitaramc
 
-  * new style, email keys; there is a "." in hostname part; so it's an email
+  * email address as username, no multikey
-    address
 
         sitaramc@gmail.com.pub                  sitaramc@gmail.com
 
-  * multikeys *with* email address
+  * email address as username, with multikeys
 
         sitaramc@gmail.com@laptop.pub           sitaramc@gmail.com
         sitaramc@gmail.com@desktop.pub          sitaramc@gmail.com
 
+</font>
+
 <a name="_security_access_control_and_auditing"></a>
 
 #### security, access control, and auditing
@@ -532,6 +532,23 @@ system. Assuming you installed gitolite to the same user as the one you used
 for SVN, SVN connectivity will be retained, and users will be able to use
 both SVN and git using the same SSH configuration.
 
+<a name="_odds_and_ends"></a>
+
+### odds and ends
+
+<a name="_poking_the_admin_repo_to_force_a_compile"></a>
+
+#### "poking" the admin repo to force a compile
+
+Sometimes you need to force a compile, as if you pushed the gitolite-admin
+repo.  I have a git alias that looks like this:
+
+    [alias]
+        poke = !git ls-remote origin | grep -w refs/heads/poke && git push origin :poke || git push origin master:poke
+
+so I just run `git poke`.  This toggles between deleting and creating a dummy
+branch called "poke".  Either operation will trigger the hooks.
+
 <a name="_design_choices"></a>
 
 ### design choices

doc/gitolite.conf.mkd

@@ -541,12 +541,14 @@ later to override the generic settings.
 
 #### repo owner/description line for gitweb
 
-Including a line like this:
+You can include owner/description information in the conf file, and gitolite
+will put it in places where gitweb will pick it up.  For example, suppose this
+software (gitolite) itself was being hosted on a gitolite server and intended
+to be shown on gitweb, I'd use a line like this:
 
-    gitolite "Sitaram Chamarty" = "fast, secure, access control for git in a corporate environment"
+    gitolite "Sitaram Chamarty" = "fast, secure, access control for git"
 
-sets the owner name and description for gitweb.  The general syntax is very
+The general syntax is very simple, just use one of:
-simple, just use one of:
 
     reponame = "some description string in double quotes"
     reponame "owner name" = "some description string in double quotes"

doc/gitolite.rc.mkd

@@ -127,7 +127,8 @@ on feedback from my users to find or fix issues.
     This setting allows the repo admin to define acceptable gitconfig keys.
 
     Gitolite allows you to set git repo options using the "config" keyword;
-    see doc/gitolite.conf.mkd for details and syntax.
+    see the section on "repo specific git config commands" in
+    [doc/gitolite.conf.mkd][gitconf] 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
@@ -367,3 +368,4 @@ of `ADC_CMD_ARGS_PATT`), please be sure you know what you're doing.
 [smart]: http://sitaramc.github.com/gitolite/doc/http-backend.html
 [dwr]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html#_disabling_write_access_to_take_backups
 [limit]: http://sitaramc.github.com/gitolite/doc/report-output.html#_using_patterns_to_limit_output
+[gitconf]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html#_repo_specific_git_config_commands

doc/mirroring.mkd

@@ -1,4 +1,4 @@
-# mirroring gitolite servers
+## mirroring gitolite servers
 
 Mirroring a repo is simple in git; you just need code like this in a
 `post-receive` hook in each repo: