From: Jeff King Date: Thu, 10 Sep 2026 19:03:45 GMT Subject: Re: [PATCH v4 2/3] advice: introduce advice scoping mechanism Message-ID: <20260910190345.GA903701@coredump.intra.peff.net> In-Reply-To: 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 [] [--type=] [--all] \ > [--value=] [--fixed-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 in "git config --help" > > The SYNOPSIS section of "git config --help" refers to > 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 > ' option. Spell it out early in the description. I agree that we should use the term 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 . 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 ` can be used to tell the command to read from only +repository local configuration files by default. Provide a +`` (`--system`, `--global`, `--local`, `--worktree`, +or `--file `) to tell the command to read from only that location (see <>). When writing, the new value is written to the repository local -configuration file by default, and options `--system`, `--global`, -`--worktree`, `--file ` 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 `` 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 :: 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 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