• Stars
    star
    5,524
  • Rank 7,424 (Top 0.2 %)
  • Language
    Rust
  • License
    Apache License 2.0
  • Created over 9 years ago
  • Updated 11 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Format Rust code

rustfmt linux mac windows crates.io

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 Contributing.md and our Code of Conduct.

You can use rustfmt in Travis CI builds. We provide a minimal Travis CI configuration (see here).

Quick start

You can run rustfmt with Rust 1.24 and above.

On the Stable toolchain

To install:

rustup component add rustfmt

To run on a cargo project in the current working directory:

cargo fmt

On the Nightly toolchain

For the latest and greatest rustfmt, nightly is required.

To install:

rustup component add rustfmt --toolchain nightly

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! In general, we are 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

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 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. The easiest way to run rustfmt against a project is with cargo fmt. cargo fmt works on both single-crate projects and cargo workspaces. Please see cargo fmt --help for usage information.

You can specify the path to your own rustfmt binary for cargo to use by setting theRUSTFMT environment variable. This was added in v1.4.22, so you must have this version or newer to leverage this feature (cargo fmt --version)

Running rustfmt directly

To format individual files or arbitrary codes from stdin, the rustfmt binary should be used. Some examples follow:

  • rustfmt lib.rs main.rs will format "lib.rs" and "main.rs" in place
  • rustfmt will read a code from stdin and write formatting to stdout
    • echo "fn main() {}" | rustfmt would emit "fn main() {}".

For more information, including arguments and emit options, see rustfmt --help.

Verifying code is formatted

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).

Running Rustfmt from your editor

Checking style on a CI server

To keep your code base consistently formatted, it can be helpful to fail the CI build when a pull request contains unformatted code. Using --check instructs rustfmt to exit with an error code if the input is not formatted correctly. It will also print any found differences. (Older versions of Rustfmt don't support --check, use --write-mode diff).

A minimal Travis setup could look like this (requires Rust 1.31.0 or greater):

language: rust
before_script:
- rustup component add rustfmt
script:
- cargo build
- cargo test
- cargo fmt --all -- --check

See this blog post for more info.

How to build and test

cargo build to build.

cargo test to run all tests.

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.

By default, Rustfmt uses a style which conforms to the Rust style guide that has been formalized through the style RFC process.

Configuration options are either stable or unstable. Stable options can always be used, while unstable ones are only available on a nightly toolchain, and opt-in. See GitHub page for details.

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]

  • To prevent rustfmt from formatting a macro or an attribute, use #[rustfmt::skip::macros(target_macro_name)] or #[rustfmt::skip::attributes(target_attribute_name)]

    Example:

    #![rustfmt::skip::attributes(custom_attribute)]
    
    #[custom_attribute(formatting , here , should , be , Skipped)]
    #[rustfmt::skip::macros(html)]
    fn main() {
        let macro_result1 = html! { <div>
    Hello</div>
        }.to_string();
  • When you run rustfmt, place a file named rustfmt.toml or .rustfmt.toml in target file directory or its parents to override the default settings of rustfmt. You can generate a file containing the default configuration with rustfmt --print-config default rustfmt.toml and customize as needed.

  • After successful compilation, a rustfmt executable can be found in the target directory.

  • If you're having issues compiling Rustfmt (or compile errors when trying to install), make sure you have the most recent version of Rust installed.

  • You can change the way rustfmt emits the changes with the --emit flag:

    Example:

    cargo fmt -- --emit files

    Options:

    Flag Description Nightly Only
    files overwrites output to files No
    stdout writes output to stdout No
    coverage displays how much of the input file was processed Yes
    checkstyle emits in a checkstyle format Yes
    json emits diffs in a json format Yes

License

Rustfmt is distributed under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE and LICENSE-MIT for details.

More Repositories

1

rust

Empowering everyone to build reliable and efficient software.
Rust
85,122
star
2

rustlings

๐Ÿฆ€ Small exercises to get you used to reading and writing Rust code!
Rust
47,148
star
3

mdBook

Create book from markdown files. Like Gitbook but implemented in Rust
Rust
15,892
star
4

book

The Rust Programming Language
Rust
13,981
star
5

rust-analyzer

A Rust compiler front-end for IDEs
Rust
13,571
star
6

cargo

The Rust package manager
Rust
11,293
star
7

rust-clippy

A bunch of lints to catch common mistakes and improve your Rust code. Book: https://doc.rust-lang.org/clippy/
Rust
9,860
star
8

rust-by-example

Learn Rust with examples (Live code editor included)
6,109
star
9

rustup

The Rust toolchain installer
Rust
5,558
star
10

rfcs

RFCs for changes to Rust
Markdown
5,390
star
11

futures-rs

Zero-cost asynchronous programming in Rust
Rust
5,119
star
12

rust-bindgen

Automatically generates Rust FFI bindings to C (and some C++) libraries.
Rust
3,830
star
13

rust.vim

Vim configuration for Rust.
Vim Script
3,628
star
14

miri

An interpreter for Rust's mid-level intermediate representation
Rust
3,581
star
15

rls

Repository for the Rust Language Server (aka RLS)
Rust
3,513
star
16

regex

An implementation of regular expressions for Rust. This implementation uses finite automata and guarantees linear time matching on all inputs.
Rust
3,083
star
17

crates.io

The Rust package registry
Rust
2,554
star
18

hashbrown

Rust port of Google's SwissTable hash map
Rust
2,266
star
19

log

Logging implementation for Rust
Rust
2,180
star
20

this-week-in-rust

Data for this-week-in-rust.org
HTML
1,826
star
21

libc

Raw bindings to platform APIs for Rust
Rust
1,786
star
22

chalk

An implementation and definition of the Rust trait system using a PROLOG-like logic solver
Rust
1,713
star
23

async-book

Asynchronous Programming in Rust
Shell
1,699
star
24

nomicon

The Dark Arts of Advanced and Unsafe Rust Programming
CSS
1,698
star
25

rustc-dev-guide

A guide to how rustc works and how to contribute to it.
HTML
1,580
star
26

rustc_codegen_cranelift

Cranelift based backend for rustc
Rust
1,538
star
27

git2-rs

libgit2 bindings for Rust
Rust
1,520
star
28

cc-rs

Rust library for build scripts to compile C/C++ code into a Rust library
Rust
1,491
star
29

vscode-rust

Rust extension for Visual Studio Code
TypeScript
1,386
star
30

polonius

Defines the Rust borrow checker.
Rust
1,255
star
31

api-guidelines

Rust API guidelines
1,202
star
32

reference

The Rust Reference
Rust
1,140
star
33

rust-playground

The Rust Playground
Rust
1,076
star
34

rust-mode

Emacs configuration for Rust
Emacs Lisp
1,009
star
35

docs.rs

crates.io documentation generator
Rust
891
star
36

rustc_codegen_gcc

libgccjit AOT codegen for rustc
Rust
875
star
37

rustfix

Automatically apply the suggestions made by rustc
Rust
853
star
38

portable-simd

The testing ground for the future of portable SIMD in Rust
Rust
816
star
39

datafrog

A lightweight Datalog engine in Rust
Rust
783
star
40

flate2-rs

DEFLATE, gzip, and zlib bindings for Rust
Rust
730
star
41

socket2

Advanced configuration options for sockets.
Rust
681
star
42

unsafe-code-guidelines

Forum for discussion about what unsafe code can and can't do
641
star
43

rust-semverver

Automatic checking for semantic versioning in library crates
Rust
639
star
44

stdarch

Rust's standard library vendor-specific APIs and run-time feature detection
Rust
597
star
45

crater

Run experiments across parts of the Rust ecosystem!
Rust
588
star
46

packed_simd

Portable Packed SIMD Vectors for Rust standard library
Rust
575
star
47

rustc-perf

Website for graphing performance of rustc
Rust
539
star
48

libm

A port of MUSL's libm to Rust.
Rust
499
star
49

cfg-if

A if/elif-like macro for Rust #[cfg] statements
Rust
479
star
50

crates.io-index

Registry index for crates.io
476
star
51

backtrace-rs

Backtraces in Rust
Rust
473
star
52

style-team

Home of the Rust style team
Rust
438
star
53

docker-rust

The official Docker images for Rust
Dockerfile
414
star
54

glob

Support for matching file paths against Unix shell style patterns.
Rust
381
star
55

rust-forge

Information useful to people contributing to Rust
Rust
380
star
56

compiler-team

A home for compiler team planning documents, meeting minutes, and other such things.
HTML
380
star
57

wg-async

Working group dedicated to improving the foundations of Async I/O in Rust
Rust
365
star
58

www.rust-lang.org

The home of the Rust website
Fluent
358
star
59

compiler-builtins

Porting `compiler-rt` intrinsics to Rust
Rust
328
star
60

measureme

Support crate for rustc's self-profiling feature
Rust
324
star
61

rustc-hash

Custom hash algorithm used by rustc (plus hashmap/set aliases): fast, deterministic, not secure
Rust
312
star
62

blog.rust-lang.org

The Rust Programming Language Blog
HTML
302
star
63

team

Rust teams structure
Rust
293
star
64

glacier

A big 'ol pile of ICE.
Rust
289
star
65

project-error-handling

Error handling project group
264
star
66

atom-ide-rust

Rust IDE support for Atom, powered by the Rust Analyzer or Rust Language Server
JavaScript
259
star
67

stacker

Manual segmented stacks for Rust
Rust
252
star
68

a-mir-formality

a model of MIR and the Rust type/trait system
Rust
245
star
69

cmake-rs

Rust build dependency for running cmake
Rust
241
star
70

edition-guide

A guide to changes between various editions of Rust
238
star
71

getopts

The getopts repo maintained by the rust-lang project
Rust
229
star
72

annotate-snippets-rs

Library for snippet annotations
Rust
223
star
73

rust-roadmap-2017

Tracking Rust's roadmap
215
star
74

areweasyncyet.rs

Are we async yet?
Rust
211
star
75

rust-playpen

A web interface for running Rust code
Rust
208
star
76

wg-allocators

Home of the Allocators working group: Paving a path for a standard set of allocator traits to be used in collections!
199
star
77

rustc-demangle

Rust symbol demangling
Rust
196
star
78

lang-team

Home of the Rust lang team
JavaScript
191
star
79

highfive

Github hooks to provide an encouraging atmosphere for new contributors
Python
185
star
80

ferris-says

A Rust flavored implementation of `cowsay`
Rust
182
star
81

rust-guidelines

This repository has moved
179
star
82

cargo-bisect-rustc

Bisects rustc, either nightlies or CI artifacts
Rust
177
star
83

rustwide

Execute your code on the Rust ecosystem.
Rust
177
star
84

homu

A bot that integrates with GitHub and your favorite continuous integration service
Python
174
star
85

triagebot

Automation/tooling for Rust spaces
Rust
162
star
86

rfcbot-rs

Coordinates asynchronous decision making on Rust repositories. Status of tracked issues and PRs can be viewed at https://rfcbot.rs.
Rust
157
star
87

prev.rust-lang.org

The previous Rust website. The current website's code is at https://github.com/rust-lang/www.rust-lang.org.
HTML
153
star
88

pkg-config-rs

Build library for invoking pkg-config for Rust
Rust
147
star
89

thanks

Celebrate Rust contributors.
Rust
146
star
90

rustc-reading-club

Rust Code Reading Clubs
141
star
91

simpleinfra

Rust Infrastructure automation
HCL
140
star
92

gll

GLL parsing framework.
Rust
137
star
93

ena

An implementation of union-find / congruence-closure in Rust. Extracted from rustc for independent experimentation.
Rust
131
star
94

wg-cargo-std-aware

Repo for working on "std aware cargo"
130
star
95

rust-memory-model

Collecting examples and information to help design a memory model for Rust.
Python
125
star
96

rust-artwork

Official artwork for the Rust project.
122
star
97

libs-team

The home of the library team
Rust
107
star
98

google-summer-of-code

Rust project ideas for Google Summer of Code
105
star
99

rustup-components-history

Rustup package status history
Rust
102
star
100

wg-grammar

Where the work of WG-grammar, aiming to provide a canonical grammar for Rust, resides
Rust
101
star