mawww's experiment for a better code editor
= image:{logo}[K,30,30,link="{website}",title="Kakoune logo by p0nce"] Kakoune image:{travis-img}[link="{travis-url}"] image:{cirrus-img}[link="{cirrus-url}"] image:{irc-img}[link="{irc-url}"] ifdef::env-github,env-browser[:outfilesuffix: .asciidoc] :logo: https://rawgit.com/mawww/kakoune/master/doc/kakoune_logo.svg :website: https://kakoune.org :travis-img: https://travis-ci.org/mawww/kakoune.svg?branch=master :travis-url: https://travis-ci.org/mawww/kakoune :cirrus-img: https://api.cirrus-ci.com/github/mawww/kakoune.svg :cirrus-url: https://cirrus-ci.com/github/mawww/kakoune :irc-img: https://img.shields.io/badge/IRC-%23kakoune-blue.svg :irc-url: https://webchat.freenode.net/?channels=kakoune :icons: font :toc: right :pp: ++
{website}
Modal editor -- Faster as in fewer keystrokes -- Multiple selections -- Orthogonal design
git clone https://github.com/mawww/kakoune.git cd kakoune/src make
See https://github.com/mawww/golf for Kakoune solutions to vimgolf challenges, regularly beating the best Vim solution.
See the link:doc/design.asciidoc[design document] for more information on Kakoune philosophy and design.
:numbered:
Kakoune is a code editor that implements Vi's "keystrokes as a text editing language" model. As it's also a modal editor, it is somewhat similar to the Vim editor (after which Kakoune was originally inspired).
Kakoune can operate in two modes, normal and insertion. In insertion mode, keys are directly inserted into the current buffer. In normal mode, keys are used to manipulate the current selection and to enter insertion mode.
Kakoune has a strong focus on interactivity, most commands provide immediate and incremental results, while still being competitive (as in keystroke count) with Vim.
Kakoune works on selections, which are oriented, inclusive ranges of characters. Selections have an anchor and a cursor. Most commands move both of them except when extending selections, where the anchor character stays fixed and the cursor moves around.
See https://vimeo.com/82711574
Join us on freenode IRC
#Kakoune
Features ~~~~~~~~
Screenshots ~~~~~~~~~~~
[[screenshot-i3]] .Kakoune in i3 image::doc/screenshot-i3.gif[Kakoune in i3]
[[screenshot-tmux]] .Kakoune in tmux image::doc/screenshot-tmux.gif[Kakoune in tmux]
Building ~~~~~~~~
Kakoune dependencies are:
To build, just type make in the src directory. To generate man pages, type make man in the src directory.
Kakoune can be built on Linux, MacOS, and Cygwin. Due to Kakoune relying heavily on being in a Unix-like environment, no native Windows version is planned.
Installing ~~~~~~~~~~
In order to install kak on your system, rather than running it directly from its source directory, type make install, you can specify the
PREFIXand
DESTDIRif needed.
[TIP]
====
[TIP]
sudo port selfupdate
====
[TIP]
====
[TIP]
dnf copr enable jkonecny/kakoune
====
[TIP]
====
[TIP]
====
[TIP]
Kakoune is found in portage as
====
[TIP]
cave resolve -x repository/mawww
====
[TIP]
Kakoune can be found in the https://software.opensuse.org/package/kakoune[repositories].
====
[TIP]
Building on Ubuntu 16.04 and 18.04. Make sure you have .local/bin in your path to make the kak binary available from your shell.
sudo apt install libncursesw5-dev pkg-config git clone https://github.com/mawww/kakoune.git && cd kakoune/src make
====
[TIP]
Kakoune can be found in Debian 9 (Stretch) and later releases.
====
[TIP]
Kakoune is available in the official ports tree as https://www.freshports.org/editors/kakoune[editors/kakoune].
====
[TIP]
Building on OpenBSD 6.7 amd64.
Kakoune is available in the 6.7-current port tree as http://cvsweb.openbsd.org/cgi-bin/cvsweb/ports/editors/kakoune/[editors/kakoune]
$ export KAKOUNEPOSIXSHELL=/usr/local/bin/dash
====
[TIP]
Kakoune is available in the Solus stable repository.
====
[TIP]
Kakoune is available in the repositories.
====
[TIP]
Kakoune is available in the repositories.
====
Running ~~~~~~~
Just running kak launches a new kak session with a client on local terminal. Run kak -help to discover the valid command line flags.
Configuration ^^^^^^^^^^^^^
There are two directories containing Kakoune's scripts:
runtime: located in
../share/kak/relative to the
kakbinary contains the system scripts, installed with Kakoune.
userconf: located in
$XDG_CONFIG_HOME/kak/, which will fallback to
$HOME/.config/kak/if
$XDG_CONFIG_HOMEis not set, containing the user configuration.
Unless
-nis specified, Kakoune will load its startup script located at
${runtime}/kakrcrelative to the
kakbinary. This startup script is responsible for loading the user configuration.
First, Kakoune will search recursively for
.kakfiles in the
autoloaddirectory. It will first look for an
autoloaddirectory at
${userconf}/autoloadand will fallback to
${runtime}/autoloadif it does not exist.
Once all those files are loaded, Kakoune will try to source
${runtime}/kakrc.localwhich is expected to contain distribution provided configuration.
And finally, the user configuration will be loaded from
${userconf}/kakrc.
NOTE: If you create a user
autoloaddirectory in
${userconf}/autoload, the system one at
${runtime}/autoloadwill not be loaded anymore. You can add a symbolic link to it (or to individual scripts) inside
${userconf}/autoloadto keep loading system scripts.
Selections ~~~~~~~~~~
The main concept in Kakoune is the selection. A selection is an inclusive, directed range of characters. A selection has two ends, the anchor and the cursor.
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).
Normal Mode ~~~~~~~~~~~
In normal mode, keys are not inserted directly inside the buffer, but are editing commands. These commands provide ways to manipulate either the selections themselves, or the selected text.
Insert Mode ~~~~~~~~~~~
When entering insert mode, keys are now directly inserted before each selection's cursor. Some additional keys are recognised in insert mode:
: delete characters under cursors
, , ,: move the cursors in given direction
f: explicit file completion
w: explicit word completion
l: explicit line completion
Movement ~~~~~~~~
See <> below for instructions on extending (appending to) the current selection, in order to select more text in multiple steps.
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
f: select to (including) the next occurrence of the given character
t: select until (excluding) the next occurrence of the given character
m: select to matching character
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
%: select whole buffer
/: search (select next match)
?: search (extend to next match)
n: select next match
N: add a new selection with next match
pageup,: scroll one page up
pagedown,: scroll one page down
): rotate selections (the main selection becomes the next one)
(: rotate selections backwards
;: reduce selections to their cursor
f/
tselection command.
_: trim selections
A word is a sequence of alphanumeric characters or underscore, a WORD is a sequence of non whitespace characters.
Appending ~~~~~~~~~
For most <> commands, using
Shiftextends the current selection instead of replacing it.
Examples:
wWWselects 3 consecutive words: first
wselects a word, then
WWextends the selection two words further.
f/F/selects up to and including the second
/character forward.
Using Counts ~~~~~~~~~~~~
Most selection commands also support counts, which are entered before the command itself.
For example,
3Wselects 3 consecutive words and
3wselect 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
\iwill 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.
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)
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 one (or given count) new lines below current selection end
O: enter insert mode in one (or given count) new lines above current selection begin
y: yank selections
p: paste after current selection end
P: paste before current selection begin
R: replace current selection with yanked text
r: replace each character with the next entered one
(>): indent selected lines
(: deindent selected lines
|: pipe each selection through the given external filter program and replace the selection with it's output.
!: insert command output before selection
u: undo last change
U: redo last change
&: align selection, align the cursor of selections by inserting spaces before the first character of the selection
```: to lower case
~: to upper case
@: convert tabs to spaces in current selections, uses the buffer tabstop option or the count parameter for tabstop.
3rotate (1, 2, 3) and (3, 4, 6) independently.
Goto Commands ~~~~~~~~~~~~~
Commands beginning with
gare used to goto certain position and or buffer. If a count is given prior to hitting
g,
gwill jump to the given line. Using
Gwill extend the selection rather than jump.
See <>.
View commands ~~~~~~~~~~~~~
Commands beginning with
vpermit to center or scroll the current view. Using
Vwill lock view mode until is hit
See <>.
Marks ~~~~~
Current selections position can be saved in a register and restored later on.
See <>.
Jump list ~~~~~~~~~
Some commands, like the goto commands, buffer switch or search commands, push the previous selections to the client's jump list.
See <>.
Multi Selection ~~~~~~~~~~~~~~~
Kak was designed from the start to handle multiple selections. One way to get a multiselection is via the
skey.
For example, to change all occurrences of word 'roger' to word 'marcel' in a paragraph, here is what can be done:
X
sand enter roger, then enter
cand marcel to replace rogers with marcels
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
Sthen ', *'
The regex syntax supported by Kakoune is the based on the ECMAScript script syntax and is described at <>.
sand
Sshare the search pattern with
/, and hence entering an empty pattern uses the last one.
As a convenience,
allows you to split the current selections on line boundaries.To clear multiple selections, use
space. To keep only the nth selection use
nfollowed by
space, in order to remove a selection, use . allows you to enter a regex and keep only the selections that contains a match for this regex. Using you can keep the selections not containing a match.
Ccopies the current selection to the next line (or lines if a count is given) 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.
Object Selection ~~~~~~~~~~~~~~~~
Objects are specific portions of text, like sentences, paragraphs, numbers… Kakoune offers many keys allowing you to select various text objects.
See <>.
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.
See <>.
Basic Commands ~~~~~~~~~~~~~~
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).
Commands starting with horizontal whitespace (e.g. a space) will not be saved in the command history.
cd []: change the current directory to , or the home directory if unspecified
doc: display documentation about a topic. The completion list displays the available topics.
e[dit][!] [ []]: 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][!] []: write buffer to 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. If specified, the client exit status will be set to .
w[a]q[!] []: write the current buffer (or all buffers when
waqis used) and quit. If specified, the client exit status will be set to .
kill[!]: terminate the current session, all the clients as well as the server, use kill! to ignore unsaved buffers
b[uffer]: switch to buffer
b[uffer]n[ext]: switch to the next buffer
b[uffer]p[rev]: switch to the previous buffer
d[el]b[uf][!] []: delete the buffer
source: execute commands in
colorscheme: load named colorscheme.
rename-client: set current client name
rename-buffer: set current buffer name
rename-session: set current session name
echo [options]: show in status line, with the following options: **
-markup: expand the markup strings in **
-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.
fail: raise an error, uses as its description
Multiple commands ~~~~~~~~~~~~~~~~~
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.
String syntax and expansions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Values, options and shell context can be interpolated in strings.
See <>.
Kakrc ~~~~~
If not launched with the
-nswitch, Kakoune will source the
../share/kak/kakrcfile relative to the
kakbinary, which will source additional files:
If the
$XDG_CONFIG_HOME/kak/autoloaddirectory exists, load every
*.kakfiles in it, and load recursively any subdirectory.
If it does not exist, falls back to the site wide autoload directory in
../share/kak/autoload/.
After that, if it exists, source the
$XDG_CONFIG_HOME/kak/kakrcfile which should be used for user configuration.
In order to continue autoloading site-wide files with a local autoload directory, just add a symbolic link to
../share/kak/autoload/into your local autoload directory.
Color Schemes ~~~~~~~~~~~~~
Kakoune ships with some color schemes that are installed to
../share/kak/colors/. If
$XDG_CONFIG_HOME/kak/colors/is present the builtin command
colorschemewill offer completion for those color schemes. If a scheme is duplicated in userspace, it will take precedence.
Kakoune can store named and typed values that can be used both to customize the core editor behaviour, and to keep data used by extension scripts.
See <>.
Faces ~~~~~
Faces describe how characters are displayed on the screen: color, bold, italic...
See <>.
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.
See <>.
Macros ~~~~~~
Kakoune can record and replay a sequence of key presses.
See <>.
Search selection ~~~~~~~~~~~~~~~~
Using the
*key, you can set the search pattern to the current selection. See <>.
Regex syntax ~~~~~~~~~~~~
Kakoune regex syntax is based on the ECMAScript syntax (ECMA-262 standard). It always runs on Unicode codepoint sequences, not on bytes.
See <>.
Exec and Eval ~~~~~~~~~~~~~
The
execute-keysand
evaluate-commandsare useful for scripting in non interactive contexts.
See <>.
Insert mode completion ~~~~~~~~~~~~~~~~~~~~~~
Kakoune can propose completions while inserting text: filenames, words, lines…
See <>.
Escape to normal mode ~~~~~~~~~~~~~~~~~~~~~
From insert mode, pressing
allows you to execute a single normal mode command. This provides a few advantages:The selections are not modified: when leaving insert mode using
the selections can change, for example when insert mode was entered withathe cursor will go back one char. Or if on an end of line the cursor will go back left (if possible).
The modes are nested: that means the normal mode can enter prompt (with
:), or any other modes (using
:on-keyor
:menufor example), and these modes will get back to the insert mode afterwards.
This feature is tailored for scripting/macros, as it provides a more predictable behaviour than leaving insert mode with
, executing normal mode command and entering back insert mode (with which binding ?)See <>.
Highlighters ~~~~~~~~~~~~
Manipulation of the displayed text, such as syntax coloration and wrapping is done through highlighters.
See <>.
Hooks ~~~~~
Commands can be registered to be executed when certain events arise with hooks.
See <>.
Key Mapping ~~~~~~~~~~~
Custom key shortcuts can be registered through mappings.
See <>.
Defining Commands and Aliases ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
New commands can be created using
:define-command.
See <>.
They can be given additional short names depending of the scope with
:alias.
See <>.
Some helper commands are available to define composite commands.
See <>.
FIFO Buffers ~~~~~~~~~~~
FIFO buffers are very useful for running some commands asynchronously while progressively displaying their result in Kakoune.
See <>.
Menus ~~~~~
When a menu is displayed, you can use
j, or to select the next entry, and
k, or to select the previous one.
Using the
/key, you can enter some regex in order to restrict available choices to the matching ones.
Thanks to https://github.com/p0nce[p0nce] for designing the https://github.com/mawww/kakoune/blob/master/doc/kakoune_logo.svg[Kakoune logo].
And thanks to all the https://github.com/mawww/kakoune/graphs/contributors[contributors] who help move the project forward!