DOCSEARCHbyAlgolia
Submit Docs

rustfmt Documentation

repository·main·Indexed 27 days ago

https://github.com/rust-lang/rustfmt

A tool for formatting Rust code according to official style guidelines. It can be used as a standalone binary, integrated into Cargo via `cargo fmt`, or used in CI/CD pipelines with the `--check` flag to enforce code style. Supports customization through `rustfmt.toml` configuration files, including language and style edition settings, and provides attribute macros like `#[rustfmt::skip]` to exclude specific code blocks from formatting.

Tokens
15.3K
Snippets
48
Records
151
Agent score
92%

What's inside rustfmt

  1. Understand rustfmt's formatting scope and semantics

    main

    Unlike simple whitespace formatters, rustfmt is designed to be semantics-preserving but not necessarily syntax-preserving. This means it can perform structural changes to the AST (Abstract Syntax Tree) to satisfy style guidelines, such as:

    • Changing glob imports to explicit list or single imports.
    • Re-ordering imports.
    • Moving bounds to where clauses.
    • Combining multiple impl blocks into a single impl block.

    However, rustfmt will not change variable names or perform any actions that could change the program's High-Level Intermediate Representation (HIR) or overall semantics.

  2. Configure Rustfmt to run on save in IntelliJ or CLion

    main

    You can automate code formatting by enabling the auto-format feature. Since IntelliJ uses autosave, your files will be formatted automatically according to rustfmt rules.

    1. Open the Rustfmt settings by navigating to File → Settings → Languages & Frameworks → Rust → Rustfmt.
    2. Enable the Run rustfmt on Save option.

    Note: You can also trigger a manual reformat by pressing Ctrl+S.

  3. Use rust-analyzer in Atom to run rustfmt

    main

    You can use rustfmt within the Atom editor via the ide-rust package, which provides rust-analyzer support.

    1. Install the package using apm install ide-rust.
    2. To format a file, use the keyboard shortcut ctrl-shift-c (Linux/Windows) or cmd-shift-c (macOS), or select the formatting option from the context menu.
    apm install ide-rust

  4. Use atom-beautify in Atom to run rustfmt

    main

    You can configure the atom-beautify package to use rustfmt for code formatting.

    1. Install the package

    Run the following command:

    apm install atom-beautify

    2. Configure settings

    Open Atom preferences via Edit -> Preferences and select atom-beautify from the packages list on the left. Configure the following:

    • Set rustfmt as the default beautifier: Locate the setting Language Config - Rust - Default Beautifier and set it to rustfmt. You can also enable auto-format on save in this section.
    • Set the rustfmt path: Locate the setting Rust - Rustfmt Path (near the bottom of the settings) and enter the absolute path to your rustfmt executable.

  5. Sync changes from rust-lang/rust to rustfmt (Subtree Push)

    main

    Use this procedure to push changes from the rust-lang/rust repository into your rustfmt fork.

    Important: All commands must be run within the rust-lang/rust checkout. Ensure you have added the rustfmt repository as a remote named upstream.

    1. Acquire/Update rust-lang/rust: Clone or git fetch the repository.
    2. Checkout latest nightly: Identify the latest nightly commit hash via rustup check.
    3. Push the subtree: Use a fresh branch (e.g., subtree-push) to avoid fast-forward issues.
    4. Merge into rustfmt: In the rustfmt repository, fetch upstream and merge upstream/main using --no-ff to create a merge commit.
    5. Bump toolchain: Manually update rust-toolchain with the latest nightly date in a dedicated commit.
    6. Open PR: Use the title subtree-push nightly-$LATEST_NIGHTLY_DATE.
    # Setup remote if not already done
$ git remote add upstream git@github.com:rust-lang/rustfmt

# Run within rust-lang/rust checkout
$ git subtree push -P src/tools/rustfmt /path/to/rustfmt/checkout subtree-push

# In the rustfmt repository (to create merge commit)
$ git fetch upstream
$ git switch subtree-push
$ git merge upstream/main --no-ff

  6. Create a rustfmt configuration file

    main

    You can configure rustfmt by creating a rustfmt.toml or .rustfmt.toml file. Place this file in your project root or any parent directory. If no project-specific file is found, rustfmt checks your home directory and the global config directory (e.g., .config/rustfmt/).

    indent_style = "Block"
reorder_imports = false

  7. Bind a keyboard shortcut to Reformat File with Rustfmt

    main

    To manually trigger rustfmt using a keyboard shortcut in IntelliJ or CLion:

    1. Open the settings window (File → Settings).
    2. Search for "reformat" in the search bar.
    3. Locate the action Reformat File with Rustfmt.
    4. Right-click the action and assign your preferred keyboard shortcut.
    5. Click OK to save the changes.

    You can now use this shortcut while working in any *.rs file.

  8. Enable unstable configuration options

    main
    Configuration options are categorized as either stable or unstable. Unstable options require a nightly toolchain and must be explicitly enabled. You can enable them by setting unstable_features = true inside your rustfmt.toml file or by passing the --unstable-features flag to the rustfmt CLI.
    unstable_features = true

  9. Stabilise a configuration option

    main

    To move a rustfmt configuration option from unstable to stable, ensure the following conditions are met:

    • The default value is correct.
    • The design and implementation are sound and clean.
    • The option is well-tested (unit tests and real-world usage).
    • There are no open bugs preventing its use.

    Steps to stabilise:

    1. Open a pull request that closes the tracking issue (found in Configurations.md).
    2. Update the Config enum to mark the option as stable.
    3. Update Configuration.md to mark the option as stable.
    4. Update CHANGELOG.md to mark the option as stable.

    Post-stabilisation requirement: Options must remain backward-compatible. If an enum variant is renamed or removed, existing usage must map to the new logic. Breaking changes must be version-gated.

  10. Format a Cargo project with `cargo fmt`

    main

    The easiest way to format a Rust project is using cargo fmt. This works for both single-crate projects and Cargo workspaces.

    On Stable

    cargo fmt

    On Nightly

    cargo +nightly fmt

    You can specify a custom rustfmt binary for Cargo to use by setting the RUSTFMT environment variable (requires version 1.4.22 or newer).

  11. Check style on a CI server (Travis CI example)

    main

    To fail a CI build when unformatted code is detected, use cargo fmt --all -- --check.

    Example Travis CI configuration (requires Rust 1.31.0+):

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

  12. Sync changes from rustfmt to rust-lang/rust (Subtree Pull)

    main

    Use this procedure to pull changes from the rustfmt repository into the rust-lang/rust repository.

    Important: All commands must be run within the rust-lang/rust checkout.

    1. Update rust-lang/rust: Ensure the latest main branch is checked out.
    2. Pull the subtree: Create a new branch and use git subtree pull to sync the rustfmt main branch into the src/tools/rustfmt directory.
    3. Open PR: Use the title rustfmt subtree update to ensure triagebot handles the merge commit correctly.
    # Run within rust-lang/rust checkout
$ git switch -c rustfmt-subtree-update
$ git subtree pull -P src/tools/rustfmt /path/to/rustfmt/checkout main