@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
@@ -17,7 +17,8 @@
17 * . Define the implementation of the built-in command `foo` with
18 * signature:
19 *
20 - * int cmd_foo(int argc, const char **argv, const char *prefix);
20 + * int cmd_foo(int argc, const char **argv,
21 + * const char *prefix, struct repository *repo);
22 *
23 * . Add the external declaration for the function to `builtin.h`.
24 *
@@ -29,12 +30,14 @@
30 * where options is the bitwise-or of:
31 *
32 * `RUN_SETUP`:
33 + *
34 * If there is not a Git directory to work on, abort. If there
35 * is a work tree, chdir to the top of it if the command was
36 * invoked in a subdirectory. If there is no work tree, no
37 * chdir() is done.
38 *
39 * `RUN_SETUP_GENTLY`:
40 + *
41 * If there is a Git directory, chdir as per RUN_SETUP, otherwise,
42 * don't chdir anywhere.
43 *
@@ -57,6 +60,12 @@
60 * more informed decision, e.g., by ignoring `pager.<cmd>` for
61 * certain subcommands.
62 *
63 + * `NO_PARSEOPT`:
64 + *
65 + * Most Git builtins use the parseopt library for parsing options.
66 + * This flag indicates that a custom parser is used and thus the
67 + * builtin would not appear in 'git --list-cmds=parseopt'.
68 + *
69 * . Add `builtin/foo.o` to `BUILTIN_OBJS` in `Makefile`.
70 *
71 * Additionally, if `foo` is a new command, there are 4 more things to do:
@@ -69,6 +78,21 @@
78 *
79 * . Add an entry for `/git-foo` to `.gitignore`.
80 *
81 + * As you work on implementing your builtin, be mindful that the
82 + * following tests will check different aspects of the builtin's
83 + * readiness and adherence to matching the documentation:
84 + *
85 + * * t0012-help.sh checks that the builtin can handle -h, which comes
86 + * automatically with the parseopt API.
87 + *
88 + * * t0450-txt-doc-vs-help.sh checks that the -h help output matches the
89 + * SYNOPSIS in the documentation for the builtin.
90 + *
91 + * * t1517-outside-repo.sh checks that the builtin can handle -h when
92 + * run outside of the context of a repository. Note that this test
93 + * requires that the usage has a space after the builtin name, so some
94 + * minimum description of options is required.
95 + *
96 *
97 * How a built-in is called
98 * ------------------------