Re: [PATCH v4 2/3] advice: introduce advice scoping mechanism

[Jeff King <peff@peff.net>]

On Thu, Sep 10, 2026 at 11:35:50AM -0700, Junio C Hamano wrote:

> The primary reason why I didn't think of "--worktree" is because
> output of "git config --help" has room for improvements.  This is a
> tangent, but one of its SYNOPSIS item reads like this:
> 
> 	git config set [<file-option>] [--type=<type>] [--all] \
> 		[--value=<pattern>] [--fixed-value] <name> <value>

If it makes you feel any better, I did not even know --worktree existed
until today. ;) I only discovered it when looking at the possible values
returned by config_scope_name().

I still have trouble imagining why a particular piece of advice would
make sense only in --worktree mode. The only concrete case I've seen for
any advice scoping is that clone/init advice config does not make sense
in repo config. And --global is the sensible solution to that (--system
works, too, but it is not a very helpful recommendation).

I kind of wonder if _all_ advice should just say "--global". I cannot
think of an advice flag that is really repo specific. They are about
silencing extra help because the _user_ understands the situation and
wants Git to be less chatty.

> --- >8 ---
> Subject: [PATCH] doc: clarify <file-option> in "git config --help"
> 
> The SYNOPSIS section of "git config --help" refers to <file-option>
> without explaining what they really mean.
> 
> I *think* they meant to refer to the mechanism to limit the file(s)
> read from or written to by giving the scope options or the '--file
> <filename>' option.  Spell it out early in the description.

I agree that we should use the term <file-option> to refer to it. I
think the paragraphs just below what you touched try to explain these,
but don't use the term.

Something like the patch below uses the term. There's also a lot of
duplication between the reading/writing paragraphs that could be
condensed (but I didn't do it here).

diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc
index 8d080e301b..18cee89f84 100644
--- a/Documentation/git-config.adoc
+++ b/Documentation/git-config.adoc
@@ -40,16 +40,14 @@ outgoing values are canonicalize-able under the given <type>.  If no
 unset an existing `--type` specifier with `--no-type`.
 
 When reading, the values are read from the system, global and
-repository local configuration files by default, and options
-`--system`, `--global`, `--local`, `--worktree` and
-`--file <filename>` can be used to tell the command to read from only
+repository local configuration files by default. Provide a
+`<file-option>` (`--system`, `--global`, `--local`, `--worktree`,
+or `--file <filename>`) to tell the command to read from only
 that location (see <<FILES>>).
 
 When writing, the new value is written to the repository local
-configuration file by default, and options `--system`, `--global`,
-`--worktree`, `--file <filename>` can be used to tell the command to
-write to that location (you can say `--local` but that is the
-default).
+configuration file by default. A `<file-options>` can be used to tell
+the command to write to that location.
 
 This command will fail with non-zero status upon error.  Some exit
 codes are:


I also considered that the options themselves should be grouped as
sub-entries of a <file-options>:: entry, but I think that may create
other awkwardness.

There is also --blob, which affects the source/dest of config, but isn't
really a "file" option. It is really more of a "location" option (and
that is what it is called in the macro grouping within the code, though
that is never exposed to the user).

>  * The SYNOPSIS section also refers to <display-option> for many
>    operations; I have no idea what it means.  I left a needswork
>    comment there.  We should either clarify it in a similar way, or
>    remove it if it does not refer to anything.

It comes from 14970509c6 (builtin/config: introduce "list" subcommand,
2024-05-06), and there's similar macro magic. It really just means
"stuff that changes the list output".

I think the manpage could probably be rewritten to focus on the
different command modes, and have a section for "here are the useful
options in list mode". Whereas historically, "--list" was just another
option. That would be a much bigger rewrite of the page, though.

-Peff