[PATCH] doc: clarify usage of XDG_CONFIG_HOME config file
- From
Jacob Keller <jacob.keller@gmail.com>
- Date
- Dec 12, 2017, 11:24 UTC
- Message-ID
- <1513077862-165-1-git-send-email-jacob.keller@gmail.com>
The documentation for git config and how it reads the user specific configuration file is misleading. In some places it implies that $XDG_CONFIG_HOME/git/config will always be read. In others, it implies that only one of ~/.gitconfig and $XDG_CONFIG_HOME/git/config will be read.
Improve the documentation explaining how the various configuration files are read, and combined.
Instead of referencing each file individually, reference each type of location git will check. When discussing the user configuration, explain how we switch between one of three choices. Ensure to note that only one of the three choices is used.
Signed-off-by: Jacob Keller <jacob.keller@gmail.com> --- Documentation/git-config.txt | 46 +++++++++++++++++++++++--------------------- 1 file changed, 24 insertions(+), 22 deletions(-)
diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 14da5fc..4299fd6 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -104,13 +104,11 @@ OPTIONS list them. Returns error code 1 if no value is found. --global:: - For writing options: write to global `~/.gitconfig` file - rather than the repository `.git/config`, write to - `$XDG_CONFIG_HOME/git/config` file if this file exists and the - `~/.gitconfig` file doesn't. + For writing options: write to global user configuration file + rather than the repository `.git/config`. + -For reading options: read only from global `~/.gitconfig` and from -`$XDG_CONFIG_HOME/git/config` rather than from all available files. +For reading options: read only from global user configuration file +rather than from all available files. + See also <<FILES>>. @@ -237,26 +235,30 @@ See also <<FILES>>. FILES ----- -If not set explicitly with `--file`, there are four files where +If not set explicitly with `--file`, there are three locations where 'git config' will search for configuration options: -$(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. +System-wide configuration:: + Located at `$(prefix)/etc/gitconfig`. -~/.gitconfig:: - User-specific configuration file. Also called "global" - configuration file. +User-specific configuration:: + One and only one of the following files will be read ++ +- `~/.gitconfig` +- `$XDG_CONFIG_HOME/git/config` +- `$HOME/.config/git/config` ++ +If `~/.gitconfig` exists, it will be used, and the other files will not be +read. Otherwise, if `$XDG_CONFIG_HOME` is set, then `$XDG_CONFIG_HOME/git/config` +will be used, otherwise `$HOME/.config/git/config` will be used. ++ +Note that git will only ever use one of these files as the global user +configuration file at once. Additionally if you sometimes use an older version +of git, it is best to only rely on `~/.gitconfig` as support for the others was +added fairly recently. -$GIT_DIR/config:: - Repository specific configuration file. +Repository-specific configuration:: + Located at `$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
-- 2.7.4