Volume XXII, number 279Tuesday, October 6, 2026Latest message 45 minutes ago

The Git List

News and archive of git@vger.kernel.org, since April 2005

patch, 2 partsguides: keep Documentation/Makefile and command-list.txt in sync

8 messages between Sep 9, 2026 and Sep 10, 2026, from Tuomas Ahola, Junio C Hamano.

Plain Markdown or JSON for tools and agents. Diffs are folded; open one to read it.

Tuomas AholaSep 9, 2026, 05:24 UTC on lore

Documentation/lint-manpages.sh was expanded with a new test ensuring that command-list.txt also includes all non-command manual pages (concept guides and interface manuals).

Based on kh/doc-datamodel.
Tuomas Ahola (2):
  command-list: add gitformat-loose(5) and gitpacking(7)
  lint-docs: check the guide list in command-list.txt
 Documentation/Makefile         | 2 ++
 Documentation/lint-manpages.sh | 9 ++++++---
 command-list.txt               | 2 ++
 3 files changed, 10 insertions(+), 3 deletions(-)

base-commit: e9019fcafe0040228b8631c30f97ae1adb61bcdc prerequisite-patch-id: 13af80fdddfc7d4f65437343cee0ca3787cbdea4

-- 
ta/command-list-guides-sync-lint
Tuomas AholaSep 9, 2026, 05:25 UTC in reply to Tuomas Ahola on lore

[PATCH 2/2] lint-docs: check the guide list in command-list.txt

Since 2135e1ad70 (command-list.txt: add missing 'gitcredentials' and 'gitremote-helpers', 2020-08-05) there has been a comment in Documentation/Makefile reminding developers to add new guides also to command-list.txt. However, there is no linter script to enforce that.

Adapt Documentation/lint-manpages.sh to fill that role. Extract MAN5_TXT and MAN7_TXT from the Makefile and check command-list.txt against them. Exempt gitweb.conf(5) from the new linter routine.

Signed-off-by: Tuomas Ahola <taahol@utu.fi>
---
Notes:
    c655855559 (doc: git: list gitdatamodel(7) as a concept guide, 2026-09-05)
    should be merged in to make the new test pass.
 Documentation/Makefile         | 2 ++
 Documentation/lint-manpages.sh | 9 ++++++---
 2 files changed, 8 insertions(+), 3 deletions(-)
Show changes to 2 files +8 −3

Documentation/Makefile, Documentation/lint-manpages.sh

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 2699f0b24a..203f6a0c31 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -67,6 +67,8 @@ MAN7_TXT += gittutorial-2.adoc
 MAN7_TXT += gittutorial.adoc
 MAN7_TXT += gitworkflows.adoc
 
+MAN_GUIDES = $(patsubst %.adoc,%,$(MAN5_TXT) $(MAN7_TXT))
+
 HOWTO_TXT += $(wildcard howto/*.adoc)
 
 DOC_DEP_TXT += $(wildcard *.adoc)
diff --git a/Documentation/lint-manpages.sh b/Documentation/lint-manpages.sh
index a0ea572382..290ebe0947 100755
--- a/Documentation/lint-manpages.sh
+++ b/Documentation/lint-manpages.sh
@@ -1,21 +1,22 @@
 #!/bin/sh
 
 extract_variable () {
+	file=${2:-../Makefile}
 	(
-		cat ../Makefile
+		cat $file
 		cat <<EOF
 print_variable:
 	@\$(foreach b,\$($1),echo XXX \$(b:\$X=) YYY;)
 EOF
 	) |
-	make -C .. -f - print_variable 2>/dev/null |
+	make -C $(dirname $file) -f - print_variable 2>/dev/null |
 	sed -n -e 's/.*XXX \(.*\) YYY.*/\1/p'
 }
 
 check_missing_docs () (
 	ret=0
 
-	for v in $ALL_COMMANDS
+	for v in $ALL_COMMANDS $MAN_GUIDES
 	do
 		case "$v" in
 		git-merge-octopus) continue;;
@@ -29,6 +30,7 @@ check_missing_docs () (
 		git-stage) continue;;
 		git-legacy-*) continue;;
 		git-?*--?* ) continue ;;
+		gitweb.conf) continue ;;
 		esac
 
 		if ! test -f "$v.adoc"
@@ -87,6 +89,7 @@ check_extraneous_docs () {
 BUILT_INS="$(extract_variable BUILT_INS)"
 ALL_COMMANDS="$(extract_variable ALL_COMMANDS)"
 EXCLUDED_PROGRAMS="$(extract_variable EXCLUDED_PROGRAMS)"
+MAN_GUIDES="$(extract_variable MAN_GUIDES ./Makefile)"
 
 findings=$(
 	if ! check_missing_docs

-- 
ta/command-list-guides-sync-lint
Tuomas AholaSep 9, 2026, 05:25 UTC in reply to Tuomas Ahola on lore

[PATCH 1/2] command-list: add gitformat-loose(5) and gitpacking(7)

Three manpages from sections 5 and 7 are not featured in command-list.txt as concept guides or interface manuals.

As easy fixes, add gitformat-loose(5) to 'developerinterfaces' and make gitpacking(7) a 'guide'.

That leaves only gitweb.conf(5) which could be added to 'userinterfaces'. However, the manual would then appear as "web.conf" in `git help -a` which is just confusing. So, perhaps we are better off by leaving it out.

Signed-off-by: Tuomas Ahola <taahol@utu.fi>
---
 command-list.txt | 2 ++
 1 file changed, 2 insertions(+)
Show changes to command-list.txt +2 −0
diff --git a/command-list.txt b/command-list.txt
index 63ae2a67c9..955eec6e7e 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -225,6 +225,7 @@ gitformat-bundle                        developerinterfaces
 gitformat-chunk                         developerinterfaces
 gitformat-commit-graph                  developerinterfaces
 gitformat-index                         developerinterfaces
+gitformat-loose                         developerinterfaces
 gitformat-pack                          developerinterfaces
 gitformat-signature                     developerinterfaces
 gitglossary                             guide
@@ -234,6 +235,7 @@ gitk                                    mainporcelain
 gitmailmap                              userinterfaces
 gitmodules                              userinterfaces
 gitnamespaces                           guide
+gitpacking                              guide
 gitprotocol-capabilities                developerinterfaces
 gitprotocol-common                      developerinterfaces
 gitprotocol-http                        developerinterfaces

-- 
ta/command-list-guides-sync-lint
Junio C HamanoSep 9, 2026, 18:15 UTC in reply to Tuomas Ahola on lore

Re: [PATCH 2/2] lint-docs: check the guide list in command-list.txt

Tuomas Ahola <taahol@utu.fi> writes:
Show 5 quoted lines
>  extract_variable () {
> +	file=${2:-../Makefile}
>  	(
> -		cat ../Makefile
> +		cat $file

Now you are allowing arbitrary path to be fed to this function, you should prepare to accept arbitrary path, without assuming that $file has no $IFS whitespaces. I.e.,

		cat "$file"
>  	) |
> -	make -C .. -f - print_variable 2>/dev/null |
> +	make -C $(dirname $file) -f - print_variable 2>/dev/null |

Ditto. $file itself may have $IFS whitespaces, and the result of running dirname on it may too.

Junio C HamanoSep 9, 2026, 18:15 UTC in reply to Tuomas Ahola on lore

Re: [PATCH 1/2] command-list: add gitformat-loose(5) and gitpacking(7)

Tuomas Ahola <taahol@utu.fi> writes:
Show 15 quoted lines
> Three manpages from sections 5 and 7 are not featured in
> command-list.txt as concept guides or interface manuals.
>
> As easy fixes, add gitformat-loose(5) to 'developerinterfaces'
> and make gitpacking(7) a 'guide'.
>
> That leaves only gitweb.conf(5) which could be added to
> 'userinterfaces'.  However, the manual would then appear
> as "web.conf" in `git help -a` which is just confusing.
> So, perhaps we are better off by leaving it out.
>
> Signed-off-by: Tuomas Ahola <taahol@utu.fi>
> ---
>  command-list.txt | 2 ++
>  1 file changed, 2 insertions(+)
Good eyes.  Thanks.
Show 21 quoted lines
>
> diff --git a/command-list.txt b/command-list.txt
> index 63ae2a67c9..955eec6e7e 100644
> --- a/command-list.txt
> +++ b/command-list.txt
> @@ -225,6 +225,7 @@ gitformat-bundle                        developerinterfaces
>  gitformat-chunk                         developerinterfaces
>  gitformat-commit-graph                  developerinterfaces
>  gitformat-index                         developerinterfaces
> +gitformat-loose                         developerinterfaces
>  gitformat-pack                          developerinterfaces
>  gitformat-signature                     developerinterfaces
>  gitglossary                             guide
> @@ -234,6 +235,7 @@ gitk                                    mainporcelain
>  gitmailmap                              userinterfaces
>  gitmodules                              userinterfaces
>  gitnamespaces                           guide
> +gitpacking                              guide
>  gitprotocol-capabilities                developerinterfaces
>  gitprotocol-common                      developerinterfaces
>  gitprotocol-http                        developerinterfaces
Tuomas AholaSep 10, 2026, 19:43 UTC in reply to Tuomas Ahola on lore

[PATCH v2 0/2] guides: keep Documentation/Makefile and command-list.txt in sync

Documentation/lint-manpages.sh was expanded with a new test ensuring that command-list.txt also includes all non-command manual pages (concept guides and interface manuals).

Based on kh/doc-datamodel.
Changes in v2:
* [1/2]: Use command-list.txt as the area identifier.
* [2/2]: Protect variables againtst whitespace breakage per review comment.
Tuomas Ahola (2):
  command-list.txt: add gitformat-loose(5) and gitpacking(7)
  lint-docs: check the guide list in command-list.txt
 Documentation/Makefile         |  2 ++
 Documentation/lint-manpages.sh | 10 +++++++---
 command-list.txt               |  2 ++
 3 files changed, 11 insertions(+), 3 deletions(-)
Intervall-diff mot v1:
1:  014da7fdff ! 1:  cb6ce6cad1 command-list: add gitformat-loose(5) and gitpacking(7)
    @@ Metadata
     Author: Tuomas Ahola <taahol@utu.fi>
     
      ## Commit message ##
    -    command-list: add gitformat-loose(5) and gitpacking(7)
    +    command-list.txt: add gitformat-loose(5) and gitpacking(7)
     
         Three manpages from sections 5 and 7 are not featured in
         command-list.txt as concept guides or interface manuals.
2:  b24d96f732 ! 2:  2dc1ee4514 lint-docs: check the guide list in command-list.txt
    @@ Documentation/lint-manpages.sh
      
      extract_variable () {
     +	file=${2:-../Makefile}
    ++	directory=$(dirname "$file")
      	(
     -		cat ../Makefile
    -+		cat $file
    ++		cat "$file"
      		cat <<EOF
      print_variable:
      	@\$(foreach b,\$($1),echo XXX \$(b:\$X=) YYY;)
      EOF
      	) |
     -	make -C .. -f - print_variable 2>/dev/null |
    -+	make -C $(dirname $file) -f - print_variable 2>/dev/null |
    ++	make -C "$directory" -f - print_variable 2>/dev/null |
      	sed -n -e 's/.*XXX \(.*\) YYY.*/\1/p'
      }
      
base-commit: b8242b093d9e941a34460d715e3ce616a34ac3fe
-- 
ta/command-list-guides-sync-lint
Tuomas AholaSep 10, 2026, 19:43 UTC in reply to Tuomas Ahola on lore

[PATCH v2 1/2] command-list.txt: add gitformat-loose(5) and gitpacking(7)

Three manpages from sections 5 and 7 are not featured in command-list.txt as concept guides or interface manuals.

As easy fixes, add gitformat-loose(5) to 'developerinterfaces' and make gitpacking(7) a 'guide'.

That leaves only gitweb.conf(5) which could be added to 'userinterfaces'. However, the manual would then appear as "web.conf" in `git help -a` which is just confusing. So, perhaps we are better off by leaving it out.

Signed-off-by: Tuomas Ahola <taahol@utu.fi>
---
 command-list.txt | 2 ++
 1 file changed, 2 insertions(+)
Show changes to command-list.txt +2 −0
diff --git a/command-list.txt b/command-list.txt
index 21b802c420..6667930e8f 100644
--- a/command-list.txt
+++ b/command-list.txt
@@ -224,6 +224,7 @@ gitformat-bundle                        developerinterfaces
 gitformat-chunk                         developerinterfaces
 gitformat-commit-graph                  developerinterfaces
 gitformat-index                         developerinterfaces
+gitformat-loose                         developerinterfaces
 gitformat-pack                          developerinterfaces
 gitformat-signature                     developerinterfaces
 gitglossary                             guide
@@ -233,6 +234,7 @@ gitk                                    mainporcelain
 gitmailmap                              userinterfaces
 gitmodules                              userinterfaces
 gitnamespaces                           guide
+gitpacking                              guide
 gitprotocol-capabilities                developerinterfaces
 gitprotocol-common                      developerinterfaces
 gitprotocol-http                        developerinterfaces

-- 
ta/command-list-guides-sync-lint
Tuomas AholaSep 10, 2026, 19:43 UTC in reply to Tuomas Ahola on lore

[PATCH v2 2/2] lint-docs: check the guide list in command-list.txt

Since 2135e1ad70 (command-list.txt: add missing 'gitcredentials' and 'gitremote-helpers', 2020-08-05) there has been a comment in Documentation/Makefile reminding developers to add new guides also to command-list.txt. However, there is no linter script to enforce that.

Adapt Documentation/lint-manpages.sh to fill that role. Extract MAN5_TXT and MAN7_TXT from the Makefile and check command-list.txt against them. Exempt gitweb.conf(5) from the new linter routine.

Signed-off-by: Tuomas Ahola <taahol@utu.fi>
---
Notes:
    c655855559 (doc: git: list gitdatamodel(7) as a concept guide, 2026-09-05)
    should be merged in to make the new test pass.
 Documentation/Makefile         |  2 ++
 Documentation/lint-manpages.sh | 10 +++++++---
 2 files changed, 9 insertions(+), 3 deletions(-)
Show changes to 2 files +9 −3

Documentation/Makefile, Documentation/lint-manpages.sh

diff --git a/Documentation/Makefile b/Documentation/Makefile
index f8dea4b395..8e28ac784b 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -67,6 +67,8 @@ MAN7_TXT += gittutorial-2.adoc
 MAN7_TXT += gittutorial.adoc
 MAN7_TXT += gitworkflows.adoc
 
+MAN_GUIDES = $(patsubst %.adoc,%,$(MAN5_TXT) $(MAN7_TXT))
+
 HOWTO_TXT += $(wildcard howto/*.adoc)
 
 DOC_DEP_TXT += $(wildcard *.adoc)
diff --git a/Documentation/lint-manpages.sh b/Documentation/lint-manpages.sh
index a0ea572382..d4a1977ba6 100755
--- a/Documentation/lint-manpages.sh
+++ b/Documentation/lint-manpages.sh
@@ -1,21 +1,23 @@
 #!/bin/sh
 
 extract_variable () {
+	file=${2:-../Makefile}
+	directory=$(dirname "$file")
 	(
-		cat ../Makefile
+		cat "$file"
 		cat <<EOF
 print_variable:
 	@\$(foreach b,\$($1),echo XXX \$(b:\$X=) YYY;)
 EOF
 	) |
-	make -C .. -f - print_variable 2>/dev/null |
+	make -C "$directory" -f - print_variable 2>/dev/null |
 	sed -n -e 's/.*XXX \(.*\) YYY.*/\1/p'
 }
 
 check_missing_docs () (
 	ret=0
 
-	for v in $ALL_COMMANDS
+	for v in $ALL_COMMANDS $MAN_GUIDES
 	do
 		case "$v" in
 		git-merge-octopus) continue;;
@@ -29,6 +31,7 @@ check_missing_docs () (
 		git-stage) continue;;
 		git-legacy-*) continue;;
 		git-?*--?* ) continue ;;
+		gitweb.conf) continue ;;
 		esac
 
 		if ! test -f "$v.adoc"
@@ -87,6 +90,7 @@ check_extraneous_docs () {
 BUILT_INS="$(extract_variable BUILT_INS)"
 ALL_COMMANDS="$(extract_variable ALL_COMMANDS)"
 EXCLUDED_PROGRAMS="$(extract_variable EXCLUDED_PROGRAMS)"
+MAN_GUIDES="$(extract_variable MAN_GUIDES ./Makefile)"
 
 findings=$(
 	if ! check_missing_docs

-- 
ta/command-list-guides-sync-lint

Back to recent threads