diff options
Diffstat (limited to 'Documentation/technical/api-command.txt')
| -rw-r--r-- | Documentation/technical/api-command.txt | 99 |
1 files changed, 0 insertions, 99 deletions
diff --git a/Documentation/technical/api-command.txt b/Documentation/technical/api-command.txt deleted file mode 100644 index d3b978177b..0000000000 --- a/Documentation/technical/api-command.txt +++ /dev/null @@ -1,99 +0,0 @@ -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 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 git-cmmands.txt -in the main directory. - -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. |