Re: [PATCH v7 1/5] Documentation/git-config.txt: add SCOPES section

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 7, 2022, 23:43 UTC
Message-ID: <xmqq4jzsxze4.fsf@gitster.g>
In-Reply-To: <5c58db3bb2189f3b4193a682aa3b43f3bfa95796.1657234914.git.gitgitgadget@gmail.com>

"Glen Choo via GitGitGadget" <gitgitgadget@gmail.com> writes:

Show 13 quoted lines

> From: Glen Choo <chooglen@google.com>
>
> In a subsequent commit, we will introduce "protected configuration",
> which is easiest to describe in terms of configuration scopes (i.e. it's
> the union of the 'system', 'global', and 'command' scopes). This
> description is fine for ML discussions, but it's inadequate for end
> users because we don't provide a good description of "configuration
> scopes" in the public docs.
>
> 145d59f482 (config: add '--show-scope' to print the scope of a config
> value, 2020-02-10) introduced the word "scope" to our public docs, but
> that only enumerates the scopes and assumes the user can figure out
> those values mean.

Probably: "figure out those values mean" -> "figure out what those
values mean"

Show 37 quoted lines

> Add a SCOPES section to Documentation/git-config.txt that describes the
> configuration scopes, their corresponding CLI options, and mentions that
> some configuration options are only respected in certain scopes. Then,
> use the word "scope" to simplify the FILES section and change some
> confusing wording.
>
> Signed-off-by: Glen Choo <chooglen@google.com>
> ---
>  Documentation/git-config.txt | 65 ++++++++++++++++++++++++++++--------
>  1 file changed, 51 insertions(+), 14 deletions(-)
>
> diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
> index 9376e39aef2..c4ce61a0493 100644
> --- a/Documentation/git-config.txt
> +++ b/Documentation/git-config.txt
> @@ -297,8 +297,8 @@ The default is to use a pager.
>  FILES
>  -----
>  
> -If not set explicitly with `--file`, there are four files where
> -'git config' will search for configuration options:
> +By default, 'git config' will read configuration options from multiple
> +files:
>  
>  $(prefix)/etc/gitconfig::
>  	System-wide configuration file.
> @@ -322,27 +322,64 @@ $GIT_DIR/config.worktree::
>  	This is optional and is only searched when
>  	`extensions.worktreeConfig` is present in $GIT_DIR/config.
>  
> -If no further options are given, all reading options will read all of these
> -files that are available. If the global or the system-wide configuration
> -file are not available they will be ignored. If the repository configuration
> -file is not available or readable, 'git config' will exit with a non-zero
> -error code. However, in neither case will an error message be issued.
> +You may also provide additional configuration parameters when running any
> +git command by using the `-c` option. See linkgit:git[1] for details.

Listing "-c" as another one in addition to these files is probably a good simplification, instead of "-c override others" in the original, as we would need to say "more specific ones override less specific ones" anyway.

Show 5 quoted lines

> +Options will be read from all of these files that are available. If the
> +global or the system-wide configuration file are not available they will be
> +ignored. If the repository configuration file is not available or readable,
> +'git config' will exit with a non-zero error code. Note that neither case
> +produces an error message.

Problem inherited from the original, but I suspect that rephrasing "not available" to "missing" (or "does not exist") may make it easier to follow. Also, "global" in the preceding description is explained as one of the user-specific configuration files, so it may be better to avoid it, e.g.

	If the user-specific or the system-wide configuration files
	are missing, they will be ignored.  If the repository
	configuration file is missing or unreadable, ...

Alternatively, we may want to tighten the description of $XDG_CONFIG_HOME/git/config and ~/.gitconfig a bit better, e.g. something along the lines of ...

	$XDG_CONFIG_HOME/git/config::
	$HOME/.gitconfig::
		User-specific configuration file.  When the
		XDG_CONFIG_HOME environment variable is not set or
		empty, $HOME/.config/ is used as $XDG_CONFIG_HOME.
	+
	These are often called the "global" configuration file.
	When either or both of them exist(s), both files are read.

Note that I deliberately omitted the mehtion that our $XDG support may be too recent and $HOME/.gitconfig may be preferred for portability. It came from 21cf3227 (config: read (but not write) from $XDG_CONFIG_HOME/git/config file, 2012-06-22) but sufficient number of years have passed.

Also note that I originally wrote the following immediately after the above

	+
	When writing to the "--global" scope (see below),
	$XDG_CONFIG_HOME/git/config is used if it exists; otherwise
	$HOME/.gitconfig is used.

but decided to discard it, since the OPTIONS -> "--global" covers it well enough.

With a tightening of the definition of what "global" is,, we can rephrase "If the global or the system configuration files are missing...".

Show 27 quoted lines

> +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 <<OPTIONS>> above.
> +
> +SCOPES
> +------
> +
> +Each configuration source falls within a configuration scope. The scopes
> +are:
> +
> +system::
> +	$(prefix)/etc/gitconfig
> +
> +global::
> +	$XDG_CONFIG_HOME/git/config
> ++
> +~/.gitconfig
> +
> +local::
> +	$GIT_DIR/config
> +
> +worktree::
> +	$GIT_DIR/config.worktree
> +
> +command::
> +	environment variables

We'd need to tighten this a bit, like:

	GIT_CONFIG_{COUNT,KEY,VALUE} environment varialbes (see below)

GIT_CONFIG_GLOBAL or GIT_CONFIG_SYSTEM environment varialbes and others are listed in the ENVIRONMENT section that comes after this section, but you do not want the readers to be confused into thinking that we'd give them more precedence over others.

> ++
> +the `-c` option

Show 14 quoted lines

> +With the exception of 'command', each scope corresponds to a command line
> +option: `--system`, `--global`, `--local`, `--worktree`.
> +
> +When reading options, specifying a scope will only read options from the
> +files within that scope. When writing options, specifying a scope will write
> +to the files within that scope (instead of the repository specific
> +configuration file). See <<OPTIONS>> above for a complete description.
>  
> +Most configuration options are respected regardless of the scope it is
> +defined in, but some options are only respected in certain scopes. See the
> +respective option's documentation for the full details.
>  
>  ENVIRONMENT
>  -----------

Overall it was a pleasant read.  Thanks, will queue.