100 lines
4.0 KiB
Plaintext
100 lines
4.0 KiB
Plaintext
|
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.
|
||
|
|
|
||
|
|
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 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. 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.
|