Formatting

Ensuring consistent formatting across a project helps reduce friction. It allows Code Reviews to focus on the content, and not the formatting of the code.

One thing the Rust community does very well is have a consistent formatting style, which eliminates the surprises you will encounter when reading other people’s code. The canonical tool used for formatting Rust code is rustfmt.

Rustfmt

Rust code can be formatted using rustfmt, which is a core piece of Rust tooling and used by the whole Rust community.

By incorporating rustfmt checks into the CI system, you can make sure that issues with formatting are caught before code review.

Installation

Usually, rustfmt comes preinstalled when you install Rust. However, if you do not have it, you can install it using:

rustup component add rustfmt

You can run rustfmt against a crate like this:

cargo fmt

In a CI system, you can check if the code is properly formatted using the --check command-line flag.

cargo fmt --check

If the code is not properly formatted, this will return a nonzero exit code and cause the CI check to fail.

Configuration

Rustfmt can also optionally take some configuration in a rustfmt.toml file. This allows you to override specific behaviour, for example to set how it will group imports.

Some configuration options are unstable at the moment and therefore require an unstable build of Rustfmt. When using it you have to call rustfmt like this:

cargo +nightly fmt

Examples

Here is one example of a project which has a rustfmt.toml to configure rustfmt, and some CI steps which enforce the formatting in CI.

/target

stages:
  - check

formatting:
  stage: check
  image: rust
  script:
    - cargo +nightly fmt --check

# This file is automatically @generated by Cargo.
# It is not intended for manual editing.
version = 4

[[package]]
name = "check-formatting"
version = "0.1.0"

[package]
name = "check-formatting"
version = "0.1.0"
edition = "2021"

[dependencies]

imports_granularity = "Crate"
group_imports = "One"
edition = "2021"

fn main() {
    println!("Hello, world!");
}

Reading