Document that cargo --config <filename> has unintuitive behavior for config-relative paths

[sunshowers]

Problem

Hi there!

I'm currently looking at configs defined by filenames, and it looks like cargo --config <filename> defines config-relative paths at one level above the config.toml file, rather than at the same level as the config.toml file.

Steps

For example, if foo.toml is created at the root of the workspace:

[build]
target-dir = "from-foo-toml"

then when you run cargo build --config foo.toml, then "from-foo-toml" is created one level above

While this behavior makes sense for files in .cargo, this is extremely surprising behavior for files defined over the command-line. I actually think it is OK to do this, but I didn't see any documentation regarding this on https://doc.rust-lang.org/cargo/reference/config.html.

Possible Solution(s)

Document this on https://doc.rust-lang.org/cargo/reference/config.html and recommend that Cargo config files be created in a directory like .cargo/foo.toml, not foo.toml. (A change to this behavior would be a breaking change, so I don't think that's what should happen.)

Notes

No response

Version

% cargo version --verbose
cargo 1.63.0 (fd9c4297c 2022-07-01)
release: 1.63.0
commit-hash: fd9c4297ccbee36d39e9a79067edab0b614edb5a
commit-date: 2022-07-01
host: x86_64-unknown-linux-gnu
libgit2: 1.4.2 (sys:0.14.2 vendored)
libcurl: 7.83.1-DEV (sys:0.4.55+curl-7.83.1 vendored ssl:OpenSSL/1.1.1n)
os: Pop!_OS 22.04 (jammy) [64-bit]

[ehuss]

Hm, that is a little surprising. I don't recall considering this case.

I actually think it is OK to do this

Can you say more about why you think it is OK?

I'm wondering is it feasible to only do this "parent directory" thing if it is in a .cargo directory?
It might be a little strange to be inconsistent with .cargo, though.

[sunshowers]

Can you say more about why you think it is OK?

It is not my ideal behavior, but I think it is fine:

• This behavior is shipped, and it isn't worth the breaking change.
• It's also relatively easy to explain as maintaining consistency with .cargo/config.toml.
• The workaround (that I think should be suggested in the documentation) is fine: just define your own config files one level down, in e.g. a .cargo or .config directory.