Re: Requirements for integrating a new git subcommand

[Shawn Pearce <spearce@spearce.org>]

On Wed, Nov 21, 2012 at 9:30 PM, Eric S. Raymond <esr@thyrsus.com> wrote:
> I have completed work on git-weave (the tool I had called 'gitpacker' in some
> previous postings).  I want to submit a patch that integrates it into git;
> in hopes of smoothing the process I have some technical and procedural
> questions.
...
> Now *my* questions:
>
> 1. I have a round-trip test for the tool that I can very easily adapt
> to speak TAP.  To function, the test will require a small linear
> history to operate on in the form of an import-stream file (so the
> result of round-tripping through a weave-unravel can be diffed against
> the original).  Does the distribution include any test repos?  If
> so, where can I find them?

No. We create the repositories from scratch using a series of
commands. If you look at the test library the environment is set in a
predictable way so the author, committer and timestamps are all set to
a single well known value, allowing Git to create a commit that is
reproducible on all platforms. A test_tick function is used in the
scripts to move the clock, allowing different times to be used. For an
example see t7502-commit.sh, or really any script in that directory.

> 2. I understand that a "git foo" command is typically implemented
> as "git-foo" binary or script in /usr/lib/git-core.  What I don't
> know is what the other interfacing requirements are.  Are they
> documented anywhere?  In particular...

Nope. "git foo" will invoke "git-foo" with GIT_DIR set in the
environment, so you know what repository to act against, and so does
any git command you recursively invoke. Other than that there really
aren't any interface requirements. Your program is executed with
whatever arguments the caller gave you. Its pretty simple UNIX stuff.
:-)

> 3. Is there any registration protocol other than simply installing
> the extension in the subcommand library?

Nope. Running "git whatever-this-is-i-have-no-idea" will try to
execute "git-whatever-this-is-i-have-no-idea" via $PATH, after adding
/usr/lib/git-core to the front of $PATH. Its pretty simple actually.
If your standard C library can find the program in $PATH its run, if
it can't find it, it dies.

> 4. How does "git help" work?  That is, how is a subcommand expected
> to know when it is being called to export its help text?

IIRC "git help foo" runs "man git-foo".

> 5. I don't see any extensions written in Python.  Are there any special
> requirements or exclusions for Python scripts?

Nope, it just has to be executable. We don't have any current Python
code. IIRC the last Python code was the implementation of
git-merge-recursive, which was ported to C many years ago. We avoid
Python because it is not on every platform where Git is installed. Yes
Python is very portable and can be installed in many places, but we
prefer not to make it a requirement.