From 530e741c726a612d78de21957d531dd2215483b4 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Sat, 24 Nov 2007 23:48:04 -0800 Subject: 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 --- Documentation/technical/api-builtin.txt | 63 +++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 Documentation/technical/api-builtin.txt (limited to 'Documentation/technical/api-builtin.txt') 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, }, + + 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. -- cgit v1.2.3 From 82936f295f803a8f1fbe2d89856e9371baa3536c Mon Sep 17 00:00:00 2001 From: Stephan Beyer Date: Sun, 22 Jun 2008 01:54:36 +0200 Subject: api-builtin.txt: update and fix typo Mention NEED_WORK_TREE flag and command-list.txt. Fix "bulit-in" typo and AsciiDoc-formatting of a paragraph. Signed-off-by: Stephan Beyer Signed-off-by: Junio C Hamano --- Documentation/technical/api-builtin.txt | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) (limited to 'Documentation/technical/api-builtin.txt') diff --git a/Documentation/technical/api-builtin.txt b/Documentation/technical/api-builtin.txt index 52cdb4c520..7ede1e64e5 100644 --- a/Documentation/technical/api-builtin.txt +++ b/Documentation/technical/api-builtin.txt @@ -4,7 +4,7 @@ builtin API Adding a new built-in --------------------- -There are 4 things to do to add a bulit-in command implementation to +There are 4 things to do to add a built-in command implementation to git: . Define the implementation of the built-in command `foo` with @@ -18,8 +18,8 @@ git: defined in `git.c`. The entry should look like: { "foo", cmd_foo, }, - - where options is the bitwise-or of: ++ +where options is the bitwise-or of: `RUN_SETUP`:: @@ -33,6 +33,12 @@ git: If the standard output is connected to a tty, spawn a pager and feed our output to it. +`NEED_WORK_TREE`:: + + Make sure there is a work tree, i.e. the command cannot act + on bare repositories. + This makes only sense when `RUN_SETUP` is also set. + . Add `builtin-foo.o` to `BUILTIN_OBJS` in `Makefile`. Additionally, if `foo` is a new command, there are 3 more things to do: @@ -41,8 +47,7 @@ Additionally, if `foo` is a new command, there are 3 more things to do: . Write documentation in `Documentation/git-foo.txt`. -. Add an entry for `git-foo` to the list at the end of - `Documentation/cmd-list.perl`. +. Add an entry for `git-foo` to `command-list.txt`. How a built-in is called -- cgit v1.2.3 From d649048e68f2f5d59f6f961839c9e9772743a505 Mon Sep 17 00:00:00 2001 From: Allan Caffee Date: Mon, 13 Apr 2009 14:11:21 -0400 Subject: Documentation: fix a grammatical error in api-builtin.txt Signed-off-by: Allan Caffee Signed-off-by: Junio C Hamano --- Documentation/technical/api-builtin.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/technical/api-builtin.txt') diff --git a/Documentation/technical/api-builtin.txt b/Documentation/technical/api-builtin.txt index 7ede1e64e5..5cb2b0590a 100644 --- a/Documentation/technical/api-builtin.txt +++ b/Documentation/technical/api-builtin.txt @@ -37,7 +37,7 @@ where options is the bitwise-or of: Make sure there is a work tree, i.e. the command cannot act on bare repositories. - This makes only sense when `RUN_SETUP` is also set. + This only makes sense when `RUN_SETUP` is also set. . Add `builtin-foo.o` to `BUILTIN_OBJS` in `Makefile`. -- cgit v1.2.3