undef/git-commit-vandalism
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Documentation/git-config.txt: add SCOPES section

Browse Source 
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
what those values mean.

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>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Glen Choo 2022-07-14 21:27:57 +00:00 committed by Junio C Hamano
parent 4e2a4d1dd4
commit 5f5af3735d
1 changed files with 59 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

82
Documentation/git-config.txt
View File

@ -297,23 +297,20 @@ 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.
$XDG_CONFIG_HOME/git/config::
Second user-specific configuration file. If $XDG_CONFIG_HOME is not set
or empty, `$HOME/.config/git/config` will be used. Any single-valued
variable set in this file will be overwritten by whatever is in
`~/.gitconfig`. It is a good idea not to create this file if
you sometimes use older versions of Git, as support for this
file was added fairly recently.
~/.gitconfig::
User-specific configuration file. Also called "global"
configuration file.
User-specific configuration files. When the XDG_CONFIG_HOME environment
variable is not set or empty, $HOME/.config/ is used as
$XDG_CONFIG_HOME.
+
These are also called "global" configuration files. If both files exist, both
files are read in the order given above.
$GIT_DIR/config::
Repository specific configuration file.
@ -322,28 +319,67 @@ $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.
Options will be read from all of these files that are available. If the
global or the system-wide configuration files are missing or unreadable they
will be ignored. If the repository configuration file is missing or unreadable,
'git config' will exit with a non-zero error code. An error message is produced
if the file is unreadable, but not if it is missing.
The files are read in the order given above, with last value found taking
precedence over values read earlier. When multiple values are taken then all
values of a key from all files will be used.
You may override individual configuration parameters when running any git
command by using the `-c` option. See linkgit:git[1] for details.
All writing options will per default write to the repository specific
By default, options are only written to the repository specific
configuration file. Note that this also affects options like `--replace-all`
and `--unset`. *'git config' will only ever change one file at a time*.
You can override these rules using the `--global`, `--system`,
`--local`, `--worktree`, and `--file` command-line options; see
<<OPTIONS>> above.
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::
GIT_CONFIG_{COUNT,KEY,VALUE} environment variables (see <<ENVIRONMENT>>
below)
+
the `-c` option
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]]
ENVIRONMENT
-----------