Helix Editor

Expansions allow you to insert dynamic values into commands using the % token. They follow the pattern %[<kind>]<open><contents><close>.

Supported Delimiters:

• ( ), [ ], { }, < >
• Single characters: ', ", or | (e.g., %{variable} is equivalent to %|variable|)

Expansion Kinds:

• Variables: No <kind> provided. Replaces the pattern with an editor value (e.g., %{cursor_line}).
• Shell (%sh{..}): Executes the contents in the configured shell. Shell expansions are evaluated recursively.
• Unicode (%u{..}): Converts hexadecimal codepoints to Unicode characters (e.g., %u{25CF} for ●).
• Register (%reg{..}): Inserts the content of a specific register (e.g., %reg{a}).

Note: To use a literal % character inside an expansion, double it (%%). Expansions are only evaluated when the Enter key is pressed.

[keys.normal]
# Example: Print git blame for the current line to the statusline
space.B = ":echo %sh{git blame -L %{cursor_line},+1 %{buffer_name}}"

Helix uses a workspace trust model to protect users from executing arbitrary code contained in potentially malicious projects (e.g., a freshly cloned repository or a checked-out PR).

Certain features are gated behind explicit per-workspace trust:

• Local workspace configuration: Loading .helix/config.toml or .helix/languages.toml.
• Git integration: Loading configuration from a repository's .git/config (specifically git filters that execute external programs).

By default, Helix operates in a restricted mode where:

• Language Servers (LSP) start automatically (using binaries from your $PATH, not from the workspace).
• Debug Adapters (DAP) are allowed to run once you launch them manually.
• Local configs and Git configs are not loaded until you grant trust.

Trust is remembered across sessions, similar to direnv. When you grant trust, Helix records a hash of every file under .helix/ to detect if the configuration changes later.

A jump is automatically created whenever you perform a "significant movement." While the list is non-exhaustive, the following actions will add a jump to the jumplist:

Buffer and File Navigation

• Switching buffers (via buffer picker, next/previous buffer, or last accessed/modified file).
• Creating a new file (:new FILE).
• Opening a file (:open FILE, :log-open, :config-open, :config-open-workspace, or :tutor).
• Navigating via pickers, global search, the file explorer, or goto_file (gf).

Large In-File Movements

• Regex operations: select_regex (s) and split_regex (S).
• Searching: search (/).
• Selection management: keep_selections (K) and remove_selections (<A-K>).
• File boundaries: goto_file_start (gg), goto_file_end, and goto_last_line (ge).
• Line jumps: :goto 123, :123, or 123G.
• Code navigation: goto_definition (gd), goto_declaration (gD), goto_type_definition (gy), and goto_reference (gr).

Other Actions

• Manual jump creation via Ctrl-s.
• Switching to a buffer when attempting to close a modified buffer.
• Jumping stack frames within the debugger.

The helix-core crate provides the fundamental, functional building blocks for the editor. Most operations are functional, meaning they return new copies of data rather than modifying it in place.

Key Concepts

• Rope: The primary data structure for representing buffers, powered by the ropey library. Ropes are efficient to clone and allow for easy state snapshots.
• Selection: Represents multiple selections in the document. A Selection consists of one or more Ranges. Each Range contains a moving head and an immovable anchor. A single cursor is a Selection with one Range where the head and anchor are at the same position.
• Transaction: Used to modify Ropes. A Transaction represents a single coherent change and can be inverted to support undo operations. Selections and marks can be mapped over a transaction to update their positions after the change is applied.
• Syntax: The interface for interacting with tree-sitter ASTs for syntax highlighting and other language-aware features.

// Main interface for generating text edits
Transaction::change
Transaction::change_by_selection

The view layer provides the logic for displaying documents in the UI. While currently tied to the terminal, it acts as an imperative layer built on top of core.

Key Abstractions

• Document: A comprehensive representation of an open file that ties together the Rope, Selection(s), Syntax, History, and the language server.
• View: Represents an open split in the UI. It manages the gutter, status line, diagnostics, and the inner code area. Note that multiple Views can display the same Document; in this case, the Document stores separate selections for each view. Use document.selection(view_id) to retrieve the correct selection for a specific view.
• Surface & Rect: A Surface is a buffer that widgets draw to. Rects define specific areas (x, y, width, height) within a Surface to limit where a Component can render (e.g., limiting a Markdown component to the bounds of a Popup).
• Component & Layer: Widgets are called Components. Multiple components are organized into Layers (a Vec<Component>). The Compositor manages these layers, rendering them in order so that newer components (like a file picker) appear on top of existing ones.
• Editor: The global state container. It holds all open documents, the tree of view splits, configuration, and the language server registry. Use the Editor to open or close files.