(collected docfixes)

This commit is contained in:
Sitaram Chamarty 2012-04-26 06:38:04 +05:30
parent e511943a45
commit 17a680e0f6
8 changed files with 101 additions and 45 deletions

View file

@ -2,7 +2,8 @@
## #server server-side administration
The following activities require command line access to the server:
The following activities require command line access to the server. They are
usually one-time or rarely done activities.
* Changing anything in the [rc][] file.
* Installing custom [hooks][], whether to all repos or just some repos.
@ -10,12 +11,19 @@ The following activities require command line access to the server:
Please read the [WARNINGS][] page first.
## #conf access control (the gitolite.conf file)
## #adminrepo access control via the gitolite-admin repo
Most day-to-day administration of a gitolite site happens like this:
* [clone][] the gitolite-admin repo to your workstation
* make appropriate changes
* add, commit, and push
### #conf the conf/gitolite.conf file
Most of gitolite's power is in the conf/gitolite.conf file, which specifies
detailed access control for repos.
### #confex example of a conf file
detailed access control for repos. Everything except [adding users][users]
happens from this file.
Here is an example of a simple conf/gitolite.conf file.

19
doc/clone.mkd Normal file
View file

@ -0,0 +1,19 @@
# cloning the admin repo
This is the third step in using gitolite, after [install][] and [setup][].
To clone the admin repo, go to the workstation where the public key used in
'setup' came from, and run this:
git clone git@host:gitolite-admin
NOTE that (1) you must not include the `repositories/` part (gitolite handles
that internally), and (2) you may include the ".git" at the end but it is
optional.
If this step succeeds, you can add [users][], [repos][], or anything else
described [here][adminrepo].
If this step fails, be sure to look at the [ssh][] documentation before asking
for help. (A very basic first step is to run `ssh git@host info`;
[this][info] page tells you what to expect).

View file

@ -1,5 +1,10 @@
# ssh
If you're installing gitolite, you're a "system admin", like it or not. If
you're using the default ssh mode (i.e., not [http][] mode), ssh is a
necessary skill. Please take the time to learn at least enough to get
passwordless access working.
There are two documents you need to read, in order:
* [Gitolite and ssh][glssh] explains how gitolite uses openssh features to

View file

@ -6,6 +6,11 @@ start [here][migr]. RTFM is *mandatory* for migrations.</font>
----
This is the first step in using gitolite, and happens on the server. It is
followed by [setup][], then [clone][].
----
[[TOC]]
----
@ -20,6 +25,9 @@ The real user used is called the **hosting user**. Typically this user is
RPMs and DEBs create a user called *gitolite* for this, so adjust instructions
and examples accordingly.
**Unless otherwise stated, everything in this page is to be done by logging in
as this "hosting user"**.
Notes:
* Any unix user can be a hosting user.
@ -72,6 +80,9 @@ side.
## the actual install
**Note**: This section describes installing an ssh-based setup. For smart
http setup click [here][http].
Gitolite has only one server side "command" now, much like git itself. This
command is `gitolite`. You don't need to place it anywhere special; worst
case you run it with the full path.

View file

@ -14,7 +14,7 @@
* [lost][lost-key] admin key/access
* [bypass][]ing gitolite
* [clean][]ing out a botched install
* [common][ce] errors (TBD)
* [common][ce] errors
* [uncommon][ue] errors
* things that are [not gitolite problems][ngp]
@ -43,16 +43,18 @@
## [setup][]
## [clone][]
## gitolite [admin][]istration
* [server][]-side
* ([server-side][server]) settings, hooks, etc.
* ([link][WARNINGS]: important cautions on server side activity)
* changing settings in the [rc][] file
* installing custom [hooks][]
* ([link][existing]: moving existing repos into gitolite)
* [access control][conf] (the gitolite.conf file)
* [example][confex] of a conf file
* basic [syntax][]
* ([client-side][adminrepo]) access control via the gitolite-admin repo
* basic [syntax][] of the [conf][] file
* include files
* ([link][sugar]: syntactic sugar)
* [groups][] (of users and repos)
@ -93,6 +95,7 @@
* [disabling pushes][writable] to take backups
* [personal][pers] branches
* ([link][votes]: voting on commits)
* [delegating][deleg] access control responsibilities
* ([link][NAME]: the NAME VREF)
* the [subconf][] command

View file

@ -1,25 +1,9 @@
# quick install, setup, and clone
(Please do not ignore the "assumptions" list below).
On the server:
# get the software
git clone git://github.com/sitaramc/gitolite
# install it
gitolite/install -ln
# setup the initial repos with your key
gitolite setup -pk your-name.pub
On your workstation:
# clone the admin repo so you can start adding stuff
git clone git@host:gitolite-admin.git
## ASSUMPTIONS
* This is an ssh-based setup. For smart http setup click [here][http].
* This is a fresh install, not a migration from the old gitolite (v1.x,
v2.x).
@ -34,15 +18,31 @@ On your workstation:
* If it does, please see [common errors][ce] and fix things before
continuing, or read the more complete [setup][] page.
## Notes
## instructions
Note that the clone path is NOT "repositories/gitolite-admin.git". If you
clone with a path that includes "repositories/", the clone should fail. If
the clone *does* succeed, a subsequent push should fail :-) See
[this][ybpfail] for some details. If that doesn't make enough sense read all
of [ssh][].
On the server, as the hosting user (e.g., 'git'):
# get the software
git clone git://github.com/sitaramc/gitolite
# install it
gitolite/install -ln
# setup the initial repos with your key
gitolite setup -pk your-name.pub
On your workstation:
# clone the admin repo so you can start adding stuff
git clone git@host:gitolite-admin.git
# Note 1: clone path must not include "repositories/"
# Note 2: it may include the ".git" at the end but it is optional
## next steps
Next steps are usually adding [users][] and [repos][] and learning about
[access control][conf].
If this step succeeds, you can add [users][], [repos][], or anything else
described [here][adminrepo].
If this step fails, be sure to look at the [ssh][] documentation before asking
for help. (A very basic first step is to run `ssh git@host info`;
[this][info] page tells you what to expect).

View file

@ -1,11 +1,16 @@
# setting up gitolite
This is the second step in using gitolite, after [install][]. This also
happens on the server, (The next step is [clone][]).
----
Installing the software gets you ready to use it, but the first "use" of it is
always the "setup" command.
The first time you run it, you need to have a public key file ready. If the
main gitolite admin's username is "alice", this file should be named
"alice.pub". Then run
The first time you run it, you need to have a public key file (usually from
the admin's workstation) ready. If the main gitolite admin's username is
"alice", this file should be named "alice.pub". Then run
gitolite setup -pk alice.pub

View file

@ -6,6 +6,10 @@ who stop reading halfway!
----
[[TOC]]
----
Here's an example to start you off.
repo r1
@ -262,12 +266,13 @@ copied to `src/VREF/EMAIL-CHECK` and it works, because VREFs get
the same first 3 arguments and those are all that it cares about. (Note: you
have to change one subroutine in that script if you want to use it)
### catching duplicate pubkeys
### #votes voting on commits
This checks keydir/ for duplicate keys and aborts the push if it finds any.
You should use this only on the gitolite-admin repo.
We covered this as a teaser example at the start.
Although gitolite can't/won't do the whole "code review + workflow
enforcement" thing that Gerrit Code Review does, a basic implementation of
voting on a commit is surprisingly easy. See src/VREF/VOTES for details (and
note that the actual *code* is just 2-3 lines; the rest is inline
documentation).
## other ideas -- code welcome!