# Configuration
Use `.profmt.toml` to define formatting policy for a project. profmt applies
settings in this order:
1. Start with the project-neutral defaults.
2. Load the nearest `.profmt.toml`, or the file passed to `--config`.
3. Apply CLI style options.
Pass `--no-config` to use the defaults. Unknown keys and invalid values are
errors.
## Options
Every field is optional. Options whose variants are named layouts default to
`preserve`, which keeps what the source does, wherever projects reasonably
disagree.
| `line_width` | `80` | Maximum width used to choose line breaks. Only the layouts that opt into wrapping, and text-format message literals, consult it. |
| `indent_width` | `2` | Spaces emitted for one indentation level. |
| `quote_style` | `"preserve"` | String delimiters: `single`, `double`, or `preserve`. Delimiters change only when the string contains no quote or backslash. |
| `header_order` | `"preserve"` | Order of the statements before the first definition. `package_first` gives `syntax`, `package`, imports, options — the Google style guide order; `imports_first` swaps `package` and the imports. |
| `import_order` | `"preserve"` | `sorted` makes the imports one contiguous block ordered by path. Each import keeps the comments attached to it. |
| `empty_block_layout` | `"compact"` | An empty `message`, `enum`, `service`, `oneof`, `extend`, group or `rpc` body: `compact` prints `{}`, `expanded` puts the closing brace on its own line. |
| `empty_rpc_body` | `"preserve"` | An `rpc` with no options ends with `semicolon` or empty `braces`. |
| `empty_statements` | `"remove"` | A `;` that terminates nothing is dropped, or `preserve`d directly after the statement it follows. |
| `declaration_spacing` | `"preserve"` | `separated` puts a blank line before and after every declaration with a multi-line body, except at the start or end of its enclosing block. |
| `comment_spacing` | `"preserve"` | `normalized` prints `//text` as `// text`. Comments starting `///` or `//!`, and block comments, are kept as written. |
| `rpc_signature_layout` | `"single_line"` | `break_before_returns` moves `returns (Response)` to an indented line when the signature does not fit. |
| `field_options_layout` | `"single_line"` | `one_per_line` puts each option of a field or enum value on its own indented line, with the closing bracket back at the field's indentation, when the field does not fit. |
| `option_value_layout` | `"single_line"` | `new_line` moves an `option` value to an indented line when the statement does not fit. A text-format message literal never moves; it breaks in place. |
| `blank_line_limit` | `1` | Longest run of blank lines kept between statements. `0` removes them all. |
| `ignore_directives` | `["profmt-ignore"]` | Comment bodies that print the following statement verbatim. |
Blank lines directly after an opening brace or before a closing brace are
always removed, and every file ends with exactly one newline.
## Policy hooks
`ignore_directives` matches the body of a `//` comment placed directly above
a statement. With the default setting, this copies the next statement without
formatting it:
```proto
// profmt-ignore
message Kept { optional int32 a=1; }
```
The corresponding CLI flag is repeatable, and providing it replaces the
configured list:
```sh
profmt --check --ignore-directive profmt-ignore --ignore-directive clang-format-off .
```
Use `--no-ignore-directives` to clear the list.
Run `profmt --help` for all CLI overrides. Each enum option is available as a
flag taking the variant name with hyphens, for example
`--header-order package-first`.