Skip to content

Commit cf7b53a

Browse files
committed
docs(config-include): emphasize inline table syntax
Discussed in 2025-11-25 t-cargo meeting. We prefer inline tables over array of tables for `include`. * `include` is special and should appear early in config files, before other configuration keys * Array-of-tables syntax allows interleaving with other config, which creates confusion about merge order and precedence * Inline tables keep all `include` declarations together at the top, making the load order and override behavior clearer
1 parent b658039 commit cf7b53a

File tree

1 file changed

+15
-15
lines changed

1 file changed

+15
-15
lines changed

src/doc/src/reference/unstable.md

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -662,8 +662,9 @@ rustflags = ["-W", "unsafe-code"]
662662

663663
#### `include`
664664

665-
* Type: array of strings, or array of tables
665+
* Type: array of strings or tables
666666
* Default: none
667+
* Environment: not supported
667668

668669
Loads additional config files. Paths are relative to the config file that
669670
includes them. Only paths ending with `.toml` are accepted.
@@ -672,25 +673,24 @@ Supports the following formats:
672673

673674
```toml
674675
# array of paths
675-
include = ["frodo.toml", "samwise.toml"]
676-
677-
# inline tables
678676
include = [
679-
"simple.toml",
680-
{ path = "optional.toml", optional = true }
677+
"frodo.toml",
678+
"samwise.toml",
681679
]
682680

683-
# array of tables
684-
[[include]]
685-
path = "required.toml"
686-
687-
[[include]]
688-
path = "optional.toml"
689-
optional = true
681+
# inline tables for more control
682+
include = [
683+
{ path = "required.toml" },
684+
{ path = "optional.toml", optional = true },
685+
]
690686
```
691687

692-
When using table syntax (inline tables or array of tables), the following
693-
fields are supported:
688+
> **Note:** For better readability and to avoid confusion, it is recommended to:
689+
> - Place `include` at the top of the configuration file
690+
> - Put one include per line for clearer version control diffs
691+
> - Use inline table syntax when optional includes are needed
692+
693+
When using table syntax, the following fields are supported:
694694

695695
* `path` (string, required): Path to the config file to include.
696696
* `optional` (boolean, default: false): If `true`, missing files are silently

0 commit comments

Comments
 (0)