cargo-fmt

Format all source files

$ cargo fmt

$ cargo fmt --check

$ cargo fmt -- [rustfmt_args]

cargo fmt [OPTIONS] [-- <RUSTFMT_OPTIONS>...]

--all
    Format all packages in the current workspace.

--package <SPEC>, -p <SPEC>
    Format only the specified package.

--lib
    Format only the current package's library.

--bin <NAME>
    Format only the specified binary.

--example <NAME>
    Format only the specified example.

--test <NAME>
    Format only the specified test.

--bench <NAME>
    Format only the specified benchmark.

--target <TRIPLE>
    Format for the given target triple.

-q, --quiet
    Do not print rustfmt output to stdout.

--message-format <FMT>
    Output messages in a specific format (e.g., human, json).

-v, --verbose
    Use verbose output.

--color <WHEN>
    Control when colors are used (auto, always, never).

--config-cli <KEY=VALUE>
    Set a rustfmt config option directly from the command line, overriding rustfmt.toml.

-- <RUSTFMT_OPTIONS>...
    Pass arbitrary options directly to the underlying rustfmt command. Common rustfmt options include --check (to only check formatting without writing), --emit stdout (to print to stdout), or --files <path>... (to format specific paths).

cargo-fmt is a convenient subcommand of cargo, the Rust package manager, designed to automatically format Rust source code. It acts as a wrapper around rustfmt, the official Rust code formatter, ensuring consistent code style across projects. This consistency greatly enhances code readability, maintainability, and streamlines collaborative development.

When invoked without arguments, cargo-fmt formats all Rust files within the current package. It can also target specific packages, binaries, or libraries. A key feature is the ability to pass arbitrary rustfmt options using a double-dash (--), enabling functionalities like checking formatting without modifying files (--check) or printing formatted code to stdout. The formatting rules are highly configurable via a rustfmt.toml file placed in the project root or parent directories, allowing teams to tailor the style to their preferences while still benefiting from automation.

cargo-fmt requires rustfmt to be installed and available in the system's PATH, which is typically done via rustup component add rustfmt. While highly configurable through rustfmt.toml, rustfmt is an opinionated formatter, meaning it enforces a specific style. Always commit your changes or back up your code before running cargo-fmt, as it modifies files in place.

cargo-fmt respects configuration options defined in a rustfmt.toml file. This file can be placed in the project root or a parent directory, allowing for per-project or per-workspace customization of formatting rules. Options like max_width, tab_spaces, and imports_layout can be adjusted here.

The command cargo fmt -- --check is invaluable for Continuous Integration/Continuous Deployment (CI/CD) pipelines. It allows you to verify that all code in the repository adheres to the defined formatting standards without actually modifying any files, thus failing the build if unformatted code is detected. This ensures code style consistency before merging changes.

rustfmt, the core formatting tool, was initially developed by Nick Cameron and others, evolving into an official component of the Rust distribution. The cargo-fmt subcommand was later introduced as a seamless integration with cargo, simplifying the workflow for Rust developers to apply consistent code formatting across their projects. This standardization effort helps maintain high code quality and readability within the Rust ecosystem, continually evolving with new Rust editions and community contributions.

rustfmt(1), cargo(1), rustup(1)