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!)
This commit is contained in:
Sitaram Chamarty 2012-06-21 21:47:56 +05:30
parent 53543ee3e6
commit 53f9a867df
9 changed files with 146 additions and 94 deletions

View file

@ -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 ...is implemented by Gitolite::Easy; the comments in src/lib/Gitolite/Easy.pm
serve as documentation. 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... ## writing your own...
### ...commands ### ...commands

104
doc/ips.mkd Normal file
View file

@ -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?)

View file

@ -2,7 +2,7 @@
## [Introduction][index] ## [Introduction][index]
* (for [current][g2] gitolite (v2) users) * (for [older][g2] gitolite (v1 or v2) users)
* [quick links][ql] * [quick links][ql]
* [what][] is gitolite * [what][] is gitolite
* [why][] might you need it * [why][] might you need it

View file

@ -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 All the commands that ship with gitolite will respond to `-h`; please report a
bug to me if they don't. 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 Here's a list of some commands where additional information is available
* 'fork' -- fork a repo elsewhere:
* 'info' -- already documented [here][info]
* 'info' -- documented [here][info]
* 'mirror' -- documented [here][sync] * 'mirror' -- documented [here][sync]
* 'perms' -- get/set the gl-perms file; see [perms][] for more * 'perms' -- get/set the gl-perms file; see [perms][] for more
* 'sskm' -- self-service key management, see [sskm][] 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 ## syntactic sugar
@ -45,56 +46,31 @@ The following "sugar" programs are available:
## triggers ## triggers
Note that some features need to be enabled in more than one trigger. Most triggers need to be enabled by adding or uncommenting an appropriate line
Mirroring is probably the best example -- it needs to hook into the `INPUT`, in the [rc][] file. There are enough examples in there for the syntax to not
`PRE_GIT`, and the `POST_GIT` triggers to work. 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. * 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] * Mirroring -- see [doc/mirroring.mkd][mirroring]
* partial-copy -- this has its own section later in this page. * 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
VREFs have their [own page][vref]. VREFs have their [own page][vref].

View file

@ -1,9 +1,7 @@
# (master copy of progit chapter on gitolite) # (expanded version of the gitolite chapter in the progit book)
## Gitolite ## ## 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. [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. 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.

View file

@ -5,10 +5,10 @@ repos into gitolite control, click [here][existing].
> ---- > ----
> *WARNING: Do NOT add new repos directly on the server. Clone the > *WARNING: Do NOT add new repos or users manually on the server. Gitolite
> 'gitolite-admin' repo to your workstation, make changes to it, then add, > users, repos, and access rules are maintained by making changes to a
> commit, and push. When the push hits the server, the server "acts" upon > special repo called 'gitolite-admin' and pushing those changes to the
> your changes.* > server.*
> ---- > ----

View file

@ -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 > *WARNING: Do NOT add new repos or users manually on the server. Gitolite
> 'gitolite-admin' repo to your workstation, make changes to it, then add, > users, repos, and access rules are maintained by making changes to a
> commit, and push. When the push hits the server, the server "acts" upon > special repo called 'gitolite-admin' and pushing those changes to the
> your changes.* > server.*
> ---- > ----

View file

@ -181,7 +181,8 @@ first rule, it might pass back (to gitolite) a virtual ref saying
### #NAME restricting pushes by dir/file name ### #NAME restricting pushes by dir/file name
The "NAME" VREF allows you to restrict pushes by the names of dirs and files 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 Here's an example. Say you don't want junior developers pushing changes to
the Makefile, because it's quite complex: the Makefile, because it's quite complex:

31
dot.pl
View file

@ -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;