Re: RFC: a plugin architecture for git extensions?

Jon Seymour wrote:

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.