## developer/patch maintainer notes
In this document:
* general stuff
* the rc file
* modules
* that 'bindir' thing
* from perl
* from shell
* OUTLIER!
* special types of setups
* Fedora
----
### 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