[PATCH] doc: clarify usage of XDG_CONFIG_HOME config file

[PATCH] doc: clarify usage of XDG_CONFIG_HOME config file

[Jacob Keller]

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

Re: [PATCH] doc: clarify usage of XDG_CONFIG_HOME config file

[Todd Zullinger]

Hi Jacob,

Jacob Keller wrote:
> 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.

Perhaps it would read a little easier as "Make it clear ..."
rather than "Ensure to note that ..." ?

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

Is it really accurate to say these were added fairly
recently?  It looks like XDG_CONFIG_HOME was added in
21cf322791 ("config: read (but not write) from
$XDG_CONFIG_HOME/git/config file", 2012-06-22) and
0e8593dc5b ("config: write to $XDG_CONFIG_HOME/git/config
file when appropriate", 2012-06-22) which are in 1.7.12.

Would it be better to say something like "if you sometimes
use a version of git prior to 1.7.12" here?

Or maybe we can drop "Additionally ..." altogether now?
Someone using a 5 year old git version sometimes will
hopefully know to check the documentation for that older
version.

-- 
Todd
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Now don't say you can't swear off drinking; it's easy. I've done it a
thousand times.
    -- W.C. Fields

Re: [PATCH] doc: clarify usage of XDG_CONFIG_HOME config file

[Jacob Keller]

On Tue, Dec 12, 2017 at 7:20 AM, Todd Zullinger <tmz@pobox.com> wrote:
> Hi Jacob,
>
> Jacob Keller wrote:
>> 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.
>
> Perhaps it would read a little easier as "Make it clear ..."
> rather than "Ensure to note that ..." ?
>
>> +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.
>
> Is it really accurate to say these were added fairly
> recently?  It looks like XDG_CONFIG_HOME was added in
> 21cf322791 ("config: read (but not write) from
> $XDG_CONFIG_HOME/git/config file", 2012-06-22) and
> 0e8593dc5b ("config: write to $XDG_CONFIG_HOME/git/config
> file when appropriate", 2012-06-22) which are in 1.7.12.
>
> Would it be better to say something like "if you sometimes
> use a version of git prior to 1.7.12" here?
>

I copied this from the original and didn't look to see how accurate it
was. I'd be ok with dropping it now that we've had support for such a
long time.

Thanks,
Jake

> Or maybe we can drop "Additionally ..." altogether now?
> Someone using a 5 year old git version sometimes will
> hopefully know to check the documentation for that older
> version.
>
> --
> Todd
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> Now don't say you can't swear off drinking; it's easy. I've done it a
> thousand times.
>     -- W.C. Fields
>

Re: [PATCH] doc: clarify usage of XDG_CONFIG_HOME config file

[Junio C Hamano]

Jacob Keller <jacob.keller@gmail.com> writes:

>  --global::
> +	For writing options: write to global user configuration file
> +	rather than the repository `.git/config`.
>  +
> +For reading options: read only from global user configuration file
> +rather than from all available files.
>  +
>  See also <<FILES>>.

OK.

> @@ -237,26 +235,30 @@ See also <<FILES>>.
>  FILES
>  -----
>  
> +If not set explicitly with `--file`, there are three locations where
>  'git config' will search for configuration options:
>  
> +System-wide configuration::
> +	Located at `$(prefix)/etc/gitconfig`.
>  
> +User-specific configuration::
> +	One and only one of the following files will be read

We said "will search for" upfront, but this talks about "will be
read", leaving the reader puzzled as to what should happen when
writing.  Perhaps "s/read/used/"?

> ++
> +- `~/.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.

And then "and the other files will not be read" can be dropped from
the first sentence of this paragraph?

Yaroslav on the original thread mentioned that reading codepath
without --file or --global does not limit to one of the three, and
this section is about "If not set explicitly with `--file`", so we'd
need to make sure if the above is what happens in reality (or update
the proposed clarification to match the reality).

Thanks.

Re: [PATCH] doc: clarify usage of XDG_CONFIG_HOME config file

[Jacob Keller]

On Tue, Dec 12, 2017 at 11:47 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Jacob Keller <jacob.keller@gmail.com> writes:
>
>>  --global::
>> +     For writing options: write to global user configuration file
>> +     rather than the repository `.git/config`.
>>  +
>> +For reading options: read only from global user configuration file
>> +rather than from all available files.
>>  +
>>  See also <<FILES>>.
>
> OK.
>
>> @@ -237,26 +235,30 @@ See also <<FILES>>.
>>  FILES
>>  -----
>>
>> +If not set explicitly with `--file`, there are three locations where
>>  'git config' will search for configuration options:
>>
>> +System-wide configuration::
>> +     Located at `$(prefix)/etc/gitconfig`.
>>
>> +User-specific configuration::
>> +     One and only one of the following files will be read
>
> We said "will search for" upfront, but this talks about "will be
> read", leaving the reader puzzled as to what should happen when
> writing.  Perhaps "s/read/used/"?
>

Ok, that makes sense. I'm definitely iffy on all this wording, as I
didn't really like the previous approach, but couldn't find anything
better than the approach shown here.

I'd be welcome to suggestions for another way to format this information.

>> ++
>> +- `~/.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.
>
> And then "and the other files will not be read" can be dropped from
> the first sentence of this paragraph?
>
> Yaroslav on the original thread mentioned that reading codepath
> without --file or --global does not limit to one of the three, and
> this section is about "If not set explicitly with `--file`", so we'd
> need to make sure if the above is what happens in reality (or update
> the proposed clarification to match the reality).

I'm pretty sure it does not read XDG_CONFIG_HOME unless ~/.gitconfig
is missing. I tried a few things, but it was 2am for me, so I may be
mis-remembering.

Either way, I'd prefer if we had explicit tests in the suite which
verified our assumptions.

Thanks,
Jake

>
> Thanks.

Re: [PATCH] doc: clarify usage of XDG_CONFIG_HOME config file

[Yaroslav Halchenko]

On Tue, 12 Dec 2017, Jacob Keller wrote:

> > And then "and the other files will not be read" can be dropped from
> > the first sentence of this paragraph?

> > Yaroslav on the original thread mentioned that reading codepath
> > without --file or --global does not limit to one of the three, and
> > this section is about "If not set explicitly with `--file`", so we'd
> > need to make sure if the above is what happens in reality (or update
> > the proposed clarification to match the reality).

> I'm pretty sure it does not read XDG_CONFIG_HOME unless ~/.gitconfig
> is missing. I tried a few things, but it was 2am for me, so I may be
> mis-remembering.

It always read it for non--global

$> ( HOME=/tmp/HOME; rm -rf $HOME; mkdir -p $HOME/.config/git; echo -e "[user]\n name=home" > $HOME/.gitconfig; echo -e "[user]\n name=xdg\n name2=xdg2" > $HOME/.config/git/config; git config user.name; git config user.name2; )     
home
xdg2

and it doesn't read it for --global

$> ( HOME=/tmp/HOME; rm -rf $HOME; mkdir -p $HOME/.config/git; echo -e "[user]\n name=home" > $HOME/.gitconfig; echo -e "[user]\n name=xdg\n name2=xdg2" > $HOME/.config/git/config; git config --global user.name; git config --global user.name2; )                                                                    
home

unless ~/.gitconfig is missing

$> ( HOME=/tmp/HOME; rm -rf $HOME; mkdir -p $HOME/.config/git; echo -e "[user]\n name=xdg\n name2=xdg2" > $HOME/.config/git/config; git config --global user.name; git config --global user.name2; )         
xdg                                                            
xdg2


-- 
Yaroslav O. Halchenko
Center for Open Neuroscience     http://centerforopenneuroscience.org
Dartmouth College, 419 Moore Hall, Hinman Box 6207, Hanover, NH 03755
Phone: +1 (603) 646-9834                       Fax: +1 (603) 646-1419
WWW:   http://www.linkedin.com/in/yarik        

Re: [PATCH] doc: clarify usage of XDG_CONFIG_HOME config file

[Junio C Hamano]

Yaroslav Halchenko <yoh@onerussian.com> writes:

> It always read it for non--global
> ...
> and it doesn't read it for --global
> ...
> unless ~/.gitconfig is missing

Yes, this dates back to 21cf3227 ("config: read (but not write) from
$XDG_CONFIG_HOME/git/config file", 2012-06-22), around the time back
when we added support to use xdg locations and doing so without breaking
existing users.

Taken together with a later commit in the same series 0e8593dc
("config: write to $XDG_CONFIG_HOME/git/config file when
appropriate", 2012-06-22), which says:

    config: write to $XDG_CONFIG_HOME/git/config file when appropriate
    
    Teach git to write to $XDG_CONFIG_HOME/git/config if
    
     - it already exists,
     - $HOME/.gitconfig file doesn't, and
     - The --global option is used.
    
    Otherwise, write to $HOME/.gitconfig when the --global option is
    given, as before.
    
    If the user doesn't create $XDG_CONFIG_HOME/git/config, there is
    absolutely no change. Users can use this new file only if they want.
    
    If $XDG_CONFIG_HOME is either not set or empty, $HOME/.config/git/config
    will be used.
    
    Advice for users who often come back to an old version of Git: you
    shouldn't create this file.

the plan is to have either one of these and not both at the same
time.  A user who wants to live in xdg world (and wants to avoid
cluttering $HOME with .many-files) can do so by creating an empty
one there, and all writes from there on go to the xdg world; as
there will no $HOME/.gitconfig created, the read side attempting to
read from it does not matter.  Other users get $HOME/.gitconfig when
running "config --global" to write for the first time, or users who
have been using Git from olden days already have $HOME/.gitconfig,
and no write goes to xdg world, so again the read side attempting to
read from there does not matter, either.

Perhaps a doc update needs to clarify these.

Thanks.