1# rustfmt [](https://github.com/rust-lang/rustfmt/actions/workflows/linux.yml) [](https://github.com/rust-lang/rustfmt/actions/workflows/mac.yml) [](https://github.com/rust-lang/rustfmt/actions/workflows/windows.yml) [](https://crates.io/crates/rustfmt-nightly) 2 3A tool for formatting Rust code according to style guidelines. 4 5If you'd like to help out (and you should, it's a fun project!), see 6[Contributing.md](Contributing.md) and our [Code of 7Conduct](CODE_OF_CONDUCT.md). 8 9You can use rustfmt in Travis CI builds. We provide a minimal Travis CI 10configuration (see [here](#checking-style-on-a-ci-server)). 11 12## Quick start 13 14You can run `rustfmt` with Rust 1.24 and above. 15 16### On the Stable toolchain 17 18To install: 19 20```sh 21rustup component add rustfmt 22``` 23 24To run on a cargo project in the current working directory: 25 26```sh 27cargo fmt 28``` 29 30### On the Nightly toolchain 31 32For the latest and greatest `rustfmt`, nightly is required. 33 34To install: 35 36```sh 37rustup component add rustfmt --toolchain nightly 38``` 39 40To run on a cargo project in the current working directory: 41 42```sh 43cargo +nightly fmt 44``` 45 46## Limitations 47 48Rustfmt tries to work on as much Rust code as possible. Sometimes, the code 49doesn't even need to compile! In general, we are looking to limit areas of 50instability; in particular, post-1.0, the formatting of most code should not 51change as Rustfmt improves. However, there are some things that Rustfmt can't 52do or can't do well (and thus where formatting might change significantly, 53even post-1.0). We would like to reduce the list of limitations over time. 54 55The following list enumerates areas where Rustfmt does not work or where the 56stability guarantees do not apply (we don't make a distinction between the two 57because in the future Rustfmt might work on code where it currently does not): 58 59* a program where any part of the program does not parse (parsing is an early 60 stage of compilation and in Rust includes macro expansion). 61* Macro declarations and uses (current status: some macro declarations and uses 62 are formatted). 63* Comments, including any AST node with a comment 'inside' (Rustfmt does not 64 currently attempt to format comments, it does format code with comments inside, but that formatting may change in the future). 65* Rust code in code blocks in comments. 66* Any fragment of a program (i.e., stability guarantees only apply to whole 67 programs, even where fragments of a program can be formatted today). 68* Code containing non-ascii unicode characters (we believe Rustfmt mostly works 69 here, but do not have the test coverage or experience to be 100% sure). 70* Bugs in Rustfmt (like any software, Rustfmt has bugs, we do not consider bug 71 fixes to break our stability guarantees). 72 73 74## Running 75 76You can run Rustfmt by just typing `rustfmt filename` if you used `cargo 77install`. This runs rustfmt on the given file, if the file includes out of line 78modules, then we reformat those too. So to run on a whole module or crate, you 79just need to run on the root file (usually mod.rs or lib.rs). Rustfmt can also 80read data from stdin. Alternatively, you can use `cargo fmt` to format all 81binary and library targets of your crate. 82 83You can run `rustfmt --help` for information about available arguments. 84The easiest way to run rustfmt against a project is with `cargo fmt`. `cargo fmt` works on both 85single-crate projects and [cargo workspaces](https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html). 86Please see `cargo fmt --help` for usage information. 87 88You can specify the path to your own `rustfmt` binary for cargo to use by setting the`RUSTFMT` 89environment variable. This was added in v1.4.22, so you must have this version or newer to leverage this feature (`cargo fmt --version`) 90 91### Running `rustfmt` directly 92 93To format individual files or arbitrary codes from stdin, the `rustfmt` binary should be used. Some 94examples follow: 95 96- `rustfmt lib.rs main.rs` will format "lib.rs" and "main.rs" in place 97- `rustfmt` will read a code from stdin and write formatting to stdout 98 - `echo "fn main() {}" | rustfmt` would emit "fn main() {}". 99 100For more information, including arguments and emit options, see `rustfmt --help`. 101 102### Verifying code is formatted 103 104When running with `--check`, Rustfmt will exit with `0` if Rustfmt would not 105make any formatting changes to the input, and `1` if Rustfmt would make changes. 106In other modes, Rustfmt will exit with `1` if there was some error during 107formatting (for example a parsing or internal error) and `0` if formatting 108completed without error (whether or not changes were made). 109 110 111 112## Running Rustfmt from your editor 113 114* [Vim](https://github.com/rust-lang/rust.vim#formatting-with-rustfmt) 115* [Emacs](https://github.com/rust-lang/rust-mode) 116* [Sublime Text 3](https://packagecontrol.io/packages/RustFmt) 117* [Atom](atom.md) 118* [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer) 119* [IntelliJ or CLion](intellij.md) 120 121 122## Checking style on a CI server 123 124To keep your code base consistently formatted, it can be helpful to fail the CI build 125when a pull request contains unformatted code. Using `--check` instructs 126rustfmt to exit with an error code if the input is not formatted correctly. 127It will also print any found differences. (Older versions of Rustfmt don't 128support `--check`, use `--write-mode diff`). 129 130A minimal Travis setup could look like this (requires Rust 1.31.0 or greater): 131 132```yaml 133language: rust 134before_script: 135- rustup component add rustfmt 136script: 137- cargo build 138- cargo test 139- cargo fmt --all -- --check 140``` 141 142See [this blog post](https://medium.com/@ag_dubs/enforcing-style-in-ci-for-rust-projects-18f6b09ec69d) 143for more info. 144 145## How to build and test 146 147`cargo build` to build. 148 149`cargo test` to run all tests. 150 151To run rustfmt after this, use `cargo run --bin rustfmt -- filename`. See the 152notes above on running rustfmt. 153 154 155## Configuring Rustfmt 156 157Rustfmt is designed to be very configurable. You can create a TOML file called 158`rustfmt.toml` or `.rustfmt.toml`, place it in the project or any other parent 159directory and it will apply the options in that file. See `rustfmt 160--help=config` for the options which are available, or if you prefer to see 161visual style previews, [GitHub page](https://rust-lang.github.io/rustfmt/). 162 163By default, Rustfmt uses a style which conforms to the [Rust style guide][style 164guide] that has been formalized through the [style RFC 165process][fmt rfcs]. 166 167Configuration options are either stable or unstable. Stable options can always 168be used, while unstable ones are only available on a nightly toolchain, and opt-in. 169See [GitHub page](https://rust-lang.github.io/rustfmt/) for details. 170 171### Rust's Editions 172 173Rustfmt is able to pick up the edition used by reading the `Cargo.toml` file if 174executed through the Cargo's formatting tool `cargo fmt`. Otherwise, the edition 175needs to be specified in `rustfmt.toml`, e.g., with `edition = "2018"`. 176 177## Tips 178 179* For things you do not want rustfmt to mangle, use `#[rustfmt::skip]` 180* To prevent rustfmt from formatting a macro or an attribute, 181 use `#[rustfmt::skip::macros(target_macro_name)]` or 182 `#[rustfmt::skip::attributes(target_attribute_name)]` 183 184 Example: 185 186 ```rust 187 #![rustfmt::skip::attributes(custom_attribute)] 188 189 #[custom_attribute(formatting , here , should , be , Skipped)] 190 #[rustfmt::skip::macros(html)] 191 fn main() { 192 let macro_result1 = html! { <div> 193 Hello</div> 194 }.to_string(); 195 ``` 196* When you run rustfmt, place a file named `rustfmt.toml` or `.rustfmt.toml` in 197 target file directory or its parents to override the default settings of 198 rustfmt. You can generate a file containing the default configuration with 199 `rustfmt --print-config default rustfmt.toml` and customize as needed. 200* After successful compilation, a `rustfmt` executable can be found in the 201 target directory. 202* If you're having issues compiling Rustfmt (or compile errors when trying to 203 install), make sure you have the most recent version of Rust installed. 204 205* You can change the way rustfmt emits the changes with the --emit flag: 206 207 Example: 208 209 ```sh 210 cargo fmt -- --emit files 211 ``` 212 213 Options: 214 215 | Flag |Description| Nightly Only | 216 |:---:|:---:|:---:| 217 | files | overwrites output to files | No | 218 | stdout | writes output to stdout | No | 219 | coverage | displays how much of the input file was processed | Yes | 220 | checkstyle | emits in a checkstyle format | Yes | 221 | json | emits diffs in a json format | Yes | 222 223## License 224 225Rustfmt is distributed under the terms of both the MIT license and the 226Apache License (Version 2.0). 227 228See [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT) for details. 229 230[rust]: https://github.com/rust-lang/rust 231[fmt rfcs]: https://github.com/rust-dev-tools/fmt-rfcs 232[style guide]: https://doc.rust-lang.org/nightly/style-guide/ 233
){kind=link}
){kind=link}
){kind=link}
){kind=link}