kakoune

Fork of kakoune, an acceptable text editor
git clone git://git.laack.co/kakoune.git
Log | Files | Refs

kak.1 (6015B)


      1 .Dd June 15, 2021
      2 .Dt KAK 1
      3 .Os
      4 .Sh NAME
      5 .Nm kak
      6 .Nd a vim-inspired, selection oriented code editor
      7 .
      8 .Sh SYNOPSIS
      9 .Nm
     10 .Op Fl d
     11 .Op Fl n
     12 .Op Fl ro
     13 .Op Fl c Ar session_id | Fl C Ar session_id | Fl s Ar session_id
     14 .Op Fl ui Ar ui_type
     15 .Op Fl e Ar command
     16 .Op Fl E Ar command
     17 .Op Sy + Ns Ar line Ns Oo Sy \&: Ns Ar column Oc | Sy +:
     18 .Op Ar file ...
     19 .
     20 .Nm
     21 .Fl f Ar keys
     22 .Op Fl q
     23 .Op Fl i Ar suffix
     24 .Op Ar file ...
     25 .
     26 .Nm
     27 .Fl p Ar session_id
     28 .
     29 .Nm
     30 .Fl l
     31 .Nm
     32 .Fl clear
     33 .
     34 .Nm
     35 .Fl version
     36 .
     37 .Nm
     38 .Fl help
     39 .
     40 .Sh DESCRIPTION
     41 .Sy Kakoune
     42 is a code editor heavily inspired by
     43 .Xr vim 1
     44 and
     45 .Xr vi 1 .
     46 As such, most of its commands are similar to
     47 .Xr vi 1 Ap s,
     48 sharing its
     49 .Dq keystrokes as a text editing language
     50 model.
     51 .Pp
     52 .Sy Kakoune
     53 operates in two modes, normal and insertion.
     54 In insertion mode, keys are directly inserted into the current buffer.
     55 In normal mode, keys are used to manipulate the current selection and to
     56 enter insertion mode.
     57 .Pp
     58 .Sy Kakoune
     59 has a strong focus on interactivity.
     60 Most commands provide immediate and incremental results, while still
     61 being competitive in keystroke count with vim.
     62 .Pp
     63 .Sy Kakoune
     64 works on selections, which are oriented, inclusive ranges of characters.
     65 Selections have an anchor and a cursor.
     66 Most commands move both of them except when extending selection, where
     67 the anchor character stays fixed and the cursor moves around.
     68 .Pp
     69 The options are as follows:
     70 .Bl -tag -width indent
     71 .It Fl help
     72 Display a help message and quit.
     73 .
     74 .It Fl version
     75 Display Kakoune version and quit.
     76 .
     77 .It Fl n
     78 Do not load the system's kakrc.
     79 .Pq often, Pa /usr/share/kak/kakrc
     80 .
     81 .It Fl l
     82 List existing sessions.
     83 .
     84 .It Fl d
     85 Run as a headless session
     86 .Pq requires Fl s .
     87 .
     88 .It Fl e Ar command
     89 Execute
     90 .Ar command
     91 after the client initialization phase.
     92 .
     93 .It Fl E Ar command
     94 Execute
     95 .Ar command
     96 after the server initialization phase.
     97 .
     98 .It Fl f Ar keys
     99 Run Kakoune in
    100 .Sq filter mode ,
    101 like
    102 .Xr sed 1 .
    103 For standard input and each file named on the command line,
    104 the whole buffer is selected
    105 (as with
    106 .Li % )
    107 then
    108 .Ar keys
    109 are executed.
    110 The filtered version of standard input
    111 is written to standard output.
    112 Any files mentioned on the command line
    113 are modified in-place,
    114 but if
    115 .Fl i
    116 is provided then Kakoune makes a backup of the original version.
    117 .
    118 .It Fl i Ar suffix
    119 Backup the files on which a filter is applied, using the given suffix.
    120 .
    121 .It Fl q
    122 When in
    123 .Sq filter mode ,
    124 don't print any errors
    125 .
    126 .It Fl p Ar session_id
    127 Send the commands written on the standard input to session
    128 .Ar session_id .
    129 .
    130 .It Fl c Ar session_id
    131 Connect to the given session
    132 .Ar session_id .
    133 .
    134 .It Fl C Ar session_id
    135 Connect to the given session
    136 .Ar session_id 
    137 or create it if it does not exist.
    138 .
    139 .It Fl s Ar session_id
    140 Set the current session name to
    141 .Ar session_id .
    142 .
    143 .It Fl ui Ar type
    144 Select the user interface type, which can be
    145 .Em terminal ,
    146 .Em dummy ,
    147 or
    148 .Em json .
    149 .
    150 .It Fl clear
    151 Remove sessions that were terminated in an incorrect state
    152 .Pq e.g. after a crash .
    153 .
    154 .It Fl ro
    155 Begin in
    156 .Em readonly mode ,
    157 all the buffers opened will not be written to disk.
    158 .
    159 .It Sy + Ns Ar line Ns Oo Sy \&: Ns Ar column Oc | Sy +:
    160 Specify a target line and column for the first file.
    161 When the plus sign is followed by only a colon, then the cursor is sent
    162 to the last line of the file.
    163 .
    164 .It Ar file ...
    165 One or more
    166 .Ar file(s)
    167 to edit.
    168 .El
    169 .
    170 .Sh ENVIRONMENT
    171 .Bl -tag -width 6n
    172 .It Ev KAKOUNE_POSIX_SHELL
    173 Overrides the POSIX shell used for
    174 .Em %sh{...}
    175 expansion, which is
    176 .Pa /bin/sh
    177 .Pq Xr sh 1
    178 if unset.
    179 .
    180 .It Ev KAKOUNE_CONFIG_DIR
    181 Overrides the location of the directory containing Kakoune user
    182 configuration.
    183 If unset,
    184 .Pa $XDG_CONFIG_HOME/kak
    185 is used.
    186 .
    187 .It Ev KAKOUNE_RUNTIME
    188 Overrides the location of the directory containing the Kakoune support files.
    189 If unset, location is determined from Kakoune's binary location.
    190 .
    191 .It Ev XDG_CONFIG_HOME
    192 Path to the user's configuration directory.
    193 If unset,
    194 .Pa $HOME/.config
    195 is used.
    196 .
    197 .It Ev XDG_RUNTIME_DIR
    198 Path to the user's session's sockets.
    199 If unset,
    200 .Pa $TMPDIR/kakoune
    201 is used.
    202 .El
    203 .
    204 .Sh FILES
    205 In the paths documented below,
    206 .Pa <rtdir>
    207 refers to the runtime directory, whose value is determined in relation
    208 to the path to
    209 .Nm Ap s
    210 binary location if 
    211 .Pa $KAKOUNE_RUNTIME
    212 is not set:
    213 .Pa <rtdir>
    214 =
    215 .Pa <path_to_kak_binary>/../share/kak .
    216 .
    217 .Pp
    218 If not started with the
    219 .Fl n
    220 switch,
    221 .Nm
    222 will first load
    223 .Pa <rtdir>/kakrc ,
    224 which will in turn load the following additional files:
    225 .
    226 .Bl -bullet
    227 .It
    228 If the
    229 .Pa $KAKOUNE_CONFIG_DIR/autoload
    230 directory exists, recursively load every
    231 .Pa *.kak
    232 file in it, and its sub-directories.
    233 .
    234 .It
    235 If it does not exist, fall back to the system-wide autoload directory in
    236 .Pa <rtdir>/autoload ,
    237 and recursively load all files in a similar way.
    238 .
    239 .It
    240 .Pa <rtdir>/kakrc.local ,
    241 if it exists; this is a user-defined system-wide configuration.
    242 .
    243 .It
    244 .Pa $KAKOUNE_CONFIG_DIR/kakrc ,
    245 if it exists; this is the user configuration.
    246 .
    247 .El
    248 .
    249 .Pp
    250 Consequently, if the
    251 .Pa $KAKOUNE_CONFIG_DIR/autoload
    252 directory exists, only scripts stored within that directory will be
    253 loaded \(em the built-in
    254 .Pa *.kak
    255 files will not be.
    256 .
    257 .Pp
    258 Users who still want the built-in scripts to be loaded along their own
    259 can create a symbolic link to
    260 .Pa <rtdir>/autoload
    261 .Pq or to individual scripts in it
    262 in their user-configuration directory:
    263 .
    264 .Pp
    265 .Dl ln -s \fI<rtdir>\fR/autoload "${XDG_CONFIG_HOME:-$HOME/.config}"/kak/autoload
    266 .
    267 .Sh EXAMPLES
    268 .Bl -tag -width 6n
    269 .It Edit a file:
    270 .Nm
    271 .Pa /path/to/file
    272 .
    273 .It Edit multiple files (multiple buffers will be created):
    274 .Nm
    275 .Pa ./file1.txt
    276 .Pa /path/to/file2.c
    277 .
    278 .It Prepend a modeline that sets the tabstop to multiple files:
    279 .Nm
    280 .Fl f Qq ggO// kak: tabstop=8<esc>
    281 .Pa *.c
    282 .El
    283 .
    284 .Sh SEE ALSO
    285 For the complete on-line documentation, use the
    286 .Ic :doc
    287 command after starting
    288 .Nm .
    289 .
    290 .Pp
    291 .Lk https://github.com/mawww/kakoune/wiki The Kakoune wiki .
    292 .Pp
    293 .Lk https://kakoune.org The main Kakoune web site .
    294 .Pp
    295 .Xr vi 1 ,
    296 .Xr vim 1 ,
    297 .Xr sam 1plan9 .
    298 .
    299 .Sh AUTHORS
    300 .An Maxime Coste Aq Mt frrrwww@gmail.com
    301 and many others.