Permalink
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...
1 parent 3f87430 commit 6e29365316f93b7039a23937bde0e69dd0294bce @sitaramc committed Nov 1, 2011
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
@@ -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)**.
@@ -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
@@ -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
@@ -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)
Oops, something went wrong.

0 comments on commit 6e29365

Please sign in to comment.