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

Jeff King [off-list ref] writes:

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 <redacted>
---

 * 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