# 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:
Below you find a detailed visual guide on all the supported configuration options of rustfmt:
-## `indent_style`
+## `indent_style` (tracking issue #3346)
Indent on expressions or items.
```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):
}
```
-## `binop_separator`
+## `binop_separator` (tracking issue #3368)
Where to put a binary operator when a binary expression goes multiline.
}
```
-## `combine_control_expr`
+## `combine_control_expr` (tracking issue #3369)
Combine control expressions with function calls.
}
```
-## `comment_width`
+## `comment_width` (tracking issue #3349)
Maximum length of comments. No effect unless`wrap_comments = true`.
See also [`wrap_comments`](#wrap_comments).
-## `condense_wildcard_suffixes`
+## `condense_wildcard_suffixes` (tracking issue #3384)
Replace strings of _ wildcards by a single .. in tuple patterns
}
```
-## `control_brace_style`
+## `control_brace_style` (tracking issue #3377)
Brace style for control flow constructs
}
```
-## `disable_all_formatting`
+## `disable_all_formatting` (tracking issue #3388)
Don't reformat anything
- **Possible values**: `true`, `false`
- **Stable**: No
-## `error_on_line_overflow`
+## `error_on_line_overflow` (tracking issue #3391)
Error if Rustfmt is unable to get all lines within `max_width`, except for comments and string
literals. If this happens, then it is a bug in Rustfmt. You might be able to work around the bug by
See also [`max_width`](#max_width).
-## `error_on_unformatted`
+## `error_on_unformatted` (tracking issue #3392)
Error if unable to get comments or string literals within `max_width`, or they are left with
trailing whitespaces.
- **Possible values**: `true`, `false`
- **Stable**: No
-## `fn_args_density`
+## `fn_args_density` (tracking issue #3375)
Argument density in functions
```
-## `brace_style`
+## `brace_style` (tracking issue #3376)
Brace style for items
```
-## `empty_item_single_line`
+## `empty_item_single_line` (tracking issue #3356)
Put empty-body functions and impls on a single line
See also [`brace_style`](#brace_style), [`control_brace_style`](#control_brace_style).
-## `fn_single_line`
+## `enum_discrim_align_threshold` (tracking issue #3372)
+
+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
+
+#### `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` (tracking issue #3358)
Put single-expression functions on a single line
See also [`control_brace_style`](#control_brace_style).
-## `where_single_line`
+## `where_single_line` (tracking issue #3359)
Forces the `where` clause to be laid out on a single line.
}
```
-## `format_strings`
+## `format_strings` (tracking issue #3353)
Format string literals where necessary
```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";
}
```
See also [`max_width`](#max_width).
+## `format_macro_matchers` (tracking issue #3354)
+
+Format the metavariable matching patterns in macros.
+
+- **Default value**: `false`
+- **Possible values**: `true`, `false`
+- **Stable**: No
+
+#### `false` (default):
+
+```rust
+macro_rules! foo {
+ ($a: ident : $b: ty) => {
+ $a(42): $b;
+ };
+ ($a: ident $b: ident $c: ident) => {
+ $a = $b + $c;
+ };
+}
+```
+
+#### `true`:
+
+```rust
+macro_rules! foo {
+ ($a:ident : $b:ty) => {
+ $a(42): $b;
+ };
+ ($a:ident $b:ident $c:ident) => {
+ $a = $b + $c;
+ };
+}
+```
+
+See also [`format_macro_bodies`](#format_macro_bodies).
+
+
+## `format_macro_bodies` (tracking issue #3355)
+
+Format the bodies of macros.
+
+- **Default value**: `true`
+- **Possible values**: `true`, `false`
+- **Stable**: No
+
+#### `true` (default):
+
+```rust
+macro_rules! foo {
+ ($a: ident : $b: ty) => {
+ $a(42): $b;
+ };
+ ($a: ident $b: ident $c: ident) => {
+ $a = $b + $c;
+ };
+}
+```
+
+#### `false`:
+
+```rust
+macro_rules! foo {
+ ($a: ident : $b: ty) => { $a(42): $b; };
+ ($a: ident $b: ident $c: ident) => { $a=$b+$c; };
+}
+```
+
+See also [`format_macro_matchers`](#format_macro_matchers).
+
+
## `hard_tabs`
Use tab characters for indentation, spaces for alignment
See also: [`tab_spaces`](#tab_spaces).
-## `imports_indent`
+## `imports_indent` (tracking issue #3360)
Indent style of imports
See also: [`imports_layout`](#imports_layout).
-## `imports_layout`
+## `imports_layout` (tracking issue #3361)
Item layout inside a imports block
};
```
-## `merge_imports`
+## `merge_imports` (tracking issue #3362)
Merge multiple imports into a single nested import.
```
-## `match_block_trailing_comma`
+## `match_block_trailing_comma` (tracking issue #3380)
Put a trailing comma after a block based match arm (non-block arms are not affected)
pub enum Foo {}
```
-## `force_multiline_blocks`
+## `force_multiline_blocks` (tracking issue #3374)
Force multiline closure and match arm bodies to be wrapped in a block
});
match lorem {
- None => if ipsum {
+ None => |ipsum| {
println!("Hello World");
},
Some(dolor) => foo(),
match lorem {
None => {
- if ipsum {
+ |ipsum| {
println!("Hello World");
}
}
Unix or Windows line endings
-- **Default value**: `"Native"`
-- **Possible values**: `"Native"`, `"Unix"`, `"Windows"`
+- **Default value**: `"Auto"`
+- **Possible values**: `"Auto"`, `"Native"`, `"Unix"`, `"Windows"`
- **Stable**: Yes
-## `normalize_comments`
+#### `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` (tracking issue #3350)
Convert /* */ comments to // comments where possible
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`
+## `reorder_impl_items` (tracking issue #3363)
Reorder impl items. `type` and `const` are put first, then macros and methods.
}
```
-## `report_todo`
+## `report_todo` (tracking issue #3393)
Report `TODO` items in comments.
See also [`report_fixme`](#report_fixme).
-## `report_fixme`
+## `report_fixme` (tracking issue #3394)
Report `FIXME` items in comments.
See also [`report_todo`](#report_todo).
-## `skip_children`
+## `skip_children` (tracking issue #3389)
Don't reformat out of line modules
- **Possible values**: `true`, `false`
- **Stable**: No
-## `space_after_colon`
+## `space_after_colon` (tracking issue #3366)
Leave a space after the colon.
See also: [`space_before_colon`](#space_before_colon).
-## `space_before_colon`
+## `space_before_colon` (tracking issue #3365)
Leave a space before the colon.
See also: [`space_after_colon`](#space_after_colon).
-## `struct_field_align_threshold`
+## `struct_field_align_threshold` (tracking issue #3371)
The maximum diff of width between struct fields to be aligned with each other.
}
```
-## `spaces_around_ranges`
+## `spaces_around_ranges` (tracking issue #3367)
Put spaces around the .., ..=, and ... range operators
}
```
-## `struct_lit_single_line`
+## `struct_lit_single_line` (tracking issue #3357)
Put small struct literals on a single line
See also: [`hard_tabs`](#hard_tabs).
-## `trailing_comma`
+## `trailing_comma` (tracking issue #3379)
How to handle trailing commas for lists
See also: [`match_block_trailing_comma`](#match_block_trailing_comma).
-## `trailing_semicolon`
+## `trailing_semicolon` (tracking issue #3378)
Add trailing semicolon after break, continue and return
}
```
-## `type_punctuation_density`
+## `type_punctuation_density` (tracking issue #3364)
Determines if `+` or `=` are wrapped in spaces in the punctuation of types
}
```
+## `format_doc_comments` (tracking issue #3348)
-## `wrap_comments`
+Format doc comments.
+
+- **Default value**: `false`
+- **Possible values**: `true`, `false`
+- **Stable**: No
+
+#### `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` (tracking issue #3347)
Break comments to fit on the line
// commodo consequat.
```
-## `match_arm_blocks`
+## `match_arm_blocks`` (tracking issue #3373)
Wrap the body of arms in blocks when it does not fit on the same line with the pattern of arms
See also: [`match_block_trailing_comma`](#match_block_trailing_comma).
+## `overflow_delimited_expr` (tracking issue #3370)
+
+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
+
+#### `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,
+ ],
+ );
+}
+```
-## `blank_lines_upper_bound`
+#### `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` (tracking issue #3381)
Maximum number of blank lines which can be put between items. If more than this number of consecutive empty
lines are found, they are trimmed down to match this integer.
See also: [`blank_lines_lower_bound`](#blank_lines_lower_bound)
-## `blank_lines_lower_bound`
+## `blank_lines_lower_bound` (tracking issue #3382)
Minimum number of blank lines which must be put between items. If two items have fewer blank lines between
them, additional blank lines are inserted.
```
-## `required_version`
+## `required_version` (tracking issue #3386)
Require a specific version of rustfmt. If you want to make sure that the
specific version of rustfmt is used in your CI, use this option.
- **Possible values**: any published version (e.g. `"0.3.8"`)
- **Stable**: No
-## `hide_parse_errors`
+## `hide_parse_errors` (tracking issue #3390)
Do not show parse errors if the parser failed to parse files.
- **Possible values**: `true`, `false`
- **Stable**: No
-## `color`
+## `color` (tracking issue #3385)
Whether to use colored output or not.
- **Possible values**: "Auto", "Always", "Never"
- **Stable**: No
-## `unstable_features`
+## `unstable_features` (tracking issue #3387)
-Enable unstable features on stable channel.
+Enable unstable features on the unstable channel.
- **Default value**: `false`
- **Possible values**: `true`, `false`
- **Stable**: No
-## `license_template_path`
+## `license_template_path` (tracking issue #3352)
Check whether beginnings of files match a license template.
`\{`, `\}` and `\\` match literal braces / backslashes.
-## `ignore`
+## `ignore` (tracking issue #3395)
Skip formatting the specified files and directories.
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
If you want to format code that requires edition 2018, add the following to your config file:
```toml
-edition = "Edition2018"
+edition = "2018"
+```
+
+## `version` (tracking issue #3383)
+
+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
+
+### Example
+
+```toml
+version = "Two"
+```
+
+## `normalize_doc_attributes` (tracking issue #3351)
+
+Convert `#![doc]` and `#[doc]` attributes to `//!` and `///` doc comments.
+
+- **Default value**: `false`
+- **Possible values**: `true`, `false`
+- **Stable**: No
+
+#### `false` (default):
+
+```rust
+#![doc = "Example documentation"]
+
+#[doc = "Example item documentation"]
+pub enum Foo {}
+```
+
+#### `true`:
+
+```rust
+//! Example documentation
+
+/// Example item documentation
+pub enum Foo {}
```
-## `emit_mode`
+## `emit_mode` (tracking issue #3399)
Internal option
-## `make_backup`
+## `make_backup` (tracking issue #3400)
Internal option, use `--backup`