User guide / Key bindings

Insert and Replace modes

Development reference · View source

Replace mode details:

• Entering collapses every selection to its active head.
• A caret at line end appends instead of overwriting.
• A newline inserts a line break rather than consuming the existing one.
• Unicode characters are replaced one for one, and CRLF stays one line ending.
• The whole Replace session is one undo checkpoint.
• Lowercase r is the single-character Normal-mode command and never enters Replace mode.

The keys shared by Insert and Replace modes:

In Insert mode, Alt-Backspace (Option-Backspace on macOS) removes all leading indentation before the caret in one press and stops at the start of the current line. Pressing it at column zero can delete across the preceding line break.

Deleting in Replace mode. Backspace or Shift-Backspace retraces the current overwrite run: overwritten characters come back, and characters appended past line end are removed. Alt-Backspace and Ctrl-u restore by word and to the start of the line.

Shift-Backspace in Insert mode deletes like Backspace, so Shift can stay held while correcting uppercase text.

Leaving. Escape or Ctrl-\ returns to Normal mode.

Commenting lines

Ctrl-c comments or uncomments every line the selection touches, using the buffer language’s line comment.

• The marker goes at the least-indented line, so nested lines keep their relative indentation.
• Blank lines are left alone both ways.
• Uncommenting removes the marker and at most one space after it: // x and //x both become x.
• A partly commented block becomes fully commented first, so a second press always undoes the first.
• In an extensionless script whose language comes only from its shebang, the shebang line is left unchanged, so the buffer keeps its language.
• In Insert mode Ctrl-c acts on each caret’s own line. Entering Insert mode collapses selections to carets, so choose a block in Normal or Select mode.

Auto-closing pairs

editor.auto_close is off by default. Turn it on in Space o o to pair typed (), [], {}, single quotes, and double quotes in Insert mode.

• The caret stays inside the pair. Typing the closer already under the caret moves past it.
• Backspace between an empty pair removes both characters, including pairs already in the document.
• Openers pair before whitespace, closing punctuation, or the end of the buffer.
• Quotes also need a non-word character before them. Escaped quotes and apostrophes inside words stay literal.
• It is a local text heuristic, independent of language syntax.
• Paste, Replace mode, prompts, and terminal input stay literal.
• Each caret is handled independently.

New lines and indentation

In Insert mode, Tab normally advances to the next visual tab stop. Backspace within leading spaces and tabs removes indentation to the previous stop. With width 4, Backspace moves columns 8 → 4, 6 → 4, and 4 → 0 (columns counted from zero). Mixed spaces and tabs use their displayed columns. After text, Backspace deletes one character; at the start of a line it keeps ordinary newline joining. Selections, paired characters, and Markdown list handling retain their existing behavior. Replace-mode Backspace still restores overwritten text.

editor.tab_width and editor.indent supply defaults. Language and file-pattern exceptions apply to individual buffers, including their display, wrapping, mouse positioning and language-server formatting options. See Indentation overrides .

o and O place the caret after the indentation, and work the same with smart newline off.

Markdown lists continue on Enter while editor.smart_newline is on (the default):

• bullets keep their marker, numbered and lettered items advance, and task items start unchecked;
• Enter on an empty item ends the list;
• Tab on a whitespace-only line immediately below a list aligns with the item’s content, including through continuation lines and nested lists. It fills the remaining distance with spaces even when the configured indent style is tabs. Once aligned, further Tab presses use the configured style and tab stops. This also applies to scratchpads with editor.scratch_markdown enabled; Shift-Tab keeps its ordinary other-style behavior;
• Backspace right after a marker turns it into a continuation indent, whether or not text follows; another Backspace removes that alignment in one press;
• Enter and Backspace renumber the following numbered or lettered items that were in sequence, skipping nested items, continuation lines, and blank lines. A list numbered 1. throughout, or one with a gap, keeps its numbers from that point on;
• a single I. or V. advances as a letter unless the previous sibling establishes Roman numbering.

In other file types, smart newline keeps the alignment under a list item’s content. With editor.smart_newline: false, Enter keeps only the row’s leading indentation and Tab uses ordinary indentation stops. List alignment looks back through at most 256 rows of at most 4096 characters each, stopping at a blank line or unrelated text; beyond those bounds Tab uses ordinary indentation.

Unsupported, malformed, oversized, and unterminated-final-line cases keep the exact prefix and never block the newline.