git-config: Improve documentation of git-config file handling

The description which files git-config uses and how the various
command line options and environment variables affect its
behaviour was incomplete, outdated and confusing.

Signed-off-by: Frank Lichtenheld <frank@lichtenheld.de>
Signed-off-by: Junio C Hamano <junkio@cox.net>

Documentation/git-config.txt

@@ -75,11 +75,22 @@ OPTIONS
 	Like --get-all, but interprets the name as a regular expression.
 
 --global::
-	Use global ~/.gitconfig file rather than the repository .git/config.
+	For writing options: write to global ~/.gitconfig file rather than
+	the repository .git/config.
++
+For reading options: read only from global ~/.gitconfig rather than
+from all available files.
++
+See also <<FILES>>.
 
 --system::
-	Use system-wide $(prefix)/etc/gitconfig rather than the repository
-	.git/config.
+	For writing options: write to system-wide $(prefix)/etc/gitconfig
+	rather than the repository .git/config.
++
+For reading options: read only from system-wide $(prefix)/etc/gitconfig
+rather than from all available files.
++
+See also <<FILES>>.
 
 --remove-section::
 	Remove the given section from the configuration file.
@@ -106,18 +117,59 @@ OPTIONS
 	by 1024, 1048576, or 1073741824 prior to output.
 
 
+[[FILES]]
+FILES
+-----
+
+There are three files where git-config will search for configuration
+options:
+
+.git/config::
+	Repository specific configuration file. (The filename is
+	of course relative to the repository root, not the working
+	directory.)
+
+~/.gitconfig::
+	User-specific configuration file. Also called "global"
+	configuration file.
+
+$(prefix)/etc/gitconfig::
+	System-wide configuration file.
+
+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.
+
+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' and the '--system' options will limit the file used
+to the global or system-wide file respectively. The GIT_CONFIG environment
+variable has a similar effect, but you can specify any filename you want.
+
+The GIT_CONFIG_LOCAL environment variable on the other hand only changes
+the name used instead of the repository configuration file. The global and
+the system-wide configuration files will still be read. (For writing options
+this will obviously result in the same behavior as using GIT_CONFIG.)
+
+
 ENVIRONMENT
 -----------
 
 GIT_CONFIG::
 	Take the configuration from the given file instead of .git/config.
-	Using the "--global" option forces this to ~/.gitconfig.
+	Using the "--global" option forces this to ~/.gitconfig. Using the
+	"--system" option forces this to $(prefix)/etc/gitconfig.
 
 GIT_CONFIG_LOCAL::
-	Currently the same as $GIT_CONFIG; when Git will support global
-	configuration files, this will cause it to take the configuration
-	from the global configuration file in addition to the given file.
+	Take the configuration from the given file instead if .git/config.
+	Still read the global and the system-wide configuration files, though.
 
+See also <<FILES>>.
 
 
 [[EXAMPLES]]