You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
99 lines
4.0 KiB
99 lines
4.0 KiB
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.
|
|
|