summaryrefslogtreecommitdiff
path: root/builtin.h
diff options
context:
space:
mode:
authorMartin Ågren <martin.agren@gmail.com>2017-08-02 21:40:49 +0200
committerJunio C Hamano <gitster@pobox.com>2017-08-03 11:08:10 -0700
commitec14d4ecb5507550e31ba0a0016eb83fcde48f3f (patch)
treee28711dbd18c6b97dc8423b7cec818f52a3439d2 /builtin.h
parent384a8b271c076693d00c97184b5c41ab3a95e64d (diff)
downloadgit-ec14d4ecb5507550e31ba0a0016eb83fcde48f3f.tar.gz
builtin.h: take over documentation from api-builtin.txt
Delete Documentation/technical/api-builtin.txt and move its content into builtin.h. Format it as a comment. Remove a '+' which was needed when the information was formatted for AsciiDoc. Similarly, change "::" to ":". Document SUPPORT_SUPER_PREFIX, thereby bringing the documentation up to date with the available flags. While at it, correct '3 more things to do' to '4 more things to do'. Signed-off-by: Martin Ågren <martin.agren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Diffstat (limited to 'builtin.h')
-rw-r--r--builtin.h80
1 files changed, 80 insertions, 0 deletions
diff --git a/builtin.h b/builtin.h
index 498ac80d07..8d87d06da4 100644
--- a/builtin.h
+++ b/builtin.h
@@ -6,6 +6,86 @@
#include "cache.h"
#include "commit.h"
+/*
+ * builtin API
+ * ===========
+ *
+ * Adding a new built-in
+ * ---------------------
+ *
+ * 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
+ * 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 the `commands[]` table defined in `git.c`.
+ * The entry should look like:
+ *
+ * { "foo", cmd_foo, <options> },
+ *
+ * where options is the bitwise-or of:
+ *
+ * `RUN_SETUP`:
+ * If there is not a Git directory to work on, abort. 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.
+ *
+ * `RUN_SETUP_GENTLY`:
+ * If there is a Git directory, chdir as per RUN_SETUP, otherwise,
+ * don't chdir anywhere.
+ *
+ * `USE_PAGER`:
+ *
+ * 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 only makes sense when `RUN_SETUP` is also set.
+ *
+ * `SUPPORT_SUPER_PREFIX`:
+ *
+ * The built-in supports `--super-prefix`.
+ *
+ * . Add `builtin/foo.o` to `BUILTIN_OBJS` in `Makefile`.
+ *
+ * Additionally, if `foo` is a new command, there are 4 more things to do:
+ *
+ * . Add tests to `t/` directory.
+ *
+ * . Write documentation in `Documentation/git-foo.txt`.
+ *
+ * . Add an entry for `git-foo` to `command-list.txt`.
+ *
+ * . Add an entry for `/git-foo` to `.gitignore`.
+ *
+ *
+ * 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.
+ */
+
#define DEFAULT_MERGE_LOG_LEN 20
extern const char git_usage_string[];