# 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**: `true`
-- **Possible values**: `true`, `false`
-- **Stable**: No
+- **Default value**: `"Default"`
+- **Possible values**: `"Default"`, `"Off"`, `"Max"`
+- **Stable**: Yes
-#### `true` (default):
+#### `Default` (default):
```rust
enum Lorem {
}
```
-#### `false`:
+#### `Off`:
```rust
enum Lorem {
}
```
-## `binop_separator`
+#### `Max`:
+
+```rust
+enum Lorem {
+ Ipsum,
+ Dolor(bool),
+ Sit { amet: Consectetur, adipiscing: Elit },
+}
+
+fn main() {
+ lorem("lorem", "ipsum", "dolor", "sit", "amet", "consectetur", "adipiscing");
+
+ let lorem = Lorem { ipsum: dolor, sit: amet };
+
+ let lorem = if ipsum { dolor } else { sit };
+}
+```
+
+## `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
-- **Default Value**: `"Visual"`
+- **Default Value**: `"Block"`
- **Possible values**: `"Block"`, `"Visual"`
- **Stable**: No
-#### `"Visual"` (default):
-
-```rust
-use foo::{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx, yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy,
- zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz};
-```
-
-#### `"Block"`:
+#### `"Block"` (default):
```rust
use foo::{
};
```
+#### `"Visual"`:
+
+```rust
+use foo::{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx, yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy,
+ zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz};
+```
+
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**: `"Unix"`
-- **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)
+
+Format doc comments.
-## `wrap_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,
+ ],
+ );
+}
+```
+
+#### `true`:
+
+```rust
+fn example() {
+ foo(ctx, |param| {
+ action();
+ foo(param)
+ });
-## `blank_lines_upper_bound`
+ 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.
}
```
-#### `2` (default):
+#### `2`:
```rust
fn foo() {
println!("a");
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.
If you want to ignore every file under `examples/`, put the following to your config file:
```toml
-ignore [
+ignore = [
"examples",
]
```
-## `emit_mode`
+## `edition`
+
+Specifies which edition is used by the parser.
+
+- **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 = "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` (tracking issue #3399)
Internal option
-## `make_backup`
+## `make_backup` (tracking issue #3400)
Internal option, use `--backup`