diff options
author | Junio C Hamano <gitster@pobox.com> | 2007-11-24 23:48:04 -0800 |
---|---|---|
committer | Junio C Hamano <gitster@pobox.com> | 2007-12-14 22:29:38 -0800 |
commit | 530e741c726a612d78de21957d531dd2215483b4 (patch) | |
tree | 52cc876e8da8eb90edfabb1f85159d065a78bc91 /Documentation/technical/api-builtin.txt | |
parent | fa4701601a62664a9246a211c5d26f238820737e (diff) | |
download | git-530e741c726a612d78de21957d531dd2215483b4.tar.gz |
Start preparing the API documents.
Most of them are still stubs, but the procedure to build the HTML
documentation, maintaining the index and installing the end product are
there.
I placed names of people who are likely to know the most about the topic
in the stub files, so that volunteers will know whom to ask questions as
needed.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Diffstat (limited to 'Documentation/technical/api-builtin.txt')
-rw-r--r-- | Documentation/technical/api-builtin.txt | 63 |
1 files changed, 63 insertions, 0 deletions
diff --git a/Documentation/technical/api-builtin.txt b/Documentation/technical/api-builtin.txt new file mode 100644 index 0000000000..52cdb4c520 --- /dev/null +++ b/Documentation/technical/api-builtin.txt @@ -0,0 +1,63 @@ +builtin API +=========== + +Adding a new built-in +--------------------- + +There are 4 things to do to add a bulit-in command implementation to +git: + +. Define the implementation of the built-in command `foo` with + signature: + + int cmd_foo(int argc, const char **argv, const char *prefix); + +. Add the external declaration for the function to `builtin.h`. + +. Add the command to `commands[]` table in `handle_internal_command()`, + defined in `git.c`. The entry should look like: + + { "foo", cmd_foo, <options> }, + + where options is the bitwise-or of: + +`RUN_SETUP`:: + + Make sure there is a git directory to work on, and if there is a + work tree, chdir to the top of it if the command was invoked + in a subdirectory. If there is no work tree, no chdir() is + done. + +`USE_PAGER`:: + + If the standard output is connected to a tty, spawn a pager and + feed our output to it. + +. Add `builtin-foo.o` to `BUILTIN_OBJS` in `Makefile`. + +Additionally, if `foo` is a new command, there are 3 more things to do: + +. Add tests to `t/` directory. + +. Write documentation in `Documentation/git-foo.txt`. + +. Add an entry for `git-foo` to the list at the end of + `Documentation/cmd-list.perl`. + + +How a built-in is called +------------------------ + +The implementation `cmd_foo()` takes three parameters, `argc`, `argv, +and `prefix`. The first two are similar to what `main()` of a +standalone command would be called with. + +When `RUN_SETUP` is specified in the `commands[]` table, and when you +were started from a subdirectory of the work tree, `cmd_foo()` is called +after chdir(2) to the top of the work tree, and `prefix` gets the path +to the subdirectory the command started from. This allows you to +convert a user-supplied pathname (typically relative to that directory) +to a pathname relative to the top of the work tree. + +The return value from `cmd_foo()` becomes the exit status of the +command. |