Skip to content

Commit

Permalink
docs: clarify the editions behavior and it's consequences on formatting
Browse files Browse the repository at this point in the history
  • Loading branch information
karolzwolak committed Feb 25, 2025
1 parent 2ad782c commit 0fa28a7
Show file tree
Hide file tree
Showing 2 changed files with 15 additions and 7 deletions.
10 changes: 6 additions & 4 deletions Configurations.md
Original file line number Diff line number Diff line change
Expand Up @@ -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"
edition = "2024"
```

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
Expand Down
12 changes: 9 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 0fa28a7

Please sign in to comment.