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 ## `enum_discrim_align_threshold`
 889
 890 The maximum length of enum variant having discriminant, that gets vertically aligned with others.
 891 Variants without discriminants would be ignored for the purpose of alignment.
 892
 893 Note that this is not how much whitespace is inserted, but instead the longest variant name that
 894 doesn't get ignored when aligning.
 895
 896 - **Default value** : 0
 897 - **Possible values**: any positive integer
 898 - **Stable**: No
 899
 900 #### `0` (default):
 901
 902 ```rust
 903 enum Bar {
 904     A = 0,
 905     Bb = 1,
 906     RandomLongVariantGoesHere = 10,
 907     Ccc = 71,
 908 }
 909
 910 enum Bar {
 911     VeryLongVariantNameHereA = 0,
 912     VeryLongVariantNameHereBb = 1,
 913     VeryLongVariantNameHereCcc = 2,
 914 }
 915 ```
 916
 917 #### `20`:
 918
 919 ```rust
 920 enum Foo {
 921     A   = 0,
 922     Bb  = 1,
 923     RandomLongVariantGoesHere = 10,
 924     Ccc = 2,
 925 }
 926
 927 enum Bar {
 928     VeryLongVariantNameHereA = 0,
 929     VeryLongVariantNameHereBb = 1,
 930     VeryLongVariantNameHereCcc = 2,
 931 }
 932 ```
 933
 934
 935 ## `fn_single_line`
 936
 937 Put single-expression functions on a single line
 938
 939 - **Default value**: `false`
 940 - **Possible values**: `true`, `false`
 941 - **Stable**: No
 942
 943 #### `false` (default):
 944
 945 ```rust
 946 fn lorem() -> usize {
 947     42
 948 }
 949
 950 fn lorem() -> usize {
 951     let ipsum = 42;
 952     ipsum
 953 }
 954 ```
 955
 956 #### `true`:
 957
 958 ```rust
 959 fn lorem() -> usize { 42 }
 960
 961 fn lorem() -> usize {
 962     let ipsum = 42;
 963     ipsum
 964 }
 965 ```
 966
 967 See also [`control_brace_style`](#control_brace_style).
 968
 969
 970 ## `where_single_line`
 971
 972 Forces the `where` clause to be laid out on a single line.
 973
 974 - **Default value**: `false`
 975 - **Possible values**: `true`, `false`
 976 - **Stable**: No
 977
 978 #### `false` (default):
 979
 980 ```rust
 981 impl<T> Lorem for T
 982 where
 983     Option<T>: Ipsum,
 984 {
 985     // body
 986 }
 987 ```
 988
 989 #### `true`:
 990
 991 ```rust
 992 impl<T> Lorem for T
 993 where Option<T>: Ipsum
 994 {
 995     // body
 996 }
 997 ```
 998
 999 See also [`brace_style`](#brace_style), [`control_brace_style`](#control_brace_style).
1000
1001
1002 ## `force_explicit_abi`
1003
1004 Always print the abi for extern items
1005
1006 - **Default value**: `true`
1007 - **Possible values**: `true`, `false`
1008 - **Stable**: Yes
1009
1010 **Note:** Non-"C" ABIs are always printed. If `false` then "C" is removed.
1011
1012 #### `true` (default):
1013
1014 ```rust
1015 extern "C" {
1016     pub static lorem: c_int;
1017 }
1018 ```
1019
1020 #### `false`:
1021
1022 ```rust
1023 extern {
1024     pub static lorem: c_int;
1025 }
1026 ```
1027
1028 ## `format_strings`
1029
1030 Format string literals where necessary
1031
1032 - **Default value**: `false`
1033 - **Possible values**: `true`, `false`
1034 - **Stable**: No
1035
1036 #### `false` (default):
1037
1038 ```rust
1039 fn main() {
1040     let lorem =
1041         "ipsum dolor sit amet consectetur adipiscing elit lorem ipsum dolor sit amet consectetur adipiscing";
1042 }
1043 ```
1044
1045 #### `true`:
1046
1047 ```rust
1048 fn main() {
1049     let lorem = "ipsum dolor sit amet consectetur adipiscing elit lorem ipsum dolor sit amet \
1050                  consectetur adipiscing";
1051 }
1052 ```
1053
1054 See also [`max_width`](#max_width).
1055
1056 ## `format_macro_matchers`
1057
1058 Format the metavariable matching patterns in macros.
1059
1060 - **Default value**: `false`
1061 - **Possible values**: `true`, `false`
1062 - **Stable**: No
1063
1064 #### `false` (default):
1065
1066 ```rust
1067 macro_rules! foo {
1068     ($a: ident : $b: ty) => {
1069         $a(42): $b;
1070     };
1071     ($a: ident $b: ident $c: ident) => {
1072         $a = $b + $c;
1073     };
1074 }
1075 ```
1076
1077 #### `true`:
1078
1079 ```rust
1080 macro_rules! foo {
1081     ($a:ident : $b:ty) => {
1082         $a(42): $b;
1083     };
1084     ($a:ident $b:ident $c:ident) => {
1085         $a = $b + $c;
1086     };
1087 }
1088 ```
1089
1090 See also [`format_macro_bodies`](#format_macro_bodies).
1091
1092
1093 ## `format_macro_bodies`
1094
1095 Format the bodies of macros.
1096
1097 - **Default value**: `true`
1098 - **Possible values**: `true`, `false`
1099 - **Stable**: No
1100
1101 #### `true` (default):
1102
1103 ```rust
1104 macro_rules! foo {
1105     ($a: ident : $b: ty) => {
1106         $a(42): $b;
1107     };
1108     ($a: ident $b: ident $c: ident) => {
1109         $a = $b + $c;
1110     };
1111 }
1112 ```
1113
1114 #### `false`:
1115
1116 ```rust
1117 macro_rules! foo {
1118     ($a: ident : $b: ty) => { $a(42): $b; };
1119     ($a: ident $b: ident $c: ident) => { $a=$b+$c; };
1120 }
1121 ```
1122
1123 See also [`format_macro_matchers`](#format_macro_matchers).
1124
1125
1126 ## `hard_tabs`
1127
1128 Use tab characters for indentation, spaces for alignment
1129
1130 - **Default value**: `false`
1131 - **Possible values**: `true`, `false`
1132 - **Stable**: Yes
1133
1134 #### `false` (default):
1135
1136 ```rust
1137 fn lorem() -> usize {
1138     42 // spaces before 42
1139 }
1140 ```
1141
1142 #### `true`:
1143
1144 ```rust
1145 fn lorem() -> usize {
1146         42 // tabs before 42
1147 }
1148 ```
1149
1150 See also: [`tab_spaces`](#tab_spaces).
1151
1152
1153 ## `imports_indent`
1154
1155 Indent style of imports
1156
1157 - **Default Value**: `"Block"`
1158 - **Possible values**: `"Block"`, `"Visual"`
1159 - **Stable**: No
1160
1161 #### `"Block"` (default):
1162
1163 ```rust
1164 use foo::{
1165     xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx, yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy,
1166     zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz,
1167 };
1168 ```
1169
1170 #### `"Visual"`:
1171
1172 ```rust
1173 use foo::{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx, yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy,
1174           zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz};
1175 ```
1176
1177 See also: [`imports_layout`](#imports_layout).
1178
1179 ## `imports_layout`
1180
1181 Item layout inside a imports block
1182
1183 - **Default value**: "Mixed"
1184 - **Possible values**: "Horizontal", "HorizontalVertical", "Mixed", "Vertical"
1185 - **Stable**: No
1186
1187 #### `"Mixed"` (default):
1188
1189 ```rust
1190 use foo::{xxxxxxxxxxxxxxxxxx, yyyyyyyyyyyyyyyyyy, zzzzzzzzzzzzzzzzzz};
1191
1192 use foo::{
1193     aaaaaaaaaaaaaaaaaa, bbbbbbbbbbbbbbbbbb, cccccccccccccccccc, dddddddddddddddddd,
1194     eeeeeeeeeeeeeeeeee, ffffffffffffffffff,
1195 };
1196 ```
1197
1198 #### `"Horizontal"`:
1199
1200 **Note**: This option forces all imports onto one line and may exceed `max_width`.
1201
1202 ```rust
1203 use foo::{xxx, yyy, zzz};
1204
1205 use foo::{aaa, bbb, ccc, ddd, eee, fff};
1206 ```
1207
1208 #### `"HorizontalVertical"`:
1209
1210 ```rust
1211 use foo::{xxxxxxxxxxxxxxxxxx, yyyyyyyyyyyyyyyyyy, zzzzzzzzzzzzzzzzzz};
1212
1213 use foo::{
1214     aaaaaaaaaaaaaaaaaa,
1215     bbbbbbbbbbbbbbbbbb,
1216     cccccccccccccccccc,
1217     dddddddddddddddddd,
1218     eeeeeeeeeeeeeeeeee,
1219     ffffffffffffffffff,
1220 };
1221 ```
1222
1223 #### `"Vertical"`:
1224
1225 ```rust
1226 use foo::{
1227     xxx,
1228     yyy,
1229     zzz,
1230 };
1231
1232 use foo::{
1233     aaa,
1234     bbb,
1235     ccc,
1236     ddd,
1237     eee,
1238     fff,
1239 };
1240 ```
1241
1242 ## `merge_imports`
1243
1244 Merge multiple imports into a single nested import.
1245
1246 - **Default value**: `false`
1247 - **Possible values**: `true`, `false`
1248 - **Stable**: No
1249
1250 #### `false` (default):
1251
1252 ```rust
1253 use foo::{a, c, d};
1254 use foo::{b, g};
1255 use foo::{e, f};
1256 ```
1257
1258 #### `true`:
1259
1260 ```rust
1261 use foo::{a, b, c, d, e, f, g};
1262 ```
1263
1264
1265 ## `match_block_trailing_comma`
1266
1267 Put a trailing comma after a block based match arm (non-block arms are not affected)
1268
1269 - **Default value**: `false`
1270 - **Possible values**: `true`, `false`
1271 - **Stable**: No
1272
1273 #### `false` (default):
1274
1275 ```rust
1276 fn main() {
1277     match lorem {
1278         Lorem::Ipsum => {
1279             println!("ipsum");
1280         }
1281         Lorem::Dolor => println!("dolor"),
1282     }
1283 }
1284 ```
1285
1286 #### `true`:
1287
1288 ```rust
1289 fn main() {
1290     match lorem {
1291         Lorem::Ipsum => {
1292             println!("ipsum");
1293         },
1294         Lorem::Dolor => println!("dolor"),
1295     }
1296 }
1297 ```
1298
1299 See also: [`trailing_comma`](#trailing_comma), [`match_arm_blocks`](#match_arm_blocks).
1300
1301 ## `max_width`
1302
1303 Maximum width of each line
1304
1305 - **Default value**: `100`
1306 - **Possible values**: any positive integer
1307 - **Stable**: Yes
1308
1309 See also [`error_on_line_overflow`](#error_on_line_overflow).
1310
1311 ## `merge_derives`
1312
1313 Merge multiple derives into a single one.
1314
1315 - **Default value**: `true`
1316 - **Possible values**: `true`, `false`
1317 - **Stable**: Yes
1318
1319 #### `true` (default):
1320
1321 ```rust
1322 #[derive(Eq, PartialEq, Debug, Copy, Clone)]
1323 pub enum Foo {}
1324 ```
1325
1326 #### `false`:
1327
1328 ```rust
1329 #[derive(Eq, PartialEq)]
1330 #[derive(Debug)]
1331 #[derive(Copy, Clone)]
1332 pub enum Foo {}
1333 ```
1334
1335 ## `force_multiline_blocks`
1336
1337 Force multiline closure and match arm bodies to be wrapped in a block
1338
1339 - **Default value**: `false`
1340 - **Possible values**: `false`, `true`
1341 - **Stable**: No
1342
1343 #### `false` (default):
1344
1345 ```rust
1346 fn main() {
1347     result.and_then(|maybe_value| match maybe_value {
1348         None => foo(),
1349         Some(value) => bar(),
1350     });
1351
1352     match lorem {
1353         None => |ipsum| {
1354             println!("Hello World");
1355         },
1356         Some(dolor) => foo(),
1357     }
1358 }
1359 ```
1360
1361 #### `true`:
1362
1363 ```rust
1364 fn main() {
1365     result.and_then(|maybe_value| {
1366         match maybe_value {
1367             None => foo(),
1368             Some(value) => bar(),
1369         }
1370     });
1371
1372     match lorem {
1373         None => {
1374             |ipsum| {
1375                 println!("Hello World");
1376             }
1377         }
1378         Some(dolor) => foo(),
1379     }
1380 }
1381 ```
1382
1383
1384 ## `newline_style`
1385
1386 Unix or Windows line endings
1387
1388 - **Default value**: `"Auto"`
1389 - **Possible values**: `"Auto"`, `"Native"`, `"Unix"`, `"Windows"`
1390 - **Stable**: Yes
1391
1392 #### `Auto` (default):
1393
1394 The newline style is detected automatically on a per-file basis. Files
1395 with mixed line endings will be converted to the first detected line
1396 ending style.
1397
1398 #### `Native`
1399
1400 Line endings will be converted to `\r\n` on Windows and `\n` on all
1401 other platforms.
1402
1403 #### `Unix`
1404
1405 Line endings will be converted to `\n`.
1406
1407 #### `Windows`
1408
1409 Line endings will be converted to `\r\n`.
1410
1411 ## `normalize_comments`
1412
1413 Convert /* */ comments to // comments where possible
1414
1415 - **Default value**: `false`
1416 - **Possible values**: `true`, `false`
1417 - **Stable**: No
1418
1419 #### `false` (default):
1420
1421 ```rust
1422 // Lorem ipsum:
1423 fn dolor() -> usize {}
1424
1425 /* sit amet: */
1426 fn adipiscing() -> usize {}
1427 ```
1428
1429 #### `true`:
1430
1431 ```rust
1432 // Lorem ipsum:
1433 fn dolor() -> usize {}
1434
1435 // sit amet:
1436 fn adipiscing() -> usize {}
1437 ```
1438
1439 ## `remove_nested_parens`
1440
1441 Remove nested parens.
1442
1443 - **Default value**: `true`,
1444 - **Possible values**: `true`, `false`
1445 - **Stable**: Yes
1446
1447
1448 #### `true` (default):
1449 ```rust
1450 fn main() {
1451     (foo());
1452 }
1453 ```
1454
1455 #### `false`:
1456 ```rust
1457 fn main() {
1458     ((((foo()))));
1459 }
1460 ```
1461
1462
1463 ## `reorder_imports`
1464
1465 Reorder import and extern crate statements alphabetically in groups (a group is
1466 separated by a newline).
1467
1468 - **Default value**: `true`
1469 - **Possible values**: `true`, `false`
1470 - **Stable**: Yes
1471
1472 #### `true` (default):
1473
1474 ```rust
1475 use dolor;
1476 use ipsum;
1477 use lorem;
1478 use sit;
1479 ```
1480
1481 #### `false`:
1482
1483 ```rust
1484 use lorem;
1485 use ipsum;
1486 use dolor;
1487 use sit;
1488 ```
1489
1490
1491 ## `reorder_modules`
1492
1493 Reorder `mod` declarations alphabetically in group.
1494
1495 - **Default value**: `true`
1496 - **Possible values**: `true`, `false`
1497 - **Stable**: Yes
1498
1499 #### `true` (default)
1500
1501 ```rust
1502 mod a;
1503 mod b;
1504
1505 mod dolor;
1506 mod ipsum;
1507 mod lorem;
1508 mod sit;
1509 ```
1510
1511 #### `false`
1512
1513 ```rust
1514 mod b;
1515 mod a;
1516
1517 mod lorem;
1518 mod ipsum;
1519 mod dolor;
1520 mod sit;
1521 ```
1522
1523 **Note** `mod` with `#[macro_export]` will not be reordered since that could change the semantic
1524 of the original source code.
1525
1526 ## `reorder_impl_items`
1527
1528 Reorder impl items. `type` and `const` are put first, then macros and methods.
1529
1530 - **Default value**: `false`
1531 - **Possible values**: `true`, `false`
1532 - **Stable**: No
1533
1534 #### `false` (default)
1535
1536 ```rust
1537 struct Dummy;
1538
1539 impl Iterator for Dummy {
1540     fn next(&mut self) -> Option<Self::Item> {
1541         None
1542     }
1543
1544     type Item = i32;
1545 }
1546 ```
1547
1548 #### `true`
1549
1550 ```rust
1551 struct Dummy;
1552
1553 impl Iterator for Dummy {
1554     type Item = i32;
1555
1556     fn next(&mut self) -> Option<Self::Item> {
1557         None
1558     }
1559 }
1560 ```
1561
1562 ## `report_todo`
1563
1564 Report `TODO` items in comments.
1565
1566 - **Default value**: `"Never"`
1567 - **Possible values**: `"Always"`, `"Unnumbered"`, `"Never"`
1568 - **Stable**: No
1569
1570 Warns about any comments containing `TODO` in them when set to `"Always"`. If
1571 it contains a `#X` (with `X` being a number) in parentheses following the
1572 `TODO`, `"Unnumbered"` will ignore it.
1573
1574 See also [`report_fixme`](#report_fixme).
1575
1576 ## `report_fixme`
1577
1578 Report `FIXME` items in comments.
1579
1580 - **Default value**: `"Never"`
1581 - **Possible values**: `"Always"`, `"Unnumbered"`, `"Never"`
1582 - **Stable**: No
1583
1584 Warns about any comments containing `FIXME` in them when set to `"Always"`. If
1585 it contains a `#X` (with `X` being a number) in parentheses following the
1586 `FIXME`, `"Unnumbered"` will ignore it.
1587
1588 See also [`report_todo`](#report_todo).
1589
1590
1591 ## `skip_children`
1592
1593 Don't reformat out of line modules
1594
1595 - **Default value**: `false`
1596 - **Possible values**: `true`, `false`
1597 - **Stable**: No
1598
1599 ## `space_after_colon`
1600
1601 Leave a space after the colon.
1602
1603 - **Default value**: `true`
1604 - **Possible values**: `true`, `false`
1605 - **Stable**: No
1606
1607 #### `true` (default):
1608
1609 ```rust
1610 fn lorem<T: Eq>(t: T) {
1611     let lorem: Dolor = Lorem {
1612         ipsum: dolor,
1613         sit: amet,
1614     };
1615 }
1616 ```
1617
1618 #### `false`:
1619
1620 ```rust
1621 fn lorem<T:Eq>(t:T) {
1622     let lorem:Dolor = Lorem {
1623         ipsum:dolor,
1624         sit:amet,
1625     };
1626 }
1627 ```
1628
1629 See also: [`space_before_colon`](#space_before_colon).
1630
1631 ## `space_before_colon`
1632
1633 Leave a space before the colon.
1634
1635 - **Default value**: `false`
1636 - **Possible values**: `true`, `false`
1637 - **Stable**: No
1638
1639 #### `false` (default):
1640
1641 ```rust
1642 fn lorem<T: Eq>(t: T) {
1643     let lorem: Dolor = Lorem {
1644         ipsum: dolor,
1645         sit: amet,
1646     };
1647 }
1648 ```
1649
1650 #### `true`:
1651
1652 ```rust
1653 fn lorem<T : Eq>(t : T) {
1654     let lorem : Dolor = Lorem {
1655         ipsum : dolor,
1656         sit : amet,
1657     };
1658 }
1659 ```
1660
1661 See also: [`space_after_colon`](#space_after_colon).
1662
1663 ## `struct_field_align_threshold`
1664
1665 The maximum diff of width between struct fields to be aligned with each other.
1666
1667 - **Default value** : 0
1668 - **Possible values**: any positive integer
1669 - **Stable**: No
1670
1671 #### `0` (default):
1672
1673 ```rust
1674 struct Foo {
1675     x: u32,
1676     yy: u32,
1677     zzz: u32,
1678 }
1679 ```
1680
1681 #### `20`:
1682
1683 ```rust
1684 struct Foo {
1685     x:   u32,
1686     yy:  u32,
1687     zzz: u32,
1688 }
1689 ```
1690
1691 ## `spaces_around_ranges`
1692
1693 Put spaces around the .., ..=, and ... range operators
1694
1695 - **Default value**: `false`
1696 - **Possible values**: `true`, `false`
1697 - **Stable**: No
1698
1699 #### `false` (default):
1700
1701 ```rust
1702 fn main() {
1703     let lorem = 0..10;
1704     let ipsum = 0..=10;
1705
1706     match lorem {
1707         1..5 => foo(),
1708         _ => bar,
1709     }
1710
1711     match lorem {
1712         1..=5 => foo(),
1713         _ => bar,
1714     }
1715
1716     match lorem {
1717         1...5 => foo(),
1718         _ => bar,
1719     }
1720 }
1721 ```
1722
1723 #### `true`:
1724
1725 ```rust
1726 fn main() {
1727     let lorem = 0 .. 10;
1728     let ipsum = 0 ..= 10;
1729
1730     match lorem {
1731         1 .. 5 => foo(),
1732         _ => bar,
1733     }
1734
1735     match lorem {
1736         1 ..= 5 => foo(),
1737         _ => bar,
1738     }
1739
1740     match lorem {
1741         1 ... 5 => foo(),
1742         _ => bar,
1743     }
1744 }
1745 ```
1746
1747 ## `struct_lit_single_line`
1748
1749 Put small struct literals on a single line
1750
1751 - **Default value**: `true`
1752 - **Possible values**: `true`, `false`
1753 - **Stable**: No
1754
1755 #### `true` (default):
1756
1757 ```rust
1758 fn main() {
1759     let lorem = Lorem { foo: bar, baz: ofo };
1760 }
1761 ```
1762
1763 #### `false`:
1764
1765 ```rust
1766 fn main() {
1767     let lorem = Lorem {
1768         foo: bar,
1769         baz: ofo,
1770     };
1771 }
1772 ```
1773
1774 See also: [`indent_style`](#indent_style).
1775
1776
1777 ## `tab_spaces`
1778
1779 Number of spaces per tab
1780
1781 - **Default value**: `4`
1782 - **Possible values**: any positive integer
1783 - **Stable**: Yes
1784
1785 #### `4` (default):
1786
1787 ```rust
1788 fn lorem() {
1789     let ipsum = dolor();
1790     let sit = vec![
1791         "amet consectetur adipiscing elit amet",
1792         "consectetur adipiscing elit amet consectetur.",
1793     ];
1794 }
1795 ```
1796
1797 #### `2`:
1798
1799 ```rust
1800 fn lorem() {
1801   let ipsum = dolor();
1802   let sit = vec![
1803     "amet consectetur adipiscing elit amet",
1804     "consectetur adipiscing elit amet consectetur.",
1805   ];
1806 }
1807 ```
1808
1809 See also: [`hard_tabs`](#hard_tabs).
1810
1811
1812 ## `trailing_comma`
1813
1814 How to handle trailing commas for lists
1815
1816 - **Default value**: `"Vertical"`
1817 - **Possible values**: `"Always"`, `"Never"`, `"Vertical"`
1818 - **Stable**: No
1819
1820 #### `"Vertical"` (default):
1821
1822 ```rust
1823 fn main() {
1824     let Lorem { ipsum, dolor, sit } = amet;
1825     let Lorem {
1826         ipsum,
1827         dolor,
1828         sit,
1829         amet,
1830         consectetur,
1831         adipiscing,
1832     } = elit;
1833 }
1834 ```
1835
1836 #### `"Always"`:
1837
1838 ```rust
1839 fn main() {
1840     let Lorem { ipsum, dolor, sit, } = amet;
1841     let Lorem {
1842         ipsum,
1843         dolor,
1844         sit,
1845         amet,
1846         consectetur,
1847         adipiscing,
1848     } = elit;
1849 }
1850 ```
1851
1852 #### `"Never"`:
1853
1854 ```rust
1855 fn main() {
1856     let Lorem { ipsum, dolor, sit } = amet;
1857     let Lorem {
1858         ipsum,
1859         dolor,
1860         sit,
1861         amet,
1862         consectetur,
1863         adipiscing
1864     } = elit;
1865 }
1866 ```
1867
1868 See also: [`match_block_trailing_comma`](#match_block_trailing_comma).
1869
1870 ## `trailing_semicolon`
1871
1872 Add trailing semicolon after break, continue and return
1873
1874 - **Default value**: `true`
1875 - **Possible values**: `true`, `false`
1876 - **Stable**: No
1877
1878 #### `true` (default):
1879 ```rust
1880 fn foo() -> usize {
1881     return 0;
1882 }
1883 ```
1884
1885 #### `false`:
1886 ```rust
1887 fn foo() -> usize {
1888     return 0
1889 }
1890 ```
1891
1892 ## `type_punctuation_density`
1893
1894 Determines if `+` or `=` are wrapped in spaces in the punctuation of types
1895
1896 - **Default value**: `"Wide"`
1897 - **Possible values**: `"Compressed"`, `"Wide"`
1898 - **Stable**: No
1899
1900 #### `"Wide"` (default):
1901
1902 ```rust
1903 fn lorem<Ipsum: Dolor + Sit = Amet>() {
1904     // body
1905 }
1906 ```
1907
1908 #### `"Compressed"`:
1909
1910 ```rust
1911 fn lorem<Ipsum: Dolor+Sit=Amet>() {
1912     // body
1913 }
1914 ```
1915
1916 ## `use_field_init_shorthand`
1917
1918 Use field initialize shorthand if possible.
1919
1920 - **Default value**: `false`
1921 - **Possible values**: `true`, `false`
1922 - **Stable**: Yes
1923
1924 #### `false` (default):
1925
1926 ```rust
1927 struct Foo {
1928     x: u32,
1929     y: u32,
1930     z: u32,
1931 }
1932
1933 fn main() {
1934     let x = 1;
1935     let y = 2;
1936     let z = 3;
1937     let a = Foo { x: x, y: y, z: z };
1938 }
1939 ```
1940
1941 #### `true`:
1942
1943 ```rust
1944 struct Foo {
1945     x: u32,
1946     y: u32,
1947     z: u32,
1948 }
1949
1950 fn main() {
1951     let x = 1;
1952     let y = 2;
1953     let z = 3;
1954     let a = Foo { x, y, z };
1955 }
1956 ```
1957
1958 ## `use_try_shorthand`
1959
1960 Replace uses of the try! macro by the ? shorthand
1961
1962 - **Default value**: `false`
1963 - **Possible values**: `true`, `false`
1964 - **Stable**: Yes
1965
1966 #### `false` (default):
1967
1968 ```rust
1969 fn main() {
1970     let lorem = try!(ipsum.map(|dolor| dolor.sit()));
1971 }
1972 ```
1973
1974 #### `true`:
1975
1976 ```rust
1977 fn main() {
1978     let lorem = ipsum.map(|dolor| dolor.sit())?;
1979 }
1980 ```
1981
1982 ## `format_doc_comments`
1983
1984 Format doc comments.
1985
1986 - **Default value**: `false`
1987 - **Possible values**: `true`, `false`
1988 - **Stable**: No
1989
1990 #### `false` (default):
1991
1992 ```rust
1993 /// Adds one to the number given.
1994 ///
1995 /// # Examples
1996 ///
1997 /// ```rust
1998 /// let five=5;
1999 ///
2000 /// assert_eq!(
2001 ///     6,
2002 ///     add_one(5)
2003 /// );
2004 /// # fn add_one(x: i32) -> i32 {
2005 /// #     x + 1
2006 /// # }
2007 /// ```
2008 fn add_one(x: i32) -> i32 {
2009     x + 1
2010 }
2011 ```
2012
2013 #### `true`
2014
2015 ```rust
2016 /// Adds one to the number given.
2017 ///
2018 /// # Examples
2019 ///
2020 /// ```rust
2021 /// let five = 5;
2022 ///
2023 /// assert_eq!(6, add_one(5));
2024 /// # fn add_one(x: i32) -> i32 {
2025 /// #     x + 1
2026 /// # }
2027 /// ```
2028 fn add_one(x: i32) -> i32 {
2029     x + 1
2030 }
2031 ```
2032
2033 ## `wrap_comments`
2034
2035 Break comments to fit on the line
2036
2037 - **Default value**: `false`
2038 - **Possible values**: `true`, `false`
2039 - **Stable**: No
2040
2041 #### `false` (default):
2042
2043 ```rust
2044 // 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.
2045 ```
2046
2047 #### `true`:
2048
2049 ```rust
2050 // Lorem ipsum dolor sit amet, consectetur adipiscing elit,
2051 // sed do eiusmod tempor incididunt ut labore et dolore
2052 // magna aliqua. Ut enim ad minim veniam, quis nostrud
2053 // exercitation ullamco laboris nisi ut aliquip ex ea
2054 // commodo consequat.
2055 ```
2056
2057 ## `match_arm_blocks`
2058
2059 Wrap the body of arms in blocks when it does not fit on the same line with the pattern of arms
2060
2061 - **Default value**: `true`
2062 - **Possible values**: `true`, `false`
2063 - **Stable**: No
2064
2065 #### `true` (default):
2066
2067 ```rust
2068 fn main() {
2069     match lorem {
2070         true => {
2071             foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x)
2072         }
2073         false => println!("{}", sit),
2074     }
2075 }
2076 ```
2077
2078 #### `false`:
2079
2080 ```rust
2081 fn main() {
2082     match lorem {
2083         true =>
2084             foooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo(x),
2085         false => println!("{}", sit),
2086     }
2087 }
2088 ```
2089
2090 See also: [`match_block_trailing_comma`](#match_block_trailing_comma).
2091
2092
2093 ## `blank_lines_upper_bound`
2094
2095 Maximum number of blank lines which can be put between items. If more than this number of consecutive empty
2096 lines are found, they are trimmed down to match this integer.
2097
2098 - **Default value**: `1`
2099 - **Possible values**: *unsigned integer*
2100 - **Stable**: No
2101
2102 ### Example
2103 Original Code:
2104
2105 ```rust
2106 #![rustfmt::skip]
2107
2108 fn foo() {
2109     println!("a");
2110 }
2111
2112
2113
2114 fn bar() {
2115     println!("b");
2116
2117
2118     println!("c");
2119 }
2120 ```
2121
2122 #### `1` (default):
2123 ```rust
2124 fn foo() {
2125     println!("a");
2126 }
2127
2128 fn bar() {
2129     println!("b");
2130
2131     println!("c");
2132 }
2133 ```
2134
2135 #### `2`:
2136 ```rust
2137 fn foo() {
2138     println!("a");
2139 }
2140
2141
2142 fn bar() {
2143     println!("b");
2144
2145
2146     println!("c");
2147 }
2148 ```
2149
2150 See also: [`blank_lines_lower_bound`](#blank_lines_lower_bound)
2151
2152 ## `blank_lines_lower_bound`
2153
2154 Minimum number of blank lines which must be put between items. If two items have fewer blank lines between
2155 them, additional blank lines are inserted.
2156
2157 - **Default value**: `0`
2158 - **Possible values**: *unsigned integer*
2159 - **Stable**: No
2160
2161 ### Example
2162 Original Code (rustfmt will not change it with the default value of `0`):
2163
2164 ```rust
2165 #![rustfmt::skip]
2166
2167 fn foo() {
2168     println!("a");
2169 }
2170 fn bar() {
2171     println!("b");
2172     println!("c");
2173 }
2174 ```
2175
2176 #### `1`
2177 ```rust
2178 fn foo() {
2179
2180     println!("a");
2181 }
2182
2183 fn bar() {
2184
2185     println!("b");
2186
2187     println!("c");
2188 }
2189 ```
2190
2191
2192 ## `required_version`
2193
2194 Require a specific version of rustfmt. If you want to make sure that the
2195 specific version of rustfmt is used in your CI, use this option.
2196
2197 - **Default value**: `CARGO_PKG_VERSION`
2198 - **Possible values**: any published version (e.g. `"0.3.8"`)
2199 - **Stable**: No
2200
2201 ## `hide_parse_errors`
2202
2203 Do not show parse errors if the parser failed to parse files.
2204
2205 - **Default value**: `false`
2206 - **Possible values**: `true`, `false`
2207 - **Stable**: No
2208
2209 ## `color`
2210
2211 Whether to use colored output or not.
2212
2213 - **Default value**: `"Auto"`
2214 - **Possible values**: "Auto", "Always", "Never"
2215 - **Stable**: No
2216
2217 ## `unstable_features`
2218
2219 Enable unstable features on stable channel.
2220
2221 - **Default value**: `false`
2222 - **Possible values**: `true`, `false`
2223 - **Stable**: No
2224
2225 ## `license_template_path`
2226
2227 Check whether beginnings of files match a license template.
2228
2229 - **Default value**: `""``
2230 - **Possible values**: path to a license template file
2231 - **Stable**: No
2232
2233 A license template is a plain text file which is matched literally against the
2234 beginning of each source file, except for `{}`-delimited blocks, which are
2235 matched as regular expressions. The following license template therefore
2236 matches strings like `// Copyright 2017 The Rust Project Developers.`, `//
2237 Copyright 2018 The Rust Project Developers.`, etc.:
2238
2239 ```
2240 // Copyright {\d+} The Rust Project Developers.
2241 ```
2242
2243 `\{`, `\}` and `\\` match literal braces / backslashes.
2244
2245 ## `ignore`
2246
2247 Skip formatting the specified files and directories.
2248
2249 - **Default value**: format every files
2250 - **Possible values**: See an example below
2251 - **Stable**: No
2252
2253 ### Example
2254
2255 If you want to ignore specific files, put the following to your config file:
2256
2257 ```toml
2258 ignore = [
2259     "src/types.rs",
2260     "src/foo/bar.rs",
2261 ]
2262 ```
2263
2264 If you want to ignore every file under `examples/`, put the following to your config file:
2265
2266 ```toml
2267 ignore = [
2268     "examples",
2269 ]
2270 ```
2271
2272 ## `edition`
2273
2274 Specifies which edition is used by the parser.
2275
2276 - **Default value**: `2015`
2277 - **Possible values**: `2015`, `2018`
2278 - **Stable**: Yes
2279
2280 ### Example
2281
2282 If you want to format code that requires edition 2018, add the following to your config file:
2283
2284 ```toml
2285 edition = "2018"
2286 ```
2287
2288 ## `normalize_doc_attributes`
2289
2290 Convert `#![doc]` and `#[doc]` attributes to `//!` and `///` doc comments.
2291
2292 - **Default value**: `false`
2293 - **Possible values**: `true`, `false`
2294 - **Stable**: No
2295
2296 #### `false` (default):
2297
2298 ```rust
2299 #![doc = "Example documentation"]
2300
2301 #[doc = "Example item documentation"]
2302 pub enum Foo {}
2303 ```
2304
2305 #### `true`:
2306
2307 ```rust
2308 //! Example documentation
2309
2310 /// Example item documentation
2311 pub enum Foo {}
2312 ```
2313
2314 ## `emit_mode`
2315
2316 Internal option
2317
2318 ## `make_backup`
2319
2320 Internal option, use `--backup`