Kakoune

Table of Contents


  • Operation
    • two modes: normal and insertion
    • kakoune's grammar is object followed by verb: <count> <selection> <change>

Insert Mode

KeyAction
<backspace> / <del>delete characters before / under cursors
<home> / <end>move cursors to line begin
c-n / c-pselect next/previous completion candidate
c-xexplicit insert completion query, followed by
fexplicit file completion
wexplicit word completion
lexplicit line completion
c-odisable automatic completion for this insert session
c-r <R>insert contents of the register R given by next key
c-vinsert next keystroke directly into the buffer,
without interpreting it.
c-ucommit changes up to now as a single undo group.
a-;escape to normal mode for a single command

Selections

  • Kak works on selections: oriented/directed, inclusive range of characters.
  • Selections have two ends: an anchor and a cursor character.
  • Most commands move both of them, except when extending selection where the anchor character stays fixed and the cursor one moves around.
  • There is always at least one selection, and a selection is always at least one character (in which case the anchor and cursor of the selections are on the same character).
  • Most selection commands also support counts, which are entered before the command itself.

Goto

  • Commands beginning with g are used to goto certain position and or buffer:
  gh       gl        go to line begin/end
  Gh       Gl        select to line begin/end
  <a-h>    <a-l>     select to line begin/end
  gi                 go to line begin (non blank)
  gg, gk / gj        go to the first/last line
  ge                 go to last char of last line
  gt / gc / gb       go to the first / middle / last displayed line
  ga                 go to the previous (alternate) buffer
  gf                 open the file whose name is selected
  g.                 go to last buffer modification position
  <N>g               go to line N

If a count is given prior to hitting g, g will jump to the given line. Using G will extend the selection rather than jump.

MOVEMENT


  A word is a sequence of alphanumeric characters or underscore,
  A WORD is a sequence of non whitespace characters.

  For most selection commands, using shift permits extending current selection
  instead of replacing it.

  h / j / k / l      select the character on the left/below/above/on the right of selection end
  w                  select [word + following whitespaces] [right] of selection end
  b                  select [preceding whitespaces + word] [left]  of selection end
  e                  select [preceding whitespaces + word] [right] of selection end
  <a-[wbe]>          same as [wbe] but select WORD instead of word
  f / t <C>          select to/until the next occurence of given character C
  <a-[ft]> <C>       same as [ft] but in the other direction
  m / M <C>          select / extend selection to matching character C
  x / X              select / extend selection to line on which selection end lies
                     (or next line when end lies on an end-of-line)
  <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
  pageup   pagedown  scroll up / 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.
     /     <a-/>     search (select next/previous match)
     ?     <a-?>     search (extend to next/previous match)
     n        N      [select / add a new selection to] next match
  <a-n>    <a-N>     [select / add a new selection to] previous match

MULTI SELECTION

  One way to get a multiselection is via the s key.

  A multiselection can also be obtained with S, which splits the current
  selection according to the regex entered.
  To split a comma separated list, use S then ', *'

  s and S share the search pattern with /, and hence entering an empty pattern
  uses the last one.

  As a convenience, <a-s> allows you to split the current selections on line
  boundaries.

  To clear multiple selections, use space.
  To keep only the nth selection use n followed by space, in order to remove a
  selection, use <a-space>.

  <a-k> allows you to enter a regex and keep only the selections that contains
  a match for this regex.
  Using <a-K> you can keep the selections not containing a match.

  C copies the current selection to the next line (or lines if a count is given)
  <a-C> does the same to previous lines.

  $ allows you to enter a shell command and pipe each selection to it.
  Selections whose shell command returns 0 will be kept, other will be dropped.

  s
  <a-s>         split current selection on line boundaries
  S<re>         split current selection according to regexp <re>
  S,<space>*    split a comma-separated list
  <space>       clear multiple selections
  <N><space>    keep only <N>th selection
  <N><a-space>  remove <N>th selection
  <a-k>         enter a regex and keep only the match
  <a-K>         enter a regex and keep selections not containing the match
  <C> <a-C>     copy the selection to the next/previos line
                (lines if count is given)
  $             enter shell command and pipe each selection to it
                selections whose command return 0 are kept

OBJECT SELECTION


  Some keys allow you to select a text object:

  <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 this key, you need to enter a second key in order to specify which
  object you want.

  b, ( or )   select the enclosing parenthesis
  B, { or }   select the enclosing {} block
  r, [ or ]   select the enclosing [] block
  a, < or >   select the enclosing <> block
  " or Q      select the enclosing double quoted string
  ' or q      select the enclosing single quoted string
  ` or 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
  :           select user defined object, will prompt for open and close text.

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

CHANGES

  i a       enter insert mode before/after current selection
  I A       enter insert mode at current selection begin line start/end
  o O       enter insert mode in one (or given count) new lines below/above
            current selection end/begin
  y         yank selections
  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)
  p P       paste after/before current selection end/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
  r <C>     replace each character with the next entered one C
  <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)

  <gt> (>)  indent selected lines
  <a-gt>    indent selected lines, including empty lines

  <lt> (<)  deindent selected lines
  <a-lt>    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 it’s output.
  <a-|>     pipe each selection through the given external filter program and
            ignore its output

  !         insert command output before selection
  a-!       append command output after selection

  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 3<a-"> rotate (1, 2, 3) and (3, 4, 6) independently.

VIEW


  Some commands, all beginning with v permit to manipulate the current view.

  vv or vc  center the main selection in the window
  vt  scroll to put the main selection on the top line of the window
  vb  scroll to put the main selection on the bottom line of the window
  vh  scroll the window count columns left
  vj  scroll the window count line downward
  vk  scroll the window count line upward
  vl  scroll the window count columns right

  Using V will lock view mode until <esc> is hit

MARKS


  Current selections position can be saved in a register and restored later on.
  By default, marks use the '^' register, but using the register can be set
  using "<reg> prefix.

  Z will save the current selections to the register. <a-Z> will append the
  current selections to the register. z will restore the selections from the
  register. <a-z> will add the selections from the register to the existing ones.

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
  forward or backward in the jump list using:

  <c-i>  Jump forward
  <c-o>  Jump backward
  <c-s>  save current selections

COMMANDS

  When pressing : in normal mode, Kakoune will open a prompt to enter a command.
  Commands are used for non editing tasks, such as opening a buffer, writing the
  current one, quitting, etc.

  A few keys are recognized by prompt mode to help edit a command:

  <ret>                 validate prompt
  <esc>                 abandon without
  <left> or <a-h>       move cursor to previous character
  <right> or <a-l>      move cursor to previous character
  <home>                move cursor to first character
  <end>                 move cursor past the last character
  <backspace> or <a-x>  erase character before cursor
  <del> or <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> or <c-p>         select previous entry in history
  <down> or <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

  Commands starting with horizontal whitespace (e.g. a space) will not be saved
  in the command history.

  Some commands take an exclamation mark (!), which can be used to force the
  execution of the command (i.e. to quit a modified buffer, the command q! has
  to be used).

  cd [<directory>]                          change the current directory to
                                            <directory>, or the home directory
                                            if unspecified
  doc <topic>                               display documentation about a topic.
                                            The completion list displays the
                                            available topics.
  e[dit][!] <filename> [<line> [<column>]]  open buffer on file, go to given
                                            line and column. If file is already
                                            opened, just switch to this file.
                                            Use edit! to force reloading.
  w[rite][!] [<filename>]                   write buffer to <filename> or use
                                            its name if filename is not given.
                                            If the file is write-protected, its
                                            permissions are temporarily changed
                                            to allow saving the buffer and
                                            restored afterwards when the write!
                                            command is used.
  w[rite]a[ll]                              write all buffers that are
                                            associated to a file.
  q[uit][!]                                 exit Kakoune, use quit! to force
                                            quitting even if there is some
                                            unsaved buffers remaining.
  kill[!]                                   terminate the current session, all
                                            the clients as well as the server,
                                            use kill! to ignore unsaved buffers
  w[a]q[!]                                  write the current buffer (or all
                                            buffers when waq is used) and quit
  b[uffer] <name>                           switch to buffer <name>
  b[uffer]n[ext]                            switch to the next buffer
  b[uffer]p[rev]                            switch to the previous buffer
  d[el]b[uf][!] [<name>]                    delete the buffer <name>
  source <filename>                         execute commands in <filename>
  colorscheme <name>                        load named colorscheme.
  rename-client <name>                      set current client name
  rename-buffer <name>                      set current buffer name
  rename-session <name>                     set current session name
  echo [options] <text>                     show <text> in status line, with the
                                            following options:
      -color <face>                         print the given text with <face>,
                                            most commonly Error or Information
      -markup                               expand the markup strings in <text>
      -debug                                print the given text to the
                                            *debug* buffer
  nop                                       does nothing, but as with every
                                            other commands, arguments may be
                                            evaluated. So nop can be used for
                                            example to execute a shell command
                                            while being sure that it’s output
                                            will not be interpreted by kak.
                                            :%sh{ echo echo tchou } will echo
                                            tchou in Kakoune, whereas
                                            :nop %sh{ echo echo tchou } will
                                            not, but both will execute the shell
                                            command.

  Multiple commands can be separated either by new lines or by semicolons, as
  such a semicolon must be escaped with \; to be considered as a literal
  semicolon argument.

STRINGS

  When entering a command, parameters are separated by whitespace (shell like),
  if you want to give parameters with spaces, you should quote them.

  'strings'   uninterpreted strings, you can use \' to escape the separator,
              every other char is itself.
  "strings"   expanded strings, % strings (see Expansions) contained are
              expended. Use \% to escape a % inside them, and \\ to escape a
              slash.
  %{strings}  these strings are very useful when entering commands

  the { and } delimiters are configurable: you can use any non alphanumeric
  character, e.g. %[string], %<string>, %(string), %~string~, %!string!.

  if the character following the % is one of {[(<,
  then the closing one is the matching }])> and the delimiters are not escapable
  but are nestable.

STRING EXPANSIONS

  A special kind of %{strings} can be used, with a type between % and the
  opening delimiter (which cannot be alphanumeric).
  These strings are expanded according to their type.

  For example %opt{autoinfo} is of type 'opt'.
  'opt' expansions are replaced by the value of the given option (here autoinfo).

  Supported types are:

    sh   shell expansion, similar to posix shell $(…​) construct
    reg  register expansion, will be replaced by the content of the given register
    opt  option expansion, will be replaced with the value of the given option
    val  value expansion, gives access to the environment variable available to
         the Shell expansion. The kak_ prefix is not used there
    arg  argument expansion, gives access to the arguments of the current
         command, the content can be a number, or @ for all arguments

SHELL EXPANSION

  The %sh{…​} expansion replaces its content with the output of the shell
  commands in it. It is similar to the shell $(…​) syntax and is evaluated only
  when needed.

  For example: %sh{ ls } is replaced with the output of the ls command.

  Some of Kakoune state is available through environment variables:

    kak_selection             content of the main selection
    kak_selections            content of the selection separated by colons,
                              colons and backslashes in the selection contents
                              are escaped with a backslash.
    kak_selection_desc        range of the main selection, represented as
                              anchor,cursor; anchor and cursor are in this
                              format: line.column
    kak_selections_desc       range of the selecations separated by colons
    kak_bufname               name of the current buffer
    kak_buffile               full path of the file or same as kak_bufname when
                              there’s no associated file
    kak_buflist               the current buffer list, each buffer separated by
                              a colon
    kak_timestamp             timestamp of the current buffer, the timestamp is
                              an integer value which is incremented each time
                              the buffer is modified.
    kak_runtime               directory containing the kak binary
    kak_count                 count parameter passed to the command
    kak_opt_<name>            value of option <name>
    kak_reg_<r>               value of register <r>
    kak_session               name of the current session
    kak_client                name of current client
    kak_source                path of the file currently getting executed
                              (through the source command)
    kak_cursor_line           line of the end of the main selection
    kak_cursor_column         column of the end of the main selection (in byte)
    kak_cursor_char_column    column of the end of the main selection (in character)
    kak_cursor_byte_offset    offset of the main selection from the beginning
                              of the buffer (in byte).
    kak_window_width          width of the current kakoune window
    kak_window_height         height of the current kakoune window
    kak_hook_param            filtering text passed to the currently executing hook
    kak_hook_param_capture_N  text captured by the hook filter regex capture N
    kak_client_env_<name>     value of the <name> variable in the client
                              environment.
                              Example: $kak_client_env_SHELL is the SHELL variable

  Note that in order to make only needed information available, Kakoune needs to
  find the environment variable reference in the shell script executed.
  Hence, %sh{ ./script.sh } with script.sh referencing an environment variable
  will not work.

MARKUP STRINGS

  In certain context, kakoune can take a markup string, which is a string
  containing formatting informations. In these strings, syntax {facename} will
  enable the face facename until another face gets activated (or the end of the
  string.
  Literal { shall be written \{, and literal \ that precede a { shall be written \\

REGISTERS

  Registers are named lists of text.
  They are used for various purposes, like storing the last yanked text, or
  the captured groups associated with the selections.

  Yanking and pasting uses the register ", however most commands using a
  register can have their default register overridden by using the " key
  followed by the register. For example "sy will yank (y command) in the s
  register. "sp will paste from the s register.

  While in insert mode or in a prompt, <c-r> followed by a register name
  (one character) inserts it.

  For example,
  <c-r> followed by " will insert the currently yanked text.
  <c-r> followed by 2 will insert the second capture group from the last regex selection.

  Registers are lists, instead of simply text in order to interact well with
  multiselection. Each selection has its own captures or yank buffer.

  Alternate names
    Non alphanumeric registers have an alternative name that can be used in
    contexts where only alphanumeric identifiers are possible.

  Special registers
    Some registers are not general purposes, they cannot be written to, but they
    contain some special data:

    % (percent)  current buffer name
    . (dot)  current selection contents
    # (hash)  selection indices (first selection has 1, second has 2, …​)
    _ (underscore)  null register, always empty

  Default registers

    Most commands using a register default to a specific one if not specified:

    " (dquote)   default yank register, used by yanking and pasting commands
                 like y, p and R
    / (slash)    default search register, used by regex based commands like
                 s, * or /
    @ (arobase)  default macro register, used by q and Q
    ^ (caret)    default mark register, used by z and Z
    | (pipe)     default shell command register, used by command that spawn a
                 subshell such as |, <a-|>, ! or <a-!>

MACROS

  Macros are recorded with the Q key, and are stored by default in the @
  register. Another register can be chosen by with hitting "<reg> before the Q
  key.

  To replay a macro, use the q key.

FEATURES

  Multiple selections as a central way of interacting
  Powerful selection manipulation primitives
  Select all regex matches in current selections
  Keep selections containing/not containing a match for a given regex
  Split current selections with a regex
  Text objects (paragraph, sentence, nestable blocks)
  Powerful text manipulation primitives
  Align selections
  Rotate selection contents
  Case manipulation
  Indentation
  Piping each selection to external filter
  Client-Server architecture
  Multiple clients on the same editing session
  Use tmux or your X11 window manager to manage windows
  Simple interaction with external programs
  Automatic contextual help
  Automatic as you type completion
  Macros
  Hooks
  Syntax Highlighting
  Supports multiple languages in the same buffer
  Highlight a buffer differently in different windows

RESOURCES

  • http://kakoune.org/
  • http://kakoune.org/why-kakoune/why-kakoune.html
  • https://github.com/danr/libkak
  • https://github.com/hiberno/kakrc/tree/master/.config/kak
  • https://github.com/mawww/config
  • https://github.com/mawww/golf
  • https://github.com/mawww/kak-ycmd
  • https://github.com/mawww/kakoune
  • https://github.com/mawww/kakoune#key-mapping
  • https://github.com/mawww/kakoune/blob/master/doc/design.asciidoc
  • https://github.com/mawww/kakoune/issues/249
  • https://github.com/mawww/kakoune/wiki
  • https://github.com/mawww/kakoune/wiki/Avoid-the-escape-key
  • https://github.com/mawww/kakoune/wiki/How-To
  • https://github.com/mawww/kakoune/wiki/Implementing-user-mode
  • https://github.com/mawww/kakoune/wiki/Migrating-from-Vim
  • https://github.com/mawww/kakoune/wiki/Migrating-from-Vim-popular-plugins
  • https://github.com/mawww/kakoune/wiki/Normal-mode-commands
  • https://github.com/search?q=kakrc&type=Code&utf8=%E2%9C%93
  • https://lobste.rs/s/gwdwjb/why_kakoune_quest_for_better_code_editor
  • https://www.reddit.com/r/kakoune/

EXAMPLES

  %sword<ret>creplacement<esc>    Global replace
                                  % selects the entire buffer,
                                  s opens a prompt for a regex
                                  <ret> validates the regex and replaces the
                                  selection with one per matches
                                  (hence, all occurences of word are selected)
                                  c deletes the selection contents and enters
                                  insert mode, replacement is typed and goes
                                  back to normal mode.

  replace in current curly braces block:

  <a-i>Bsword<ret>creplacement<esc>

  delete to line end
  alt-ld or Gld

CLI OPTIONS


  +line[:column]    open at line:column
  +:                open and send cursor to the last line
  -n                do not load resource
  -l                list existing sessions
  -d                run as a headless session
  -e <command>      execute command after initialization fase
  -f <keys>         enter filter mode and execute keys on the files passed as
                    argument
  -q                when in filter mode, don't print any errors
  -p <session_id>   send the commands written on the standard input to the session
  -c <session_id>   connect to the session
  -s <session_id>   set the current session name to session_id
  -ui <type>        select the user interface
                      ncurses: default terminal user interface
                      dummy:   empty user interface not displaying anything
                      json:    json-rpc based user interface that writes json on
                               stdout and read keystrokes as json on stdin.
  -clear            remove sessions that terminated in an incorrect state
  -ro               enter in readonly mode

CONFIGURATION

  two directories containing Kakoune’s scripts:
    runtime:  located in ../share/kak/ relative to the kak binary contains the
              system scripts
    userconf: located in $XDG_CONFIG_HOME/kak/, which defaults to
              $HOME/.config/kak/ on most systems, containing the user
              configuration

  1 ../share/kak/kakrc
  2 $XDG_CONFIG_HOME/kak/autoload/*.kak
  3 ../share/kak/autoload/*.kak
  4 $XDG_CONFIG_HOME/kak/kakrc

  1 Unless -n is specified, Kakoune will load its startup script located at
    ${runtime}/kakrc relative to the kak binary. This startup script is
    responsible for loading the user configuration.
  2 First, Kakoune will search recursively for .kak files in the autoload
    directory. It will first look for an autoload directory at
    ${userconf}/autoload and will fallback to ${runtime}/autoload if it does
    not exist.
  3 Once all those files are loaded, Kakoune will try to source
    ${runtime}/kakrc.local which is expected to contain distribution provided
    configuration.
  4 And finally, the user configuration will be loaded from ${userconf}/kakrc.

  If you create a user autoload directory in ${userconf}/autoload,
  the system one at ${runtime}/autoload will not be loaded anymore.
  You can add a symbolic link to it (or to individual scripts) inside
  ${userconf}/autoload to keep loading system scripts.

CONFIGURATION OPTIONS

  Options are typed, their type can be

    int                     an integer number
    bool                    a boolean value, yes/true or no/false
    str                     a string, some freeform text
    coord                   a line,column pair (separated by comma)
    regex                   as a string but the set commands will complain if
                            the entered text is not a valid regex.
    {int,str}-list          a list, elements are separated by a colon ( ) if an
                            element needs to contain a colon, it can be escaped
                            with a backslash.
    range-faces             a : separated list of a pair of a buffer range
                            (<begin line>.<begin column>,<end line>.<end column>
                            or <begin line>.<end line>+<length>) and a face
                            (separated by |), except for the first element which
                            is just the timestamp of the buffer.
    completions             a : separated list of <text>|<docstring>|<menu text>
                            candidates, except for the first element which
                            follows the <line>.<column>[+<length>]@<timestamp>
                            format to define where the completion apply in the
                            buffer.
    enum(value1|value2|…​)   an enum, taking on of the given values
    flags(value1|value2|…​)  a set of flags, taking a combination of the given
                            values joined by |.

  Options value can be changed using the set commands:

  :set [global,buffer,window] <option> <value> # buffer, window, or global scope

  Option values can be different by scope, an option can have a global value, a
  buffer value and a window value. The effective value of an option depends on
  the current context. If we have a window in the context (interactive edition
  for example), then the window value (if any) is used, if not we try the buffer
  value (if we have a buffer in the context), and if not we use the global
  value.

  That means that two windows on the same buffer can use different options (like
  different filetype, or different tabstop). However, some options might end up
  ignored if their scope is not in the command context

  Writing a file never uses the window options for example, so any options
  related to writing won’t be taken into account if set in the window scope (BOM
  or eolformat for example).

  New options can be declared using the :decl command

  :decl [-hidden] <type> <name> [<value>]

  The -hidden parameter makes the option invisible in completion, but still
  modifiable.

  Some options are built in Kakoune, and can be used to control its behaviour

  tabstop int                           width of a tab character.
  indentwidth int                       width (in spaces) used for indentation.
                                        0 means a tab character.
  scrolloff coord                       number of lines,columns to keep visible
                                        around the cursor when scrolling.
  eolformat enum(lf|crlf)               the format of end of lines when writing
                                        a buffer, this is autodetected on load;
                                        values of this option assigned to the
                                        window scope are ignored
  BOM enum(none|utf8)                   define if the file should be written
                                        with a unicode byte order mark.
                                        Values of this option assigned to the
                                        window scope are ignored
  readonly bool                         prevent modifications from being saved
                                        to disk, all buffers if set to true in
                                        the global scope, or current buffer if
                                        set in the buffer scope; values of this
                                        option assigned to the window scope are
                                        ignored
  incsearch bool                        execute search as it is typed
  aligntab bool                         use tabs for alignment command
  autoinfo flags(command|onkey|normal)  display automatic information box in the
                                        enabled contexts.
  autoshowcompl bool                    automatically display possible
                                        completions when editing a prompt.
  ignored_files regex                   filenames matching this regex won’t be
                                        considered as candidates on filename
                                        completion (except if the text being
                                        completed already matches it).
  disabled_hooks regex                  hooks whose group matches this regex
                                        won’t be executed.
                                        For example indentation hooks can be
                                        disabled with '.*-indent'.
  filetype str                          arbitrary string defining the type of
                                        the file filetype dependant actions
                                        should hook on this option changing for
                                        activation/deactivation.
  path str-list                         directories to search for gf command.
  completers str-list                   completion systems to use for insert
                                        mode completion. The given completers
                                        are tried in order until one generate
                                        some completion candidates.
                                        Existing completers are:
                                          word=all    complete using words in
                                                      all buffers
                                          word=buffer complete using words in
                                                      only the current one
                                          filename    tries to detect when a
                                                      filename is being entered
                                                      and provides completion
                                                      based on local filesystem.
                                          option=<opt-name>
                                                      where <opt-name> is a
                                                      completions option.
  static_words str-list                 list of words that are always added to
                                        completion candidates when completing
                                        words in insert mode.
  completions_extra_word_chars str      a string containing all additional
                                        character that should be considered as
                                        word character for the purpose of insert
                                        mode completion.
  autoreload enum(yes|no|ask)           auto reload the buffers when an external
                                        modification is detected.
  debug flags(hooks|shell|profile)      dump various debug information in the
                                        debug buffer.
  idle_timeout int                      timeout, in milliseconds, with no user
                                        input that will trigger the InsertIdle
                                        and NormalIdle hooks.
  fs_checkout_timeout int               timeout, in milliseconds, between checks
                                        in normal mode of modifications of the
                                        file associated with the current buffer
                                        on the filesystem.
  modelinefmt string                    A format string used to generate the
                                        mode line, that string is first expanded
                                        as a command line would be (expanding
                                        %…​{…​} strings), then markup tags are
                                        applied (see Markup strings). Two
                                        special atoms are available as markup:
                                        {{mode_info}} with information about the
                                        current mode (example insert 3 sel), and
                                        {{context_info}} with information such
                                        as if the file has been modified
                                        (with [+]), or if it is new
                                        (with [new file]).
  ui_options                            colon separated list of key=value pairs
                                        that are forwarded to the user interface
                                        implementation.
                                        The NCurses UI supports the following
                                        options:
    ncurses_set_title                     if yes or true, the terminal emulator
                                          title will be changed.
    ncurses_status_on_top                 if yes, or true the status line will
                                          be placed at the top of the terminal
                                          rather than at the bottom.
    ncurses_assistant                     specify the nice assistant you get in
                                          info boxes, can be 'clippy', 'cat',
                                          'dilbert' or 'none'
    ncurses_enable_mouse                  boolean option that enables mouse
    ncurses_change_colors                 boolean option that can disable color
                                          palette changing if the terminfo
                                          enables it but the terminal does not
                                          support it.
    ncurses_wheel_down_button             specify which button send for wheel
                                          down events.
    ncurses_wheel_up_button               specify which button send for wheel
                                          up events.

Notes

Auto-completion

    I use kak for writing emails, and I store all my email adress contacts in a file, on per line, like

    Joe Bla <joe.bla@gmail.com>
    G z <g.z@a.com>
    I'd like each line to appear as a possible auto-completion candidate. Is this possible?

    i use something like this:
    execute

    set window static_words "%sh{tr '\n' ':' < ~/.contacts | cut -b 1-}"
    set window completion_extra_word_char @
    for your desired filetype.

    starting with @ in insert mode will give you the complete list to cycle through.

Use kakoune as an IDE

    As a convention, many commands respect the toolsclient, docsclient and jumpclient options. These string options store the name of the client to use. toolsclient will be used for :make and :grep commands, when an entry is selected in them, they will try to open the file in the jumpclient client. The :man and :doc commands will display their content in the docsclient.

    If neither of those options are defined, it will fallback on the current client.

    Here’s a small snippet you can trigger to launch multiple clients and bind them to the right options:

    def ide %{
        rename-client main
        set global jumpclient main

        new rename-client tools
        set global toolsclient tools

        new rename-client docs
        set global docsclient docs
    }
    Then it’s up to tmux or your window manager to fit them correctly on your monitor.
    https://github.com/mawww/config/blob/bd58ee3f0314be8561846681d2e837d9545fdde6/ide.kak

How to make x select lines downward, and X - select lines upward.

    more here https://github.com/mawww/kakoune/issues/1285

    def -hidden -params 1 extend-line-down %{
      exec "<a-:>%arg{1}X"
    }
    def -hidden -params 1 extend-line-up %{
      exec "<a-:><a-;>%arg{1}K<a-x>"
    }
    map global normal x ":extend-line-down %val{count}<ret>"
    map global normal X ":extend-line-up %val{count}<ret>"