gitolite/doc/g3why.mkd

# 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',
            <etc>

  * 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.