@matheusbsbs / matheus-bagliano / commits / 2ac93bfcbc

builtin.h: update documentation

The documentation for the builtin API was moved from the technical documentation and into a comment in builtin.h by ec14d4ecb5 (builtin.h: take over documentation from api-builtin.txt, 2017-08-02). This documentation wasn't updated as part of the major overhaul to include a repository struct in 9b1cb5070f (builtin: add a repository parameter for builtin functions, 2024-09-13). There was a brief update regarding the move from *.txt to *.adoc by e8015223c7 (builtin.h: *.txt -> *.adoc fixes, 2025-03-03). I noticed that there was quite a bit missing from the old documentation, which is still visible on git-scm.com [1]. [1] https://github.com/git/git-scm.com/issues/2124 This change updates the documentation in the following ways: 1. Updates the cmd_foo() prototype to include a repository. 2. Adds some newlines to have uniformity in the list of flags. 3. Adds a description of the NO_PARSEOPT flag. 4. Describes the tests that perform checks on all builtins, which may trip up a contributor working on a new builtin. I double-checked these instructions against a toy example in my local branch to be sure that it was complete. Signed-off-by: Derrick Stolee <stolee@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Derrick Stolee committed Jan 9, 2026 at 03:39 UTC 2ac93bfcbc28e28a4844095648988558dad02aa3
1 file changed +25 -1
builtin.h
+25 -1
index 1b35565fbd..e5e16ecaa6 100644 --- a/builtin.h +++ b/builtin.h @@ -17,7 +17,8 @@ * . Define the implementation of the built-in command `foo` with * signature: * - * int cmd_foo(int argc, const char **argv, const char *prefix); + * int cmd_foo(int argc, const char **argv, + * const char *prefix, struct repository *repo); * * . Add the external declaration for the function to `builtin.h`. * @@ -29,12 +30,14 @@ * 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. * @@ -57,6 +60,12 @@ * more informed decision, e.g., by ignoring `pager.<cmd>` for * certain subcommands. * + * `NO_PARSEOPT`: + * + * Most Git builtins use the parseopt library for parsing options. + * This flag indicates that a custom parser is used and thus the + * builtin would not appear in 'git --list-cmds=parseopt'. + * * . Add `builtin/foo.o` to `BUILTIN_OBJS` in `Makefile`. * * Additionally, if `foo` is a new command, there are 4 more things to do: @@ -69,6 +78,21 @@ * * . Add an entry for `/git-foo` to `.gitignore`. * + * As you work on implementing your builtin, be mindful that the + * following tests will check different aspects of the builtin's + * readiness and adherence to matching the documentation: + * + * * t0012-help.sh checks that the builtin can handle -h, which comes + * automatically with the parseopt API. + * + * * t0450-txt-doc-vs-help.sh checks that the -h help output matches the + * SYNOPSIS in the documentation for the builtin. + * + * * t1517-outside-repo.sh checks that the builtin can handle -h when + * run outside of the context of a repository. Note that this test + * requires that the usage has a space after the builtin name, so some + * minimum description of options is required. + * * * How a built-in is called * ------------------------