Re: [PATCH v4 2/3] advice: introduce advice scoping mechanism
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Sep 10, 2026, 18:35 UTC
- Message-ID
- <xmqqpkyldke1.fsf@gitster.g>
- In-Reply-To
- <20260910155247.GA251185@coredump.intra.peff.net>
Jeff King <peff@peff.net> writes:
Show 5 quoted lines
> I'm really not sure why anybody would use those other flags, though (or > even --system, for that matter). After reading the thread again, I get > why we want "--global" for advice that only affects new repository > creation (like defaultBranchName), since otherwise it could never have > any effect. But why would you ever want --system?
No particular concrete expected use case in mind. But I figured that it would not be too much additional effort to allow other scopes once we need to add support to allow "--global" to be added to the message. I didn't think of "--worktree", but now you have mentioned it, I tend to think it is more plausible to have real use case than "--system" (which users often do not even have power to set).
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>
And nowhere in the body of the documentation there is any description on what <file-option> is. There is this sentence
... and options --system, --global, --local, --worktree and
--file <filename> can be used to tell the command to read from
only that location.in one paragraph that gives enough hints that these five options are related to each other and give the closest thing as the definition of <file-option>, but I wouldn't call it a very good form of documentation.
There is a section called FILES, at the end of which has
You can limit which configuration sources are read from or
written to by specifying the path of a file with the --file
option, or by specifying a configuration scope with --system,
--global, --local, or --worktree. For more, see the section
called “OPTIONS” above.but it is not explicit that the section is talking about <file-option>, either.
--- >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.
Signed-off-by: Junio C Hamano <gitster@pobox.com> ---
* 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.
Documentation/git-config.adoc | 6 ++++++ 1 file changed, 6 insertions(+)
diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc index 57af010ade..3673226505 100644 --- a/Documentation/git-config.adoc +++ b/Documentation/git-config.adoc @@ -39,6 +39,12 @@ outgoing values are canonicalize-able under the given <type>. If no `--type=<type>` is given, no canonicalization will be performed. Callers may unset an existing `--type` specifier with `--no-type`. +The `<file-option>` in the SYNOPSIS refers to options that limit the +read/write operations to a specific scope (see <<SCOPES>>) or a single +file (see <<FILES>>). + +// NEEDSWORK: What is the `<display-option>` meant to refer to? + When reading, the values are read from the system, global and repository local configuration files by default, and options `--system`, `--global`, `--local`, `--worktree` and
-- 2.56.0-rc0-135-g9520983108