Re: [PATCH] doc: clarify usage of XDG_CONFIG_HOME config file
Yaroslav Halchenkowrites: > 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.
Re: [PATCH] doc: clarify usage of XDG_CONFIG_HOME config file
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
On Tue, Dec 12, 2017 at 11:47 AM, Junio C Hamanowrote: > Jacob Keller 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 <>. > > OK. > >> @@ -237,26 +235,30 @@ See also <>. >> 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
On Tue, Dec 12, 2017 at 7:20 AM, Todd Zullingerwrote: > 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
Jacob Kellerwrites: > --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 <>. OK. > @@ -237,26 +235,30 @@ See also <>. > 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
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