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

[Jacob Keller <jacob.keller@gmail.com>]

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.