2024-01-22 17:39:28 +03:00
= image:{logo}[K,30,30,link="{website}",title="Kakoune logo by p0nce"] Kakoune image:{cirrus-img}[link="{cirrus-url}"] image:{srht-img}[link="{srht-url}"] image:{irc-img}[link="{irc-url}"]
2017-11-01 14:49:13 +03:00
ifdef::env-github,env-browser[:outfilesuffix: .asciidoc]
2015-03-31 21:21:31 +03:00
:logo: https://rawgit.com/mawww/kakoune/master/doc/kakoune_logo.svg
2020-01-02 01:47:41 +03:00
:website: https://kakoune.org
2019-12-15 11:19:02 +03:00
:cirrus-img: https://api.cirrus-ci.com/github/mawww/kakoune.svg
2019-12-10 20:56:58 +03:00
:cirrus-url: https://cirrus-ci.com/github/mawww/kakoune
2024-01-21 04:43:22 +03:00
:srht-img: https://builds.sr.ht/~mawww/kakoune.svg
:srht-url: https://builds.sr.ht/~mawww/kakoune?
2017-03-08 09:51:34 +03:00
:irc-img: https://img.shields.io/badge/IRC-%23kakoune-blue.svg
2021-06-13 17:54:19 +03:00
:irc-url: https://web.libera.chat/?channels=kakoune
2015-04-03 20:42:12 +03:00
:icons: font
:toc: right
2017-01-20 00:52:42 +03:00
:pp: ++
2011-11-04 13:09:27 +04:00
2014-07-30 22:14:37 +04:00
TL;DR
-----
2015-10-18 14:42:52 +03:00
{website}
2017-12-27 10:13:11 +03:00
*Modal editor* -- *Faster as in fewer keystrokes* --
2014-10-06 23:23:56 +04:00
*Multiple selections* -- *Orthogonal design*
2014-07-31 03:08:00 +04:00
---------------------------------------------
2020-01-02 01:47:41 +03:00
git clone https://github.com/mawww/kakoune.git
2024-02-29 14:51:11 +03:00
cd kakoune
2014-07-30 22:14:37 +04:00
make
2024-02-29 14:51:11 +03:00
./src/kak
2014-07-31 03:08:00 +04:00
---------------------------------------------
2014-07-30 22:14:37 +04:00
2020-01-02 01:47:41 +03:00
See https://github.com/mawww/golf for Kakoune solutions to vimgolf challenges,
2017-12-27 10:13:11 +03:00
regularly beating the best Vim solution.
2015-01-23 22:14:12 +03:00
2015-06-12 15:38:53 +03:00
See the link:doc/design.asciidoc[design document] for more information on
2022-04-13 05:26:39 +03:00
Kakoune's philosophy and design.
2015-06-12 15:38:53 +03:00
2015-03-31 21:21:31 +03:00
Introduction
------------
2011-11-04 13:09:27 +04:00
2017-12-27 10:13:11 +03:00
Kakoune is a code editor that implements Vi's "keystrokes as a text editing
2022-04-13 05:26:39 +03:00
language" model. As it is also a modal editor, it is somewhat similar to the
2017-12-27 10:13:11 +03:00
Vim editor (after which Kakoune was originally inspired).
2011-11-04 13:09:27 +04:00
2022-04-13 05:26:39 +03:00
Kakoune can operate in two modes: *normal* and *insertion*. In insertion mode,
2011-11-04 13:09:27 +04:00
keys are directly inserted into the current buffer. In normal mode, keys
are used to manipulate the current selection and to enter insertion mode.
2022-04-13 05:26:39 +03:00
Kakoune has a strong focus on interactivity. Most commands provide immediate
and incremental results, while being competitive with Vim in terms of keystroke count.
2014-01-28 17:53:44 +04:00
2020-09-09 21:00:59 +03:00
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.
2011-11-04 13:09:27 +04:00
2020-01-02 01:47:41 +03:00
See https://vimeo.com/82711574
2013-12-26 15:59:30 +04:00
2021-06-13 17:54:19 +03:00
Join us on libera IRC `#Kakoune`
2014-01-04 00:17:33 +04:00
2013-12-31 23:40:09 +04:00
Features
2015-04-03 20:42:12 +03:00
~~~~~~~~
2013-12-31 23:40:09 +04:00
2014-03-24 00:35:11 +04:00
* Multiple selections as a central way of interacting
2013-12-31 23:40:09 +04:00
* Powerful selection manipulation primitives
- Select all regex matches in current selections
2014-01-28 17:53:44 +04:00
- Keep selections containing/not containing a match for a given regex
2013-12-31 23:40:09 +04:00
- 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
2014-05-12 22:02:15 +04:00
* Client-Server architecture
- Multiple clients on the same editing session
- Use tmux or your X11 window manager to manage windows
2013-12-31 23:40:09 +04:00
* Simple interaction with external programs
2014-01-28 17:53:44 +04:00
* Automatic contextual help
* Automatic as you type completion
2013-12-31 23:40:09 +04:00
* Macros
* Hooks
* Syntax Highlighting
2014-06-16 04:18:11 +04:00
- Supports multiple languages in the same buffer
- Highlight a buffer differently in different windows
2013-12-31 23:40:09 +04:00
2015-05-07 02:34:50 +03:00
Screenshots
2015-05-07 02:36:32 +03:00
~~~~~~~~~~~
2015-05-07 02:34:50 +03:00
2015-06-04 09:52:46 +03:00
[[screenshot-i3]]
2015-05-07 02:34:50 +03:00
.Kakoune in i3
image::doc/screenshot-i3.gif[Kakoune in i3]
[[screenshot-tmux]]
.Kakoune in tmux
image::doc/screenshot-tmux.gif[Kakoune in tmux]
2015-04-03 20:42:12 +03:00
Getting started
---------------
2011-11-04 18:05:05 +04:00
Building
2015-04-03 20:42:12 +03:00
~~~~~~~~
2011-11-04 18:05:05 +04:00
2022-04-13 05:26:39 +03:00
Kakoune's dependencies are:
2011-11-04 18:28:29 +04:00
2022-03-06 02:03:00 +03:00
* A {cpp}20 compliant compiler (GCC >= 10.3 or clang >= 11) along with its
2021-11-25 23:27:10 +03:00
associated {cpp} standard library (libstdc{pp} >= 10 or libc{pp})
2011-11-04 18:05:05 +04:00
2016-12-20 06:17:32 +03:00
To build, just type *make* in the src directory.
2017-11-30 01:04:22 +03:00
To generate man pages, type *make man* in the src directory.
2011-11-04 13:09:27 +04:00
2013-12-31 23:40:09 +04:00
Kakoune can be built on Linux, MacOS, and Cygwin. Due to Kakoune relying heavily
2015-06-04 09:52:46 +03:00
on being in a Unix-like environment, no native Windows version is planned.
2013-12-31 23:40:09 +04:00
2013-12-24 01:41:42 +04:00
Installing
2015-04-03 20:42:12 +03:00
~~~~~~~~~~
2013-12-24 01:41:42 +04:00
2022-04-13 05:26:39 +03:00
In order to install *kak* on your system, rather than running it directly from
2021-07-31 22:00:36 +03:00
its source directory, type *make install*. You can specify the `PREFIX` and
2015-04-03 20:58:26 +03:00
`DESTDIR` if needed.
2013-12-24 01:41:42 +04:00
2015-04-03 20:42:12 +03:00
[TIP]
2018-05-26 12:52:37 +03:00
.Homebrew (macOS) or Linuxbrew
2015-04-03 20:42:12 +03:00
====
2016-12-15 02:47:32 +03:00
---------------------------------
2018-05-23 16:35:47 +03:00
brew install kakoune
2016-12-15 02:47:32 +03:00
---------------------------------
2015-04-03 20:42:12 +03:00
====
2015-03-24 16:56:16 +03:00
2021-02-04 02:10:50 +03:00
[TIP]
.MacPorts (macOS)
====
---------------------------------
sudo port selfupdate
sudo port install kakoune
---------------------------------
====
2015-04-03 20:42:12 +03:00
[TIP]
2017-11-13 19:06:53 +03:00
.Fedora supported versions and Rawhide
2015-04-03 20:42:12 +03:00
====
2019-11-29 09:47:05 +03:00
---------------------------------
dnf install kakoune
---------------------------------
====
2015-03-31 17:29:50 +03:00
2019-12-19 17:24:45 +03:00
[TIP]
.Fedora daily builds
====
Use the https://copr.fedoraproject.org/coprs/jkonecny/kakoune/[copr] repository.
---------------------------------
dnf copr enable jkonecny/kakoune
dnf install kakoune
---------------------------------
====
2019-11-29 09:47:05 +03:00
[TIP]
.RHEL/CentOS 8
====
Kakoune can be found in the https://src.fedoraproject.org/rpms/kakoune/tree/epel8[EPEL8 repositories].
2015-03-24 23:13:27 +03:00
---------------------------------
dnf install kakoune
---------------------------------
2015-04-03 20:42:12 +03:00
====
2015-03-24 23:13:27 +03:00
2015-04-03 20:42:12 +03:00
[TIP]
.Arch Linux
====
2018-05-25 20:10:17 +03:00
Kakoune is found in the https://www.archlinux.org/packages/community/x86_64/kakoune/[repositories].
2016-12-16 01:12:28 +03:00
--------------------------------------------------
2018-05-25 20:10:17 +03:00
pacman -S kakoune
2016-12-16 01:12:28 +03:00
--------------------------------------------------
2015-04-03 20:42:12 +03:00
====
2015-03-30 21:13:04 +03:00
2016-05-11 01:08:56 +03:00
[TIP]
.Gentoo
====
Kakoune is found in portage as
2021-07-03 16:36:38 +03:00
https://packages.gentoo.org/packages/app-editors/kakoune[app-editors/kakoune].
2020-11-10 18:29:39 +03:00
--------------------------------
emerge kakoune
--------------------------------
2021-07-03 16:36:38 +03:00
https://wiki.gentoo.org/wiki/Kakoune[Installation and Gentoo specific documentation] is available.
2016-05-11 01:08:56 +03:00
====
2015-04-03 20:42:12 +03:00
[TIP]
.Exherbo
====
2015-03-25 16:46:41 +03:00
--------------------------------
cave resolve -x repository/mawww
cave resolve -x kakoune
--------------------------------
2015-04-03 20:42:12 +03:00
====
2015-03-25 16:46:41 +03:00
2015-11-13 18:40:00 +03:00
[TIP]
.openSUSE
====
2019-12-19 17:24:45 +03:00
Kakoune can be found in the https://software.opensuse.org/package/kakoune[repositories].
2019-10-01 19:40:52 +03:00
---------------------------
2015-11-13 18:40:00 +03:00
sudo zypper install kakoune
2019-10-01 19:40:52 +03:00
---------------------------
2015-11-13 18:40:00 +03:00
====
2017-08-28 23:20:46 +03:00
[TIP]
.Ubuntu
====
2022-03-20 18:15:16 +03:00
Kakoune can be found in the Ubuntu repositories.
----------------------------
sudo apt install kakoune
----------------------------
If you want to compile from source on 20.04 or earlier, you must force the build to use GCC 10, which is not the default. Also, make sure you have .local/bin in your path so that kak is available after the installation.
2017-08-28 23:20:46 +03:00
2017-11-01 09:15:11 +03:00
----------------------------------------------------------------
2017-08-28 23:20:46 +03:00
git clone https://github.com/mawww/kakoune.git && cd kakoune/src
2022-03-20 18:15:16 +03:00
CXX=g++-10 make
2024-03-20 16:31:54 +03:00
make PREFIX=$HOME/.local install
2017-11-01 09:15:11 +03:00
----------------------------------------------------------------
2017-08-28 23:20:46 +03:00
====
2020-08-06 18:12:45 +03:00
[TIP]
.Debian
====
Kakoune can be found in Debian 9 (Stretch) and later releases.
---------------------------
sudo apt install kakoune
---------------------------
====
2018-04-13 14:16:34 +03:00
[TIP]
.FreeBSD
====
Kakoune is available in the official ports tree as
https://www.freshports.org/editors/kakoune[editors/kakoune].
A binary package is also available and can be installed with
--------------------------------------------------
pkg install kakoune
--------------------------------------------------
====
2019-12-07 23:53:42 +03:00
[TIP]
.OpenBSD
====
2020-06-15 11:18:46 +03:00
Building on OpenBSD 6.7 amd64.
2019-12-07 23:53:42 +03:00
--------------------------------------------------
# pkg_add git gmake
# git clone https://github.com/mawww/kakoune
# cd kakoune
# export CXX=clang++
# gmake install
--------------------------------------------------
2020-06-15 11:18:46 +03:00
Kakoune is available in the 6.7-current port tree as
http://cvsweb.openbsd.org/cgi-bin/cvsweb/ports/editors/kakoune/[editors/kakoune]
A binary package is also available for -current snapshot and can be installed with
--------------------------------------------------
# pkg_add kakoune
--------------------------------------------------
2019-12-07 23:53:42 +03:00
Running with support for plugins.
--------------------------------------------------
# pkg_add dash
$ export KAKOUNE_POSIX_SHELL=/usr/local/bin/dash
$ kak
--------------------------------------------------
====
2018-08-11 01:10:19 +03:00
[TIP]
.Solus
====
Kakoune is available in the Solus stable repository.
It can be installed with
---------------------
eopkg install kakoune
---------------------
2018-09-12 17:58:41 +03:00
====
[TIP]
.Void
====
Kakoune is available in the repositories.
It can be installed with
2018-09-13 13:45:43 +03:00
-----------------------
2018-09-12 17:58:41 +03:00
xbps-install -S kakoune
2018-09-13 13:45:43 +03:00
-----------------------
2018-09-12 17:58:41 +03:00
====
[TIP]
.Termux
====
Kakoune is available in the repositories.
It can be installed with
2018-09-13 13:45:43 +03:00
-------------------
2018-09-12 17:58:41 +03:00
pkg install kakoune
2018-09-13 13:45:43 +03:00
-------------------
2018-08-11 01:10:19 +03:00
====
2021-07-31 22:00:36 +03:00
[TIP]
.Nix
====
--------------------------------
nix-env -iA nixpkgs.kakoune
--------------------------------
====
2013-01-07 17:25:19 +04:00
Running
2015-04-03 20:42:12 +03:00
~~~~~~~
2013-01-07 17:25:19 +04:00
2022-04-13 05:26:39 +03:00
Running *kak* launches a new kak session with a client on local terminal.
2019-06-23 09:38:45 +03:00
Run *kak -help* to discover the valid command line flags.
2013-01-07 17:25:19 +04:00
2017-01-05 14:28:22 +03:00
Configuration
^^^^^^^^^^^^^
There are two directories containing Kakoune's scripts:
* `runtime`: located in `../share/kak/` relative to the `kak` binary
contains the system scripts, installed with Kakoune.
2018-09-01 09:17:58 +03:00
* `userconf`: located in `$XDG_CONFIG_HOME/kak/`, which will fallback
to `$HOME/.config/kak/` if `$XDG_CONFIG_HOME` is not set, containing
the user configuration.
2017-01-05 14:28:22 +03:00
2017-01-05 22:30:38 +03:00
Unless `-n` is specified, Kakoune will load its startup script located
2017-01-05 14:28:22 +03:00
at `${runtime}/kakrc` relative to the `kak` binary. This startup script
is responsible for loading the user configuration.
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
2017-04-21 13:32:47 +03:00
it does not exist.
2017-01-05 14:28:22 +03:00
Once all those files are loaded, Kakoune will try to source
2022-04-13 05:26:39 +03:00
`${runtime}/kakrc.local`, which is expected to contain distribution provided
2017-01-05 14:28:22 +03:00
configuration.
2022-04-13 05:26:39 +03:00
Finally, the user configuration will load from `${userconf}/kakrc`.
2017-01-05 14:28:22 +03:00
NOTE: If you create a user `autoload` directory in `${userconf}/autoload`,
2022-04-13 05:26:39 +03:00
the system one at `${runtime}/autoload` will not load anymore. You can
2017-01-05 14:28:22 +03:00
add a symbolic link to it (or to individual scripts) inside
`${userconf}/autoload` to keep loading system scripts.
2013-12-24 01:41:42 +04:00
2015-04-03 20:42:12 +03:00
Basic Interaction
-----------------
Selections
~~~~~~~~~~
The main concept in Kakoune is the selection. A selection is an inclusive,
2020-05-02 18:36:58 +03:00
directed range of characters. A selection has two ends, the anchor and the
2015-04-03 20:42:12 +03:00
cursor.
There is always at least one selection, and a selection is always at least
2022-09-05 13:22:05 +03:00
one character (in which case the anchor and cursor of the selection are
2015-04-03 20:42:12 +03:00
on the same character).
Normal Mode
~~~~~~~~~~~
In normal mode, keys are not inserted directly inside the buffer, but are editing
2022-04-13 05:26:39 +03:00
commands. These commands provide ways to manipulate either the selections themselves
2015-04-03 20:42:12 +03:00
or the selected text.
Insert Mode
~~~~~~~~~~~
2017-04-21 13:32:47 +03:00
When entering insert mode, keys are now directly inserted before each
selection's cursor. Some additional keys are recognised in insert mode:
2015-11-15 16:25:02 +03:00
* `<esc>`: leave insert mode
* `<backspace>`: delete characters before cursors
* `<del>`: delete characters under cursors
2022-04-13 05:26:39 +03:00
* `<left>, <right>, <up>, <down>`: move cursors in given direction
* `<home>`: move cursors to line beginning
* `<end>`: move cursors to line ending
2015-11-15 16:25:02 +03:00
* `<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
- `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,
2022-04-13 05:26:39 +03:00
without interpreting it
2015-11-15 16:25:02 +03:00
2022-04-13 05:26:39 +03:00
* `<c-u>`: commit changes up to now as a single undo group
2015-11-15 16:25:02 +03:00
* `<a-;>`: escape to normal mode for a single command
2015-04-03 20:42:12 +03:00
Movement
~~~~~~~~
2011-11-04 13:09:27 +04:00
2022-04-13 05:26:39 +03:00
See <<Appending>> below for instructions on extending (appending to) the current selection in order to select more text.
2018-12-18 15:27:40 +03:00
2015-06-04 09:52:46 +03:00
* `h`: select the character on the left of selection end
2015-04-03 20:58:26 +03:00
* `j`: select the character below the selection end
* `k`: select the character above the selection end
2015-06-04 09:52:46 +03:00
* `l`: select the character on the right of selection end
2011-11-04 13:09:27 +04:00
2018-12-18 15:28:14 +03:00
* `w`: select the word and following whitespaces on the right of selection end
2015-04-03 20:58:26 +03:00
* `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
2022-04-13 05:26:39 +03:00
* `<a-[wbe]>`: same as [wbe], but select WORD instead of word
2011-11-04 13:09:27 +04:00
2018-12-18 15:30:29 +03:00
* `f`: select to (including) the next occurrence of the given character
2018-12-18 15:28:14 +03:00
* `t`: select until (excluding) the next occurrence of the given character
2016-12-27 09:56:06 +03:00
* `<a-[ft]>`: same as [ft] but in the other direction
2016-02-02 23:15:47 +03:00
2015-07-15 21:03:53 +03:00
* `m`: select to matching character
* `M`: extend selection to matching character
2022-11-06 12:10:33 +03:00
* `x`: expand selections to contain full lines (including end-of-lines)
2022-11-03 07:56:02 +03:00
* `<a-x>`: trim selections to only contain full lines (not including last
2013-04-16 16:30:11 +04:00
end-of-line)
2011-11-22 18:32:05 +04:00
2015-04-03 20:58:26 +03:00
* `%`: select whole buffer
2011-11-04 13:09:27 +04:00
2016-12-27 09:56:06 +03:00
* `<a-h>`: select to line begin
* `<a-l>`: select to line end
2011-11-04 13:09:27 +04:00
2015-04-03 20:58:26 +03:00
* `/`: search (select next match)
2016-12-27 09:56:06 +03:00
* `<a-/>`: search (select previous match)
2015-04-03 20:58:26 +03:00
* `?`: search (extend to next match)
2016-12-27 09:56:06 +03:00
* `<a-?>`: search (extend to previous match)
2015-04-03 20:58:26 +03:00
* `n`: select next match
* `N`: add a new selection with next match
2016-12-27 09:56:06 +03:00
* `<a-n>`: select previous match
* `<a-N>`: add a new selection with previous match
2013-01-03 17:01:48 +04:00
2017-10-04 13:47:56 +03:00
* `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
2012-10-16 20:53:05 +04:00
2018-03-29 15:18:16 +03:00
* `)`: rotate selections (the main selection becomes the next one)
* `(`: rotate selections backwards
2013-10-02 22:10:31 +04:00
2015-04-03 20:58:26 +03:00
* `;`: reduce selections to their cursor
2017-04-21 13:32:47 +03:00
* `<a-;>`: flip the selections' direction
2016-12-27 09:56:06 +03:00
* `<a-:>`: ensure selections are in forward direction (cursor after anchor)
2014-07-05 15:01:12 +04:00
2016-12-27 09:56:06 +03:00
* `<a-.>`: repeat last object or `f`/`t` selection command.
2016-12-14 23:45:15 +03:00
2018-03-29 15:18:16 +03:00
* `_`: trim selections
2014-07-05 15:01:12 +04:00
2014-03-24 00:35:11 +04:00
A word is a sequence of alphanumeric characters or underscore, a WORD is a
sequence of non whitespace characters.
2011-11-04 13:09:27 +04:00
Appending
2015-04-03 20:42:12 +03:00
~~~~~~~~~
2011-11-04 13:09:27 +04:00
2018-12-18 15:27:40 +03:00
For most <<Movement>> commands, using `Shift` extends the current selection
instead of replacing it.
Examples:
* `wWW` selects 3 consecutive words: first `w` selects a word, then `WW` extends the selection two words further.
* `f/F/` selects up to and including the second `/` character forward.
2011-11-04 13:09:27 +04:00
Using Counts
2015-04-03 20:42:12 +03:00
~~~~~~~~~~~~
2011-11-04 13:09:27 +04:00
Most selection commands also support counts, which are entered before the
command itself.
2017-04-21 13:32:47 +03:00
For example, `3W` selects 3 consecutive words and `3w` select the third word on
2011-11-04 13:09:27 +04:00
the right of selection end.
2017-02-19 16:18:00 +03:00
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.
2011-11-04 13:09:27 +04:00
Changes
2015-04-03 20:42:12 +03:00
~~~~~~~
2011-11-04 13:09:27 +04:00
2022-09-10 16:23:50 +03:00
* `i`: enter insert mode before each selection
* `a`: enter insert mode after each selection
* `d`: yank and delete each selection
* `c`: yank and delete each selection and enter insert mode
2015-04-03 20:58:26 +03:00
* `.`: repeat last insert mode change (`i`, `a`, or `c`, including
2014-05-05 21:09:16 +04:00
the inserted text)
2011-11-04 13:09:27 +04:00
2022-09-10 16:23:50 +03:00
* `<a-d>`: delete each selection
* `<a-c>`: delete each selection and enter insert mode
2017-07-11 07:49:29 +03:00
2022-09-10 16:23:50 +03:00
* `I`: enter insert mode at each selection begin line start
* `A`: enter insert mode at each selection end line end
2016-10-24 21:41:05 +03:00
* `o`: enter insert mode in one (or given count) new lines below
2022-09-10 16:23:50 +03:00
each selection end
2016-10-24 21:41:05 +03:00
* `O`: enter insert mode in one (or given count) new lines above
2022-09-10 16:23:50 +03:00
each selection begin
2011-11-04 13:09:27 +04:00
2022-09-10 16:23:50 +03:00
* `<a-o>`: add an empty line below each cursor
* `<a-O>`: add an empty line above each cursor
2017-07-10 12:55:19 +03:00
2015-04-03 20:58:26 +03:00
* `y`: yank selections
2022-09-10 16:23:50 +03:00
* `p`: paste after each selection end
* `P`: paste before each selection begin
* `<a-p>`: paste all after each selection end
* `<a-P>`: paste all before each selection begin
* `R`: replace each selection with yanked text
* `<a-R>`: replace each selection with every yanked text
2014-07-03 03:25:39 +04:00
2015-04-03 20:58:26 +03:00
* `r`: replace each character with the next entered one
2011-11-04 13:09:27 +04:00
2016-12-27 09:56:06 +03:00
* `<a-j>`: join selected lines
* `<a-J>`: join selected lines and select spaces inserted
2013-04-23 20:54:31 +04:00
in place of line breaks
2022-09-05 13:22:05 +03:00
* `<a-_>`: merge contiguous selections together (works across lines as well)
2011-11-22 18:32:05 +04:00
2016-12-27 21:50:55 +03:00
* `<gt> (>)`: indent selected lines
2016-12-27 09:56:06 +03:00
* `<a-gt>`: indent selected lines, including empty lines
2016-12-27 21:50:55 +03:00
* `<lt> (<)`: deindent selected lines
2016-12-27 09:56:06 +03:00
* `<a-lt>`: deindent selected lines, do not remove incomplete
2013-11-14 04:20:49 +04:00
indent (3 leading spaces when indent is 4)
2013-01-03 17:01:48 +04:00
2017-04-21 13:32:47 +03:00
* `|`: pipe each selection through the given external filter program
2022-09-05 13:22:05 +03:00
and replace the selection with its output.
2017-04-21 13:32:47 +03:00
* `<a-|>`: pipe each selection through the given external filter program
2014-12-13 16:17:05 +03:00
and ignore its output
2022-09-10 16:23:50 +03:00
* `!`: insert command output before each selection
* `<a-!>`: append command output after each selection
2011-12-28 23:09:54 +04:00
2015-04-03 20:58:26 +03:00
* `u`: undo last change
2023-06-17 10:30:43 +03:00
* `<c-k>`: move backward in history
2023-11-04 00:30:29 +03:00
* `<a-u>`: undo selection changes
2015-04-03 20:58:26 +03:00
* `U`: redo last change
2023-06-17 11:14:15 +03:00
* `<c-j>`: move forward in history
2023-11-04 00:30:29 +03:00
* `<a-U>`: redo selection changes
2013-01-03 17:01:48 +04:00
2022-09-10 16:23:50 +03:00
* `&`: align selections, align the cursor of selections by inserting
2014-01-28 17:53:44 +04:00
spaces before the first character of the selection
2016-12-27 09:56:06 +03:00
* `<a-&>`: copy indent, copy the indentation of the main selection
2014-01-28 17:53:44 +04:00
(or the count one if a count is given) to all other ones
2015-04-13 15:03:43 +03:00
* ```: to lower case
2015-04-03 20:58:26 +03:00
* `~`: to upper case
2017-11-30 01:04:22 +03:00
* ``<a-`>``: swap case
2013-05-15 20:47:58 +04:00
2022-09-10 16:23:50 +03:00
* `@`: convert selected tabs to spaces, uses the buffer tabstop option or
the count parameter for tabstop.
* `<a-@>`: convert selected spaces to tabs, uses the buffer tabstop option
or the count parameter for tabstop.
2014-03-02 05:04:26 +04:00
2018-03-29 15:18:16 +03:00
* `<a-)>`: rotate selections content, if specified, the count groups
2022-09-05 13:22:05 +03:00
selections, so `3<a-)>` rotate (1, 2, 3) and (4, 5, 6)
2014-03-27 03:42:10 +04:00
independently.
2018-03-29 15:18:16 +03:00
* `<a-(>`: rotate selections content backwards
2013-10-02 22:10:31 +04:00
2013-04-11 23:15:54 +04:00
Goto Commands
2015-04-03 20:42:12 +03:00
~~~~~~~~~~~~~
2013-04-11 23:15:54 +04:00
2017-11-07 11:37:16 +03:00
Commands beginning with `g` are used to goto certain position and or buffer.
2015-06-25 21:41:07 +03:00
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.
2017-11-08 17:59:03 +03:00
See <<doc/pages/keys#goto-commands,`:doc keys goto-commands`>>.
2017-11-07 11:37:16 +03:00
2013-04-16 15:54:04 +04:00
View commands
2015-04-03 20:42:12 +03:00
~~~~~~~~~~~~~
2013-04-11 23:15:54 +04:00
2017-11-07 11:37:16 +03:00
Commands beginning with `v` permit to center or scroll the current
view. Using `V` will lock view mode until `<esc>` is hit
2013-04-11 23:15:54 +04:00
2017-11-08 17:59:03 +03:00
See <<doc/pages/keys#view-commands,`:doc keys view-commands`>>.
2015-11-05 16:39:29 +03:00
2015-06-25 16:00:50 +03:00
Marks
~~~~~
Current selections position can be saved in a register and restored later on.
2015-08-19 23:16:26 +03:00
2017-11-10 20:06:38 +03:00
See <<doc/pages/keys#marks,`:doc keys marks`>>.
2015-06-25 16:00:50 +03:00
2013-10-02 21:48:50 +04:00
Jump list
2015-04-03 20:42:12 +03:00
~~~~~~~~~
2013-10-02 21:48:50 +04:00
Some commands, like the goto commands, buffer switch or search commands,
2017-11-10 20:06:38 +03:00
push the previous selections to the client's jump list.
2013-10-02 21:48:50 +04:00
2017-11-10 20:06:38 +03:00
See <<doc/pages/keys#jump-list,`:doc keys jump-list`>>.
2013-10-02 21:48:50 +04:00
2011-11-16 18:15:40 +04:00
Multi Selection
2015-04-03 20:42:12 +03:00
~~~~~~~~~~~~~~~
2011-11-16 18:15:40 +04:00
Kak was designed from the start to handle multiple selections.
2015-04-03 20:58:26 +03:00
One way to get a multiselection is via the `s` key.
2011-11-16 18:15:40 +04:00
2016-03-05 21:21:29 +03:00
For example, to change all occurrences of word 'roger' to word 'marcel'
2011-11-16 18:15:40 +04:00
in a paragraph, here is what can be done:
2023-01-23 17:09:36 +03:00
* select the paragraph with `x` then enough `J`
2017-04-21 13:32:47 +03:00
* press `s` and enter roger, then enter
* now paragraph selection was replaced with multiselection of each roger in
the paragraph
* press `c` and marcel<esc> to replace rogers with marcels
2011-11-16 18:15:40 +04:00
2015-04-03 20:58:26 +03:00
A multiselection can also be obtained with `S`, which splits the current
2011-11-21 23:35:02 +04:00
selection according to the regex entered. To split a comma separated list,
2015-04-03 20:58:26 +03:00
use `S` then ', *'
2013-02-22 21:37:34 +04:00
2018-07-31 17:58:07 +03:00
The regex syntax supported by Kakoune is the based on the ECMAScript script
syntax and is described at <<doc/pages/regex#,`:doc regex`>>.
2016-02-23 00:22:05 +03:00
2015-04-03 20:58:26 +03:00
`s` and `S` share the search pattern with `/`, and hence entering an empty
2013-02-22 21:37:34 +04:00
pattern uses the last one.
2016-12-27 09:56:06 +03:00
As a convenience, `<a-s>` allows you to split the current selections on
2013-02-22 21:37:34 +04:00
line boundaries.
2011-11-21 23:35:02 +04:00
2022-04-15 01:14:17 +03:00
To clear multiple selections, use `,`. To keep only the nth selection
use `n` followed by `,`, in order to remove a selection, use `<a-,>`.
2012-01-26 01:26:41 +04:00
2016-12-27 09:56:06 +03:00
`<a-k>` allows you to enter a regex and keep only the selections that
2017-04-21 13:32:47 +03:00
contains a match for this regex. Using `<a-K>` you can keep the selections
2013-04-03 21:05:57 +04:00
not containing a match.
2022-10-06 15:28:37 +03:00
`C` duplicates selections on the lines that follow them.
`<a-C>` does the same but on the preceding lines.
2015-02-06 00:25:04 +03:00
2017-04-21 13:32:47 +03:00
`$` allows you to enter a shell command and pipe each selection to it.
2014-05-05 21:00:24 +04:00
Selections whose shell command returns 0 will be kept, other will be dropped.
2012-05-29 15:32:29 +04:00
Object Selection
2015-04-03 20:42:12 +03:00
~~~~~~~~~~~~~~~~
2012-05-29 15:32:29 +04:00
2017-11-10 20:06:38 +03:00
Objects are specific portions of text, like sentences, paragraphs, numbers…
Kakoune offers many keys allowing you to select various text objects.
See <<doc/pages/keys#object-selection,`:doc keys object-selection`>>.
2013-10-08 22:38:10 +04:00
2015-04-03 20:42:12 +03:00
Commands
--------
2013-11-14 17:59:32 +04:00
2015-04-03 20:58:26 +03:00
When pressing `:` in normal mode, Kakoune will open a prompt to enter a command.
2013-02-19 22:04:09 +04:00
2015-04-03 20:42:12 +03:00
Commands are used for non editing tasks, such as opening a buffer, writing the
2015-11-15 16:25:02 +03:00
current one, quitting, etc.
2017-11-10 20:06:38 +03:00
See <<doc/pages/keys#prompt-commands,`:doc keys prompt-commands`>>.
2013-04-02 20:46:33 +04:00
2012-08-08 02:11:36 +04:00
Basic Commands
2015-04-03 20:42:12 +03:00
~~~~~~~~~~~~~~
2012-08-08 02:11:36 +04:00
2016-04-08 19:00:24 +03:00
Some commands take an exclamation mark (`!`), which can be used to force
2016-03-12 12:13:49 +03:00
the execution of the command (i.e. to quit a modified buffer, the
command `q!` has to be used).
2017-11-10 20:06:38 +03:00
Commands starting with horizontal whitespace (e.g. a space) will not be
saved in the command history.
2017-10-04 00:00:08 +03:00
* `cd [<directory>]`: change the current directory to `<directory>`, or the home directory if unspecified
2016-12-13 21:11:45 +03:00
* `doc <topic>`: display documentation about a topic. The completion list
displays the available topics.
2016-03-12 12:13:49 +03:00
* `e[dit][!] <filename> [<line> [<column>]]`: open buffer on file, go to given
2012-08-08 02:11:36 +04:00
line and column. If file is already opened, just switch to this file.
2017-04-21 13:32:47 +03:00
Use edit! to force reloading.
* `w[rite][!] [<filename>]`: write buffer to <filename> or use its name if
2017-04-19 18:47:07 +03:00
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.
2015-04-03 20:58:26 +03:00
* `w[rite]a[ll]`: write all buffers that are associated to a file.
2017-08-23 09:22:23 +03:00
* `q[uit][!] [<exit status>]`: 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 <exit status>.
* `w[a]q[!] [<exit status>]`: write the current buffer (or all buffers when
`waq` is used) and quit. If specified, the client exit status will be set
to <exit status>.
2016-04-29 23:58:04 +03:00
* `kill[!]`: terminate the current session, all the clients as well as the server,
use kill! to ignore unsaved buffers
2015-04-03 20:58:26 +03:00
* `b[uffer] <name>`: switch to buffer <name>
2016-03-12 12:13:49 +03:00
* `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>
2015-04-03 20:58:26 +03:00
* `source <filename>`: execute commands in <filename>
2015-07-03 23:14:08 +03:00
* `colorscheme <name>`: load named colorscheme.
2016-12-15 21:39:05 +03:00
* `rename-client <name>`: set current client name
* `rename-buffer <name>`: set current buffer name
* `rename-session <name>`: set current session name
2016-03-12 12:13:49 +03:00
* `echo [options] <text>`: show <text> in status line, with the following options:
** `-markup`: expand the markup strings in <text>
** `-debug`: print the given text to the `\*debug*` buffer
2015-04-03 20:58:26 +03:00
* `nop`: does nothing, but as with every other commands, arguments may be
2016-03-12 12:13:49 +03:00
evaluated. So nop can be used for example to execute a shell command
2022-09-05 13:22:05 +03:00
while being sure that its output will not be interpreted by kak.
2016-03-12 12:13:49 +03:00
`:%sh{ echo echo tchou }` will echo tchou in Kakoune, whereas
`:nop %sh{ echo echo tchou }` will not, but both will execute the
shell command.
2017-10-17 05:02:11 +03:00
* `fail <text>`: raise an error, uses <text> as its description
2012-08-08 02:11:36 +04:00
2016-01-04 00:48:55 +03:00
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.
2017-11-01 14:49:13 +03:00
String syntax and expansions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2012-08-08 02:11:36 +04:00
2017-11-07 11:37:16 +03:00
Values, options and shell context can be interpolated in strings.
2017-11-01 14:49:13 +03:00
See <<doc/pages/expansions#,`:doc expansions`>>.
2015-09-20 19:40:06 +03:00
2015-07-17 17:54:07 +03:00
Configuration & Autoloading
---------------------------
2015-04-03 20:42:12 +03:00
Kakrc
2015-07-17 17:54:07 +03:00
~~~~~
2015-04-03 20:42:12 +03:00
2015-05-30 16:32:04 +03:00
If not launched with the `-n` switch, Kakoune will source the
2015-07-17 17:54:07 +03:00
`../share/kak/kakrc` file relative to the `kak` binary, which
will source additional files:
2015-05-30 16:32:04 +03:00
If the `$XDG_CONFIG_HOME/kak/autoload` directory exists, load every
`*.kak` files in it, and load recursively any subdirectory.
2017-04-21 13:32:47 +03:00
If it does not exist, falls back to the site wide autoload directory
2015-05-30 16:32:04 +03:00
in `../share/kak/autoload/`.
After that, if it exists, source the `$XDG_CONFIG_HOME/kak/kakrc` file
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.
2015-04-03 20:42:12 +03:00
2015-07-17 17:54:07 +03:00
Color Schemes
~~~~~~~~~~~~~
Kakoune ships with some color schemes that are installed to
`../share/kak/colors/`. If `$XDG_CONFIG_HOME/kak/colors/` is present
2016-03-05 21:21:29 +03:00
the builtin command `colorscheme` will offer completion for those
2017-04-21 13:32:47 +03:00
color schemes. If a scheme is duplicated in userspace, it will take
2015-07-17 17:54:07 +03:00
precedence.
2013-07-25 01:16:32 +04:00
Options
-------
2017-11-07 11:37:16 +03:00
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.
2017-11-01 14:49:13 +03:00
See <<doc/pages/options#,`:doc options`>>.
2015-04-03 20:42:12 +03:00
Advanced topics
---------------
2017-11-01 14:49:13 +03:00
Faces
2017-11-06 01:06:32 +03:00
~~~~~
2015-08-11 15:44:07 +03:00
2017-11-07 11:37:16 +03:00
Faces describe how characters are displayed on the screen: color, bold, italic...
2017-11-01 14:49:13 +03:00
See <<doc/pages/faces#,`:doc faces`>>.
2015-11-10 23:30:27 +03:00
2017-11-01 14:49:13 +03:00
Registers
~~~~~~~~~
2015-11-10 23:30:27 +03:00
2017-11-07 11:37:16 +03:00
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.
2017-11-01 14:49:13 +03:00
See <<doc/pages/registers#,`:doc registers`>>.
2015-11-10 23:30:27 +03:00
2015-04-03 20:42:12 +03:00
Macros
~~~~~~
2015-06-04 09:52:46 +03:00
Kakoune can record and replay a sequence of key presses.
2015-04-03 20:42:12 +03:00
2017-11-10 20:06:38 +03:00
See <<doc/pages/keys#macros,`:doc keys macros`>>.
2015-04-03 20:42:12 +03:00
Search selection
~~~~~~~~~~~~~~~~
2015-04-03 20:58:26 +03:00
Using the `*` key, you can set the search pattern to the current selection.
2017-11-10 20:06:38 +03:00
See <<doc/pages/keys#searching,`:doc keys searching`>>.
2015-04-03 20:42:12 +03:00
2016-02-23 00:22:05 +03:00
Regex syntax
~~~~~~~~~~~~
2017-11-07 11:37:16 +03:00
Kakoune regex syntax is based on the ECMAScript syntax (ECMA-262 standard).
2020-05-02 18:36:58 +03:00
It always runs on Unicode codepoint sequences, not on bytes.
2017-11-07 11:37:16 +03:00
2017-11-01 14:49:13 +03:00
See <<doc/pages/regex#,`:doc regex`>>.
2016-02-23 00:22:05 +03:00
2015-04-03 20:42:12 +03:00
Exec and Eval
~~~~~~~~~~~~~
2017-11-07 11:37:16 +03:00
The `execute-keys` and `evaluate-commands` are useful for scripting
in non interactive contexts.
2017-11-01 14:49:13 +03:00
See <<doc/pages/execeval#,`:doc execeval`>>.
2013-08-04 21:34:08 +04:00
2015-04-03 20:42:12 +03:00
Insert mode completion
~~~~~~~~~~~~~~~~~~~~~~
2018-03-05 10:47:28 +03:00
Kakoune can propose completions while inserting text: filenames, words, lines…
See <<doc/pages/keys#insert-mode-completion,`:doc keys insert-mode-completion`>>.
2015-06-04 09:52:46 +03:00
2015-06-14 19:54:31 +03:00
Escape to normal mode
~~~~~~~~~~~~~~~~~~~~~
From insert mode, pressing `<a-;>` allows you to execute a single normal mode
command. This provides a few advantages:
* The selections are not modified: when leaving insert mode using `<esc>` the
selections can change, for example when insert mode was entered with `a` the
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 `:`),
2017-02-01 01:48:24 +03:00
or any other modes (using `:on-key` or `:menu` for example), and these modes
2015-06-14 19:54:31 +03:00
will get back to the insert mode afterwards.
2016-03-05 21:21:29 +03:00
This feature is tailored for scripting/macros, as it provides a more predictable
2015-06-14 19:54:31 +03:00
behaviour than leaving insert mode with `<esc>`, executing normal mode command
and entering back insert mode (with which binding ?)
2018-02-23 16:31:28 +03:00
See <<doc/pages/modes#,`:doc modes`>>.
2011-11-30 02:37:20 +04:00
Highlighters
2015-04-03 20:42:12 +03:00
~~~~~~~~~~~~
2011-11-08 18:30:10 +04:00
2017-11-07 11:37:16 +03:00
Manipulation of the displayed text, such as syntax coloration and wrapping
is done through highlighters.
2017-11-01 14:49:13 +03:00
See <<doc/pages/highlighters#,`:doc highlighters`>>.
2013-12-04 02:20:33 +04:00
2011-11-26 23:19:08 +04:00
Hooks
2015-04-03 20:42:12 +03:00
~~~~~
2011-11-26 23:19:08 +04:00
2017-11-07 11:37:16 +03:00
Commands can be registered to be executed when certain events arise with hooks.
2017-11-01 14:49:13 +03:00
See <<doc/pages/hooks#,`:doc hooks`>>.
2013-03-20 22:10:16 +04:00
2013-10-26 03:51:19 +04:00
Key Mapping
2015-04-03 20:42:12 +03:00
~~~~~~~~~~~
2013-10-26 03:51:19 +04:00
2017-11-07 11:37:16 +03:00
Custom key shortcuts can be registered through mappings.
2017-11-01 14:49:13 +03:00
See <<doc/pages/mapping#,`:doc mapping`>>.
2016-09-19 11:10:41 +03:00
2019-04-20 00:13:23 +03:00
Defining Commands and Aliases
2019-04-20 11:28:41 +03:00
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2012-08-08 02:11:36 +04:00
2017-11-07 11:37:16 +03:00
New commands can be created using `:define-command`.
2017-11-08 17:59:03 +03:00
See <<doc/pages/commands#declaring-new-commands,`:doc commands declaring-new-commands`>>.
2017-11-07 11:37:16 +03:00
2019-04-20 00:13:23 +03:00
They can be given additional short names depending of the scope with `:alias`.
2012-09-11 15:54:43 +04:00
2019-04-20 00:13:23 +03:00
See <<doc/pages/commands#aliases,`:doc commands aliases`>>.
2014-10-30 02:22:54 +03:00
2019-04-20 00:13:23 +03:00
Some helper commands are available to define composite commands.
2014-10-30 02:22:54 +03:00
2019-04-20 00:13:23 +03:00
See <<doc/pages/commands#helpers,`:doc commands helpers`>>.
2014-10-30 02:22:54 +03:00
2017-11-10 21:50:54 +03:00
FIFO Buffers
2015-04-03 20:42:12 +03:00
~~~~~~~~~~~
2012-09-11 15:54:43 +04:00
2017-11-10 21:50:54 +03:00
FIFO buffers are very useful for running some commands asynchronously while
progressively displaying their result in Kakoune.
2013-01-03 21:57:30 +04:00
2017-11-10 21:50:54 +03:00
See <<doc/pages/buffers#fifo-buffers,`:doc buffers fifo-buffers`>>.
2012-09-12 21:54:46 +04:00
2018-10-06 10:26:49 +03:00
Credits
-------
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!