Initial entry of markdown documentation as generated by pod2markdown.
Note addition of table-of-contents and appropriate anchors
Signed-off-by: Christopher M. Fuhrman <cfuhrman@panix.com>
[some formatting type changes done by Sitaram]
you might wonder why these are different from all the other variables in
the rc file... it's just that I never thought people would want to
change these!
This patch is dedicated to the person who, when referred to [1] for
gitweb access help, assumed we're talking about a Unix userid called
"gitweb" and said it still doesn't work. He looked at the description
examples and wasn't sure what to do with them. Finally, he missed the
sentence "All gitolite does is:" in the document, and assumed *he* was
supposed to do what the next 3 bullets said (in this case, create the
"description" file manually).
He didn't once think of the gitolite.conf file as being the location for
these instructions, or that "give read access" means "R = ..." instead
of a Unix level "chmod ...".
Do things have to be spelled out so goddamn clearly? Can't people think
for a few seconds and see if there is another way before giving up?
I blame the prevalence of Windows and GUI IDEs. People can only
"click". They can't "think" anymore...
[1]: http://sitaramc.github.com/gitolite/doc/2-admin.html#gwd
- allow a mob username to be defined; all unauthenticated access will
look to gitolite like this user (if you setup apache also properly)
- update doc with more details (some repeat stuff from `man
git-http-backend` but it's probably worth having everything in one
place
Fedora's config has over 11,000 repositories and the compiled config
file is over 20 MB in size. Although negligible on a server class
machine, on my laptop just parsing this file takes a good 2.5 seconds.
Even if you use GL_ALL_READ_ALL (see a couple of commits before this
one) to remove the overhead for 'read's, that's still a pretty big
overhead for writes. And GL_ALL_READ_ALL is not really a solution for
most people anyway.
With this commit, using GL_BIG_CONFIG adds another optimisation; see
doc/big-config.mkd for details (look for the word "split config" to find
the section that talks about it).
----
Implementation notes:
- the check for GL_NO_CREATE_REPOS has moved *into* the loop (which it
completely bypassed earlier) so that write_1_compiled_conf can be
called on each item
(we quietly do not document the 'able' adc, which is now the most
"official" adc in the sense that it has a new test, t64-write-able!)
other notes: fix bug in 'able' (not setting $loc)
(thanks to a somewhat heated "discussion" with "abstrakt" on #git)
While I don't agree with everything he said, some improvements are
always possible (always, always!) in docs:
- move the "conventions used" section closer to the action
- add note about RPM/DEB using "gitolite" as the user, not "git"
- de-emphasise multiple gitolite hosting users at the top; refer
advanced users to the already present detailed section later instead
- in that section, add a bit of intro, and hand-wave the inconsistency
between its 2 sub-sections ;-)
----
Unrelated to the "discussion" today, someone else (running Arch? don't
remember) had a system where /usr/local/bin was not in $PATH for a
normal user, so I added a note about that.
