README.asciidoc (28670B)
1 = image:{logo}[K,32,32,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}"] 2 ifdef::env-github,env-browser[:outfilesuffix: .asciidoc] 3 :logo: http://kakoune.org/img/kakoune_logo_32.png 4 :website: https://kakoune.org 5 :cirrus-img: https://api.cirrus-ci.com/github/mawww/kakoune.svg 6 :cirrus-url: https://cirrus-ci.com/github/mawww/kakoune 7 :srht-img: https://builds.sr.ht/~mawww/kakoune.svg 8 :srht-url: https://builds.sr.ht/~mawww/kakoune? 9 :irc-img: https://img.shields.io/badge/IRC-%23kakoune-blue.svg 10 :irc-url: https://web.libera.chat/?channels=kakoune 11 :icons: font 12 :toc: right 13 :pp: ++ 14 15 TL;DR 16 ----- 17 18 {website} 19 20 *Modal editor* -- *Faster as in fewer keystrokes* -- 21 *Multiple selections* -- *Orthogonal design* 22 23 --------------------------------------------- 24 git clone https://github.com/mawww/kakoune.git 25 cd kakoune 26 make 27 ./src/kak 28 --------------------------------------------- 29 30 See https://github.com/mawww/golf for Kakoune solutions to vimgolf challenges, 31 regularly beating the best Vim solution. 32 33 See the link:doc/design.asciidoc[design document] for more information on 34 Kakoune's philosophy and design. 35 36 Introduction 37 ------------ 38 39 Kakoune is a code editor that implements Vi's "keystrokes as a text editing 40 language" model. As it is also a modal editor, it is somewhat similar to the 41 Vim editor (after which Kakoune was originally inspired). 42 43 Kakoune can operate in two modes: *normal* and *insertion*. In insertion mode, 44 keys are directly inserted into the current buffer. In normal mode, keys 45 are used to manipulate the current selection and to enter insertion mode. 46 47 Kakoune has a strong focus on interactivity. Most commands provide immediate 48 and incremental results, while being competitive with Vim in terms of keystroke count. 49 50 Kakoune works on selections, which are oriented, inclusive ranges of characters. 51 Selections have an anchor and a cursor. Most commands move both of 52 them except when extending selections, where the anchor character stays fixed 53 and the cursor moves around. 54 55 See https://vimeo.com/82711574 56 57 Join us on libera IRC `#Kakoune` 58 59 Features 60 ~~~~~~~~ 61 62 * Multiple selections as a central way of interacting 63 * Powerful selection manipulation primitives 64 - Select all regex matches in current selections 65 - Keep selections containing/not containing a match for a given regex 66 - Split current selections with a regex 67 - Text objects (paragraph, sentence, nestable blocks) 68 * Powerful text manipulation primitives 69 - Align selections 70 - Rotate selection contents 71 - Case manipulation 72 - Indentation 73 - Piping each selection to external filter 74 * Client-Server architecture 75 - Multiple clients on the same editing session 76 - Use tmux, zellij, kitty, wezterm or your X11/Wayland window manager to 77 manage splits/panes by spawning clients connected to the same session 78 * Simple interaction with external programs 79 * Automatic contextual help 80 * Automatic as you type completion 81 * Macros 82 * Hooks 83 * Syntax Highlighting 84 - Supports multiple languages in the same buffer 85 - Highlight a buffer differently in different windows 86 87 Screenshots 88 ~~~~~~~~~~~ 89 90 [[screenshot-i3]] 91 .Kakoune in i3 92 image::doc/screenshot-i3.gif[Kakoune in i3] 93 94 [[screenshot-tmux]] 95 .Kakoune in tmux 96 image::doc/screenshot-tmux.gif[Kakoune in tmux] 97 98 Getting started 99 --------------- 100 101 Building 102 ~~~~~~~~ 103 104 Kakoune's dependencies are: 105 106 * A {cpp}20 compliant compiler (GCC >= 10.3 or clang >= 11) along with its 107 associated {cpp} standard library (libstdc{pp} >= 10 or libc{pp}) 108 109 To build, just type *make* in the root directory. 110 To generate man pages, type *make man* in the root directory. 111 112 Kakoune can be built on Linux, MacOS, and Cygwin. Due to Kakoune relying heavily 113 on being in a Unix-like environment, no native Windows version is planned. 114 115 Installing 116 ~~~~~~~~~~ 117 118 In order to install *kak* on your system, rather than running it directly from 119 its source directory, type *make install*. You can specify the `PREFIX` and 120 `DESTDIR` if needed. 121 122 [TIP] 123 .Homebrew (macOS) or Linuxbrew 124 ==== 125 --------------------------------- 126 brew install kakoune 127 --------------------------------- 128 ==== 129 130 [TIP] 131 .MacPorts (macOS) 132 ==== 133 --------------------------------- 134 sudo port selfupdate 135 sudo port install kakoune 136 --------------------------------- 137 ==== 138 139 [TIP] 140 .Fedora supported versions and Rawhide 141 ==== 142 --------------------------------- 143 dnf install kakoune 144 --------------------------------- 145 ==== 146 147 [TIP] 148 .Fedora daily builds 149 ==== 150 Use the https://copr.fedoraproject.org/coprs/jkonecny/kakoune/[copr] repository. 151 --------------------------------- 152 dnf copr enable jkonecny/kakoune 153 dnf install kakoune 154 --------------------------------- 155 ==== 156 157 [TIP] 158 .RHEL/CentOS 8 159 ==== 160 Kakoune can be found in the https://src.fedoraproject.org/rpms/kakoune/tree/epel8[EPEL8 repositories]. 161 --------------------------------- 162 dnf install kakoune 163 --------------------------------- 164 ==== 165 166 [TIP] 167 .Arch Linux 168 ==== 169 Kakoune is found in the https://www.archlinux.org/packages/community/x86_64/kakoune/[repositories]. 170 -------------------------------------------------- 171 pacman -S kakoune 172 -------------------------------------------------- 173 ==== 174 175 [TIP] 176 .Gentoo 177 ==== 178 Kakoune is found in portage as 179 https://packages.gentoo.org/packages/app-editors/kakoune[app-editors/kakoune]. 180 -------------------------------- 181 emerge kakoune 182 -------------------------------- 183 https://wiki.gentoo.org/wiki/Kakoune[Installation and Gentoo specific documentation] is available. 184 ==== 185 186 [TIP] 187 .Exherbo 188 ==== 189 -------------------------------- 190 cave resolve -x repository/mawww 191 cave resolve -x kakoune 192 -------------------------------- 193 ==== 194 195 [TIP] 196 .openSUSE 197 ==== 198 Kakoune can be found in the https://software.opensuse.org/package/kakoune[repositories]. 199 200 --------------------------- 201 sudo zypper install kakoune 202 --------------------------- 203 ==== 204 205 [TIP] 206 .Ubuntu 207 ==== 208 Kakoune can be found in the Ubuntu repositories. 209 210 ---------------------------- 211 sudo apt install kakoune 212 ---------------------------- 213 214 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. 215 216 ---------------------------------------------------------------- 217 git clone https://github.com/mawww/kakoune.git && cd kakoune/src 218 CXX=g++-10 make 219 make PREFIX=$HOME/.local install 220 ---------------------------------------------------------------- 221 ==== 222 223 [TIP] 224 .Debian 225 ==== 226 Kakoune can be found in Debian 9 (Stretch) and later releases. 227 228 --------------------------- 229 sudo apt install kakoune 230 --------------------------- 231 ==== 232 233 [TIP] 234 .FreeBSD 235 ==== 236 Kakoune is available in the official ports tree as 237 https://www.freshports.org/editors/kakoune[editors/kakoune]. 238 239 A binary package is also available and can be installed with 240 -------------------------------------------------- 241 pkg install kakoune 242 -------------------------------------------------- 243 ==== 244 245 [TIP] 246 .OpenBSD 247 ==== 248 Building on OpenBSD 6.7 amd64. 249 250 -------------------------------------------------- 251 # pkg_add git gmake 252 # git clone https://github.com/mawww/kakoune 253 # cd kakoune 254 # export CXX=clang++ 255 # gmake install 256 -------------------------------------------------- 257 258 Kakoune is available in the 6.7-current port tree as 259 http://cvsweb.openbsd.org/cgi-bin/cvsweb/ports/editors/kakoune/[editors/kakoune] 260 261 A binary package is also available for -current snapshot and can be installed with 262 -------------------------------------------------- 263 # pkg_add kakoune 264 -------------------------------------------------- 265 266 Running with support for plugins. 267 -------------------------------------------------- 268 # pkg_add dash 269 $ export KAKOUNE_POSIX_SHELL=/usr/local/bin/dash 270 $ kak 271 -------------------------------------------------- 272 ==== 273 274 [TIP] 275 .Solus 276 ==== 277 Kakoune is available in the Solus stable repository. 278 279 It can be installed with 280 --------------------- 281 eopkg install kakoune 282 --------------------- 283 ==== 284 285 [TIP] 286 .Void 287 ==== 288 Kakoune is available in the repositories. 289 290 It can be installed with 291 ----------------------- 292 xbps-install -S kakoune 293 ----------------------- 294 ==== 295 296 [TIP] 297 .Termux 298 ==== 299 Kakoune is available in the repositories. 300 301 It can be installed with 302 ------------------- 303 pkg install kakoune 304 ------------------- 305 ==== 306 307 [TIP] 308 .Nix 309 ==== 310 -------------------------------- 311 nix-env -iA nixpkgs.kakoune 312 -------------------------------- 313 ==== 314 315 [TIP] 316 .pkgsrc (NetBSD, SmartOS, macOS, Linux, etc) 317 ==== 318 -------------------------------- 319 pkg_add kakoune 320 -------------------------------- 321 ==== 322 https://repology.org/project/kakoune/versions[image:https://repology.org/badge/vertical-allrepos/kakoune.svg[Packaging status]] 323 324 Running 325 ~~~~~~~ 326 327 Running *kak* launches a new kak session with a client on local terminal. 328 Run *kak -help* to discover the valid command line flags. 329 330 Configuration 331 ^^^^^^^^^^^^^ 332 333 There are two directories containing Kakoune's scripts: 334 335 * `runtime`: located in `../share/kak/` relative to the `kak` binary 336 contains the system scripts, installed with Kakoune. 337 * `userconf`: located in `$XDG_CONFIG_HOME/kak/`, which will fallback 338 to `$HOME/.config/kak/` if `$XDG_CONFIG_HOME` is not set, containing 339 the user configuration. 340 341 Unless `-n` is specified, Kakoune will load its startup script located 342 at `${runtime}/kakrc` relative to the `kak` binary. This startup script 343 is responsible for loading the user configuration. 344 345 First, Kakoune will search recursively for `.kak` files in the `autoload` 346 directory. It will first look for an `autoload` directory at 347 `${userconf}/autoload` and will fallback to `${runtime}/autoload` if 348 it does not exist. 349 350 Once all those files are loaded, Kakoune will try to source 351 `${runtime}/kakrc.local`, which is expected to contain distribution provided 352 configuration. 353 354 Finally, the user configuration will load from `${userconf}/kakrc`. 355 356 NOTE: If you create a user `autoload` directory in `${userconf}/autoload`, 357 the system one at `${runtime}/autoload` will not load anymore. You can 358 add a symbolic link to it (or to individual scripts) inside 359 `${userconf}/autoload` to keep loading system scripts. 360 361 Basic Interaction 362 ----------------- 363 364 Selections 365 ~~~~~~~~~~ 366 367 The main concept in Kakoune is the selection. A selection is an inclusive, 368 directed range of characters. A selection has two ends, the anchor and the 369 cursor. 370 371 There is always at least one selection, and a selection is always at least 372 one character (in which case the anchor and cursor of the selection are 373 on the same character). 374 375 Normal Mode 376 ~~~~~~~~~~~ 377 378 In normal mode, keys are not inserted directly inside the buffer, but are editing 379 commands. These commands provide ways to manipulate either the selections themselves 380 or the selected text. 381 382 Insert Mode 383 ~~~~~~~~~~~ 384 385 When entering insert mode, keys are now directly inserted before each 386 selection's cursor. Some additional keys are recognised in insert mode: 387 388 * `<esc>`: leave insert mode 389 * `<backspace>`: delete characters before cursors 390 * `<del>`: delete characters under cursors 391 * `<left>, <right>, <up>, <down>`: move cursors in given direction 392 * `<home>`: move cursors to line beginning 393 * `<end>`: move cursors to line ending 394 395 * `<c-n>`: select next completion candidate 396 * `<c-p>`: select previous completion candidate 397 * `<c-x>`: explicit insert completion query, followed by: 398 - `f`: explicit file completion 399 - `w`: explicit word completion 400 - `l`: explicit line completion 401 * `<c-o>`: disable automatic completion for this insert session 402 403 * `<c-r>`: insert contents of the register given by next key 404 * `<c-v>`: insert next keystroke directly into the buffer, 405 without interpreting it 406 407 * `<c-u>`: commit changes up to now as a single undo group 408 409 * `<a-;>`: escape to normal mode for a single command 410 411 Movement 412 ~~~~~~~~ 413 414 See <<Appending>> below for instructions on extending (appending to) the current selection in order to select more text. 415 416 * `h`: select the character on the left of selection end 417 * `j`: select the character below the selection end 418 * `k`: select the character above the selection end 419 * `l`: select the character on the right of selection end 420 421 * `w`: select the word and following whitespaces on the right of selection end 422 * `b`: select preceding whitespaces and the word on the left of selection end 423 * `e`: select preceding whitespaces and the word on the right of selection end 424 * `<a-[wbe]>`: same as [wbe], but select WORD instead of word 425 426 * `f`: select to (including) the next occurrence of the given character 427 * `t`: select until (excluding) the next occurrence of the given character 428 * `<a-[ft]>`: same as [ft] but in the other direction 429 430 * `m`: select to matching character 431 * `M`: extend selection to matching character 432 433 * `x`: expand selections to contain full lines (including end-of-lines) 434 * `<a-x>`: trim selections to only contain full lines (including 435 end-of-lines) 436 437 * `%`: select whole buffer 438 439 * `<a-h>`: select to line begin 440 * `<a-l>`: select to line end 441 442 * `/`: search (select next match) 443 * `<a-/>`: search (select previous match) 444 * `?`: search (extend to next match) 445 * `<a-?>`: search (extend to previous match) 446 * `n`: select next match 447 * `N`: add a new selection with next match 448 * `<a-n>`: select previous match 449 * `<a-N>`: add a new selection with previous match 450 451 * `pageup, <c-b>`: scroll one page up 452 * `pagedown, <c-f>`: scroll one page down 453 * `<c-u>`: scroll half a page up 454 * `<c-d>`: scroll half a page down 455 456 * `)`: rotate selections (the main selection becomes the next one) 457 * `(`: rotate selections backwards 458 459 * `;`: reduce selections to their cursor 460 * `<a-;>`: flip the selections' direction 461 * `<a-:>`: ensure selections are in forward direction (cursor after anchor) 462 463 * `<a-.>`: repeat last object or `f`/`t` selection command. 464 465 * `_`: trim selections 466 467 A word is a sequence of alphanumeric characters or underscore, a WORD is a 468 sequence of non whitespace characters. 469 470 Appending 471 ~~~~~~~~~ 472 473 For most <<Movement>> commands, using `Shift` extends the current selection 474 instead of replacing it. 475 476 Examples: 477 478 * `wWW` selects 3 consecutive words: first `w` selects a word, then `WW` extends the selection two words further. 479 * `f/F/` selects up to and including the second `/` character forward. 480 481 Using Counts 482 ~~~~~~~~~~~~ 483 484 Most selection commands also support counts, which are entered before the 485 command itself. 486 487 For example, `3W` selects 3 consecutive words and `3w` select the third word on 488 the right of selection end. 489 490 Disabling Hooks 491 ~~~~~~~~~~~~~~~ 492 493 Any normal mode command can be prefixed with `\` which will disable hook execution 494 for the duration for the command (including the duration of modes the command could 495 move to, so `\i` will disable hooks for the whole insert session). 496 497 As autoindentation is implemented in terms of hooks, this can be used to disable 498 it when pasting text. 499 500 Changes 501 ~~~~~~~ 502 503 * `i`: enter insert mode before each selection 504 * `a`: enter insert mode after each selection 505 * `d`: yank and delete each selection 506 * `c`: yank and delete each selection and enter insert mode 507 * `.`: repeat last insert mode change (`i`, `a`, or `c`, including 508 the inserted text) 509 510 * `<a-d>`: delete each selection 511 * `<a-c>`: delete each selection and enter insert mode 512 513 * `I`: enter insert mode at each selection begin line start 514 * `A`: enter insert mode at each selection end line end 515 * `o`: enter insert mode in one (or given count) new lines below 516 each selection end 517 * `O`: enter insert mode in one (or given count) new lines above 518 each selection begin 519 520 * `<a-o>`: add an empty line below each cursor 521 * `<a-O>`: add an empty line above each cursor 522 523 * `y`: yank selections 524 * `p`: paste after each selection end 525 * `P`: paste before each selection begin 526 * `<a-p>`: paste all after each selection end 527 * `<a-P>`: paste all before each selection begin 528 * `R`: replace each selection with yanked text 529 * `<a-R>`: replace each selection with every yanked text 530 531 * `r`: replace each character with the next entered one 532 533 * `<a-j>`: join selected lines 534 * `<a-J>`: join selected lines and select spaces inserted 535 in place of line breaks 536 * `<a-_>`: merge contiguous selections together (works across lines as well) 537 538 * `<gt> (>)`: indent selected lines 539 * `<a-gt>`: indent selected lines, including empty lines 540 * `<lt> (<)`: deindent selected lines 541 * `<a-lt>`: deindent selected lines, do not remove incomplete 542 indent (3 leading spaces when indent is 4) 543 544 * `|`: pipe each selection through the given external filter program 545 and replace the selection with its output. 546 * `<a-|>`: pipe each selection through the given external filter program 547 and ignore its output 548 549 * `!`: insert command output before each selection 550 * `<a-!>`: append command output after each selection 551 552 * `u`: undo last change 553 * `<c-k>`: move backward in history 554 * `<a-u>`: undo selection changes 555 * `U`: redo last change 556 * `<c-j>`: move forward in history 557 * `<a-U>`: redo selection changes 558 559 * `&`: align selections, align the cursor of selections by inserting 560 spaces before the first character of the selection 561 * `<a-&>`: copy indent, copy the indentation of the main selection 562 (or the count one if a count is given) to all other ones 563 564 * ```: to lower case 565 * `~`: to upper case 566 * ``<a-`>``: swap case 567 568 * `@`: convert selected tabs to spaces, uses the buffer tabstop option or 569 the count parameter for tabstop. 570 * `<a-@>`: convert selected spaces to tabs, uses the buffer tabstop option 571 or the count parameter for tabstop. 572 573 * `<a-)>`: rotate selections content, if specified, the count groups 574 selections, so `3<a-)>` rotate (1, 2, 3) and (4, 5, 6) 575 independently. 576 * `<a-(>`: rotate selections content backwards 577 578 Goto Commands 579 ~~~~~~~~~~~~~ 580 581 Commands beginning with `g` are used to goto certain position and or buffer. 582 If a count is given prior to hitting `g`, `g` will jump to the given line. 583 Using `G` will extend the selection rather than jump. 584 585 See <<doc/pages/keys#goto-commands,`:doc keys goto-commands`>>. 586 587 View commands 588 ~~~~~~~~~~~~~ 589 590 Commands beginning with `v` permit to center or scroll the current 591 view. Using `V` will lock view mode until `<esc>` is hit 592 593 See <<doc/pages/keys#view-commands,`:doc keys view-commands`>>. 594 595 Marks 596 ~~~~~ 597 598 Current selections position can be saved in a register and restored later on. 599 600 See <<doc/pages/keys#marks,`:doc keys marks`>>. 601 602 Jump list 603 ~~~~~~~~~ 604 605 Some commands, like the goto commands, buffer switch or search commands, 606 push the previous selections to the client's jump list. 607 608 See <<doc/pages/keys#jump-list,`:doc keys jump-list`>>. 609 610 Multi Selection 611 ~~~~~~~~~~~~~~~ 612 613 Kak was designed from the start to handle multiple selections. 614 One way to get a multiselection is via the `s` key. 615 616 For example, to change all occurrences of word 'roger' to word 'marcel' 617 in a paragraph, here is what can be done: 618 619 * select the paragraph with `x` then enough `J` 620 * press `s` and enter roger, then enter 621 * now paragraph selection was replaced with multiselection of each roger in 622 the paragraph 623 * press `c` and marcel<esc> to replace rogers with marcels 624 625 A multiselection can also be obtained with `S`, which splits the current 626 selection according to the regex entered. To split a comma separated list, 627 use `S` then ', *' 628 629 The regex syntax supported by Kakoune is the based on the ECMAScript script 630 syntax and is described at <<doc/pages/regex#,`:doc regex`>>. 631 632 `s` and `S` share the search pattern with `/`, and hence entering an empty 633 pattern uses the last one. 634 635 As a convenience, `<a-s>` allows you to split the current selections on 636 line boundaries. 637 638 To clear multiple selections, use `,`. To keep only the nth selection 639 use `n` followed by `,`, in order to remove a selection, use `<a-,>`. 640 641 `<a-k>` allows you to enter a regex and keep only the selections that 642 contains a match for this regex. Using `<a-K>` you can keep the selections 643 not containing a match. 644 645 `C` duplicates selections on the lines that follow them, column-wise. 646 `<a-C>` does the same but on the preceding lines. 647 648 `$` allows you to enter a shell command and pipe each selection to it. 649 Selections whose shell command returns 0 will be kept, other will be dropped. 650 651 Object Selection 652 ~~~~~~~~~~~~~~~~ 653 654 Objects are specific portions of text, like sentences, paragraphs, numbers… 655 Kakoune offers many keys allowing you to select various text objects. 656 657 See <<doc/pages/keys#object-selection,`:doc keys object-selection`>>. 658 659 Commands 660 -------- 661 662 When pressing `:` in normal mode, Kakoune will open a prompt to enter a command. 663 664 Commands are used for non editing tasks, such as opening a buffer, writing the 665 current one, quitting, etc. 666 667 See <<doc/pages/keys#prompt-commands,`:doc keys prompt-commands`>>. 668 669 Basic Commands 670 ~~~~~~~~~~~~~~ 671 672 Some commands take an exclamation mark (`!`), which can be used to force 673 the execution of the command (i.e. to quit a modified buffer, the 674 command `q!` has to be used). 675 676 Commands starting with horizontal whitespace (e.g. a space) will not be 677 saved in the command history. 678 679 * `cd [<directory>]`: change the current directory to `<directory>`, or the home directory if unspecified 680 * `doc <topic>`: display documentation about a topic. The completion list 681 displays the available topics. 682 * `e[dit][!] <filename> [<line> [<column>]]`: open buffer on file, go to given 683 line and column. If file is already opened, just switch to this file. 684 Use edit! to force reloading. 685 * `w[rite][!] [<filename>]`: write buffer to <filename> or use its name if 686 filename is not given. If the file is write-protected, its 687 permissions are temporarily changed to allow saving the buffer and 688 restored afterwards when the write! command is used. 689 * `w[rite]a[ll]`: write all buffers that are associated to a file. 690 * `q[uit][!] [<exit status>]`: exit Kakoune, use quit! to force quitting even 691 if there is some unsaved buffers remaining. If specified, the client exit 692 status will be set to <exit status>. 693 * `w[a]q[!] [<exit status>]`: write the current buffer (or all buffers when 694 `waq` is used) and quit. If specified, the client exit status will be set 695 to <exit status>. 696 * `kill[!]`: terminate the current session, all the clients as well as the server, 697 use kill! to ignore unsaved buffers 698 * `b[uffer] <name>`: switch to buffer <name> 699 * `b[uffer]n[ext]`: switch to the next buffer 700 * `b[uffer]p[rev]`: switch to the previous buffer 701 * `d[el]b[uf][!] [<name>]`: delete the buffer <name> 702 * `source <filename>`: execute commands in <filename> 703 * `colorscheme <name>`: load named colorscheme. 704 * `rename-client <name>`: set current client name 705 * `rename-buffer <name>`: set current buffer name 706 * `rename-session <name>`: set current session name 707 * `echo [options] <text>`: show <text> in status line, with the following options: 708 ** `-markup`: expand the markup strings in <text> 709 ** `-debug`: print the given text to the `\*debug*` buffer 710 * `nop`: does nothing, but as with every other commands, arguments may be 711 evaluated. So nop can be used for example to execute a shell command 712 while being sure that its output will not be interpreted by kak. 713 `:%sh{ echo echo tchou }` will echo tchou in Kakoune, whereas 714 `:nop %sh{ echo echo tchou }` will not, but both will execute the 715 shell command. 716 * `fail <text>`: raise an error, uses <text> as its description 717 718 Multiple commands 719 ~~~~~~~~~~~~~~~~~ 720 721 Multiple commands can be separated either by new lines or by semicolons, 722 as such a semicolon must be escaped with `\;` to be considered as a literal 723 semicolon argument. 724 725 String syntax and expansions 726 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 727 728 Values, options and shell context can be interpolated in strings. 729 730 See <<doc/pages/expansions#,`:doc expansions`>>. 731 732 Configuration & Autoloading 733 --------------------------- 734 735 Kakrc 736 ~~~~~ 737 738 If not launched with the `-n` switch, Kakoune will source the 739 `../share/kak/kakrc` file relative to the `kak` binary, which 740 will source additional files: 741 742 If the `$XDG_CONFIG_HOME/kak/autoload` directory exists, load every 743 `*.kak` files in it, and load recursively any subdirectory. 744 745 If it does not exist, falls back to the site wide autoload directory 746 in `../share/kak/autoload/`. 747 748 After that, if it exists, source the `$XDG_CONFIG_HOME/kak/kakrc` file 749 which should be used for user configuration. 750 751 In order to continue autoloading site-wide files with a local autoload 752 directory, just add a symbolic link to `../share/kak/autoload/` into 753 your local autoload directory. 754 755 Color Schemes 756 ~~~~~~~~~~~~~ 757 758 Kakoune ships with some color schemes that are installed to 759 `../share/kak/colors/`. If `$XDG_CONFIG_HOME/kak/colors/` is present 760 the builtin command `colorscheme` will offer completion for those 761 color schemes. If a scheme is duplicated in userspace, it will take 762 precedence. 763 764 Options 765 ------- 766 767 Kakoune can store named and typed values that can be used both to 768 customize the core editor behaviour, and to keep data used by extension 769 scripts. 770 771 See <<doc/pages/options#,`:doc options`>>. 772 773 774 Advanced topics 775 --------------- 776 777 Faces 778 ~~~~~ 779 780 Faces describe how characters are displayed on the screen: color, bold, italic... 781 782 See <<doc/pages/faces#,`:doc faces`>>. 783 784 Registers 785 ~~~~~~~~~ 786 787 Registers are named lists of text. They are used for various purposes, 788 like storing the last yanked text, or the captured groups associated with the selections. 789 790 See <<doc/pages/registers#,`:doc registers`>>. 791 792 Macros 793 ~~~~~~ 794 795 Kakoune can record and replay a sequence of key presses. 796 797 See <<doc/pages/keys#macros,`:doc keys macros`>>. 798 799 Search selection 800 ~~~~~~~~~~~~~~~~ 801 802 Using the `*` key, you can set the search pattern to the current selection. 803 See <<doc/pages/keys#searching,`:doc keys searching`>>. 804 805 Regex syntax 806 ~~~~~~~~~~~~ 807 808 Kakoune regex syntax is based on the ECMAScript syntax (ECMA-262 standard). 809 It always runs on Unicode codepoint sequences, not on bytes. 810 811 See <<doc/pages/regex#,`:doc regex`>>. 812 813 Exec and Eval 814 ~~~~~~~~~~~~~ 815 816 The `execute-keys` and `evaluate-commands` are useful for scripting 817 in non interactive contexts. 818 819 See <<doc/pages/execeval#,`:doc execeval`>>. 820 821 Insert mode completion 822 ~~~~~~~~~~~~~~~~~~~~~~ 823 824 Kakoune can propose completions while inserting text: filenames, words, lines… 825 826 See <<doc/pages/keys#insert-mode-completion,`:doc keys insert-mode-completion`>>. 827 828 Escape to normal mode 829 ~~~~~~~~~~~~~~~~~~~~~ 830 831 From insert mode, pressing `<a-;>` allows you to execute a single normal mode 832 command. This provides a few advantages: 833 834 * The selections are not modified: when leaving insert mode using `<esc>` the 835 selections can change, for example when insert mode was entered with `a` the 836 cursor will go back one char. Or if on an end of line the cursor will go back 837 left (if possible). 838 839 * The modes are nested: that means the normal mode can enter prompt (with `:`), 840 or any other modes (using `:on-key` or `:menu` for example), and these modes 841 will get back to the insert mode afterwards. 842 843 This feature is tailored for scripting/macros, as it provides a more predictable 844 behaviour than leaving insert mode with `<esc>`, executing normal mode command 845 and entering back insert mode (with which binding ?) 846 847 See <<doc/pages/modes#,`:doc modes`>>. 848 849 Highlighters 850 ~~~~~~~~~~~~ 851 852 Manipulation of the displayed text, such as syntax coloration and wrapping 853 is done through highlighters. 854 855 See <<doc/pages/highlighters#,`:doc highlighters`>>. 856 857 Hooks 858 ~~~~~ 859 860 Commands can be registered to be executed when certain events arise with hooks. 861 862 See <<doc/pages/hooks#,`:doc hooks`>>. 863 864 Key Mapping 865 ~~~~~~~~~~~ 866 867 Custom key shortcuts can be registered through mappings. 868 869 See <<doc/pages/mapping#,`:doc mapping`>>. 870 871 Defining Commands and Aliases 872 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 873 874 New commands can be created using `:define-command`. 875 876 See <<doc/pages/commands#declaring-new-commands,`:doc commands declaring-new-commands`>>. 877 878 They can be given additional short names depending of the scope with `:alias`. 879 880 See <<doc/pages/commands#aliases,`:doc commands aliases`>>. 881 882 Some helper commands are available to define composite commands. 883 884 See <<doc/pages/commands#helpers,`:doc commands helpers`>>. 885 886 FIFO Buffers 887 ~~~~~~~~~~~ 888 889 FIFO buffers are very useful for running some commands asynchronously while 890 progressively displaying their result in Kakoune. 891 892 See <<doc/pages/buffers#fifo-buffers,`:doc buffers fifo-buffers`>>. 893 894 Credits 895 ------- 896 897 Thanks to https://github.com/p0nce[p0nce] for designing the 898 https://github.com/mawww/kakoune/blob/master/doc/kakoune_logo.svg[Kakoune 899 logo]. 900 901 And thanks to all the 902 https://github.com/mawww/kakoune/graphs/contributors[contributors] who help 903 move the project forward!