home/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, or *a* for Alt, 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-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

*<c-o>*::
    disable automatic completion for this insert session

*<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-;>*::
    escape to normal mode for a single command

== 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 selection end.

== 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).

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 underscore, and 'WORD'
is a sequence of non whitespace characters

*h*::
    select the character on the left of selection end

*j*::
    select the character below the selection end

*k*::
    select the character above the selection end

*l*::
    select the character on the right of selection end

*w*::
    select the word and following whitespaces on the right of selection end

*b*::
    select preceding whitespaces and the word on the left of selection end

*e*::
    select preceding whitespaces and the word on the right of selection end

*<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

*m*::
    select to matching character, see the `matching_pairs` option
    in <<options#,`:doc options`>>

*M*::
    extend selection to matching character

*x*::
    select line on which selection end lies (or next line when end lies
    on an end-of-line)

*X*::
    similar to *x*, except the current selection is extended

*<a-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)

*%*::
    select whole buffer

*<a-h>*::
    select to line begin

*<a-l>*::
    select to line end

*/*::
    search (select next match)

*<a-/>*::
    search (select previous match)

*?*::
    search (extend to next match)

*<a-?>*::
    search (extend to previous match)

*n*::
    select next match

*N*::
    add a new selection with next match

*<a-n>*::
    select previous match

*<a-N>*::
    add a new selection with previous match

*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

*'*::
    rotate selections (the main selection becomes the next one)

*<a-'>*::
    rotate selections backwards

*;*::
    reduce selections to their cursor

*<a-;>*::
    flip the selections direction

*<a-:>*::
    ensure selections are in forward direction (cursor after anchor)

*<a-.>*::
    repeat last object or *f*/*t* selection command

== Changes

*i*::
    enter insert mode before current selection

*a*::
    enter insert mode after current selection

*d*::
    yank and delete current selection

*c*::
    yank and delete current selection and enter insert mode

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

*<a-d>*::
    delete current selection (not yanking)

*<a-c>*::
    delete current selection and enter insert mode (not yanking)

*I*::
    enter insert mode at current selection begin line start

*A*::
    enter insert mode at current selection end line end

*o*::
    enter insert mode in a new line (or in a given count of new lines) below
    current selection end

*O*::
    enter insert mode in a new line (or in a given count of new lines) above
    current selection begin

*<a-o>*::
    add an empty line below cursor

*<a-O>*::
    add an empty line above cursor

*y*::
    yank selections

*p*::
    paste after current selection end

*P*::
    paste before current selection begin

*<a-p>*::
    paste all after current selection end, and select each pasted string

*<a-P>*::
    paste all before current selection begin, and select each pasted string

*R*::
    replace current selection with yanked text

*<a-R>*::
    replace current selection 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-m>*::
    merge contiguous selections together (works across lines as well)

*>*::
    indent selected lines

*<a\->>*::
    indent selected lines, including empty lines

*<*::
    deindent selected lines

*<a-<>*::
    deindent selected lines, do not remove incomplete indent (3 leading
    spaces when indent is 4)

*|*::
    pipe each selection through the given external filter program and
    replace the selection with its output. Shell expansions are available,
    (See <<expansions#shell-expansions,`:doc expansions shell-expansions`>>)

*<a-|>*::
    pipe each selection through the given external filter program and
    ignore its output. Shell expansions are available,
    (See <<expansions#shell-expansions,`:doc expansions shell-expansions`>>)

*!*::
    insert command output before selection. Shell expansions are available,
    (See <<expansions#shell-expansions,`:doc expansions shell-expansions`>>)

*<a-!>*::
    append command output after selection. Shell expansions are available,
    (See <<expansions#shell-expansions,`:doc expansions shell-expansions`>>)

*u*::
    undo last change

*<a-u>*::
    move backward in history

*U*::
    redo last change

*<a-U>*::
    move forward in history

*&*::
    align selection, align the cursor of selections by inserting spaces
    before the first character of the 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 current selections, uses the buffer tabstop
    option or the count parameter for tabstop

*<a-@>*::
    convert spaces to tabs in current selections, uses the buffer tabstop
    option or the count parameter for tabstop

*<a-">*::
    rotate selections content, if specified, the count groups selections,
    so the following command

----------
    3<a-">
----------

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

== Goto commands

*g*, *G*::
    When a count is specified, *G* only extends the current 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 <<registers#,`:doc registers`>>)

*Z*::
    save the current selections to the register

*z*::
    restore the selections from the register

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

    *a*:::
        append the selections

    *u*:::
        keep a union of the selections

    *i*:::
        keep an intersection of the 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

*<esc>*::
    end macro recording

== Searching

Searches use the */* register by default (See <<registers#,`:doc registers`>>)

***::
    set the search pattern to the current selection (automatically
    detects word boundaries)

*<a-***>*::
    set the search pattern to the current selection (verbatim, no smart
    detection)

== 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>*::
    save current selections

== Multiple selections

*s*::
    create a selection

*S*::
    split the current selection

*<a-s>*::
    split the current selections on line boundaries

*<a-S>*::
    select first and last characters of each selections

*C*::
    copy the current selection to the next line

*<a-C>*::
    copy the current selection to the previous line

*<space>*::
    clear a multiple selection

*<a-space>*::
    clear the current selection

*<a-k>*::
    keep the 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`>>)

== Object Selection

For nestable objects, a count can be used in order to specify which surrounding
level to select.

*<a-a>*::
    selects the whole object

*<a-i>*::
    selects the inner object, that is the object excluding its surrounder.
    For example, for a quoted string, this will not select the quote, and
    for a word this will not select trailing spaces.

*[*::
    selects to object start

*]*::
    selects to object end

*{*::
    extends selections to object start

*}*::
    extends selections to object end

After these keys, 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

*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

== Prompt commands

When pressing `:` in normal mode, Kakoune will open a prompt to enter a command.
The following keys are recognized by this mode to help edition.
(See <<commands#,`:doc commands`>>)

*<ret>*::
    validate prompt

*<esc>*::
    abandon without

*<left>*, *<a-h>*::
    move cursor to previous character

*<right>*, *<a-l>*::
    move cursor to previous character

*<home>*::
    move cursor to first character

*<end>*::
    move cursor past the last character

*<backspace>*, *<a-x>*::
    erase character before cursor

*<del>*, *<a-d>*::
    erase character under cursor

*<c-w>*::
    advance to next word begin

*<c-a-w>*::
    advance to next WORD begin

*<c-b>*::
    go back to previous word begin

*<c-a-b>*::
    go back to previous WORD begin

*<c-e>*::
    advance to next word end

*<c-a-e>*::
    advance to next word end

*<up>*, *<c-p>*::
    select previous entry in history

*<down>*, *<c-n>*::
    select next entry in history

*<tab>*::
    select next completion candidate

*<backtab>*::
    select previous completion candidate

*<c-r>*::
    insert then content of the register given by next key

*<c-v>*::
    insert next keystroke without interpreting it

*<c-o>*::
    disable auto completion for this prompt