mirror of
https://github.com/mawww/kakoune.git
synced 2024-12-24 03:56:32 +03:00
906 lines
28 KiB
Plaintext
906 lines
28 KiB
Plaintext
= image:{logo}[K,30,30,link="{website}",title="Kakoune logo by p0nce"] Kakoune 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
|
|
: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://web.libera.chat/?channels=kakoune
|
|
:icons: font
|
|
:toc: right
|
|
:pp: ++
|
|
|
|
TL;DR
|
|
-----
|
|
|
|
{website}
|
|
|
|
*Modal editor* -- *Faster as in fewer keystrokes* --
|
|
*Multiple selections* -- *Orthogonal design*
|
|
|
|
---------------------------------------------
|
|
git clone https://github.com/mawww/kakoune.git
|
|
cd kakoune/src
|
|
make
|
|
./kak
|
|
---------------------------------------------
|
|
|
|
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's philosophy and design.
|
|
|
|
:numbered:
|
|
|
|
Introduction
|
|
------------
|
|
|
|
Kakoune is a code editor that implements Vi's "keystrokes as a text editing
|
|
language" model. As it is 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 being competitive with Vim in terms of keystroke count.
|
|
|
|
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 libera IRC `#Kakoune`
|
|
|
|
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
|
|
|
|
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]
|
|
|
|
Getting started
|
|
---------------
|
|
|
|
Building
|
|
~~~~~~~~
|
|
|
|
Kakoune's dependencies are:
|
|
|
|
* A {cpp}20 compliant compiler (GCC >= 10.3 or clang >= 11) along with its
|
|
associated {cpp} standard library (libstdc{pp} >= 10 or libc{pp})
|
|
|
|
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 `PREFIX` and
|
|
`DESTDIR` if needed.
|
|
|
|
[TIP]
|
|
.Homebrew (macOS) or Linuxbrew
|
|
====
|
|
---------------------------------
|
|
brew install kakoune
|
|
---------------------------------
|
|
====
|
|
|
|
[TIP]
|
|
.MacPorts (macOS)
|
|
====
|
|
---------------------------------
|
|
sudo port selfupdate
|
|
sudo port install kakoune
|
|
---------------------------------
|
|
====
|
|
|
|
[TIP]
|
|
.Fedora supported versions and Rawhide
|
|
====
|
|
---------------------------------
|
|
dnf install kakoune
|
|
---------------------------------
|
|
====
|
|
|
|
[TIP]
|
|
.Fedora daily builds
|
|
====
|
|
Use the https://copr.fedoraproject.org/coprs/jkonecny/kakoune/[copr] repository.
|
|
---------------------------------
|
|
dnf copr enable jkonecny/kakoune
|
|
dnf install kakoune
|
|
---------------------------------
|
|
====
|
|
|
|
[TIP]
|
|
.RHEL/CentOS 8
|
|
====
|
|
Kakoune can be found in the https://src.fedoraproject.org/rpms/kakoune/tree/epel8[EPEL8 repositories].
|
|
---------------------------------
|
|
dnf install kakoune
|
|
---------------------------------
|
|
====
|
|
|
|
[TIP]
|
|
.Arch Linux
|
|
====
|
|
Kakoune is found in the https://www.archlinux.org/packages/community/x86_64/kakoune/[repositories].
|
|
--------------------------------------------------
|
|
pacman -S kakoune
|
|
--------------------------------------------------
|
|
====
|
|
|
|
[TIP]
|
|
.Gentoo
|
|
====
|
|
Kakoune is found in portage as
|
|
https://packages.gentoo.org/packages/app-editors/kakoune[app-editors/kakoune].
|
|
--------------------------------
|
|
emerge kakoune
|
|
--------------------------------
|
|
https://wiki.gentoo.org/wiki/Kakoune[Installation and Gentoo specific documentation] is available.
|
|
====
|
|
|
|
[TIP]
|
|
.Exherbo
|
|
====
|
|
--------------------------------
|
|
cave resolve -x repository/mawww
|
|
cave resolve -x kakoune
|
|
--------------------------------
|
|
====
|
|
|
|
[TIP]
|
|
.openSUSE
|
|
====
|
|
Kakoune can be found in the https://software.opensuse.org/package/kakoune[repositories].
|
|
|
|
---------------------------
|
|
sudo zypper install kakoune
|
|
---------------------------
|
|
====
|
|
|
|
[TIP]
|
|
.Ubuntu
|
|
====
|
|
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.
|
|
|
|
----------------------------------------------------------------
|
|
git clone https://github.com/mawww/kakoune.git && cd kakoune/src
|
|
CXX=g++-10 make
|
|
PREFIX=$HOME/.local make install
|
|
----------------------------------------------------------------
|
|
====
|
|
|
|
[TIP]
|
|
.Debian
|
|
====
|
|
Kakoune can be found in Debian 9 (Stretch) and later releases.
|
|
|
|
---------------------------
|
|
sudo apt install kakoune
|
|
---------------------------
|
|
====
|
|
|
|
[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
|
|
--------------------------------------------------
|
|
====
|
|
|
|
[TIP]
|
|
.OpenBSD
|
|
====
|
|
Building on OpenBSD 6.7 amd64.
|
|
|
|
--------------------------------------------------
|
|
# pkg_add git gmake
|
|
# git clone https://github.com/mawww/kakoune
|
|
# cd kakoune
|
|
# export CXX=clang++
|
|
# gmake install
|
|
--------------------------------------------------
|
|
|
|
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
|
|
--------------------------------------------------
|
|
|
|
Running with support for plugins.
|
|
--------------------------------------------------
|
|
# pkg_add dash
|
|
$ export KAKOUNE_POSIX_SHELL=/usr/local/bin/dash
|
|
$ kak
|
|
--------------------------------------------------
|
|
====
|
|
|
|
[TIP]
|
|
.Solus
|
|
====
|
|
Kakoune is available in the Solus stable repository.
|
|
|
|
It can be installed with
|
|
---------------------
|
|
eopkg install kakoune
|
|
---------------------
|
|
====
|
|
|
|
[TIP]
|
|
.Void
|
|
====
|
|
Kakoune is available in the repositories.
|
|
|
|
It can be installed with
|
|
-----------------------
|
|
xbps-install -S kakoune
|
|
-----------------------
|
|
====
|
|
|
|
[TIP]
|
|
.Termux
|
|
====
|
|
Kakoune is available in the repositories.
|
|
|
|
It can be installed with
|
|
-------------------
|
|
pkg install kakoune
|
|
-------------------
|
|
====
|
|
|
|
[TIP]
|
|
.Nix
|
|
====
|
|
--------------------------------
|
|
nix-env -iA nixpkgs.kakoune
|
|
--------------------------------
|
|
====
|
|
|
|
Running
|
|
~~~~~~~
|
|
|
|
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 `kak` binary
|
|
contains the system scripts, installed with Kakoune.
|
|
* `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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
Once all those files are loaded, Kakoune will try to source
|
|
`${runtime}/kakrc.local`, which is expected to contain distribution provided
|
|
configuration.
|
|
|
|
Finally, the user configuration will load from `${userconf}/kakrc`.
|
|
|
|
NOTE: If you create a user `autoload` directory in `${userconf}/autoload`,
|
|
the system one at `${runtime}/autoload` will not load anymore. You can
|
|
add a symbolic link to it (or to individual scripts) inside
|
|
`${userconf}/autoload` to keep loading system scripts.
|
|
|
|
Basic Interaction
|
|
-----------------
|
|
|
|
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:
|
|
|
|
* `<esc>`: leave insert mode
|
|
* `<backspace>`: delete characters before cursors
|
|
* `<del>`: delete characters under cursors
|
|
* `<left>, <right>, <up>, <down>`: move cursors in given direction
|
|
* `<home>`: move cursors to line beginning
|
|
* `<end>`: move cursors to line ending
|
|
|
|
* `<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,
|
|
without interpreting it
|
|
|
|
* `<c-u>`: commit changes up to now as a single undo group
|
|
|
|
* `<a-;>`: escape to normal mode for a single command
|
|
|
|
Movement
|
|
~~~~~~~~
|
|
|
|
See <<Appending>> below for instructions on extending (appending to) the current selection in order to select more text.
|
|
|
|
* `h`: select the character on the left of selection end
|
|
* `j`: select the character below the selection end
|
|
* `k`: select the character above the selection end
|
|
* `l`: select the character on the right of selection end
|
|
|
|
* `w`: select the word and following whitespaces on the right of selection end
|
|
* `b`: select preceding whitespaces and the word on the left of selection end
|
|
* `e`: select preceding whitespaces and the word on the right of selection end
|
|
* `<a-[wbe]>`: same as [wbe], but select WORD instead of word
|
|
|
|
* `f`: select to (including) the next occurrence of the given character
|
|
* `t`: select until (excluding) the next occurrence of the given character
|
|
* `<a-[ft]>`: same as [ft] but in the other direction
|
|
|
|
* `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
|
|
* `<a-x>`: expand selections to contain full lines (including end-of-lines)
|
|
* `<a-X>`: trim selections to only contain full lines (not including last
|
|
end-of-line)
|
|
|
|
* `%`: select whole buffer
|
|
|
|
* `<a-h>`: select to line begin
|
|
* `<a-l>`: select to line end
|
|
|
|
* `/`: search (select next match)
|
|
* `<a-/>`: search (select previous match)
|
|
* `?`: search (extend to next match)
|
|
* `<a-?>`: search (extend to previous match)
|
|
* `n`: select next match
|
|
* `N`: add a new selection with next match
|
|
* `<a-n>`: select previous match
|
|
* `<a-N>`: add a new selection with previous match
|
|
|
|
* `pageup, <c-b>`: scroll one page up
|
|
* `pagedown, <c-f>`: scroll one page down
|
|
* `<c-u>`: scroll half a page up
|
|
* `<c-d>`: scroll half a page down
|
|
|
|
* `)`: rotate selections (the main selection becomes the next one)
|
|
* `(`: 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.
|
|
|
|
* `_`: trim selections
|
|
|
|
A word is a sequence of alphanumeric characters or underscore, a WORD is a
|
|
sequence of non whitespace characters.
|
|
|
|
Appending
|
|
~~~~~~~~~
|
|
|
|
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.
|
|
|
|
Using Counts
|
|
~~~~~~~~~~~~
|
|
|
|
Most selection commands also support counts, which are entered before the
|
|
command itself.
|
|
|
|
For example, `3W` selects 3 consecutive words and `3w` select the third word on
|
|
the right of selection end.
|
|
|
|
Disabling Hooks
|
|
~~~~~~~~~~~~~~~
|
|
|
|
Any normal mode command can be prefixed with `\` which will disable hook execution
|
|
for the duration for the command (including the duration of modes the command could
|
|
move to, so `\i` will disable hooks for the whole insert session).
|
|
|
|
As autoindentation is implemented in terms of hooks, this can be used to disable
|
|
it when pasting text.
|
|
|
|
Changes
|
|
~~~~~~~
|
|
|
|
* `i`: enter insert mode before current selection
|
|
* `a`: enter insert mode after current selection
|
|
* `d`: yank and delete current selection
|
|
* `c`: yank and delete current selection and enter insert mode
|
|
* `.`: repeat last insert mode change (`i`, `a`, or `c`, including
|
|
the inserted text)
|
|
|
|
* `<a-d>`: delete current selection
|
|
* `<a-c>`: delete current selection and enter insert mode
|
|
|
|
* `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
|
|
|
|
* `<a-o>`: add an empty line below cursor
|
|
* `<a-O>`: add an empty line above cursor
|
|
|
|
* `y`: yank selections
|
|
* `p`: paste after current selection end
|
|
* `P`: paste before current selection begin
|
|
* `<a-p>`: paste all after current selection end, and
|
|
select each pasted string.
|
|
* `<a-P>`: paste all before current selection begin, and
|
|
select each pasted string.
|
|
* `R`: replace current selection with yanked text
|
|
* `<a-R>`: replace current selection with every yanked text
|
|
|
|
* `r`: replace each character with the next entered one
|
|
|
|
* `<a-j>`: join selected lines
|
|
* `<a-J>`: join selected lines and select spaces inserted
|
|
in place of line breaks
|
|
* `<a-m>`: merge contiguous selections together (works across lines as well)
|
|
|
|
* `<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.
|
|
* `<a-(>`: rotate selections content backwards
|
|
|
|
Goto Commands
|
|
~~~~~~~~~~~~~
|
|
|
|
Commands beginning with `g` are used to goto certain position and or buffer.
|
|
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.
|
|
|
|
See <<doc/pages/keys#goto-commands,`:doc keys goto-commands`>>.
|
|
|
|
View commands
|
|
~~~~~~~~~~~~~
|
|
|
|
Commands beginning with `v` permit to center or scroll the current
|
|
view. Using `V` will lock view mode until `<esc>` is hit
|
|
|
|
See <<doc/pages/keys#view-commands,`:doc keys view-commands`>>.
|
|
|
|
Marks
|
|
~~~~~
|
|
|
|
Current selections position can be saved in a register and restored later on.
|
|
|
|
See <<doc/pages/keys#marks,`:doc keys marks`>>.
|
|
|
|
Jump list
|
|
~~~~~~~~~
|
|
|
|
Some commands, like the goto commands, buffer switch or search commands,
|
|
push the previous selections to the client's jump list.
|
|
|
|
See <<doc/pages/keys#jump-list,`:doc keys jump-list`>>.
|
|
|
|
Multi Selection
|
|
~~~~~~~~~~~~~~~
|
|
|
|
Kak was designed from the start to handle multiple selections.
|
|
One way to get a multiselection is via the `s` key.
|
|
|
|
For example, to change all occurrences of word 'roger' to word 'marcel'
|
|
in a paragraph, here is what can be done:
|
|
|
|
* select the paragraph with enough `X`
|
|
* 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
|
|
|
|
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 ', *'
|
|
|
|
The regex syntax supported by Kakoune is the based on the ECMAScript script
|
|
syntax and is described at <<doc/pages/regex#,`:doc regex`>>.
|
|
|
|
`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 `,`. To keep only the nth selection
|
|
use `n` followed by `,`, in order to remove a selection, use `<a-,>`.
|
|
|
|
`<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` duplicates selections on the lines that follow them.
|
|
`<a-C>` does the same but on the preceding 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 <<doc/pages/keys#object-selection,`:doc keys object-selection`>>.
|
|
|
|
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.
|
|
|
|
See <<doc/pages/keys#prompt-commands,`:doc keys prompt-commands`>>.
|
|
|
|
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 [<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 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>.
|
|
* `kill[!]`: terminate the current session, all the clients as well as the server,
|
|
use kill! to ignore unsaved buffers
|
|
* `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:
|
|
** `-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.
|
|
* `fail <text>`: raise an error, uses <text> 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 <<doc/pages/expansions#,`:doc expansions`>>.
|
|
|
|
Configuration & Autoloading
|
|
---------------------------
|
|
|
|
Kakrc
|
|
~~~~~
|
|
|
|
If not launched with the `-n` switch, Kakoune will source the
|
|
`../share/kak/kakrc` file relative to the `kak` binary, which
|
|
will source additional files:
|
|
|
|
If the `$XDG_CONFIG_HOME/kak/autoload` directory exists, load every
|
|
`*.kak` files 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/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.
|
|
|
|
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 `colorscheme` will offer completion for those
|
|
color schemes. If a scheme is duplicated in userspace, it will take
|
|
precedence.
|
|
|
|
Options
|
|
-------
|
|
|
|
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 <<doc/pages/options#,`:doc options`>>.
|
|
|
|
|
|
Advanced topics
|
|
---------------
|
|
|
|
Faces
|
|
~~~~~
|
|
|
|
Faces describe how characters are displayed on the screen: color, bold, italic...
|
|
|
|
See <<doc/pages/faces#,`:doc faces`>>.
|
|
|
|
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 <<doc/pages/registers#,`:doc registers`>>.
|
|
|
|
Macros
|
|
~~~~~~
|
|
|
|
Kakoune can record and replay a sequence of key presses.
|
|
|
|
See <<doc/pages/keys#macros,`:doc keys macros`>>.
|
|
|
|
Search selection
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
Using the `*` key, you can set the search pattern to the current selection.
|
|
See <<doc/pages/keys#searching,`:doc keys searching`>>.
|
|
|
|
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 <<doc/pages/regex#,`:doc regex`>>.
|
|
|
|
Exec and Eval
|
|
~~~~~~~~~~~~~
|
|
|
|
The `execute-keys` and `evaluate-commands` are useful for scripting
|
|
in non interactive contexts.
|
|
|
|
See <<doc/pages/execeval#,`:doc execeval`>>.
|
|
|
|
Insert mode completion
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Kakoune can propose completions while inserting text: filenames, words, lines…
|
|
|
|
See <<doc/pages/keys#insert-mode-completion,`:doc keys insert-mode-completion`>>.
|
|
|
|
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 `:`),
|
|
or any other modes (using `:on-key` or `:menu` for 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 `<esc>`, executing normal mode command
|
|
and entering back insert mode (with which binding ?)
|
|
|
|
See <<doc/pages/modes#,`:doc modes`>>.
|
|
|
|
Highlighters
|
|
~~~~~~~~~~~~
|
|
|
|
Manipulation of the displayed text, such as syntax coloration and wrapping
|
|
is done through highlighters.
|
|
|
|
See <<doc/pages/highlighters#,`:doc highlighters`>>.
|
|
|
|
Hooks
|
|
~~~~~
|
|
|
|
Commands can be registered to be executed when certain events arise with hooks.
|
|
|
|
See <<doc/pages/hooks#,`:doc hooks`>>.
|
|
|
|
Key Mapping
|
|
~~~~~~~~~~~
|
|
|
|
Custom key shortcuts can be registered through mappings.
|
|
|
|
See <<doc/pages/mapping#,`:doc mapping`>>.
|
|
|
|
Defining Commands and Aliases
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
New commands can be created using `:define-command`.
|
|
|
|
See <<doc/pages/commands#declaring-new-commands,`:doc commands declaring-new-commands`>>.
|
|
|
|
They can be given additional short names depending of the scope with `:alias`.
|
|
|
|
See <<doc/pages/commands#aliases,`:doc commands aliases`>>.
|
|
|
|
Some helper commands are available to define composite commands.
|
|
|
|
See <<doc/pages/commands#helpers,`:doc commands helpers`>>.
|
|
|
|
FIFO Buffers
|
|
~~~~~~~~~~~
|
|
|
|
FIFO buffers are very useful for running some commands asynchronously while
|
|
progressively displaying their result in Kakoune.
|
|
|
|
See <<doc/pages/buffers#fifo-buffers,`:doc buffers fifo-buffers`>>.
|
|
|
|
Menus
|
|
~~~~~
|
|
|
|
When a menu is displayed, you can use `j`, `<c-n>` or `<tab>` to select the next
|
|
entry, and `k`, `<c-p>` or `<shift-tab>` to select the previous one.
|
|
|
|
Using the `/` key, you can enter some regex in order to restrict available choices
|
|
to the matching ones.
|
|
|
|
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!
|