blob: 15a4c8031f1f3bee61ca77d4d37b7ae443d98d9c [file] [log] [blame]
Thomas Ackermann81670e92012-12-21 19:05:28 +01001From: Eric S. Raymond <esr@thyrsus.com>
2Abstract: This is how-to documentation for people who want to add extension
Thomas Ackermann2de9b712013-01-21 20:17:53 +01003 commands to Git. It should be read alongside api-builtin.txt.
Thomas Ackermann81670e92012-12-21 19:05:28 +01004Content-type: text/asciidoc
5
6How to integrate new subcommands
7================================
Eric S. Raymond29ed5482012-11-26 00:35:57 -05008
9This is how-to documentation for people who want to add extension
Thomas Ackermann2de9b712013-01-21 20:17:53 +010010commands to Git. It should be read alongside api-builtin.txt.
Eric S. Raymond29ed5482012-11-26 00:35:57 -050011
12Runtime environment
13-------------------
14
Thomas Ackermann2de9b712013-01-21 20:17:53 +010015Git subcommands are standalone executables that live in the Git exec
Eric S. Raymond29ed5482012-11-26 00:35:57 -050016path, normally /usr/lib/git-core. The git executable itself is a
17thin wrapper that knows where the subcommands live, and runs them by
18passing command-line arguments to them.
19
Thomas Ackermann2de9b712013-01-21 20:17:53 +010020(If "git foo" is not found in the Git exec path, the wrapper
Eric S. Raymond29ed5482012-11-26 00:35:57 -050021will look in the rest of your $PATH for it. Thus, it's possible
Thomas Ackermann2de9b712013-01-21 20:17:53 +010022to write local Git extensions that don't live in system space.)
Eric S. Raymond29ed5482012-11-26 00:35:57 -050023
24Implementation languages
25------------------------
26
27Most subcommands are written in C or shell. A few are written in
28Perl.
29
30While we strongly encourage coding in portable C for portability,
31these specific scripting languages are also acceptable. We won't
32accept more without a very strong technical case, as we don't want
Thomas Ackermann2de9b712013-01-21 20:17:53 +010033to broaden the Git suite's required dependencies. Import utilities,
Eric S. Raymond29ed5482012-11-26 00:35:57 -050034surgical tools, remote helpers and other code at the edges of the
Thomas Ackermann2de9b712013-01-21 20:17:53 +010035Git suite are more lenient and we allow Python (and even Tcl/tk),
Eric S. Raymond29ed5482012-11-26 00:35:57 -050036but they should not be used for core functions.
37
38This may change in the future. Especially Python is not allowed in
Thomas Ackermann2de9b712013-01-21 20:17:53 +010039core because we need better Python integration in the Git Windows
Eric S. Raymond29ed5482012-11-26 00:35:57 -050040installer before we can be confident people in that environment
41won't experience an unacceptably large loss of capability.
42
43C commands are normally written as single modules, named after the
44command, that link a collection of functions called libgit. Thus,
45your 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
47binary); this organization makes it easy for people reading the code
48to find things.
49
50See the CodingGuidelines document for other guidance on what we consider
51good practice in C and shell, and api-builtin.txt for the support
52functions available to built-in commands written in C.
53
54What every extension command needs
55----------------------------------
56
Thomas Ackermann2de9b712013-01-21 20:17:53 +010057You must have a man page, written in asciidoc (this is what Git help
Eric S. Raymond29ed5482012-11-26 00:35:57 -050058followed by your subcommand name will display). Be aware that there is
59a local asciidoc configuration and macros which you should use. It's
60often helpful to start by cloning an existing page and replacing the
61text content.
62
63You must have a test, written to report in TAP (Test Anything Protocol).
64Tests are executables (usually shell scripts) that live in the 't'
65subdirectory of the tree. Each test name begins with 't' and a sequence
66number that controls where in the test sequence it will be executed;
67conventionally the rest of the name stem is that of the command
68being tested.
69
70Read the file t/README to learn more about the conventions to be used
71in writing tests, and the test support library.
72
73Integrating a command
74---------------------
75
76Here are the things you need to do when you want to merge a new
Thomas Ackermann2de9b712013-01-21 20:17:53 +010077subcommand into the Git tree.
Eric S. Raymond29ed5482012-11-26 00:35:57 -050078
Thomas Ackermannfef11962012-12-15 09:29:07 +0100791. Don't forget to sign off your patch!
Eric S. Raymond29ed5482012-11-26 00:35:57 -050080
Thomas Ackermannfef11962012-12-15 09:29:07 +0100812. Append your command name to one of the variables BUILTIN_OBJS,
Eric S. Raymond29ed5482012-11-26 00:35:57 -050082EXTRA_PROGRAMS, SCRIPT_SH, SCRIPT_PERL or SCRIPT_PYTHON.
83
Thomas Ackermannfef11962012-12-15 09:29:07 +0100843. Drop its test in the t directory.
Eric S. Raymond29ed5482012-11-26 00:35:57 -050085
Thomas Ackermannfef11962012-12-15 09:29:07 +0100864. If your command is implemented in an interpreted language with a
Eric S. Raymond29ed5482012-11-26 00:35:57 -050087p-code intermediate form, make sure .gitignore in the main directory
88includes a pattern entry that ignores such files. Python .pyc and
89.pyo files will already be covered.
90
Thomas Ackermannfef11962012-12-15 09:29:07 +0100915. If your command has any dependency on a particular version of
Eric S. Raymond29ed5482012-11-26 00:35:57 -050092your language, document it in the INSTALL file.
93
Thomas Ackermannfef11962012-12-15 09:29:07 +0100946. There is a file command-list.txt in the distribution main directory
Eric S. Raymond29ed5482012-11-26 00:35:57 -050095that categorizes commands by type, so they can be listed in appropriate
96subsections in the documentation's summary command list. Add an entry
Nguyễn Thái Ngọc Duy82f61782016-06-25 15:55:14 +020097for yours. To understand the categories, look at command-list.txt
Sébastien Guimmara413f50b2015-05-21 19:39:19 +020098in the main directory. If the new command is part of the typical Git
99workflow and you believe it common enough to be mentioned in 'git help',
100map this command to a common group in the column [common].
Eric S. Raymond29ed5482012-11-26 00:35:57 -0500101
Thomas Ackermannfef11962012-12-15 09:29:07 +01001027. Give the maintainer one paragraph to include in the RelNotes file
Eric S. Raymond29ed5482012-11-26 00:35:57 -0500103to describe the new feature; a good place to do so is in the cover
104letter [PATCH 0/n].
105
106That's all there is to it.