Migrating from Vim

Vi(m) to Kakoune:

Kakoune is inspired heavily by Vim. It strives to be as efficient as Vim, more consistent and simpler. A big difference is that a lot of special features in Vim just become regular interaction of basic features in Kakoune.

Operations and moves are reversed in Kakoune. First select whatever text you want to operate on, and then use a modifying operation. That makes things more consistent (Vim needs a separate x and d operation because of the operator -> move order, Kakoune only needs the d operation). That also allows more complex selections.

delete a word:

• vim: dw
• kak: wd

delete a character:

• vim: x
• kak: d or ;d (; reduces the selection to a single char)

copy a line:

• vim: yy
• kak: xy

global replace:

• vim: :%s/word/replacement/g<ret>
• kak: %sword<ret>creplacement<esc>

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

Note that the Kakoune version is three key less, and is not a special feature per se, but just a nice way Kakoune features work together.

Substitute in selection (assume that selection has been made already) with sub-patterns:

• vim: :'<,'>s/(word1):(word2):(word3):(word4)/\4\2\3\1/
• kak: s(word1):(word2):(word3):(word4)<ret>c<c-r>4<c-r>2<c-r>3<c-r>1<esc>
• kak: | sed -e 's/\(word1\)\(word2\)\(word3\)\(word4\)/\4\2\3\1/'

Note that again the first Kakoune version is again some keys shorter. The second one shows at the same time, how to use external tools with pipes.

replace in current curly braces block:

• vim: viB:s/word/replacement<ret>
• kak: <a-i>Bsword<ret>creplacement<esc>

Here again, we need to rely on another Vim special feature, visual mode.

join line with next:

• vim: J
• kak: alt-J

delete to line end:

• vim: D
• kak: alt-ld or Gld

some classic vim moves are not bound to the same key, this is due to Kakoune using shifted moves to append to selection, so moves that were bound to non alphabetic chars had to change.

• % become m (for matching), however m will replace selection with the next block, if you want to get a selection from current cursor to next block end, you should use ;M (; clears the selection to one character)

• 0 and $ became alt-h and alt-l (selects from cursor to begin/end of line) or gh and gl (move cursor and anchor to begin/end of line).

Edit lines matching a regex:

• vim: :g/re/cmd
• kak: %<a-s><a-k>re<ret>cmd

Explanation: to emulate :g, use % to select the whole buffer, alt-s to split the selection into lines, then alt-k to keep selections matching a regex (or alt-K to drop selections, if you're trying to emulate :v). The cmd refers to the command to perform, for example substitution.

Repeat the last movement:

• vim: ;
• kak: <a-.>

Explanation: <a-.> is used to repeat the last movement. It works with all the f t selection, but also with the <a-i> and <a-a> command. Type :doc keys in kakoune for more infos.

Switch from Insert to Normal mode for one command:

• vim: <c-o> (in Insert mode)
• kak: <a-;> (in Insert mode)

Explanation: Like Vim, Kakoune has a command that will switch to Normal mode for a single command, then switch back. Unlike Vim, if this Normal mode enters a new Insert mode (like i or o), it will be nested: when you hit <esc> to leave, you'll wind up in the original Insert mode you started in, and you'll have to hit <esc> again to get back to Normal mode. Normally this is what you want (especially for scripting and mappings), but if you use it interactively you may get a surprise.

Edit alternate file / Previously edited file:

• vim: <c-^> (in Normal mode)
• kak: ga (in Normal mode)

Your kakrc

Just like vim, you can keep an rc-file with your settings. It should be located in $XDG_CONFIG_HOME/kak/kakrc (usually ~/.config/kak/kakrc) Gists Repos

Composing commands

Just like vi commands, Kakoune movements and selection commands can be composed. But knowing how many words there are between the cursor and the target is not a trivial task and takes quite some practice. In vi, it is not possible to incrementally change the effect of an operation in normal mode. But Kakoune is, so to speak, in visual mode by default. This makes composing operations, guess what, quite visual. Regarding selections, as Kakoune displays them, you should not have to count, you can just do 5 hit on W to add 5 words in the selection (just stop when you see the selection is good), or 5 hits on w to select the 5th word from current cursor (similarly, just stop when the word selected it the one you want).

Smarttab, expandtab and noexpandtab

You can use smarttab.kak plugin. It provides these commands to toggle different policies when using Tab and > keys:

• noexpandtab - use tab for everything.
  Tab will insert \t character, and > will use \t character when indenting. Aligning cursors with & uses \t character.
• expandtab - use space for everything.
  Tab will insert %opt{tabstop} amount of spaces, and > will indent with spaces.
• smarttab - indent with tab, align with space.
  Tab will insert \t character if your cursor is inside indentation area, e.g. before any non-whitespace character, and insert spaces if cursor is after any non-whitespace character. Aligning cursors with & uses space.

If you are looking for a more faithful implementation of vim's expandtab and softtabstop options, try this gist: vimtab.kak. Just copy and paste it into your kakrc file and set the options as you wish. It also respects the usage of \ to disable hooks for insert mode, thus allowing you to insert a <tab> even when expandtab is enabled.

Autocmd

Vim's autocmds equivalent in Kakoune terms are hooks. They let you register commands to be executed when certain events arise.

To temporarily disable hooks for a given command, press \ key in normal mode. A [no-hooks] flag will appear in the status line.

Whichwrap

Vim default whichwrap does not exist in Kakoune but is easily programmable with hooks on the move command:

hook global NormalKey h %{
    try %{
        execute-keys <a-k>$<ret> l
    }
}

hook global NormalKey l %{
    try %{
        execute-keys <a-k>^<ret>h
    }
}

Marks

The z key is used to deal with marks (it's used for folding commands in vim). In kakoune marks are tightly related to registers, i.e. when you want to set the a mark the current selections coordinates are stored in the a register.

Code folding

There's currently no implementation of this feature. Follow this issue to discover how it goes: https://github.com/mawww/kakoune/issues/453

Highlight current line/column

Kakoune doesn't have cursorline or cursorcolumn commands but you can use kak-crosshairs plugin.

UI

The terminology of some ui elements is a bit different, but they work the same:

• listchars, lsc: add-highlighter show_whitespaces
• signs, SignColumn (limited to 2 chars in vim): add-highlighter flag_lines. See Line flags

Quickfix and Location windows

By default in kakoune, multiple clients can share the same environment (opened buffers…) if they are connected to the same session. For example if in a terminal you start a first instance of kakoune: kak -s mysession foo.txt, you can then open a second terminal and connect a second kakoune client: kak -c mysession.

So with a bit of coordination, you could tell that the first terminal is your main editor, and the second one displays related info such as the output of grep or lint commands and therefore conceptually acts as an equivalent of vim's Quickfix window. See Use kakoune as an IDE for a quick recipe.

Vim plugins - VimL, VimScript

Most of Vim's power comes from its huge ecosystem of plugins. Many of them are not needed in kakoune because they are already provided as native commands. Check out this guide to learn more about them.

You can of course write your own script if you need to extend the core functionalities. Kakoune intentionally offers no built-in language, but offers a simple (but powerful) string expansion system, %sh{} blocks, that let you express your thoughts from simple shell one-liners to complete programs in awk, python, ruby, js…

That's why there's no distinction between command and function. There are only commands.

Check the content of the rc directory or this community contributions page to have a taste.

Bring your Vim colorscheme to Kakoune

You can export Vim color themes for use in Kakoune using export-colorscheme.nvim.