git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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
Previous: Tuomas AholaNext: Tuomas Ahola
Message 14 of 17 in “guides: keep Documentation/Makefile and command-list.txt in sync”
  1. 0/2 guides: keep Documentation/Makefile and command-list.txt in syncTuomas Ahola, Sep 9, 2026
  2. 2/2 lint-docs: check the guide list in command-list.txtTuomas Ahola, Sep 9, 2026
  3. Junio C HamanoSep 9, 2026
  4. 1/2 command-list: add gitformat-loose(5) and gitpacking(7)Tuomas Ahola, Sep 9, 2026
  5. Junio C HamanoSep 9, 2026
  6. 0/2 guides: keep Documentation/Makefile and command-list.txt in syncTuomas Ahola, Sep 10, 2026
  7. 1/2 command-list.txt: add gitformat-loose(5) and gitpacking(7)Tuomas Ahola, Sep 10, 2026
  8. 2/2 lint-docs: check the guide list in command-list.txtTuomas Ahola, Sep 10, 2026
  9. 0/2 guides: keep Documentation/Makefile and command-list.txt in syncTuomas Ahola, Oct 29, 2026
  10. 1/2 command-list.txt: add gitformat-loose(5) and gitpacking(7)Tuomas Ahola, Oct 29, 2026
  11. Junio C HamanoNov 5, 2026
  12. Tuomas AholaNov 11, 2026
  13. 2/2 lint-docs: check the guide list in command-list.txtTuomas Ahola, Oct 29, 2026
  14. Julia EvansNov 2, 2026
  15. Tuomas AholaNov 3, 2026
  16. Junio C HamanoNov 5, 2026
  17. Tuomas AholaNov 11, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.