patchdoc: clarify usage of XDG_CONFIG_HOME config file

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(-)

Hi Jacob,

Jacob Keller wrote:

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

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.

On Tue, Dec 12, 2017 at 7:20 AM, Todd Zullinger <tmz@pobox.com> wrote:

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

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

OK.

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/"?

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.

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

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.

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

On Tue, 12 Dec 2017, Jacob Keller wrote:

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 Halchenko <yoh@onerussian.com> writes:

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.