diff --git a/README.md b/README.md index 1fb3454a48e..39d2bd363b0 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,27 @@ # rustfmt [![Linux badge][linux-build-status]][linux-build] [![Mac badge][mac-build-status]][mac-build] [![Windows badge][windows-build-status]][windows-build] [![crates.io badge][cratesio-badge]][cratesio-package] [![Travis config badge][travis-config-badge]][travis-config-job] + + + + + + +- [Quick start](#quick-start) + - [On the Stable toolchain](#on-the-stable-toolchain) + - [On the Nightly toolchain](#on-the-nightly-toolchain) + - [Installing from source](#installing-from-source) +- [Running](#running) +- [Configuring Rustfmt](#configuring-rustfmt) + - [Rust's Editions](#rusts-editions) +- [Limitations](#limitations) +- [Running Rustfmt from your editor](#running-rustfmt-from-your-editor) +- [Checking style on a CI server](#checking-style-on-a-ci-server) +- [How to build and test](#how-to-build-and-test) +- [Tips](#tips) +- [License](#license) + + + A tool for formatting Rust code according to style guidelines. If you'd like to help out (and you should, it's a fun project!), see @@ -45,42 +67,7 @@ To run on a cargo project in the current working directory: cargo +nightly fmt ``` -## Limitations - -Rustfmt tries to work on as much Rust code as possible. Sometimes, the code -doesn't even need to compile! As we approach a 1.0 release we are also looking -to limit areas of instability; in particular, post-1.0, the formatting of most -code should not change as Rustfmt improves. However, there are some things that -Rustfmt can't do or can't do well (and thus where formatting might change -significantly, even post-1.0). We would like to reduce the list of limitations -over time. - -The following list enumerates areas where Rustfmt does not work or where the -stability guarantees do not apply (we don't make a distinction between the two -because in the future Rustfmt might work on code where it currently does not): - -* a program where any part of the program does not parse (parsing is an early - stage of compilation and in Rust includes macro expansion). -* Macro declarations and uses (current status: some macro declarations and uses - are formatted). -* Comments, including any AST node with a comment 'inside' (Rustfmt does not - currently attempt to format comments, it does format code with comments inside, but that formatting may change in the future). -* Rust code in code blocks in comments. -* Any fragment of a program (i.e., stability guarantees only apply to whole - programs, even where fragments of a program can be formatted today). -* Code containing non-ascii unicode characters (we believe Rustfmt mostly works - here, but do not have the test coverage or experience to be 100% sure). -* Bugs in Rustfmt (like any software, Rustfmt has bugs, we do not consider bug - fixes to break our stability guarantees). - - -## Installation - -```sh -rustup component add rustfmt -``` - -## Installing from source +### Installing from source To install from source (nightly required), first checkout to the tag or branch for the version of rustfmt you want. @@ -102,9 +89,10 @@ cargo install --path . --force --locked --features rustfmt,cargo-fmt This will install `rustfmt` in your `~/.cargo/bin`. Make sure to add `~/.cargo/bin` directory to your PATH variable. - ## Running +You can run `rustfmt --help` for information about available arguments. + You can run Rustfmt by just typing `rustfmt filename` if you used `cargo install`. This runs rustfmt on the given file, if the file includes out of line modules, then we reformat those too. So to run on a whole module or crate, you @@ -112,15 +100,64 @@ just need to run on the root file (usually mod.rs or lib.rs). Rustfmt can also read data from stdin. Alternatively, you can use `cargo fmt` to format all binary and library targets of your crate. -You can run `rustfmt --help` for information about available arguments. - When running with `--check`, Rustfmt will exit with `0` if Rustfmt would not make any formatting changes to the input, and `1` if Rustfmt would make changes. In other modes, Rustfmt will exit with `1` if there was some error during formatting (for example a parsing or internal error) and `0` if formatting completed without error (whether or not changes were made). +## Configuring Rustfmt + +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. See `rustfmt +--help=config` for the options which are available, or if you prefer to see +visual style previews, [GitHub page](https://rust-lang.github.io/rustfmt/). + +By default, Rustfmt uses a style which conforms to the [Rust style guide][style +guide] that has been formalized through the [style RFC +process][fmt rfcs]. + +Configuration options are either stable or unstable. Stable options can always +be used on any channel. Unstable options are always available on nightly, but can only be used on stable and beta with an explicit opt-in (starting in Rustfmt v2.0). + +Unstable options are not available on stable/beta with Rustfmt v1.x. + +See the configuration documentation on the Rustfmt [GitHub page](https://rust-lang.github.io/rustfmt/) for details (look for the `unstable_features` section). + +### Rust's Editions + +Rustfmt is able to pick up the edition used by reading the `Cargo.toml` file if +executed through the Cargo's formatting tool `cargo fmt`. Otherwise, the edition +needs to be specified in `rustfmt.toml`, e.g., with `edition = "2018"`. + +## Limitations + +Rustfmt tries to work on as much Rust code as possible. Sometimes, the code +doesn't even need to compile! As we approach a 1.0 release we are also looking +to limit areas of instability; in particular, post-1.0, the formatting of most +code should not change as Rustfmt improves. However, there are some things that +Rustfmt can't do or can't do well (and thus where formatting might change +significantly, even post-1.0). We would like to reduce the list of limitations +over time. +The following list enumerates areas where Rustfmt does not work or where the +stability guarantees do not apply (we don't make a distinction between the two +because in the future Rustfmt might work on code where it currently does not): + +* a program where any part of the program does not parse (parsing is an early + stage of compilation and in Rust includes macro expansion). +* Macro declarations and uses (current status: some macro declarations and uses + are formatted). +* Comments, including any AST node with a comment 'inside' (Rustfmt does not + currently attempt to format comments, it does format code with comments inside, but that formatting may change in the future). +* Rust code in code blocks in comments. +* Any fragment of a program (i.e., stability guarantees only apply to whole + programs, even where fragments of a program can be formatted today). +* Code containing non-ascii unicode characters (we believe Rustfmt mostly works + here, but do not have the test coverage or experience to be 100% sure). +* Bugs in Rustfmt (like any software, Rustfmt has bugs, we do not consider bug + fixes to break our stability guarantees). ## Running Rustfmt from your editor @@ -131,7 +168,6 @@ completed without error (whether or not changes were made). * Visual Studio Code using [vscode-rust](https://github.com/editor-rs/vscode-rust), [vsc-rustfmt](https://github.com/Connorcpu/vsc-rustfmt) or [rls_vscode](https://github.com/jonathandturner/rls_vscode) through RLS. * [IntelliJ or CLion](intellij.md) - ## Checking style on a CI server To keep your code base consistently formatted, it can be helpful to fail the CI build @@ -197,32 +233,6 @@ CFG_RELEASE_CHANNEL=nightly CFG_RELEASE=1.45.0-nightly cargo test --all-features To run rustfmt after this, use `cargo run --bin rustfmt -- filename`. See the notes above on running rustfmt. - -## Configuring Rustfmt - -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. See `rustfmt ---help=config` for the options which are available, or if you prefer to see -visual style previews, [GitHub page](https://rust-lang.github.io/rustfmt/). - -By default, Rustfmt uses a style which conforms to the [Rust style guide][style -guide] that has been formalized through the [style RFC -process][fmt rfcs]. - -Configuration options are either stable or unstable. Stable options can always -be used on any channel. Unstable options are always available on nightly, but can only be used on stable and beta with an explicit opt-in (starting in Rustfmt v2.0). - -Unstable options are not available on stable/beta with Rustfmt v1.x. - -See the configuration documentation on the Rustfmt [GitHub page](https://rust-lang.github.io/rustfmt/) for details (look for the `unstable_features` section). - -### Rust's Editions - -Rustfmt is able to pick up the edition used by reading the `Cargo.toml` file if -executed through the Cargo's formatting tool `cargo fmt`. Otherwise, the edition -needs to be specified in `rustfmt.toml`, e.g., with `edition = "2018"`. - ## Tips * For things you do not want rustfmt to mangle, use `#[rustfmt::skip]` diff --git a/src/cargo-fmt/main.rs b/src/cargo-fmt/main.rs index 57c2d5933c8..7b4e98ca470 100644 --- a/src/cargo-fmt/main.rs +++ b/src/cargo-fmt/main.rs @@ -47,6 +47,9 @@ pub struct Opts { message_format: Option, /// Options passed to rustfmt + /// + /// To see all rustfmt options, run `rustfmt --help'. + /// To see all rustfmt configuration options, please visit https://rust-lang.github.io/rustfmt. // 'raw = true' to make `--` explicit. #[structopt(name = "rustfmt_options", raw(true))] rustfmt_options: Vec, diff --git a/src/rustfmt/main.rs b/src/rustfmt/main.rs index 9a696b2cf5d..f42e931f7d8 100644 --- a/src/rustfmt/main.rs +++ b/src/rustfmt/main.rs @@ -43,7 +43,30 @@ fn main() { /// Format Rust code #[derive(Debug, StructOpt, Clone)] -#[structopt(name = "rustfmt", version = include_str!(concat!(env!("OUT_DIR"),"/version-info.txt")))] +#[structopt( + name = "rustfmt", + version = include_str!(concat!(env!("OUT_DIR"),"/version-info.txt")), + about = r#"Format Rust code + +Rustfmt runs on a set of files or stdin. When invoked without any file arguments, rustfmt will +read code from stdin. + +Please visit https://rust-lang.github.io/rustfmt to see all rustfmt configuration options. + +EXAMPLES + + cat lib.rs | rustfmt + Feed the contents of "lib.rs" to rustfmt via stdin + + rustfmt lib.rs main.rs + Run rustfmt over "lib.rs" and "main.rs", formatting in-place. + + rustfmt --emit=stdout lib.rs main.rs + Run rustfmt over "lib.rs" and "main.rs", writing to stdout (rather than in-place) + + rustfmt --config-path=rustfmt.toml --print-config=current + Print the resolved rustfmt configuration formed by rustfmt.toml +"#)] struct Opt { /// Run in 'check' mode. /// @@ -60,7 +83,8 @@ struct Opt { config_path: Option, /// Rust compiler edition /// - /// Specify which edition of the compiler to use when formatting code. + /// Specify which edition of the compiler to use when formatting code. This behaves identically + /// to the "edition" configuration option. #[structopt(long, name = "2015|2018")] edition: Option, /// Print configuration options.