Skip to content

Commit 26b7725

Browse files
committed
doc(unstable): merge precedence of -Zconfig-include
1 parent 33b0a24 commit 26b7725

File tree

1 file changed

+18
-15
lines changed

1 file changed

+18
-15
lines changed

src/doc/src/reference/unstable.md

Lines changed: 18 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -450,27 +450,30 @@ cargo check --keep-going -Z unstable-options
450450
### config-include
451451
* Tracking Issue: [#7723](https://github.com/rust-lang/cargo/issues/7723)
452452

453+
This feature requires the `-Zconfig-include` command-line option.
454+
453455
The `include` key in a config file can be used to load another config file. It
454-
takes a string for a path to another file relative to the config file, or a
455-
list of strings. It requires the `-Zconfig-include` command-line option.
456+
takes a string for a path to another file relative to the config file, or an
457+
array of config file paths. Only path ending with `.toml` is accepted.
456458

457459
```toml
458-
# .cargo/config
459-
include = '../../some-common-config.toml'
460-
```
461-
462-
The config values are first loaded from the include path, and then the config
463-
file's own values are merged on top of it.
460+
# a path ending with `.toml`
461+
include = "path/to/mordor.toml"
464462

465-
This can be paired with [config-cli](#config-cli) to specify a file to load
466-
from the command-line. Pass a path to a config file as the argument to
467-
`--config`:
468-
469-
```console
470-
cargo +nightly -Zunstable-options -Zconfig-include --config somefile.toml build
463+
# or an array of paths
464+
include = ["frodo.toml", "samwise.toml"]
471465
```
472466

473-
CLI paths are relative to the current working directory.
467+
Unlike other config values, the merge behavior of the `include` key is
468+
different. When a config file contains an `include` key:
469+
470+
1. The config values are first loaded from the `include` path.
471+
* If the value of the `include` key is an array of paths, the config values
472+
are loaded and merged from left to right for each path.
473+
* Recurse this step if the config values from the `include` path also
474+
contain an `include` key.
475+
2. Then, the config file's own values are merged on top of the config
476+
from the `include` path.
474477

475478
### target-applies-to-host
476479
* Original Pull Request: [#9322](https://github.com/rust-lang/cargo/pull/9322)

0 commit comments

Comments
 (0)