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

better anchors in docs: changed autotoc and ran it through all docs

Browse source
This commit is contained in:
Sitaram Chamarty 2010-06-01 06:16:13 +05:30
parent 5bbd102059
commit faf1629fd8
12 changed files with 251 additions and 267 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
README.mkd
View file

@ -8,15 +8,15 @@ given branch.
In this document:
* <a href="#A1">what</a>
* <a href="#A2">why</a>
* <a href="#A3">other features</a>
* <a href="#A4">security</a>
* <a href="#A5">contact and license</a>
* <a href="#what">what</a>
* <a href="#why">why</a>
* <a href="#other_features">other features</a>
* <a href="#security">security</a>
* <a href="#contact_and_license">contact and license</a>
----
<a name="A1"></a>
<a name="what"></a>
### what
@ -33,7 +33,7 @@ requiring root permissions, and with no additional software than git itself
and perl. It also has several other neat features described below and
elsewhere in the [doc/][docs] directory.
<a name="A2"></a>
<a name="why"></a>
### why
@ -80,7 +80,7 @@ Gitolite does away with all this:
read-write access, not only at the repository level, but at the branch
level within repositories.
<a name="A3"></a>
<a name="other_features"></a>
### other features
@ -114,7 +114,7 @@ detail somewhere in gitolite's [doc/][docs] subdirectory.
* specify repos using patterns (patterns may include creator's name)
* define powerful operations on the server side, even github-like forking
<a name="A4"></a>
<a name="security"></a>
### security
@ -136,7 +136,7 @@ details, looking for the word "security".
----
<a name="A5"></a>
<a name="contact_and_license"></a>
### contact and license

36
contrib/autotoc
View file

@ -1,25 +1,31 @@
#!/usr/bin/perl -w
use strict;
# filter gitolite's mkd files through this; it's designed to be idempotent of
# course
undef $/;
$doc = <>;
$doc =~ s/^<a name="A\d+"><\/a>\n\n//mg;
@toc = $doc =~ /^###.*/mg;
$i = 0;
$doc =~ s/^###/$i++; "<a name=\"A$i\"><\/a>\n\n###"/mge;
$i = 0;
for (@toc) {
$i++;
s/### (.*)/ * <a href="#A$i">$1<\/a>/;
s/^(#+)/' ' x length($1)/e;
sub make_anchor {
# make an anchor out of a section heading
my $sh = shift;
$sh =~ s/\W+/_/g;
$sh =~ s/^_//;
return $sh;
}
$toc = "In this document:\n\n";
undef $/;
my $doc = <>;
$doc =~ s/^<a name=".*"><\/a>\n\n//mg;
my @toc = $doc =~ /^###+ .*/mg;
$doc =~ s/^(###+) (.*)/"<a name=\"" . &make_anchor($2) . "\"><\/a>\n\n$1 $2"/mge;
for (@toc) {
s/^(###+) (.*)/' ' x (length($1)-3) . ' * <a href="#' . &make_anchor($2) . "\">$2<\/a>"/e;
}
my $toc = "In this document:\n\n";
$toc .= join("\n", @toc);
$toc .= "\n\n";

72
doc/0-INSTALL.mkd
View file

@ -2,32 +2,32 @@
In this document:
* <a href="#A1">please read this first</a>
* <a href="#A2">important notes</a>
* <a href="#A3">conventions used</a>
* <a href="#A4">requirements</a>
* <a href="#A5">client side</a>
* <a href="#A6">server side</a>
* <a href="#A7">installation and setup</a>
* <a href="#A8">(package method) directly on the server, using RPM/DEB</a>
* <a href="#A9">(root method) directly on the server, manually, with root access</a>
* <a href="#A10">(non-root method) directly on the server, manually, without root access</a>
* <a href="#A11">(from-client method) install from the client to the server</a>
* <a href="#A12">special cases -- multiple gitolite servers</a>
* <a href="#A13">package method and root method</a>
* <a href="#A14">from-client method</a>
* <a href="#A15">upgrading</a>
* <a href="#A16">uninstalling</a>
* <a href="#A17">cleaning out a botched install</a>
* <a href="#A18">uninstalling gitolite completely</a>
* <a href="#please_read_this_first">please read this first</a>
* <a href="#important_notes">important notes</a>
* <a href="#conventions_used">conventions used</a>
* <a href="#requirements">requirements</a>
* <a href="#client_side">client side</a>
* <a href="#server_side">server side</a>
* <a href="#installation_and_setup">installation and setup</a>
* <a href="#package_method_directly_on_the_server_using_RPM_DEB">(package method) directly on the server, using RPM/DEB</a>
* <a href="#root_method_directly_on_the_server_manually_with_root_access">(root method) directly on the server, manually, with root access</a>
* <a href="#non_root_method_directly_on_the_server_manually_without_root_access">(non-root method) directly on the server, manually, without root access</a>
* <a href="#from_client_method_install_from_the_client_to_the_server">(from-client method) install from the client to the server</a>
* <a href="#special_cases_multiple_gitolite_servers">special cases -- multiple gitolite servers</a>
* <a href="#package_method_and_root_method">package method and root method</a>
* <a href="#from_client_method">from-client method</a>
* <a href="#upgrading">upgrading</a>
* <a href="#uninstalling">uninstalling</a>
* <a href="#cleaning_out_a_botched_install">cleaning out a botched install</a>
* <a href="#uninstalling_gitolite_completely">uninstalling gitolite completely</a>
----
<a name="A1"></a>
<a name="please_read_this_first"></a>
### please read this first
<a name="A2"></a>
<a name="important_notes"></a>
#### important notes
@ -44,7 +44,7 @@ Please make sure you understand the following points first.
To make matters worse, ssh problems in gitolite don't always look like ssh
problems. See [doc/6-ssh-troubleshooting.mkd][doc6] for help.
<a name="A3"></a>
<a name="conventions_used"></a>
#### conventions used
@ -52,11 +52,11 @@ We assume the admin user is "sitaram", and his workstation is called "client".
The hosting user is "git", and the server is called "server". Substitute your
values as needed.
<a name="A4"></a>
<a name="requirements"></a>
#### requirements
<a name="A5"></a>
<a name="client_side"></a>
##### client side
@ -68,7 +68,7 @@ values as needed.
shell is needed
* again, msysgit on Windows is fine
<a name="A6"></a>
<a name="server_side"></a>
##### server side
@ -81,11 +81,11 @@ values as needed.
* perl (but since git requires it anyway, you probably have it)
* openssh or any ssh that can understand the `authorized_keys` file format
<a name="A7"></a>
<a name="installation_and_setup"></a>
### installation and setup
<a name="A8"></a>
<a name="package_method_directly_on_the_server_using_RPM_DEB"></a>
#### (package method) directly on the server, using RPM/DEB
@ -99,7 +99,7 @@ values as needed.
* on the client, run `cd; git clone git@server:gitolite-admin`
<a name="A9"></a>
<a name="root_method_directly_on_the_server_manually_with_root_access"></a>
#### (root method) directly on the server, manually, with root access
@ -119,7 +119,7 @@ values as needed.
* on the client, run `cd; git clone git@server:gitolite-admin`
<a name="A10"></a>
<a name="non_root_method_directly_on_the_server_manually_without_root_access"></a>
#### (non-root method) directly on the server, manually, without root access
@ -147,7 +147,7 @@ server so that if you screw up the keys you can still get on, or be able to
* on the client, run `cd; git clone git@server:gitolite-admin`
<a name="A11"></a>
<a name="from_client_method_install_from_the_client_to_the_server"></a>
#### (from-client method) install from the client to the server
@ -162,11 +162,11 @@ documentation.
This method is verbosely documented in [doc/7-install-transcript.mkd][doc7],
including *outputs* of the commands concerned.
<a name="A12"></a>
<a name="special_cases_multiple_gitolite_servers"></a>
### special cases -- multiple gitolite servers
<a name="A13"></a>
<a name="package_method_and_root_method"></a>
#### package method and root method
@ -190,7 +190,7 @@ to have a command line on the server, so don't give them the passwords if you
don't need to -- the pubkey will allow them to be gitolite admins on their
domain, and that's quite enough for normal operations.
<a name="A14"></a>
<a name="from_client_method"></a>
#### from-client method
@ -210,7 +210,7 @@ have been created as respective clones. Or you can re-clone elsewhere:
cd ~/admin1; git clone gitolite_server_1:gitolite-admin.git
cd ~/admin2; git clone gitolite_server_2:gitolite-admin.git
<a name="A15"></a>
<a name="upgrading"></a>
### upgrading
@ -222,11 +222,11 @@ arguments!
Also, remember that some new features may require additional settings in your
`~/.gitolite.rc` file.
<a name="A16"></a>
<a name="uninstalling"></a>
### uninstalling
<a name="A17"></a>
<a name="cleaning_out_a_botched_install"></a>
#### cleaning out a botched install
@ -244,7 +244,7 @@ here's how to clean the slate.
* remove `~/.gitolite`, `~/.gitolite.rc` and
`~/repositories/gitolite-admin.git`
<a name="A18"></a>
<a name="uninstalling_gitolite_completely"></a>
#### uninstalling gitolite completely

32
doc/2-admin.mkd
View file

@ -5,18 +5,18 @@
In this document:
* <a href="#A1">please read this first</a>
* <a href="#A2">adding users and repos</a>
* <a href="#A3">other features</a>
* <a href="#A4">moving pre-existing repos into gitolite</a>
* <a href="#A5">specifying gitweb and daemon access</a>
* <a href="#A6">custom hooks</a>
* <a href="#A7">hook chaining</a>
* <a href="#A8">custom git config</a>
* <a href="#please_read_this_first">please read this first</a>
* <a href="#adding_users_and_repos">adding users and repos</a>
* <a href="#other_features">other features</a>
* <a href="#moving_pre_existing_repos_into_gitolite">moving pre-existing repos into gitolite</a>
* <a href="#specifying_gitweb_and_daemon_access">specifying gitweb and daemon access</a>
* <a href="#custom_hooks">custom hooks</a>
* <a href="#hook_chaining">hook chaining</a>
* <a href="#custom_git_config">custom git config</a>
----
<a name="A1"></a>
<a name="please_read_this_first"></a>
### please read this first
@ -31,7 +31,7 @@ In this document:
Once you've cloned it, you're ready to add users and repos.
<a name="A2"></a>
<a name="adding_users_and_repos"></a>
### adding users and repos
@ -54,11 +54,11 @@ Once you've cloned it, you're ready to add users and repos.
automatically be created (empty, but clonable) and users' access will be
updated as needed.
<a name="A3"></a>
<a name="other_features"></a>
### other features
<a name="A4"></a>
<a name="moving_pre_existing_repos_into_gitolite"></a>
#### moving pre-existing repos into gitolite
@ -79,7 +79,7 @@ gitolite:
`conf/gitolite.conf` in your gitolite-admin repo clone. Then add, commit,
push.
<a name="A5"></a>
<a name="specifying_gitweb_and_daemon_access"></a>
#### specifying gitweb and daemon access
@ -117,7 +117,7 @@ The "compile" script will keep these files consistent with the config settings
-- this includes removing such settings/files if you remove "read" permissions
for the special usernames or remove the description line.
<a name="A6"></a>
<a name="custom_hooks"></a>
#### custom hooks
@ -136,7 +136,7 @@ implements all the branch-level permissions in gitolite. If you fiddle with
the hooks directory, please make sure you do not mess with this file
accidentally, or all your fancy per-branch permissions will stop working.**
<a name="A7"></a>
<a name="hook_chaining"></a>
#### hook chaining
@ -159,7 +159,7 @@ Finally, these names (`update.secondary` and `post-update.secondary`) are
merely the defaults. You can change them to anything you want; look in
conf/example.gitolite.rc for details.
<a name="A8"></a>
<a name="custom_git_config"></a>
#### custom git config

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

@ -2,44 +2,44 @@
In this document:
* <a href="#A1">common errors and mistakes</a>
* <a href="#A2">git version dependency</a>
* <a href="#A3">other errors, warnings, notes...</a>
* <a href="#A4">cloning an empty repo</a>
* <a href="#A5">`@all` syntax for repos</a>
* <a href="#A6">umask setting</a>
* <a href="#A7">getting a tar file from a clone</a>
* <a href="#A8">features</a>
* <a href="#A9">syntax and normal usage</a>
* <a href="#A10">simpler syntax</a>
* <a href="#A11">one user, many keys</a>
* <a href="#A12">security, access control, and auditing</a>
* <a href="#A13">two levels of access rights checking</a>
* <a href="#A14">better logging</a>
* <a href="#A15">"exclude" (or "deny") rules</a>
* <a href="#A16">separating delete and rewind rights</a>
* <a href="#A17">file/dir NAME based restrictions</a>
* <a href="#A18">delegating parts of the config file</a>
* <a href="#A19">convenience features</a>
* <a href="#A20">what repos do I have access to?</a>
* <a href="#A21">including config lines from other files</a>
* <a href="#A22">support for git installed outside default PATH</a>
* <a href="#A23">"personal" branches</a>
* <a href="#A24">custom hooks and custom git config</a>
* <a href="#A25">helping with gitweb</a>
* <a href="#A26">easier to specify gitweb "description" and gitweb/daemon access</a>
* <a href="#A27">easier to link gitweb authorisation with gitolite</a>
* <a href="#A28">advanced features</a>
* <a href="#A29">repos named with wildcards</a>
* <a href="#A30">admin defined commands</a>
* <a href="#A31">access control for external commands</a>
* <a href="#A32">svnserve</a>
* <a href="#A33">design choices</a>
* <a href="#A34">keeping the parser and the access control separate</a>
* <a href="#common_errors_and_mistakes">common errors and mistakes</a>
* <a href="#git_version_dependency">git version dependency</a>
* <a href="#other_errors_warnings_notes_">other errors, warnings, notes...</a>
* <a href="#cloning_an_empty_repo">cloning an empty repo</a>
* <a href="#all_syntax_for_repos">`@all` syntax for repos</a>
* <a href="#umask_setting">umask setting</a>
* <a href="#getting_a_tar_file_from_a_clone">getting a tar file from a clone</a>
* <a href="#features">features</a>
* <a href="#syntax_and_normal_usage">syntax and normal usage</a>
* <a href="#simpler_syntax">simpler syntax</a>
* <a href="#one_user_many_keys">one user, many keys</a>
* <a href="#security_access_control_and_auditing">security, access control, and auditing</a>
* <a href="#two_levels_of_access_rights_checking">two levels of access rights checking</a>
* <a href="#better_logging">better logging</a>
* <a href="#exclude_or_deny_rules">"exclude" (or "deny") rules</a>
* <a href="#separating_delete_and_rewind_rights">separating delete and rewind rights</a>
* <a href="#file_dir_NAME_based_restrictions">file/dir NAME based restrictions</a>
* <a href="#delegating_parts_of_the_config_file">delegating parts of the config file</a>
* <a href="#convenience_features">convenience features</a>
* <a href="#what_repos_do_I_have_access_to_">what repos do I have access to?</a>
* <a href="#including_config_lines_from_other_files">including config lines from other files</a>
* <a href="#support_for_git_installed_outside_default_PATH">support for git installed outside default PATH</a>
* <a href="#personal_branches">"personal" branches</a>
* <a href="#custom_hooks_and_custom_git_config">custom hooks and custom git config</a>
* <a href="#helping_with_gitweb">helping with gitweb</a>
* <a href="#easier_to_specify_gitweb_description_and_gitweb_daemon_access">easier to specify gitweb "description" and gitweb/daemon access</a>
* <a href="#easier_to_link_gitweb_authorisation_with_gitolite">easier to link gitweb authorisation with gitolite</a>
* <a href="#advanced_features">advanced features</a>
* <a href="#repos_named_with_wildcards">repos named with wildcards</a>
* <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="#design_choices">design choices</a>
* <a href="#keeping_the_parser_and_the_access_control_separate">keeping the parser and the access control separate</a>
----
<a name="A1"></a>
<a name="common_errors_and_mistakes"></a>
### common errors and mistakes
@ -63,17 +63,17 @@ In this document:
Please see doc/6-ssh-troubleshooting.mkd for what all this means.
<a name="A2"></a>
<a name="git_version_dependency"></a>
### git version dependency
Gitolite (on the server) now refuses to run if git is not at least 1.6.2.
<a name="A3"></a>
<a name="other_errors_warnings_notes_"></a>
### other errors, warnings, notes...
<a name="A4"></a>
<a name="cloning_an_empty_repo"></a>
#### cloning an empty repo
@ -86,7 +86,7 @@ end hung up unexpectedly`. However, you can ignore this, since it doesn't
seem to hurt anything. [Update 2009-09-14; this has been fixed in git
1.6.4.3]
<a name="A5"></a>
<a name="all_syntax_for_repos"></a>
#### `@all` syntax for repos
@ -98,14 +98,14 @@ There *is* a way to use the `@all` syntax for repos also, as described in
access, we do not support this.
* don't try giving `@all` users some permission for `@all` repos
<a name="A6"></a>
<a name="umask_setting"></a>
#### umask setting
Gitweb not able to read your repos? You can change the umask for newly
created repos to something more relaxed -- see the `~/.gitolite.rc` file
<a name="A7"></a>
<a name="getting_a_tar_file_from_a_clone"></a>
### getting a tar file from a clone
@ -123,22 +123,18 @@ plain "git archive", because the Makefile adds a file called
<a name="features"></a>
<a name="A8"></a>
### features
Apart from the big ones listed in the top level README, and subjective ones
like "better config file format", gitolite has evolved to have many useful
features than the original goal of branch-level access control.
<a name="A9"></a>
<a name="syntax_and_normal_usage"></a>
#### syntax and normal usage
<a name="simpler_syntax"></a>
<a name="A10"></a>
##### simpler syntax
The basic syntax is simpler and cleaner but it goes beyond that: **you can
@ -182,9 +178,7 @@ do not worry that this causes some duplication or inefficiency. It doesn't
See the "specify gitweb/daemon access" section below for one more example.
<a name="multikeys"></a>
<a name="A11"></a>
<a name="one_user_many_keys"></a>
##### one user, many keys
@ -229,13 +223,11 @@ corresponding derived usernames (which is what goes into the
sitaramc@gmail.com@laptop.pub sitaramc@gmail.com
sitaramc@gmail.com@desktop.pub sitaramc@gmail.com
<a name="A12"></a>
<a name="security_access_control_and_auditing"></a>
#### security, access control, and auditing
<a name="two_levels"></a>
<a name="A13"></a>
<a name="two_levels_of_access_rights_checking"></a>
##### two levels of access rights checking
@ -271,7 +263,7 @@ any of the refexes match, the push succeeds. If none of them match, it fails.
Gitolite also allows "exclude" or "deny" rules. See later in this document
for details.
<a name="A14"></a>
<a name="better_logging"></a>
##### better logging
@ -299,7 +291,7 @@ The other parts of the log line are the name of the repo, the refname being
updated, the user updating it, and the refex pattern (from the config file)
that matched, in case you need to debug the config file itself.
<a name="A15"></a>
<a name="exclude_or_deny_rules"></a>
##### "exclude" (or "deny") rules
@ -350,7 +342,7 @@ And here's how it works:
before the third one, and it has a `-` as the permission, so the push
fails
<a name="A16"></a>
<a name="separating_delete_and_rewind_rights"></a>
##### separating delete and rewind rights
@ -389,7 +381,7 @@ message when you push, a non-existant user.
[sdrr]: http://groups.google.com/group/gitolite/browse_thread/thread/9f2b4358ce406d4c#
<a name="A17"></a>
<a name="file_dir_NAME_based_restrictions"></a>
##### file/dir NAME based restrictions
@ -400,7 +392,7 @@ changed, treating each filename as a "ref" to be matched.
Please see `conf/example.conf` for syntax and examples.
<a name="A18"></a>
<a name="delegating_parts_of_the_config_file"></a>
##### delegating parts of the config file
@ -409,13 +401,11 @@ access control for their own pieces. See
[doc/5-delegation.mkd](http://github.com/sitaramc/gitolite/blob/pu/doc/5-delegation.mkd)
for details.
<a name="A19"></a>
<a name="convenience_features"></a>
#### convenience features
<a name="myrights"></a>
<a name="A20"></a>
<a name="what_repos_do_I_have_access_to_"></a>
##### what repos do I have access to?
@ -448,13 +438,13 @@ administrator can also say things like:
to get this info for other user(s).
<a name="A21"></a>
<a name="including_config_lines_from_other_files"></a>
##### including config lines from other files
See the entry under "INCLUDE SOME OTHER FILE" in `conf/example.conf`.
<a name="A22"></a>
<a name="support_for_git_installed_outside_default_PATH"></a>
##### support for git installed outside default PATH
@ -488,7 +478,7 @@ the full PATH in the rc file, like so:
$ENV{PATH} = "/home/sitaram/bin:$ENV{PATH}";
<a name="A23"></a>
<a name="personal_branches"></a>
##### "personal" branches
@ -512,7 +502,7 @@ important thing is that the "branch" name should contain `/USER/` (including
the slashes). At runtime this will match whoever is the current user. Access
is still determined by the right hand side of course.
<a name="A24"></a>
<a name="custom_hooks_and_custom_git_config"></a>
##### custom hooks and custom git config
@ -520,9 +510,7 @@ You can specify hooks that you want to propagate to all repos, as well as
per-repo "gitconfig" settings. Please see `doc/2-admin.mkd` and
`conf/example.conf` for details.
<a name="gitweb"></a>
<a name="A25"></a>
<a name="helping_with_gitweb"></a>
#### helping with gitweb
@ -530,7 +518,7 @@ Although gitweb is a completely separate program, gitolite can do quite a
lot to help you manage gitweb access as well; once the initial setup is
complete, you can do it all from within the gitolite config file!
<a name="A26"></a>
<a name="easier_to_specify_gitweb_description_and_gitweb_daemon_access"></a>
##### easier to specify gitweb "description" and gitweb/daemon access
@ -579,9 +567,7 @@ Here's an example, using really short reponames because I'm lazy:
repo r2
# ...and so on...
<a name="gitwebauth"></a>
<a name="A27"></a>
<a name="easier_to_link_gitweb_authorisation_with_gitolite"></a>
##### easier to link gitweb authorisation with gitolite
@ -617,24 +603,24 @@ Gitweb allows you to specify a subroutine to decide on access. We use that
feature and tie it to gitolite. Configuration example can be found in
`contrib/gitweb/`.
<a name="A28"></a>
<a name="advanced_features"></a>
#### advanced features
<a name="A29"></a>
<a name="repos_named_with_wildcards"></a>
##### repos named with wildcards
Please see `doc/4-wildcard-repositories.mkd` for all the details.
<a name="A30"></a>
<a name="admin_defined_commands"></a>
##### admin defined commands
This requires the wildcards feature to be enabled, but is then an extremely
powerful feature. See `doc/admin-defined-commands.mkd`.
<a name="A31"></a>
<a name="access_control_for_external_commands"></a>
##### access control for external commands
@ -660,8 +646,6 @@ Commands implemented so far are:
<a name="svnserve"></a>
<a name="A32"></a>
###### svnserve
If you are transitioning from SVN to gitolite, and have a lot of users using
@ -672,11 +656,11 @@ 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="A33"></a>
<a name="design_choices"></a>
### design choices
<a name="A34"></a>
<a name="keeping_the_parser_and_the_access_control_separate"></a>
#### keeping the parser and the access control separate

44
doc/4-wildcard-repositories.mkd
View file

@ -19,17 +19,17 @@ workarounds I may not have the time to code it right away.
In this document:
* <a href="#A1">rc file setting required</a>
* <a href="#A2">Wildcard repos</a>
* <a href="#A3">Wildcard repos with creator name in them</a>
* <a href="#A4">Wildcard repos without creator name in them</a>
* <a href="#A5">Side-note: Line-anchored regexes</a>
* <a href="#A6">Contrast with refexes</a>
* <a href="#A7">Handing out rights to wildcard-matched repos</a>
* <a href="#A8">setting a gitweb description for a wildcard-matched repo</a>
* <a href="#A9">reporting</a>
* <a href="#A10">other issues and discussion</a>
* <a href="#A11">how it actually works</a>
* <a href="#rc_file_setting_required">rc file setting required</a>
* <a href="#Wildcard_repos">Wildcard repos</a>
* <a href="#Wildcard_repos_with_creator_name_in_them">Wildcard repos with creator name in them</a>
* <a href="#Wildcard_repos_without_creator_name_in_them">Wildcard repos without creator name in them</a>
* <a href="#Side_note_Line_anchored_regexes">Side-note: Line-anchored regexes</a>
* <a href="#Contrast_with_refexes">Contrast with refexes</a>
* <a href="#Handing_out_rights_to_wildcard_matched_repos">Handing out rights to wildcard-matched repos</a>
* <a href="#setting_a_gitweb_description_for_a_wildcard_matched_repo">setting a gitweb description for a wildcard-matched repo</a>
* <a href="#reporting">reporting</a>
* <a href="#other_issues_and_discussion">other issues and discussion</a>
* <a href="#how_it_actually_works">how it actually works</a>
----
@ -37,7 +37,7 @@ This document is mostly "by example".
----
<a name="A1"></a>
<a name="rc_file_setting_required"></a>
### rc file setting required
@ -45,7 +45,7 @@ This feature requires that you set `$GL_WILDREPOS` to "1" in `~/.gitolite.rc`
on the server. Please search for that variable and see comments around it in
`conf/example.gitolite.rc` for more information on this.
<a name="A2"></a>
<a name="Wildcard_repos"></a>
### Wildcard repos
@ -53,7 +53,7 @@ Which of these alternatives you choose depends on your needs, and the social
aspects of your environment. The first one is a little more rigid, making it
harder to make mistakes, and the second is more flexible and trusting.
<a name="A3"></a>
<a name="Wildcard_repos_with_creator_name_in_them"></a>
#### Wildcard repos with creator name in them
@ -79,7 +79,7 @@ new repo, as user "u4" (a student):
Notice the *two* empty repo inits, and the order in which they occur ;-)
<a name="A4"></a>
<a name="Wildcard_repos_without_creator_name_in_them"></a>
#### Wildcard repos without creator name in them
@ -106,7 +106,7 @@ and have a TA create the repos in advance.
In either case, they could then use the `setperms` feature to specify which
users are "READERS" and which are "WRITERS". See later for details.
<a name="A5"></a>
<a name="Side_note_Line_anchored_regexes"></a>
### Side-note: Line-anchored regexes
@ -123,7 +123,7 @@ But you may be surprised to find that it does not match even
`^assignments/S[0-9]+/A[0-9]+$` -- notice the line beginning and ending
metacharacters.
<a name="A6"></a>
<a name="Contrast_with_refexes"></a>
#### Contrast with refexes
@ -135,7 +135,7 @@ if no one will actually push such a branch! You can anchor both sides if you
really care, by using `master$` instead of `master`, but that is *not* the
default for refexes.
<a name="A7"></a>
<a name="Handing_out_rights_to_wildcard_matched_repos"></a>
### Handing out rights to wildcard-matched repos
@ -182,14 +182,14 @@ The following points are important:
* whoever you specify as "R" will match the special user READERS. "RW" will
match WRITERS.
<a name="A8"></a>
<a name="setting_a_gitweb_description_for_a_wildcard_matched_repo"></a>
### setting a gitweb description for a wildcard-matched repo
Similar to the getperm/setperm commands, there are the getdesc/setdesc
commands, thanks to Teemu.
<a name="A9"></a>
<a name="reporting"></a>
### reporting
@ -215,7 +215,7 @@ Push the config, then try
ssh gitolite expand
<a name="A10"></a>
<a name="other_issues_and_discussion"></a>
### other issues and discussion
@ -237,7 +237,7 @@ Push the config, then try
of the time, it won't be difficult; the fixed prefix will usually be
different anyway so there won't be overlaps.
<a name="A11"></a>
<a name="how_it_actually_works"></a>
### how it actually works

16
doc/5-delegation.mkd
View file

@ -6,14 +6,14 @@
In this document:
* <a href="#A1">lots of repos, lots of users</a>
* <a href="#A2">splitting up the set of repos into groups</a>
* <a href="#A3">delegating ownership of groups of repos</a>
* <a href="#A4">security/philosophy note</a>
* <a href="#lots_of_repos_lots_of_users">lots of repos, lots of users</a>
* <a href="#splitting_up_the_set_of_repos_into_groups">splitting up the set of repos into groups</a>
* <a href="#delegating_ownership_of_groups_of_repos">delegating ownership of groups of repos</a>
* <a href="#security_philosophy_note">security/philosophy note</a>
----
<a name="A1"></a>
<a name="lots_of_repos_lots_of_users"></a>
### lots of repos, lots of users
@ -47,7 +47,7 @@ access control rules for a set of repos they have been given authority for.
It's easier to show how it all works with an example instead of long
descriptions.
<a name="A2"></a>
<a name="splitting_up_the_set_of_repos_into_groups"></a>
### splitting up the set of repos into groups
@ -63,7 +63,7 @@ or repos, same syntax). So the basic idea is that the main config file
# any other config as usual, including access control lines for any of the
# above projects or groups
<a name="A3"></a>
<a name="delegating_ownership_of_groups_of_repos"></a>
### delegating ownership of groups of repos
@ -117,7 +117,7 @@ to the bottom of the main file.
----
<a name="A4"></a>
<a name="security_philosophy_note"></a>
### security/philosophy note

64
doc/6-ssh-troubleshooting.mkd
View file

@ -2,21 +2,21 @@
In this document:
* <a href="#A1">the most common problems that an admin will see</a>
* <a href="#A2">basic ssh troubleshooting</a>
* <a href="#A3">passphrases versus passwords</a>
* <a href="#A4">ssh-agent problems</a>
* <a href="#A5">basic ssh troubleshooting for the main admin</a>
* <a href="#A6">basic ssh troubleshooting for a normal user</a>
* <a href="#A7">windows issues</a>
* <a href="#A8">details</a>
* <a href="#A9">files on the server</a>
* <a href="#A10">files on client</a>
* <a href="#A11">why two keys on client</a>
* <a href="#A12">some other tips and tricks</a>
* <a href="#A13">giving shell access to gitolite users</a>
* <a href="#A14">losing your admin key</a>
* <a href="#A15">simulating ssh-copy-id</a>
* <a href="#the_most_common_problems_that_an_admin_will_see">the most common problems that an admin will see</a>
* <a href="#basic_ssh_troubleshooting">basic ssh troubleshooting</a>
* <a href="#passphrases_versus_passwords">passphrases versus passwords</a>
* <a href="#ssh_agent_problems">ssh-agent problems</a>
* <a href="#basic_ssh_troubleshooting_for_the_main_admin">basic ssh troubleshooting for the main admin</a>
* <a href="#basic_ssh_troubleshooting_for_a_normal_user">basic ssh troubleshooting for a normal user</a>
* <a href="#windows_issues">windows issues</a>
* <a href="#details">details</a>
* <a href="#files_on_the_server">files on the server</a>
* <a href="#files_on_client">files on client</a>
* <a href="#why_two_keys_on_client">why two keys on client</a>
* <a href="#some_other_tips_and_tricks">some other tips and tricks</a>
* <a href="#giving_shell_access_to_gitolite_users">giving shell access to gitolite users</a>
* <a href="#losing_your_admin_key">losing your admin key</a>
* <a href="#simulating_ssh_copy_id">simulating ssh-copy-id</a>
----
@ -33,7 +33,7 @@ In addition to both these documents, there's now a program called
`sshkeys-lint` that you can run on your client. Run it without arguments to
get help on how to run it and what inputs it needs.
<a name="A1"></a>
<a name="the_most_common_problems_that_an_admin_will_see"></a>
### the most common problems that an admin will see
@ -85,7 +85,7 @@ the repo and clones ok. But when you push, gitolite's **update hook** kicks
in, and fails to run because you some of the environment variables it is
expecting are not present.
<a name="A2"></a>
<a name="basic_ssh_troubleshooting"></a>
### basic ssh troubleshooting
@ -98,7 +98,7 @@ username* of the admin.
Unless specifically mentioned, all these commands are run on the user's or
admin's workstation, not on the server.
<a name="A3"></a>
<a name="passphrases_versus_passwords"></a>
#### passphrases versus passwords
@ -119,7 +119,7 @@ The second is to use `ssh-agent` (or `keychain`, which in turn uses
`ssh-agent`) or something like that to manage your keys. Other than the next
section, further discussion of this is out of scope of this document.
<a name="A4"></a>
<a name="ssh_agent_problems"></a>
#### ssh-agent problems
@ -145,7 +145,7 @@ all, ssh will only use those keys. Even if you explicitly specify an unlisted
key using `ssh -i` or an `identityfile` directive in the config file, it won't
use it.
<a name="A5"></a>
<a name="basic_ssh_troubleshooting_for_the_main_admin"></a>
#### basic ssh troubleshooting for the main admin
@ -215,7 +215,7 @@ from scratch:
That's a long sequence but it should work.
<a name="A6"></a>
<a name="basic_ssh_troubleshooting_for_a_normal_user"></a>
#### basic ssh troubleshooting for a normal user
@ -234,7 +234,7 @@ you had command line access to the server *before* you were added as a
gitolite user. If you send that same key to your gitolite admin to include in
the admin repo, it won't work. For reasons why, see below.
<a name="A7"></a>
<a name="windows_issues"></a>
### windows issues
@ -252,13 +252,11 @@ link, or in contrib/ if it's a longer piece of text.
<a name="details"></a>
<a name="A8"></a>
### details
Here's how it all hangs together.
<a name="A9"></a>
<a name="files_on_the_server"></a>
#### files on the server
@ -290,7 +288,7 @@ Here's how it all hangs together.
argument `sitaram`. This is how gitolite is invoked, (and is told the
user logging in is "sitaram").
<a name="A10"></a>
<a name="files_on_client"></a>
#### files on client
@ -360,9 +358,7 @@ Here's how it all hangs together.
now works as expected, invoking the special keypair instead of the default
one.
<a name="twokeys"></a>
<a name="A11"></a>
<a name="why_two_keys_on_client"></a>
#### why two keys on client
@ -429,13 +425,11 @@ that should have enough info to get you going (but it helps to know ssh well):
That should do it.
<a name="complex"></a>
<a name="A12"></a>
<a name="some_other_tips_and_tricks"></a>
### some other tips and tricks
<a name="A13"></a>
<a name="giving_shell_access_to_gitolite_users"></a>
#### giving shell access to gitolite users
@ -463,7 +457,7 @@ access would not manage to get himself shell access.
Giving someone shell access requires that you should have shell access in the
first place, so the simplest way is to enable it from the server side only.
<a name="A14"></a>
<a name="losing_your_admin_key"></a>
#### losing your admin key
@ -473,7 +467,7 @@ gitolite-admin repository with a fresh key, take a look at the
of course. The top of the script has useful information on how to use it and
what it needs.
<a name="A15"></a>
<a name="simulating_ssh_copy_id"></a>
#### simulating ssh-copy-id

20
doc/7-install-transcript.mkd
View file

@ -20,15 +20,15 @@ you have to run it on your workstation, NOT on the server!**
In this document:
* <a href="#A1">create userids on server and client (optional)</a>
* <a href="#A2">get pubkey access from client to server</a>
* <a href="#A3">get gitolite source</a>
* <a href="#A4">install gitolite</a>
* <a href="#A5">examine what you have</a>
* <a href="#create_userids_on_server_and_client_optional_">create userids on server and client (optional)</a>
* <a href="#get_pubkey_access_from_client_to_server">get pubkey access from client to server</a>
* <a href="#get_gitolite_source">get gitolite source</a>
* <a href="#install_gitolite">install gitolite</a>
* <a href="#examine_what_you_have">examine what you have</a>
----
<a name="A1"></a>
<a name="create_userids_on_server_and_client_optional_"></a>
### create userids on server and client (optional)
@ -75,7 +75,7 @@ because I'm not showing the actual "vi" session):
----
<a name="A2"></a>
<a name="get_pubkey_access_from_client_to_server"></a>
### get pubkey access from client to server
@ -126,7 +126,7 @@ Double check to make sure you can log on to `git@server` without a password:
----
<a name="A3"></a>
<a name="get_gitolite_source"></a>
### get gitolite source
@ -138,7 +138,7 @@ Double check to make sure you can log on to `git@server` without a password:
Receiving objects: 100% (1157/1157), 270.08 KiB | 61 KiB/s, done.
Resolving deltas: 100% (756/756), done.
<a name="A4"></a>
<a name="install_gitolite"></a>
### install gitolite
@ -209,7 +209,7 @@ install mode that allows you to change the defaults etc.
----
<a name="A5"></a>
<a name="examine_what_you_have"></a>
### examine what you have

16
doc/9-gitolite-and-ssh.mkd
View file

@ -13,14 +13,14 @@ blaming ***git/gitolite*** for whatever is going wrong with your setup :-)
In this document:
* <a href="#A1">ssh basics</a>
* <a href="#A2">how does gitolite use all this ssh magic?</a>
* <a href="#A3">restricting shell access/distinguishing one user from another</a>
* <a href="#A4">restricting branch level actions</a>
* <a href="#ssh_basics">ssh basics</a>
* <a href="#how_does_gitolite_use_all_this_ssh_magic_">how does gitolite use all this ssh magic?</a>
* <a href="#restricting_shell_access_distinguishing_one_user_from_another">restricting shell access/distinguishing one user from another</a>
* <a href="#restricting_branch_level_actions">restricting branch level actions</a>
----
<a name="A1"></a>
<a name="ssh_basics"></a>
### ssh basics
@ -88,7 +88,7 @@ from somewhere, or maybe buy the OReilly ssh book.
**This is the backbone of what makes gitolite work; please make sure you
understand this**
<a name="A2"></a>
<a name="how_does_gitolite_use_all_this_ssh_magic_"></a>
### how does gitolite use all this ssh magic?
@ -98,7 +98,7 @@ These are two different questions you ought to be having by now:
logging in as the same remote user "git"
* how does it restrict what I can do within a repository
<a name="A3"></a>
<a name="restricting_shell_access_distinguishing_one_user_from_another"></a>
#### restricting shell access/distinguishing one user from another
@ -131,7 +131,7 @@ at its config file, and either allows or rejects the request.
But this cannot differentiate between different branches within a repo; that
has to be done separately.
<a name="A4"></a>
<a name="restricting_branch_level_actions"></a>
#### restricting branch level actions

32
doc/admin-defined-commands.mkd
View file

@ -11,18 +11,18 @@ There may be other such **WARNING** sections below. **Read all of them**.
In this document:
* <a href="#A1">background</a>
* <a href="#A2">setting it up</a>
* <a href="#A3">anatomy of a command</a>
* <a href="#A4">example uses and sample commands in contrib</a>
* <a href="#A5">fork</a>
* <a href="#A6">rmrepo</a>
* <a href="#A7">enable/disable push access temporarily</a>
* <a href="#A8">(bonus) restricted admin</a>
* <a href="#background">background</a>
* <a href="#setting_it_up">setting it up</a>
* <a href="#anatomy_of_a_command">anatomy of a command</a>
* <a href="#example_uses_and_sample_commands_in_contrib">example uses and sample commands in contrib</a>
* <a href="#fork">fork</a>
* <a href="#rmrepo">rmrepo</a>
* <a href="#enable_disable_push_access_temporarily">enable/disable push access temporarily</a>
* <a href="#bonus_restricted_admin">(bonus) restricted admin</a>
----
<a name="A1"></a>
<a name="background"></a>
### background
@ -62,7 +62,7 @@ What we want now is more than that, as you'll see in the examples below. And
I'm sure if you think of more uses you'll send them to me as "contrib"
entries, right?
<a name="A2"></a>
<a name="setting_it_up"></a>
### setting it up
@ -82,7 +82,7 @@ to inadvertently *hide* some of the "official" commands (like "info",
executable files with those names in this directory. So don't do that -- you
have been warned!**
<a name="A3"></a>
<a name="anatomy_of_a_command"></a>
### anatomy of a command
@ -137,11 +137,11 @@ convenient. See any of the other samples for how to use it.
If you don't like this, roll your own. If you don't like bash, do the eqvt in
your language of choice.
<a name="A4"></a>
<a name="example_uses_and_sample_commands_in_contrib"></a>
### example uses and sample commands in contrib
<a name="A5"></a>
<a name="fork"></a>
#### fork
@ -176,7 +176,7 @@ So now we have an actual command to just create a repo and do nothing else:
`ssh git@server git-init \'reponame\'`. [Yes; those single quotes are
required. Deal with it.]
<a name="A6"></a>
<a name="rmrepo"></a>
#### rmrepo
@ -188,7 +188,7 @@ Use it like this:
The script checks to make sure that the repo being deleted was *created* by
the user invoking it.
<a name="A7"></a>
<a name="enable_disable_push_access_temporarily"></a>
#### enable/disable push access temporarily
@ -226,7 +226,7 @@ in doc/2. You need code like this in `update.secondary` (don't forget to
exit 0
<a name="A8"></a>
<a name="bonus_restricted_admin"></a>
#### (bonus) restricted admin

20
doc/big-config.mkd
View file

@ -2,13 +2,13 @@
In this document:
* <a href="#A1">when/why do we need it?</a>
* <a href="#A2">how do we use it?</a>
* <a href="#A3">summary of settings in RC file</a>
* <a href="#A4">what are the downsides?</a>
* <a href="#A5">(extra coolness) usergroups and LDAP/similar tools</a>
* <a href="#when_why_do_we_need_it_">when/why do we need it?</a>
* <a href="#how_do_we_use_it_">how do we use it?</a>
* <a href="#summary_of_settings_in_RC_file">summary of settings in RC file</a>
* <a href="#what_are_the_downsides_">what are the downsides?</a>
* <a href="#extra_coolness_usergroups_and_LDAP_similar_tools">(extra coolness) usergroups and LDAP/similar tools</a>
<a name="A1"></a>
<a name="when_why_do_we_need_it_"></a>
### when/why do we need it?
@ -95,7 +95,7 @@ Phew!
You can imagine what that does when you have 10,000 users and 10,000 repos.
Let's just say it's not pretty :)
<a name="A2"></a>
<a name="how_do_we_use_it_"></a>
### how do we use it?
@ -142,7 +142,7 @@ configuration, the compiled file looks like this:
That's a lot smaller, and allows orders of magintude more repos and groups to
be supported.
<a name="A3"></a>
<a name="summary_of_settings_in_RC_file"></a>
### summary of settings in RC file
@ -162,7 +162,7 @@ you push the gitolite-admin repo with changes.
[gw]: http://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#gitweb
<a name="A4"></a>
<a name="what_are_the_downsides_"></a>
### what are the downsides?
@ -176,7 +176,7 @@ subset of the allowed @fragname, which would work normally, do not work now).
(If you didn't understand all that, you're probably not using delegation, so
feel free to ignore it!)
<a name="A5"></a>
<a name="extra_coolness_usergroups_and_LDAP_similar_tools"></a>
### (extra coolness) usergroups and LDAP/similar tools