Re: [PATCH] Add documentation on how to integrate commands.

[Junio C Hamano <gitster@pobox.com>]

esr@thyrsus.com (Eric S. Raymond) writes:

> ---

Sign off?

>  Documentation/CommandIntegration |   69 ++++++++++++++++++++++++++++++++++++++
>  1 file changed, 69 insertions(+)
>  create mode 100644 Documentation/CommandIntegration
>
> diff --git a/Documentation/CommandIntegration b/Documentation/CommandIntegration
> new file mode 100644
> index 0000000..be248f7
> --- /dev/null
> +++ b/Documentation/CommandIntegration
> @@ -0,0 +1,69 @@
> += Integrating new subcommands =
> +
> +This is how-to documentation for people who want to add extension
> +commands to git.
> +
> +== Runtime environment ==
> +
> +git subcommands are standalone executables that live in the git
> +execution directory, normally /usr/lib/git-core.  The git executable itself
> +is a thin wrapper that sets GIT_DIR and passes command-line arguments
> +to the subcommand.
> +
> +(If "git foo" is not found in the git execution directory, the wrapper
> +will look in the rest of your $PATH for it.  Thus, it's possible

As the first sentence in this paragraph does not make it clear
enough that you are defining a new term "git execution directory",
"execution directory" here may be misleading and can easily be
mistaken as if we look something in the directory where the user
runs "git" in.  We usually call it "exec path".

> +== Implementation languages ==
> +
> +Most subcommands are written in C or shell.  A few are written in
> +Perl.  A tiny minority are written in Python.
> +
> +While we strongly encourage coding in portable C for portability, these
> +specific scripting languages are also acceptable. We won't accept more
> +without a very strong technical case, as we don't want to broaden the
> +git suite's required dependencies.

Actually, we tend to avoid Python dependency for anything important
and allow it only on fringes; people who lack Python environment are
not missing much, and we would want to keep it that way until the
situation on the Windows front changes.

> +C commands are normally written as single modules, named after the
> +command, that link a core library called libgit.  Thus, your command

I would prefer to see this sentence not call libgit.a a "library".
We primarily use libgit.a to let linker pick necessary object files
without us having to list object files for non-builtin command
implementations and it is not designed to be used by other people.

> +== Integrating a command ==
> +
> +Here are the things you need to do when you want to merge a new 
> +subcommand into the git tree.
> +
> +1. Append your command name to one of the variables BUILTIN_OBJS,
> +EXTRA_PROGRAMS, SCRIPT_SH, SCRIPT_PERL or SCRIPT_PYTHON.
> +
> +2. Drop its test in the t directory.
> +
> +That's all there is to it.

And when sending a patch in, do not forget to sign off your patches
;-)