diff --git a/doc/0-INSTALL.mkd b/doc/0-INSTALL.mkd index 9a8f2fc..970237e 100644 --- a/doc/0-INSTALL.mkd +++ b/doc/0-INSTALL.mkd @@ -2,47 +2,54 @@ ### pre-requisites -One of the big needs I'm trying to fill here is people who do not have root -access, permissions to create other userids, etc. This could be a typical -hosting provider type of thing, or -- in a corporate setting -- a very tightly -controlled server. - -Gitolite requires these: +If you managed to install git, you might already have what gitolite needs: * git itself, the more recent the better * perl, typically installed with git, since git sort of needs it; any version that includes `Data::Dumper`[1] will do. * one user account on the server, with password access [2] -### quickinstall +A major objective is to allow use by people without root access, permissions +to create other userids, etc. If you have root, congratulations and all that, +but go add a user just for gitolite and do all this from that user. Really. +I see no earthly reason for this to run as root. -I assume all the files pertaining to this software are untarred and available -in the current directory. +And don't bug me about wanting to install it in `/opt` or whatever if you +haven't the time to read the docs or change a path in a config file. -A quick install, taking all the defaults, can be done with the `install.sh` -script in the `src` directory. +### quick install -Note: + * cd to the directory where you unpacked the source + * run `src/install.pl` and follow the prompts + +**When you are told to edit some file, please read the comments in the file**. +And if you can make some time to read the documentation, please do. +Especially if you have problems. + +Notes: * At present the location of `~/.gitolite.rc` is fixed (maybe later I'll - change it to a "git config" variable). + change it to a "git config" variable but I don't see much need right now) If you edit it and change any paths, be sure to keep the perl syntax -- you *don't* have to know perl to do so, it's fairly easy to guess in this limited case. And of course, make sure you adjust the commands shown above to suit the new locations - * the config file is (by default) at `~/.gitolite/conf/gitolite.conf`. - Edit the file as you wish. The comments in the file ought to be clear - enough but let me know if not + * the config file is (by default) at `~/.gitolite/conf/gitolite.conf`, + though you can change its location in the "rc" file. Edit the file as you + wish. The comments in the file ought to be clear enough but let me know + if not * if you want to bring in existing (bare, server) repos into gitolite, this - should work: + should work (refer to `~/.gitolite.rc` for *your* values of the pathnames + below): * backup the repo, then move it to `$BASE_REPO` * copy `$GL_ADMINDIR/src/update-hook.pl` to `[reponame].git/hooks/update` -- if you don't do this, per branch restrictions will not work - * then update the keys and the config file and "compile" + * then update the keys and the config file and "compile" (see "admin" + document) ### Footnotes: diff --git a/doc/1-migrate.mkd b/doc/1-migrate.mkd index ca520c6..6ef0c90 100644 --- a/doc/1-migrate.mkd +++ b/doc/1-migrate.mkd @@ -7,7 +7,8 @@ the same. The differences are: You can choose to version that directory but it is not required that you do so -Here's how we migrated my work repos: +Here's how we migrated my work repos (note: substitute real paths, from your +`~/.gitolite.rc`, for `$REPO_BASE` and `$GL_ADMINDIR` below): 1. login as the `git` user on the server, and get a bash shell prompt @@ -18,7 +19,7 @@ Here's how we migrated my work repos: 3. For added safety, **delete** the post-update hook that gitosis-admin installed - rm ~/repositories/gitosis-admin.git/hooks/post-update + rm $REPO_BASE/gitosis-admin.git/hooks/post-update or at least rename it to `.sample` like all the other hooks hanging around, or edit it and comment out the line that calls `gitosis-run-hook @@ -27,31 +28,29 @@ Here's how we migrated my work repos: If you do not do this, an accidental push to the gitosis-admin repo will mess up your `~/.ssh/authorized_keys` file -4. take a **backup** of the `~/repositories` directory +4. take a **backup** of the `$REPO_BASE` directory 5. untar gitolite to some temporary directory and follow the instructions to - **install** it. Some of the steps (like `mkdir ~/repositories`) will - fail, but this is expected. Once this is done, cd to the `$GL_ADMINDIR` - (by default `~/.gitolite`) - - cd ~/.gitolite + **install** it using `src/install.pl` 6. **convert** your gitosis config file: + cd $GL_ADMINDIR src/conf-convert.pl < ~/.gitosis.conf > conf/gitolite.conf be sure to check the file to make sure it converted correctly -7. **copy** the update hook to each of the existing repos +7. **copy** the update hook to each of the existing repos (if you have repos + in subdirectories, this won't work as is; adapt it): - for i in ~/repositories/*.git + for i in $REPO_BASE/*.git do cp src/update-hook.pl $i/hooks/update done 8. **copy** the keys from gitosis's keydir - cp ~/repositories/gitosis-admin.git/gitosis-export/keydir/* keydir + cp $REPO_BASE/gitosis-admin.git/gitosis-export/keydir/* keydir 9. **Important: expand** any multi-key files you may have. See the "faq, tips, etc" document in the doc directory for an explanation of what @@ -61,6 +60,7 @@ Here's how we migrated my work repos: You can split the keys manually, or use the following code (just copy-paste it into your xterm): + cd $GL_ADMINDIR wc -l keydir/*.pub | grep -v total | grep -v -w 1 | while read a b do i=1 diff --git a/doc/2-admin.mkd b/doc/2-admin.mkd index 7f1c507..ea8d06f 100644 --- a/doc/2-admin.mkd +++ b/doc/2-admin.mkd @@ -1,8 +1,7 @@ # administering and running gitolite -Note: some of the paths in this document use variable names. Just refer to -`~/.gitolite.rc` for the correct values, assuming you followed the -instructions in the "INSTALL" document. +*Note*: some of the paths in this document use variable names. Just refer to +`~/.gitolite.rc` for the correct values for *your* installation. ### administer @@ -30,10 +29,8 @@ the first couple of times you use it, you may want to check these: not remove!). The line should contain a "command=" pointing to a `$GL_ADMINDIR/src/gl-auth-command` file, then some sshd restrictions, the key, etc. - * `$GL_CONF_COMPILED` (default - `~/.gitolite/conf/gitolite.conf-compiled.pm`) should contain an - expanded list of the access control rules. It may look a little long, - but it's fairly intuitive! + * `$GL_CONF_COMPILED` should contain an expanded list of the access + control rules. It may look a little long, but it's fairly intuitive! * if the run threw up any "initialising empty repo" messages, check the individual repos (inside `$REPO_BASE`) if you wish. Especially make sure