Documentation/git-config.txt: add SCOPES section
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>
Glen Choo committed
Jul 14, 2022 at 21:27 UTC
5f5af3735dede73d6714311e20f17c7f77b1d907
1 file changed
+59
-23
Documentation/git-config.txt
+59
-23
@@ -297,23 +297,20 @@ The default is to use a pager.
297
FILES
298
-----
299
300
-If not set explicitly with `--file`, there are four files where
301
-'git config' will search for configuration options:
300
+By default, 'git config' will read configuration options from multiple
301
+files:
302
303
$(prefix)/etc/gitconfig::
304
System-wide configuration file.
305
306
$XDG_CONFIG_HOME/git/config::
307
- Second user-specific configuration file. If $XDG_CONFIG_HOME is not set
308
- or empty, `$HOME/.config/git/config` will be used. Any single-valued
309
- variable set in this file will be overwritten by whatever is in
310
- `~/.gitconfig`. It is a good idea not to create this file if
311
- you sometimes use older versions of Git, as support for this
312
- file was added fairly recently.
313
-
307
~/.gitconfig::
315
- User-specific configuration file. Also called "global"
316
- configuration file.
308
+ User-specific configuration files. When the XDG_CONFIG_HOME environment
309
+ variable is not set or empty, $HOME/.config/ is used as
310
+ $XDG_CONFIG_HOME.
311
++
312
+These are also called "global" configuration files. If both files exist, both
313
+files are read in the order given above.
314
315
$GIT_DIR/config::
316
Repository specific configuration file.
@@ -322,28 +319,67 @@ $GIT_DIR/config.worktree::
319
This is optional and is only searched when
320
`extensions.worktreeConfig` is present in $GIT_DIR/config.
321
325
-If no further options are given, all reading options will read all of these
326
-files that are available. If the global or the system-wide configuration
327
-file are not available they will be ignored. If the repository configuration
328
-file is not available or readable, 'git config' will exit with a non-zero
329
-error code. However, in neither case will an error message be issued.
322
+You may also provide additional configuration parameters when running any
323
+git command by using the `-c` option. See linkgit:git[1] for details.
324
+
325
+Options will be read from all of these files that are available. If the
326
+global or the system-wide configuration files are missing or unreadable they
327
+will be ignored. If the repository configuration file is missing or unreadable,
328
+'git config' will exit with a non-zero error code. An error message is produced
329
+if the file is unreadable, but not if it is missing.
330
331
The files are read in the order given above, with last value found taking
332
precedence over values read earlier. When multiple values are taken then all
333
values of a key from all files will be used.
334
335
-You may override individual configuration parameters when running any git
336
-command by using the `-c` option. See linkgit:git[1] for details.
337
-
338
-All writing options will per default write to the repository specific
335
+By default, options are only written to the repository specific
336
configuration file. Note that this also affects options like `--replace-all`
337
and `--unset`. *'git config' will only ever change one file at a time*.
338
342
-You can override these rules using the `--global`, `--system`,
343
-`--local`, `--worktree`, and `--file` command-line options; see
344
-<<OPTIONS>> above.
339
+You can limit which configuration sources are read from or written to by
340
+specifying the path of a file with the `--file` option, or by specifying a
341
+configuration scope with `--system`, `--global`, `--local`, or `--worktree`.
342
+For more, see <<OPTIONS>> above.
343
+
344
+SCOPES
345
+------
346
+
347
+Each configuration source falls within a configuration scope. The scopes
348
+are:
349
+
350
+system::
351
+ $(prefix)/etc/gitconfig
352
+
353
+global::
354
+ $XDG_CONFIG_HOME/git/config
355
++
356
+~/.gitconfig
357
+
358
+local::
359
+ $GIT_DIR/config
360
+
361
+worktree::
362
+ $GIT_DIR/config.worktree
363
+
364
+command::
365
+ GIT_CONFIG_{COUNT,KEY,VALUE} environment variables (see <<ENVIRONMENT>>
366
+ below)
367
++
368
+the `-c` option
369
+
370
+With the exception of 'command', each scope corresponds to a command line
371
+option: `--system`, `--global`, `--local`, `--worktree`.
372
+
373
+When reading options, specifying a scope will only read options from the
374
+files within that scope. When writing options, specifying a scope will write
375
+to the files within that scope (instead of the repository specific
376
+configuration file). See <<OPTIONS>> above for a complete description.
377
378
+Most configuration options are respected regardless of the scope it is
379
+defined in, but some options are only respected in certain scopes. See the
380
+respective option's documentation for the full details.
381
382
+[[ENVIRONMENT]]
383
ENVIRONMENT
384
-----------
385