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):
508 let (lorem, ipsum, _, _) = (1, 2, 3, 4);
509 let (lorem, ipsum, ..) = (1, 2, 3, 4);
517 let (lorem, ipsum, ..) = (1, 2, 3, 4);
521 ## `control_brace_style`
523 Brace style for control flow constructs
525 - **Default value**: `"AlwaysSameLine"`
526 - **Possible values**: `"AlwaysNextLine"`, `"AlwaysSameLine"`, `"ClosingNextLine"`
529 #### `"AlwaysSameLine"` (default):
541 #### `"AlwaysNextLine"`:
554 #### `"ClosingNextLine"`:
565 ## `disable_all_formatting`
567 Don't reformat anything
569 - **Default value**: `false`
570 - **Possible values**: `true`, `false`
573 ## `error_on_line_overflow`
575 Error if unable to get all lines within `max_width`
577 - **Default value**: `true`
578 - **Possible values**: `true`, `false`
581 See also [`max_width`](#max_width).
583 ## `error_on_line_overflow_comments`
585 Error if unable to get all comment lines within `comment_width`.
587 - **Default value**: `true`
588 - **Possible values**: `true`, `false`
591 See also [`comment_width`](#comment_width).
595 Argument density in functions
597 - **Default value**: `"Tall"`
598 - **Possible values**: `"Compressed"`, `"Tall"`, `"Vertical"`
601 #### `"Tall"` (default):
605 fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet);
607 fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet) {
616 consectetur: Consectetur,
617 adipiscing: Adipiscing,
626 consectetur: Consectetur,
627 adipiscing: Adipiscing,
639 fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet);
641 fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet) {
646 ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet, consectetur: Consectetur,
647 adipiscing: Adipiscing, elit: Elit,
651 ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet, consectetur: Consectetur,
652 adipiscing: Adipiscing, elit: Elit,
663 fn lorem(ipsum: Ipsum,
668 fn lorem(ipsum: Ipsum,
675 fn lorem(ipsum: Ipsum,
679 consectetur: Consectetur,
680 adipiscing: Adipiscing,
683 fn lorem(ipsum: Ipsum,
687 consectetur: Consectetur,
688 adipiscing: Adipiscing,
698 Brace style for items
700 - **Default value**: `"SameLineWhere"`
701 - **Possible values**: `"AlwaysNextLine"`, `"PreferSameLine"`, `"SameLineWhere"`
706 #### `"SameLineWhere"` (default):
713 fn lorem(ipsum: usize) {
717 fn lorem<T>(ipsum: T)
719 T: Add + Sub + Mul + Div,
725 #### `"AlwaysNextLine"`:
733 fn lorem(ipsum: usize)
738 fn lorem<T>(ipsum: T)
740 T: Add + Sub + Mul + Div,
746 #### `"PreferSameLine"`:
753 fn lorem(ipsum: usize) {
757 fn lorem<T>(ipsum: T)
759 T: Add + Sub + Mul + Div, {
764 ### Structs and enums
766 #### `"SameLineWhere"` (default):
780 #### `"AlwaysNextLine"`:
795 #### `"PreferSameLine"`:
809 ## `empty_item_single_line`
811 Put empty-body functions and impls on a single line
813 - **Default value**: `true`
814 - **Possible values**: `true`, `false`
817 #### `true` (default):
835 See also [`brace_style`](#brace_style), [`control_brace_style`](#control_brace_style).
840 Put single-expression functions on a single line
842 - **Default value**: `false`
843 - **Possible values**: `true`, `false`
846 #### `false` (default):
849 fn lorem() -> usize {
853 fn lorem() -> usize {
862 fn lorem() -> usize { 42 }
864 fn lorem() -> usize {
870 See also [`control_brace_style`](#control_brace_style).
873 ## `where_single_line`
875 To force single line where layout
877 - **Default value**: `false`
878 - **Possible values**: `true`, `false`
881 #### `false` (default):
896 where Option<T>: Ipsum {
901 See also [`brace_style`](#brace_style), [`control_brace_style`](#control_brace_style).
904 ## `force_explicit_abi`
906 Always print the abi for extern items
908 - **Default value**: `true`
909 - **Possible values**: `true`, `false`
912 **Note:** Non-"C" ABIs are always printed. If `false` then "C" is removed.
914 #### `true` (default):
918 pub static lorem: c_int;
926 pub static lorem: c_int;
932 Format string literals where necessary
934 - **Default value**: `false`
935 - **Possible values**: `true`, `false`
938 #### `false` (default):
941 let lorem = "ipsum dolor sit amet consectetur adipiscing elit lorem ipsum dolor sit";
948 "ipsum dolor sit amet consectetur \
949 adipiscing elit lorem ipsum dolor sit";
952 See also [`max_width`](#max_width).
956 Use tab characters for indentation, spaces for alignment
958 - **Default value**: `false`
959 - **Possible values**: `true`, `false`
962 #### `false` (default):
965 fn lorem() -> usize {
966 42 // spaces before 42
973 fn lorem() -> usize {
978 See also: [`tab_spaces`](#tab_spaces).
983 Indent style of imports
985 - **Default Value**: `"Visual"`
986 - **Possible values**: `"Block"`, `"Visual"`
989 #### `"Visual"` (default):
1007 See also: [`imports_layout`](#imports_layout).
1011 Item layout inside a imports block
1013 - **Default value**: "Mixed"
1014 - **Possible values**: "Horizontal", "HorizontalVertical", "Mixed", "Vertical"
1017 #### `"Mixed"` (default):
1020 use foo::{xxx, yyy, zzz};
1022 use foo::{aaa, bbb, ccc,
1026 #### `"Horizontal"`:
1028 **Note**: This option forces all imports onto one line and may exceed `max_width`.
1031 use foo::{xxx, yyy, zzz};
1033 use foo::{aaa, bbb, ccc, ddd, eee, fff};
1036 #### `"HorizontalVertical"`:
1039 use foo::{xxx, yyy, zzz};
1065 ## `match_block_trailing_comma`
1067 Put a trailing comma after a block based match arm (non-block arms are not affected)
1069 - **Default value**: `false`
1070 - **Possible values**: `true`, `false`
1073 #### `false` (default):
1080 Lorem::Dolor => println!("dolor"),
1091 Lorem::Dolor => println!("dolor"),
1095 See also: [`trailing_comma`](#trailing_comma), [`match_arm_blocks`](#match_arm_blocks).
1099 Maximum width of each line
1101 - **Default value**: `100`
1102 - **Possible values**: any positive integer
1105 See also [`error_on_line_overflow`](#error_on_line_overflow).
1109 Merge multiple derives into a single one.
1111 - **Default value**: `true`
1112 - **Possible values**: `true`, `false`
1115 #### `true` (default):
1118 #[derive(Eq, PartialEq, Debug, Copy, Clone)]
1125 #[derive(Eq, PartialEq)]
1127 #[derive(Copy, Clone)]
1131 ## `force_multiline_blocks`
1133 Force multiline closure and match arm bodies to be wrapped in a block
1135 - **Default value**: `false`
1136 - **Possible values**: `false`, `true`
1139 #### `false` (default):
1142 result.and_then(|maybe_value| match maybe_value {
1149 println!("Hello World");
1159 result.and_then(|maybe_value| {
1169 println!("Hello World");
1179 Unix or Windows line endings
1181 - **Default value**: `"Unix"`
1182 - **Possible values**: `"Native"`, `"Unix"`, `"Windows"`
1185 ## `normalize_comments`
1187 Convert /* */ comments to // comments where possible
1189 - **Default value**: `false`
1190 - **Possible values**: `true`, `false`
1193 #### `false` (default):
1197 fn dolor() -> usize {}
1200 fn adipiscing() -> usize {}
1207 fn dolor() -> usize {}
1210 fn adipiscing() -> usize {}
1213 ## `reorder_imported_names`
1215 Reorder lists of names in import statements alphabetically
1217 - **Default value**: `false`
1218 - **Possible values**: `true`, `false`
1221 #### `false` (default):
1224 use super::{lorem, ipsum, dolor, sit};
1230 use super::{dolor, ipsum, lorem, sit};
1233 See also [`reorder_imports`](#reorder_imports).
1235 ## `reorder_imports`
1237 Reorder import statements alphabetically
1239 - **Default value**: `false`
1240 - **Possible values**: `true`, `false`
1243 #### `false` (default):
1261 See also [`reorder_imported_names`](#reorder_imported_names), [`reorder_imports_in_group`](#reorder_imports_in_group).
1263 ## `reorder_imports_in_group`
1265 Reorder import statements in group
1267 - **Default value**: `false`
1268 - **Possible values**: `true`, `false`
1271 **Note:** This option takes effect only when [`reorder_imports`](#reorder_imports) is set to `true`.
1273 #### `false` (default):
1297 See also [`reorder_imports`](#reorder_imports).
1299 ## `reorder_extern_crates`
1301 Reorder `extern crate` statements alphabetically
1303 - **Default value**: `true`
1304 - **Possible values**: `true`, `false`
1307 #### `true` (default):
1325 See also [`reorder_extern_crates_in_group`](#reorder_extern_crates_in_group).
1327 ## `reorder_extern_crates_in_group`
1329 Reorder `extern crate` statements in group
1331 - **Default value**: `true`
1332 - **Possible values**: `true`, `false`
1335 **Note:** This option takes effect only when [`reorder_imports`](#reorder_imports) is set to `true`.
1337 #### `true` (default):
1361 See also [`reorder_extern_crates`](#reorder_extern_crates).
1365 Report `TODO` items in comments.
1367 - **Default value**: `"Never"`
1368 - **Possible values**: `"Always"`, `"Unnumbered"`, `"Never"`
1371 Warns about any comments containing `TODO` in them when set to `"Always"`. If
1372 it contains a `#X` (with `X` being a number) in parentheses following the
1373 `TODO`, `"Unnumbered"` will ignore it.
1375 See also [`report_fixme`](#report_fixme).
1379 Report `FIXME` items in comments.
1381 - **Default value**: `"Never"`
1382 - **Possible values**: `"Always"`, `"Unnumbered"`, `"Never"`
1385 Warns about any comments containing `FIXME` in them when set to `"Always"`. If
1386 it contains a `#X` (with `X` being a number) in parentheses following the
1387 `FIXME`, `"Unnumbered"` will ignore it.
1389 See also [`report_todo`](#report_todo).
1394 Don't reformat out of line modules
1396 - **Default value**: `false`
1397 - **Possible values**: `true`, `false`
1400 ## `space_after_colon`
1402 Leave a space after the colon.
1404 - **Default value**: `true`
1405 - **Possible values**: `true`, `false`
1408 #### `true` (default):
1411 fn lorem<T: Eq>(t: T) {
1412 let lorem: Dolor = Lorem {
1422 fn lorem<T:Eq>(t:T) {
1423 let lorem:Dolor = Lorem {
1430 See also: [`space_before_colon`](#space_before_colon).
1432 ## `space_before_colon`
1434 Leave a space before the colon.
1436 - **Default value**: `false`
1437 - **Possible values**: `true`, `false`
1440 #### `false` (default):
1443 fn lorem<T: Eq>(t: T) {
1444 let lorem: Dolor = Lorem {
1454 fn lorem<T : Eq>(t : T) {
1455 let lorem : Dolor = Lorem {
1462 See also: [`space_after_colon`](#space_after_colon).
1464 ## `struct_field_align_threshold`
1466 The maximum diff of width between struct fields to be aligned with each other.
1468 - **Default value** : 0
1469 - **Possible values**: any positive integer
1492 ## `spaces_around_ranges`
1494 Put spaces around the .. and ... range operators
1496 - **Default value**: `false`
1497 - **Possible values**: `true`, `false`
1500 #### `false` (default):
1509 let lorem = 0 .. 10;
1512 ## `spaces_within_parens_and_brackets`
1514 Put spaces within non-empty generic arguments, parentheses, and square brackets
1516 - **Default value**: `false`
1517 - **Possible values**: `true`, `false`
1520 #### `false` (default):
1523 // generic arguments
1524 fn lorem<T: Eq>(t: T) {
1528 // non-empty parentheses
1529 fn lorem<T: Eq>(t: T) {
1530 let lorem = (ipsum, dolor);
1533 // non-empty square brackets
1534 let lorem: [usize; 2] = [ipsum, dolor];
1540 // generic arguments
1541 fn lorem< T: Eq >(t: T) {
1545 // non-empty parentheses
1546 fn lorem<T: Eq>( t: T ) {
1547 let lorem = ( ipsum, dolor );
1550 // non-empty square brackets
1551 let lorem: [ usize; 2 ] = [ ipsum, dolor ];
1554 ## `struct_lit_single_line`
1556 Put small struct literals on a single line
1558 - **Default value**: `true`
1559 - **Possible values**: `true`, `false`
1562 #### `true` (default):
1565 let lorem = Lorem { ipsum: dolor, sit: amet };
1577 See also: [`indent_style`](#indent_style).
1582 Number of spaces per tab
1584 - **Default value**: `4`
1585 - **Possible values**: any positive integer
1592 let ipsum = dolor();
1594 "amet consectetur adipiscing elit."
1603 let ipsum = dolor();
1605 "amet consectetur adipiscing elit."
1610 See also: [`hard_tabs`](#hard_tabs).
1615 How to handle trailing commas for lists
1617 - **Default value**: `"Vertical"`
1618 - **Possible values**: `"Always"`, `"Never"`, `"Vertical"`
1621 #### `"Vertical"` (default):
1624 let Lorem { ipsum, dolor, sit } = amet;
1638 let Lorem { ipsum, dolor, sit, } = amet;
1652 let Lorem { ipsum, dolor, sit } = amet;
1663 See also: [`match_block_trailing_comma`](#match_block_trailing_comma).
1665 ## `trailing_semicolon`
1667 Add trailing semicolon after break, continue and return
1669 - **Default value**: `true`
1670 - **Possible values**: `true`, `false`
1673 #### `true` (default):
1687 ## `type_punctuation_density`
1689 Determines if `+` or `=` are wrapped in spaces in the punctuation of types
1691 - **Default value**: `"Wide"`
1692 - **Possible values**: `"Compressed"`, `"Wide"`
1695 #### `"Wide"` (default):
1698 fn lorem<Ipsum: Dolor + Sit = Amet>() {
1703 #### `"Compressed"`:
1706 fn lorem<Ipsum: Dolor+Sit=Amet>() {
1711 ## `use_try_shorthand`
1713 Replace uses of the try! macro by the ? shorthand
1715 - **Default value**: `false`
1716 - **Possible values**: `true`, `false`
1719 #### `false` (default):
1722 let lorem = try!(ipsum.map(|dolor|dolor.sit()));
1728 let lorem = ipsum.map(|dolor| dolor.sit())?;
1734 Break comments to fit on the line
1736 - **Default value**: `false`
1737 - **Possible values**: `true`, `false`
1740 #### `false` (default):
1743 // 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.
1749 // Lorem ipsum dolor sit amet, consectetur adipiscing elit,
1750 // sed do eiusmod tempor incididunt ut labore et dolore
1751 // magna aliqua. Ut enim ad minim veniam, quis nostrud
1752 // exercitation ullamco laboris nisi ut aliquip ex ea
1753 // commodo consequat.
1756 ## `match_arm_blocks`
1758 Wrap the body of arms in blocks when it does not fit on the same line with the pattern of arms
1760 - **Default value**: `true`
1761 - **Possible values**: `true`, `false`
1764 #### `true` (default):
1769 foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x)
1771 false => println!("{}", sit),
1780 foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x),
1781 false => println!("{}", sit),
1785 See also: [`match_block_trailing_comma`](#match_block_trailing_comma).
1789 What Write Mode to use when none is supplied: Replace, Overwrite, Display, Diff, Coverage
1791 - **Default value**: `"Overwrite"`
1792 - **Possible values**: `"Checkstyle"`, `"Coverage"`, `"Diff"`, `"Display"`, `"Overwrite"`, `"Plain"`, `"Replace"`
1795 ## `blank_lines_upper_bound`
1797 Maximum number of blank lines which can be put between items. If more than this number of consecutive empty
1798 lines are found, they are trimmed down to match this integer.
1800 - **Default value**: `1`
1801 - **Possible values**: *unsigned integer*
1850 See also: [`blank_lines_lower_bound`](#blank_lines_lower_bound)
1852 ## `blank_lines_lower_bound`
1854 Minimum number of blank lines which must be put between items. If two items have fewer blank lines between
1855 them, additional blank lines are inserted.
1857 - **Default value**: `0`
1858 - **Possible values**: *unsigned integer*
1862 Original Code (rustfmt will not change it with the default value of `0`):