# Configuring Rustfmt
-Rustfmt is designed to be very configurable. You can create a TOML file called `rustfmt.toml` or `.rustfmt.toml`, place it in the project or any other parent directory and it will apply the options in that file.
+Rustfmt is designed to be very configurable. You can create a TOML file called `rustfmt.toml` or `.rustfmt.toml`, place it in the project or any other parent directory and it will apply the options in that file. If none of these directories contain such a file, both your home directory and a directory called `rustfmt` in your [global config directory](https://docs.rs/dirs/1.0.4/dirs/fn.config_dir.html) (e.g. `.config/rustfmt/`) are checked as well.
A possible content of `rustfmt.toml` or `.rustfmt.toml` might look like this:
- **Default value**: `"Block"`
- **Possible values**: `"Block"`, `"Visual"`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3346)
### Array
```rust
fn main() {
let lorem = Lorem { ipsum: dolor,
- sit: amet, };
+ sit: amet };
}
```
Whether to use different formatting for items and expressions if they satisfy a heuristic notion of 'small'.
-- **Default value**: `Default`
-- **Possible values**: `Default`, `Off`, `Max`
+- **Default value**: `"Default"`
+- **Possible values**: `"Default"`, `"Off"`, `"Max"`
- **Stable**: Yes
#### `Default` (default):
- **Default value**: `"Front"`
- **Possible values**: `"Front"`, `"Back"`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3368)
#### `"Front"` (default):
- **Default value**: `true`
- **Possible values**: `true`, `false`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3369)
#### `true` (default):
- **Default value**: `80`
- **Possible values**: any positive integer
-- **Stable**: No
+- **Stable**: No (tracking issue: #3349)
**Note:** A value of `0` results in [`wrap_comments`](#wrap_comments) being applied regardless of a line's width.
- **Default value**: `false`
- **Possible values**: `true`, `false`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3384)
#### `false` (default):
- **Default value**: `"AlwaysSameLine"`
- **Possible values**: `"AlwaysNextLine"`, `"AlwaysSameLine"`, `"ClosingNextLine"`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3377)
#### `"AlwaysSameLine"` (default):
- **Default value**: `false`
- **Possible values**: `true`, `false`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3388)
## `error_on_line_overflow`
- **Default value**: `false`
- **Possible values**: `true`, `false`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3391)
See also [`max_width`](#max_width).
- **Default value**: `false`
- **Possible values**: `true`, `false`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3392)
## `fn_args_density`
- **Default value**: `"Tall"`
- **Possible values**: `"Compressed"`, `"Tall"`, `"Vertical"`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3375)
#### `"Tall"` (default):
- **Default value**: `"SameLineWhere"`
- **Possible values**: `"AlwaysNextLine"`, `"PreferSameLine"`, `"SameLineWhere"`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3376)
### Functions
- **Default value**: `true`
- **Possible values**: `true`, `false`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3356)
#### `true` (default):
See also [`brace_style`](#brace_style), [`control_brace_style`](#control_brace_style).
+## `enum_discrim_align_threshold`
+
+The maximum length of enum variant having discriminant, that gets vertically aligned with others.
+Variants without discriminants would be ignored for the purpose of alignment.
+
+Note that this is not how much whitespace is inserted, but instead the longest variant name that
+doesn't get ignored when aligning.
+
+- **Default value** : 0
+- **Possible values**: any positive integer
+- **Stable**: No (tracking issue: #3372)
+
+#### `0` (default):
+
+```rust
+enum Bar {
+ A = 0,
+ Bb = 1,
+ RandomLongVariantGoesHere = 10,
+ Ccc = 71,
+}
+
+enum Bar {
+ VeryLongVariantNameHereA = 0,
+ VeryLongVariantNameHereBb = 1,
+ VeryLongVariantNameHereCcc = 2,
+}
+```
+
+#### `20`:
+
+```rust
+enum Foo {
+ A = 0,
+ Bb = 1,
+ RandomLongVariantGoesHere = 10,
+ Ccc = 2,
+}
+
+enum Bar {
+ VeryLongVariantNameHereA = 0,
+ VeryLongVariantNameHereBb = 1,
+ VeryLongVariantNameHereCcc = 2,
+}
+```
+
+
## `fn_single_line`
Put single-expression functions on a single line
- **Default value**: `false`
- **Possible values**: `true`, `false`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3358)
#### `false` (default):
- **Default value**: `false`
- **Possible values**: `true`, `false`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3359)
#### `false` (default):
- **Default value**: `false`
- **Possible values**: `true`, `false`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3353)
#### `false` (default):
```rust
fn main() {
- let lorem =
- "ipsum dolor sit amet consectetur adipiscing elit lorem ipsum dolor sit amet consectetur adipiscing";
+ let lorem = "ipsum dolor sit amet consectetur adipiscing elit lorem ipsum dolor sit amet consectetur adipiscing";
}
```
- **Default value**: `false`
- **Possible values**: `true`, `false`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3354)
#### `false` (default):
- **Default value**: `true`
- **Possible values**: `true`, `false`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3355)
#### `true` (default):
- **Default Value**: `"Block"`
- **Possible values**: `"Block"`, `"Visual"`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3360)
#### `"Block"` (default):
- **Default value**: "Mixed"
- **Possible values**: "Horizontal", "HorizontalVertical", "Mixed", "Vertical"
-- **Stable**: No
+- **Stable**: No (tracking issue: #3361)
#### `"Mixed"` (default):
- **Default value**: `false`
- **Possible values**: `true`, `false`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3362)
#### `false` (default):
- **Default value**: `false`
- **Possible values**: `true`, `false`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3380)
#### `false` (default):
- **Default value**: `false`
- **Possible values**: `false`, `true`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3374)
#### `false` (default):
});
match lorem {
- None => if ipsum {
+ None => |ipsum| {
println!("Hello World");
},
Some(dolor) => foo(),
match lorem {
None => {
- if ipsum {
+ |ipsum| {
println!("Hello World");
}
}
- **Possible values**: `"Auto"`, `"Native"`, `"Unix"`, `"Windows"`
- **Stable**: Yes
+#### `Auto` (default):
+
+The newline style is detected automatically on a per-file basis. Files
+with mixed line endings will be converted to the first detected line
+ending style.
+
+#### `Native`
+
+Line endings will be converted to `\r\n` on Windows and `\n` on all
+other platforms.
+
+#### `Unix`
+
+Line endings will be converted to `\n`.
+
+#### `Windows`
+
+Line endings will be converted to `\r\n`.
+
## `normalize_comments`
Convert /* */ comments to // comments where possible
- **Default value**: `false`
- **Possible values**: `true`, `false`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3350)
#### `false` (default):
mod sit;
```
-**Note** `mod` with `#[macro_export]` will not be reordered since that could change the semantic
+**Note** `mod` with `#[macro_export]` will not be reordered since that could change the semantics
of the original source code.
## `reorder_impl_items`
- **Default value**: `false`
- **Possible values**: `true`, `false`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3363)
#### `false` (default)
- **Default value**: `"Never"`
- **Possible values**: `"Always"`, `"Unnumbered"`, `"Never"`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3393)
Warns about any comments containing `TODO` in them when set to `"Always"`. If
it contains a `#X` (with `X` being a number) in parentheses following the
- **Default value**: `"Never"`
- **Possible values**: `"Always"`, `"Unnumbered"`, `"Never"`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3394)
Warns about any comments containing `FIXME` in them when set to `"Always"`. If
it contains a `#X` (with `X` being a number) in parentheses following the
- **Default value**: `false`
- **Possible values**: `true`, `false`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3389)
## `space_after_colon`
- **Default value**: `true`
- **Possible values**: `true`, `false`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3366)
#### `true` (default):
- **Default value**: `false`
- **Possible values**: `true`, `false`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3365)
#### `false` (default):
The maximum diff of width between struct fields to be aligned with each other.
- **Default value** : 0
-- **Possible values**: any positive integer
-- **Stable**: No
+- **Possible values**: any non-negative integer
+- **Stable**: No (tracking issue: #3371)
#### `0` (default):
- **Default value**: `false`
- **Possible values**: `true`, `false`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3367)
#### `false` (default):
- **Default value**: `true`
- **Possible values**: `true`, `false`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3357)
#### `true` (default):
- **Default value**: `"Vertical"`
- **Possible values**: `"Always"`, `"Never"`, `"Vertical"`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3379)
#### `"Vertical"` (default):
- **Default value**: `true`
- **Possible values**: `true`, `false`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3378)
#### `true` (default):
```rust
- **Default value**: `"Wide"`
- **Possible values**: `"Compressed"`, `"Wide"`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3364)
#### `"Wide"` (default):
}
```
+## `format_code_in_doc_comments`
+
+Format code snippet included in doc comments.
+
+- **Default value**: `false`
+- **Possible values**: `true`, `false`
+- **Stable**: No (tracking issue: #3348)
+
+#### `false` (default):
+
+```rust
+/// Adds one to the number given.
+///
+/// # Examples
+///
+/// ```rust
+/// let five=5;
+///
+/// assert_eq!(
+/// 6,
+/// add_one(5)
+/// );
+/// # fn add_one(x: i32) -> i32 {
+/// # x + 1
+/// # }
+/// ```
+fn add_one(x: i32) -> i32 {
+ x + 1
+}
+```
+
+#### `true`
+
+```rust
+/// Adds one to the number given.
+///
+/// # Examples
+///
+/// ```rust
+/// let five = 5;
+///
+/// assert_eq!(6, add_one(5));
+/// # fn add_one(x: i32) -> i32 {
+/// # x + 1
+/// # }
+/// ```
+fn add_one(x: i32) -> i32 {
+ x + 1
+}
+```
## `wrap_comments`
- **Default value**: `false`
- **Possible values**: `true`, `false`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3347)
#### `false` (default):
- **Default value**: `true`
- **Possible values**: `true`, `false`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3373)
#### `true` (default):
See also: [`match_block_trailing_comma`](#match_block_trailing_comma).
+## `overflow_delimited_expr`
+
+When structs, slices, arrays, and block/array-like macros are used as the last
+argument in an expression list, allow them to overflow (like blocks/closures)
+instead of being indented on a new line.
+
+- **Default value**: `false`
+- **Possible values**: `true`, `false`
+- **Stable**: No (tracking issue: #3370)
+
+#### `false` (default):
+
+```rust
+fn example() {
+ foo(ctx, |param| {
+ action();
+ foo(param)
+ });
+
+ foo(
+ ctx,
+ Bar {
+ x: value,
+ y: value2,
+ },
+ );
+
+ foo(
+ ctx,
+ &[
+ MAROON_TOMATOES,
+ PURPLE_POTATOES,
+ ORGANE_ORANGES,
+ GREEN_PEARS,
+ RED_APPLES,
+ ],
+ );
+
+ foo(
+ ctx,
+ vec![
+ MAROON_TOMATOES,
+ PURPLE_POTATOES,
+ ORGANE_ORANGES,
+ GREEN_PEARS,
+ RED_APPLES,
+ ],
+ );
+}
+```
+
+#### `true`:
+
+```rust
+fn example() {
+ foo(ctx, |param| {
+ action();
+ foo(param)
+ });
+
+ foo(ctx, Bar {
+ x: value,
+ y: value2,
+ });
+
+ foo(ctx, &[
+ MAROON_TOMATOES,
+ PURPLE_POTATOES,
+ ORGANE_ORANGES,
+ GREEN_PEARS,
+ RED_APPLES,
+ ]);
+
+ foo(ctx, vec![
+ MAROON_TOMATOES,
+ PURPLE_POTATOES,
+ ORGANE_ORANGES,
+ GREEN_PEARS,
+ RED_APPLES,
+ ]);
+}
+```
## `blank_lines_upper_bound`
lines are found, they are trimmed down to match this integer.
- **Default value**: `1`
-- **Possible values**: *unsigned integer*
-- **Stable**: No
+- **Possible values**: any non-negative integer
+- **Stable**: No (tracking issue: #3381)
### Example
Original Code:
- **Default value**: `0`
- **Possible values**: *unsigned integer*
-- **Stable**: No
+- **Stable**: No (tracking issue: #3382)
### Example
Original Code (rustfmt will not change it with the default value of `0`):
- **Default value**: `CARGO_PKG_VERSION`
- **Possible values**: any published version (e.g. `"0.3.8"`)
-- **Stable**: No
+- **Stable**: No (tracking issue: #3386)
## `hide_parse_errors`
- **Default value**: `false`
- **Possible values**: `true`, `false`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3390)
## `color`
- **Default value**: `"Auto"`
- **Possible values**: "Auto", "Always", "Never"
-- **Stable**: No
+- **Stable**: No (tracking issue: #3385)
## `unstable_features`
-Enable unstable features on stable channel.
+Enable unstable features on the unstable channel.
- **Default value**: `false`
- **Possible values**: `true`, `false`
-- **Stable**: No
+- **Stable**: No (tracking issue: #3387)
## `license_template_path`
Check whether beginnings of files match a license template.
-- **Default value**: `""``
+- **Default value**: `""`
- **Possible values**: path to a license template file
-- **Stable**: No
+- **Stable**: No (tracking issue: #3352)
A license template is a plain text file which is matched literally against the
beginning of each source file, except for `{}`-delimited blocks, which are
Skip formatting the specified files and directories.
-- **Default value**: format every files
+- **Default value**: format every file
- **Possible values**: See an example below
-- **Stable**: No
+- **Stable**: No (tracking issue: #3395)
### Example
Specifies which edition is used by the parser.
-- **Default value**: `Edition2015`
-- **Possible values**: `Edition2015`, `Edition2018`
-- **Stable**: No
+- **Default value**: `2015`
+- **Possible values**: `2015`, `2018`
+- **Stable**: Yes
-### Example
+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:
-If you want to format code that requires edition 2018, add the following to your config file:
+```toml
+edition = "2018"
+```
+
+## `version`
+
+Which version of the formatting rules to use. `Version::One` is backwards-compatible
+with Rustfmt 1.0. Other versions are only backwards compatible within a major
+version number.
+
+- **Default value**: `One`
+- **Possible values**: `One`, `Two`
+- **Stable**: No (tracking issue: #3383)
+
+### Example
```toml
-edition = "Edition2018"
+version = "Two"
+```
+
+## `normalize_doc_attributes`
+
+Convert `#![doc]` and `#[doc]` attributes to `//!` and `///` doc comments.
+
+- **Default value**: `false`
+- **Possible values**: `true`, `false`
+- **Stable**: No (tracking issue: #3351)
+
+#### `false` (default):
+
+```rust
+#![doc = "Example documentation"]
+
+#[doc = "Example item documentation"]
+pub enum Foo {}
+```
+
+#### `true`:
+
+```rust
+//! Example documentation
+
+/// Example item documentation
+pub enum Foo {}
+```
+
+## `inline_attribute_width`
+
+Write an item and its attribute on the same line if their combined width is below a threshold
+
+- **Default value**: 0
+- **Possible values**: any positive integer
+- **Stable**: No (tracking issue: #3343)
+
+### Example
+
+#### `0` (default):
+```rust
+#[cfg(feature = "alloc")]
+use core::slice;
+```
+
+#### `50`:
+```rust
+#[cfg(feature = "alloc")] use core::slice;
```
## `emit_mode`
projects / rust.git / blobdiff