From 4bb9eb5f91102f1df4f5d47cf7d78ed67307f144 Mon Sep 17 00:00:00 2001 From: Jeff King Date: Wed, 14 Jul 2021 17:37:29 -0400 Subject: [PATCH 1/3] doc/git-config: explain --file instead of referring to GIT_CONFIG The explanation for the --file option only refers to GIT_CONFIG. This redirection to an environment variable is confusing, but doubly so because the description of GIT_CONFIG is out of date. Let's describe --file from scratch, detailing both the reading and writing behavior as we do for other similar options like --system, etc. Signed-off-by: Jeff King Reviewed-by: Taylor Blau Signed-off-by: Junio C Hamano --- Documentation/git-config.txt | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 5cddadafd2..6c78ad1c13 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -143,7 +143,13 @@ See also <>. -f config-file:: --file config-file:: - Use the given config file instead of the one specified by GIT_CONFIG. + For writing options: write to the specified file rather than the + repository `.git/config`. ++ +For reading options: read only from the specified file rather than from all +available files. ++ +See also <>. --blob blob:: Similar to `--file` but use the given blob instead of a file. E.g. From b3b186262fd982d795be79a268c90efdd8116c1b Mon Sep 17 00:00:00 2001 From: Jeff King Date: Wed, 14 Jul 2021 17:38:16 -0400 Subject: [PATCH 2/3] doc/git-config: clarify GIT_CONFIG environment variable The scope and utility of the GIT_CONFIG variable was drastically reduced by dc87183189 (Only use GIT_CONFIG in "git config", not other programs, 2008-06-30). But the documentation in git-config(1) predates that, which makes it rather misleading. These days it is really just another way to say "--file". So let's say that, and explicitly make it clear that it does not impact other Git commands (like GIT_CONFIG_SYSTEM, etc, would). I also bumped it to the bottom of the list of variables, and warned people off of using it. We don't have any plans for deprecation at this point, but there's little point in encouraging people to use it by putting it at the top of the list. Signed-off-by: Jeff King Reviewed-by: Taylor Blau Signed-off-by: Junio C Hamano --- Documentation/git-config.txt | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 6c78ad1c13..1348957497 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -341,11 +341,6 @@ can specify any filename you want. ENVIRONMENT ----------- -GIT_CONFIG:: - Take the configuration from the given file instead of .git/config. - Using the "--global" option forces this to ~/.gitconfig. Using the - "--system" option forces this to $(prefix)/etc/gitconfig. - GIT_CONFIG_GLOBAL:: GIT_CONFIG_SYSTEM:: Take the configuration from the given files instead from global or @@ -373,6 +368,12 @@ This is useful for cases where you want to spawn multiple git commands with a common configuration but cannot depend on a configuration file, for example when writing scripts. +GIT_CONFIG:: + If no `--file` option is provided to `git config`, use the file + given by `GIT_CONFIG` as if it were provided via `--file`. This + variable has no effect on other Git commands, and is mostly for + historical compatibility; there is generally no reason to use it + instead of the `--file` option. [[EXAMPLES]] EXAMPLES From 734283855f86bab97a060278538d5c68ca5edbc7 Mon Sep 17 00:00:00 2001 From: Jeff King Date: Wed, 14 Jul 2021 17:38:27 -0400 Subject: [PATCH 3/3] doc/git-config: simplify "override" advice for FILES section At the end of the FILES section, we indicate that you can override the regular lookup rules with --global, etc. But: - we're missing the --local option - we point to GIT_CONFIG instead of --file, but the latter has much better documentation - we're vague about how the overrides work; the actual option descriptions are much better here So let's just mention the names and point people back to the OPTIONS section. We could perhaps even delete this paragraph entirely, but the presence of the names may give people reading FILES a clue about where to look for more information. Signed-off-by: Jeff King Reviewed-by: Taylor Blau Signed-off-by: Junio C Hamano --- Documentation/git-config.txt | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 1348957497..2dc4bae6da 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -71,6 +71,7 @@ codes are: On success, the command returns the exit code 0. +[[OPTIONS]] OPTIONS ------- @@ -331,11 +332,9 @@ All writing options will per default write 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 either by command-line options or by environment -variables. The `--global`, `--system` and `--worktree` options will limit -the file used to the global, system-wide or per-worktree file respectively. -The `GIT_CONFIG` environment variable has a similar effect, but you -can specify any filename you want. +You can override these rules using the `--global`, `--system`, +`--local`, `--worktree`, and `--file` command-line options; see +<> above. ENVIRONMENT