| From: Eric S. Raymond <esr@thyrsus.com> |
| Abstract: This is how-to documentation for people who want to add extension |
| commands to Git. It should be read alongside builtin.h. |
| Content-type: text/asciidoc |
| |
| How to integrate new subcommands |
| ================================ |
| |
| This is how-to documentation for people who want to add extension |
| commands to Git. It should be read alongside builtin.h. |
| |
| Runtime environment |
| ------------------- |
| |
| Git subcommands are standalone executables that live in the Git exec |
| path, normally /usr/lib/git-core. The git executable itself is a |
| thin wrapper that knows where the subcommands live, and runs them by |
| passing command-line arguments to them. |
| |
| (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. |
| |
| 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. Import utilities, |
| surgical tools, remote helpers and other code at the edges of the |
| Git suite are more lenient and we allow Python (and even Tcl/tk), |
| but they should not be used for core functions. |
| |
| This may change in the future. Especially Python is not allowed in |
| core because 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" (or "builtin/foo.c" if it is to be linked to the main |
| binary); 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. |
| |
| 1. Don't forget to sign off your patch! |
| |
| 2. Append your command name to one of the variables BUILTIN_OBJS, |
| EXTRA_PROGRAMS, SCRIPT_SH, SCRIPT_PERL or SCRIPT_PYTHON. |
| |
| 3. Drop its test in the t directory. |
| |
| 4. 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. |
| |
| 5. If your command has any dependency on a particular version of |
| your language, document it in the INSTALL file. |
| |
| 6. 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 command-list.txt |
| in the main directory. If the new command is part of the typical Git |
| workflow and you believe it common enough to be mentioned in 'git help', |
| map this command to a common group in the column [common]. |
| |
| 7. Give the maintainer one paragraph to include in the RelNotes file |
| to describe the new feature; a good place to do so is in the cover |
| letter [PATCH 0/n]. |
| |
| That's all there is to it. |