s around - # "paragraphs" that are wrapped in non-block-level tags, such as anchors, - # phrase emphasis, and spans. The list of tags we're looking for is - # hard-coded: - my $block_tags_a = qr/p|div|h[1-6]|blockquote|pre|table|dl|ol|ul|script|noscript|form|fieldset|iframe|math|ins|del/; - my $block_tags_b = qr/p|div|h[1-6]|blockquote|pre|table|dl|ol|ul|script|noscript|form|fieldset|iframe|math/; - - # First, look for nested blocks, e.g.: - #
- #
- #
- # The outermost tags must start at the left margin for this to match, and
- # the inner nested divs must be indented.
- # We need to do this before the next, more liberal match, because the next
- # match will start at the first `
- # tags for inner block must be indented.
- #
- # ` and stop at the first `
`.
- $text =~ s{
- ( # save in $1
- ^ # start of line (with /m)
- <($block_tags_a) # start tag = $2
- \b # word break
- (.*\n)*? # any number of lines, minimally matching
- # the matching end tag
- [ \t]* # trailing spaces/tabs
- (?=\n+|\Z) # followed by a newline or end of document
- )
- }{
- my $key = md5_hex($1);
- $g_html_blocks{$key} = $1;
- "\n\n" . $key . "\n\n";
- }egmx;
-
-
- #
- # Now match more liberally, simply from `\n. It was easier to make a special case than - # to make the other regex more complicated. - $text =~ s{ - (?: - (?<=\n\n) # Starting after a blank line - | # or - \A\n? # the beginning of the doc - ) - ( # save in $1 - [ ]{0,$less_than_tab} - <(hr) # start tag = $2 - \b # word break - ([^<>])*? # - /?> # the matching end tag/ - [ \t]* - (?=\n{2,}|\Z) # followed by a blank line or end of document - ) - }{ - my $key = md5_hex($1); - $g_html_blocks{$key} = $1; - "\n\n" . $key . "\n\n"; - }egx; - - # Special case for standalone HTML comments: - $text =~ s{ - (?: - (?<=\n\n) # Starting after a blank line - | # or - \A\n? # the beginning of the doc - ) - ( # save in $1 - [ ]{0,$less_than_tab} - (?s: - - ) - [ \t]* - (?=\n{2,}|\Z) # followed by a blank line or end of document - ) - }{ - my $key = md5_hex($1); - $g_html_blocks{$key} = $1; - "\n\n" . $key . "\n\n"; - }egx; - - - return $text; -} - - -sub _RunBlockGamut { -# -# These are all the transformations that form block-level -# tags like paragraphs, headers, and list items. -# - my $text = shift; - - $text = _DoHeaders($text); - - # Do Horizontal Rules: - $text =~ s{^[ ]{0,2}([ ]?\*[ ]?){3,}[ \t]*$}{\n
tags.
-# my $tags_to_skip = qr!<(/?)(?:pre|code|kbd|script|math)[\s>]!;
-
- foreach my $cur_token (@$tokens) {
- if ($cur_token->[0] eq "tag") {
- # Within tags, encode * and _ so they don't conflict
- # with their use in Markdown for italics and strong.
- # We're replacing each such character with its
- # corresponding MD5 checksum value; this is likely
- # overkill, but it should prevent us from colliding
- # with the escape values by accident.
- $cur_token->[1] =~ s! \* !$g_escape_table{'*'}!gx;
- $cur_token->[1] =~ s! _ !$g_escape_table{'_'}!gx;
- $text .= $cur_token->[1];
- } else {
- my $t = $cur_token->[1];
- $t = _EncodeBackslashEscapes($t);
- $text .= $t;
- }
- }
- return $text;
-}
-
-
-sub _DoAnchors {
-#
-# Turn Markdown link shortcuts into XHTML tags.
-#
- my $text = shift;
-
- #
- # First, handle reference-style links: [link text] [id]
- #
- $text =~ s{
- ( # wrap whole match in $1
- \[
- ($g_nested_brackets) # link text = $2
- \]
-
- [ ]? # one optional space
- (?:\n[ ]*)? # one optional newline followed by spaces
-
- \[
- (.*?) # id = $3
- \]
- )
- }{
- my $result;
- my $whole_match = $1;
- my $link_text = $2;
- my $link_id = lc $3;
-
- if ($link_id eq "") {
- $link_id = lc $link_text; # for shortcut links like [this][].
- }
-
- if (defined $g_urls{$link_id}) {
- my $url = $g_urls{$link_id};
- $url =~ s! \* !$g_escape_table{'*'}!gx; # We've got to encode these to avoid
- $url =~ s! _ !$g_escape_table{'_'}!gx; # conflicting with italics/bold.
- $result = "? # href = $3
- [ \t]*
- ( # $4
- (['"]) # quote char = $5
- (.*?) # Title = $6
- \5 # matching quote
- )? # title is optional
- \)
- )
- }{
- my $result;
- my $whole_match = $1;
- my $link_text = $2;
- my $url = $3;
- my $title = $6;
-
- $url =~ s! \* !$g_escape_table{'*'}!gx; # We've got to encode these to avoid
- $url =~ s! _ !$g_escape_table{'_'}!gx; # conflicting with italics/bold.
- $result = " tags.
-#
- my $text = shift;
-
- #
- # First, handle reference-style labeled images: ![alt text][id]
- #
- $text =~ s{
- ( # wrap whole match in $1
- !\[
- (.*?) # alt text = $2
- \]
-
- [ ]? # one optional space
- (?:\n[ ]*)? # one optional newline followed by spaces
-
- \[
- (.*?) # id = $3
- \]
-
- )
- }{
- my $result;
- my $whole_match = $1;
- my $alt_text = $2;
- my $link_id = lc $3;
-
- if ($link_id eq "") {
- $link_id = lc $alt_text; # for shortcut links like ![this][].
- }
-
- $alt_text =~ s/"/"/g;
- if (defined $g_urls{$link_id}) {
- my $url = $g_urls{$link_id};
- $url =~ s! \* !$g_escape_table{'*'}!gx; # We've got to encode these to avoid
- $url =~ s! _ !$g_escape_table{'_'}!gx; # conflicting with italics/bold.
- $result = "![\"$alt_text\"";](\"$url\")
? # src url = $3
- [ \t]*
- ( # $4
- (['"]) # quote char = $5
- (.*?) # title = $6
- \5 # matching quote
- [ \t]*
- )? # title is optional
- \)
- )
- }{
- my $result;
- my $whole_match = $1;
- my $alt_text = $2;
- my $url = $3;
- my $title = '';
- if (defined($6)) {
- $title = $6;
- }
-
- $alt_text =~ s/"/"/g;
- $title =~ s/"/"/g;
- $url =~ s! \* !$g_escape_table{'*'}!gx; # We've got to encode these to avoid
- $url =~ s! _ !$g_escape_table{'_'}!gx; # conflicting with italics/bold.
- $result = "" . _RunSpanGamut($1) . "\n\n";
- }egmx;
-
- $text =~ s{ ^(.+)[ \t]*\n-+[ \t]*\n+ }{
- "" . _RunSpanGamut($1) . "
\n\n";
- }egmx;
-
-
- # atx-style headers:
- # # Header 1
- # ## Header 2
- # ## Header 2 with closing hashes ##
- # ...
- # ###### Header 6
- #
- $text =~ s{
- ^(\#{1,6}) # $1 = string of #'s
- [ \t]*
- (.+?) # $2 = Header text
- [ \t]*
- \#* # optional closing #'s (not counted)
- \n+
- }{
- my $h_level = length($1);
- "" . _RunSpanGamut($2) . " \n\n";
- }egmx;
-
- return $text;
-}
-
-
-sub _DoLists {
-#
-# Form HTML ordered (numbered) and unordered (bulleted) lists.
-#
- my $text = shift;
- my $less_than_tab = $g_tab_width - 1;
-
- # Re-usable patterns to match list item bullets and number markers:
- my $marker_ul = qr/[*+-]/;
- my $marker_ol = qr/\d+[.]/;
- my $marker_any = qr/(?:$marker_ul|$marker_ol)/;
-
- # Re-usable pattern to match any entirel ul or ol list:
- my $whole_list = qr{
- ( # $1 = whole list
- ( # $2
- [ ]{0,$less_than_tab}
- (${marker_any}) # $3 = first list item marker
- [ \t]+
- )
- (?s:.+?)
- ( # $4
- \z
- |
- \n{2,}
- (?=\S)
- (?! # Negative lookahead for another list item marker
- [ \t]*
- ${marker_any}[ \t]+
- )
- )
- )
- }mx;
-
- # We use a different prefix before nested lists than top-level lists.
- # See extended comment in _ProcessListItems().
- #
- # Note: There's a bit of duplication here. My original implementation
- # created a scalar regex pattern as the conditional result of the test on
- # $g_list_level, and then only ran the $text =~ s{...}{...}egmx
- # substitution once, using the scalar as the pattern. This worked,
- # everywhere except when running under MT on my hosting account at Pair
- # Networks. There, this caused all rebuilds to be killed by the reaper (or
- # perhaps they crashed, but that seems incredibly unlikely given that the
- # same script on the same server ran fine *except* under MT. I've spent
- # more time trying to figure out why this is happening than I'd like to
- # admit. My only guess, backed up by the fact that this workaround works,
- # is that Perl optimizes the substition when it can figure out that the
- # pattern will never change, and when this optimization isn't on, we run
- # afoul of the reaper. Thus, the slightly redundant code to that uses two
- # static s/// patterns rather than one conditional pattern.
-
- if ($g_list_level) {
- $text =~ s{
- ^
- $whole_list
- }{
- my $list = $1;
- my $list_type = ($3 =~ m/$marker_ul/) ? "ul" : "ol";
- # Turn double returns into triple returns, so that we can make a
- # paragraph for the last item in a list, if necessary:
- $list =~ s/\n{2,}(?! {8,})/\n\n\n/g;
- my $result = _ProcessListItems($list, $marker_any);
- $result = "<$list_type>\n" . $result . "\n";
- $result;
- }egmx;
- }
- else {
- $text =~ s{
- (?:(?<=\n\n)|\A\n?)
- $whole_list
- }{
- my $list = $1;
- my $list_type = ($3 =~ m/$marker_ul/) ? "ul" : "ol";
- # Turn double returns into triple returns, so that we can make a
- # paragraph for the last item in a list, if necessary:
- $list =~ s/\n{2,}(?! {8,})/\n\n\n/g;
- my $result = _ProcessListItems($list, $marker_any);
- $result = "<$list_type>\n" . $result . "\n";
- $result;
- }egmx;
- }
-
-
- return $text;
-}
-
-
-sub _ProcessListItems {
-#
-# Process the contents of a single ordered or unordered list, splitting it
-# into individual list items.
-#
-
- my $list_str = shift;
- my $marker_any = shift;
-
-
- # The $g_list_level global keeps track of when we're inside a list.
- # Each time we enter a list, we increment it; when we leave a list,
- # we decrement. If it's zero, we're not in a list anymore.
- #
- # We do this because when we're not inside a list, we want to treat
- # something like this:
- #
- # I recommend upgrading to version
- # 8. Oops, now this line is treated
- # as a sub-list.
- #
- # As a single paragraph, despite the fact that the second line starts
- # with a digit-period-space sequence.
- #
- # Whereas when we're inside a list (or sub-list), that line will be
- # treated as the start of a sub-list. What a kludge, huh? This is
- # an aspect of Markdown's syntax that's hard to parse perfectly
- # without resorting to mind-reading. Perhaps the solution is to
- # change the syntax rules such that sub-lists must start with a
- # starting cardinal number; e.g. "1." or "a.".
-
- $g_list_level++;
-
- # trim trailing blank lines:
- $list_str =~ s/\n{2,}\z/\n/;
-
-
- $list_str =~ s{
- (\n)? # leading line = $1
- (^[ \t]*) # leading whitespace = $2
- ($marker_any) [ \t]+ # list marker = $3
- ((?s:.+?) # list item text = $4
- (\n{1,2}))
- (?= \n* (\z | \2 ($marker_any) [ \t]+))
- }{
- my $item = $4;
- my $leading_line = $1;
- my $leading_space = $2;
-
- if ($leading_line or ($item =~ m/\n{2,}/)) {
- $item = _RunBlockGamut(_Outdent($item));
- }
- else {
- # Recursion for sub-lists:
- $item = _DoLists(_Outdent($item));
- chomp $item;
- $item = _RunSpanGamut($item);
- }
-
- "" . $item . " \n";
- }egmx;
-
- $g_list_level--;
- return $list_str;
-}
-
-
-
-sub _DoCodeBlocks {
-#
-# Process Markdown `` blocks.
-#
-
- my $text = shift;
-
- $text =~ s{
- (?:\n\n|\A)
- ( # $1 = the code block -- one or more lines, starting with a space/tab
- (?:
- (?:[ ]{$g_tab_width} | \t) # Lines must start with a tab or a tab-width of spaces
- .*\n+
- )+
- )
- ((?=^[ ]{0,$g_tab_width}\S)|\Z) # Lookahead for non-space at line-start, or end of doc
- }{
- my $codeblock = $1;
- my $result; # return value
-
- $codeblock = _EncodeCode(_Outdent($codeblock));
- $codeblock = _Detab($codeblock);
- $codeblock =~ s/\A\n+//; # trim leading newlines
- $codeblock =~ s/\s+\z//; # trim trailing whitespace
-
- $result = "\n\n" . $codeblock . "\n
\n\n";
-
- $result;
- }egmx;
-
- return $text;
-}
-
-
-sub _DoCodeSpans {
-#
-# * Backtick quotes are used for Just type foo `bar` baz at the prompt.
-#
-# There's no arbitrary limit to the number of backticks you
-# can use as delimters. If you need three consecutive backticks
-# in your code, use four for delimiters, etc.
-#
-# * You can use spaces to get literal backticks at the edges:
-#
-# ... type `` `bar` `` ...
-#
-# Turns to:
-#
-# ... type `bar` ...
-#
-
- my $text = shift;
-
- $text =~ s@
- (`+) # $1 = Opening run of `
- (.+?) # $2 = The code block
- (?$c";
- @egsx;
-
- return $text;
-}
-
-
-sub _EncodeCode {
-#
-# Encode/escape certain characters inside Markdown code runs.
-# The point is that in code, these characters are literals,
-# and lose their special Markdown meanings.
-#
- local $_ = shift;
-
- # Encode all ampersands; HTML entities are not
- # entities within a Markdown code span.
- s/&/&/g;
-
- # Encode $'s, but only if we're running under Blosxom.
- # (Blosxom interpolates Perl variables in article bodies.)
- {
- no warnings 'once';
- if (defined($blosxom::version)) {
- s/\$/$/g;
- }
- }
-
-
- # Do the angle bracket song and dance:
- s! < !<!gx;
- s! > !>!gx;
-
- # Now, escape characters that are magic in Markdown:
- s! \* !$g_escape_table{'*'}!gx;
- s! _ !$g_escape_table{'_'}!gx;
- s! { !$g_escape_table{'{'}!gx;
- s! } !$g_escape_table{'}'}!gx;
- s! \[ !$g_escape_table{'['}!gx;
- s! \] !$g_escape_table{']'}!gx;
- s! \\ !$g_escape_table{'\\'}!gx;
-
- return $_;
-}
-
-
-sub _DoItalicsAndBold {
- my $text = shift;
-
- # must go first:
- $text =~ s{ (\*\*|__) (?=\S) (.+?[*_]*) (?<=\S) \1 }
- {$2}gsx;
-
- $text =~ s{ (\*|_) (?=\S) (.+?) (?<=\S) \1 }
- {$2}gsx;
-
- return $text;
-}
-
-
-sub _DoBlockQuotes {
- my $text = shift;
-
- $text =~ s{
- ( # Wrap whole match in $1
- (
- ^[ \t]*>[ \t]? # '>' at the start of a line
- .+\n # rest of the first line
- (.+\n)* # subsequent consecutive lines
- \n* # blanks
- )+
- )
- }{
- my $bq = $1;
- $bq =~ s/^[ \t]*>[ \t]?//gm; # trim one level of quoting
- $bq =~ s/^[ \t]+$//mg; # trim whitespace-only lines
- $bq = _RunBlockGamut($bq); # recurse
-
- $bq =~ s/^/ /g;
- # These leading spaces screw with content, so we need to fix that:
- $bq =~ s{
- (\s*.+?
)
- }{
- my $pre = $1;
- $pre =~ s/^ //mg;
- $pre;
- }egsx;
-
- "\n$bq\n
\n\n";
- }egmx;
-
-
- return $text;
-}
-
-
-sub _FormParagraphs {
-#
-# Params:
-# $text - string to process with html tags
-#
- my $text = shift;
-
- # Strip leading and trailing lines:
- $text =~ s/\A\n+//;
- $text =~ s/\n+\z//;
-
- my @grafs = split(/\n{2,}/, $text);
-
- #
- # Wrap
tags.
- #
- foreach (@grafs) {
- unless (defined( $g_html_blocks{$_} )) {
- $_ = _RunSpanGamut($_);
- s/^([ \t]*)/
/;
- $_ .= "
";
- }
- }
-
- #
- # Unhashify HTML blocks
- #
- foreach (@grafs) {
- if (defined( $g_html_blocks{$_} )) {
- $_ = $g_html_blocks{$_};
- }
- }
-
- return join "\n\n", @grafs;
-}
-
-
-sub _EncodeAmpsAndAngles {
-# Smart processing for ampersands and angle brackets that need to be encoded.
-
- my $text = shift;
-
- # Ampersand-encoding based entirely on Nat Irons's Amputator MT plugin:
- # http://bumppo.net/projects/amputator/
- $text =~ s/&(?!#?[xX]?(?:[0-9a-fA-F]+|\w+);)/&/g;
-
- # Encode naked <'s
- $text =~ s{<(?![a-z/?\$!])}{<}gi;
-
- return $text;
-}
-
-
-sub _EncodeBackslashEscapes {
-#
-# Parameter: String.
-# Returns: The string, with after processing the following backslash
-# escape sequences.
-#
- local $_ = shift;
-
- s! \\\\ !$g_escape_table{'\\'}!gx; # Must process escaped backslashes first.
- s! \\` !$g_escape_table{'`'}!gx;
- s! \\\* !$g_escape_table{'*'}!gx;
- s! \\_ !$g_escape_table{'_'}!gx;
- s! \\\{ !$g_escape_table{'{'}!gx;
- s! \\\} !$g_escape_table{'}'}!gx;
- s! \\\[ !$g_escape_table{'['}!gx;
- s! \\\] !$g_escape_table{']'}!gx;
- s! \\\( !$g_escape_table{'('}!gx;
- s! \\\) !$g_escape_table{')'}!gx;
- s! \\> !$g_escape_table{'>'}!gx;
- s! \\\# !$g_escape_table{'#'}!gx;
- s! \\\+ !$g_escape_table{'+'}!gx;
- s! \\\- !$g_escape_table{'-'}!gx;
- s! \\\. !$g_escape_table{'.'}!gx;
- s{ \\! }{$g_escape_table{'!'}}gx;
-
- return $_;
-}
-
-
-sub _DoAutoLinks {
- my $text = shift;
-
- $text =~ s{<((https?|ftp):[^'">\s]+)>}{$1}gi;
-
- # Email addresses:
- $text =~ s{
- <
- (?:mailto:)?
- (
- [-.\w]+
- \@
- [-a-z0-9]+(\.[-a-z0-9]+)*\.[a-z]+
- )
- >
- }{
- _EncodeEmailAddress( _UnescapeSpecialChars($1) );
- }egix;
-
- return $text;
-}
-
-
-sub _EncodeEmailAddress {
-#
-# Input: an email address, e.g. "foo@example.com"
-#
-# Output: the email address as a mailto link, with each character
-# of the address encoded as either a decimal or hex entity, in
-# the hopes of foiling most address harvesting spam bots. E.g.:
-#
-# foo
-# @example.com
-#
-# Based on a filter by Matthew Wickline, posted to the BBEdit-Talk
-# mailing list:
-#
-
- my $addr = shift;
-
- srand;
- my @encode = (
- sub { '&#' . ord(shift) . ';' },
- sub { '&#x' . sprintf( "%X", ord(shift) ) . ';' },
- sub { shift },
- );
-
- $addr = "mailto:" . $addr;
-
- $addr =~ s{(.)}{
- my $char = $1;
- if ( $char eq '@' ) {
- # this *must* be encoded. I insist.
- $char = $encode[int rand 1]->($char);
- } elsif ( $char ne ':' ) {
- # leave ':' alone (to spot mailto: later)
- my $r = rand;
- # roughly 10% raw, 45% hex, 45% dec
- $char = (
- $r > .9 ? $encode[2]->($char) :
- $r < .45 ? $encode[1]->($char) :
- $encode[0]->($char)
- );
- }
- $char;
- }gex;
-
- $addr = qq{$addr};
- $addr =~ s{">.+?:}{">}; # strip the mailto: from the visible part
-
- return $addr;
-}
-
-
-sub _UnescapeSpecialChars {
-#
-# Swap back in all the special characters we've hidden.
-#
- my $text = shift;
-
- while( my($char, $hash) = each(%g_escape_table) ) {
- $text =~ s/$hash/$char/g;
- }
- return $text;
-}
-
-
-sub _TokenizeHTML {
-#
-# Parameter: String containing HTML markup.
-# Returns: Reference to an array of the tokens comprising the input
-# string. Each token is either a tag (possibly with nested,
-# tags contained therein, such as , or a
-# run of text between tags. Each element of the array is a
-# two-element array; the first is either 'tag' or 'text';
-# the second is the actual value.
-#
-#
-# Derived from the _tokenize() subroutine from Brad Choate's MTRegex plugin.
-#
-#
-
- my $str = shift;
- my $pos = 0;
- my $len = length $str;
- my @tokens;
-
- my $depth = 6;
- my $nested_tags = join('|', ('(?:<[a-z/!$](?:[^<>]') x $depth) . (')*>)' x $depth);
- my $match = qr/(?s: ) | # comment
- (?s: <\? .*? \?> ) | # processing instruction
- $nested_tags/ix; # nested tags
-
- while ($str =~ m/($match)/g) {
- my $whole_tag = $1;
- my $sec_start = pos $str;
- my $tag_start = $sec_start - length $whole_tag;
- if ($pos < $tag_start) {
- push @tokens, ['text', substr($str, $pos, $tag_start - $pos)];
- }
- push @tokens, ['tag', $whole_tag];
- $pos = pos $str;
- }
- push @tokens, ['text', substr($str, $pos, $len - $pos)] if $pos < $len;
- \@tokens;
-}
-
-
-sub _Outdent {
-#
-# Remove one level of line-leading tabs or spaces
-#
- my $text = shift;
-
- $text =~ s/^(\t|[ ]{1,$g_tab_width})//gm;
- return $text;
-}
-
-
-sub _Detab {
-#
-# Cribbed from a post by Bart Lateur:
-#
-#
- my $text = shift;
-
- $text =~ s{(.*?)\t}{$1.(' ' x ($g_tab_width - length($1) % $g_tab_width))}ge;
- return $text;
-}
-
-
-1;
-
-__END__
-
-
-=pod
-
-=head1 NAME
-
-B
-
-
-=head1 SYNOPSIS
-
-B [ B<--html4tags> ] [ B<--version> ] [ B<-shortversion> ]
- [ I ... ]
-
-
-=head1 DESCRIPTION
-
-Markdown is a text-to-HTML filter; it translates an easy-to-read /
-easy-to-write structured text format into HTML. Markdown's text format
-is most similar to that of plain text email, and supports features such
-as headers, *emphasis*, code blocks, blockquotes, and links.
-
-Markdown's syntax is designed not as a generic markup language, but
-specifically to serve as a front-end to (X)HTML. You can use span-level
-HTML tags anywhere in a Markdown document, and you can use block level
-HTML tags (like and as well).
-
-For more information about Markdown's syntax, see:
-
- http://daringfireball.net/projects/markdown/
-
-
-=head1 OPTIONS
-
-Use "--" to end switch parsing. For example, to open a file named "-z", use:
-
- Markdown.pl -- -z
-
-=over 4
-
-
-=item B<--html4tags>
-
-Use HTML 4 style for empty element tags, e.g.:
-
-
-
-instead of Markdown's default XHTML style tags, e.g.:
-
-
-
-
-=item B<-v>, B<--version>
-
-Display Markdown's version number and copyright information.
-
-
-=item B<-s>, B<--shortversion>
-
-Display the short-form version number.
-
-
-=back
-
-
-
-=head1 BUGS
-
-To file bug reports or feature requests (other than topics listed in the
-Caveats section above) please send email to:
-
- support@daringfireball.net
-
-Please include with your report: (1) the example input; (2) the output
-you expected; (3) the output Markdown actually produced.
-
-
-=head1 VERSION HISTORY
-
-See the readme file for detailed release notes for this version.
-
-1.0.1 - 14 Dec 2004
-
-1.0 - 28 Aug 2004
-
-
-=head1 AUTHOR
-
- John Gruber
- http://daringfireball.net
-
- PHP port and other contributions by Michel Fortin
- http://michelf.com
-
-
-=head1 COPYRIGHT AND LICENSE
-
-Copyright (c) 2003-2004 John Gruber
-.pub duplicates a non-gitolite key, sshd will ignore it`
-
- You used a key that is already set to give you shell access. You cannot
- use the same key to get shell access as well as access gitolite repos.
-
- Solution: use a different keypair for gitolite. There's a slightly longer
- discussion in the [setup][] page. Also see [why bypassing causes a
- problem][ybpfail] and both the documents in [ssh][] for background.
-
- * `Empty compile time value given to use lib at hooks/update line 6`
-
- (followed by `Can't locate Gitolite/Hooks/Update.pm in @INC` a couple of
- lines later).
-
- You're bypassing gitolite. You cloned the repo using the full path (i.e.,
- including the `repositories/` prefix), either directly on the server, or
- via ssh but with a key that gives you **shell** access.
-
- Solution: same as for the previous bullet.
-
- NOTE: If you really *must* do it, and this is a one-time thing, you can
- try `gitolite push` instead of `git push`. **BUT**... this defeats all
- gitolite access control, so if you're going to do this often, maybe you
- don't need gitolite!
-
-## #ue uncommon errors
-
- * `WARNING: split conf not set, gl-conf present for `
-
- (Case 1) you copied a bare repo ("repo.git") from another g3 site (or g2
- with `GL_BIG_CONFIG` on). Then you pushed a change to "gitolite.conf" or
- ran certain server-side commands without adding the repo to the conf.
-
- Conversely, you removed "repo" from "gitolite.conf" but did not remove the
- actual "repo.git" on disk.
-
- (Case 2) This can also happen if you changed something like this
-
- repo foo
- ......
-
- to this
-
- @grp = foo
- repo @grp
- ......
-
- Also, even running `gitolite setup` will not fix this.
-
- The root cause is an internal consistency check that I do not wish to
- disable or subvert. It is there for a reason, and I would prefer a
- warning that a human can investigate.
-
- If you're sure the reasons are one of the two above, you can either add
- the repo to the conf file in case 1, or manually remove the gl-conf file
- from the repo.git directory in case 2.
-
- Either way, run `gitolite setup` afterwards to make sure things are in
- good shape.
-
- If you think neither of those is the cause, email me.
-
-## #ngp things that are not gitolite problems
-
-There are several things that appear to be gitolite problems but are not. I
-cannot help with most of these (although the good folks on irc or the mailing
-list -- see [contact][] -- might be able to; they certainly appear to have a
-lot more patience than I do, bless 'em!)
-
- * **Client side software**
-
- * putty/plink
- * jgit/Eclipse
- * Mac OS client **or** server
- * putty/plink
- * windows as a server
- * ...probably some more I forgot; will update this list as I remember...
- * did I mention putty/plink?
-
- * **Ssh**
-
- The *superstar* of the "not a gitolite problem" category is actually ssh.
-
- Surprised? It is so common that it has [its own document][auth] to tell
- you why it is *not* a gitolite problem, while [another one][ssh] tries to
- help you anyway!
-
- Everything I know is in that latter link. Please email me about ssh ONLY
- if you find something wrong or missing in those documents.
-
- * **Git**
-
- I wish I had a dollar for each time someone did a *first push* on a new
- repo, got an error because there were "no refs in common (etc.)", and
- asked me why gitolite was not allowing the push.
-
- Gitolite is designed to look like just another bare repo server to a
- client (except requiring public keys -- no passwords allowed). It is
- *completely transparent* when there is no authorisation failure (i.e.,
- when the access is allowed, the remote client has no way of knowing
- gitolite was even installed!)
-
- Even "on disk", apart from reserving the `update` hook for itself,
- gitolite does nothing to your bare repos unless you tell it to (for
- example, adding 'gitweb.owner' and such to the config file).
-
- BEFORE you think gitolite is the problem, try the same thing with a normal
- bare repo. In most cases you can play with it just by doing something
- like this:
-
- mkdir /tmp/throwaway
- cd /tmp/throwaway
- git clone --mirror bare.git
- git clone bare.git worktree
- cd worktree
- <...try stuff>
diff --git a/doc/external.mkd b/doc/external.mkd
deleted file mode 100644
index 45d19a7..0000000
--- a/doc/external.mkd
+++ /dev/null
@@ -1,71 +0,0 @@
-# interfacing with external tools
-
-> ----
-
-> **Note**: The old gitolite (v1.x, v2.x) used to tie itself into knots
-> dealing with gitweb and daemon. One of the goals of g3 was to get out of
-> that game, which your author does not play anyway. This means statements
-> like "...special user called 'gitweb'..." really apply to the [non-core][]
-> programs that gitolite ships with, not to "core" gitolite, and any or all
-> of this functionality can be disabled by commenting out certain lines in
-> the [rc][] file.
-
-> ----
-
-> Also, **note** that gitolite does **not** install or configure
-> gitweb/git-daemon -- that is a one-time setup you must do separately.
-
-> ----
-
-## gitweb
-
-The following repos are deemed to be readable by gitweb:
-
- * any repos readable by the special user `gitweb`
- * any repos containing one or more of the following types of lines:
-
- config gitweb.owner = owner name
- config gitweb.description = some description
- config gitweb.category = some category
-
- Side note: the following shorter forms are available as [syntactic
- sugar][sugar] for the above longer forms:
-
- owner = owner name
- desc = some description
- category = some category
-
-The list of gitweb-readable repos is written to a file whose name is given by
-the [rc][] file variable `GITWEB_PROJECTS_LIST`. The default value of this
-variable, if it is not specified or empty, is `$HOME/projects.list`.
-
-In addition, each of the config variables described above is written to the
-repo to which it pertains, so that gitweb can use them.
-
-### #umask changing the UMASK
-
-Gitweb typically runs under a different userid, and the default permissions
-that gitolite sets make them unreadable.
-
-See the section on the `UMASK` variable in the documentation for the [rc
-file][rc].
-
-## git-daemon
-
-Any repo readable by the special user `daemon` is deemed to be readable by
-git-daemon. For each of these repos, an empty file called
-`git-daemon-export-ok` is created in the repository (i.e., the `repo.git`
-directory inside `$HOME/repositories`).
-
-## tips
-
-Setting descriptions en-masse usually does not make sense, but you can
-certainly do things like
-
- repo @all
- R = gitweb daemon
-
-assuming you have other means of setting 'gitweb.description' and
-'gitweb.owner'.
-
-Also see [this][deny-rules] for a twist on that.
diff --git a/doc/extras/auth.mkd b/doc/extras/auth.mkd
deleted file mode 100644
index 1b88a6a..0000000
--- a/doc/extras/auth.mkd
+++ /dev/null
@@ -1,106 +0,0 @@
-# authentication versus authorisation
-
-This document will explain why an "ssh issue" is almost never a "gitolite
-issue", and, indirectly, why I dont get too excited about the former.
-
-Note: for actual ssh troubleshooting see [this][sts].
-
-Here is a fundamental point: **Gitolite does not do
-authentication. It only does authorisation**.
-
-So first, let's loosely define these words:
-
-> **Authentication** is the process of verifying that you are who you claim
-> to be. An authentication system will establish that I am the user
-> "sitaram" on my work system. The one behind gmail will similarly
-> establish that I am "sitaramc". And so on...
-
-> **Authorisation** is the process of asking what you want to do and
-> deciding if you're allowed to do it or not.
-
-Now, if you managed to read about [gitolite and ssh][glssh], you
-know that gitolite is meant to be invoked as:
-
- /full/path/to/gitolite-shell some-authenticated-gitolite-username
-
-(where the "gitolite username" is a "virtual" username; it does not have to
-be, and usually *isn't*, an actual *unix* username).
-
-As you can see, authentication happens before gitolite is called.
-
-## but... but... you have all that ssh stuff in gitolite!
-
-No I don't. Not in "core" gitolite from g3 onwards :-)
-
-The default setup does use ssh keys, but it's only helping you **setup**
-ssh-based authentication **as a convenience to you**. But in fact it is a
-*completely* separate program that you can disable (in the rc file) or replace
-with something else of your choice.
-
-For example, in both [smart http][http] and ldap-backed sshd, gitolite has no
-role to play in creating users, setting up their passwords/keys, etc.
-
-## so you're basically saying you won't support "X"
-
-(where "X" is some ssh related behaviour change or feature)
-
-Well, if it's not a security issue I won't. But since it's no longer part of
-"core" gitolite, I can be much more relaxed about taking patches, or even
-alternative implementations.
-
-While we're on the subject, locking someone out is *not* a security issue.
-Even if you [lost the admin key][lost-key], the docs tell you how to recover
-from such errors. You do need some password based method to get a shell
-command line on the server, of course.
-
-## #otherauth how to use other authentication systems with gitolite
-
-The bottom line in terms of how to invoke gitolite has been described above,
-and as long as you manage to do that gitolite won't even know how the
-authentication was done. Which in turn means you can use whatever
-authentication scheme you want.
-
-It also expects the `SSH_ORIGINAL_COMMAND` environment variable to contain the
-full command (typically starting with git-receive-pack or git-upload-pack)
-that the client sent. Also, when using [smart http][http], things are somewhat
-different: gitolite uses certain environment variables that it expects httpd
-to have set up. Even the user name comes from the `REMOTE_USER` environment
-variable instead of as a command line argument in this case.
-
-However, it has to be an authentication system that is compatible with sshd or
-httpd in some form. Why? Because the git *client* accessing the server only
-knows those 2 protocols to "speak git". (Well, the `git://` protocol is
-unauthenticated, and `file://` doesn't really apply to this discussion, so
-we're ignoring those).
-
-For example, let's say you have an LDAP-based authentication system somewhere.
-It is possible to make apache use that to authenticate users, so when a user
-accesses a git url using `http://sitaram:password@git.example.com/repo`, it is
-LDAP that does the actual authentication. [I wouldn't know how to do it but I
-know it is possible. Patches to this doc explaining how are welcome!]
-
-There are also ssh daemons that use LDAP to store the authorised keys (instead
-of putting them all in `~/.ssh/authorized_keys`). The clients will still need
-to generate keypairs and send them to the admin, but they can be more
-centrally stored and perhaps used by other programs or tools simultaneously,
-which can be useful.
-
-## #ldap getting user group info from LDAP
-
-Gitolite's [groups][] are pretty convenient, but some organisations already
-have similar (or sufficient) information in their LDAP store.
-
-Gitolite can tap into that information, with a little help. Write a program
-which, given a username, queries your LDAP store and returns a space-separated
-list of groups that the user is a member of. Then put the full path to this
-program in an [rc][] variable called `GROUPLIST_PGM`, like so:
-
- GROUPLIST_PGM => '/home/git/bin/ldap-query-groups',
-
-Now you can use those groupnames in access rules in gitolite, just as if you
-had declared their memberships in the conf file.
-
-Caution: your program must do its own logging if you want the audit trail of
-"why/how did this user get access to this repo at this time?" to resolve
-properly. Gitolite does not do any logging of the results of the queries
-because for people who don't need it that would be a huge waste.
diff --git a/doc/extras/glssh.mkd b/doc/extras/glssh.mkd
deleted file mode 100644
index f25bc13..0000000
--- a/doc/extras/glssh.mkd
+++ /dev/null
@@ -1,149 +0,0 @@
-# #glssh how gitolite uses ssh
-
-[[TOC]]
-
-----
-
-Although other forms of authentications exist (see the document on
-[authentication versus authorisation][auth]), ssh is the one that most git
-users use.
-
-***Therefore, gitolite is (usually) heavily dependent on ssh***.
-
-Most people didn't realise this, and even if they did they don't know ssh
-well enough to help themselves. If you don't understand how ssh public key
-authentication works, or how the `~/.ssh/authorized_keys` file can be used to
-restrict users, etc., you will have endless amounts of trouble getting
-gitolite to work, because you'll be attacking the wrong problem.
-
-So please please please understand this before tearing your hair out and
-blaming ***git/gitolite*** for whatever is going wrong with your setup :-)
-
-## ssh basics
-
-Let's start with some basics, focusing *only* on the pieces relevant to
-`gitolite`. If this is not detailed enough, please use google and learn more
-from somewhere, or maybe buy the OReilly ssh book.
-
- * You can login to an ssh server by typing a password, but ssh can also use
- ***public-private keys*** (also called "key pairs") for authentication.
- `gitolite` *requires* you to use this mechanism for your users -- they
- cannot log in using passwords. Hopefully by the time you finish reading
- this document you will understand why :-)
-
- The way you set this up is you generate a key pair on your workstation,
- and give the server the public key. (I need not add that the "private"
- key must be, well, kept *private*!)
-
- * **Generating a key pair on your workstation** is done by running the
- command `ssh-keygen -t rsa`. This produces two files in `~/.ssh`. One is
- `id_rsa`; this is the **private** key -- ***never*** let it out of your
- machine. The other is `id_rsa.pub`, which is the corresponding public
- key. This public key is usually just one long line of text.
-
- * On Windows machines with msysgit installed, you should do this from
- within a "git bash" window. The command will report the full path where
- the files have been written; make a note of this, and use those files in
- any of the description that follows.
-
- * **Adding your public key to the server**'s `~/.ssh/authorized_keys`
- file is how ssh uses pubkeys to authenticate users. Let's say
- sita@work.station is trying to log in as git@serv.er. What you have to do
- is take the `~/.ssh/id_rsa.pub` file for user sita on work.station and
- append its contents (remember it's only one line) to
- `~/.ssh/authorized_keys` for user git on serv.er.
-
- The `authorized_keys` file can have multiple public keys (from many
- different people) added to it so any of them can log in to git@serv.er.
-
- In the normal case (not gitolite, but your normal everyday shell access),
- there's a command that does this, `ssh-copy-id`, which also fixes up
- permissions etc., as needed, since sshd is a little picky about allowing
- pubkey access if permissions on the server are loose. Or you can do it
- manually, as long as you know what you're doing and you're careful not to
- erase or overwrite the existing contents of `~/.ssh/authorized_keys` on
- the server!
-
- But in the gitolite case, it's different; we'll get to that in a minute.
-
- * **Troubleshooting pubkey authentication failures**: if you are unable to
- get ssh access to the server after doing all this, you'll have to look
- in `/var/log/secure` or `/var/log/auth.log` or some such file on the
- server to see what specific error `sshd` is complaining about.
-
- * **Restricting users to specific commands** is very important for gitolite.
- If you read `man sshd` and look for `authorized_keys file format`, you'll
- see a lot of options you can add to the public key line, which restrict
- the incoming user in various ways. In particular, note the `command=`
- option, which means "regardless of what the incoming user is asking to do,
- forcibly run this command instead".
-
- Also note that when there are many public keys (i.e., lines) in the
- `authorized_keys` file, each line can have a *different* set of options
- and `command=` values.
-
- Without this `command=` option, the ssh daemon will simply give you a
- shell, which is not what we want for our gitolite keys (although we may
- well have other keys which we use to get a shell).
-
- **This is the backbone of what makes gitolite work; please make sure you
- understand this**.
-
-## how does gitolite use all this ssh magic?
-
-These are two different questions you ought to be having by now:
-
- * How does it distinguish between me and someone else, since we're all
- logging in as the same remote user "git".
- * How does it restrict what I can do within a repository.
-
-### restricting shell access/distinguishing one user from another
-
-The answer to the first question is the `command=` we talked about before. If
-you look in the `authorized_keys` file, you'll see entries like this (I chopped
-off the ends of course; they're pretty long lines):
-
- command="[path]/gitolite-shell sitaram",[more options] ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEA18S2t...
- command="[path]/gitolite-shell usertwo",[more options] ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEArXtCT...
-
-First, it finds out which of the public keys in this file match the incoming
-login. That's crypto stuff, and I won't go into it. Once the match has been
-found, it will run the command given on that line; e.g., if I logged in, it
-would run `[path]/gitolite-shell sitaram`. So the first thing to note is
-that such users do not get "shell access", which is good!
-
-Before running the command, however, sshd sets up an environment variable
-called `SSH_ORIGINAL_COMMAND` which contains the actual git command that your
-workstation sent out. This is the command that *would have run* if you did
-not have the `command=` part in the authorised keys file.
-
-When `gitolite-shell` gets control, it looks at the first argument
-("sitaram", "usertwo", etc) to determine who you are. It then looks at the
-`SSH_ORIGINAL_COMMAND` variable to find out which repository you want to
-access, and whether you're reading or writing.
-
-Now that it has a user, repository, and access requested (read/write), gitolite looks
-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.
-
-### restricting branch level actions
-
-[If you look inside the git source tree, there's a file among the "howto"s in
-there called `update-hook-example.txt`, which was the inspiration for this
-part of gitolite.]
-
-Git allows you to specify many "hooks", which get control as various events
-happen -- see `git help hooks` for details. One of those hooks is the
-`update` hook, which, if it is present, is invoked just before a branch or a
-tag is about to be updated. The hook is passed the name of the branch or tag,
-the old SHA1 value, and the new SHA1 value, as arguments. Hooks that are
-called *before* an action happens are allowed to prevent that action from
-happening by returning an error code.
-
-When gitolite is told to create a new repository (by the admin), it installs
-a special update hook. This hook takes all the information presented, looks
-at the config file, and decides to allow or reject the update.
-
-And that's basically it.
diff --git a/doc/extras/putty.mkd b/doc/extras/putty.mkd
deleted file mode 100644
index 5a4ff56..0000000
--- a/doc/extras/putty.mkd
+++ /dev/null
@@ -1,203 +0,0 @@
-# putty and msysgit
-
-This document is intended for those who wish to use Putty/Plink with msysgit.
-
-If you need more help with putty or component programs I suggest looking at [the official putty documentation](http://the.earth.li/~sgtatham/putty/latest/htmldoc/).
-
-**If you are not already using Putty for SSH it is recommended you do _NOT_ use it with msysgit.**
-
-**Please note that this only covers the client side of things, and does not involve server side components to troubleshooting. For that, please see the [ssh-troubleshooting document][sts].**
-
-
-
-## msysgit setup
-
-Provided you have putty sessions msysgit should give you the option of specifying a location to plink. If it did not then you will need to add an environment variable named "GIT\_SSH" to point at plink.exe, wherever you have that sitting.
-
-How to do that on your version of windows will likely vary, and is not covered here. For purposes of example, on a 64 bit Windows Vista machine the GIT\_SSH value could be:
-
- C:\Program Files (x86)\PuTTY\plink.exe
-
-Note the lack of quotes.
-
-Testing that msysgit is properly configured can be done from the git bash shell. Simply type (case sensitive, include the quotes):
-
- "$GIT_SSH" -V
-
-You should get a response similar to this:
-
- plink: Release 0.60
-
-If instead you get a "command not found" type error you likely have a typo in your environment variable.
-
-
-
-## Going back to OpenSSH
-
-If you wish to go back to OpenSSH all you need to do is delete the GIT\_SSH environment variable. This will vary by your version of windows and thus is not covered here.
-
-
-
-## Putty keys
-
-If you do not already have putty private key files (.ppk) you will need to make at least one. You can either make a new one or convert an existing key to putty private key format.
-
-Either way, you will want to use puttygen. Note that you can go the other way if you want to stop using putty but keep the key by exporting the key to OpenSSH format.
-
-
-
-### Creating a new key
-
-To make it simple, I suggest SSH-2 RSA and a bit size of at least 1024. Larger keys will take longer to generate and will take longer to authenticate you on most systems. Making the key is as simple at hitting "Generate".
-
-It is recommended to give the key a meaningful comment.
-
-
-
-### Importing an existing key
-
-If you already have an OpenSSH or ssh.com key you can import it using the "Import" option on the "Conversions" menu.
-
-If the key does not have a meaningful comment I would suggest adding one at this point.
-
-
-
-### Loading an existing key
-
-If you need to load an existing key to edit or view it you can do so from the File menu.
-
-
-
-### Public key
-
-To get your public key for use with gitolite, load (or generate, or import) your key into puttygen. There is a box labeled "Public key for pasting into OpenSSH `authorized_keys` file" there. Copy the text into your preferred text editor and save.
-
-
-
-### Putty ageant
-
-Though not required in all cases you may wish to use the putty ageant, pageant, to load your key(s). This will allow for your key(s) to be passphrase protected but not have to enter the passphrase when you go to use them, provided you have already loaded the key into the ageant.
-
-
-
-## Sessionless or raw hostname usage
-
-When using plink without a putty session you pretty much have to load your keys with putty ageant, if only so that plink can find them.
-
-
-
-## Putty sessions
-
-In addition to hostnames msysgit can, when using putty, use putty sessions. This works in a manner similar to definitions in OpenSSH's `ssh_config` file. All settings in the session that apply to plink usage will be loaded, including the key file to use and even the username to connect to. Thus, instead of:
-
- ssh://user@host.example.ext:port/repo
-
-You can use:
-
- ssh://session_name/repo
-
-
-
-## Host key authentication
-
-Whether you are using hostnames or sessions you still run into one potential problem. Plink currently wants to validate the server's SSH host key before allowing you to connect, and when git calls plink there is no way to tell it yes. Thus, you may get something like this:
-
- The server's host key is not cached in the registry. You
- have no guarantee that the server is the computer you
- think it is.
- The server's rsa2 key fingerprint is:
- ssh-rsa 2048 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00
- Connection abandoned.
- fatal: The remote end hung up unexpectedly
-
-Or, in the case of the host key changing, something like this:
-
- WARNING - POTENTIAL SECURITY BREACH!
- The server's host key does not match the one PuTTY has
- cached in the registry. This means that either the
- server administrator has changed the host key, or you
- have actually connected to another computer pretending
- to be the server.
- The new rsa2 key fingerprint is:
- ssh-rsa 2048 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00
- Connection abandoned.
- fatal: The remote end hung up unexpectedly
-
-The solution is to call plink directly, or start putty and connect with it first. To use plink, open the Git Bash shell and enter:
-
- "$GIT_SSH" hostname_or_session_name
-
-When you do you will see something like this:
-
- The server's host key is not cached in the registry. You
- have no guarantee that the server is the computer you
- think it is.
- The server's rsa2 key fingerprint is:
- ssh-rsa 2048 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00
- If you trust this host, enter "y" to add the key to
- PuTTY's cache and carry on connecting.
- If you want to carry on connecting just once, without
- adding the key to the cache, enter "n".
- If you do not trust this host, press Return to abandon the
- connection.
- Store key in cache? (y/n)
-
-Or, in the case of a changed key, a response like this:
-
- WARNING - POTENTIAL SECURITY BREACH!
- The server's host key does not match the one PuTTY has
- cached in the registry. This means that either the
- server administrator has changed the host key, or you
- have actually connected to another computer pretending
- to be the server.
- The new rsa2 key fingerprint is:
- ssh-rsa 2048 00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00
- If you were expecting this change and trust the new key,
- enter "y" to update PuTTY's cache and continue connecting.
- If you want to carry on connecting but without updating
- the cache, enter "n".
- If you want to abandon the connection completely, press
- Return to cancel. Pressing Return is the ONLY guaranteed
- safe choice.
- Update cached key? (y/n, Return cancels connection)
-
-In either case hit y and the key will be stored.
-
-
-
-## Debugging multiple putty ageant keys
-
-In the event you are using putty ageant with multiple keys loaded you may see the wrong key being used. In general, pageant keys are tried in the order they were loaded into the ageant. If you have descriptive comment on each of your keys you can try connecting with plink in verbose mode to see what keys are being tried. Simply open the Git bash shell and run:
-
- "$GIT_SSH" -v user@hostname
-
-Or, if using sessions with a pre-entered username:
-
- "$GIT_SSH" -v session_name
-
-In either case, you should look for lines like:
-
- Trying Pageant key #0
- Authenticating with public key "My Key" from agent
-
-The first says which (numerical) key the ageant is trying. The second tells you the key comment for the authenticating key. To my knowledge the second line should only show up once, for the valid key.
-
-
-
-## Setperms and other commands
-
-When using wildcard repos the setperms command is very important, and other commands can come in handy as well. See their documentation for how to use them, but where they use:
-
- ssh user@host command etc etc
-
-You will want to use:
-
- "$GIT_SSH" user@host command etc etc
-
-Otherwise everything should be identical.
-
-
-
-## About this document
-
-This document was written by Thomas Berezansky (tsbere (at) mvlc (dot) org) in the hopes that it would be useful to those using putty on windows and wishing to use git/gitolite with their putty keys and sessions.
diff --git a/doc/extras/regex.mkd b/doc/extras/regex.mkd
deleted file mode 100644
index c334c2c..0000000
--- a/doc/extras/regex.mkd
+++ /dev/null
@@ -1,34 +0,0 @@
-# extremely brief regex overview
-
-Regexes are powerful. Gitolite uses that power as much as it can. If you
-can't handle that power, hire someone who can and become a manager.
-
-That said, here's a very quick overview of the highlights.
-
-`^` and `$` are called "anchors". They anchor the match to the beginning and
-end of the string respectively.
-
- ^foo matches any string starting with 'foo'
- foo$ matches any string ending with 'foo'
- ^foo$ matches exact string 'foo'.
-
-To be precise, the last one is "any string starting and ending with *the same*
-'foo'". "foofoo" does not match.
-
-`[0-9]` is an example of a character class; it matches any single digit.
-`[a-z]` matches any lower case alpha, and `[0-9a-f]` is the range of hex
-characters. You should now guess what `[a-zA-Z0-9_]` does.
-
-`.` (the period) is special -- it matches any character. If you want to match
-an actual period, you need to say `\.`.
-
-`*`, `?`, and `+` are quantifiers. They apply to the previous token. `a*`
-means "zero or more 'a' characters". Similarly `a+` means "one or more", and
-`a?` means "zero or one".
-
-As a result, `.*` means "any number (including zero) of any character".
-
-The previous token need not be a single character; you can use parens to make
-it longer. `(foo)+` matches one or more "foo", (like "foo", "foofoo",
-"foofoofoo", etc.)
-
diff --git a/doc/extras/ssh.mkd b/doc/extras/ssh.mkd
deleted file mode 100644
index fb51655..0000000
--- a/doc/extras/ssh.mkd
+++ /dev/null
@@ -1,16 +0,0 @@
-# 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
- create any number of virtual users over just one actual (unix) user, and
- distinguish between them by their public keys.
-
- * [Ssh troubleshooting][sts] is a rather long document that, as far as I
- know, covers almost every known ssh related issue. If you find something
- missing, send me an email with details so I can update it.
diff --git a/doc/extras/sts.mkd b/doc/extras/sts.mkd
deleted file mode 100644
index 1c68f42..0000000
--- a/doc/extras/sts.mkd
+++ /dev/null
@@ -1,472 +0,0 @@
-# #sts ssh troubleshooting and tips
-
-**This document must be read in full the first time. If you start from some
-nice looking section in the middle it may not help you unless you're already
-an expert at ssh**.
-
-This document should help you troubleshoot ssh-related problems in installing
-and accessing gitolite. It also has a section of random ssh-related tips and
-tricks that gitolite can do.
-
-----
-
-[[TOC]]
-
-----
-
-## IMPORTANT -- READ THIS FIRST
-
-### caveats
-
- * Before reading this document, it is **mandatory** to read and **completely
- understand** [this][ssh], which is a very detailed look at how gitolite
- uses ssh's features on the server side. Don't assume you know all that;
- if you did, you wouldn't be needing *this* document either!
-
- * This document, and others linked from this, together comprise all the help
- I can give you in terms of the ssh aspect of using gitolite. If you're
- installing gitolite, you're a "system admin", like it or not. Ssh is
- therefore a necessary skill. Please take the time to learn at least
- enough to get passwordless access working.
-
- * Please note that authentication is not really gitolite's job at all. I'd
- rather spend time on actual gitolite features, code, and documentation
- than authentication (i.e., ssh, in the common case).
-
- Surprised? [This][auth] might help explain better.
-
-### naming conventions used
-
- * Your workstation is the **client**. Your userid on the client does not
- matter, and it has no relation to your gitolite username.
-
- * The server is called **server** and the "hosting user" is **git**. If
- this is an RPM/DEB install, the hosting user is probably called
- "gitolite", however we will use "git" in this document.
-
-### taking stock -- relevant files and directories
-
- * The client has a `~/.ssh` containing a few keypairs. It may also have a
- `config` file.
-
- * The client also has a clone of the "gitolite-admin" repo, which contains a
- bunch of `*.pub` files in `keydir`. We assume this clone is in `$HOME`;
- if it is not, adjust instructions accordingly when needed.
-
- * The git user on the server has a `~/.ssh/authorized_keys` file that the
- ssh daemon uses to authenticate incoming users. We often call this file
- **authkeys** to save typing, and it always means the one on the server
- (we're not interested in this file on the client side).
-
- * The server also has a `~/.gitolite/keydir` which contains a bunch of
- `*.pub` files.
-
-### normal gitolite key handling
-
-Here's how normal gitolite key handling works:
-
- * (On client) pub key changes like adding new ones, deleting old ones, etc.,
- are done in the `keydir` directory in the gitolite-admin repo clone. Then
- the admin `git add`s and `git commit`s those changes, then `git push`es
- them to the server.
-
- * (On server) a successful push from the client makes git invoke the
- post-update hook in the gitolite-admin repo. This hook is installed by
- gitolite, and it does a bunch of things which are quite transparent to
- the admin, but we'll describe briefly here:
-
- * The pubkey files from this push are checked-out into
- `~/.gitolite/keydir` (and similarly the config files into
- `~/.gitolite/conf`).
-
- * The "compile" script then runs, which uses these files to populate
- `~/.ssh/authorized_keys` on the server.
-
- The authkeys file may have other, (non-gitolite) keys also. Those
- lines are preserved. Gitolite only touches lines that are found
- between gitolite's "marker" lines (`# gitolite start` and `# gitolite
- end`).
-
-## common ssh problems
-
-Since I'm pretty sure at least some of you didn't bother to read the
-"IMPORTANT: PLEASE READ FIRST" section above, let me take a minute to point
-you there again. Especially the first bullet.
-
-Done? OK, read on...
-
-The following problem(s) indicate that pubkey access is not working at all, so
-you should start with [appendix 1][stsapp1]. If that doesn't fix the problem, continue
-with the other appendices in sequence.
-
- * Running any git clone/fetch/ls-remote or just `ssh git@server info` asks
- you for a password.
-
-The following problem(s) indicate that your pubkey is bypassing gitolite and
-going straight to a shell. You should start with [appendix 2][sshkeys-lint]
-and continue with the rest in sequence. [Appendix 5][ybpfail] has some
-background info.
-
- * Running `ssh git@server info` gets you the output of the GNU 'info'
- command instead of gitolite's version and access info.
-
- * Running `git clone git@server:repositories/reponame` (note presence of
- `repositories/` in URL) works.
-
- [A proper gitolite key will only let you `git clone git@server:reponame`
- (note absence of `repositories/`)]
-
- * You are able to clone repositories but are unable to push changes back
- (the error complains about the `GL_BINDIR` environment variable not being
- set, and the `hooks/update` failing in some way).
-
- [If you run `git remote -v` you will find that your clone URL included the
- `repositories/` described above!]
-
- * Conversely, using the correct syntax, `git clone git@server:reponame`
- (note absence of `repositories/` in the URL), gets you `fatal: 'reponame'
- does not appear to be a git repository`, and yet you are sure 'reponame'
- exists, you haven't mis-spelled it, etc.
-
-## step by step
-
-Since I'm pretty sure at least some of you didn't bother to read the
-"IMPORTANT: PLEASE READ FIRST" section above, let me take a minute to point
-you there again. Especially the first bullet.
-
-Done? OK, now the general outline for ssh troubleshooting is this:
-
- * Make sure the server's overall setup even *allows* pubkey based login.
- I.e., check that git fetch/clone/ls-remote commands or a plain `ssh
- git@server info` do NOT ask for a password. If you do get asked for a
- password, see [appendix 1][stsapp1].
-
- * Match client-side pubkeys (`~/.ssh/*.pub`) with the server's authkeys
- file. To do this, run `sshkeys-lint`, which tells you in detail what key
- has what access. See [appendix 2][sshkeys-lint].
-
- * At this point, we know that we have the right key, and that if sshd
- receives that key, things will work. But we're not done yet. We still
- need to make sure that this specific key is being offered/sent by the
- client, instead of the default key. See [appendix 3][stsapp3] and
- [appendix 4][ssh-ha].
-
-## random tips, tricks, and notes
-
-### #giving-shell giving shell access to gitolite users
-
-Thanks to an idea from Jesse Keating, a single key can allow both gitolite
-access *and* shell access.
-
-To do this:
-
- * add the list of users who will have shell access -- one username per line,
- no extra whitespace -- to a plain text file of your choice.
-
- * put the name of this file in a new rc variable `SHELL_USERS_LIST`. For
- example it could be
-
- SHELL_USERS_LIST => "$ENV{HOME}/.gitolite.shell-users",
-
- * add the line `'Shell::input',` to the `INPUT` list in the rc file. This
- must be the first item on the list (possibly preceded by CpuTime, if
- you're using that).
-
- * add the line `'post-compile/ssh-authkeys-shell-users',` to the
- `POST_COMPILE` list, *after* the `'post-compile/ssh-authkeys',` line.
-
-Then run `gitolite compile; gitolite trigger POST_COMPILE` or push a dummy
-change to the admin repo.
-
-### #kfn distinguishing one key from another
-
-Since a user can have [more than one key][multi-key], it is sometimes useful
-to distinguish one key from another. Sshd does not tell you even the
-fingerprint of the key that finally matched, so normally all you have is the
-`GL_USER` env var.
-
-However, if you replace
-
- 'post-compile/ssh-authkeys',
-
-in the `POST_COMPILE` trigger list in the rc file with
-
- 'post-compile/ssh-authkeys --key-file-name',
-
-then an extra argument is added after the username in the "command" variable
-of the authkeys file. That is, instead of this:
-
- command="/home/g3/gitolite/src/gitolite-shell u3",no-port-forwarding,...
-
-you get this:
-
- command="/home/g3/gitolite/src/gitolite-shell u3 keydir/u3.pub",no-port-forwarding,...
-
-You can then write an INPUT trigger to do whatever you need with the file
-name, which is in `$ARGV[1]` (the second argument). The actual file is
-available at `$ENV{GL_ADMIN_BASE}/$ARGV[1]` if you need its contents.
-
-### simulating ssh-copy-id
-
-don't have `ssh-copy-id`? This is broadly what that command does, if you want
-to replicate it manually. The input is your pubkey, typically
-`~/.ssh/id_rsa.pub` from your client/workstation.
-
- * It copies it to the server as some file.
-
- * It appends that file to `~/.ssh/authorized_keys` on the server
- (creating it if it doesn't already exist).
-
- * It then makes sure that all these files/directories have go-w perms
- set (assuming user is "git"):
-
- /home/git/.ssh/authorized_keys
- /home/git/.ssh
- /home/git
-
-[Actually, `sshd` requires that even directories *above* `~` (`/`, `/home`,
-typically) also must be `go-w`, but that needs root. And typically
-they're already set that way anyway. (Or if they're not, you've got
-bigger problems than gitolite install not working!)]
-
-### problems with using non-openssh public keys
-
-Gitolite accepts public keys only in openssh format. Trying to use an "ssh2"
-key (used by proprietary SSH software) will not be a happy experience.
-src/triggers/post-compile/ssh-authkeys can be made to detect non-openssh
-formats and automatically convert them; patches welcome!
-
-The actual conversion command, if you want to just do it manually for now and
-be done with it, is:
-
- ssh-keygen -i -f /tmp/ssh2/YourName.pub > /tmp/openssh/YourName.pub
-
-then use the resulting pubkey as you normally would in gitolite.
-
-### windows issues
-
-On windows, I have only used msysgit, and the openssh that comes with it.
-Over time, I have grown to distrust putty/plink due to the number of people
-who seem to have trouble when those beasts are involved (I myself have never
-used them for any kind of git access). If you have unusual ssh problems that
-just don't seem to have any explanation, try removing all traces of
-putty/plink, including environment variables, etc., and then try again.
-
-Thankfully, someone contributed [this][putty].
-
-## #stsapp1 appendix 1: ssh daemon asks for a password
-
-> **NOTE**: This section should be useful to anyone trying to get
-> password-less access working. It is not necessarily specific to gitolite,
-> so keep that in mind if the wording feels a little more general than you
-> were expecting.
-
-You have generated a keypair on your workstation (`ssh-keygen`) and copied the
-public part of it (`~/.ssh/id_rsa.pub`, by default) to the server.
-
-On the server you have appended this file to `~/.ssh/authorized_keys`. Or you
-ran something, like the `gitolite setup` step during a gitolite install, which
-should have done that for you.
-
-You now expect to log in without having to type in a password, but when you
-try, you are being asked for a password.
-
-This is a quick checklist:
-
- * Make sure you're being asked for a password and not a pass*phrase*. Do
- not confuse or mistake a prompt saying `Enter passphrase for key
- '/home/sitaram/.ssh/id_rsa':` for a password prompt from the remote
- server!
-
- When you create an ssh keypair using `ssh-keygen`, you have the option of
- protecting it with a passphrase. When you subsequently use that keypair
- to access a remote host, your *local* ssh client needs to unlock the
- corresponding private key, and ssh will probably ask for the passphrase
- you set when you created the keypair.
-
- You have two choices to avoid this prompt every time you try to use the
- private key. The first is to create keypairs *without* a passphrase (just
- hit enter when prompted for one). **Be sure to add a passphrase later,
- once everything is working, using `ssh-keygen -p`**.
-
- 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
- discussing one more potential trouble-spot with ssh-agent (see below),
- further discussion of ssh-agent/keychain is out of scope of this document.
-
- * Ssh is very sensitive to permissions. An extremely conservative setup is
- given below, but be sure to do this on **both the client and the server**:
-
- cd $HOME
- chmod go-rwx .
- chmod -R go-rwx .ssh
-
- * Actually, every component of the path to `~/.ssh/authorized_keys` all the
- way upto the root directory must be at least `chmod go-w`. So be sure to
- check `/` and `/home` also.
-
- * While you're doing this, make sure the owner and group info for each of
- these components are correct. `ls -ald ~ ~/.ssh ~/.ssh/authorized_keys`
- will tell you what they are.
-
- * You may also want to check `/etc/ssh/sshd_config` to see if the "git" user
- is allowed to login at all. For example, if that file contains an
- `AllowUsers` config entry, then only users mentioned in that line are
- allowed to log in!
-
- * While you're in there, check that file does NOT have a setting for
- `AuthorizedKeysFile`. See `man sshd_config` for details. This setting is
- a show stopper for gitolite to use ssh.
-
- * Some OSs/distributions require that the "git" user should have a password
- and/or not be a locked account. You may want to check that as well.
-
- * If your server is running SELinux, and you install gitolite to
- `/var/gitolite` or another location unsupported by default SELinux
- policies, then SELinux will prevent sshd from reading
- `.ssh/authorized_keys`. Consider installing gitolite to
- `/var/lib/gitolite`, which is a supported location by default SELinux
- policies.
-
- * If all that fails, log onto the server as root, `cd /var/log`, and look
- for a file called `auth.log` or `secure` or some such name. Look inside
- this file for messages matching the approximate time of your last attempt
- to login, to see if they tell you what is the problem.
-
-## #sshkeys-lint appendix 2: which key is which -- running sshkeys-lint
-
-The sshkeys-lint program can be run on the server or the client. Run it with
-'-h' to get a help message.
-
-On the server you can run `gitolite sshkeys-lint` and it will tell you, for
-each key in the admin directory's keydir, what access is available. This is
-especially good at finding duplicate keys and such.
-
-To run it on the client you have to copy the file src/commands/sshkeys-lint
-from some gitolite clone, then follow these steps:
-
- * Get a copy of `~/.ssh/authorized_keys` from the server and put it in
- `/tmp/foo` or something.
-
- * cd to `~/.ssh`.
-
- * Run `/path/to/sshkeys-lint *.pub < /tmp/foo`.
-
-Note that it is not trying to log in or anything -- it's just comparing
-fingerprints as computed by `ssh-keygen -l`.
-
-If the pubkey file you're interested in appears to have the correct access to
-the server, you're done with this step.
-
-Otherwise you have to rename some keypairs and try again to get the effect you
-need. Be careful:
-
- * Do not just rename the ".pub" file; you will have to rename the
- corresponding private key also (the one with the same basename but without
- an extension).
-
- * If you're running ssh-agent, you may have to delete (using `ssh-add -D`)
- and re-add identities for it to pick up the renamed ones correctly.
-
-### typical cause(s)
-
-The admin often has passwordless shell access to `git@server` already, and
-then used that same key to get access to gitolite (i.e., copied that same
-pubkey as YourName.pub and ran `gitolite setup` on it).
-
-As a result, the same key appears twice in the authkeys file now, and since
-the ssh server will always use the first match, the second occurrence (which
-invokes gitolite) is ignored.
-
-To fix this, you have to use a different keypair for gitolite access. The
-best way to do this is to create a new keypair, copy the pubkey to the server
-as YourName.pub, then run `gitolite setup -pk YourName.pub` on the server.
-Remember to adjust your agent identities using ssh-add -D and ssh-add if
-you're using ssh-agent, otherwise these new keys may not work.
-
-## #stsapp3 appendix 3: ssh client may not be offering the right key
-
- * Make sure the right private key is being offered. Run ssh in very
- verbose mode and look for the word "Offering", like so:
-
- ssh -vvv user@host pwd 2> >(grep -i offer)
-
- If some keys *are* being offered, but not the key that was supposed to be
- used, you may be using ssh-agent (next bullet). You may also need to
- create some host aliases in `~/.ssh/config` ([appendix 4][ssh-ha]).
-
- * (ssh-agent issues) If `ssh-add -l` responds with either "The agent has no
- identities." or "Could not open a connection to your authentication
- agent.", then you can skip this bullet.
-
- However, if `ssh-add -l` lists *any* keys at all, then something weird
- happens. Due to a quirk in ssh-agent, ssh will now *only* use one of
- those keys, *even if you explicitly ask* for some other key to be used.
-
- In that case, add the key you want using `ssh-add ~/.ssh/YourName` and try
- the access again.
-
-## #ssh-ha appendix 4: ssh host aliases
-
-(or "making git use the right options for ssh")
-
-The ssh command has several options for non-default items to be specified.
-Two common examples are `-p` for the port number if it is not 22, and `-i` for
-the public key file if you do not want to use just `~/.ssh/id_rsa` or such.
-
-Git has two ssh-based URL syntaxes, but neither allows specifying a
-non-default public key file. And a port number is only allowed in one of
-them. (See `man git-clone` for details). Finally, hosts often have to be
-referred with IP addresses (such is life), or the name is very long, or hard
-to remember.
-
-Using a "host" para in `~/.ssh/config` lets you nicely encapsulate all this
-within ssh and give it a short, easy-to-remember, name. Example:
-
- host gitolite
- user git
- hostname a.long.server.name.or.annoying.IP.address
- port 22
- identityfile ~/.ssh/id_rsa
-
-Now you can simply use the one word `gitolite` (which is the host alias we
-defined here) and ssh will infer all those details defined under it -- just
-say `ssh gitolite` and `git clone gitolite:reponame` and things will work.
-
-(By the way, the 'port' and 'identityfile' lines are needed only if you have
-non-default values, although I put them in anyway just to be complete).
-
-If you have *more than one* pubkey with access to the *same* server, you
-**must** use this method to make git pick up the right key. There is no other
-way to do this, as far as I know.
-
-[tut]: http://sites.google.com/site/senawario/home/gitolite-tutorial
-
-## #ybpfail appendix 5: why bypassing gitolite causes a problem
-
-When you bypass gitolite, you end up running your normal shell instead of the
-special gitolite entry point script `gitolite-shell`.
-
-This means commands (like 'info') are interpreted by the shell instead of
-gitolite.
-
-It also means git operations look for repos in `$HOME`.
-
-However, gitolite places all your repos in a subdirectory pointed to by
-`$REPO_BASE` in the rc file (default: `repositories`), and internally prefixes
-this before calling the actual git command you invoked. Thus, the pathname of
-the repo that you use on the client is almost never the correct pathname on
-the server. (This is by design. Don't argue...)
-
-This means that, you get 2 kinds of errors if you bypass gitolite
-
- * When you use `git@server:reponame` with a key that bypasses gitolite
- (i.e., gets you a shell), this prefixing does not happen, and so the repo
- is not found. Neither a clone/fetch nor a push will work.
-
- * Conversely, consider `git@server:repositories/reponame.git`. The clone
- operation will work -- you're using the full Unix path, (assuming default
- `$REPO_BASE` setting), and so the shell finds the repo where you said it
- would be. However, when you push, gitolite's **update hook** kicks in,
- and fails to run because some of the environment variables it is expecting
- are not present.
diff --git a/doc/files.mkd b/doc/files.mkd
deleted file mode 100644
index 1cb7b2d..0000000
--- a/doc/files.mkd
+++ /dev/null
@@ -1,86 +0,0 @@
-# files involved in gitolite
-
-## install
-
-Let's say you start from a totally clean slate:
-
- $ pwd
- /home/gl-test
-
- $ ls -a
- . .. .bash_logout .bash_profile .bashrc
-
-You run `git clone git://github.com/sitaramc/gitolite`.
-
-Now you have
-
- $ ls -aF
- ./ ../ .bash_logout .bash_profile .bashrc gitolite/
-
- $ ls -aF gitolite
- ./ ../ check-g2-compat* doc/ dot.pl .git/ install* src/ t/
-
-If we were an existing user, we'd run the migration checker 'check-g2-compat'
-(see [here][g2migr]). For now we're only interested in "gitolite/src", so:
-
- $ ls -aF gitolite/src
- ./ ../ commands/ gitolite* Gitolite/ gitolite-shell* syntactic-sugar/ triggers/ VREF/
-
-We check our PATH to make sure `$HOME/bin` is in it:
-
- $ echo $PATH
- /usr/local/bin:/bin:/usr/bin:/usr/local/sbin:/usr/sbin:/sbin:/home/gl-test/.local/bin:/home/gl-test/bin
-
-Since it is, we run `mkdir bin; gitolite/install -ln`, and get:
-
- $ mkdir bin
- $ gitolite/install -ln
-
- $ ls -aF
- ./ ../ .bash_logout .bash_profile .bashrc bin/ gitolite/
-
- $ ls -aF bin
- ./ ../ gitolite@
-
- $ file bin/gitolite
- bin/gitolite: symbolic link to `/home/gl-test/gitolite/src/gitolite'
-
-That's the install done. At the end of it, we have just *one* symlink in
-`$HOME/bin`; everything else is in a different directory.
-
-## setup
-
-Now you copy your pubkey (typically `id_rsa.pub`) from your workstation to the
-server, then run `gitolite setup -pk "yourname.pub"`. Which gives you this:
-
- $ ls -aF
- ./ .bash_logout .bashrc gitolite/ .gitolite.rc repositories/ .ssh/
- ../ .bash_profile bin/ .gitolite/ projects.list sitaram.pub
-
- $ ls -aF bin
- ./ ../ gitolite@
-
- $ ls -aF .gitolite
- ./ ../ conf/ hooks/ keydir/ logs/
-
- $ ls -aF repositories
- ./ ../ gitolite-admin.git/ testing.git/
-
- $ ls -aF .ssh
- ./ ../ authorized_keys*
-
-And that's the setup done. At the end of this step, you have
-
- * `~/bin/gitolite` -- a symlink to `~/gitolite/src/gitolite`. The target of
- this symlink tells gitolite where the rest of the code is.
- * `~/gitolite/src` -- the rest of the code.
- * `~/.gitolite` -- the gitolite "admin" directory. The only thing you
- should directly touch here are the [log][] files and [hooks][]. (I.e., do
- NOT change the conf or keydir contents here; see adding [users][] and
- [repos][] for how to do that.
- * `~/.gitolite.rc` -- the [rc][] file.
- * `~/repositories` -- which contains all the repositories that gitolite will
- be managing.
- * `~/.ssh` -- which contains (at least) the `authorized_keys` file that
- provides access to users. You can look inside that file and correlate it
- with what the [ssh][] docs tell you, if you wish.
diff --git a/doc/g2incompat.mkd b/doc/g2incompat.mkd
deleted file mode 100644
index ca54ebc..0000000
--- a/doc/g2incompat.mkd
+++ /dev/null
@@ -1,103 +0,0 @@
-# #g2incompat incompatibility with g2
-
-This page expands on some incompatibilities that were only briefly mentioned
-in the [migration][g2migr] page.
-
-## #g2i-name NAME rules
-
-1. NAME/ rules must be changed to VREF/NAME/
-
-2. Fallthru on all VREFs is "success" now, so any NAME/ rules you have
- **MUST** change the ruleset in some way to maintain the same restrictions.
- The simplest is to add the following line to the end of each repo's rule
- list:
-
- - VREF/NAME/ = @all
-
-## #g2i-subconf subconf command in admin repo
-
-(This is also affected by the previous issue, 'NAME rules'; please read that
-as well).
-
-If you're using delegation in your admin conf setup, please add the following
-lines to the end of the gitolite-admin rules in your conf/gitolite.conf file:
-
- repo gitolite-admin
- - VREF/NAME/ = @all
-
- subconf "fragments/*.conf"
-
-The first part compensates for fallthru now being a success when processing
-[VREF][vref] rules (NAME rules are just one specific VREF). Although,
-**ideally**, you should change your ruleset so that you no longer require that
-line. As the [vref documentation][vref] says:
-
-> **Virtual refs are best used as additional "deny" rules**, performing
-> extra checks that core gitolite cannot.
-
-The second part explicitly says when and where to include the subconf files.
-(Before subconf was invented, this used to happen implicitly at the end of the
-main conf file, and was hardcoded to that specific glob.)
-
-## #g2i-gl-time gl-time for performance measurement
-
-If you've been using gl-time for performance measurement, there's a much
-better system available now.
-
-gl-time used to only log elapsed time. The new 'CpuTime' trigger module
-shipped with gitolite, if enabled in the rc file, can also report CPU times
-using perl's 'times()' function. See comments within that file and in the
-default rc file that contain the word "cpu", for more details.
-
-Further, you can copy that module with a different name, add your own
-functionality, and invoke *that* from the rc file instead.
-
-## #g2i-mirroring changes in mirroring setup
-
-There are several changes with regard to mirroring:
-
- * There is no 'post-receive' hook to be installed. Mirroring is handled by
- g3's [triggers][] mechanism. Gitolite triggers are enabled by adding (or
- uncommenting, in this case) appropriate lines in the rc file.
-
- * The `GL_HOSTNAME` variable is now `HOSTNAME`. (Note that the rc file
- syntax itself has changed quite a bit; to be accurate, HOSTNAME is not a
- variable but a hash key with an associated value).
-
- * The `GL_GITCONFIG_KEYS` variable is now `GIT_CONFIG_KEYS`, **but** you no
- longer need to set it to anything for mirroring to work.
-
- * The `gl-tool` program does not exist anymore. Adding keys for peer
- servers is done just like adding user keys, except that the pubkey file
- name must start with `server-`. For example, to add a peer host called
- frodo, you will acquire its pubkey and add it as `server-frodo.pub`.
-
- * The config variables are quite different now. The main ones now look like
- this:
-
- option mirror.master = sam
- option mirror.slaves = frodo gollum
-
- The redirectOK looks like this:
-
- option mirror.redirectOK = frodo
-
- The special value "true" to say that all slaves are trusted is now "all":
-
- option mirror.redirectOK = all
-
- * There are no more mirroring "keys", (lists of servers named in config keys
- like 'gitolite.mirror.nightly', etc). You can certainly add lines like
-
- option mirror.nightly = merry pippin
-
- but they will not be processed by gitolite. Your cron jobs should use
- `gitolite git-config` to query this variable, grab the list of peers, and
- run `gitolite mirror` on each of them.
-
- * The external command to resync mirrors is 'mirror', run just like any
- other [command][commands]. In particular, you can run `gitolite mirror
- -h` to get help. It cannot be run from a slave to ask a master to push
- (unlike in the old system) but what's more convenient is that any user who
- has any access to the master can run it remotely (if you allow it) to
- invoke a push.
diff --git a/doc/g2migr-example.mkd b/doc/g2migr-example.mkd
deleted file mode 100644
index 28ec8b2..0000000
--- a/doc/g2migr-example.mkd
+++ /dev/null
@@ -1,269 +0,0 @@
-# migration example
-
-This shows what a typical migration would look like, using a test setup.
-
-[[TOC]]
-
-## existing setup
-
-The existing gitolite is the latest in the "g2" (v2.x) branch.
-
-First, the rc file has the following lines different from the default:
-
- -$GL_WILDREPOS = 0;
- +$GL_WILDREPOS = 1;
-
- -$GL_GITCONFIG_KEYS = "";
- +$GL_GITCONFIG_KEYS = ".*";
-
-Next, the conf/gitolite.conf file in `~/.gitolite`:
-
- repo gitolite-admin
- RW+ = tester u1
-
- repo testing
- RW+ = @all
-
- repo foo
- RW+ = u1 u2
- RW+ NAME/ = u1
- RW+ NAME/u2 = u2
-
- repo bar
- RW = u2
-
- repo baz/..*
- C = u3 u4
- RW+ = CREATOR
- config foo.bar = baz
-
-(Note that this conf file has NAME/ rules, which **have changed**
-significantly in g3; see [here][g2i-name] for details).
-
-These are the repos already existing
-
- $ find repositories -name "*.git" | sort
- repositories/bar.git
- repositories/baz/u3.git
- repositories/baz/u4.git
- repositories/baz/uthree.git
- repositories/foo.git
- repositories/gitolite-admin.git
- repositories/testing.git
-
-The config entries exist for all the baz/ repos:
-
- $ grep -2 foo `find repositories -name "config" `
- repositories/baz/uthree.git/config-[gitweb]
- repositories/baz/uthree.git/config- owner = u3
- repositories/baz/uthree.git/config:[foo]
- repositories/baz/uthree.git/config- bar = baz
- --
- repositories/baz/u4.git/config-[gitweb]
- repositories/baz/u4.git/config- owner = u4
- repositories/baz/u4.git/config:[foo]
- repositories/baz/u4.git/config- bar = baz
- --
- repositories/baz/u3.git/config-[gitweb]
- repositories/baz/u3.git/config- owner = u3
- repositories/baz/u3.git/config:[foo]
- repositories/baz/u3.git/config- bar = baz
-
-## preparing for the migration
-
-### getting g3
-
-Fortunately this is easy here; I just happened to have the repo already
-fetched so I just had to switch branches. You may have to 'git clone ...'
-from github.
-
- $ cd gitolite
- $ git checkout master
- Branch master set up to track remote branch master from origin.
- Switched to a new branch 'master'
-
-### run check-g2-compat
-
-This is a quick and dirty program to catch some of the big issues.
-
- $ cd
- $ gitolite/check-g2-compat
- INFO This program only checks for uses that make the new g3 completely unusable
- or that might end up giving *more* access to someone if migrated as-is.
- It does NOT attempt to catch all the differences described in the docs.
-
- INFO 'see docs' usually means doc/g2migr.mkd
- (online at http://sitaramc.github.com/gitolite/g2migr.html)
-
- checking rc file...
- NOTE GL_ADMINDIR is in the right place; assuming you did not mess with
- GL_CONF, GL_LOGT, GL_KEYDIR, and GL_CONF_COMPILED
-
- checking conf file(s)...
- SEVERE NAME rules; see docs
-
- checking repos...
- WARNING found 3 gl-creater files; see docs
-
- ...all done...
-
-## the actual migration
-
-Here's the actual migration, step by step
-
-### step 1
-
- $ ls -a bin
- . gl-admin-push gl-install gl-setup-authkeys gl-VREF-DUPKEYS
- .. gl-auth-command gl-mirror-push gl-system-install gl-VREF-EMAIL_CHECK
- gitolite_env.pm gl-compile-conf gl-mirror-shell gl-time gl-VREF-FILETYPE
- gitolite.pm gl-conf-convert gl-query-rc gl-tool gl-VREF-MERGE_CHECK
- gitolite_rc.pm gl-dryrun gl-setup gl-VREF-COUNT sshkeys-lint
- $ rm -rf bin;mkdir bin
-
- $ grep GL_PACKAGE .gitolite.rc
- $GL_PACKAGE_CONF = "/home/g3/share/gitolite/conf";
- $GL_PACKAGE_HOOKS = "/home/g3/share/gitolite/hooks";
- $ rm -rf share
-
- $GL_PACKAGE_HOOKS = "/home/g3/share/gitolite/hooks";
- $ rm -rf share
-
- $ mv .gitolite.rc old.grc
-
-(still on step 1, this is substep 3) notice we are cloning **on the server**,
-using a **full path** to the repo.
-
- $ git clone repositories/gitolite-admin.git old.ga
- Cloning into 'old.ga'...
- done.
- $ rm -rf repositories/gitolite-admin.git/
-
-Since I'm not interested in preserving the logs and don't have any custom
-hooks:
-
- $ rm -rf .gitolite
-
-### step 2
-
-I have no variables that *must* be preset, since the report by
-`check-g2-compat` is clear.
-
-### step 3
-
-Here we install the new gitolite. Remember we already got the new software
-(in order to run 'check-g2-compat').
-
-Just check that bin is empty, then run 'install -ln' from the gitolite source
-tree:
-
- $ ls -al bin
- total 8
- drwxrwxr-x 2 g3 g3 4096 Apr 24 10:57 .
- drwx------ 8 g3 g3 4096 Apr 24 10:59 ..
- $ gitolite/install -ln
- $ ls -al bin
- total 8
- drwxrwxr-x 2 g3 g3 4096 Apr 24 11:01 .
- drwx------ 8 g3 g3 4096 Apr 24 10:59 ..
- lrwxrwxrwx 1 g3 g3 30 Apr 24 11:01 gitolite -> /home/g3/gitolite/src/gitolite
-
-OK that went well. Now setup gitolite. You don't need a key here; just use a
-random name:
-
- $ gitolite setup -a admin
- Initialized empty Git repository in /home/g3/repositories/gitolite-admin.git/
-
-### step 4
-
-Now go to your old clone, and push it:
-
- $ cd old.ga
- $ gitolite push -f
- ...usual git progress output deleted...
- remote: FATAL: git config foo.bar not allowed
- remote: check GIT_CONFIG_KEYS in the rc file
- To /home/g3/repositories/gitolite-admin.git
- + 7eb8163...1474770 master -> master (forced update)
-
-Aaha! I forgot to set `CONFIG_KEYS` (new name for `GL_GIT_CONFIG_KEYS`) in
-the new rc file so fix that:
-
- $ vim ~/.gitolite.rc
- (edit and set it to `.*` for now)
-
-and push again:
-
- $ gitolite push -f
- Everything up-to-date
-
-Damn. We have to make a dummy commit to allow the push to do something.
-
-But wait! We forgot fix the [NAME/][g2i-name] rules, so may as well fix
-those, add, and push:
-
- $ vim conf/gitolite.conf
- # change all NAME/ to VREF/NAME/
- # append a '- VREF/NAME/ = @all' at the end
- # save
- git add conf
-
- $ git commit -m name-rules
- ... some output for add...
-
- $ gitolite push -f
- Counting objects: 1, done.
- Writing objects: 100% (1/1), 181 bytes, done.
- Total 1 (delta 0), reused 0 (delta 0)
- Unpacking objects: 100% (1/1), done.
- To /home/g3/repositories/gitolite-admin.git
- 1474770..4c2b41d master -> master
-
-### step 5
-
-The only thing left is to fix up the gl-creater files:
-
- $ cd $HOME/repositories
- $ find . -type d -name "*.git" -prune | while read r
- > do
- > mv $r/gl-creater $r/gl-creator
- > done 2>/dev/null
-
-And we're done!
-
-## checking things out
-
-Let's see what repos u3 has:
-
- ssh u3 info
- hello u3, this is g3@sita-lt running gitolite3 v3.0-11-g090b0f5 on git 1.7.7.6
-
- C baz/..*
- R W baz/u3
- R W baz/uthree
- R W gitolite-admin
- R W testing
-
-That's a combination of 'info' and 'expand', by the way. There is no expand
-command any more.
-
-How about adding a new repo and checking if the config entries made it?
-
- $ git ls-remote u4:baz/ufour
- Initialized empty Git repository in /home/g3/repositories/baz/ufour.git/
- $ grep -A1 foo `find repositories -name "config" `
- repositories/baz/u3.git/config:[foo]
- repositories/baz/u3.git/config- bar = baz
- --
- repositories/baz/u4.git/config:[foo]
- repositories/baz/u4.git/config- bar = baz
- --
- repositories/baz/ufour.git/config:[foo]
- repositories/baz/ufour.git/config- bar = baz
- --
- repositories/baz/uthree.git/config:[foo]
- repositories/baz/uthree.git/config- bar = baz
-
-And there it is, in the second block of lines...
-
-And now we're really done.
diff --git a/doc/g2migr.mkd b/doc/g2migr.mkd
deleted file mode 100644
index 2783cf8..0000000
--- a/doc/g2migr.mkd
+++ /dev/null
@@ -1,279 +0,0 @@
-# #g2migr migrating from g2
-
- **This document is a *MUST* read if you are currently using
-g2 and want to move to g3.**
-
-----
-
-[[TOC]]
-
-----
-
-First things first: g2 will be supported for a good long time for critical
-bugs, although enhancements and new features won't happen.
-
-Migration should be straightforward, but it is not automatic. The biggest
-differences are in the rc file, mirroring, "NAME/" rules, and delegation.
-
-> ----
-
-> **Presetting the rc file**
-
-> Some rc settings in the older gitolite are such that you cannot directly
-> run `gitolite setup` when you're ready to migrate. **Doing that will
-> clobber something important**. See [presetting the rc file][rc-preset]
-> for details.
-
-> ----
-
-The `check-g2-compat` program attempts to identify any *big* issues you will
-be facing; run that first. See [later][cg2c] in this page for what its
-messages mean. If it does not report any issues, your migrate will probably
-go quickly. I still suggest you go through the links below in case that
-program missed something.
-
-## incompatible features
-
-Here's a list of incompatible features and what you need to do to migrate.
-Some of them have links where there is more detail than I want to put here.
-
-### high impact
-
-(serious loss of functionality and/or access control compromised)
-
- * [`NAME/`][g2i-name] rules: thes need to change to `VREF/NAME/`, and you
- need to add a deny rule at the end because fallthru is "success" for all
- [VREFs][vref] now, including the "NAME" VREF.
-
- * [subconf][g2i-subconf]: if you're using [delegation][deleg], there is no
- implicit "subconf" at the end; you'll have to add it in.
-
- * There are several important differences in mirroring. You can start from
- scratch by reading the new [mirroring][mirroring] doc or
- [migrate][g2i-mirroring] (carefully!).
-
- * `ADMIN_POST_UPDATE_CHAINS_TO` -- **dropped**. Add your script to the
- `POST_COMPILE` trigger chain. Your script won't be getting the arguments
- that *git* sends to the post-update hook, but for the admin repo the only
- argument that even comes in (or is significant) is "refs/heads/master"
- anyway.
-
- * `GL_ALL_INCLUDES_SPECIAL` -- **dropped**, **requires presetting**.
-
- @all always includes gitweb and daemon now. Use [deny-rules][] if you
- want to say `R = @all` but not have the repo(s) be visible to gitweb or
- daemon.
-
- * `GL_NO_CREATE_REPOS` -- **dropped**. If you think you need this, email
- me. I know one group who does need this so I will be putting it in
- eventually but not right away. It's almost certain to be renamed anyway.
-
- * `GL_NO_DAEMON_NO_GITWEB` **dropped**, **requires presetting**. Default
- will clobber your projects.list file and git-daemon-export-ok files.
-
- Comment out the appropriate lines in the rc file, in the `POST_COMPILE`
- *and* the `POST_CREATE` trigger sections. As a bonus, gitweb and daemon
- can now be separately disabled, instead of both being tied to the same
- setting.
-
- * `GL_NO_SETUP_AUTHKEYS` **dropped**, **requires presetting**. Default will
- clobber your authkeys file.
-
- Comment out all the line(s) that call ssh-authkeys in the rc file.
-
- * `UPDATE_CHAINS_TO` **dropped**, **requires presetting**. Default will
- fail to run this extra check when users push.
-
- Use a [vref][] instead. You can directly use any existing chained-to
- script as a VREF; they'll work. Don't forget to add a rule that
- references the new VREF!
-
- * `GIT_PATH` **dropped**, **requires presetting**.
-
- If you need its functionality, add these lines to the end of the rc file:
-
- $ENV{PATH}="...whatever you want...";
- 1;
-
-### medium impact
-
-(important functionality lost, but access control not compromised)
-
- * `GL_ADMINDIR` -- **dropped**, is now at a fixed location: `~/.gitolite`.
- If you want it somewhere else go ahead and move it, then place a symlink
- from the assumed location to the real one.
-
- * `GL_GET_MEMBERSHIPS_PGM` -- is now `GROUPLIST_PGM`, see
- [here][ldap].
-
- * `GL_WILDREPOS_DEFPERMS` -- is now `DEFAULT_ROLE_PERMS`.
-
- * `REPO_BASE` -- **dropped**, is now at a fixed location: `~/repositories`.
- If you want it somewhere else go ahead and move it, then place a symlink
- from the assumed location to the real one.
-
-### low impact
-
-(ancillary, non-core, or minor functionality lost)
-
- * Built-in command `expand` -- **dropped**. The 'info' command shows you
- both normal and wild repos now. The output format is also much simpler.
-
- * Built-in commands 'getperms', 'setperms' -- **merged** into external
- command 'perms'. Run `ssh git@host perms -h` for details.
-
- Similarly, 'getdesc' and 'setdesc' have been merged into 'desc'.
-
- * Several 'ADC's -- see the [dev-status][] page for more on this.
-
- * [gl-time][g2i-gl-time]: the CpuTime module replaces gl-time.
-
- * `BIG_INFO_CAP` -- **dropped**. If you think you must have this, try it
- without and see if there's a difference. If you *know* you need this,
- convince me.
-
- * `GL_ADC_PATH` -- **dropped**. It is obsolete; use [commands][] or add
- [your own][dev-notes].
-
- * `GL_ALL_READ_ALL` -- **dropped**. If you think you must have this, try it
- without and see if there's a difference. If you *know* you need this,
- convince me.
-
- * `GL_BIG_CONFIG` -- **dropped**. This feature is default now.
-
- * `GL_CONF`, `GL_CONF_COMPILED`, and `GL_KEYDIR` -- **dropped**. You had no
- business touching these anyway; if you did, move them into the expected
- default locations before attempting to run `gitolite setup`
-
- * `GL_GITCONFIG_KEYS` -- is now `GIT_CONFIG_KEYS`.
-
- * `GL_LOGT` -- now has a fixed value; email me if this is a problem.
-
- * `GL_PACKAGE_CONF` and `GL_PACKAGE_HOOKS` -- **dropped**. They are not
- needed anymore, but check if you had any custom hooks set in the latter
- location and copy them across.
-
- * `GL_PERFLOGT` -- **dropped**. See [gl-time][g2i-gl-time].
-
- * `GL_SITE_INFO` -- is now `SITE_INFO`.
-
- * `GL_WILDREPOS` -- **dropped**. This feature is default now.
-
- * `GL_WILDREPOS_PERM_CATS` -- is now the ROLES hash in the rc file.
-
- * `RSYNC_BASE` -- needs work. Email me if you are using this.
-
- * `NICE_VALUE` -- **dropped**. Uncomment the 'renice 10' line in the rc
- file. You can also change the 10 to something else if you wish.
-
- * `PROJECTS_LIST` -- is now `GITWEB_PROJECTS_LIST`. More importantly, it is
- only used by update-gitweb-access-list in src/commands/post-compile. This
- variable now has nothing to do with gitolite core, and the rc is just
- helping to store settings for external programs like that one.
-
- * `REPO_UMASK` -- is now `UMASK`.
-
- * `WEB_INTERFACE` and `GITWEB_URI_ESCAPE` -- **dropped**. Patches to the
- update program to directly do those things are welcome. Personally, I
- think people who use spaces and other funky characters in dir/file names
- should be shot but no one listens to me anyway.
-
-## #cg2c using the "check-g2-compat" program
-
-This program checks a few things only, not everything. In particular, it
-looks for settings and status that might:
-
- * make g3 unusable for lots of users
- * make g3 give *more* access than g2 under some conditions
-
-It does NOT look for or warn about anything else; you're expected to read (and
-act upon, if needed) the rest of the migration guide links given a few paras
-above to cover everything else.
-
-Here's an explanation of those messages that the check-g2-compat program may
-put that contain the words "see docs":
-
- * `GL_ADMINDIR in the wrong place -- aborting`
-
- It expects to find `GL_ADMINDIR` and `REPO_BASE` pointing to the right
- places. It aborts if these conditions are not met and does not scan
- further since that sort of guesswork is not good. If you are in that
- position, make a symlink from the real location to the expected location,
- change the RC accordingly, and re-try.
-
- * `REPO_BASE in the wrong place -- aborting`
-
- same as above
-
- * `NAME rules`
-
- **This is a significant difference and affects access badly (gives access
- that would otherwise not be given)**. Please see the [list of non-RC
- incompatibilities][g2incompat].
-
- * `subconf command in admin repo`
-
- This is not so bad security wise but it might *reduce* access by not
- processing files you intended to. Again, see the same link as in the
- previous bullet.
-
- * `mirroring used`
-
- There have been quite a few changes to mirroring. You can start from
- scratch by reading the new [mirroring][mirroring] doc or
- [migrate][g2i-mirroring] (carefully!).
-
- * `found N gl-creater files`
-
- These need to be renamed to `gl-creator` (the correct spelling at last,
- hooray!). Suggested command sequence:
-
- cd $HOME/repositories
- find . -type d -name "*.git" -prune | while read r
- do
- mv $r/gl-creater $r/gl-creator
- done 2>/dev/null
-
- Once you do this, the g2 will not work completely unless you change them
- back.
-
- * `found N gl-perms files with R or RW`
-
- Setting perms of R and RW will no longer work; you have to say READERS and
- WRITERS now. Suggested command:
-
- find `gitolite query-rc GL_REPO_BASE` -name gl-perms |
- xargs perl -pi -e 's/\bR\b/READERS/;s/\bRW\b/WRITERS/'
-
-## #rc-preset presetting the rc file
-
-Some rc settings in the older gitolite are such that you cannot directly run
-`gitolite setup` when you're ready to migrate. **Doing that will clobber
-something important**. You have to create a default rc file, edit it
-appropriately, and *then* run `gitolite setup`.
-
-The most serious example of this is `GL_NO_SETUP_AUTHKEYS`, which tells the
-(old) gitolite that you want to manage `~/.ssh/authorized_keys` yourself and
-it should not fiddle with it.
-
-If you don't preset the rc (in this case, by commenting out the 'ssh-authkeys'
-line) **before** running `gitolite setup`, **your `~/.ssh/authorized_keys`
-file will get clobbered**.
-
-The actual rc settings that require presetting are listed in the "high
-impact" section above. This section tells you how to do the presetting.
-
- * save your old (g2) rc file somewhere, just in case
-
- * run
-
- gitolite print-default-rc > $HOME/.gitolite.rc
-
- * edit the file
-
- ${EDITOR:-vim} $HOME/.gitolite.rc
-
- make appropriate changes as described elsewhere in this migration guide,
- and save it.
-
- * *then* you can run [gitolite setup][setup].
diff --git a/doc/g3why.mkd b/doc/g3why.mkd
deleted file mode 100644
index ae6cad0..0000000
--- a/doc/g3why.mkd
+++ /dev/null
@@ -1,97 +0,0 @@
-# why a completely new version?
-
-Gitolite started life as 400 lines of perl written on a weekend because I was
-quickly losing control of my projects at work, exacerbated by git newbies
-doing all the wrong things. I really needed it!
-
-That little 400 line thing is now a huge bunch of programs that do all sorts
-of things (I mean, rsync access control in a git related program? WTF!),
-because it kinda just *grew* while I wasn't looking.
-
-So, briefly, here are the advantages of g3:
-
- * compile versus everything else
-
- g2's "compile" script was doing way, way too much. For example, dealing
- with gitweb and git-daemon was a good chunk of code in g2. In contrast,
- here's how g3 generates gitweb's projects.list file:
-
- (
- gitolite list-phy-repos | gitolite access % gitweb R any | grep -v DENIED
- gitolite list-phy-repos | gitolite git-config -r % gitweb\\.
- ) |
- cut -f1 | sort -u | sed -e 's/$/.git/' > $plf
-
- * core versus non-core
-
- That's just the tip of the iceberg. The commands above run from a script
- that is itself outside gitolite, and can be enabled and disabled from the
- rc file. There are six different "events" within gitolite that can
- trigger external programs, with specific arguments passed to them, much
- like git's own hooks. The example you saw is called from the
- "POST_COMPILE" trigger.
-
- And as you can see, these programs be in any language.
-
- * get/set perms/desc, and ADCs
-
- I've always wanted to kick setperms out of core and make it an ADC.
- Sadly, it couldn't be done because when you update your repo's permissions
- using setperms, that can affect gitweb/daemon access, which -- you guessed
- right -- feeds back into the main code in complex ways. It *had* to be an
- "inside job".
-
- But now, the new 'perms' program is quite external to gitolite. And how
- does it fix up gitweb/daemon permissions after it is done updating the
- "gl-perms" file?
-
- system("gitolite", "trigger", "POST_CREATE");
-
- * syntax versus semantics
-
- I got tired of people asking things like "why can't I have
- backslash-escaped continuation lines?" I designed it differently because
- I don't like them but perhaps it's reasonable for some people.
-
- Someone else wanted to use subdirectories of 'keydir' as group names. Why
- not?
-
- G3 comes with a stackable set of "syntactic sugar" helpers. And you can
- write your own, though they do have to be in perl (because they're not
- standalone programs).
-
- Once the code is written and placed in the right place, all a site has to
- do to enable it is to uncomment some lines in the rc file:
-
- # these will run in sequence during the conf file parse
- SYNTACTIC_SUGAR =>
- [
- # 'continuation-lines',
- # 'keysubdirs-as-groups',
-
-
- * roll your own
-
- Having a decent shell API helps enormously. You saw an example above but
- how about if your boss asks you "I need a list of everyone who *currently*
- has read access to the 'foo' repo"?
-
- Sure you could look in conf/gitolite.conf, all its include files (if you
- have any), and if the repo is user-created, then in its gl-perms.
-
- Or you could do something like this:
-
- gitolite list-users | gitolite access foo % R any | cut -f1
-
- * over-engineered
-
- g2 was, to some extent, over-engineered. One of the best examples is the
- documentation on hook-propagation in g2, which required even a *picture*
- to make clear (always a bad sign). In g3, the [hooks][] section is 4
- sentences.
-
-Anyway you get the idea.
-
-The point is not that you can do all these cool tricks. The point is they are
-possible because of the redesign. There is no way on God's green earth I
-could have done this with the old code.
diff --git a/doc/git-config.mkd b/doc/git-config.mkd
deleted file mode 100644
index 94487e1..0000000
--- a/doc/git-config.mkd
+++ /dev/null
@@ -1,66 +0,0 @@
-# "git-config" keys and values
-
-Here's all you want to know about setting repo-specific git-config values.
-
-(Original version thanks to teemu dot matilainen at iki dot fi)
-
-> ----
-
-> **Note**: this won't work unless the rc file has the right settings;
-> please see `$GIT_CONFIG_KEYS` in the [rc file doc][rc].
-
-> ----
-
-The syntax is simple:
-
- config sectionname.keyname = [optional value_string]
-
-For example:
-
- repo gitolite
- config hooks.mailinglist = gitolite-commits@example.tld
- config hooks.emailprefix = "[gitolite] "
- config foo.bar = ""
- config foo.baz =
-
-This does either a plain "git config section.key value" (for the first 2
-examples above) or "git config --unset-all section.key" (for the last 2
-examples). Other forms of the `git config` command (`--add`, the
-`value_regex`, etc) are not supported.
-
-> ----
-
-> **WARNING**: simply deleting the config line from the `conf/gitolite.conf`
-> file will *not* delete the variable from `repo.git/config`. The syntax in
-> the last example is the *only* way to make gitolite execute a
-> `--unset-all` operation on the given key.
-
-> ----
-
-You can also use the special value `%GL_REPO` in the string to save typing:
-
- repo foo bar baz
- config hooks.mailinglist = %GL_REPO-commits@example.tld
- config hooks.emailprefix = "[%GL_REPO] "
-
-You can repeat the 'config' line as many times as you like, and the last
-occurrence will be the one in effect. This allows you to override settings
-just for one project, as in this example:
-
- repo @all
- config hooks.mailinglist = %GL_REPO-commits@example.tld
- config hooks.emailprefix = "[%GL_REPO] "
-
- repo customer-project
- # different mailing list
- config hooks.mailinglist = announce@customer.tld
-
-The "delete config variable" syntax can also be used, if you wish:
-
- repo secret # no emails for this one please
- config hooks.mailinglist =
- config hooks.emailprefix =
-
-As you can see, the general idea is to place the most generic ones (`repo
-@all`, or repo patterns like `repo foo.*`) first, and place more specific ones
-later to override the generic settings.
diff --git a/doc/groups.mkd b/doc/groups.mkd
deleted file mode 100644
index 970ea1d..0000000
--- a/doc/groups.mkd
+++ /dev/null
@@ -1,30 +0,0 @@
-# group definitions
-
-You can group repos or users for convenience. The syntax is the same for both
-and does not distinguish; until you *use* the group name it could really be
-either.
-
-Here's an example:
-
- @developers = dilbert alice wally
-
-Group definitions accumulate; this is the same as the above:
-
- @developers = dilbert
- @developers = alice
- @developers = wally
-
-You can use one group in another group definition; the values will be expanded
-right there (meaning later additions will not appear in the second group).
-
- @developers = dilbert alice
- @interns = ashok
- @staff = @interns @developers
- @developers = wally
-
- # wally is NOT part of @staff
-
-## special group `@all`
-
-`@all` is a special group name that is often convenient to use if you really
-mean "all repos" or "all users".
diff --git a/doc/gsmigr.mkd b/doc/gsmigr.mkd
deleted file mode 100644
index 0f54bbb..0000000
--- a/doc/gsmigr.mkd
+++ /dev/null
@@ -1,125 +0,0 @@
-# migrating from gitosis to gitolite
-
-[2012-04-09] Modified for gitolite g3. These instructions have not really
-been tested with g3, but are expected to work.
-
-Migrating from gitosis to gitolite is fairly easy, because the basic design is
-the same.
-
-There's only one thing that might trip up people: the userid. Gitosis uses
-`gitosis`. Gitolite can use any userid you want; most of the documentation
-uses `git`, while DEB/RPM packages use `gitolite`.
-
-Here are the steps on the server:
-
- * (as 'gitosis' on the server) **Rename** `~/.ssh/authorized_keys` to
- something else so that no one can accidentally push while you're doing
- this.
-
- * (as 'gitosis' on the server) For added safety, **delete** the post-update
- hook that gitosis-admin installed
-
- rm ~/repositories/gitosis-admin.git/hooks/post-update
-
- or at least rename it to `.sample` like all the other hooks hanging
- around, or edit it and comment out the line that calls `gitosis-run-hook
- post-update`.
-
- * (as 'gitosis' on the server) If you already use the `update` hook for some
- reason, you'll have to make that a [VREF][vref]. This is because gitolite
- uses the update hook for checking write access.
-
- * (as 'root' on the server) copy all of `~/repositories` to the gitolite
- hosting user's home directory. Something like
-
- cp -a /home/gitosis/repositories /home/git
- chown -R git.git /home/git/repositories
-
- * (as 'root' and/or 'git' on the server) Follow instructions to install
- gitolite; see the [install document][install].
-
- This will give you a gitolite config that has the required entries for the
- "gitolite-admin" repo.
-
-Now, log off the server and get back to the client. All subsequent
-instructions are to be read as "on gitolite admin's workstation".
-
- * **Clone** the new gitolite-admin repo to your workstation. (You already
- have a clone of the gitosis-admin repo so now you have both).
-
- * **Convert** your gitosis config file and append it to your gitolite config
- file. Substitute the path for your gitosis-admin clone in `$GSAC` below,
- and similarly the path for your gito**lite**-admin clone in `$GLAC`. (The
- convert-gitosis-conf program is a standalone program that you can bring
- over from any gitolite clone; you don't have to install all of gitolite on
- your workstation to use this):
-
- ./convert-gitosis-conf < $GSAC/gitosis.conf >> $GLAC/conf/gitolite.conf
-
- **Be sure to check the file to make sure it converted correctly** -- due
- it's "I only need it once" nature, this program has not received too much
- attention from anyone!
-
- * Remove the entry for the 'gitosis-admin' repo. You do not need it here
- and it may cause confusion.
-
- * **Copy** the keys from gitosis's keydir (same meanings for GSAC and GLAC)
-
- cp $GSAC/keydir/* $GLAC/keydir
-
- If your gitosis-admin key was `you@machine.pub`, and you supplied the same
- one to gitolite's gl-setup program as `you.pub` when you installed
- gitolite, then you should remove `you@machine.pub` from the new keydir
- now. Otherwise you will have 2 pubkey files (`you.pub` and
- `you@machine.pub`) which are identical, which is *not* a good idea.
-
- Similarly, you should replace all occurrences of `you@machine.pub` with
- `you` in the `conf/gitolite.conf` file.
-
- * **IMPORTANT**: if you have any users with names like `user@foo`, where the
- part after the `@` does *not* have a `.` in it (i.e., does not look like
- an email address), you need to change them, because gitolite uses that
- syntax for [enabling multi keys][multi-key].
-
- You have two choices in how to fix this. You can change the gitolite
- config so that all mention of `user@foo` is changed to just `user`.
-
- Or you can change each occurrence of `user@foo` to, say, `user_foo` *and*
- change the pubkey filename in keydir/ also the same way (`user_foo.pub`).
-
- Just to repeat, you do NOT need to do this if the username was like
- `user@foo.bar`, i.e., the part after the `@` had a `.` in it, because then
- it looks like an email address.
-
- * **IMPORTANT: expand any multi-key files you may have**. Gitosis is happy
- to accept files containing more than one public key (one per line) and
- assign all the keys to the same user. Gitolite does not allow that; see
- [here][multi-key]'s for how gitolite handles multi-keys.
-
- So if you had any multi-keys in gitosis, they need to be carefully split
- into individual keys.
-
- You can split the keys manually, or use the following code (just
- copy-paste it into your xterm after "cd"-ing to your gitolite-admin repo
- clone):
-
- wc -l keydir/*.pub | grep -v total | grep -v -w 1 | while read a b
- do
- i=1
- cat $b|while read l
- do
- echo "$l" > ${b%.pub}@$i.pub
- (( i++ ))
- done
- mv $b $b.done
- done
-
- This will split each multi-key file (say "sitaram.pub") into individual
- files called "sitaram@1.pub", "sitaram@2.pub", etc., and rename the
- original to "sitaram.pub.done" so gitolite won't pick it up.
-
- At this point you can rename the split parts more appropriately, like
- "sitaram@laptop.pub" and "sitaram@desktop.pub" or whatever. *Please check
- the files to make sure this worked properly*
-
- * Check all your changes to your gitolite-admin clone, commit, and push.
diff --git a/doc/http.mkd b/doc/http.mkd
deleted file mode 100644
index 3b9809e..0000000
--- a/doc/http.mkd
+++ /dev/null
@@ -1,157 +0,0 @@
-# how to setup gitolite to use smart http mode
-
-**Note**: "smart http" refers to the feature that came with git 1.6.6, late
-2009 or so. The base documentation for this is `man git-http-backend`. Do
-**NOT** read `Documentation/howto/setup-git-server-over-http.txt` and think
-that is the same or even relevant -- that is from 2006 and is quite different
-(and arguably obsolete).
-
-## WARNINGS and important notes
-
- * Please read [authentication versus authorisation][auth] first, and make
- sure you understand what is gitolite's responsibility and what isn't.
-
- * I have tested this only on stock Fedora 16; YDMV.
-
-## assumptions:
-
- * Apache 2.x and git installed.
- * Httpd runs under the "apache" userid; adjust instructions below if not.
- * Similarly for "/var/www" and other file names/locations.
-
-## instructions
-
-The detailed instructions I used to have in g2 have now been replaced by a
-script called `t/smart-http.root-setup`. **Do NOT run this script as is -- it
-is actually meant for my testing setup and deletes stuff**. However, it does
-provide an excellent (and working!) narration of what you need to do to
-install gitolite in smart http mode.
-
-Make a copy of the script, go through it carefully, (possibly removing lines
-that delete files etc.), change values per your system, and only then run it.
-
-Note that the `GIT_PROJECT_ROOT` variable (see "man
-git-http-backend") is no longer optional. Make sure you set it to some place
-outside apache's `DOCUMENT_ROOT`.
-
-## Making repositories available to both ssh and http mode clients
-
-This section has been contributed by Thomas Hager (duke at sigsegv dot at).
-
-Assumptions:
-
- * Apache 2.x with CGI and Suexec support installed.
- * Git and Gitolite installed with user "git" and group "git", and pubkey SSH
- access configured and working.
- * Git plumbing installed to /usr/libexec/git-core
- * Gitolite base located at /opt/git
- * Apache `DOCUMENT_ROOT` set to /var/www
- * Apache runs with user www and group www
-
-Please adjust the instructions below to reflect your setup (users and paths).
-
-Edit your .gitolite.rc and add
-
- $ENV{PATH} .= ":/opt/git/bin";
-
-at the very top (as described in `t/smart-http.root-setup`).
-
-Next, check which document root your Apache's suexec accepts:
-
- # suexec -V
- -D AP_DOC_ROOT="/var/www"
- -D AP_GID_MIN=100
- -D AP_HTTPD_USER="www"
- -D AP_LOG_EXEC="/var/log/apache/suexec.log"
- -D AP_SAFE_PATH="/usr/local/bin:/usr/bin:/bin"
- -D AP_UID_MIN=100
- -D AP_USERDIR_SUFFIX="public_html"
-
-We're interested in `AP_DOC_ROOT`, which is set to `/var/www` in our case.
-
-Create a `bin` and a `git` directory in `AP_DOC_ROOT`:
-
- install -d -m 0755 -o git -g git /var/www/bin
- install -d -m 0755 -o www -g www /var/www/git
-
-`/var/www/git` is just a dummy directory used as Apache's document root (see below).
-
-Next, create a shell script inside `/var/www/bin` named `gitolite-suexec-wrapper.sh`,
-with mode **0700** and owned by user and group **git**. Add the following content:
-
- #!/bin/bash
- #
- # Suexec wrapper for gitolite-shell
- #
-
- export GIT_PROJECT_ROOT="/opt/git/repositories"
- export GITOLITE_HTTP_HOME="/opt/git"
-
- exec ${GITOLITE_HTTP_HOME}/gitolite-source/src/gitolite-shell
-
-Edit your Apache's config to add http pull/push support, preferably in
-a dedicated `VirtualHost` section:
-
-
- ServerName git.example.com
- ServerAlias git
- ServerAdmin you@example.com
-
- DocumentRoot /var/www/git
-
- Options None
- AllowOverride none
- Order allow,deny
- Allow from all
-
-
- SuexecUserGroup git git
- ScriptAlias /git/ /var/www/bin/gitolite-suexec-wrapper.sh/
- ScriptAlias /gitmob/ /var/www/bin/gitolite-suexec-wrapper.sh/
-
-
- AuthType Basic
- AuthName "Git Access"
- Require valid-user
- AuthUserFile /etc/apache/git.passwd
-
-
-
-This Apache config is just an example, you probably should adapt the authentication
-section and use https instead of http!
-
-Finally, add an `R = daemon` access rule to all repositories you want to
-make available via http.
-
-## usage
-
-### client side
-
-Git URLs look like `http://user:password@server/git/reponame.git`.
-
-The custom commands, like "info", "expand" should be handled as follows. The
-command name will come just after the `/git/`, followed by a `?`, followed by
-the arguments, with `+` representing a space. Here are some examples:
-
- # ssh git@server info
- curl http://user:password@server/git/info
- # ssh git@server info repopatt
- curl http://user:password@server/git/info?repopatt
- # ssh git@server info repopatt user1 user2
- curl http://user:password@server/git/info?repopatt+user1+user2
-
-With a few nice shell aliases, you won't even notice the horrible convolutions
-here ;-) See t/smart-http for a couple of useful ones.
-
-### server side
-
-The 'gitolite' command (for example, 'gitolite compile', 'gitolite query-rc',
-and so on) *can* be run on the server, but it's not straightforward. Assuming
-you installed exactly as given in this document, you should
-
- * get a shell by using, say, `su -s /bin/bash - apache`
- * run `export HOME=$HOME/gitolite-home`
- * run `export PATH=$PATH:$HOME/bin`
-
-and *then* you can run `gitolite `
-
diff --git a/doc/index.mkd b/doc/index.mkd
deleted file mode 100644
index 9552975..0000000
--- a/doc/index.mkd
+++ /dev/null
@@ -1,66 +0,0 @@
-# Hosting git repositories
-
-Gitolite allows you to setup git hosting on a central server, with
-fine-grained access control and many more powerful features.
-
-Here's more on [what][] it is and [why][] you might need it.
-
-
-
-## #g2 (for older gitolite (v1.x and v2.x) users)
-
-For users of gitolite v2.x (call it "g2" for convenience),
-
- * [Why][g3why] I rewrote gitolite.
- * Development [status][dev-status].
- * Information on [migrating][migr] from g2 to g3.
-
-
-
-## #ql quick links
-
- * [Trying][trying] out gitolite.
- * Minimum [requirements][req].
- * Here's how to do a [quick install, setup, and clone][qi].
- * Don't know ssh well enough? [Learn][ssh]. It's **IMPORTANT**.
- * Add [users][] and [repos][].
- * Learn about fine-grained access control with the [conf][] file.
- * Explain gitolite to your [users][user].
-
-The rest of the documentation is in the "master index" link at the top of each
-page on this website. This is the first place you should search when looking
-for specific information.
-
-## #what What is gitolite?
-
-Gitolite is an access control layer on top of git. Here are the features that
-most people see:
-
- * Use a single unix user ("real" user) on the server.
- * Provide access to many gitolite users:
- * they are not "real" users,
- * they do not get shell access.
- * Control access to many git repositories:
- * read access controlled at the repo level,
- * write access controlled at the branch/tag/file/directory level,
- including who can rewind, create, and delete branches/tags.
- * Can be installed without root access, assuming git and perl are already
- installed.
- * Authentication is most commonly done using sshd, but you can also use
- [http][] if you prefer (this may require root access).
-
-## #contact contact
-
- * author: sitaramc@gmail.com, sitaram@atc.tcs.com
- * mailing list: gitolite@googlegroups.com
- * list subscribe address : gitolite+subscribe@googlegroups.com
- * IRC: #git and #gitolite on freenode. Note that I live in India (UTC+0530
- time zone).
-
-## #license license
-
-The gitolite *code* is released under GPL v2. See COPYING for details.
-
-The gitolite documentation is provided under a [Creative Commons
-Attribution-NonCommercial-ShareAlike 3.0 Unported
-License](http://creativecommons.org/licenses/by-nc-sa/3.0/).
diff --git a/doc/install.mkd b/doc/install.mkd
deleted file mode 100644
index 519ab52..0000000
--- a/doc/install.mkd
+++ /dev/null
@@ -1,265 +0,0 @@
-# installing gitolite
-
-**NOTE**: if you're migrating from g2, there are some
-settings that MUST be dealt with **before** running `gitolite setup`; please
-start [here][migr]. RTFM is *mandatory* for migrations.
-
-----
-
-This is the first step in using gitolite, and happens on the server. It is
-followed by [setup][], then [clone][].
-
-----
-
-[[TOC]]
-
-----
-
-## notes and naming conventions
-
-Gitolite uses a single "real" (i.e., unix) user to provide secure access to
-git repos to any number of "virtual" users, without giving them a shell.
-
-The real user used is called the **hosting user**. Typically this user is
-*git*, and that is what we will use throughout the documentation. However
-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.
- * Which also means you can have several hosting users on the same machine.
- * The URLs used will be of the form `git@host:reponame` (or its longer
- equivalent starting with `ssh://`). The `.git` at the end is optional. I
- recommend you leave it out, so your reponames are consistent with what the
- conf file uses.
-
-## #req requirements
-
-### your skills
-
- * If you're installing gitolite, you're a "system admin", like it or not.
- Ssh is therefore a necessary skill. Please take the time to learn at
- least enough to get passwordless access working.
-
- * You also need to be somewhat familiar with git itself. You cannot
- administer a whole bunch of git repositories if you don't know the basics
- of git.
-
- * Some familiarity with Unix and shells is probably required.
-
- * Regular expressions are a big part of gitolite in many places but
- familiarity is not necessary to do *basic* access control.
-
-### server
-
- * Any Unix system with a posix compatible "sh".
- * Git version 1.6.6 or later.
- * Perl 5.8.8 or later.
- * Openssh (almost any version). Optional if you're using [smart
- http][http].
- * A dedicated Unix userid to be the hosting user, usually "git" but it can
- be any user, even your own normal one. (If you're using an RPM/DEB the
- install probably created one called "gitolite").
-
-Also see the [WARNINGS][] page for more on what gitolite expects on the server
-side.
-
-### client
-
- * Openssh client.
- * Git 1.6.6 or later. Almost any git client will work, as long as it knows
- how to use ssh keys and send the right one along.
-
-## getting the software
-
- git clone git://github.com/sitaramc/gitolite
-
-## 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.
-
-"Installation" consists of the following options:
-
-1. Keep the sources anywhere and use the full path to run the `gitolite`
- command.
-2. Keep the sources anywhere and symlink *just* the `gitolite` program to
- some directory on your `$PATH`.
-3. Copy the sources somewhere and use that path to run the `gitolite`
- command.
-
-Option 2 is the best for general use.
-
-There is a program called 'install' that helps you do these easily. Assuming
-your cloned the repo like this:
-
- git clone git://github.com/sitaramc/gitolite
-
-you can run the 'install' command in 3 different ways:
-
- # option 1
- gitolite/install
-
- # option 2
- gitolite/install -ln
- # defaults to $HOME/bin (which is assumed to exist)
- # ** or **
- # or use a specific directory (please supply full path):
- gitolite/install -ln /usr/local/bin
-
- # option 3
- # (again, please supply a full path)
- gitolite/install -to /usr/local/gitolite/bin
-
-Creating a symlink doesn't need a separate program but 'install' also runs
-`git describe` to create a VERSION file, which, trust me, is important!
-
-**Next step**: run [**setup**][setup].
-
-## upgrading
-
- * Update your clone of the gitolite source.
- * Repeat the install command you used earlier (make sure you use the same
- arguments as before).
- * Run `gitolite setup`.
-
-## #package packaging gitolite
-
-Gitolite has broad similarities to git in terms of packaging requirements.
-
- * Git has 150 executables to marshal and put somewhere. Gitolite has the
- directories `commands`, `lib`, `syntactic-sugar`, `triggers`, and `VREF`.
-
- It doesn't matter what this directory is. As an example, Fedora keeps
- git's 150 executables in /usr/libexec/git-core, so /usr/libexec/gitolite
- may be a good choice; it's upto you.
-
- *The rest of this section will assume you chose /usr/libexec/gitolite as
- the location, and that this location contains the 5 directories named
- above*.
-
- * Git has the `GIT_EXEC_PATH` env var to point to this directory. Gitolite
- has `GL_BINDIR`. However, in git, the "make" process embeds a suitable
- default into the binary, making the env var optional.
-
-With that said, here's one way to package gitolite:
-
- * Put the executable `gitolite` somewhere in PATH. Put the executable
- `gitolite-shell` in /usr/libexec/gitolite (along with those 5 directories).
-
- Change the 2 assignments to `$ENV{GL_BINDIR}`, one in 'gitolite', one in
- 'gitolite-shell', to "/usr/libexec/gitolite" from `$FindBin::RealBin`.
- This is equivalent to "make" embedding the exec-path into the executable.
-
- **OR**
-
- Put both executables `gitolite` and `gitolite-shell` also into
- /usr/libexec/gitolite (i.e., as siblings to the 5 directories mentioned
- above). Then *symlink* `/usr/libexec/gitolite/gitolite` to some directory
- in the PATH. Do not *copy* it; it must be a symlink.
-
- Gitolite will find the exec-path by following the symlink.
-
- * The `Gitolite` subdirectory in `/usr/libexec/gitolite/lib` can stay right
- there, **OR**, if your distro policies don't allow that, can be put in any
- directory in perl's `@INC` path (such as `/usr/share/perl5/vendor_perl`).
-
- * Finally, a file called `/usr/libexec/gitolite/VERSION` must contain a
- suitable version string.
-
-## #migr migrating
-
-This section is about migrating from older gitolite to
-"g3". If you're migrating from gitosis, see [here][gsmigr].
-
-First things first: g2 will be supported for a good long time for critical
-bugs, although enhancements and new features won't happen.
-
-If you're an existing (gitolite v1.x or v2.x) user, and wish to migrate , here
-are the steps:
-
-### pre-migration checks
-
-1. Check the [dev-status][] page to make sure all the features you want have
- been implemented in g3.
-
-2. Read the [g2 migration][g2migr] page to see what changes affect you and
- your users, and how much time it might take you to migrate. (The closer
- you were to a default install of the old gitolite, the less time a
- migration will take.)
-
- This includes at least running `check-g2-compat` to see what are the big
- issues you might need to address during the migration.
-
-### the actual migration
-
-(Note: You may also like the [example migration][g2migr-example] page).
-
-**Note**: nothing in any of the gitolite install/setup/etc will ever touch the
-*data* in any repository except the gitolite-admin repo. The only thing it
-will normally touch in normal repos is the `update` hook.
-
-**Note: all migration happens on the server; you do not need your
-workstation**.
-
-1. Carefully wipe out the old gitolite:
-
- * The **code**
-
- * Delete or move away all the old gitolite scripts. Check the path
- to the gl-auth-command in `~/.ssh/authorized_keys` if you forgot
- where you put them.
-
- * Delete or move away the two directories named in the two variables
- `GL_PACKAGE_CONF` and `GL_PACKAGE_HOOKS` in `~/.gitolite.rc`.
-
- * The **rc file**
-
- * Rename `~/.gitolite.rc` to something else.
-
- * The **admin repo**
-
- * clone `~/repositories/gitolite-admin.git` to someplace safe
- * then delete `~/repositories/gitolite-admin.git`
-
- (Make sure you do not delete any other repos!)
-
- * The **admin directory**.
-
- * If you need to preserve logs, move the ~/.gitolite/logs` directory
- somewhere else.
-
- * If you added any custom hooks and wish to preserve them, move the
- ~/.gitolite/hooks` directory somewhere else.
-
- * Delete `~/.gitolite`.
-
-2. Read about [presetting][rc-preset] the rc file; if you're using any
- variables listed as requiring preset, follow those instructions to create
- your new rc file.
-
-3. Install gitolite g3; see [quick install and setup][qi] or [install][]
- followed by [setup][]. However, the 'setup' step need not supply a
- private key. You can run it as `gitolite setup -a admin`.
-
- NOTE: ignore any 'split conf not set, gl-conf present...' errors at this
- time. You may see none, some, or many. It does not matter right now.
-
-4. Make sure your gitolite-admin clone has the correct pubkey for the
- administrator in its `keydir` directory, then run [`gitolite push
- -f`][bypass] to overwrite the "default" admin repo created by the install.
-
-5. Handle any errors, look for migration issues, etc., as described in the
- links at the top of this page.
-
- This also includes building up your new `~/.gitolite.rc` file.
-
-You're done.
diff --git a/doc/ips.mkd b/doc/ips.mkd
deleted file mode 100644
index dcbff02..0000000
--- a/doc/ips.mkd
+++ /dev/null
@@ -1,104 +0,0 @@
-## 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?)
diff --git a/doc/locking.mkd b/doc/locking.mkd
deleted file mode 100644
index 2799003..0000000
--- a/doc/locking.mkd
+++ /dev/null
@@ -1,160 +0,0 @@
-# locking binary files
-
-Locking is useful to make sure that binary files (office docs, images, ...)
-don't get into a merge state. (If you think it's not a big
-deal, you have never manually merged independent changes to an ODT or
-something!)
-
-When git is used in a truly distributed fashion, locking is impossible.
-However, in most corporate setups, there is a single central server acting as
-the canonical source of truth and collaboration point for all developers. In
-this situation it should be possible to at least prevent commits from being
-pushed that contains changes to files locked by someone else.
-
-The two "lock" programs (one a command that a user uses, and one a VREF that
-the admin adds to a repo's access rules) together attempt to achieve this.
-
-Of course, locking by itself is not quite enough. You may still get into
-merge situations if you make changes in branches. For best results you should
-actually keep all the binary files in their own branch, separate from the ones
-containing source code.
-
-----
-
-[[TOC]]
-
-## problem description
-
-Our users are alice, bob, and carol. Our repo is foo. It has some "odt"
-files in the "doc/" directory. We want to make sure these odt files never get
-into a "merge" situation.
-
-## admin/setup
-
-First, someone with shell access to the server must add 'lock' to the
-"COMMANDS" list in the rc file.
-
-Next, the gitolite.conf file should have something like this:
-
- repo foo
- <...other rules...>
- - VREF/lock = @all
-
-However, see below for the difference between "RW" and "RW+" from the point of
-view of this feature and adjust permissions accordingly.
-
-## user view
-
-Here's a summary:
-
- * Any user with "W" permissions to any branch in the repo can "lock" any
- file. Once locked, no other user can push changes to that file, *in any
- branch*, until it is unlocked.
- * Any user with "+" permissions to any branch in the repo can "break" a lock
- held by someone else if needed.
-
-For best results, everyone on the team should:
-
- * Switch to the branch containing the binary files when wanting to make a
- change.
- * Run 'git pull' or eqvt, then lock the binary file(s) before editing them.
- * Finish the editing task as quickly as possible, then commit, push, and
- unlock the file(s) so others are not needlessly blocked.
- * Understand that breaking a lock require additional, (out of band)
- communication. It is upto the team's policies what that entails.
-
-## detailed example
-
-Alice declares her intent to work on "d1.odt":
-
- $ git pull
- $ ssh git@host lock -l foo doc/d1.odt
-
-Similarly Bob starts on "d2.odt"
-
- $ git pull
- $ ssh git@host lock -l foo doc/d2.odt
-
-Carol makes some changes to d2.odt (**without attempting to lock the file or
-checking to see if it is already locked**) and pushes:
-
- $ ooffice doc/d2.odt
- $ git add doc/d2.odt
- $ git commit -m 'added footnotes to d2 in klingon'
- $ git push
- <...normal push progress output...>
- remote: FATAL: W VREF/lock testing carol DENIED by VREF/lock
- remote: 'doc/d2.odt' locked by 'bob'
- remote: error: hook declined to update refs/heads/master
- To u2:testing
- ! [remote rejected] master -> master (hook declined)
- error: failed to push some refs to 'carol:foo'
-
-Carol backs out her changes, but saves them away for a "manual merge" later.
-
- git reset HEAD^
- git stash save 'klingon changes to d2.odt saved for possible manual merge later'
-
-Note that this still represents wasted work in some sense, because Carol would
-have to somehow re-apply the same changes to the new version of d2.odt after
-pulling it down. **This is because she did not lock the file before making
-changes on her local repo. Educating users in doing this is important if this
-scheme is to help you.**
-
-She now decides to work on "d1.odt". However, she has learned her lesson and
-decides to follow the protocol described above:
-
- $ git pull
- $ ssh git@host lock -l foo doc/d1.odt
- FATAL: 'doc/d1.odt' locked by 'alice' since Sun May 27 17:59:59 2012
-
-Oh damn; can't work on that either.
-
-Carol now decides to see what else there may be. Instead of checking each
-file to see if she can lock it, she starts with a list of what is already
-locked:
-
- $ ssh git@host lock -ls foo
-
- # locks held:
-
- alice doc/d1.odt (Sun May 27 17:59:59 2012)
- bob doc/d2.odt (Sun May 27 18:00:06 2012)
-
- # locks broken:
-
-Aha, looks like only d1 and d2 are locked. She picks d3.odt to work on. This
-time, she starts by locking it:
-
- $ ssh git@host lock -l foo doc/d3.odt
- $ ooffice doc/d3.odt
- <...etc...>
-
-Meanwhile, in a parallel universe where d3.odt doesn't exist, and Alice has
-gone on vacation while keeping d1.odt locked, Carol breaks the lock. Carol
-can do this because she has RW+ permissions for the repository itself.
-
-However, protocol in this team requires that she get email approval from the
-team lead before doing this and that Alice be in CC in those emails, so she
-does that first, and *then* she breaks the lock:
-
- $ git pull
- $ ssh git@host lock --break foo doc/d1.odt
-
-She then locks d1.odt for herself:
-
- $ ssh git@host lock -l foo doc/d1.odt
-
-When Alice comes back, she can tell who broke her lock and when:
-
- $ ssh git@host lock -ls foo
-
- # locks held:
-
- carol doc/d1.odt (Sun May 27 18:17:29 2012)
- bob doc/d2.odt (Sun May 27 18:00:06 2012)
-
- # locks broken:
-
- carol doc/d1.odt (Sun May 27 18:17:03 2012) (locked by alice at Sun May 27 17:59:59 2012)
-
diff --git a/doc/master-toc.mkd b/doc/master-toc.mkd
deleted file mode 100644
index 77cd40f..0000000
--- a/doc/master-toc.mkd
+++ /dev/null
@@ -1,170 +0,0 @@
-# gitolite documentation
-
-## [Introduction][index]
-
- * (for [older][g2] gitolite (v1 or v2) users)
- * [quick links][ql]
- * [what][] is gitolite
- * [why][] might you need it
- * [contact][] info, mailing list, IRC channel
- * [license][] info
-
-## help for [emergencies][]
-
- * [lost][lost-key] admin key/access
- * [bypass][]ing gitolite
- * [clean][]ing out a botched install
- * [common][ce] errors
- * [uncommon][ue] errors
- * things that are [not gitolite problems][ngp]
-
-## [WARNINGS][]
-
-
-## [testing][] gitolite
- * [trying][] out gitolite
-
-
-## [quick][qi] install, setup, and clone
-
-
-## [install][]
-
- * notes and naming conventions
- * requirements
- * your skills
- * server
- * client
- * getting the software
- * the actual install
- * upgrading
- * packaging gitolite
- * [migr][]ating
-
-## [setup][]
-
-
-## [clone][]
-
-
-## gitolite [admin][]istration
-
- * ([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)
- * ([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)
- * special: '@all'
- * (link: storing user group info in LDAP)
- * adding and removing [users][]
- * multiple keys per user
- * adding and removing [repos][]
- * renaming repos
- * defining access [rules][]
- * what does a rule look like?
- * when are the rules checked?
- * how are the rules matched?
- * summary of [permissions][permsum]
- * additional topics
- * [rule accumulation][rule-accum]
- * applying [deny rules][deny-rules] during the pre-git check
- * ([link][refex]: refexes)
- * ([link][write-types]: different types of write operations)
- * ([link][vref]: virtual refs)
- * gitolite [options][]
- * "[git config][git-config]" keys and values
- * ["wild"][wild] repos (user created repos)
- * quick introduction
- * (admin) declaring wild repos in the conf file
- * (user) [creating][create] a specific repo
- * repo patterns
- * roles
- * adding other roles
- * [IMPORTANT WARNING ABOUT THIS FEATURE][rolenamewarn]
- * listing wild repos
- * deleting wild repos
-
-## what your [user][]s need to know
-
-
-## [special][] features/setups
-
- * putting 'repositories' and '.gitolite' [somewhere else][elsewhere]
- * [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
- * ([link][partial-copy]: faking selective READ control)
- * using pubkeys obtained [from elsewhere][keysonly]
- * ([link][pushcode]: updating code via the admin repo)
-
-## interfacing with [external][] tools
-
- * gitweb
- * changing the [UMASK][umask]
- * git-daemon
-
-## [mirroring][]
-
-
-## [rare][]/one-time activities
-
- * moving [existing][] repos into gitolite
- * [moving][] servers
-
-## [customisation][cust]
-
- * where do you put custom code?
- * types of non-core programs
- * [commands][]
- * [hooks][]
- * syntactic [sugar][]
- * ([link][triggers]: triggers)
- * ([link][vref]: VREFs)
- * ([link][non-core]: non-core programs shipped with gitolite)
- * [developer notes][dev-notes] -- writing custom code
- * environment variables and other inputs
- * APIs
- * the shell API
- * the perl API
- * writing your own...
- * hooks
- * commands
- * trigger programs
- * sugar
-
-## [non-core][] programs shipped with gitolite
-
- * commands
- * syntactic sugar
- * triggers
- * ([link][vref]: VREFs)
- * special cases
- * [partial-copy][]: selective read control for branches
-
-## background info
-
- * [files and directories][files] involved in install+setup
- * [auth][]entication versus authorisation
- * interfacing with [other authentication][otherauth] systems
- * getting user group info from [LDAP][ldap]
- * [ssh][]
- * [regular expressions][regex]
-
-## contributed software, tools, and documentation
-
- * TBD
-
-## TBD
-
- * log file format, LOG_EXTRA
- * hub
- * mob branches
- * password access
diff --git a/doc/mirroring.mkd b/doc/mirroring.mkd
deleted file mode 100644
index 7b07882..0000000
--- a/doc/mirroring.mkd
+++ /dev/null
@@ -1,235 +0,0 @@
-# mirroring using gitolite
-
-**WARNING** existing gitolite mirroring users please note:
-**there are [significant changes][g2i-mirroring]** in syntax and usage
-compared to g2. If you're not the kind who reads documentation before doing
-serious system admin things, well... good luck!
-
-----
-
-[[TOC]]
-
-----
-
-Mirroring is simple: you have one "master" server and one or more "slave"
-servers. The slaves get updates only from the master; to the rest of the
-world they are at best read-only.
-
-Gitolite extends this simple notion in the following ways:
-
- * Different masters and sets of slaves for different repos
-
- This lets you do things like:
-
- * Use the server closest to *most* of its developers as the master for
- that repo.
- * Not mirror a repo at all to some servers.
- * Have repos that are purely local to a server (not mirrored at all).
- * Negotiate mirroring with servers that are not even under your control.
- * Push to a slave on demand or via cron (helps deal with bandwidth or
- connectivity constraints).
-
- * Pushes to a slave can be transparently forwarded to the real master.
-
- Your developers need not worry about where a repo's master is -- they just
- write to their local mirror for *all* repos, even if their local mirror is
- only a slave for some.
-
-## caveats
-
- * Mirroring will never *create* a repo on a slave; it has to exist and be
- prepared to receive updates from the master.
-
- However, there is limited support for auto-creating wild card repos and
- sending 'perms' info across, with the following caveats at present. (Some
- of this text won't make sense unless you know what those features are).
-
- * *WARNING: it does NOT make sense to mirror wild repos in setups where
- the authentication data is not the same (i.e., where "alice" on the
- master and "alice" on a slave maybe totally different people)*.
-
- * This has only been minimally tested. For example, complex setups or
- asymmetric configs on master and slave, etc. have NOT been tested.
-
- * Permission changes will only propagate on the next 'git push'. Of
- course, if you know the name of the slave server, you can run
-
- ssh git@host mirror push slave-server-name repo-name
-
- * Using 'perms' on a slave is allowed but will neither propagate nor
- persist. They will be overwritten by whatever perms the master has
- (even if it is an empty set) on the next 'git push'.
-
- * As with lots of extra features in gitolite, smart http support is not
- on my radar. Don't ask.
-
- Please test it out and let me know if something surprising happens. Be
- aware that I have been known to claim bugs are features if I don't have
- time to fix them immediately :-)
-
- * Mirroring is only for git repos. Ancillary files like gl-creator and
- gl-perms in the repo directory are not mirrored; you must do that
- separately. Files in the admin directory (like log files) are also not
- mirrored.
-
- * If you ever do a [bypass push][bypass], mirroring will not work.
- Mirroring checks also will not work -- for example, you can push to a
- slave, which is not usually a good idea. So don't bypass gitolite if the
- repo is mirrored!
-
-## setting up mirroring
-
-This is in two parts: the initial setup and the rc file, followed by the conf
-file settings and syntax.
-
-### the initial setup and the rc file
-
-On **each** server:
-
- * Install gitolite normally. Make clones of the server's 'gitolite-admin'
- repo on your workstation so you can admin them all from one place.
-
- * Give the server a short, simple, "hostname" and set the HOSTNAME in the
- rc file to this name, for example 'mars'.
-
- * Run ssh-keygen if needed and get an ssh key pair for the server. Copy the
- public key to a common area and name it after the host, but with 'server-'
- prefixed. For example, the pubkey for server 'mars' must be stored as
- 'server-mars.pub'.
-
- * Copy all keys to all the admin repo clones on your workstation and and add
- them as usual. This is an `O(N^2)` operation ;-)
-
- You may have guessed that the prefix 'server-' is special, and
- distinguishes a human user from a mirroring peer.
-
- * Create "host" aliases to refer to all other machines. See [here][ssh-ha]
- for what/how.
-
- The host alias for a host (in all other machines' `~/.ssh/config` files)
- MUST be the same as the `HOSTNAME` in the referred host's
- `~/.gitolite.rc`. Gitolite mirroring **requires** this consistency in
- naming; things will NOT work otherwise.
-
- Normally you should be able to build one common file and append it to all
- the servers' `~/.ssh/config` files.
-
- * The following **MUST** work for **each pair** of servers that must talk to
- each other:
-
- # on server mars
- ssh phobos info
- # the response MUST start with "hello, server-mars..."
-
- Note the exact syntax used; variations like "ssh git@phobos.example.com
- info" are NOT sufficient. That is why you need the ssh host aliases.
-
- Check this command from *everywhere to everywhere else*, and make sure you
- get expected results. **Do NOT proceed otherwise.**
-
- * Setup the gitolite.conf file on all the servers. If the slaves are to be
- exact copies of the master, you need to do the complete configuration only
- on the master; the slaves can have just this:
-
- repo gitolite-admin
- RW+ =
-
- option mirror.master = mars
- option mirror.slaves = phobos
-
- because on the first push to the master it will update all the slaves
- anyway.
-
- * When that is all done and tested, **enable mirroring** by going through
- the rc file and uncommenting all the lines mentioning `Mirroring`.
-
-### conf file settings and syntax
-
-Mirroring is defined by the following [options][]. You can have different
-settings for different repos, and of course some repos may not have any mirror
-options at all -- they are then purely local.
-
- repo foo
- ...access rules...
-
- option mirror.master = mars
- option mirror.slaves = phobos deimos
- option mirror.redirectOK = all
-
-The first line is easy, since a repo can have only one master.
-
-The second is a space separated list of hosts that are all slaves. You can
-have several slave lists, as long as the config key starts with
-'mirror.slaves' and is unique. For example.
-
- option mirror.slaves-1 = phobos deimos
- option mirror.slaves-2 = io europa
- option mirror.slaves-3 = ganymede callisto
-
-Do not repeat a key; then only the last line for that key will be effective.
-
-## redirected pushes
-
-**Please read carefully; there are security implications if you enable this
-for mirrors NOT under your control**.
-
-Normally, a master, (and *only* a master), pushes to a slave, and the slaves
-are "read-only" to the users. Gitolite allows a *slave* to receive pushes
-from a user and transparently redirect them to the *master*.
-
-This simplifies things for users in complex setups, letting them use their
-local mirror for both fetch and push access to all repos.
-
-Just remember that if you do this, **authentication** happens on the slave,
-but **authorisation** is on the master. The master is trusting the slave to
-authenticate the user correctly, *and* use the same authentication data (i.e.,
-user alice on the slave should be guaranteed to be the same as user alice on
-the master).
-
-The syntax for enabling this is one of these:
-
- option mirror.redirectOK = all
- option mirror.redirectOK = phobos deimos
-
-The first syntax trusts all valid slaves to redirect user pushes, while the
-second one trusts only some slaves.
-
-Note that you cannot redirect gitolite commands (like perms, etc).
-
-## #sync manually synchronising a slave repo
-
-You can use the `gitolite mirror push` command on a master to manually
-synchronise any of its slaves. Try it with `-h` to get usage info.
-
-Tip: if you want to do this to all the slaves, try this:
-
- for s in `gitolite git-config -r reponame mirror.slave | cut -f3`
- do
- gitolite mirror push $s reponame
- done
-
-This command can also be run remotely; run `ssh git@host mirror -h` for
-details.
-
-## #HOSTNAME appendix A: HOSTNAME substitution
-
-Wherever gitolite sees the word `%HOSTNAME`, it will replace it with the
-HOSTNAME supplied in the rc file, if one was supplied. This lets you maintain
-configurations for all servers in one repo, yet havethem act differently on
-different servers, by saying something like:
-
- subconf "%HOSTNAME/*.conf"
-
-You can use it in other places also, for example:
-
- RW+ VREF/NAME/subs/%HOSTNAME/ = @%HOSTNAME-admins
-
-(you still have to define @mars-admins, @phobos-admins, etc., but the actual
-VREF is now one line instead of one for each server!)
-
-## appendix B: efficiency versus paranoia
-
-If you're paranoid enough to use mirrors, you should be paranoid enough to
-set this on each server, despite the possible CPU overhead:
-
- git config --global receive.fsckObjects true
diff --git a/doc/mkdoc b/doc/mkdoc
deleted file mode 100755
index 72470d3..0000000
--- a/doc/mkdoc
+++ /dev/null
@@ -1,126 +0,0 @@
-#!/usr/bin/perl
-
-# cd /doc; ./mkdoc # --> creates ../html/*.html
-
-my $MKD = "./Markdown.pl";
-
-use 5.10.0;
-use strict;
-use warnings;
-use lib '../src/lib/Gitolite/Test';
-use Tsh;
-
-$ENV{TSH_ERREXIT} = 1;
-
-try "
- mkdir ../html; ok
- git status -s -uno; !/./
- git log --oneline -1
-" or die 1;
-
-my $head = (lines())[0];
-
-main();
-
-try "
- git checkout gh-pages; ok
- git reset --hard github/gh-pages; ok
- cd ..; ok
- git rm *.html; ok
- mv html/*.html .; ok
- git add *.html; ok
- git commit -m '$head'; ok
- git checkout master; ok
- rmdir html; ok
-" or die 2;
-
-sub main {
- chomp(@ARGV = `find . -name "*.mkd" | cut -c3-`) if not @ARGV;
- @ARGV = grep { /./ } @ARGV;
- my @save = @ARGV;
- my $css_block = join("", );
-
- my %ct; # chapter tocs
- my %title;
- my $mf = '';
- my $fh;
-
- while (<>) {
- $ARGV =~ /^(?:.*\/)?([^\/]+)\.mkd$/;
- my $b = $1;
-
- if (/^(#+) (?:#(\S+) )?(.*)/) {
- $title{$b} ||= $3;
- if ( length($1) == 1 ) {
- $ct{$b} .= "\n";
- $ct{$b} .= " * [$3][$b]\n";
- $mf .= "[$b]: $b.html\n";
- } else {
- $ct{$b} .= " " x ( 4 * ( length($1) - 1 ) );
- $ct{$b} .= " * ";
- $ct{$b} .= (
- $2
- ? "[$3][$2]"
- : "$3"
- );
- $ct{$b} .= "\n";
- $mf .= "[$2]: $b.html" . ($2 ne $b ? "#$2" : "") . "\n" if $2;
- }
- }
- }
-
- # open($fh, ">", "master-toc.mk2")
- # and print $fh $mt
- # and close $fh;
-
- # after this, do this for every mkd (including the master-toc.mkd)
-
- # cat $css_block > $base.html
- # cat $base.mkd $mf | $MKD >> $base.html
-
- for my $mkd (@save) {
- $mkd =~ /^(?:.*\/)?([^\/]+)\.mkd$/;
- my $b = $1;
-
- my $css = $css_block;
- $css =~ s/%TITLE/$title{$b} || $b/e;
-
- open($fh, ">", "../html/$b.html")
- and print $fh $css
- and close $fh;
-
- my $mkt = `cat $mkd`;
- $mkt =~ s/^(#+) #(\S+) /$1 <\/a> /mg;
- $mkt =~ s/^\[\[TOC\]\]/$ct{$b}/mg;
- open($fh, "|-", "$MKD >> ../html/$b.html")
- and print $fh $mkt, "\n\n", $mf
- and close $fh;
- }
-}
-
-__DATA__
-
-
- %TITLE
-
-
-
-
- master TOC
-|
- main page
-|
- license
-
-
-This is for gitolite "g3"; for older (v2.x) documentation click here
-
diff --git a/doc/non-core.mkd b/doc/non-core.mkd
deleted file mode 100644
index dc0e188..0000000
--- a/doc/non-core.mkd
+++ /dev/null
@@ -1,131 +0,0 @@
-# non-core programs shipped with gitolite
-
-----
-
-[[TOC]]
-
-----
-
-## commands
-
-A list of these commands can be obtained by running `gitolite help` on the
-server. A different (and probably much smaller) list can be obtained by a
-remote user running `ssh git@host help`.
-
-All the commands that ship with gitolite will respond to `-h`; please report a
-bug to me if they don't.
-
-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!)
-
-Here's a list of some commands where additional information is available
-elsewhere:
-
- * 'info' -- documented [here][info]
- * 'mirror' -- documented [here][sync]
- * 'perms' -- get/set the gl-perms file; see [perms][] for more
- * 'sskm' -- self-service key management, see [sskm][] for more
-
-## syntactic sugar
-
-The following "sugar" programs are available:
-
- * Continuation-lines -- allow the use of C-style backslash escaped
- continuation lines in the conf file. I don't like it but some people do,
- and now I can support them without bulking up the "core" conf parser!
-
- * Keysubdirs-as-groups -- someone wanted the sub-directory name (of
- "keydir/") in which the pubkey was placed to be a group to which the user
- automatically belonged. A very unusual requirement, and one which would
- *never* have seen the light of day in g2, but in g3 it's easy, and doesn't
- affect anyone else!
-
- (Note: the last component of the directory path is used if there are more
- than one level between "keydir/" and the actual file).
-
-## triggers
-
-Most triggers need to be enabled by adding or uncommenting an appropriate line
-in the [rc][] file. There are enough examples in there for the syntax to not
-need explanation.
-
-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:
-
- * Shell -- see "giving shell access to gitolite users" in [this][sts] page.
- * Mirroring -- see [doc/mirroring.mkd][mirroring]
- * partial-copy -- this has its own section later in this page.
-
-## VREFs
-
-VREFs have their [own page][vref].
-
-## special cases
-
-### #partial-copy partial-copy: selective read control for branches
-
-Git (and therefore gitolite) cannot do selective read control -- allowing
-someone to read branch A but not branch B. It's the entire repo or nothing.
-
- [Side note: Gerrit Code Review can do that, but that is
-because they have their own git stack (and their own sshd, and so on) all in
-one big Java program. Gerrit is *really* useful if you want code review to be
-part of the access control decision]
-
-Gitolite can now help you do this. Note that this is only for branches; you
-can't do this for files and directories.
-
-Here's how:
-
-1. enable 'partial-copy' in the `PRE_GIT` section in the rc file.
-
-2. for each repo "foo" which has secret branches that a certain set of
- developers (we'll use a group called `@temp-emp` as an example) are not
- supposed to see, do this:
-
- repo foo
- # rules should allow @temp-emp NO ACCESS
-
- repo foo-partialcopy-1
- - secret-branch = @temp-emp
-
- # other rules; see notes below
-
- - VREF/partial-copy = @all
- config gitolite.partialCopyOf = foo
-
- **IMPORTANT NOTES**:
-
- * if you're using other VREFs, **make sure** this one is placed at the
- end, after all the others.
-
- * remember that any change allowed to be made to the partial-copy repo
- will propagate to the main repo so make sure you use other rules to
- restrict pushes to other branches and tags as needed.
-
-And that should be it. **Please test it and let me know if it doesn't work!**
-
-WARNINGS:
-
- * If you change the config to disallow something that used to be allowed,
- you should delete the partial repo on the server and then run `gitolite
- compile; gitolite trigger POST_COMPILE` to let it build again.
-
- * Not tested with smart http; probably won't work.
-
- * Also not tested with mirroring, or with wild card repos.
diff --git a/doc/options.mkd b/doc/options.mkd
deleted file mode 100644
index 22d12af..0000000
--- a/doc/options.mkd
+++ /dev/null
@@ -1,20 +0,0 @@
-# gitolite options
-
-Some gitolite features are enabled, or gitolite's behaviour changed, by
-setting "options".
-
-Options are set by repo. The syntax is very simple:
-
- option foo.bar = baz
-
-Of course this is useless if some other part of gitolite, or some external
-command, is not querying for the option key 'foo.bar'!
-
-Options are therefore documented in the section/page they belong in, not here.
-Here are the currently recognised options:
-
- * [deny-rules][] -- ask gitolite to honor deny rules during the pre-git
- check also.
-
- * [mirroring][] related options -- tell gitolite who is the master server,
- and who are the slaves, for each repo.
diff --git a/doc/progit.mkd b/doc/progit.mkd
deleted file mode 100644
index 5e293c1..0000000
--- a/doc/progit.mkd
+++ /dev/null
@@ -1,163 +0,0 @@
-# (expanded version of the gitolite chapter in the progit book)
-
-## Gitolite ##
-
-[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.
-
-Gitolite allows you to specify permissions not just by repository, but also by branch or tag names within each repository. That is, you can specify that certain people (or groups of people) can only push certain "refs" (branches or tags) but not others.
-
-### Installing ###
-
-Installing Gitolite is very easy, even if you don't read the extensive documentation that comes with it. You need an account on a Unix server of some kind. You do not need root access, assuming git, perl, and an openssh compatible ssh server are already installed. In the examples below, we will use the `git` account on a host called `gitserver`.
-
-Gitolite is somewhat unusual as far as "server" software goes -- access is via ssh, and so every userid on the server is a potential "gitolite host". Gitolite is at present best installed manually, as the "g3" version does not yet have RPM/DEB support from distros. We will describe the simplest install method in this article; for the other methods please see the documentation.
-
-To begin, create a user called `git` on your server and login to this user. Copy your ssh pubkey (a file called `~/.ssh/id_rsa.pub` if you did a plain `ssh-keygen` with all the defaults) from your workstation, renaming it to `YourName.pub`. Then run these commands:
-
- git clone git://github.com/sitaramc/gitolite
- gitolite/install -ln
- # assumes $HOME/bin exists and is in your $PATH
- gitolite setup -pk $HOME/YourName.pub
- # for example, I would run 'gitolite setup -pk $HOME/sitaram.pub'
-
-Finally, back on your workstation, run `git clone git@server:gitolite-admin`.
-
-And you're done! Gitolite has now been installed on the server, and you now have a brand new repository called `gitolite-admin` in your workstation. You administer your gitolite setup by making changes to this repository and pushing. See adding [users][] and [repos][] to start with.
-
-### Customising the Install ###
-
-While the default, quick, install works for most people, there are some ways to customise the install if you need to. Some changes can be made simply by editing the [rc file][rc], but if that is not sufficient, there's documentation on [customising gitolite][cust] by using non-core programs.
-
-### Config File and Access Control Rules ###
-
-Once the install is done, you switch to the `gitolite-admin` repository (placed in your HOME directory) and poke around to see what you got:
-
- $ cd ~/gitolite-admin/
- $ ls
- conf/ keydir/
- $ find conf keydir -type f
- conf/gitolite.conf
- keydir/sitaram.pub
- $ cat conf/gitolite.conf
-
- repo gitolite-admin
- RW+ = sitaram
-
- repo testing
- RW+ = @all
-
-Notice that "sitaram" (the name of the pubkey in the gl-setup command you used earlier) has read-write permissions on the `gitolite-admin` repository as well as a public key file of the same name.
-
-The config file syntax for gitolite is [well documented][conf], so we'll only mention some highlights here.
-
-You can group users or repos for convenience. The group names are just like macros; when defining them, it doesn't even matter whether they are projects or users; that distinction is only made when you *use* the "macro".
-
- @oss_repos = linux perl rakudo git gitolite
- @secret_repos = fenestra pear
-
- @admins = scott # Adams, not Chacon, sorry :)
- @interns = ashok # get the spelling right, Scott!
- @engineers = sitaram dilbert wally alice
- @staff = @admins @engineers @interns
-
-You can control permissions at the "ref" level. In the following example, interns can only push the "int" branch. Engineers can push any branch whose name starts with "eng-", and tags that start with "rc" followed by a digit. And the admins can do anything (including rewind) to any ref.
-
- repo @oss_repos
- RW int$ = @interns
- RW eng- = @engineers
- RW refs/tags/rc[0-9] = @engineers
- RW+ = @admins
-
-The expression after the `RW` or `RW+` is a regular expression (regex) that the refname (ref) being pushed is matched against. So we call it a "refex"! Of course, a refex can be far more powerful than shown here, so don't overdo it if you're not comfortable with perl regexes.
-
-Also, as you probably guessed, Gitolite prefixes `refs/heads/` as a syntactic convenience if the refex does not begin with `refs/`.
-
-An important feature of the config file's syntax is that all the rules for a repository need not be in one place. You can keep all the common stuff together, like the rules for all `oss_repos` shown above, then add specific rules for specific cases later on, like so:
-
- repo gitolite
- RW+ = sitaram
-
-That rule will just get added to the ruleset for the `gitolite` repository.
-
-At this point you might be wondering how the access control rules are actually applied, so let's go over that briefly.
-
-There are two levels of access control in gitolite. The first is at the repository level; if you have read (or write) access to *any* ref in the repository, then you have read (or write) access to the repository.
-
-The second level, applicable only to "write" access, is by branch or tag within a repository. The username, the access being attempted (`W` or `+`), and the refname being updated are known. The access rules are checked in order of appearance in the config file, looking for a match for this combination (but remember that the refname is regex-matched, not merely string-matched). If a match is found, the push succeeds. A fallthrough results in access being denied.
-
-### Advanced Access Control with "deny" rules ###
-
-So far, we've only seen permissions to be one or `R`, `RW`, or `RW+`. However, gitolite allows another permission: `-`, standing for "deny". This gives you a lot more power, at the expense of some complexity, because now fallthrough is not the *only* way for access to be denied, so the *order of the rules now matters*!
-
-Let us say, in the situation above, we want engineers to be able to rewind any branch *except* master and integ. Here's how to do that:
-
- RW master integ = @engineers
- - master integ = @engineers
- RW+ = @engineers
-
-Again, you simply follow the rules top down until you hit a match for your access mode, or a deny. Non-rewind push to master or integ is allowed by the first rule. A rewind push to those refs does not match the first rule, drops down to the second, and is therefore denied. Any push (rewind or non-rewind) to refs other than master or integ won't match the first two rules anyway, and the third rule allows it.
-
-You can also use deny rules to hide specific repos from people (or gitweb, or git-daemon, etc.), when you have otherwise allowed them access to *all* repos. For example, a server containing open source repos may nevertheless wish to hide the special 'gitolite-admin' repo from gitweb, even though all the other repos can be made visible:
-
- repo gitolite-admin
- - = gitweb daemon
- [... other access rules ...]
- option deny-rules = 1
- # remember this is for gitolite "g3"; the older gitolite had a
- # different syntax
-
- repo @all
- R = gitweb daemon
-
-[This][deny-rules] page has more details.
-
-### Restricting pushes by files changed ###
-
-In addition to restricting what branches a user can push changes to, you can also restrict what files they are allowed to touch. For example, perhaps the Makefile (or some other program) is really not supposed to be changed by just anyone, because a lot of things depend on it or would break if the changes are not done *just right*. You can tell gitolite:
-
- repo foo
- RW = @junior_devs @senior_devs
-
- - VREF/NAME/Makefile = @junior_devs
-
-User who are migrating from the older gitolite should note that there is a significant change in behaviour with regard to this feature; please see the [migration guide][migr] for details.
-
-### Personal Branches ###
-
-Gitolite also has a feature called "personal branches" (or rather, "personal branch namespace") that can be very useful in a corporate environment.
-
-A lot of code exchange in the git world happens by "please pull" requests. In a corporate environment, however, unauthenticated access is a no-no, and a developer workstation cannot do authentication, so you have to push to the central server and ask someone to pull from there.
-
-This would normally cause the same branch name clutter as in a centralised VCS, plus setting up permissions for this becomes a chore for the admin.
-
-Gitolite lets you define a "personal" or "scratch" namespace prefix for each developer (for example, `refs/personal//*`); the details are [here][pers].
-
-### "Wildcard" repositories ###
-
-Gitolite allows you to specify repositories with wildcards (actually perl regexes), like, for example `assignments/s[0-9][0-9]/a[0-9][0-9]`, to pick a random example. It allows you to assign a new permission mode ("C") which allows users to create repositories based on such wild cards, automatically assigns ownership to the specific user who created it, allows him/her to hand out R and RW permissions to other users to collaborate, etc. This feature is documented [here][wild].
-
-### Other Features ###
-
-We'll round off this discussion with a sampling of other features, all of which, and many more, are described in great detail in the documentation.
-
-**Logging**: Gitolite logs all successful accesses. If you were somewhat relaxed about giving people rewind permissions (`RW+`) and some kid blew away "master", the log file is a life saver, in terms of easily and quickly finding the SHA that got hosed.
-
-**Access rights reporting**: Another convenient feature is what happens when you try and just ssh to the server. Gitolite shows you what repos you have access to, and what that access may be. Here's an example:
-
- hello sitaram, this is git@git running gitolite3 v0.02-15-g1db50f4 on git 1.7.4.4
-
- R anu-wsd
- R entrans
- R W git-notes
- R W gitolite
- R W gitolite-admin
- R indic_web_input
- R shreelipi_converter
-
-**Delegation**: For really large installations, you can delegate responsibility for groups of repositories to various people and have them manage those pieces independently. This reduces the load on the main admin, and makes him less of a bottleneck. See [here][deleg] for more on this.
-
-**Mirroring**: Gitolite can help you maintain multiple [mirrors][mirroring], and switch between them easily if the primary server goes down.
-
-[progit]: http://sitaramc.github.com/gitolite/progit.html
diff --git a/doc/qi.mkd b/doc/qi.mkd
deleted file mode 100644
index 90a83c2..0000000
--- a/doc/qi.mkd
+++ /dev/null
@@ -1,48 +0,0 @@
-# quick install, setup, and clone
-
-## 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).
-
- * On the server, `$HOME/bin` exists and is in your `$PATH`. If you don't
- like that, there are [other install methods][install].
-
- * "your-name.pub" is your public key from your workstation.
- * Also, this key does not already have shell access to this gitolite
- hosting user.
-
- * The setup command does not generate any warnings.
- * If it does, please see [common errors][ce] and fix things before
- continuing, or read the more complete [setup][] page.
-
-## instructions
-
-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
-
-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).
diff --git a/doc/rare.mkd b/doc/rare.mkd
deleted file mode 100644
index bcb1c6a..0000000
--- a/doc/rare.mkd
+++ /dev/null
@@ -1,52 +0,0 @@
-# rare or one-time activities
-
-## #existing moving existing repos into gitolite
-
-On the server:
-
- * Move the repos to `$HOME/repositories`.
-
- * Make sure that:
-
- * They are all *bare* repos.
- * All the repo names end in ".git".
- * All the files and directories are owned and writable by the gitolite
- hosting user (especially true if you copied them as root).
-
- * Run `gitolite setup`. **If you forget this step, you can also forget
- about write access control!**
-
-Back on your workstation:
-
- * [Add them][repos] to conf/gitolite.conf in your clone of the admin repo,
- then commit and push the change.
-
- If the repos are already covered by some [wild][] pattern, this is
- optional.
-
-## #moving moving servers
-
-This is adapted from the "migrating" section of the [install][] page; if
-you're actually *migrating* from g2 please go there!
-
-Nothing in any of the gitolite install/setup/etc will ever touch the *data* in
-any repository except the gitolite-admin repo. The only thing it will
-normally touch is the `update` hook. So one fool-proof way of "moving"
-servers is this (untested but should work; feedback appreciated):
-
-1. Install gitolite on the new server, using the same key for the admin as
- for the old server.
-
-2. Copy the [rc][] file from the old server, overwriting this one.
-
-3. [Disable][writable] the old server so people won't push to it.
-
-4. Copy all the repos over from the old server, including gitolite-admin.
- Make sure the files end up with the right ownership and permissions; if
- not, chown/chmod them.
-
-5. Run `gitolite setup`.
-
-6. On a clone of the old gitolite-admin, add a new remote (or change an
- existing one) to point to the new server. Then `git push -f` to this
- remote.
diff --git a/doc/rc.mkd b/doc/rc.mkd
deleted file mode 100644
index 98ad1d7..0000000
--- a/doc/rc.mkd
+++ /dev/null
@@ -1,104 +0,0 @@
-# the "rc" file (`$HOME/.gitolite.rc`)
-
-**NOTE**: if you're migrating from g2, there are some settings that MUST be
-dealt with **before** running `gitolite setup`; please read the [g2
-migration][g2migr] page and linked pages, and especially the one on
-[presetting the rc file][rc-preset].
-
-----
-
-The rc file for g3 is *quite* different from that of g2.
-
-As before, it is designed to be the only thing unique to your site for most
-setups. What is new is that it is easy to extend it when new needs come up,
-without having to touch core gitolite.
-
-The rc file is perl code, but you do NOT need to know perl to edit it. Just
-mind the commas, use single quotes unless you know what you're doing, and make
-sure the brackets and braces stay matched up!
-
-Please look at the `~/.gitolite.rc` file that gets installed when you setup
-gitolite. As you can see there are 3 types of variables in it:
-
- * simple variables (like `UMASK`)
- * lists (like `POST_COMPILE`, `POST_CREATE`)
- * hashes (like `ROLES`, `COMMANDS`)
-
-While some of the variables are documented in this file, many of them are not.
-Their purposes are to be found in each of their individual documentation files
-around; start with [customising gitolite][cust]. If a setting is used by an
-external command then running that command with '-h' may give you additional
-information.
-
-## specific variables
-
- * `$UMASK`, octal, default `0077`
-
- The default UMASK that gitolite uses makes all the repos and their
- contents have `rwx------` permissions. People who want to run gitweb
- realise that this will not do.
-
- The correct way to deal with this is to give this variable a value like
- `0027` (note the syntax: the leading 0 is required), and then make the
- user running the webserver (apache, www-data, whatever) a member of the
- 'git' group.
-
- If you've already installed gitolite then existing files will have to be
- fixed up manually (for a umask or 0027, that would be `chmod -R g+rX`).
- This is because umask only affects permissions on newly created files, not
- existing ones.
-
- * `$GIT_CONFIG_KEYS`, string, default empty
-
- This setting allows the repo admin to define acceptable gitconfig keys.
-
- Gitolite allows you to set git config values using the "config" keyword;
- see [here][git-config] 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
- arbitrary repo config options *may* be a security risk -- some config
- settings allow executing arbitrary commands!
-
- You have 3 choices. By default `$GIT_CONFIG_KEYS` is left empty, which
- completely disables this feature (meaning you cannot set git configs via
- the repo config).
-
- The second choice is to give it a space separated list of settings you
- consider safe. (These are actually treated as a set of [regular
- expression][regex] patterns, and any one of them must match).
-
- For example:
-
- $GIT_CONFIG_KEYS = 'core\.logAllRefUpdates core\..*compression';
-
- Each pattern should match the *whole* key (in other words, there
- is an implicit `^` at the start of each pattern, and a `$` at the
- end).
-
- The third choice (which you may have guessed already if you're familiar
- with regular expressions) is to allow anything and everything:
- `$GIT_CONFIG_KEYS = '.*';`
-
- * `DEFAULT_ROLE_PERMS`, string, default undef
-
- This sets default wildcard permissions for newly created wildcard repos.
-
- If set, this value will be used as the default role permissions for new
- wildcard repositories. The user can change this value with the perms
- command as desired after repository creation; it is only a default.
-
- Please be aware this is potentially a multi-line variable. In most
- setups, it will be left undefined. Some installations may benefit from
- setting it to `READERS @all`.
-
- If you want multiple roles to be assigned by default, here is how. Note
- double quotes this time, due to the embedded newline, which in turn
- require the '@' to be escaped:
-
- DEFAULT_ROLE_PERMS => "READERS \@all\nWRITERS \@senior_devs",
-
- * `LOCAL_CODE`, string
-
- This is described in more detail [here][localcode]. Please be aware
- **this must be a FULL path**, not a relative path.
diff --git a/doc/refex.mkd b/doc/refex.mkd
deleted file mode 100644
index c5359c2..0000000
--- a/doc/refex.mkd
+++ /dev/null
@@ -1,34 +0,0 @@
-## #refex matching a ref and a refex
-
-A refex is a word I made up to mean "a regex that matches a ref". If you know
-[regular expressions][regex] you're halfway there.
-
-In addition:
-
- * If no refex is supplied, it defaults to `refs/.*`, for example in a rule
- like this:
-
- RW = alice
-
- * A refex not starting with `refs/` is assumed to start with `refs/heads/`.
- This means normal branches can be conveniently written like this:
-
- RW master = alice
- # becomes 'refs/heads/master' internally
-
- while tags will need to be fully qualified
-
- RW refs/tags/v[0-9] = bob
-
- * A refex is implicitly anchored at the start, but not at the end. In
- regular expression lingo, a `^` is assumed at the start (but no `$` at the
- end is assumed). So a refex of `master` will match all these:
-
- refs/heads/master
- refs/heads/master1
- refs/heads/master2
- refs/heads/master/full
-
- If you want to restrict the match to just the one specific ref, use
-
- RW master$ = alice
diff --git a/doc/repos.mkd b/doc/repos.mkd
deleted file mode 100644
index fc73d36..0000000
--- a/doc/repos.mkd
+++ /dev/null
@@ -1,56 +0,0 @@
-# adding and removing repos
-
-**NOTE**: this page describes how to add new repos. To bring already existing
-repos into gitolite control, click [here][existing].
-
-> ----
-
-> *WARNING: Do NOT add new repos or users manually on the server. Gitolite
-> users, repos, and access rules are maintained by making changes to a
-> special repo called 'gitolite-admin' and pushing those changes to the
-> server.*
-
-> ----
-
-Just as for [users][], all operations are in a clone of the gitolite-admin
-repo.
-
-To **add** a new repo, edit `conf/gitolite.conf` and add it, along with at
-least one user with some permissions. Or add it to an existing repo line:
-
- repo gitolite tsh gitpod
- RW+ = sitaram
- RW dev = alice bob
- R = @all
-
-The "repo" line can have any number of repo names or repo group names in it.
-However, it can only be one line; this will not work
-
- repo foo
- repo bar # WRONG; 'foo' is now forgotten
- RW = alice
-
-If you have too many, use a group name:
-
- @myrepos = foo
- @myrepos = bar
-
- repo @myrepos
- RW = alice
-
-Finally, you add, commit, and push this change. Gitolite will create a bare,
-empty, repo on the server that is ready to be cloned.
-
-**Removing** a repo is not so straightforward. You certainly must remove the
-appropriate lines from the `conf/gitolite.conf` file, but gitolite will not
-automatically delete the repo from the server. You have to log on to the
-server and do the dirty deed yourself :-)
-
-It is best to make the change in the conf file, push it, and *then* go to the
-server and do what you need to.
-
-**Renaming** a repo is also not automatic. Here's what you do (and the order
-is important):
-
- * Go to the server and rename the repo at the Unix command line.
- * Change the name in the conf/gitolite.conf file and add/commit/push.
diff --git a/doc/rules.mkd b/doc/rules.mkd
deleted file mode 100644
index 39cabe9..0000000
--- a/doc/rules.mkd
+++ /dev/null
@@ -1,151 +0,0 @@
-## #rules access rules
-
-This is arguably the most complex part of day-to-day gitolite. There are
-several interconnected ideas that make this hard to lay out easily if you're
-totally new to this, so read carefully.
-
-We will use this as a running example:
-
- @staff = dilbert alice wally bob
-
- repo foo
- RW+ = dilbert # line 1
- RW+ dev = alice # line 2
- - = wally # line 3
- RW temp/ = @staff # line 4
- R = ashok # line 5
-
-### what does a rule look like?
-
-A rule line has the structure
-
- =
-
-The most common permissions used are:
-
- * R, for read only
- * RW, for push existing ref or create new ref
- * RW+, for "push -f" or ref deletion allowed (i.e., destroy
- information)
- * `-` (the minus sign), to **deny** access.
-
-There are also other, less commonly used, [types of permissions][write-types].
-
-A refex is an expression that matches the ref (i.e., branch or tag) being
-pushed. See [this][refex] for more info.
-
-### when are the rules checked?
-
-There are 2 places where access rules are checked.
-
-The "pre-git" check is before git is invoked. Gitolite knows the repo name,
-user name, and attempted access (R or W), but no ref name.
-
-The "update" check is only for write operations, and it is just before git
-updates a ref. This time gitolite knows the refname also.
-
-### how are the rules matched?
-
-For the **pre-git check**, any permission that contains "R" matches a read
-operation, and any permission that contains "W" matches a write operation.
-This is because we simply don't know enough to make finer distinctions at this
-point.
-
-In addition, *gitolite ignores deny rules during the pre-git check*. (You can [change this][deny-rules] if you wish, though it's
-rarely needed). This means line 3 is ignored, and so Wally in our
-example will pass the pre-git check.
-
-For the **update check**, git gives us all the information we need. Then:
-
- * All the rules for a repo are [accumulated][rule-accum].
-
- * The rules pertaining to this repo *and* this user (or to a group to which
- they belong, respectively) are kept; the rest are ignored.
-
- * These rules are examined *in the sequence they appeared in the conf file*.
- For each rule:
-
- * If the ref does not match the [refex][], the rule is skipped.
- * If it's a deny rule (the permissions field is a `-`), access is
- **rejected** and the matching stops.
- * If the permission field matches the specific [type of
- write][write-types] operation, access is **allowed** and the matching
- stops.
-
- * If no rule ends with a decision, ("fallthru"), access is **rejected**.
-
-Now you need to understand how [refex][] matching happens and how the
-permissions match the various [types of write operations][write-types].
-
-Using these, you can see, in our example, that:
-
- * Everyone, even wally, can read the repo.
- * Dilbert can push, rewind, or delete any ref.
- * Alice can push, rewind, or delete any ref whose name starts with 'dev';
- see [refex][] for details.
- * Alice can also push (but not rewind or delete) any ref whose name starts
- with 'temp/'. This applies to bob also.
- * If it weren't for line 3, the previous statement would apply to wally
- also.
-
-Interestingly, wally can get past the pre-git check because gitolite ignores
-deny rules for pre-git, but having got past it, he can't actually do anything.
-That's by design, and as I said if you don't like it you can ask gitolite to
-[deny at pre-git][deny-rules].
-
-### #permsum summary of permissions
-
-The full set of permissions, in regex syntax: `-|R|RW+?C?D?M?`. This expands
-to one of `-`, `R`, `RW`, `RW+`, `RWC`, `RW+C`, `RWD`, `RW+D`, `RWCD`, or
-`RW+CD`, all but the first two optionally followed by an `M`. And by now you
-know what they all mean.
-
-## additional topics
-
-### #rule-accum rule accumulation
-
-Gitolite was meant to collect rules from multiple places and apply them all.
-For example, this:
-
- repo foo
- RW = u1
-
- @gr1 = foo bar
-
- repo @gr1
- RW = u2
- R = u3
-
- repo @all
- R = gitweb
-
-is effectively the same as this, for repo foo:
-
- repo foo
- RW = u1
- RW = u2
- R = u3
- R = gitweb
-
-This extends to patterns also, but I'll leave an example for later.
-
-### #deny-rules applying deny rules during the pre-git check
-
-The access rules section above describes the problem in one scenario. Here's
-another. Let's say you have this at the end of your gitolite.conf file:
-
- repo @all
- R = gitweb daemon
-
-but you don't want the gitolite-admin repo showing up on gitweb. How do you
-do that? Here's how:
-
- repo gitolite-admin
- - = gitweb daemon
- option deny-rules = 1
-
- repo @all
- R = gitweb daemon
-
-Note that the order matters; the `-` rule must come *before* the `R` rule.
diff --git a/doc/setup.mkd b/doc/setup.mkd
deleted file mode 100644
index ef866c2..0000000
--- a/doc/setup.mkd
+++ /dev/null
@@ -1,48 +0,0 @@
-# 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 (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
-
-If that command completes without any warnings, you should be done. If it had
-a warning, you probably supplied a key which already has shell access to the
-server. That won't work.
-
-> ----
-
-> Normally, gitolite is hosted on a user that no one accesses directly --
-> you log on to the server using some other userid, and then `su - git`. In
-> this scenario, there *is* no key being used for shell access, so there is
-> no conflict.
-
-> An alternative method is to use two different keys, and a [host
-> alias][ssh-ha] to distinguish the two.
-
-> [common errors][ce] has some links to background information on this
-> issue.
-
-> ----
-
-The 'setup' command has other uses, so you will be running it at other times
-after the install as well:
-
- * To setup the update hook when you move [existing][] repos to gitolite.
- This also applies if someone has been fiddling with the hooks on some
- repos and you want to put them all right quickly.
-
- * To replace a [lost admin key][lost-key].
-
- * To setup gitolite for http mode (run 'gitolite setup -h' for more info).
-
-When in doubt, run 'gitolite setup' anyway; it doesn't do any harm, though it
-may take a minute or so if you have more than a few thousand repos!
diff --git a/doc/special.mkd b/doc/special.mkd
deleted file mode 100644
index 4ff6d75..0000000
--- a/doc/special.mkd
+++ /dev/null
@@ -1,102 +0,0 @@
-# special features and setups
-
-----
-
-[[TOC]]
-
-----
-
-## #elsewhere putting 'repositories' and '.gitolite' somewhere else
-
-Gitolite insists that the "repositories" and ".gitolite" directories be in
-`$HOME`. If you want them somewhere else:
-
- * do the install as normal,
- * *then* move those directories to wherever you want and replace them with
- symlinks pointing to the new location.
-
-## #writable disabling pushes to take backups
-
-The `writable` command allows you to disable pushes to all repos or just the
-named repo, in order to do file-system level things to the repo directory that
-require it not to change, like using normal backup software.
-
-Run `gitolite writable -h` for more info.
-
-## #pers "personal" branches
-
-"personal" branches are great for environments where developers need to share
-work but can't directly pull from each other (usually due to either a
-networking or authentication related reason, both common in corporate setups).
-
-Personal branches exist **in a namespace** of their own. The syntax is
-
- RW+ personal/USER/ = @userlist
-
-where the "personal" can be anything you like (but cannot be empty), and the
-"/USER/" part is **necessary (including both slashes)**.
-
-A user "alice" (if she's in the userlist) can then push any branches inside
-`personal/alice/`. Which means she can push `personal/alice/foo` and
-`personal/alice/bar`, but NOT `personal/alice`.
-
-(Background: at runtime the "USER" component will be replaced by the name of
-the invoking user. Access is determined by the right hand side, as usual).
-
-Compared to using arbitrary branch names on the same server, this:
-
- * Reduces namespace pollution by corralling all these ad hoc branches into
- the "personal/" namespace.
- * Reduces branch name collision by giving each developer her own
- sub-hierarchy within that.
- * Removes the need to think about access control, because a user can push
- only to his own sub-hierarchy.
-
-## delegating access control responsibilities
-
-See [this][deleg].
-
-## #keysonly using pubkeys obtained from elsewhere
-
-If you're not managing keys via the gitolite-admin repo, but getting them from
-somewhere else, you'll want to periodically "update" the keys.
-
-To do that, first edit your rc file and add something like this:
-
- SSH_AUTHKEYS =>
- [
- 'post-compile/ssh-authkeys',
- ],
-
-Then write a script that
-
- * gets all the keys and dumps them into `$HOME/.gitolite/keydir` (or into a
- subdirectory of it).
-
- * runs `gitolite trigger SSH_AUTHKEYS`.
-
-Run this from cron or however you want.
-
-## #gh giving users their own repos
-
-(Please see [this][wild] for background on the ideas in this section).
-
-It's very easy to give users their own set of repos to create, with the
-username at the top level. The simplest setup is:
-
- repo CREATOR/..*
- C = @all
- RW+ = CREATOR
- RW = WRITERS
- R = READERS
-
-Now users can create any repo under their own name simply by cloning it or
-pushing to it, then use the [perms][] command to add other users to their
-WRITERS and READERS lists.
-
-Of course you can get much more creative if you add a few more roles (see
-"roles" in [this][wild] page).
-
-(I prefer using some prefix, say "u", as in `repo
-u/CREATOR/..*`. This helps to keep user-created repos separate, and avoid
-name clashes in some far-fetched scenarios).
diff --git a/doc/sskm.mkd b/doc/sskm.mkd
deleted file mode 100644
index 4ac908d..0000000
--- a/doc/sskm.mkd
+++ /dev/null
@@ -1,242 +0,0 @@
-# changing keys -- self service key management
-
-[Note on g3 version: this has been manually spot-tested; there is no test suite. Changes from g2 version are minimal so it should all work fine but please report errors!]
-
-Follow this guide to add keys to or remove keys from your account. Note that you cannot use this method to add your *first* key to the account; you must still email your initial key to your admin.
-
-The key management is done using a command called `sskm`. This command must be enabled for remote use by the admin (see [here][commands] for more on this).
-
-----
-
-[[TOC]]
-
-----
-
-## Important!
-
-There are a few things that you should know before using the key management system. Please do not ignore this section!
-
-### Key fingerprints
-
-Keys are identified in some of these subcommands by their fingerprints. To see the fingerprint for a public key on your computer, use the following syntax:
-
- ssh-keygen -l -f
-
-You'll get output like:
-
- jeff@baklava ~ $ ssh-keygen -l -f .ssh/jeffskey.pub
- 2048 2d:78:d4:2c:b1:6d:9a:dc:d9:0d:94:3c:d8:c2:65:44 .ssh/jeffskey.pub (RSA)
-
-### Active keys
-
-Any keys that you can use to interact with the system are active keys. (Inactive keys are keys that are, for instance, scheduled to be added or removed.) Keys are identified with their `keyid`; see the section below on listing keys.
-
-If you have no current active keys, you will be locked out of the system (in which case email your admin for help). Therefore, be sure that you are never removing your only active key!
-
-### Selecting which key to use
-
-Although you can identify yourself to the Gitolite system with any of your active keys on the server, at times it is necessary to specifically pick which key you are identifying with. To pick the key to use, pass the `-i` flag into `ssh`:
-
- jeff@baklava ~ $ ssh -i .ssh/jeffskey git@git info
- hello jeff, the gitolite version here is v2.0.1-11-g1cd3414
- the gitolite config gives you the following access:
- @C R W [a-zA-Z0-9][a-zA-Z0-9_\-\.]+[a-zA-Z0-9]
- ....
-
-*N.B.*: If you have any keys loaded into `ssh-agent` (i.e., `ssh-add -l` shows
-at least one key), then this may not work properly. `ssh` has a bug which
-makes it ignore `-i` values when that key has not been loaded into the agent.
-One solution is to add the key you want to use (e.g., `ssh-add
-.ssh/jeffskey`). The other is to remove *all* the keys from the agent or
-disable the agent, using one of these commands:
-
-* Terminate `ssh-agent` or use `ssh-add -D` flag to remove identities from it
-* If using `keychain`, run `keychain --clear` to remove identities
-* Unset the `SSH_AUTH_SOCK` and `SSH_AGENT_PID` variables in the current shell
-
-### Public vs. private keys
-
-In this guide, all keys are using their full suffix. In other words, if you see a `.pub` at the end of a key, it's the public key; if you don't, it's the private key. For instance, when using the `-i` flag with `ssh`, you are specifying private keys to use. When you are submitting a key for addition to the system, you are using the public key.
-
-## Listing your existing keys
-
-To see a list of your existing keys, use the `list` argument to `sskm`:
-
- jeff@baklava ~ $ ssh git@git sskm list
- hello jeff, you are currently using a normal ("active") key
- you have the following keys:
- == active keys ==
- 1: 72:ef:a3:e0:f5:06:f8:aa:6f:a2:88:9d:50:86:25:4e : jeff@key1.pub
- 2: 61:38:a7:9f:ba:cb:99:81:4f:49:2c:8b:c8:63:8e:33 : jeff@key2.pub
- 3: 2d:78:d4:2c:b1:6d:9a:dc:d9:0d:94:3c:d8:c2:65:44 : jeff@key3.pub
-
-Notice the `@` sign in each key's name? That sign and the text after that up until the `.pub` is the `keyid`. This is what you will use when identifying keys to the system. Above, for instance, one of my keys has the `keyid` of `@key3`.
-
-A keyid may be *empty*; in fact to start with you may only have a single
-`jeff.pub` key, depending on how your admin added your initial key. You can
-use any keyid you wish when adding keys (like `@home`, `@laptop`, ...); the
-only rules are that it must start with the `@` character and after that
-contain only digits, letters, or underscores.
-
-## Adding or Replacing a key
-
-### Step 1: Adding the Key
-
-Adding and replacing a key is the same process. What matters is the `keyid`. When adding a new key, use a new `keyid`; when replacing a key, pass in the `keyid` of the key you want to replace, as found by using the `list` subcommand. Pretty simple!
-
-To add a key, pipe in the text of your new key using `cat` to the `add` subcommand. In the example below, I explicitly select which existing, active pubkey to identify with for the command (using the `-i` parameter to ssh) for clarity:
-
- jeff@baklava ~ $ cat .ssh/newkey.pub | ssh -i .ssh/jeffskey git@git sskm add @key4
- hello jeff, you are currently using a normal ("active") key
- please supply the new key on STDIN. (I recommend you
- don't try to do this interactively, but use a pipe)
-
-If you now run the `list` command you'll see that it's scheduled for addition:
-
- jeff@baklava ~ $ ssh -i .ssh/jeffskey git@git sskm list
- hello jeff, you are currently using a normal ("active") key
- you have the following keys:
- == active keys ==
- 1: 72:ef:a3:e0:f5:06:f8:aa:6f:a2:88:9d:50:86:25:4e : jeff@key1.pub
- 2: 61:38:a7:9f:ba:cb:99:81:4f:49:2c:8b:c8:63:8e:33 : jeff@key2.pub
- 3: 2d:78:d4:2c:b1:6d:9a:dc:d9:0d:94:3c:d8:c2:65:44 : jeff@key3.pub
- == keys marked for addition/replacement ==
- 1: ff:92:a2:20:6d:42:6b:cf:20:e8:a2:4a:3b:b0:32:3a : jeff@key4.pub
-
-### Step 2: Confirming the addition
-
-Gitolite uses Git internally to store the keys. Just like with Git, where you commit locally before `push`-ing up to the server, you need to confirm the key addition (see the next section if you made a mistake). We use the `confirm-add` subcommand to do this, *but*: to verify that you truly have ownership of the corresponding private key, you *must* use the key you are adding itself to do the confirmation! (Inconvenient like most security, but very necessary from a security perspective.) This is where using the `-i` flag of `ssh` comes in handy:
-
- jeff@baklava ~ $ ssh -i .ssh/newkey git@git sskm confirm-add @key4
- hello jeff, you are currently using a key in the 'marked for add' state
-
-Listing keys again shows that all four keys are now active:
-
- jeff@baklava ~ $ ssh -i .ssh/newkey git@git sskm list
- hello jeff, you are currently using a normal ("active") key
- you have the following keys:
- == active keys ==
- 1: 72:ef:a3:e0:f5:06:f8:aa:6f:a2:88:9d:50:86:25:4e : jeff@key1.pub
- 2: 61:38:a7:9f:ba:cb:99:81:4f:49:2c:8b:c8:63:8e:33 : jeff@key2.pub
- 3: 2d:78:d4:2c:b1:6d:9a:dc:d9:0d:94:3c:d8:c2:65:44 : jeff@key3.pub
- 4: ff:92:a2:20:6d:42:6b:cf:20:e8:a2:4a:3b:b0:32:3a : jeff@key4.pub
-
-### Optional: Undoing a mistaken add (before confirmation)
-
-Another advantage of Gitolite using Git internally is that that if we mistakenly add the wrong key, we can undo it before it's confirmed by passing in the `keyid` we want to remove into the `undo-add` subcommand:
-
- jeff@baklava ~ $ ssh -i .ssh/jeffskey git@git sskm undo-add @key4
- hello jeff, you are currently using a normal ("active") key
-
-Listing the keys shows that that new key has been removed:
-
- jeff@baklava ~ $ ssh -i .ssh/jeffskey git@git sskm list
- hello jeff, you are currently using a normal ("active") key
- you have the following keys:
- == active keys ==
- 1: 72:ef:a3:e0:f5:06:f8:aa:6f:a2:88:9d:50:86:25:4e : jeff@key1.pub
- 2: 61:38:a7:9f:ba:cb:99:81:4f:49:2c:8b:c8:63:8e:33 : jeff@key2.pub
- 3: 2d:78:d4:2c:b1:6d:9a:dc:d9:0d:94:3c:d8:c2:65:44 : jeff@key3.pub
-
-## Removing a key
-
-### Step 1: Mark the key for deletion
-
-Deleting a key works very similarly to adding a key, with `del` substituted for `add`.
-
-Let's say that I have my four keys from the example above:
-
- jeff@baklava ~ $ ssh -i .ssh/newkey git@git sskm list
- hello jeff, you are currently using a normal ("active") key
- you have the following keys:
- == active keys ==
- 1: 72:ef:a3:e0:f5:06:f8:aa:6f:a2:88:9d:50:86:25:4e : jeff@key1.pub
- 2: 61:38:a7:9f:ba:cb:99:81:4f:49:2c:8b:c8:63:8e:33 : jeff@key2.pub
- 3: 2d:78:d4:2c:b1:6d:9a:dc:d9:0d:94:3c:d8:c2:65:44 : jeff@key3.pub
- 4: ff:92:a2:20:6d:42:6b:cf:20:e8:a2:4a:3b:b0:32:3a : jeff@key4.pub
-
-I would like to remove the key that on my box is called `newkey` and in the Gitolite system is known as `@key4`.
-
-I simply pass in the identifier to the `del` subcommand of `sskm`:
-
- jeff@baklava ~ $ ssh -i .ssh/newkey git@git sskm del @key4
- hello jeff, you are currently using a normal ("active") key
-
-Listing the keys now shows that it is marked for deletion:
-
- jeff@baklava ~ $ ssh -i .ssh/newkey git@git sskm list
- hello jeff, you are currently using a key in the 'marked for del' state
- you have the following keys:
- == active keys ==
- 1: 72:ef:a3:e0:f5:06:f8:aa:6f:a2:88:9d:50:86:25:4e : jeff@key1.pub
- 2: 61:38:a7:9f:ba:cb:99:81:4f:49:2c:8b:c8:63:8e:33 : jeff@key2.pub
- 3: 2d:78:d4:2c:b1:6d:9a:dc:d9:0d:94:3c:d8:c2:65:44 : jeff@key3.pub
- == keys marked for deletion ==
- 1: ff:92:a2:20:6d:42:6b:cf:20:e8:a2:4a:3b:b0:32:3a : jeff@key4.pub
-
-### Step 2: Confirming the deletion
-
-Just like with Git, where you commit locally before `push`-ing up to the server, you need to confirm the key addition (see the next section if you made a mistake). We use the `confirm-del` subcommand to do this, *but*: unlike the `confirm-add` subcommand, you *must* use a *different* key than the key you are deleting to do the confirmation! This prevents you from accidentally locking yourself out of the system by removing all active keys:
-
- jeff@baklava ~ $ ssh -i .ssh/jeffskey git@git sskm confirm-del @key4
- hello jeff, you are currently using a normal ("active") key
-
-Listing keys again shows that the fourth key has been removed:
-
- jeff@baklava ~ $ ssh -i .ssh/jeffskey git@git sskm list
- hello jeff, you are currently using a normal ("active") key
- you have the following keys:
- == active keys ==
- 1: 72:ef:a3:e0:f5:06:f8:aa:6f:a2:88:9d:50:86:25:4e : jeff@key1.pub
- 2: 61:38:a7:9f:ba:cb:99:81:4f:49:2c:8b:c8:63:8e:33 : jeff@key2.pub
- 3: 2d:78:d4:2c:b1:6d:9a:dc:d9:0d:94:3c:d8:c2:65:44 : jeff@key3.pub
-
-### Optional: Undoing a mistaken delete (before confirmation)
-
-Another advantage of Gitolite using Git internally is that that if we mistakenly delete the wrong key, we can undo it before it's confirmed by passing in the `keyid` we want to keep into the `undo-del` subcommand. Note that this operation *must* be performed using the private key that corresponds to the key you are trying to keep! (Security reasons, similar to the reason that you must confirm an addition this way; it prevents anyone from undoing a deletion, and therefore keeping in the system, a key that they cannot prove (by having the corresponding private key) should stay in the system):
-
- jeff@baklava ~ $ ssh -i .ssh/newkey git@git sskm undo-del @key4
- hello jeff, you are currently using a key in the 'marked for del' state
-
- You're undeleting a key that is currently marked for deletion.
- Hit ENTER to undelete this key
- Hit Ctrl-C to cancel the undelete
- Please see documentation for caveats on the undelete process as well as how to
- actually delete it.
-
-(Go ahead and hit ENTER there; the caveats are really only on the administrative side of things.)
-
-Listing the keys shows that that new key is now marked active again:
-
- jeff@baklava ~ $ ssh -i .ssh/newkey git@git sskm list
- hello jeff, you are currently using a normal ("active") key
- you have the following keys:
- == active keys ==
- 1: 72:ef:a3:e0:f5:06:f8:aa:6f:a2:88:9d:50:86:25:4e : jeff@key1.pub
- 2: 61:38:a7:9f:ba:cb:99:81:4f:49:2c:8b:c8:63:8e:33 : jeff@key2.pub
- 3: 2d:78:d4:2c:b1:6d:9a:dc:d9:0d:94:3c:d8:c2:65:44 : jeff@key3.pub
- 4: ff:92:a2:20:6d:42:6b:cf:20:e8:a2:4a:3b:b0:32:3a : jeff@key4.pub
-
-----
-
-## important notes for the admin
-
-These are the things that can break if you allow your users to use this
-command:
-
- * "sskm" clones, changes, and pushes back the gitolite-admin repo. This
- means, even if you're the only administrator, you should never 'git push
- -f', in case you end up overwriting something sskm did.
-
- * There is no way to distinguish `foo/alice.pub` from `bar/alice.pub` using
- this command. You can distinguish `foo/alice.pub` from
- `bar/alice@home.pub`, but that's not because of the foo and bar, it's
- because the two files have different keyids.
-
- In other words, sskm only works with the older style, not with the
- "subdirectory" style of [multi-key][] management.
-
- * Keys placed in specific folders (for whatever reasons), will probably not
- stay in those folders if this command is used. Even a key delete, followed
- by undoing the delete, will cause the key to effectively move to the root
- of the key store (i.e., the `keydir` directory in the gitolite-admin repo).
diff --git a/doc/syntax.mkd b/doc/syntax.mkd
deleted file mode 100644
index 5d3b6b5..0000000
--- a/doc/syntax.mkd
+++ /dev/null
@@ -1,46 +0,0 @@
-# #syntax basic syntax
-
-In general, everything is **space separated**; there are no commas,
-semicolons, etc., in the syntax.
-
-**Comments** are in the usual shell-ish style.
-
-**User names** and **repo names** are as simple as possible; they must start
-with an alphanumeric, but after that they can also contain `.`, `_`, or `-`.
-
-Usernames can optionally be followed by an `@` and a domainname containing at
-least one `.` (this allows you to use an email address as someone's username).
-Reponames can contain `/` characters (this allows you to put your repos in a
-tree-structure for convenience)
-
-There are no continuation lines by default. You do not need them; the section
-on "groups" will tell you how you can break up large lists of names in a group
-definition into multiple lines.
-
-If you *must* have them, you can optionally enable them;
-see the syntactic [sugar][] section.
-
-## #include include files
-
-Gitolite allows you to break up the configuration into multiple files and
-include them in the main file for convenience.
-
- include "foo.conf"
-
-will include the contents of the file "foo.conf".
-
-Details:
-
- * You can also use a glob (`include "*.conf"`), or put your include files
- into subdirectories of "conf" (`include "foo/bar.conf"`), or both
- (`include "repos/*.conf"`).
-
- * Included files are always searched from the gitolite-admin repo's "conf/"
- directory, unless you supplied an absolute path. (Note: in the interests
- of cloning the admin-repo sanely you should avoid absolute paths!)
-
- * If you ended up recursing, files that have been already processed once are
- skipped, with a warning.
-
-Advanced users: `subconf`, a command that is very closely
-related to `include`, is documented [here][subconf].
diff --git a/doc/testing.mkd b/doc/testing.mkd
deleted file mode 100644
index bf3eb4d..0000000
--- a/doc/testing.mkd
+++ /dev/null
@@ -1,50 +0,0 @@
-# testing gitolite
-
-Here's how to *run* the tests.
-
-**WARNING: they will clobber lots of things in your `$HOME`,
-so be sure to use a throwaway userid**.
-
- git clone git://github.com/sitaramc/gitolite
- cd gitolite
- prove
-
-Make sure:
-
- * `$HOME/bin` is in `$PATH`
- * sshd allows incoming ssh to this userid, at least from localhost
-
-Gitolite's test suite is mostly written using [tsh][] -- the "testing shell".
-Take a look at some of the scripts and you will see what it looks like. It
-has a few quirks and nuances; if you really care, email me.
-
-[tsh]: http://github.com/sitaramc/tsh
-
-The tests also use a somewhat convoluted system of environment variables in
-order to run *entirely* as a local user, without going through ssh at all.
-This lets a complete test suite run in about a fifth or less of the time it
-would otherwise take.
-
-If you think that defeats the purpose of the testing, you haven't read
-[this][auth] yet.
-
-## #trying trying out gitolite
-
-It's easy to take gitolite for a trial run, in ssh mode, and play with all of
-its features (except mirroring).
-
-Create a **throw-away userid**, log in to it, then do what the "testing
-gitolite" section above says, except instead of running `prove`, you run
-`prove t/ssh*`.
-
-When this is done, you get a gitolite installation with 7 gitolite users
-("admin", and "u1" through "u6").
-
-Don't forget that the client and the server are all on the same user on the
-same machine; we're *simulating* 7 gitolite users using ssh keys! (How?
-Maybe `~/.ssh/config` will give you a hint).
-
-URLs look like `user:repo`, so for example you can clone the admin repo by
-`git clone admin:gitolite-admin`. Remote commands look like `ssh u1 info`.
-
-So start by cloning the admin repo, and try out whatever you want!
diff --git a/doc/triggers.mkd b/doc/triggers.mkd
deleted file mode 100644
index 9ecdbc9..0000000
--- a/doc/triggers.mkd
+++ /dev/null
@@ -1,161 +0,0 @@
-# gitolite triggers
-
-[[TOC]]
-
-## intro and sample rc excerpt
-
-Gitolite fires off external commands at 7 different times. The [rc][] file
-specifies what commands to run at each trigger point, but for illustration,
-here's an excerpt:
-
- %RC = (
-
- <...several lines later...>
-
- # comment out or uncomment as needed
- # these will run in sequence after post-update
- POST_COMPILE =>
- [
- 'post-compile/ssh-authkeys',
- 'post-compile/update-git-configs',
- 'post-compile/update-gitweb-access-list',
- 'post-compile/update-git-daemon-access-list',
- ],
-
- # comment out or uncomment as needed
- # these will run in sequence after a new wild repo is created
- POST_CREATE =>
- [
- 'post-compile/update-git-configs',
- 'post-compile/update-gitweb-access-list',
- 'post-compile/update-git-daemon-access-list',
- ],
-
-(As you can see, post-create runs 3 programs that also run from post-compile.
-This is perfectly fine, by the way)
-
-## types of trigger programs
-
-There are two types of trigger programs. Standalone scripts are placed in
-src/triggers or its subdirectories. They are invoked by being added to a
-trigger list (using the path after "src/triggers/", as you can see). Such
-scripts are quick and easy to write in any language of your choice.
-
-Triggers written as perl modules are placed in src/lib/Gitolite/Triggers.
-They are invoked by being listed with the package+function name, although even
-here the 'Gitolite::Triggers' part is skipped. Perl modules have to follow
-some conventions (see some of the shipped modules to ideas) but the advantage
-is that they can set environment variables and change the argument list of the
-gitolite-shell program that invokes them.
-
-If this does not make sense, please examine a default install of gitolite,
-paying attention to:
-
- * the path names in various trigger lists in the rc file
- * corresponding path names in the src/ directory in gitolite source
- * and for perl modules, the package names and function names within.
-
-## manually firing triggers
-
-...from the server command line is easy. For example:
-
- gitolite trigger POST_COMPILE
-
-However if the triggered code depends on arguments (see next section) this
-won't work. (The `POST_COMPILE` trigger programs all just happen to not
-require any arguments, so it works).
-
-## common arguments
-
-Triggers receive the following arguments:
-
-1. any arguments mentioned in the rc file (for an example, see the renice
- command in the PRE_GIT trigger sequence),
-
-2. the name of the trigger as a string (example, `"POST_COMPILE"`), so you
- can call the same program from multiple triggers and it can know where it
- was called from,
-
-3. followed by zero or more arguments specific to the trigger, as given in
- the next section.
-
-## trigger-specific arguments and other details
-
-Here are the **rest of** the arguments for each trigger, plus a brief
-description of when the trigger runs:
-
- * `INPUT` runs before pretty much anything else. INPUT trigger scripts
- *must* be in perl, since they manipulate the arguments to and the
- environment of the 'gitolite-shell' program itself. Most commonly they
- will read/change `@ARGV`, and/or `$ENV{SSH_ORIGINAL_COMMAND}`.
-
- There are certain conventions to adhere to; please see some of the shipped
- samples or ask me if you need help writing your own.
-
- * `ACCESS_1` runs after the first access check. Extra arguments:
- * repo
- * user
- * 'R' or 'W'
- * 'any'
- * result (see notes below)
-
- 'result' is the return value of the access() function. If it contains the
- uppercase word "DENIED", the access was rejected. Otherwise it is the
- refex that caused the access to succeed.
-
- *Please note that if access is rejected, gitolite-shell will die as soon
- as it returns from the trigger*.
-
- * `ACCESS_2` runs after the second access check, which is invoked by the
- update hook to check the ref. Extra arguments:
- * repo
- * user
- * any of W, +, C, D, WM, +M, CM, DM
- * the ref being updated (e.g., 'refs/heads/master')
- * result
- * old SHA
- * new SHA
-
- `ACCESS_2` also runs on each [VREF][vref] that gets checked. In this case
- the "ref" argument will start with "VREF/", and the last two arguments
- won't be passed.
-
- 'result' is similar to `ACCESS_1`, except that it is the *update hook*
- which dies as soon as access is rejected for the ref or any of the VREFs.
- Control then returns to git, and then to gitolite-shell, so the `POST_GIT`
- trigger *will* run.
-
- * `PRE_GIT` and `POST_GIT` run just before and after the git command.
- Extra arguments:
- * repo
- * user
- * 'R' or 'W'
- * 'any'
- * the git command ('git-receive-pack', 'git-upload-pack', or
- 'git-upload-archive') being invoked.
-
- * `PRE_CREATE` and `POST_CREATE` run just before and after a new "[wild][]"
- repo is created by user action. Extra arguments:
- * repo
- * user
- * invoking operation
- * 'R' for fetch/clone/ls-remote, 'W' for push
- * can also be anything set by the external command running the
- trigger (e.g., see the perms and fork commands).
-
- They are also run when a *normal* repo is created (say by adding a "repo
- foo" line to the conf file). This case has only one extra argument:
- * repo
-
- * `POST_COMPILE` runs after an admin push has successfully "compiled" the
- config file. By default, the next thing is to update the ssh authkeys
- file, then all the 'git-config's, gitweb access, and daemon access.
-
- No extra arguments.
-
-## tips
-
-If you have code that latches onto more than one trigger, collecting data
-(such as for logging), then the outputs may be intermixed. You can record the
-value of the environment variable `GL_TID` to tie together related entries.
-
diff --git a/doc/user.mkd b/doc/user.mkd
deleted file mode 100644
index a0a767e..0000000
--- a/doc/user.mkd
+++ /dev/null
@@ -1,97 +0,0 @@
-# what users (not admins) need to know about gitolite
-
-...written for the one guy in the world no one will think of as "just a normal
-user" ;-)
-
-----
-
-[[TOC]]
-
-----
-
-## accessing gitolite
-
-The most common setup is based on ssh, where your admin asks you to send him
-your public key, and uses that to setup your access.
-
-Your actual access is either a git command (like `git clone
-git@server:reponame`, and we won't be discussing these any more in this
-document), or an ssh command (like `ssh git@server info`).
-
-Note that you do *not* get a shell on the server -- the whole point of
-gitolite is to prevent that!
-
-## #info the info command
-
-The only command that is *always* available to every user is the `info`
-command (run `ssh git@host info -h` for help), which tells you what version of
-gitolite and git are on the server, and what repositories you have access to.
-The list of repos is very useful if you have doubts about the spelling of some
-new repo that you know was setup.
-
-## digression: two kinds of repos
-
-Gitolite has two kinds of repos. Normal repos are specified by their full
-names in the config file. "Wildcard" repos are specified by a regex in the
-config file. Try the [`info` command][info] and see if it shows any lines
-that look like regex patterns, (with a "C" permission).
-
-If you see any, it means you are allowed to create brand new repos whose names
-fit that pattern. When you create such a repo, your "ownership" of it (as far
-as gitolite is concerned) is automatically recorded by gitolite.
-
-## other commands
-
-### #perms set/get additional permissions for repos you created
-
-The gitolite config may have several permissions lines for your repo, like so:
-
- repo pub/CREATOR/..*
- RW+ = CREATOR
- RW = user1 user2
- R = user3
-
-If that's all it had, you really can't do much. Any changes to access must be
-done by the administrator. (Note that "CREATOR" is a reserved word that gets
-expanded to your userid in some way, so the admin can literally add just the
-first two lines, and *every* authenticated user now has his own personal repo
-namespace, starting with `pub//`).
-
-To give some flexibility to users, the admin could add rules like this:
-
- RW = WRITERS
- R = READERS
-
-(he could also add other roles but then he needs to read the documentation).
-
-Once he does this, you can then use the `perms` command (run `ssh git@host
-perms -h` for help) to set permissions for other users by specifying which
-users are in the list of "READERS", and which in "WRITERS".
-
-If you think of READERS and WRITERS as "roles", it will help. You can't
-change what access a role has, but you *can* say which users have that role.
-
-**Note**: there isn't a way for you to see the actual rule set unless you're
-given read access to the special 'gitolite-admin' repo. Sorry. The idea is
-that your admin will tell you what "roles" he added into rules for your repos,
-and what permissions those roles have.
-
-### #desc adding a description to repos you created
-
-The `desc` command is extremely simple. Run `ssh git@host desc -h` for help.
-
-## "site-local" commands
-
-The main purpose of gitolite is to prevent you from getting a shell. But
-there are commands that you often need to run on the server (i.e., cannot be
-done by pushing something to a repo).
-
-To enable this, gitolite allows the admin to setup scripts in a special
-directory that users can then run. Gitolite comes with a set of working
-scripts that your admin may install, or may use as a starting point for his
-own, if he chooses.
-
-Think of these commands as equivalent to those in `COMMAND_DIR` in `man
-git-shell`.
-
-You can get a list of available commands by running `ssh git@host help`.
diff --git a/doc/users.mkd b/doc/users.mkd
deleted file mode 100644
index 6211278..0000000
--- a/doc/users.mkd
+++ /dev/null
@@ -1,67 +0,0 @@
-# adding and removing users
-
-Strictly speaking, gitolite doesn't know where users come from. If that
-surprises you, read [this][auth]. However, gitolite does help with ssh-based
-authentication, so here's some info on adding and removing users.
-
-> ----
-
-> *WARNING: Do NOT add new repos or users manually on the server. Gitolite
-> users, repos, and access rules are maintained by making changes to a
-> special repo called 'gitolite-admin' and pushing those changes to the
-> server.*
-
-> ----
-
-All operations are in a clone of the gitolite-admin repo.
-
-To **add** a user, say Alice, obtain her public key (typically
-`$HOME/.ssh/id_rsa.pub` on her workstation), copy it to `keydir` with the user
-name as the basename (e.g., 'alice.pub' for user alice), then `git add
-keydir/alice.pub`. (All keys files must have names ending in ".pub", and must
-be in openssh's default format).
-
-To **remove** a user, `git rm keydir/alice.pub`.
-
-In both cases, you must commit and push. On receiving the push, gitolite will
-carry out the changes specified.
-
-The user name is simply the base name of the public key file name. So
-'alice.pub', 'foo/alice.pub' and 'bar/alice.pub', all resolve to user "alice".
-
-## #multi-key multiple keys per user
-
-The simplest and most understandable is to put their keys in different
-subdirectories, (alice.pub, home/alice.pub, laptop/alice.pub, etc).
-
-### old style multi-keys
-
-There is another way that involves creating key files like `alice@home.pub`
-and `alice@laptop.pub`, but there is a complication because gitolite also
-allows *full email addresses* as user names. (I.e., `sitaramc@gmail.com.pub`
-denotes the user called `sitaramc@gmail.com`).
-
-This older method of enabling multi-keys was developed to deal with that. It
-will continue to work and be supported in *code*, simply because I prefer it.
-But I will not accept questions or doc patches for it, because it seems it is
-too difficult to understand for a lot of people. This table of sample pubkey
-filenames and the corresponding derived usernames is all you get:
-
- * plain username, no multikey
-
- sitaramc.pub sitaramc
-
- * plain username, with multikeys
-
- sitaramc@laptop.pub sitaramc
- sitaramc@desktop.pub sitaramc
-
- * email address as username, no multikey
-
- sitaramc@gmail.com.pub sitaramc@gmail.com
-
- * email address as username, with multikeys
-
- sitaramc@gmail.com@laptop.pub sitaramc@gmail.com
- sitaramc@gmail.com@desktop.pub sitaramc@gmail.com
-
diff --git a/doc/vref.mkd b/doc/vref.mkd
deleted file mode 100644
index 0f7c382..0000000
--- a/doc/vref.mkd
+++ /dev/null
@@ -1,308 +0,0 @@
-# virtual refs
-
-**IMPORTANT**: fallthru is success in VREFs, unlike the normal refs. That
-won't make sense until you read further, but I had to put it up here for folks
-who stop reading halfway!
-
-----
-
-[[TOC]]
-
-----
-
-Here's an example to start you off.
-
- repo r1
- RW+ = lead_dev dev2 dev3
- - VREF/COUNT/9 = dev2 dev3
- - VREF/COUNT/3/NEWFILES = dev2 dev3
-
-Now dev2 and dev3 cannot push changes that affect more than 9 files at a time,
-nor those that have more than 3 new files.
-
-----
-
-## rule matching recap
-
-You won't get any joy out of this if you don't understand at least
-[refex][]es and how [rules][] are processed.
-
-But VREFs have one **very important difference** from normal rules. With
-VREFs, a **fallthru results in success**. You'll see why this is more
-convenient as you read on.
-
-----
-
-## what is a virtual ref
-
-A ref like `refs/heads/master` is the main property of a push that gitolite
-uses to make its yes/no decision. I call this a "real" ref.
-
-Any *other* property of the push that you want to use to help in the decision
-is therefore a *virtual* ref. This could be a property that git knows about,
-like in the example above, or comes from outside git like, say, the current
-time; see examples section later for some ideas.
-
-## #vref-fallthru fallthru is success here
-
-Notice that you didn't need to add an `RW+ VREF/...` rule for user `lead_dev`
-in our example. This section explains why.
-
-**Virtual refs are best used as additional "deny" rules**, performing extra
-checks that core gitolite cannot.
-
-Making fallthru be a "fail" forces you to add rules for all users, instead of
-just the ones who should have those extra checks. Worse, since every virtual
-ref involves calling an external program, many of these calls may be wasted.
-
-There's another advantage to doing it this way: a VREF can choose to simply
-die if things look bad, and it will have the same effect, assuming you used
-the VREF only in "deny" rules.
-
-This in turn means any existing update hook can be used as a VREF *as-is*, as
-long as it (a) prints nothing on success and (b) dies on failure. See the
-email-check example later.
-
-## how it works -- overview
-
-Briefly, a refex starting with `VREF/FOO` triggers a call to a program called
-`FOO` in `$GL_BINDIR/VREF`.
-
-That program is expected to print zero or more lines to its STDOUT; each line
-that starts with `VREF/` is taken by gitolite as a new "ref" to be matched
-against all the refexes for this user in the config. Including the refex that
-caused the vref call, of course.
-
-Normally, you send back the refex itself, if the test determines that the rule
-should be matched, otherwise nothing. So, in our example, we print
-`VREF/COUNT/9` if the count was indeed greater than 9. Otherwise we just
-exit.
-
-## how it works -- details
-
- * The VREF code is only called if there are any VREF rules for the user,
- which means when the lead developer pushes, the VREF is not called at all.
-
- Side note: this is enormously more efficient than adding additional
- `update` hooks, which will get executed whether they are needed or not,
- for every repo and every user!
-
- * When dev2 or dev3 push, gitolite first checks the real ref
- (`ref/heads/master` or whatever). After this it looks at VREF rules, and
- calls an external program for every one it finds. Specifically, in a line
- like
-
- - VREF/COUNT/3/NEWFILES = user
-
- COUNT is the vref name, so the program called is
- `$GL_BINDIR/VREF/COUNT`.
-
- The program is passed **nine arguments** in this case (see next section
- for details).
-
- * The script can print anything it wants to STDOUT. Lines not starting with
- `VREF/` are printed as is (so your VREF can do mostly-normal printing to
- STDOUT).
-
- For lines starting with `VREF/`, the first word in each such line will be
- treated as a virtual ref to be matched against all the rules, while the
- rest, if any, is a message to be added to the standard "...DENIED..."
- message that gitolite prints if that refex matches.
-
- Usually it only makes sense to either
-
- * Print nothing that starts with `VREF/` -- if you don't want the rule
- that triggered it to match (ie., whatever condition being tested was
- not violated; like if the count of changed files did not exceed 9, in
- our earlier example).
- * Print the refex itself (plus an optional message), so that it matches
- the line which invoked it.
-
-### #vref-args arguments passed to the vref code
-
- * Arguments **1, 2, 3**: the 'ref', 'oldsha', and 'newsha' that git passed
- to the update hook (see 'man githooks').
-
- This, combined with the fact that non-zero exits are detected, mean that
- you can simply use an existing update.secondary as a new VREF as-is, no
- changes needed.
-
- * Arguments **4 and 5**: the 'oldtree' and 'newtree' SHAs. These are the
- same as the oldsha and newsha values, except if one of them is all-0.
- (indicating a ref creation or deletion). In that case the corresponding
- 'tree' SHA is set (by gitolite, as a courtesy) to the special SHA
- `4b825dc642cb6eb9a060e54bf8d69288fbee4904`, which is the hash of an empty
- tree.
-
- (None of these shenanigans would have been needed if `git diff $oldsha
- $newsha` would not error out when passed an all-0 SHA.)
-
- * Argument **6**: the attempted access flag. Typically `W` or `+`, but
- could also be `C`, `D`, or any of these 4 followed by `M`. If you have to
- ask what they mean, you haven't read enough gitolite documentation to be
- able to make virtual refs work.
-
- * Argument **7**: is the entire refex; in our example
- `VREF/COUNT/3/NEWFILES`.
-
- * Arguments **8 onward**: are the split out (by `/`) portions of the refex,
- excluding the first two components. In our example they would be `3`
- followed by `NEWFILES`.
-
-Yes, argument 7 is redundant if you have 8 and 9. It's meant to make it easy
-to write vref scripts in any language. See script examples in source.
-
-## what (else) can the vref code pass back
-
-Actually, the vref code can pass anything back; each line in its output that
-starts with `VREF/` will be matched against all the rules as usual (with the
-exception that fallthru is not failure).
-
-For example, you could have a ruleset like this:
-
- repo r1
- # ... normal rules ...
-
- - VREF/TIME/WEEKEND = @interns
- - VREF/TIME/WEEKNIGHT = @interns
- - VREF/TIME/HOLIDAY = @interns
-
-and you could write the TIME vref code to passback any or all
-of the times that match. Then if an intern tried to access the system, each
-rule would trigger a call to gl-bindir/VREF/TIME.
-
-The script should send back any of the applicable times (even more than one,
-or none at all, as the case may be). So even if it was invoked using the
-first rule, it might pass back (to gitolite) a virtual ref saying
-'VREF/TIME/HOLIDAY', which would promptly cause the request to be denied.
-
-## VREFs shipped with gitolite
-
-### #NAME restricting pushes by dir/file name
-
-The "NAME" VREF allows you to restrict pushes by the names of dirs and files
-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
-the Makefile, because it's quite complex:
-
- repo foo
- RW+ = @senior_devs
- RW = @junior_devs
-
- - VREF/NAME/Makefile = @junior_devs
-
-When a senior dev pushes, the VREF is not invoked at all. But when a junior
-dev pushes, the VREF is invoked, and it returns a list of files changed **as
-refs**, looking like this:
-
- VREF/NAME/file-1
- VREF/NAME/dir-2/file-3
- ...etc...
-
-Each of these refs is matched against the access rules. If one of them
-happens to be the Makefile, then the ref returned (VREF/NAME/Makefile) will
-match the deny rule and kill the push.
-
-Another way to use this is when you know what is allowed instead of what is
-not allowed. Let's say the QA person is only allowed to touch a file called
-CHANGELOG and any files in a directory called ReleaseNotes:
-
- repo foo
- RW+ = @senior_devs
- RW = @junior_devs
- RW+ = QA-guy
-
- RW+ VREF/NAME/CHANGELOG = QA-guy
- RW+ VREF/NAME/ReleaseNotes/ = QA-guy
- - VREF/NAME/ = QA-guy
-
-### number of new files
-
-The COUNT VREF is used like this:
-
- - VREF/COUNT/9 = @junior-developers
-
-In response, if anyone in the user list pushes a commit series that
-changes more than 9 files, a vref of "VREF/COUNT/9" is returned. Gitolite
-uses that as a "ref" to match against all the rules, hits the same rule
-that invoked it, and denies the request.
-
-If the user did not push more than 9 files, the VREF code returns nothing,
-and nothing happens.
-
-COUNT can take one more argument:
-
- - VREF/COUNT/9/NEWFILES = @junior-developers
-
-This is the same as before, but have to be more than 9 *new* files not
-just changed files.
-
-### advanced filetype detection
-
-Note: this is more for illustration than use; it's rather specific to one of
-the projects I manage but the idea is the important thing.
-
-Sometimes a file has a standard extension (that cannot be 'gitignore'd), but
-it is actually automatically generated. Here's one way to catch it:
-
- - VREF/FILETYPE/AUTOGENERATED = @all
-
-You can look at `src/VREF/FILETYPE` to see how it handles the
-'AUTOGENERATED' option. You could also have a more generic option, like
-perhaps BINARY, and handle that in the FILETYPE vref too.
-
-### checking author email
-
-Some people want to ensure that "you can only push your own commits".
-
-If you force it on everyone, this is a very silly idea (see "Philosophical
-Notes" section of `src/VREF/EMAIL-CHECK`).
-
-But there may be value in enforcing it just for the junior developers.
-
-The neat thing is that the existing `contrib/update.email-check` was just
-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)
-
-### #votes voting on commits
-
-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!
-
-### "no non-merge first-parents"
-
-Shruggar on #gitolite wanted this. Possible code to implement it would be
-something like this (untested)
-
- [ -z "$(git rev-list --first-parent --no-merges $2..$3)" ]
-
-This can be implemented using `src/VREF/MERGE-CHECK` as a model. That script
-does what the 'M' qualifier does in access rules (see last part of
-[this][write-types]), although the syntax to be used in conf/gitolite will be
-quite different.
-
-### other ideas for VREFs
-
-Here are some more ideas:
-
- * Number of commits (`git rev-list --count $old $new`).
- * Number of binary files in commit (currently I only know to count
- occurrences of ` Bin ` in the output of `git diff --stat`.
- * Number of *new* binary files (count ` Bin 0 ->` in `git diff --stat`
- output).
- * Time of day/day of week (see example snippet somewhere above).
- * IP address.
- * Phase of the moon.
-
-Note that pretty much anything that involves `$oldsha..$newsha` will have to
-deal with the issue that when you push a new tag or branch, the "old" part
-is all 0's, and unless you consider `--all` existing branches and tags it
-becomes meaningless in terms of "number of new files" etc.
diff --git a/doc/why.mkd b/doc/why.mkd
deleted file mode 100644
index f88f7c1..0000000
--- a/doc/why.mkd
+++ /dev/null
@@ -1,97 +0,0 @@
-# why might you need gitolite
-
-[[TOC]]
-
-----
-
-## basic use case
-
-Gitolite is useful in any server that is going to host multiple git
-repositories, each with many developers, where "anyone can do anything to any
-repo" is not a good idea. Here're two examples to illustrate.
-
-Example 1, 3 repos, 3 developers with different levels of access to each repo:
-
- repo foo
- RW+ = alice
- R = bob
-
- repo bar
- RW+ = bob
- R = alice
-
- repo baz
- RW+ = carol
- R = alice bob
-
-Example 2, one repo, but different levels of access to different branches and
-tags for different developers:
-
- repo foo
- RW+ master = alice
- RW+ dev/ = bob
- RW refs/heads/tags/v[0-9] = ashok
-
-## #alt alternatives
-
-### unix permissions and ACLs
-
-If you're a masochist, you could probably do example 1 with Unix permissions
-and facls. But you can't do example 2 -- git is not designed to allow that!
-
-Here are some other disadvantages of the Unix ACL method:
-
- * Every user needs a userid and password on the server.
- * Changing access rights involves complex `usermod -G ...` mumblings
- (I.e., the "pain" mentioned above is not a one-time pain!)
- * *Viewing* the current set of permissions requires running multiple
- commands to list directories and their permissions/ownerships, users and
- their group memberships, and then correlating all these manually.
- * Auditing historical permissions or permission changes is impossible.
-
-### #gcr Gerrit Code Review
-
-The best real alternative to gitolite is Gerrit Code Review. If code review
-is an essential part of your workflow, you should use Gerrit.
-
-Here're some high level differences between gitolite and Gerrit:
-
-**Size**: 3000+ lines of perl versus of 56,000+ lines of Java
-
-**Architecture**: Gitolite sits on top of "standard" git and openssh, which
-are assumed to already be installed. Gerrit includes its own git stack (jgit)
-and sshd (Apache Mina). In Java tradition, they all come bundled together.
-
-(Corollary: As far as I know jgit does not support the same hooks that 'man
-githooks' talks about).
-
-Gitolite uses a plain text config file; gerrit uses a database.
-
-**User view**: Gitolite is invisible to users except when access is denied. I
-think Gerrit is much more visible to devs.
-
-On a related note, gitolite does not do anything special with signed or
-annotated tags, nor does it check author/committer identity. However, it is
-trivial to add your own code to do either (or if someone contributes it, to
-just "enable" what ships with gitolite in a disabled state).
-
-### gitorious
-
-Anecdotally, gitorious is very hard to install. Comparison with gitolite may
-be useless because I believe it doesn't have branch/tag level access control.
-However, I can't confirm or deny this because I can't find any documentation
-on the website.
-
-In addition, the main website hides the source code very well, so you already
-have a challenge! [The only link I could find was tucked away at the bottom
-of the About page, in the License section].
-
-### gitlab
-
-Gitlab is built on top of gitolite, but I don't know more than that as yet.
-Patches welcome.
-
-### others
-
-Please send in patches to this doc if you know of other open source git
-hosting solutions that do access control.
diff --git a/doc/wild.mkd b/doc/wild.mkd
deleted file mode 100644
index 4670cc4..0000000
--- a/doc/wild.mkd
+++ /dev/null
@@ -1,157 +0,0 @@
-# "wild" repos (user created repos)
-
-## quick introduction
-
-The wildrepos feature allows you to specify access control rules using regular
-expression patterns, so you can have many actual repos being served by a
-single set of rules in the config file. The regex pattern can also include
-the word `CREATOR` in it, allowing you to parametrise the name of the user
-creating the repo.
-
-See the section on "repo patterns" later for additional information on what
-counts as a "wild" repo pattern and how it is matched.
-
-## (admin) declaring wild repos in the conf file
-
-Here's an example:
-
- @prof = u1
- @TAs = u2 u3
- @students = u4 u5 u6
-
- repo assignments/CREATOR/a[0-9][0-9]
- C = @students
- RW+ = CREATOR
- RW = WRITERS @TAs
- R = READERS @prof
-
-Note the "C" permission. This is a standalone "C", which gives the named
-users the right to *create a repo*. This is not to be
-confused with the "RWC" or its variants described elsewhere, which are about
-*branches*, not *repos*.
-
-## #create (user) creating a specific repo
-
-For now, ignore the special usernames READERS and WRITERS, and just create a
-new repo, as user "u4" (a student):
-
- $ git clone git@server:assignments/u4/a12
- Initialized empty Git repository in /home/sitaram/a12/.git/
- Initialized empty Git repository in /home/git/repositories/assignments/u4/a12.git/
- warning: You appear to have cloned an empty repository.
-
-Notice the *two* empty repo inits, and the order in which they occur ;-)
-
-## a slightly different example
-
-Here's how the same example would look if you did not want the CREATOR's name
-to be part of the actual repo name.
-
- repo assignments/a[0-9][0-9]
- C = @students
- RW+ = CREATOR
- RW = WRITERS @TAs
- R = READERS @prof
-
-We haven't changed anything except the repo name pattern. This means that the
-first student that creates, say, `assignments/a12` becomes the owner.
-Mistakes (such as claiming a12 instead of a13) need to be rectified by an
-admin logging on to the back end, though it's not too difficult.
-
-You could also repace the C line like this:
-
- C = @TAs
-
-and have a TA create the repos in advance.
-
-## repo patterns
-
-### pattern versus normal repo
-
-Due to projects like `gtk+`, the `+` character is now considered a valid
-character for an *ordinary* repo. Therefore, a pattern like `foo/.+` does not
-look like a regex to gitolite. Use `foo/..*` if you want that.
-
-Also, `..*` by itself is not considered a valid repo pattern. Try
-`[a-zA-Z0-9].*`.
-
-### line-anchored regexes
-
-A regex like
-
- repo assignments/S[0-9]+/A[0-9]+
-
-would match `assignments/S02/A37`. It will not match `assignments/S02/ABC`,
-or `assignments/S02/a37`, obviously.
-
-But you may be surprised to find that it does not match even
-`assignments/S02/A37/B99`. This is because internally, gitolite
-*line-anchors* the given regex; so that regex actually becomes
-`^assignments/S[0-9]+/A[0-9]+$` -- notice the line beginning and ending
-metacharacters.
-
-> ----
-
-> *Side-note: contrast with refexes*
-
-> Just for interest, note that this is in contrast to the refexes for the
-> normal "branch" permissions, as described in `doc/gitolite.conf.mkd` and
-> elsewhere. These "refexes" are only anchored at the start; a pattern like
-> `refs/heads/master` actually can match `refs/heads/master01/bar` as well,
-> even 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.
-
-> ----
-
-## roles
-
-The tokens READERS and WRITERS are called "role" names. The access rules in
-the conf file decide what permissions these roles have, but they don't say
-what users are in each of these roles.
-
-That needs to be done by the creator of the repo, using the `perms` command.
-You can run `ssh git@host perms -h` for detailed help, but in brief, that
-command lets you give and take away roles to users. [This][perms] has some
-more detail.
-
-## adding other roles
-
-If you want to have more than just the 2 default roles, say something like:
-
- repo foo/..*
- C = u1
- RW refs/tags/ = TESTERS
- - refs/tags/ = @all
- RW+ = WRITERS
- RW = INTERNS
- R = READERS
- RW+D = MANAGERS
-
-You can add the new names to the ROLES hash in the [rc][] file. Be sure to
-run the 2 commands mentioned there after you have added the roles.
-file. The rc file documentation (`doc/gitolite.rc.mkd`) explains how.
-
-#### #rolenamewarn **IMPORTANT WARNING ABOUT THIS FEATURE**
-
-Please make sure that none of the role names conflict with any of the user
-names or group names in the system. For example, if you have a user called
-"foo" or a group called "@foo", make sure you do not include "foo" as a valid
-role in the ROLES hash.
-
-You can keep things sane by using UPPERCASE names for roles, while keeping all
-your user and group names lowercase; then you don't have to worry about this
-problem.
-
-## listing wild repos
-
-In order to see what repositories were created from a wildcard, use the 'info'
-command. Try `ssh git@host info -h` to get help on the info command.
-
-## deleting a wild repo
-
-Run the whimsically named "D" command -- try `ssh git@host D -h` for more info
-on how to delete a wild repo. (Yes the command is "D"; it's meant to be a
-counterpart to the "C" permission that allowed you to create the repo in the
-first place). Of course this only works if your admin has enabled the command
-(gitolite ships with the command disabled for remote use).
diff --git a/doc/write-types.mkd b/doc/write-types.mkd
deleted file mode 100644
index 79d8f67..0000000
--- a/doc/write-types.mkd
+++ /dev/null
@@ -1,31 +0,0 @@
-## #write-types different types of write operations
-
-Git supplies enough information to the update hook to be able to distinguish
-several types of writes.
-
-The most common are:
-
- * `RW` -- create a ref or fast-forward push a ref. No rewinds or deletes.
- * `RW+` -- create, fast-forward push, rewind push, or delete a ref.
-
-Sometimes you want to allow people to push, but not *create* a ref. Or
-rewind, but not *delete* a ref. The `C` and `D` qualifiers help here.
-
- * When a rule specifies `RWC` or `RW+C`, then *rules that do NOT have the C
- qualifier will no longer permit **creating** a ref*.
-
- Please do not confuse this with the standalone `C`
- permission that allows someone to [create][] a **repo**
-
- * When a rule specifies `RWD` or `RW+D`, then *rules that do NOT have the D
- qualifier will no longer permit **deleting** a ref*.
-
-Note: These two can be combined, so you can have `RWCD` and `RW+CD` as well.
-
-One very rare need is to reject merge commits (a commit series that is not a
-straight line of commits). The `M` qualifier helps here:
-
- * When a rule has `M` appended to the permissions, *rules that do NOT have
- it will reject a commit sequence that contains a merge commit* (i.e., they
- only accept a straight line series of commits).
-