Documentation/howto/new-command.txt - jrn/git - Git at Google

 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.
	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.