# Options

**URL:** <https://discuss.kakoune.com/t/options/549>\
**Category:** Manual++\
**Created:** [May 8, 2019, 2:23am UTC](https://discuss.kakoune.com/t/options/549 "2019-05-08T02:23:59Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![robertmeta](https://discuss.kakoune.com/user_avatar/discuss.kakoune.com/robertmeta/32/833_2.png) [@robertmeta](https://discuss.kakoune.com/u/robertmeta)\
**Post date:** [May 8, 2019, 2:23am UTC](https://discuss.kakoune.com/t/options/549/1 "2019-05-08T02:23:59Z")

</div>

# Description

Kakoune can store named and typed values that can be used both to  
customize the core editor behaviour, and to store data used by extension  
scripts.

Options can be modified using the `set-option` command:

```
set-option [-add] <scope> <name> <values>...

```

\<scope\> can be **global** , **buffer** , **window** or **current**  
(See [`:doc scopes`](https://discuss.kakoune.com/t/scopes/552)). **current** relates to the narrowest  
scope in which the option is already set.

Multiple \<values\> can be given as separate arguments when the  
option is a list or map.

If `-add` is specified, the new value is **added** to the current one  
instead of replacing it (the exact outcome depends on the type, see  
below).

Options values can be unset in a specific scope with the `unset-option`  
command:

```
unset-option <scope> <name>

```

Unsetting an option will make it fallback to the value of its parent  
mode, hence options cannot be unset from the **global** scope.

New options can be declared using the `declare-option` command:

```
declare-option [-hidden] <type> <name> [<value>...]

```

If `-hidden` is specified, the option will not be displayed in  
completion suggestions.

Certain option type can be **updated** , usually to match potential  
changes in the buffer they relate to. This can be triggered by the  
`update-option` command:

```
update-option <scope> <name>

```

# Types

All options have a type, which defines how they are translated to/from  
text and their set of valid values.

Some types are usable for user defined options while some other types  
are exclusively available to built-in options.

**int**  
an integer number. `set -add` performs a math addition

**bool**  
a boolean value, yes/true or no/false

**str**  
a string, some freeform text

**regex**  
as a string but the set commands will complain if the entered text is  
not a valid regex

**coord**  
a line, column pair (separated by a comma) Cannot be used with  
`declare-option`

**\<type\>-list**  
a list, elements are specified as separate arguments to the command.  
`set -add` appends the new element to the list Only `int-list` and  
`str-list` options can be created with `declare-option`.

**range-specs**  
a timestamp (like `%val{timestamp}`, see  
[`:doc expansions value-expansions`](#expansions#value-expansions))  
followed by a list of range descriptors. Each range descriptor must use  
the syntax `a.b,c.d|string` or `a.b+length|string`, where _a_ is the  
line containing the first character, _b_ is the number of bytes from the  
start of the line to the first byte of the first character, _c_ is the  
line containing the last character, _d_ is the number of bytes from the  
start of the line to the first byte of the last character, _length_ is  
the length of the range in bytes and _string_ is an arbitrary string  
which is associated with the range. All numeric fields are 1-based. When  
the `update-option` is used on an option of this type, its ranges gets  
updated according to all the buffer modifications that happened since  
its timestamp. See  
[`:doc highlighters specs-highlighters`](#highlighters#specs-highlighters))  
`set -add` appends the new pair to the list

**line-specs**  
a list of a line number and a corresponding flag (`<line>|<flag text>`), except for the first element which is just the timestamp of  
the buffer. When the `update-option` is used on an option of this type,  
its lines gets updated according to all the buffer modifications that  
happened since its timestamp. See  
[`:doc highlighters specs-highlighters`](#highlighters#specs-highlighters))  
`set -add` appends the new spec to the list

**completions**  
a list of `<text>|<select cmd>|<menu text>` candidates, except for the  
first element which follows the `<line>.<column>[+<length>]@<timestamp>`  
format to define where the completion apply in the buffer.

```
Select commands are arbitrary kakoune commands that will be executed
each time the element is selected in the menu. The common use case is
to display element specific documentation.

Markup can be used in the menu text.
(see <<faces#markup-strings,`:doc faces markup-strings`>>)

`set -add` adds a new completion to the list

```

**enum(value1|value2|…)**  
an enum, taking one of the given values Cannot be used with  
`declare-option`

**flags(value1|value2|…)**  
a set of flags, taking a combination of the given values joined by a _|_  
character. `set -add` adds the new flag to the combination Cannot be  
used with `declare-option`

**\<type\>-to-\<type\>-map**  
a list of `key=value` pairs. `set -add` adds the new pair to the hashmap  
or replace an already existing key. Only `str-to-str-map` options can be  
created with `declare-option`.

# Builtin options

**tabstop** `int`  
_default_ 8  
width of a tab character

**indentwidth** `int`  
_default_ 4  
width (in spaces) used for indentation, 0 means a tab character

**scrolloff** `coord`  
_default_ 0,0  
number of lines, columns to keep visible around the cursor when  
scrolling

**eolformat** `enum(lf|crlf)`  
_default_ lf  
the format of end of lines when writing a buffer, this is autodetected  
on load; values of this option assigned to the `window` scope are  
ignored

**BOM** `enum(none|utf8)`  
_default_ none  
define if the file should be written with a unicode byte order mark;  
values of this option assigned to the `window` scope are ignored

**readonly** `bool`  
_default_ false  
prevent modifications from being saved to disk, all buffers if set to  
`true` in the `global` scope, or current buffer if set in the `buffer`  
scope; values of this option assigned to the `window` scope are ignored

**incsearch** `bool`  
_default_ true  
execute search as it is typed

**aligntab** `bool`  
_default_ false  
use tabs for alignment command

**autoinfo** `flags(command|onkey|normal)`  
_default_ command|onkey  
display automatic information box in the enabled contexts

**autocomplete** `flags(insert|prompt)`  
_default_ insert|prompt  
automatically display possible completions in the enabled modes.

**ignored\_files** `regex`  
filenames matching this regex won’t be considered as candidates on  
filename completion (except if the text being completed already matches  
it)

**disabled\_hooks** `regex`  
hooks whose group matches this regex won’t be executed. For example  
indentation hooks can be disabled with `.*-indent`. (See  
[`:doc hooks`](#hooks#disabling-hooks))

**filetype** `str`  
arbitrary string defining the type of the file. Filetype dependent  
actions should hook on this option changing for activation/deactivation

**path** `str-list`  
_default_ ./ %/ /usr/include  
directories to search for **gf** command and filenames completion `%/`  
represents the current buffer directory

**completers** `completer-list`  
_default_ filename word=all  
completion engines to use for insert mode completion (they are tried in  
order until one generates candidates). Existing completers are:

**word=all** , **word=buffer**  
which complete using words in all buffers ( **word=all** ) or only the  
current one ( **word=buffer** )

**filename**  
which tries to detect when a filename is being entered and provides  
completion based on local filesystem

**line**  
which complete using lines in current buffer

**option=\<opt-name\>**  
where **opt-name** is an option of type _completions_ whose contents  
will be used

**static\_words** `str-list`  
list of words that are always added to completion candidates when  
completing words in insert mode

**extra\_word\_chars** `codepoint-list`  
a list of all additional codepoints that should be considered as word  
character.

**matching\_pairs** `codepoint-list`  
_default_ ( ) { } [] \< \>  
a list of codepoints that are to be treated as matching pairs for the  
**m** command.

**autoreload** `enum(yes|no|ask)`  
_default_ ask  
auto reload the buffers when an external modification is detected

**writemethod** `enum(overwrite|replace)`  
_default_ overwrite  
method used to write buffers to file, `overwrite` will open the existing  
file and write on top of the previous data, `replace` will open a  
temporary file next to the target file, write it and then rename it to  
the target file.

**debug** `flags(hooks|shell|profile|keys|commands)`  
dump various debug information in the _\*debug\*_ buffer

**idle\_timeout** `int`  
_default_ 50  
timeout, in milliseconds, with no user input that will trigger the  
**PromptIdle** , **InsertIdle** and **NormalIdle** hooks, and  
autocompletion.

**fs\_checkout\_timeout** `int`  
_default_ 500  
timeout, in milliseconds, between checks in normal mode of modifications  
of the file associated with the current buffer on the filesystem.

**modelinefmt** `string`  
A format string used to generate the mode line, that string is first  
expanded as a command line would be (expanding _%…{…}_ strings), then  
markup tags are applied (see  
[`:doc faces markup-strings`](#faces#markup-strings)) Two special atoms  
are available as markup:

**`{{mode_info}}`**  
Information about the current mode, such as `insert 3 sel` or `prompt`.  
The faces used are StatusLineMode, StatusLineInfo, and StatusLineValue.

**`{{context_info}}`**  
Information such as `[+][recording (@)][no-hooks][new file][fifo]`, in  
face Information.

```
The default value is '%val{bufname} %val{cursor_line}:%val{cursor_char_column} {{context_info}} {{mode_info}} - %val{client}@[%val{session}]'

```

**ui\_options** `str-to-str-map`  
a list of `key=value` pairs that are forwarded to the user interface  
implementation. The NCurses UI support the following options:

**ncurses\_set\_title**  
if **yes** or **true** , the terminal emulator title will be changed

**ncurses\_status\_on\_top**  
if **yes** , or **true** the status line will be placed at the top of the  
terminal rather than at the bottom

**ncurses\_assistant**  
specify the nice assistant displayed in info boxes, can be **clippy**  
(the default), **cat** , **dilbert** or **none**

**ncurses\_enable\_mouse**  
boolean option that enables mouse support

**ncurses\_change\_colors**  
boolean option that can disable color palette changing if the terminfo  
enables it but the terminal does not support it.

**ncurses\_wheel\_down\_button** , **ncurses\_wheel\_up\_button**  
specify which button send for wheel down/up events

**ncurses\_shift\_function\_key**  
Function key from which shifted function key start, if the terminal  
sends F13 for \<s-F1\>, this should be set to 12.

**ncurses\_builtin\_key\_parser**  
Bypass ncurses key parser and use an internal one.

**startup\_info\_version** `int`  
_default_ 0  
Controls which messages will be displayed in the startup info box, only  
messages relating to a Kakoune version greater than this value will be  
displayed. Versions are written as a single number: Like `20180413` for  
version `2018.04.13`

# Current values

The current value for an option can be viewed using  
[`:doc expansions option-expansions`](https://discuss.kakoune.com/t/expansions/540#option-expansions).

For example, the current value of the `BOM` option can be displayed in  
the status line using the `echo` command:

```
echo %opt{BOM}

```

The current values for all options can be dumped to the  
**\*debug** \* buffer using the following command:

```
debug options
```
