threads / patch / 66298

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

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

## tl;dr

17 messages between Sep 9, 2026 and Nov 11, 2026. Diffs are folded; open one to read it.

replies: 16people: 3as markdown or json

Tuomas Ahola· Sep 9, 2026, 05:24 UTC · 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 Ahola· Sep 9, 2026, 05:25 UTC · re: Tuomas Ahola · 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
Junio C Hamano· Sep 9, 2026, 18:15 UTC · re: Tuomas Ahola · 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.

Tuomas Ahola· Sep 9, 2026, 05:25 UTC · re: Tuomas Ahola · 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 Hamano· Sep 9, 2026, 18:15 UTC · re: Tuomas Ahola · 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 Ahola· Sep 10, 2026, 19:43 UTC · re: Tuomas Ahola · 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 Ahola· Sep 10, 2026, 19:43 UTC · re: Tuomas Ahola · 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 Ahola· Sep 10, 2026, 19:43 UTC · re: Tuomas Ahola · 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
Tuomas Ahola· Oct 29, 2026, 18:48 UTC · re: Tuomas Ahola · lore

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

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
Tuomas Ahola· Oct 29, 2026, 18:48 UTC · re: Tuomas Ahola · lore

[PATCH v3 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 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
Junio C Hamano· Nov 5, 2026, 19:32 UTC · re: Tuomas Ahola · lore

Re: [PATCH v3 1/2] command-list.txt: 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(+)

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

Thanks.
Show 21 quoted lines
>
> 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
Tuomas Ahola· Nov 11, 2026, 21:57 UTC · re: Junio C Hamano · lore

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

Junio C Hamano <gitster@pobox.com> wrote:
Show 21 quoted lines
> 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?
> 
AFAIK, yes.
Tuomas Ahola· Oct 29, 2026, 18:48 UTC · re: Tuomas Ahola · lore

[PATCH v3 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) 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(-)
Show changes to 2 files +10 −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..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
Julia Evans· Nov 2, 2026, 18:39 UTC · re: Tuomas Ahola · lore

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

On Thu, Oct 29, 2026, at 2:48 PM, Tuomas Ahola wrote:
Show 38 quoted lines
> 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?
Show 41 quoted lines
> +	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
Tuomas Ahola· Nov 3, 2026, 17:09 UTC · re: Julia Evans · lore

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

"Julia Evans" <julia@jvns.ca> wrote:
Show 17 quoted lines
> 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)?

Show 41 quoted lines
> > +	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
Junio C Hamano· Nov 5, 2026, 19:41 UTC · re: Tuomas Ahola · lore

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

Tuomas Ahola <taahol@utu.fi> writes:
Show 13 quoted lines
>  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 ...
Show 5 quoted lines
> @@ -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.
Tuomas Ahola· Nov 11, 2026, 22:00 UTC · re: Junio C Hamano · lore

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

Junio C Hamano <gitster@pobox.com> wrote:
Show 23 quoted lines
> 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.
> 
Hmm, sounds sensible.
Show 15 quoted lines
> 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)"
> 
Okay, I'll do that.
Show 5 quoted lines
> Other than that, looking good.
> 
> Thanks.
> 
> 

← back to recent threads