]>
Commit | Line | Data |
---|---|---|
81670e9b TA |
1 | From: Eric S. Raymond <esr@thyrsus.com> |
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 | |
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. |
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. |
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 |
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. |