On 2018-09-24 03:24 PM, Philip Oakley wrote: > Rather than attaching the problem with code, I decided to simply update > the config file documentation. > > As the userbase expands the documentation will need to be more comprehensive > about exclusions and omissions, along with better highlighting for core > areas. > > I would be useful if Stas could comment on whether these changes would > have assisted in debugging the faulty config file.
Thank you for writing this doc patch, Philip. The documentation improvement would be most useful in conjunction with a an improved debugging/tracing facility. So that a user can see what git is seeing. Once a user sees that their configuration is broken then they can peruse the improved documentation to find why it is broken. Without the debugging ability, the docs would help but it'll be a much longer journey, since words like: "Single quotes are not special and form part of the variable's value." aren't necessarily going to stand out as an indicator of a potential problem, when you won't think twice that quotes could even be a suspect, even though the docs say so explicitly. A trace saying: "./.git/'.gitconfig'" is not found would speak volumes and be self-documenting. In lieu of that, the docs would be need to have more examples. Here are the potential expansions to the patch you shared: 1. "Single quotes are not special and form part of the variable's value. For example, if the configuration includes: include = '.gitconfig' then git will look for "'.gitconfig'", single quotes included. Also note that it'll look for the file relative to "REPO/.git/", hence it'll look for "REPO/.git/'.gitconfig'", which is most likely incorrect, since you can't check in files under "REPO/.git/". The correct configuration for including "REPO/.gitconfig" is: include = ../.gitconfig 2. Same with: "Both the `include` and `includeIf` sections implicitly apply an 'if found' condition to the given path names." To a user this would be a difficult statement to make sense of. An example would fix that: "Both the `include` and `includeIf` sections implicitly apply an 'if found' condition to the given path names. For example, if the configuration includes: include = ../.gitconfig and git finds "REPO/.gitconfig", it will include its configuration. If git can't find it, it will silently ignore this include statement until this file appears. It has been designed this way to allow for optional user-specific configuration facilities." Thank you. -- ________________________________________________ Stas Bekman <'))))>< <'))))>< https://stasosphere.com https://chestofbooks.com https://experientialsexlab.com https://stason.org https://stasosphere.com/experience-life/my-books
