Gradual formatting settings changes via `existing` vs `desired` config sections.

[dpc]

I really wish Rust had is a standardized solution to gradually introducing/changing formatting. In a larger project changing formatting settings always involve either a very undesirable huge patch changing formatting over the whole project, or some shenanigans around avoiding it.

I had an idea how gradual formatting changes with rustfmt could be achieved that I posted on reddit and no one pointed out how is it infeasible, so I thought I'll post it here as well:

Maybe rustfmt could maintain "existing" and "desired" sections in "rustfmt.toml" and if an existing file (or even better: a piece of code) matches "existing" formatting settings just leave it as is when formatting, while parts that are not correctly formatted w.r.t "existing" format would get formatted using "desired" settings. cargo fmt --check would accept code formatted with any of the two styles.

I hope that this would be relatively easy to implement (thought might be wrong), and it seems to me it would work well in practice and allow project to gradually roll out formatting changes, and also allow Rust style team to evolve things without introducing continuous churn.

If something like this already exists or was proposed, please let me know and feel free to close this issue. Thanks.

[ytmimi]

Thanks for reaching out!

I'm not sure I fully understand the request. Could you post an example of what a hypothetical rustfmt.toml would look like with your proposed changes.

[dpc]

@ytmimi

[existing]

[desired]
group_imports = "StdExternalCrate"

The simplest example I can come up with. "existing" settings are default settings, while "desired" settings have group_imports changed.

I'm not sure about the exact semantics, but these two sections could even be two separate files: rustfmt.toml (for "desired") and rustfmt-existing.toml (for "existing"/"previous"/"past"/"still accepted").

Anyway - assuming one file with two sections:

After changing rustfmt.toml to this content, cargo fmt --all would... change nothing. Because all files are still valid, matching "existing" settings. cargo fmt --check would be successful as well.

It would only reformat files (or chunks of code) when they actually don't pass existing or desired formatting rules, and then it would use desired settings for the generated code.

As the developers change code, they would trigger reformatting (to "desired" settings) only of files/code that they already change.

After a while, as the normal development goes, most (especially most often touched) files would get reformatted with the new settings and maintainers could change the content to:

[existing]
group_imports = "StdExternalCrate"

(missing [desired] should imply that "existing" == "desired")

possibly reformatting couple of last "cold" files (that are rarely touched). The gradual reformatting of the codebase is complete, avoiding big-bang codebase reformatting and messing up git blame output needlessly, and unnecessary merge conflicts.

[dpc]

I think it is possible to implement this exact behavior by just wrapping rustfmt, calling it twice, comparing files etc. but the problem with it is that every developer would now have to use such wrapper, or otherwise rustfmt would just create a huge change, possibly causing big problem.

That's why I think this behavior needs to be built-in into rustfmt itself.

[calebcartwright]

Thanks for reaching out, but I'm going to close as this isn't something that would be feasible nor does it align with core goals and objectives.

There's various means available if you want to gradually introduce formatting and/or formatting gates to your project, or to only format a subset of your project. The input to rustfmt is actually individual file(s), and it also supports a more granular formatting of subsets of files via the --file-lines option, alongside other config options, like ignore that can be used to skip enumerated files. cargo fmt invocations simply build and execute the stereotypical "format my entire project" rustfmt ... commands on your behalf for simplicity. However, it's not entirely uncommon for larger projects, e.g. the rust compiler itself, to utilize rustfmt directly if they want/need something more complex.

If you decide to introduce rustfmt to your project, whether you choose to do it incrementally in small chunks via the above mechanisms, or in a big bang approach (as was done for the main rust-lang/rust repo), is entirely your decision.

The delineation you are trying to draw between camps of config options doesn't actually diverge from existing behavior in the context of actually formatting a given AST node. If the code is already formatted correctly according to the rules+config options then there's no impact from running rustfmt (output is identical to input/no changes/--check passes/etc.). However, if the input code is formatted incorrectly, then the corrected output will of course be different.

It's still unclear, but I assume you are trying to propose a way wherein you could run rustfmt to "only change one thing" or only apply a single/specific set of formatting rules. However, formatters don't typically work that way; rustfmt absolutely does not and will not. rustfmt is an AST-driven pretty-printer style formatter that does not directly process your input files. It has to do something for every single node in the AST, and we can't/won't support a mode where you only run rustfmt for a single "rule".

[dpc]

@calebcartwright Please make sure you've read the comment just above yours (I happen to post right before you).

The goal here is to have a standard, practical and holistic approach to gradually introducing formatting changes across (especially larger) Rust projects. It's a huge problem that I see being stumbled upon over and over in the projects I work on, and I think Rust should lead the charge and have such problems figured out in the standard tooling.

[dpc]

It's still unclear, but I assume you are trying to propose a way wherein you could run rustfmt to "only change one thing" or only apply a single/specific set of formatting rules.

I think we misunderstand each other. @calebcartwright

I don't want to change one thing. The "existing" vs "desired" could be very long and contain plenty of settings each. I only want to avoid big reformatting of the whole Rust project, just because there's a new awesome formatting option available and maintainers would like to "phase it in" smoothly.

[calebcartwright]

@dpc - I've seen and read all of your comments.

I've already enumerated the various options that are available for introducing formatting to an unformatted project, and the approaches that have been applied successfully across projects big and small. There's never going to be a singular/standard way because context always matters and what works better for one team/codebase may not work well for another.

There's not really anything else I can say without repeating my prior comment, so I'd recommend re-reading my comment and asking questions if you'd like clarification, or if you'd like us to recommend a particular approach given your context and constraints "e.g. is there a way we could get our imports regrouped without modifying other formatting?"

However, it's a firm, unequivocal "no" to your feature request for the reasons previously articulated.

[dpc]

@calebcartwright

There's never going to be a singular/standard way because context always matters and what works better for one team/codebase may not work well for another.

But why? Why are we forcing every single project to invent ad-hoc solutions to a common problem. This does not seem very Rusty at all.

I am yet to see a project that eventually doesn't hit the "we would like change formatting rules, but reformatting existing code is such a PITA".

It feel like writing your own Makefiles and configure.ac files again, just in the formatting realm. The same rationale are given: "every project has own needs, context matters, yada yada..." and then people love Rust because there's cargo and stuff just builds.

I can acknowledge that "context matters" but I'm sure we could have a solution that works reasonably well for 99% of projects, while the 1% with the scope and needs can still use their own custom solutions.

[dpc]

For completeness: it was pointed out to me that this method only helps projects that are already formatted using certain style, and it does not work for project that don't have any automated format (were not using rustfmt before, which is a bad idea, IMO, but does happen).