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

From: Jacob Keller <jacob.keller@gmail.com>
Date: Dec 13, 2017, 05:38 UTC
Message-ID: <CA+P7+xqR0C_Z5fJFdSBvzqCT=LU-mK0cdtaqJ=6TH5Ty60PQrg@mail.gmail.com>
In-Reply-To: <xmqqo9n320ep.fsf@gitster.mtv.corp.google.com>

On Tue, Dec 12, 2017 at 11:47 AM, Junio C Hamano <gitster@pobox.com> wrote:

Show 30 quoted lines

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

Show 17 quoted lines

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