User guide / Configuration

Editing the file and reloading

Development reference · View source

After editing the file by hand, run :config-reload. It re-reads the file this editor loaded, including one given with --config.

• Nothing is watched or polled. The reload happens when you run the command.
• It covers only the workspace you run it in. Run it again in another running session to update that one.

Failed reloads change nothing. Invalid YAML, an out-of-range value, and a deleted file are reported, and the running configuration stays exactly as it was.

• A file replaced atomically (written elsewhere, then renamed) is always read whole.
• A file rewritten in place can be caught half-written. That fails as invalid YAML; reload again once the write finishes.
• A path that never had a file is reported as missing, not as deleted. Create the file and reload to start using it mid-session.

What applies immediately: everything except the restart settings below. That includes the theme, notifications.history_limit, and the keys section. Key dispatch, help, and key hints are rebuilt together, with each running plugin’s keys laid back over them.

What keeps its startup value: editor.mouse, lsp.enable, mode, workspace.state, and workspace.state_anchor. The status line names them as needing a restart. The [config] page shows the file’s value as saved, while the editor keeps using the startup value.

Partial failures:

• A keys section that collides with a running plugin’s binding is refused on its own. The rest of the file still applies.
• A theme that cannot be built keeps the current theme on screen and says so.

Language servers are reconfigured, not restarted.

• A server whose command, args, and initialization_options are unchanged keeps its process, handshake, open documents, and diagnostics.
• A changed definition stops and starts again on the next request.
• A language removed from the file stops.
• A remembered launch failure is forgotten when its definition changes, so a corrected command is tried again.

Plugins are matched by id, so moving an entry within the file changes nothing.

• An unchanged entry keeps its running process.
• A changed entry restarts its plugin. A removed or disabled entry stops it.
• An added entry starts. One that was disabled or refused at startup can be fixed and started the same way.
• A plugin that is busy keeps running until its work is done. Busy means a running job, an activity lease, a helper process, outstanding cleanup, an unsaved remote document, an unanswered command, local filesystem work, or a prompt you are part-way through.
• While a plugin waits, :plugins shows the pending state and a notification says so. The saved entry applies by itself when the work is gone. :plugin-restart <id> applies it sooner, or :plugin-stop <id> for an entry the file no longer enables.