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