# 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.
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).
-## `enum_discrim_align_threshold`
+## `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.
```
-## `fn_single_line`
+## `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`
+## `format_macro_matchers` (tracking issue #3354)
Format the metavariable matching patterns in macros.
See also [`format_macro_bodies`](#format_macro_bodies).
-## `format_macro_bodies`
+## `format_macro_bodies` (tracking issue #3355)
Format the bodies of macros.
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
Line endings will be converted to `\r\n`.
-## `normalize_comments`
+## `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`
+## `format_doc_comments` (tracking issue #3348)
Format doc comments.
}
```
-## `wrap_comments`
+## `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)
-## `blank_lines_upper_bound`
+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)
+ });
+
+ 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.
edition = "2018"
```
-## `normalize_doc_attributes`
+## `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.
pub enum Foo {}
```
-## `emit_mode`
+## `emit_mode` (tracking issue #3399)
Internal option
-## `make_backup`
+## `make_backup` (tracking issue #3400)
Internal option, use `--backup`
projects / rust.git / blobdiff