keys.asciidoc

Keys

Key Syntax

Usual keys are written using their ascii character, including capital keys. Non printable keys use an alternate name, written between < and >, such as <esc> or <del>. Modified keys are written between < and > as well, with the modifier specified as either c for Control, a for Alt, or s for Shift, followed by a - and the key (either its name or ascii character), for example <c-x>, <a-space>, <c-a-w>.

In order to bind some keys to arbitrary ones, refer to :doc mapping

Insert mode

<esc>

leave insert mode

<backspace>

delete characters before cursors

<del>

delete characters under cursors

<left>, <right>, <up>, <down>

move the cursors in given direction

<home>

move cursors to line begin

<end>

move cursors to end of line

<c-r>

insert contents of the register given by next key

<c-v>

insert next keystroke directly into the buffer, without interpreting it

<c-u>

commit changes up to now as a single undo group

<a-;>, <a-semicolon>

escape to normal mode for a single command

Insert mode completion

The completers option controls automatic completion, which kicks in when the value specified in the idle_timeout option is reached.

<c-o>

toggle automatic completion

<c-n>

select next completion candidate

<c-p>

select previous completion candidate

<c-x>

explicit insert completion query, followed by:

f

explicit file completion

w

explicit word completion (current buffer)

W

explicit word completion (all buffers)

l

explicit line completion (current buffer)

L

explicit line completion (all buffers)

Using Counts

In normal mode, commands can be prefixed with a numeric count, which can control the command behaviour.

For example, 3W selects 3 consecutive words and 3w select the third word on the right of the end of each selection.

Disabling Hooks

Any normal mode command can be prefixed with \ which will disable hook execution for the duration for the command (including the duration of modes the command could move to, so \i will disable hooks for the whole insert session) (see :doc hooks).

As autoindentation is implemented in terms of hooks, this can be used to disable it when pasting text.

Movement

'word' is a sequence of alphanumeric characters, or those in the extra_word_chars option (see :doc options builtin-options). 'WORD' is a sequence of non whitespace characters. Generally, a movement on its own will move each selection to cover the text moved over, while holding down the Shift modifier and moving will extend each selection instead.

h

select the character on the left of the end of each selection <left> maps to this by default. (See :doc mapping default-mappings)

j

select the character below the end of each selection <down> maps to this by default. (See :doc mapping default-mappings)

k

select the character above the end of each selection <up> maps to this by default. (See :doc mapping default-mappings)

l

select the character on the right of the end of each selection <right> maps to this by default. (See :doc mapping default-mappings)

w

select the word and following whitespaces on the right of the end of each selection

b

select preceding whitespaces and the word on the left of the end of each selection

e

select preceding whitespaces and the word on the right of the end of each selection

<a-[wbe]>

same as [wbe] but select WORD instead of word

f

select to the next occurrence of given character

t

select until the next occurrence of given character

<a-[ft]>

same as [ft] but in the other direction

<a-.>

repeat last object or f/t selection command

m

select to the next sequence enclosed by matching characters, see the matching_pairs option in :doc options

M

extend the current selection to the next sequence enclosed by matching character, see the matching_pairs option in :doc options

<a-m>

select to the previous sequence enclosed by matching characters, see the matching_pairs option in :doc options

<a-M>

extend the current selection to the previous sequence enclosed by matching characters, see the matching_pairs option in :doc options

x

expand selections to contain full lines (including end-of-lines)

<a-x>

trim selections to only contain full lines (not including last end-of-line)

%, <percent>

select whole buffer

<a-h>

select to line begin <home> maps to this by default. (See :doc mapping default-mappings)

<a-l>

select to line end <end> maps to this by default. (See :doc mapping default-mappings)

<pageup>, <c-b>

scroll one page up

<pagedown>, <c-f>

scroll one page down

<c-u>

scroll half a page up

<c-d>

scroll half a page down

;, <semicolon>

reduce selections to their cursor

<a-;>, <a-semicolon>

flip the direction of each selection

<a-:>

ensure selections are in forward direction (cursor after anchor)

Changes

Yanking (copying) and pasting use the " register by default (See :doc registers)

i

enter insert mode before selections

a

enter insert mode after selections

d

yank and delete selections

c

yank and delete selections and enter insert mode

.

repeat last insert mode change (i, a, or c, including the inserted text)

<a-d>

delete selections (not yanking)

<a-c>

delete selections and enter insert mode (not yanking)

I

enter insert mode at the beginning of the lines containing the start of each selection

A

enter insert mode at the end of the lines containing the end of each selection

o

enter insert mode in a new line (or in a given count of new lines) below the end of each selection

O

enter insert mode in a new line (or in a given count of new lines) above the beginning of each selection

<a-o>

add an empty line below cursor

<a-O>

add an empty line above cursor

y

yank selections

p

paste after the end of each selection

P

paste before the beginning of each selection

<a-p>

paste all after the end of each selection, and select each pasted string

<a-P>

paste all before the start of each selection, and select each pasted string

R

replace selections with yanked text

<a-R>

replace selections with every yanked text

r

replace each character with the next entered one

<a-j>

join selected lines

<a-J>

join selected lines and select spaces inserted in place of line breaks

<a-_>

merge contiguous selections together (works across lines as well)

<+>, <plus>

duplicate each selection (generating overlapping selections)

<a-+>, <a-plus>

merge overlapping selections

>, <gt>

indent selected lines

<a-\>>, <a-gt>

indent selected lines, including empty lines

<, <lt>

unindent selected lines

<a-<>, <a-lt>

unindent selected lines, do not remove incomplete indent (3 leading spaces when indent is 4)

u

undo last change

U

redo last change

<c-j>

move forward in changes history

<c-k>

move backward in changes history

<a-u>

undo last selection change

<a-U>

redo last selection change

&

align selections, align the cursor of each selection by inserting spaces before the first character of each selection

<a-&>

copy indent, copy the indentation of the main selection (or the count one if a count is given) to all other ones

`

to lower case

~

to upper case

<a-`>

swap case

@

convert tabs to spaces in each selection, uses the buffer tabstop option or the count parameter for tabstop

<a-@>

convert spaces to tabs in each selection, uses the buffer tabstop option or the count parameter for tabstop

_

unselect whitespace surrounding each selection, drop those that only contain whitespace

<a-)>

rotate selections content, if specified, the count groups selections, so the following command

    3<a-)>

rotates (1, 2, 3) and (3, 4, 6) independently

<a-(>

rotate selections content backward

Changes through external programs

Shell expansions are available, (See :doc expansions shell-expansions) The default command comes from the | register (See :doc registers)

|

pipe each selection through the given external filter program and replace the selection with its output.

<a-|>

pipe each selection through the given external filter program and ignore its output.

!

insert and select command output before each selection.

<a-!>

append and select command output after each selection.

Searching

Searches use the / register by default (See :doc registers)

/

select next match after each selection

<a-/>

select previous match before each selection

?

extend to next match after each selection

<a-?>

extend to previous match before each selection

n

select next match after the main selection

N

add a new selection with next match after the main selection

<a-n>

select previous match before the main selection

<a-N>

add a new selection with previous match before the main selection

*

set the search pattern to the main selection (automatically detects word boundaries)

<a-*>

set the search pattern to the main selection (verbatim, no smart detection)

Goto commands

g, G

When a count is specified, G only extends the selection to the given line, g sends the anchor to the given line and a menu is then displayed which waits for one of the following additional keys:

h

go to line begin

l

go to line end

i

go to non blank line start

g, k

go to the first line

j

go to the last line

e

go to last char of last line

t

go to the first displayed line

c

go to the middle displayed line

b

go to the last displayed line

a

go to the previous (alternate) buffer

f

open the file whose name is selected

.

go to last buffer modification position

View commands

v, V

V enters lock view mode (which will be left when the <esc> is hit), and v modifies the current view; a menu is then displayed which waits for one of the following additional keys:

v, c

center the main selection in the window (vertically)

m

center the main selection in the window (horizontally)

t

scroll to put the main selection on the top line of the window

b

scroll to put the main selection on the bottom line of the window

h

scroll the window count columns left

j

scroll the window count line downward

k

scroll the window count line upward

l

scroll the window count columns right

Marks

Current selections position can be saved in a register and restored later on. Marks use the ^ register by default (See :doc registers)

Z

save selections to the register

z

restore selections from the register

<a-z>, <a-Z>

<a-z> combines selections from the register with the current ones, whereas <a-Z> combines current selections with the ones in the register; a menu is then displayed which waits for one of the following additional keys:

a

append selections

u

keep a union of selections

i

keep an intersection of selections

<

select the selection with the leftmost cursor for each pair

>

select the selection with the rightmost cursor for each pair

+

select the longest selection

-

select the shortest selection

Macros

Macros use the @ register by default (See :doc registers)

Q

start or end macro recording

q

play a recorded macro

<esc>

end macro recording

Jump list

Some commands, like the goto commands, buffer switch or search commands, push the previous selections to the client’s jump list. It is possible to skim through the jump list using:

<c-i>

jump forward

<c-o>

jump backward

<c-s>

create a jump step, but also save the current selection to have it be restored when the step is subsequently cycled through

Multiple selections

s, S, <a-k> and <a-K> use the / register by default (See :doc registers)

s

create a selection for each match of the given regex (selects the count capture if it is given)

S

split selections with the given regex (selects the count capture if it is given)

<a-s>

split selections on line boundaries

<a-S>

select first and last characters of each selection

C

duplicate selections on the lines that follow them

<a-C>

duplicate selections on the lines that precede them

,

clear selections to only keep the main one

<a-,>

clear the main selection

<a-k>

keep selections that match the given regex

<a-K>

clear selections that match the given regex

$

pipe each selection to the given shell command and keep the ones for which the shell returned 0. Shell expansions are available, (See :doc expansions shell-expansions)

)

rotate main selection (the main selection becomes the next one)

(

rotate main selection backward (the main selection becomes the previous one)

Object Selection

For nestable objects, a count can be used in order to specify which surrounding level to select. Object selections are repeatable using <a-.>.

Whole object

A 'whole object' is an object including its surrounding characters. For example, for a quoted string this will select the quotes, and for a word this will select trailing spaces.

<a-a>

select the whole object

[

select to the whole object start

]

select to the whole object end

{

extend selections to the whole object start

}

extend selections to the whole object end

Inner object

An 'inner object' is an object excluding its surrounding characters. For example, for a quoted string this will not select the quotes, and for a word this will not select trailing spaces.

<a-i>

select the inner object

<a-[>

select to the inner object start

<a-]>

select to the inner object end

<a-{>

extend selections to the inner object start

<a-}>

extend selections to the inner object end

Objects types

After the keys described above, a second key needs to be entered in order to specify the wanted object:

b, (, )

select the enclosing parenthesis

B, {, }

select the enclosing {} block

r, [, ]

select the enclosing [] block

a, <, >

select the enclosing <> block

Q, "

select the enclosing double quoted string

q, '

select the enclosing single quoted string

g, `

select the enclosing grave quoted string

w

select the whole word

<a-w>

select the whole WORD

s

select the sentence

p

select the paragraph

␣

select the whitespaces

i

select the current indentation block

n

select the number

u

select the argument

c

select user defined object, will prompt for open and close text

<a-;>, <a-semicolon>

run a command with additional expansions describing the selection context (See :doc expansions)

If a punctuation character is entered, it will act as the delimiter. For instance, if the cursor is on the o of /home/bar, typing <a-a>/ will select /home/.

Prompt commands

When pressing : in normal mode, Kakoune will open a prompt to enter a command. The executed command line is stored in the : register (See :doc registers).

During editing, a transient clipboard is available, its content is empty at the start of prompt edition, and is not preserved afterwards.

The following keys are recognized by this mode to help with editing (See :doc commands).

<ret>

validate prompt

<esc>

abandon without validating prompt

<left>, <c-b>

move cursor to previous character

<right>, <c-f>

move cursor to next character

<home>, <c-a>

move cursor to first character

<end>, <c-e>

move cursor past the last character

<backspace>, <c-h>

erase character before cursor

<del>, <c-d>

erase character under cursor

<a-f>

advance to next word begin

<a-F>

advance to next WORD begin

<a-b>

go back to previous word begin

<a-B>

go back to previous WORD begin

<a-e>

advance to next word end

<a-E>

advance to next WORD end

<c-w>

erase to previous word begin, save erased content to clipboard

<c-W>

erase to previous WORD begin, save erased content to clipboard

<a-d>

erase to next word begin, save erased content to clipboard

<a-D>

erase to next WORD begin, save erased content to clipboard

<c-k>

erase to end of line, save erased content to clipboard

<c-u>

erase to begin of line, save erased content to clipboard

<c-y>

insert clipboard content before cursor

<up>, <c-p>

select previous entry in history

<down>, <c-n>

select next entry in history

<tab>

select next completion candidate

<s-tab>

select previous completion candidate

<c-r>

insert then content of the register given by next key, if next key has the Alt modifier, it will insert all values in the register joined with spaces, else it will insert the main one

<c-v>

insert next keystroke without interpreting it

<c-x>

explicit completion query, followed by:

f

explicit file completion

w

explicit word completion (from current buffer)

<c-o>

toggle automatic completion

<a-!>

expand the typed expansions in currently entered text (See :doc expansions)

<a-;>, <a-semicolon>

escape to normal mode for a single command

User commands

<space>

enter default user mode to access custom commands (See :doc modes user-mode)

Cancelling operations

These keys are used to cancel long-running operations, either inside Kakoune or outside it. Because they are intended as a safety mechanism when something goes wrong, these keys are handled very early on in Kakoune’s input processing, and therefore cannot be remapped in any mode.

<c-c>

Stop any external processes. If you ever see Kakoune display a message like "waiting for shell command to finish", this key will stop that command so you can regain control of Kakoune. Technically, this key causes Kakoune to send the SIGINT signal to its entire process group.

<c-g>

Cancel a long-running Kakoune operation, such as a regex search on a very large file. This also clears Kakoune’s input buffer, so any commands that were waiting for the long-running operation to complete will also be cancelled.