preserve_block_start_blank_lines config simply doesn't exist

[Jerald]

Describe the bug

As the title says, the preserve_block_start_blank_lines config option simply doesn't exist to rustfmt . If it's in my rustfmt.toml I get this error:

Warning: Unknown configuration option `preserve_block_start_blank_lines`

To Reproduce

It's as easy as manually adding the key via the --config flag:

cargo +nightly fmt -- --check --config preserve_block_start_blank_lines=true

This produces a similar (but not exactly the same) error as above. To get the same error as above, just put it into a rustfmt.toml file.

Expected behavior

The flag actually works and applies the formatting.

Meta

• rustfmt version: rustfmt 1.4.21-nightly (01f2eadc 2020-09-04)
• From where did you install rustfmt?: rustup
• How do you run rustfmt: with cargo fmt

---

I found the PR that introduced this flag at #4303, which definitely seems to be after the date that my nightly release was built from. This seems to indicate the flag is just straight up broken? I'm guessing a future change broke the parsing of the key and it slipped through, possibly by the tests not functioning correctly...

[Jerald]

Closing since I discovered that apparently, it's for v2 but not v1.4.

My expectation is that "nightly" is literally the nightly build from master, and therefore the newest build. But apparently rustfmt doesn't work like that? Either way, the configuration option selection is real confusing these days...

[calebcartwright]

My expectation is that "nightly" is literally the nightly build from master, and therefore the newest build. But apparently rustfmt doesn't work like that?

That's an incorrect assumption.The nightly builds are based on the content within the rust-lang/rust repo, including tools like rustfmt. Most of the tools distributed as components via rustup are submods within the main rust-lang/rust repo, and when a tool wants to release a new version the corresponding submod is updated accordingly. The distributed tools/components are not built directly from the latest in-source version of the tools in their respective repos.

You should always refer to the rustfmt configuration documentation https://rust-lang.github.io/rustfmt/ for your version of rustfmt when you want to understand the available configuration options for the particular version you are using. You can use the dropdown to select your version, or direct link here https://rust-lang.github.io/rustfmt/version=v1.4.21

There's a lot of different versions of rustfmt used across different channels in the wild, and the available configuration options can and do vary between versions, for example between v0.x vs v1.x vs the upcoming v2.x, as well as new options sometimes added with a minor or patch version bump. We can't readily reflect those different configurations within a markdown file on the default branch in a repo, which is why the version-specific configuration site exists and why we encourage folks to use it.

More info here: https://github.com/rust-lang/rustfmt#configuring-rustfmt

[bluenote10]

That's an incorrect assumption.

I made exactly the same assumption and was puzzled by the error for a while. Probably because the documentation says

and typically "not stable" equals "nightly". Would it make sense to document the rustfmt version there instead?

Pardon my stupid question, but I'm completely new to the rustup toolchain world, and don't fully understand the above explanation. Does it mean that it is in general impossible to run rustfmt 2.x via cargo +nightly fmt? If so, is there a way to setup rustfmt 2.x in a way that is similar easy to invoke?

[calebcartwright]

@bluenote10 -

I made exactly the same assumption and was puzzled by the error for a while. Probably because the documentation says
and typically "not stable" equals "nightly".

Whether or not an option has been stabilized and is available with rustfmt on stable is separate from the rustfmt release process. The contents of the master branch of this repo are not necessarily what's been released and available via a distributed nightly rust.

Would it make sense to document the rustfmt version there instead?

Nope. There are two separate data points conveyed between versions and whether or not an option has been stabilized. Replacing the stable/unstable indicator with a version (and not sure what that version would mean) would remove a critical point of information for users.

Pardon my stupid question, but I'm completely new to the rustup toolchain world, and don't fully understand the above explanation.

No worries, and there's definitely no stupid questions here 😄

There's a few different ways users can get rustfmt on their system.

• Clone the repo and build from source (requires nightly)
• Grab from crates.io, either use as a lib or install the bin (requires nightly) https://crates.io/crates/rustfmt-nightly, https://crates.io/crates/rustfmt_lib/2.0.0-rc.2
• use rustup

While using rustup is the recommended and most common way to grab rustfmt, there's plenty of folks using crates.io and some building from source as well. There's also folks using rustup but that for various reasons are pinned to a specific nightly version that's not the latest-and-greatest nightly.

In all these cases folks will have a version of rustfmt built/distributed with a nightly channel, but that could be just about any version of rustfmt and the latest version of rustfmt release (v1.4.22) supports a lot of newer configuration options that are unknown/unsupported/unavailable in a different version like v1.4.9, and 1.4.22 will have stabilized various options that were still unstable/potentially broken in v1.4.9.

If you're currently using rustfmt v1.4.9, then you want to look at the configuration docs for v1.4.9 and you don't want to look at the configuration docs for a different version (like v1.4.22). Supported rustfmt configuration options and the stability of those options are tightly coupled to the version of rustfmt, so make sure you use the right version of the docs.

Does it mean that it is in general impossible to run rustfmt 2.x via cargo +nightly fmt? If so, is there a way to setup rustfmt 2.x in a way that is similar easy to invoke?

rustfmt 2.0 hasn't been released. Some folks are using it already by building rustfmt from source, but the 2.0rc is not available via rustup. If you want to use rustfmt 2.0 (either directly via rustfmt .. or via cargo fmt) then you'll need to build rustfmt from source as well.