helix/book/src/usage.md

Using Helix

• Registers
  • User-defined registers
  • Special registers
• Surround
• Selecting and manipulating text with textobjects
• Navigating using tree-sitter textobjects
• Moving the selection with syntax-aware motions

For a full interactive introduction to Helix, refer to the tutor which can be accessed via the command hx --tutor or :tutor.

💡 Currently, not all functionality is fully documented, please refer to the key mappings list.

Registers

In Helix, registers are storage locations for text and other data, such as the result of a search. Registers can be used to cut, copy, and paste text, similar to the clipboard in other text editors. Usage is similar to Vim, with " being used to select a register.

User-defined registers

Helix allows you to create your own named registers for storing text, for example:

• "ay - Yank the current selection to register a.
• "op - Paste the text in register o after the selection.

If a register is selected before invoking a change or delete command, the selection will be stored in the register and the action will be carried out:

• "hc - Store the selection in register h and then change it (delete and enter insert mode).
• "md - Store the selection in register m and delete it.

Default registers

Commands that use registers, like yank (y), use a default register if none is specified. These registers are used as defaults:

Register character	Contains
/	Last search
:	Last executed command
"	Last yanked text
@	Last recorded macro

Special registers

Some registers have special behavior when read from and written to.

Register character	When read	When written
_	No values are returned	All values are discarded
#	Selection indices (first selection is 1, second is 2, etc.)	This register is not writable
.	Contents of the current selections	This register is not writable
%	Name of the current file	This register is not writable
*	Reads from the system clipboard	Joins and yanks to the system clipboard
+	Reads from the primary clipboard	Joins and yanks to the primary clipboard

When yanking multiple selections to the clipboard registers, the selections are joined with newlines. Pasting from these registers will paste multiple selections if the clipboard was last yanked to by the Helix session. Otherwise the clipboard contents are pasted as one selection.

Surround

Helix includes built-in functionality similar to vim-surround. The keymappings have been inspired from vim-sandwich:

Key Sequence	Action
ms<char> (after selecting text)	Add surround characters to selection
mr<char_to_replace><new_char>	Replace the closest surround characters
md<char_to_delete>	Delete the closest surround characters

You can use counts to act on outer pairs.

Surround can also act on multiple selections. For example, to change every occurrence of (use) to [use]:

1. % to select the whole file
2. s to split the selections on a search term
3. Input use and hit Enter
4. mr([ to replace the parentheses with square brackets

Multiple characters are currently not supported, but planned for future release.

Selecting and manipulating text with textobjects

In Helix, textobjects are a way to select, manipulate and operate on a piece of text in a structured way. They allow you to refer to blocks of text based on their structure or purpose, such as a word, sentence, paragraph, or even a function or block of code.

• ma - Select around the object (va in Vim, <alt-a> in Kakoune)
• mi - Select inside the object (vi in Vim, <alt-i> in Kakoune)

Key after mi or ma	Textobject selected
w	Word
W	WORD
p	Paragraph
(, [, ', etc.	Specified surround pairs
m	The closest surround pair
f	Function
t	Type (or Class)
a	Argument/parameter
c	Comment
T	Test
g	Change

💡 f, t, etc. need a tree-sitter grammar active for the current document and a special tree-sitter query file to work properly. Only some grammars currently have the query file implemented. Contributions are welcome!

Navigating using tree-sitter textobjects

Navigating between functions, classes, parameters, and other elements is possible using tree-sitter and textobject queries. For example to move to the next function use ]f, to move to previous type use [t, and so on.

For the full reference see the unimpaired section of the key bind documentation.

💡 This feature relies on tree-sitter textobjects and requires the corresponding query file to work properly.

Moving the selection with syntax-aware motions

Alt-p, Alt-o, Alt-i, and Alt-n (or Alt and arrow keys) allow you to move the selection according to its location in the syntax tree. For example, many languages have the following syntax for function calls:

func(arg1, arg2, arg3);

A function call might be parsed by tree-sitter into a tree like the following.

(call
  function: (identifier) ; func
  arguments:
    (arguments           ; (arg1, arg2, arg3)
      (identifier)       ; arg1
      (identifier)       ; arg2
      (identifier)))     ; arg3

Use :tree-sitter-subtree to view the syntax tree of the primary selection. In a more intuitive tree format:

            ┌────┐
            │call│
      ┌─────┴────┴─────┐
      │                │
┌─────▼────┐      ┌────▼────┐
│identifier│      │arguments│
│  "func"  │ ┌────┴───┬─────┴───┐
└──────────┘ │        │         │
             │        │         │
   ┌─────────▼┐  ┌────▼─────┐  ┌▼─────────┐
   │identifier│  │identifier│  │identifier│
   │  "arg1"  │  │  "arg2"  │  │  "arg3"  │
   └──────────┘  └──────────┘  └──────────┘

If you have a selection that wraps arg1 (see the tree above), and you use Alt-n, it will select the next sibling in the syntax tree: arg2.

// before
func([arg1], arg2, arg3)
// after
func(arg1, [arg2], arg3);

Similarly, Alt-o will expand the selection to the parent node, in this case, the arguments node.

func[(arg1, arg2, arg3)];

There is also some nuanced behavior that prevents you from getting stuck on a node with no sibling. When using Alt-p with a selection on arg1, the previous child node will be selected. In the event that arg1 does not have a previous sibling, the selection will move up the syntax tree and select the previous element. As a result, using Alt-p with a selection on arg1 will move the selection to the "func" identifier.