Usage
(Currently not fully documented, see the keymappings list for more.)
See tutor (accessible via hx --tutor
or :tutor
) for a vimtutor-like introduction.
Registers
Vim-like registers can be used to yank and store text to be pasted later. Usage is similar, with "
being used to select a register:
"ay
- Yank the current selection to registera
."op
- Paste the text in registero
after the selection.
If there is a selected register 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 registerh
and then change it (delete and enter insert mode)."md
- Store the selection in registerm
and delete it.
Special Registers
Register character | Contains |
---|---|
/ | Last search |
: | Last executed command |
" | Last yanked text |
_ | Black hole |
There is no special register for copying to system clipboard, instead special commands and keybindings are provided. See the keymap for the specifics. The black hole register works as a no-op register, meaning no data will be written to / read from it.
Surround
Functionality similar to vim-surround is built into helix. The keymappings have been inspired from vim-sandwich:
ms
- Add surround charactersmr
- Replace surround charactersmd
- Delete surround characters
ms
acts on a selection, so select the text first and use ms<char>
. mr
and md
work
on the closest pairs found and selections are not required; use counts to act in outer pairs.
It can also act on multiple selections (yay!). For example, to change every occurrence of (use)
to [use]
:
%
to select the whole files
to split the selections on a search term- Input
use
and hit Enter mr([
to replace the parens with square brackets
Multiple characters are currently not supported, but planned.
Syntax-tree Motions
A-p
, A-o
, A-i
, and A-n
(or Alt
and arrow keys) move the primary
selection according to the selection's place in the syntax tree. Let's walk
through an example to get familiar with them. Many languages have a syntax like
so 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" │
└──────────┘ └──────────┘ └──────────┘
Say we have a selection that wraps arg1
. The selection is on the arg1
leaf
in the tree above.
func([arg1], arg2, arg3)
Using A-n
would select the next sibling in the syntax tree: arg2
.
func(arg1, [arg2], arg3)
While A-o
would expand the selection to the parent node. In the tree above we
can see that we would select 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. If we have a selection on arg1
, A-p
would bring us
to the previous child node. Since arg1
doesn't have a sibling to its left,
though, we climb the syntax tree and then take the previous selection. So A-p
will move the selection over to the "func" identifier
.
[func](arg1, arg2, arg3)
Textobjects
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 | Closest surround pair |
f | Function |
c | Class |
a | Argument/parameter |
o | Comment |
t | Test |
NOTE:
f
,c
, 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!
Tree-sitter Textobject Based Navigation
Navigating between functions, classes, parameters, etc is made
possible by leveraging tree-sitter and textobjects queries. For
example to move to the next function use ]f
, to move to previous
class use [c
, and so on.
See the unimpaired section of the keybind documentation for the full reference.
NOTE: This feature is dependent on tree-sitter based textobjects and therefore requires the corresponding query file to work properly.