Junio C Hamano | 3dac504 | 2007-12-15 08:40:54 | [diff] [blame] | 1 | builtin API |
| 2 | =========== |
| 3 | |
| 4 | Adding a new built-in |
| 5 | --------------------- |
| 6 | |
Junio C Hamano | 4224f99 | 2008-06-23 07:14:08 | [diff] [blame] | 7 | There are 4 things to do to add a built-in command implementation to |
Junio C Hamano | 3dac504 | 2007-12-15 08:40:54 | [diff] [blame] | 8 | git: |
| 9 | |
| 10 | . Define the implementation of the built-in command `foo` with |
| 11 | signature: |
| 12 | |
| 13 | int cmd_foo(int argc, const char **argv, const char *prefix); |
| 14 | |
| 15 | . Add the external declaration for the function to `builtin.h`. |
| 16 | |
| 17 | . Add the command to `commands[]` table in `handle_internal_command()`, |
| 18 | defined in `git.c`. The entry should look like: |
| 19 | |
| 20 | { "foo", cmd_foo, <options> }, |
Junio C Hamano | 4224f99 | 2008-06-23 07:14:08 | [diff] [blame] | 21 | + |
| 22 | where options is the bitwise-or of: |
Junio C Hamano | 3dac504 | 2007-12-15 08:40:54 | [diff] [blame] | 23 | |
| 24 | `RUN_SETUP`:: |
| 25 | |
| 26 | Make sure there is a git directory to work on, and if there is a |
| 27 | work tree, chdir to the top of it if the command was invoked |
| 28 | in a subdirectory. If there is no work tree, no chdir() is |
| 29 | done. |
| 30 | |
| 31 | `USE_PAGER`:: |
| 32 | |
| 33 | If the standard output is connected to a tty, spawn a pager and |
| 34 | feed our output to it. |
| 35 | |
Junio C Hamano | 4224f99 | 2008-06-23 07:14:08 | [diff] [blame] | 36 | `NEED_WORK_TREE`:: |
| 37 | |
| 38 | Make sure there is a work tree, i.e. the command cannot act |
| 39 | on bare repositories. |
Junio C Hamano | 301bc7b | 2009-04-28 09:29:36 | [diff] [blame] | 40 | This only makes sense when `RUN_SETUP` is also set. |
Junio C Hamano | 4224f99 | 2008-06-23 07:14:08 | [diff] [blame] | 41 | |
Junio C Hamano | 3dac504 | 2007-12-15 08:40:54 | [diff] [blame] | 42 | . Add `builtin-foo.o` to `BUILTIN_OBJS` in `Makefile`. |
| 43 | |
| 44 | Additionally, if `foo` is a new command, there are 3 more things to do: |
| 45 | |
| 46 | . Add tests to `t/` directory. |
| 47 | |
| 48 | . Write documentation in `Documentation/git-foo.txt`. |
| 49 | |
Junio C Hamano | 4224f99 | 2008-06-23 07:14:08 | [diff] [blame] | 50 | . Add an entry for `git-foo` to `command-list.txt`. |
Junio C Hamano | 3dac504 | 2007-12-15 08:40:54 | [diff] [blame] | 51 | |
| 52 | |
| 53 | How a built-in is called |
| 54 | ------------------------ |
| 55 | |
| 56 | The implementation `cmd_foo()` takes three parameters, `argc`, `argv, |
| 57 | and `prefix`. The first two are similar to what `main()` of a |
| 58 | standalone command would be called with. |
| 59 | |
| 60 | When `RUN_SETUP` is specified in the `commands[]` table, and when you |
| 61 | were started from a subdirectory of the work tree, `cmd_foo()` is called |
| 62 | after chdir(2) to the top of the work tree, and `prefix` gets the path |
| 63 | to the subdirectory the command started from. This allows you to |
| 64 | convert a user-supplied pathname (typically relative to that directory) |
| 65 | to a pathname relative to the top of the work tree. |
| 66 | |
| 67 | The return value from `cmd_foo()` becomes the exit status of the |
| 68 | command. |