deac/gitolite
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

doc changes after split

Browse source
This commit is contained in:
Sitaram Chamarty 2009-08-27 15:24:23 +05:30
parent 4e74652b38
commit 00b4baa435
6 changed files with 160 additions and 197 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

84
doc/0-INSTALL.mkd Normal file
View file

@ -0,0 +1,84 @@
# installing gitolite
### 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:
* 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
I assume all the files pertaining to this software are untarred and available
in the current directory.
A quick install, taking all the defaults, can be done with the `install.sh`
script in the `src` directory.
Note:
* At present the location of `~/.gitolite.rc` is fixed (maybe later I'll
change it to a "git config" variable).
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
* if you want to bring in existing (bare, server) repos into gitolite, this
should work:
* 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"
### Footnotes:
[1] Actually, due to the way gitolite is architected, you can manage
without `Data::Dumper` on the server if you have no choice. Only
`gl-compile-conf` needs it, so just run that on some other machine and copy
the two output files across. Cumbersome but doable... the advantage of
separating all the hard work into a manually-run piece :)
[2] If you have *only* pubkey access, and **no** password access, then your
pubkey is already in the server's `~/.ssh/authorized_keys`. If you also need
to access git as a developer (clone, push, etc), do *not* submit this same
pubkey to gitolite -- it won't work.
Instead, create a different keypair for your "developer" role (by, e.g.,
`ssh-keygen -t rsa -f ~/.ssh/gitdev`), then give `~/.ssh/gitdev.pub` to
gitolite as "yourname.pub", just like you would do for any other user.
Then you create a suitable `~/.ssh/config` to use the correct key
automatically, something like this:
host gitadm
hostname my.server
user my_userid_on_server
host gitdev
hostname my.server
user my_userid_on_server
identityfile ~/.ssh/gitdev
From now on, `ssh gitadm` will get you a command line on the server, to do
gitolite admin and other work. And your repository URLs would look like
`gitdev:reponame.git`. Very, very, simple...
And as with gitosis, there's more "ssh" magic than "git" magic here :-)
----
gitolite is released under the GPL v2 license. See COPYING for details

3
doc/1-migrate.mkd Normal file
View file

@ -0,0 +1,3 @@
# migrating from gitosis to gitolite

35
doc/2-admin.mkd Normal file
View file

@ -0,0 +1,35 @@
# administering and running gitolite
### administer
* ask each user who will get access to send you a public key. See other
sources (for example
[here](http: /sitaramc.github.com/0-installing/2-access-gitolite.html#generating_a_public_key))
for how to do this
* for each "user" in `$GL_CONF`, copy their public key to a file called
"user.pub" in `$GL_KEYDIR`. For example, mine would be called
"sitaram.pub"
* edit the config file (`$GL_CONF`) to add the new users in whatever way you
like
* backup your `~/.ssh/authorized_keys` file if you feel nervous :-)
* cd to `$GL_ADMINDIR` and run `src/gl-compile-conf`
That should be it, really. However, if you want to be doubly sure, or maybe
the first couple of times you use it, you may want to check these:
* check the outputs
* `~/.ssh/authorized_keys` should contain one line for each "user" pub
key added, between two "marker" lines (which you should please please
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!
* if the run threw up any "initialising empty repo" messages, check the
individual repos (inside `$REPO_BASE`) if you wish. Especially make sure
the `$REPO_BASE/[reponame].git/hooks/update` got copied OK and is
executable

38
doc/3-faq-tips-etc.mkd Normal file
View file

@ -0,0 +1,38 @@
# assorted faqs, tips, and notes on gitolite
### errors, warnings, notes...
* cloning an empty repo is only possible with clients greater than 1.6.2.
So at least one of your clients needs to have a recent git. Once at least
one commit has been made, older clients can also use it.
* when you clone an empty repo, git seems to complain about the remote
hanging up or something. I have no idea what that is, but it doesn't seem
to hurt anything. This happens even in normal git, not just gitolite.
* once in a while, if you're feeling particularly BOFH-ish, take a look at
`$GL_ADMINDIR/log` :-)
### special cases
#### one user, many keys
Sometimes the same user needs to access the server from differnt machines
(like a desktop and a laptop, for instance). Gitolite needs to be given all
these public keys, but associate *all* of them with the same user.
Recall from the "admin" document that each "user" has one public key file
called "user.pub", which seems to imply a one-to-one match.
But this is not strictly true -- gitolite allows a *filename* to have a small
"location" piece attached to it. So you can have "sitaram@laptop.pub" and
"sitaram@desktop.pub", for instance, and they'll all be treated as keys for
"sitaram". Just add both the files to "keydir/", and use the username
"sitaram" (*without* the "@location" part) in your `gitolite.conf` file.
Advantages: if a user reports *one of his keys* is lost or needs replacing,
it's easy to remove or replace just that.
(Contrast with gitosis, which keeps multiple entries in the same "user.pub"
file. Deleting or changing one of the keys involves editing the file and
figuring out which key is the right one!)

189
doc/INSTALL.mkd
View file

@ -1,189 +0,0 @@
In this document:
* pre-requisites
* quickinstall
* install notes
* administer
* run
* special cases
* errors, warnings, etc
----
### 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:
* 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
I assume all the files pertaining to this software are untarred and available
in the current directory.
A quick install, taking all the defaults, can be done with the following
commands; just copy and paste them into your shell:
# this one is fixed to the location shown
cp example.gitolite.rc ~/.gitolite.rc
# the destinations below are defaults; if you change the paths in the "rc"
# file above, these destinations also must change accordingly
# mkdir $REPO_BASE, $GL_ADMINDIR, and $GL_KEYDIR
mkdir ~/repositories
mkdir ~/.gitolite
mkdir ~/.gitolite/keydir
# copy sample conf to $GL_CONF
cp example.conf ~/.gitolite/gitolite.conf
# copy the 3 programs to $GL_ADMINDIR
cp update-hook.pl ~/.gitolite
cp gl-auth-command ~/.gitolite
cp gl-compile-conf ~/.gitolite
# optional; copy the documents also (if you untarred the package into a
# temporary directory and need to get rid of it)
cp INSTALL README.markdown ~/.gitolite
### install notes
* At present the location of `~/.gitolite.rc` is fixed (maybe later I'll
change it to a "git config" variable).
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/gitolite.conf`.
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:
* backup the repo, then move it to `$BASE_REPO`
* copy `$GL_ADMINDIR/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"
### administer
* ask each user who will get access to send you a public key. See other
sources (for example
[here](http://sitaramc.github.com/0-installing/2-access-gitosis.html#generating_a_public_key))
for how to do this
* for each "user" in `$GL_CONF`, copy their public key to a file called
"user.pub" in `$GL_KEYDIR`. For example, mine would be called
"sitaram.pub"
* edit the config file (`$GL_CONF`) to add the new users in whatever way you
like
* backup your `~/.ssh/authorized_keys` file if you feel nervous :-)
* cd to `$GL_ADMINDIR` and run `./gl-compile-conf`
#### optional -- if you want to be doubly sure
It should all work, but the first couple of times you may want to check these
* check the outputs
* `~/.ssh/authorized_keys` should contain one line for each "user" pub
key added, between two "marker" lines (which you should please please
not remove!). The line should contain a "command=" pointing to a
`$GL_ADMINDIR/gl-auth-command` file, then some sshd restrictions, the
key, etc.
* `$GL_CONF_COMPILED` (default
`~/.gitolite/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!
* if the run threw up any "initialising empty repo" messages, check the
individual repos (inside `$REPO_BASE`) if you wish. Especially make sure
the `$REPO_BASE/[reponame].git/hooks/update` got copied OK and is
executable
### run
Just use it as normal. Every new repo mentioned has been created already, so
(as long as your clients are using git > 1.6.2), you can just clone it.
And once in a while, if you're feeling particularly BOFH-ish, take a look at
`$GL_ADMINDIR/log` :-)
### special cases
#### one user, many keys
Sometimes the same user needs to access the server from differnt machines
(like a desktop and a laptop, for instance). Gitolite needs to be given all
these public keys, but associate *all* of them with the same user.
Recall from the "administer" section above that each "user" has one public key
file called "user.pub", which seems to imply a one-to-one match.
But this is not strictly true -- gitolite allows a *filename* to have a small
"location" piece attached to it. So you can have "sitaram@laptop.pub" and
"sitaram@desktop.pub", for instance, and they'll all be treated as keys for
"sitaram". Just add both the files to "keydir/", and use the username
"sitaram" (*without* the "@location" part) in your `gitolite.conf` file.
Advantages: if a user reports *one of his keys* is lost or needs replacing,
it's easy to remove or replace just that.
(Gitosis keeps multiple entries in the same "user.pub", which means to delete
or change one of the keys you have to edit the file and figure out which of
the 2 or more long lines should be removed).
### errors, warnings, etc
* when you clone an empty repo, git seems to complain about the remote
hanging up or something. I have no idea what that is, but it doesn't seem
to hurt anything. This happens even in normal git, not just gitolite.
### Footnotes:
[1] Actually, due to the way gitolite is architected, you can manage
without `Data::Dumper` on the server if you have no choice. Only
`gl-compile-conf` needs it, so just run that on some other machine and copy
the two output files across. Cumbersome but doable... the advantage of
separating all the hard work into a manually-run piece :)
[2] If you have *only* pubkey access, and **no** password access, then your
pubkey is already in the server's `~/.ssh/authorized_keys`. If you also need
to access git as a developer (clone, push, etc), do *not* submit this same
pubkey to gitolite -- it won't work.
Instead, create a different keypair for your "developer" role (by, e.g.,
`ssh-keygen -t rsa -f ~/.ssh/gitdev`), then give `~/.ssh/gitdev.pub` to
gitolite as "yourname.pub", just like you would do for any other user.
Then you create a suitable `~/.ssh/config` to use the correct key
automatically, something like this:
host gitadm
hostname my.server
user my_userid_on_server
host gitdev
hostname my.server
user my_userid_on_server
identityfile ~/.ssh/gitdev
From now on, `ssh gitadm` will get you a command line on the server, to do
gitolite admin and other work. And your repository URLs would look like
`gitdev:reponame.git`. Very, very, simple...
And as with gitosis, there's more "ssh" magic than "git" magic here :-)
----
gitolite is released under the GPL v2 license. See COPYING for details

8
doc/TODO
View file

@ -1,11 +1,3 @@
* a proper INSTALL file with clear instructions for non-experts
* make a proper test suite
* `use Git` instead of run git commands: I don't run too many git commands
in this and Git.pm just runs the same commands (per the documentation), so
it's sorta moot right now, but it's worth trying
* change the "rc" file to use "gitconfig" instead...
* check user/group names with some suitable regex