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"`:
556 #### `"ClosingNextLine"`:
569 ## `disable_all_formatting`
571 Don't reformat anything
573 - **Default value**: `false`
574 - **Possible values**: `true`, `false`
577 ## `error_on_line_overflow`
579 Error if unable to get all lines within `max_width`
581 - **Default value**: `true`
582 - **Possible values**: `true`, `false`
585 See also [`max_width`](#max_width).
587 ## `error_on_line_overflow_comments`
589 Error if unable to get all comment lines within `comment_width`.
591 - **Default value**: `true`
592 - **Possible values**: `true`, `false`
595 See also [`comment_width`](#comment_width).
599 Argument density in functions
601 - **Default value**: `"Tall"`
602 - **Possible values**: `"Compressed"`, `"Tall"`, `"Vertical"`
605 #### `"Tall"` (default):
609 fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet);
611 fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet) {
620 consectetur: Consectetur,
621 adipiscing: Adipiscing,
630 consectetur: Consectetur,
631 adipiscing: Adipiscing,
643 fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet);
645 fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet) {
650 ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet, consectetur: Consectetur,
651 adipiscing: Adipiscing, elit: Elit,
655 ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet, consectetur: Consectetur,
656 adipiscing: Adipiscing, elit: Elit,
688 consectetur: Consectetur,
689 adipiscing: Adipiscing,
698 consectetur: Consectetur,
699 adipiscing: Adipiscing,
710 Brace style for items
712 - **Default value**: `"SameLineWhere"`
713 - **Possible values**: `"AlwaysNextLine"`, `"PreferSameLine"`, `"SameLineWhere"`
718 #### `"SameLineWhere"` (default):
725 fn lorem(ipsum: usize) {
729 fn lorem<T>(ipsum: T)
731 T: Add + Sub + Mul + Div,
737 #### `"AlwaysNextLine"`:
745 fn lorem(ipsum: usize)
750 fn lorem<T>(ipsum: T)
752 T: Add + Sub + Mul + Div,
758 #### `"PreferSameLine"`:
765 fn lorem(ipsum: usize) {
769 fn lorem<T>(ipsum: T)
771 T: Add + Sub + Mul + Div, {
776 ### Structs and enums
778 #### `"SameLineWhere"` (default):
792 #### `"AlwaysNextLine"`:
808 #### `"PreferSameLine"`:
822 ## `empty_item_single_line`
824 Put empty-body functions and impls on a single line
826 - **Default value**: `true`
827 - **Possible values**: `true`, `false`
830 #### `true` (default):
848 See also [`brace_style`](#brace_style), [`control_brace_style`](#control_brace_style).
853 Put single-expression functions on a single line
855 - **Default value**: `false`
856 - **Possible values**: `true`, `false`
859 #### `false` (default):
862 fn lorem() -> usize {
866 fn lorem() -> usize {
875 fn lorem() -> usize { 42 }
877 fn lorem() -> usize {
883 See also [`control_brace_style`](#control_brace_style).
886 ## `where_single_line`
888 To force single line where layout
890 - **Default value**: `false`
891 - **Possible values**: `true`, `false`
894 #### `false` (default):
909 where Option<T>: Ipsum {
914 See also [`brace_style`](#brace_style), [`control_brace_style`](#control_brace_style).
917 ## `force_explicit_abi`
919 Always print the abi for extern items
921 - **Default value**: `true`
922 - **Possible values**: `true`, `false`
925 **Note:** Non-"C" ABIs are always printed. If `false` then "C" is removed.
927 #### `true` (default):
931 pub static lorem: c_int;
939 pub static lorem: c_int;
945 Format string literals where necessary
947 - **Default value**: `false`
948 - **Possible values**: `true`, `false`
951 #### `false` (default):
954 let lorem = "ipsum dolor sit amet consectetur adipiscing elit lorem ipsum dolor sit";
961 "ipsum dolor sit amet consectetur \
962 adipiscing elit lorem ipsum dolor sit";
965 See also [`max_width`](#max_width).
969 Use tab characters for indentation, spaces for alignment
971 - **Default value**: `false`
972 - **Possible values**: `true`, `false`
975 #### `false` (default):
978 fn lorem() -> usize {
979 42 // spaces before 42
986 fn lorem() -> usize {
991 See also: [`tab_spaces`](#tab_spaces).
996 Indent style of imports
998 - **Default Value**: `"Visual"`
999 - **Possible values**: `"Block"`, `"Visual"`
1002 #### `"Visual"` (default):
1020 See also: [`imports_layout`](#imports_layout).
1024 Item layout inside a imports block
1026 - **Default value**: "Mixed"
1027 - **Possible values**: "Horizontal", "HorizontalVertical", "Mixed", "Vertical"
1030 #### `"Mixed"` (default):
1033 use foo::{xxx, yyy, zzz};
1035 use foo::{aaa, bbb, ccc,
1039 #### `"Horizontal"`:
1041 **Note**: This option forces all imports onto one line and may exceed `max_width`.
1044 use foo::{xxx, yyy, zzz};
1046 use foo::{aaa, bbb, ccc, ddd, eee, fff};
1049 #### `"HorizontalVertical"`:
1052 use foo::{xxx, yyy, zzz};
1078 ## `match_block_trailing_comma`
1080 Put a trailing comma after a block based match arm (non-block arms are not affected)
1082 - **Default value**: `false`
1083 - **Possible values**: `true`, `false`
1086 #### `false` (default):
1093 Lorem::Dolor => println!("dolor"),
1104 Lorem::Dolor => println!("dolor"),
1108 See also: [`trailing_comma`](#trailing_comma), [`match_arm_blocks`](#match_arm_blocks).
1112 Maximum width of each line
1114 - **Default value**: `100`
1115 - **Possible values**: any positive integer
1118 See also [`error_on_line_overflow`](#error_on_line_overflow).
1122 Merge multiple derives into a single one.
1124 - **Default value**: `true`
1125 - **Possible values**: `true`, `false`
1128 #### `true` (default):
1131 #[derive(Eq, PartialEq, Debug, Copy, Clone)]
1138 #[derive(Eq, PartialEq)]
1140 #[derive(Copy, Clone)]
1144 ## `force_multiline_blocks`
1146 Force multiline closure and match arm bodies to be wrapped in a block
1148 - **Default value**: `false`
1149 - **Possible values**: `false`, `true`
1152 #### `false` (default):
1155 result.and_then(|maybe_value| match maybe_value {
1162 println!("Hello World");
1172 result.and_then(|maybe_value| {
1182 println!("Hello World");
1192 Unix or Windows line endings
1194 - **Default value**: `"Unix"`
1195 - **Possible values**: `"Native"`, `"Unix"`, `"Windows"`
1198 ## `normalize_comments`
1200 Convert /* */ comments to // comments where possible
1202 - **Default value**: `false`
1203 - **Possible values**: `true`, `false`
1206 #### `false` (default):
1210 fn dolor() -> usize {}
1213 fn adipiscing() -> usize {}
1220 fn dolor() -> usize {}
1223 fn adipiscing() -> usize {}
1226 ## `reorder_imported_names`
1228 Reorder lists of names in import statements alphabetically
1230 - **Default value**: `false`
1231 - **Possible values**: `true`, `false`
1234 #### `false` (default):
1237 use super::{lorem, ipsum, dolor, sit};
1243 use super::{dolor, ipsum, lorem, sit};
1246 See also [`reorder_imports`](#reorder_imports).
1248 ## `reorder_imports`
1250 Reorder import statements alphabetically
1252 - **Default value**: `false`
1253 - **Possible values**: `true`, `false`
1256 #### `false` (default):
1274 See also [`reorder_imported_names`](#reorder_imported_names), [`reorder_imports_in_group`](#reorder_imports_in_group).
1276 ## `reorder_imports_in_group`
1278 Reorder import statements in group
1280 - **Default value**: `false`
1281 - **Possible values**: `true`, `false`
1284 **Note:** This option takes effect only when [`reorder_imports`](#reorder_imports) is set to `true`.
1286 #### `false` (default):
1310 See also [`reorder_imports`](#reorder_imports).
1312 ## `reorder_extern_crates`
1314 Reorder `extern crate` statements alphabetically
1316 - **Default value**: `true`
1317 - **Possible values**: `true`, `false`
1320 #### `true` (default):
1338 See also [`reorder_extern_crates_in_group`](#reorder_extern_crates_in_group).
1340 ## `reorder_extern_crates_in_group`
1342 Reorder `extern crate` statements in group
1344 - **Default value**: `true`
1345 - **Possible values**: `true`, `false`
1348 **Note:** This option takes effect only when [`reorder_imports`](#reorder_imports) is set to `true`.
1350 #### `true` (default):
1374 See also [`reorder_extern_crates`](#reorder_extern_crates).
1378 Report `TODO` items in comments.
1380 - **Default value**: `"Never"`
1381 - **Possible values**: `"Always"`, `"Unnumbered"`, `"Never"`
1384 Warns about any comments containing `TODO` in them when set to `"Always"`. If
1385 it contains a `#X` (with `X` being a number) in parentheses following the
1386 `TODO`, `"Unnumbered"` will ignore it.
1388 See also [`report_fixme`](#report_fixme).
1392 Report `FIXME` items in comments.
1394 - **Default value**: `"Never"`
1395 - **Possible values**: `"Always"`, `"Unnumbered"`, `"Never"`
1398 Warns about any comments containing `FIXME` in them when set to `"Always"`. If
1399 it contains a `#X` (with `X` being a number) in parentheses following the
1400 `FIXME`, `"Unnumbered"` will ignore it.
1402 See also [`report_todo`](#report_todo).
1407 Don't reformat out of line modules
1409 - **Default value**: `false`
1410 - **Possible values**: `true`, `false`
1413 ## `space_after_colon`
1415 Leave a space after the colon.
1417 - **Default value**: `true`
1418 - **Possible values**: `true`, `false`
1421 #### `true` (default):
1424 fn lorem<T: Eq>(t: T) {
1425 let lorem: Dolor = Lorem {
1435 fn lorem<T:Eq>(t:T) {
1436 let lorem:Dolor = Lorem {
1443 See also: [`space_before_colon`](#space_before_colon).
1445 ## `space_before_colon`
1447 Leave a space before the colon.
1449 - **Default value**: `false`
1450 - **Possible values**: `true`, `false`
1453 #### `false` (default):
1456 fn lorem<T: Eq>(t: T) {
1457 let lorem: Dolor = Lorem {
1467 fn lorem<T : Eq>(t : T) {
1468 let lorem : Dolor = Lorem {
1475 See also: [`space_after_colon`](#space_after_colon).
1477 ## `struct_field_align_threshold`
1479 The maximum diff of width between struct fields to be aligned with each other.
1481 - **Default value** : 0
1482 - **Possible values**: any positive integer
1505 ## `spaces_around_ranges`
1507 Put spaces around the .. and ... range operators
1509 - **Default value**: `false`
1510 - **Possible values**: `true`, `false`
1513 #### `false` (default):
1522 let lorem = 0 .. 10;
1525 ## `spaces_within_parens_and_brackets`
1527 Put spaces within non-empty generic arguments, parentheses, and square brackets
1529 - **Default value**: `false`
1530 - **Possible values**: `true`, `false`
1533 #### `false` (default):
1536 // generic arguments
1537 fn lorem<T: Eq>(t: T) {
1541 // non-empty parentheses
1542 fn lorem<T: Eq>(t: T) {
1543 let lorem = (ipsum, dolor);
1546 // non-empty square brackets
1547 let lorem: [usize; 2] = [ipsum, dolor];
1553 // generic arguments
1554 fn lorem< T: Eq >(t: T) {
1558 // non-empty parentheses
1559 fn lorem<T: Eq>( t: T ) {
1560 let lorem = ( ipsum, dolor );
1563 // non-empty square brackets
1564 let lorem: [ usize; 2 ] = [ ipsum, dolor ];
1567 ## `struct_lit_single_line`
1569 Put small struct literals on a single line
1571 - **Default value**: `true`
1572 - **Possible values**: `true`, `false`
1575 #### `true` (default):
1578 let lorem = Lorem { ipsum: dolor, sit: amet };
1590 See also: [`indent_style`](#indent_style).
1595 Number of spaces per tab
1597 - **Default value**: `4`
1598 - **Possible values**: any positive integer
1605 let ipsum = dolor();
1607 "amet consectetur adipiscing elit."
1616 let ipsum = dolor();
1618 "amet consectetur adipiscing elit."
1623 See also: [`hard_tabs`](#hard_tabs).
1628 How to handle trailing commas for lists
1630 - **Default value**: `"Vertical"`
1631 - **Possible values**: `"Always"`, `"Never"`, `"Vertical"`
1634 #### `"Vertical"` (default):
1637 let Lorem { ipsum, dolor, sit } = amet;
1651 let Lorem { ipsum, dolor, sit, } = amet;
1665 let Lorem { ipsum, dolor, sit } = amet;
1676 See also: [`match_block_trailing_comma`](#match_block_trailing_comma).
1678 ## `trailing_semicolon`
1680 Add trailing semicolon after break, continue and return
1682 - **Default value**: `true`
1683 - **Possible values**: `true`, `false`
1686 #### `true` (default):
1700 ## `type_punctuation_density`
1702 Determines if `+` or `=` are wrapped in spaces in the punctuation of types
1704 - **Default value**: `"Wide"`
1705 - **Possible values**: `"Compressed"`, `"Wide"`
1708 #### `"Wide"` (default):
1711 fn lorem<Ipsum: Dolor + Sit = Amet>() {
1716 #### `"Compressed"`:
1719 fn lorem<Ipsum: Dolor+Sit=Amet>() {
1724 ## `use_try_shorthand`
1726 Replace uses of the try! macro by the ? shorthand
1728 - **Default value**: `false`
1729 - **Possible values**: `true`, `false`
1732 #### `false` (default):
1735 let lorem = try!(ipsum.map(|dolor|dolor.sit()));
1741 let lorem = ipsum.map(|dolor| dolor.sit())?;
1747 Break comments to fit on the line
1749 - **Default value**: `false`
1750 - **Possible values**: `true`, `false`
1753 #### `false` (default):
1756 // 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.
1762 // Lorem ipsum dolor sit amet, consectetur adipiscing elit,
1763 // sed do eiusmod tempor incididunt ut labore et dolore
1764 // magna aliqua. Ut enim ad minim veniam, quis nostrud
1765 // exercitation ullamco laboris nisi ut aliquip ex ea
1766 // commodo consequat.
1769 ## `match_arm_blocks`
1771 Wrap the body of arms in blocks when it does not fit on the same line with the pattern of arms
1773 - **Default value**: `true`
1774 - **Possible values**: `true`, `false`
1777 #### `true` (default):
1782 foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x)
1784 false => println!("{}", sit),
1793 foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x),
1794 false => println!("{}", sit),
1798 See also: [`match_block_trailing_comma`](#match_block_trailing_comma).
1802 What Write Mode to use when none is supplied: Replace, Overwrite, Display, Diff, Coverage
1804 - **Default value**: `"Overwrite"`
1805 - **Possible values**: `"Checkstyle"`, `"Coverage"`, `"Diff"`, `"Display"`, `"Overwrite"`, `"Plain"`, `"Replace"`
1808 ## `blank_lines_upper_bound`
1810 Maximum number of blank lines which can be put between items. If more than this number of consecutive empty
1811 lines are found, they are trimmed down to match this integer.
1813 - **Default value**: `1`
1814 - **Possible values**: *unsigned integer*
1863 See also: [`blank_lines_lower_bound`](#blank_lines_lower_bound)
1865 ## `blank_lines_lower_bound`
1867 Minimum number of blank lines which must be put between items. If two items have fewer blank lines between
1868 them, additional blank lines are inserted.
1870 - **Default value**: `0`
1871 - **Possible values**: *unsigned integer*
1875 Original Code (rustfmt will not change it with the default value of `0`):