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

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

[Tuomas Ahola]

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

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

[Tuomas Ahola]

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(+)

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

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

[Junio C Hamano]

Tuomas Ahola <taahol@utu.fi> writes:

> 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.

>
> 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

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

[Tuomas Ahola]

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(-)

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

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

[Junio C Hamano]

Tuomas Ahola <taahol@utu.fi> writes:

>  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.

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

[Tuomas Ahola]

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

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

[Tuomas Ahola]

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(+)

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

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

[Tuomas Ahola]

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(-)

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

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

[Tuomas Ahola]

A new linter test has been added to Documentation/lint-manpages.sh
to ensure that all non-command manual pages (concept guides and
interface manuals) listed in Documentation/Makefile are present in
command-list.txt.

Changes in v3:

* [2/2]:
   - Exempt obsoleted gittutorial-2(7).
   - Even more defensive quotation.

Changes in v2:

* [1/2]: Use command-list.txt as the area identifier.
* [2/2]: Protect variables againtst whitespace breakage per review comment.

synthetic-base: master + je/doc-remove-gittutorial-2

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 | 11 ++++++++---
 command-list.txt               |  2 ++
 3 files changed, 12 insertions(+), 3 deletions(-)

Intervall-diff mot v2:
1:  cb6ce6cad1 = 1:  9a1ba61ac0 command-list.txt: add gitformat-loose(5) and gitpacking(7)
2:  2dc1ee4514 ! 2:  5d36d75859 lint-docs: check the guide list in command-list.txt
    @@ Commit message
     
         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.
    +    against them.  Exempt gitweb.conf(5) and gittutorial-2(7) from the
    +    new linter routine.
     
         Signed-off-by: Tuomas Ahola <taahol@utu.fi>
     
    @@ Documentation/lint-manpages.sh
      #!/bin/sh
      
      extract_variable () {
    -+	file=${2:-../Makefile}
    -+	directory=$(dirname "$file")
    ++	file="${2:-../Makefile}"
    ++	directory="$(dirname "$file")"
      	(
     -		cat ../Makefile
     +		cat "$file"
    @@ Documentation/lint-manpages.sh: check_missing_docs () (
      		git-stage) continue;;
      		git-legacy-*) continue;;
      		git-?*--?* ) continue ;;
    ++		gittutorial-2) continue ;;
     +		gitweb.conf) continue ;;
      		esac
      

base-commit: b9e5cff1803ab24582201ef059516eb16014b9d9
prerequisite-patch-id: 7f3cc00ab656bf1192d93c2e6a434c0d0fda2b6b
prerequisite-patch-id: eb8fbd9fc3f96e3cbffddbeaf47b99f397e5330b
-- 
ta/command-list-guides-sync-lint

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

[Tuomas Ahola]

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(+)

diff --git a/command-list.txt b/command-list.txt
index 5c649c882e..d96f56a379 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

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

[Junio C Hamano]

Tuomas Ahola <taahol@utu.fi> writes:

> 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(+)

I agree we can decide what to do about gitweb.  Is the list
otherwise complete to cover the available documents in .adoc format?

Thanks.

>
> diff --git a/command-list.txt b/command-list.txt
> index 5c649c882e..d96f56a379 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

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

[Tuomas Ahola]

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) and gittutorial-2(7) from the
new linter routine.

Signed-off-by: Tuomas Ahola <taahol@utu.fi>
---
 Documentation/Makefile         |  2 ++
 Documentation/lint-manpages.sh | 11 ++++++++---
 2 files changed, 10 insertions(+), 3 deletions(-)

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..31ee3cbe72 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,8 @@ check_missing_docs () (
 		git-stage) continue;;
 		git-legacy-*) continue;;
 		git-?*--?* ) continue ;;
+		gittutorial-2) continue ;;
+		gitweb.conf) continue ;;
 		esac
 
 		if ! test -f "$v.adoc"
@@ -87,6 +91,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

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

[Julia Evans]

On Thu, Oct 29, 2026, at 2:48 PM, Tuomas Ahola wrote:
> 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) and gittutorial-2(7) from the
> new linter routine.
>
> Signed-off-by: Tuomas Ahola <taahol@utu.fi>
> ---
>  Documentation/Makefile         |  2 ++
>  Documentation/lint-manpages.sh | 11 ++++++++---
>  2 files changed, 10 insertions(+), 3 deletions(-)
>
> 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..31ee3cbe72 100755
> --- a/Documentation/lint-manpages.sh
> +++ b/Documentation/lint-manpages.sh
> @@ -1,21 +1,23 @@
>  #!/bin/sh
> 
>  extract_variable () {
> +	file="${2:-../Makefile}"

I think what's happening here is that previously we were
getting the variables from ./Makefile (in the basedir), but now we need
some variables from ./Makefile and some from Documentation/Makefile.

Would it make sense to get all the variables from Documentation/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,8 @@ check_missing_docs () (
>  		git-stage) continue;;
>  		git-legacy-*) continue;;
>  		git-?*--?* ) continue ;;
> +		gittutorial-2) continue ;;
> +		gitweb.conf) continue ;;
>  		esac
> 
>  		if ! test -f "$v.adoc"
> @@ -87,6 +91,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

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

[Tuomas Ahola]

"Julia Evans" <julia@jvns.ca> wrote:

> On Thu, Oct 29, 2026, at 2:48 PM, Tuomas Ahola wrote:
> > diff --git a/Documentation/lint-manpages.sh b/Documentation/lint-manpages.sh
> > index a0ea572382..31ee3cbe72 100755
> > --- a/Documentation/lint-manpages.sh
> > +++ b/Documentation/lint-manpages.sh
> > @@ -1,21 +1,23 @@
> >  #!/bin/sh
> > 
> >  extract_variable () {
> > +	file="${2:-../Makefile}"
> 
> I think what's happening here is that previously we were
> getting the variables from ./Makefile (in the basedir), but now we need
> some variables from ./Makefile and some from Documentation/Makefile.
> 
> Would it make sense to get all the variables from Documentation/Makefile?
> 

If that's possible, then sure, why not.  But I think we are mostly extracting
from the top-level Makefile such information that simply isn't available in the
docs Makefile (and vice versa)?

> > +	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,8 @@ check_missing_docs () (
> >  		git-stage) continue;;
> >  		git-legacy-*) continue;;
> >  		git-?*--?* ) continue ;;
> > +		gittutorial-2) continue ;;
> > +		gitweb.conf) continue ;;
> >  		esac
> > 
> >  		if ! test -f "$v.adoc"
> > @@ -87,6 +91,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

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

[Junio C Hamano]

Tuomas Ahola <taahol@utu.fi> writes:

>  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 |

I like this sayIt pattern to prepend a snippet in front of the
Makefile.  As we allow extracting from different Makefile with this
change, it would make more sense to (1) make the path to the Makefile
mandatory, (2) move the path to the Makefile first, and (3) use not
just the $1 but all the remainder of the command line as listing the
symbols we are inquiring.

which would mean ...

> @@ -87,6 +91,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)"

These would become

    BUILT_INS="$(extract_variable ../Makefile BUILT_INS)"
    ALL_COMMANDS="$(extract_variable ../Makefile ALL_COMMANDS)"
    EXCLUDED_PROGRAMS="$(extract_variable ../Makefile EXCLUDED_PROGRAMS)"
    MAN_GUIDES="$(extract_variable Makefile MAN_GUIDES)"

Other than that, looking good.

Thanks.