Who is .cargo/config.toml meant for?

[SamB]

https://doc.rust-lang.org/cargo/reference/overriding-dependencies.html#paths-overrides suggests that cargo/config.toml isn't expected to be included in version control (I mean, why would editing one verion-controlled file be better than editing another?), but I don't see anything like that actually specified on https://doc.rust-lang.org/cargo/reference/config.html.

It was hoping to see something along the lines of ".cargo/config.toml is intended for local configuration and it's best if you can avoid adding one to version control" , or perhaps an additonal file for user-specific config, in the style of https://learn.microsoft.com/en-us/visualstudio/msbuild/customize-your-local-build?view=vs-2022#user-file, to use for settings that are specific to the user, their machine, or what they are tinkering with at the moment.

If .cargo/config.toml is actually meant to be shared in version control, then I suppose this is a feature request to add a .cargo/config.local.toml or .cargo/config.user.toml to the hierarchy before each .cargo/config.toml (except $CARGO_HOME/config.toml, which is clearly supposed to be user-specific already).

Otherwise, this is a docs bug.

[epage]

Whether the file is checked in or not is project dependent. Manifests (Cargo.toml) are for static, project configuration. Configuration (.cargo/config.toml, --config, CARGO_*) is for transient or environmental configuration. We have #12738 for finding ways to migrate project configuration in environmental config into manifests which would hopefully reduce the use of people committing their .cargo/config.toml files.

Potentially related to your specific idea, #7723 proposes ways to have additional config files. If we had glob support, then no change would be needed for a user one. I think @weihanglo previously had use cases for sometimes-there-sometimes-not config files and they might have other ideas in that direction.

[weihanglo]

If .cargo/config.toml is actually meant to be shared in version control, then I suppose this is a feature request to add a .cargo/config.local.toml or .cargo/config.user.toml

The idea sounds pretty much like a use case of optionality of the config-include unstable feature, which can provide the flexibility without enforcing a convention. (A convention could be added if wished though, like .cargo/conf.d/ mentioned in that thread).

but I don't see anything like that actually specified on https://doc.rust-lang.org/cargo/reference/config.html.

Like epage has said, it's pretty project dependent. The doc of the config has mentioned this:

"With this structure, you can specify configuration per-package, and even possibly check it into version control. You can also specify personal defaults with a configuration file in your home directory."

I'd like to understand what you're looking for in the documentation. Could you provide some suggestions about how to make the doc clearer?