From 53f9a867dfca290628a13b7d012ba92213eebfac Mon Sep 17 00:00:00 2001 From: Sitaram Chamarty Date: Thu, 21 Jun 2012 21:47:56 +0530 Subject: [PATCH] accumulated docfixes... - non-core documentation reduced to be easier to maintain - much reduced progit section submitted to scott chacon, necessitating some changes to this copy - other minor stuff - the "idiot-proof setup" :) (plus get rid of that silly "dot.pl"; it's not needed any more, if it ever was!) --- doc/dev-notes.mkd | 4 ++ doc/ips.mkd | 104 +++++++++++++++++++++++++++++++++++++++++++++ doc/master-toc.mkd | 2 +- doc/non-core.mkd | 76 ++++++++++++--------------------- doc/progit.mkd | 4 +- doc/repos.mkd | 8 ++-- doc/users.mkd | 8 ++-- doc/vref.mkd | 3 +- dot.pl | 31 -------------- 9 files changed, 146 insertions(+), 94 deletions(-) create mode 100644 doc/ips.mkd delete mode 100644 dot.pl diff --git a/doc/dev-notes.mkd b/doc/dev-notes.mkd index 18cd005..a493ee7 100644 --- a/doc/dev-notes.mkd +++ b/doc/dev-notes.mkd @@ -55,6 +55,10 @@ In addition, you can also look at the comments in src/lib/Gitolite/Easy.pm ...is implemented by Gitolite::Easy; the comments in src/lib/Gitolite/Easy.pm serve as documentation. +Note that some of the perl functions called by Easy.pm will change the current +directory to something else, without saving and restoring the directory. +Patches (to Easy.pm *only*) welcome. + ## writing your own... ### ...commands diff --git a/doc/ips.mkd b/doc/ips.mkd new file mode 100644 index 0000000..dcbff02 --- /dev/null +++ b/doc/ips.mkd @@ -0,0 +1,104 @@ +## idiot-proof setup for gitolite + +WARNING 1: this document uses my new, Linus-inspired, motto: people who get +offended, *should* be offended. + +WARNING 2: contains more words in ALL CAPS than all my other documents put +together. + +WARNING 3: this document will work for any Linux on which git has already been +installed. BSDs, or legacy systems like Solaris, also should work but I can't +guarantee it or test it. + +---- + +Some people seem to get terribly, **terribly** confused by ssh. If you've +read through all the [documentation on ssh][ssh] that came with gitolite, yet +you *still* cannot get things to work, you have two choices: + +1. exchange your "developer" badge for a "manager" badge and then hire + someone to do this. + +2. start over with the instructions below. They include some DRASTIC + measures, requirements, and restrictions, almost NONE of which are + normally necessary, but it's either that or a suit and tie from tomorrow + so play along. + +**IMPORTANT**: Do NOT ask for help on these instructions unless you have kept +a detailed log of every command you typed, and the complete response you got. +I do not ask for this information to help you -- that's only a front. I +*know* these instructions work (at least on any Linux that already has git +installed), so the real reason is to find where you mistyped something and +mock you for that, + +### Assumptions + + * your name is Ron. Substitute accordingly in the instructions below. + + * you have a workstation. + + * you have a server called `server`. + + * you have root access on this server. + +### Tasks + +1. Create a new userid on the server, say `git`. This will be the **hosting + user**. ("hosting user" means when you're done installing, your users + will use URLs like `git@server:reponame` or `ssh://git@server/reponame`). + + **Make sure this is a NEW userid**. + + If the name you want already exists, then: + + * log in as root + * if you have any data on that user's HOME directory save it somewhere + else + * delete the userid + * obliterate the home directory of the user (since on most systems + merely deleting the user does not remove the home directory). + * re-create the userid again + +2. If you don't already have one, make yourself an ssh keypair **on your + workstation**. + + Do NOT, in a fit of inspiration and energy, add this public key to the + authorised keys file on the newly created hosting user! + + Your ONLY access to the new (`git`) userid should be by logging onto the + server as root, then running `su - git`. + +3. Now copy the pubkey from your workstation (`~/.ssh/id_rsa.pub`) to the + server as `/tmp/ron.pub`. (Your name is Ron, remember?) + +4. Log on to the server as root. + +5. Switch to the `git` user: + + su - git + +6. Clone the gitolite source code + + git clone git://github.com/sitaramc/gitolite + +7. Install it + + cd $HOME + mkdir -p bin + gitolite/install -to $HOME/bin + +8. Set it up + + cd $HOME + $HOME/bin/gitolite setup -pk /tmp/ron.pub + +9. Now go to your workstation and type in + + git ls-remote git@server:gitolite-admin + + This should return something like + + 9dd8aab60bac5e54ccf887a87b4f3d35c96b05e4 HEAD + 9dd8aab60bac5e54ccf887a87b4f3d35c96b05e4 refs/heads/master + + (do I have to mention that your SHAs will be different?) diff --git a/doc/master-toc.mkd b/doc/master-toc.mkd index 9e4672a..77cd40f 100644 --- a/doc/master-toc.mkd +++ b/doc/master-toc.mkd @@ -2,7 +2,7 @@ ## [Introduction][index] - * (for [current][g2] gitolite (v2) users) + * (for [older][g2] gitolite (v1 or v2) users) * [quick links][ql] * [what][] is gitolite * [why][] might you need it diff --git a/doc/non-core.mkd b/doc/non-core.mkd index c07c3e3..dc0e188 100644 --- a/doc/non-core.mkd +++ b/doc/non-core.mkd @@ -15,16 +15,17 @@ remote user running `ssh git@host help`. All the commands that ship with gitolite will respond to `-h`; please report a bug to me if they don't. -Here's a list of remote commands that are shipped: +A particularly interesting command is the 'sudo' command, which allows an +admin to run any remote command as some other user (though not the other way +round!) - * 'desc' -- get/set the 'description' file for a repo - * 'fork' -- fork a repo - * 'info' -- already documented [here][info] +Here's a list of some commands where additional information is available +elsewhere: + + * 'info' -- documented [here][info] * 'mirror' -- documented [here][sync] * 'perms' -- get/set the gl-perms file; see [perms][] for more * 'sskm' -- self-service key management, see [sskm][] for more - * 'writable' -- disabling pushes to take backups etc - * 'D' -- deleting user-created repos ## syntactic sugar @@ -45,56 +46,31 @@ The following "sugar" programs are available: ## triggers -Note that some features need to be enabled in more than one trigger. -Mirroring is probably the best example -- it needs to hook into the `INPUT`, -`PRE_GIT`, and the `POST_GIT` triggers to work. +Most triggers need to be enabled by adding or uncommenting an appropriate line +in the [rc][] file. There are enough examples in there for the syntax to not +need explanation. -The `INPUT` triggers are: +Some features need to be enabled in more than one trigger. Mirroring is +probably the best example -- it needs to hook into the `INPUT`, `PRE_GIT`, and +the `POST_GIT` triggers to work. + +In general, the source code for each trigger will tell you what it is doing +and which trigger list you should add it to. Please note that there are two +types of [triggers][]; the perl triggers usually have subroutine names that +reflect what trigger sections they should go into. (Using mirroring as an +example again, the Mirroring.pm perl module has sub's named 'input', +'pre\_git', and 'post\_git'). + +Please report a bug to me if you could not find the information you wanted on +any specific trigger. + +Here's a list of some triggers where additional information is available +elsewhere: - * CpuTime -- see the `POST_GIT` section below * Shell -- see "giving shell access to gitolite users" in [this][sts] page. - * Alias -- documentation is within the source file Alias.pm - * Mirroring -- see [doc/mirroring.mkd][mirroring] - -The `PRE_GIT` triggers are: - - * renice -- this renices the entire job to whatever value you specify. * Mirroring -- see [doc/mirroring.mkd][mirroring] * partial-copy -- this has its own section later in this page. -The `POST_GIT` triggers are: - - * Mirroring -- see [doc/mirroring.mkd][mirroring] - * CpuTime -- this is only a sample because it only prints the CPU times - data. In reality you will want to do something else with it. - -The `POST_COMPILE` triggers are: - - * post-compile/ssh-authkeys -- takes the pubkeys in keydir and populates - `~/.ssh/authorized_keys`. - - * post-compile/update-git-configs -- updates individual 'repo.git/config' - files (using the 'git config ...' command) from settings supplied in the - conf file. All sections except 'gitolite-options' are processed. (The - 'gitolite-options' section is considered internal to gitolite). - - * post-compile/update-git-daemon-access-list -- create/delete - 'git-daemon-export-ok' files in each repo based on whether the conf says - 'daemon' can read the repo or not. - - * post-compile/update-gitweb-access-list -- populates the file named in - `GITWEB_PROJECTS_LIST` in the rc file (default: `$HOME/projects.list`) - with the list of repos that gitweb is allowed to access. This could be - more than just "R = gitweb"; any repo that has any config setting with the - section name 'gitweb' (like 'gitweb.owner', 'gitweb.description', etc) is - considered readable by gitweb, so the final list is a union of these two - methods. - -The `POST_CREATE` triggers are: - - * The last 3 in the `POST_COMPILE` list also run from `POST_CREATE`, for - obvious reasons. - ## VREFs VREFs have their [own page][vref]. diff --git a/doc/progit.mkd b/doc/progit.mkd index fe4e304..5e293c1 100644 --- a/doc/progit.mkd +++ b/doc/progit.mkd @@ -1,9 +1,7 @@ -# (master copy of progit chapter on gitolite) +# (expanded version of the gitolite chapter in the progit book) ## Gitolite ## -Note: the latest copy of this section of the ProGit book is always available within the [gitolite documentation][progit]. The author would also like to humbly state that, while this section is accurate, and *can* (and often *has*) been used to install gitolite without reading any other documentation, it is of necessity not complete, and cannot completely replace the enormous amount of documentation that gitolite comes with. - [Update 2012-04-10]: This page has been completely rewritten for gitolite version 3, informally called "g3". G3 is a *total* rewrite of gitolite to push a lot more features away from "core", give the core a bunch of extension mechanisms, and finally have much better shell and perl APIs to bring all this together. Git has become very popular in corporate environments, which tend to have some additional requirements in terms of access control. Gitolite was originally created to help with those requirements, but it turns out that it's equally useful in the open source world: the Fedora Project controls access to their package management repositories (over 10,000 of them!) using gitolite, and this is probably the largest gitolite installation anywhere too. KDE, and kernel.org, are other very high-profile users of gitolite. diff --git a/doc/repos.mkd b/doc/repos.mkd index d32062a..fc73d36 100644 --- a/doc/repos.mkd +++ b/doc/repos.mkd @@ -5,10 +5,10 @@ repos into gitolite control, click [here][existing]. > ---- -> *WARNING: Do NOT add new repos directly on the server. Clone the -> 'gitolite-admin' repo to your workstation, make changes to it, then add, -> commit, and push. When the push hits the server, the server "acts" upon -> your changes.* +> *WARNING: Do NOT add new repos or users manually on the server. Gitolite +> users, repos, and access rules are maintained by making changes to a +> special repo called 'gitolite-admin' and pushing those changes to the +> server.* > ---- diff --git a/doc/users.mkd b/doc/users.mkd index f815aaa..6211278 100644 --- a/doc/users.mkd +++ b/doc/users.mkd @@ -6,10 +6,10 @@ authentication, so here's some info on adding and removing users. > ---- -> *WARNING: Do NOT add users directly on the server. Clone the -> 'gitolite-admin' repo to your workstation, make changes to it, then add, -> commit, and push. When the push hits the server, the server "acts" upon -> your changes.* +> *WARNING: Do NOT add new repos or users manually on the server. Gitolite +> users, repos, and access rules are maintained by making changes to a +> special repo called 'gitolite-admin' and pushing those changes to the +> server.* > ---- diff --git a/doc/vref.mkd b/doc/vref.mkd index 147b42e..0f7c382 100644 --- a/doc/vref.mkd +++ b/doc/vref.mkd @@ -181,7 +181,8 @@ first rule, it might pass back (to gitolite) a virtual ref saying ### #NAME restricting pushes by dir/file name The "NAME" VREF allows you to restrict pushes by the names of dirs and files -changed. +changed. (Side note: the NAME VREF is the only one directly implemented +within the update hook, so you won't find it in the VREF directory). Here's an example. Say you don't want junior developers pushing changes to the Makefile, because it's quite complex: diff --git a/dot.pl b/dot.pl deleted file mode 100644 index 40b9a7c..0000000 --- a/dot.pl +++ /dev/null @@ -1,31 +0,0 @@ -#!/usr/bin/perl -use strict; -use warnings; - -my @a = `grep -r use.Gitolite . | grep -i '^./gitolite'`; - -# chomp(@a); -open( my $fh, "|-", "tee module-tree.gv | dot -Tpng | tee module-tree.png | display" ); - -@a = map { - print $fh "#$_"; - s/^\.\/gitolite\///i; - s/-/_/g; - s/\.\///; - s/\//_/g; - s/\.pm:/ -> /; - s/use Gitolite:://; - s/::/_/g; - s/:/ -> /; - s/;//; - s/^(\S+) -> \1$//; - s/.* -> Rc//; - s/.* -> Common//; - $_; -} @a; - -# open(my $fh, "|-", "cat > /tmp/junkg3"); -print $fh "digraph G {\n"; -print $fh $_ for @a; -print $fh "}\n"; -close $fh;