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**: `"Auto"`
1342 - **Possible values**: `"Auto"`, `"Native"`, `"Unix"`, `"Windows"`
1343 - **Stable**: Yes
1344
1345 #### `Auto` (default):
1346
1347 The newline style is detected automatically on a per-file basis. Files
1348 with mixed line endings will be converted to the first detected line
1349 ending style.
1350
1351 #### `Native`
1352
1353 Line endings will be converted to `\r\n` on Windows and `\n` on all
1354 other platforms.
1355
1356 #### `Unix`
1357
1358 Line endings will be converted to `\n`.
1359
1360 #### `Windows`
1361
1362 Line endings will be converted to `\r\n`.
1363
1364 ## `normalize_comments`
1365
1366 Convert /* */ comments to // comments where possible
1367
1368 - **Default value**: `false`
1369 - **Possible values**: `true`, `false`
1370 - **Stable**: No
1371
1372 #### `false` (default):
1373
1374 ```rust
1375 // Lorem ipsum:
1376 fn dolor() -> usize {}
1377
1378 /* sit amet: */
1379 fn adipiscing() -> usize {}
1380 ```
1381
1382 #### `true`:
1383
1384 ```rust
1385 // Lorem ipsum:
1386 fn dolor() -> usize {}
1387
1388 // sit amet:
1389 fn adipiscing() -> usize {}
1390 ```
1391
1392 ## `remove_nested_parens`
1393
1394 Remove nested parens.
1395
1396 - **Default value**: `true`,
1397 - **Possible values**: `true`, `false`
1398 - **Stable**: Yes
1399
1400
1401 #### `true` (default):
1402 ```rust
1403 fn main() {
1404     (foo());
1405 }
1406 ```
1407
1408 #### `false`:
1409 ```rust
1410 fn main() {
1411     ((((foo()))));
1412 }
1413 ```
1414
1415
1416 ## `reorder_imports`
1417
1418 Reorder import and extern crate statements alphabetically in groups (a group is
1419 separated by a newline).
1420
1421 - **Default value**: `true`
1422 - **Possible values**: `true`, `false`
1423 - **Stable**: Yes
1424
1425 #### `true` (default):
1426
1427 ```rust
1428 use dolor;
1429 use ipsum;
1430 use lorem;
1431 use sit;
1432 ```
1433
1434 #### `false`:
1435
1436 ```rust
1437 use lorem;
1438 use ipsum;
1439 use dolor;
1440 use sit;
1441 ```
1442
1443
1444 ## `reorder_modules`
1445
1446 Reorder `mod` declarations alphabetically in group.
1447
1448 - **Default value**: `true`
1449 - **Possible values**: `true`, `false`
1450 - **Stable**: Yes
1451
1452 #### `true` (default)
1453
1454 ```rust
1455 mod a;
1456 mod b;
1457
1458 mod dolor;
1459 mod ipsum;
1460 mod lorem;
1461 mod sit;
1462 ```
1463
1464 #### `false`
1465
1466 ```rust
1467 mod b;
1468 mod a;
1469
1470 mod lorem;
1471 mod ipsum;
1472 mod dolor;
1473 mod sit;
1474 ```
1475
1476 **Note** `mod` with `#[macro_export]` will not be reordered since that could change the semantic
1477 of the original source code.
1478
1479 ## `reorder_impl_items`
1480
1481 Reorder impl items. `type` and `const` are put first, then macros and methods.
1482
1483 - **Default value**: `false`
1484 - **Possible values**: `true`, `false`
1485 - **Stable**: No
1486
1487 #### `false` (default)
1488
1489 ```rust
1490 struct Dummy;
1491
1492 impl Iterator for Dummy {
1493     fn next(&mut self) -> Option<Self::Item> {
1494         None
1495     }
1496
1497     type Item = i32;
1498 }
1499 ```
1500
1501 #### `true`
1502
1503 ```rust
1504 struct Dummy;
1505
1506 impl Iterator for Dummy {
1507     type Item = i32;
1508
1509     fn next(&mut self) -> Option<Self::Item> {
1510         None
1511     }
1512 }
1513 ```
1514
1515 ## `report_todo`
1516
1517 Report `TODO` items in comments.
1518
1519 - **Default value**: `"Never"`
1520 - **Possible values**: `"Always"`, `"Unnumbered"`, `"Never"`
1521 - **Stable**: No
1522
1523 Warns about any comments containing `TODO` in them when set to `"Always"`. If
1524 it contains a `#X` (with `X` being a number) in parentheses following the
1525 `TODO`, `"Unnumbered"` will ignore it.
1526
1527 See also [`report_fixme`](#report_fixme).
1528
1529 ## `report_fixme`
1530
1531 Report `FIXME` items in comments.
1532
1533 - **Default value**: `"Never"`
1534 - **Possible values**: `"Always"`, `"Unnumbered"`, `"Never"`
1535 - **Stable**: No
1536
1537 Warns about any comments containing `FIXME` in them when set to `"Always"`. If
1538 it contains a `#X` (with `X` being a number) in parentheses following the
1539 `FIXME`, `"Unnumbered"` will ignore it.
1540
1541 See also [`report_todo`](#report_todo).
1542
1543
1544 ## `skip_children`
1545
1546 Don't reformat out of line modules
1547
1548 - **Default value**: `false`
1549 - **Possible values**: `true`, `false`
1550 - **Stable**: No
1551
1552 ## `space_after_colon`
1553
1554 Leave a space after the colon.
1555
1556 - **Default value**: `true`
1557 - **Possible values**: `true`, `false`
1558 - **Stable**: No
1559
1560 #### `true` (default):
1561
1562 ```rust
1563 fn lorem<T: Eq>(t: T) {
1564     let lorem: Dolor = Lorem {
1565         ipsum: dolor,
1566         sit: amet,
1567     };
1568 }
1569 ```
1570
1571 #### `false`:
1572
1573 ```rust
1574 fn lorem<T:Eq>(t:T) {
1575     let lorem:Dolor = Lorem {
1576         ipsum:dolor,
1577         sit:amet,
1578     };
1579 }
1580 ```
1581
1582 See also: [`space_before_colon`](#space_before_colon).
1583
1584 ## `space_before_colon`
1585
1586 Leave a space before the colon.
1587
1588 - **Default value**: `false`
1589 - **Possible values**: `true`, `false`
1590 - **Stable**: No
1591
1592 #### `false` (default):
1593
1594 ```rust
1595 fn lorem<T: Eq>(t: T) {
1596     let lorem: Dolor = Lorem {
1597         ipsum: dolor,
1598         sit: amet,
1599     };
1600 }
1601 ```
1602
1603 #### `true`:
1604
1605 ```rust
1606 fn lorem<T : Eq>(t : T) {
1607     let lorem : Dolor = Lorem {
1608         ipsum : dolor,
1609         sit : amet,
1610     };
1611 }
1612 ```
1613
1614 See also: [`space_after_colon`](#space_after_colon).
1615
1616 ## `struct_field_align_threshold`
1617
1618 The maximum diff of width between struct fields to be aligned with each other.
1619
1620 - **Default value** : 0
1621 - **Possible values**: any positive integer
1622 - **Stable**: No
1623
1624 #### `0` (default):
1625
1626 ```rust
1627 struct Foo {
1628     x: u32,
1629     yy: u32,
1630     zzz: u32,
1631 }
1632 ```
1633
1634 #### `20`:
1635
1636 ```rust
1637 struct Foo {
1638     x:   u32,
1639     yy:  u32,
1640     zzz: u32,
1641 }
1642 ```
1643
1644 ## `spaces_around_ranges`
1645
1646 Put spaces around the .., ..=, and ... range operators
1647
1648 - **Default value**: `false`
1649 - **Possible values**: `true`, `false`
1650 - **Stable**: No
1651
1652 #### `false` (default):
1653
1654 ```rust
1655 fn main() {
1656     let lorem = 0..10;
1657     let ipsum = 0..=10;
1658
1659     match lorem {
1660         1..5 => foo(),
1661         _ => bar,
1662     }
1663
1664     match lorem {
1665         1..=5 => foo(),
1666         _ => bar,
1667     }
1668
1669     match lorem {
1670         1...5 => foo(),
1671         _ => bar,
1672     }
1673 }
1674 ```
1675
1676 #### `true`:
1677
1678 ```rust
1679 fn main() {
1680     let lorem = 0 .. 10;
1681     let ipsum = 0 ..= 10;
1682
1683     match lorem {
1684         1 .. 5 => foo(),
1685         _ => bar,
1686     }
1687
1688     match lorem {
1689         1 ..= 5 => foo(),
1690         _ => bar,
1691     }
1692
1693     match lorem {
1694         1 ... 5 => foo(),
1695         _ => bar,
1696     }
1697 }
1698 ```
1699
1700 ## `struct_lit_single_line`
1701
1702 Put small struct literals on a single line
1703
1704 - **Default value**: `true`
1705 - **Possible values**: `true`, `false`
1706 - **Stable**: No
1707
1708 #### `true` (default):
1709
1710 ```rust
1711 fn main() {
1712     let lorem = Lorem { foo: bar, baz: ofo };
1713 }
1714 ```
1715
1716 #### `false`:
1717
1718 ```rust
1719 fn main() {
1720     let lorem = Lorem {
1721         foo: bar,
1722         baz: ofo,
1723     };
1724 }
1725 ```
1726
1727 See also: [`indent_style`](#indent_style).
1728
1729
1730 ## `tab_spaces`
1731
1732 Number of spaces per tab
1733
1734 - **Default value**: `4`
1735 - **Possible values**: any positive integer
1736 - **Stable**: Yes
1737
1738 #### `4` (default):
1739
1740 ```rust
1741 fn lorem() {
1742     let ipsum = dolor();
1743     let sit = vec![
1744         "amet consectetur adipiscing elit amet",
1745         "consectetur adipiscing elit amet consectetur.",
1746     ];
1747 }
1748 ```
1749
1750 #### `2`:
1751
1752 ```rust
1753 fn lorem() {
1754   let ipsum = dolor();
1755   let sit = vec![
1756     "amet consectetur adipiscing elit amet",
1757     "consectetur adipiscing elit amet consectetur.",
1758   ];
1759 }
1760 ```
1761
1762 See also: [`hard_tabs`](#hard_tabs).
1763
1764
1765 ## `trailing_comma`
1766
1767 How to handle trailing commas for lists
1768
1769 - **Default value**: `"Vertical"`
1770 - **Possible values**: `"Always"`, `"Never"`, `"Vertical"`
1771 - **Stable**: No
1772
1773 #### `"Vertical"` (default):
1774
1775 ```rust
1776 fn main() {
1777     let Lorem { ipsum, dolor, sit } = amet;
1778     let Lorem {
1779         ipsum,
1780         dolor,
1781         sit,
1782         amet,
1783         consectetur,
1784         adipiscing,
1785     } = elit;
1786 }
1787 ```
1788
1789 #### `"Always"`:
1790
1791 ```rust
1792 fn main() {
1793     let Lorem { ipsum, dolor, sit, } = amet;
1794     let Lorem {
1795         ipsum,
1796         dolor,
1797         sit,
1798         amet,
1799         consectetur,
1800         adipiscing,
1801     } = elit;
1802 }
1803 ```
1804
1805 #### `"Never"`:
1806
1807 ```rust
1808 fn main() {
1809     let Lorem { ipsum, dolor, sit } = amet;
1810     let Lorem {
1811         ipsum,
1812         dolor,
1813         sit,
1814         amet,
1815         consectetur,
1816         adipiscing
1817     } = elit;
1818 }
1819 ```
1820
1821 See also: [`match_block_trailing_comma`](#match_block_trailing_comma).
1822
1823 ## `trailing_semicolon`
1824
1825 Add trailing semicolon after break, continue and return
1826
1827 - **Default value**: `true`
1828 - **Possible values**: `true`, `false`
1829 - **Stable**: No
1830
1831 #### `true` (default):
1832 ```rust
1833 fn foo() -> usize {
1834     return 0;
1835 }
1836 ```
1837
1838 #### `false`:
1839 ```rust
1840 fn foo() -> usize {
1841     return 0
1842 }
1843 ```
1844
1845 ## `type_punctuation_density`
1846
1847 Determines if `+` or `=` are wrapped in spaces in the punctuation of types
1848
1849 - **Default value**: `"Wide"`
1850 - **Possible values**: `"Compressed"`, `"Wide"`
1851 - **Stable**: No
1852
1853 #### `"Wide"` (default):
1854
1855 ```rust
1856 fn lorem<Ipsum: Dolor + Sit = Amet>() {
1857     // body
1858 }
1859 ```
1860
1861 #### `"Compressed"`:
1862
1863 ```rust
1864 fn lorem<Ipsum: Dolor+Sit=Amet>() {
1865     // body
1866 }
1867 ```
1868
1869 ## `use_field_init_shorthand`
1870
1871 Use field initialize shorthand if possible.
1872
1873 - **Default value**: `false`
1874 - **Possible values**: `true`, `false`
1875 - **Stable**: Yes
1876
1877 #### `false` (default):
1878
1879 ```rust
1880 struct Foo {
1881     x: u32,
1882     y: u32,
1883     z: u32,
1884 }
1885
1886 fn main() {
1887     let x = 1;
1888     let y = 2;
1889     let z = 3;
1890     let a = Foo { x: x, y: y, z: z };
1891 }
1892 ```
1893
1894 #### `true`:
1895
1896 ```rust
1897 struct Foo {
1898     x: u32,
1899     y: u32,
1900     z: u32,
1901 }
1902
1903 fn main() {
1904     let x = 1;
1905     let y = 2;
1906     let z = 3;
1907     let a = Foo { x, y, z };
1908 }
1909 ```
1910
1911 ## `use_try_shorthand`
1912
1913 Replace uses of the try! macro by the ? shorthand
1914
1915 - **Default value**: `false`
1916 - **Possible values**: `true`, `false`
1917 - **Stable**: Yes
1918
1919 #### `false` (default):
1920
1921 ```rust
1922 fn main() {
1923     let lorem = try!(ipsum.map(|dolor| dolor.sit()));
1924 }
1925 ```
1926
1927 #### `true`:
1928
1929 ```rust
1930 fn main() {
1931     let lorem = ipsum.map(|dolor| dolor.sit())?;
1932 }
1933 ```
1934
1935
1936 ## `wrap_comments`
1937
1938 Break comments to fit on the line
1939
1940 - **Default value**: `false`
1941 - **Possible values**: `true`, `false`
1942 - **Stable**: No
1943
1944 #### `false` (default):
1945
1946 ```rust
1947 // 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.
1948 ```
1949
1950 #### `true`:
1951
1952 ```rust
1953 // Lorem ipsum dolor sit amet, consectetur adipiscing elit,
1954 // sed do eiusmod tempor incididunt ut labore et dolore
1955 // magna aliqua. Ut enim ad minim veniam, quis nostrud
1956 // exercitation ullamco laboris nisi ut aliquip ex ea
1957 // commodo consequat.
1958 ```
1959
1960 ## `match_arm_blocks`
1961
1962 Wrap the body of arms in blocks when it does not fit on the same line with the pattern of arms
1963
1964 - **Default value**: `true`
1965 - **Possible values**: `true`, `false`
1966 - **Stable**: No
1967
1968 #### `true` (default):
1969
1970 ```rust
1971 fn main() {
1972     match lorem {
1973         true => {
1974             foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x)
1975         }
1976         false => println!("{}", sit),
1977     }
1978 }
1979 ```
1980
1981 #### `false`:
1982
1983 ```rust
1984 fn main() {
1985     match lorem {
1986         true =>
1987             foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x),
1988         false => println!("{}", sit),
1989     }
1990 }
1991 ```
1992
1993 See also: [`match_block_trailing_comma`](#match_block_trailing_comma).
1994
1995
1996 ## `blank_lines_upper_bound`
1997
1998 Maximum number of blank lines which can be put between items. If more than this number of consecutive empty
1999 lines are found, they are trimmed down to match this integer.
2000
2001 - **Default value**: `1`
2002 - **Possible values**: *unsigned integer*
2003 - **Stable**: No
2004
2005 ### Example
2006 Original Code:
2007
2008 ```rust
2009 #![rustfmt::skip]
2010
2011 fn foo() {
2012     println!("a");
2013 }
2014
2015
2016
2017 fn bar() {
2018     println!("b");
2019
2020
2021     println!("c");
2022 }
2023 ```
2024
2025 #### `1` (default):
2026 ```rust
2027 fn foo() {
2028     println!("a");
2029 }
2030
2031 fn bar() {
2032     println!("b");
2033
2034     println!("c");
2035 }
2036 ```
2037
2038 #### `2`:
2039 ```rust
2040 fn foo() {
2041     println!("a");
2042 }
2043
2044
2045 fn bar() {
2046     println!("b");
2047
2048
2049     println!("c");
2050 }
2051 ```
2052
2053 See also: [`blank_lines_lower_bound`](#blank_lines_lower_bound)
2054
2055 ## `blank_lines_lower_bound`
2056
2057 Minimum number of blank lines which must be put between items. If two items have fewer blank lines between
2058 them, additional blank lines are inserted.
2059
2060 - **Default value**: `0`
2061 - **Possible values**: *unsigned integer*
2062 - **Stable**: No
2063
2064 ### Example
2065 Original Code (rustfmt will not change it with the default value of `0`):
2066
2067 ```rust
2068 #![rustfmt::skip]
2069
2070 fn foo() {
2071     println!("a");
2072 }
2073 fn bar() {
2074     println!("b");
2075     println!("c");
2076 }
2077 ```
2078
2079 #### `1`
2080 ```rust
2081 fn foo() {
2082
2083     println!("a");
2084 }
2085
2086 fn bar() {
2087
2088     println!("b");
2089
2090     println!("c");
2091 }
2092 ```
2093
2094
2095 ## `required_version`
2096
2097 Require a specific version of rustfmt. If you want to make sure that the
2098 specific version of rustfmt is used in your CI, use this option.
2099
2100 - **Default value**: `CARGO_PKG_VERSION`
2101 - **Possible values**: any published version (e.g. `"0.3.8"`)
2102 - **Stable**: No
2103
2104 ## `hide_parse_errors`
2105
2106 Do not show parse errors if the parser failed to parse files.
2107
2108 - **Default value**: `false`
2109 - **Possible values**: `true`, `false`
2110 - **Stable**: No
2111
2112 ## `color`
2113
2114 Whether to use colored output or not.
2115
2116 - **Default value**: `"Auto"`
2117 - **Possible values**: "Auto", "Always", "Never"
2118 - **Stable**: No
2119
2120 ## `unstable_features`
2121
2122 Enable unstable features on stable channel.
2123
2124 - **Default value**: `false`
2125 - **Possible values**: `true`, `false`
2126 - **Stable**: No
2127
2128 ## `license_template_path`
2129
2130 Check whether beginnings of files match a license template.
2131
2132 - **Default value**: `""``
2133 - **Possible values**: path to a license template file
2134 - **Stable**: No
2135
2136 A license template is a plain text file which is matched literally against the
2137 beginning of each source file, except for `{}`-delimited blocks, which are
2138 matched as regular expressions. The following license template therefore
2139 matches strings like `// Copyright 2017 The Rust Project Developers.`, `//
2140 Copyright 2018 The Rust Project Developers.`, etc.:
2141
2142 ```
2143 // Copyright {\d+} The Rust Project Developers.
2144 ```
2145
2146 `\{`, `\}` and `\\` match literal braces / backslashes.
2147
2148 ## `ignore`
2149
2150 Skip formatting the specified files and directories.
2151
2152 - **Default value**: format every files
2153 - **Possible values**: See an example below
2154 - **Stable**: No
2155
2156 ### Example
2157
2158 If you want to ignore specific files, put the following to your config file:
2159
2160 ```toml
2161 ignore = [
2162     "src/types.rs",
2163     "src/foo/bar.rs",
2164 ]
2165 ```
2166
2167 If you want to ignore every file under `examples/`, put the following to your config file:
2168
2169 ```toml
2170 ignore = [
2171     "examples",
2172 ]
2173 ```
2174
2175 ## `edition`
2176
2177 Specifies which edition is used by the parser.
2178
2179 - **Default value**: `2015`
2180 - **Possible values**: `2015`, `2018`
2181 - **Stable**: No
2182
2183 ### Example
2184
2185 If you want to format code that requires edition 2018, add the following to your config file:
2186
2187 ```toml
2188 edition = "2018"
2189 ```
2190
2191 ## `emit_mode`
2192
2193 Internal option
2194
2195 ## `make_backup`
2196
2197 Internal option, use `--backup`