README.md

   1 # rustfmt
   2
   3 A tool for formatting Rust code according to style guidelines.
   4
   5
   6 ## Installation
   7
   8 > **Note:** this method currently requires you to be running a nightly install
   9 > of Rust as `cargo install` has not yet made its way onto the stable channel.
  10
  11 ```
  12 cargo install --git https://github.com/nrc/rustfmt
  13 ```
  14
  15 or if you're using [`multirust`](https://github.com/brson/multirust)
  16
  17 ```
  18 multirust run nightly cargo install --git https://github.com/nrc/rustfmt
  19 ```
  20
  21
  22 ## Running Rustfmt from Vim
  23
  24 See [instructions](http://johannh.me/blog/rustfmt-vim.html).
  25
  26
  27 ## How to build and test
  28
  29 First make sure you've got Rust **1.4.0** or greater available, then:
  30
  31 `cargo build` to build.
  32
  33 `cargo test` to run all tests.
  34
  35 `cargo run -- filename` to run on a file, if the file includes out of line
  36 modules, then we reformat those too. So to run on a whole module or crate, you
  37 just need to run on the top file.
  38
  39 You'll probably want to specify the write mode. Currently, there are the
  40 replace, overwrite, display and coverage modes. The replace mode is the default
  41 and overwrites the original files after renaming them. In overwrite mode,
  42 rustfmt does not backup the source files. To print the output to stdout, use the
  43 display mode. The write mode can be set by passing the `--write-mode` flag on
  44 the command line.
  45
  46 `cargo run -- filename --write-mode=display` prints the output of rustfmt to the
  47 screen, for example.
  48
  49
  50 ## Gotchas
  51
  52 * For things you do not want rustfmt to mangle, use one of
  53    ```rust
  54    #[rustfmt_skip]
  55    #[cfg_attr(rustfmt, rustfmt_skip)]
  56     ```
  57 * When you run rustfmt, place a file named rustfmt.toml in target file
  58   directory or its parents to override the default settings of rustfmt.
  59 * After successful compilation, a `rustfmt` executable can be found in the
  60   target directory.