From 5f342c0444771ba21a2aeb05fff307590e10b79b Mon Sep 17 00:00:00 2001 From: Sitaram Chamarty Date: Thu, 2 Sep 2010 19:15:32 +0530 Subject: [PATCH] more doc revamp; some notes below - all anchors prefixed by AUTO_ now - some bad links fixed (maybe still a few I didn't catch) - misc wording changes/additions (support section to README, "technical skills" section to install doc, etc). --- README.mkd | 85 +++++--- doc/{0-INSTALL.mkd => 1-INSTALL.mkd} | 184 ++++++++++++------ doc/2-admin.mkd | 84 ++++---- doc/3-faq-tips-etc.mkd | 177 ++++++++--------- doc/admin-defined-commands.mkd | 43 ++-- doc/big-config.mkd | 28 +-- doc/{5-delegation.mkd => delegation.mkd} | 29 ++- ...olite-and-ssh.mkd => gitolite-and-ssh.mkd} | 16 +- doc/hook-propagation.mkd | 40 ++-- ...-transcript.mkd => install-transcript.mkd} | 34 ++-- doc/{1-migrate.mkd => migrate.mkd} | 4 +- doc/mirroring.mkd | 62 +++--- doc/{9-packaging.mkd => packaging.mkd} | 0 doc/progit-article.mkd | 18 +- doc/report-output.mkd | 18 +- ...leshooting.mkd => ssh-troubleshooting.mkd} | 80 ++++---- doc/{9-uninstall.mkd => uninstall.mkd} | 0 ...sitories.mkd => wildcard-repositories.mkd} | 50 +++-- 18 files changed, 527 insertions(+), 425 deletions(-) rename doc/{0-INSTALL.mkd => 1-INSTALL.mkd} (54%) rename doc/{5-delegation.mkd => delegation.mkd} (82%) rename doc/{9-gitolite-and-ssh.mkd => gitolite-and-ssh.mkd} (92%) rename doc/{7-install-transcript.mkd => install-transcript.mkd} (89%) rename doc/{1-migrate.mkd => migrate.mkd} (98%) rename doc/{9-packaging.mkd => packaging.mkd} (100%) rename doc/{6-ssh-troubleshooting.mkd => ssh-troubleshooting.mkd} (87%) rename doc/{9-uninstall.mkd => uninstall.mkd} (100%) rename doc/{4-wildcard-repositories.mkd => wildcard-repositories.mkd} (86%) diff --git a/README.mkd b/README.mkd index 80a4e4b..6e91578 100644 --- a/README.mkd +++ b/README.mkd @@ -1,3 +1,5 @@ + + # gitolite Gitolite is an access control layer on top of git, which allows access control @@ -8,45 +10,39 @@ Gitolite comes with a **huge** amount of documentation. If you're absolutely new, the suggested reading order is this: * the README (this document) for a quick intro - * **IMPORTANT:** if you don't know anything about ssh, read [this][doc9gas] * the [INSTALL][install] document - * if you run into trouble with ssh, read [this][doc6sts] * the [ADMIN][admin] document - * if you're migrating from gitosis, read [this][migr] + +If you run into trouble start [here](#support). If you're migrating from +gitosis, read [this][migr]. Once you've installed it and started using it, you'll want to explore some of the more powerful features. All the documentation is available in the source repo as well as [online][docs]. All the longer documents have tables of contents, so you can quickly get a feel for what is covered right at the top. -[install]: http://github.com/sitaramc/gitolite/blob/master/doc/0-INSTALL.mkd -[admin]: http://github.com/sitaramc/gitolite/blob/master/doc/2-admin.mkd -[migr]: http://github.com/sitaramc/gitolite/blob/master/doc/1-migrate.mkd -[docs]: http://github.com/sitaramc/gitolite/blob/pu/doc -[doc9gas]: http://github.com/sitaramc/gitolite/blob/pu/doc/9-gitolite-and-ssh.mkd -[doc6sts]: http://github.com/sitaramc/gitolite/blob/pu/doc/6-ssh-troubleshooting.mkd - ---- In this document: - * what - * why - * other features - * security - * contact and license + * what + * why + * main features + * support + * security + * contact and license ---- - + ### what -Gitolite allows a server to host many git repositories and provide access to -many developers, without having to give them real userids on or shell access -to the server. The essential magic in doing this is ssh's pubkey access and -the `authorized_keys` file, and the inspiration was an older program called -gitosis. +Gitolite lets you use a single user on a server to host many git repositories +and provide access to many developers, without having to give them real +userids on or shell access to the server. The essential magic in doing this +is ssh's pubkey access and the `authorized_keys` file, and the inspiration was +an older program called gitosis. Gitolite can restrict who can read from (clone/fetch) or write to (push) a repository. It can also restrict who can push to what branch or tag, which is @@ -55,7 +51,7 @@ requiring root permissions, and with no additional software than git itself and perl. It also has several other neat features described below and elsewhere in the [doc/][docs] directory. - + ### why @@ -74,9 +70,9 @@ 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...! + killer, especially in tightly controlled environments * adding/removing access rights involves complex `usermod -G ...` mumblings - which most admins would rather not deal with, thanks to you-know-who + 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 @@ -102,9 +98,9 @@ Gitolite does away with all this: read-write access, not only at the repository level, but at the branch level within repositories. - + -### other features +### 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 @@ -136,7 +132,26 @@ detail somewhere in gitolite's [doc/][docs] subdirectory. * specify repos using patterns (patterns may include creator's name) * define powerful operations on the server side, even github-like forking - + + + + +### support + +Most installation problems are caused by not knowing ssh. Take a look at this +[transcript][] to see how simple it actually is, if your server's ssh daemon +is behaving itself. + +If I suspect your problem is an ssh issue, I will probably ignore it. Please +learn how [gitolite uses ssh][doc9gas] and then methodically go through the +[ssh trouble shooting][doc6sts] document. These two documents contain +everything I could possibly tell you. I have nothing to add. + +Even for other topics, please look through at least the table of contents of +at least the numbered documents to see if your question is already answered, +before asking. + + ### security @@ -158,11 +173,21 @@ details, looking for the word "security". ---- - + ### contact and license Gitolite is released under GPL v2. See COPYING for details. -sitaramc@gmail.com -mailing list: gitolite@googlegroups.com + * author: sitaramc@gmail.com, sitaram@atc.tcs.com + * mailing list: gitolite@googlegroups.com + * list subscribe address : gitolite+subscribe@googlegroups.com + +[transcript]: http://github.com/sitaramc/gitolite/blob/pu/doc/install-transcript.mkd +[install]: http://github.com/sitaramc/gitolite/blob/pu/doc/1-INSTALL.mkd +[admin]: http://github.com/sitaramc/gitolite/blob/pu/doc/2-admin.mkd +[migr]: http://github.com/sitaramc/gitolite/blob/pu/doc/migrate.mkd +[docs]: http://github.com/sitaramc/gitolite/blob/pu/doc +[doc9gas]: http://github.com/sitaramc/gitolite/blob/pu/doc/gitolite-and-ssh.mkd +[doc6sts]: http://github.com/sitaramc/gitolite/blob/pu/doc/ssh-troubleshooting.mkd + diff --git a/doc/0-INSTALL.mkd b/doc/1-INSTALL.mkd similarity index 54% rename from doc/0-INSTALL.mkd rename to doc/1-INSTALL.mkd index 8c0f2f4..ae801c4 100644 --- a/doc/0-INSTALL.mkd +++ b/doc/1-INSTALL.mkd @@ -2,40 +2,42 @@ In this document: - * please read this first - * important notes - * conventions used - * requirements - * client side - * server side - * installation and setup - * (package method) directly on the server, using RPM/DEB - * (root method) directly on the server, manually, with root access - * (non-root method) directly on the server, manually, without root access - * (from-client method) install from the client to the server - * URLs for gitolite-managed repos - * special cases -- multiple gitolite servers - * package method and root method - * from-client method - * upgrading - * uninstalling - * cleaning out a botched install - * uninstalling gitolite completely + * please read this first + * important notes + * conventions used + * requirements + * client/workstation + * server + * technical skills + * installation and setup + * install methods and deciding which one to use + * (package method) directly on the server, using RPM/DEB + * (root method) directly on the server, manually, with root access + * (non-root method) directly on the server, manually, without root access + * (from-client method) install from the client to the server + * URLs for gitolite-managed repos + * special cases -- multiple gitolite servers + * package method and root method + * from-client method + * upgrading + * uninstalling + * cleaning out a botched install + * uninstalling gitolite completely ---- - + ### please read this first - + #### important notes Please make sure you understand the following points first. - * gitolite is somewhat unusual as far as "server" software goes -- every - userid on the server is a potential "gitolite host". + * gitolite runs as a single user on a server, and is invoked via ssh. Thus, + every user on the server is a potential "gitolite host". * gitolite depends **heavily** on ssh pubkey (passwordless) access. Do not assume you know all about ssh -- most people **don't**. If in doubt, use @@ -43,23 +45,45 @@ Please make sure you understand the following points first. administration of gitolite. To make matters worse, ssh problems in gitolite don't always look like ssh - problems. See [doc/6-ssh-troubleshooting.mkd][doc6] for help. + problems. See [doc/ssh-troubleshooting.mkd][doc6] for help. - +A gitolite setup has: + + * a server + * a "hosting user" on the server -- the userid under which gitolite runs. + You can have any number of "hosting users" on one server; in fact every + user can host their own gitolite instance + * an "admin user" -- the user who sets up gitolite and configures it + * the admin user's client or workstation, from which he does all his work + +It is possible to have the server and the client be the same machine, and even +the admin user be also the hosting user, (i.e., `sitaram@server` can install +and administer a gitolite setup running under `sitaram@server`, a situation +that is common with some hosting services). It's actually fairly easy and +**safe** to do, **as long as you have password access to the server** for +emergency use. However, I will not be documenting it because (a) if you know +ssh you'll know how to extrapolate my instructions to do this and (b) if you +don't know ssh it'll be a nightmare to support you. + + #### conventions used -We assume the admin user is "sitaram", and his workstation is called "client". -The hosting user is "git", and the server is called "server". Substitute your -values as needed. +Throughout the documentation, we use "sitaram" as the admin user, and his +workstation is called "client". The hosting user is "git", and the server is +called "server". **Please substitute your values as needed**. - +Also, we often say "the rc file". This means `~/.gitolite.rc` on the server. +And when we say the "access control rules", or "conf file", or "config file", +we mean `conf/gitolite.conf` on your gitolite-admin clone. + + #### requirements - + -##### client side +##### client/workstation * git version 1.6.2 or greater * even msysgit on Windows is fine; please don't ask me for help if @@ -69,9 +93,9 @@ values as needed. shell is needed * again, msysgit on Windows is fine - + -##### server side +##### server * any Unix system with a posix compatible "sh". * people using "csh" or derivatives please don't ask me for help -- tell @@ -82,11 +106,47 @@ values as needed. * perl (but since git requires it anyway, you probably have it) * openssh or any ssh that can understand the `authorized_keys` file format - + + +##### technical skills + + * if you're installing gitolite, you're a "system admin", like it or not. + Ssh is therefore a necessary skill. Please take the time to learn at + least enough to get passwordless access working. + + * you also need to be somewhat familiar with git itself. You cannot + administer a whole bunch of git repositories if you don't know the basics + of git. + + * some familiarity with Unix and shells is probably required + + * regular expressions are a big part of gitolite in many places but + familiarity is not necessary to do basic access control. + + ### installation and setup - + + + + +#### install methods and deciding which one to use + +Gitolite has 4 install methods: + + * **package method** if you have a gitolite RPM or a DEB available + * **root method** if you have root access to the server, and you plan to + have multiple "hosting users" on it + * **non-root method** if you don't have root access to the server, but you + do have at least one account with a password + * **from-client method** if you are not comfortable with public keys and + server side commands + +Here's how you install using these 3 methods. Future upgrades are equally +easy -- the steps required for upgrading are marked "(U)". + + #### (package method) directly on the server, using RPM/DEB @@ -100,7 +160,7 @@ values as needed. * on the client, run `cd; git clone git@server:gitolite-admin` - + #### (root method) directly on the server, manually, with root access @@ -122,7 +182,7 @@ values as needed. * on the client, run `cd; git clone git@server:gitolite-admin` - + #### (non-root method) directly on the server, manually, without root access @@ -151,22 +211,25 @@ server so that if you screw up the keys you can still get on, or be able to * on the client, run `cd; git clone git@server:gitolite-admin` - + + + #### (from-client method) install from the client to the server -This used to be the most common install method for a long time, and it is -still the one I use for most of my testing. The **main advantage** of this -method is that it **forces you** to solve the ssh pubkey problem **before** -attempting to install. Sadly, it also forces the admin to use a **different** -URL for gitolite repos than normal users, which seems to confuse a heck of a -lot of people who don't read the prominently displayed messages and/or the -documentation. +The advantage of this method is that it forces you to solve the ssh pubkey +problem **before** attempting to install. It works best if you have dedicated +userids, one on the server for installing gitolite, and one the client for +administering it. -This method is verbosely documented in [doc/7-install-transcript.mkd][doc7], -including *outputs* of the commands concerned. +Sadly, it also forces the admin to use a different URL to access gitolite +repos than normal users, which seems to confuse a heck of a lot of people who +don't read the prominently displayed messages and/or the documentation. - +This method is verbosely documented in this [transcript][], including +*outputs* of the commands concerned. + + ### URLs for gitolite-managed repos @@ -181,11 +244,11 @@ However, in the fourth ("from-client") method, the admin user needs a different URL (`gitolite:reponame`) to gain access to the gitolite repositories. Check [here][twokeys] for why. - + ### special cases -- multiple gitolite servers - + #### package method and root method @@ -209,7 +272,7 @@ to have a command line on the server, so don't give them the passwords if you don't need to -- the pubkey will allow them to be gitolite admins on their domain, and that's quite enough for normal operations. - + #### from-client method @@ -229,7 +292,7 @@ have been created as respective clones. Or you can re-clone elsewhere: cd ~/admin1; git clone gitolite_server_1:gitolite-admin.git cd ~/admin2; git clone gitolite_server_2:gitolite-admin.git - + ### upgrading @@ -244,11 +307,11 @@ also. Also, remember that some new features may require additional settings in your `~/.gitolite.rc` file. - + ### uninstalling - + #### cleaning out a botched install @@ -266,18 +329,17 @@ here's how to clean the slate. * remove `~/.gitolite`, `~/.gitolite.rc` and `~/repositories/gitolite-admin.git` - + #### uninstalling gitolite completely There's some duplication between this and the previous section, but uninstalling gitolite is described in great detail in -[doc/9-uninstall.mkd][doc9unin] +[doc/uninstall.mkd][doc9unin] ---- -[doc6]: http://github.com/sitaramc/gitolite/blob/pu/doc/6-ssh-troubleshooting.mkd -[doc7]: http://github.com/sitaramc/gitolite/blob/pu/doc/7-install-transcript.mkd -[doc9unin]: http://github.com/sitaramc/gitolite/blob/pu/doc/9-uninstall.mkd -[doc9ssh]: http://github.com/sitaramc/gitolite/blob/pu/doc/9-ssh-tips.mkd -[twokeys]: http://github.com/sitaramc/gitolite/blob/pu/doc/6-ssh-troubleshooting.mkd#why_two_keys_on_client +[doc6]: http://github.com/sitaramc/gitolite/blob/pu/doc/ssh-troubleshooting.mkd +[doc9unin]: http://github.com/sitaramc/gitolite/blob/pu/doc/uninstall.mkd +[twokeys]: http://github.com/sitaramc/gitolite/blob/pu/doc/ssh-troubleshooting.mkd#twokeys +[transcript]: http://github.com/sitaramc/gitolite/blob/pu/doc/install-transcript.mkd diff --git a/doc/2-admin.mkd b/doc/2-admin.mkd index 9b2a7be..5f979c2 100644 --- a/doc/2-admin.mkd +++ b/doc/2-admin.mkd @@ -1,38 +1,46 @@ # administering and running gitolite +In this document: + + * please read this first + * adding users and repos + * other features + * moving pre-existing repos into gitolite + * specifying gitweb and daemon access + * custom hooks + * hook chaining + * environment variables available to hooks + * custom git config + +---- + + + +### please read this first + +Unless you know what you're doing, do not do **anything** manually on the +server, like adding new repositories or users or changing the access control +rules. Things will break. For example, if you manually create a repo on the +server, it will not have the required "update" hook, without which there is no +access control for pushes. + +Most normal (day-to-day) gitolite admin work is done by cloning the +gitolite-admin repo from the server to your workstation, making changes to the +clone, and pushing those changes back. + +The installation steps in the previous section include the steps to do this +clone, so you should already have one on your workstation, in +`~/gitolite-admin`. You can of course clone it anywhere else you want and use +that clone. + +Either way, make sure you `cd` into this clone first. + *Note*: some of the paths in this document use variable names. Just refer to `~/.gitolite.rc` for the correct values for *your* installation. -In this document: - - * please read this first - * adding users and repos - * other features - * moving pre-existing repos into gitolite - * specifying gitweb and daemon access - * custom hooks - * hook chaining - * environment variables available to hooks - * custom git config - ----- - - - -### please read this first - - * ***do NOT add new repos manually***, unless you know how to add the - required hook as well. Without the hook, branch-level access control will - not work for that repo, which sorta defeats the idea of using gitolite :-) - - * most normal (day-to-day) gitolite admin work is done by cloning the - gitolite-admin repo from the server to your workstation, making changes to - the clone, and pushing those changes back. The installation steps in - [doc/0-INSTALL.mkd][doc0] include the steps to do this clone if needed. - Once you've cloned it, you're ready to add users and repos. - + ### adding users and repos @@ -57,11 +65,11 @@ Once you've cloned it, you're ready to add users and repos. automatically be created (empty, but clonable) and users' access will be updated as needed. - + ### other features - + #### moving pre-existing repos into gitolite @@ -93,7 +101,7 @@ to take a bunch of existing repos and add them to gitolite: `conf/gitolite.conf` in your gitolite-admin repo clone. Then add, commit, push. - + #### specifying gitweb and daemon access @@ -102,10 +110,7 @@ like unauthenticated access of any kind to any repo!), but someone wanted it, so here goes. To make a repo or repo group accessible via "git daemon", just give read -permission to the special user "daemon". See the [faq, tips, etc][ss] -document for easy ways to specify access for multiple repositories. - -[ss]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#gwd +permission to the special user "daemon". There's a special user called "gitweb" also, which works the same way. However, setting a description for the project also enables gitweb permissions @@ -131,7 +136,7 @@ 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. - + #### custom hooks @@ -150,7 +155,7 @@ implements all the branch-level permissions in gitolite. If you fiddle with the hooks directory, please make sure you do not mess with this file accidentally, or all your fancy per-branch permissions will stop working.** - + #### hook chaining @@ -173,7 +178,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. - + #### environment variables available to hooks @@ -189,7 +194,7 @@ 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 - + #### custom git config @@ -213,6 +218,5 @@ basic forms of the "git config" command: It does not (currently) support other options like `--add`, the `value_regex`, etc. -[doc0]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd [genpub]: http://sitaramc.github.com/0-installing/2-access-gitolite.html#generating_a_public_key diff --git a/doc/3-faq-tips-etc.mkd b/doc/3-faq-tips-etc.mkd index 4a65e2e..466471f 100644 --- a/doc/3-faq-tips-etc.mkd +++ b/doc/3-faq-tips-etc.mkd @@ -2,48 +2,48 @@ In this document: - * common errors and mistakes - * git version dependency - * other errors, warnings, notes... - * cloning an empty repo - * `@all` syntax for repos - * umask setting - * getting a tar file from a clone - * features - * syntax and normal usage - * simpler syntax - * one user, many keys - * security, access control, and auditing - * two levels of access rights checking - * better logging - * "exclude" (or "deny") rules - * separating delete and rewind rights - * separating create and push rights - * file/dir NAME based restrictions - * delegating parts of the config file - * convenience features - * what repos do I have access to? - * including config lines from other files - * support for git installed outside default PATH - * "personal" branches - * custom hooks and custom git config - * bypassing gitolite - * INconvenience features - * deleting a repo - * helping with gitweb - * easier to specify gitweb "description" and gitweb/daemon access - * easier to link gitweb authorisation with gitolite - * advanced features - * repos named with wildcards - * admin defined commands - * access control for external commands - * svnserve - * design choices - * keeping the parser and the access control separate + * common errors and mistakes + * git version dependency + * other errors, warnings, notes... + * cloning an empty repo + * `@all` syntax for repos + * umask setting + * getting a tar file from a clone + * features + * syntax and normal usage + * simpler syntax + * one user, many keys + * security, access control, and auditing + * two levels of access rights checking + * better logging + * "exclude" (or "deny") rules + * separating delete and rewind rights + * separating create and push rights + * file/dir NAME based restrictions + * delegating parts of the config file + * convenience features + * what repos do I have access to? + * including config lines from other files + * support for git installed outside default PATH + * "personal" branches + * custom hooks and custom git config + * bypassing gitolite + * INconvenience features + * deleting a repo + * helping with gitweb + * easier to specify gitweb "description" and gitweb/daemon access + * easier to link gitweb authorisation with gitolite + * advanced features + * repos named with wildcards + * admin defined commands + * access control for external commands + * svnserve + * design choices + * keeping the parser and the access control separate ---- - + ### common errors and mistakes @@ -65,19 +65,19 @@ In this document: In other words, you used a key that completely bypassed gitolite and went straight to the shell to do the clone. - Please see doc/6-ssh-troubleshooting.mkd for what all this means. + Please see doc/ssh-troubleshooting.mkd for what all this means. - + ### git version dependency Gitolite (on the server) now refuses to run if git is not at least 1.6.2. - + ### other errors, warnings, notes... - + #### cloning an empty repo @@ -90,7 +90,7 @@ end hung up unexpectedly`. However, you can ignore this, since it doesn't seem to hurt anything. [Update 2009-09-14; this has been fixed in git 1.6.4.3] - + #### `@all` syntax for repos @@ -102,14 +102,14 @@ There *is* a way to use the `@all` syntax for repos also, as described in access, we do not support this. * don't try giving `@all` users some permission for `@all` repos - + #### umask setting Gitweb not able to read your repos? You can change the umask for newly created repos to something more relaxed -- see the `~/.gitolite.rc` file - + ### getting a tar file from a clone @@ -125,7 +125,7 @@ plain "git archive", because the Makefile adds a file called make master.tar # or maybe "make pu.tar" - + ### features @@ -133,11 +133,11 @@ Apart from the big ones listed in the top level README, and subjective ones like "better config file format", gitolite has evolved to have many useful features than the original goal of branch-level access control. - + #### syntax and normal usage - + ##### simpler syntax @@ -182,7 +182,9 @@ do not worry that this causes some duplication or inefficiency. It doesn't See the "specify gitweb/daemon access" section below for one more example. - + + + ##### one user, many keys @@ -227,11 +229,11 @@ corresponding derived usernames (which is what goes into the sitaramc@gmail.com@laptop.pub sitaramc@gmail.com sitaramc@gmail.com@desktop.pub sitaramc@gmail.com - + #### security, access control, and auditing - + ##### two levels of access rights checking @@ -267,7 +269,7 @@ any of the refexes match, the push succeeds. If none of them match, it fails. Gitolite also allows "exclude" or "deny" rules. See later in this document for details. - + ##### better logging @@ -295,7 +297,7 @@ The other parts of the log line are the name of the repo, the refname being updated, the user updating it, and the refex pattern (from the config file) that matched, in case you need to debug the config file itself. - + ##### "exclude" (or "deny") rules @@ -346,7 +348,7 @@ And here's how it works: before the third one, and it has a `-` as the permission, so the push fails - + ##### separating delete and rewind rights @@ -386,9 +388,7 @@ message when you push, a non-existant user. Note 3: you can combine this with the "create a branch" permissions described in the next section, as the example line in conf/example.conf shows. -[sdrr]: http://groups.google.com/group/gitolite/browse_thread/thread/9f2b4358ce406d4c# - - + ##### separating create and push rights @@ -406,7 +406,7 @@ Briefly: Note: you can combine this with the "delete a branch" permissions described in the previous section, as the example line in conf/example.conf shows. - + ##### file/dir NAME based restrictions @@ -417,20 +417,18 @@ changed, treating each filename as a "ref" to be matched. Please see `conf/example.conf` for syntax and examples. - + ##### delegating parts of the config file You can now split up the config file and delegate the authority to specify -access control for their own pieces. See -[doc/5-delegation.mkd](http://github.com/sitaramc/gitolite/blob/pu/doc/5-delegation.mkd) -for details. +access control for their own pieces. See [delegation][] for details. - + #### convenience features - + ##### what repos do I have access to? @@ -441,15 +439,13 @@ etc. You'd just like a simple way to know what repos you have access to. Gitolite provides two commands (`info` and `expand`) to help you find this information; please check [doc/report-output.mkd][repout] for details. -[repout]: http://github.com/sitaramc/gitolite/blob/pu/doc/report-output.mkd - - + ##### including config lines from other files See the entry under "INCLUDE SOME OTHER FILE" in `conf/example.conf`. - + ##### support for git installed outside default PATH @@ -483,7 +479,7 @@ the full PATH in the rc file, like so: $ENV{PATH} = "/home/sitaram/bin:$ENV{PATH}"; - + ##### "personal" branches @@ -507,7 +503,7 @@ important thing is that the "branch" name should contain `/USER/` (including the slashes). At runtime this will match whoever is the current user. Access is still determined by the right hand side of course. - + ##### custom hooks and custom git config @@ -515,7 +511,7 @@ You can specify hooks that you want to propagate to all repos, as well as per-repo "gitconfig" settings. Please see `doc/2-admin.mkd` and `conf/example.conf` for details. - + ##### bypassing gitolite @@ -538,11 +534,11 @@ to set that variable permanently, preferring this mode instead: GL_BYPASS_UPDATE_HOOK=1 git push - + #### INconvenience features - + ##### deleting a repo @@ -550,8 +546,6 @@ By design, there is no code in gitolite to *delete* a repo if the repo was specified by name in the config file. (Wildcard repos *can* be deleted by the user; see [here][rmrepo] for details). -[rmrepo]: http://github.com/sitaramc/gitolite/blob/pu/doc/admin-defined-commands.mkd#rmrepo - If you *do* want to permanently delete a *non*-wildcard repo, here's what you do: @@ -561,7 +555,7 @@ do: * *then* remove the repo from `~/repositories` on the server (or whatever you set `$GL_REPO_BASE` to in the `~/.gitolite.rc`) - + #### helping with gitweb @@ -569,7 +563,9 @@ Although gitweb is a completely separate program, gitolite can do quite a lot to help you manage gitweb access as well; once the initial setup is complete, you can do it all from within the gitolite config file! - + + + ##### easier to specify gitweb "description" and gitweb/daemon access @@ -618,7 +614,7 @@ Here's an example, using really short reponames because I'm lazy: repo r2 # ...and so on... - + ##### easier to link gitweb authorisation with gitolite @@ -654,24 +650,24 @@ Gitweb allows you to specify a subroutine to decide on access. We use that feature and tie it to gitolite. Configuration example can be found in `contrib/gitweb/`. - + #### advanced features - + ##### repos named with wildcards -Please see `doc/4-wildcard-repositories.mkd` for all the details. +Please see `doc/wildcard-repositories.mkd` for all the details. - + ##### admin defined commands This requires the wildcards feature to be enabled, but is then an extremely powerful feature. See `doc/admin-defined-commands.mkd`. - + ##### access control for external commands @@ -681,7 +677,7 @@ server-side command that contains enough information to make an access control decision. Note that this is incompatible with giving people shell access as described in -`doc/6-ssh-troubleshooting.mkd` -- people who have shell access are not +`doc/ssh-troubleshooting.mkd` -- people who have shell access are not subject to this mechanism (it wouldn't make sense to try and control someone who has shell access anyway). @@ -695,7 +691,7 @@ Commands implemented so far are: * svnserve (see next section for a brief description; this has been contributed by Simon and Vladimir) - + ###### svnserve @@ -707,11 +703,11 @@ system. Assuming you installed gitolite to the same user as the one you used for SVN, SVN connectivity will be retained, and users will be able to use both SVN and git using the same SSH configuration. - + ### design choices - + #### keeping the parser and the access control separate @@ -732,3 +728,8 @@ have to be first "compiled", and the access control programs use this If you choose the "easy install" method, all this is quite transparent to you anyway. If you cannot use the easy install and must install manually, I have clear instructions on how to set it up. + +[repout]: http://github.com/sitaramc/gitolite/blob/pu/doc/report-output.mkd +[sdrr]: http://groups.google.com/group/gitolite/browse_thread/thread/9f2b4358ce406d4c# +[delegation]: http://github.com/sitaramc/gitolite/blob/pu/doc/delegation.mkd +[rmrepo]: http://github.com/sitaramc/gitolite/blob/pu/doc/admin-defined-commands.mkd#rmrepo diff --git a/doc/admin-defined-commands.mkd b/doc/admin-defined-commands.mkd index 61e4b6a..36f7b9e 100644 --- a/doc/admin-defined-commands.mkd +++ b/doc/admin-defined-commands.mkd @@ -11,18 +11,18 @@ There may be other such **WARNING** sections below. **Read all of them**. In this document: - * background - * setting it up - * anatomy of a command - * example uses and sample commands in contrib - * fork - * rmrepo - * enable/disable push access temporarily - * (bonus) restricted admin + * background + * setting it up + * anatomy of a command + * example uses and sample commands in contrib + * fork + * rmrepo + * enable/disable push access temporarily + * (bonus) restricted admin ---- - + ### background @@ -36,9 +36,6 @@ resisted the urge to point him to [this][xkcd224], told him that's a great idea and he should go for it, mentally blessing him for letting me off the hook on coding it ;-) [Laziness][lazy] *is* the first virtue you know! -[xkcd224]: http://xkcd.com/224/ -[lazy]: http://c2.com/cgi/wiki?LazinessImpatienceHubris - And that was that. For a couple of days. Soon, though, I realised that there could be a pretty big bonus in this for @@ -47,13 +44,11 @@ on "restricted admin" for what's really exciting about this for *me*. ---- -It may be a good idea to read [doc/4-wildcard-repositories.mkd][wild] before +It may be a good idea to read [doc/wildcard-repositories.mkd][wild] before you continue here though, because most of the uses of this feature also need wildcard repos. (This also means you must set `$GL_WILDREPOS` to "1" in the rc file). -[wild]: http://github.com/sitaramc/gitolite/blob/pu/doc/4-wildcard-repositories.mkd - The wildcard repo feature is a way to create repositories matching a pattern (even if it as simple as `personal/CREATOR/.+`), and a way to specify two categories of permissions for each such user-created repo. @@ -62,7 +57,7 @@ What we want now is more than that, as you'll see in the examples below. And I'm sure if you think of more uses you'll send them to me as "contrib" entries, right? - + ### setting it up @@ -82,7 +77,7 @@ to inadvertently *hide* some of the "official" commands (like "info", executable files with those names in this directory. So don't do that -- you have been warned!** - + ### anatomy of a command @@ -137,11 +132,11 @@ convenient. See any of the other samples for how to use it. If you don't like this, roll your own. If you don't like bash, do the eqvt in your language of choice. - + ### example uses and sample commands in contrib - + #### fork @@ -169,6 +164,8 @@ or some such incantation. + + #### rmrepo This is one thing that you really could not do before this setup was created. @@ -179,7 +176,7 @@ Use it like this: The script checks to make sure that the repo being deleted was *created* by the user invoking it. - + #### enable/disable push access temporarily @@ -217,7 +214,7 @@ in doc/2. You need code like this in `update.secondary` (don't forget to exit 0 - + #### (bonus) restricted admin @@ -239,3 +236,7 @@ script to proceed. [Note that this particular use does not require `$GL_WILDREPOS` to be enabled, because it's not using any wildcard repos]. + +[xkcd224]: http://xkcd.com/224/ +[lazy]: http://c2.com/cgi/wiki?LazinessImpatienceHubris +[wild]: http://github.com/sitaramc/gitolite/blob/pu/doc/wildcard-repositories.mkd diff --git a/doc/big-config.mkd b/doc/big-config.mkd index bbe126d..b2f35b0 100644 --- a/doc/big-config.mkd +++ b/doc/big-config.mkd @@ -2,13 +2,13 @@ In this document: - * when/why do we need it? - * how do we use it? - * other optimisations - * what are the downsides? - * (extra coolness) usergroups and LDAP/similar tools + * when/why do we need it? + * how do we use it? + * other optimisations + * what are the downsides? + * (extra coolness) usergroups and LDAP/similar tools - + ### when/why do we need it? @@ -95,7 +95,7 @@ Phew! You can imagine what that does when you have 10,000 users and 10,000 repos. Let's just say it's not pretty :) - + ### how do we use it? @@ -143,7 +143,7 @@ looks like this: That's a lot smaller, and allows orders of magintude more repos and groups to be supported. - + ### other optimisations @@ -158,8 +158,8 @@ first one): `GL_NO_DAEMON_NO_GITWEB` is a very useful optimisation that you *must* enable if you *do* have a large number of repositories, and do *not* use gitolite's support for gitweb or git-daemon access (see "[easier to specify gitweb -description and gitweb/daemon access][gw]" for details). This will save a lot -of time when you push the gitolite-admin repo with changes. This variable +description and gitweb/daemon access][gwd]" for details). This will save a +lot of time when you push the gitolite-admin repo with changes. This variable also control whether "git config" lines (such as `config hooks.emailprefix = "[gitolite]"`) will be processed or not. @@ -176,9 +176,7 @@ Also note that using all 3 of the `GL_NO_*` variables will result in *everything* after the config compile being skipped. In other words, gitolite is being used **only** for its access control language. -[gw]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#gitweb - - + ### what are the downsides? @@ -192,7 +190,7 @@ subset of the allowed @fragname, which would work normally, do not work now). (If you didn't understand all that, you're probably not using delegation, so feel free to ignore it!) - + ### (extra coolness) usergroups and LDAP/similar tools @@ -238,3 +236,5 @@ specified: @foo = alice @bar = alice + +[gwd]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#gwd diff --git a/doc/5-delegation.mkd b/doc/delegation.mkd similarity index 82% rename from doc/5-delegation.mkd rename to doc/delegation.mkd index 8cc341f..c711bf6 100644 --- a/doc/5-delegation.mkd +++ b/doc/delegation.mkd @@ -6,25 +6,22 @@ In this document: - * lots of repos, lots of users - * splitting up the set of repos into groups - * delegating ownership of groups of repos - * security/philosophy note + * lots of repos, lots of users + * splitting up the set of repos into groups + * delegating ownership of groups of repos + * security/philosophy note ---- - + ### 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. (The example in [this -section][ss] should give you an idea). As you can see, it lets you specify -bits and pieces of the access control separately -- i.e., *all* the access -specs for a certain repo need not be together; they can be scattered, which -makes it easier to manage the sort of slice and dice needed in that example. - -[ss]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#simpler_syntax +exploiting commonalities wherever possible. It lets you specify bits and +pieces of the access control separately -- i.e., *all* the access specs for a +certain repo need not be together; they can be scattered, which makes it +easier to manage the sort of slice and dice needed in that example. But eventually the config file will become too big. If you let only one person have control, he could become a bottleneck. If you give it to multiple @@ -47,7 +44,7 @@ access control rules for a set of repos they have been given authority for. It's easier to show how it all works with an example instead of long descriptions. - + ### splitting up the set of repos into groups @@ -63,7 +60,7 @@ or repos, same syntax). So the basic idea is that the main config file # any other config as usual, including access control lines for any of the # above projects or groups - + ### delegating ownership of groups of repos @@ -117,7 +114,7 @@ to the bottom of the main file. ---- - + ### security/philosophy note @@ -136,4 +133,4 @@ If you feel the need to delegate even that, please just go the whole hog and give them separate gitolite instances! It's pretty easy to setup the *software* itself system-wide, so that many users can use it without all the "easy install" fuss. See the "system install / user setup" section in -doc/0-INSTALL.mkd for details. +doc/1-INSTALL.mkd for details. diff --git a/doc/9-gitolite-and-ssh.mkd b/doc/gitolite-and-ssh.mkd similarity index 92% rename from doc/9-gitolite-and-ssh.mkd rename to doc/gitolite-and-ssh.mkd index 26087dd..f4bd74b 100644 --- a/doc/9-gitolite-and-ssh.mkd +++ b/doc/gitolite-and-ssh.mkd @@ -13,14 +13,14 @@ blaming ***git/gitolite*** for whatever is going wrong with your setup :-) In this document: - * ssh basics - * how does gitolite use all this ssh magic? - * restricting shell access/distinguishing one user from another - * restricting branch level actions + * ssh basics + * how does gitolite use all this ssh magic? + * restricting shell access/distinguishing one user from another + * restricting branch level actions ---- - + ### ssh basics @@ -88,7 +88,7 @@ from somewhere, or maybe buy the OReilly ssh book. **This is the backbone of what makes gitolite work; please make sure you understand this** - + ### how does gitolite use all this ssh magic? @@ -98,7 +98,7 @@ These are two different questions you ought to be having by now: logging in as the same remote user "git" * how does it restrict what I can do within a repository - + #### restricting shell access/distinguishing one user from another @@ -131,7 +131,7 @@ at its config file, and either allows or rejects the request. But this cannot differentiate between different branches within a repo; that has to be done separately. - + #### restricting branch level actions diff --git a/doc/hook-propagation.mkd b/doc/hook-propagation.mkd index 44ef8da..97cb3ce 100644 --- a/doc/hook-propagation.mkd +++ b/doc/hook-propagation.mkd @@ -6,17 +6,17 @@ put them, what takes precedence. I'll try and set out the logic here. In this document: - * hooks used by gitolite - * **where** do I (the admin) put the hooks? - * the "from-client" method - * the other 3 methods - * the `GL_PACKAGE_HOOKS` directory - * the `$HOME/.gitolite` directory - * why two places? - * special case: the "non-root" method - * **when** do hooks propagate? + * hooks used by gitolite + * **where** do I (the admin) put the hooks? + * the "from-client" method + * the other 3 methods + * the `GL_PACKAGE_HOOKS` directory + * the `$HOME/.gitolite` directory + * why two places? + * special case: the "non-root" method + * **when** do hooks propagate? - + ### hooks used by gitolite @@ -32,7 +32,7 @@ In addition there is a "sentinel file" -- an empty file called The final objective of all this is that each repo's `hooks/` directory should get all the hooks that it is meant to get. - + ### **where** do I (the admin) put the hooks? @@ -44,9 +44,9 @@ Now we'll discuss the locations of these `hooks/common` and `hooks/gitolite-admin` directories. This depends on which install method you used. -(Please refer to [doc/0-INSTALL.mkd][0inst] for what these "methods" are). +(Please refer to [doc/1-INSTALL.mkd][0inst] for what these "methods" are). - + #### the "from-client" method @@ -57,11 +57,11 @@ gitolite clone on the client side. This is where you run method; skip to the next section ("when do hooks propagate") if you installed using the "from-client" method. - + #### the other 3 methods - + ##### the `GL_PACKAGE_HOOKS` directory @@ -80,7 +80,7 @@ process does the equivalent of `gl-system-install`. So now we know there's a location called `$GL_PACKAGE_HOOKS` where you can place your hooks. - + ##### the `$HOME/.gitolite` directory @@ -90,7 +90,7 @@ directory, which also contains a `hooks/` directory. So now there are two places you can put your hooks, apparently. - + #### why two places? @@ -116,7 +116,7 @@ get copied to `$HOME/.gitolite/hooks` when you "install". I need to fix and thoroughly test this later; for now, just ignore the extra files you see in there; they're harmless/redundant (TODO)] - + #### special case: the "non-root" method @@ -127,7 +127,7 @@ existed to cater to the "package" and "root" methods. In this method, the *strongly* suggest putting them in `$GL_PACKAGE_HOOKS` and ignoring `$HOME/.gitolite` completely. - + ### **when** do hooks propagate? @@ -171,5 +171,5 @@ For people who do not want certain hooks to run for certain repos, one simple solution that will work right now is to check the value of `$GL_REPO` at the start of the hook, and `exit 0` based on what it contains/matches. -[0inst]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd +[0inst]: http://github.com/sitaramc/gitolite/blob/pu/doc/1-INSTALL.mkd diff --git a/doc/7-install-transcript.mkd b/doc/install-transcript.mkd similarity index 89% rename from doc/7-install-transcript.mkd rename to doc/install-transcript.mkd index 4730123..67093ed 100644 --- a/doc/7-install-transcript.mkd +++ b/doc/install-transcript.mkd @@ -2,18 +2,18 @@ In this document: - * about this document - * create userids on server and client (optional) - * get pubkey access from client to server - * get gitolite source - * install gitolite - * VERY IMPORTANT... - * examine what you have - * emergency password access + * about this document + * create userids on server and client (optional) + * get pubkey access from client to server + * get gitolite source + * install gitolite + * VERY IMPORTANT... + * examine what you have + * emergency password access ---- - + ### about this document @@ -40,7 +40,7 @@ you have to run it on your workstation, NOT on the server!** ---- - + ### create userids on server and client (optional) @@ -87,7 +87,7 @@ because I'm not showing the actual "vi" session): ---- - + ### get pubkey access from client to server @@ -136,9 +136,11 @@ Double check to make sure you can log on to `git@server` without a password: sita@sita-lt:~ $ ssh git@server pwd /home/git +**DO NOT PROCEED UNTIL THIS WORKS OK!** + ---- - + ### get gitolite source @@ -150,7 +152,7 @@ Double check to make sure you can log on to `git@server` without a password: Receiving objects: 100% (1157/1157), 270.08 KiB | 61 KiB/s, done. Resolving deltas: 100% (756/756), done. - + ### install gitolite @@ -221,7 +223,7 @@ install mode that allows you to change the defaults etc. ---- - + ### VERY IMPORTANT... @@ -235,7 +237,7 @@ non-standard ports were used). Try out that `tail -31 ./gl-easy-install` too :) - + ### examine what you have @@ -258,7 +260,7 @@ gitolite-admin repo in `~/gitolite-admin`. And that's really all. Add keys to keydir here, edit conf/gitolite.conf as needed, then add, commit, and push the changes to the server. - + ### emergency password access diff --git a/doc/1-migrate.mkd b/doc/migrate.mkd similarity index 98% rename from doc/1-migrate.mkd rename to doc/migrate.mkd index 641f9c5..dd27b8b 100644 --- a/doc/1-migrate.mkd +++ b/doc/migrate.mkd @@ -36,8 +36,6 @@ Here's how we migrated my work repos: Now, log off the server and get back to the client: -[inst]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd - 1. follow instructions to install gitolite; see the [install document][inst]. Make sure that you **don't** change the default path for `$REPO_BASE` if you edit the config file! @@ -87,4 +85,4 @@ Now, log off the server and get back to the client: 5. Check all your changes to your gitolite-admin clone, commit, and push [mk]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#multikeys - +[inst]: http://github.com/sitaramc/gitolite/blob/pu/doc/1-INSTALL.mkd diff --git a/doc/mirroring.mkd b/doc/mirroring.mkd index 40988b0..382f95f 100644 --- a/doc/mirroring.mkd +++ b/doc/mirroring.mkd @@ -9,7 +9,7 @@ update, you just add a post-receive hook that says But life is never that simple... **This document has been tested using a 3-server setup, all installed using -the "non-root" method (see doc/0-INSTALL.mkd). However, the process is +the "non-root" method (see doc/1-INSTALL.mkd). However, the process is probably not going to be very forgiving of human error -- like anything that is this deep in "system admin" territory, errors are likely to be costly. If you're the kind who hits enter first and then thinks about what he typed, @@ -22,23 +22,23 @@ never *really* lost until you do a `git gc`**. In this document: - * RULE NUMBER ONE! - * things that will NOT be mirrored by this process - * conventions in this document - * setting up mirroring - * install gitolite on all servers - * generate keypairs - * setup the mirror-shell on each server - * set slaves to slave mode - * set slave server lists - * syncing the mirrors the first time - * switching over - * the return of foo - * switching back - * making foo a slave - * URLs that your users will use + * RULE NUMBER ONE! + * things that will NOT be mirrored by this process + * conventions in this document + * setting up mirroring + * install gitolite on all servers + * generate keypairs + * setup the mirror-shell on each server + * set slaves to slave mode + * set slave server lists + * syncing the mirrors the first time + * switching over + * the return of foo + * switching back + * making foo a slave + * URLs that your users will use - + ### RULE NUMBER ONE! @@ -52,7 +52,7 @@ Corollary: if the primary went down and you effected a changeover, you must make sure that the primary does not come up in a push-enabled mode when it recovers. - + ### things that will NOT be mirrored by this process @@ -72,7 +72,7 @@ important, (especially the gl-creator, although if your wildcard pattern had Your best bet is to use rsync for the log files, and tar for the others, at regular intervals. - + ### conventions in this document @@ -80,11 +80,11 @@ The userid hosting gitolite is `gitolite` on all machines. The servers are foo, bar, and baz. At the beginning, foo is the master, the other 2 are slaves. - + ### setting up mirroring - + #### install gitolite on all servers @@ -99,7 +99,7 @@ slaves. * Use the same "admin key" on all the machines, so that the same person has gitolite-admin access to all of them. - + #### generate keypairs @@ -108,7 +108,7 @@ servers, so first generate keypairs for all of them (`ssh-keygen`) and copy the `.pub` files to all other servers, named appropriately. So foo will have bar.pub and baz.pub, etc. - + #### setup the mirror-shell on each server @@ -136,7 +136,7 @@ Now test this access: Similarly test the other combinations. - + #### set slaves to slave mode @@ -145,7 +145,7 @@ Set slave mode on all the *slave* servers by setting `$GL_SLAVE_MODE = 1` Leave the master server's file as is. - + #### set slave server lists @@ -181,7 +181,7 @@ port number: And that's really all there is, unless... - + ### syncing the mirrors the first time @@ -193,7 +193,7 @@ them up once. gl-mirror-sync gitolite@bar # path to "sync" program is ~/.gitolite/src if "from-client" install - + ### switching over @@ -225,11 +225,11 @@ to have "baz" be a slave. system comes up. Better still, use extraneous means to block incoming connections from normal users (out of scope for this document). - + ### the return of foo - + #### switching back @@ -260,7 +260,7 @@ Switching back is fairly easy. * on foo, set slave mode off * tell everyone to switch back - + #### making foo a slave @@ -281,7 +281,7 @@ this, but YMMV. ---- - + ### URLs that your users will use diff --git a/doc/9-packaging.mkd b/doc/packaging.mkd similarity index 100% rename from doc/9-packaging.mkd rename to doc/packaging.mkd diff --git a/doc/progit-article.mkd b/doc/progit-article.mkd index 48bccbb..ce967f8 100644 --- a/doc/progit-article.mkd +++ b/doc/progit-article.mkd @@ -4,6 +4,8 @@ Git has started to become very popular in corporate environments, which tend to Gitolite allows you to specify permissions not just by repository, but also by branch or tag names within each repository. That is, you can specify that certain people (or groups of people) can only push certain "refs" (branches or tags) but not others. + + ### Installing ### Installing Gitolite is very easy, even if you don't read the extensive documentation that comes with it. You need an account on a Unix server of some kind; various Linux flavours, and Solaris 10, have been tested. You do not need root access, assuming git, perl, and an openssh compatible ssh server are already installed. In the examples below, we will use the `gitolite` account on a host called `gitserver`. @@ -35,10 +37,14 @@ And you're done! Gitolite has now been installed on the server, and you now hav That last command does produce a fair amount of output, which might be interesting to read. Also, the first time you run this, a new keypair is created; you will have to choose a passphrase or hit enter for none. Why a second keypair is needed, and how it is used, is explained in the "ssh troubleshooting" document that comes with Gitolite. (Hey the documentation has to be good for *something*!) + + ### Customising the Install ### While the default, quick, install works for most people, there are some ways to customise the install if you need to. If you omit the `-q` argument, you get a "verbose" mode install -- detailed information on what the install is doing at each step. The verbose mode also allows you to change certain server-side parameters, such as the location of the actual repositories, by editing an "rc" file that the server uses. This "rc" file is liberally commented so you should be able to make any changes you need quite easily, save it, and continue. This file also contains various settings that you can change to enable or disable some of gitolite's advanced features. + + ### Config File and Access Control Rules ### Once the install is done, you switch to the `gitolite-admin` repository (placed in your HOME directory) and poke around to see what you got: @@ -98,6 +104,8 @@ There are two levels of access control in gitolite. The first is at the reposit The second level, applicable only to "write" access, is by branch or tag within a repository. The username, the access being attempted (`W` or `+`), and the refname being updated are known. The access rules are checked in order of appearance in the config file, looking for a match for this combination (but remember that the refname is regex-matched, not merely string-matched). If a match is found, the push succeeds. A fallthrough results in access being denied. + + ### Advanced Access Control with "deny" rules ### So far, we've only seen permissions to be one or `R`, `RW`, or `RW+`. However, gitolite allows another permission: `-`, standing for "deny". This gives you a lot more power, at the expense of some complexity, because now fallthrough is not the *only* way for access to be denied, so the *order of the rules now matters*! @@ -110,6 +118,8 @@ Let us say, in the situation above, we want engineers to be able to rewind any b Again, you simply follow the rules top down until you hit a match for your access mode, or a deny. Non-rewind push to master or integ is allowed by the first rule. A rewind push to those refs does not match the first rule, drops down to the second, and is therefore denied. Any push (rewind or non-rewind) to refs other than master or integ won't match the first two rules anyway, and the third rule allows it. + + ### Restricting pushes by files changed ### In addition to restricting what branches a user can push changes to, you can also restrict what files they are allowed to touch. For example, perhaps the Makefile (or some other program) is really not supposed to be changed by just anyone, because a lot of things depend on it or would break if the changes are not done *just right*. You can tell gitolite: @@ -123,6 +133,8 @@ In addition to restricting what branches a user can push changes to, you can als This powerful feature is documented in `conf/example.conf`. + + ### Personal Branches ### Gitolite also has a feature called "personal branches" (or rather, "personal branch namespace") that can be very useful in a corporate environment. @@ -133,9 +145,13 @@ This would normally cause the same branch name clutter as in a centralised VCS, Gitolite lets you define a "personal" or "scratch" namespace prefix for each developer (for example, `refs/personal//*`); see the "personal branches" section in `doc/3-faq-tips-etc.mkd` for details. + + ### "Wildcard" repositories ### -Gitolite allows you to specify repositories with wildcards (actually perl regexes), like, for example `assignments/s[0-9][0-9]/a[0-9][0-9]`, to pick a random example. This is a *very* powerful feature, which has to be enabled by setting `$GL_WILDREPOS = 1;` in the rc file. It allows you to assign a new permission mode ("C") which allows users to create repositories based on such wild cards, automatically assigns ownership to the specific user who created it, allows him/her to hand out R and RW permissions to other users to collaborate, etc. This feature is documented in `doc/4-wildcard-repositories.mkd`. +Gitolite allows you to specify repositories with wildcards (actually perl regexes), like, for example `assignments/s[0-9][0-9]/a[0-9][0-9]`, to pick a random example. This is a *very* powerful feature, which has to be enabled by setting `$GL_WILDREPOS = 1;` in the rc file. It allows you to assign a new permission mode ("C") which allows users to create repositories based on such wild cards, automatically assigns ownership to the specific user who created it, allows him/her to hand out R and RW permissions to other users to collaborate, etc. This feature is documented in `doc/wildcard-repositories.mkd`. + + ### Other Features ### diff --git a/doc/report-output.mkd b/doc/report-output.mkd index 255cab6..e85db22 100644 --- a/doc/report-output.mkd +++ b/doc/report-output.mkd @@ -10,14 +10,14 @@ through this document). In this document: - * the "info" command - * interpreting the output - * using patterns to limit output - * the "expand" command + * the "info" command + * interpreting the output + * using patterns to limit output + * the "expand" command ---- - + ### the "info" command @@ -52,7 +52,7 @@ is often blank. @R_ @W_ testing R W vkc - + #### interpreting the output @@ -77,7 +77,7 @@ suffixed by a symbol: The `_` suffix is special. This says the user has only implicit access (due to one of the `@all` uses), but no explicit access. - + #### using patterns to limit output @@ -103,7 +103,7 @@ The pattern is also mandatory when an admin wants to find out what access some *other* user has, which you may have guessed from the syntax in the "usage" line above. - + ### the "expand" command @@ -119,6 +119,6 @@ For each repo found, it searches for it in the config -- either the actual repo entry (when the repo is not a wildcard repo), or an entry for the wildcard that matches it -- and reports permissions. It also takes into account extra permissions enabled by the `setperms` command (see -doc/4-wildcard-repositories.mkd). It shows you the "creator" of the repo as +doc/wildcard-repositories.mkd). It shows you the "creator" of the repo as an additional column, defaulting to `` if it was not a wildcard repo. diff --git a/doc/6-ssh-troubleshooting.mkd b/doc/ssh-troubleshooting.mkd similarity index 87% rename from doc/6-ssh-troubleshooting.mkd rename to doc/ssh-troubleshooting.mkd index 7ae6616..59570a2 100644 --- a/doc/6-ssh-troubleshooting.mkd +++ b/doc/ssh-troubleshooting.mkd @@ -2,20 +2,20 @@ In this document: - * (common) ssh asks for a password - * problems when using package, root, or non-root install methods - * problems when using the "from-client" install method - * (sidebar) why two keys on client for the admin - * bypassing gitolite without intending to - * basic ssh troubleshooting for the admin - * windows issues - * details - * files on the server - * files on client - * some other tips and tricks - * giving shell access to gitolite users - * losing your admin key - * simulating ssh-copy-id + * (common) ssh asks for a password + * problems when using package, root, or non-root install methods + * problems when using the "from-client" install method + * (sidebar) why two keys on client for the admin + * bypassing gitolite without intending to + * basic ssh troubleshooting for the admin + * windows issues + * details + * files on the server + * files on client + * some other tips and tricks + * giving shell access to gitolite users + * losing your admin key + * simulating ssh-copy-id ---- @@ -36,11 +36,10 @@ code, and documentation.** Other resources: - * people who think this is too hard should take a look at - [doc/7-install-transcript.mkd][doc7] to **see how simple it *actually* - is**. + * people who think this is too hard should take a look at this + [transcript][] to **see how simple it *actually* is**. - * I **strongly** recommend reading [doc/9-gitolite-and-ssh.mkd][doc9gas], + * I **strongly** recommend reading [doc/gitolite-and-ssh.mkd][doc9gas], which is a very detailed look at how gitolite uses ssh's features on the server side. Most people don't know ssh as well as they *think* they do; even if you don't have any problems right now, it's worth skimming over. @@ -51,7 +50,7 @@ Other resources: ---- - + ### (common) ssh asks for a password @@ -136,7 +135,7 @@ This is a quick checklist: ---- - + ### problems when using package, root, or non-root install methods @@ -163,7 +162,7 @@ first match, the second occurrence (which invokes gitolite) is ignored. You'll have to (create and) use a different keypair for gitolite access. - + ### problems when using the "from-client" install method @@ -191,7 +190,9 @@ key. All this applies *only* to the admin. Normal users will only have one key and do not need any of this. - + + + #### (sidebar) why two keys on client for the admin @@ -214,7 +215,7 @@ do not need any of this. > methods to install gitolite. Please see the [install doc][install] for > details. - + #### bypassing gitolite without intending to @@ -261,7 +262,7 @@ the repo and clones ok. But when you push, gitolite's **update hook** kicks in, and fails to run because some of the environment variables it is expecting are not present. - + #### basic ssh troubleshooting for the admin @@ -310,7 +311,7 @@ from scratch: That's a long sequence but it should work. - + ### windows issues @@ -326,13 +327,13 @@ how to resolve them and get things working, I'd be happy to credit you and include it, either directly here if it is short enough or just an external link, or in contrib/ if it's a longer piece of text. - + ### details Here's how it all hangs together. - + #### files on the server @@ -364,7 +365,7 @@ Here's how it all hangs together. argument `sitaram`. This is how gitolite is invoked, (and is told the user logging in is "sitaram"). - + #### files on client @@ -392,11 +393,11 @@ Here's how it all hangs together. non-default keypair (unlike command line ssh, which can be given the `-i ~/.ssh/sitaram` flag to do so). - + ### some other tips and tricks - + #### giving shell access to gitolite users @@ -415,7 +416,7 @@ or The first method is to be used if you used the **user-install** mode, while the second method is for the **system-install followed by user-setup** mode -(see doc/0-INSTALL.mkd, section on "install methods", for more on this) +(see doc/1-INSTALL.mkd, section on "install methods", for more on this) **IMPORTANT UPGRADE NOTE**: previous implementations of this feature were crap. There was no easy/elegant way to ensure that someone who had repo admin @@ -424,7 +425,7 @@ access would not manage to get himself shell access. Giving someone shell access requires that you should have shell access in the first place, so the simplest way is to enable it from the server side only. - + #### losing your admin key @@ -433,7 +434,7 @@ gitolite-admin repository with a fresh key, take a look at the `src/gl-dont-panic` program. You will need shell access to the server of course. Run it without arguments to get instructions. - + #### simulating ssh-copy-id @@ -458,11 +459,10 @@ typically) also must be `go-w`, but that needs root. And typically they're already set that way anyway. (Or if they're not, you've got bigger problems than gitolite install not working!)] -[doc0]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd -[doc9gas]: http://github.com/sitaramc/gitolite/blob/pu/doc/9-gitolite-and-ssh.mkd -[install]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd -[o3]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd#installation_and_setup -[fc]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd#from_client_method_install_from_the_client_to_the_server -[urls]: http://github.com/sitaramc/gitolite/blob/pu/doc/0-INSTALL.mkd#URLs_for_gitolite_managed_repos +[doc9gas]: http://github.com/sitaramc/gitolite/blob/pu/doc/gitolite-and-ssh.mkd +[install]: http://github.com/sitaramc/gitolite/blob/pu/doc/1-INSTALL.mkd +[o3]: http://github.com/sitaramc/gitolite/blob/pu/doc/1-INSTALL.mkd#methods +[fc]: http://github.com/sitaramc/gitolite/blob/pu/doc/1-INSTALL.mkd#fc +[urls]: http://github.com/sitaramc/gitolite/blob/pu/doc/1-INSTALL.mkd#URLs_for_gitolite_managed_repos [repout]: http://github.com/sitaramc/gitolite/blob/pu/doc/report-output.mkd -[doc7]: http://github.com/sitaramc/gitolite/blob/pu/doc/7-install-transcript.mkd +[transcript]: http://github.com/sitaramc/gitolite/blob/pu/doc/install-transcript.mkd diff --git a/doc/9-uninstall.mkd b/doc/uninstall.mkd similarity index 100% rename from doc/9-uninstall.mkd rename to doc/uninstall.mkd diff --git a/doc/4-wildcard-repositories.mkd b/doc/wildcard-repositories.mkd similarity index 86% rename from doc/4-wildcard-repositories.mkd rename to doc/wildcard-repositories.mkd index e9a506b..974455e 100644 --- a/doc/4-wildcard-repositories.mkd +++ b/doc/wildcard-repositories.mkd @@ -19,17 +19,17 @@ workarounds I may not have the time to code it right away. In this document: - * rc file setting required - * wildcard repos - * wildcard repos with creator name in them - * wildcard repos without creator name in them - * side-note: line-anchored regexes - * contrast with refexes - * handing out rights to wildcard-matched repos - * setting a gitweb description for a wildcard-matched repo - * reporting - * other issues and discussion - * how it actually works + * rc file setting required + * wildcard repos + * wildcard repos with creator name in them + * wildcard repos without creator name in them + * side-note: line-anchored regexes + * contrast with refexes + * handing out rights to wildcard-matched repos + * setting a gitweb description for a wildcard-matched repo + * reporting + * other issues and discussion + * how it actually works ---- @@ -37,7 +37,7 @@ This document is mostly "by example". ---- - + ### rc file setting required @@ -45,7 +45,7 @@ This feature requires that you set `$GL_WILDREPOS` to "1" in `~/.gitolite.rc` on the server. Please search for that variable and see comments around it in `conf/example.gitolite.rc` for more information on this. - + ### wildcard repos @@ -53,7 +53,7 @@ Which of these alternatives you choose depends on your needs, and the social aspects of your environment. The first one is a little more rigid, making it harder to make mistakes, and the second is more flexible and trusting. - + #### wildcard repos with creator name in them @@ -79,7 +79,7 @@ new repo, as user "u4" (a student): Notice the *two* empty repo inits, and the order in which they occur ;-) - + #### wildcard repos without creator name in them @@ -106,7 +106,7 @@ and have a TA create the repos in advance. In either case, they could then use the `setperms` feature to specify which users are "READERS" and which are "WRITERS". See later for details. - + ### side-note: line-anchored regexes @@ -123,7 +123,7 @@ But you may be surprised to find that it does not match even `^assignments/S[0-9]+/A[0-9]+$` -- notice the line beginning and ending metacharacters. - + #### contrast with refexes @@ -135,7 +135,7 @@ if no one will actually push such a branch! You can anchor both sides if you really care, by using `master$` instead of `master`, but that is *not* the default for refexes. - + ### handing out rights to wildcard-matched repos @@ -182,23 +182,21 @@ The following points are important: * whoever you specify as "R" will match the special user READERS. "RW" will match WRITERS. - + ### setting a gitweb description for a wildcard-matched repo Similar to the getperms/setperms commands, there are the getdesc/setdesc commands, thanks to Teemu. - + ### reporting In order to see what repositories were created from a wildcard, use the "expand" command, described briefly in [doc/report-output.mkd][repout]. -[repout]: http://github.com/sitaramc/gitolite/blob/pu/doc/report-output.mkd - - + ### other issues and discussion @@ -220,7 +218,7 @@ In order to see what repositories were created from a wildcard, use the of the time, it won't be difficult; the fixed prefix will usually be different anyway so there won't be overlaps. - + ### how it actually works @@ -295,6 +293,4 @@ I hope that helps. Enjoy, and please use with care. This is pretty powerful stuff. As they say: if you break it, you get to keep both pieces :) -[jwzq]: http://regex.info/blog/2006-09-15/247 - -[av]: http://en.wikipedia.org/wiki/Autovivification +[repout]: http://github.com/sitaramc/gitolite/blob/pu/doc/report-output.mkd