facebook
Support formatting of specific line ranges
The repeatable --lines option of google-java-format allows for formatting specific line ranges only rather than a whole file. This is useful for scripts/tools that want to run formatters only on lines that have been touched by a change, which avoids churn when formatter behavior changes.
An example of a tool that would utilize this is the fix Mercurial extension.
GJF does this by expanding the formatted region to a minimal region that makes sense semantically. For example, formatting a line from a method would reformat the entire method. GJF code has markers that tell the engine when to stop expanding a region: OpsBuilder.markForPartialFormat.
ktfmt inherits the infra, but not the semantic knowledge, meaning we'll need to add markForpartialFormat calls in places that make sense for this expansion.
I think a reasonable place to start is function boundaries. Tests can be strongly inspired by GJF's.
We (facebook) haven't invested in this because we have other means to avoid churn.
At work we format whole-hog, so this feature isn't very necessary. On my home project, I indulge in hand-formatting when the formatter does something I find intolerable. For that workflow, this feature would be nearly essential. (It's still annoying, of course, since whenever you actually touch code near the hand-formatted region you will always have to revert the reformatting. But it's workable and we never bothered trying to improve on it for GJF.)
How much this tool should value that use case vs. the first is a completely fair question.
On my home project, I indulge in hand-formatting when the formatter does something I find intolerable.
The intent of this isn't to allow hand-formatting of some lines, but rather avoiding churn when ktfmt changes formatting logic between versions. e.g. ktfmt 0.43 formats some things differently than ktfmt 0.41. To avoid churn, we'd want to limit the "splash damage" caused by editing lines in a file.
Well, the original intent in the ancestor tool was both. :-) I wanted there to be some escape valve without visible "format off" comments in the code. No matter anyway; I've added my use case and the devs can decide to value it however they will.