diff --git a/README.mkd b/README.mkd index 70ecac6..0f9e9a5 100644 --- a/README.mkd +++ b/README.mkd @@ -28,7 +28,9 @@ don't miss out on them by skipping the excellent [documentation][docs]!) * create a user called `git`. Login to this user. + * copy your ssh pubkey from your workstation. Rename it to `YourName.pub`. + * now run these commands: git clone git://github.com/sitaramc/gitolite @@ -36,8 +38,12 @@ don't miss out on them by skipping the excellent src/gl-system-install gl-setup ~/YourName.pub -You're done. Now run `git clone git@server:gitolite-admin` on your -workstation and [add users and repos][aur]. +You're done. + +A word of caution: do **NOT** add repos or users directly on the server! You +MUST manage the server by cloning the special 'gitolite-admin' repo on your +workstation (`git clone git@server:gitolite-admin`), making changes, and +pushing them. See [here][aur] for how to add users and repos. [aur]: http://sitaramc.github.com/gitolite/doc/2-admin.html#_adding_users_and_repos diff --git a/contrib/adc/README.mkd b/contrib/adc/README.mkd index 6467957..6ba9e99 100644 --- a/contrib/adc/README.mkd +++ b/contrib/adc/README.mkd @@ -1,4 +1,4 @@ -# brief descriptions of the shipped ADCs (admin-defined commands) +## brief descriptions of the shipped ADCs (admin-defined commands) (...with pointers to further information where needed) diff --git a/contrib/adc/hub.mkd b/contrib/adc/hub.mkd index 8957860..e3e35f5 100644 --- a/contrib/adc/hub.mkd +++ b/contrib/adc/hub.mkd @@ -1,4 +1,4 @@ -# the 'hub' ADC +## the 'hub' ADC In this document: diff --git a/contrib/adc/repo-deletion.mkd b/contrib/adc/repo-deletion.mkd index c46e151..99f66b6 100644 --- a/contrib/adc/repo-deletion.mkd +++ b/contrib/adc/repo-deletion.mkd @@ -1,4 +1,11 @@ -# deleting repos safely +## deleting repos safely + +**NOTE**: this page is about deleting [user-created repos][wcr]. It is +**not** about deleting "normal" repos (the kind that are specified in the +gitolite.conf file itself) -- to delete those read [here][dnr]. + +[wcr]: http://sitaramc.github.com/gitolite/doc/wildcard-repositories.html +[dnr]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html#_deleting_a_repo (see [this thread][thr] on the gitolite mailing list) diff --git a/contrib/mirroring-complex-example.mkd b/contrib/mirroring-complex-example.mkd index 0cc8117..7b5061f 100644 --- a/contrib/mirroring-complex-example.mkd +++ b/contrib/mirroring-complex-example.mkd @@ -1,4 +1,4 @@ -# semi-autonomous mirroring setup example +## semi-autonomous mirroring setup example [deldoc]: http://sitaramc.github.com/gitolite/doc/delegation.html [sc]: http://sitaramc.github.com/gitolite/doc/delegation.html#_the_subconf_command diff --git a/doc/2-admin.mkd b/doc/2-admin.mkd index ebc45ce..aa29580 100644 --- a/doc/2-admin.mkd +++ b/doc/2-admin.mkd @@ -50,6 +50,11 @@ Once you've cloned it, you're ready to add users and repos. ### adding users and repos +Do **NOT** add repos or users directly on the server! You MUST manage the +server by cloning the special 'gitolite-admin' repo on your workstation (`git +clone git@server:gitolite-admin`), making changes, and pushing them. This +section tells you how to add users and repos. + * ask each user who will get access to send you a public key. See other sources (for example [here][genpub]) for how to do this @@ -245,8 +250,9 @@ important here: `~/repositories`), making sure that the directory names end in ".git". * back on your workstation, add each repo (without the `.git` suffix) to - `conf/gitolite.conf` in your gitolite-admin repo clone. Then add, commit, - push. + `conf/gitolite.conf` in your gitolite-admin repo clone. Give *some* user + (even a non-existent one like "DUMMY" is fine) at least "R" access to + these repos. Then add, commit, push. **Case 3 -- far too many repos** (or your initials are JH ;-): This is when you're like Case 2, except you have *so many* repos that step 3 becomes too diff --git a/doc/3-faq-tips-etc.mkd b/doc/3-faq-tips-etc.mkd index 7ca1e1a..5bccc38 100644 --- a/doc/3-faq-tips-etc.mkd +++ b/doc/3-faq-tips-etc.mkd @@ -32,6 +32,8 @@ In this document: * admin defined commands * access control for external commands * svnserve + * odds and ends + * "poking" the admin repo to force a compile * design choices * keeping the parser and the access control separate @@ -107,47 +109,45 @@ features than the original goal of branch-level access control. ##### one user, many keys -I have a laptop and a desktop I need to access the server from. I have -different private keys on them, but as far as gitolite is concerned both of -them should be treated as "sitaram". How does this work? +If you have a user who has more than one pubkey (like from different machines) +the simplest way to deal with it is to add subdirectories and add keys there. +For example, I might have these files in `keydir/`: -The way it works is that you copy one pubkey as "sitaram@laptop.pub" and the -other as "sitaram@desktop.pub". The part before the "@" is the username, so -gitolite knows these two keys belong to the same person. The part after the -"@" can be anything you like, of course; gitolite doesn't care. + sitaram.pub + home/sitaram.pub + laptop/sitaram.pub -Note that you don't say "sitaram@laptop" and so on in the **config** file -- -as far as the config file is concerned there's just **one** user called -"sitaram" -- so you only say "sitaram" there. + -I think this is easier to maintain if you have to delete or change one of -those keys. +The older method will continue to work, simply because I prefer it. But I am +not going to document it except for the example below, nor am I going to +support it in terms of questions. Sorry. Apparently it was too complex to +understand, even for some smart folks I know. This tells me it was probably +ill thought out and should have been obsoleted as soon as e0fe73a was pushed. -However, now that `sitaramc@gmail.com` is also a valid username, we need to -distinguish between `sitaramc@gmail.com.pub` and `sitaramc@desktop.pub`. We -do that by requiring that the multi-key suffix you use (like "desktop" and -"laptop") should not have a `"."` in it. If it does, it looks like an email -address. The following table lists sample pubkey filenames and the -corresponding derived usernames (which is what goes into the -`conf/gitolite.conf` file): +Anyway, here's *all* the documentation for it -- some sample pubkey filenames +and the corresponding derived usernames: - * old style multikeys; not mistaken for emails because there is no "." in - hostname part + * plain username, no multikey sitaramc.pub sitaramc + + * plain username, with multikeys + sitaramc@laptop.pub sitaramc sitaramc@desktop.pub sitaramc - * new style, email keys; there is a "." in hostname part; so it's an email - address + * email address as username, no multikey sitaramc@gmail.com.pub sitaramc@gmail.com - * multikeys *with* email address + * email address as username, with multikeys sitaramc@gmail.com@laptop.pub sitaramc@gmail.com sitaramc@gmail.com@desktop.pub sitaramc@gmail.com + + #### security, access control, and auditing @@ -532,6 +532,23 @@ 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. + + +### odds and ends + + + +#### "poking" the admin repo to force a compile + +Sometimes you need to force a compile, as if you pushed the gitolite-admin +repo. I have a git alias that looks like this: + + [alias] + poke = !git ls-remote origin | grep -w refs/heads/poke && git push origin :poke || git push origin master:poke + +so I just run `git poke`. This toggles between deleting and creating a dummy +branch called "poke". Either operation will trigger the hooks. + ### design choices diff --git a/doc/gitolite.conf.mkd b/doc/gitolite.conf.mkd index a820ea1..e1b3d61 100644 --- a/doc/gitolite.conf.mkd +++ b/doc/gitolite.conf.mkd @@ -541,12 +541,14 @@ later to override the generic settings. #### repo owner/description line for gitweb -Including a line like this: +You can include owner/description information in the conf file, and gitolite +will put it in places where gitweb will pick it up. For example, suppose this +software (gitolite) itself was being hosted on a gitolite server and intended +to be shown on gitweb, I'd use a line like this: - gitolite "Sitaram Chamarty" = "fast, secure, access control for git in a corporate environment" + gitolite "Sitaram Chamarty" = "fast, secure, access control for git" -sets the owner name and description for gitweb. The general syntax is very -simple, just use one of: +The general syntax is very simple, just use one of: reponame = "some description string in double quotes" reponame "owner name" = "some description string in double quotes" diff --git a/doc/gitolite.rc.mkd b/doc/gitolite.rc.mkd index 5b442f7..fb90d53 100644 --- a/doc/gitolite.rc.mkd +++ b/doc/gitolite.rc.mkd @@ -127,7 +127,8 @@ on feedback from my users to find or fix issues. This setting allows the repo admin to define acceptable gitconfig keys. Gitolite allows you to set git repo options using the "config" keyword; - see doc/gitolite.conf.mkd for details and syntax. + see the section on "repo specific git config commands" in + [doc/gitolite.conf.mkd][gitconf] for details and syntax. However, if you are in an installation where the repo admin does not (and should not) have shell access to the server, then allowing him to set @@ -367,3 +368,4 @@ of `ADC_CMD_ARGS_PATT`), please be sure you know what you're doing. [smart]: http://sitaramc.github.com/gitolite/doc/http-backend.html [dwr]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html#_disabling_write_access_to_take_backups [limit]: http://sitaramc.github.com/gitolite/doc/report-output.html#_using_patterns_to_limit_output +[gitconf]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html#_repo_specific_git_config_commands diff --git a/doc/mirroring.mkd b/doc/mirroring.mkd index 43730c7..a72ebdc 100644 --- a/doc/mirroring.mkd +++ b/doc/mirroring.mkd @@ -1,4 +1,4 @@ -# mirroring gitolite servers +## mirroring gitolite servers Mirroring a repo is simple in git; you just need code like this in a `post-receive` hook in each repo: