In a Dart or Flutter analysis_options.yaml, what do include:, linter: rules, analyzer: errors: and analyzer: exclude: each control?

## Where the file lives and how it is found `analysis_options.yaml` configures the Dart **analyzer**, the engine behind IDE squiggles, `dart analyze` and `flutter analyze`. Put it at the **package root**, in the same directory as `pubspec.yaml`. If the analyzer finds no file there it **walks up** the directory tree and uses the first one it finds; with none at all it runs its default checks. In a repository with several packages, a package that has its own file uses that one, while packages without one inherit the nearest file above them. The file has a few top-level keys. This question covers the four most used ones: | Key | Controls | Typical value | |---|---|---| | `include:` | shared option files merged in first | `package:flutter_lints/flutter.yaml` | | `linter: rules:` | which lint rules are on or off | list of names, or `name: true/false` | | `analyzer: errors:` | severity of specific diagnostics | `todo: ignore`, `avoid_print: error` | | `analyzer: exclude:` | files not analyzed | `build/**`, `lib/**.g.dart` | Others exist: `analyzer: language:` for the strict type modes, top-level `plugins:` for analyzer plugins, and a `formatter:` section read by `dart format`. ## include: and merge order `include:` takes a single `package:` URI or relative path, or a **list** of them. The analyzer merges in this order: 1. the first included file, including anything it recursively includes; 2. each later included file, adding options or overriding conflicting ones; 3. finally the options written directly in this file, which override everything included. Merging is **per setting**, not per section. If an included set enables fifty rules and your file disables one, you get forty-nine; your `linter:` section does not wipe out the included one. Since Dart 3.10 the analyzer also reports when included files enable rules that are **incompatible** with each other, such as `prefer_single_quotes` and `prefer_double_quotes`. ## linter: rules in two shapes - **List form** enables rules: `- cancel_subscriptions`, `- close_sinks`. - **Map form** sets each rule explicitly: `avoid_print: false`, `unawaited_futures: true`. This is the only way to switch **off** a rule that an included set turned on. - YAML does not allow mixing the two in one `rules:` entry. An included file may use the other form. Lint rules report at **info** severity by default, which matters for CI gating. ## analyzer: errors: severities `errors:` is a map from a diagnostic code or lint name to one of four values: - `ignore`: never report it anywhere in the package; - `info`: report it without failing analysis; - `warning`: report it as a warning, which `dart analyze` treats as fatal by default; - `error`: report it as an error, which always fails `dart analyze`. It works for the analyzer's own diagnostics (`dead_code`, `invalid_assignment`, `todo`) and for lint names alike. It changes how a finding is **reported**, not whether the compiler accepts the code: `flutter run` does not read severities from this file. ## analyzer: exclude: globs `exclude:` lists file paths or glob patterns, **relative to the directory holding the options file**. Diagnostics are not reported for matching files. Typical entries are `build/**`, platform folders, and generated code such as `lib/**.g.dart` or `**.freezed.dart` when you do not want its findings. Excluding a file is coarse: every diagnostic for it disappears, including real errors, so it suits code you do not own or maintain by hand. ## A complete example ```yaml include: package:flutter_lints/flutter.yaml analyzer: exclude: - build/** - lib/**.g.dart errors: todo: ignore avoid_print: error linter: rules: avoid_print: true prefer_single_quotes: true use_key_in_widget_constructors: false ``` Reading it top to bottom: take flutter_lints' rules; skip build output and generated parts; hide `TODO` comments; make any `print` call an error; also enforce single quotes; and switch off one rule the included set enabled. ## Pitfalls - **Tabs or bad indentation** break YAML silently; use two spaces per level. - Using `exclude:` to silence one noisy rule hides every other finding in those files; `errors: <rule>: ignore` or `rule: false` is narrower. - Changes to `plugins:` need an analysis server restart before they take effect. - Enabling a rule and setting its severity are **separate**: `avoid_print: true` under `linter: rules:` makes the rule run, while `avoid_print: error` under `analyzer: errors:` decides how loudly it reports. Setting a severity for a rule that no included file or local entry enables has nothing to report. - A package nested inside another uses **its own** options file if it has one, not the parent's; a shared team file therefore has to be included explicitly (`include: ../../analysis_options.yaml`) when a nested package also needs local settings. ## Reading someone else's options file In an interview you may be handed an options file and asked what it does. Read it in merge order: resolve each `include:` first, then apply the local `linter:` toggles, then the `analyzer:` severities and excludes. Ask two questions of every entry: does it change **which** findings exist, or **how** they are reported?