From: Jean-Noël Avila <jn.avila@free.fr>
Date: Fri, 06 Feb 2026 04:49:09 GMT
Subject: Re: [PATCH 04/11] config-batch: create 'help' command
Message-ID: <a023e4a2-e58f-49c7-83ee-a84554b83bc6@free.fr>
In-Reply-To: <d5e0c32497581e6ac4890c6e71c5c33b92d67d51.1770214803.git.gitgitgadget@gmail.com>

Le 04/02/2026 à 15:19, Derrick Stolee via GitGitGadget a écrit :
> From: Derrick Stolee <stolee@gmail.com>
> 
> Tools that use the 'git config-batch' tool will want to know which commands
> are available in the current Git version. Having a 'help' command assists
> greatly to give a clear set of available commands and their versions.
> 
> Signed-off-by: Derrick Stolee <stolee@gmail.com>
> ---
>  Documentation/git-config-batch.adoc | 17 +++++++++++++++
>  builtin/config-batch.c              | 32 +++++++++++++++++++++++++++++
>  t/t1312-config-batch.sh             | 13 ++++++++++++
>  3 files changed, 62 insertions(+)
> 
> diff --git a/Documentation/git-config-batch.adoc b/Documentation/git-config-batch.adoc
> index 31dd42f481..1fff68a13c 100644
> --- a/Documentation/git-config-batch.adoc
> +++ b/Documentation/git-config-batch.adoc
> @@ -38,6 +38,23 @@ unknown_command LF
>  
>  These are the commands that are currently understood:
>  
> +`help` version 1::
> +	The `help` command lists the currently-available commands in

The boilerplat text "The `help` command" is not very useful to the
reader. The new usage is to directly state the command in imperative mood:

List the currently...

> +	this version of Git. The output is multi-line, but the first
> +	line provides the count of possible commands via `help count <N>`.
> +	The next `<N>` lines are of the form `help <command> <version>`
> +	to state that this Git version supports that `<command>` at
> +	version `<version>`. Note that the same command may have multiple
> +	available versions.

Placeholder punning to keep a consistency between the command and its
description. Good!

> ++
> +Here is the currentl output of the help text at the latest version:

current

It may not be wise to talk about the "latest version". If the manpages
and the git command are out of sync (the user compiles her own git
version, but does not update the man pages), this may be confusing.

Is this specification of version critical to the understanding?


> ++
> +------------
> +help 1 count 2
> +help 1 help 1
> +help 1 get 1
> +------------
> +
>  `get` version 1::
>  	The `get` command searches the config key-value pairs within a
>  	given `<scope>` for values that match the fixed `<key>` and