Rast1234
commented
3 days ago TL;DR summary: please investigate exact actual algorithm on how nuget-related tooling looks for configs, and describe it clearly in the docs. what variables are in play here? what paths on what OS are considered? in what order? what locations/vars are recommended, not recommended/deprecated? what would be best practice to set up, say, in containers or other scenarios?
it's difficult to figure out from source code and not miss something. it really is, i tried. also an outside contributor has no idea what's actually recommended, what's deprecated and kept for compatibility reasons
current docs have phrases like (varies by tooling) and on linux, previous location was ... which are confusing
NuGet Product Used
Other/NA
Product Version
N/A
Worked before?
No response
Impact
None
Repro Steps & Context
Ported from NuGet Docs, where we are closing issues. Opener: Rast1234
NuGet Product(s) Involved dotnet.exe
The Elevator Pitch From the docs it's unclear where dotnet add, dotnet nuget, etc look for configs:
$XDG_DATA_HOME (typically ~/.local/share or /usr/local/share, depending on OS distribution)
In my case, this variable is not set. I wanted to add a global configuration for my docker image and tried these options:
location: /usr/local/share, /etc/opt, / filename: NuGet.Config, NuGetDefaults.Config, nuget.config The only working solution turned out to be /nuget.config.
How docs can be improved in this regard:
describe exact algorithm used by tooling for locating configs if $XDG_DATA_HOME is unset, what is the fallback? it can't be distro-specific, it's somewhere in nuget source code clarify use case of NuGetDefaults.Config clarify if nuget looks for case-sensitive config names or not: NuGet.Config vs nuget.config describe recommended and legacy locations/filenames. "On Linux, this previous location was /etc/opt" is not clear Additional Context and Details No response
COMMENTS from @Rast1234 Thanks for looking at this ticket. I don't think PR from any external contributor is really possible here: in order to make a PR, one would have to dig into previous, current and upcoming versions of nuget and dotnet nuget cli to figure out developer intentions. Some things are not possible to understand from code, eg. what's going to be depreacted and what is the most recommended mechanism the team is currently betting on...
COMMENTS from @nkolev92 @Rast1234
@heng-liu recently updated the doc: https://learn.microsoft.com/en-us/nuget/consume-packages/configuring-nuget-behavior#config-file-locations-and-uses
I went through the questions and spent a minute or 2 where appropriate to help out the person changing the doc and maybe help answer some questions for you in the meantime.
describe exact algorithm used by tooling for locating configs I think https://learn.microsoft.com/en-us/nuget/consume-packages/configuring-nuget-behavior#how-settings-are-applied covers that.
if $XDG_DATA_HOME is unset, what is the fallback? it can't be distro-specific, it's somewhere in nuget source code
The backup is Home, https://github.com/NuGet/NuGet.Client/blob/741f7d55477ebd3e2201a5d9e6a030daa25ec5f2/src/NuGet.Core/NuGet.Common/PathUtil/NuGetEnvironment.cs#L223. https://github.com/NuGet/NuGet.Client/blob/741f7d55477ebd3e2201a5d9e6a030daa25ec5f2/src/NuGet.Core/NuGet.Common/PathUtil/NuGetEnvironment.cs#L284-L305. Basically looks at the HOME variable.
clarify use case of NuGetDefaults.Config
It's to add non-removable sources. I don't think this is something we recommend folks use much, but deeper analysis is needed here.
clarify if nuget looks for case-sensitive config names or not: NuGet.Config vs nuget.config
It matters on case sensitive FS. nuget.config, NuGet.config and NuGet.Config are all respected in that order. https://github.com/NuGet/NuGet.Client/blob/741f7d55477ebd3e2201a5d9e6a030daa25ec5f2/src/NuGet.Core/NuGet.Configuration/Settings/Settings.cs#L34-L36
describe recommended and legacy locations/filenames. "On Linux, this previous location was /etc/opt" is not clear
I think /etc/opt is not used anymore, so it's not recommended as a machine wide config location.
COMMENTS from @Rast1234 i'm not sure what changed in docs but it looks better, great!
NuGetEnvironment.cs is interesting. looks like a approached my task with wrong mindset:
i expected tooling to look in some predefined specific place for a global, user-independent config if no user/project configs exist, like most linux tools place their global settings in /etc/something/nuget.config. i see this is not the case as it tries really hard to use one of env variables. i think even root always has at least $HOME that's why GetValueOrThrowMissingEnvVar doesn't throw, but i'm not sure this assumption is 100% valid. especially in containers... the config which happens to work for me, /nuget.config, works because tooling looks up the directory tree until it finds anything? and back to docs:
~/.local/share or /usr/local/share will be used (varies by OS distribution)
why? i only see Path.Combine(_getHome.Value, ".local", "share"); in source code. how can local (without dot) end up in here?
On Linux, this previous location was /etc/opt
i see a fallback to /etc/opt in a branch related to CommonApplicationData enum value. since docs say previous (version?), is branch effectively dead?
COMMENTS from @nkolev92 why? i only see Path.Combine(_getHome.Value, ".local", "share"); in source code. how can local (without dot) end up in here?
Might be something that true at some point but not now? Not sure, requires deeper analysis.
Yeah, I think the /etc/opt on is probably not reachable anymore.
COMMENTS from @Rast1234 issue is still relevant. please make sure docs are up to date with actual implementation and without hard to verify statements like "on linux, previous location was ..." with no clear meaning
Verbose Logs
No response