*options.txt* Nvim

VIM REFERENCE MANUAL by Bram Moolenaar

Options *options*

For an overview of options see quickref.txt |option-list|.

Vim has a number of internal variables and switches which can be set to

achieve special effects. These options come in three forms:

boolean can only be on or off *boolean* *toggle*

number has a numeric value

string has a string value

Type |gO| to see the table of contents.

==============================================================================

1. Setting options *set-option* *E764*

*:se* *:set*

:se[t][!] Show all options that differ from their default value.

When [!] is present every option is on a separate

line.

:se[t][!] all Show all options.

When [!] is present every option is on a separate

line.

*E518* *E519*

:se[t] {option}? Show value of {option}.

NOTE: some legacy options were removed. |nvim-removed|

:se[t] {option} Toggle option: set, switch it on.

Number option: show value.

String option: show value.

:se[t] no{option} Toggle option: Reset, switch it off.

*:set-!* *:set-inv*

:se[t] {option}! or

:se[t] inv{option} Toggle option: Invert value.

*:set-default* *:set-&* *:set-&vi* *:set-&vim*

:se[t] {option}& Reset option to its default value.

:se[t] {option}&vi Reset option to its Vi default value.

:se[t] {option}&vim Reset option to its Vim default value.

:se[t] all& Set all options to their default value. The values of

these options are not changed:

'columns'

'lines'

Warning: This may have a lot of side effects.

*:set-args* *:set=* *E487* *E521*

:se[t] {option}={value} or

:se[t] {option}:{value}

Set string or number option to {value}.

For numeric options the value can be given in decimal,

hex (preceded with 0x) or octal (preceded with '0' or

'0o').

The old value can be inserted by typing 'wildchar' (by

default this is a <Tab>). Many string options with

fixed syntax also support completing known values.

See |cmdline-completion| and |complete-set-option|.

White space between {option} and '=' is allowed and

will be ignored. White space between '=' and {value}

is not allowed.

See |option-backslash| for using white space and

backslashes in {value}.

:se[t] {option}+={value} *:set+=*

Add the {value} to a number option, or append the

{value} to a string option. When the option is a

comma-separated list, a comma is added, unless the

value was empty.

If the option is a list of flags, superfluous flags

are removed. When adding a flag that was already

present the option value doesn't change.

Also see |:set-args| above.

:se[t] {option}^={value} *:set^=*

Multiply the {value} to a number option, or prepend

the {value} to a string option. When the option is a

comma-separated list, a comma is added, unless the

value was empty.

Also see |:set-args| above.

:se[t] {option}-={value} *:set-=*

Subtract the {value} from a number option, or remove

the {value} from a string option, if it is there.

If the {value} is not found in a string option, there

is no error or warning. When the option is a comma-

separated list, a comma is deleted, unless the option

becomes empty.

When the option is a list of flags, {value} must be

exactly as they appear in the option. Remove flags

one by one to avoid problems.

The individual values from a comma separated list or

list of flags can be inserted by typing 'wildchar'.

See |complete-set-option|.

Also see |:set-args| above.

The {option} arguments to ":set" may be repeated. For example: >

:set ai nosi sw=3 ts=3

If you make an error in one of the arguments, an error message will be given

and the following arguments will be ignored.

*:set-verbose*

When 'verbose' is non-zero, displaying an option value will also tell where it

was last set. Example: >

:verbose set shiftwidth cindent?

< shiftwidth=4 ~

Last set from modeline line 1 ~

cindent ~

Last set from /usr/local/share/vim/vim60/ftplugin/c.vim line 30 ~

This is only done when specific option values are requested, not for ":verbose

set all" or ":verbose set" without an argument.

When the option was set by hand there is no "Last set" message.

When the option was set while executing a function, user command or

autocommand, the script in which it was defined is reported.

A few special texts:

Last set from modeline line 1 ~

Option was set in a |modeline|.

Last set from --cmd argument ~

Option was set with command line argument |--cmd| or +.

Last set from -c argument ~

Option was set with command line argument |-c|, +, |-S| or

|-q|.

Last set from environment variable ~

Option was set from $VIMINIT.

Last set from error handler ~

Option was cleared when evaluating it resulted in an error.

*option-backslash*

To include white space in a string option value it has to be preceded with a

backslash. To include a backslash you have to use two. Effectively this

means that the number of backslashes in an option value is halved (rounded

down).

In options 'path', 'cdpath', and 'tags', spaces have to be preceded with three

backslashes instead because they can be separated by either commas or spaces.

Comma-separated options like 'backupdir' and 'tags' will also require commas

to be escaped with two backslashes, whereas this is not needed for

non-comma-separated ones like 'makeprg'.

When setting options using |:let| and |literal-string|, you need to use one

fewer layer of backslash.

A few examples: >

:set makeprg=make\ file results in "make file"

:let &makeprg='make file' (same as above)

:set makeprg=make\\\ file results in "make\ file"

:set tags=tags\ /usr/tags results in "tags" and "/usr/tags"

:set tags=tags\\\ file results in "tags file"

:let &tags='tags\ file' (same as above)

:set makeprg=make,file results in "make,file"

:set makeprg=make\\,file results in "make\,file"

:set tags=tags,file results in "tags" and "file"

:set tags=tags\\,file results in "tags,file"

:let &tags='tags\,file' (same as above)

The "|" character separates a ":set" command from a following command. To

include the "|" in the option value, use "\|" instead. This example sets the

'titlestring' option to "hi|there": >

:set titlestring=hi\|there

This sets the 'titlestring' option to "hi" and 'iconstring' to "there": >

:set titlestring=hi|set iconstring=there

Similarly, the double quote character starts a comment. To include the '"' in

the option value, use '\"' instead. This example sets the 'titlestring'

option to "hi "there"": >

:set titlestring=hi\ \"there\"

For Win32 backslashes in file names are mostly not removed. More precise: For

options that expect a file name (those where environment variables are

expanded) a backslash before a normal file name character is not removed. But

a backslash before a special character (space, backslash, comma, etc.) is used

like explained above.

There is one special situation, when the value starts with "\\": >

:set dir=\\machine\path results in "\\machine\path"

:set dir=\\\\machine\\path results in "\\machine\path"

:set dir=\\path\\file results in "\\path\file" (wrong!)

For the first one the start is kept, but for the second one the backslashes

are halved. This makes sure it works both when you expect backslashes to be

halved and when you expect the backslashes to be kept. The third gives a

result which is probably not what you want. Avoid it.

*add-option-flags* *remove-option-flags*

*E539*

Some options are a list of flags. When you want to add a flag to such an

option, without changing the existing ones, you can do it like this: >

:set guioptions+=a

Remove a flag from an option like this: >

:set guioptions-=a

This removes the 'a' flag from 'guioptions'.

Note that you should add or remove one flag at a time. If 'guioptions' has

the value "ab", using "set guioptions-=ba" won't work, because the string "ba"

doesn't appear.

*:set_env* *expand-env* *expand-environment-var*

Environment variables in specific string options will be expanded. If the

environment variable exists the '$' and the following environment variable

name is replaced with its value. If it does not exist the '$' and the name

are not modified. Any non-id character (not a letter, digit or '_') may

follow the environment variable name. That character and what follows is

appended to the value of the environment variable. Examples: >

:set term=$TERM.new

:set path=/usr/$INCLUDE,$HOME/include,.

When adding or removing a string from an option with ":set opt-=val" or ":set

opt+=val" the expansion is done before the adding or removing.

Handling of local options *local-options*

Note: The following also applies to |global-local| options.

Some of the options only apply to a window or buffer. Each window or buffer

has its own copy of this option, thus each can have its own value. This

allows you to set 'list' in one window but not in another. And set

'shiftwidth' to 3 in one buffer and 4 in another.

The following explains what happens to these local options in specific

situations. You don't really need to know all of this, since Vim mostly uses

the option values you would expect. Unfortunately, doing what the user

expects is a bit complicated...

When splitting a window, the local options are copied to the new window. Thus

right after the split the contents of the two windows look the same.

When editing a new buffer, its local option values must be initialized. Since

the local options of the current buffer might be specifically for that buffer,

these are not used. Instead, for each buffer-local option there also is a

global value, which is used for new buffers. With ":set" both the local and

global value is changed. With "setlocal" only the local value is changed,

thus this value is not used when editing a new buffer.

When editing a buffer that has been edited before, the options from the window

that was last closed are used again. If this buffer has been edited in this

window, the values from back then are used. Otherwise the values from the

last closed window where the buffer was edited last are used.

It's possible to set a local window option specifically for a type of buffer.

When you edit another buffer in the same window, you don't want to keep

using these local window options. Therefore Vim keeps a global value of the

local window options, which is used when editing another buffer. Each window

has its own copy of these values. Thus these are local to the window, but

global to all buffers in the window. With this you can do: >

:e one

:set list

:e two

Now the 'list' option will also be set in "two", since with the ":set list"

command you have also set the global value. >

:set nolist

:e one

:setlocal list

:e two

Now the 'list' option is not set, because ":set nolist" resets the global

value, ":setlocal list" only changes the local value and ":e two" gets the

global value. Note that if you do this next: >

:e one

You will get back the 'list' value as it was the last time you edited "one".

The options local to a window are remembered for each buffer. This also

happens when the buffer is not loaded, but they are lost when the buffer is

wiped out |:bwipe|.

Special local window options *local-noglobal*

The following local window options won't be copied over when new windows are

created, thus they behave slightly differently:

Option Reason ~

'previewwindow' there can only be a single one

'scroll' specific to existing window

'winfixbuf' specific to existing window

'winfixheight' specific to existing window

'winfixwidth' specific to existing window

Special local buffer options

The following local buffer options won't be copied over when new buffers are

created, thus they behave slightly differently:

Option Reason ~

'filetype' explicitly set by autocommands

'syntax' explicitly set by autocommands

'bufhidden' denote |special-buffers|

'buftype' denote |special-buffers|

'readonly' will be detected automatically

'modified' will be detected automatically

*:setl* *:setlocal*

:setl[ocal][!] ... Like ":set" but set only the value local to the

current buffer or window. Not all options have a

local value. If the option does not have a local

value the global value is set.

With the "all" argument: display local values for all

local options.

Without argument: Display local values for all local

options which are different from the default.

When displaying a specific local option, show the

local value. For a global/local boolean option, when

the global value is being used, "--" is displayed

before the option name.

For a global option the global value is

shown (but that might change in the future).

:se[t] {option}< Set the effective value of {option} to its global

value.

For |global-local| options, the local value is removed,

so that the global value will be used.

For all other options, the global value is copied to

the local value.

:setl[ocal] {option}< Set the effective value of {option} to its global

value by copying the global value to the local value.

Note that the behaviour for |global-local| options is slightly different

between string and number-based options.

*:setg* *:setglobal*

:setg[lobal][!] ... Like ":set" but set only the global value for a local

option without changing the local value.

When displaying an option, the global value is shown.

With the "all" argument: display global values for all

local options.

Without argument: display global values for all local

options which are different from the default.

For buffer-local and window-local options:

Command global value local value condition ~

:set option=value set set

:setlocal option=value - set

:setglobal option=value set -

:set option? - display local value is set

:set option? display - local value is not set

:setlocal option? - display

:setglobal option? display -

Global options with a local value *global-local*

Options are global when you mostly use one value for all buffers and windows.

For some global options it's useful to sometimes have a different local value.

You can set the local value with ":setlocal". That buffer or window will then

use the local value, while other buffers and windows continue using the global

value.

For example, you have two windows, both on C source code. They use the global

'makeprg' option. If you do this in one of the two windows: >

:set makeprg=gmake

then the other window will switch to the same value. There is no need to set

the 'makeprg' option in the other C source window too.

However, if you start editing a Perl file in a new window, you want to use

another 'makeprg' for it, without changing the value used for the C source

files. You use this command: >

:setlocal makeprg=perlmake

You can switch back to using the global value by making the local value empty: >

:setlocal makeprg=

This only works for a string option. For a number or boolean option you need

to use the "<" flag, like this: >

:setlocal autoread<

Note that for non-boolean and non-number options using "<" copies the global

value to the local value, it doesn't switch back to using the global value

(that matters when the global value changes later). You can also use: >

:set path<

This will make the local value of 'path' empty, so that the global value is

used. Thus it does the same as: >

:setlocal path=

Note: In the future more global options can be made |global-local|. Using

":setlocal" on a global option might work differently then.

*option-value-function*

Some options ('completefunc', 'findfunc', 'omnifunc', 'operatorfunc',

'quickfixtextfunc', 'tagfunc' and 'thesaurusfunc') are set to a function name

or a function reference or a lambda function. When using a lambda it will be

converted to the name, e.g. "<lambda>123".

Examples:

>

set opfunc=MyOpFunc

set opfunc=function('MyOpFunc')

set opfunc=funcref('MyOpFunc')

set opfunc={a\ ->\ MyOpFunc(a)}

Set to a script-local function: >

set opfunc=s:MyLocalFunc

set opfunc=<SID>MyLocalFunc

Set using a funcref variable: >

let Fn = function('MyTagFunc')

let &tagfunc = Fn

Set using a lambda expression: >

let &tagfunc = {t -> MyTagFunc(t)}

Set using a variable with lambda expression: >

let L = {a, b, c -> MyTagFunc(a, b , c)}

let &tagfunc = L

Calling a function in an expr option *expr-option-function*

The value of a few options, such as 'foldexpr', is an expression that is

evaluated to get a value. The evaluation can have quite a bit of overhead.

One way to minimize the overhead, and also to keep the option value very

simple, is to define a function and set the option to call it without

arguments. A |v:lua-call| can also be used. Example: >vim

lua << EOF

function _G.MyFoldFunc()

-- ... compute fold level for line v:lnum

return level

end

EOF

set foldexpr=v:lua.MyFoldFunc()

Setting the filetype

:setf[iletype] [FALLBACK] {filetype} *:setf* *:setfiletype*

Set the 'filetype' option to {filetype}, but only if

not done yet in a sequence of (nested) autocommands.

This is short for: >

:if !did_filetype()

: setlocal filetype={filetype}

:endif

< This command is used in a filetype.vim file to avoid

setting the 'filetype' option twice, causing different

settings and syntax files to be loaded.

When the optional FALLBACK argument is present, a

later :setfiletype command will override the

'filetype'. This is to be used for filetype

detections that are just a guess. |did_filetype()|

will return false after this command.

*option-window* *optwin*

:bro[wse] se[t] *:set-browse* *:browse-set* *:opt* *:options*

:opt[ions] Open a window for viewing and setting all options.

Options are grouped by function.

Offers short help for each option. Hit <CR> on the

short help to open a help window with more help for

the option.

Modify the value of the option and hit <CR> on the

"set" line to set the new value. For window and

buffer specific options, the last accessed window is

used to set the option value in, unless this is a help

window, in which case the window below help window is

used (skipping the option-window).

*$HOME*

Using "~" is like using "$HOME", but it is only recognized at the start of an

option and after a space or comma.

On Unix systems "~user" can be used too. It is replaced by the home directory

of user "user". Example: >

:set path=~mool/include,/usr/include,.

On Unix systems the form "${HOME}" can be used too. The name between {} can

contain non-id characters then. Note that if you want to use this for the

"gf" command, you need to add the '{' and '}' characters to 'isfname'.

NOTE: expanding environment variables and "~/" is only done with the ":set"

command, not when assigning a value to an option with ":let".

*$HOME-windows*

On MS-Windows, if $HOME is not defined as an environment variable, then

at runtime Vim will set it to the expansion of $HOMEDRIVE$HOMEPATH.

If $HOMEDRIVE is not set then $USERPROFILE is used.

This expanded value is not exported to the environment, this matters when

running an external command: >

:echo system('set | findstr ^HOME=')

and >

:echo luaeval('os.getenv("HOME")')

should echo nothing (an empty string) despite exists('$HOME') being true.

When setting $HOME to a non-empty string it will be exported to the

subprocesses.

Note the maximum length of an expanded option is limited. How much depends on

the system, mostly it is something like 256 or 1024 characters.

==============================================================================

2. Automatically setting options *auto-setting*

Besides changing options with the ":set" command, you can set options

automatically in various ways:

1. With a |config| file or a |startup| argument. You can create an

initialization file with |:mkvimrc|, |:mkview| and |:mksession|.

2. |autocommand|s executed when you edit a file.

3. ".nvim.lua" files in the current directory, if 'exrc' is enabled.

4. |editorconfig| in the current buffer's directory or ancestors.

5. 'modeline' settings found at the beginning or end of the file. See below.

*modeline* *vim:* *vi:* *ex:* *E520*

There are two forms of modelines. The first form:

[text{white}]{vi:|vim:|ex:}[white]{options}

[text{white}] empty or any text followed by at least one blank

character (<Space> or <Tab>); "ex:" always requires at

least one blank character

{vi:|vim:|ex:} the string "vi:", "vim:" or "ex:"

[white] optional white space

{options} a list of option settings, separated with white space

or ':', where each part between ':' is the argument

for a ":set" command (can be empty)

Examples:

vi:noai:sw=3 ts=6 ~

vim: tw=77 ~

The second form (this is compatible with some versions of Vi):

[text{white}]{vi:|vim:|Vim:|ex:}[white]se[t] {options}:[text]

[text{white}] empty or any text followed by at least one blank

character (<Space> or <Tab>); "ex:" always requires at

least one blank character

{vi:|vim:|Vim:|ex:} the string "vi:", "vim:", "Vim:" or "ex:"

[white] optional white space

se[t] the string "set " or "se " (note the space); When

"Vim" is used it must be "set".

{options} a list of options, separated with white space, which

is the argument for a ":set" command

: a colon

[text] any text or empty

Examples: >

/* vim: set ai tw=75: */

/* Vim: set ai tw=75: */

The white space before {vi:|vim:|Vim:|ex:} is required. This minimizes the

chance that a normal word like "lex:" is caught. There is one exception:

"vi:" and "vim:" can also be at the start of the line (for compatibility with

version 3.0). Using "ex:" at the start of the line will be ignored (this

could be short for "example:").

If the modeline is disabled within a modeline, subsequent modelines will be

ignored. This is to allow turning off modeline on a per-file basis. This is

useful when a line looks like a modeline but isn't. For example, it would be

good to start a YAML file containing strings like "vim:" with

# vim: nomodeline ~

so as to avoid modeline misdetection. Following options on the same line

after modeline deactivation, if any, are still evaluated (but you would

normally not have any).

*modeline-local*

The options are set like with ":setlocal": The new value only applies to the

buffer and window that contain the file. Although it's possible to set global

options from a modeline, this is unusual. If you have two windows open and

the files in it set the same global option to a different value, the result

depends on which one was opened last.

When editing a file that was already loaded, only the window-local options

from the modeline are used. Thus if you manually changed a buffer-local

option after opening the file, it won't be changed if you edit the same buffer

in another window. But window-local options will be set.

*modeline-version*

If the modeline is only to be used for some versions of Vim, the version

number can be specified where "vim:" or "Vim:" is used:

vim{vers}: version {vers} or later

vim<{vers}: version before {vers}

vim={vers}: version {vers}

vim>{vers}: version after {vers}

{vers} is 700 for Vim 7.0 (hundred times the major version plus minor).

For example, to use a modeline only for Vim 7.0: >

/* vim700: set foldmethod=marker */

To use a modeline for Vim after version 7.2: >

/* vim>702: set cole=2: */

There can be no blanks between "vim" and the ":".

The modeline is ignored if {vers} does not fit in an integer.

The number of lines that are checked can be set with the 'modelines' option.

If 'modeline' is off or 'modelines' is 0 no lines are checked.

Note that for the first form all of the rest of the line is used, thus a line

like: >

/* vi:ts=4: */

will give an error message for the trailing "*/". This line is OK: >

/* vi:set ts=4: */

If an error is detected the rest of the line is skipped.

If you want to include a ':' in a set command precede it with a '\'. The

backslash in front of the ':' will be removed. Example: >

/* vi:set fillchars=stl\:^,vert\:\|: */

This sets the 'fillchars' option to "stl:^,vert:\|". Only a single backslash

before the ':' is removed. Thus to include "\:" you have to specify "\\:".

*E992*

No other commands than "set" are supported, for security reasons (somebody

might create a Trojan horse text file with modelines). And not all options

can be set. For some options a flag is set, so that when the value is used

the |sandbox| is effective. Some options can only be set from the modeline

when 'modelineexpr' is set (the default is off).

Still, there is always a small risk that a modeline causes trouble. E.g.,

when some joker sets 'textwidth' to 5 all your lines are wrapped unexpectedly.

So disable modelines before editing untrusted text. The mail ftplugin does

this, for example.

Hint: If you would like to do something else than setting an option, you could

define an autocommand that checks the file for a specific string. For

example: >

au BufReadPost * if getline(1) =~ "VAR" | call SetVar() | endif

And define a function SetVar() that does something with the line containing

"VAR".

==============================================================================

3. Options summary *option-summary*

In the list below all the options are mentioned with their full name and with

an abbreviation if there is one. Both forms may be used.

In this document when a boolean option is "set" that means that ":set option"

is entered. When an option is "reset", ":set nooption" is used.

Most options are the same in all windows and buffers. There are a few that

are specific to how the text is presented in a window. These can be set to a

different value in each window. For example the 'list' option can be set in

one window and reset in another for the same text, giving both types of view

at the same time. There are a few options that are specific to a certain

file. These can have a different value for each file or buffer. For example

the 'textwidth' option can be 78 for a normal text file and 0 for a C

program.

global one option for all buffers and windows

local to window each window has its own copy of this option

local to buffer each buffer has its own copy of this option

When creating a new window the option values from the currently active window

are used as a default value for the window-specific options. For the

buffer-specific options this depends on the 's' and 'S' flags in the

'cpoptions' option. If 's' is included (which is the default) the values for

buffer options are copied from the currently active buffer when a buffer is

first entered. If 'S' is present the options are copied each time the buffer

is entered, this is almost like having global options. If 's' and 'S' are not

present, the options are copied from the currently active buffer when the

buffer is created.

Hidden options *hidden-options*

Not all options are supported in all versions. This depends on the supported

features and sometimes on the system. A remark about this is in curly braces

below. When an option is not supported, it is called a hidden option. Trying

to get the value of a hidden option will not give an error, it will return the

default value for that option instead. You can't change the value of a hidden

option.

To test if "foo" is a valid option name, use something like this: >

if exists('&foo')

This also returns true for a hidden option. To test if option "foo" is really

supported use something like this: >

if exists('+foo')

<

*E355*

A jump table for the options with a short description can be found at |Q_op|.

*'allowrevins'* *'ari'* *'noallowrevins'* *'noari'*

'allowrevins' 'ari' boolean (default off)

global

Allow CTRL-_ in Insert mode. This is default off, to avoid that users

that accidentally type CTRL-_ instead of SHIFT-_ get into reverse

Insert mode, and don't know how to get out. See 'revins'.

*'ambiwidth'* *'ambw'*

'ambiwidth' 'ambw' string (default "single")

global

Tells Vim what to do with characters with East Asian Width Class

Ambiguous (such as Euro, Registered Sign, Copyright Sign, Greek

letters, Cyrillic letters).

There are currently two possible values:

"single": Use the same width as characters in US-ASCII. This is

expected by most users.

"double": Use twice the width of ASCII characters.

*E834* *E835*

The value "double" cannot be used if 'listchars' or 'fillchars'

contains a character that would be double width. These errors may

also be given when calling setcellwidths().

The values are overruled for characters specified with

|setcellwidths()|.

There are a number of CJK fonts for which the width of glyphs for

those characters are solely based on how many octets they take in

legacy/traditional CJK encodings. In those encodings, Euro,

Registered sign, Greek/Cyrillic letters are represented by two octets,

therefore those fonts have "wide" glyphs for them. This is also

true of some line drawing characters used to make tables in text

file. Therefore, when a CJK font is used for GUI Vim or

Vim is running inside a terminal (emulators) that uses a CJK font

(or Vim is run inside an xterm invoked with "-cjkwidth" option.),

this option should be set to "double" to match the width perceived

by Vim with the width of glyphs in the font. Perhaps it also has

to be set to "double" under CJK MS-Windows when the system locale is

set to one of CJK locales. See Unicode Standard Annex #11

(https://www.unicode.org/reports/tr11).

*'arabic'* *'arab'* *'noarabic'* *'noarab'*

'arabic' 'arab' boolean (default off)

local to window

This option can be set to start editing Arabic text.

Setting this option will:

- Set the 'rightleft' option, unless 'termbidi' is set.

- Set the 'arabicshape' option, unless 'termbidi' is set.

- Set the 'keymap' option to "arabic"; in Insert mode CTRL-^ toggles

between typing English and Arabic key mapping.

- Set the 'delcombine' option

Resetting this option will:

- Reset the 'rightleft' option.

- Disable the use of 'keymap' (without changing its value).

Note that 'arabicshape' and 'delcombine' are not reset (it is a global

option).

Also see |arabic.txt|.

*'arabicshape'* *'arshape'* *'noarabicshape'* *'noarshape'*

'arabicshape' 'arshape' boolean (default on)

global

When on and 'termbidi' is off, the required visual character

corrections that need to take place for displaying the Arabic language

take effect. Shaping, in essence, gets enabled; the term is a broad

one which encompasses:

a) the changing/morphing of characters based on their location

within a word (initial, medial, final and stand-alone).

b) the enabling of the ability to compose characters

c) the enabling of the required combining of some characters

When disabled the display shows each character's true stand-alone

form.

Arabic is a complex language which requires other settings, for

further details see |arabic.txt|.

*'autochdir'* *'acd'* *'noautochdir'* *'noacd'*

'autochdir' 'acd' boolean (default off)

global

When on, Vim will change the current working directory whenever you

open a file, switch buffers, delete a buffer or open/close a window.

It will change to the directory containing the file which was opened

or selected. When a buffer has no name it also has no directory, thus

the current directory won't change when navigating to it.

Note: When this option is on some plugins may not work.

*'autoindent'* *'ai'* *'noautoindent'* *'noai'*

'autoindent' 'ai' boolean (default on)

local to buffer

Copy indent from current line when starting a new line (typing <CR>

in Insert mode or when using the "o" or "O" command). If you do not

type anything on the new line except <BS> or CTRL-D and then type

<Esc>, CTRL-O or <CR>, the indent is deleted again. Moving the cursor

to another line has the same effect, unless the 'I' flag is included

in 'cpoptions'.

When autoindent is on, formatting (with the "gq" command or when you

reach 'textwidth' in Insert mode) uses the indentation of the first

line.

When 'smartindent' or 'cindent' is on the indent is changed in

a different way.

*'autoread'* *'ar'* *'noautoread'* *'noar'*

'autoread' 'ar' boolean (default on)

global or local to buffer |global-local|

When a file has been detected to have been changed outside of Vim and

it has not been changed inside of Vim, automatically read it again.

When the file has been deleted this is not done, so you have the text

from before it was deleted. When it appears again then it is read.

|timestamp|

If this option has a local value, use this command to switch back to

using the global value: >vim

set autoread<

<

*'autowrite'* *'aw'* *'noautowrite'* *'noaw'*

'autowrite' 'aw' boolean (default off)

global

Write the contents of the file, if it has been modified, on each

`:next`, `:rewind`, `:last`, `:first`, `:previous`, `:stop`,

`:suspend`, `:tag`, `:!`, `:make`, CTRL-] and CTRL-^ command; and when

a `:buffer`, CTRL-O, CTRL-I, '{A-Z0-9}, or `{A-Z0-9} command takes one

to another file.

A buffer is not written if it becomes hidden, e.g. when 'bufhidden' is

set to "hide" and `:next` is used.

Note that for some commands the 'autowrite' option is not used, see

'autowriteall' for that.

Some buffers will not be written, specifically when 'buftype' is

"nowrite", "nofile", "terminal" or "prompt".

USE WITH CARE: If you make temporary changes to a buffer that you

don't want to be saved this option may cause it to be saved anyway.

Renaming the buffer with ":file {name}" may help avoid this.

*'autowriteall'* *'awa'* *'noautowriteall'* *'noawa'*

'autowriteall' 'awa' boolean (default off)

global

Like 'autowrite', but also used for commands ":edit", ":enew", ":quit",

":qall", ":exit", ":xit", ":recover" and closing the Vim window.

Setting this option also implies that Vim behaves like 'autowrite' has

been set.

*'background'* *'bg'*

'background' 'bg' string (default "dark")

global

When set to "dark" or "light", adjusts the default color groups for

that background type. The |TUI| or other UI sets this on startup

(triggering |OptionSet|) if it can detect the background color.

This option does NOT change the background color, it tells Nvim what

the "inherited" (terminal/GUI) background looks like.

See |:hi-normal| if you want to set the background color explicitly.

*g:colors_name*

When a color scheme is loaded (the "g:colors_name" variable is set)

changing 'background' will cause the color scheme to be reloaded. If

the color scheme adjusts to the value of 'background' this will work.

However, if the color scheme sets 'background' itself the effect may

be undone. First delete the "g:colors_name" variable when needed.

Normally this option would be set in the vimrc file. Possibly

depending on the terminal name. Example: >vim

if $TERM ==# "xterm"

set background=dark

endif

< When this option is changed, the default settings for the highlight groups

will change. To use other settings, place ":highlight" commands AFTER

the setting of the 'background' option.

*'backspace'* *'bs'*

'backspace' 'bs' string (default "indent,eol,start")

global

Influences the working of <BS>, <Del>, CTRL-W and CTRL-U in Insert

mode. This is a list of items, separated by commas. Each item allows

a way to backspace over something:

value effect ~

indent allow backspacing over autoindent

eol allow backspacing over line breaks (join lines)

start allow backspacing over the start of insert; CTRL-W and CTRL-U

stop once at the start of insert.

nostop like start, except CTRL-W and CTRL-U do not stop at the start of

insert.

When the value is empty, Vi compatible backspacing is used, none of

the ways mentioned for the items above are possible.

*'backup'* *'bk'* *'nobackup'* *'nobk'*

'backup' 'bk' boolean (default off)

global

Make a backup before overwriting a file. Leave it around after the

file has been successfully written. If you do not want to keep the

backup file, but you do want a backup while the file is being

written, reset this option and set the 'writebackup' option (this is

the default). If you do not want a backup file at all reset both

options (use this if your file system is almost full). See the

|backup-table| for more explanations.

When the 'backupskip' pattern matches, a backup is not made anyway.

When 'patchmode' is set, the backup may be renamed to become the

oldest version of a file.

*'backupcopy'* *'bkc'*

'backupcopy' 'bkc' string (default "auto")

global or local to buffer |global-local|

When writing a file and a backup is made, this option tells how it's

done. This is a comma-separated list of words.

The main values are:

"yes" make a copy of the file and overwrite the original one

"no" rename the file and write a new one

"auto" one of the previous, what works best

Extra values that can be combined with the ones above are:

"breaksymlink" always break symlinks when writing

"breakhardlink" always break hardlinks when writing

Making a copy and overwriting the original file:

- Takes extra time to copy the file.

+ When the file has special attributes, is a (hard/symbolic) link or

has a resource fork, all this is preserved.

- When the file is a link the backup will have the name of the link,

not of the real file.

Renaming the file and writing a new one:

+ It's fast.

- Sometimes not all attributes of the file can be copied to the new

file.

- When the file is a link the new file will not be a link.

The "auto" value is the middle way: When Vim sees that renaming the

file is possible without side effects (the attributes can be passed on

and the file is not a link) that is used. When problems are expected,

a copy will be made.

The "breaksymlink" and "breakhardlink" values can be used in

combination with any of "yes", "no" and "auto". When included, they

force Vim to always break either symbolic or hard links by doing

exactly what the "no" option does, renaming the original file to

become the backup and writing a new file in its place. This can be

useful for example in source trees where all the files are symbolic or

hard links and any changes should stay in the local source tree, not

be propagated back to the original source.

*crontab*

One situation where "no" and "auto" will cause problems: A program

that opens a file, invokes Vim to edit that file, and then tests if

the open file was changed (through the file descriptor) will check the

backup file instead of the newly created file. "crontab -e" is an

example, as are several |file-watcher| daemons like inotify. In that

case you probably want to switch this option.

When a copy is made, the original file is truncated and then filled

with the new text. This means that protection bits, owner and

symbolic links of the original file are unmodified. The backup file,

however, is a new file, owned by the user who edited the file. The

group of the backup is set to the group of the original file. If this

fails, the protection bits for the group are made the same as for

others.

When the file is renamed, this is the other way around: The backup has

the same attributes of the original file, and the newly written file

is owned by the current user. When the file was a (hard/symbolic)

link, the new file will not! That's why the "auto" value doesn't

rename when the file is a link. The owner and group of the newly

written file will be set to the same ones as the original file, but

the system may refuse to do this. In that case the "auto" value will

again not rename the file.

*'backupdir'* *'bdir'*

'backupdir' 'bdir' string (default ".,$XDG_STATE_HOME/nvim/backup//")

global

List of directories for the backup file, separated with commas.

- The backup file will be created in the first directory in the list

where this is possible. If none of the directories exist Nvim will

attempt to create the last directory in the list.

- Empty means that no backup file will be created ('patchmode' is

impossible!). Writing may fail because of this.

- A directory "." means to put the backup file in the same directory

as the edited file.

- A directory starting with "./" (or ".\" for MS-Windows) means to put

the backup file relative to where the edited file is. The leading

"." is replaced with the path name of the edited file.

("." inside a directory name has no special meaning).

- Spaces after the comma are ignored, other spaces are considered part

of the directory name. To have a space at the start of a directory

name, precede it with a backslash.

- To include a comma in a directory name precede it with a backslash.

- A directory name may end in an '/'.

- For Unix and Win32, if a directory ends in two path separators "//",

the swap file name will be built from the complete path to the file

with all path separators changed to percent '%' signs. This will

ensure file name uniqueness in the backup directory.

On Win32, it is also possible to end with "\\". However, When a

separating comma is following, you must use "//", since "\\" will

include the comma in the file name. Therefore it is recommended to

use '//', instead of '\\'.

- Environment variables are expanded |:set_env|.

- Careful with '\' characters, type one before a space, type two to

get one in the option (see |option-backslash|), for example: >vim

set bdir=c:\\tmp,\ dir\\,with\\,commas,\\\ dir\ with\ spaces

<

See also 'backup' and 'writebackup' options.

If you want to hide your backup files on Unix, consider this value: >vim

set backupdir=./.backup,~/.backup,.,/tmp

< You must create a ".backup" directory in each directory and in your

home directory for this to work properly.

The use of |:set+=| and |:set-=| is preferred when adding or removing

directories from the list. This avoids problems when a future version

uses another default.

This option cannot be set from a |modeline| or in the |sandbox|, for

security reasons.

*'backupext'* *'bex'* *E589*

'backupext' 'bex' string (default "~")

global

String which is appended to a file name to make the name of the

backup file. The default is quite unusual, because this avoids

accidentally overwriting existing files with a backup file. You might

prefer using ".bak", but make sure that you don't have files with

".bak" that you want to keep.

Only normal file name characters can be used; `/\*?[|<>` are illegal.

If you like to keep a lot of backups, you could use a BufWritePre

autocommand to change 'backupext' just before writing the file to

include a timestamp. >vim

au BufWritePre * let &bex = '-' .. strftime("%Y%b%d%X") .. '~'

< Use 'backupdir' to put the backup in a different directory.

*'backupskip'* *'bsk'*

'backupskip' 'bsk' string (default "$TMPDIR/*,$TMP/*,$TEMP/*"

Unix: "/tmp/*,$TMPDIR/*,$TMP/*,$TEMP/*"

Mac: "/private/tmp/*,$TMPDIR/*,$TMP/*,$TEMP/*")

global

A list of file patterns. When one of the patterns matches with the

name of the file which is written, no backup file is created. Both

the specified file name and the full path name of the file are used.

The pattern is used like with |:autocmd|, see |autocmd-pattern|.

Watch out for special characters, see |option-backslash|.

When $TMPDIR, $TMP or $TEMP is not defined, it is not used for the

default value. "/tmp/*" is only used for Unix.

WARNING: Not having a backup file means that when Vim fails to write

your buffer correctly and then, for whatever reason, Vim exits, you

lose both the original file and what you were writing. Only disable

backups if you don't care about losing the file.

Note that environment variables are not expanded. If you want to use

$HOME you must expand it explicitly, e.g.: >vim