[PATCH] doc: clarify usage of XDG_CONFIG_HOME config file

[Jacob Keller <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