{"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-11-11T22:00:01Z","messageCount":17,"participants":["Tuomas Ahola","Junio C Hamano","Julia Evans"],"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,"sender":{"key":"taahol@utu.fi","avatar":"https://avatars.githubusercontent.com/u/114303477?v=4"},"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,"sender":{"key":"taahol@utu.fi","avatar":"https://avatars.githubusercontent.com/u/114303477?v=4"},"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,"sender":{"key":"taahol@utu.fi","avatar":"https://avatars.githubusercontent.com/u/114303477?v=4"},"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,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"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,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"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,"sender":{"key":"taahol@utu.fi","avatar":"https://avatars.githubusercontent.com/u/114303477?v=4"},"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,"sender":{"key":"taahol@utu.fi","avatar":"https://avatars.githubusercontent.com/u/114303477?v=4"},"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,"sender":{"key":"taahol@utu.fi","avatar":"https://avatars.githubusercontent.com/u/114303477?v=4"},"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"},{"id":"556815","messageId":"20261029184834.2273-1-taahol@utu.fi","threadId":"66298","inReplyTo":"20260909052501.8448-1-taahol@utu.fi","subject":"[PATCH v3 0/2] guides: keep Documentation/Makefile and command-list.txt in sync","fromName":"Tuomas Ahola","fromEmail":"taahol@utu.fi","sentAt":"2026-10-29T18:48:32Z","receivedAt":"2026-10-29T18:48:32Z","isPatch":true,"sender":{"key":"taahol@utu.fi","avatar":"https://avatars.githubusercontent.com/u/114303477?v=4"},"body":"A new linter test has been added to Documentation/lint-manpages.sh\nto ensure that all non-command manual pages (concept guides and\ninterface manuals) listed in Documentation/Makefile are present in\ncommand-list.txt.\n\nChanges in v3:\n\n* [2/2]:\n   - Exempt obsoleted gittutorial-2(7).\n   - Even more defensive quotation.\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\nsynthetic-base: master + je/doc-remove-gittutorial-2\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 | 11 ++++++++---\n command-list.txt               |  2 ++\n 3 files changed, 12 insertions(+), 3 deletions(-)\n\nIntervall-diff mot v2:\n1:  cb6ce6cad1 = 1:  9a1ba61ac0 command-list.txt: add gitformat-loose(5) and gitpacking(7)\n2:  2dc1ee4514 ! 2:  5d36d75859 lint-docs: check the guide list in command-list.txt\n    @@ Commit message\n     \n         Adapt Documentation/lint-manpages.sh to fill that role.  Extract\n         MAN5_TXT and MAN7_TXT from the Makefile and check command-list.txt\n    -    against them.  Exempt gitweb.conf(5) from the new linter routine.\n    +    against them.  Exempt gitweb.conf(5) and gittutorial-2(7) from the\n    +    new linter routine.\n     \n         Signed-off-by: Tuomas Ahola <taahol@utu.fi>\n     \n    @@ Documentation/lint-manpages.sh\n      #!/bin/sh\n      \n      extract_variable () {\n    -+\tfile=${2:-../Makefile}\n    -+\tdirectory=$(dirname \"$file\")\n    ++\tfile=\"${2:-../Makefile}\"\n    ++\tdirectory=\"$(dirname \"$file\")\"\n      \t(\n     -\t\tcat ../Makefile\n     +\t\tcat \"$file\"\n    @@ Documentation/lint-manpages.sh: check_missing_docs () (\n      \t\tgit-stage) continue;;\n      \t\tgit-legacy-*) continue;;\n      \t\tgit-?*--?* ) continue ;;\n    ++\t\tgittutorial-2) continue ;;\n     +\t\tgitweb.conf) continue ;;\n      \t\tesac\n      \n\nbase-commit: b9e5cff1803ab24582201ef059516eb16014b9d9\nprerequisite-patch-id: 7f3cc00ab656bf1192d93c2e6a434c0d0fda2b6b\nprerequisite-patch-id: eb8fbd9fc3f96e3cbffddbeaf47b99f397e5330b\n-- \nta/command-list-guides-sync-lint\n\n\n"},{"id":"556836","messageId":"20261029184834.2273-2-taahol@utu.fi","threadId":"66298","inReplyTo":"20261029184834.2273-1-taahol@utu.fi","subject":"[PATCH v3 1/2] command-list.txt: add gitformat-loose(5) and gitpacking(7)","fromName":"Tuomas Ahola","fromEmail":"taahol@utu.fi","sentAt":"2026-10-29T18:48:33Z","receivedAt":"2026-10-29T18:48:33Z","isPatch":true,"sender":{"key":"taahol@utu.fi","avatar":"https://avatars.githubusercontent.com/u/114303477?v=4"},"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 5c649c882e..d96f56a379 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\n"},{"id":"556816","messageId":"20261029184834.2273-3-taahol@utu.fi","threadId":"66298","inReplyTo":"20261029184834.2273-1-taahol@utu.fi","subject":"[PATCH v3 2/2] lint-docs: check the guide list in command-list.txt","fromName":"Tuomas Ahola","fromEmail":"taahol@utu.fi","sentAt":"2026-10-29T18:48:34Z","receivedAt":"2026-10-29T18:48:34Z","isPatch":true,"sender":{"key":"taahol@utu.fi","avatar":"https://avatars.githubusercontent.com/u/114303477?v=4"},"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) and gittutorial-2(7) from the\nnew linter routine.\n\nSigned-off-by: Tuomas Ahola <taahol@utu.fi>\n---\n Documentation/Makefile         |  2 ++\n Documentation/lint-manpages.sh | 11 ++++++++---\n 2 files changed, 10 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..31ee3cbe72 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,8 @@ check_missing_docs () (\n \t\tgit-stage) continue;;\n \t\tgit-legacy-*) continue;;\n \t\tgit-?*--?* ) continue ;;\n+\t\tgittutorial-2) continue ;;\n+\t\tgitweb.conf) continue ;;\n \t\tesac\n \n \t\tif ! test -f \"$v.adoc\"\n@@ -87,6 +91,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\n"},{"id":"557222","messageId":"48aa1e9a-3049-4316-9054-644a8754b0dd@app.fastmail.com","threadId":"66298","inReplyTo":"20261029184834.2273-3-taahol@utu.fi","subject":"Re: [PATCH v3 2/2] lint-docs: check the guide list in command-list.txt","fromName":"Julia Evans","fromEmail":"julia@jvns.ca","sentAt":"2026-11-02T18:39:06Z","receivedAt":"2026-11-02T18:39:06Z","isPatch":true,"sender":{"key":"julia@jvns.ca","avatar":"https://avatars.githubusercontent.com/u/817739?v=4"},"body":"On Thu, Oct 29, 2026, at 2:48 PM, Tuomas Ahola wrote:\n> Since 2135e1ad70 (command-list.txt: add missing 'gitcredentials' and\n> 'gitremote-helpers', 2020-08-05) there has been a comment in\n> Documentation/Makefile reminding developers to add new guides also to\n> command-list.txt.  However, there is no linter script to enforce that.\n>\n> Adapt Documentation/lint-manpages.sh to fill that role.  Extract\n> MAN5_TXT and MAN7_TXT from the Makefile and check command-list.txt\n> against them.  Exempt gitweb.conf(5) and gittutorial-2(7) from the\n> new linter routine.\n>\n> Signed-off-by: Tuomas Ahola <taahol@utu.fi>\n> ---\n>  Documentation/Makefile         |  2 ++\n>  Documentation/lint-manpages.sh | 11 ++++++++---\n>  2 files changed, 10 insertions(+), 3 deletions(-)\n>\n> diff --git a/Documentation/Makefile b/Documentation/Makefile\n> index 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)\n> diff --git a/Documentation/lint-manpages.sh b/Documentation/lint-manpages.sh\n> index a0ea572382..31ee3cbe72 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\nI think what's happening here is that previously we were\ngetting the variables from ./Makefile (in the basedir), but now we need\nsome variables from ./Makefile and some from Documentation/Makefile.\n\nWould it make sense to get all the variables from Documentation/Makefile?\n\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,8 @@ check_missing_docs () (\n>  \t\tgit-stage) continue;;\n>  \t\tgit-legacy-*) continue;;\n>  \t\tgit-?*--?* ) continue ;;\n> +\t\tgittutorial-2) continue ;;\n> +\t\tgitweb.conf) continue ;;\n>  \t\tesac\n> \n>  \t\tif ! test -f \"$v.adoc\"\n> @@ -87,6 +91,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> -- \n> ta/command-list-guides-sync-lint\n\n"},{"id":"557336","messageId":"20261103170944.kmZMv%taahol@utu.fi","threadId":"66298","inReplyTo":"48aa1e9a-3049-4316-9054-644a8754b0dd@app.fastmail.com","subject":"Re: [PATCH v3 2/2] lint-docs: check the guide list in command-list.txt","fromName":"Tuomas Ahola","fromEmail":"taahol@utu.fi","sentAt":"2026-11-03T17:09:44Z","receivedAt":"2026-11-03T17:09:44Z","isPatch":true,"sender":{"key":"taahol@utu.fi","avatar":"https://avatars.githubusercontent.com/u/114303477?v=4"},"body":"\"Julia Evans\" <julia@jvns.ca> wrote:\n\n> On Thu, Oct 29, 2026, at 2:48 PM, Tuomas Ahola wrote:\n> > diff --git a/Documentation/lint-manpages.sh b/Documentation/lint-manpages.sh\n> > index a0ea572382..31ee3cbe72 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> \n> I think what's happening here is that previously we were\n> getting the variables from ./Makefile (in the basedir), but now we need\n> some variables from ./Makefile and some from Documentation/Makefile.\n> \n> Would it make sense to get all the variables from Documentation/Makefile?\n> \n\nIf that's possible, then sure, why not.  But I think we are mostly extracting\nfrom the top-level Makefile such information that simply isn't available in the\ndocs Makefile (and vice versa)?\n\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,8 @@ check_missing_docs () (\n> >  \t\tgit-stage) continue;;\n> >  \t\tgit-legacy-*) continue;;\n> >  \t\tgit-?*--?* ) continue ;;\n> > +\t\tgittutorial-2) continue ;;\n> > +\t\tgitweb.conf) continue ;;\n> >  \t\tesac\n> > \n> >  \t\tif ! test -f \"$v.adoc\"\n> > @@ -87,6 +91,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> > -- \n> > ta/command-list-guides-sync-lint\n\n"},{"id":"557606","messageId":"xmqqh5hvt6ot.fsf@gitster.g","threadId":"66298","inReplyTo":"20261029184834.2273-2-taahol@utu.fi","subject":"Re: [PATCH v3 1/2] command-list.txt: add gitformat-loose(5) and gitpacking(7)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-11-05T19:32:50Z","receivedAt":"2026-11-05T19:32:50Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"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\nI agree we can decide what to do about gitweb.  Is the list\notherwise complete to cover the available documents in .adoc format?\n\nThanks.\n\n>\n> diff --git a/command-list.txt b/command-list.txt\n> index 5c649c882e..d96f56a379 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\n"},{"id":"557607","messageId":"xmqqcxsjt6b3.fsf@gitster.g","threadId":"66298","inReplyTo":"20261029184834.2273-3-taahol@utu.fi","subject":"Re: [PATCH v3 2/2] lint-docs: check the guide list in command-list.txt","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-11-05T19:41:04Z","receivedAt":"2026-11-05T19:41:04Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Tuomas Ahola <taahol@utu.fi> writes:\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\nI like this sayIt pattern to prepend a snippet in front of the\nMakefile.  As we allow extracting from different Makefile with this\nchange, it would make more sense to (1) make the path to the Makefile\nmandatory, (2) move the path to the Makefile first, and (3) use not\njust the $1 but all the remainder of the command line as listing the\nsymbols we are inquiring.\n\nwhich would mean ...\n\n> @@ -87,6 +91,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\nThese would become\n\n    BUILT_INS=\"$(extract_variable ../Makefile BUILT_INS)\"\n    ALL_COMMANDS=\"$(extract_variable ../Makefile ALL_COMMANDS)\"\n    EXCLUDED_PROGRAMS=\"$(extract_variable ../Makefile EXCLUDED_PROGRAMS)\"\n    MAN_GUIDES=\"$(extract_variable Makefile MAN_GUIDES)\"\n\nOther than that, looking good.\n\nThanks.\n\n\n\n"},{"id":"558252","messageId":"20261111215745.5LxQ4%taahol@utu.fi","threadId":"66298","inReplyTo":"xmqqh5hvt6ot.fsf@gitster.g","subject":"Re: [PATCH v3 1/2] command-list.txt: add gitformat-loose(5) and gitpacking(7)","fromName":"Tuomas Ahola","fromEmail":"taahol@utu.fi","sentAt":"2026-11-11T21:57:45Z","receivedAt":"2026-11-11T21:57:45Z","isPatch":true,"sender":{"key":"taahol@utu.fi","avatar":"https://avatars.githubusercontent.com/u/114303477?v=4"},"body":"Junio C Hamano <gitster@pobox.com> wrote:\n\n> 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> \n> I agree we can decide what to do about gitweb.  Is the list\n> otherwise complete to cover the available documents in .adoc format?\n> \n\nAFAIK, yes.\n\n"},{"id":"558253","messageId":"20261111220001.VKwmr%taahol@utu.fi","threadId":"66298","inReplyTo":"xmqqcxsjt6b3.fsf@gitster.g","subject":"Re: [PATCH v3 2/2] lint-docs: check the guide list in command-list.txt","fromName":"Tuomas Ahola","fromEmail":"taahol@utu.fi","sentAt":"2026-11-11T22:00:01Z","receivedAt":"2026-11-11T22:00:01Z","isPatch":true,"sender":{"key":"taahol@utu.fi","avatar":"https://avatars.githubusercontent.com/u/114303477?v=4"},"body":"Junio C Hamano <gitster@pobox.com> wrote:\n\n> Tuomas Ahola <taahol@utu.fi> writes:\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> \n> I like this sayIt pattern to prepend a snippet in front of the\n> Makefile.  As we allow extracting from different Makefile with this\n> change, it would make more sense to (1) make the path to the Makefile\n> mandatory, (2) move the path to the Makefile first, and (3) use not\n> just the $1 but all the remainder of the command line as listing the\n> symbols we are inquiring.\n> \n\nHmm, sounds sensible.\n\n> which would mean ...\n> \n> > @@ -87,6 +91,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> These would become\n> \n>     BUILT_INS=\"$(extract_variable ../Makefile BUILT_INS)\"\n>     ALL_COMMANDS=\"$(extract_variable ../Makefile ALL_COMMANDS)\"\n>     EXCLUDED_PROGRAMS=\"$(extract_variable ../Makefile EXCLUDED_PROGRAMS)\"\n>     MAN_GUIDES=\"$(extract_variable Makefile MAN_GUIDES)\"\n> \n\nOkay, I'll do that.\n\n> Other than that, looking good.\n> \n> Thanks.\n> \n> \n\n"}]}