# [PATCH 0/2] check-docs: fix 'diagnose' and 'version' 4 messages from 2022-09-20 to 2022-09-20. Participants: Victoria Dye via GitGitGadget, Junio C Hamano. Thread: https://gitlist.dev/t/58459 ## Victoria Dye via GitGitGadget, 2022-09-20 00:19 Subject: [PATCH 0/2] check-docs: fix 'diagnose' and 'version' Message-ID: URL: https://gitlist.dev/e/pull.1360.git.1663633195.gitgitgadget%40gmail.com ``` While locally verifying an unrelated documentation change, I noticed that the 'check-docs' target displayed two warnings on the 'master' branch: no link: git-diagnose removed but documented: git-version The first message was due to the introduction of 'git diagnose' [1] not including a corresponding update to 'command-list.txt'; the latter was due to 'git-version' not being built as a standalone builtin executable. This series corrects both, adding 'git-diagnose' and 'git-version' as "ancilliaryinterrogators" to 'command-list.txt' and building a 'git-version' executable. A possible future improvement to avoid this sort of thing could be to have 'check-docs' exit with an error if it encounters any issues (rather than printing a warning that's easily lost in build logs). For now, though, this series is restricted to fixing what's currently broken for ease of review and minimal risk. Maintainer's note: if this would be too much of a disruption to include in v2.38 last-minute, I'm happy deferring it to the next release cycle. Alternatively, the series could be split, aiming to review & merge the first patch in this release cycle (since the 'git diagnose' error was introduced in this version) and leave the second the next cycle. Thanks! * Victoria [1] https://lore.kernel.org/git/pull.1310.v4.git.1660335019.gitgitgadget@gmail.com/ Victoria Dye (2): diagnose: add to command-list.txt version: fix builtin linking & documentation .gitignore | 1 + Makefile | 1 + command-list.txt | 2 ++ 3 files changed, 4 insertions(+) base-commit: dda7228a83e2e9ff584bf6adbf55910565b41e14 Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1360%2Fvdye%2Fbugfix%2Fcheck-docs-fixes-v1 Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1360/vdye/bugfix/check-docs-fixes-v1 Pull-Request: https://github.com/gitgitgadget/git/pull/1360 -- gitgitgadget ``` ## Victoria Dye via GitGitGadget, 2022-09-20 00:19 Subject: [PATCH 1/2] diagnose: add to command-list.txt Message-ID: <68b4d8bea78568f8f00164a7b7c3f8e724699bd9.1663633195.git.gitgitgadget@gmail.com> URL: https://gitlist.dev/e/68b4d8bea78568f8f00164a7b7c3f8e724699bd9.1663633195.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Victoria Dye Add 'git diagnose' as an "ancilliaryinterrogator" (like 'git bugreport') to 'command-list.txt' in order to have it show up in 'git help -a' and avoid the "no link" warning message from the 'check-docs' Makefile target. Signed-off-by: Victoria Dye --- command-list.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/command-list.txt b/command-list.txt index 93f94e42ab7..bb2e0a9214b 100644 --- a/command-list.txt +++ b/command-list.txt @@ -91,6 +91,7 @@ git-cvsimport foreignscminterface git-cvsserver foreignscminterface git-daemon synchingrepositories git-describe mainporcelain +git-diagnose ancillaryinterrogators git-diff mainporcelain info git-diff-files plumbinginterrogators git-diff-index plumbinginterrogators -- gitgitgadget ``` ## Victoria Dye via GitGitGadget, 2022-09-20 00:19 Subject: [PATCH 2/2] version: fix builtin linking & documentation Message-ID: URL: https://gitlist.dev/e/f97ca224ef4d33c098048fa9c80003dfa960da96.1663633195.git.gitgitgadget%40gmail.com In-Reply-To: ``` From: Victoria Dye Like most builtins, 'version' is documented in a corresponding 'Documentation/git-version.txt' and can be invoked with 'git version'. However, the 'check-docs' Makefile target showed that it was "removed but documented: git-version." This was cause by the fact that it is not built as a standalone 'git-version' executable, therefore appearing "removed" to 'check-docs'. Without a precedent for documented builtins that aren't built into an executable *or* any clear reason why a standalone 'git-version' shouldn't exist, the 'check-docs' error appears to correctly identify an issue. To correct that mismatch, add 'git-version' to the 'BUILT_INS' list in the root Makefile (indicating that the 'cmd_version()' function appears in a file that is *not* 'builtin/version.c'). Additionally, to avoid the "no link" message in 'check-docs', list 'git-version' as an "ancilliaryinterrogator" (like 'git help') in 'command-list.txt'. Signed-off-by: Victoria Dye --- .gitignore | 1 + Makefile | 1 + command-list.txt | 1 + 3 files changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index 3d1b880101e..b3dcafcb331 100644 --- a/.gitignore +++ b/.gitignore @@ -181,6 +181,7 @@ /git-verify-commit /git-verify-pack /git-verify-tag +/git-version /git-web--browse /git-whatchanged /git-worktree diff --git a/Makefile b/Makefile index 35a07f80c52..cac3452edb9 100644 --- a/Makefile +++ b/Makefile @@ -818,6 +818,7 @@ BUILT_INS += git-show$X BUILT_INS += git-stage$X BUILT_INS += git-status$X BUILT_INS += git-switch$X +BUILT_INS += git-version$X BUILT_INS += git-whatchanged$X # what 'all' will build but not install in gitexecdir diff --git a/command-list.txt b/command-list.txt index bb2e0a9214b..54b2a50f5f1 100644 --- a/command-list.txt +++ b/command-list.txt @@ -199,6 +199,7 @@ git-var plumbinginterrogators git-verify-commit ancillaryinterrogators git-verify-pack plumbinginterrogators git-verify-tag ancillaryinterrogators +git-version ancillaryinterrogators git-whatchanged ancillaryinterrogators complete git-worktree mainporcelain git-write-tree plumbingmanipulators -- gitgitgadget ``` ## Junio C Hamano, 2022-09-20 00:27 Subject: Re: [PATCH 0/2] check-docs: fix 'diagnose' and 'version' Message-ID: URL: https://gitlist.dev/e/xmqqbkra99gh.fsf%40gitster.g In-Reply-To: ``` "Victoria Dye via GitGitGadget" writes: > While locally verifying an unrelated documentation change, I noticed that > the 'check-docs' target displayed two warnings on the 'master' branch: > > no link: git-diagnose > removed but documented: git-version > > > The first message was due to the introduction of 'git diagnose' [1] not > including a corresponding update to 'command-list.txt'; the latter was due > to 'git-version' not being built as a standalone builtin executable. This > series corrects both, adding 'git-diagnose' and 'git-version' as > "ancilliaryinterrogators" to 'command-list.txt' and building a 'git-version' > executable. Very much appreciated. I agree that making it an error would have helped us a lot, and I also agree with you that it can be left for the next cycle. Will queue. Thanks. ```