From f7afddf1b3088bbb85a606d879a9fd1a5e5bd557 Mon Sep 17 00:00:00 2001 From: Karol Zwolak Date: Tue, 25 Feb 2025 14:19:05 +0100 Subject: [PATCH 1/9] docs: clarify the editions behavior and it's consequences on formatting --- Configurations.md | 8 +++++--- README.md | 12 +++++++++--- 2 files changed, 14 insertions(+), 6 deletions(-) diff --git a/Configurations.md b/Configurations.md index 8e04ddd325e..f0783f12abd 100644 --- a/Configurations.md +++ b/Configurations.md @@ -537,14 +537,16 @@ Specifies which edition is used by the parser. - **Possible values**: `"2015"`, `"2018"`, `"2021"`, `"2024"` - **Stable**: Yes -Rustfmt is able to pick up the edition used by reading the `Cargo.toml` file if executed -through the Cargo's formatting tool `cargo fmt`. Otherwise, the edition needs to be specified -in your config file: +Starting with the 2024 edition, Rust introduced changes to default formatting. This can lead to inconsistencies between `rustfmt` and `cargo fmt` if the edition is not explicitly configured. This is because `cargo fmt` automatically picks up the edition from `Cargo.toml`, while `rustfmt` defaults to the `2015` edition unless otherwise specified. + +To ensure consistent formatting, it is recommended to specify the edition in a `rustfmt.toml` configuration file. For example: ```toml edition = "2018" ``` +Alternatively, you can use the `--edition` flag when running `rustfmt` directly. + ## `empty_item_single_line` Put empty-body functions and impls on a single line diff --git a/README.md b/README.md index b68a942e463..ffaa5f74fca 100644 --- a/README.md +++ b/README.md @@ -170,9 +170,13 @@ See [GitHub page](https://rust-lang.github.io/rustfmt/) for details. ### Rust's Editions -Rustfmt is able to pick up the edition used by reading the `Cargo.toml` file if -executed through the Cargo's formatting tool `cargo fmt`. Otherwise, the edition -needs to be specified in `rustfmt.toml`, e.g., with `edition = "2018"`. +Starting with the 2024 edition, Rust introduced changes to default formatting. This can lead to inconsistencies between `rustfmt` and `cargo fmt` if the edition is not explicitly configured. This is because `cargo fmt` automatically picks up the edition from `Cargo.toml`, while `rustfmt` defaults to the `2015` edition unless otherwise specified. + +To ensure consistent formatting, it is recommended to specify the edition in a `rustfmt.toml` configuration file. For example: + +```toml +edition = "2024" +``` ## Tips @@ -220,6 +224,8 @@ needs to be specified in `rustfmt.toml`, e.g., with `edition = "2018"`. | checkstyle | emits in a checkstyle format | Yes | | json | emits diffs in a json format | Yes | +* When using `rustfmt` directly in a Cargo project, set the `edition` in `rustfmt.toml` to the same value as in `Cargo.toml` to ensure consistent formatting. For more details, see the [Rust's Editions](#rusts-editions) section. + ## License Rustfmt is distributed under the terms of both the MIT license and the From 15781b2f0aa4b9b6970ec6757d43406f6deaaa3d Mon Sep 17 00:00:00 2001 From: Karol Zwolak Date: Tue, 25 Feb 2025 16:41:12 +0100 Subject: [PATCH 2/9] docs: correct that style_edition dictates formatting settings, not edition --- Configurations.md | 16 ++++++++++++++-- README.md | 22 +++++++++++++++++++--- 2 files changed, 33 insertions(+), 5 deletions(-) diff --git a/Configurations.md b/Configurations.md index f0783f12abd..41f32485b0f 100644 --- a/Configurations.md +++ b/Configurations.md @@ -537,9 +537,10 @@ Specifies which edition is used by the parser. - **Possible values**: `"2015"`, `"2018"`, `"2021"`, `"2024"` - **Stable**: Yes -Starting with the 2024 edition, Rust introduced changes to default formatting. This can lead to inconsistencies between `rustfmt` and `cargo fmt` if the edition is not explicitly configured. This is because `cargo fmt` automatically picks up the edition from `Cargo.toml`, while `rustfmt` defaults to the `2015` edition unless otherwise specified. +The `edition` option determines the Rust language edition used for parsing the code. This is important for syntax compatibility but does not directly control formatting behavior (see [style_edition](#style_edition)). -To ensure consistent formatting, it is recommended to specify the edition in a `rustfmt.toml` configuration file. For example: +When running `cargo fmt`, the `edition` is automatically inferred from the `Cargo.toml` file. However, when running `rustfmt` directly, the `edition` must be explicitly set in the configuration file or via the command line. +For example in your `rustfmt.toml` file: ```toml edition = "2018" @@ -2805,6 +2806,17 @@ Controls the edition of the [Rust Style Guide] to use for formatting ([RFC 3338] - **Possible values**: `"2015"`, `"2018"`, `"2021"`, `"2024"` (unstable variant) - **Stable**: No +This option is inferred from the `edition` if not specified. +Starting with the 2024 edition, Rust introduced changes to default formatting. This can lead to inconsistencies between `rustfmt` and `cargo fmt` if the style edition is not explicitly configured. This is because `cargo fmt` automatically picks up the edition from `Cargo.toml`, while `rustfmt` defaults to the `2015` edition unless otherwise specified. + +To ensure consistent formatting, it is recommended to specify the `edition` or `style_edition` in a `rustfmt.toml` configuration file. For example: + +```toml +style_edition = "2024" +``` + +Alternatively, you can use the `--style-edition` flag when running `rustfmt` directly. + [Rust Style Guide]: https://doc.rust-lang.org/nightly/style-guide/ [RFC 3338]: https://rust-lang.github.io/rfcs/3338-style-evolution.html diff --git a/README.md b/README.md index ffaa5f74fca..d4467b99670 100644 --- a/README.md +++ b/README.md @@ -170,14 +170,30 @@ See [GitHub page](https://rust-lang.github.io/rustfmt/) for details. ### Rust's Editions -Starting with the 2024 edition, Rust introduced changes to default formatting. This can lead to inconsistencies between `rustfmt` and `cargo fmt` if the edition is not explicitly configured. This is because `cargo fmt` automatically picks up the edition from `Cargo.toml`, while `rustfmt` defaults to the `2015` edition unless otherwise specified. +The `edition` option determines the Rust language edition used for parsing the code. This is important for syntax compatibility but does not directly control formatting behavior (see [Style Editions](#style-editions)). +By default, Rustfmt uses the `2015` edition. + +When running `cargo fmt`, the `edition` is automatically inferred from the `Cargo.toml` file. However, when running `rustfmt` directly, the `edition` must be explicitly set in the configuration file or via the command line. -To ensure consistent formatting, it is recommended to specify the edition in a `rustfmt.toml` configuration file. For example: +For example in your `rustfmt.toml` file: ```toml edition = "2024" ``` +### Style Editions + +The option `style_edition` controls the edition of the [Rust Style Guide] to use for formatting ([RFC 3338]) +It is inferred from `edition` if not explicitly set, and defaults to the `2015` edition. + +Starting with the 2024 edition, Rust introduced changes to default formatting. This can lead to inconsistencies between `rustfmt` and `cargo fmt` if the edition is not explicitly configured. This is because `cargo fmt` automatically picks up the edition from `Cargo.toml`, while `rustfmt` defaults to the `2015` edition unless otherwise specified. + +To ensure consistent formatting, it is recommended to specify the `edition` or `style_edition` in a `rustfmt.toml` configuration file. For example: + +```toml +style_edition = "2024" +``` + ## Tips * For things you do not want rustfmt to mangle, use `#[rustfmt::skip]` @@ -224,7 +240,7 @@ edition = "2024" | checkstyle | emits in a checkstyle format | Yes | | json | emits diffs in a json format | Yes | -* When using `rustfmt` directly in a Cargo project, set the `edition` in `rustfmt.toml` to the same value as in `Cargo.toml` to ensure consistent formatting. For more details, see the [Rust's Editions](#rusts-editions) section. +* When using `rustfmt` directly in a Cargo project, set the `style_edition` or `edition` in `rustfmt.toml` to the same value as in `Cargo.toml` to ensure consistent formatting. For more details, see the [Style Editions](#style-editions) and [Rust's Editions](#rusts-editions) sections. ## License From a680d9ac550918559e8e178415e5f0570e9cbc8b Mon Sep 17 00:00:00 2001 From: Karol Zwolak Date: Tue, 25 Feb 2025 18:12:49 +0100 Subject: [PATCH 3/9] docs: fix Rust Style Guide links --- Configurations.md | 2 +- README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Configurations.md b/Configurations.md index 41f32485b0f..5057b427e27 100644 --- a/Configurations.md +++ b/Configurations.md @@ -2800,7 +2800,7 @@ See also [`max_width`](#max_width) and [`use_small_heuristics`](#use_small_heuri ## `style_edition` -Controls the edition of the [Rust Style Guide] to use for formatting ([RFC 3338]) +Controls the edition of the [Rust Style Guide](https://doc.rust-lang.org/nightly/style-guide/editions.html?highlight=editions#rust-style-editions) to use for formatting ([RFC 3338]) - **Default value**: `"2015"` - **Possible values**: `"2015"`, `"2018"`, `"2021"`, `"2024"` (unstable variant) diff --git a/README.md b/README.md index d4467b99670..007ccd8adb5 100644 --- a/README.md +++ b/README.md @@ -183,7 +183,7 @@ edition = "2024" ### Style Editions -The option `style_edition` controls the edition of the [Rust Style Guide] to use for formatting ([RFC 3338]) +The option `style_edition` controls the edition of the [Rust Style Guide](https://doc.rust-lang.org/nightly/style-guide/editions.html?highlight=editions#rust-style-editions) to use for formatting ([RFC 3338](https://rust-lang.github.io/rfcs/3338-style-evolution.html)) It is inferred from `edition` if not explicitly set, and defaults to the `2015` edition. Starting with the 2024 edition, Rust introduced changes to default formatting. This can lead to inconsistencies between `rustfmt` and `cargo fmt` if the edition is not explicitly configured. This is because `cargo fmt` automatically picks up the edition from `Cargo.toml`, while `rustfmt` defaults to the `2015` edition unless otherwise specified. From b4ed076fb2b102914aa56489bcb3b95b7b65449d Mon Sep 17 00:00:00 2001 From: Karol Zwolak Date: Tue, 25 Feb 2025 19:13:53 +0100 Subject: [PATCH 4/9] docs: revert changing link to rust style guide --- Configurations.md | 5 ++++- README.md | 6 +++++- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/Configurations.md b/Configurations.md index 5057b427e27..8b5d2dc35c2 100644 --- a/Configurations.md +++ b/Configurations.md @@ -2800,13 +2800,15 @@ See also [`max_width`](#max_width) and [`use_small_heuristics`](#use_small_heuri ## `style_edition` -Controls the edition of the [Rust Style Guide](https://doc.rust-lang.org/nightly/style-guide/editions.html?highlight=editions#rust-style-editions) to use for formatting ([RFC 3338]) +Controls the edition of the [Rust Style Guide] to use for formatting ([RFC 3338]) - **Default value**: `"2015"` - **Possible values**: `"2015"`, `"2018"`, `"2021"`, `"2024"` (unstable variant) - **Stable**: No This option is inferred from the `edition` if not specified. + +See [Rust Style Editions] for details on style editions. Starting with the 2024 edition, Rust introduced changes to default formatting. This can lead to inconsistencies between `rustfmt` and `cargo fmt` if the style edition is not explicitly configured. This is because `cargo fmt` automatically picks up the edition from `Cargo.toml`, while `rustfmt` defaults to the `2015` edition unless otherwise specified. To ensure consistent formatting, it is recommended to specify the `edition` or `style_edition` in a `rustfmt.toml` configuration file. For example: @@ -2817,6 +2819,7 @@ style_edition = "2024" Alternatively, you can use the `--style-edition` flag when running `rustfmt` directly. +[Rust Style Editions]: https://doc.rust-lang.org/nightly/style-guide/editions.html?highlight=editions#rust-style-editions [Rust Style Guide]: https://doc.rust-lang.org/nightly/style-guide/ [RFC 3338]: https://rust-lang.github.io/rfcs/3338-style-evolution.html diff --git a/README.md b/README.md index 007ccd8adb5..69d2181587d 100644 --- a/README.md +++ b/README.md @@ -183,9 +183,10 @@ edition = "2024" ### Style Editions -The option `style_edition` controls the edition of the [Rust Style Guide](https://doc.rust-lang.org/nightly/style-guide/editions.html?highlight=editions#rust-style-editions) to use for formatting ([RFC 3338](https://rust-lang.github.io/rfcs/3338-style-evolution.html)) +Controls the edition of the [Rust Style Guide] to use for formatting ([RFC 3338]) It is inferred from `edition` if not explicitly set, and defaults to the `2015` edition. +See [Rust Style Editions] for details on style editions. Starting with the 2024 edition, Rust introduced changes to default formatting. This can lead to inconsistencies between `rustfmt` and `cargo fmt` if the edition is not explicitly configured. This is because `cargo fmt` automatically picks up the edition from `Cargo.toml`, while `rustfmt` defaults to the `2015` edition unless otherwise specified. To ensure consistent formatting, it is recommended to specify the `edition` or `style_edition` in a `rustfmt.toml` configuration file. For example: @@ -193,6 +194,9 @@ To ensure consistent formatting, it is recommended to specify the `edition` or ` ```toml style_edition = "2024" ``` +[Rust Style Editions]: https://doc.rust-lang.org/nightly/style-guide/editions.html?highlight=editions#rust-style-editions +[Rust Style Guide]: https://doc.rust-lang.org/nightly/style-guide/ +[RFC 3338]: https://rust-lang.github.io/rfcs/3338-style-evolution.html ## Tips From 4b496112bd6e6eed733027d46d468fbe340b1653 Mon Sep 17 00:00:00 2001 From: Karol Zwolak Date: Tue, 25 Feb 2025 19:18:22 +0100 Subject: [PATCH 5/9] docs: link to edition in style_edition section --- Configurations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Configurations.md b/Configurations.md index 8b5d2dc35c2..eb5ba4c290c 100644 --- a/Configurations.md +++ b/Configurations.md @@ -2806,12 +2806,12 @@ Controls the edition of the [Rust Style Guide] to use for formatting ([RFC 3338] - **Possible values**: `"2015"`, `"2018"`, `"2021"`, `"2024"` (unstable variant) - **Stable**: No -This option is inferred from the `edition` if not specified. +This option is inferred from the [`edition`](#edition) if not specified. See [Rust Style Editions] for details on style editions. Starting with the 2024 edition, Rust introduced changes to default formatting. This can lead to inconsistencies between `rustfmt` and `cargo fmt` if the style edition is not explicitly configured. This is because `cargo fmt` automatically picks up the edition from `Cargo.toml`, while `rustfmt` defaults to the `2015` edition unless otherwise specified. -To ensure consistent formatting, it is recommended to specify the `edition` or `style_edition` in a `rustfmt.toml` configuration file. For example: +To ensure consistent formatting, it is recommended to specify the [`edition`](#edition) or `style_edition` in a `rustfmt.toml` configuration file. For example: ```toml style_edition = "2024" From ecf3b6280ae0f920e26b9cbd8b683f1798a02256 Mon Sep 17 00:00:00 2001 From: Karol Zwolak Date: Thu, 27 Feb 2025 10:49:32 +0100 Subject: [PATCH 6/9] docs: more accurate docs about `editon` and `style_edition` options Co-authored-by: Yacin Tmimi --- Configurations.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Configurations.md b/Configurations.md index eb5ba4c290c..67debec1ddb 100644 --- a/Configurations.md +++ b/Configurations.md @@ -539,7 +539,7 @@ Specifies which edition is used by the parser. The `edition` option determines the Rust language edition used for parsing the code. This is important for syntax compatibility but does not directly control formatting behavior (see [style_edition](#style_edition)). -When running `cargo fmt`, the `edition` is automatically inferred from the `Cargo.toml` file. However, when running `rustfmt` directly, the `edition` must be explicitly set in the configuration file or via the command line. +When running `cargo fmt`, the `edition` is automatically read from the `Cargo.toml` file. However, when running `rustfmt` directly the `edition` defaults to 2015 if not explicitly configured. For consistent parsing between rustfmt and `cargo fmt` you should configure the `edition`. For example in your `rustfmt.toml` file: ```toml @@ -2808,10 +2808,10 @@ Controls the edition of the [Rust Style Guide] to use for formatting ([RFC 3338] This option is inferred from the [`edition`](#edition) if not specified. -See [Rust Style Editions] for details on style editions. -Starting with the 2024 edition, Rust introduced changes to default formatting. This can lead to inconsistencies between `rustfmt` and `cargo fmt` if the style edition is not explicitly configured. This is because `cargo fmt` automatically picks up the edition from `Cargo.toml`, while `rustfmt` defaults to the `2015` edition unless otherwise specified. +See [Rust Style Editions] for details on formatting differences between style editions. +rustfmt has a default style edition of `2015` while `cargo fmt` infers the style edition from the `edition` set in `Cargo.toml`. This can lead to inconsistencies between `rustfmt` and `cargo fmt` if the style edition is not explicitly configured. -To ensure consistent formatting, it is recommended to specify the [`edition`](#edition) or `style_edition` in a `rustfmt.toml` configuration file. For example: +To ensure consistent formatting, it is recommended to specify the `style_edition` in a `rustfmt.toml` configuration file. For example: ```toml style_edition = "2024" From 14f12fbda31291910dd79c4ad6d90fe9d829533e Mon Sep 17 00:00:00 2001 From: Karol Zwolak Date: Thu, 27 Feb 2025 15:23:15 +0100 Subject: [PATCH 7/9] docs: ensure consistency between readme and configuration docs on editions --- README.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 69d2181587d..c0a020410c5 100644 --- a/README.md +++ b/README.md @@ -171,25 +171,22 @@ See [GitHub page](https://rust-lang.github.io/rustfmt/) for details. ### Rust's Editions The `edition` option determines the Rust language edition used for parsing the code. This is important for syntax compatibility but does not directly control formatting behavior (see [Style Editions](#style-editions)). -By default, Rustfmt uses the `2015` edition. - -When running `cargo fmt`, the `edition` is automatically inferred from the `Cargo.toml` file. However, when running `rustfmt` directly, the `edition` must be explicitly set in the configuration file or via the command line. +When running `cargo fmt`, the `edition` is automatically read from the `Cargo.toml` file. However, when running `rustfmt` directly the `edition` defaults to 2015 if not explicitly configured. For consistent parsing between rustfmt and `cargo fmt` you should configure the `edition`. For example in your `rustfmt.toml` file: ```toml -edition = "2024" +edition = "2018" ``` ### Style Editions -Controls the edition of the [Rust Style Guide] to use for formatting ([RFC 3338]) -It is inferred from `edition` if not explicitly set, and defaults to the `2015` edition. +This option is inferred from the [`edition`](#rusts-editions) if not specified. -See [Rust Style Editions] for details on style editions. -Starting with the 2024 edition, Rust introduced changes to default formatting. This can lead to inconsistencies between `rustfmt` and `cargo fmt` if the edition is not explicitly configured. This is because `cargo fmt` automatically picks up the edition from `Cargo.toml`, while `rustfmt` defaults to the `2015` edition unless otherwise specified. +See [Rust Style Editions] for details on formatting differences between style editions. +rustfmt has a default style edition of `2015` while `cargo fmt` infers the style edition from the `edition` set in `Cargo.toml`. This can lead to inconsistencies between `rustfmt` and `cargo fmt` if the style edition is not explicitly configured. -To ensure consistent formatting, it is recommended to specify the `edition` or `style_edition` in a `rustfmt.toml` configuration file. For example: +To ensure consistent formatting, it is recommended to specify the `style_edition` in a `rustfmt.toml` configuration file. For example: ```toml style_edition = "2024" From 4f891656422b41f8647aa20860ae44840fa7fb30 Mon Sep 17 00:00:00 2001 From: Karol Zwolak Date: Thu, 27 Feb 2025 15:32:31 +0100 Subject: [PATCH 8/9] docs: improve tip on edition inconsistency between cargo and rustfmt --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c0a020410c5..c54f1da8013 100644 --- a/README.md +++ b/README.md @@ -197,6 +197,10 @@ style_edition = "2024" ## Tips +* When using `rustfmt` directly in a Cargo project, Cargo will determine [`edition`](#rusts-editions) from `Cargo.toml`, but rustfmt will not, as it has its own configuration file, `rustfmt.toml`. + To ensure consistent parsing between `cargo fmt` and `rustfmt`, you should configure the [`edition`](#rusts-editions) in your `rustfmt.toml` file. + To ensure consistent formatting between `cargo fmt` and `rustfmt`, you should configure the [`style_edition`](#style-editions) in your `rustfmt.toml` file. + * For things you do not want rustfmt to mangle, use `#[rustfmt::skip]` * To prevent rustfmt from formatting a macro or an attribute, use `#[rustfmt::skip::macros(target_macro_name)]` or @@ -241,8 +245,6 @@ style_edition = "2024" | checkstyle | emits in a checkstyle format | Yes | | json | emits diffs in a json format | Yes | -* When using `rustfmt` directly in a Cargo project, set the `style_edition` or `edition` in `rustfmt.toml` to the same value as in `Cargo.toml` to ensure consistent formatting. For more details, see the [Style Editions](#style-editions) and [Rust's Editions](#rusts-editions) sections. - ## License Rustfmt is distributed under the terms of both the MIT license and the From 9fb7d89a273ed6b943ce64f1f6eba8701cfdcd95 Mon Sep 17 00:00:00 2001 From: Karol Zwolak Date: Thu, 27 Feb 2025 18:01:14 +0100 Subject: [PATCH 9/9] docs: remove confusing sentence in editions tips --- README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index c54f1da8013..0fdd2a6b60a 100644 --- a/README.md +++ b/README.md @@ -197,9 +197,8 @@ style_edition = "2024" ## Tips -* When using `rustfmt` directly in a Cargo project, Cargo will determine [`edition`](#rusts-editions) from `Cargo.toml`, but rustfmt will not, as it has its own configuration file, `rustfmt.toml`. - To ensure consistent parsing between `cargo fmt` and `rustfmt`, you should configure the [`edition`](#rusts-editions) in your `rustfmt.toml` file. - To ensure consistent formatting between `cargo fmt` and `rustfmt`, you should configure the [`style_edition`](#style-editions) in your `rustfmt.toml` file. +* To ensure consistent parsing between `cargo fmt` and `rustfmt`, you should configure the [`edition`](#rusts-editions) in your `rustfmt.toml` file. +* To ensure consistent formatting between `cargo fmt` and `rustfmt`, you should configure the [`style_edition`](#style-editions) in your `rustfmt.toml` file. * For things you do not want rustfmt to mangle, use `#[rustfmt::skip]` * To prevent rustfmt from formatting a macro or an attribute,