Keep `use`d items on individual lines when requested

[tomassedovic]

Feature Request

Summary

This is a request for an option to not collapse items in braced blocks into a single line. E.g.:

This (Example 1):

use crate::{
    example1,
};

is now collapsed to:

use crate::example1;

And this (Example 2):

use crate::{
    example1,
    example2::{
        example3,
        example4,
        example5,
    },
    example6,
    example7,
    example8::example9,
};

is collapsed to:

use crate::{
    example1,
    example2::{example3, example4, example5},
    example6, example7,
    example8::example9,
};

We would like for these items to remain within the braced blocks.

Motivation

This comes form the Linux kernel, where the coding style guidelines request each imported item be on a separate line:

https://docs.kernel.org/rust/coding-guidelines.html#imports

The justification is to minimise the diff when adding/removing new imports. This makes the changes easier to review as well as comment on.

That same reasoning can be extended to anyone who'd like to have the "line churn" reduced when making changes to the use sections.

Workaround

Right now, the Rust code in Linux works around this by appending a trailing double slash (//, an empty comment) to the last item before the ending brace, which leaves the spacing as is:

use crate::{
    example1, //
};

and:

use crate::{
    example1,
    example2::{
        example3,
        example4,
        example5, //
    },
    example6,
    example7,
    example8::example9, //
};

In other words, we'd like to have this behaviour without having to specify the empty comments.

Related configuration options

The Vertical imports_layout is almost what we want (it covers Example 2), but it collapses a single item within braces (Example 1). We'd like to be able to do both.

[ojeda]

Right now, the Rust code in Linux works around this by appending a trailing double slash (//, an empty comment) to the last item before the ending brace, which leaves the spacing as is:

To add/clarify on the "as is": rustfmt actually reformats the code that way already (i.e. rather than just skipping the imports).

So it is true that those examples will remain as is, but if you were to change them slightly (or even substantially, as long as the //s are there), rustfmt would reformat them back to what we want. For instance, the following "broken" example will be reformatted to the expected example above:

use crate::{
    example1,
    example2::{example3, example4, example5, //
    },
    example6, example7,
    example8::example9, //
};

This is important because it allows us to easily format the imports today in stable Rust and it shows that the logic to implement it is essentially there, i.e. it is not a completely new format.

So one could say, in a sense, that what we need is for rustfmt to have an option to format things like it already does, but assuming those //s are there.

[ytmimi]

Just want to point out that imports_layout=Vertical leaves Example 2 unchanged.

And this (Example 2):

use crate::{
    example1,
    example2::{
        example3,
        example4,
        example5,
    },
    example6,
    example7,
    example8::example9,
};

So The main ask here is to prevent collapsing

use crate::{
    example1,
};

into

use crate::example1;

The trailing comment in the example prevents rustfmt from normalizing the import list.

use crate::{
    example1, //
};

[ojeda]

Just want to point out that imports_layout=Vertical leaves Example 2 unchanged.

Yeah, Tomas mentions it in OP and links to a comment of mine elsewhere. It is very close to what we want -- not sure if there may be other significant differences, though.

It would be nice to consider the pros/cons of the single item case. For instance, it is more consistent with the single items themselves inside the inner levels, but we don't really need use foo; at the top level (without pub etc.). So for us it is better to add the braces already so that it is a list, so that one may have just pure addition diffs later on.

Do you know if there are other advantages for keeping it in a single line? Would it make sense to have a variation of Vertical? (i.e. I assume changing Vertical would be too disruptive, even if unstable).

Thanks for taking a look!

[ytmimi]

I'm wondering if we added an option named single_item_import_style (name pending). Here's roughly how I think it could work:

single_item_import_style

• Default value(s):
  • NoBrace: For style_edition 2015, 2018, 2021, 2024
  • Preserve: For style_edition 2027
• Possible values: Preserve, Brace, NoBrace
• Stable: No

NoBrace (default for style_edition 2015, 2018, 2021, 2024):

Always remove braces from an import list if only one item is being brought into scope. Does not apply for self imports or top level imports.

use external_crate;
use external_crate2::{self};

use crate::example1;
use crate::example2;
use crate::{example3::example4, example5::example6};

Preserve (default for style_edition 2027)

Leave single item imports as the user wrote them.

use external_crate;
use external_crate2::{self};

use crate::example1;
use crate::{example2};
use crate::{example3::example4, example5::example6};

Brace

Always add braces to single item imports. Does not apply for top level imports.

use external_crate;
use external_crate2::{self};

use crate::{example1};
use crate::{example2};
use crate::{example3::{example4}, example5::{example6}};

---

Technically, it wouldn't be a breaking formatting change to set the default value to Preserve since all code formatted a certain way would stay the same. However, if we wanted to be conservative and keep the behavior the same we should start with NoBrace as the default and then change the default to Preserve in the next style_edition. Preserve would allow you to remove the load bearing comments, but you'd still need to manually add braces. What I think you'd want is Brace, but I don't know if you need to wait for this option to be stabilized before you could start using it.

[ojeda]

What I think you'd want is Brace

Yeah, I think that would be ideal!

but I don't know if you need to wait for this option to be stabilized before you could start using it.

We are happy using unstable options, but rustfmt doesn't (or didn't) allow RUSTC_BOOTSTRAP=1 -- I asked about it at #4884 (there has been recent activity around it, e.g. a comment from Ralf from December).

To give some context, in case it helps: while using unstable in rustfmt is of course quite risky in general, it would be nice to be able to use unstable options when they are known to be stable "enough" ("functionally stable") in the future, because we support a range of stable versions.

For instance, if we know single_item_import_style is implemented in Rust 1.97, and something critical was fixed in Rust 1.98, and it was renamed in Rust 1.99, and a small bug fix for a corner case that doesn't affect us happens in Rust 1.100, and then it becomes stable in Rust 1.101, then we could actually use it since Rust 1.98, rather than Rust 1.101.

The reason is that we do not need that something is stable in the sense of "nightly features" or even across renames (we handle those on the build system), but rather that whoever has toolchain version X can use it or not (where X could be an upstream stable release or beta or nightly, or a distro version that may be patched somehow etc.).

The same approach was taken for other unstable features and tools we use, i.e. we enable them in older versions where they are not actually stable. Also please note that we don't allow kernel developers to enable them randomly, i.e. I gate them, and if we wanted to use something new that is not already stable officially, then we would ask first.

Thanks again!

[ojeda]

(Re-posting, I hadn't finished writing it, sorry!)

Thinking about it a bit more, what we currently do is closer to Preserve for nested imports (please see below), but Brace for crates.

For instance, in your example, we sometimes don't use braces for ::{example4} unless the parent is something that we know may have other imports later inside, like a module with many other things we will be likely to use. The same reason is why we would most likely want braces for crate and external_crate2 in your example, since they are crates. (And we don't really have the case for non-pub, non-as single top-level imports like use external_crate;, I think).

i.e. following your example, what we would perhaps write is, assuming we expect more items from example3 but we don't from example5 (and assuming example4 and example6 are not modules or enums, or if they are we don't plan to use {self, ...}), is:

use external_crate;
use external_crate2::{
    self,
};

use crate::{
    example1,
};
use crate::{
    example2,
};
use crate::{
    example3::{
        example4,
    },
    example5::example6,
};

Since I think you don't know within rustfmt what kind of item something is (and even casing wouldn't help, since e.g. both functions and modules both usually use snake_case), then we could perhaps want Preserve instead of a full Brace, because otherwise perhaps it could be too many braces and newlines even for things that will likely never have siblings, right?

On the other hand, Brace is more consistent. Taking a real example we have from a random file (copy-pasting with // included):

use crate::{
    alloc::Flags,
    bindings,
    device::{
        Bound,
        Device, //
    },
    error::to_result,
    prelude::*,
    revocable::{
        Revocable,
        RevocableGuard, //
    },
    sync::{
        aref::ARef,
        rcu,
        Arc, //
    },
    types::ForeignOwnable, //
};

With full-fledged Brace (and removing // since we wouldn't need the hack anymore) this would be, if I understand correctly:

use crate::{
    alloc::{
        Flags,
    },
    bindings,
    device::{
        Bound,
        Device,
    },
    error::{
        to_result,
    },
    prelude::*,
    revocable::{
        Revocable,
        RevocableGuard,
    },
    sync::{
        aref::{
            ARef,
        },
        rcu,
        Arc,
    },
    types::{
        ForeignOwnable,
    },
};

That isn't too bad -- I think it could be reasonable as well. I will ask others.

Not sure about the ::* case, though (for prelude it doesn't matter much, since the plan is to have custom preludes supported in the compiler, so they wouldn't be there, but we do have other ::* cases out there).

[ojeda]

I will ask others.

I asked the team in our meeting today. There are a wide variety of opinions, but I think overall the sentiment is that, as long as we get to remove the // comments soon, we will be able to live one way or the other with whatever option(s) you decide to provide, including stabilizing Vertical as-is, or the Preserve-like logic that rustfmt has when it faces // comments, or even Brace proposed here.