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):
222 let lorem = Lorem { ipsum: dolor,
226 See also: [`struct_lit_single_line`](#struct_lit_single_line), [`indent_style`](#indent_style).
230 #### `"Block"` (default):
233 fn lorem<Ipsum, Dolor, Sit, Amet>() -> T
247 fn lorem<Ipsum, Dolor, Sit, Amet>() -> T
257 ## `use_small_heuristics`
259 Whether to use different formatting for items and expressions if they satisfy a heuristic notion of 'small'.
261 - **Default value**: `true`
262 - **Possible values**: `true`, `false`
265 #### `true` (default):
271 Sit { amet: Consectetur, adipiscing: Elit },
285 let lorem = Lorem { ipsum: dolor, sit: amet };
287 let lorem = if ipsum { dolor } else { sit };
304 lorem("lorem", "ipsum", "dolor", "sit", "amet", "consectetur", "adipiscing");
311 let lorem = if ipsum {
321 Where to put a binary operator when a binary expression goes multiline.
323 - **Default value**: `"Front"`
324 - **Possible values**: `"Front"`, `"Back"`
327 #### `"Front"` (default):
338 let range = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
339 ..bbbbbbbbbbbbbbbbbbbbbbbbbbbbb;
346 let or = foofoofoofoofoofoofoofoofoofoofoofoofoofoofoofoo ||
347 barbarbarbarbarbarbarbarbarbarbarbarbarbarbarbar;
349 let sum = 123456789012345678901234567890 + 123456789012345678901234567890 +
350 123456789012345678901234567890;
352 let range = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa..
353 bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb;
357 ## `combine_control_expr`
359 Combine control expressions with function calls.
361 - **Default value**: `true`
362 - **Possible values**: `true`, `false`
365 #### `true` (default):
377 foo!(if let Some(..) = x {
390 foo!(while let Some(..) = x {
424 if let Some(..) = x {
441 while let Some(..) = x {
467 Maximum length of comments. No effect unless`wrap_comments = true`.
469 - **Default value**: `80`
470 - **Possible values**: any positive integer
473 **Note:** A value of `0` results in [`wrap_comments`](#wrap_comments) being applied regardless of a line's width.
475 #### `80` (default; comments shorter than `comment_width`):
477 // Lorem ipsum dolor sit amet, consectetur adipiscing elit.
480 #### `60` (comments longer than `comment_width`):
482 // Lorem ipsum dolor sit amet,
483 // consectetur adipiscing elit.
486 See also [`wrap_comments`](#wrap_comments).
488 ## `condense_wildcard_suffixes`
490 Replace strings of _ wildcards by a single .. in tuple patterns
492 - **Default value**: `false`
493 - **Possible values**: `true`, `false`
496 #### `false` (default):
499 let (lorem, ipsum, _, _) = (1, 2, 3, 4);
505 let (lorem, ipsum, ..) = (1, 2, 3, 4);
508 ## `control_brace_style`
510 Brace style for control flow constructs
512 - **Default value**: `"AlwaysSameLine"`
513 - **Possible values**: `"AlwaysNextLine"`, `"AlwaysSameLine"`, `"ClosingNextLine"`
516 #### `"AlwaysSameLine"` (default):
526 #### `"AlwaysNextLine"`:
539 #### `"ClosingNextLine"`:
550 ## `disable_all_formatting`
552 Don't reformat anything
554 - **Default value**: `false`
555 - **Possible values**: `true`, `false`
558 ## `error_on_line_overflow`
560 Error if unable to get all lines within `max_width`
562 - **Default value**: `true`
563 - **Possible values**: `true`, `false`
566 See also [`max_width`](#max_width).
568 ## `error_on_line_overflow_comments`
570 Error if unable to get all comment lines within `comment_width`.
572 - **Default value**: `true`
573 - **Possible values**: `true`, `false`
576 See also [`comment_width`](#comment_width).
580 Argument density in functions
582 - **Default value**: `"Tall"`
583 - **Possible values**: `"Compressed"`, `"Tall"`, `"Vertical"`
586 #### `"Tall"` (default):
590 fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet);
592 fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet) {
601 consectetur: Consectetur,
602 adipiscing: Adipiscing,
611 consectetur: Consectetur,
612 adipiscing: Adipiscing,
624 fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet);
626 fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet) {
631 ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet, consectetur: Consectetur,
632 adipiscing: Adipiscing, elit: Elit,
636 ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet, consectetur: Consectetur,
637 adipiscing: Adipiscing, elit: Elit,
648 fn lorem(ipsum: Ipsum,
653 fn lorem(ipsum: Ipsum,
660 fn lorem(ipsum: Ipsum,
664 consectetur: Consectetur,
665 adipiscing: Adipiscing,
668 fn lorem(ipsum: Ipsum,
672 consectetur: Consectetur,
673 adipiscing: Adipiscing,
683 Brace style for items
685 - **Default value**: `"SameLineWhere"`
686 - **Possible values**: `"AlwaysNextLine"`, `"PreferSameLine"`, `"SameLineWhere"`
691 #### `"SameLineWhere"` (default):
698 fn lorem(ipsum: usize) {
702 fn lorem<T>(ipsum: T)
704 T: Add + Sub + Mul + Div,
710 #### `"AlwaysNextLine"`:
718 fn lorem(ipsum: usize)
723 fn lorem<T>(ipsum: T)
725 T: Add + Sub + Mul + Div,
731 #### `"PreferSameLine"`:
738 fn lorem(ipsum: usize) {
742 fn lorem<T>(ipsum: T)
744 T: Add + Sub + Mul + Div, {
749 ### Structs and enums
751 #### `"SameLineWhere"` (default):
765 #### `"AlwaysNextLine"`:
780 #### `"PreferSameLine"`:
794 ## `empty_item_single_line`
796 Put empty-body functions and impls on a single line
798 - **Default value**: `true`
799 - **Possible values**: `true`, `false`
802 #### `true` (default):
820 See also [`brace_style`](#brace_style), [`control_brace_style`](#control_brace_style).
825 Put single-expression functions on a single line
827 - **Default value**: `false`
828 - **Possible values**: `true`, `false`
831 #### `false` (default):
834 fn lorem() -> usize {
838 fn lorem() -> usize {
847 fn lorem() -> usize { 42 }
849 fn lorem() -> usize {
855 See also [`control_brace_style`](#control_brace_style).
858 ## `where_single_line`
860 To force single line where layout
862 - **Default value**: `false`
863 - **Possible values**: `true`, `false`
866 #### `false` (default):
881 where Option<T>: Ipsum {
886 See also [`brace_style`](#brace_style), [`control_brace_style`](#control_brace_style).
889 ## `force_explicit_abi`
891 Always print the abi for extern items
893 - **Default value**: `true`
894 - **Possible values**: `true`, `false`
897 **Note:** Non-"C" ABIs are always printed. If `false` then "C" is removed.
899 #### `true` (default):
903 pub static lorem: c_int;
911 pub static lorem: c_int;
917 Format string literals where necessary
919 - **Default value**: `false`
920 - **Possible values**: `true`, `false`
923 #### `false` (default):
926 let lorem = "ipsum dolor sit amet consectetur adipiscing elit lorem ipsum dolor sit";
933 "ipsum dolor sit amet consectetur \
934 adipiscing elit lorem ipsum dolor sit";
937 See also [`max_width`](#max_width).
941 Use tab characters for indentation, spaces for alignment
943 - **Default value**: `false`
944 - **Possible values**: `true`, `false`
947 #### `false` (default):
950 fn lorem() -> usize {
951 42 // spaces before 42
958 fn lorem() -> usize {
963 See also: [`tab_spaces`](#tab_spaces).
968 Indent style of imports
970 - **Default Value**: `"Visual"`
971 - **Possible values**: `"Block"`, `"Visual"`
974 #### `"Visual"` (default):
992 See also: [`imports_layout`](#imports_layout).
996 Item layout inside a imports block
998 - **Default value**: "Mixed"
999 - **Possible values**: "Horizontal", "HorizontalVertical", "Mixed", "Vertical"
1002 #### `"Mixed"` (default):
1005 use foo::{xxx, yyy, zzz};
1007 use foo::{aaa, bbb, ccc,
1011 #### `"Horizontal"`:
1013 **Note**: This option forces all imports onto one line and may exceed `max_width`.
1016 use foo::{xxx, yyy, zzz};
1018 use foo::{aaa, bbb, ccc, ddd, eee, fff};
1021 #### `"HorizontalVertical"`:
1024 use foo::{xxx, yyy, zzz};
1050 ## `match_block_trailing_comma`
1052 Put a trailing comma after a block based match arm (non-block arms are not affected)
1054 - **Default value**: `false`
1055 - **Possible values**: `true`, `false`
1058 #### `false` (default):
1065 Lorem::Dolor => println!("dolor"),
1076 Lorem::Dolor => println!("dolor"),
1080 See also: [`trailing_comma`](#trailing_comma), [`match_arm_blocks`](#match_arm_blocks).
1084 Maximum width of each line
1086 - **Default value**: `100`
1087 - **Possible values**: any positive integer
1090 See also [`error_on_line_overflow`](#error_on_line_overflow).
1094 Merge multiple derives into a single one.
1096 - **Default value**: `true`
1097 - **Possible values**: `true`, `false`
1100 #### `true` (default):
1103 #[derive(Eq, PartialEq, Debug, Copy, Clone)]
1110 #[derive(Eq, PartialEq)]
1112 #[derive(Copy, Clone)]
1116 ## `force_multiline_blocks`
1118 Force multiline closure and match arm bodies to be wrapped in a block
1120 - **Default value**: `false`
1121 - **Possible values**: `false`, `true`
1124 #### `false` (default):
1127 result.and_then(|maybe_value| match maybe_value {
1134 println!("Hello World");
1144 result.and_then(|maybe_value| {
1154 println!("Hello World");
1164 Unix or Windows line endings
1166 - **Default value**: `"Unix"`
1167 - **Possible values**: `"Native"`, `"Unix"`, `"Windows"`
1170 ## `normalize_comments`
1172 Convert /* */ comments to // comments where possible
1174 - **Default value**: `false`
1175 - **Possible values**: `true`, `false`
1178 #### `false` (default):
1182 fn dolor() -> usize {}
1185 fn adipiscing() -> usize {}
1192 fn dolor() -> usize {}
1195 fn adipiscing() -> usize {}
1198 ## `reorder_imported_names`
1200 Reorder lists of names in import statements alphabetically
1202 - **Default value**: `false`
1203 - **Possible values**: `true`, `false`
1206 #### `false` (default):
1209 use super::{lorem, ipsum, dolor, sit};
1215 use super::{dolor, ipsum, lorem, sit};
1218 See also [`reorder_imports`](#reorder_imports).
1220 ## `reorder_imports`
1222 Reorder import statements alphabetically
1224 - **Default value**: `false`
1225 - **Possible values**: `true`, `false`
1228 #### `false` (default):
1246 See also [`reorder_imported_names`](#reorder_imported_names), [`reorder_imports_in_group`](#reorder_imports_in_group).
1248 ## `reorder_imports_in_group`
1250 Reorder import statements in group
1252 - **Default value**: `false`
1253 - **Possible values**: `true`, `false`
1256 **Note:** This option takes effect only when [`reorder_imports`](#reorder_imports) is set to `true`.
1258 #### `false` (default):
1282 See also [`reorder_imports`](#reorder_imports).
1284 ## `reorder_extern_crates`
1286 Reorder `extern crate` statements alphabetically
1288 - **Default value**: `true`
1289 - **Possible values**: `true`, `false`
1292 #### `true` (default):
1310 See also [`reorder_extern_crates_in_group`](#reorder_extern_crates_in_group).
1312 ## `reorder_extern_crates_in_group`
1314 Reorder `extern crate` statements in group
1316 - **Default value**: `true`
1317 - **Possible values**: `true`, `false`
1320 **Note:** This option takes effect only when [`reorder_imports`](#reorder_imports) is set to `true`.
1322 #### `true` (default):
1346 See also [`reorder_extern_crates`](#reorder_extern_crates).
1350 Report `TODO` items in comments.
1352 - **Default value**: `"Never"`
1353 - **Possible values**: `"Always"`, `"Unnumbered"`, `"Never"`
1356 Warns about any comments containing `TODO` in them when set to `"Always"`. If
1357 it contains a `#X` (with `X` being a number) in parentheses following the
1358 `TODO`, `"Unnumbered"` will ignore it.
1360 See also [`report_fixme`](#report_fixme).
1364 Report `FIXME` items in comments.
1366 - **Default value**: `"Never"`
1367 - **Possible values**: `"Always"`, `"Unnumbered"`, `"Never"`
1370 Warns about any comments containing `FIXME` in them when set to `"Always"`. If
1371 it contains a `#X` (with `X` being a number) in parentheses following the
1372 `FIXME`, `"Unnumbered"` will ignore it.
1374 See also [`report_todo`](#report_todo).
1379 Don't reformat out of line modules
1381 - **Default value**: `false`
1382 - **Possible values**: `true`, `false`
1385 ## `space_after_colon`
1387 Leave a space after the colon.
1389 - **Default value**: `true`
1390 - **Possible values**: `true`, `false`
1393 #### `true` (default):
1396 fn lorem<T: Eq>(t: T) {
1397 let lorem: Dolor = Lorem {
1407 fn lorem<T:Eq>(t:T) {
1408 let lorem:Dolor = Lorem {
1415 See also: [`space_before_colon`](#space_before_colon).
1417 ## `space_before_colon`
1419 Leave a space before the colon.
1421 - **Default value**: `false`
1422 - **Possible values**: `true`, `false`
1425 #### `false` (default):
1428 fn lorem<T: Eq>(t: T) {
1429 let lorem: Dolor = Lorem {
1439 fn lorem<T : Eq>(t : T) {
1440 let lorem : Dolor = Lorem {
1447 See also: [`space_after_colon`](#space_after_colon).
1449 ## `struct_field_align_threshold`
1451 The maximum diff of width between struct fields to be aligned with each other.
1453 - **Default value** : 0
1454 - **Possible values**: any positive integer
1477 ## `spaces_around_ranges`
1479 Put spaces around the .. and ... range operators
1481 - **Default value**: `false`
1482 - **Possible values**: `true`, `false`
1485 #### `false` (default):
1494 let lorem = 0 .. 10;
1497 ## `spaces_within_parens_and_brackets`
1499 Put spaces within non-empty generic arguments, parentheses, and square brackets
1501 - **Default value**: `false`
1502 - **Possible values**: `true`, `false`
1505 #### `false` (default):
1508 // generic arguments
1509 fn lorem<T: Eq>(t: T) {
1513 // non-empty parentheses
1514 fn lorem<T: Eq>(t: T) {
1515 let lorem = (ipsum, dolor);
1518 // non-empty square brackets
1519 let lorem: [usize; 2] = [ipsum, dolor];
1525 // generic arguments
1526 fn lorem< T: Eq >(t: T) {
1530 // non-empty parentheses
1531 fn lorem<T: Eq>( t: T ) {
1532 let lorem = ( ipsum, dolor );
1535 // non-empty square brackets
1536 let lorem: [ usize; 2 ] = [ ipsum, dolor ];
1539 ## `struct_lit_single_line`
1541 Put small struct literals on a single line
1543 - **Default value**: `true`
1544 - **Possible values**: `true`, `false`
1547 #### `true` (default):
1550 let lorem = Lorem { ipsum: dolor, sit: amet };
1562 See also: [`indent_style`](#indent_style).
1567 Number of spaces per tab
1569 - **Default value**: `4`
1570 - **Possible values**: any positive integer
1577 let ipsum = dolor();
1579 "amet consectetur adipiscing elit."
1588 let ipsum = dolor();
1590 "amet consectetur adipiscing elit."
1595 See also: [`hard_tabs`](#hard_tabs).
1600 How to handle trailing commas for lists
1602 - **Default value**: `"Vertical"`
1603 - **Possible values**: `"Always"`, `"Never"`, `"Vertical"`
1606 #### `"Vertical"` (default):
1609 let Lorem { ipsum, dolor, sit } = amet;
1623 let Lorem { ipsum, dolor, sit, } = amet;
1637 let Lorem { ipsum, dolor, sit } = amet;
1648 See also: [`match_block_trailing_comma`](#match_block_trailing_comma).
1650 ## `trailing_semicolon`
1652 Add trailing semicolon after break, continue and return
1654 - **Default value**: `true`
1655 - **Possible values**: `true`, `false`
1658 #### `true` (default):
1672 ## `type_punctuation_density`
1674 Determines if `+` or `=` are wrapped in spaces in the punctuation of types
1676 - **Default value**: `"Wide"`
1677 - **Possible values**: `"Compressed"`, `"Wide"`
1680 #### `"Wide"` (default):
1683 fn lorem<Ipsum: Dolor + Sit = Amet>() {
1688 #### `"Compressed"`:
1691 fn lorem<Ipsum: Dolor+Sit=Amet>() {
1696 ## `use_try_shorthand`
1698 Replace uses of the try! macro by the ? shorthand
1700 - **Default value**: `false`
1701 - **Possible values**: `true`, `false`
1704 #### `false` (default):
1707 let lorem = try!(ipsum.map(|dolor|dolor.sit()));
1713 let lorem = ipsum.map(|dolor| dolor.sit())?;
1719 Break comments to fit on the line
1721 - **Default value**: `false`
1722 - **Possible values**: `true`, `false`
1725 #### `false` (default):
1728 // 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.
1734 // Lorem ipsum dolor sit amet, consectetur adipiscing elit,
1735 // sed do eiusmod tempor incididunt ut labore et dolore
1736 // magna aliqua. Ut enim ad minim veniam, quis nostrud
1737 // exercitation ullamco laboris nisi ut aliquip ex ea
1738 // commodo consequat.
1741 ## `match_arm_blocks`
1743 Wrap the body of arms in blocks when it does not fit on the same line with the pattern of arms
1745 - **Default value**: `true`
1746 - **Possible values**: `true`, `false`
1749 #### `true` (default):
1754 foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x)
1756 false => println!("{}", sit),
1765 foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x),
1766 false => println!("{}", sit),
1770 See also: [`match_block_trailing_comma`](#match_block_trailing_comma).
1774 What Write Mode to use when none is supplied: Replace, Overwrite, Display, Diff, Coverage
1776 - **Default value**: `"Overwrite"`
1777 - **Possible values**: `"Checkstyle"`, `"Coverage"`, `"Diff"`, `"Display"`, `"Overwrite"`, `"Plain"`, `"Replace"`
1780 ## `blank_lines_upper_bound`
1782 Maximum number of blank lines which can be put between items. If more than this number of consecutive empty
1783 lines are found, they are trimmed down to match this integer.
1785 - **Default value**: `1`
1786 - **Possible values**: *unsigned integer*
1835 See also: [`blank_lines_lower_bound`](#blank_lines_lower_bound)
1837 ## `blank_lines_lower_bound`
1839 Minimum number of blank lines which must be put between items. If two items have fewer blank lines between
1840 them, additional blank lines are inserted.
1842 - **Default value**: `0`
1843 - **Possible values**: *unsigned integer*
1847 Original Code (rustfmt will not change it with the default value of `0`):