Q: all doc stuff

doc/add.mkd

@@ -0,0 +1,34 @@
+# adding users and repos
+
+Do NOT add repos directly on the server.  Clone the 'gitolite-admin' repo to
+your workstation, make changes to it, then add, commit, and push.  When the
+push hits the server, the server "acts" upon your changes.
+
+Full documentation on the conf file is [here][conf].
+
+Here's a sample sequence, on your workstation, after your install is done
+
+    git clone git@host:gitolite-admin
+    cd gitolite-admin
+    vi conf/gitolite.conf
+
+    # now add lines like these:
+        repo foo
+            RW+ =   me
+            RW  =   alice
+            R   =   wally
+    # now save the file and add it
+    git add conf
+
+    # add a couple of users; get their pubkeys by email or something, then:
+    cp /some/where/alice.pub keydir
+    cp /else/where/wally.pub keydir
+    git add keydir
+
+    # now commit and push
+    git commit -m 'added repo foo'
+    git push
+
+    # at this point gitolite will create the new repo 'foo' (if it did not
+    # already exist) then update the authorized keys file to include alice and
+    # wally's pubkeys

doc/commands.mkd

@@ -0,0 +1,26 @@
+# gitolite "commands"
+
+Gitolite comes with several commands that users can run.  Remote user run the
+commands by saying:
+
+    ssh git@host command-name [args...]
+
+while on the server you can run
+
+    gitolite command [args...]
+
+Very few commands are designed to be run both ways, but it can be done, by
+checking for the presence of env var `GL_USER`.
+
+You can get a **list of available commands** by using the `help` command.
+Naturally, a remote user will see only a subset of what the server user will
+see.
+
+You add commands to the "allowed from remote" list by adding its name (or
+uncommenting it if it's already added but commented out) to the COMMANDS hash
+in the [rc][] file.
+
+If you write your own commands, put them in src/commands.
+
+**Note that this is also the place that all triggered programs go**.  In fact,
+all standalone programs related to gitolite go here.

doc/conf.mkd

@@ -0,0 +1,31 @@
+# the gitolite.conf file
+
+This file is the crux of all of gitolite's access control.  The basic syntax
+is very simple.
+
+Note: `<user>+` means one or more user or user group names, `<repo>+` means
+one or more repo or repo group names, and `<refex>*` means zero or more
+refexes.
+
+  * [group][group] definitions (optional, for convenience)
+
+        @<group> = <user>+
+        @<group> = <repo>+
+
+  * [repo][repo] definitions and access [rules][]
+
+        repo <repo>+
+            <perm>  <refex>*    =   <user>+
+            # one or more such lines
+
+  * [gitolite options][options] that apply to the repo(s) in the last
+    "repo ..." line, for example:
+
+            option deny-rules = 1
+
+  * [git config][git-config] keys and values that also apply to the last named
+    repo(s), for example:
+
+            config hooks.emailprefix = '[%GL_REPO] '
+
+In addition, you can also have [include][] statements.

doc/cust.mkd

@@ -0,0 +1,23 @@
+# customising gitolite
+
+Here are the ways you can customise gitolite on the server.
+
+First, learn about:
+
+  * [git hooks][hooks] and [virtual refs][vref]
+
+  * [commands][] for your [users][] to run own][dev-notes]
+
+  * [triggers][] to be run by gitolite as various points in its execution
+
+  * [syntactic sugar][sugar] to change the conf language for your convenience
+
+For all of the above:
+
+  * [edit the rc file][rc] to enable optional features that are shipped in a
+    disabled state
+
+  * [write your own][dev-notes]
+
+(Note: "trigger" is the same concept as "hook", applied to gitolite; I just
+chose a different name to avoid constant ambiguity in documentation).

doc/dev-notes.mkd

@@ -0,0 +1,116 @@
+# notes for developers
+
+Gitolite has a huge bunch of existing features that gradually need to moved
+over.  Plus you may want to write your own programs to interact with it.
+
+Hints for developers wishing to help migrate features over from g2 are
+[here][dev-hints].
+
+Here are some random notes on developing hooks, commands, triggers, and sugar
+scripts.
+
+## environment variables
+
+In general, the following environment variables should always be available:
+
+    GL_BINDIR
+    GL_REPO_BASE
+    GL_ADMIN_BASE
+
+Commands invoked by a remote client will also have `GL_USER` set.  Hooks will
+have `GL_REPO` also set.
+
+## APIs
+
+### the shell API
+
+The following commands exist to help you write shell scripts that interact
+easily with gitolite.  Each of them responds to `h` so please run that for
+more info.
+
+  * `gitolite access` to check access rights given repo, user, type of access
+    (R, W, ...) and refname (optional).  Example use: src/commands/desc
+
+  * `gitolite creator` to get/check the creator of a repo.  Example use:
+    src/commands/desc
+
+  * `gitolite git-config` to check gitolite options or git config variables
+    directly from gitolite's "compiled output, (i.e., without looking at the
+    actual `repo.git/config` file or using the `git config` command).  Example
+    use: none yet
+
+  * `gitolite query-rc` to check the value of an RC variable.  Example use:
+    src/commands/desc.
+
+In addition, you can also look at the comments in src/Gitolite/Easy.pm (the
+perl API module) for ideas.
+
+### the perl API
+
+...is implemented by Gitolite::Easy; see src/Gitolite/Easy.pm.  This is a work
+in progress; for example it does not yet have the equivalent of `gitolite
+git-config`.  I'll add it when I or someone else needs it.
+
+## your own hooks
+
+### anything but the update hook
+
+If you want to add your own hook, it's easy as long as it's not the 'update'
+hook.  Just add it to `$HOME/.gitolite/hooks/common` and run `gitolite setup`.
+
+The rest is between you and 'man githooks' :-)
+
+### update hook
+
+If you want to add additional `update` hook functionality, do this:
+
+  * write and test your update hook separately from gitolite
+
+  * now add the code to src/VREF.  Let's say it is called "foo".
+
+  * to call your new update hook to all accesses for all repos, add this to
+    the end of your conf file:
+
+        repo @all
+            -       VREF/foo        =   @all
+
+As you probably guessed, you can now make your additional update hooks more
+selective, applying them only to some repos / users / combinations.
+
+Note: a normal update hook expects 3 arguments (ref, old SHA, new SHA).  A
+VREF will get those three, followed by at least 4 more.  Your VREF should just
+ignore the extra args.
+
+## your own commands
+
+You can add your own commands.  You can run them on the server (example,
+`gitolite access`).  Then you can enable certain commands to be allowed to run
+by a remote user by adding them to the "COMMANDS" hash of the [rc][] file.
+
+Commands are standalone programs, in any language you like.  They simply
+receive the arguments you append.  In addition, the env var `GL_USER` is
+available if it is being run remotely.  src/commands/desc is the best example
+at present.
+
+## your own trigger programs
+
+Trigger programs are just commands whose names have been added to the
+appropriate list in the [rc][] file.  Triggers get specific arguments
+depending on when they are called; see [here][triggers] for details.
+
+You can write programs that are both manually runnable as well as callable by
+trigger events, especially if they don't *need* any arguments.
+
+Look in the distributed [rc][] file for example programs; at this point there
+aren't many.
+
+## your own "sugar"
+
+Syntactic sugar helpers are NOT complete, standalone, programs.  They must
+include a perl sub called `sugar_script` that takes in a listref, and returns
+a listref.  The listrefs point to a list that contains the entire conf file
+(with all [include][] processing already done).  You create a new list with
+contents modified as you like and return a ref to it.
+
+There are a couple of examples in src/syntactic-sugar.
+

doc/dev-status.mkd

@@ -0,0 +1,35 @@
+## #dev-status g3 development status
+
+Not yet done (will be tackled in this order unless someone asks):
+
+  * detailed documentation for new features
+  * querying the outside world for group info (see gl-get-membership-program
+    in g2)
+  * mirroring
+  * pulling in documentation for things that are the same in g2
+  * "unrestricted arguments" for some ADCs (like git-annexe)
+  * smart http
+  * special features (no-create-repos, shell-access, gl-all-read-all, etc)
+
+Help needed:
+
+  * I'd like distro packagers to play with it and help with migration advice
+    for distro-upgrades
+  * [rsync][pw2], htpasswd
+  * git-annexe support (but this has a pre-requisite in the previous list)
+
+Won't be done unless someone asks (saw no evidence that anyone used them in g2
+anyway!):
+
+  * mob branches
+  * password access
+  * specific ADCs -- there are too many for me to bother without applying
+    Pareto somewhere, so I choose to not do any and wait for people to ask :-)
+
+Done:
+
+  * core code
+  * test suite
+  * some documentation
+  * distro packaging instructions
+  * migration advice for common cases

doc/extras/auth.mkd

@@ -0,0 +1,89 @@
+# authentication versus authorisation
+
+This document will explain why an "ssh issue" is almost never a "gitolite
+issue", and, indirectly, why I dont get too excited about the former.
+
+Note: for actual ssh troubleshooting see [this][ssh-troubleshooting].
+
+Here is a fundamental point: <font color="red">**Gitolite does not do
+authentication.  It only does authorisation**.</font>
+
+So first, let's loosely define these words:
+
+>   **Authentication** is the process of verifying that you are who you claim
+>   to be.  An authentication system will establish that I am the user
+>   "sitaram" on my work system.  The one behind gmail will similarly
+>   establish that I am "sitaramc".  And so on...
+
+>   **Authorisation** is the process of asking what you want to do and
+>   deciding if you're allowed to do it or not.
+
+Now, if you managed to read about [gitolite and ssh][gitolite-and-ssh], you
+know that gitolite is meant to be invoked as:
+
+    /full/path/to/gl-auth-command some-authenticated-gitolite-username
+
+(where the "gitolite username" is a "virtual" username; it does not have to
+be, and usually *isn't*, an actual *unix* username).
+
+As you can see, authentication happens before gitolite is called.
+
+## but... but... you have all that ssh stuff in there!
+
+The default mode of using gitolite does use ssh keys, but all it's doing is
+helping you **setup** ssh-based authentication **as a convenience to you**.
+
+You don't have to use it, though.  And many people don't.  The examples I know
+are [smart http][http], and ldap-backed sshd.  In both cases, gitolite has no
+role to play in creating users, setting up their passwords/keys, etc.  There's
+even a `GL_NO_SETUP_AUTHKEYS` option to make sure gitolite doesn't meddle with
+the authkeys file in such installations.
+
+## so you're basically saying you won't support "X"
+
+(where "X" is some ssh related behaviour change or feature)
+
+Well, if it's not a security issue I *probably* won't.  I'm willing to change
+my mind if enough people convince me they need it.  (There's a mailing list if
+you want to find others who also need the same thing.)
+
+While we're on the subject, locking someone out is *not* a security issue.
+Even if you locked yourself (the admin) out, the docs tell you how to recover
+from such errors.  You do need some password based method to get a shell
+command line on the server, of course.
+
+## appendix: how to use other authentication systems with gitolite
+
+The bottom line in terms of how to invoke gitolite has been described above,
+and as long as you manage to do that gitolite won't even know how the
+authentication was done.  Which in turn means you can use whatever
+authentication scheme you want.
+
+It also expects the `SSH_ORIGINAL_COMMAND` environment variable to contain the
+full command (typically starting with git-receive-pack or git-upload-pack)
+that the client sent.  Also, when using [smart http][http], things are somewhat
+different: gitolite uses certain environment variables that it expects httpd
+to have set up.  Even the user name comes from the `REMOTE_USER` environment
+variable instead of as a command line argument in this case.
+
+However, it has to be an authentication system that is compatible with sshd or
+httpd in some form.  Why?  Because the git *client* accessing the server only
+knows those 2 protocols to "speak git".  (Well, the `git://` protocol is
+unauthenticated, and `file://` doesn't really apply to this discussion, so
+we're ignoring those).
+
+For example, let's say you have an LDAP-based authentication system somewhere.
+It is possible to make apache use that to authenticate users, so when a user
+accesses a git url using `http://sitaram:password@git.example.com/repo`, it is
+LDAP that does the actual authentication.  [I wouldn't know how to do it but I
+know it is possible.  Patches to this doc explaining how are welcome!]
+
+There are also ssh daemons that use LDAP to store the authorised keys (instead
+of putting them all in `~/.ssh/authorized_keys`).  The clients will still need
+to generate keypairs and send them to the admin, but they can be more
+centrally stored and perhaps used by other programs or tools simultaneously,
+which can be useful.
+
+Finally, gitolite allows you to store *group* information externally too.  See
+[here][ldap] for more on this.
+