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]
git 1.7.4+ insists on these two being defined. So I reduce my support
load by forcing them if they were not set.
Much easier than explaining to people what should be obvious from the
error message.
The need for this comes about as follows:
- a project may allow its developers "RWC" (or "RW+C") so that they
can create feature branches when needed. Note that these are
*feature* branches, so they can't use the "personal branches"
mechanism that gitolite already has.
- the developers are *not* given RWCD (or RW+CD) to prevent accidental
deletion of an important branch. Branch *deletion* is something
that only a few trusted admins can do.
- as a result, there are sometimes situations where a developer
creates a misnamed branch and then has to ask the admins to help get
rid of it.
What the KDE folks wanted was a way to allow the creator of a branch to
be able to delete it. In addition, they needed this allowed only for a
fixed duration after the creation of a branch, not forever (for the same
reason they don't get RWCD, to prevent accidents).
These are my reasons why this feature is implemented as an ADC instead
of being "in core":
- we'd need additional syntax to differentiate this special case
(which is sort of in between RWC and RWCD, if you think about it).
I'm reluctant to complicate the syntax further for something that is
only occasionally needed.
- we'd need either (a) code to parse the log files, or, (b) code to
maintain "who created this ref" on every push that creates a ref.
- parsing the log files is too kludgy and inelegant to be in core,
not to mention potentially very slow for really large projects
- code to maintain the a history of "who created this ref" is too
cumbersome, especially because of the need to expire old entries
after a time.
the first one is commented clearly enough, the second one is a pure bug
(though it wouldn't have affected anything except for the ultra-paranoid
"fsckObjects" config var not being set; no biggie...)
$ENV{GL_REPO_BASE_ABS} is meant to point to the same directory as
$REPO_BASE, except it is meant to be passed to hooks, ADCs and other
child programs. And since you can't be sure where the child program
starts in, this became an absolute path.
Gradually, however, I started using it wherever I needed an absolute
path (mostly in code that jumps around various directories to do stuff).
Which is silly, because there's no reason $REPO_BASE cannot also be made
an absolute, even if the rc file has a relative path.
So that's what I did now: made $REPO_BASE absolute very early on, and
then systematically changed all uses of the longer form to the shorter
form when appropriate. And so the only thing we now use the longer one
for is to pass to child programs.
(Implementation note: The actual change is not very big, but while I was
about it I decided to make the test suite able to test with an absolute
REPO_BASE also, which is why the commit seems so large.)
----
This all started with a complaint from Damien Regad. He had an
extremely odd setup where his bashrc changed PWD to something other than
$HOME before anything else ran. This caused those two variables to
beceom inconsistent, and he had a 1-line fix he wanted me to apply.
I generally don't like making special fixes for for non-standard setups,
and anyway all he had to do was set the full path to REPO_BASE in the rc
file to get around this. Which is what I told him and he very politely
left it at that.
However, this did get me thinking, and I soon realised I was needlessly
conflating "relative versus absolute" with "able to be passed to child
programs". Fixing that solved his problem also, as a side-effect.
So I guess this is all thanks to Damien!
Technically this does not add any new information, but I'm hoping it
will help the folks just won't read what's on the screen otherwise.
The main impetus this time is git 1.7.4, which is strict about
user.email and user.name and rejects commits when those config variables
are not set. As a result, the number of times gl-easy-install hits a
fatal error and bombs out without completing its job, has increased
drastically.
The code that sets %projlist doesn't even run if GL_NO_DAEMON_NO_GITWEB
is set, so it doesn't make sense to then *use* that (empty) variable and
effectively wipe out the projects.list file.
Thanks to m0 for asking...
(suggested by cmyers and ryan_c on #gitolite)
Between wrap_print(), which now takes a list, and the new slurp(),
pretty much everything to do with 'cat' or 'echo' has been converted to
pure perl.
----
Personally, I consider these changes to be somewhat gratuitous, because
none of these had a security *or* a performance concern. But since the
amount of new perl code was not too high (just the slurp() function,
really), I figure it's not a big deal to do it.
with warns now being logged, it's nice to make sure that anything that
could even vaguely be considered someone playing with the system, *or*
is otherwise noteworthy, be emitted as a 'warn' instead of as a 'print
STDERR'. Similarly stuff that is clearly a syntactic warning or typo
should come from 'print STDERR', instead of from a 'warn'.
ryan-c on #gitolite (ryan.castellucci@gmail.com) found that if a user
types in
ssh git@server `echo -e "\033[2J"`
or eqvt, he can get raw ASCII control characters into gitolite's log
file. Then if a gitolite admin 'cat's the log file (instead of using a
pager, or uses a pager in raw mode like 'less -r'), those control
characters hit his screen and do stuff.
While clearing the screen etc is probably harmless and I would not have
bothered, we know that the old vt100 would allow the keyboard to be
remapped by the server sending control codes, and we're not really sure
which of the currently in use terminals emulate this.
And finally, I found somewhere that "PuTTY allows the server to send
control codes that let it take over the mouse". Scary...
(...of course, I hate putty/plink so I was sorely tempted to leave this
as is to punish people who use it <grin> but not really; I'd joke about
it but won't actually *do* it!)
Earlier, it wasn't as critical for gl-setup to be run with the full
path; the BINDIR deduction used to happen in almost every program. Now
it's a lot more important.
Apparently I never noticed that "/bin/bash -l gl-setup" does not set $0
to the correct, fq path. Adding a "-c" does, however...
[thanks to Jeff from the KDE team for finding this]
This shaves 3 seconds off of KDE's config compile time :-)
Yes, I know wrap_print has that extra print statement, but otherwise it
was lying around not earning its keep so I gave it a little side job :-)
