mirror of
https://github.com/mawww/kakoune.git
synced 2024-12-24 03:56:32 +03:00
996 lines
35 KiB
Plaintext
996 lines
35 KiB
Plaintext
= image:{logo}[K,30,30,link="{website}"] Kakoune image:{travis-img}[link="{travis-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: http://kakoune.org
|
|
:travis-img: https://travis-ci.org/mawww/kakoune.svg?branch=master
|
|
:travis-url: https://travis-ci.org/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: ++
|
|
|
|
TL;DR
|
|
-----
|
|
|
|
{website}
|
|
|
|
*Vim inspired* -- *Faster as in fewer keystrokes* --
|
|
*Multiple selections* -- *Orthogonal design*
|
|
|
|
---------------------------------------------
|
|
git clone http://github.com/mawww/kakoune.git
|
|
cd kakoune/src
|
|
make
|
|
./kak
|
|
---------------------------------------------
|
|
|
|
See http://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:
|
|
|
|
Introduction
|
|
------------
|
|
|
|
Kakoune is a code editor heavily inspired by Vim, as such most of its
|
|
commands are similar to vi's ones, and it shares Vi's "keystrokes as
|
|
a text editing language" model.
|
|
|
|
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 range of characters,
|
|
selections have an anchor and a cursor character. Most commands move both of
|
|
them, except when extending selection where the anchor character stays fixed
|
|
and the cursor one moves around.
|
|
|
|
See http://vimeo.com/82711574
|
|
|
|
Join us on freenode 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 dependencies are:
|
|
|
|
* A {cpp}14 compliant compiler (GCC >= 5 or clang >= 3.9) along with its
|
|
associated {cpp} standard library (libstdc{pp} or libc{pp})
|
|
* ncurses with wide-characters support (>= 5.3, generally referred to as libncursesw)
|
|
* asciidoc (for the `a2k` tool), to generate man pages
|
|
|
|
To build, just type *make* in the src directory.
|
|
To generate man pages, type *make doc* 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 (OSX)
|
|
====
|
|
NOTE: The ncurses library that comes with OSX is not new enough to support some
|
|
mouse based features of Kakoune (only tested on OSX 10.11.3, where the
|
|
packaged ncurses library is version 5.4, whereas the latest version is 6.0).
|
|
Currently, a fresh Kakoune install requires that you install ncurses 6.0. You
|
|
can install ncurses 6.0 via Homebrew,
|
|
--------------------
|
|
brew install ncurses
|
|
--------------------
|
|
|
|
Then, to install,
|
|
---------------------------------------------------------------------------------------------
|
|
brew install --HEAD https://raw.githubusercontent.com/mawww/kakoune/master/contrib/kakoune.rb
|
|
---------------------------------------------------------------------------------------------
|
|
|
|
To update kakoune,
|
|
---------------------------------
|
|
brew upgrade --fetch-HEAD kakoune
|
|
---------------------------------
|
|
====
|
|
|
|
[TIP]
|
|
.Fedora 22/23/24/Rawhide
|
|
====
|
|
Use the https://copr.fedoraproject.org/coprs/jkonecny/kakoune/[copr]
|
|
repository.
|
|
|
|
---------------------------------
|
|
dnf copr enable jkonecny/kakoune
|
|
dnf install kakoune
|
|
---------------------------------
|
|
====
|
|
|
|
[TIP]
|
|
.Arch Linux
|
|
====
|
|
A PKGBUILD https://aur.archlinux.org/packages/kakoune-git[kakoune-git]
|
|
to install Kakoune is available in the
|
|
https://wiki.archlinux.org/index.php/Arch_User_Repository[AUR].
|
|
|
|
--------------------------------------------------
|
|
# For example build and install Kakoune via yaourt
|
|
yaourt -Sy kakoune-git
|
|
--------------------------------------------------
|
|
====
|
|
|
|
[TIP]
|
|
.Gentoo
|
|
====
|
|
Kakoune is found in portage as
|
|
https://packages.gentoo.org/packages/app-editors/kakoune[app-editors/kakoune]
|
|
====
|
|
|
|
[TIP]
|
|
.Exherbo
|
|
====
|
|
--------------------------------
|
|
cave resolve -x repository/mawww
|
|
cave resolve -x kakoune
|
|
--------------------------------
|
|
====
|
|
|
|
[TIP]
|
|
.openSUSE
|
|
====
|
|
kakoune can be found in the
|
|
https://build.opensuse.org/package/show/editors/kakoune[editors] devel
|
|
project. Make sure to adjust the link below to point to the repository of
|
|
your openSUSE version.
|
|
|
|
---------------------------------------------------------------------------------------------------
|
|
#Example for Tumbleweed:
|
|
sudo zypper addrepo http://download.opensuse.org/repositories/editors/openSUSE_Factory/editors.repo
|
|
sudo zypper refresh
|
|
sudo zypper install kakoune
|
|
---------------------------------------------------------------------------------------------------
|
|
====
|
|
|
|
[TIP]
|
|
.Ubuntu
|
|
====
|
|
Building on Ubuntu 16.04.
|
|
Make sure you have .local/bin in your path to make the kak binary available from your shell.
|
|
|
|
----------------------------------------------------------------
|
|
sudo apt install libncursesw5-dev asciidoc
|
|
git clone https://github.com/mawww/kakoune.git && cd kakoune/src
|
|
make
|
|
PREFIX=$HOME/.local make install
|
|
----------------------------------------------------------------
|
|
====
|
|
|
|
Running
|
|
~~~~~~~
|
|
|
|
Just running *kak* launch a new kak session with a client on local terminal.
|
|
*kak* accepts some switches:
|
|
|
|
* `-c <session>`: connect to given session, sessions are unix sockets
|
|
`/tmp/kakoune/<user>/<session>`, `<user>/<session>` can be used
|
|
as well to connect to another user's session, provided the socket
|
|
permissions have been changed to allow it.
|
|
* `-e <commands>`: execute commands on startup
|
|
* `-n`: ignore kakrc file
|
|
* `-s <session>`: set the session name, by default it will be the pid
|
|
of the initial kak process.
|
|
* `-d`: run Kakoune in daemon mode, without user interface. This requires
|
|
the session name to be specified with -s. In this mode, the Kakoune
|
|
server will keep running even if there is no connected client, and
|
|
will quit when receiving SIGTERM.
|
|
* `-p <session>`: read stdin, and then send its content to the given session
|
|
acting as a remote control.
|
|
* `-f <keys>`: Work as a filter, read every file given on the command line
|
|
and stdin if piped in, and apply given keys on each.
|
|
* `-ui <userinterface>`: use given user interface, `<userinterface>` can be
|
|
- `ncurses`: default terminal user interface
|
|
- `dummy`: empty user interface not displaying anything
|
|
- `json`: json-rpc based user interface that writes json on stdout and
|
|
read keystrokes as json on stdin.
|
|
* `-l`: list existing sessions, and check the dead ones
|
|
* `-clear`: clear dead session's socket files
|
|
* `-ro`: prevent modifications to all buffers from being saved to disk
|
|
* `+line[:column]`: specify a target line and column for the first file
|
|
|
|
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 defaults
|
|
to `$HOME/.config/kak/` on most systems, 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.
|
|
|
|
And finally, the user configuration will be loaded from `${userconf}/kakrc`.
|
|
|
|
NOTE: If you create a user `autoload` directory in `${userconf}/autoload`,
|
|
the system one at `${runtime}/autoload` will not be loaded anymore. You can
|
|
add a symbolic link to it (or to individual scripts) inside
|
|
`${userconf}/autoload` to keep loading system scripts.
|
|
|
|
Basic Interaction
|
|
-----------------
|
|
|
|
Selections
|
|
~~~~~~~~~~
|
|
|
|
The main concept in Kakoune is the selection. A selection is an inclusive,
|
|
directed range of character. 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 the cursors in given direction
|
|
* `<home>`: move cursors to line begin
|
|
* `<end>`: move cursors to end of line
|
|
|
|
* `<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
|
|
~~~~~~~~
|
|
|
|
* `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 the next occurence of given character
|
|
* `t`: select until the next occurence of 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)
|
|
* `<a-'>`: rotate selections backwards
|
|
|
|
* `;`: reduce selections to their cursor
|
|
* `<a-;>`: flip the selections' direction
|
|
* `<a-:>`: ensure selections are in forward direction (cursor after anchor)
|
|
|
|
* `<a-.>`: repeat last object or `f`/`t` selection command.
|
|
|
|
|
|
A word is a sequence of alphanumeric characters or underscore, a WORD is a
|
|
sequence of non whitespace characters.
|
|
|
|
Appending
|
|
~~~~~~~~~
|
|
|
|
for most selection commands, using shift permits extending current selection
|
|
instead of replacing it. for example, `wWW` selects 3 consecutive words
|
|
|
|
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.
|
|
|
|
Goto Commands
|
|
~~~~~~~~~~~~~
|
|
|
|
Commands beginning with g are used to goto certain position and or buffer:
|
|
|
|
* `gh`: select to line begin
|
|
* `gl`: select to line end
|
|
* `gi`: select to line begin (non blank)
|
|
|
|
* `gg`, `gk`: go to the first line
|
|
* `gj`: go to the last line
|
|
* `ge`: go to last char of last line
|
|
|
|
* `gt`: go to the first displayed line
|
|
* `gc`: go to the middle displayed line
|
|
* `gb`: go to the last displayed line
|
|
|
|
* `ga`: go to the previous (alternate) buffer
|
|
* `gf`: open the file whose name is selected
|
|
|
|
* `g.`: go to last buffer modification position
|
|
|
|
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.
|
|
|
|
View commands
|
|
~~~~~~~~~~~~~
|
|
|
|
Some commands, all beginning with v permit to manipulate the current
|
|
view.
|
|
|
|
* `vv` or `vc`: center the main selection in the window (vertically)
|
|
* `vm`: center the main selection in the window (horizontally)
|
|
* `vt`: scroll to put the main selection on the top line of the window
|
|
* `vb`: scroll to put the main selection on the bottom line of the window
|
|
* `vh`: scroll the window count columns left
|
|
* `vj`: scroll the window count line downward
|
|
* `vk`: scroll the window count line upward
|
|
* `vl`: scroll the window count columns right
|
|
|
|
Using `V` will lock view mode until `<esc>` is hit
|
|
|
|
Marks
|
|
~~~~~
|
|
|
|
Current selections position can be saved in a register and restored later on.
|
|
By default, marks use the '^' register, but using the register can be set
|
|
using `"<reg>` prefix.
|
|
|
|
`Z` will save the current selections to the register.
|
|
`<a-Z>` will combine the current selections to the register.
|
|
`z` will restore the selections from the register.
|
|
`<a-z>` will combine the selections from the register with the existing ones.
|
|
|
|
When combining selections, kakoune will prompt for a combining mode:
|
|
|
|
`+` will append selections from both lists into a single list
|
|
`<` will select the selection with the leftmost cursor for each pair
|
|
`>` will select the selection with the rightmost cursor for each pair
|
|
|
|
Jump list
|
|
~~~~~~~~~
|
|
|
|
Some commands, like the goto commands, buffer switch or search commands,
|
|
push the previous selections to the client's jump list. It is possible
|
|
to forward or backward in the jump list using:
|
|
|
|
* `<c-i>`: Jump forward
|
|
* `<c-o>`: Jump backward
|
|
* `<c-s>`: save current selections
|
|
|
|
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 Perl one and is described
|
|
here <<Regex syntax>>.
|
|
|
|
`s` and `S` share the search pattern with `/`, and hence entering an empty
|
|
pattern uses the last one.
|
|
|
|
As a convenience, `<a-s>` allows you to split the current selections on
|
|
line boundaries.
|
|
|
|
To clear multiple selections, use `space`. To keep only the nth selection
|
|
use `n` followed by `space`, in order to remove a selection, use `<a-space>`.
|
|
|
|
`<a-k>` allows you to enter a regex and keep only the selections that
|
|
contains a match for this regex. Using `<a-K>` you can keep the selections
|
|
not containing a match.
|
|
|
|
`C` copies the current selection to the next line (or lines if a count is given)
|
|
`<a-C>` does the same to previous lines.
|
|
|
|
`$` allows you to enter a shell command and pipe each selection to it.
|
|
Selections whose shell command returns 0 will be kept, other will be dropped.
|
|
|
|
Object Selection
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
Some keys allow you to select a text object:
|
|
|
|
* `<a-a>`: selects the whole object
|
|
* `<a-i>`: selects the inner object, that is the object excluding its surrounder.
|
|
For example, for a quoted string, this will not select the quote, and
|
|
for a word this will not select trailing spaces.
|
|
* `[`: selects to object start
|
|
* `]`: selects to object end
|
|
* `{`: extends selections to object start
|
|
* `}`: extends selections to object end
|
|
|
|
After this key, you need to enter a second key in order to specify which
|
|
object you want.
|
|
|
|
* `b`, `(` or `)`: select the enclosing parenthesis
|
|
* `B`, `{` or `}`: select the enclosing {} block
|
|
* `r`, `[` or `]`: select the enclosing [] block
|
|
* `a`, `<` or `>`: select the enclosing <> block
|
|
* `"` or `Q`: select the enclosing double quoted string
|
|
* `'` or `q`: select the enclosing single quoted string
|
|
* ``` or `g`: select the enclosing grave quoted string
|
|
* `w`: select the whole word
|
|
* `W`: select the whole WORD
|
|
* `s`: select the sentence
|
|
* `p`: select the paragraph
|
|
* `␣`: select the whitespaces
|
|
* `i`: select the current indentation block
|
|
* `n`: select the number
|
|
* `u`: select the argument
|
|
* `c`: select user defined object, will prompt
|
|
for open and close text.
|
|
|
|
For nestable objects, a count can be used in order to specify which surrounding
|
|
level to select.
|
|
|
|
Commands
|
|
--------
|
|
|
|
When pressing `:` in normal mode, Kakoune will open a prompt to enter a command.
|
|
|
|
Commands are used for non editing tasks, such as opening a buffer, writing the
|
|
current one, quitting, etc.
|
|
|
|
A few keys are recognized by prompt mode to help edit a command:
|
|
|
|
* `<ret>`: validate prompt
|
|
* `<esc>`: abandon without
|
|
|
|
* `<left> or <a-h>`: move cursor to previous character
|
|
* `<right> or <a-l>`: move cursor to previous character
|
|
* `<home>`: move cursor to first character
|
|
* `<end>`: move cursor past the last character
|
|
* `<backspace> or <a-x>`: erase character before cursor
|
|
* `<del> or <a-d>`: erase character under cursor
|
|
|
|
* `<c-w>`: advance to next word begin
|
|
* `<c-a-w>`: advance to next WORD begin
|
|
* `<c-b>`: go back to previous word begin
|
|
* `<c-a-b>`: go back to previous WORD begin
|
|
* `<c-e>`: advance to next word end
|
|
* `<c-a-e>`: advance to next word end
|
|
|
|
* `<up> or <c-p>`: select previous entry in history
|
|
* `<down> or <c-n>`: select next entry in history
|
|
|
|
* `<tab>`: select next completion candidate
|
|
* `<backtab>`: select previous completion candidate
|
|
|
|
* `<c-r>`: insert then content of the register given by next key.
|
|
* `<c-v>`: insert next keystroke without interpreting it
|
|
|
|
* `<c-o>`: disable auto completion for this prompt
|
|
|
|
|
|
Commands starting with horizontal whitespace (e.g. a space) will not be
|
|
saved in the command history.
|
|
|
|
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).
|
|
|
|
* `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
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
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
|
|
-------
|
|
|
|
See <<doc/pages/options#,`:doc options`>>.
|
|
|
|
|
|
Advanced topics
|
|
---------------
|
|
|
|
Faces
|
|
~~~~~
|
|
|
|
See <<doc/pages/faces#,`:doc faces`>>.
|
|
|
|
Registers
|
|
~~~~~~~~~
|
|
|
|
See <<doc/pages/registers#,`:doc registers`>>.
|
|
|
|
Macros
|
|
~~~~~~
|
|
|
|
Kakoune can record and replay a sequence of key presses.
|
|
|
|
Macros are recorded with the `Q` key, and are stored by default in the `@`
|
|
register. Another register can be chosen by with hitting `"<reg>` before
|
|
the `Q` key.
|
|
|
|
To replay a macro, use the `q` key.
|
|
|
|
Search selection
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
Using the `*` key, you can set the search pattern to the current selection.
|
|
This tries to be intelligent. It will for example detect if the current selection
|
|
begins and/or ends at word boundaries and set the search pattern accordingly.
|
|
|
|
With `<a-*>` you can set the search pattern to the current selection without
|
|
Kakoune trying to be smart.
|
|
|
|
Regex syntax
|
|
~~~~~~~~~~~~
|
|
|
|
See <<doc/pages/regex#,`:doc regex`>>.
|
|
|
|
Exec and Eval
|
|
~~~~~~~~~~~~~
|
|
|
|
See <<doc/pages/execeval#,`:doc execeval`>>.
|
|
|
|
Insert mode completion
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Kakoune can propose completions while inserting text, the `completers` option
|
|
controls automatic completion, which kicks in when a certain idle timeout is
|
|
reached (see `idle_timeout` option). Insert mode completion can be explicitly triggered
|
|
using `<c-x>`, followed, by:
|
|
|
|
* *f* : filename completion
|
|
* *w* : word completion (current buffer)
|
|
* *W* : word completion (all buffers)
|
|
* *l* : line completion (current buffer)
|
|
|
|
Completion candidates can be selected using `<c-n>` and `<c-p>`.
|
|
|
|
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 ?)
|
|
|
|
Highlighters
|
|
~~~~~~~~~~~~
|
|
|
|
See <<doc/pages/highlighters#,`:doc highlighters`>>.
|
|
|
|
Hooks
|
|
~~~~~
|
|
|
|
See <<doc/pages/hooks#,`:doc hooks`>>.
|
|
|
|
Key Mapping
|
|
~~~~~~~~~~~
|
|
|
|
See <<doc/pages/mapping#,`:doc mapping`>>.
|
|
|
|
Defining Commands
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
New commands can be defined using the `:def` command.
|
|
|
|
------------------------------
|
|
:def <command_name> <commands>
|
|
------------------------------
|
|
|
|
`<commands>` is a string containing the commands to execute.
|
|
|
|
`def` can also take some flags:
|
|
|
|
* `-params <num>`: the command accept <num> parameters, with <num>
|
|
either a number, or of the form <min>..<max>, with both <min> and
|
|
<max> omittable.
|
|
* `-file-completion`: try file completion on any parameter passed
|
|
to this command
|
|
* `-client-completion`: try client name completion on any parameter
|
|
passed to this command
|
|
* `-buffer-completion`: try buffer name completion on any parameter
|
|
passed to this command
|
|
* `-command-completion`: try command completion on any parameter
|
|
passed to this command
|
|
* `-shell-completion`: following string is a shell command which takes
|
|
parameters as positional params and output one completion candidate
|
|
per line. The provided shell command will run after each keypress
|
|
* `-shell-candidates`: following string is a shell command which takes
|
|
parameters as positional params and output one completion candidate
|
|
per line. The provided shell command will run once at the beginning
|
|
of each completion session, candidates are cached and then used by
|
|
kakoune internal fuzzy engine
|
|
* `-allow-override`: allow the new command to replace an existing one
|
|
with the same name.
|
|
* `-hidden`: do not show the command in command name completions
|
|
* `-docstring`: define the documentation string for the command
|
|
|
|
Using shell expansion permits defining complex commands or accessing
|
|
Kakoune state:
|
|
|
|
------------------------------------------------------
|
|
:def print_selection %{ echo %sh{ ${kak_selection} } }
|
|
------------------------------------------------------
|
|
|
|
Some helper commands can be used to define composite commands:
|
|
|
|
* `prompt <prompt> <command>`: prompt the user for a string, when the user validates,
|
|
executes <command>. The entered text is available in the `text` value
|
|
accessible through `$kak_text` in shells or `%val{text}` in commands.
|
|
* `on-key <command>`: wait for next key from user, then execute <command>,
|
|
the key is available through the `key` value, accessible through `$kak_key`.
|
|
* `menu <label1> <commands1> <label2> <commands2>...`: display a menu using
|
|
labels, the selected label's commands are executed.
|
|
`menu` can take a -auto-single argument, to automatically run commands
|
|
when only one choice is provided. And a -select-cmds argument, in which
|
|
case menu takes three argument per item, the last one being a command
|
|
to execute when the item is selected (but not validated).
|
|
* `info <text>`: display text in an information box, at can take a -anchor
|
|
option, which accepts `left`, `right` and `cursor` as value, in order to
|
|
specify where the info box should be anchored relative to the main selection.
|
|
* `try <commands> catch <on_error_commands>`: prevent an error in <commands>
|
|
from aborting the command execution, execute <on_error_commands>
|
|
instead. If nothing is to be done on error, the catch part can be ommitted.
|
|
* `reg <name> <content>`: set register <name> to <content>
|
|
* `select <anchor_line>.<anchor_column>,<cursor_line>.<cursor_column>:...`:
|
|
replace the current selections with the one described in the argument
|
|
* `debug {info,buffers,options,memory,shared-strings,profile-hash-maps,faces,mappings}`:
|
|
print some debug information in the `*debug*` buffer
|
|
|
|
Note that these commands are available in interactive command mode, but are
|
|
not that useful in this context.
|
|
|
|
Aliases
|
|
~~~~~~~
|
|
|
|
With `:alias` commands can be given additional names. Aliases are scoped, so
|
|
that an alias can refer to one command for a buffer, and to another for another
|
|
buffer. The following command defines `<alias>` as an alias for `<command>`:
|
|
|
|
--------------------------------
|
|
:alias <scope> <alias> <command>
|
|
--------------------------------
|
|
|
|
`<scope>` can be one of `global`, `buffer` or `window`.
|
|
|
|
-------------------------------------
|
|
:unalias <scope> <alias> [<expected>]
|
|
-------------------------------------
|
|
|
|
Will remove the given alias in the given scope. If `<expected>` is specified
|
|
the alias will only be removed if its current value is `<expected>`.
|
|
|
|
FIFO Buffer
|
|
~~~~~~~~~~~
|
|
|
|
The `:edit` command can take a `-fifo` parameter:
|
|
|
|
---------------------------------------------
|
|
:edit -fifo <filename> [-scroll] <buffername>
|
|
---------------------------------------------
|
|
|
|
In this case, a buffer named `<buffername>` is created which reads its content
|
|
from fifo `<filename>`. When the fifo is written to, the buffer is automatically
|
|
updated.
|
|
|
|
If the `-scroll` switch is specified, the initial cursor position will be made
|
|
such as the window displaying the buffer will scroll as new data is read.
|
|
|
|
This is very useful for running some commands asynchronously while displaying
|
|
their result in a buffer. See `rc/make.kak` and `rc/grep.kak` for examples.
|
|
|
|
When the buffer is deleted, the fifo will be closed, so any program writing
|
|
to it will receive `SIGPIPE`. This is useful as it permits to stop the writing
|
|
program when the buffer is deleted.
|
|
|
|
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.
|