path: root/Documentation/technical/api-builtin.txt
diff options
authorJunio C Hamano <>2007-11-25 07:48:04 (GMT)
committerJunio C Hamano <>2007-12-15 06:29:38 (GMT)
commit530e741c726a612d78de21957d531dd2215483b4 (patch)
tree52cc876e8da8eb90edfabb1f85159d065a78bc91 /Documentation/technical/api-builtin.txt
parentfa4701601a62664a9246a211c5d26f238820737e (diff)
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 <>
Diffstat (limited to 'Documentation/technical/api-builtin.txt')
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 0000000..52cdb4c
--- /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
+. 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:
+ 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.
+ 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