d85e9448dd
Commit ec14d4ecb5 (builtin.h: take over documentation from
api-builtin.txt, 2017-08-02) deleted api-builtin.txt and moved the
contents into builtin.h, but new-command.txt still references the old
file.
Signed-off-by: Wes Lord <weslord@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
107 lines
4.4 KiB
Plaintext
107 lines
4.4 KiB
Plaintext
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.
|