Using Helix
+ +-
+
- 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 registera.
+"op- Paste the text in registeroafter 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 registerhand then change it (delete and enter insert mode).
+"md- Store the selection in registermand 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]:
-
+
%to select the whole file
+sto split the selections on a search term
+- Input
useand hit Enter
+ 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 (vain Vim,<alt-a>in Kakoune)
+mi- Select inside the object (viin 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.