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):
158 #### `"Block"` (default):
166 Adipiscing: Eq = usize,
167 Consectetur: Eq = usize,
174 adipiscing: Adipiscing,
175 consectetur: Consectetur,
185 fn lorem<Ipsum: Eq = usize,
189 Adipiscing: Eq = usize,
190 Consectetur: Eq = usize,
196 adipiscing: Adipiscing,
197 consectetur: Consectetur,
206 #### `"Block"` (default):
218 let lorem = Lorem { ipsum: dolor,
222 See also: [`struct_lit_single_line`](#struct_lit_single_line), [`indent_style`](#indent_style).
226 #### `"Block"` (default):
229 fn lorem<Ipsum, Dolor, Sit, Amet>() -> T
243 fn lorem<Ipsum, Dolor, Sit, Amet>() -> T
253 ## `use_small_heuristics`
255 Whether to use different formatting for items and expressions if they satisfy a heuristic notion of 'small'.
257 - **Default value**: `true`
258 - **Possible values**: `true`, `false`
261 #### `true` (default):
267 Sit { amet: Consectetur, adipiscing: Elit },
281 let lorem = Lorem { ipsum: dolor, sit: amet };
283 let lorem = if ipsum { dolor } else { sit };
300 lorem("lorem", "ipsum", "dolor", "sit", "amet", "consectetur", "adipiscing");
307 let lorem = if ipsum {
317 Where to put a binary operator when a binary expression goes multiline.
319 - **Default value**: `"Front"`
320 - **Possible values**: `"Front"`, `"Back"`
323 #### `"Front"` (default):
334 let range = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
335 ..bbbbbbbbbbbbbbbbbbbbbbbbbbbbb;
342 let or = foofoofoofoofoofoofoofoofoofoofoofoofoofoofoofoo ||
343 barbarbarbarbarbarbarbarbarbarbarbarbarbarbarbar;
345 let sum = 123456789012345678901234567890 + 123456789012345678901234567890 +
346 123456789012345678901234567890;
348 let range = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa..
349 bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb;
353 ## `combine_control_expr`
355 Combine control expressions with function calls.
357 - **Default value**: `true`
358 - **Possible values**: `true`, `false`
361 #### `true` (default):
373 foo!(if let Some(..) = x {
386 foo!(while let Some(..) = x {
420 if let Some(..) = x {
437 while let Some(..) = x {
463 Maximum length of comments. No effect unless`wrap_comments = true`.
465 - **Default value**: `80`
466 - **Possible values**: any positive integer
469 **Note:** A value of `0` results in [`wrap_comments`](#wrap_comments) being applied regardless of a line's width.
471 #### `80` (default; comments shorter than `comment_width`):
473 // Lorem ipsum dolor sit amet, consectetur adipiscing elit.
476 #### `60` (comments longer than `comment_width`):
478 // Lorem ipsum dolor sit amet,
479 // consectetur adipiscing elit.
482 See also [`wrap_comments`](#wrap_comments).
484 ## `condense_wildcard_suffixes`
486 Replace strings of _ wildcards by a single .. in tuple patterns
488 - **Default value**: `false`
489 - **Possible values**: `true`, `false`
492 #### `false` (default):
495 let (lorem, ipsum, _, _) = (1, 2, 3, 4);
501 let (lorem, ipsum, ..) = (1, 2, 3, 4);
504 ## `control_brace_style`
506 Brace style for control flow constructs
508 - **Default value**: `"AlwaysSameLine"`
509 - **Possible values**: `"AlwaysNextLine"`, `"AlwaysSameLine"`, `"ClosingNextLine"`
512 #### `"AlwaysSameLine"` (default):
522 #### `"AlwaysNextLine"`:
535 #### `"ClosingNextLine"`:
546 ## `disable_all_formatting`
548 Don't reformat anything
550 - **Default value**: `false`
551 - **Possible values**: `true`, `false`
554 ## `error_on_line_overflow`
556 Error if unable to get all lines within `max_width`
558 - **Default value**: `true`
559 - **Possible values**: `true`, `false`
562 See also [`max_width`](#max_width).
564 ## `error_on_line_overflow_comments`
566 Error if unable to get all comment lines within `comment_width`.
568 - **Default value**: `true`
569 - **Possible values**: `true`, `false`
572 See also [`comment_width`](#comment_width).
576 Argument density in functions
578 - **Default value**: `"Tall"`
579 - **Possible values**: `"Compressed"`, `"Tall"`, `"Vertical"`
582 #### `"Tall"` (default):
586 fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet);
588 fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet) {
597 consectetur: Consectetur,
598 adipiscing: Adipiscing,
607 consectetur: Consectetur,
608 adipiscing: Adipiscing,
620 fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet);
622 fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet) {
627 ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet, consectetur: Consectetur,
628 adipiscing: Adipiscing, elit: Elit,
632 ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet, consectetur: Consectetur,
633 adipiscing: Adipiscing, elit: Elit,
644 fn lorem(ipsum: Ipsum,
649 fn lorem(ipsum: Ipsum,
656 fn lorem(ipsum: Ipsum,
660 consectetur: Consectetur,
661 adipiscing: Adipiscing,
664 fn lorem(ipsum: Ipsum,
668 consectetur: Consectetur,
669 adipiscing: Adipiscing,
679 Brace style for items
681 - **Default value**: `"SameLineWhere"`
682 - **Possible values**: `"AlwaysNextLine"`, `"PreferSameLine"`, `"SameLineWhere"`
687 #### `"SameLineWhere"` (default):
694 fn lorem(ipsum: usize) {
698 fn lorem<T>(ipsum: T)
700 T: Add + Sub + Mul + Div,
706 #### `"AlwaysNextLine"`:
714 fn lorem(ipsum: usize)
719 fn lorem<T>(ipsum: T)
721 T: Add + Sub + Mul + Div,
727 #### `"PreferSameLine"`:
734 fn lorem(ipsum: usize) {
738 fn lorem<T>(ipsum: T)
740 T: Add + Sub + Mul + Div, {
745 ### Structs and enums
747 #### `"SameLineWhere"` (default):
761 #### `"AlwaysNextLine"`:
776 #### `"PreferSameLine"`:
790 ## `empty_item_single_line`
792 Put empty-body functions and impls on a single line
794 - **Default value**: `true`
795 - **Possible values**: `true`, `false`
798 #### `true` (default):
816 See also [`brace_style`](#brace_style), [`control_brace_style`](#control_brace_style).
821 Put single-expression functions on a single line
823 - **Default value**: `false`
824 - **Possible values**: `true`, `false`
827 #### `false` (default):
830 fn lorem() -> usize {
834 fn lorem() -> usize {
843 fn lorem() -> usize { 42 }
845 fn lorem() -> usize {
851 See also [`control_brace_style`](#control_brace_style).
854 ## `where_single_line`
856 To force single line where layout
858 - **Default value**: `false`
859 - **Possible values**: `true`, `false`
862 #### `false` (default):
877 where Option<T>: Ipsum {
882 See also [`brace_style`](#brace_style), [`control_brace_style`](#control_brace_style).
885 ## `force_explicit_abi`
887 Always print the abi for extern items
889 - **Default value**: `true`
890 - **Possible values**: `true`, `false`
893 **Note:** Non-"C" ABIs are always printed. If `false` then "C" is removed.
895 #### `true` (default):
899 pub static lorem: c_int;
907 pub static lorem: c_int;
913 Format string literals where necessary
915 - **Default value**: `false`
916 - **Possible values**: `true`, `false`
919 #### `false` (default):
922 let lorem = "ipsum dolor sit amet consectetur adipiscing elit lorem ipsum dolor sit";
929 "ipsum dolor sit amet consectetur \
930 adipiscing elit lorem ipsum dolor sit";
933 See also [`max_width`](#max_width).
937 Use tab characters for indentation, spaces for alignment
939 - **Default value**: `false`
940 - **Possible values**: `true`, `false`
943 #### `false` (default):
946 fn lorem() -> usize {
947 42 // spaces before 42
954 fn lorem() -> usize {
959 See also: [`tab_spaces`](#tab_spaces).
964 Indent style of imports
966 - **Default Value**: `"Visual"`
967 - **Possible values**: `"Block"`, `"Visual"`
970 #### `"Visual"` (default):
988 See also: [`imports_layout`](#imports_layout).
992 Item layout inside a imports block
994 - **Default value**: "Mixed"
995 - **Possible values**: "Horizontal", "HorizontalVertical", "Mixed", "Vertical"
998 #### `"Mixed"` (default):
1001 use foo::{xxx, yyy, zzz};
1003 use foo::{aaa, bbb, ccc,
1007 #### `"Horizontal"`:
1009 **Note**: This option forces all imports onto one line and may exceed `max_width`.
1012 use foo::{xxx, yyy, zzz};
1014 use foo::{aaa, bbb, ccc, ddd, eee, fff};
1017 #### `"HorizontalVertical"`:
1020 use foo::{xxx, yyy, zzz};
1046 ## `match_block_trailing_comma`
1048 Put a trailing comma after a block based match arm (non-block arms are not affected)
1050 - **Default value**: `false`
1051 - **Possible values**: `true`, `false`
1054 #### `false` (default):
1061 Lorem::Dolor => println!("dolor"),
1072 Lorem::Dolor => println!("dolor"),
1076 See also: [`trailing_comma`](#trailing_comma), [`match_arm_blocks`](#match_arm_blocks).
1080 Maximum width of each line
1082 - **Default value**: `100`
1083 - **Possible values**: any positive integer
1086 See also [`error_on_line_overflow`](#error_on_line_overflow).
1090 Merge multiple derives into a single one.
1092 - **Default value**: `true`
1093 - **Possible values**: `true`, `false`
1096 #### `true` (default):
1099 #[derive(Eq, PartialEq, Debug, Copy, Clone)]
1106 #[derive(Eq, PartialEq)]
1108 #[derive(Copy, Clone)]
1112 ## `force_multiline_blocks`
1114 Force multiline closure and match arm bodies to be wrapped in a block
1116 - **Default value**: `false`
1117 - **Possible values**: `false`, `true`
1120 #### `false` (default):
1123 result.and_then(|maybe_value| match maybe_value {
1130 println!("Hello World");
1140 result.and_then(|maybe_value| {
1150 println!("Hello World");
1160 Unix or Windows line endings
1162 - **Default value**: `"Unix"`
1163 - **Possible values**: `"Native"`, `"Unix"`, `"Windows"`
1166 ## `normalize_comments`
1168 Convert /* */ comments to // comments where possible
1170 - **Default value**: `false`
1171 - **Possible values**: `true`, `false`
1174 #### `false` (default):
1178 fn dolor() -> usize {}
1181 fn adipiscing() -> usize {}
1188 fn dolor() -> usize {}
1191 fn adipiscing() -> usize {}
1194 ## `reorder_imported_names`
1196 Reorder lists of names in import statements alphabetically
1198 - **Default value**: `false`
1199 - **Possible values**: `true`, `false`
1202 #### `false` (default):
1205 use super::{lorem, ipsum, dolor, sit};
1211 use super::{dolor, ipsum, lorem, sit};
1214 See also [`reorder_imports`](#reorder_imports).
1216 ## `reorder_imports`
1218 Reorder import statements alphabetically
1220 - **Default value**: `false`
1221 - **Possible values**: `true`, `false`
1224 #### `false` (default):
1242 See also [`reorder_imported_names`](#reorder_imported_names), [`reorder_imports_in_group`](#reorder_imports_in_group).
1244 ## `reorder_imports_in_group`
1246 Reorder import statements in group
1248 - **Default value**: `false`
1249 - **Possible values**: `true`, `false`
1252 **Note:** This option takes effect only when [`reorder_imports`](#reorder_imports) is set to `true`.
1254 #### `false` (default):
1278 See also [`reorder_imports`](#reorder_imports).
1280 ## `reorder_extern_crates`
1282 Reorder `extern crate` statements alphabetically
1284 - **Default value**: `true`
1285 - **Possible values**: `true`, `false`
1288 #### `true` (default):
1306 See also [`reorder_extern_crates_in_group`](#reorder_extern_crates_in_group).
1308 ## `reorder_extern_crates_in_group`
1310 Reorder `extern crate` statements in group
1312 - **Default value**: `true`
1313 - **Possible values**: `true`, `false`
1316 **Note:** This option takes effect only when [`reorder_imports`](#reorder_imports) is set to `true`.
1318 #### `true` (default):
1342 See also [`reorder_extern_crates`](#reorder_extern_crates).
1346 Report `TODO` items in comments.
1348 - **Default value**: `"Never"`
1349 - **Possible values**: `"Always"`, `"Unnumbered"`, `"Never"`
1352 Warns about any comments containing `TODO` in them when set to `"Always"`. If
1353 it contains a `#X` (with `X` being a number) in parentheses following the
1354 `TODO`, `"Unnumbered"` will ignore it.
1356 See also [`report_fixme`](#report_fixme).
1360 Report `FIXME` items in comments.
1362 - **Default value**: `"Never"`
1363 - **Possible values**: `"Always"`, `"Unnumbered"`, `"Never"`
1366 Warns about any comments containing `FIXME` in them when set to `"Always"`. If
1367 it contains a `#X` (with `X` being a number) in parentheses following the
1368 `FIXME`, `"Unnumbered"` will ignore it.
1370 See also [`report_todo`](#report_todo).
1375 Don't reformat out of line modules
1377 - **Default value**: `false`
1378 - **Possible values**: `true`, `false`
1381 ## `space_after_colon`
1383 Leave a space after the colon.
1385 - **Default value**: `true`
1386 - **Possible values**: `true`, `false`
1389 #### `true` (default):
1392 fn lorem<T: Eq>(t: T) {
1393 let lorem: Dolor = Lorem {
1403 fn lorem<T:Eq>(t:T) {
1404 let lorem:Dolor = Lorem {
1411 See also: [`space_before_colon`](#space_before_colon).
1413 ## `space_before_colon`
1415 Leave a space before the colon.
1417 - **Default value**: `false`
1418 - **Possible values**: `true`, `false`
1421 #### `false` (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_after_colon`](#space_after_colon).
1445 ## `struct_field_align_threshold`
1447 The maximum diff of width between struct fields to be aligned with each other.
1449 - **Default value** : 0
1450 - **Possible values**: any positive integer
1473 ## `spaces_around_ranges`
1475 Put spaces around the .. and ... range operators
1477 - **Default value**: `false`
1478 - **Possible values**: `true`, `false`
1481 #### `false` (default):
1490 let lorem = 0 .. 10;
1493 ## `spaces_within_parens_and_brackets`
1495 Put spaces within non-empty generic arguments, parentheses, and square brackets
1497 - **Default value**: `false`
1498 - **Possible values**: `true`, `false`
1501 #### `false` (default):
1504 // generic arguments
1505 fn lorem<T: Eq>(t: T) {
1509 // non-empty parentheses
1510 fn lorem<T: Eq>(t: T) {
1511 let lorem = (ipsum, dolor);
1514 // non-empty square brackets
1515 let lorem: [usize; 2] = [ipsum, dolor];
1521 // generic arguments
1522 fn lorem< T: Eq >(t: T) {
1526 // non-empty parentheses
1527 fn lorem<T: Eq>( t: T ) {
1528 let lorem = ( ipsum, dolor );
1531 // non-empty square brackets
1532 let lorem: [ usize; 2 ] = [ ipsum, dolor ];
1535 ## `struct_lit_single_line`
1537 Put small struct literals on a single line
1539 - **Default value**: `true`
1540 - **Possible values**: `true`, `false`
1543 #### `true` (default):
1546 let lorem = Lorem { ipsum: dolor, sit: amet };
1558 See also: [`indent_style`](#indent_style).
1563 Number of spaces per tab
1565 - **Default value**: `4`
1566 - **Possible values**: any positive integer
1573 let ipsum = dolor();
1575 "amet consectetur adipiscing elit."
1584 let ipsum = dolor();
1586 "amet consectetur adipiscing elit."
1591 See also: [`hard_tabs`](#hard_tabs).
1596 How to handle trailing commas for lists
1598 - **Default value**: `"Vertical"`
1599 - **Possible values**: `"Always"`, `"Never"`, `"Vertical"`
1602 #### `"Vertical"` (default):
1605 let Lorem { ipsum, dolor, sit } = amet;
1619 let Lorem { ipsum, dolor, sit, } = amet;
1633 let Lorem { ipsum, dolor, sit } = amet;
1644 See also: [`match_block_trailing_comma`](#match_block_trailing_comma).
1646 ## `trailing_semicolon`
1648 Add trailing semicolon after break, continue and return
1650 - **Default value**: `true`
1651 - **Possible values**: `true`, `false`
1654 #### `true` (default):
1668 ## `type_punctuation_density`
1670 Determines if `+` or `=` are wrapped in spaces in the punctuation of types
1672 - **Default value**: `"Wide"`
1673 - **Possible values**: `"Compressed"`, `"Wide"`
1676 #### `"Wide"` (default):
1679 fn lorem<Ipsum: Dolor + Sit = Amet>() {
1684 #### `"Compressed"`:
1687 fn lorem<Ipsum: Dolor+Sit=Amet>() {
1692 ## `use_try_shorthand`
1694 Replace uses of the try! macro by the ? shorthand
1696 - **Default value**: `false`
1697 - **Possible values**: `true`, `false`
1700 #### `false` (default):
1703 let lorem = try!(ipsum.map(|dolor|dolor.sit()));
1709 let lorem = ipsum.map(|dolor| dolor.sit())?;
1715 Break comments to fit on the line
1717 - **Default value**: `false`
1718 - **Possible values**: `true`, `false`
1721 #### `false` (default):
1724 // 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.
1730 // Lorem ipsum dolor sit amet, consectetur adipiscing elit,
1731 // sed do eiusmod tempor incididunt ut labore et dolore
1732 // magna aliqua. Ut enim ad minim veniam, quis nostrud
1733 // exercitation ullamco laboris nisi ut aliquip ex ea
1734 // commodo consequat.
1737 ## `match_arm_blocks`
1739 Wrap the body of arms in blocks when it does not fit on the same line with the pattern of arms
1741 - **Default value**: `true`
1742 - **Possible values**: `true`, `false`
1745 #### `true` (default):
1750 foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x)
1752 false => println!("{}", sit),
1761 foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x),
1762 false => println!("{}", sit),
1766 See also: [`match_block_trailing_comma`](#match_block_trailing_comma).
1770 What Write Mode to use when none is supplied: Replace, Overwrite, Display, Diff, Coverage
1772 - **Default value**: `"Overwrite"`
1773 - **Possible values**: `"Checkstyle"`, `"Coverage"`, `"Diff"`, `"Display"`, `"Overwrite"`, `"Plain"`, `"Replace"`
1776 ## `blank_lines_upper_bound`
1778 Maximum number of blank lines which can be put between items. If more than this number of consecutive empty
1779 lines are found, they are trimmed down to match this integer.
1781 - **Default value**: `1`
1782 - **Possible values**: *unsigned integer*
1831 See also: [`blank_lines_lower_bound`](#blank_lines_lower_bound)
1833 ## `blank_lines_lower_bound`
1835 Minimum number of blank lines which must be put between items. If two items have fewer blank lines between
1836 them, additional blank lines are inserted.
1838 - **Default value**: `0`
1839 - **Possible values**: *unsigned integer*
1843 Original Code (rustfmt will not change it with the default value of `0`):