feat: stabilize -Zconfig-include (#16284)

FCP:
#16284 (comment)

# Stabilization report

## Summary

The `include` key in Cargo configuration files allows loading additional
config files, enabling better organization, sharing, and management of
Cargo configurations across projects and environments.

This feature has been available under the `-Zconfig-include` flag since
2019 (Cargo 1.42) and has seen real-world usage.

The stabilization includes support for multiple syntax forms and the
`optional` field, which were added in October 2025 based on user
feedback.

Tracking issue: #7723

### What is stabilized

The `include` configuration key allows loading additional config files.

**Supported syntax:**

- Array: `include = ["a.toml", "b.toml"]`
- Inline tables (preferred): `include = [{ path = "optional.toml",
optional = true }]`
- Array of tables (not preferred): `[[include]]` with `path` and
`optional` fields

**Key behaviors:**

- Paths are relative to the including config file and must end with
`.toml`
- Glob syntax and templated paths (with `{}` braces} are disallowed in
paths.
- Merge follows precedence order: included files (left-to-right) →
parent config
- `optional = true` silently skips missing files (default: `false`)
- Cyclic includes are detected and reported as errors

See the config documentation for complete details and examples.

### Future extensions

Several potential extensions are not implemented at this time:

* Glob patterns: like `include = "config.d/*.toml"` —
#9306
* Conditional include: conditions like gitconfig's `includeIf` —
#7723 (comment)
* Variable substitution and template: placeholders like `{CONFIG_DIR}`
or `{CARGO_HOME}` — #15769
* Implicit-include: like `.cargo/config.user.toml` or `.cargo/config.d`
for config fragments — [#t-cargo > Built-in
`.cargo/config.local.toml`for non-committed
config](https://rust-lang.zulipchat.com/#narrow/channel/246057-t-cargo/topic/Built-in.20.60.2Ecargo.2Fconfig.2Elocal.2Etoml.60for.20non-committed.20config/with/558705263)
* Environment variable include support: like
`CARGO_INCLUDE=path/to/config.toml` —
#6728

See "Doors closed" for more.

## Design

### Key evolution

All significant changes occurred during the unstable period (2019-2024)
and were approved by the Cargo team.

**1. File naming restrictions** (#12298, 2023-06-21)
(#16285, 2025-11-21)

The syntax has a couple restrictions:

* Path must end with `.toml` extension
* Path must not contain glob syntax or template braces

The team considered the restriction was reasonable. The restriction
applies to config file discovery but not to `--config` CLI arguments
which has already been stabilized.

**2. Loading precedence for arrays**

Config values in array elements are loaded left to right, with later
values taking precedence. The parent config file's values always take
precedence over included configs. This provides intuitive layering
behavior.

**3. Syntax complexity** (#16174, 2025-10-30)
(#16298 2025-11-25)

The feature started with simple string/array syntax. The team debated
and decided to add table syntax, and remove single string shorthand
before stabilization to allow future extensions and reduce complexity.

**4. Optional includes by default vs. explicit** (#16180,
2025-10-31)

Some users wanted missing files to be silently ignored by default for
local customization workflows. Others wanted errors to catch typos. The
team chose to error by default but added an explicit `optional = true`
field, requiring users to be intentional about optional behavior.

### Nightly extensions

No nightly-only extensions remain. The feature is fully stabilized as
implemented.

### Doors closed

**This stabilization commits to**:

1. Supporting the `include` key in Cargo configuration
2. Relative path resolution from the including config file
3. Left-to-right merge order for arrays
4. Parent config taking precedence over includes
5. The `path` and `optional` fields in table syntax

**This does NOT prevent**:

- Adding glob/wildcard support
- Adding conditional includes
- Adding variable substitution and template

**This MAY prevent**:

* Adding new implicit-include for user local config or config fragments
directory

As we are going to allow all file paths. Adding any implicit includes
after stabilization might break the merge precedence if people already
include those paths.

The only possible way to support it is accepting `.cargo/config.toml/`
as a directory and treat it as a config fragments directory.
`.cargo/config.toml` (and the legacy `cargo/config/`) is the only path
Cargo reserves.

## Feedback

### Call for testing

No formal "call for testing" was issued, but the feature has been
available under `-Zconfig-include` since Cargo 1.42 (2019) and has seen
real-world adoption.

### Use cases

Users reported use cases:

- **Sharing flags and environment conditionally**: [Tock
OS](https://github.com/tock/tock),
[esp-hal](https://github.com/esp-rs/esp-hal), rtos, and some FFI
libraries use it for preset management across multiple board
configurations for different hardware platforms, architectures, and
downstream crates. A board's config (used by entering its directory) is
defined by pulling from role-based config slices.

- **Beyond hierarchical discovery**: Some use cases require explicit
includes because configs need to be loaded from locations outside the
hierarchical path, or need to be conditionally included based on
per-package or per-machine requirements that can't rely on the directory
structure alone. This usually happens in a meta build system that
generates configs, especially when setting `CARGO_HOME` to a different
location off the hierarchical path.

- **User and project configuration**: Projects with checked-in configs
(e.g., `[profile.test] debug = false` for CI) can allow developers to
override settings locally without modifying the checked-in file.
Developers can include an optional `.cargo/local-config.toml` without
using git workarounds like `update-index --assume-unchanged`.

### Coverage

Test coverage is comprehensive in `tests/testsuite/config_include.rs`:

- Merge behavior: left-to-right order, hierarchy interaction
- Path handling: relative paths, different directory structures
- Cycle detection: Direct and indirect cycles
- Error cases: missing files, invalid paths, wrong extensions, missing
required fields
- Syntax variations: string, array, inline table, array of tables
- Optional includes: missing optional files, mixed optional/required
- CLI integration: includes from `--config` arguments
- Forward compatibility: unknown table fields, glob/template syntax
restrictions

### Known limitations

Issue #15769 tracks inconsistent relative path behavior
between `include` paths (relative to config file) and other config paths
like `build.target-dir` (relative to cargo root). This is considered a
known limitation and confusion that can be addressed separately and
doesn't block stabilization.

No other known limitations blocking stabilization.

## History

- 2019-02-25: Original proposal (#6699)
- 2019-12-19: initial implementation (#7649)
- 2023-06-21: file extension restriction added (#12298)
- 2025-10-30: table syntax support added (#16174)
- 2025-10-31: optional field support added (#16180)
- 2025-11-21: glob and template syntax restriction added
(#16285)
- 2025-11-25: single string shorthand syntax removed
(#16298)

## Acknowledgments

Contributors to this feature:

- `@ehuss` for initial implementation and design
- `@weihanglo` for extra syntax support and enhancement
- `@rust-lang/cargo` team for the support, review and feedback
- All users providing feedback in #7723

Author: epage

src/cargo/core/features.rs

@@ -856,7 +856,6 @@ unstable_cli_options!(
     cargo_lints: bool = ("Enable the `[lints.cargo]` table"),
     checksum_freshness: bool = ("Use a checksum to determine if output is fresh rather than filesystem mtime"),
     codegen_backend: bool = ("Enable the `codegen-backend` option in profiles in .cargo/config.toml file"),
-    config_include: bool = ("Enable the `include` key in config files"),
     direct_minimal_versions: bool = ("Resolve minimal dependency versions instead of maximum (direct dependencies only)"),
     dual_proc_macros: bool = ("Build proc-macros for both the host and the target"),
     feature_unification: bool = ("Enable new feature unification modes in workspaces"),
@@ -979,6 +978,8 @@ const STABILIZED_PACKAGE_WORKSPACE: &str =
 
 const STABILIZED_BUILD_DIR: &str = "build.build-dir is now always enabled.";
 
+const STABILIZED_CONFIG_INCLUDE: &str = "The `include` config key is now always available";
+
 fn deserialize_comma_separated_list<'de, D>(
     deserializer: D,
 ) -> Result<Option<Vec<String>>, D::Error>
@@ -1363,6 +1364,7 @@ impl CliUnstable {
             "doctest-xcompile" => stabilized_warn(k, "1.89", STABILIZED_DOCTEST_XCOMPILE),
             "package-workspace" => stabilized_warn(k, "1.89", STABILIZED_PACKAGE_WORKSPACE),
             "build-dir" => stabilized_warn(k, "1.91", STABILIZED_BUILD_DIR),
+            "config-include" => stabilized_warn(k, "1.93", STABILIZED_CONFIG_INCLUDE),
 
             // Unstable features
             // Sorted alphabetically:
@@ -1377,7 +1379,6 @@ impl CliUnstable {
             "build-std-features" => self.build_std_features = Some(parse_list(v)),
             "cargo-lints" => self.cargo_lints = parse_empty(k, v)?,
             "codegen-backend" => self.codegen_backend = parse_empty(k, v)?,
-            "config-include" => self.config_include = parse_empty(k, v)?,
             "direct-minimal-versions" => self.direct_minimal_versions = parse_empty(k, v)?,
             "dual-proc-macros" => self.dual_proc_macros = parse_empty(k, v)?,
             "feature-unification" => self.feature_unification = parse_empty(k, v)?,

src/cargo/util/context/mod.rs

@@ -187,10 +187,8 @@ pub const TOP_LEVEL_CONFIG_KEYS: &[&str] = &[
 enum WhyLoad {
     /// Loaded due to a request from the global cli arg `--config`
     ///
-    /// Indirect configs loaded via [`config-include`] are also seen as from cli args,
+    /// Indirect configs loaded via [`ConfigInclude`] are also seen as from cli args,
     /// if the initial config is being loaded from cli.
-    ///
-    /// [`config-include`]: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#config-include
     Cli,
     /// Loaded due to config file discovery.
     FileDiscovery,
@@ -1139,19 +1137,7 @@ impl GlobalContext {
             self.merge_cli_args()?;
         }
 
-        // Load the unstable flags from config file here first, as the config
-        // file itself may enable inclusion of other configs. In that case, we
-        // want to re-load configs with includes enabled:
         self.load_unstable_flags_from_config()?;
-        if self.unstable_flags.config_include {
-            // If the config was already loaded (like when fetching the
-            // `[alias]` table), it was loaded with includes disabled because
-            // the `unstable_flags` hadn't been set up, yet. Any values
-            // fetched before this step will not process includes, but that
-            // should be fine (`[alias]` is one of the only things loaded
-            // before configure). This can be removed when stabilized.
-            self.reload_rooted_at(self.cwd.clone())?;
-        }
 
         // Ignore errors in the configuration files. We don't want basic
         // commands like `cargo version` to error out due to config file
@@ -1278,9 +1264,7 @@ impl GlobalContext {
         let home = self.home_path.clone().into_path_unlocked();
         self.walk_tree(&self.cwd, &home, |path| {
             let mut cv = self._load_file(path, &mut seen, false, WhyLoad::FileDiscovery)?;
-            if self.cli_unstable().config_include {
-                self.load_unmerged_include(&mut cv, &mut seen, &mut result)?;
-            }
+            self.load_unmerged_include(&mut cv, &mut seen, &mut result)?;
             result.push(cv);
             Ok(())
         })
@@ -1351,11 +1335,9 @@ impl GlobalContext {
     ///
     /// This is actual implementation of loading a config value from a path.
     ///
-    /// * `includes` determines whether to load configs from [`config-include`].
+    /// * `includes` determines whether to load configs from [`ConfigInclude`].
     /// * `seen` is used to check for cyclic includes.
     /// * `why_load` tells why a config is being loaded.
-    ///
-    /// [`config-include`]: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#config-include
     fn _load_file(
         &self,
         path: &Path,
@@ -1407,10 +1389,7 @@ impl GlobalContext {
     ) -> CargoResult<CV> {
         // Get the list of files to load.
         let includes = self.include_paths(&mut value, true)?;
-        // Check unstable.
-        if !self.cli_unstable().config_include {
-            return Ok(value);
-        }
+
         // Accumulate all values here.
         let mut root = CV::Table(HashMap::new(), value.definition().clone());
         for include in includes {

src/doc/src/reference/config.md

@@ -269,6 +269,58 @@ cargo --config "target.'cfg(all(target_arch = \"arm\", target_os = \"none\"))'.r
 cargo --config profile.dev.package.image.opt-level=3 …
 ```
 
+## Including extra configuration files
+
+Configuration can include other configuration files using the top-level `include` key.
+This allows sharing configuration across multiple projects
+or splitting complex configurations into multiple files.
+
+### `include`
+
+* Type: array of strings or tables
+* Default: none
+* Environment: not supported
+
+Loads additional configuration files.
+Paths are relative to the configuration file that includes them.
+Only paths ending with `.toml` are accepted.
+
+Supports the following formats:
+
+```toml
+# array of paths
+include = [
+    "frodo.toml",
+    "samwise.toml",
+]
+
+# inline tables for more control
+include = [
+    { path = "required.toml" },
+    { path = "optional.toml", optional = true },
+]
+```
+
+> **Note:** For better readability and to avoid confusion, it is recommended to:
+> - Place `include` at the top of the configuration file
+> - Put one include per line for clearer version control diffs
+> - Use inline table syntax when optional includes are needed
+
+When using table syntax, the following fields are supported:
+
+* `path` (string, required): Path to the config file to include.
+* `optional` (boolean, default: false): If `true`, missing files are silently
+  skipped instead of causing an error.
+
+The merge behavior of `include` is different from other config values:
+
+1. Config values are first loaded from the `include` paths.
+    * Included files are loaded left to right,
+      with values from later files taking precedence over earlier ones.
+    * This step recurses if included config files also contain `include` keys.
+2. Then, the config file's own values are merged on top of the included config,
+   taking highest precedence.
+
 ## Config-relative paths
 
 Paths in config files may be absolute, relative, or a bare name without any path separators.

src/doc/src/reference/unstable.md

@@ -120,7 +120,6 @@ Each new feature described below should explain how to use it.
     * [Build analysis](#build-analysis) --- Record and persist detailed build metrics across runs, with new commands to query past builds.
     * [`rustc-unicode`](#rustc-unicode) --- Enables `rustc`'s unicode error format in Cargo's error messages 
 * Configuration
-    * [config-include](#config-include) --- Adds the ability for config files to include other files.
     * [`cargo config`](#cargo-config) --- Adds a new subcommand for viewing config files.
 * Registries
     * [publish-timeout](#publish-timeout) --- Controls the timeout between uploading the crate and being available in the index
@@ -637,85 +636,6 @@ like to stabilize it somehow!
 
 [rust-lang/rust#64158]: https://github.com/rust-lang/rust/pull/64158
 
-## config-include
-* Tracking Issue: [#7723](https://github.com/rust-lang/cargo/issues/7723)
-
-This feature requires the `-Zconfig-include` command-line option.
-
-The `include` key in a config file can be used to load another config file.
-For example:
-
-```toml
-# .cargo/config.toml
-include = ["other-config.toml"]
-
-[build]
-jobs = 4
-```
-
-```toml
-# .cargo/other-config.toml
-[build]
-rustflags = ["-W", "unsafe-code"]
-```
-
-### Documentation updates
-
-> put this after `## Command-line overrides` before `## Config-relative paths`
-> to emphasize its special nature than other config keys.
-
-#### Including extra configuration files
-
-Configuration can include other configuration files using the top-level `include` key.
-This allows sharing configuration across multiple projects
-or splitting complex configurations into multiple files.
-
-##### `include`
-
-* Type: array of strings or tables
-* Default: none
-* Environment: not supported
-
-Loads additional configuration files.
-Paths are relative to the configuration file that includes them.
-Only paths ending with `.toml` are accepted.
-
-Supports the following formats:
-
-```toml
-# array of paths
-include = [
-    "frodo.toml",
-    "samwise.toml",
-]
-
-# inline tables for more control
-include = [
-    { path = "required.toml" },
-    { path = "optional.toml", optional = true },
-]
-```
-
-> **Note:** For better readability and to avoid confusion, it is recommended to:
-> - Place `include` at the top of the configuration file
-> - Put one include per line for clearer version control diffs
-> - Use inline table syntax when optional includes are needed
-
-When using table syntax, the following fields are supported:
-
-* `path` (string, required): Path to the config file to include.
-* `optional` (boolean, default: false): If `true`, missing files are silently
-  skipped instead of causing an error.
-
-The merge behavior of `include` is different from other config values:
-
-1. Config values are first loaded from the `include` paths.
-    * Included files are loaded left to right,
-      with values from later files taking precedence over earlier ones.
-    * This step recurses if included config files also contain `include` keys.
-2. Then, the config file's own values are merged on top of the included config,
-   taking highest precedence.
-
 ## target-applies-to-host
 * Original Pull Request: [#9322](https://github.com/rust-lang/cargo/pull/9322)
 * Tracking Issue: [#9453](https://github.com/rust-lang/cargo/issues/9453)
@@ -2347,3 +2267,9 @@ See the [config documentation](config.md#buildbuild-dir) for information about c
 
 The `--build-plan` argument for the `build` command has been removed in 1.93.0-nightly.
 See <https://github.com/rust-lang/cargo/issues/7614> for the reason for its removal.
+
+## config-include
+
+Support for including extra configuration files via the `include` config key
+has been stabilized in 1.93.0.
+See the [`include` config documentation](config.md#include) for more.