3 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.
5 A possible content of `rustfmt.toml` or `.rustfmt.toml` might look like this:
9 reorder_imported_names = true
12 Each configuration option is either stable or unstable.
13 Stable options can be used directly, while unstable options are opt-in.
14 To enable unstable options, set `unstable_features = true` in `rustfmt.toml` or pass `--unstable-options` to rustfmt.
16 # Configuration Options
18 Below you find a detailed visual guide on all the supported configuration options of rustfmt:
23 Indent on expressions or items.
25 - **Default value**: `"Block"`
26 - **Possible values**: `"Block"`, `"Visual"`
31 #### `"Block"` (default):
51 let lorem = vec!["ipsum",
63 #### `"Block"` (default):
84 See also: [`control_brace_style`](#control_brace_style).
86 ### Function arguments
88 #### `"Block"` (default):
93 fn lorem(ipsum: usize) {}
113 fn lorem(ipsum: usize) {}
115 fn lorem(ipsum: usize,
128 #### `"Block"` (default):
162 #### `"Block"` (default):
170 Adipiscing: Eq = usize,
171 Consectetur: Eq = usize,
178 adipiscing: Adipiscing,
179 consectetur: Consectetur,
189 fn lorem<Ipsum: Eq = usize,
193 Adipiscing: Eq = usize,
194 Consectetur: Eq = usize,
200 adipiscing: Adipiscing,
201 consectetur: Consectetur,
210 #### `"Block"` (default):
225 let lorem = Lorem { ipsum: dolor,
230 See also: [`struct_lit_single_line`](#struct_lit_single_line), [`indent_style`](#indent_style).
234 #### `"Block"` (default):
237 fn lorem<Ipsum, Dolor, Sit, Amet>() -> T
251 fn lorem<Ipsum, Dolor, Sit, Amet>() -> T
261 ## `use_small_heuristics`
263 Whether to use different formatting for items and expressions if they satisfy a heuristic notion of 'small'.
265 - **Default value**: `true`
266 - **Possible values**: `true`, `false`
269 #### `true` (default):
275 Sit { amet: Consectetur, adipiscing: Elit },
293 let lorem = Lorem { ipsum: dolor };
295 let lorem = if ipsum { dolor } else { sit };
312 lorem("lorem", "ipsum", "dolor", "sit", "amet", "consectetur", "adipiscing");
319 let lorem = if ipsum {
329 Where to put a binary operator when a binary expression goes multiline.
331 - **Default value**: `"Front"`
332 - **Possible values**: `"Front"`, `"Back"`
335 #### `"Front"` (default):
339 let or = foofoofoofoofoofoofoofoofoofoofoofoofoofoofoofoo
340 || barbarbarbarbarbarbarbarbarbarbarbarbarbarbarbar;
342 let sum = 123456789012345678901234567890 + 123456789012345678901234567890
343 + 123456789012345678901234567890;
345 let range = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
346 ..bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb;
354 let or = foofoofoofoofoofoofoofoofoofoofoofoofoofoofoofoo ||
355 barbarbarbarbarbarbarbarbarbarbarbarbarbarbarbar;
357 let sum = 123456789012345678901234567890 + 123456789012345678901234567890 +
358 123456789012345678901234567890;
360 let range = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa..
361 bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb;
365 ## `combine_control_expr`
367 Combine control expressions with function calls.
369 - **Default value**: `true`
370 - **Possible values**: `true`, `false`
373 #### `true` (default):
385 foo!(if let Some(..) = x {
398 foo!(while let Some(..) = x {
432 if let Some(..) = x {
449 while let Some(..) = x {
475 Maximum length of comments. No effect unless`wrap_comments = true`.
477 - **Default value**: `80`
478 - **Possible values**: any positive integer
481 **Note:** A value of `0` results in [`wrap_comments`](#wrap_comments) being applied regardless of a line's width.
483 #### `80` (default; comments shorter than `comment_width`):
485 // Lorem ipsum dolor sit amet, consectetur adipiscing elit.
488 #### `60` (comments longer than `comment_width`):
490 // Lorem ipsum dolor sit amet,
491 // consectetur adipiscing elit.
494 See also [`wrap_comments`](#wrap_comments).
496 ## `condense_wildcard_suffixes`
498 Replace strings of _ wildcards by a single .. in tuple patterns
500 - **Default value**: `false`
501 - **Possible values**: `true`, `false`
504 #### `false` (default):
507 let (lorem, ipsum, _, _) = (1, 2, 3, 4);
513 let (lorem, ipsum, ..) = (1, 2, 3, 4);
516 ## `control_brace_style`
518 Brace style for control flow constructs
520 - **Default value**: `"AlwaysSameLine"`
521 - **Possible values**: `"AlwaysNextLine"`, `"AlwaysSameLine"`, `"ClosingNextLine"`
524 #### `"AlwaysSameLine"` (default):
534 #### `"AlwaysNextLine"`:
547 #### `"ClosingNextLine"`:
558 ## `disable_all_formatting`
560 Don't reformat anything
562 - **Default value**: `false`
563 - **Possible values**: `true`, `false`
566 ## `error_on_line_overflow`
568 Error if unable to get all lines within `max_width`
570 - **Default value**: `true`
571 - **Possible values**: `true`, `false`
574 See also [`max_width`](#max_width).
576 ## `error_on_line_overflow_comments`
578 Error if unable to get all comment lines within `comment_width`.
580 - **Default value**: `true`
581 - **Possible values**: `true`, `false`
584 See also [`comment_width`](#comment_width).
588 Argument density in functions
590 - **Default value**: `"Tall"`
591 - **Possible values**: `"Compressed"`, `"Tall"`, `"Vertical"`
594 #### `"Tall"` (default):
598 fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet);
600 fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet) {
609 consectetur: Consectetur,
610 adipiscing: Adipiscing,
619 consectetur: Consectetur,
620 adipiscing: Adipiscing,
632 fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet);
634 fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet) {
639 ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet, consectetur: Consectetur,
640 adipiscing: Adipiscing, elit: Elit,
644 ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet, consectetur: Consectetur,
645 adipiscing: Adipiscing, elit: Elit,
656 fn lorem(ipsum: Ipsum,
661 fn lorem(ipsum: Ipsum,
668 fn lorem(ipsum: Ipsum,
672 consectetur: Consectetur,
673 adipiscing: Adipiscing,
676 fn lorem(ipsum: Ipsum,
680 consectetur: Consectetur,
681 adipiscing: Adipiscing,
691 Brace style for items
693 - **Default value**: `"SameLineWhere"`
694 - **Possible values**: `"AlwaysNextLine"`, `"PreferSameLine"`, `"SameLineWhere"`
699 #### `"SameLineWhere"` (default):
706 fn lorem(ipsum: usize) {
710 fn lorem<T>(ipsum: T)
712 T: Add + Sub + Mul + Div,
718 #### `"AlwaysNextLine"`:
726 fn lorem(ipsum: usize)
731 fn lorem<T>(ipsum: T)
733 T: Add + Sub + Mul + Div,
739 #### `"PreferSameLine"`:
746 fn lorem(ipsum: usize) {
750 fn lorem<T>(ipsum: T)
752 T: Add + Sub + Mul + Div, {
757 ### Structs and enums
759 #### `"SameLineWhere"` (default):
773 #### `"AlwaysNextLine"`:
788 #### `"PreferSameLine"`:
802 ## `empty_item_single_line`
804 Put empty-body functions and impls on a single line
806 - **Default value**: `true`
807 - **Possible values**: `true`, `false`
810 #### `true` (default):
828 See also [`brace_style`](#brace_style), [`control_brace_style`](#control_brace_style).
833 Put single-expression functions on a single line
835 - **Default value**: `false`
836 - **Possible values**: `true`, `false`
839 #### `false` (default):
842 fn lorem() -> usize {
846 fn lorem() -> usize {
855 fn lorem() -> usize { 42 }
857 fn lorem() -> usize {
863 See also [`control_brace_style`](#control_brace_style).
866 ## `where_single_line`
868 To force single line where layout
870 - **Default value**: `false`
871 - **Possible values**: `true`, `false`
874 #### `false` (default):
889 where Option<T>: Ipsum {
894 See also [`brace_style`](#brace_style), [`control_brace_style`](#control_brace_style).
897 ## `force_explicit_abi`
899 Always print the abi for extern items
901 - **Default value**: `true`
902 - **Possible values**: `true`, `false`
905 **Note:** Non-"C" ABIs are always printed. If `false` then "C" is removed.
907 #### `true` (default):
911 pub static lorem: c_int;
919 pub static lorem: c_int;
925 Format string literals where necessary
927 - **Default value**: `false`
928 - **Possible values**: `true`, `false`
931 #### `false` (default):
934 let lorem = "ipsum dolor sit amet consectetur adipiscing elit lorem ipsum dolor sit";
941 "ipsum dolor sit amet consectetur \
942 adipiscing elit lorem ipsum dolor sit";
945 See also [`max_width`](#max_width).
949 Use tab characters for indentation, spaces for alignment
951 - **Default value**: `false`
952 - **Possible values**: `true`, `false`
955 #### `false` (default):
958 fn lorem() -> usize {
959 42 // spaces before 42
966 fn lorem() -> usize {
971 See also: [`tab_spaces`](#tab_spaces).
976 Indent style of imports
978 - **Default Value**: `"Visual"`
979 - **Possible values**: `"Block"`, `"Visual"`
982 #### `"Visual"` (default):
1000 See also: [`imports_layout`](#imports_layout).
1004 Item layout inside a imports block
1006 - **Default value**: "Mixed"
1007 - **Possible values**: "Horizontal", "HorizontalVertical", "Mixed", "Vertical"
1010 #### `"Mixed"` (default):
1013 use foo::{xxx, yyy, zzz};
1015 use foo::{aaa, bbb, ccc,
1019 #### `"Horizontal"`:
1021 **Note**: This option forces all imports onto one line and may exceed `max_width`.
1024 use foo::{xxx, yyy, zzz};
1026 use foo::{aaa, bbb, ccc, ddd, eee, fff};
1029 #### `"HorizontalVertical"`:
1032 use foo::{xxx, yyy, zzz};
1058 ## `match_block_trailing_comma`
1060 Put a trailing comma after a block based match arm (non-block arms are not affected)
1062 - **Default value**: `false`
1063 - **Possible values**: `true`, `false`
1066 #### `false` (default):
1073 Lorem::Dolor => println!("dolor"),
1084 Lorem::Dolor => println!("dolor"),
1088 See also: [`trailing_comma`](#trailing_comma), [`match_arm_blocks`](#match_arm_blocks).
1092 Maximum width of each line
1094 - **Default value**: `100`
1095 - **Possible values**: any positive integer
1098 See also [`error_on_line_overflow`](#error_on_line_overflow).
1102 Merge multiple derives into a single one.
1104 - **Default value**: `true`
1105 - **Possible values**: `true`, `false`
1108 #### `true` (default):
1111 #[derive(Eq, PartialEq, Debug, Copy, Clone)]
1118 #[derive(Eq, PartialEq)]
1120 #[derive(Copy, Clone)]
1124 ## `force_multiline_blocks`
1126 Force multiline closure and match arm bodies to be wrapped in a block
1128 - **Default value**: `false`
1129 - **Possible values**: `false`, `true`
1132 #### `false` (default):
1135 result.and_then(|maybe_value| match maybe_value {
1142 println!("Hello World");
1152 result.and_then(|maybe_value| {
1162 println!("Hello World");
1172 Unix or Windows line endings
1174 - **Default value**: `"Unix"`
1175 - **Possible values**: `"Native"`, `"Unix"`, `"Windows"`
1178 ## `normalize_comments`
1180 Convert /* */ comments to // comments where possible
1182 - **Default value**: `false`
1183 - **Possible values**: `true`, `false`
1186 #### `false` (default):
1190 fn dolor() -> usize {}
1193 fn adipiscing() -> usize {}
1200 fn dolor() -> usize {}
1203 fn adipiscing() -> usize {}
1206 ## `reorder_imported_names`
1208 Reorder lists of names in import statements alphabetically
1210 - **Default value**: `false`
1211 - **Possible values**: `true`, `false`
1214 #### `false` (default):
1217 use super::{lorem, ipsum, dolor, sit};
1223 use super::{dolor, ipsum, lorem, sit};
1226 See also [`reorder_imports`](#reorder_imports).
1228 ## `reorder_imports`
1230 Reorder import statements alphabetically
1232 - **Default value**: `false`
1233 - **Possible values**: `true`, `false`
1236 #### `false` (default):
1254 See also [`reorder_imported_names`](#reorder_imported_names), [`reorder_imports_in_group`](#reorder_imports_in_group).
1256 ## `reorder_imports_in_group`
1258 Reorder import statements in group
1260 - **Default value**: `false`
1261 - **Possible values**: `true`, `false`
1264 **Note:** This option takes effect only when [`reorder_imports`](#reorder_imports) is set to `true`.
1266 #### `false` (default):
1290 See also [`reorder_imports`](#reorder_imports).
1292 ## `reorder_extern_crates`
1294 Reorder `extern crate` statements alphabetically
1296 - **Default value**: `true`
1297 - **Possible values**: `true`, `false`
1300 #### `true` (default):
1318 See also [`reorder_extern_crates_in_group`](#reorder_extern_crates_in_group).
1320 ## `reorder_extern_crates_in_group`
1322 Reorder `extern crate` statements in group
1324 - **Default value**: `true`
1325 - **Possible values**: `true`, `false`
1328 **Note:** This option takes effect only when [`reorder_imports`](#reorder_imports) is set to `true`.
1330 #### `true` (default):
1354 See also [`reorder_extern_crates`](#reorder_extern_crates).
1358 Report `TODO` items in comments.
1360 - **Default value**: `"Never"`
1361 - **Possible values**: `"Always"`, `"Unnumbered"`, `"Never"`
1364 Warns about any comments containing `TODO` in them when set to `"Always"`. If
1365 it contains a `#X` (with `X` being a number) in parentheses following the
1366 `TODO`, `"Unnumbered"` will ignore it.
1368 See also [`report_fixme`](#report_fixme).
1372 Report `FIXME` items in comments.
1374 - **Default value**: `"Never"`
1375 - **Possible values**: `"Always"`, `"Unnumbered"`, `"Never"`
1378 Warns about any comments containing `FIXME` in them when set to `"Always"`. If
1379 it contains a `#X` (with `X` being a number) in parentheses following the
1380 `FIXME`, `"Unnumbered"` will ignore it.
1382 See also [`report_todo`](#report_todo).
1387 Don't reformat out of line modules
1389 - **Default value**: `false`
1390 - **Possible values**: `true`, `false`
1393 ## `space_after_colon`
1395 Leave a space after the colon.
1397 - **Default value**: `true`
1398 - **Possible values**: `true`, `false`
1401 #### `true` (default):
1404 fn lorem<T: Eq>(t: T) {
1405 let lorem: Dolor = Lorem {
1415 fn lorem<T:Eq>(t:T) {
1416 let lorem:Dolor = Lorem {
1423 See also: [`space_before_colon`](#space_before_colon).
1425 ## `space_before_colon`
1427 Leave a space before the colon.
1429 - **Default value**: `false`
1430 - **Possible values**: `true`, `false`
1433 #### `false` (default):
1436 fn lorem<T: Eq>(t: T) {
1437 let lorem: Dolor = Lorem {
1447 fn lorem<T : Eq>(t : T) {
1448 let lorem : Dolor = Lorem {
1455 See also: [`space_after_colon`](#space_after_colon).
1457 ## `struct_field_align_threshold`
1459 The maximum diff of width between struct fields to be aligned with each other.
1461 - **Default value** : 0
1462 - **Possible values**: any positive integer
1485 ## `spaces_around_ranges`
1487 Put spaces around the .. and ... range operators
1489 - **Default value**: `false`
1490 - **Possible values**: `true`, `false`
1493 #### `false` (default):
1502 let lorem = 0 .. 10;
1505 ## `spaces_within_parens_and_brackets`
1507 Put spaces within non-empty generic arguments, parentheses, and square brackets
1509 - **Default value**: `false`
1510 - **Possible values**: `true`, `false`
1513 #### `false` (default):
1516 // generic arguments
1517 fn lorem<T: Eq>(t: T) {
1521 // non-empty parentheses
1522 fn lorem<T: Eq>(t: T) {
1523 let lorem = (ipsum, dolor);
1526 // non-empty square brackets
1527 let lorem: [usize; 2] = [ipsum, dolor];
1533 // generic arguments
1534 fn lorem< T: Eq >(t: T) {
1538 // non-empty parentheses
1539 fn lorem<T: Eq>( t: T ) {
1540 let lorem = ( ipsum, dolor );
1543 // non-empty square brackets
1544 let lorem: [ usize; 2 ] = [ ipsum, dolor ];
1547 ## `struct_lit_single_line`
1549 Put small struct literals on a single line
1551 - **Default value**: `true`
1552 - **Possible values**: `true`, `false`
1555 #### `true` (default):
1558 let lorem = Lorem { ipsum: dolor, sit: amet };
1570 See also: [`indent_style`](#indent_style).
1575 Number of spaces per tab
1577 - **Default value**: `4`
1578 - **Possible values**: any positive integer
1585 let ipsum = dolor();
1587 "amet consectetur adipiscing elit."
1596 let ipsum = dolor();
1598 "amet consectetur adipiscing elit."
1603 See also: [`hard_tabs`](#hard_tabs).
1608 How to handle trailing commas for lists
1610 - **Default value**: `"Vertical"`
1611 - **Possible values**: `"Always"`, `"Never"`, `"Vertical"`
1614 #### `"Vertical"` (default):
1617 let Lorem { ipsum, dolor, sit } = amet;
1631 let Lorem { ipsum, dolor, sit, } = amet;
1645 let Lorem { ipsum, dolor, sit } = amet;
1656 See also: [`match_block_trailing_comma`](#match_block_trailing_comma).
1658 ## `trailing_semicolon`
1660 Add trailing semicolon after break, continue and return
1662 - **Default value**: `true`
1663 - **Possible values**: `true`, `false`
1666 #### `true` (default):
1680 ## `type_punctuation_density`
1682 Determines if `+` or `=` are wrapped in spaces in the punctuation of types
1684 - **Default value**: `"Wide"`
1685 - **Possible values**: `"Compressed"`, `"Wide"`
1688 #### `"Wide"` (default):
1691 fn lorem<Ipsum: Dolor + Sit = Amet>() {
1696 #### `"Compressed"`:
1699 fn lorem<Ipsum: Dolor+Sit=Amet>() {
1704 ## `use_try_shorthand`
1706 Replace uses of the try! macro by the ? shorthand
1708 - **Default value**: `false`
1709 - **Possible values**: `true`, `false`
1712 #### `false` (default):
1715 let lorem = try!(ipsum.map(|dolor|dolor.sit()));
1721 let lorem = ipsum.map(|dolor| dolor.sit())?;
1727 Break comments to fit on the line
1729 - **Default value**: `false`
1730 - **Possible values**: `true`, `false`
1733 #### `false` (default):
1736 // Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
1742 // Lorem ipsum dolor sit amet, consectetur adipiscing elit,
1743 // sed do eiusmod tempor incididunt ut labore et dolore
1744 // magna aliqua. Ut enim ad minim veniam, quis nostrud
1745 // exercitation ullamco laboris nisi ut aliquip ex ea
1746 // commodo consequat.
1749 ## `match_arm_blocks`
1751 Wrap the body of arms in blocks when it does not fit on the same line with the pattern of arms
1753 - **Default value**: `true`
1754 - **Possible values**: `true`, `false`
1757 #### `true` (default):
1762 foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x)
1764 false => println!("{}", sit),
1773 foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x),
1774 false => println!("{}", sit),
1778 See also: [`match_block_trailing_comma`](#match_block_trailing_comma).
1782 What Write Mode to use when none is supplied: Replace, Overwrite, Display, Diff, Coverage
1784 - **Default value**: `"Overwrite"`
1785 - **Possible values**: `"Checkstyle"`, `"Coverage"`, `"Diff"`, `"Display"`, `"Overwrite"`, `"Plain"`, `"Replace"`
1788 ## `blank_lines_upper_bound`
1790 Maximum number of blank lines which can be put between items. If more than this number of consecutive empty
1791 lines are found, they are trimmed down to match this integer.
1793 - **Default value**: `1`
1794 - **Possible values**: *unsigned integer*
1843 See also: [`blank_lines_lower_bound`](#blank_lines_lower_bound)
1845 ## `blank_lines_lower_bound`
1847 Minimum number of blank lines which must be put between items. If two items have fewer blank lines between
1848 them, additional blank lines are inserted.
1850 - **Default value**: `0`
1851 - **Possible values**: *unsigned integer*
1855 Original Code (rustfmt will not change it with the default value of `0`):