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