(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 ## #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. * Changing anything in the [rc][] file.
* Installing custom [hooks][], whether to all repos or just some repos. * 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. 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 Most of gitolite's power is in the conf/gitolite.conf file, which specifies
detailed access control for repos. detailed access control for repos. Everything except [adding users][users]
happens from this file.
### #confex example of a conf file
Here is an example of a simple conf/gitolite.conf 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 # 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: There are two documents you need to read, in order:
* [Gitolite and ssh][glssh] explains how gitolite uses openssh features to * [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]] [[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 RPMs and DEBs create a user called *gitolite* for this, so adjust instructions
and examples accordingly. and examples accordingly.
**Unless otherwise stated, everything in this page is to be done by logging in
as this "hosting user"**.
Notes: Notes:
* Any unix user can be a hosting user. * Any unix user can be a hosting user.
@ -72,6 +80,9 @@ side.
## the actual install ## 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 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 command is `gitolite`. You don't need to place it anywhere special; worst
case you run it with the full path. case you run it with the full path.

View file

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

View file

@ -1,25 +1,9 @@
# quick install, setup, and clone # 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 ## 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, * This is a fresh install, not a migration from the old gitolite (v1.x,
v2.x). v2.x).
@ -34,15 +18,31 @@ On your workstation:
* If it does, please see [common errors][ce] and fix things before * If it does, please see [common errors][ce] and fix things before
continuing, or read the more complete [setup][] page. continuing, or read the more complete [setup][] page.
## Notes ## instructions
Note that the clone path is NOT "repositories/gitolite-admin.git". If you On the server, as the hosting user (e.g., 'git'):
clone with a path that includes "repositories/", the clone should fail. If
the clone *does* succeed, a subsequent push should fail :-) See # get the software
[this][ybpfail] for some details. If that doesn't make enough sense read all git clone git://github.com/sitaramc/gitolite
of [ssh][].
# 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
Next steps are usually adding [users][] and [repos][] and learning about If this step succeeds, you can add [users][], [repos][], or anything else
[access control][conf]. 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 # 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 Installing the software gets you ready to use it, but the first "use" of it is
always the "setup" command. always the "setup" command.
The first time you run it, you need to have a public key file ready. If the The first time you run it, you need to have a public key file (usually from
main gitolite admin's username is "alice", this file should be named the admin's workstation) ready. If the main gitolite admin's username is
"alice.pub". Then run "alice", this file should be named "alice.pub". Then run
gitolite setup -pk alice.pub gitolite setup -pk alice.pub

View file

@ -6,6 +6,10 @@ who stop reading halfway!
---- ----
[[TOC]]
----
Here's an example to start you off. Here's an example to start you off.
repo r1 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 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) 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. Although gitolite can't/won't do the whole "code review + workflow
You should use this only on the gitolite-admin repo. 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
We covered this as a teaser example at the start. note that the actual *code* is just 2-3 lines; the rest is inline
documentation).
## other ideas -- code welcome! ## other ideas -- code welcome!