Since Dart 3.7, how does dart format choose between the short and tall styles, and how do you configure page width and trailing commas?

## Two styles, chosen per file Dart 3.7 shipped a largely rewritten formatter with a new **tall style**, better suited to the declarative, deeply nested code common in Flutter widget trees. Rather than flip every project at once, the formatter decides **per file** using the file's **language version**: | Language version | Style | Trailing commas | |---|---|---| | 3.6 or lower | short (old) style | a trailing comma you write forces a split and is kept | | 3.7 or later | tall style | the formatter adds them to split lists and removes them from lists that fit | The language version usually comes from the **lower bound of the SDK constraint** in `pubspec.yaml`. Raising `environment: sdk:` to `^3.7.0` or higher therefore opts the whole package into the tall style the next time it is formatted. The formatter reads that version through the package configuration file, which is why `dart pub get` must have run. The release notes say the old style will not be supported forever; once most of the ecosystem is on 3.7 or later, support for it is planned to be removed. ## Project-wide configuration The formatter looks for an `analysis_options.yaml` in the file's directory and walks upward until it finds one. It reads a top-level `formatter` section: - **`page_width`** - the target line length. The default is 80. Setting it in one file applies to everything beneath it, and because analysis options support `include`, a shared options file can carry it across many packages. - **`trailing_commas: preserve`** - added in Dart 3.8 and off by default. When set, a trailing comma you add to an argument list, parameter list or similar construct **forces** it to split across lines even if it would fit, giving manual control over line breaks. Without it, the tall style removes a trailing comma from anything that fits on one line. These options require a language version of at least 3.7; `trailing_commas` requires 3.8. ## Per-file and per-region overrides 1. **`// dart format width=123`** placed before any code in a file overrides the page width for that file. It exists mainly for code generators, which format their output without knowing the surrounding options file. 2. **`// dart format off`** and **`// dart format on`** exempt the lines between them from formatting - useful for hand-aligned tables of numbers. The comments must match exactly, and regions cannot overlap or nest. ## The command-line flag `--page-width` sets the width on the command line. It replaced `--line-length` in 3.7; the old name still works for backwards compatibility. Project configuration is preferred because every developer, editor and CI job then reads the same value. ## Scenario: formatting a new command-line package A package created today with `dart create` gets an SDK constraint of `^` the current SDK version, so 3.7 or later, so it is formatted in the tall style from the first commit. If the team wants a width of 100, it adds `formatter: page_width: 100` to the generated `analysis_options.yaml` - not a flag in a script - so format-on-save and the CI check agree. ## Common mistakes - Expecting a hand-written trailing comma to force a split in tall style without `trailing_commas: preserve`. - Setting the width only in an editor setting, so CI formats differently. - Raising the SDK lower bound in a large repository without planning for the one-time reformat of every file. - Assuming the style is chosen per package; it is chosen per file, by that file's language version.