6e29365316
I got tired of being told "TL;DR". Now the online versions of most documents fit on a page or two, or at least most of them do. The rest has been split out (and you can see the links to the split out sections right where the text is in the raw Markdown). This is much more pleasant to read, and I've improved the linking so it's much less effort for me to keep the links correct.
149 lines
5.8 KiB
Markdown
149 lines
5.8 KiB
Markdown
# F=dev_notes developer/patch maintainer notes
|
|
|
|
## general stuff
|
|
|
|
* all scripts and libraries must be in the same directory. However, RPM/DEB
|
|
packagers can put the libraries where they want, as long as they can be
|
|
found in perl's default `@INC`.
|
|
|
|
* gl-auth-command **requires** an actual `~/.gitolite.rc` (except if your
|
|
initials are "JK" or "DG", in which case `/etc/gitolite/gitolite.rc` also
|
|
works!) It knows how to look around and set env vars etc correctly
|
|
|
|
* all programs except gl-auth-command **require** the environment variables
|
|
`GL_RC` and `GL_BINDIR` set properly. Your best bet is to run them *via*
|
|
gl-auth-command, like so:
|
|
|
|
path/to/gl-auth-command -e other_program other_program_arguments
|
|
|
|
In any case none of these programs are meant to be run manually -- pretty
|
|
much all of them are run via gl-auth-command or from something that was
|
|
forked from it so the variables *will* exist during normal operation.
|
|
|
|
## the rc file
|
|
|
|
The 'rc' file has one major change from v1: any new values in the rc file need
|
|
to be added to the @EXPORT list in `src/gitolite_rc.pm`.
|
|
|
|
## modules
|
|
|
|
There are 3 "modules" (`gitolite_rc`, `gitolite_env`, and `gitolite` itself).
|
|
Their purposes should be fairly obvious.
|
|
|
|
## that 'bindir' thing
|
|
|
|
The importance of `GL_BINDIR` is that the command= argument in
|
|
`~/.ssh/authorized_keys` must be a full path, ideally, and the compile script
|
|
gets this from `GL_BINDIR`.
|
|
|
|
### from perl
|
|
|
|
* for frequently run perl programs, I prefer my method
|
|
|
|
* gl-auth-command -- this is invoked with a full path
|
|
* gl-mirror-shell -- same as above
|
|
* gl-time -- same as above
|
|
|
|
* "their" ideal is "FindBin". I will use it only on manually or
|
|
infrequently run programs
|
|
|
|
* gl-setup-authkeys (external shim to compile keys separately from PTA)
|
|
|
|
### from shell
|
|
|
|
* a perl program called gl-query-rc finds its own BINDIR (using my perl
|
|
method, not FindBin). This is suitable for calling from shell scripts
|
|
as `${0%/*}/gl-query-rc GL_BINDIR`
|
|
|
|
* gl-setup
|
|
* gl-tool
|
|
* gl-mirror-push
|
|
|
|
### OUTLIER!
|
|
|
|
* gl-admin-push is an outlier. For some silly reason I have the notion that
|
|
even if it runs from /tmp it should get the right values, so it is the
|
|
only one that interrogates `~/.ssh/authorized_keys` to get the actual
|
|
BINDIR in use!
|
|
|
|
## special types of setups
|
|
|
|
### Fedora
|
|
|
|
Fedora has a very special setup, as follows:
|
|
|
|
* each user has his own userid and login
|
|
* his/her ~/.ssh/authkeys file (containing only his/her key) has a
|
|
"command=" clause invoking gl-auth-command
|
|
* trusted users have "gl-auth-command -s" meaning they can get a shell if
|
|
they want to
|
|
|
|
* actual git repos are under "git" (or some such), and include the chmod g+s
|
|
(git init --shared) unix perms tricks for shared access
|
|
|
|
* but since they're coming through gl-auth, branch-level acls are in effect
|
|
|
|
* the gitolite config file is generated from some database and compiled (all
|
|
via cron)
|
|
|
|
* the keydir/ is empty; in fact they probably don't use the admin repo at
|
|
all, AFAIK
|
|
|
|
The most important implication of this setup is that **the RC file is no
|
|
longer is `$HOME` of the 'git' user**. They keep it in
|
|
`/etc/gitolite/gitolite.rc`. This means that a properly setup rc file must
|
|
already be present in `/etc/gitolite/gitolite.rc` before doing any such
|
|
installs.
|
|
|
|
There are also some other "impedance mismatches" that may show up. For
|
|
example, the gl-setup triggered by detecting a change in `$data_version`
|
|
following an RPM update once caused problems. This auto-update is designed to
|
|
run on the next "hit" of any kind (which arguably makes things very easy in
|
|
normal installations), but in Fedora's case it also means it runs *as that
|
|
user*. Who may not have "write" access to `$GL_ADMINDIR`! So the compile
|
|
fails, and you now have new code trying to work with old format data.
|
|
|
|
The solution is to explicitly run a compile, from a properly privileged
|
|
userid, as soon as you do an RPM upgrade.
|
|
|
|
# **Why v2?**
|
|
|
|
I went onto `#perl` to ask some question about setpriority() and got yelled at
|
|
for writing "horrible code". And that was one of the kinder comments; my
|
|
rather fragile ego is trying to forget the rest ;-)
|
|
|
|
They also gave me a link to a PDF book, "Modern Perl" by 'chromatic'. Nice
|
|
book; one of the first things you learn from it is that you should not go to
|
|
`#perl` for general help.
|
|
|
|
Anyway, the summary of the collective angst of `#perl` (well 2 people anyway)
|
|
was: use Getopt::Long, FindBin, 'use lib', a library for HTTP stuff, stop
|
|
prefixing subs with '&', and get rid of the huge number of 'our' declarations.
|
|
|
|
That last item is the only one I totally agree with, because it was on my long
|
|
term todo list anyway. And 'use lib' sorta goes with it, so that's fine too.
|
|
And as soon as I found that vim colors the sub names differently if you take
|
|
out the '&' I decided I'd do that too :-) [But honestly, if `&sub` is so bad
|
|
shouldn't "man perlsub" at least say something negative about it, other than
|
|
"disables prototype checking", which doesn't matter here since I'm not using
|
|
prototypes?]
|
|
|
|
As for the rest, FindBin brings in a good 1000+ lines for something that I do
|
|
in a line or two (since I don't care about all the pathological edge cases).
|
|
Getopt::Long is 2649 lines to replace the code below [note that there *is*
|
|
only one possible option to this command, and it is *never* run manually
|
|
either, so I don't need any fancy features]:
|
|
|
|
my $shell_allowed = 0;
|
|
if (@ARGV and $ARGV[0] eq '-s') {
|
|
$shell_allowed = 1;
|
|
shift;
|
|
}
|
|
|
|
Apparently TMTOWTDI has given way to TOOWTDI.
|
|
|
|
Anyway, I spent a few hours refactoring it. And I do thank them for pushing
|
|
me to stop being lazy on the "our" business.
|
|
|
|
[gw]: https://github.com/sitaramc/gitolite/blob/pu/doc/3-faq-tips-etc.mkd#_easier_to_link_gitweb_authorisation_with_gitolite
|