[thirdparty/git.git] / Documentation / howto / new-command.txt

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 api-builtin.txt.
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 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 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.
Commit	Line	Data
81670e9b TA	1	From: Eric S. Raymond <esr@thyrsus.com>
81670e9b TA	2	Abstract: This is how-to documentation for people who want to add extension
2de9b711	3	commands to Git. It should be read alongside api-builtin.txt.
81670e9b TA	4	Content-type: text/asciidoc
	5
	6	How to integrate new subcommands
	7	================================
29ed5489 ER	8
29ed5489 ER	9	This is how-to documentation for people who want to add extension
2de9b711	10	commands to Git. It should be read alongside api-builtin.txt.
29ed5489 ER	11
	12	Runtime environment
	13	-------------------
	14
2de9b711	15	Git subcommands are standalone executables that live in the Git exec
29ed5489 ER	16	path, normally /usr/lib/git-core. The git executable itself is a
	17	thin wrapper that knows where the subcommands live, and runs them by
	18	passing command-line arguments to them.
	19
2de9b711	20	(If "git foo" is not found in the Git exec path, the wrapper
29ed5489	21	will look in the rest of your $PATH for it. Thus, it's possible
2de9b711	22	to write local Git extensions that don't live in system space.)
29ed5489 ER	23
	24	Implementation languages
	25	------------------------
	26
	27	Most subcommands are written in C or shell. A few are written in
	28	Perl.
	29
	30	While we strongly encourage coding in portable C for portability,
	31	these specific scripting languages are also acceptable. We won't
	32	accept more without a very strong technical case, as we don't want
2de9b711	33	to broaden the Git suite's required dependencies. Import utilities,
29ed5489	34	surgical tools, remote helpers and other code at the edges of the
2de9b711	35	Git suite are more lenient and we allow Python (and even Tcl/tk),
29ed5489 ER	36	but they should not be used for core functions.
	37
	38	This may change in the future. Especially Python is not allowed in
2de9b711	39	core because we need better Python integration in the Git Windows
29ed5489 ER	40	installer before we can be confident people in that environment
	41	won't experience an unacceptably large loss of capability.
	42
	43	C commands are normally written as single modules, named after the
	44	command, that link a collection of functions called libgit. Thus,
	45	your command 'git-foo' would normally be implemented as a single
	46	"git-foo.c" (or "builtin/foo.c" if it is to be linked to the main
	47	binary); this organization makes it easy for people reading the code
	48	to find things.
	49
	50	See the CodingGuidelines document for other guidance on what we consider
	51	good practice in C and shell, and api-builtin.txt for the support
	52	functions available to built-in commands written in C.
	53
	54	What every extension command needs
	55	----------------------------------
	56
2de9b711	57	You must have a man page, written in asciidoc (this is what Git help
29ed5489 ER	58	followed by your subcommand name will display). Be aware that there is
	59	a local asciidoc configuration and macros which you should use. It's
	60	often helpful to start by cloning an existing page and replacing the
	61	text content.
	62
	63	You must have a test, written to report in TAP (Test Anything Protocol).
	64	Tests are executables (usually shell scripts) that live in the 't'
	65	subdirectory of the tree. Each test name begins with 't' and a sequence
	66	number that controls where in the test sequence it will be executed;
	67	conventionally the rest of the name stem is that of the command
	68	being tested.
	69
	70	Read the file t/README to learn more about the conventions to be used
	71	in writing tests, and the test support library.
	72
	73	Integrating a command
	74	---------------------
	75
	76	Here are the things you need to do when you want to merge a new
2de9b711	77	subcommand into the Git tree.
29ed5489	78
fef11965	79	1. Don't forget to sign off your patch!
29ed5489	80
fef11965	81	2. Append your command name to one of the variables BUILTIN_OBJS,
29ed5489 ER	82	EXTRA_PROGRAMS, SCRIPT_SH, SCRIPT_PERL or SCRIPT_PYTHON.
29ed5489 ER	83
fef11965	84	3. Drop its test in the t directory.
29ed5489	85
fef11965	86	4. If your command is implemented in an interpreted language with a
29ed5489 ER	87	p-code intermediate form, make sure .gitignore in the main directory
	88	includes a pattern entry that ignores such files. Python .pyc and
	89	.pyo files will already be covered.
	90
fef11965	91	5. If your command has any dependency on a particular version of
29ed5489 ER	92	your language, document it in the INSTALL file.
29ed5489 ER	93
fef11965	94	6. There is a file command-list.txt in the distribution main directory
29ed5489 ER	95	that categorizes commands by type, so they can be listed in appropriate
29ed5489 ER	96	subsections in the documentation's summary command list. Add an entry
82f6178a	97	for yours. To understand the categories, look at command-list.txt
413f50b9 SG	98	in the main directory. If the new command is part of the typical Git
	99	workflow and you believe it common enough to be mentioned in 'git help',
	100	map this command to a common group in the column [common].
29ed5489	101
fef11965	102	7. Give the maintainer one paragraph to include in the RelNotes file
29ed5489 ER	103	to describe the new feature; a good place to do so is in the cover
	104	letter [PATCH 0/n].
	105
	106	That's all there is to it.