git-config(1): clarify precedence of multiple values

In order to clarify which value is used when there are multiple values
defined for a key, re-order the list of file locations so that it runs
from least specific to most specific.  Then add a paragraph which simply
says that the last value will be used.

Signed-off-by: John Keeping <john@keeping.me.uk>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
index d88a6fcb29395ac200930191518fdbceca78bbd4..e60b7b6f100e359b190300877dc747aa6088a3c9 100644 (file)
--- a/Documentation/git-config.txt
+++ b/Documentation/git-config.txt
@@ -197,12 +197,8 @@ FILES
 If not set explicitly with '--file', there are four files where
 'git config' will search for configuration options:
 
 If not set explicitly with '--file', there are four files where
 'git config' will search for configuration options:
 

-$GIT_DIR/config::
-       Repository specific configuration file.
-
-~/.gitconfig::
-       User-specific configuration file. Also called "global"
-       configuration file.
+$(prefix)/etc/gitconfig::
+       System-wide configuration file.

 
 $XDG_CONFIG_HOME/git/config::
        Second user-specific configuration file. If $XDG_CONFIG_HOME is not set
 
 $XDG_CONFIG_HOME/git/config::
        Second user-specific configuration file. If $XDG_CONFIG_HOME is not set


@@ -212,8 +208,12 @@ $XDG_CONFIG_HOME/git/config::
        you sometimes use older versions of Git, as support for this
        file was added fairly recently.
 
        you sometimes use older versions of Git, as support for this
        file was added fairly recently.
 

-$(prefix)/etc/gitconfig::
-       System-wide configuration file.
+~/.gitconfig::
+       User-specific configuration file. Also called "global"
+       configuration file.
+
+$GIT_DIR/config::
+       Repository specific 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
 
 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


@@ -221,6 +221,10 @@ 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.
 
 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.
 

+The files are read in the order given above, with last value found taking
+precedence over values read earlier.  When multiple values are taken then all
+values of a key from all files will be used.
+

 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*.
 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*.