Configurations.md

   1 # Configuring Rustfmt
   2
   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.
   4
   5 A possible content of `rustfmt.toml` or `.rustfmt.toml` might look like this:
   6
   7 ```toml
   8 indent_style = "Block"
   9 reorder_imports = false
  10 ```
  11
  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-features` to rustfmt.
  15
  16 # Configuration Options
  17
  18 Below you find a detailed visual guide on all the supported configuration options of rustfmt:
  19
  20
  21 ## `indent_style`
  22
  23 Indent on expressions or items.
  24
  25 - **Default value**: `"Block"`
  26 - **Possible values**: `"Block"`, `"Visual"`
  27 - **Stable**: No
  28
  29 ### Array
  30
  31 #### `"Block"` (default):
  32
  33 ```rust
  34 fn main() {
  35     let lorem = vec![
  36         "ipsum",
  37         "dolor",
  38         "sit",
  39         "amet",
  40         "consectetur",
  41         "adipiscing",
  42         "elit",
  43     ];
  44 }
  45 ```
  46
  47 #### `"Visual"`:
  48
  49 ```rust
  50 fn main() {
  51     let lorem = vec!["ipsum",
  52                      "dolor",
  53                      "sit",
  54                      "amet",
  55                      "consectetur",
  56                      "adipiscing",
  57                      "elit"];
  58 }
  59 ```
  60
  61 ### Control flow
  62
  63 #### `"Block"` (default):
  64
  65 ```rust
  66 fn main() {
  67     if lorem_ipsum
  68         && dolor_sit
  69         && amet_consectetur
  70         && lorem_sit
  71         && dolor_consectetur
  72         && amet_ipsum
  73         && lorem_consectetur
  74     {
  75         // ...
  76     }
  77 }
  78 ```
  79
  80 #### `"Visual"`:
  81
  82 ```rust
  83 fn main() {
  84     if lorem_ipsum
  85        && dolor_sit
  86        && amet_consectetur
  87        && lorem_sit
  88        && dolor_consectetur
  89        && amet_ipsum
  90        && lorem_consectetur
  91     {
  92         // ...
  93     }
  94 }
  95 ```
  96
  97 See also: [`control_brace_style`](#control_brace_style).
  98
  99 ### Function arguments
 100
 101 #### `"Block"` (default):
 102
 103 ```rust
 104 fn lorem() {}
 105
 106 fn lorem(ipsum: usize) {}
 107
 108 fn lorem(
 109     ipsum: usize,
 110     dolor: usize,
 111     sit: usize,
 112     amet: usize,
 113     consectetur: usize,
 114     adipiscing: usize,
 115     elit: usize,
 116 ) {
 117     // body
 118 }
 119 ```
 120
 121 #### `"Visual"`:
 122
 123 ```rust
 124 fn lorem() {}
 125
 126 fn lorem(ipsum: usize) {}
 127
 128 fn lorem(ipsum: usize,
 129          dolor: usize,
 130          sit: usize,
 131          amet: usize,
 132          consectetur: usize,
 133          adipiscing: usize,
 134          elit: usize) {
 135     // body
 136 }
 137 ```
 138
 139 ### Function calls
 140
 141 #### `"Block"` (default):
 142
 143 ```rust
 144 fn main() {
 145     lorem(
 146         "lorem",
 147         "ipsum",
 148         "dolor",
 149         "sit",
 150         "amet",
 151         "consectetur",
 152         "adipiscing",
 153         "elit",
 154     );
 155 }
 156 ```
 157
 158 #### `"Visual"`:
 159
 160 ```rust
 161 fn main() {
 162     lorem("lorem",
 163           "ipsum",
 164           "dolor",
 165           "sit",
 166           "amet",
 167           "consectetur",
 168           "adipiscing",
 169           "elit");
 170 }
 171 ```
 172
 173 ### Generics
 174
 175 #### `"Block"` (default):
 176
 177 ```rust
 178 fn lorem<
 179     Ipsum: Eq = usize,
 180     Dolor: Eq = usize,
 181     Sit: Eq = usize,
 182     Amet: Eq = usize,
 183     Adipiscing: Eq = usize,
 184     Consectetur: Eq = usize,
 185     Elit: Eq = usize,
 186 >(
 187     ipsum: Ipsum,
 188     dolor: Dolor,
 189     sit: Sit,
 190     amet: Amet,
 191     adipiscing: Adipiscing,
 192     consectetur: Consectetur,
 193     elit: Elit,
 194 ) -> T {
 195     // body
 196 }
 197 ```
 198
 199 #### `"Visual"`:
 200
 201 ```rust
 202 fn lorem<Ipsum: Eq = usize,
 203          Dolor: Eq = usize,
 204          Sit: Eq = usize,
 205          Amet: Eq = usize,
 206          Adipiscing: Eq = usize,
 207          Consectetur: Eq = usize,
 208          Elit: Eq = usize>(
 209     ipsum: Ipsum,
 210     dolor: Dolor,
 211     sit: Sit,
 212     amet: Amet,
 213     adipiscing: Adipiscing,
 214     consectetur: Consectetur,
 215     elit: Elit)
 216     -> T {
 217     // body
 218 }
 219 ```
 220
 221 #### Struct
 222
 223 #### `"Block"` (default):
 224
 225 ```rust
 226 fn main() {
 227     let lorem = Lorem {
 228         ipsum: dolor,
 229         sit: amet,
 230     };
 231 }
 232 ```
 233
 234 #### `"Visual"`:
 235
 236 ```rust
 237 fn main() {
 238     let lorem = Lorem { ipsum: dolor,
 239                         sit: amet, };
 240 }
 241 ```
 242
 243 See also: [`struct_lit_single_line`](#struct_lit_single_line), [`indent_style`](#indent_style).
 244
 245 ### Where predicates
 246
 247 #### `"Block"` (default):
 248
 249 ```rust
 250 fn lorem<Ipsum, Dolor, Sit, Amet>() -> T
 251 where
 252     Ipsum: Eq,
 253     Dolor: Eq,
 254     Sit: Eq,
 255     Amet: Eq,
 256 {
 257     // body
 258 }
 259 ```
 260
 261 #### `"Visual"`:
 262
 263 ```rust
 264 fn lorem<Ipsum, Dolor, Sit, Amet>() -> T
 265     where Ipsum: Eq,
 266           Dolor: Eq,
 267           Sit: Eq,
 268           Amet: Eq
 269 {
 270     // body
 271 }
 272 ```
 273
 274 ## `use_small_heuristics`
 275
 276 Whether to use different formatting for items and expressions if they satisfy a heuristic notion of 'small'.
 277
 278 - **Default value**: `true`
 279 - **Possible values**: `true`, `false`
 280 - **Stable**: No
 281
 282 #### `true` (default):
 283
 284 ```rust
 285 enum Lorem {
 286     Ipsum,
 287     Dolor(bool),
 288     Sit { amet: Consectetur, adipiscing: Elit },
 289 }
 290
 291 fn main() {
 292     lorem(
 293         "lorem",
 294         "ipsum",
 295         "dolor",
 296         "sit",
 297         "amet",
 298         "consectetur",
 299         "adipiscing",
 300     );
 301
 302     let lorem = Lorem {
 303         ipsum: dolor,
 304         sit: amet,
 305     };
 306     let lorem = Lorem { ipsum: dolor };
 307
 308     let lorem = if ipsum { dolor } else { sit };
 309 }
 310 ```
 311
 312 #### `false`:
 313
 314 ```rust
 315 enum Lorem {
 316     Ipsum,
 317     Dolor(bool),
 318     Sit {
 319         amet: Consectetur,
 320         adipiscing: Elit,
 321     },
 322 }
 323
 324 fn main() {
 325     lorem("lorem", "ipsum", "dolor", "sit", "amet", "consectetur", "adipiscing");
 326
 327     let lorem = Lorem {
 328         ipsum: dolor,
 329         sit: amet,
 330     };
 331
 332     let lorem = if ipsum {
 333         dolor
 334     } else {
 335         sit
 336     };
 337 }
 338 ```
 339
 340 ## `binop_separator`
 341
 342 Where to put a binary operator when a binary expression goes multiline.
 343
 344 - **Default value**: `"Front"`
 345 - **Possible values**: `"Front"`, `"Back"`
 346 - **Stable**: No
 347
 348 #### `"Front"` (default):
 349
 350 ```rust
 351 fn main() {
 352     let or = foofoofoofoofoofoofoofoofoofoofoofoofoofoofoofoo
 353         || barbarbarbarbarbarbarbarbarbarbarbarbarbarbarbar;
 354
 355     let sum = 123456789012345678901234567890
 356         + 123456789012345678901234567890
 357         + 123456789012345678901234567890;
 358
 359     let range = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
 360         ..bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb;
 361 }
 362 ```
 363
 364 #### `"Back"`:
 365
 366 ```rust
 367 fn main() {
 368     let or = foofoofoofoofoofoofoofoofoofoofoofoofoofoofoofoo ||
 369         barbarbarbarbarbarbarbarbarbarbarbarbarbarbarbar;
 370
 371     let sum = 123456789012345678901234567890 +
 372         123456789012345678901234567890 +
 373         123456789012345678901234567890;
 374
 375     let range = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa..
 376         bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb;
 377 }
 378 ```
 379
 380 ## `combine_control_expr`
 381
 382 Combine control expressions with function calls.
 383
 384 - **Default value**: `true`
 385 - **Possible values**: `true`, `false`
 386 - **Stable**: No
 387
 388 #### `true` (default):
 389
 390 ```rust
 391 fn example() {
 392     // If
 393     foo!(if x {
 394         foo();
 395     } else {
 396         bar();
 397     });
 398
 399     // IfLet
 400     foo!(if let Some(..) = x {
 401         foo();
 402     } else {
 403         bar();
 404     });
 405
 406     // While
 407     foo!(while x {
 408         foo();
 409         bar();
 410     });
 411
 412     // WhileLet
 413     foo!(while let Some(..) = x {
 414         foo();
 415         bar();
 416     });
 417
 418     // ForLoop
 419     foo!(for x in y {
 420         foo();
 421         bar();
 422     });
 423
 424     // Loop
 425     foo!(loop {
 426         foo();
 427         bar();
 428     });
 429 }
 430 ```
 431
 432 #### `false`:
 433
 434 ```rust
 435 fn example() {
 436     // If
 437     foo!(
 438         if x {
 439             foo();
 440         } else {
 441             bar();
 442         }
 443     );
 444
 445     // IfLet
 446     foo!(
 447         if let Some(..) = x {
 448             foo();
 449         } else {
 450             bar();
 451         }
 452     );
 453
 454     // While
 455     foo!(
 456         while x {
 457             foo();
 458             bar();
 459         }
 460     );
 461
 462     // WhileLet
 463     foo!(
 464         while let Some(..) = x {
 465             foo();
 466             bar();
 467         }
 468     );
 469
 470     // ForLoop
 471     foo!(
 472         for x in y {
 473             foo();
 474             bar();
 475         }
 476     );
 477
 478     // Loop
 479     foo!(
 480         loop {
 481             foo();
 482             bar();
 483         }
 484     );
 485 }
 486 ```
 487
 488 ## `comment_width`
 489
 490 Maximum length of comments. No effect unless`wrap_comments = true`.
 491
 492 - **Default value**: `80`
 493 - **Possible values**: any positive integer
 494 - **Stable**: No
 495
 496 **Note:** A value of `0` results in [`wrap_comments`](#wrap_comments) being applied regardless of a line's width.
 497
 498 #### `80` (default; comments shorter than `comment_width`):
 499 ```rust
 500 // Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 501 ```
 502
 503 #### `60` (comments longer than `comment_width`):
 504 ```rust
 505 // Lorem ipsum dolor sit amet,
 506 // consectetur adipiscing elit.
 507 ```
 508
 509 See also [`wrap_comments`](#wrap_comments).
 510
 511 ## `condense_wildcard_suffixes`
 512
 513 Replace strings of _ wildcards by a single .. in tuple patterns
 514
 515 - **Default value**: `false`
 516 - **Possible values**: `true`, `false`
 517 - **Stable**: No
 518
 519 #### `false` (default):
 520
 521 ```rust
 522 fn main() {
 523     let (lorem, ipsum, _, _) = (1, 2, 3, 4);
 524     let (lorem, ipsum, ..) = (1, 2, 3, 4);
 525 }
 526 ```
 527
 528 #### `true`:
 529
 530 ```rust
 531 fn main() {
 532     let (lorem, ipsum, ..) = (1, 2, 3, 4);
 533 }
 534 ```
 535
 536 ## `control_brace_style`
 537
 538 Brace style for control flow constructs
 539
 540 - **Default value**: `"AlwaysSameLine"`
 541 - **Possible values**: `"AlwaysNextLine"`, `"AlwaysSameLine"`, `"ClosingNextLine"`
 542 - **Stable**: No
 543
 544 #### `"AlwaysSameLine"` (default):
 545
 546 ```rust
 547 fn main() {
 548     if lorem {
 549         println!("ipsum!");
 550     } else {
 551         println!("dolor!");
 552     }
 553 }
 554 ```
 555
 556 #### `"AlwaysNextLine"`:
 557
 558 ```rust
 559 fn main() {
 560     if lorem
 561     {
 562         println!("ipsum!");
 563     }
 564     else
 565     {
 566         println!("dolor!");
 567     }
 568 }
 569 ```
 570
 571 #### `"ClosingNextLine"`:
 572
 573 ```rust
 574 fn main() {
 575     if lorem {
 576         println!("ipsum!");
 577     }
 578     else {
 579         println!("dolor!");
 580     }
 581 }
 582 ```
 583
 584 ## `disable_all_formatting`
 585
 586 Don't reformat anything
 587
 588 - **Default value**: `false`
 589 - **Possible values**: `true`, `false`
 590 - **Stable**: No
 591
 592 ## `error_on_line_overflow`
 593
 594 Error if Rustfmt is unable to get all lines within `max_width`, except for comments and string
 595 literals. If this happens, then it is a bug in Rustfmt. You might be able to work around the bug by
 596 refactoring your code to avoid long/complex expressions, usually by extracting a local variable or
 597 using a shorter name.
 598
 599 - **Default value**: `false`
 600 - **Possible values**: `true`, `false`
 601 - **Stable**: No
 602
 603 See also [`max_width`](#max_width).
 604
 605 ## `error_on_unformatted`
 606
 607 Error if unable to get comments or string literals within `max_width`, or they are left with
 608 trailing whitespaces.
 609
 610 - **Default value**: `false`
 611 - **Possible values**: `true`, `false`
 612 - **Stable**: No
 613
 614 ## `fn_args_density`
 615
 616 Argument density in functions
 617
 618 - **Default value**: `"Tall"`
 619 - **Possible values**: `"Compressed"`, `"Tall"`, `"Vertical"`
 620 - **Stable**: No
 621
 622 #### `"Tall"` (default):
 623
 624 ```rust
 625 trait Lorem {
 626     fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet);
 627
 628     fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet) {
 629         // body
 630     }
 631
 632     fn lorem(
 633         ipsum: Ipsum,
 634         dolor: Dolor,
 635         sit: Sit,
 636         amet: Amet,
 637         consectetur: Consectetur,
 638         adipiscing: Adipiscing,
 639         elit: Elit,
 640     );
 641
 642     fn lorem(
 643         ipsum: Ipsum,
 644         dolor: Dolor,
 645         sit: Sit,
 646         amet: Amet,
 647         consectetur: Consectetur,
 648         adipiscing: Adipiscing,
 649         elit: Elit,
 650     ) {
 651         // body
 652     }
 653 }
 654 ```
 655
 656 #### `"Compressed"`:
 657
 658 ```rust
 659 trait Lorem {
 660     fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet);
 661
 662     fn lorem(ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet) {
 663         // body
 664     }
 665
 666     fn lorem(
 667         ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet, consectetur: Consectetur,
 668         adipiscing: Adipiscing, elit: Elit,
 669     );
 670
 671     fn lorem(
 672         ipsum: Ipsum, dolor: Dolor, sit: Sit, amet: Amet, consectetur: Consectetur,
 673         adipiscing: Adipiscing, elit: Elit,
 674     ) {
 675         // body
 676     }
 677 }
 678 ```
 679
 680 #### `"Vertical"`:
 681
 682 ```rust
 683 trait Lorem {
 684     fn lorem(
 685         ipsum: Ipsum,
 686         dolor: Dolor,
 687         sit: Sit,
 688         amet: Amet,
 689     );
 690
 691     fn lorem(
 692         ipsum: Ipsum,
 693         dolor: Dolor,
 694         sit: Sit,
 695         amet: Amet,
 696     ) {
 697         // body
 698     }
 699
 700     fn lorem(
 701         ipsum: Ipsum,
 702         dolor: Dolor,
 703         sit: Sit,
 704         amet: Amet,
 705         consectetur: Consectetur,
 706         adipiscing: Adipiscing,
 707         elit: Elit,
 708     );
 709
 710     fn lorem(
 711         ipsum: Ipsum,
 712         dolor: Dolor,
 713         sit: Sit,
 714         amet: Amet,
 715         consectetur: Consectetur,
 716         adipiscing: Adipiscing,
 717         elit: Elit,
 718     ) {
 719         // body
 720     }
 721 }
 722 ```
 723
 724
 725 ## `brace_style`
 726
 727 Brace style for items
 728
 729 - **Default value**: `"SameLineWhere"`
 730 - **Possible values**: `"AlwaysNextLine"`, `"PreferSameLine"`, `"SameLineWhere"`
 731 - **Stable**: No
 732
 733 ### Functions
 734
 735 #### `"SameLineWhere"` (default):
 736
 737 ```rust
 738 fn lorem() {
 739     // body
 740 }
 741
 742 fn lorem(ipsum: usize) {
 743     // body
 744 }
 745
 746 fn lorem<T>(ipsum: T)
 747 where
 748     T: Add + Sub + Mul + Div,
 749 {
 750     // body
 751 }
 752 ```
 753
 754 #### `"AlwaysNextLine"`:
 755
 756 ```rust
 757 fn lorem()
 758 {
 759     // body
 760 }
 761
 762 fn lorem(ipsum: usize)
 763 {
 764     // body
 765 }
 766
 767 fn lorem<T>(ipsum: T)
 768 where
 769     T: Add + Sub + Mul + Div,
 770 {
 771     // body
 772 }
 773 ```
 774
 775 #### `"PreferSameLine"`:
 776
 777 ```rust
 778 fn lorem() {
 779     // body
 780 }
 781
 782 fn lorem(ipsum: usize) {
 783     // body
 784 }
 785
 786 fn lorem<T>(ipsum: T)
 787 where
 788     T: Add + Sub + Mul + Div, {
 789     // body
 790 }
 791 ```
 792
 793 ### Structs and enums
 794
 795 #### `"SameLineWhere"` (default):
 796
 797 ```rust
 798 struct Lorem {
 799     ipsum: bool,
 800 }
 801
 802 struct Dolor<T>
 803 where
 804     T: Eq,
 805 {
 806     sit: T,
 807 }
 808 ```
 809
 810 #### `"AlwaysNextLine"`:
 811
 812 ```rust
 813 struct Lorem
 814 {
 815     ipsum: bool,
 816 }
 817
 818 struct Dolor<T>
 819 where
 820     T: Eq,
 821 {
 822     sit: T,
 823 }
 824 ```
 825
 826 #### `"PreferSameLine"`:
 827
 828 ```rust
 829 struct Lorem {
 830     ipsum: bool,
 831 }
 832
 833 struct Dolor<T>
 834 where
 835     T: Eq, {
 836     sit: T,
 837 }
 838 ```
 839
 840
 841 ## `empty_item_single_line`
 842
 843 Put empty-body functions and impls on a single line
 844
 845 - **Default value**: `true`
 846 - **Possible values**: `true`, `false`
 847 - **Stable**: No
 848
 849 #### `true` (default):
 850
 851 ```rust
 852 fn lorem() {}
 853
 854 impl Lorem {}
 855 ```
 856
 857 #### `false`:
 858
 859 ```rust
 860 fn lorem() {
 861 }
 862
 863 impl Lorem {
 864 }
 865 ```
 866
 867 See also [`brace_style`](#brace_style), [`control_brace_style`](#control_brace_style).
 868
 869
 870 ## `fn_single_line`
 871
 872 Put single-expression functions on a single line
 873
 874 - **Default value**: `false`
 875 - **Possible values**: `true`, `false`
 876 - **Stable**: No
 877
 878 #### `false` (default):
 879
 880 ```rust
 881 fn lorem() -> usize {
 882     42
 883 }
 884
 885 fn lorem() -> usize {
 886     let ipsum = 42;
 887     ipsum
 888 }
 889 ```
 890
 891 #### `true`:
 892
 893 ```rust
 894 fn lorem() -> usize { 42 }
 895
 896 fn lorem() -> usize {
 897     let ipsum = 42;
 898     ipsum
 899 }
 900 ```
 901
 902 See also [`control_brace_style`](#control_brace_style).
 903
 904
 905 ## `where_single_line`
 906
 907 Forces the `where` clause to be laid out on a single line.
 908
 909 - **Default value**: `false`
 910 - **Possible values**: `true`, `false`
 911 - **Stable**: No
 912
 913 #### `false` (default):
 914
 915 ```rust
 916 impl<T> Lorem for T
 917 where
 918     Option<T>: Ipsum,
 919 {
 920     // body
 921 }
 922 ```
 923
 924 #### `true`:
 925
 926 ```rust
 927 impl<T> Lorem for T
 928 where Option<T>: Ipsum
 929 {
 930     // body
 931 }
 932 ```
 933
 934 See also [`brace_style`](#brace_style), [`control_brace_style`](#control_brace_style).
 935
 936
 937 ## `force_explicit_abi`
 938
 939 Always print the abi for extern items
 940
 941 - **Default value**: `true`
 942 - **Possible values**: `true`, `false`
 943 - **Stable**: Yes
 944
 945 **Note:** Non-"C" ABIs are always printed. If `false` then "C" is removed.
 946
 947 #### `true` (default):
 948
 949 ```rust
 950 extern "C" {
 951     pub static lorem: c_int;
 952 }
 953 ```
 954
 955 #### `false`:
 956
 957 ```rust
 958 extern {
 959     pub static lorem: c_int;
 960 }
 961 ```
 962
 963 ## `format_strings`
 964
 965 Format string literals where necessary
 966
 967 - **Default value**: `false`
 968 - **Possible values**: `true`, `false`
 969 - **Stable**: No
 970
 971 #### `false` (default):
 972
 973 ```rust
 974 fn main() {
 975     let lorem =
 976         "ipsum dolor sit amet consectetur adipiscing elit lorem ipsum dolor sit amet consectetur adipiscing";
 977 }
 978 ```
 979
 980 #### `true`:
 981
 982 ```rust
 983 fn main() {
 984     let lorem = "ipsum dolor sit amet consectetur adipiscing elit lorem ipsum dolor sit amet \
 985                  consectetur adipiscing";
 986 }
 987 ```
 988
 989 See also [`max_width`](#max_width).
 990
 991 ## `hard_tabs`
 992
 993 Use tab characters for indentation, spaces for alignment
 994
 995 - **Default value**: `false`
 996 - **Possible values**: `true`, `false`
 997 - **Stable**: Yes
 998
 999 #### `false` (default):
1000
1001 ```rust
1002 fn lorem() -> usize {
1003     42 // spaces before 42
1004 }
1005 ```
1006
1007 #### `true`:
1008
1009 ```rust
1010 fn lorem() -> usize {
1011         42 // tabs before 42
1012 }
1013 ```
1014
1015 See also: [`tab_spaces`](#tab_spaces).
1016
1017
1018 ## `imports_indent`
1019
1020 Indent style of imports
1021
1022 - **Default Value**: `"Visual"`
1023 - **Possible values**: `"Block"`, `"Visual"`
1024 - **Stable**: No
1025
1026 #### `"Visual"` (default):
1027
1028 ```rust
1029 use foo::{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx, yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy,
1030           zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz};
1031 ```
1032
1033 #### `"Block"`:
1034
1035 ```rust
1036 use foo::{
1037     xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx, yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy,
1038     zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz,
1039 };
1040 ```
1041
1042 See also: [`imports_layout`](#imports_layout).
1043
1044 ## `imports_layout`
1045
1046 Item layout inside a imports block
1047
1048 - **Default value**: "Mixed"
1049 - **Possible values**: "Horizontal", "HorizontalVertical", "Mixed", "Vertical"
1050 - **Stable**: No
1051
1052 #### `"Mixed"` (default):
1053
1054 ```rust
1055 use foo::{xxxxxxxxxxxxxxxxxx, yyyyyyyyyyyyyyyyyy, zzzzzzzzzzzzzzzzzz};
1056
1057 use foo::{
1058     aaaaaaaaaaaaaaaaaa, bbbbbbbbbbbbbbbbbb, cccccccccccccccccc, dddddddddddddddddd,
1059     eeeeeeeeeeeeeeeeee, ffffffffffffffffff,
1060 };
1061 ```
1062
1063 #### `"Horizontal"`:
1064
1065 **Note**: This option forces all imports onto one line and may exceed `max_width`.
1066
1067 ```rust
1068 use foo::{xxx, yyy, zzz};
1069
1070 use foo::{aaa, bbb, ccc, ddd, eee, fff};
1071 ```
1072
1073 #### `"HorizontalVertical"`:
1074
1075 ```rust
1076 use foo::{xxxxxxxxxxxxxxxxxx, yyyyyyyyyyyyyyyyyy, zzzzzzzzzzzzzzzzzz};
1077
1078 use foo::{
1079     aaaaaaaaaaaaaaaaaa,
1080     bbbbbbbbbbbbbbbbbb,
1081     cccccccccccccccccc,
1082     dddddddddddddddddd,
1083     eeeeeeeeeeeeeeeeee,
1084     ffffffffffffffffff,
1085 };
1086 ```
1087
1088 #### `"Vertical"`:
1089
1090 ```rust
1091 use foo::{
1092     xxx,
1093     yyy,
1094     zzz,
1095 };
1096
1097 use foo::{
1098     aaa,
1099     bbb,
1100     ccc,
1101     ddd,
1102     eee,
1103     fff,
1104 };
1105 ```
1106
1107 ## `merge_imports`
1108
1109 Merge multiple imports into a single nested import.
1110
1111 - **Default value**: `false`
1112 - **Possible values**: `true`, `false`
1113 - **Stable**: No
1114
1115 #### `false` (default):
1116
1117 ```rust
1118 use foo::{a, c, d};
1119 use foo::{b, g};
1120 use foo::{e, f};
1121 ```
1122
1123 #### `true`:
1124
1125 ```rust
1126 use foo::{a, b, c, d, e, f, g};
1127 ```
1128
1129
1130 ## `match_block_trailing_comma`
1131
1132 Put a trailing comma after a block based match arm (non-block arms are not affected)
1133
1134 - **Default value**: `false`
1135 - **Possible values**: `true`, `false`
1136 - **Stable**: No
1137
1138 #### `false` (default):
1139
1140 ```rust
1141 fn main() {
1142     match lorem {
1143         Lorem::Ipsum => {
1144             println!("ipsum");
1145         }
1146         Lorem::Dolor => println!("dolor"),
1147     }
1148 }
1149 ```
1150
1151 #### `true`:
1152
1153 ```rust
1154 fn main() {
1155     match lorem {
1156         Lorem::Ipsum => {
1157             println!("ipsum");
1158         },
1159         Lorem::Dolor => println!("dolor"),
1160     }
1161 }
1162 ```
1163
1164 See also: [`trailing_comma`](#trailing_comma), [`match_arm_blocks`](#match_arm_blocks).
1165
1166 ## `max_width`
1167
1168 Maximum width of each line
1169
1170 - **Default value**: `100`
1171 - **Possible values**: any positive integer
1172 - **Stable**: Yes
1173
1174 See also [`error_on_line_overflow`](#error_on_line_overflow).
1175
1176 ## `merge_derives`
1177
1178 Merge multiple derives into a single one.
1179
1180 - **Default value**: `true`
1181 - **Possible values**: `true`, `false`
1182 - **Stable**: Yes
1183
1184 #### `true` (default):
1185
1186 ```rust
1187 #[derive(Eq, PartialEq, Debug, Copy, Clone)]
1188 pub enum Foo {}
1189 ```
1190
1191 #### `false`:
1192
1193 ```rust
1194 #[derive(Eq, PartialEq)]
1195 #[derive(Debug)]
1196 #[derive(Copy, Clone)]
1197 pub enum Foo {}
1198 ```
1199
1200 ## `force_multiline_blocks`
1201
1202 Force multiline closure and match arm bodies to be wrapped in a block
1203
1204 - **Default value**: `false`
1205 - **Possible values**: `false`, `true`
1206 - **Stable**: No
1207
1208 #### `false` (default):
1209
1210 ```rust
1211 fn main() {
1212     result.and_then(|maybe_value| match maybe_value {
1213         None => foo(),
1214         Some(value) => bar(),
1215     });
1216
1217     match lorem {
1218         None => if ipsum {
1219             println!("Hello World");
1220         },
1221         Some(dolor) => foo(),
1222     }
1223 }
1224 ```
1225
1226 #### `true`:
1227
1228 ```rust
1229 fn main() {
1230     result.and_then(|maybe_value| {
1231         match maybe_value {
1232             None => foo(),
1233             Some(value) => bar(),
1234         }
1235     });
1236
1237     match lorem {
1238         None => {
1239             if ipsum {
1240                 println!("Hello World");
1241             }
1242         }
1243         Some(dolor) => foo(),
1244     }
1245 }
1246 ```
1247
1248
1249 ## `newline_style`
1250
1251 Unix or Windows line endings
1252
1253 - **Default value**: `"Unix"`
1254 - **Possible values**: `"Native"`, `"Unix"`, `"Windows"`
1255 - **Stable**: Yes
1256
1257 ## `normalize_comments`
1258
1259 Convert /* */ comments to // comments where possible
1260
1261 - **Default value**: `false`
1262 - **Possible values**: `true`, `false`
1263 - **Stable**: Yes
1264
1265 #### `false` (default):
1266
1267 ```rust
1268 // Lorem ipsum:
1269 fn dolor() -> usize {}
1270
1271 /* sit amet: */
1272 fn adipiscing() -> usize {}
1273 ```
1274
1275 #### `true`:
1276
1277 ```rust
1278 // Lorem ipsum:
1279 fn dolor() -> usize {}
1280
1281 // sit amet:
1282 fn adipiscing() -> usize {}
1283 ```
1284
1285 ## `remove_nested_parens`
1286
1287 Remove nested parens.
1288
1289 - **Defalut value**: `false`,
1290 - **Possible values**: `true`, `false`
1291 - **Stable**: No
1292
1293 #### `false` (default):
1294 ```rust
1295 fn main() {
1296     ((((foo()))));
1297 }
1298 ```
1299
1300 #### `true`:
1301 ```rust
1302 fn main() {
1303     (foo());
1304 }
1305 ```
1306
1307
1308 ## `reorder_imports`
1309
1310 Reorder import and extern crate statements alphabetically in groups (a group is
1311 separated by a newline).
1312
1313 - **Default value**: `true`
1314 - **Possible values**: `true`, `false`
1315 - **Stable**: No
1316
1317 #### `true` (default):
1318
1319 ```rust
1320 use dolor;
1321 use ipsum;
1322 use lorem;
1323 use sit;
1324 ```
1325
1326 #### `false`:
1327
1328 ```rust
1329 use lorem;
1330 use ipsum;
1331 use dolor;
1332 use sit;
1333 ```
1334
1335
1336 ## `reorder_modules`
1337
1338 Reorder `mod` declarations alphabetically in group.
1339
1340 - **Default value**: `true`
1341 - **Possible values**: `true`, `false`
1342 - **Stable**: No
1343
1344 #### `true` (default)
1345
1346 ```rust
1347 mod a;
1348 mod b;
1349
1350 mod dolor;
1351 mod ipsum;
1352 mod lorem;
1353 mod sit;
1354 ```
1355
1356 #### `false`
1357
1358 ```rust
1359 mod b;
1360 mod a;
1361
1362 mod lorem;
1363 mod ipsum;
1364 mod dolor;
1365 mod sit;
1366 ```
1367
1368 **Note** `mod` with `#[macro_export]` will not be reordered since that could change the semantic
1369 of the original source code.
1370
1371 ## `reorder_impl_items`
1372
1373 Reorder impl items. `type` and `const` are put first, then macros and methods.
1374
1375 - **Default value**: `false`
1376 - **Possible values**: `true`, `false`
1377 - **Stable**: No
1378
1379 #### `false` (default)
1380
1381 ```rust
1382 struct Dummy;
1383
1384 impl Iterator for Dummy {
1385     fn next(&mut self) -> Option<Self::Item> {
1386         None
1387     }
1388
1389     type Item = i32;
1390 }
1391 ```
1392
1393 #### `true`
1394
1395 ```rust
1396 struct Dummy;
1397
1398 impl Iterator for Dummy {
1399     type Item = i32;
1400
1401     fn next(&mut self) -> Option<Self::Item> {
1402         None
1403     }
1404 }
1405 ```
1406
1407 ## `report_todo`
1408
1409 Report `TODO` items in comments.
1410
1411 - **Default value**: `"Never"`
1412 - **Possible values**: `"Always"`, `"Unnumbered"`, `"Never"`
1413 - **Stable**: No
1414
1415 Warns about any comments containing `TODO` in them when set to `"Always"`. If
1416 it contains a `#X` (with `X` being a number) in parentheses following the
1417 `TODO`, `"Unnumbered"` will ignore it.
1418
1419 See also [`report_fixme`](#report_fixme).
1420
1421 ## `report_fixme`
1422
1423 Report `FIXME` items in comments.
1424
1425 - **Default value**: `"Never"`
1426 - **Possible values**: `"Always"`, `"Unnumbered"`, `"Never"`
1427 - **Stable**: No
1428
1429 Warns about any comments containing `FIXME` in them when set to `"Always"`. If
1430 it contains a `#X` (with `X` being a number) in parentheses following the
1431 `FIXME`, `"Unnumbered"` will ignore it.
1432
1433 See also [`report_todo`](#report_todo).
1434
1435
1436 ## `skip_children`
1437
1438 Don't reformat out of line modules
1439
1440 - **Default value**: `false`
1441 - **Possible values**: `true`, `false`
1442 - **Stable**: No
1443
1444 ## `space_after_colon`
1445
1446 Leave a space after the colon.
1447
1448 - **Default value**: `true`
1449 - **Possible values**: `true`, `false`
1450 - **Stable**: No
1451
1452 #### `true` (default):
1453
1454 ```rust
1455 fn lorem<T: Eq>(t: T) {
1456     let lorem: Dolor = Lorem {
1457         ipsum: dolor,
1458         sit: amet,
1459     };
1460 }
1461 ```
1462
1463 #### `false`:
1464
1465 ```rust
1466 fn lorem<T:Eq>(t:T) {
1467     let lorem:Dolor = Lorem {
1468         ipsum:dolor,
1469         sit:amet,
1470     };
1471 }
1472 ```
1473
1474 See also: [`space_before_colon`](#space_before_colon).
1475
1476 ## `space_before_colon`
1477
1478 Leave a space before the colon.
1479
1480 - **Default value**: `false`
1481 - **Possible values**: `true`, `false`
1482 - **Stable**: No
1483
1484 #### `false` (default):
1485
1486 ```rust
1487 fn lorem<T: Eq>(t: T) {
1488     let lorem: Dolor = Lorem {
1489         ipsum: dolor,
1490         sit: amet,
1491     };
1492 }
1493 ```
1494
1495 #### `true`:
1496
1497 ```rust
1498 fn lorem<T : Eq>(t : T) {
1499     let lorem : Dolor = Lorem {
1500         ipsum : dolor,
1501         sit : amet,
1502     };
1503 }
1504 ```
1505
1506 See also: [`space_after_colon`](#space_after_colon).
1507
1508 ## `struct_field_align_threshold`
1509
1510 The maximum diff of width between struct fields to be aligned with each other.
1511
1512 - **Default value** : 0
1513 - **Possible values**: any positive integer
1514 - **Stable**: No
1515
1516 #### `0` (default):
1517
1518 ```rust
1519 struct Foo {
1520     x: u32,
1521     yy: u32,
1522     zzz: u32,
1523 }
1524 ```
1525
1526 #### `20`:
1527
1528 ```rust
1529 struct Foo {
1530     x:   u32,
1531     yy:  u32,
1532     zzz: u32,
1533 }
1534 ```
1535
1536 ## `spaces_around_ranges`
1537
1538 Put spaces around the .., ..=, and ... range operators
1539
1540 - **Default value**: `false`
1541 - **Possible values**: `true`, `false`
1542 - **Stable**: No
1543
1544 #### `false` (default):
1545
1546 ```rust
1547 fn main() {
1548     let lorem = 0..10;
1549     let ipsum = 0..=10;
1550
1551     match lorem {
1552         1..5 => foo(),
1553         _ => bar,
1554     }
1555
1556     match lorem {
1557         1..=5 => foo(),
1558         _ => bar,
1559     }
1560
1561     match lorem {
1562         1...5 => foo(),
1563         _ => bar,
1564     }
1565 }
1566 ```
1567
1568 #### `true`:
1569
1570 ```rust
1571 fn main() {
1572     let lorem = 0 .. 10;
1573     let ipsum = 0 ..= 10;
1574
1575     match lorem {
1576         1 .. 5 => foo(),
1577         _ => bar,
1578     }
1579
1580     match lorem {
1581         1 ..= 5 => foo(),
1582         _ => bar,
1583     }
1584
1585     match lorem {
1586         1 ... 5 => foo(),
1587         _ => bar,
1588     }
1589 }
1590 ```
1591
1592 ## `spaces_within_parens_and_brackets`
1593
1594 Put spaces within non-empty generic arguments, parentheses, and square brackets
1595
1596 - **Default value**: `false`
1597 - **Possible values**: `true`, `false`
1598 - **Stable**: No
1599
1600 #### `false` (default):
1601
1602 ```rust
1603 // generic arguments
1604 fn lorem<T: Eq>(t: T) {
1605     // body
1606 }
1607
1608 // non-empty parentheses
1609 fn lorem<T: Eq>(t: T) {
1610     let lorem = (ipsum, dolor);
1611 }
1612
1613 // non-empty square brackets
1614 fn lorem<T: Eq>(t: T) {
1615     let lorem: [usize; 2] = [ipsum, dolor];
1616 }
1617 ```
1618
1619 #### `true`:
1620
1621 ```rust
1622 // generic arguments
1623 fn lorem< T: Eq >( t: T ) {
1624     // body
1625 }
1626
1627 // non-empty parentheses
1628 fn lorem< T: Eq >( t: T ) {
1629     let lorem = ( ipsum, dolor );
1630 }
1631
1632 // non-empty square brackets
1633 fn lorem< T: Eq >( t: T ) {
1634     let lorem: [ usize; 2 ] = [ ipsum, dolor ];
1635 }
1636 ```
1637
1638 ## `struct_lit_single_line`
1639
1640 Put small struct literals on a single line
1641
1642 - **Default value**: `true`
1643 - **Possible values**: `true`, `false`
1644 - **Stable**: No
1645
1646 #### `true` (default):
1647
1648 ```rust
1649 fn main() {
1650     let lorem = Lorem { foo: bar, baz: ofo };
1651 }
1652 ```
1653
1654 #### `false`:
1655
1656 ```rust
1657 fn main() {
1658     let lorem = Lorem {
1659         foo: bar,
1660         baz: ofo,
1661     };
1662 }
1663 ```
1664
1665 See also: [`indent_style`](#indent_style).
1666
1667
1668 ## `tab_spaces`
1669
1670 Number of spaces per tab
1671
1672 - **Default value**: `4`
1673 - **Possible values**: any positive integer
1674 - **Stable**: Yes
1675
1676 #### `4` (default):
1677
1678 ```rust
1679 fn lorem() {
1680     let ipsum = dolor();
1681     let sit = vec![
1682         "amet consectetur adipiscing elit amet",
1683         "consectetur adipiscing elit amet consectetur.",
1684     ];
1685 }
1686 ```
1687
1688 #### `2`:
1689
1690 ```rust
1691 fn lorem() {
1692   let ipsum = dolor();
1693   let sit = vec![
1694     "amet consectetur adipiscing elit amet",
1695     "consectetur adipiscing elit amet consectetur.",
1696   ];
1697 }
1698 ```
1699
1700 See also: [`hard_tabs`](#hard_tabs).
1701
1702
1703 ## `trailing_comma`
1704
1705 How to handle trailing commas for lists
1706
1707 - **Default value**: `"Vertical"`
1708 - **Possible values**: `"Always"`, `"Never"`, `"Vertical"`
1709 - **Stable**: No
1710
1711 #### `"Vertical"` (default):
1712
1713 ```rust
1714 fn main() {
1715     let Lorem { ipsum, dolor, sit } = amet;
1716     let Lorem {
1717         ipsum,
1718         dolor,
1719         sit,
1720         amet,
1721         consectetur,
1722         adipiscing,
1723     } = elit;
1724 }
1725 ```
1726
1727 #### `"Always"`:
1728
1729 ```rust
1730 fn main() {
1731     let Lorem { ipsum, dolor, sit, } = amet;
1732     let Lorem {
1733         ipsum,
1734         dolor,
1735         sit,
1736         amet,
1737         consectetur,
1738         adipiscing,
1739     } = elit;
1740 }
1741 ```
1742
1743 #### `"Never"`:
1744
1745 ```rust
1746 fn main() {
1747     let Lorem { ipsum, dolor, sit } = amet;
1748     let Lorem {
1749         ipsum,
1750         dolor,
1751         sit,
1752         amet,
1753         consectetur,
1754         adipiscing
1755     } = elit;
1756 }
1757 ```
1758
1759 See also: [`match_block_trailing_comma`](#match_block_trailing_comma).
1760
1761 ## `trailing_semicolon`
1762
1763 Add trailing semicolon after break, continue and return
1764
1765 - **Default value**: `true`
1766 - **Possible values**: `true`, `false`
1767 - **Stable**: No
1768
1769 #### `true` (default):
1770 ```rust
1771 fn foo() -> usize {
1772     return 0;
1773 }
1774 ```
1775
1776 #### `false`:
1777 ```rust
1778 fn foo() -> usize {
1779     return 0
1780 }
1781 ```
1782
1783 ## `type_punctuation_density`
1784
1785 Determines if `+` or `=` are wrapped in spaces in the punctuation of types
1786
1787 - **Default value**: `"Wide"`
1788 - **Possible values**: `"Compressed"`, `"Wide"`
1789 - **Stable**: No
1790
1791 #### `"Wide"` (default):
1792
1793 ```rust
1794 fn lorem<Ipsum: Dolor + Sit = Amet>() {
1795     // body
1796 }
1797 ```
1798
1799 #### `"Compressed"`:
1800
1801 ```rust
1802 fn lorem<Ipsum: Dolor+Sit=Amet>() {
1803     // body
1804 }
1805 ```
1806
1807 ## `use_field_init_shorthand`
1808
1809 Use field initialize shorthand if possible.
1810
1811 - **Default value**: `false`
1812 - **Possible values**: `true`, `false`
1813 - **Stable**: No
1814
1815 #### `false` (default):
1816
1817 ```rust
1818 struct Foo {
1819     x: u32,
1820     y: u32,
1821     z: u32,
1822 }
1823
1824 fn main() {
1825     let x = 1;
1826     let y = 2;
1827     let z = 3;
1828     let a = Foo { x: x, y: y, z: z };
1829 }
1830 ```
1831
1832 #### `true`:
1833
1834 ```rust
1835 struct Foo {
1836     x: u32,
1837     y: u32,
1838     z: u32,
1839 }
1840
1841 fn main() {
1842     let x = 1;
1843     let y = 2;
1844     let z = 3;
1845     let a = Foo { x, y, z };
1846 }
1847 ```
1848
1849 ## `use_try_shorthand`
1850
1851 Replace uses of the try! macro by the ? shorthand
1852
1853 - **Default value**: `false`
1854 - **Possible values**: `true`, `false`
1855 - **Stable**: No
1856
1857 #### `false` (default):
1858
1859 ```rust
1860 fn main() {
1861     let lorem = try!(ipsum.map(|dolor| dolor.sit()));
1862 }
1863 ```
1864
1865 #### `true`:
1866
1867 ```rust
1868 fn main() {
1869     let lorem = ipsum.map(|dolor| dolor.sit())?;
1870 }
1871 ```
1872
1873
1874 ## `wrap_comments`
1875
1876 Break comments to fit on the line
1877
1878 - **Default value**: `false`
1879 - **Possible values**: `true`, `false`
1880 - **Stable**: Yes
1881
1882 #### `false` (default):
1883
1884 ```rust
1885 // 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.
1886 ```
1887
1888 #### `true`:
1889
1890 ```rust
1891 // Lorem ipsum dolor sit amet, consectetur adipiscing elit,
1892 // sed do eiusmod tempor incididunt ut labore et dolore
1893 // magna aliqua. Ut enim ad minim veniam, quis nostrud
1894 // exercitation ullamco laboris nisi ut aliquip ex ea
1895 // commodo consequat.
1896 ```
1897
1898 ## `match_arm_blocks`
1899
1900 Wrap the body of arms in blocks when it does not fit on the same line with the pattern of arms
1901
1902 - **Default value**: `true`
1903 - **Possible values**: `true`, `false`
1904 - **Stable**: No
1905
1906 #### `true` (default):
1907
1908 ```rust
1909 fn main() {
1910     match lorem {
1911         true => {
1912             foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x)
1913         }
1914         false => println!("{}", sit),
1915     }
1916 }
1917 ```
1918
1919 #### `false`:
1920
1921 ```rust
1922 fn main() {
1923     match lorem {
1924         true =>
1925             foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x),
1926         false => println!("{}", sit),
1927     }
1928 }
1929 ```
1930
1931 See also: [`match_block_trailing_comma`](#match_block_trailing_comma).
1932
1933 ## `write_mode`
1934
1935 What Write Mode to use when none is supplied: Replace, Overwrite, Display, Diff, Coverage
1936
1937 - **Default value**: `"Overwrite"`
1938 - **Possible values**: `"Checkstyle"`, `"Coverage"`, `"Diff"`, `"Display"`, `"Overwrite"`, `"Plain"`, `"Replace"`
1939 - **Stable**: No
1940
1941 ## `blank_lines_upper_bound`
1942
1943 Maximum number of blank lines which can be put between items. If more than this number of consecutive empty
1944 lines are found, they are trimmed down to match this integer.
1945
1946 - **Default value**: `1`
1947 - **Possible values**: *unsigned integer*
1948 - **Stable**: No
1949
1950 ### Example
1951 Original Code:
1952
1953 ```rust
1954 #![rustfmt_skip]
1955
1956 fn foo() {
1957     println!("a");
1958 }
1959
1960
1961
1962 fn bar() {
1963     println!("b");
1964
1965
1966     println!("c");
1967 }
1968 ```
1969
1970 #### `1` (default):
1971 ```rust
1972 fn foo() {
1973     println!("a");
1974 }
1975
1976 fn bar() {
1977     println!("b");
1978
1979     println!("c");
1980 }
1981 ```
1982
1983 #### `2` (default):
1984 ```rust
1985 fn foo() {
1986     println!("a");
1987 }
1988
1989
1990 fn bar() {
1991     println!("b");
1992
1993
1994     println!("c");
1995 }
1996 ```
1997
1998 See also: [`blank_lines_lower_bound`](#blank_lines_lower_bound)
1999
2000 ## `blank_lines_lower_bound`
2001
2002 Minimum number of blank lines which must be put between items. If two items have fewer blank lines between
2003 them, additional blank lines are inserted.
2004
2005 - **Default value**: `0`
2006 - **Possible values**: *unsigned integer*
2007 - **Stable**: No
2008
2009 ### Example
2010 Original Code (rustfmt will not change it with the default value of `0`):
2011
2012 ```rust
2013 #![rustfmt_skip]
2014
2015 fn foo() {
2016     println!("a");
2017 }
2018 fn bar() {
2019     println!("b");
2020     println!("c");
2021 }
2022 ```
2023
2024 #### `1`
2025 ```rust
2026 fn foo() {
2027
2028     println!("a");
2029 }
2030
2031 fn bar() {
2032
2033     println!("b");
2034
2035     println!("c");
2036 }
2037 ```
2038
2039 ## `remove_blank_lines_at_start_or_end_of_block`
2040
2041 Remove blank lines at the start or the end of a block.
2042
2043 - **Default value**: `true`
2044 - **Possible values**: `true`, `false`
2045 - **Stable**: No
2046
2047 #### `true`
2048
2049 ```rust
2050 fn foo() {
2051     let msg = {
2052         let mut str = String::new();
2053         str.push_str("hello, ");
2054         str.push_str("world!");
2055         str
2056     };
2057     println!("{}", msg);
2058 }
2059 ```
2060
2061 #### `false`
2062
2063 ```rust
2064 fn foo() {
2065
2066     let msg = {
2067
2068         let mut str = String::new();
2069         str.push_str("hello, ");
2070         str.push_str("world!");
2071         str
2072
2073     };
2074     println!("{}", msg);
2075
2076 }
2077 ```
2078
2079 ## `required_version`
2080
2081 Require a specific version of rustfmt. If you want to make sure that the
2082 specific version of rustfmt is used in your CI, use this option.
2083
2084 - **Default value**: `CARGO_PKG_VERSION`
2085 - **Possible values**: any published version (e.g. `"0.3.8"`)
2086 - **Stable**: No
2087
2088 ## `hide_parse_errors`
2089
2090 Do not show parse errors if the parser failed to parse files.
2091
2092 - **Default value**: `false`
2093 - **Possible values**: `true`, `false`
2094 - **Stable**: No
2095
2096 ## `color`
2097
2098 Whether to use colored output or not.
2099
2100 - **Default value**: `"Auto"`
2101 - **Possible values**: "Auto", "Always", "Never"
2102 - **Stable**: No
2103
2104 ## `unstable_features`
2105
2106 Enable unstable features on stable channel.
2107
2108 - **Default value**: `false`
2109 - **Possible values**: `true`, `false`
2110 - **Stable**: Yes
2111
2112 ## `license_template_path`
2113
2114 Check whether beginnings of files match a license template.
2115
2116 - **Default value**: `""``
2117 - **Possible values**: path to a license template file
2118 - **Stable**: No
2119
2120 A license template is a plain text file which is matched literally against the
2121 beginning of each source file, except for `{}`-delimited blocks, which are
2122 matched as regular expressions. The following license template therefore
2123 matches strings like `// Copyright 2017 The Rust Project Developers.`, `//
2124 Copyright 2018 The Rust Project Developers.`, etc.:
2125
2126 ```
2127 // Copyright {\d+} The Rust Project Developers.
2128 ```
2129
2130 `\{`, `\}` and `\\` match literal braces / backslashes.
2131
2132 ## `ignore`
2133
2134 Skip formatting the specified files and directories.
2135
2136 - **Default value**: format every files
2137 - **Possible values**: See an example below
2138 - **Stable**: No
2139
2140 ### Example
2141
2142 If you want to ignore specific files, put the following to your config file:
2143
2144 ```toml
2145 ignore = [
2146     "src/types.rs",
2147     "src/foo/bar.rs",
2148 ]
2149 ```
2150
2151 If you want to ignore every file under `examples/`, put the following to your config file:
2152
2153 ```toml
2154 ignore [
2155     "examples",
2156 ]
2157 ```