<<<<<<< HEAD
= Kakoune
: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: ++
{website}
Modal editor — 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 design document for more information on Kakoune philosophy and design.
Kakoune is a code editor that implements Vi’s "keystrokes as a text editing language" model. As it’s also a modal editor, it is somewhat similar to the Vim editor (after which Kakoune was originally inspired).
Kakoune can operate in two modes, normal and insertion. In insertion mode, keys are directly inserted into the current buffer. In normal mode, keys are used to manipulate the current selection and to enter insertion mode.
Kakoune has a strong focus on interactivity, most commands provide immediate and incremental results, while still being competitive (as in keystroke count) with Vim.
Kakoune works on selections, which are oriented, inclusive 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.
Join us on freenode IRC #Kakoune
-
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
-
Kakoune dependencies are:
-
A C++14 compliant compiler (GCC >= 5 or clang >= 3.9) along with its associated C++ standard library (libstdc++ or libc++)
-
ncurses with wide-characters support (>= 5.3, generally referred to as libncursesw)
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.
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
|
Fedora supported versions and Rawhide
Use the copr repository. dnf copr enable jkonecny/kakoune dnf install kakoune |
|
Tip
|
Arch Linux
Kakoune is found in the repositories. pacman -S kakoune |
|
Tip
|
Gentoo
Kakoune is found in portage as app-editors/kakoune |
|
Tip
|
Exherbo
cave resolve -x repository/mawww cave resolve -x kakoune |
|
Tip
|
openSUSE
kakoune can be found in the 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 pkg-config git clone https://github.com/mawww/kakoune.git && cd kakoune/src make PREFIX=$HOME/.local make install |
|
Tip
|
FreeBSD
Kakoune is available in the official ports tree as editors/kakoune. A binary package is also available and can be installed with pkg install kakoune |
|
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 |
Just running kak launch a new kak session with a client on local terminal. Run kak -help to discover the valid command line flags.
There are two directories containing Kakoune’s scripts:
-
runtime: located in../share/kak/relative to thekakbinary contains the system scripts, installed with Kakoune. -
userconf: located in$XDG_CONFIG_HOME/kak/, which will fallback to$HOME/.config/kak/if$XDG_CONFIG_HOMEis not set, containing the user configuration.
Unless -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.
|
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).
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.
>>>>>>> hakoune: add README
# Hakoune
_ _ | | | | | |__ __ _| | _____ _ _ _ __ ___ | '_ \ / _` | |/ / _ \| | | | '_ \ / _ \ | | | | (_| | < (_) | |_| | | | | __/ |_| |_|\__,_|_|\_\___/ \__,_|_| |_|\___|
Hakoune is a friendly fork of the Kakoune text editor offering 6 extra independent features. It aims to remain compatible and up to date with the original project.
This code repository is structured as a collection of git branches:
-
vanilla: ref tomawww/masterbranch. It’s regularly pulled from upstream and serves as the platform to rebase the other branches. -
hakoune: this is the complete edition, with all feature-branches merged-in.
Distribution packages with prebuilt binaries are not provided. You have to build from the source:
cd src && make && make installFeel free to use the full hakoune branch or cherry-pick only the patches you want
to craft your own customized experience.
## TUI
# layout branch
This branch lets you add extra UI bars (lines) around the editor. They can be useful to display a permanent buffer list bar, grep result counters, git status, registers contents…
To do so, add a new ncurses_layout value to the option ui_options.
It’s a comma separated list of zone names describing the UI appearance
from top to bottom. Default value is main,status, meaning that
the status bar is displayed below the main editing zone.
main and status are mandatory names reserved by Hakoune.
If specified, additional zone names must refer to existing string
typed options.
For example:
decl str foo hello
set global ui_options 'ncurses_assistant=cat:ncurses_layout=foo,main,status'
will add a bar on top of the screen displaying hello. Then it’s up to you
to replace hello with a more meaningful value in periodical hooks.
This string can contain markup, like the classic echo command.
PR: #1942 - Mar 2018 - open
# recorded-keys branch
During macro recording (Q), the recorded keys are displayed in the status line.
Issue: #1273 - Mar 2017 - open
# status-selections branch
This branch adds a new selection_count value and removes selections info from the
{{mode_info}} expansion in the modelinefmt option.
The benefit is that you are now in control of displaying selections info as you want
and when you want. For instance, displaying the number of current selections is valuable
in search mode.
e.g. part of modelinefmt may contain {StatusLineInfo}#%reg{#}/%val{selection_count}{Default}
## Keys
# upper-registers branch
This branch adds a distinct behavior between lowercase and uppercase registers:
-
"ayyanks the current selection(s) in thearegister (as usual). -
"Ayappends the current selection(s) to the content of thearegister.
PR: #1630 - Oct 2017 - open
# count-repeat branch
This feature lets you prefix the . (repeat last insert) and <a-.> (repeat last select) with a count.
Examples:
-
ihello<esc>5.first inserthelloand then insert it again 5 more times. -
fe3<a-.>select to nexteand then select to the 3rde.
The "and then" concept above is nice, because you can take a break after the insert or select
operations. It fixes many workflow scenarios when you say to yourself: "oops, I forgot to prefix this f
by a count :(". With this feature: "No worries, I can still do it afterwards :)"
PR: #1602 - Sep 2017 - open
# goto-matching branch
This branch binds the gm keys to go to the next matching character (the closing } if the cursor
is on a {). The g<a-m> does the same for the previous matching character.
map global goto m '<esc>m;' -docstring 'matching next char'
map global goto <a-m> '<esc><a-m>;' -docstring 'matching previous char'PR: #1151 - Jan 2017 - closed
## Obsolete features
The following features are now available in native Kakoune.
# rotate-content-backward branch
This branch provides the reverse operation of the builtin <a-"> (rotate content forward).
Thie problem is " is already reserved for register handling.
In order to avoid breaking compatibility with existing scripts,
the rotate-content-backward primitive is bound to <c-k>, which is free by default.
It seems a weird choice at first but here’s the trick:
map global normal <ret> '<a-">' -docstring 'rotate selections content forward'Currently <ret> is a synonym for <c-j> because of crazy terminal protocol legacy.
So we obtain a nice symmetry with a up (k) and down (j) keys mnemonic for backward/forward.
<<<<<<< HEAD String syntax and expansions ^^^^^^^^^^
Values, options and shell context can be interpolated in strings.
See :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 run 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 ~~~~~~~~~~~~~~~~~ New commands can be created using `:define-command`. See <<doc/pages/commands#declaring-new-commands,`:doc commands declaring-new-commands`>>. Some helper commands are available to define composite commands. See <<doc/pages/commands#helpers,`:doc commands helpers`>>. 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 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!