path: root/doc/pages/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 <<mapping#,`: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
<<hooks#,`: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 <<options#builtin-options,`: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 <<mapping#default-mappings,`:doc mapping default-mappings`>>)

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

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

*l*::
    select the character on the right of the end of each selection
    `<right>` maps to this by default.
    (See <<mapping#default-mappings,`: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 <<options#,`:doc options`>>

*M*::
    extend the current selection to the next sequence enclosed by matching
    character, see the `matching_pairs` option in <<options#,`:doc options`>>

*<a-m>*::
    select to the previous sequence enclosed by matching characters, see the
    `matching_pairs` option in <<options#,`:doc options`>>

*<a-M>*::
    extend the current selection to the previous sequence enclosed by matching
    characters, see the `matching_pairs` option in <<options#,`: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 <<mapping#default-mappings,`:doc mapping default-mappings`>>)

*<a-l>*::
    select to line end
    `<end>` maps to this by default.
    (See <<mapping#default-mappings,`: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 <<registers#,`: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 <<expansions#shell-expansions,`:doc expansions shell-expansions`>>)
The default command comes from the *|* register (See <<registers#,`: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 <<registers#,`: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

    *<*:::
        scroll to put the main cursor on the leftmost column of the window

    *>*:::
        scroll to put the main cursor on the rightmost column 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 <<registers#,`: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 <<registers#,`:doc registers`>>)

*Q*::
    start or end macro recording

*q*::
    play a recorded macro

== 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 <<registers#,`: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 <<expansions#shell-expansions,`: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 <<expansions#,`: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 <<registers#,`: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 <<commands#,`: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 the 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. if it has the Control modifier,
    it will quote the inserted value(s).

*<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 <<expansions#,`: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 <<modes#user-mode,`: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.