From b8f19f340fbca06902105464d17ef98710d7c6a5 Mon Sep 17 00:00:00 2001 From: Sitaram Chamarty Date: Sun, 13 Nov 2011 07:52:26 +0530 Subject: [PATCH] next round of doc changes --- README.mkd | 4 +- doc/1000-words.mkd | 2 +- doc/gitolite.conf.mkd | 71 ++++++++++++++++----- doc/index.mkd | 56 +++++++---------- doc/install.mkd | 119 +++++++++++++++++++----------------- doc/ssh-troubleshooting.mkd | 22 +++---- doc/support.mkd | 15 +++-- doc/tips-notes.mkd | 12 ++-- 8 files changed, 173 insertions(+), 128 deletions(-) diff --git a/README.mkd b/README.mkd index e5ca831..4396ec0 100644 --- a/README.mkd +++ b/README.mkd @@ -6,7 +6,9 @@ instructions. 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)**. +[here](http://sitaramc.github.com/gitolite)** -- this is the best starting +point for general questions about git, such as what it is, why you would need +it, features, contact/mailing list info, and so on. For convenience, here is a link to the [master table of contents](http://sitaramc.github.com/gitolite/master-toc.html), which is very diff --git a/doc/1000-words.mkd b/doc/1000-words.mkd index 7824aca..6eb32d4 100644 --- a/doc/1000-words.mkd +++ b/doc/1000-words.mkd @@ -156,7 +156,7 @@ together. This is particularly useful for an admin to see where his site-local hooks fit, how they get called, and what stages of the process they affect. -Legend: diamonds are decision boxes whose results can abort the operation. +**Legend**: diamonds are decision boxes whose results can abort the operation. Arrows are calls/invocations. Dashed lines just point to sub-parts of the process on the left side. Blue processes are external to gitolite. Green is gitolite code. Yellow is site-local code that you (the admin of your site) diff --git a/doc/gitolite.conf.mkd b/doc/gitolite.conf.mkd index 8060d10..10ef912 100644 --- a/doc/gitolite.conf.mkd +++ b/doc/gitolite.conf.mkd @@ -7,10 +7,48 @@ and users. There was also, in the author's mind, a desperate need to create something as different as possible from the brain-dead, nausea-inducing "Windows INI" style syntax that some other popular tools seem to favour. -This document describes the syntax and semantics of the access control rules -and other configuration directives in the `gitolite.conf` file. +## #confrecap a quick summary of the conf file -## #syntax syntax +This is a quick *recap* of the *most common* elements in a typical config +file. (In the following description, the angle brackets are not part of the +syntax). + + * (optional) [group][groups] definitions + + @ = + + * repo access rules + + repo + # one or more access rules like + = + + The [most common][bac] permissions are: + + * R, for read only + * RW, for push existing ref or create new ref + * RW+, for "push -f" or ref deletion allowed (i.e., destroy + information) + * `-` (the minus sign), to [deny][] access + + If no [refex][] is supplied, the access rule applies to all refs. + + Later, gitolite [acquired][rwcd] + + * RWC and RW+C, for ref creation. Once you use this in a repo, a normal + RW/RW+ can no longer create a ref; it can only push existing refs + (Note also that a standalone "C" permission is + something [completely different][wild]) + * RWD and RW+D, for ref deletion. Once you use this in a repo, a normal + RW+ can no longer delete a ref; it can only rewind + * (RWCD and RW+CD, which is just a combination of these two) + +The following sections dig deeper into the syntax and semantics of the access +control rules and other configuration directives in the `gitolite.conf` file. +If narrative descriptions scare you, or your English is not upto scratch, try +[gitolite config by example][conf_examples] also. + +## F=syntax lexical syntax In general, everything is **space separated**; there are no commas, semicolons, etc., in the syntax. @@ -39,18 +77,20 @@ include them in the main file for convenience. include "foo.conf" -will include the contents of the file "foo.conf" from the same directory as -the main config file. You can also use an absolute path if you like, although -in the interests of cloning the admin-repo sanely you should avoid doing this! +will include the contents of the file "foo.conf". -You can also use a glob, as in: +Details: - include "*.conf" + * You can also use a glob (`include "*.conf"`), or put your include files + into subdirectories of "conf" (`include "foo/bar.conf"`), or both + (`include "repos/*.conf"`). -which will include all the ".conf" files from the directory in which the main -config file exists. + * Included files are always searched from the gitolite-admin repo's "conf/" + directory, unless you supplied an absolute path. (Note: in the interests + of cloning the admin-repo sanely you should avoid absolute paths!) -Files that have been already processed once are skipped, with a warning. + * If you ended up recursing, files that have been already processed once are + skipped, with a warning. Advanced users: `subconf`, a command that is very closely related to `include`, is documented [here][subconf]. @@ -105,7 +145,7 @@ Gitolite goes down the list of rules matching the user, repo, and the ref. The first matching rule that has the permission you're looking for (`W` or `+`), results in success. A fallthrough results in failure. -### branches, tags, and specifying "refex"es +### #refex branches, tags, and specifying "refex"es One of the original goals of gitolite was to allow access control at the branch/tag (aka "ref") level. The git source code contains a sample update @@ -162,7 +202,7 @@ looks like "refs/heads/foo", while a tag ref looks like "refs/tags/bar") "v1.0", "v2.0rc1", all match the criterion specified by `v[0-9]` because this is a prefix match only. -### groups +### #groups groups Gitolite allows you to define **groups** of repos. users, or even refexes. A group is semantically (but *not* syntactically) like a `#define` in C. Here @@ -211,7 +251,8 @@ when used as a username; you've seen examples of it earlier. Advanced users: also see the entry for `GL_ALL_INCLUDES_SPECIAL` in the documentation for [`~/.gitolite.rc`][rc]. -When used as a reponame, it includes all repos. +When used as a reponame, it includes all repos physically present in +`~/repositories` (or whatever is the value of `$REPO_BASE`). ### F=rpr_ side note: "R" permissions for refs @@ -358,7 +399,7 @@ had core.logAllRefUpdates set, which is *not* a default setting). However, there seem to be cases where it is useful to distinguish these cases. Arguments can be made on all sides if you're dealing with new users, so -gitolite supports that. +gitolite now supports that (in a backward compatible way). We'll look at the delete/rewind case in detail first: diff --git a/doc/index.mkd b/doc/index.mkd index eabd2d6..7b0b42e 100644 --- a/doc/index.mkd +++ b/doc/index.mkd @@ -24,57 +24,47 @@ manage the server by cloning the special 'gitolite-admin' repo on your workstation (`git clone git@server:gitolite-admin`), making changes, and pushing them. Here's how to [add users and repos][add]. -## #rtfm what should you read? +## #rtfm what to read... -The complete online documentation for gitolite is -[here](http://sitaramc.github.com/gitolite). There's a lot of it, so here're -some reading suggestions. - -If you're a **user** (i.e., not a gitolite admin), you only need [this][user]. - -Otherwise, the suggested reading order is this: - - * **quick intro**: this document, or at least the "[what is - gitolite][gl_what]" section just below this one. - * **installation**: if the [quick install][qi] above did not work for you, - then read the [INSTALL][install] document. The "[trouble][insttrouble]" - section in it may be useful too. - * **basic** administration tasks: [adding users and repos][add]. - -When you have to use more features, look in the master table of contents -(there's a link to it at the top of *every* document), and use your browser's -search function to search for stuff. - -### F=other_docs what do the other docs contain - -The master TOC (see link above) is really the only *comprehensive* list of -what is there, but here's an attempt to give you an overview! +Gitolite comes with a *lot* of documentation. The master TOC (see link above) +is the *only* comprehensive list of what is there, but here's an overview. * understanding gitolite + * [what is gitolite][gl_what], and the rest of this document * gitolite install and basic admin in [pictures][] - * gitolite.conf by [example][conf_examples] * gitolite and [ssh][gl_ssh] + * explaining gitolite to your *users* + * the [user][] document is all they need + + * install and setup + * the "[install trouble?][insttrouble]" section, which links, among + other things, to arguably the most useful doc for a newbie: [ssh + troubleshooting][sts]! + * maybe even the complete [install][] document + * normal admin tasks done on the server - * [admin][]: adding your own hooks, adding existing repos into gitolite, etc. - * [rc][]: setting gitolite behaviour options (warning: some of the + * [adding users and repos][add] + * [admin][]: add your own hooks, add existing repos into gitolite, etc. + * [rc][]: sett gitolite behaviour options (warning: some of the variables have a security impact if you're careless) * normal admin tasks done by changing [gitolite.conf][conf] * basic access control * advanced access control * extras: personal branches, gitweb/git-daemon access, git config settings + * [gitolite.conf by example][conf_examples] may also help * advanced use (experts only; you can shoot yourself in the foot nicely!) - * [ADCs][]: allowing users to run specific shell commands (but not give them a shell) + * [ADCs][]: allow users to run specific shell commands (but not give them a shell) * (also, [sample ADCs][shipped_ADCs] that come with gitolite) - * letting [users create][wild] their own repos and assign permissions - * [delegating][deleg] admin rights - * [mirroring][] + * let [users create][wild] their own repos and assign permissions + * [delegate][deleg] admin rights + * [mirror][mirroring] your servers * special installation scenarios: - * using smart-[http][] instead of ssh - * [migrating][migr] from gitolite + * use smart-[http][] instead of ssh + * [migrate][migr] from gitosis Finally, [tips][] has a lot of useful information. diff --git a/doc/install.mkd b/doc/install.mkd index 5a93c8e..9f3f3ef 100644 --- a/doc/install.mkd +++ b/doc/install.mkd @@ -150,13 +150,13 @@ On your *workstation*: ### #upgrade upgrading Upgrading is easy; you just re-run some of the same commands used for install. -These commands are clearly noted in the install instructions below. +These commands are clearly noted in the install instructions above. However, if you've added any new hooks, you must also run the next step (the `gl-setup` command), although this time you don't need to supply a pubkey filename as an argument. -## #insttrouble if you run into trouble... +## #insttrouble install trouble? If you run into trouble, please read the following sections. @@ -248,10 +248,10 @@ don't know ssh it'll be a nightmare to support you. * any Unix system with a posix compatible "sh". * people using "csh" or derivatives please don't ask me for help -- tell your admin csh is not posix compatible - * git version 1.6.6 or greater + * git version 1.6.6 or later * can be in a non-PATH location if you are unable to install it normally; see the `$GIT_PATH` variable in the "rc" file - * perl (but since git requires it anyway, you probably have it) + * perl 5.8 or later * openssh or any ssh that can understand the `authorized_keys` file format (probably optional if you're using the http backend) * a Unix userid to be the hosting user, usually "git" but it can be any @@ -332,74 +332,81 @@ Good luck. ### #clean appendix b: cleaning out a botched install When people have trouble installing gitolite, they often try to change a bunch -of things manually on the server. This usually makes things worse ;-) so -here's how to clean the slate. +of things manually on the server. Or sometimes they'll upgrade from one +install method to another without checking some things over properly. Or +they'll follow instructions meant for a much newer version of gitolite and +make a royal mess of the whole thing. + +Here's how to clean up, without losing your actual repositories. + +All this is on the server. Note that the instructions are so long because +they're generic enough to fit any situation. + + * Clean out the existing install - * client-side - * edit `~/.ssh/config` and delete the paragraph starting with `host - gitolite`, if present. - * remove `~/gitolite-admin` - * server-side * edit `~/.ssh/authorized_keys` and delete all lines between `# gitolite start` and `# gitolite end` inclusive. - * remove `~/.gitolite`, `~/.gitolite.rc` and - `~/repositories/gitolite-admin.git` - * depending on which install method you used, you may also need to clean - out all gitolite files from `/usr/local/bin` or `$HOME/bin`, and then - delete `/var/gitolite/conf` and `/var/gitolite/hooks` or - `$HOME/share/gitolite/conf` and `$HOME/share/gitolite/hooks` -### F=uninstall_ appendix c: uninstalling gitolite completely + * look in `~/.gitolite.rc` for 2 variables starting with `GL_PACKAGE_`. + If they are defined (and not just commented out), you need to clean + out all gitolite related files and directories from those two paths. -(There's some duplication between this and the previous section). + Just for reference, the defaults for a non-root install are 'conf' and + 'hooks' in `$HOME/share/gitolite`, while for an RPM/DEB or root + install they should be in `/var/gitolite/` or some such. -Uninstalling gitolite is fairly easy, although it is manual. (We'll assume -`$REPO_BASE` in the rc file was left at its default of `~/repositories`; if -not, adjust accordingly): + If those variables don't exist or are commented out, ignore this step. -**server side tasks** + * look in `$PATH` for any gitolite programs and delete them also. A + good way to hunt them down is `which gl-auth-command`, and in the path + you find, delete all "gl-*" programs (perhaps after checking the list, + if the path you find happens to be /usr/bin or such!!) - * edit `~/.ssh/authorized_keys` and delete the `# gitolite start` and `# - gitolite end` markers and all the lines between them. This will prevent - any of your users from attempting a push while you are doing this. + Repeat this step until there are no more. I know of people who mixed + different install methods and had two, or even three, versions lying + around. - If you are the only user, and/or *need* one or more of those keys to - continue to access this account (like if one of them is your laptop or - your home desktop etc.) then instead of deleting the line you can just - delete everything upto but not including the words "ssh-rsa" or "ssh-dss". + * make some temp directory (say "old"), and **move** the following + files/directories into it: `~/.gitolite`, `~/.gitolite.rc` and + `~/repositories/gitolite-admin.git`. If there's nothing you need to + salvage from them you can delete them too. - * Now remove (or move aside or rename to something else if you're paranoid) - the following files and directories. + * if you used an RPM/DEB install, remove the package also. - ~/.gitolite - ~/.gitolite.rc - ~/repositories/gitolite-admin.git + * Now install a fresh copy of gitolite using whatever method you prefer. + (If you used a different method earlier and did not clean things out + properly per the instructions given above, expect trouble). - * You can remove all of `~/repositories` if you have not really started - using gitolite properly yet; that's your choice. + * You now have a brand new "rc" file. If your old rc file had any + non-default settings you should **manually** pull them in to the new one. + However, **do NOT** change the two variables starting with `GL_PACKAGE_` + in the new rc file; even if the old one had something different leave them + alone. - If you *do* need to preserve the other repos and continue to use them, - remove all the `update` hooks that git installs on each repository. The - easiest way is: + * You also have a brand new gitolite-admin repo. Clone this to your + workstation, then use the saved copy of the old admin repo to salvage + whatever you need (entire revision history, or just the conf/key files, + whatever floats your boat). - find ~/repositories -wholename "*.git/hooks/update" | xargs rm -f + Once you've got your admin repo looking how you want it, including 'repo' + statements for all your existing repos, just add/commit/push it. - but you can do it manually if you want to be careful. + * Go back to the server and run `gl-setup` once again (no arguments needed). -**client side tasks** +That should do it. - * Any remote users that still have access must update their clone's remote - URLs (edit `.git/config` in the repo) to prefix `repositories/` before the - actual path used, in order for the remote to still work. This is because - you'll now be accessing it through plain ssh, which means you have to give - it the full path. +### #uninstall_ appendix c: uninstalling gitolite completely - * Finally, you as the gitolite admin *nay* have a host stanza for "gitolite" - in your *client*'s `~/.ssh/config`. Find and delete lines that look like - this: +To uninstall gitolite completely, first follow the "clean out..." steps in the +previous section. - host gitolite - user git - hostname your.server - port 22 - identityfile ~/.ssh/your-gitolite-admin-username +If you have not really started using gitolite properly yet, you can remove all +of `~/repositories` also and be done. + +But if you *do* need to preserve the other repos and wish to continue to use +them, remove all the `update` hooks that gitolite installs in each repository. +The easiest way is: + + find ~/repositories -wholename "*.git/hooks/update" | xargs rm -f + +but you can do it manually if you want to be careful. diff --git a/doc/ssh-troubleshooting.mkd b/doc/ssh-troubleshooting.mkd index 8dcc289..7b159a6 100644 --- a/doc/ssh-troubleshooting.mkd +++ b/doc/ssh-troubleshooting.mkd @@ -94,15 +94,15 @@ you there again. Especially the first bullet. Done? OK, read on... The following problem(s) indicate that pubkey access is not working at all, so -you should start with appendix 1. If that doesn't fix the problem, continue +you should start with [appendix 1][stsapp1_]. If that doesn't fix the problem, continue with the other appendices in sequence. * running any git clone/fetch/ls-remote or just `ssh git@server info` asks you for a password. The following problem(s) indicate that your pubkey is bypassing gitolite and -going straight to a shell. You should start with appendix 2 and continue with -the rest in sequence. Appendix 5 has some background info. +going straight to a shell. You should start with [appendix 2][stsapp2_] and continue with +the rest in sequence. [Appendix 5][stsapp5_] has some background info. * running `ssh git@server info` gets you the output of the GNU 'info' command instead of gitolite's version and access info. @@ -136,16 +136,16 @@ Done? OK, now the general outline for ssh troubleshooting is this: * make sure the server's overall setup even *allows* pubkey based login. I.e., check that git fetch/clone/ls-remote commands or a plain `ssh git@server info` do NOT ask for a password. If you do get asked for a - password, see appendix 1. + password, see [appendix 1][stsapp1_]. * match client-side pubkeys (`~/.ssh/*.pub`) with the server's authkeys file. To do this, run `sshkeys-lint`, which tells you in detail what key - has what access. See appendix 2. + has what access. See [appendix 2][stsapp2_]. * at this point, we know that we have the right key, and that if sshd receives that key, things will work. But we're not done yet. We still need to make sure that this specific key is being offered/sent by the - client, instead of the default key. See appendix 3 and 4. + client, instead of the default key. See [appendix 3][stsapp3_] and [appendix 4][sshhostaliases]. ## random tips, tricks, and notes @@ -220,7 +220,7 @@ putty/plink, including environment variables, etc., and then try again. Thankfully, someone contributed [contrib/putty.mkd][contrib_putty]. -## appendix 1: ssh daemon asks for a password +## #stsapp1_ appendix 1: ssh daemon asks for a password > **NOTE**: This section should be useful to anyone trying to get > password-less access working. It is not necessarily specific to gitolite, @@ -288,7 +288,7 @@ This is a quick checklist: this file for messages matching the approximate time of your last attempt to login, to see if they tell you what is the problem. -## appendix 2: which key is which -- running sshkeys-lint +## #stsapp2_ appendix 2: which key is which -- running sshkeys-lint Follow these steps on the client: @@ -339,7 +339,7 @@ as YourName.pub, then run `gl-setup YourName.pub` on the server. Remember to adjust your agent identities using ssh-add -D and ssh-add if you're using ssh-agent, otherwise these new keys may not work. -## appendix 3: ssh client may not be offering the right key +## #stsapp3_ appendix 3: ssh client may not be offering the right key * make sure the right private key is being offered. Run ssh in very verbose mode and look for the word "Offering", like so: @@ -348,7 +348,7 @@ ssh-agent, otherwise these new keys may not work. If some keys *are* being offered, but not the key that was supposed to be used, you may be using ssh-agent (next bullet). You may also need to - create some host aliases in `~/.ssh/config` (appendix 4). + create some host aliases in `~/.ssh/config` ([appendix 4][sshhostaliases]). * (ssh-agent issues) If `ssh-add -l` responds with either "The agent has no identities." or "Could not open a connection to your authentication @@ -397,7 +397,7 @@ way to do this, as far as I know. [tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial -## appendix 5: why bypassing gitolite causes a problem +## #stsapp5_ appendix 5: why bypassing gitolite causes a problem When you bypass gitolite, you end up running your normal shell instead of the special gitolite entry point script `gl-auth-command`. diff --git a/doc/support.mkd b/doc/support.mkd index 83e329b..e3fd286 100644 --- a/doc/support.mkd +++ b/doc/support.mkd @@ -8,14 +8,17 @@ issues. I often don't bother responding for silly issues that are already in the docs. Seriously, folks, troubleshooting involves reading; do I really need to *say* that? - * For install/setup issues see the [if you run into trouble][insttrouble] - section of the [install][] document. + * Lost your admin key? Try [gl-admin-push][adminpush]. - In particular, that section has two links for ssh issues. I've yet to see - a problem that is not already covered by those. + * For install/setup issues see the [install trouble?][insttrouble] section + of the [install][] document. - * For usage issues after install, check out the [suggested reading - list][rtfm] and the [other docs][other_docs] section. + In particular, that section has two links for ssh issues. **I've yet to + see an ssh problem that is not already covered by those** (but please tell + me if you find one!) + + * The [suggested reading list][rtfm] section is a quick overview of the + documentation. * If you still can't find what you need, try the [**master index/table of contents**](http://sitaramc.github.com/gitolite/master-toc.html) and use diff --git a/doc/tips-notes.mkd b/doc/tips-notes.mkd index b4cda6e..91725de 100644 --- a/doc/tips-notes.mkd +++ b/doc/tips-notes.mkd @@ -259,8 +259,12 @@ will work for all the repos managed by gitolite, **except** for the special is also a `post-update` hook that runs here, and this needs additional information which is NOT available if you bypass gitolite. -Use the `gl-admin-push` program to make changes to the admin repo directly on -the server. Here's how: +(Note: If your gitolite is too old to have the `gl-admin-push` program, try +`gl-dont-panic`; run it without arguments for usage info. If you don't even +have that, it may be best to [clean][] things out more thoroughly!) + +Use the `gl-admin-push` program to make changes to the admin repo *directly on +the server*. Here's how: * clone the repo to some safe location and cd to it: @@ -274,9 +278,7 @@ the server. Here's how: fix up some config problem that may have lost you your access. * when done, instead of `git push `, use this program - instead, like so: - - gl-admin-push + instead. For example, instead of `git push -f`, use `gl-admin-push -f`. Note that this method will work for *any* repo, not just the special admin repo.