Re: RFC: a plugin architecture for git extensions?

[Jonathan Nieder <jrnieder@gmail.com>]

Jon Seymour wrote:

> I would appreciate any feedback you (or others) have about:
>
>     http://permalink.gmane.org/gmane.comp.version-control.git/172419
>
> In particular, I would be interested in feedback about how to best support:
>
> - multiple extensions - do we want support installing extensions in
> their own directories, per Pau's suggestion or simply allow them to
> write to a common directory?
> - multiple extension directories - how to support Jonathan's
> requirement to allow user specific extension directories?

Well, let's step back for a moment.  What problem are we solving?
I still don't even know the answer to that!

Once upon a time, all git commands lived on the $PATH (typically in
/usr/bin, $HOME/bin, or some similar place) and could even be
invoked directly as git-commandname.  At some point someone noticed
that by running

	git-<TAB>

it was possible to read the list of all git commands.  Unfortunately
the list was very long, and this seemed like a much worse introduction
to git than the shorter list shown by "git --help".

There were also some related minor problems --- for example, git was
putting more pressure than necessary on filesystems and other
facilities to keep track of all the files in $bindir, and providing
the dashed forms of commands provides a temptation to use them
exclusively, making features (like aliases) of the git wrapper less
discoverable.  But the main thing was the tab completion.

The fix was to tuck away the individual commands somewhere under
libexecdir, outside $PATH.

Now at some point in this discussion I thought you were solving a
related problem.  If a person were to install 100 new commands for
git, or a single package with 100 commands in it, then

	git-<TAB>

would be daunting again.  So the task becomes to find a place to tuck
away these new commands without placing them on the $PATH.

But now I am less sure.  The motivating example has less than 10
commands; that doesn't seem worth all the fuss at all.  Why not just
install the command on the $PATH?  "git help work" _would_ work on all
the systems I have easy access to.  For example, if I write:

	install:
		install -m0755 git-work $(prefix)/bin
		install -d -m0755 $(prefix)/share/man/man1
		gzip -9 <git-work.1 >git-work.1.gz
		install -m0644 git-work.1.gz $(prefix)/share/man/man1/
		install -d -m0755 $(prefix)/bin

and the user runs

	make install
	PATH=$HOME/bin:$PATH

then "man git-work" will just work.  Similarly, "git work --help"
(which the git wrapper transforms to "git help work") would just work.

I see only a few potential problems remaining:

 1. There is no automatically generated documentation page pointing
    to the documentation for all new commands of this kind.  So
    I can run "git help -a" to learn about installed commands, but
    I cannot run "man git" to do so.  Likewise for info.

 2. On platforms like Windows that do not use manpages, my "git work"
    documentation will not show up with "git work --help".  For this,
    it would certainly be useful to have a GIT_HTML_PATH environment
    variable (or some similar name) that could be used to point to a
    list of directories with additional documentation.  The default
    could be something along the lines of the default library search
    path (but simpler), like:

	/usr/local/share/git/help:/usr/share/git/help

    Users installing new commands under $HOME might want to prepend
    something like

	$HOME/share/git/help:

    or whatever directory names suit their tastes.

    Even better might be a way for "git help" to ask the command
    where it puts its documentation, so "git help work" would
    internally run "git work --html-path".

 3. On a machine with multiple installations of git, my new command
    is not tied to any particular installation but shared by all of
    them.  This is a feature, not a bug.

 4. My command is visible with git-<TAB>, as mentioned above.

My comments about unprivileged users installing new commands were to
explain why an alternative solution to (2) that uses a single
directory where "git help" always looks would be inadequate.  I still
think that but luckily there is a large space of possible designs
without that problem; two are mentioned in the description of (2)
above.

Now problems 2 and 4 can be solved at the same time by introducing
something like a GIT_PLUGINS_PATH variable that could be shared for
both uses.  I'm not so convinced that's a good idea (I prefer to see
decoupled solutions to independent problems when it's simple to do)
but it could very well turn out okay.