Thomas Ackermann | 81670e9 | 2012-12-21 19:05:28 +0100 | [diff] [blame] | 1 | From: Eric S. Raymond <esr@thyrsus.com> |
| 2 | Abstract: This is how-to documentation for people who want to add extension |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 3 | commands to Git. It should be read alongside api-builtin.txt. |
Thomas Ackermann | 81670e9 | 2012-12-21 19:05:28 +0100 | [diff] [blame] | 4 | Content-type: text/asciidoc |
| 5 | |
| 6 | How to integrate new subcommands |
| 7 | ================================ |
Eric S. Raymond | 29ed548 | 2012-11-26 00:35:57 -0500 | [diff] [blame] | 8 | |
| 9 | This is how-to documentation for people who want to add extension |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 10 | commands to Git. It should be read alongside api-builtin.txt. |
Eric S. Raymond | 29ed548 | 2012-11-26 00:35:57 -0500 | [diff] [blame] | 11 | |
| 12 | Runtime environment |
| 13 | ------------------- |
| 14 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 15 | Git subcommands are standalone executables that live in the Git exec |
Eric S. Raymond | 29ed548 | 2012-11-26 00:35:57 -0500 | [diff] [blame] | 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 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 20 | (If "git foo" is not found in the Git exec path, the wrapper |
Eric S. Raymond | 29ed548 | 2012-11-26 00:35:57 -0500 | [diff] [blame] | 21 | will look in the rest of your $PATH for it. Thus, it's possible |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 22 | to write local Git extensions that don't live in system space.) |
Eric S. Raymond | 29ed548 | 2012-11-26 00:35:57 -0500 | [diff] [blame] | 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 |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 33 | to broaden the Git suite's required dependencies. Import utilities, |
Eric S. Raymond | 29ed548 | 2012-11-26 00:35:57 -0500 | [diff] [blame] | 34 | surgical tools, remote helpers and other code at the edges of the |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 35 | Git suite are more lenient and we allow Python (and even Tcl/tk), |
Eric S. Raymond | 29ed548 | 2012-11-26 00:35:57 -0500 | [diff] [blame] | 36 | but they should not be used for core functions. |
| 37 | |
| 38 | This may change in the future. Especially Python is not allowed in |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 39 | core because we need better Python integration in the Git Windows |
Eric S. Raymond | 29ed548 | 2012-11-26 00:35:57 -0500 | [diff] [blame] | 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 | |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 57 | You must have a man page, written in asciidoc (this is what Git help |
Eric S. Raymond | 29ed548 | 2012-11-26 00:35:57 -0500 | [diff] [blame] | 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 |
Thomas Ackermann | 2de9b71 | 2013-01-21 20:17:53 +0100 | [diff] [blame] | 77 | subcommand into the Git tree. |
Eric S. Raymond | 29ed548 | 2012-11-26 00:35:57 -0500 | [diff] [blame] | 78 | |
Thomas Ackermann | fef1196 | 2012-12-15 09:29:07 +0100 | [diff] [blame] | 79 | 1. Don't forget to sign off your patch! |
Eric S. Raymond | 29ed548 | 2012-11-26 00:35:57 -0500 | [diff] [blame] | 80 | |
Thomas Ackermann | fef1196 | 2012-12-15 09:29:07 +0100 | [diff] [blame] | 81 | 2. Append your command name to one of the variables BUILTIN_OBJS, |
Eric S. Raymond | 29ed548 | 2012-11-26 00:35:57 -0500 | [diff] [blame] | 82 | EXTRA_PROGRAMS, SCRIPT_SH, SCRIPT_PERL or SCRIPT_PYTHON. |
| 83 | |
Thomas Ackermann | fef1196 | 2012-12-15 09:29:07 +0100 | [diff] [blame] | 84 | 3. Drop its test in the t directory. |
Eric S. Raymond | 29ed548 | 2012-11-26 00:35:57 -0500 | [diff] [blame] | 85 | |
Thomas Ackermann | fef1196 | 2012-12-15 09:29:07 +0100 | [diff] [blame] | 86 | 4. If your command is implemented in an interpreted language with a |
Eric S. Raymond | 29ed548 | 2012-11-26 00:35:57 -0500 | [diff] [blame] | 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 | |
Thomas Ackermann | fef1196 | 2012-12-15 09:29:07 +0100 | [diff] [blame] | 91 | 5. If your command has any dependency on a particular version of |
Eric S. Raymond | 29ed548 | 2012-11-26 00:35:57 -0500 | [diff] [blame] | 92 | your language, document it in the INSTALL file. |
| 93 | |
Thomas Ackermann | fef1196 | 2012-12-15 09:29:07 +0100 | [diff] [blame] | 94 | 6. There is a file command-list.txt in the distribution main directory |
Eric S. Raymond | 29ed548 | 2012-11-26 00:35:57 -0500 | [diff] [blame] | 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 |
Nguyễn Thái Ngọc Duy | 82f6178 | 2016-06-25 15:55:14 +0200 | [diff] [blame] | 97 | for yours. To understand the categories, look at command-list.txt |
Sébastien Guimmara | 413f50b | 2015-05-21 19:39:19 +0200 | [diff] [blame] | 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]. |
Eric S. Raymond | 29ed548 | 2012-11-26 00:35:57 -0500 | [diff] [blame] | 101 | |
Thomas Ackermann | fef1196 | 2012-12-15 09:29:07 +0100 | [diff] [blame] | 102 | 7. Give the maintainer one paragraph to include in the RelNotes file |
Eric S. Raymond | 29ed548 | 2012-11-26 00:35:57 -0500 | [diff] [blame] | 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. |