{"thread":{"id":"58459","subject":"[PATCH 0/2] check-docs: fix 'diagnose' and 'version'","startedAt":"2022-09-20T00:20:06Z","lastAt":"2022-09-20T00:27:24Z","messageCount":4,"participants":["Victoria Dye via GitGitGadget","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"463244","messageId":"pull.1360.git.1663633195.gitgitgadget@gmail.com","threadId":"58459","inReplyTo":null,"subject":"[PATCH 0/2] check-docs: fix 'diagnose' and 'version'","fromName":"Victoria Dye via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-09-20T00:19:53Z","receivedAt":"2022-09-20T00:20:06Z","isPatch":true,"sender":{"key":"vdye@github.com","avatar":"https://avatars.githubusercontent.com/u/3619353?v=4"},"body":"While locally verifying an unrelated documentation change, I noticed that\nthe 'check-docs' target displayed two warnings on the 'master' branch:\n\nno link: git-diagnose\nremoved but documented: git-version\n\n\nThe first message was due to the introduction of 'git diagnose' [1] not\nincluding a corresponding update to 'command-list.txt'; the latter was due\nto 'git-version' not being built as a standalone builtin executable. This\nseries corrects both, adding 'git-diagnose' and 'git-version' as\n\"ancilliaryinterrogators\" to 'command-list.txt' and building a 'git-version'\nexecutable.\n\nA possible future improvement to avoid this sort of thing could be to have\n'check-docs' exit with an error if it encounters any issues (rather than\nprinting a warning that's easily lost in build logs). For now, though, this\nseries is restricted to fixing what's currently broken for ease of review\nand minimal risk.\n\nMaintainer's note: if this would be too much of a disruption to include in\nv2.38 last-minute, I'm happy deferring it to the next release cycle.\nAlternatively, the series could be split, aiming to review & merge the first\npatch in this release cycle (since the 'git diagnose' error was introduced\nin this version) and leave the second the next cycle.\n\nThanks!\n\n * Victoria\n\n[1]\nhttps://lore.kernel.org/git/pull.1310.v4.git.1660335019.gitgitgadget@gmail.com/\n\nVictoria Dye (2):\n diagnose: add to command-list.txt\n version: fix builtin linking & documentation\n\n .gitignore | 1 +\n Makefile | 1 +\n command-list.txt | 2 ++\n 3 files changed, 4 insertions(+)\n\n\nbase-commit: dda7228a83e2e9ff584bf6adbf55910565b41e14\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1360%2Fvdye%2Fbugfix%2Fcheck-docs-fixes-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1360/vdye/bugfix/check-docs-fixes-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1360\n-- \ngitgitgadget\n"},{"id":"463245","messageId":"68b4d8bea78568f8f00164a7b7c3f8e724699bd9.1663633195.git.gitgitgadget@gmail.com","threadId":"58459","inReplyTo":"pull.1360.git.1663633195.gitgitgadget@gmail.com","subject":"[PATCH 1/2] diagnose: add to command-list.txt","fromName":"Victoria Dye via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-09-20T00:19:54Z","receivedAt":"2022-09-20T00:20:08Z","isPatch":true,"sender":{"key":"vdye@github.com","avatar":"https://avatars.githubusercontent.com/u/3619353?v=4"},"body":"From: Victoria Dye \n\nAdd 'git diagnose' as an \"ancilliaryinterrogator\" (like 'git bugreport') to\n'command-list.txt' in order to have it show up in 'git help -a' and avoid\nthe \"no link\" warning message from the 'check-docs' Makefile target.\n\nSigned-off-by: Victoria Dye \n---\n command-list.txt | 1 +\n 1 file changed, 1 insertion(+)\n\ndiff --git a/command-list.txt b/command-list.txt\nindex 93f94e42ab7..bb2e0a9214b 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -91,6 +91,7 @@ git-cvsimport foreignscminterface\n git-cvsserver foreignscminterface\n git-daemon synchingrepositories\n git-describe mainporcelain\n+git-diagnose ancillaryinterrogators\n git-diff mainporcelain info\n git-diff-files plumbinginterrogators\n git-diff-index plumbinginterrogators\n-- \ngitgitgadget\n\n"},{"id":"463246","messageId":"f97ca224ef4d33c098048fa9c80003dfa960da96.1663633195.git.gitgitgadget@gmail.com","threadId":"58459","inReplyTo":"pull.1360.git.1663633195.gitgitgadget@gmail.com","subject":"[PATCH 2/2] version: fix builtin linking & documentation","fromName":"Victoria Dye via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-09-20T00:19:55Z","receivedAt":"2022-09-20T00:20:09Z","isPatch":true,"sender":{"key":"vdye@github.com","avatar":"https://avatars.githubusercontent.com/u/3619353?v=4"},"body":"From: Victoria Dye \n\nLike most builtins, 'version' is documented in a corresponding\n'Documentation/git-version.txt' and can be invoked with 'git version'.\nHowever, the 'check-docs' Makefile target showed that it was \"removed but\ndocumented: git-version.\" This was cause by the fact that it is not built as\na standalone 'git-version' executable, therefore appearing \"removed\" to\n'check-docs'.\n\nWithout a precedent for documented builtins that aren't built into an\nexecutable *or* any clear reason why a standalone 'git-version' shouldn't\nexist, the 'check-docs' error appears to correctly identify an issue. To\ncorrect that mismatch, add 'git-version' to the 'BUILT_INS' list in the root\nMakefile (indicating that the 'cmd_version()' function appears in a file\nthat is *not* 'builtin/version.c'). Additionally, to avoid the \"no link\"\nmessage in 'check-docs', list 'git-version' as an \"ancilliaryinterrogator\"\n(like 'git help') in 'command-list.txt'.\n\nSigned-off-by: Victoria Dye \n---\n .gitignore | 1 +\n Makefile | 1 +\n command-list.txt | 1 +\n 3 files changed, 3 insertions(+)\n\ndiff --git a/.gitignore b/.gitignore\nindex 3d1b880101e..b3dcafcb331 100644\n--- a/.gitignore\n+++ b/.gitignore\n@@ -181,6 +181,7 @@\n /git-verify-commit\n /git-verify-pack\n /git-verify-tag\n+/git-version\n /git-web--browse\n /git-whatchanged\n /git-worktree\ndiff --git a/Makefile b/Makefile\nindex 35a07f80c52..cac3452edb9 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -818,6 +818,7 @@ BUILT_INS += git-show$X\n BUILT_INS += git-stage$X\n BUILT_INS += git-status$X\n BUILT_INS += git-switch$X\n+BUILT_INS += git-version$X\n BUILT_INS += git-whatchanged$X\n \n # what 'all' will build but not install in gitexecdir\ndiff --git a/command-list.txt b/command-list.txt\nindex bb2e0a9214b..54b2a50f5f1 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -199,6 +199,7 @@ git-var plumbinginterrogators\n git-verify-commit ancillaryinterrogators\n git-verify-pack plumbinginterrogators\n git-verify-tag ancillaryinterrogators\n+git-version ancillaryinterrogators\n git-whatchanged ancillaryinterrogators complete\n git-worktree mainporcelain\n git-write-tree plumbingmanipulators\n-- \ngitgitgadget\n"},{"id":"463247","messageId":"xmqqbkra99gh.fsf@gitster.g","threadId":"58459","inReplyTo":"pull.1360.git.1663633195.gitgitgadget@gmail.com","subject":"Re: [PATCH 0/2] check-docs: fix 'diagnose' and 'version'","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-09-20T00:27:10Z","receivedAt":"2022-09-20T00:27:24Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Victoria Dye via GitGitGadget\" writes:\n\n> While locally verifying an unrelated documentation change, I noticed that\n> the 'check-docs' target displayed two warnings on the 'master' branch:\n>\n> no link: git-diagnose\n> removed but documented: git-version\n>\n>\n> The first message was due to the introduction of 'git diagnose' [1] not\n> including a corresponding update to 'command-list.txt'; the latter was due\n> to 'git-version' not being built as a standalone builtin executable. This\n> series corrects both, adding 'git-diagnose' and 'git-version' as\n> \"ancilliaryinterrogators\" to 'command-list.txt' and building a 'git-version'\n> executable.\n\nVery much appreciated. I agree that making it an error would have\nhelped us a lot, and I also agree with you that it can be left for\nthe next cycle.\n\nWill queue. Thanks.\n"}]}