NuGet Docs: nuget.config locations on linux

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

Start with the NuGet documentation section on config file locations and uses, then compare it with the linked NuGetEnvironment.cs and Settings.cs references. Done means the documentation accurately explains the location algorithm, environment-variable fallback, filename casing, NuGetDefaults.Config, and recommended versus legacy locations without unresolved claims.