Correct wrong default values in the settings reference (#64196)

# Objective

Fixes #56544

The settings reference documents `format_on_save` as defaulting to `on`,
but `assets/settings/default.json` ships `"format_on_save": "off"`. The
reporter in #56544 hit exactly that: a fresh config, a C file, save, and
nothing happens.

The reason the documented default looks right to many people is that Zed
enables it per language for twelve languages (Astro, Dart, EEx, Elixir,
Elm, Go, GraphQL, HEEx, Kotlin, Rust, Starlark, Zig). Save formats a
Rust buffer and not a C one, and neither the reference nor the
reporter's mental model had anywhere to hang that difference.

Checking that one entry made me wonder how many others were stale, so I
compared every `Setting:`/`Default:` pair on the page against the
corresponding path in `default.json`. Six more were wrong.

## Solution

| Setting | Documented | Ships as |
| --- | --- | --- |
| `format_on_save` | `on` | `off` |
| `auto_indent` | `true`, "`boolean` values" | `syntax_aware`, a
three-way enum |
| `diagnostics_max_severity` | `null` | `all` |
| `terminal.cursor_shape` | `null` (defaults to block) | `block` |
| `terminal.alternate_scroll` | `off` | `on` |
| `edit_predictions.disabled_globs` | 7 globs | 10 globs |
| `git.gutter_debounce` | `null` | `0` |

Two of these needed more than a value swap:

`auto_indent` stopped being a boolean when it became `AutoIndentMode`
(`crates/settings_content/src/language.rs:411`), so the options list now
covers `syntax_aware`, `preserve_indent` and `none`, and the description
no longer reads as a yes/no toggle.

`format_on_save` gets a sentence naming the twelve languages, so the
difference between saving a Rust buffer and a C one has somewhere to
hang.

`diagnostics_max_severity` and `terminal.cursor_shape` were
self-contradicting rather than merely stale: each section's own prose
already described the real default while the `Default:` line said
`null`.

## Testing

`cd docs && npx prettier --check src/` passes, as required by
`docs/AGENTS.md`. The change is prose and adds no `{#action}` or `{#kb}`
references, so it does not depend on the action metadata that
`check_docs` generates. The `[\`languages\`](#languages)` link resolves
to the single `## Languages` heading on the same page.

Every value in the table above was read out of
`assets/settings/default.json` on `main`, and I confirmed `default.json`
is authoritative for each by following the resolved-settings path (the
`user_content.<x>.unwrap()` style accessors) rather than trusting the
file alone.

## Notes for review

Found while auditing, deliberately left out of this PR — happy to take
any of them in a follow-up, or here if you would rather:

- Two Rust doc comments carry the same wrong defaults and feed the
settings.json schema tooltips, so the in-editor hover still disagrees
with the site: `crates/settings_content/src/language.rs` says `///
Default: on` for `format_on_save`, and
`crates/settings_content/src/editor.rs` says `/// Default: warning` for
`diagnostics_max_severity` while also saying "Shows all diagnostics if
not specified". Fixing those is a source change rather than a docs one.
- `docs/src/diagnostics.md` and `docs/src/visual-customization.md` still
present `diagnostics_max_severity: null`, and the latter also shows
`cursor_shape: null` for the editor where `default.json` ships `bar`.
Same defect class, different pages and a different presentation
(defaults listings rather than a reference), so I kept this PR to the
reference page.
- The reference's `diagnostics_max_severity` options omit `off`, which
is a live variant (`DiagnosticSeverityContent` in
`crates/settings_content/src/project.rs`). That is a missing option
rather than a wrong default, so it is not in scope here.
- Neither the Format On Save nor the Autosave section mentions that
`"autosave": {"after_delay": {...}}` disables format on save outright
(`crates/workspace/src/pane.rs`), even though `default.json` carries
that warning as a comment.
- The twelve-language list is a maintenance cost: it has to be edited
whenever a language gains or loses a default. `default.json` sets
per-language defaults for `tab_size`, `soft_wrap`, `allow_rewrap`,
`hard_tabs` and others too, and none of them are called out anywhere. A
single general statement about per-language defaults overriding
top-level ones would cover all of them and never go stale. I kept the
explicit list because it is what actually answers #56544, but I will
happily swap it for the general version if you prefer.

## Self-Review Checklist:

- [x] I've reviewed my own diff for quality, security, and reliability
- [x] Unsafe blocks (if any) have justifying comments
- [x] The content adheres to Zed's UI standards
([UX/UI](https://github.com/zed-industries/zed/blob/main/CONTRIBUTING.md#uiux-checklist)
and
[icon](https://github.com/zed-industries/zed/blob/main/crates/icons/README.md)
guidelines)
- [x] Tests cover the new/changed behavior
- [x] Performance impact has been considered and is acceptable

Release Notes:

- N/A
This commit is contained in:
Rusty Raven authored and GitHub committed 2026-09-15 03:06:39 +00:00
1 parent 4d0d1f1835
commit 977458038b
1 file changed
+34 -10
+34 -10
View File
@@ -134,13 +134,35 @@ Non-negative `float` values
## Auto Indent
- Description: Whether indentation should be adjusted based on context while typing. This can be specified on a per-language basis.
- Description: Controls automatic indentation behavior when typing. This can be specified on a per-language basis.
- Setting: `auto_indent`
- Default: `true`
- Default: `syntax_aware`
**Options**
`boolean` values
1. `syntax_aware`, adjusts indentation based on syntax context, using Tree-sitter to analyze the code structure:
```json [settings]
{
"auto_indent": "syntax_aware"
}
```
2. `preserve_indent`, keeps the indentation of the current line when starting a new one, without adjusting for syntax:
```json [settings]
{
"auto_indent": "preserve_indent"
}
```
3. `none`, disables automatic indentation, so new lines start at column 0:
```json [settings]
{
"auto_indent": "none"
}
```
## Auto Indent On Paste
@@ -544,7 +566,7 @@ When enabled, this setting will automatically close tabs for files that have bee
- Description: Which level to use to filter out diagnostics displayed in the editor
- Setting: `diagnostics_max_severity`
- Default: `null`
- Default: `all`
**Options**
@@ -689,7 +711,7 @@ For the case of "open", regular selection behavior can be achieved by holding `a
- Description: A list of globs for which edit predictions should be disabled for. This list adds to a pre-existing, sensible default set of globs. Any additional ones you add are combined with them.
- Setting: `disabled_globs`
- Default: `["**/.env*", "**/*.pem", "**/*.key", "**/*.cert", "**/*.crt", "**/.dev.vars", "**/secrets.yml"]`
- Default: `["**/.env*", "**/*.pem", "**/*.key", "**/*.cert", "**/*.crt", "**/.dev.vars", "**/secrets.yml", "**/.zed/settings.json", "/**/zed/settings.json", "/**/zed/keymap.json"]`
**Options**
@@ -2065,7 +2087,9 @@ Non-negative `integer` values
- Description: Whether or not to perform a buffer format before saving.
- Setting: `format_on_save`
- Default: `on`
- Default: `off`
Zed ships `"format_on_save": "on"` as a per-language default for Astro, Dart, EEx, Elixir, Elm, Go, GraphQL, HEEx, Kotlin, Rust, Starlark, and Zig. Every other language uses the top-level default above. Use [`languages`](#languages) to configure individual languages differently.
**Options**
@@ -2526,7 +2550,7 @@ To interpret all `.c` files as C++, files called `MyLockFile` as TOML and files
- Description: Sets the debounce threshold (in milliseconds) after which changes are reflected in the git gutter.
- Setting: `gutter_debounce`
- Default: `null`
- Default: `0`
**Options**
@@ -4536,7 +4560,7 @@ List of `integer` column numbers
- Description: Set whether Alternate Scroll mode (DECSET code: `?1007`) is active by default. Alternate Scroll mode converts mouse scroll events into up / down key presses when in the alternate screen (e.g. when running applications like vim or less). The terminal can still set and unset this mode with ANSI escape codes.
- Setting: `alternate_scroll`
- Default: `off`
- Default: `on`
**Options**
@@ -4620,9 +4644,9 @@ List of `integer` column numbers
### Terminal: Cursor Shape
- Description: Controls the visual shape of the cursor in the terminal. When not explicitly set, it defaults to a block shape.
- Description: Controls the visual shape of the cursor in the terminal.
- Setting: `cursor_shape`
- Default: `null` (defaults to block)
- Default: `block`
**Options**