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