-
Notifications
You must be signed in to change notification settings - Fork 999
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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
Showing
45 changed files
with
1,080 additions
and
2,592 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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)**. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.