feat: stabilize -Zconfig-include

# 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: rust-lang#7723

### What is stabilized

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

**Supported syntax:**

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

**Key behaviors:**

- Paths are relative to the including config file and must end with `.toml`
- 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"`
* Conditional include: conditions like gitconfig's `includeIf`
* Variable substitution and template: placeholders like `{CONFIG_DIR}`
  or `{CARGO_HOME}`
* Implicit-include: like `.cargo/config.user.toml` or
  `.cargo/config.d` for config fragments

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** (rust-lang#12298, 2023-06-21)

The team decided 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** (rust-lang#16174, 2025-10-30)

The feature started with simple string/array syntax. The team debated
and decided to add table syntax before stabilization to allow future
extensions.

**4. Optional includes by default vs. explicit** (rust-lang#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 `.toml` file extension requirement
6. The `path` and `optional` fields in table syntax

**This does NOT prevent**:

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

The `[[include]]` table syntax could optionally have a field to enable
the future extensions above. For example,

```toml
[[include]]
path = "path/config/*.toml" glob = true

[[include]]
path = "path/*/config.toml" if = "<some-condition>"

[[include]]
path = "path/*/config.toml" templatized = true
```

**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 precendence if people already
include those paths.

## 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.

- **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.
- **Per-project profile overrides**: 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
  `.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

### Known limitations

Issue rust-lang#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 (rust-lang#6699)
- 2019-12-19: initial implementation (rust-lang#7649)
- 2023-06-21: file extension restriction added (rust-lang#12298)
- 2025-10-30: table syntax support added (rust-lang#16174)
- 2025-10-31: optional field support added (rust-lang#16180)

## 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 rust-lang#7723 (not going to tag each of them)

Author: weihanglo

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"),
@@ -978,6 +977,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>
@@ -1362,6 +1363,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:
@@ -1376,7 +1378,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

@@ -186,10 +186,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,
@@ -1138,19 +1136,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
@@ -1277,9 +1263,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(())
         })
@@ -1350,11 +1334,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,
@@ -1406,10 +1388,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

@@ -828,6 +828,57 @@ without pipelining.
 Specifies a custom user-agent header to use. The default if not specified is a
 string that includes Cargo's version.
 
+### `include`
+
+* Type: string, array of strings, or array of tables
+* Default: none
+* Environment: not supported
+
+Loads additional config files. Paths are relative to the config file that
+includes them. Only paths ending with `.toml` are accepted.
+
+Supports the following formats:
+
+```toml
+# single path
+include = "path/to/mordor.toml"
+
+# array of paths
+include = ["frodo.toml", "samwise.toml"]
+
+# inline tables
+include = [
+    "simple.toml",
+    { path = "optional.toml", optional = true }
+]
+
+# array of tables
+[[include]]
+path = "required.toml"
+
+[[include]]
+path = "optional.toml"
+optional = true
+```
+
+When using table syntax (inline tables or array of tables), 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` follows a precedence order
+where later values take precedence over earlier ones:
+
+1. Config values are first loaded from the `include` path.
+    * If `include` is an array,
+      config values are loaded and merged from left to right for each path 
+      with later values taking precedence.
+    * 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.
+
 ### `[install]`
 
 The `[install]` table defines defaults for the [`cargo install`] command.

src/doc/src/reference/unstable.md

@@ -119,7 +119,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
@@ -636,77 +635,9 @@ 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
 
-#### `include`
-
-* Type: string, array of strings, or array of tables
-* Default: none
-
-Loads additional config files. Paths are relative to the config file that
-includes them. Only paths ending with `.toml` are accepted.
-
-Supports the following formats:
-
-```toml
-# single path
-include = "path/to/mordor.toml"
-
-# array of paths
-include = ["frodo.toml", "samwise.toml"]
-
-# inline tables
-include = [
-    "simple.toml",
-    { path = "optional.toml", optional = true }
-]
-
-# array of tables
-[[include]]
-path = "required.toml"
-
-[[include]]
-path = "optional.toml"
-optional = true
-```
-
-When using table syntax (inline tables or array of tables), 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` path.
-    * If `include` is an array, config values are loaded and merged from left
-      to right for each path.
-    * 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.
-
 ## 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)
@@ -2327,3 +2258,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.