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);
516 let (lorem, ipsum, ..) = (1, 2, 3, 4);
519 ## `control_brace_style`
521 Brace style for control flow constructs
523 - **Default value**: `"AlwaysSameLine"`
524 - **Possible values**: `"AlwaysNextLine"`, `"AlwaysSameLine"`, `"ClosingNextLine"`
527 #### `"AlwaysSameLine"` (default):
537 #### `"AlwaysNextLine"`:
550 #### `"ClosingNextLine"`:
561 ## `disable_all_formatting`
563 Don't reformat anything
565 - **Default value**: `false`
566 - **Possible values**: `true`, `false`
569 ## `error_on_line_overflow`
571 Error if unable to get all lines within `max_width`
573 - **Default value**: `true`
574 - **Possible values**: `true`, `false`
577 See also [`max_width`](#max_width).
579 ## `error_on_line_overflow_comments`
581 Error if unable to get all comment lines within `comment_width`.
583 - **Default value**: `true`
584 - **Possible values**: `true`, `false`
587 See also [`comment_width`](#comment_width).
591 Argument density in functions
593 - **Default value**: `"Tall"`
594 - **Possible values**: `"Compressed"`, `"Tall"`, `"Vertical"`
597 #### `"Tall"` (default):
601 fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet);
603 fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet) {
612 consectetur: Consectetur,
613 adipiscing: Adipiscing,
622 consectetur: Consectetur,
623 adipiscing: Adipiscing,
635 fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet);
637 fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet) {
642 ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet, consectetur: Consectetur,
643 adipiscing: Adipiscing, elit: Elit,
647 ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet, consectetur: Consectetur,
648 adipiscing: Adipiscing, elit: Elit,
659 fn lorem(ipsum: Ipsum,
664 fn lorem(ipsum: Ipsum,
671 fn lorem(ipsum: Ipsum,
675 consectetur: Consectetur,
676 adipiscing: Adipiscing,
679 fn lorem(ipsum: Ipsum,
683 consectetur: Consectetur,
684 adipiscing: Adipiscing,
694 Brace style for items
696 - **Default value**: `"SameLineWhere"`
697 - **Possible values**: `"AlwaysNextLine"`, `"PreferSameLine"`, `"SameLineWhere"`
702 #### `"SameLineWhere"` (default):
709 fn lorem(ipsum: usize) {
713 fn lorem<T>(ipsum: T)
715 T: Add + Sub + Mul + Div,
721 #### `"AlwaysNextLine"`:
729 fn lorem(ipsum: usize)
734 fn lorem<T>(ipsum: T)
736 T: Add + Sub + Mul + Div,
742 #### `"PreferSameLine"`:
749 fn lorem(ipsum: usize) {
753 fn lorem<T>(ipsum: T)
755 T: Add + Sub + Mul + Div, {
760 ### Structs and enums
762 #### `"SameLineWhere"` (default):
776 #### `"AlwaysNextLine"`:
791 #### `"PreferSameLine"`:
805 ## `empty_item_single_line`
807 Put empty-body functions and impls on a single line
809 - **Default value**: `true`
810 - **Possible values**: `true`, `false`
813 #### `true` (default):
831 See also [`brace_style`](#brace_style), [`control_brace_style`](#control_brace_style).
836 Put single-expression functions on a single line
838 - **Default value**: `false`
839 - **Possible values**: `true`, `false`
842 #### `false` (default):
845 fn lorem() -> usize {
849 fn lorem() -> usize {
858 fn lorem() -> usize { 42 }
860 fn lorem() -> usize {
866 See also [`control_brace_style`](#control_brace_style).
869 ## `where_single_line`
871 To force single line where layout
873 - **Default value**: `false`
874 - **Possible values**: `true`, `false`
877 #### `false` (default):
892 where Option<T>: Ipsum {
897 See also [`brace_style`](#brace_style), [`control_brace_style`](#control_brace_style).
900 ## `force_explicit_abi`
902 Always print the abi for extern items
904 - **Default value**: `true`
905 - **Possible values**: `true`, `false`
908 **Note:** Non-"C" ABIs are always printed. If `false` then "C" is removed.
910 #### `true` (default):
914 pub static lorem: c_int;
922 pub static lorem: c_int;
928 Format string literals where necessary
930 - **Default value**: `false`
931 - **Possible values**: `true`, `false`
934 #### `false` (default):
937 let lorem = "ipsum dolor sit amet consectetur adipiscing elit lorem ipsum dolor sit";
944 "ipsum dolor sit amet consectetur \
945 adipiscing elit lorem ipsum dolor sit";
948 See also [`max_width`](#max_width).
952 Use tab characters for indentation, spaces for alignment
954 - **Default value**: `false`
955 - **Possible values**: `true`, `false`
958 #### `false` (default):
961 fn lorem() -> usize {
962 42 // spaces before 42
969 fn lorem() -> usize {
974 See also: [`tab_spaces`](#tab_spaces).
979 Indent style of imports
981 - **Default Value**: `"Visual"`
982 - **Possible values**: `"Block"`, `"Visual"`
985 #### `"Visual"` (default):
1003 See also: [`imports_layout`](#imports_layout).
1007 Item layout inside a imports block
1009 - **Default value**: "Mixed"
1010 - **Possible values**: "Horizontal", "HorizontalVertical", "Mixed", "Vertical"
1013 #### `"Mixed"` (default):
1016 use foo::{xxx, yyy, zzz};
1018 use foo::{aaa, bbb, ccc,
1022 #### `"Horizontal"`:
1024 **Note**: This option forces all imports onto one line and may exceed `max_width`.
1027 use foo::{xxx, yyy, zzz};
1029 use foo::{aaa, bbb, ccc, ddd, eee, fff};
1032 #### `"HorizontalVertical"`:
1035 use foo::{xxx, yyy, zzz};
1061 ## `match_block_trailing_comma`
1063 Put a trailing comma after a block based match arm (non-block arms are not affected)
1065 - **Default value**: `false`
1066 - **Possible values**: `true`, `false`
1069 #### `false` (default):
1076 Lorem::Dolor => println!("dolor"),
1087 Lorem::Dolor => println!("dolor"),
1091 See also: [`trailing_comma`](#trailing_comma), [`match_arm_blocks`](#match_arm_blocks).
1095 Maximum width of each line
1097 - **Default value**: `100`
1098 - **Possible values**: any positive integer
1101 See also [`error_on_line_overflow`](#error_on_line_overflow).
1105 Merge multiple derives into a single one.
1107 - **Default value**: `true`
1108 - **Possible values**: `true`, `false`
1111 #### `true` (default):
1114 #[derive(Eq, PartialEq, Debug, Copy, Clone)]
1121 #[derive(Eq, PartialEq)]
1123 #[derive(Copy, Clone)]
1127 ## `force_multiline_blocks`
1129 Force multiline closure and match arm bodies to be wrapped in a block
1131 - **Default value**: `false`
1132 - **Possible values**: `false`, `true`
1135 #### `false` (default):
1138 result.and_then(|maybe_value| match maybe_value {
1145 println!("Hello World");
1155 result.and_then(|maybe_value| {
1165 println!("Hello World");
1175 Unix or Windows line endings
1177 - **Default value**: `"Unix"`
1178 - **Possible values**: `"Native"`, `"Unix"`, `"Windows"`
1181 ## `normalize_comments`
1183 Convert /* */ comments to // comments where possible
1185 - **Default value**: `false`
1186 - **Possible values**: `true`, `false`
1189 #### `false` (default):
1193 fn dolor() -> usize {}
1196 fn adipiscing() -> usize {}
1203 fn dolor() -> usize {}
1206 fn adipiscing() -> usize {}
1209 ## `reorder_imported_names`
1211 Reorder lists of names in import statements alphabetically
1213 - **Default value**: `false`
1214 - **Possible values**: `true`, `false`
1217 #### `false` (default):
1220 use super::{lorem, ipsum, dolor, sit};
1226 use super::{dolor, ipsum, lorem, sit};
1229 See also [`reorder_imports`](#reorder_imports).
1231 ## `reorder_imports`
1233 Reorder import statements alphabetically
1235 - **Default value**: `false`
1236 - **Possible values**: `true`, `false`
1239 #### `false` (default):
1257 See also [`reorder_imported_names`](#reorder_imported_names), [`reorder_imports_in_group`](#reorder_imports_in_group).
1259 ## `reorder_imports_in_group`
1261 Reorder import statements in group
1263 - **Default value**: `false`
1264 - **Possible values**: `true`, `false`
1267 **Note:** This option takes effect only when [`reorder_imports`](#reorder_imports) is set to `true`.
1269 #### `false` (default):
1293 See also [`reorder_imports`](#reorder_imports).
1295 ## `reorder_extern_crates`
1297 Reorder `extern crate` statements alphabetically
1299 - **Default value**: `true`
1300 - **Possible values**: `true`, `false`
1303 #### `true` (default):
1321 See also [`reorder_extern_crates_in_group`](#reorder_extern_crates_in_group).
1323 ## `reorder_extern_crates_in_group`
1325 Reorder `extern crate` statements in group
1327 - **Default value**: `true`
1328 - **Possible values**: `true`, `false`
1331 **Note:** This option takes effect only when [`reorder_imports`](#reorder_imports) is set to `true`.
1333 #### `true` (default):
1357 See also [`reorder_extern_crates`](#reorder_extern_crates).
1361 Report `TODO` items in comments.
1363 - **Default value**: `"Never"`
1364 - **Possible values**: `"Always"`, `"Unnumbered"`, `"Never"`
1367 Warns about any comments containing `TODO` in them when set to `"Always"`. If
1368 it contains a `#X` (with `X` being a number) in parentheses following the
1369 `TODO`, `"Unnumbered"` will ignore it.
1371 See also [`report_fixme`](#report_fixme).
1375 Report `FIXME` items in comments.
1377 - **Default value**: `"Never"`
1378 - **Possible values**: `"Always"`, `"Unnumbered"`, `"Never"`
1381 Warns about any comments containing `FIXME` in them when set to `"Always"`. If
1382 it contains a `#X` (with `X` being a number) in parentheses following the
1383 `FIXME`, `"Unnumbered"` will ignore it.
1385 See also [`report_todo`](#report_todo).
1390 Don't reformat out of line modules
1392 - **Default value**: `false`
1393 - **Possible values**: `true`, `false`
1396 ## `space_after_colon`
1398 Leave a space after the colon.
1400 - **Default value**: `true`
1401 - **Possible values**: `true`, `false`
1404 #### `true` (default):
1407 fn lorem<T: Eq>(t: T) {
1408 let lorem: Dolor = Lorem {
1418 fn lorem<T:Eq>(t:T) {
1419 let lorem:Dolor = Lorem {
1426 See also: [`space_before_colon`](#space_before_colon).
1428 ## `space_before_colon`
1430 Leave a space before the colon.
1432 - **Default value**: `false`
1433 - **Possible values**: `true`, `false`
1436 #### `false` (default):
1439 fn lorem<T: Eq>(t: T) {
1440 let lorem: Dolor = Lorem {
1450 fn lorem<T : Eq>(t : T) {
1451 let lorem : Dolor = Lorem {
1458 See also: [`space_after_colon`](#space_after_colon).
1460 ## `struct_field_align_threshold`
1462 The maximum diff of width between struct fields to be aligned with each other.
1464 - **Default value** : 0
1465 - **Possible values**: any positive integer
1488 ## `spaces_around_ranges`
1490 Put spaces around the .. and ... range operators
1492 - **Default value**: `false`
1493 - **Possible values**: `true`, `false`
1496 #### `false` (default):
1505 let lorem = 0 .. 10;
1508 ## `spaces_within_parens_and_brackets`
1510 Put spaces within non-empty generic arguments, parentheses, and square brackets
1512 - **Default value**: `false`
1513 - **Possible values**: `true`, `false`
1516 #### `false` (default):
1519 // generic arguments
1520 fn lorem<T: Eq>(t: T) {
1524 // non-empty parentheses
1525 fn lorem<T: Eq>(t: T) {
1526 let lorem = (ipsum, dolor);
1529 // non-empty square brackets
1530 let lorem: [usize; 2] = [ipsum, dolor];
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 ];
1550 ## `struct_lit_single_line`
1552 Put small struct literals on a single line
1554 - **Default value**: `true`
1555 - **Possible values**: `true`, `false`
1558 #### `true` (default):
1561 let lorem = Lorem { ipsum: dolor, sit: amet };
1573 See also: [`indent_style`](#indent_style).
1578 Number of spaces per tab
1580 - **Default value**: `4`
1581 - **Possible values**: any positive integer
1588 let ipsum = dolor();
1590 "amet consectetur adipiscing elit."
1599 let ipsum = dolor();
1601 "amet consectetur adipiscing elit."
1606 See also: [`hard_tabs`](#hard_tabs).
1611 How to handle trailing commas for lists
1613 - **Default value**: `"Vertical"`
1614 - **Possible values**: `"Always"`, `"Never"`, `"Vertical"`
1617 #### `"Vertical"` (default):
1620 let Lorem { ipsum, dolor, sit } = amet;
1634 let Lorem { ipsum, dolor, sit, } = amet;
1648 let Lorem { ipsum, dolor, sit } = amet;
1659 See also: [`match_block_trailing_comma`](#match_block_trailing_comma).
1661 ## `trailing_semicolon`
1663 Add trailing semicolon after break, continue and return
1665 - **Default value**: `true`
1666 - **Possible values**: `true`, `false`
1669 #### `true` (default):
1683 ## `type_punctuation_density`
1685 Determines if `+` or `=` are wrapped in spaces in the punctuation of types
1687 - **Default value**: `"Wide"`
1688 - **Possible values**: `"Compressed"`, `"Wide"`
1691 #### `"Wide"` (default):
1694 fn lorem<Ipsum: Dolor + Sit = Amet>() {
1699 #### `"Compressed"`:
1702 fn lorem<Ipsum: Dolor+Sit=Amet>() {
1707 ## `use_try_shorthand`
1709 Replace uses of the try! macro by the ? shorthand
1711 - **Default value**: `false`
1712 - **Possible values**: `true`, `false`
1715 #### `false` (default):
1718 let lorem = try!(ipsum.map(|dolor|dolor.sit()));
1724 let lorem = ipsum.map(|dolor| dolor.sit())?;
1730 Break comments to fit on the line
1732 - **Default value**: `false`
1733 - **Possible values**: `true`, `false`
1736 #### `false` (default):
1739 // 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.
1745 // Lorem ipsum dolor sit amet, consectetur adipiscing elit,
1746 // sed do eiusmod tempor incididunt ut labore et dolore
1747 // magna aliqua. Ut enim ad minim veniam, quis nostrud
1748 // exercitation ullamco laboris nisi ut aliquip ex ea
1749 // commodo consequat.
1752 ## `match_arm_blocks`
1754 Wrap the body of arms in blocks when it does not fit on the same line with the pattern of arms
1756 - **Default value**: `true`
1757 - **Possible values**: `true`, `false`
1760 #### `true` (default):
1765 foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x)
1767 false => println!("{}", sit),
1776 foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x),
1777 false => println!("{}", sit),
1781 See also: [`match_block_trailing_comma`](#match_block_trailing_comma).
1785 What Write Mode to use when none is supplied: Replace, Overwrite, Display, Diff, Coverage
1787 - **Default value**: `"Overwrite"`
1788 - **Possible values**: `"Checkstyle"`, `"Coverage"`, `"Diff"`, `"Display"`, `"Overwrite"`, `"Plain"`, `"Replace"`
1791 ## `blank_lines_upper_bound`
1793 Maximum number of blank lines which can be put between items. If more than this number of consecutive empty
1794 lines are found, they are trimmed down to match this integer.
1796 - **Default value**: `1`
1797 - **Possible values**: *unsigned integer*
1846 See also: [`blank_lines_lower_bound`](#blank_lines_lower_bound)
1848 ## `blank_lines_lower_bound`
1850 Minimum number of blank lines which must be put between items. If two items have fewer blank lines between
1851 them, additional blank lines are inserted.
1853 - **Default value**: `0`
1854 - **Possible values**: *unsigned integer*
1858 Original Code (rustfmt will not change it with the default value of `0`):