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

(doc) assorted docfixes

Browse source
This commit is contained in:
Sitaram Chamarty 2011-09-04 06:52:00 +05:30
parent a6668b90c3
commit 8b501a1872
10 changed files with 78 additions and 38 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
README.mkd
View file

@ -28,7 +28,9 @@ don't miss out on them by skipping the excellent
[documentation][docs]!)</font>
* create a user called `git`. Login to this user.
* copy your ssh pubkey from your workstation. Rename it to `YourName.pub`.
* now run these commands:
git clone git://github.com/sitaramc/gitolite
@ -36,8 +38,12 @@ don't miss out on them by skipping the excellent
src/gl-system-install
gl-setup ~/YourName.pub
You're done. Now run `git clone git@server:gitolite-admin` on your
workstation and [add users and repos][aur].
You're done.
A word of caution: do **NOT** add repos or users directly on the server! You
MUST manage the server by cloning the special 'gitolite-admin' repo on your
workstation (`git clone git@server:gitolite-admin`), making changes, and
pushing them. See [here][aur] for how to add users and repos.
[aur]: http://sitaramc.github.com/gitolite/doc/2-admin.html#_adding_users_and_repos

2
contrib/adc/README.mkd
View file

@ -1,4 +1,4 @@
# brief descriptions of the shipped ADCs (admin-defined commands)
## brief descriptions of the shipped ADCs (admin-defined commands)
(...with pointers to further information where needed)

2
contrib/adc/hub.mkd
View file

@ -1,4 +1,4 @@
# the 'hub' ADC
## the 'hub' ADC
In this document:

9
contrib/adc/repo-deletion.mkd
View file

@ -1,4 +1,11 @@
# deleting repos safely
## deleting repos safely
**NOTE**: this page is about deleting [user-created repos][wcr]. It is
**not** about deleting "normal" repos (the kind that are specified in the
gitolite.conf file itself) -- to delete those read [here][dnr].
[wcr]: http://sitaramc.github.com/gitolite/doc/wildcard-repositories.html
[dnr]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html#_deleting_a_repo
(see [this thread][thr] on the gitolite mailing list)

2
contrib/mirroring-complex-example.mkd
View file

@ -1,4 +1,4 @@
# semi-autonomous mirroring setup example
## semi-autonomous mirroring setup example
[deldoc]: http://sitaramc.github.com/gitolite/doc/delegation.html
[sc]: http://sitaramc.github.com/gitolite/doc/delegation.html#_the_subconf_command

10
doc/2-admin.mkd
View file

@ -50,6 +50,11 @@ Once you've cloned it, you're ready to add users and repos.
### adding users and repos
Do **NOT** add repos or users directly on the server! You MUST manage the
server by cloning the special 'gitolite-admin' repo on your workstation (`git
clone git@server:gitolite-admin`), making changes, and pushing them. This
section tells you how to add users and repos.
* ask each user who will get access to send you a public key. See other
sources (for example [here][genpub]) for how to do this
@ -245,8 +250,9 @@ important here:
`~/repositories`), making sure that the directory names end in ".git".
* back on your workstation, add each repo (without the `.git` suffix) to
`conf/gitolite.conf` in your gitolite-admin repo clone. Then add, commit,
push.
`conf/gitolite.conf` in your gitolite-admin repo clone. Give *some* user
(even a non-existent one like "DUMMY" is fine) at least "R" access to
these repos. Then add, commit, push.
**Case 3 -- far too many repos** (or your initials are JH ;-): This is when
you're like Case 2, except you have *so many* repos that step 3 becomes too

65
doc/3-faq-tips-etc.mkd
View file

@ -32,6 +32,8 @@ In this document:
* <a href="#_admin_defined_commands">admin defined commands</a>
* <a href="#_access_control_for_external_commands">access control for external commands</a>
* <a href="#_svnserve">svnserve</a>
* <a href="#_odds_and_ends">odds and ends</a>
* <a href="#_poking_the_admin_repo_to_force_a_compile">"poking" the admin repo to force a compile</a>
* <a href="#_design_choices">design choices</a>
* <a href="#_keeping_the_parser_and_the_access_control_separate">keeping the parser and the access control separate</a>
@ -107,47 +109,45 @@ features than the original goal of branch-level access control.
##### one user, many keys
I have a laptop and a desktop I need to access the server from. I have
different private keys on them, but as far as gitolite is concerned both of
them should be treated as "sitaram". How does this work?
If you have a user who has more than one pubkey (like from different machines)
the simplest way to deal with it is to add subdirectories and add keys there.
For example, I might have these files in `keydir/`:
The way it works is that you copy one pubkey as "sitaram@laptop.pub" and the
other as "sitaram@desktop.pub". The part before the "@" is the username, so
gitolite knows these two keys belong to the same person. The part after the
"@" can be anything you like, of course; gitolite doesn't care.
sitaram.pub
home/sitaram.pub
laptop/sitaram.pub
Note that you don't say "sitaram@laptop" and so on in the **config** file --
as far as the config file is concerned there's just **one** user called
"sitaram" -- so you only say "sitaram" there.
<font color="gray">
I think this is easier to maintain if you have to delete or change one of
those keys.
The older method will continue to work, simply because I prefer it. But I am
not going to document it except for the example below, nor am I going to
support it in terms of questions. Sorry. Apparently it was too complex to
understand, even for some smart folks I know. This tells me it was probably
ill thought out and should have been obsoleted as soon as e0fe73a was pushed.
However, now that `sitaramc@gmail.com` is also a valid username, we need to
distinguish between `sitaramc@gmail.com.pub` and `sitaramc@desktop.pub`. We
do that by requiring that the multi-key suffix you use (like "desktop" and
"laptop") should not have a `"."` in it. If it does, it looks like an email
address. The following table lists sample pubkey filenames and the
corresponding derived usernames (which is what goes into the
`conf/gitolite.conf` file):
Anyway, here's *all* the documentation for it -- some sample pubkey filenames
and the corresponding derived usernames:
* old style multikeys; not mistaken for emails because there is no "." in
hostname part
* plain username, no multikey
sitaramc.pub sitaramc
* plain username, with multikeys
sitaramc@laptop.pub sitaramc
sitaramc@desktop.pub sitaramc
* new style, email keys; there is a "." in hostname part; so it's an email
address
* email address as username, no multikey
sitaramc@gmail.com.pub sitaramc@gmail.com
* multikeys *with* email address
* email address as username, with multikeys
sitaramc@gmail.com@laptop.pub sitaramc@gmail.com
sitaramc@gmail.com@desktop.pub sitaramc@gmail.com
</font>
<a name="_security_access_control_and_auditing"></a>
#### security, access control, and auditing
@ -532,6 +532,23 @@ system. Assuming you installed gitolite to the same user as the one you used
for SVN, SVN connectivity will be retained, and users will be able to use
both SVN and git using the same SSH configuration.
<a name="_odds_and_ends"></a>
### odds and ends
<a name="_poking_the_admin_repo_to_force_a_compile"></a>
#### "poking" the admin repo to force a compile
Sometimes you need to force a compile, as if you pushed the gitolite-admin
repo. I have a git alias that looks like this:
[alias]
poke = !git ls-remote origin | grep -w refs/heads/poke && git push origin :poke || git push origin master:poke
so I just run `git poke`. This toggles between deleting and creating a dummy
branch called "poke". Either operation will trigger the hooks.
<a name="_design_choices"></a>
### design choices

10
doc/gitolite.conf.mkd
View file

@ -541,12 +541,14 @@ later to override the generic settings.
#### repo owner/description line for gitweb
Including a line like this:
You can include owner/description information in the conf file, and gitolite
will put it in places where gitweb will pick it up. For example, suppose this
software (gitolite) itself was being hosted on a gitolite server and intended
to be shown on gitweb, I'd use a line like this:
gitolite "Sitaram Chamarty" = "fast, secure, access control for git in a corporate environment"
gitolite "Sitaram Chamarty" = "fast, secure, access control for git"
sets the owner name and description for gitweb. The general syntax is very
simple, just use one of:
The general syntax is very simple, just use one of:
reponame = "some description string in double quotes"
reponame "owner name" = "some description string in double quotes"

4
doc/gitolite.rc.mkd
View file

@ -127,7 +127,8 @@ on feedback from my users to find or fix issues.
This setting allows the repo admin to define acceptable gitconfig keys.
Gitolite allows you to set git repo options using the "config" keyword;
see doc/gitolite.conf.mkd for details and syntax.
see the section on "repo specific git config commands" in
[doc/gitolite.conf.mkd][gitconf] for details and syntax.
However, if you are in an installation where the repo admin does not (and
should not) have shell access to the server, then allowing him to set
@ -367,3 +368,4 @@ of `ADC_CMD_ARGS_PATT`), please be sure you know what you're doing.
[smart]: http://sitaramc.github.com/gitolite/doc/http-backend.html
[dwr]: http://sitaramc.github.com/gitolite/doc/3-faq-tips-etc.html#_disabling_write_access_to_take_backups
[limit]: http://sitaramc.github.com/gitolite/doc/report-output.html#_using_patterns_to_limit_output
[gitconf]: http://sitaramc.github.com/gitolite/doc/gitolite.conf.html#_repo_specific_git_config_commands

2
doc/mirroring.mkd
View file

@ -1,4 +1,4 @@
# mirroring gitolite servers
## mirroring gitolite servers
Mirroring a repo is simple in git; you just need code like this in a
`post-receive` hook in each repo: