Re: [PATCH v3 2/2] lint-docs: check the guide list in command-list.txt
- From
Julia Evans <julia@jvns.ca>
- Date
- Nov 2, 2026, 18:39 UTC
- Message-ID
- <48aa1e9a-3049-4316-9054-644a8754b0dd@app.fastmail.com>
- In-Reply-To
- <20261029184834.2273-3-taahol@utu.fi>
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