Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

MASSIVE set of changes to documents!

I got tired of being told "TL;DR".  Now the online versions of most
documents fit on a page or two, or at least most of them do.  The rest
has been split out (and you can see the links to the split out sections
right where the text is in the raw Markdown).

This is much more pleasant to read, and I've improved the linking so
it's much less effort for me to keep the links correct.
  • Loading branch information...
commit 6e29365316f93b7039a23937bde0e69dd0294bce 1 parent 3f87430
@sitaramc authored
Showing with 1,080 additions and 2,592 deletions.
  1. +7 −219 README.mkd
  2. +2 −11 contrib/adc/{README.mkd → README-adc.mkd}
  3. +8 −32 contrib/adc/hub.mkd
  4. +3 −6 contrib/adc/repo-deletion.mkd
  5. +17 −68 contrib/adc/sskm.mkd
  6. +1 −1  contrib/gerrit.mkd
  7. +1 −1  contrib/gitolite-tools.mkd
  8. +2 −5 contrib/ldap/{README.mkd → README-ldap.mkd}
  9. +17 −67 contrib/mirroring-complex-example.mkd
  10. +1 −1  {doc → contrib}/monkeysphere.mkd
  11. +15 −60 contrib/putty.mkd
  12. +10 −21 contrib/real-users/password-access.mkd
  13. +1 −2  contrib/vim/{README.mkd → README-vim.mkd}
  14. +4 −8 doc/1000-words.mkd
  15. +18 −77 doc/admin-defined-commands.mkd
  16. +46 −158 doc/{2-admin.mkd → admin.mkd}
  17. +8 −23 doc/{authentication-vs-authorisation.mkd → auth.mkd}
  18. +151 −174 doc/big-config.mkd
  19. +8 −32 doc/delegation.mkd
  20. +10 −44 doc/developer-notes.mkd
  21. +8 −27 doc/gitolite-and-ssh.mkd
  22. +16 −62 doc/gitolite-gitweb-http-backend.mkd
  23. +9 −30 doc/gitolite.conf-by-example.mkd
  24. +130 −171 doc/gitolite.conf.mkd
  25. +29 −64 doc/gitolite.rc.mkd
  26. +10 −38 doc/hook-propagation.mkd
  27. +10 −44 doc/http-backend.mkd
  28. +205 −0 doc/index.mkd
  29. +114 −199 doc/{1-INSTALL.mkd → install.mkd}
  30. +6 −7 doc/migrate.mkd
  31. +40 −118 doc/mirroring.mkd
  32. +1 −1  doc/mob-branches.mkd
  33. +13 −49 doc/nagp.mkd
  34. +0 −57 doc/overkill.mkd
  35. +1 −1  doc/packaging.mkd
  36. +6 −28 doc/progit-article.mkd
  37. +8 −29 doc/report-output.mkd
  38. +0 −86 doc/shell-games.mkd
  39. +27 −113 doc/ssh-troubleshooting.mkd
  40. +58 −224 doc/{3-faq-tips-etc.mkd → tips-notes.mkd}
  41. +0 −67 doc/uninstall.mkd
  42. +28 −64 doc/{user-manual.mkd → user.mkd}
  43. +1 −3 doc/who-uses-it.mkd
  44. +24 −76 doc/wildcard-repositories.mkd
  45. +6 −24 t/{README.mkd → README-t.mkd}
View
226 README.mkd
@@ -1,221 +1,9 @@
-# Hosting git repositories
+# Gitolite README
-<a name="start"></a>
+If you're really impatient, and you're familiar with Unix and ssh, follow the
+[quick install](http://sitaramc.github.com/gitolite/index.html#qi)
+instructions.
-Gitolite allows you to setup git hosting on a central server, with
-fine-grained access control and many (many!) more powerful features.
-
-----
-
-In this document:
-
- * <a href="#_quick_install">quick install</a>
- * <a href="#_what">what</a>
- * <a href="#_documentation">documentation</a>
- * <a href="#_why">why</a>
- * <a href="#_main_features">main features</a>
- * <a href="#_security">security</a>
- * <a href="#_contact_and_license">contact and license</a>
-
-----
-
-<a name="_quick_install"></a>
-
-### quick install
-
-If you're comfortable with Unix and ssh, the following steps should work.
-<font color="gray">(However, gitolite has lots and lots of useful features;
-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
- cd gitolite
- src/gl-system-install
- gl-setup ~/YourName.pub
-
-You're done.
-
-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
-
-<a name="_what"></a>
-
-### what
-
-Gitolite is an access control layer on top of git. Here's an "executive
-summary":
-
- * use a single unix user ("real" user) on the server
- * provide access to many gitolite users
- * they are not "real" users
- * they do not get shell access
- * control access to many git repositories
- * read access controlled at the repo level
- * write access controlled at the branch/tag/file/directory level,
- including who can rewind, create, and delete branches/tags
- * can be installed without root access, assuming git and perl are already
- installed
- * authentication is most commonly done using sshd, but you can also use
- httpd if you prefer (this may require root access).
- * several other neat features described below and elsewhere in the
- [doc/][docs] directory.
-
-<a name="_documentation"></a>
-
-#### documentation
-
-Gitolite comes with a **huge** amount of documentation. Almost all of it is
-for the *administrator* of a gitolite server. If you're a *user*, you only
-need [this][user].
-
-Otherwise, the suggested reading order is this:
-
- * the README (this document) for a quick intro
- * the [INSTALL][install] document
- * the most common installation issues are caused by ssh. Here's how
- [gitolite uses ssh][doc9gas]. And here's an [ssh trouble
- shooting][doc6sts] document
- * the [ADMIN][admin] document
- * (if you're migrating from gitosis, read [this][migr])
-
-There is also a **[master TOC of all gitolite documentation][docs]**; use your
-browser's search function to look for likely sounding words or just browse
-around -- you never know what you'll find!
-
-[Here][who]'s some information on some of the projects and
-people using gitolite (and who, in turn, have helped shape its features).
-
-<a name="_why"></a>
-
-### why
-
-Gitolite is separate from git, and needs to be installed and configured. So...
-why do we bother?
-
-Gitolite is useful in any server that is going to host multiple git
-repositories, each with many developers, where some sort of access control is
-required.
-
-In theory, this can be done with plain old Unix permissions: each user is a
-member of one or more groups, each group "owns" one or more repositories, and
-using unix permissions (especially the setgid bit -- `chmod g+s`) you can
-allow/disallow users access to repos.
-
-But there are several disadvantages here:
-
- * every user needs a userid and password on the server. This is usually a
- killer, especially in tightly controlled environments
- * adding/removing access rights involves complex `usermod -G ...` mumblings
- which most admins would rather not deal with
- * *viewing* (aka auditing) the current set of permissions requires running
- multiple commands to list directories and their permissions/ownerships,
- users and their group memberships, and then correlating all these manually
- * auditing historical permissions or permission changes is pretty much
- impossible without extraneous tools
- * errors or omissions in setting the permissions exactly can cause problems
- of either kind: false accepts or false rejects
- * without going into ACLs it is not possible to give some people read-only
- access while some others have read-write access to a repo (unless you make
- it world-readable). Group access just doesn't have enough granularity
- * it is absolutely impossible to restrict pushing by branch name or tag
- name.
-
-Gitolite does away with all this:
-
- * it uses ssh magic to remove the need to give actual unix userids to
- developers
- * it uses a simple but powerful config file format to specify access rights
- * access control changes are affected by modifying this file, adding or
- removing user's public keys, and "compiling" the configuration
- * this also makes auditing trivial -- all the data is in one place, and
- changes to the configuration are also logged, so you can audit them.
- * finally, the config file allows distinguishing between read-only and
- read-write access, not only at the repository level, but at the branch
- level within repositories.
-
-<a name="_main_features"></a>
-
-### main features
-
-The most important feature I needed was **per-branch permissions**. This is
-pretty much mandatory in a corporate environment, and is almost the single
-reason I started *thinking* about writing gitolite.
-
-It's not just "read-only" versus "read-write". Rewinding a branch (aka "non
-fast forward push") is potentially dangerous, but sometimes needed. So is
-deleting a branch (which is really just an extreme form of rewind). I needed
-something in between allowing anyone to do it (the default) and disabling it
-completely (`receive.denyNonFastForwards` or `receive.denyDeletes`).
-
-Here're **some more features**. All of them, and more, are documented in
-detail somewhere in gitolite's [doc/][docs] subdirectory.
-
- * simple, yet powerful, config file syntax, including specifying
- gitweb/daemon access. You'll need this power if you manage lots of
- users+repos+combinations of access
- * apart from branch-name based restrictions, you can also restrict by
- file/dir name changed (i.e., output of `git diff --name-only`)
- * if your requirements are still too complex, you can split up the config
- file and delegate authority over parts of it
- * easy to specify gitweb owner, description and gitweb/daemon access
- * easy to sync gitweb (http) authorisation with gitolite's access config
- * comprehensive logging [aka: management does not think "blame" is just a
- synonym for "annotate" :-)]
- * "personal namespace" prefix for each dev
- * migration guide and simple converter for gitosis conf file
- * "exclude" (or "deny") rights at the branch/tag level
- * specify repos using patterns (patterns may include creator's name)
- * define powerful operations on the server side, even github-like forking
-
-<a name="_security"></a>
-
-### security
-
-Due to the environment in which this was created and the need it fills, I
-consider this a "security" program, albeit a very modest one.
-
-For the first person to find a security hole in it, defined as allowing a
-normal user (not the gitolite admin) to read a repo, or write/rewind a ref,
-that the config file says he shouldn't, and caused by a bug in *code* that is
-in the "master" branch, (not in the other branches, or the configuration file
-or in Unix, perl, shell, etc.)... well I can't afford 1000 USD rewards like
-djb, so you'll have to settle for 5000 INR (Indian Rupees) as a "token" prize
-:-)
-
-However, there are a few optional features (which must be explicitly enabled
-in the RC file) where I just haven't had the time to reason about security
-thoroughly enough. Please read the comments in `conf/example.gitolite.rc` for
-details, looking for the word "security".
-
-----
-
-<a name="_contact_and_license"></a>
-
-### contact and license
-
-Gitolite is released under GPL v2. See COPYING for details.
-
- * author: sitaramc@gmail.com, sitaram@atc.tcs.com
- * mailing list: gitolite@googlegroups.com
- * list subscribe address : gitolite+subscribe@googlegroups.com
-
-[transcript]: http://sitaramc.github.com/gitolite/doc/install-transcript.html
-[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
-[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
-[tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial
-[docs]: http://sitaramc.github.com/gitolite
-[user]: http://sitaramc.github.com/gitolite/doc/user-manual.html
+But if you want to do anything meaningful with gitolite you have to spend some
+time cuddling up to the docs. **The complete online documentation starts
+[here](http://sitaramc.github.com/gitolite)**.
View
13 contrib/adc/README.mkd → contrib/adc/README-adc.mkd
@@ -1,4 +1,4 @@
-## brief descriptions of the shipped ADCs (admin-defined commands)
+# F=shipped_ADCs brief descriptions of the shipped ADCs (admin-defined commands)
(...with pointers to further information where needed)
@@ -8,19 +8,14 @@
or other admin chores); details [here][able]. This ADC is meant only for
admins.
-[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.
@@ -36,14 +31,10 @@ 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
+> two families of repo deletion commands; details [here][wild_repodel]
**sudo**: allow admin to run ADCs on behalf of a user. Useful in support
situations I guess. Details in source.
View
40 contrib/adc/hub.mkd
@@ -1,18 +1,6 @@
-## the 'hub' ADC
+# F=hub the 'hub' ADC
-In this document:
-
- * <a href="#_a_home_grown_hub_for_git_repos">a home grown 'hub' for git repos</a>
- * <a href="#_general_syntax">general syntax</a>
- * <a href="#_Bob_s_commands">Bob's commands</a>
- * <a href="#_Alice_s_just_looking_commands">Alice's "just looking" commands</a>
- * <a href="#_Alice_s_action_commands">Alice's "action" commands</a>
- * <a href="#_what_next_">what next?</a>
- * <a href="#_note_to_the_admin_configuration_variables">note to the admin: configuration variables</a>
-
-<a name="_a_home_grown_hub_for_git_repos"></a>
-
-### a home grown 'hub' for git repos
+## a home grown 'hub' for git repos
This ADC (admin-defined command) helps collaboration among repos. The name is
in honor of github, which is the primary host for gitolite itself.
@@ -51,17 +39,13 @@ do a normal `git fetch [origin]` to get it to her workstation. This has the
added advantage that other people, who may be watching her repo but not Bob's,
now get to see what Bob sent her and send comments etc.
-<a name="_general_syntax"></a>
-
-### general syntax
+## general syntax
The general syntax is
ssh git@server hub <hub-command> <args>
-<a name="_Bob_s_commands"></a>
-
-#### Bob's commands
+### Bob's commands
The following commands do not cause a fetch, and should be quite fast:
@@ -92,9 +76,7 @@ The following commands do not cause a fetch, and should be quite fast:
ssh git@server hub request-status child [parent] request-number
-<a name="_Alice_s_just_looking_commands"></a>
-
-#### Alice's "just looking" commands
+### Alice's "just looking" commands
* Alice lists requests waiting for her to check and possibly pull into
parent. For each waiting pull request, she will see a serial number, the
@@ -140,9 +122,7 @@ The following commands do not cause a fetch, and should be quite fast:
to ADCs, you probably can't do things like `pu^` or `master~3`, and have
to use SHAs instead.
-<a name="_Alice_s_action_commands"></a>
-
-#### Alice's "action" commands
+### Alice's "action" commands
* Alice doesn't like what she sees and decides to reject it. This command
expects some text on STDIN as the rejection message:
@@ -179,9 +159,7 @@ The following commands do not cause a fetch, and should be quite fast:
Notice the sequence of Alice's action commands: it's either 'reject', or a
'fetch' then 'accept'.
-<a name="_what_next_"></a>
-
-### what next?
+## what next?
At this point, you're done with the `hub` ADC. However, all this is on the
bare `parent.git` on the server, and nothing has hit Alice's workstation yet!
@@ -195,9 +173,7 @@ Finally, note that Alice does not actually need to use the `fetch` subcommand.
She can do the traditional thing and fetch Bob's repo/branch directly to her
*workstation*.
-<a name="_note_to_the_admin_configuration_variables"></a>
-
-### note to the admin: configuration variables
+## note to the admin: configuration variables
There are 2 configuration variables. `BASE_FETCH_URL` should be set to a
simple "read" URL (so it doesn't even have to be ssh) that almost anyone using
View
9 contrib/adc/repo-deletion.mkd
@@ -1,11 +1,8 @@
-## deleting repos safely
+# F=wild_repodel deleting repos safely
-**NOTE**: this page is about deleting [user-created repos][wcr]. It is
+**NOTE**: this page is about deleting [user-created repos][wild]. 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
+gitolite.conf file itself) -- to delete those read [here][repodel].
(see [this thread][thr] on the gitolite mailing list)
View
85 contrib/adc/sskm.mkd
@@ -1,38 +1,16 @@
-## changing keys -- self service key management
+# F=sskm changing keys -- self service key management
Follow this guide to add keys to or remove keys from your account. Note that you cannot use this method to add your *first* key to the account; you must still email your initial key to your admin.
The key management is done using an ADC (admin-defined command) called `sskm`.
-In this document:
-
- * <a href="#_Important_">Important!</a>
- * <a href="#_Key_fingerprints">Key fingerprints</a>
- * <a href="#_Active_keys">Active keys</a>
- * <a href="#_Selecting_which_key_to_use">Selecting which key to use</a>
- * <a href="#_Public_vs_private_keys">Public vs. private keys</a>
- * <a href="#_Listing_your_existing_keys">Listing your existing keys</a>
- * <a href="#_Adding_or_Replacing_a_key">Adding or Replacing a key</a>
- * <a href="#_Step_1_Adding_the_Key">Step 1: Adding the Key</a>
- * <a href="#_Step_2_Confirming_the_addition">Step 2: Confirming the addition</a>
- * <a href="#_Optional_Undoing_a_mistaken_add_before_confirmation_">Optional: Undoing a mistaken add (before confirmation)</a>
- * <a href="#_Removing_a_key">Removing a key</a>
- * <a href="#_Step_1_Mark_the_key_for_deletion">Step 1: Mark the key for deletion</a>
- * <a href="#_Step_2_Confirming_the_deletion">Step 2: Confirming the deletion</a>
- * <a href="#_Optional_Undoing_a_mistaken_delete_before_confirmation_">Optional: Undoing a mistaken delete (before confirmation)</a>
- * <a href="#_important_notes_for_the_admin">important notes for the admin</a>
-
----
-<a name="_Important_"></a>
-
-### Important!
+## Important!
There are a few things that you should know before using the key management system. Please do not ignore this section!
-<a name="_Key_fingerprints"></a>
-
-#### Key fingerprints
+### Key fingerprints
Keys are identified in some of these subcommands by their fingerprints. To see the fingerprint for a public key on your computer, use the following syntax:
@@ -43,18 +21,13 @@ You'll get output like:
jeff@baklava ~ $ ssh-keygen -l -f .ssh/jeffskey.pub
2048 2d:78:d4:2c:b1:6d:9a:dc:d9:0d:94:3c:d8:c2:65:44 .ssh/jeffskey.pub (RSA)
-
-<a name="_Active_keys"></a>
-
-#### Active keys
+### Active keys
Any keys that you can use to interact with the system are active keys. (Inactive keys are keys that are, for instance, scheduled to be added or removed.) Keys are identified with their `keyid`; see the section below on listing keys.
If you have no current active keys, you will be locked out of the system (in which case email your admin for help). Therefore, be sure that you are never removing your only active key!
-<a name="_Selecting_which_key_to_use"></a>
-
-#### Selecting which key to use
+### Selecting which key to use
Although you can identify yourself to the Gitolite system with any of your active keys on the server, at times it is necessary to specifically pick which key you are identifying with. To pick the key to use, pass the `-i` flag into `ssh`:
@@ -75,15 +48,11 @@ disable the agent, using one of these commands:
* If using `keychain`, run `keychain --clear` to remove identities
* Unset the `SSH_AUTH_SOCK` and `SSH_AGENT_PID` variables in the current shell
-<a name="_Public_vs_private_keys"></a>
-
-#### Public vs. private keys
+### Public vs. private keys
In this guide, all keys are using their full suffix. In other words, if you see a `.pub` at the end of a key, it's the public key; if you don't, it's the private key. For instance, when using the `-i` flag with `ssh`, you are specifying private keys to use. When you are submitting a key for addition to the system, you are using the public key.
-<a name="_Listing_your_existing_keys"></a>
-
-### Listing your existing keys
+## Listing your existing keys
To see a list of your existing keys, use the `list` argument to `sskm`:
@@ -103,13 +72,9 @@ use any keyid you wish when adding keys (like `@home`, `@laptop`, ...); the
only rules are that it must start with the `@` character and after that
contain only digits, letters, or underscores.
-<a name="_Adding_or_Replacing_a_key"></a>
-
-### Adding or Replacing a key
+## Adding or Replacing a key
-<a name="_Step_1_Adding_the_Key"></a>
-
-#### Step 1: Adding the Key
+### Step 1: Adding the Key
Adding and replacing a key is the same process. What matters is the `keyid`. When adding a new key, use a new `keyid`; when replacing a key, pass in the `keyid` of the key you want to replace, as found by using the `list` subcommand. Pretty simple!
@@ -132,9 +97,7 @@ If you now run the `list` command you'll see that it's scheduled for addition:
== keys marked for addition/replacement ==
1: ff:92:a2:20:6d:42:6b:cf:20:e8:a2:4a:3b:b0:32:3a : jeff@key4.pub
-<a name="_Step_2_Confirming_the_addition"></a>
-
-#### Step 2: Confirming the addition
+### Step 2: Confirming the addition
Gitolite uses Git internally to store the keys. Just like with Git, where you commit locally before `push`-ing up to the server, you need to confirm the key addition (see the next section if you made a mistake). We use the `confirm-add` subcommand to do this, *but*: to verify that you truly have ownership of the corresponding private key, you *must* use the key you are adding itself to do the confirmation! (Inconvenient like most security, but very necessary from a security perspective.) This is where using the `-i` flag of `ssh` comes in handy:
@@ -152,9 +115,7 @@ Listing keys again shows that all four keys are now active:
3: 2d:78:d4:2c:b1:6d:9a:dc:d9:0d:94:3c:d8:c2:65:44 : jeff@key3.pub
4: ff:92:a2:20:6d:42:6b:cf:20:e8:a2:4a:3b:b0:32:3a : jeff@key4.pub
-<a name="_Optional_Undoing_a_mistaken_add_before_confirmation_"></a>
-
-#### Optional: Undoing a mistaken add (before confirmation)
+### Optional: Undoing a mistaken add (before confirmation)
Another advantage of Gitolite using Git internally is that that if we mistakenly add the wrong key, we can undo it before it's confirmed by passing in the `keyid` we want to remove into the `undo-add` subcommand:
@@ -171,13 +132,9 @@ Listing the keys shows that that new key has been removed:
2: 61:38:a7:9f:ba:cb:99:81:4f:49:2c:8b:c8:63:8e:33 : jeff@key2.pub
3: 2d:78:d4:2c:b1:6d:9a:dc:d9:0d:94:3c:d8:c2:65:44 : jeff@key3.pub
-<a name="_Removing_a_key"></a>
-
-### Removing a key
-
-<a name="_Step_1_Mark_the_key_for_deletion"></a>
+## Removing a key
-#### Step 1: Mark the key for deletion
+### Step 1: Mark the key for deletion
Deleting a key works very similarly to adding a key, with `del` substituted for `add`.
@@ -211,9 +168,7 @@ Listing the keys now shows that it is marked for deletion:
== keys marked for deletion ==
1: ff:92:a2:20:6d:42:6b:cf:20:e8:a2:4a:3b:b0:32:3a : jeff@key4.pub
-<a name="_Step_2_Confirming_the_deletion"></a>
-
-#### Step 2: Confirming the deletion
+### Step 2: Confirming the deletion
Just like with Git, where you commit locally before `push`-ing up to the server, you need to confirm the key addition (see the next section if you made a mistake). We use the `confirm-del` subcommand to do this, *but*: unlike the `confirm-add` subcommand, you *must* use a *different* key than the key you are deleting to do the confirmation! This prevents you from accidentally locking yourself out of the system by removing all active keys:
@@ -230,9 +185,7 @@ Listing keys again shows that the fourth key has been removed:
2: 61:38:a7:9f:ba:cb:99:81:4f:49:2c:8b:c8:63:8e:33 : jeff@key2.pub
3: 2d:78:d4:2c:b1:6d:9a:dc:d9:0d:94:3c:d8:c2:65:44 : jeff@key3.pub
-<a name="_Optional_Undoing_a_mistaken_delete_before_confirmation_"></a>
-
-#### Optional: Undoing a mistaken delete (before confirmation)
+### Optional: Undoing a mistaken delete (before confirmation)
Another advantage of Gitolite using Git internally is that that if we mistakenly delete the wrong key, we can undo it before it's confirmed by passing in the `keyid` we want to keep into the `undo-del` subcommand. Note that this operation *must* be performed using the private key that corresponds to the key you are trying to keep! (Security reasons, similar to the reason that you must confirm an addition this way; it prevents anyone from undoing a deletion, and therefore keeping in the system, a key that they cannot prove (by having the corresponding private key) should stay in the system):
@@ -260,9 +213,7 @@ Listing the keys shows that that new key is now marked active again:
----
-<a name="_important_notes_for_the_admin"></a>
-
-### important notes for the admin
+## important notes for the admin
These are the things that can break if you enable this ADC for your users:
@@ -279,10 +230,8 @@ These are the things that can break if you enable this ADC for your users:
So, if you have the same *filename* in different subdirectories of
`keydir`, you can't use this tool.
- * keys placed in specific folders (perhaps to do [this][optak], or for
+ * keys placed in specific folders (perhaps to do [this][authkeyopt], or for
whatever other reasons), will probably not stay in those folders if this
ADC is used. Even a key delete, followed by undoing the delete, will
cause the key to effectively move to the root of the key store (i.e., the
`keydir` directory in the gitolite-admin repo).
-
-[optak]: http://sitaramc.github.com/gitolite/doc/big-config.html#_optimising_the_authkeys_file
View
2  contrib/gerrit.mkd
@@ -1,4 +1,4 @@
-## comparing gerrit and gitolite
+# F=gerrit comparing gerrit and gitolite
Gerrit and gitolite have too many high level differences. Size is most
visible of course: 56000 lines of Java versus 1300 lines of perl+shell,
View
2  contrib/gitolite-tools.mkd
@@ -1,4 +1,4 @@
-## gitolite-tools
+# F=_gitolite_tools gitolite-tools
gitolite-tools is a collection of external git commands to work with
gitolite server and repositories:
View
7 contrib/ldap/README.mkd → contrib/ldap/README-ldap.mkd
@@ -1,20 +1,17 @@
-## ldap helper programs
+# F=ldap_helpers ldap helper programs
These programs were contributed by the Nokia MeeGo folks.
The first 2 are perl and shell verisions of programs meant to be used as
`$GL_GET_MEMBERSHIPS_PGM` (see [this][ldap] for more).
-
* ldap-query-example.pl
* ldap-query-example.sh
The third program is meant to be installed as an adc (admin-defined command,
-see [here][adc]), and helps users change their LDAP passwords.
+see [here][ADCs]), and helps users change their LDAP passwords.
* passwd
Enjoy!
-[ldap]: http://sitaramc.github.com/gitolite/doc/big-config.html#_storing_usergroup_information_outside_gitolite_like_in_LDAP_
-[adc]: http://sitaramc.github.com/gitolite/doc/admin-defined-commands.html
View
84 contrib/mirroring-complex-example.mkd
@@ -1,33 +1,9 @@
-## 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
+# F=mirr_complex_example semi-autonomous mirroring setup example
This document describes one way to do this. Gitolite is powerful so you can
probably find other ways to suit you.
-In this document:
-
- * <a href="#_overview_of_problem">overview of problem</a>
- * <a href="#_overview_of_setup">overview of setup</a>
- * <a href="#_gitolite_feature_recap">gitolite feature recap</a>
- * <a href="#_pre_requisites">pre-requisites</a>
- * <a href="#_quick_setup">quick setup</a>
- * <a href="#_step_by_step">step by step</a>
- * <a href="#_1_gitolite_conf_">(1) `gitolite.conf`</a>
- * <a href="#_2_master_sam_conf_">(2) `master/sam.conf`</a>
- * <a href="#_3_host_admins_only_master_sam_p1_conf_">(3) host admins only -- `master/sam/p1.conf`</a>
- * <a href="#_4_mirrors_sam_p1_conf_">(4) `mirrors/sam/p1.conf`</a>
- * <a href="#_5_slave_frodo_sam_conf_">(5) `slave/frodo/sam.conf`</a>
- * <a href="#_6_manual_sync">(6) manual sync</a>
- * <a href="#_next_steps">next steps</a>
- * <a href="#_appendix_A_delegation_helper_files">appendix A: delegation helper files</a>
-
-----
-
-<a name="_overview_of_problem"></a>
-
-### overview of problem
+## overview of problem
The example is from real life, with the following characteristics:
@@ -55,9 +31,7 @@ The following can only be done by the master admins:
* mirroring setup -- who's the master and who're the slaves for any repo
* allowing redirected pushes from slaves
-<a name="_overview_of_setup"></a>
-
-### overview of setup
+## overview of setup
We will use p1 as the product, with sam as the master and frodo as a slave.
Assume equivalent text/code for other product/master/slave combos.
@@ -67,22 +41,18 @@ name; either a product name or, for local repos, a hostname. In our example,
these directory names would be p1 or sam on the host sam, and frodo on the
host frodo.
-<a name="_gitolite_feature_recap"></a>
-
-#### gitolite feature recap
+### gitolite feature recap
-We use [delegation][deldoc], to ensure that admins for sam can only write
+We use [delegation][deleg], to ensure that admins for sam can only write
files whose names start with `master/sam/`. The actual files they will write
are `master/sam/p1.conf` etc., one for each product that is mastered on their
server.
-We use [subconf][sc]. When you say `subconf "path/to/foo.conf`, then within
+We use [subconf][]. When you say `subconf "path/to/foo.conf`, then within
that file (and anything included from it), access can only be defined for
repos that regex-match one of the elements of `@foo`.
-<a name="_pre_requisites"></a>
-
-### pre-requisites
+## pre-requisites
First, install mirroring on all servers according to the main mirroring
document. Set it up so that the gitolite-admin repo is mastered at one server
@@ -91,9 +61,7 @@ and everyone else slaves it.
Also, after (or during) the normal mirroring install, edit `~/.gitolite.rc` on
all servers and set `$GL_WILDREPOS` to 1 (from its default of 0).
-<a name="_quick_setup"></a>
-
-### quick setup
+## quick setup
* edit your `gitolite.conf` file as given in step 1 below
* ignore all the comments, even the ones that tell you to do something :-)
@@ -126,9 +94,7 @@ A typical sequence with that script is:
You can then treat the detailed steps described below as extra information or
"background reading" ;-)
-<a name="_step_by_step"></a>
-
-### step by step
+## F=_mirrexsteps step by step
If the script is not cutting it for you and want to vary the technique for
some reason, or you simply want to gain a better understanding of what is
@@ -139,9 +105,7 @@ script.
only place where you have to explicitly state this is in the delegation code
in the appendix. The rest of the time, "conf/" is assumed.
-<a name="_1_gitolite_conf_"></a>
-
-#### (1) `gitolite.conf`
+### (1) `gitolite.conf`
The main config file has these items in it. **Please add them in this
order**.
@@ -209,9 +173,7 @@ Here's what it looks like:
You'll get some warnings about missing include files; ignore them.
-<a name="_2_master_sam_conf_"></a>
-
-#### (2) `master/sam.conf`
+### (2) `master/sam.conf`
For each host sam, one file called `master/sam.conf` is needed. This file
contains just one line:
@@ -223,9 +185,7 @@ contains just one line:
"master/sam.conf"`. The only purpose of this is to setup the subconf
restriction on the combined contents of `master/sam/*.conf`.</font>
-<a name="_3_host_admins_only_master_sam_p1_conf_"></a>
-
-#### (3) host admins only -- `master/sam/p1.conf`
+### (3) host admins only -- `master/sam/p1.conf`
(recap: the host admins for sam can only write files in `master/sam`).
@@ -240,9 +200,7 @@ product.conf files.
By default, everything is local to their server. (Mirroring can only be setup
by the master admins).
-<a name="_4_mirrors_sam_p1_conf_"></a>
-
-#### (4) `mirrors/sam/p1.conf`
+### (4) `mirrors/sam/p1.conf`
For each product p1 mastered on host sam, a file called `mirrors/sam/p1.conf`
will be created, containing mirror config lines for all repos of product p1.
@@ -254,9 +212,7 @@ In this case, it could be
If this file does not exist, p1 is local to sam and not mirrored.
-<a name="_5_slave_frodo_sam_conf_"></a>
-
-#### (5) `slave/frodo/sam.conf`
+### (5) `slave/frodo/sam.conf`
For each product that slave frodo gets from master sam, this file has the
following lines
@@ -278,18 +234,14 @@ restriction of "sam"*. This is important to prevent sam's admins from writing
rules for repos they don't own and having them processed on other
servers!</font>
-<a name="_6_manual_sync"></a>
-
-#### (6) manual sync
+### (6) manual sync
The new repo(s) you just created would not have been synced up to frodo. You
can either make an empty commit and push, or log on to sam and run
gl-mirror-shell request-push p1/reponame
-<a name="_next_steps"></a>
-
-### next steps
+## next steps
Once you've done the initial setup, here's what ongoing additions will
require.
@@ -302,9 +254,7 @@ require.
hostname in the slaves list for the admin repo (this is in the main
gitolite.conf file)
-<a name="_appendix_A_delegation_helper_files"></a>
-
-### appendix A: delegation helper files
+## F=_mirrappA appendix A: delegation helper files
These two files were briefly mentioned in the delegation setup.
View
2  doc/monkeysphere.mkd → contrib/monkeysphere.mkd
@@ -1,4 +1,4 @@
-## (contributed doc: integrating gitolite with monkeysphere)
+# F=monkeysphere (contributed doc: integrating gitolite with monkeysphere)
This document attempts to describe one way to integrate
[Monkeysphere](http://web.monkeysphere.info/) authentication
View
75 contrib/putty.mkd
@@ -1,21 +1,4 @@
-## putty and msysgit
-
-In this document:
-
- * <a href="#_msysgit_setup">msysgit setup</a>
- * <a href="#_Going_back_to_OpenSSH">Going back to OpenSSH</a>
- * <a href="#_Putty_keys">Putty keys</a>
- * <a href="#_Creating_a_new_key">Creating a new key</a>
- * <a href="#_Importing_an_existing_key">Importing an existing key</a>
- * <a href="#_Loading_an_existing_key">Loading an existing key</a>
- * <a href="#_Public_key">Public key</a>
- * <a href="#_Putty_ageant">Putty ageant</a>
- * <a href="#_Sessionless_or_raw_hostname_usage">Sessionless or raw hostname usage</a>
- * <a href="#_Putty_sessions">Putty sessions</a>
- * <a href="#_Host_key_authentication">Host key authentication</a>
- * <a href="#_Debugging_multiple_putty_ageant_keys">Debugging multiple putty ageant keys</a>
- * <a href="#_Setperms_and_other_commands">Setperms and other commands</a>
- * <a href="#_About_this_document">About this document</a>
+# F=contrib_putty putty and msysgit
This document is intended for those who wish to use Putty/Plink with msysgit.
@@ -27,9 +10,7 @@ If you need more help with putty or component programs I suggest looking at [the
<a name="msysgit_setup"/>
-<a name="_msysgit_setup"></a>
-
-### msysgit setup
+## msysgit setup
Provided you have putty sessions msysgit should give you the option of specifying a location to plink. If it did not then you will need to add an environment variable named "GIT\_SSH" to point at plink.exe, wherever you have that sitting.
@@ -51,17 +32,13 @@ If instead you get a "command not found" type error you likely have a typo in yo
<a name="Going_back_to_OpenSSH"/>
-<a name="_Going_back_to_OpenSSH"></a>
-
-### Going back to OpenSSH
+## Going back to OpenSSH
If you wish to go back to OpenSSH all you need to do is delete the GIT\_SSH environment variable. This will vary by your version of windows and thus is not covered here.
<a name="Putty_keys"/>
-<a name="_Putty_keys"></a>
-
-### Putty keys
+## Putty keys
If you do not already have putty private key files (.ppk) you will need to make at least one. You can either make a new one or convert an existing key to putty private key format.
@@ -69,9 +46,7 @@ Either way, you will want to use puttygen. Note that you can go the other way if
<a name="Creating_a_new_key"/>
-<a name="_Creating_a_new_key"></a>
-
-#### Creating a new key
+### Creating a new key
To make it simple, I suggest SSH-2 RSA and a bit size of at least 1024. Larger keys will take longer to generate and will take longer to authenticate you on most systems. Making the key is as simple at hitting "Generate".
@@ -79,9 +54,7 @@ It is recommended to give the key a meaningful comment.
<a name="Importing_an_existing_key"/>
-<a name="_Importing_an_existing_key"></a>
-
-#### Importing an existing key
+### Importing an existing key
If you already have an OpenSSH or ssh.com key you can import it using the "Import" option on the "Conversions" menu.
@@ -89,41 +62,31 @@ If the key does not have a meaningful comment I would suggest adding one at this
<a name="Loading_an_existing_key"/>
-<a name="_Loading_an_existing_key"></a>
-
-#### Loading an existing key
+### Loading an existing key
If you need to load an existing key to edit or view it you can do so from the File menu.
<a name="Public_key"/>
-<a name="_Public_key"></a>
-
-#### Public key
+### Public key
To get your public key for use with gitolite, load (or generate, or import) your key into puttygen. There is a box labeled "Public key for pasting into OpenSSH `authorized_keys` file" there. Copy the text into your preferred text editor and save.
<a name="Putty_ageant"/>
-<a name="_Putty_ageant"></a>
-
-#### Putty ageant
+### Putty ageant
Though not required in all cases you may wish to use the putty ageant, pageant, to load your key(s). This will allow for your key(s) to be passphrase protected but not have to enter the passphrase when you go to use them, provided you have already loaded the key into the ageant.
<a name="Sessionless_or_raw_hostname_usage"/>
-<a name="_Sessionless_or_raw_hostname_usage"></a>
-
-### Sessionless or raw hostname usage
+## Sessionless or raw hostname usage
When using plink without a putty session you pretty much have to load your keys with putty ageant, if only so that plink can find them.
<a name="Putty_sessions"/>
-<a name="_Putty_sessions"></a>
-
-### Putty sessions
+## Putty sessions
In addition to hostnames msysgit can, when using putty, use putty sessions. This works in a manner similar to definitions in OpenSSH's `ssh_config` file. All settings in the session that apply to plink usage will be loaded, including the key file to use and even the username to connect to. Thus, instead of:
@@ -135,9 +98,7 @@ You can use:
<a name="Host_key_authentication"/>
-<a name="_Host_key_authentication"></a>
-
-### Host key authentication
+## Host key authentication
Whether you are using hostnames or sessions you still run into one potential problem. Plink currently wants to validate the server's SSH host key before allowing you to connect, and when git calls plink there is no way to tell it yes. Thus, you may get something like this:
@@ -204,9 +165,7 @@ In either case hit y and the key will be stored.
<a name="Debugging_multiple_putty_ageant_keys"/>
-<a name="_Debugging_multiple_putty_ageant_keys"></a>
-
-### Debugging multiple putty ageant keys
+## Debugging multiple putty ageant keys
In the event you are using putty ageant with multiple keys loaded you may see the wrong key being used. In general, pageant keys are tried in the order they were loaded into the ageant. If you have descriptive comment on each of your keys you can try connecting with plink in verbose mode to see what keys are being tried. Simply open the Git bash shell and run:
@@ -225,9 +184,7 @@ The first says which (numerical) key the ageant is trying. The second tells you
<a name="Setperms_and_other_commands"/>
-<a name="_Setperms_and_other_commands"></a>
-
-### Setperms and other commands
+## Setperms and other commands
When using wildcard repos the setperms command is very important, and other commands can come in handy as well. See their documentation for how to use them, but where they use:
@@ -241,8 +198,6 @@ Otherwise everything should be identical.
<a name="About_this_document"/>
-<a name="_About_this_document"></a>
-
-### About this document
+## About this document
This document was written by Thomas Berezansky (tsbere (at) mvlc (dot) org) in the hopes that it would be useful to those using putty on windows and wishing to use git/gitolite with their putty keys and sessions.
View
31 contrib/real-users/password-access.mkd
@@ -1,10 +1,8 @@
-# password access to gitolite
+# F=password_access password access to gitolite
-## (a.k.a: turning real users into gitolite users)
+(a.k.a: turning real users into gitolite users)
-<a name="_problems"></a>
-
-### problems
+## problems
*Problem 1*: Here's one type of problem some admins have:
@@ -33,9 +31,7 @@ pesky password problem, and do not wish them to actually have shell access or
be able to do anything else on the server, don't worry -- that's easy to
handle too.</font>
-<a name="_solution"></a>
-
-### solution
+## solution
Briefly, the Unix userid is made to act like a "gitolite proxy".
@@ -73,17 +69,13 @@ This second connection *does* require ssh keys, but since they're all on the
server, it's scriptable and automatable so the user doesn't have to deal with
these pesky ssh keys.
-<a name="_some_hints_notes_and_caveats"></a>
-
-### some hints, notes and caveats
+## some hints, notes and caveats
* This doesn't mean all your users have to be like this. You can have
normal users also. In fact, you can have users who give you a pub key
from their workstation the normal way, as well as use this method.
-<a name="_what_the_2_scripts_actually_do"></a>
-
-### what the 2 scripts actually do
+## what the 2 scripts actually do
* `gl-shell` will become the new login shell for these users. This shell
will forward git clone/fetch/push requests to the gitolite server.
@@ -99,12 +91,11 @@ these pesky ssh keys.
example) `alice@localhost.pub` in keydir of the admin repo, which is then
pushed.
- Notice the use of [this trick][oumk] to allow Alice to allow users to have
- other (gitolite normal) keys as well, such as perhaps from a laptop.
-
-<a name="_setting_it_up"></a>
+ Notice the use of [this trick][oldmultikeys] to allow Alice to allow users
+ to have other (gitolite normal) keys as well, such as perhaps from a
+ laptop.
-### setting it up
+## setting up password access
Here's how to set this up. First, the **one-time** tasks:
@@ -131,5 +122,3 @@ Now, for each user 'alice' that has her own real (unix) userid, and also needs
to access gitolite *via* her own id, run the command `gl-shell-setup alice`.
And that's really all there is to it.
-
-[oumk]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html#_one_user_many_keys
View
3  contrib/vim/README.mkd → contrib/vim/README-vim.mkd
@@ -1,11 +1,10 @@
-## Vim Syntax Highlight
+# F=_vimsyntax Vim Syntax Highlight
[Vim][] Syntax highlight for `gitolite.conf` can be found from:
- [vim.org script page][vim.org] (Releases)
- [GitHub][] (Sources)
-
[Vim]: http://www.vim.org/
[vim.org]: http://www.vim.org/scripts/script.php?script_id=2900
[GitHub]: http://github.com/tmatilai/gitolite.vim
View
12 doc/1000-words.mkd
@@ -1,4 +1,4 @@
-# gitolite in pictures
+# F=pictures gitolite in pictures
Well, they say a picture speaks a thousand words, so here're a few!
@@ -9,9 +9,7 @@ had to use Unicode 2010 for it. I expect that I will have to resort to
similar tricks for colon, equals, and many others like it if and when I need
those in text within a ditaa diagram.
-<a name="_installation_and_setup"></a>
-
-### installation and setup
+## installation and setup
Here's a picture showing the "non-root" install. We assume Alice is the
gitolite admin, and "git" is the hosting user on the server.
@@ -56,9 +54,7 @@ Note also that you only need ONE real user on the server. In our example it
is git. In particular, you do NOT create Unix userids for your gitolite
users.
-<a name="_adding_users_to_gitolite"></a>
-
-### adding users to gitolite
+## adding users to gitolite
Once you've done the install, here's how you add users.
@@ -103,7 +99,7 @@ You do NOT need to add Carol or Bob as *real* (Unix) users. You do NOT add
their keys directly anywhere on the server; you do it by cloning, adding keys,
and pushing.
-### adding repos to gitolite
+## adding repos to gitolite
Adding a repo is even easier. It's so easy that you don't really need a
picture. OK maybe a small one:
View
95 doc/admin-defined-commands.mkd
@@ -1,29 +1,6 @@
-## admin defined commands
+# F=ADCs admin defined commands
-----
-
-In this document:
-
- * <a href="#_background">background</a>
- * <a href="#_details">details</a>
- * <a href="#_installing_ADCs">installing ADCs</a>
- * <a href="#_user_invocation">user invocation</a>
- * <a href="#_checking_authorisation">checking authorisation</a>
- * <a href="#_checking_arguments">checking arguments</a>
- * <a href="#_passing_unchecked_arguments">passing unchecked arguments</a>
- * <a href="#_fake_repos_and_access_control_for_non_git_programs">"fake" repos and access control for non-git programs</a>
- * <a href="#_anatomy_of_a_command">anatomy of a command</a>
- * <a href="#_example_uses_and_sample_commands_in_contrib_adc_">example uses and sample commands in `contrib/adc`</a>
- * <a href="#_fork">fork</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="#_how_this_feature_came_about">how this feature came about</a>
-
-----
-
-<a name="_background"></a>
-
-### background
+## ADC background
The admin-defined commands (ADCs) feature allows controlled access to
specific, "safe", programs or scripts, without giving users full shell access.
@@ -36,17 +13,11 @@ but an extra pair of eyes never hurt, so please review before use.
<font color="gray">Although this is a generic way to allow pretty much any
command to be run, most of the examples and sample ADCs pertain to allowing
users to manage their "own" repos. If that's your use case, please read
-[doc/wildcard-repositories.mkd][wild] before you continue here.</font>
-
-[wild]: http://sitaramc.github.com/gitolite/doc/wildcard-repositories.html
+the [wildcard repositories][wild] doc before you continue here.</font>
-<a name="_details"></a>
+## ADC details
-### details
-
-<a name="_installing_ADCs"></a>
-
-#### installing ADCs
+### installing ADCs
ADCs can only be installed by someone with shell access to the server; merely
having push rights to the admin repo is not enough.
@@ -63,18 +34,14 @@ This is by design. So be careful what you name your scripts.
However, it is perfectly ok, and may even be necessary in some cases, to name
them after system executables (like 'rsync').
-<a name="_user_invocation"></a>
-
-#### user invocation
+### user invocation
If you have a command called "foo" in that directory, then a user can invoke
it by saying:
ssh git@server foo argument list
-<a name="_checking_authorisation"></a>
-
-#### checking authorisation
+### checking authorisation inside an ADC
Once an ADC is installed, *all* users can run it. But sometimes you want only
some people to be able to do so.
@@ -87,17 +54,13 @@ repo, which is an easy way of making sure an ADC is only run by admins.
See the section on "the anatomy of a command" later for this and many more
details.
-<a name="_checking_arguments"></a>
-
-#### checking arguments
+### checking arguments
Gitolite will call an ADC only if the arguments passed to it match a very
strict pattern (see `$ADC_CMD_ARGS_PATT` in `src/gitolite_rc.pm`). This
reduces the risk of various kinds of shell-meta related compromises.
-<a name="_passing_unchecked_arguments"></a>
-
-#### passing unchecked arguments
+### passing unchecked arguments
Some commands need arguments with a broader range of characters than
`$ADC_CMD_ARGS_PATT` will allow. As long as you are sure those commands are
@@ -107,9 +70,7 @@ arguments**.
The "ua" stand for "unchecked arguments". Consider this your last warning ;-)
-<a name="_fake_repos_and_access_control_for_non_git_programs"></a>
-
-### "fake" repos and access control for non-git programs
+## "fake" repos and access control for non-git programs
A "fake" repo is a repo that exists in the config file but is specially named
(starts with "EXTCMD/") so that gitolite will not create an actual repo on
@@ -126,9 +87,7 @@ server has sufficient information to decide. Protocols where the command line
is just one word and everything else happens in the conversation later cannot
be helped by this mechanism.</font>
-<a name="_anatomy_of_a_command"></a>
-
-### anatomy of a command
+## anatomy of a command
You can do whatever you want in an ADC! It's upto you to check the
permissions of *each* repo that the user is manipulating using your ADC --
@@ -176,13 +135,9 @@ convenient. See any of the other samples for how to use it.
If you prefer perl, there is a nicely commented example in
`contrib/adc/get-rights-and-owner.in-perl`.
-<a name="_example_uses_and_sample_commands_in_contrib_adc_"></a>
-
-### example uses and sample commands in `contrib/adc`
+## example uses and sample commands in `contrib/adc`
-<a name="_fork"></a>
-
-#### fork
+### #fork the 'fork' ADC
A user would use the fork command like this:
@@ -206,19 +161,11 @@ the client side:
or some such incantation.
-<a name="rmrepo"></a>
-
-<a name="_deleting_trashing_repos"></a>
-
-#### deleting/trashing repos
+### deleting/trashing repos
-See the [repo-deletion document][rdR] for details about this.
+See the [repo-deletion document][wild_repodel] for details about this.
-[rdR]: http://sitaramc.github.com/gitolite/contrib/adc/repo-deletion.html
-
-<a name="_enable_disable_push_access_temporarily"></a>
-
-#### enable/disable push access temporarily
+### #able enable/disable push access temporarily
If you want to disable push access to gitolite temporarily (maybe for
maintenance), anyone with write access to the gitolite-admin repo can do this:
@@ -233,15 +180,9 @@ You can also do this for one or more individual repos; in place of `@all`,
just use a space separated list of reponames (exactly as they would appear in
the config file). Wildcards are not supported; patches welcome ;-)
-Note: please see [this][diswr] for more on this.
-
-[diswr]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html#_disabling_write_access_to_take_backups
-
-----
-
-<a name="_how_this_feature_came_about"></a>
+Note: please see [this][disable] for more on this.
-### how this feature came about
+## how the ADC feature came about
<font color="gray">
View
204 doc/2-admin.mkd → doc/admin.mkd
@@ -1,26 +1,6 @@
-# administering and running gitolite
+# F=admin administering and running gitolite
-In this document:
-
- * <a href="#_please_read_this_first">please read this first</a>
- * <a href="#_adding_users_and_repos">adding users and repos</a>
- * <a href="#_using_hooks">using hooks</a>
- * <a href="#_custom_hooks">custom hooks</a>
- * <a href="#_gl_post_init_hook">"gl-post-init" hook</a>
- * <a href="#_gl_pre_git_hook">"gl-pre-git" hook</a>
- * <a href="#_hook_chaining">hook chaining</a>
- * <a href="#_environment_variables_available_to_hooks">environment variables available to hooks</a>
- * <a href="#_other_features">other features</a>
- * <a href="#_moving_pre_existing_repos_into_gitolite">moving pre-existing repos into gitolite</a>
- * <a href="#_moving_the_whole_thing_from_one_server_to_another">moving the whole thing from one server to another</a>
- * <a href="#_specifying_gitweb_and_daemon_access">specifying gitweb and daemon access</a>
- * <a href="#_custom_git_config">custom git config</a>
-
-----
-
-<a name="_please_read_this_first"></a>
-
-### please read this first
+## please read this first
Unless you know what you're doing, do not do **anything** manually on the
server (except when the documentation says you should, for example to add
@@ -46,9 +26,7 @@ Either way, make sure you `cd` into this clone first.
Once you've cloned it, you're ready to add users and repos.
-<a name="_adding_users_and_repos"></a>
-
-### adding users and repos
+## F=add 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
@@ -67,23 +45,20 @@ section tells you how to add users and repos.
if you wish, since the entire tree is searched.
* edit the config file (`conf/gitolite.conf` in your admin repo clone). See
- [doc/gitolite.conf.mkd][confmkd] in the gitolite source for details on
- what goes in that file, syntax, etc. Just add new repos as needed, and
- add new users and give them permissions as required. The users names
- should be exactly the same as their keyfile names, but without the `.pub`
- extension
+ the [gitolite.conf][conf] documentation for details on what goes in that
+ file, syntax, etc. Just add new repos as needed, and add new users and
+ give them permissions as required. The users names should be exactly the
+ same as their keyfile names, but without the `.pub` extension
* when done, commit your changes and push. Any new repos you specified will
automatically be created (empty, but clonable) and users' access will be
updated as needed.
-<a name="_using_hooks"></a>
-
-### using hooks
+[genpub]: http://sitaramc.github.com/0-installing/2-access-gitolite.html#generating_a_public_key
-<a name="_custom_hooks"></a>
+## F=hooks using hooks
-#### custom hooks
+### #customhooks custom hooks
You can supply your own, custom, hook scripts if you wish. Install gitolite
as usual, then:
@@ -104,37 +79,7 @@ that you had previously installed.
* Do not under any conditions put anything in `hooks/gitolite-admin` --
nothing in gitolite requires you to do anything here. Leave it alone!
-<a name="_gl_post_init_hook"></a>
-
-#### "gl-post-init" hook
-
-Sometimes it is necessary to do something whenever a new repo is created. If
-you need this functionality, just supply a hook called "gl-post-init" with
-whatever code you want in it.
-
-<a name="_gl_pre_git_hook"></a>
-
-#### "gl-pre-git" hook
-
-Although git has lots of nice hooks you can tap into, they all run only on a
-push. There's nothing that runs on a fetch or a clone, and there's no way to
-run something *before* git-receive-pack or git-upload-pack, (as the case may
-be) are invoked.
-
-That's what the `gl-pre-git` hook is for. If an executable hook called
-`gl-pre-git` is present, it will be invoked with the current directory set to
-`repo.git`, and with a single argument which will be either `R` or `W`
-depending on what the client is trying to do. The environment variables
-`GL_USER` and `GL_REPO` are available. STDOUT will be forced to STDERR before
-it is called, to avoid confusing the client.
-
-If the code returns anything other than 0, gitolite will terminate the
-operation (i.e., not run git at all), just like many git hooks do, so make
-sure you end with `exit 0` or equivalent.
-
-<a name="_hook_chaining"></a>
-
-#### hook chaining
+### #hookchaining hook chaining
Sometimes you need to use git hooks for your own purposes (site-local
validations, CI integration, email notifications, or the ever popular "live
@@ -183,9 +128,7 @@ Finally, these names ('update.secondary' and 'post-update.secondary') are
merely the defaults. You can change them to anything you want; look in
conf/example.gitolite.rc for details.
-<a name="_environment_variables_available_to_hooks"></a>
-
-#### environment variables available to hooks
+### environment variables available to hooks
The following environment variables are set, and may be useful for any custom
processing you wish to do in your hook code:
@@ -199,13 +142,33 @@ The following variables are also set, but are generally less useful:
* `GL_BINDIR` -- where all the binaries live
* `GL_ADMINDIR` -- common directory for many gitolite things
-<a name="_other_features"></a>
+### "gl-post-init" hook
+
+Sometimes it is necessary to do something whenever a new repo is created. If
+you need this functionality, just supply a hook called "gl-post-init" with
+whatever code you want in it.
+
+### "gl-pre-git" hook
-### other features
+Although git has lots of nice hooks you can tap into, they all run only on a
+push. There's nothing that runs on a fetch or a clone, and there's no way to
+run something *before* git-receive-pack or git-upload-pack, (as the case may
+be) are invoked.
-<a name="_moving_pre_existing_repos_into_gitolite"></a>
+That's what the `gl-pre-git` hook is for. If an executable hook called
+`gl-pre-git` is present, it will be invoked with the current directory set to
+`repo.git`, and with a single argument which will be either `R` or `W`
+depending on what the client is trying to do. The environment variables
+`GL_USER` and `GL_REPO` are available. STDOUT will be forced to STDERR before
+it is called, to avoid confusing the client.
-#### moving pre-existing repos into gitolite
+If the code returns anything other than 0, gitolite will terminate the
+operation (i.e., not run git at all), just like many git hooks do, so make
+sure you end with `exit 0` or equivalent.
+
+## other features
+
+### F=moverepos moving pre-existing repos into gitolite
It's best to split this into different use cases.
@@ -254,10 +217,8 @@ Assuming you can group your repo names into various patterns, and can use
similar access control lines within each such group, you can use gitolite's
"wildcard repos" feature.
-[wild]: http://sitaramc.github.com/gitolite/doc/wildcard-repositories.html
-
-First read [doc/wildcard-repositories.mkd][wild], or at least skim through it,
-to understand the basic concept. Then do this:
+First read the [wildcard repositories][wild] document, or at least skim
+through it, to understand the basic concept. Then do this:
* do step 1 just like step 1 in Case 2 above
@@ -294,7 +255,7 @@ to understand the basic concept. Then do this:
* what's with the `gl-creater` file in case 3?
- What [doc/wildcard-repositories.mkd][wild] does not explain is how
+ What the [wildcard repositories][wild] document does not explain is how
ownership is *recorded* in gitolite: the `gl-creater` file contains the
owner name. If you want to "pretend" these repos were created by some
user, you need to add that in. That user then gets whatever access you
@@ -313,9 +274,7 @@ In the end, it all boils down to (a) making sure the `update` hook is correct
on all repos, wild or normal, and (b) making sure `gl-creater` contains the
owner name for wild repos. The rest of the setup is in the conf file.
-<a name="_moving_the_whole_thing_from_one_server_to_another"></a>
-
-#### moving the whole thing from one server to another
+### F=moveserver moving the whole thing from one server to another
[**NOTE**: I would appreciate help testing these instructions]
@@ -391,83 +350,12 @@ if things are not clear -- you can help me fine tune this document :-)
And that should be that!
-<a name="gwd"></a>
-
-<a name="_specifying_gitweb_and_daemon_access"></a>
-
-#### specifying gitweb and daemon access
-
-This is a feature that I personally do not use (corporate environments don't
-like unauthenticated access of any kind to any repo!), but someone wanted it,
-so here goes.
-
-Gitolite has two pre-defined, "special", usernames: `daemon` and `gitweb`.
-
-To make a repo or repo group accessible via "git daemon", just give read
-permission to the special user "daemon". Similarly, give read permission to
-`gitweb` to allow the gitweb CGI to show the repo. Something like this:
-
- repo foo bar baz
- R = gitweb daemon
-
-This gives you a quick way to offer multiple repos up for gitweb and/or daemon
-access.
-
-However, **setting a description** for the project also enables gitweb
-permissions so you can do it that way if you want. Of course in this case you
-have to deal with each repo separately. Add lines like this to gitolite.conf:
-
- foo = "some description"
- bar = "some other description"
- baz = "yet another description"
-
-You can also **specify an owner** for gitweb to show, if you like; for example
-I might use:
-
- gitolite "Sitaram Chamarty" = "fast, secure, fine-grained, access control for git"
-
-These lines are standalone, so you can add them anywhere in the conf file.
-
-Note that gitolite does **not** install or configure gitweb/git-daemon -- that
-is a one-time setup you must do separately. All gitolite does is:
-
- * for daemon, create the file `git-daemon-export-ok` in the repository
- * for gitweb, add the repo (plus owner name, if given) to the list of
- projects to be served by gitweb (see the config file variable
- `$PROJECTS_LIST`, which should have the same value you specified for
- `$projects_list` when setting up gitweb)
- * put the description, if given, in `$repo/description`
-
-The "compile" script will keep these files consistent with the config settings
--- this includes removing such settings/files if you remove "read" permissions
-for the special usernames or remove the description line.
-
-Please **note** that giving permissions to these special users via `@all`
-(that is, using either `repo @all` or `R = @all`), will not work unless you
-set the rc-file variable `$GL_ALL_INCLUDES_SPECIAL` to `1`. Also, **NOTE**
-that giving them read access to `repo @all` means the `gitolite-admin` repo is
-also accessible. **It is upto you to decide if that is OK in your
-environment**.
-
-<a name="_custom_git_config"></a>
-
-#### custom git config
+### custom git config
The custom hooks feature is a blunt instrument -- all repos get the hook you
-specified and will run it. In order to make it a little more fine-grained,
-you could set your hooks to only work if a certain "gitconfig" variable was
-set. Which means we now need a way to specify "git config" settings on a per
-repository basis.
-
-Thanks to Teemu (teemu dot matilainen at iki dot fi), gitolite now does this
-very easily. For security reasons, this can only be done from the master
-config file (i.e., if you're using delegation, the delegated admins cannot
-specify git config settings).
+specified and will run it. You can of course install hooks manually on the
+server, but sometimes that's cumbersome.
-Please see `doc/gitolite.conf.mkd` for syntax and limitations. Also note that
-this feature is disabled by default. Read the comments on a variable called
-`GL_GITCONFIG_KEYS` in the rc file documentation, then set it to some
-appropriate value, to enable this feature.
-
-[genpub]: http://sitaramc.github.com/0-installing/2-access-gitolite.html#generating_a_public_key
-[confmkd]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html
+Instead, you could set your hooks to only work if a certain "gitconfig"
+variable was set. See [this][rsgc] for a way to specify "git config"
+settings on a per repository basis.
View
31 doc/authentication-vs-authorisation.mkd → doc/auth.mkd
@@ -1,13 +1,9 @@
-# authentication versus authorisation
+# F=auth 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][glsts].
-
-[glsts]: http://sitaramc.github.com/gitolite/doc/ssh-troubleshooting.html
-
-----
+Note: for actual ssh troubleshooting see [this][sts].
Here is a fundamental point: <font color="red">**Gitolite does not do
authentication. It only does authorisation**.</font>
@@ -22,7 +18,7 @@ So first, let's loosely define these words:
> **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 [doc/gitolite-and-ssh.mkd][gas], you know that
+Now, if you managed to read about [gitolite and ssh][gl_ssh], you know that
gitolite is meant to be invoked as:
/full/path/to/gl-auth-command some-authenticated-gitolite-username
@@ -32,26 +28,18 @@ be, and usually *isn't*, an actual *unix* username).
As you can see, authentication happens before gitolite is called.
-[gas]: http://sitaramc.github.com/gitolite/doc/gitolite-and-ssh.html
-
-<a name="_but_but_you_have_all_that_ssh_stuff_in_there_"></a>
-
-### but... but... you have all that ssh stuff in there!
+## 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][sh], and ldap-backed sshd. In both cases, gitolite has no
+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.
-[sh]: http://sitaramc.github.com/gitolite/doc/http-backend.html
-
-<a name="_so_you_re_basically_saying_you_won_t_support_X_"></a>
-
-### so you're basically saying you won't support "X"
+## so you're basically saying you won't support "X"
(where "X" is some ssh related behaviour change or feature)
@@ -64,9 +52,7 @@ 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.
-<a name="_appendix_how_to_use_other_authentication_systems_with_gitolite"></a>
-
-### appendix: how to use other authentication systems with gitolite
+## 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
@@ -75,7 +61,7 @@ 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][sh], things are somewhat
+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.
@@ -101,4 +87,3 @@ which can be useful.
Finally, gitolite allows you to store *group* information externally too. See
[here][ldap] for more on this.
-[ldap]: http://sitaramc.github.com/gitolite/doc/big-config.html#_storing_usergroup_information_outside_gitolite_like_in_LDAP_
View
325 doc/big-config.mkd
@@ -1,27 +1,22 @@
-## what is a "big-config"
+# F=bc what is a "big-config"
-In this document:
+This document is just background info; you don't actually need to read the
+whole thing if you don't care. All you need to do is set `BIG_CONFIG` to 1 in
+the rc file and you're done. If you have no use for gitweb and daemon, you
+can save even more time by setting `GL_NO_DAEMON_NO_GITWEB`.
- * <a href="#_when_why_do_we_need_it_">when/why do we need it?</a>
- * <a href="#_how_do_we_use_it_">how do we use it?</a>
- * <a href="#_access_rules_for_groups">access rules for groups</a>
- * <a href="#_access_rules_for_individual_repos_split_config_">access rules for individual repos (split config)</a>
- * <a href="#_other_optimisations">other optimisations</a>
- * <a href="#_disabling_various_defaults">disabling various defaults</a>
- * <a href="#_optimising_the_authkeys_file">optimising the authkeys file</a>
- * <a href="#_what_are_the_downsides_">what are the downsides?</a>
- * <a href="#_storing_usergroup_information_outside_gitolite_like_in_LDAP_">storing usergroup information outside gitolite (like in LDAP)</a>
- * <a href="#_why">why</a>
- * <a href="#_how">how</a>
- * <a href="#_implementation_notes">implementation notes</a>
+Finally, if you're *really* an expert (or your initials are "JK"), you can
+even set `GL_NO_CREATE_REPOS` and `GL_NO_SETUP_AUTHKEYS`. However, be warned
+that if you're not sufficiently clueful, those last 2 variables could have a
+[security impact][rcsecurity].
-<a name="_when_why_do_we_need_it_"></a>
-
-### when/why do we need it?
+## when/why do we need it?
A "big config" is anything that has a few thousand users and a few thousand
repos, resulting in a very large 'compiled' config file.
+### the problem
+
To understand the problem, consider what happens if you have something like
this in your gitolite conf file:
@@ -40,80 +35,7 @@ Without the 'big config' setting, gitolite internally translates this to:
and then generates the actual config rules once for each user-repo-ref
combination (there are 8 combinations above); the compiled config file looks
-somewhat like this:
-
- %repos = (
- 'firefox' => {
- 'R' => {
- 'alice' => 1,
- 'bob' => 1
- },
- 'W' => {
- 'alice' => 1,
- 'bob' => 1
- },
- 'alice' => [
- [
- 0,
- 'refs/heads/next',
- 'RW+'
- ],
- [
- 4,
- 'refs/heads/master',
- 'RW'
- ]
- ],
- 'bob' => [
- [
- 1,
- 'refs/heads/next',
- 'RW+'
- ],
- [
- 5,
- 'refs/heads/master',
- 'RW'
- ]
- ]
- },
- 'lynx' => {
- 'R' => {
- 'alice' => 1,
- 'bob' => 1
- },
- 'W' => {
- 'alice' => 1,
- 'bob' => 1
- },
- 'alice' => [
- [
- 2,
- 'refs/heads/next',
- 'RW+'
- ],
- [
- 6,
- 'refs/heads/master',
- 'RW'
- ]
- ],
- 'bob' => [
- [
- 3,
- 'refs/heads/next',
- 'RW+'
- ],
- [
- 7,
- 'refs/heads/master',
- 'RW'
- ]
- ]
- }
- );
-
-Phew!
+somewhat like [this][_bigno].
Of course, the output is the same whether you used groups (like `@wbr` and
`@devs` in the example above) or listed the repos directly on the 'repo'
@@ -122,9 +44,7 @@ lines.
Anyway, you can imagine what that does when you have 10,000 users and 10,000
repos. Let's just say it's not pretty :)
-<a name="_how_do_we_use_it_"></a>
-
-### how do we use it?
+## how do we use it?
Just set
@@ -134,52 +54,15 @@ in the `~/.gitolite.rc` file on the server (see next section for more
variables). When you do that, and push this configuration, one of two things
happens.
-<a name="_access_rules_for_groups"></a>
-
-#### access rules for groups
+### access rules for groups
If you used group names in the 'repo' lines (as in `repo @wbr`), then the
-compiled config looks like this:
-
- %repos = (
- '@wbr' => {
- '@devs' => [
- [
- 0,
- 'refs/heads/next',
- 'RW+'
- ],
- [
- 1,
- 'refs/heads/master',
- 'RW'
- ]
- ],
- 'R' => {
- '@devs' => 1
- },
- 'W' => {
- '@devs' => 1
- }
- }
- );
- %groups = (
- '@devs' => {
- 'alice' => 'master',
- 'bob' => 'master'
- },
- '@wbr' => {
- 'firefox' => 'master',
- 'lynx' => 'master'
- }
- );
+compiled config looks like [this][_bigyes].
That's a lot smaller, and allows orders of magintude more repos and groups to
be supported.
-<a name="_access_rules_for_individual_repos_split_config_"></a>
-
-#### access rules for individual repos (split config)
+### access rules for individual repos (split config)
If, on the other hand, you had the repos listed individually, (as in `repo
lynx firefox`), then the main config file would now look like this:
@@ -233,13 +116,26 @@ instance, `~/repositories/lynx.git/gl-conf` would look like this:
That does not reduce the overall size of the repo config (because you did not
group the repos), but the main repo config is now even smaller!
-<a name="_other_optimisations"></a>
+## what are the downsides?
+
+There are some downsides.
+
+The following apply if individual ("split") conf files are written, which in
+turn only happens if you used repo names instead of group names on the `repo`
+lines:
+
+ * the compile (gitolite-admin push) is now slower, because it potentially
+ has to write a few thousand small files instead of one large one. Since
+ the compile should be relatively infrequent compared to developer access,
+ this is ok -- the main config file is parsed much faster now, so every hit
+ to the server will benefit.
-### other optimisations
+ * we can no longer distinguish 'repo not found on disk' from 'you dont have
+ access'. They both now look like 'you dont have access'.
-<a name="_disabling_various_defaults"></a>
+## other optimisations
-#### disabling various defaults
+### disabling various defaults
The default RC file contains the following lines (we've already discussed the
first one):
@@ -265,9 +161,7 @@ authentication setup (ssh auth keys), respectively.
Summary: Please **leave those two variables alone** unless you're initials are
"JK" ;-)
-<a name="_optimising_the_authkeys_file"></a>
-
-#### optimising the authkeys file
+### #authkeyopt optimising the authkeys file
Sshd does a linear scan of the `~/.ssh/authorized_keys` file when an incoming
connection shows up. This means that keys found near the top get served
@@ -304,28 +198,7 @@ this (note the clever date command that always gets you last months log file!)
cat .gitolite/logs/gitolite-`date +%Y-%m -d -30days`.log |
cut -f2 | sort | uniq -c | sort -n -r
-<a name="_what_are_the_downsides_"></a>
-
-### what are the downsides?
-
-There are some downsides.
-
-The following apply if individual ("split") conf files are written, which in
-turn only happens if you used repo names instead of group names on the `repo`
-lines:
-
- * the compile (gitolite-admin push) is now slower, because it potentially
- has to write a few thousand small files instead of one large one. Since
- the compile should be relatively infrequent compared to developer access,
- this is ok -- the main config file is parsed much faster now, so every hit
- to the server will benefit.
-
- * we can no longer distinguish 'repo not found on disk' from 'you dont have
- access'. They both now look like 'you dont have access'.
-
-<a name="_storing_usergroup_information_outside_gitolite_like_in_LDAP_"></a>
-
-### storing usergroup information outside gitolite (like in LDAP)
+## F=ldap storing usergroup information outside gitolite (like in LDAP)
[Please NOTE: this is all about *user* groups, not *repo* groups]
@@ -335,9 +208,7 @@ the commit message for details]
Gitolite now allows usergroup information to be stored outside its own config
file. We'll see "why" first, then the "how".
-<a name="_why"></a>
-
-#### why
+### #_ldapwhy why
Large sites often have LDAP servers that already contain user and group
information, including group membership details. Such sites may prefer that
@@ -361,9 +232,7 @@ However, if the corporate LDAP server already tags these people correctly, and
if there is some way of getting that information out **at run time**, that
would be cool.
-<a name="_how"></a>
-
-#### how
+### #_ldaphow how
All you need is a script that, given a username, queries your LDAP or similar
server, and returns a space-separated list of all the groups she is a member
@@ -376,11 +245,7 @@ example scripts that were contributed by the Nokia MeeGo team.)
Then set the `$GL_GET_MEMBERSHIPS_PGM` variable in the rc file to the full
path of this program, set `$GL_BIG_CONFIG` to 1, and that will be that.
-[gwd]: http://sitaramc.github.com/gitolite/doc/2-admin.html#gwd
-
-<a name="_implementation_notes"></a>
-
-### implementation notes
+## implementation notes
To understand how big-config works (at least when you're using grouped repos),
we'll first look at how it works without this setting. Think back to the
@@ -419,3 +284,115 @@ inherits all permissions pertaining to the following combinations:
Anyway, all ACL rules for these combinations are clubbed together to make the
composite set of rules that 'alice' accessing 'lynx' is subject to.
+
+## config listings
+
+### F=_bigno compiled config with big-config disabled
+
+ %repos = (
+ 'firefox' => {
+ 'R' => {
+ 'alice' => 1,
+ 'bob' => 1
+ },
+ 'W' => {
+ 'alice' => 1,
+ 'bob' => 1
+ },
+ 'alice' => [
+ [
+ 0,
+ 'refs/heads/next',
+ 'RW+'
+ ],
+ [
+ 4,
+ 'refs/heads/master',
+ 'RW'
+ ]
+ ],
+ 'bob' => [
+ [
+ 1,
+ 'refs/heads/next',
+ 'RW+'
+ ],
+ [
+ 5,
+ 'refs/heads/master',
+ 'RW'
+ ]
+ ]
+ },
+ 'lynx' => {
+ 'R' => {
+ 'alice' => 1,
+ 'bob' => 1
+ },
+ 'W' => {
+ 'alice' => 1,
+ 'bob' => 1
+ },
+ 'alice' => [
+ [
+ 2,
+ 'refs/heads/next',
+ 'RW+'
+ ],
+ [
+ 6,
+ 'refs/heads/master',
+ 'RW'
+ ]
+ ],
+ 'bob' => [
+ [
+ 3,
+ 'refs/heads/next',
+ 'RW+'
+ ],
+ [
+ 7,
+ 'refs/heads/master',
+ 'RW'
+ ]
+ ]
+ }
+ );
+
+Phew!
+
+### F=_bigyes compiled config with big-config enabled
+
+ %repos = (
+ '@wbr' => {
+ '@devs' => [
+ [
+ 0,
+ 'refs/heads/next',
+ 'RW+'
+ ],
+ [
+ 1,
+ 'refs/heads/master',
+ 'RW'
+ ]
+ ],
+ 'R' => {
+ '@devs' => 1
+ },
+ 'W' => {
+ '@devs' => 1
+ }
+ }
+ );
+ %groups = (
+ '@devs' => {
+ 'alice' => 'master',
+ 'bob' => 'master'
+ },
+ '@wbr' => {
+ 'firefox' => 'master',
+ 'lynx' => 'master'
+ }
+ );
View
40 doc/delegation.mkd
@@ -1,20 +1,8 @@
-## delegating access control responsibilities
-
-In this document:
-
- * <a href="#_lots_of_repos_lots_of_users">lots of repos, lots of users</a>
- * <a href="#_how_to_use_delegation">how to use delegation</a>
- * <a href="#_the_subconf_command">the subconf command</a>
- * <a href="#_backward_compatibility">backward compatibility</a>
- * <a href="#_security_notes">security notes</a>
- * <a href="#_group_names">group names</a>
- * <a href="#_delegating_pubkeys">delegating pubkeys</a>
+# F=deleg delegating access control responsibilities
----
-<a name="_lots_of_repos_lots_of_users"></a>
-
-### lots of repos, lots of users
+## lots of repos, lots of users
Gitolite tries to make it easy to manage access to lots of users and repos,
exploiting commonalities wherever possible. It lets you specify bits and
@@ -39,9 +27,7 @@ for a set of repos to be specified in a **subconf** file and allow someone (a
**sub-admin**) to make changes within that file. (Note: sub-admins cannot
create or remove users).
-<a name="_how_to_use_delegation"></a>
-
-### how to use delegation
+## how to use delegation
First, you group your repos however you want. In the example below, I'm
considering firefox and lynx (projects at the root of the gitolite server) as
@@ -89,9 +75,7 @@ commit and push.
And that's really all there is to it.
-<a name="_the_subconf_command"></a>
-
-#### the subconf command
+### #subconf the subconf command
This command is much like the "include" command, but in addition it checks
that a subconf does not contain ACL rules for repos that are outside its
@@ -112,9 +96,7 @@ In more precise terms:
(Additional notes: it can also contain lines for an actual repo called
`webbrowsers`, or, in big-config mode, for a group called `@webbrowsers`).
-<a name="_backward_compatibility"></a>
-
-#### backward compatibility
+### backward compatibility
For backward compatibility, if no `subconf` commands have been seen at the end
of processing the main config file, gitolite pretends you appended
@@ -123,13 +105,9 @@ of processing the main config file, gitolite pretends you appended
to the end of the file.
-<a name="_security_notes"></a>
-
-### security notes
+## security notes
-<a name="_group_names"></a>
-
-#### group names
+### group names
You can use "@group"s defined in the main config file but do not attempt to
redefine or extend them in your own subconf file. If you must extend a group
@@ -141,9 +119,7 @@ redefine or extend them in your own subconf file. If you must extend a group
Group names you define in your subconf will not clash even if the exact same
name is used in another subconf file, so you need not worry about that.
-<a name="_delegating_pubkeys"></a>
-
-#### delegating pubkeys
+### delegating pubkeys
Short answer: not gonna happen.
View
54 doc/developer-notes.mkd
@@ -1,22 +1,6 @@
-## developer/patch maintainer notes
+# F=dev_notes developer/patch maintainer notes
-In this document:
-
- * <a href="#_general_stuff">general stuff</a>
- * <a href="#_the_rc_file">the rc file</a>
- * <a href="#_modules">modules</a>
- * <a href="#_that_bindir_thing">that 'bindir' thing</a>
- * <a href="#_from_perl">from perl</a>
- * <a href="#_from_shell">from shell</a>
- * <a href="#_OUTLIER_">OUTLIER!</a>
- * <a href="#_special_types_of_setups">special types of setups</a>
- * <a href="#_Fedora">Fedora</a>
-
-----
-
-<a name="_general_stuff"></a>
-
-### general stuff
+## general stuff
* all scripts and libraries must be in the same directory. However, RPM/DEB
packagers can put the libraries where they want, as long as they can be
@@ -36,31 +20,23 @@ In this document:
much all of them are run via gl-auth-command or from something that was
forked from it so the variables *will* exist during normal operation.
-<a name="_the_rc_file"></a>
-
-### the rc file
+## the rc file