{"thread":{"id":"47431","subject":"[PATCH] doc: clarify usage of XDG_CONFIG_HOME config file","startedAt":"2017-12-12T11:24:32Z","lastAt":"2017-12-13T19:57:32Z","messageCount":7,"participants":["Jacob Keller","Todd Zullinger","Junio C Hamano","Yaroslav Halchenko"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"334674","messageId":"1513077862-165-1-git-send-email-jacob.keller@gmail.com","threadId":"47431","inReplyTo":null,"subject":"[PATCH] doc: clarify usage of XDG_CONFIG_HOME config file","fromName":"Jacob Keller","fromEmail":"jacob.keller@gmail.com","sentAt":"2017-12-12T11:24:22Z","receivedAt":"2017-12-12T11:24:32Z","isPatch":true,"sender":{"key":"jacob.keller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/874719?v=4"},"body":"The documentation for git config and how it reads the user specific\nconfiguration file is misleading. In some places it implies that\n$XDG_CONFIG_HOME/git/config will always be read. In others, it implies\nthat only one of ~/.gitconfig and $XDG_CONFIG_HOME/git/config will be\nread.\n\nImprove the documentation explaining how the various configuration files\nare read, and combined.\n\nInstead of referencing each file individually, reference each type of\nlocation git will check. When discussing the user configuration, explain\nhow we switch between one of three choices. Ensure to note that only one\nof the three choices is used.\n\nSigned-off-by: Jacob Keller <jacob.keller@gmail.com>\n---\n Documentation/git-config.txt | 46 +++++++++++++++++++++++---------------------\n 1 file changed, 24 insertions(+), 22 deletions(-)\n\ndiff --git a/Documentation/git-config.txt b/Documentation/git-config.txt\nindex 14da5fc..4299fd6 100644\n--- a/Documentation/git-config.txt\n+++ b/Documentation/git-config.txt\n@@ -104,13 +104,11 @@ OPTIONS\n \tlist them.  Returns error code 1 if no value is found.\n \n --global::\n-\tFor writing options: write to global `~/.gitconfig` file\n-\trather than the repository `.git/config`, write to\n-\t`$XDG_CONFIG_HOME/git/config` file if this file exists and the\n-\t`~/.gitconfig` file doesn't.\n+\tFor writing options: write to global user configuration file\n+\trather than the repository `.git/config`.\n +\n-For reading options: read only from global `~/.gitconfig` and from\n-`$XDG_CONFIG_HOME/git/config` rather than from all available files.\n+For reading options: read only from global user configuration file\n+rather than from all available files.\n +\n See also <<FILES>>.\n \n@@ -237,26 +235,30 @@ See also <<FILES>>.\n FILES\n -----\n \n-If not set explicitly with `--file`, there are four files where\n+If not set explicitly with `--file`, there are three locations where\n 'git config' will search for configuration options:\n \n-$(prefix)/etc/gitconfig::\n-\tSystem-wide configuration file.\n-\n-$XDG_CONFIG_HOME/git/config::\n-\tSecond user-specific configuration file. If $XDG_CONFIG_HOME is not set\n-\tor empty, `$HOME/.config/git/config` will be used. Any single-valued\n-\tvariable set in this file will be overwritten by whatever is in\n-\t`~/.gitconfig`.  It is a good idea not to create this file if\n-\tyou sometimes use older versions of Git, as support for this\n-\tfile was added fairly recently.\n+System-wide configuration::\n+\tLocated at `$(prefix)/etc/gitconfig`.\n \n-~/.gitconfig::\n-\tUser-specific configuration file. Also called \"global\"\n-\tconfiguration file.\n+User-specific configuration::\n+\tOne and only one of the following files will be read\n++\n+- `~/.gitconfig`\n+- `$XDG_CONFIG_HOME/git/config`\n+- `$HOME/.config/git/config`\n++\n+If `~/.gitconfig` exists, it will be used, and the other files will not be\n+read. Otherwise, if `$XDG_CONFIG_HOME` is set, then `$XDG_CONFIG_HOME/git/config`\n+will be used, otherwise `$HOME/.config/git/config` will be used.\n++\n+Note that git will only ever use one of these files as the global user\n+configuration file at once. Additionally if you sometimes use an older version\n+of git, it is best to only rely on `~/.gitconfig` as support for the others was\n+added fairly recently.\n \n-$GIT_DIR/config::\n-\tRepository specific configuration file.\n+Repository-specific configuration::\n+\tLocated at `$GIT_DIR/config`.\n \n If no further options are given, all reading options will read all of these\n files that are available. If the global or the system-wide configuration\n-- \n2.7.4\n\n"},{"id":"334680","messageId":"20171212152009.GS3693@zaya.teonanacatl.net","threadId":"47431","inReplyTo":"1513077862-165-1-git-send-email-jacob.keller@gmail.com","subject":"Re: [PATCH] doc: clarify usage of XDG_CONFIG_HOME config file","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2017-12-12T15:20:09Z","receivedAt":"2017-12-12T15:20:19Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"Hi Jacob,\n\nJacob Keller wrote:\n> The documentation for git config and how it reads the user specific\n> configuration file is misleading. In some places it implies that\n> $XDG_CONFIG_HOME/git/config will always be read. In others, it implies\n> that only one of ~/.gitconfig and $XDG_CONFIG_HOME/git/config will be\n> read.\n> \n> Improve the documentation explaining how the various configuration files\n> are read, and combined.\n> \n> Instead of referencing each file individually, reference each type of\n> location git will check. When discussing the user configuration, explain\n> how we switch between one of three choices. Ensure to note that only one\n> of the three choices is used.\n\nPerhaps it would read a little easier as \"Make it clear ...\"\nrather than \"Ensure to note that ...\" ?\n\n> +Note that git will only ever use one of these files as the global user\n> +configuration file at once. Additionally if you sometimes use an older version\n> +of git, it is best to only rely on `~/.gitconfig` as support for the others was\n> +added fairly recently.\n\nIs it really accurate to say these were added fairly\nrecently?  It looks like XDG_CONFIG_HOME was added in\n21cf322791 (\"config: read (but not write) from\n$XDG_CONFIG_HOME/git/config file\", 2012-06-22) and\n0e8593dc5b (\"config: write to $XDG_CONFIG_HOME/git/config\nfile when appropriate\", 2012-06-22) which are in 1.7.12.\n\nWould it be better to say something like \"if you sometimes\nuse a version of git prior to 1.7.12\" here?\n\nOr maybe we can drop \"Additionally ...\" altogether now?\nSomeone using a 5 year old git version sometimes will\nhopefully know to check the documentation for that older\nversion.\n\n-- \nTodd\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nNow don't say you can't swear off drinking; it's easy. I've done it a\nthousand times.\n    -- W.C. Fields\n\n"},{"id":"334697","messageId":"xmqqo9n320ep.fsf@gitster.mtv.corp.google.com","threadId":"47431","inReplyTo":"1513077862-165-1-git-send-email-jacob.keller@gmail.com","subject":"Re: [PATCH] doc: clarify usage of XDG_CONFIG_HOME config file","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-12-12T19:47:58Z","receivedAt":"2017-12-12T19:48:07Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jacob Keller <jacob.keller@gmail.com> writes:\n\n>  --global::\n> +\tFor writing options: write to global user configuration file\n> +\trather than the repository `.git/config`.\n>  +\n> +For reading options: read only from global user configuration file\n> +rather than from all available files.\n>  +\n>  See also <<FILES>>.\n\nOK.\n\n> @@ -237,26 +235,30 @@ See also <<FILES>>.\n>  FILES\n>  -----\n>  \n> +If not set explicitly with `--file`, there are three locations where\n>  'git config' will search for configuration options:\n>  \n> +System-wide configuration::\n> +\tLocated at `$(prefix)/etc/gitconfig`.\n>  \n> +User-specific configuration::\n> +\tOne and only one of the following files will be read\n\nWe said \"will search for\" upfront, but this talks about \"will be\nread\", leaving the reader puzzled as to what should happen when\nwriting.  Perhaps \"s/read/used/\"?\n\n> ++\n> +- `~/.gitconfig`\n> +- `$XDG_CONFIG_HOME/git/config`\n> +- `$HOME/.config/git/config`\n> ++\n> +If `~/.gitconfig` exists, it will be used, and the other files will not be\n> +read. Otherwise, if `$XDG_CONFIG_HOME` is set, then `$XDG_CONFIG_HOME/git/config`\n> +will be used, otherwise `$HOME/.config/git/config` will be used.\n\nAnd then \"and the other files will not be read\" can be dropped from\nthe first sentence of this paragraph?\n\nYaroslav on the original thread mentioned that reading codepath\nwithout --file or --global does not limit to one of the three, and\nthis section is about \"If not set explicitly with `--file`\", so we'd\nneed to make sure if the above is what happens in reality (or update\nthe proposed clarification to match the reality).\n\nThanks.\n"},{"id":"334737","messageId":"CA+P7+xqZAYqTHjfbTSDG8Uj4Sdj3Ja6xxFYBfS=P92XiBMvLmA@mail.gmail.com","threadId":"47431","inReplyTo":"20171212152009.GS3693@zaya.teonanacatl.net","subject":"Re: [PATCH] doc: clarify usage of XDG_CONFIG_HOME config file","fromName":"Jacob Keller","fromEmail":"jacob.keller@gmail.com","sentAt":"2017-12-13T05:36:32Z","receivedAt":"2017-12-13T05:36:59Z","isPatch":true,"sender":{"key":"jacob.keller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/874719?v=4"},"body":"On Tue, Dec 12, 2017 at 7:20 AM, Todd Zullinger <tmz@pobox.com> wrote:\n> Hi Jacob,\n>\n> Jacob Keller wrote:\n>> The documentation for git config and how it reads the user specific\n>> configuration file is misleading. In some places it implies that\n>> $XDG_CONFIG_HOME/git/config will always be read. In others, it implies\n>> that only one of ~/.gitconfig and $XDG_CONFIG_HOME/git/config will be\n>> read.\n>>\n>> Improve the documentation explaining how the various configuration files\n>> are read, and combined.\n>>\n>> Instead of referencing each file individually, reference each type of\n>> location git will check. When discussing the user configuration, explain\n>> how we switch between one of three choices. Ensure to note that only one\n>> of the three choices is used.\n>\n> Perhaps it would read a little easier as \"Make it clear ...\"\n> rather than \"Ensure to note that ...\" ?\n>\n>> +Note that git will only ever use one of these files as the global user\n>> +configuration file at once. Additionally if you sometimes use an older version\n>> +of git, it is best to only rely on `~/.gitconfig` as support for the others was\n>> +added fairly recently.\n>\n> Is it really accurate to say these were added fairly\n> recently?  It looks like XDG_CONFIG_HOME was added in\n> 21cf322791 (\"config: read (but not write) from\n> $XDG_CONFIG_HOME/git/config file\", 2012-06-22) and\n> 0e8593dc5b (\"config: write to $XDG_CONFIG_HOME/git/config\n> file when appropriate\", 2012-06-22) which are in 1.7.12.\n>\n> Would it be better to say something like \"if you sometimes\n> use a version of git prior to 1.7.12\" here?\n>\n\nI copied this from the original and didn't look to see how accurate it\nwas. I'd be ok with dropping it now that we've had support for such a\nlong time.\n\nThanks,\nJake\n\n> Or maybe we can drop \"Additionally ...\" altogether now?\n> Someone using a 5 year old git version sometimes will\n> hopefully know to check the documentation for that older\n> version.\n>\n> --\n> Todd\n> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n> Now don't say you can't swear off drinking; it's easy. I've done it a\n> thousand times.\n>     -- W.C. Fields\n>\n"},{"id":"334738","messageId":"CA+P7+xqR0C_Z5fJFdSBvzqCT=LU-mK0cdtaqJ=6TH5Ty60PQrg@mail.gmail.com","threadId":"47431","inReplyTo":"xmqqo9n320ep.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] doc: clarify usage of XDG_CONFIG_HOME config file","fromName":"Jacob Keller","fromEmail":"jacob.keller@gmail.com","sentAt":"2017-12-13T05:38:22Z","receivedAt":"2017-12-13T05:38:48Z","isPatch":true,"sender":{"key":"jacob.keller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/874719?v=4"},"body":"On Tue, Dec 12, 2017 at 11:47 AM, Junio C Hamano <gitster@pobox.com> wrote:\n> Jacob Keller <jacob.keller@gmail.com> writes:\n>\n>>  --global::\n>> +     For writing options: write to global user configuration file\n>> +     rather than the repository `.git/config`.\n>>  +\n>> +For reading options: read only from global user configuration file\n>> +rather than from all available files.\n>>  +\n>>  See also <<FILES>>.\n>\n> OK.\n>\n>> @@ -237,26 +235,30 @@ See also <<FILES>>.\n>>  FILES\n>>  -----\n>>\n>> +If not set explicitly with `--file`, there are three locations where\n>>  'git config' will search for configuration options:\n>>\n>> +System-wide configuration::\n>> +     Located at `$(prefix)/etc/gitconfig`.\n>>\n>> +User-specific configuration::\n>> +     One and only one of the following files will be read\n>\n> We said \"will search for\" upfront, but this talks about \"will be\n> read\", leaving the reader puzzled as to what should happen when\n> writing.  Perhaps \"s/read/used/\"?\n>\n\nOk, that makes sense. I'm definitely iffy on all this wording, as I\ndidn't really like the previous approach, but couldn't find anything\nbetter than the approach shown here.\n\nI'd be welcome to suggestions for another way to format this information.\n\n>> ++\n>> +- `~/.gitconfig`\n>> +- `$XDG_CONFIG_HOME/git/config`\n>> +- `$HOME/.config/git/config`\n>> ++\n>> +If `~/.gitconfig` exists, it will be used, and the other files will not be\n>> +read. Otherwise, if `$XDG_CONFIG_HOME` is set, then `$XDG_CONFIG_HOME/git/config`\n>> +will be used, otherwise `$HOME/.config/git/config` will be used.\n>\n> And then \"and the other files will not be read\" can be dropped from\n> the first sentence of this paragraph?\n>\n> Yaroslav on the original thread mentioned that reading codepath\n> without --file or --global does not limit to one of the three, and\n> this section is about \"If not set explicitly with `--file`\", so we'd\n> need to make sure if the above is what happens in reality (or update\n> the proposed clarification to match the reality).\n\nI'm pretty sure it does not read XDG_CONFIG_HOME unless ~/.gitconfig\nis missing. I tried a few things, but it was 2am for me, so I may be\nmis-remembering.\n\nEither way, I'd prefer if we had explicit tests in the suite which\nverified our assumptions.\n\nThanks,\nJake\n\n>\n> Thanks.\n"},{"id":"334744","messageId":"20171213142334.oy2uvkamho4whspj@hopa.kiewit.dartmouth.edu","threadId":"47431","inReplyTo":"CA+P7+xqR0C_Z5fJFdSBvzqCT=LU-mK0cdtaqJ=6TH5Ty60PQrg@mail.gmail.com","subject":"Re: [PATCH] doc: clarify usage of XDG_CONFIG_HOME config file","fromName":"Yaroslav Halchenko","fromEmail":"yoh@onerussian.com","sentAt":"2017-12-13T14:23:34Z","receivedAt":"2017-12-13T14:24:51Z","isPatch":true,"sender":{"key":"yoh@onerussian.com","avatar":"https://gravatar.com/avatar/8901b82415ae451a83aea49409708912726e53620e3ac92320bf1f86548d97e9?d=mp&s=160"},"body":"\nOn Tue, 12 Dec 2017, Jacob Keller wrote:\n\n> > And then \"and the other files will not be read\" can be dropped from\n> > the first sentence of this paragraph?\n\n> > Yaroslav on the original thread mentioned that reading codepath\n> > without --file or --global does not limit to one of the three, and\n> > this section is about \"If not set explicitly with `--file`\", so we'd\n> > need to make sure if the above is what happens in reality (or update\n> > the proposed clarification to match the reality).\n\n> I'm pretty sure it does not read XDG_CONFIG_HOME unless ~/.gitconfig\n> is missing. I tried a few things, but it was 2am for me, so I may be\n> mis-remembering.\n\nIt always read it for non--global\n\n$> ( 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; )     \nhome\nxdg2\n\nand it doesn't read it for --global\n\n$> ( 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; )                                                                    \nhome\n\nunless ~/.gitconfig is missing\n\n$> ( 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; )         \nxdg                                                            \nxdg2\n\n\n-- \nYaroslav O. Halchenko\nCenter for Open Neuroscience     http://centerforopenneuroscience.org\nDartmouth College, 419 Moore Hall, Hinman Box 6207, Hanover, NH 03755\nPhone: +1 (603) 646-9834                       Fax: +1 (603) 646-1419\nWWW:   http://www.linkedin.com/in/yarik        \n"},{"id":"334775","messageId":"xmqqmv2mwgd7.fsf@gitster.mtv.corp.google.com","threadId":"47431","inReplyTo":"20171213142334.oy2uvkamho4whspj@hopa.kiewit.dartmouth.edu","subject":"Re: [PATCH] doc: clarify usage of XDG_CONFIG_HOME config file","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-12-13T19:57:24Z","receivedAt":"2017-12-13T19:57:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Yaroslav Halchenko <yoh@onerussian.com> writes:\n\n> It always read it for non--global\n> ...\n> and it doesn't read it for --global\n> ...\n> unless ~/.gitconfig is missing\n\nYes, this dates back to 21cf3227 (\"config: read (but not write) from\n$XDG_CONFIG_HOME/git/config file\", 2012-06-22), around the time back\nwhen we added support to use xdg locations and doing so without breaking\nexisting users.\n\nTaken together with a later commit in the same series 0e8593dc\n(\"config: write to $XDG_CONFIG_HOME/git/config file when\nappropriate\", 2012-06-22), which says:\n\n    config: write to $XDG_CONFIG_HOME/git/config file when appropriate\n    \n    Teach git to write to $XDG_CONFIG_HOME/git/config if\n    \n     - it already exists,\n     - $HOME/.gitconfig file doesn't, and\n     - The --global option is used.\n    \n    Otherwise, write to $HOME/.gitconfig when the --global option is\n    given, as before.\n    \n    If the user doesn't create $XDG_CONFIG_HOME/git/config, there is\n    absolutely no change. Users can use this new file only if they want.\n    \n    If $XDG_CONFIG_HOME is either not set or empty, $HOME/.config/git/config\n    will be used.\n    \n    Advice for users who often come back to an old version of Git: you\n    shouldn't create this file.\n\nthe plan is to have either one of these and not both at the same\ntime.  A user who wants to live in xdg world (and wants to avoid\ncluttering $HOME with .many-files) can do so by creating an empty\none there, and all writes from there on go to the xdg world; as\nthere will no $HOME/.gitconfig created, the read side attempting to\nread from it does not matter.  Other users get $HOME/.gitconfig when\nrunning \"config --global\" to write for the first time, or users who\nhave been using Git from olden days already have $HOME/.gitconfig,\nand no write goes to xdg world, so again the read side attempting to\nread from there does not matter, either.\n\nPerhaps a doc update needs to clarify these.\n\nThanks.\n"}]}