Re: Requirements for integrating a new git subcommand

From: Shawn Pearce <spearce@spearce.org>
Date: Nov 22, 2012, 19:17 UTC
Message-ID: <CAJo=hJsQjXEhmfRUEgBc=RkF3Lk8QVqUqmeAJiOZ0dtvcMYVFw@mail.gmail.com>
In-Reply-To: <20121122053012.GA17265@thyrsus.com>

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.

...

Show 8 quoted lines

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