This document contains no new policies or proposals; it attempts to document established practices and interface requirements. Signed-off-by: Eric S. Raymond <esr@xxxxxxxxxxx> --- Documentation/technical/api-command.txt | 91 +++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 Documentation/technical/api-command.txt diff --git a/Documentation/technical/api-command.txt b/Documentation/technical/api-command.txt new file mode 100644 index 0000000..c1c1afb --- /dev/null +++ b/Documentation/technical/api-command.txt @@ -0,0 +1,91 @@ += Integrating new subcommands = + +This is how-to documentation for people who want to add extension +commands to git. It should be read alongside api-builtin.txt. + +== 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 exec path, the wrapper +will look in the rest of your $PATH for it. Thus, it's possible +to write local git extensions that don't live in system space.) + +== 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. + +Python is fine for import utilities, surgical tools, remote helpers +and other code at the edges of the git suite - but it should not yet +be used for core functions. This may change in the future; the problem +is that we need better Python integration in the git Windows installer +before we can be confident people in that environment won't +experience an unacceptably large loss of capability. + +C commands are normally written as single modules, named after the +command, that link a collection of functions called libgit. Thus, +your command 'git-foo' would normally be implemented as a single +"git-foo.c"; this organization makes it easy for people reading the +code to find things. + +See the CodingGuidelines document for other guidance on what we consider +good practice in C and shell, and api-builtin.txt for the support +functions available to built-in commands written in C. + +== What every extension command needs == + +You must have a man page, written in asciidoc (this is what git help +followed by your subcommand name will display). Be aware that there is +a local asciidoc configuration and macros which you should use. It's +often helpful to start by cloning an existing page and replacing the +text content. + +You must have a test, written to report in TAP (Test Anything Protocol). +Tests are executables (usually shell scripts) that live in the 't' +subdirectory of the tree. Each test name begins with 't' and a sequence +number that controls where in the test sequence it will be executed; +conventionally the rest of the name stem is that of the command +being tested. + +Read the file t/README to learn more about the conventions to be used +in writing tests, and the test support library. + +== Integrating a command == + +Here are the things you need to do when you want to merge a new +subcommand into the git tree. + +0. Don't forget to sign off your patch! + +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. + +3. If your command is implemented in an interpreted language with a +p-code intermediate form, make sure .gitignore in the main directory +includes a pattern entry that ignores such files. Python .pyc and +.pyo files will already be covered. + +4. If your command has any dependency on a a particular version of +your language, document it in the INSTALL file. + +5. There is a file command-list.txt in the distribution main directory +that categorizes commands by type, so they can be listed in appropriate +subsections in the documentation's summary command list. Add an entry +for yours. To understand the categories, look at git-cmmands.txt +in the main directory. + +6. When your patch is merged, remind the maintainer to add something +about it in the RelNotes file. + +That's all there is to it. -- 1.7.9.5 -- <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a> Whether the authorities be invaders or merely local tyrants, the effect of such [gun control] laws is to place the individual at the mercy of the state, unable to resist. -- Robert Anson Heinlein, 1949 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html