{"thread":{"id":"66298","subject":"[PATCH 0/2] guides: keep Documentation/Makefile and command-list.txt in sync","startedAt":"2026-09-09T05:25:11Z","lastAt":"2026-09-10T19:44:15Z","messageCount":8,"participants":["Tuomas Ahola","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"552277","messageId":"20260909052501.8448-1-taahol@utu.fi","threadId":"66298","inReplyTo":null,"subject":"[PATCH 0/2] guides: keep Documentation/Makefile and command-list.txt in sync","fromName":"Tuomas Ahola","fromEmail":"taahol@utu.fi","sentAt":"2026-09-09T05:24:59Z","receivedAt":"2026-09-09T05:25:11Z","isPatch":true,"body":"Documentation/lint-manpages.sh was expanded with a new test\nensuring that command-list.txt also includes all non-command\nmanual pages (concept guides and interface manuals).\n\nBased on kh/doc-datamodel.\n\nTuomas Ahola (2):\n  command-list: add gitformat-loose(5) and gitpacking(7)\n  lint-docs: check the guide list in command-list.txt\n\n Documentation/Makefile         | 2 ++\n Documentation/lint-manpages.sh | 9 ++++++---\n command-list.txt               | 2 ++\n 3 files changed, 10 insertions(+), 3 deletions(-)\n\n\nbase-commit: e9019fcafe0040228b8631c30f97ae1adb61bcdc\nprerequisite-patch-id: 13af80fdddfc7d4f65437343cee0ca3787cbdea4\n-- \nta/command-list-guides-sync-lint\n\n"},{"id":"552278","messageId":"20260909052501.8448-3-taahol@utu.fi","threadId":"66298","inReplyTo":"20260909052501.8448-1-taahol@utu.fi","subject":"[PATCH 2/2] lint-docs: check the guide list in command-list.txt","fromName":"Tuomas Ahola","fromEmail":"taahol@utu.fi","sentAt":"2026-09-09T05:25:01Z","receivedAt":"2026-09-09T05:25:15Z","isPatch":true,"body":"Since 2135e1ad70 (command-list.txt: add missing 'gitcredentials' and\n'gitremote-helpers', 2020-08-05) there has been a comment in\nDocumentation/Makefile reminding developers to add new guides also to\ncommand-list.txt.  However, there is no linter script to enforce that.\n\nAdapt Documentation/lint-manpages.sh to fill that role.  Extract\nMAN5_TXT and MAN7_TXT from the Makefile and check command-list.txt\nagainst them.  Exempt gitweb.conf(5) from the new linter routine.\n\nSigned-off-by: Tuomas Ahola <taahol@utu.fi>\n---\n\nNotes:\n    c655855559 (doc: git: list gitdatamodel(7) as a concept guide, 2026-09-05)\n    should be merged in to make the new test pass.\n\n Documentation/Makefile         | 2 ++\n Documentation/lint-manpages.sh | 9 ++++++---\n 2 files changed, 8 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 2699f0b24a..203f6a0c31 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -67,6 +67,8 @@ MAN7_TXT += gittutorial-2.adoc\n MAN7_TXT += gittutorial.adoc\n MAN7_TXT += gitworkflows.adoc\n \n+MAN_GUIDES = $(patsubst %.adoc,%,$(MAN5_TXT) $(MAN7_TXT))\n+\n HOWTO_TXT += $(wildcard howto/*.adoc)\n \n DOC_DEP_TXT += $(wildcard *.adoc)\ndiff --git a/Documentation/lint-manpages.sh b/Documentation/lint-manpages.sh\nindex a0ea572382..290ebe0947 100755\n--- a/Documentation/lint-manpages.sh\n+++ b/Documentation/lint-manpages.sh\n@@ -1,21 +1,22 @@\n #!/bin/sh\n \n extract_variable () {\n+\tfile=${2:-../Makefile}\n \t(\n-\t\tcat ../Makefile\n+\t\tcat $file\n \t\tcat <<EOF\n print_variable:\n \t@\\$(foreach b,\\$($1),echo XXX \\$(b:\\$X=) YYY;)\n EOF\n \t) |\n-\tmake -C .. -f - print_variable 2>/dev/null |\n+\tmake -C $(dirname $file) -f - print_variable 2>/dev/null |\n \tsed -n -e 's/.*XXX \\(.*\\) YYY.*/\\1/p'\n }\n \n check_missing_docs () (\n \tret=0\n \n-\tfor v in $ALL_COMMANDS\n+\tfor v in $ALL_COMMANDS $MAN_GUIDES\n \tdo\n \t\tcase \"$v\" in\n \t\tgit-merge-octopus) continue;;\n@@ -29,6 +30,7 @@ check_missing_docs () (\n \t\tgit-stage) continue;;\n \t\tgit-legacy-*) continue;;\n \t\tgit-?*--?* ) continue ;;\n+\t\tgitweb.conf) continue ;;\n \t\tesac\n \n \t\tif ! test -f \"$v.adoc\"\n@@ -87,6 +89,7 @@ check_extraneous_docs () {\n BUILT_INS=\"$(extract_variable BUILT_INS)\"\n ALL_COMMANDS=\"$(extract_variable ALL_COMMANDS)\"\n EXCLUDED_PROGRAMS=\"$(extract_variable EXCLUDED_PROGRAMS)\"\n+MAN_GUIDES=\"$(extract_variable MAN_GUIDES ./Makefile)\"\n \n findings=$(\n \tif ! check_missing_docs\n-- \nta/command-list-guides-sync-lint\n\n"},{"id":"552279","messageId":"20260909052501.8448-2-taahol@utu.fi","threadId":"66298","inReplyTo":"20260909052501.8448-1-taahol@utu.fi","subject":"[PATCH 1/2] command-list: add gitformat-loose(5) and gitpacking(7)","fromName":"Tuomas Ahola","fromEmail":"taahol@utu.fi","sentAt":"2026-09-09T05:25:00Z","receivedAt":"2026-09-09T05:25:15Z","isPatch":true,"body":"Three manpages from sections 5 and 7 are not featured in\ncommand-list.txt as concept guides or interface manuals.\n\nAs easy fixes, add gitformat-loose(5) to 'developerinterfaces'\nand make gitpacking(7) a 'guide'.\n\nThat leaves only gitweb.conf(5) which could be added to\n'userinterfaces'.  However, the manual would then appear\nas \"web.conf\" in `git help -a` which is just confusing.\nSo, perhaps we are better off by leaving it out.\n\nSigned-off-by: Tuomas Ahola <taahol@utu.fi>\n---\n command-list.txt | 2 ++\n 1 file changed, 2 insertions(+)\n\ndiff --git a/command-list.txt b/command-list.txt\nindex 63ae2a67c9..955eec6e7e 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -225,6 +225,7 @@ gitformat-bundle                        developerinterfaces\n gitformat-chunk                         developerinterfaces\n gitformat-commit-graph                  developerinterfaces\n gitformat-index                         developerinterfaces\n+gitformat-loose                         developerinterfaces\n gitformat-pack                          developerinterfaces\n gitformat-signature                     developerinterfaces\n gitglossary                             guide\n@@ -234,6 +235,7 @@ gitk                                    mainporcelain\n gitmailmap                              userinterfaces\n gitmodules                              userinterfaces\n gitnamespaces                           guide\n+gitpacking                              guide\n gitprotocol-capabilities                developerinterfaces\n gitprotocol-common                      developerinterfaces\n gitprotocol-http                        developerinterfaces\n-- \nta/command-list-guides-sync-lint\n\n"},{"id":"552342","messageId":"xmqq5x0es33y.fsf@gitster.g","threadId":"66298","inReplyTo":"20260909052501.8448-3-taahol@utu.fi","subject":"Re: [PATCH 2/2] lint-docs: check the guide list in command-list.txt","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-09-09T18:15:29Z","receivedAt":"2026-09-09T18:15:34Z","isPatch":true,"body":"Tuomas Ahola <taahol@utu.fi> writes:\n\n>  extract_variable () {\n> +\tfile=${2:-../Makefile}\n>  \t(\n> -\t\tcat ../Makefile\n> +\t\tcat $file\n\nNow you are allowing arbitrary path to be fed to this function, you\nshould prepare to accept arbitrary path, without assuming that $file\nhas no $IFS whitespaces.  I.e.,\n\n\t\tcat \"$file\"\n\n>  \t) |\n> -\tmake -C .. -f - print_variable 2>/dev/null |\n> +\tmake -C $(dirname $file) -f - print_variable 2>/dev/null |\n\nDitto.  $file itself may have $IFS whitespaces, and the result of\nrunning dirname on it may too.\n\n"},{"id":"552343","messageId":"xmqq1pb2s33e.fsf@gitster.g","threadId":"66298","inReplyTo":"20260909052501.8448-2-taahol@utu.fi","subject":"Re: [PATCH 1/2] command-list: add gitformat-loose(5) and gitpacking(7)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-09-09T18:15:49Z","receivedAt":"2026-09-09T18:15:51Z","isPatch":true,"body":"Tuomas Ahola <taahol@utu.fi> writes:\n\n> Three manpages from sections 5 and 7 are not featured in\n> command-list.txt as concept guides or interface manuals.\n>\n> As easy fixes, add gitformat-loose(5) to 'developerinterfaces'\n> and make gitpacking(7) a 'guide'.\n>\n> That leaves only gitweb.conf(5) which could be added to\n> 'userinterfaces'.  However, the manual would then appear\n> as \"web.conf\" in `git help -a` which is just confusing.\n> So, perhaps we are better off by leaving it out.\n>\n> Signed-off-by: Tuomas Ahola <taahol@utu.fi>\n> ---\n>  command-list.txt | 2 ++\n>  1 file changed, 2 insertions(+)\n\nGood eyes.  Thanks.\n\n>\n> diff --git a/command-list.txt b/command-list.txt\n> index 63ae2a67c9..955eec6e7e 100644\n> --- a/command-list.txt\n> +++ b/command-list.txt\n> @@ -225,6 +225,7 @@ gitformat-bundle                        developerinterfaces\n>  gitformat-chunk                         developerinterfaces\n>  gitformat-commit-graph                  developerinterfaces\n>  gitformat-index                         developerinterfaces\n> +gitformat-loose                         developerinterfaces\n>  gitformat-pack                          developerinterfaces\n>  gitformat-signature                     developerinterfaces\n>  gitglossary                             guide\n> @@ -234,6 +235,7 @@ gitk                                    mainporcelain\n>  gitmailmap                              userinterfaces\n>  gitmodules                              userinterfaces\n>  gitnamespaces                           guide\n> +gitpacking                              guide\n>  gitprotocol-capabilities                developerinterfaces\n>  gitprotocol-common                      developerinterfaces\n>  gitprotocol-http                        developerinterfaces\n"},{"id":"552485","messageId":"20260910194351.20809-1-taahol@utu.fi","threadId":"66298","inReplyTo":"20260909052501.8448-1-taahol@utu.fi","subject":"[PATCH v2 0/2] guides: keep Documentation/Makefile and command-list.txt in sync","fromName":"Tuomas Ahola","fromEmail":"taahol@utu.fi","sentAt":"2026-09-10T19:43:49Z","receivedAt":"2026-09-10T19:44:03Z","isPatch":true,"body":"Documentation/lint-manpages.sh was expanded with a new test\nensuring that command-list.txt also includes all non-command\nmanual pages (concept guides and interface manuals).\n\nBased on kh/doc-datamodel.\n\nChanges in v2:\n\n* [1/2]: Use command-list.txt as the area identifier.\n* [2/2]: Protect variables againtst whitespace breakage per review comment.\n\nTuomas Ahola (2):\n  command-list.txt: add gitformat-loose(5) and gitpacking(7)\n  lint-docs: check the guide list in command-list.txt\n\n Documentation/Makefile         |  2 ++\n Documentation/lint-manpages.sh | 10 +++++++---\n command-list.txt               |  2 ++\n 3 files changed, 11 insertions(+), 3 deletions(-)\n\nIntervall-diff mot v1:\n1:  014da7fdff ! 1:  cb6ce6cad1 command-list: add gitformat-loose(5) and gitpacking(7)\n    @@ Metadata\n     Author: Tuomas Ahola <taahol@utu.fi>\n     \n      ## Commit message ##\n    -    command-list: add gitformat-loose(5) and gitpacking(7)\n    +    command-list.txt: add gitformat-loose(5) and gitpacking(7)\n     \n         Three manpages from sections 5 and 7 are not featured in\n         command-list.txt as concept guides or interface manuals.\n2:  b24d96f732 ! 2:  2dc1ee4514 lint-docs: check the guide list in command-list.txt\n    @@ Documentation/lint-manpages.sh\n      \n      extract_variable () {\n     +\tfile=${2:-../Makefile}\n    ++\tdirectory=$(dirname \"$file\")\n      \t(\n     -\t\tcat ../Makefile\n    -+\t\tcat $file\n    ++\t\tcat \"$file\"\n      \t\tcat <<EOF\n      print_variable:\n      \t@\\$(foreach b,\\$($1),echo XXX \\$(b:\\$X=) YYY;)\n      EOF\n      \t) |\n     -\tmake -C .. -f - print_variable 2>/dev/null |\n    -+\tmake -C $(dirname $file) -f - print_variable 2>/dev/null |\n    ++\tmake -C \"$directory\" -f - print_variable 2>/dev/null |\n      \tsed -n -e 's/.*XXX \\(.*\\) YYY.*/\\1/p'\n      }\n      \n\nbase-commit: b8242b093d9e941a34460d715e3ce616a34ac3fe\n-- \nta/command-list-guides-sync-lint\n\n"},{"id":"552486","messageId":"20260910194351.20809-2-taahol@utu.fi","threadId":"66298","inReplyTo":"20260910194351.20809-1-taahol@utu.fi","subject":"[PATCH v2 1/2] command-list.txt: add gitformat-loose(5) and gitpacking(7)","fromName":"Tuomas Ahola","fromEmail":"taahol@utu.fi","sentAt":"2026-09-10T19:43:50Z","receivedAt":"2026-09-10T19:44:09Z","isPatch":true,"body":"Three manpages from sections 5 and 7 are not featured in\ncommand-list.txt as concept guides or interface manuals.\n\nAs easy fixes, add gitformat-loose(5) to 'developerinterfaces'\nand make gitpacking(7) a 'guide'.\n\nThat leaves only gitweb.conf(5) which could be added to\n'userinterfaces'.  However, the manual would then appear\nas \"web.conf\" in `git help -a` which is just confusing.\nSo, perhaps we are better off by leaving it out.\n\nSigned-off-by: Tuomas Ahola <taahol@utu.fi>\n---\n command-list.txt | 2 ++\n 1 file changed, 2 insertions(+)\n\ndiff --git a/command-list.txt b/command-list.txt\nindex 21b802c420..6667930e8f 100644\n--- a/command-list.txt\n+++ b/command-list.txt\n@@ -224,6 +224,7 @@ gitformat-bundle                        developerinterfaces\n gitformat-chunk                         developerinterfaces\n gitformat-commit-graph                  developerinterfaces\n gitformat-index                         developerinterfaces\n+gitformat-loose                         developerinterfaces\n gitformat-pack                          developerinterfaces\n gitformat-signature                     developerinterfaces\n gitglossary                             guide\n@@ -233,6 +234,7 @@ gitk                                    mainporcelain\n gitmailmap                              userinterfaces\n gitmodules                              userinterfaces\n gitnamespaces                           guide\n+gitpacking                              guide\n gitprotocol-capabilities                developerinterfaces\n gitprotocol-common                      developerinterfaces\n gitprotocol-http                        developerinterfaces\n-- \nta/command-list-guides-sync-lint\n\n"},{"id":"552487","messageId":"20260910194351.20809-3-taahol@utu.fi","threadId":"66298","inReplyTo":"20260910194351.20809-1-taahol@utu.fi","subject":"[PATCH v2 2/2] lint-docs: check the guide list in command-list.txt","fromName":"Tuomas Ahola","fromEmail":"taahol@utu.fi","sentAt":"2026-09-10T19:43:51Z","receivedAt":"2026-09-10T19:44:15Z","isPatch":true,"body":"Since 2135e1ad70 (command-list.txt: add missing 'gitcredentials' and\n'gitremote-helpers', 2020-08-05) there has been a comment in\nDocumentation/Makefile reminding developers to add new guides also to\ncommand-list.txt.  However, there is no linter script to enforce that.\n\nAdapt Documentation/lint-manpages.sh to fill that role.  Extract\nMAN5_TXT and MAN7_TXT from the Makefile and check command-list.txt\nagainst them.  Exempt gitweb.conf(5) from the new linter routine.\n\nSigned-off-by: Tuomas Ahola <taahol@utu.fi>\n---\n\nNotes:\n    c655855559 (doc: git: list gitdatamodel(7) as a concept guide, 2026-09-05)\n    should be merged in to make the new test pass.\n\n Documentation/Makefile         |  2 ++\n Documentation/lint-manpages.sh | 10 +++++++---\n 2 files changed, 9 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex f8dea4b395..8e28ac784b 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -67,6 +67,8 @@ MAN7_TXT += gittutorial-2.adoc\n MAN7_TXT += gittutorial.adoc\n MAN7_TXT += gitworkflows.adoc\n \n+MAN_GUIDES = $(patsubst %.adoc,%,$(MAN5_TXT) $(MAN7_TXT))\n+\n HOWTO_TXT += $(wildcard howto/*.adoc)\n \n DOC_DEP_TXT += $(wildcard *.adoc)\ndiff --git a/Documentation/lint-manpages.sh b/Documentation/lint-manpages.sh\nindex a0ea572382..d4a1977ba6 100755\n--- a/Documentation/lint-manpages.sh\n+++ b/Documentation/lint-manpages.sh\n@@ -1,21 +1,23 @@\n #!/bin/sh\n \n extract_variable () {\n+\tfile=${2:-../Makefile}\n+\tdirectory=$(dirname \"$file\")\n \t(\n-\t\tcat ../Makefile\n+\t\tcat \"$file\"\n \t\tcat <<EOF\n print_variable:\n \t@\\$(foreach b,\\$($1),echo XXX \\$(b:\\$X=) YYY;)\n EOF\n \t) |\n-\tmake -C .. -f - print_variable 2>/dev/null |\n+\tmake -C \"$directory\" -f - print_variable 2>/dev/null |\n \tsed -n -e 's/.*XXX \\(.*\\) YYY.*/\\1/p'\n }\n \n check_missing_docs () (\n \tret=0\n \n-\tfor v in $ALL_COMMANDS\n+\tfor v in $ALL_COMMANDS $MAN_GUIDES\n \tdo\n \t\tcase \"$v\" in\n \t\tgit-merge-octopus) continue;;\n@@ -29,6 +31,7 @@ check_missing_docs () (\n \t\tgit-stage) continue;;\n \t\tgit-legacy-*) continue;;\n \t\tgit-?*--?* ) continue ;;\n+\t\tgitweb.conf) continue ;;\n \t\tesac\n \n \t\tif ! test -f \"$v.adoc\"\n@@ -87,6 +90,7 @@ check_extraneous_docs () {\n BUILT_INS=\"$(extract_variable BUILT_INS)\"\n ALL_COMMANDS=\"$(extract_variable ALL_COMMANDS)\"\n EXCLUDED_PROGRAMS=\"$(extract_variable EXCLUDED_PROGRAMS)\"\n+MAN_GUIDES=\"$(extract_variable MAN_GUIDES ./Makefile)\"\n \n findings=$(\n \tif ! check_missing_docs\n-- \nta/command-list-guides-sync-lint\n\n"}]}