Options
Nvim:help pages,generated fromsource using thetree-sitter-vimdoc parser.
Options
For an overview of options see quickref.txt
option-list.
Vim has a number of internal variables and switches which can be set toachieve special effects. These options come in three forms:booleancan only be on or off
booleantogglenumberhas a numeric valuestringhas a string value
:se:set:se[t][!]Show all options that differ from their default value.When [!] is present every option is on a separateline.
:se[t][!] allShow all options.When [!] is present every option is on a separateline.
: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}&viReset option to its Vi default value.:se[t]
{option}&vimReset option to its Vim default value.
:se[t] all&Set all options to their default value. The values ofthese options are not changed:
'columns''lines'Warning: This may have a lot of side effects.
:set-args:set=E487E521: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' (bydefault this is a
<Tab>). Many string options withfixed syntax also support completing known values.See
cmdline-completion and
complete-set-option.White space between
{option} and '=' is allowed andwill be ignored. White space between '=' and
{value}is not allowed.See
option-backslash for using white space andbackslashes 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 acomma-separated list, a comma is added, unless thevalue was empty.If the option is a list of flags, superfluous flagsare removed. When adding a flag that was alreadypresent the option value doesn't change.Also see
:set-args above.
:se[t]
{option}^={value}
:set^=Multiply the
{value} to a number option, or prependthe
{value} to a string option. When the option is acomma-separated list, a comma is added, unless thevalue was empty.Also see
:set-args above.
:se[t]
{option}-={value}
:set-=Subtract the
{value} from a number option, or removethe
{value} from a string option, if it is there.If the
{value} is not found in a string option, thereis no error or warning. When the option is a comma-separated list, a comma is deleted, unless the optionbecomes empty.When the option is a list of flags,
{value} must beexactly as they appear in the option. Remove flagsone by one to avoid problems.The individual values from a comma separated list orlist 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 givenand the following arguments will be ignored.
:set-verboseWhen
'verbose' is non-zero, displaying an option value will also tell where itwas 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 ":verboseset 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 orautocommand, 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-backslashTo include white space in a string option value it has to be preceded with abackslash. To include a backslash you have to use two. Effectively thismeans that the number of backslashes in an option value is halved (roundeddown).In options
'path',
'cdpath', and
'tags', spaces have to be preceded with threebackslashes instead because they can be separated by either commas or spaces.Comma-separated options like
'backupdir' and
'tags' will also require commasto be escaped with two backslashes, whereas this is not needed fornon-comma-separated ones like
'makeprg'.When setting options using
:let and
literal-string, you need to use onefewer 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. Toinclude 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 '"' inthe 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: Foroptions that expect a file name (those where environment variables areexpanded) a backslash before a normal file name character is not removed. Buta backslash before a special character (space, backslash, comma, etc.) is usedlike 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 backslashesare halved. This makes sure it works both when you expect backslashes to behalved and when you expect the backslashes to be kept. The third gives aresult which is probably not what you want. Avoid it.
add-option-flagsremove-option-flagsE539Some options are a list of flags. When you want to add a flag to such anoption, 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' hasthe value "ab", using "set guioptions-=ba" won't work, because the string "ba"doesn't appear.
:set_envexpand-envexpand-environment-varEnvironment variables in specific string options will be expanded. If theenvironment variable exists the '$' and the following environment variablename is replaced with its value. If it does not exist the '$' and the nameare not modified. Any non-id character (not a letter, digit or '_') mayfollow the environment variable name. That character and what follows isappended 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 ":setopt+=val" the expansion is done before the adding or removing.
Some of the options only apply to a window or buffer. Each window or bufferhas its own copy of this option, thus each can have its own value. Thisallows 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 specificsituations. You don't really need to know all of this, since Vim mostly usesthe option values you would expect. Unfortunately, doing what the userexpects is a bit complicated...
When splitting a window, the local options are copied to the new window. Thusright after the split the contents of the two windows look the same.
When editing a new buffer, its local option values must be initialized. Sincethe 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 aglobal value, which is used for new buffers. With ":set" both the local andglobal 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 windowthat was last closed are used again. If this buffer has been edited in thiswindow, the values from back then are used. Otherwise the values from thelast 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 keepusing these local window options. Therefore Vim keeps a global value of thelocal window options, which is used when editing another buffer. Each windowhas its own copy of these values. Thus these are local to the window, butglobal 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 globalvalue, ":setlocal list" only changes the local value and ":e two" gets theglobal 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 alsohappens when the buffer is not loaded, but they are lost when the buffer iswiped out
:bwipe.
The following local window options won't be copied over when new windows arecreated, thus they behave slightly differently:
Special local buffer options
The following local buffer options won't be copied over when new buffers arecreated, thus they behave slightly differently:
:setl:setlocal:setl[ocal][!] ...Like ":set" but set only the value local to thecurrent buffer or window. Not all options have alocal value. If the option does not have a localvalue the global value is set.With the "all" argument: display local values for alllocal options.Without argument: Display local values for all localoptions which are different from the default.When displaying a specific local option, show thelocal value. For a global/local boolean option, whenthe global value is being used, "--" is displayedbefore the option name.For a global option the global value isshown (but that might change in the future).
:se[t]
{option}<Set the effective value of
{option} to its globalvalue.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 tothe local value.
:setl[ocal]{option}<Set the effective value of{option} to its globalvalue by copying the global value to the local value.
Note that the behaviour for
global-local options is slightly differentbetween string and number-based options.
:setg:setglobal:setg[lobal][!] ...Like ":set" but set only the global value for a localoption without changing the local value.When displaying an option, the global value is shown.With the "all" argument: display global values for alllocal options.Without argument: display global values for all localoptions 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 -
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 thenuse the local value, while other buffers and windows continue using the globalvalue.
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 setthe
'makeprg' option in the other C source window too.However, if you start editing a Perl file in a new window, you want to useanother
'makeprg' for it, without changing the value used for the C sourcefiles. 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 needto use the "<" flag, like this:
:setlocal autoread<
Note that for non-boolean and non-number options using "<" copies the globalvalue 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 isused. 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-functionSome options (
'completefunc',
'findfunc',
'omnifunc',
'operatorfunc',
'quickfixtextfunc',
'tagfunc' and
'thesaurusfunc') are set to a function nameor a function reference or a lambda function. When using a lambda it will beconverted to the name, e.g. "<lambda>123".Examples:
set opfunc=MyOpFuncset opfunc=function('MyOpFunc')set opfunc=funcref('MyOpFunc')set opfunc={a\ ->\ MyOpFunc(a)}Set to a script-local function:
set opfunc=s:MyLocalFuncset opfunc=<SID>MyLocalFunc
Set using a funcref variable:
let Fn = function('MyTagFunc')let &tagfunc = FnSet 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 = LCalling a function in an expr option
expr-option-function The value of a few options, such as
'foldexpr', is an expression that isevaluated 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 verysimple, is to define a function and set the option to call it withoutarguments. A
v:lua-call can also be used. Example:
lua << EOF function _G.MyFoldFunc() -- ... compute fold level for line v:lnum return level endEOFset foldexpr=v:lua.MyFoldFunc()
Setting the filetype
:setf[iletype] [FALLBACK]
{filetype}:setf:setfiletypeSet the
'filetype' option to
{filetype}, but only ifnot done yet in a sequence of (nested) autocommands.This is short for:
:if !did_filetype(): setlocal filetype={filetype}:endifThis command is used in a filetype.vim file to avoidsetting the
'filetype' option twice, causing differentsettings and syntax files to be loaded.
When the optional FALLBACK argument is present, alater :setfiletype command will override the
'filetype'. This is to be used for filetypedetections that are just a guess.
did_filetype()will return false after this command.
option-windowoptwin: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 theshort help to open a help window with more help forthe option.Modify the value of the option and hit
<CR> on the"set" line to set the new value. For window andbuffer specific options, the last accessed window isused to set the option value in, unless this is a helpwindow, in which case the window below help window isused (skipping the option-window).
$HOMEUsing "~" is like using "$HOME", but it is only recognized at the start of anoption and after a space or comma.
On Unix systems "~user" can be used too. It is replaced by the home directoryof user "user". Example:
:set path=~mool/include,/usr/include,.
On Unix systems the form "${HOME}" can be used too. The name between {} cancontain 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-windowsOn MS-Windows, if $HOME is not defined as an environment variable, thenat 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 whenrunning 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 thesubprocesses.
Note the maximum length of an expanded option is limited. How much depends onthe system, mostly it is something like 256 or 1024 characters.
Besides changing options with the ":set" command, you can set optionsautomatically in various ways:
modelinevim:vi:ex:E520There 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 blankcharacter (<Space> or<Tab>); "ex:" always requires atleast 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 spaceor ':', where each part between ':' is the argumentfor 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 blankcharacter (<Space> or<Tab>); "ex:" always requires atleast one blank character{vi:|vim:|Vim:|ex:}the string "vi:", "vim:", "Vim:" or "ex:"[white]optional white spacese[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, whichis 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 thechance 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 withversion 3.0). Using "ex:" at the start of the line will be ignored (thiscould be short for "example:").
If the modeline is disabled within a modeline, subsequent modelines will beignored. This is to allow turning off modeline on a per-file basis. This isuseful when a line looks like a modeline but isn't. For example, it would begood to start a YAML file containing strings like "vim:" with
# vim: nomodeline
so as to avoid modeline misdetection. Following options on the same lineafter modeline deactivation, if any, are still evaluated (but you wouldnormally not have any).
modeline-localThe options are set like with ":setlocal": The new value only applies to thebuffer and window that contain the file. Although it's possible to set globaloptions from a modeline, this is unusual. If you have two windows open andthe files in it set the same global option to a different value, the resultdepends on which one was opened last.
When editing a file that was already loaded, only the window-local optionsfrom the modeline are used. Thus if you manually changed a buffer-localoption after opening the file, it won't be changed if you edit the same bufferin another window. But window-local options will be set.
modeline-versionIf the modeline is only to be used for some versions of Vim, the versionnumber can be specified where "vim:" or "Vim:" is used:vim{vers}:version
{vers} or latervim<{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.
Note that for the first form all of the rest of the line is used, thus a linelike:
/* 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 '\'. Thebackslash in front of the ':' will be removed. Example:
/* vi:set fillchars=stl\:^,vert\:\|: */
This sets the
'fillchars' option to "stl:^,vert:\|". Only a single backslashbefore the ':' is removed. Thus to include "\:" you have to specify "\\:".
E992No other commands than "set" are supported, for security reasons (somebodymight create a Trojan horse text file with modelines). And not all optionscan be set. For some options a flag is set, so that when the value is usedthe
sandbox is effective. Some options can only be set from the modelinewhen
'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 doesthis, for example.
Hint: If you would like to do something else than setting an option, you coulddefine an autocommand that checks the file for a specific string. Forexample:
au BufReadPost * if getline(1) =~ "VAR" | call SetVar() | endif
And define a function SetVar() that does something with the line containing"VAR".
In the list below all the options are mentioned with their full name and withan 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 thatare specific to how the text is presented in a window. These can be set to adifferent value in each window. For example the
'list' option can be set inone window and reset in another for the same text, giving both types of viewat the same time. There are a few options that are specific to a certainfile. These can have a different value for each file or buffer. For examplethe
'textwidth' option can be 78 for a normal text file and 0 for a Cprogram.
globalone option for all buffers and windowslocal to windoweach window has its own copy of this optionlocal to buffereach buffer has its own copy of this option
When creating a new window the option values from the currently active windoware used as a default value for the window-specific options. For thebuffer-specific options this depends on the 's' and 'S' flags in the
'cpoptions' option. If 's' is included (which is the default) the values forbuffer options are copied from the currently active buffer when a buffer isfirst entered. If 'S' is present the options are copied each time the bufferis entered, this is almost like having global options. If 's' and 'S' are notpresent, the options are copied from the currently active buffer when thebuffer is created.
Not all options are supported in all versions. This depends on the supportedfeatures and sometimes on the system. A remark about this is in curly bracesbelow. When an option is not supported, it is called a hidden option. Tryingto get the value of a hidden option will not give an error, it will return thedefault value for that option instead. You can't change the value of a hiddenoption.
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 reallysupported use something like this:
if exists('+foo')E355A jump table for the options with a short description can be found at
Q_op.
'ambiwidth''ambw''ambiwidth''ambw'string(default "single")globalTells Vim what to do with characters with East Asian Width ClassAmbiguous (such as Euro, Registered Sign, Copyright Sign, Greekletters, Cyrillic letters).
There are currently two possible values:"single":Use the same width as characters in US-ASCII. This isexpected by most users."double":Use twice the width of ASCII characters.
E834E835The value "double" cannot be used if
'listchars' or
'fillchars'contains a character that would be double width. These errors mayalso be given when calling setcellwidths().
There are a number of CJK fonts for which the width of glyphs forthose characters are solely based on how many octets they take inlegacy/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 alsotrue of some line drawing characters used to make tables in textfile. Therefore, when a CJK font is used for GUI Vim orVim 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 perceivedby Vim with the width of glyphs in the font. Perhaps it also hasto be set to "double" under CJK MS-Windows when the system locale isset 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 windowThis option can be set to start editing Arabic text.Setting this option will:
Set the
'keymap' option to "arabic"; in Insert mode
CTRL-^ toggles between typing English and Arabic key mapping.
Resetting this option will:
'arabicshape''arshape''noarabicshape''noarshape''arabicshape''arshape'boolean(default on)globalWhen on and
'termbidi' is off, the required visual charactercorrections that need to take place for displaying the Arabic languagetake effect. Shaping, in essence, gets enabled; the term is a broadone 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 charactersWhen disabled the display shows each character's true stand-aloneform.Arabic is a complex language which requires other settings, forfurther details see
arabic.txt.
'autochdir''acd''noautochdir''noacd''autochdir''acd'boolean(default off)globalWhen on, Vim will change the current working directory whenever youopen a file, switch buffers, delete a buffer or open/close a window.It will change to the directory containing the file which was openedor selected. When a buffer has no name it also has no directory, thusthe 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 bufferCopy 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 nottype 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 cursorto another line has the same effect, unless the 'I' flag is includedin
'cpoptions'.When autoindent is on, formatting (with the "gq" command or when youreach
'textwidth' in Insert mode) uses the indentation of the firstline.When
'smartindent' or
'cindent' is on the indent is changed ina different way.
'autoread''ar''noautoread''noar''autoread''ar'boolean(default on)global or local to buffer
global-localWhen a file has been detected to have been changed outside of Vim andit 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 textfrom 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 tousing the global value:
set autoread<
'autowrite''aw''noautowrite''noaw''autowrite''aw'boolean(default off)globalWrite 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 whena
:buffer,
CTRL-O,
CTRL-I, '
{A-Z0-9}, or{A-Z0-9} command takes oneto another file.A buffer is not written if it becomes hidden, e.g. when
'bufhidden' isset 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 youdon't want to be saved this option may cause it to be saved anyway.Renaming the buffer with ":file
{name}" may help avoid this.
'background''bg''background''bg'string(default "dark")globalWhen set to "dark" or "light", adjusts the default color groups forthat 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 whatthe "inherited" (terminal/GUI) background looks like.See
:hi-normal if you want to set the background color explicitly.
g:colors_nameWhen a color scheme is loaded (the "g:colors_name" variable is set)changing
'background' will cause the color scheme to be reloaded. Ifthe color scheme adjusts to the value of
'background' this will work.However, if the color scheme sets
'background' itself the effect maybe undone. First delete the "g:colors_name" variable when needed.
Normally this option would be set in the vimrc file. Possiblydepending on the terminal name. Example:
if $TERM ==# "xterm" set background=darkendif
When this option is changed, the default settings for the highlight groupswill change. To use other settings, place ":highlight" commands AFTERthe setting of the
'background' option.
'backspace''bs''backspace''bs'string(default "indent,eol,start")globalInfluences the working of
<BS>,
<Del>,
CTRL-W and
CTRL-U in Insertmode. This is a list of items, separated by commas. Each item allowsa way to backspace over something:
valueeffect
indentallow backspacing over autoindenteolallow backspacing over line breaks (join lines)startallow backspacing over the start of insert;
CTRL-W and
CTRL-Ustop once at the start of insert.nostoplike start, except
CTRL-W and
CTRL-U do not stop at the start ofinsert.
When the value is empty, Vi compatible backspacing is used, none ofthe ways mentioned for the items above are possible.
'backup''bk''nobackup''nobk''backup''bk'boolean(default off)globalMake a backup before overwriting a file. Leave it around after thefile has been successfully written. If you do not want to keep thebackup file, but you do want a backup while the file is beingwritten, reset this option and set the
'writebackup' option (this isthe default). If you do not want a backup file at all reset bothoptions (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 theoldest version of a file.
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 thefile is possible without side effects (the attributes can be passed onand 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 incombination with any of "yes", "no" and "auto". When included, theyforce Vim to always break either symbolic or hard links by doingexactly what the "no" option does, renaming the original file tobecome the backup and writing a new file in its place. This can beuseful for example in source trees where all the files are symbolic orhard links and any changes should stay in the local source tree, notbe propagated back to the original source.
crontabOne situation where "no" and "auto" will cause problems: A programthat opens a file, invokes Vim to edit that file, and then tests ifthe open file was changed (through the file descriptor) will check thebackup file instead of the newly created file. "crontab -e" is anexample, as are several
file-watcher daemons like inotify. In thatcase you probably want to switch this option.
When a copy is made, the original file is truncated and then filledwith the new text. This means that protection bits, owner andsymbolic links of the original file are unmodified. The backup file,however, is a new file, owned by the user who edited the file. Thegroup of the backup is set to the group of the original file. If thisfails, the protection bits for the group are made the same as forothers.
When the file is renamed, this is the other way around: The backup hasthe same attributes of the original file, and the newly written fileis 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'trename when the file is a link. The owner and group of the newlywritten file will be set to the same ones as the original file, butthe system may refuse to do this. In that case the "auto" value willagain not rename the file.
'backupdir''bdir''backupdir''bdir'string(default ".,$XDG_STATE_HOME/nvim/backup//")globalList 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:
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:
set backupdir=./.backup,~/.backup,.,/tmp
You must create a ".backup" directory in each directory and in yourhome directory for this to work properly.The use of
:set+= and
:set-= is preferred when adding or removingdirectories from the list. This avoids problems when a future versionuses another default.This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
'backupext''bex'E589'backupext''bex'string(default "~")globalString which is appended to a file name to make the name of thebackup file. The default is quite unusual, because this avoidsaccidentally overwriting existing files with a backup file. You mightprefer 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 BufWritePreautocommand to change
'backupext' just before writing the file toinclude a timestamp.
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/*")globalA list of file patterns. When one of the patterns matches with thename of the file which is written, no backup file is created. Boththe 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 thedefault value. "/tmp/*" is only used for Unix.
WARNING: Not having a backup file means that when Vim fails to writeyour buffer correctly and then, for whatever reason, Vim exits, youlose both the original file and what you were writing. Only disablebackups 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.:
let &backupskip = escape(expand('$HOME'), '\') .. '/tmp/*'
Note that the default also makes sure that "crontab -e" works (when abackup would be made by renaming the original file crontab won't seethe newly created file). Also see
'backupcopy' and
crontab.
'belloff''bo''belloff''bo'string(default "all")globalSpecifies for which events the bell will not be rung. It is a comma-separated list of items. For each item that is present, the bellwill be silenced. This is most useful to specify specific events ininsert mode to be silenced.You can also make it flash by using
'visualbell'.
item meaning when present
all All events.backspace When hitting
<BS> or
<Del> and deleting results in an error.cursor Fail to move around using the cursor keys or
<PageUp>/<PageDown> in
Insert-mode.complete Error occurred when using
i_CTRL-X_CTRL-K or
i_CTRL-X_CTRL-T.copy Cannot copy char from insert mode using
i_CTRL-Y or
i_CTRL-E.ctrlg Unknown Char after
<C-G> in Insert mode.error Other Error occurred (e.g. try to join last line) (mostly used in
Normal-mode or
Cmdline-mode).esc hitting
<Esc> in
Normal-mode.hangul Ignored.lang Calling the beep module for Lua/Mzscheme/TCL.mess No output available for
g<.showmatch Error occurred for
'showmatch' function.operator Empty region error
cpo-E.register Unknown register after
<C-R> in
Insert-mode.shell Bell from shell output
:!.spell Error happened on spell suggest.term Bell from
:terminal output.wildmode More matches in
cmdline-completion available (depends on the
'wildmode' setting).
This is most useful to fine tune when in Insert mode the bell shouldbe rung. For Normal mode and Ex commands, the bell is often rung toindicate that an error occurred. It can be silenced by adding the"error" keyword.
'binary''bin''nobinary''nobin''binary''bin'boolean(default off)local to bufferThis option should be set before editing a binary file. You can alsouse the
-b Vim argument. When this option is switched on a fewoptions will be changed (also when it already was on):
'textwidth' will be set to 0
'wrapmargin' will be set to 0
'modeline' will be off
'expandtab' will be offAlso,
'fileformat' and
'fileformats' options will not be used, thefile is read and written like
'fileformat' was "unix" (a single
<NL>separates lines).The
'fileencoding' and
'fileencodings' options will not be used, thefile is read without conversion.
NOTE: When you start editing a(nother) file while the
'bin' option ison, settings from autocommands may change the settings again (e.g.,
'textwidth'), causing trouble when editing. You might want to set
'bin' again when the file has been loaded.The previous values of these options are remembered and restored when
'bin' is switched from on to off. Each buffer has its own set ofsaved option values.To edit a file with
'binary' set you can use the
++bin argument.This avoids you have to do ":set bin", which would have effect for allfiles you edit.When writing a file the
<EOL> for the last line is only written ifthere was one in the original file (normally Vim appends an
<EOL> tothe last line if there is none; this would make the file longer). Seethe
'endofline' option.
'bomb''nobomb''bomb'boolean(default off)local to bufferWhen writing a file and the following conditions are met, a BOM (ByteOrder Mark) is prepended to the file:
this option is on
'fileencoding' is "utf-8", "ucs-2", "ucs-4" or one of the little/big endian variants.Some applications use the BOM to recognize the encoding of the file.Often used for UCS-2 files on MS-Windows. For other applications itcauses trouble, for example: "cat file1 file2" makes the BOM of file2appear halfway through the resulting file. Gcc doesn't accept a BOM.When Vim reads a file and
'fileencodings' starts with "ucs-bom", acheck for the presence of the BOM is done and
'bomb' set accordingly.Unless
'binary' is set, it is removed from the first line, so that youdon't see it when editing. When you don't change the options, the BOMwill be restored when writing the file.
'breakindentopt''briopt''breakindentopt''briopt'string(default "")local to windowSettings for
'breakindent'. It can consist of the following optionalitems and must be separated by a comma:min:{n} Minimum text width that will be kept after applying
'breakindent', even if the resulting text should normally be narrower. This prevents text indented almost to the right window border occupying lots of vertical space when broken. (default: 20)shift:{n} After applying
'breakindent', the wrapped line's beginning will be shifted by the given number of characters. It permits dynamic French paragraph indentation (negative) or emphasizing the line continuation (positive). (default: 0)sbr Display the
'showbreak' value before applying the additional indent. (default: off)list:{n} Adds an additional indent for lines that match a numbered or bulleted list (using the
'formatlistpat' setting). (default: 0)list:-1 Uses the width of a match with
'formatlistpat' for indentation.column:{n} Indent at column
{n}. Will overrule the other sub-options.
Note: an additional indent may be added for the
'showbreak' setting. (default: off)
'bufhidden''bh''bufhidden''bh'string(default "")local to buffer
local-noglobalThis option specifies what happens when a buffer is no longerdisplayed in a window:
<empty>follow the global
'hidden' option hidehide the buffer (don't unload it), even if
'hidden' isnot set unloadunload the buffer, even if
'hidden' is set; the
:hide command will also unload the buffer deletedelete the buffer from the buffer list, even if
'hidden' is set; the
:hide command will also deletethe buffer, making it behave like
:bdelete wipewipe the buffer from the buffer list, even if
'hidden' is set; the
:hide command will also wipeout the buffer, making it behave like
:bwipeout CAREFUL: when "unload", "delete" or "wipe" is used changes in a bufferare lost without a warning. Also, these values may break autocommandsthat switch between buffers temporarily.This option is used together with
'buftype' and
'swapfile' to specifyspecial kinds of buffers. See
special-buffers.
'buflisted''bl''nobuflisted''nobl'E85'buflisted''bl'boolean(default on)local to bufferWhen this option is set, the buffer shows up in the buffer list. Ifit is reset it is not used for ":bnext", "ls", the Buffers menu, etc.This option is reset by Vim for buffers that are only used to remembera file name or marks. Vim sets it when starting to edit a buffer.But not when moving to a buffer with ":buffer".
'buftype''bt'E382'buftype''bt'string(default "")local to buffer
local-noglobalThe value of this option specifies the type of a buffer:
<empty>normal buffer acwritebuffer will always be written with
BufWriteCmds helphelp buffer (do not set this manually) nofilebuffer is not related to a file, will not be written nowritebuffer will not be written promptbuffer where only the last section can be edited, foruse by plugins.
prompt-buffer quickfixlist of errors
:cwindow or locations
:lwindow terminal
terminal-emulator buffer
Be careful with changing this option, it can have many side effects!One such effect is that Vim will not check the timestamp of the file,if the file is changed by another program this will not be noticed.
A "quickfix" buffer is only used for the error list and the locationlist. This value is set by the
:cwindow and
:lwindow commands andyou are not supposed to change it.
"nofile" and "nowrite" buffers are similar:both:The buffer is not to be written to disk, ":w" doesn'twork (":w filename" does work though).both:The buffer is never considered to be
'modified'.There is no warning when the changes will be lost, forexample when you quit Vim.both:A swap file is only created when using too much memory(when
'swapfile' has been reset there is never a swapfile).nofile only:The buffer name is fixed, it is not handled like afile name. It is not modified in response to a
:cdcommand.both:When using ":e bufname" and already editing "bufname"the buffer is made empty and autocommands aretriggered as usual for
:edit.
E676"acwrite" implies that the buffer name is not related to a file, like"nofile", but it will be written. Thus, in contrast to "nofile" and"nowrite", ":w" does work and a modified buffer can't be abandonedwithout saving. For writing there must be matching
BufWriteCmd,
FileWriteCmd or
FileAppendCmd autocommands.
'busy''busy'number(default 0)local to bufferSets a buffer "busy" status. Indicated in the default statusline.When busy status is larger then 0 busy flag is shown in statusline.The semantics of "busy" are arbitrary, typically decided by the plugin that owns the buffer.
'casemap''cmp''casemap''cmp'string(default "internal,keepascii")globalSpecifies details about changing the case of letters. It may containthese words, separated by a comma:internalUse internal case mapping functions, the currentlocale does not change the case mapping. When"internal" is omitted, the towupper() and towlower()system library functions are used when available.keepasciiFor the ASCII characters (0x00 to 0x7f) use the UScase mapping, the current locale is not effective.This probably only matters for Turkish.
'cdpath''cd'E344E346'cdpath''cd'string(default equivalent to $CDPATH or ",,")globalThis is a list of directories which will be searched when using the
:cd,
:tcd and
:lcd commands, provided that the directory beingsearched for has a relative path, not an absolute part starting with"/", "./" or "../", the
'cdpath' option is not used then.The
'cdpath' option's value has the same form and semantics as
'path'. Also see
file-searching.The default value is taken from $CDPATH, with a "," prepended to lookin the current directory first.If the default value taken from $CDPATH is not what you want, includea modified version of the following command in your vimrc file tooverride it:
let &cdpath = ',' .. substitute(substitute($CDPATH, '[, ]', '\\\0', 'g'), ':', ',', 'g')
This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.(parts of
'cdpath' can be passed to the shell to expand file names).
'cedit''cedit'string(default
CTRL-F)globalThe key used in Command-line Mode to open the command-line window.Only non-printable keys are allowed.The key can be specified as a single character, but it is difficult totype. The preferred way is to use
key-notation (e.g.
<Up>,
<C-F>) ora letter preceded with a caret (e.g.
^F is
CTRL-F). Examples:
set cedit=^Yset cedit=<Esc>
Nvi also has this option, but it only uses the first character.See
cmdwin.
'channel''channel'number(default 0)local to buffer
channel connected to the buffer, or 0 if no channel is connected.In a
:terminal buffer this is the terminal channel.Read-only.
'charconvert''ccv'E202E214E513'charconvert''ccv'string(default "")globalAn expression that is used for character encoding conversion. It isevaluated when a file that is to be read or has been written has adifferent encoding from what is desired.
'charconvert' is not used when the internal iconv() function issupported and is able to do the conversion. Using iconv() ispreferred, because it is much faster.
'charconvert' is not used when reading stdin
--, because there is nofile to convert from. You will have to save the text in a file first.The expression must return zero, false or an empty string for success,non-zero or true for failure.See
encoding-names for possible encoding names.Additionally, names given in
'fileencodings' and
'fileencoding' areused.Conversion between "latin1", "unicode", "ucs-2", "ucs-4" and "utf-8"is done internally by Vim,
'charconvert' is not used for this.Also used for Unicode conversion.Example:
set charconvert=CharConvert()fun CharConvert() system("recode " \ .. v:charconvert_from .. ".." .. v:charconvert_to \ .. " <" .. v:fname_in .. " >" .. v:fname_out) return v:shell_errorendfun
The related Vim variables are:v:charconvert_fromname of the current encodingv:charconvert_toname of the desired encodingv:fname_inname of the input filev:fname_outname of the output fileNote that v:fname_in and v:fname_out will never be the same.
The advantage of using a function call without arguments is that it isfaster, see
expr-option-function.
If the
'charconvert' expression starts with s: or
<SID>, then it isreplaced with the script ID (
local-function). Example:
set charconvert=s:MyConvert()set charconvert=<SID>SomeConvert()
Otherwise the expression is evaluated in the context of the scriptwhere the option was set, thus script-local items are available.
This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
'chistory''chi''chistory''chi'number(default 10)globalNumber of quickfix lists that should be remembered for the quickfixstack. Must be between 1 and 100. If the option is set to a valuethat is lower than the amount of entries in the quickfix list stack,entries will be removed starting from the oldest one. If the currentquickfix list was removed, then the quickfix list at top of the stack(the most recently created) will be used in its place. For additionalinfo, see
quickfix-stack.
'cinkeys''cink''cinkeys''cink'string(default "0{,0},0),0],:,0#,!^F,o,O,e")local to bufferA list of keys that, when typed in Insert mode, cause reindenting ofthe current line. Only used if
'cindent' is on and
'indentexpr' isempty.For the format of this option see
cinkeys-format.See
C-indenting.
'cinscopedecls''cinsd''cinscopedecls''cinsd'string(default "public,protected,private")local to bufferKeywords that are interpreted as a C++ scope declaration by
cino-g.Useful e.g. for working with the Qt framework that defines additionalscope declarations "signals", "public slots" and "private slots":
set cinscopedecls+=signals,public\ slots,private\ slots
clipboard-unnamedunnamedWhen included, Vim will use the clipboard register "*"for all yank, delete, change and put operations whichwould normally go to the unnamed register. When aregister is explicitly specified, it will always beused regardless of whether "unnamed" is in
'clipboard'or not. The clipboard register can always beexplicitly accessed using the "* notation. Also see
clipboard.
clipboard-unnamedplusunnamedplusA variant of the "unnamed" flag which uses theclipboard register "+" (
quoteplus) instead ofregister "*" for all yank, delete, change and putoperations which would normally go to the unnamedregister. When "unnamed" is also included to theoption, yank and delete operations (but not put)will additionally copy the text into register"*". See
clipboard.
'cmdheight''ch''cmdheight''ch'number(default 1)global or local to tab pageNumber of screen lines to use for the command-line. Helps avoiding
hit-enter prompts.The value of this option is stored with the tab page, so that each tabpage can have a different value.
When
'cmdheight' is zero, there is no command-line unless it is beingused. The command-line will cover the last line of the screen whenshown.
WARNING:cmdheight=0 is EXPERIMENTAL. Expect some unwanted behaviour.Some
'shortmess' flags and similar mechanism might fail to take effect,causing unwanted hit-enter prompts. Some informative messages, bothfrom Nvim itself and plugins, will not be displayed.
'colorcolumn''cc''colorcolumn''cc'string(default "")local to window
'colorcolumn' is a comma-separated list of screen columns that arehighlighted with ColorColumn
hl-ColorColumn. Useful to aligntext. Will make screen redrawing slower.The screen column can be an absolute number, or a number preceded with'+' or '-', which is added to or subtracted from
'textwidth'.
set cc=+1 " highlight column after 'textwidth'set cc=+1,+2,+3 " highlight three columns after 'textwidth'hi ColorColumn ctermbg=lightgrey guibg=lightgrey
When
'textwidth' is zero then the items with '-' and '+' are not used.A maximum of 256 columns are highlighted.
'columns''co'E594'columns''co'number(default 80 or terminal width)globalNumber of columns of the screen. Normally this is set by the terminalinitialization and does not have to be set by hand.When Vim is running in the GUI or in a resizable window, setting thisoption will cause the window size to be changed. When you only wantto use the size for the GUI, put the command in your
ginit.vim file.When you set this option and Vim is unable to change the physicalnumber of columns of the display, the display may be messed up. Forthe GUI it is always possible and Vim limits the number of columns towhat fits on the screen. You can use this command to get the widestwindow possible:
set columns=9999
Minimum value is 12, maximum value is 10000.
'complete''cpt'E535'complete''cpt'string(default ".,w,b,u,t")local to bufferThis option specifies how keyword completion
ins-completion workswhen
CTRL-P or
CTRL-N are used. It is also used for whole-linecompletion
i_CTRL-X_CTRL-L. It indicates the type of completionand the places to scan. It is a comma-separated list of flags:.scan the current buffer (
'wrapscan' is ignored)wscan buffers from other windowsbscan other loaded buffers that are in the buffer listuscan the unloaded buffers that are in the buffer listUscan the buffers that are not in the buffer listkscan the files given with the
'dictionary' optionkspell use the currently active spell checking
spellk{dict}scan the file
{dict}. Several "k" flags can be given,patterns are valid too. For example:
set cpt=k/usr/dict/*,k~/spanish
sscan the files given with the
'thesaurus' options{tsr}scan the file
{tsr}. Several "s" flags can be given, patternsare valid too.iscan current and included filesdscan current and included files for defined name or macro
i_CTRL-X_CTRL-D ]tag completiontsame as "]"fscan the buffer names (as opposed to buffer contents)F{func}call the function
{func}. Multiple "F" flags may be specified.Refer to
complete-functions for details on how the functionis invoked and what it should return. The value can be thename of a function or a
Funcref. For
Funcref values,spaces must be escaped with a backslash ('\'), and commas withdouble backslashes ('\\') (see
option-backslash).Unlike other sources, functions can provide completions startingfrom a non-keyword character before the cursor, and theirstart position for replacing text may differ from other sources.If the Dict returned by the
{func} includes
{"refresh":} "always"},the function will be invoked again whenever the leading textchanges.If generating matches is potentially slow,
complete_check()should be used to avoid blocking and preserve editorresponsiveness.Fequivalent to using "F{func}", where the function is taken fromthe
'completefunc' option.oequivalent to using "F{func}", where the function is taken fromthe
'omnifunc' option.
Unloaded buffers are not loaded, thus their autocmds
:autocmd arenot executed, this may lead to unexpected completions from some files(gzipped files for example). Unloaded buffers are not scanned forwhole-line completion.
An optional match limit can be specified for a completion source byappending a caret ("^") followed by a{count} to the source flag.For example: ".^9,w,u,t^5" limits matches from the current bufferto 9 and from tags to 5. Other sources remain unlimited.Note: The match limit takes effect only during forward completion(CTRL-N) and is ignored during backward completion (CTRL-P).
'completefuzzycollect''cfc''completefuzzycollect''cfc'string(default "")globalA comma-separated list of strings to enable fuzzy collection forspecific
ins-completion modes, affecting how matches are gatheredduring completion. For specified modes, fuzzy matching is used tofind completion candidates instead of the standard prefix-basedmatching. This option can contain the following values:
When using the
'completeopt' "longest" option value, fuzzy collectioncan identify the longest common string among the best fuzzy matchesand insert it automatically.
'completeitemalign''cia''completeitemalign''cia'string(default "abbr,kind,menu")globalA comma-separated list of strings that controls the alignment anddisplay order of items in the popup menu during Insert modecompletion. The supported values are "abbr", "kind", and "menu".These values allow customizing how
complete-items are shown in thepopup menu.
Note: must always contain those three values in anyorder.
fuzzy Enable
fuzzy-matching for completion candidates. This allows for more flexible and intuitive matching, where characters can be skipped and matches can be found even if the exact sequence is not typed.
Note: This option does not affect the collection of candidate list, it only controls how completion candidates are reduced from the list of alternatives. If you want to use
fuzzy-matching to gather more alternatives for your candidate list, see
'completefuzzycollect'.
longest Only insert the longest common text of the matches. If the menu is displayed you can use
CTRL-L to add more characters. Whether case is ignored depends on the kind of completion. For buffer text the
'ignorecase' option is used.
menu Use a popup menu to show the possible completions. The menu is only shown when there is more than one match and sufficient colors are available.
ins-completion-menu menuone Use the popup menu also when there is only one match. Useful when there is additional information about the match, e.g., what file it comes from.
nearest Matches are listed based on their proximity to the cursor position, unlike the default behavior, which only considers proximity for matches appearing below the cursor. This applies only to matches from the current buffer. No effect if "fuzzy" is present.
noinsert Do not insert any text for a match until the user selects a match from the menu. Only works in combination with "menu" or "menuone". No effect if "longest" is present.
noselect Same as "noinsert", except that no menu item is pre-selected. If both "noinsert" and "noselect" are present, "noselect" has precedence.
nosort Disable sorting of completion candidates based on fuzzy scores when "fuzzy" is enabled. Candidates will appear in their original order.
popup Show extra information about the currently selected completion in a popup window. Only works in combination with "menu" or "menuone". Overrides "preview".
preinsert Preinsert the portion of the first candidate word that is not part of the current completion leader and using the
hl-ComplMatchIns highlight group. In order for it to work, "fuzzy" must not be set and "menuone" must be set.
preview Show extra information about the currently selected completion in the preview window. Only works in combination with "menu" or "menuone".
'completeslash''csl''completeslash''csl'string(default "")local to bufferonly modifiable in MS-WindowsWhen this option is set it overrules
'shellslash' for completion:
When this option is set to "slash", a forward slash is used for path completion in insert mode. This is useful when editing HTML tag, or Makefile with
'noshellslash' on MS-Windows.
When this option is set to "backslash", backslash is used. This is useful when editing a batch file with
'shellslash' set on MS-Windows.
When this option is empty, same character is used as for
'shellslash'.For Insert mode completion the buffer-local value is used. Forcommand line completion the global value is used.
'concealcursor''cocu''concealcursor''cocu'string(default "")local to windowSets the modes in which text in the cursor line can also be concealed.When the current mode is listed then concealing happens just like inother lines. nNormal mode vVisual mode iInsert mode cCommand line editing, for
'incsearch' 'v' applies to all lines in the Visual area, not only the cursor.A useful value is "nc". This is used in help files. So long as youare moving around text is concealed, but when starting to insert textor selecting a Visual area the concealed text is displayed, so thatyou can see what you are doing.Keep in mind that the cursor position is not always where it'sdisplayed. E.g., when moving vertically it may change column.
ValueEffect
0Text is shown normally1Each block of concealed text is replaced with onecharacter. If the syntax item does not have a customreplacement character defined (see
:syn-cchar) thecharacter defined in
'listchars' is used.It is highlighted with the "Conceal" highlight group.2Concealed text is completely hidden unless it has acustom replacement character defined (see
:syn-cchar).3Concealed text is completely hidden.
Note: in the cursor line concealed text is not hidden, so that you canedit and copy the text. This can be changed with the
'concealcursor'option.
'confirm''cf''noconfirm''nocf''confirm''cf'boolean(default off)globalWhen
'confirm' is on, certain operations that would normallyfail because of unsaved changes to a buffer, e.g. ":q" and ":e",instead raise a dialog asking if you wish to save the currentfile(s). You can still use a ! to unconditionally
abandon a buffer.If
'confirm' is off you can still activate confirmation for onecommand only (this is most useful in mappings) with the
:confirmcommand.Also see the
confirm() function and the 'v' flag in
'guioptions'.
'copyindent''ci''nocopyindent''noci''copyindent''ci'boolean(default off)local to bufferCopy the structure of the existing lines indent when autoindenting anew line. Normally the new indent is reconstructed by a series oftabs followed by spaces as required (unless
'expandtab' is enabled,in which case only spaces are used). Enabling this option makes thenew line copy whatever characters were used for indenting on theexisting line.
'expandtab' has no effect on these characters, a Tabremains a Tab. If the new indent is greater than on the existingline, the remaining space is filled in the normal manner.See
'preserveindent'.
'cpoptions''cpo'cpo'cpoptions''cpo'string(default "aABceFs_")globalA sequence of single character flags. When a character is presentthis indicates Vi-compatible behavior. This is used for things wherenot being Vi-compatible is mostly or sometimes preferred.
'cpoptions' stands for "compatible-options".Commas can be added for readability.To avoid problems with flags that are added in the future, use the"+=" and "-=" feature of ":set"
add-option-flags.
containsbehavior
cpo-aaWhen included, a ":read" command with a file nameargument will set the alternate file name for thecurrent window.
cpo-AAWhen included, a ":write" command with a file nameargument will set the alternate file name for thecurrent window.
cpo-bb"\|" in a ":map" command is recognized as the end ofthe map command. The '\' is included in the mapping,the text after the '|' is interpreted as the nextcommand. Use a
CTRL-V instead of a backslash toinclude the '|' in the mapping. Applies to allmapping, abbreviation, menu and autocmd commands.See also
map_bar.
cpo-BBA backslash has no special meaning in mappings,abbreviations, user commands and the "to" part of themenu commands. Remove this flag to be able to use abackslash like a
CTRL-V. For example, the command":map X \<Esc>" results in X being mapped to:'B' included:"\^[" (^[ is a real
<Esc>)'B' excluded:"<Esc>" (5 characters)
cpo-ccSearching continues at the end of any match at thecursor position, but not further than the start of thenext line. When not present searching continuesone character from the cursor position. With 'c'"abababababab" only gets three matches when repeating"/abab", without 'c' there are five matches.
cpo-CCDo not concatenate sourced lines that start with abackslash. See
line-continuation.
cpo-ddUsing "./" in the
'tags' option doesn't mean to usethe tags file relative to the current file, but thetags file in the current directory.
cpo-DDCan't use
CTRL-K to enter a digraph after Normal modecommands with a character argument, like
r,
f and
t.
cpo-eeWhen executing a register with ":@r", always add a
<CR> to the last line, also when the register is notlinewise. If this flag is not present, the registeris not linewise and the last line does not end in a
<CR>, then the last line is put on the command-lineand can be edited before hitting
<CR>.
cpo-EEIt is an error when using "y", "d", "c", "g~", "gu" or"gU" on an Empty region. The operators only work whenat least one character is to be operated on. Example:This makes "y0" fail in the first column.
cpo-ffWhen included, a ":read" command with a file nameargument will set the file name for the current buffer,if the current buffer doesn't have a file name yet.
cpo-FFWhen included, a ":write" command with a file nameargument will set the file name for the currentbuffer, if the current buffer doesn't have a file nameyet. Also see
cpo-P.
cpo-iiWhen included, interrupting the reading of a file willleave it modified.
cpo-IIWhen moving the cursor up or down just after insertingindent for
'autoindent', do not delete the indent.
cpo-JJA
sentence has to be followed by two spaces afterthe '.', '!' or '?'. A
<Tab> is not recognized aswhite space.
cpo-KKDon't wait for a key code to complete when it ishalfway through a mapping. This breaks mapping
<F1><F1> when only part of the second
<F1> has beenread. It enables cancelling the mapping by typing
<F1><Esc>.
cpo-llBackslash in a [] range in a search pattern is takenliterally, only "\]", "\^", "\-" and "\\" are special.See
/[] 'l' included: "/[ \t]" finds
<Space>, '\' and 't' 'l' excluded: "/[ \t]" finds
<Space> and
<Tab>cpo-LLWhen the
'list' option is set,
'wrapmargin',
'textwidth',
'softtabstop' and Virtual Replace mode(see
gR) count a
<Tab> as two characters, instead ofthe normal behavior of a
<Tab>.
cpo-mmWhen included, a showmatch will always wait half asecond. When not included, a showmatch will wait halfa second or until a character is typed.
'showmatch'cpo-MMWhen excluded, "%" matching will take backslashes intoaccount. Thus in "( \( )" and "\( ( \)" the outerparenthesis match. When included "%" ignoresbackslashes, which is Vi compatible.
cpo-nnWhen included, the column used for
'number' and
'relativenumber' will also be used for text of wrappedlines.
cpo-ooLine offset to search command is not remembered fornext search.
cpo-OODon't complain if a file is being overwritten, evenwhen it didn't exist when editing it. This is aprotection against a file unexpectedly created bysomeone else. Vi didn't complain about this.
cpo-PPWhen included, a ":write" command that appends to afile will set the file name for the current buffer, ifthe current buffer doesn't have a file name yet andthe 'F' flag is also included
cpo-F.
cpo-qqWhen joining multiple lines leave the cursor at theposition where it would be when joining two lines.
cpo-rrRedo ("." command) uses "/" to repeat a searchcommand, instead of the actually used search string.
cpo-RRRemove marks from filtered lines. Without this flagmarks are kept like
:keepmarks was used.
cpo-ssSet buffer options when entering the buffer for thefirst time. This is like it is in Vim version 3.0.And it is the default. If not present the options areset when the buffer is created.
cpo-SSSet buffer options always when entering a buffer(except
'readonly',
'fileformat',
'filetype' and
'syntax'). This is the (most) Vi compatible setting.The options are set to the values in the currentbuffer. When you change an option and go to anotherbuffer, the value is copied. Effectively makes thebuffer options global to all buffers.
's' 'S' copy buffer optionsno no when buffer createdyes no when buffer first entered (default) X yes each time when buffer entered (vi comp.)
cpo-ttSearch pattern for the tag command is remembered for"n" command. Otherwise Vim only puts the pattern inthe history for search pattern, but doesn't change thelast used search pattern.
cpo-uuUndo is Vi compatible. See
undo-two-ways.
cpo-vvBackspaced characters remain visible on the screen inInsert mode. Without this flag the characters areerased from the screen right away. With this flag thescreen newly typed text overwrites backspacedcharacters.
cpo-WWDon't overwrite a readonly file. When omitted, ":w!"overwrites a readonly file, if possible.
cpo-xx
<Esc> on the command-line executes the command-line.The default in Vim is to abandon the command-line,because
<Esc> normally aborts a command.
c_<Esc>cpo-XXWhen using a count with "R" the replaced text isdeleted only once. Also when repeating "R" with "."and a count.
cpo-yyA yank command can be redone with ".". Think twice ifyou really want to use this, it may break someplugins, since most people expect "." to only repeat achange.
cpo-ZZWhen using "w!" while the
'readonly' option is set,don't reset
'readonly'.
cpo-!!When redoing a filter command, use the last usedexternal command, whatever it was. Otherwise the lastused -filter- command is used.
cpo-$$When making a change to one line, don't redisplay theline, but put a '$' at the end of the changed text.The changed text will be overwritten when you type thenew text. The line is redisplayed if you type anycommand that moves the cursor from the insertionpoint.
cpo-%%Vi-compatible matching is done for the "%" command.Does not recognize "#if", "#endif", etc.Does not recognize "/*" and "*/".Parens inside single and double quotes are alsocounted, causing a string that contains a paren todisturb the matching. For example, in a line like"if (strcmp("foo(", s))" the first paren does notmatch the last one. When this flag is not included,parens inside single and double quotes are treatedspecially. When matching a paren outside of quotes,everything inside quotes is ignored. When matching aparen inside quotes, it will find the matching one (ifthere is one). This works very well for C programs.This flag is also used for other features, such asC-indenting.
cpo-++When included, a ":write file" command will reset the
'modified' flag of the buffer, even though the bufferitself may still be different from its file.
cpo->>When appending to a register, put a line break beforethe appended text.
cpo-;;When using
, or
; to repeat the last
t searchand the cursor is right in front of the searchedcharacter, the cursor won't move. When not included,the cursor would skip over it and jump to thefollowing occurrence.
cpo-~~When included, don't resolve symbolic links whenchanging directory with
:cd,
:lcd, or
:tcd.This preserves the symbolic link path in buffer namesand when displaying the current directory. Whenexcluded (default), symbolic links are resolved totheir target paths.
cpo-__When using
cw on a word, do not include thewhitespace following the word in the motion.
'cursorbind''crb''nocursorbind''nocrb''cursorbind''crb'boolean(default off)local to windowWhen this option is set, as the cursor in the currentwindow moves other cursorbound windows (windows that also havethis option set) move their cursors to the corresponding line andcolumn. This option is useful for viewing thedifferences between two versions of a file (see
'diff'); in diff mode,inserted and deleted lines (though not characters within a line) aretaken into account.
'cursorcolumn''cuc''nocursorcolumn''nocuc''cursorcolumn''cuc'boolean(default off)local to windowHighlight the screen column of the cursor with CursorColumn
hl-CursorColumn. Useful to align text. Will make screen redrawingslower.If you only want the highlighting in the current window you can usethese autocommands:
au WinLeave * set nocursorline nocursorcolumnau WinEnter * set cursorline cursorcolumn
Special value:"both"Alias for the values "line,number".
"line" and "screenline" cannot be used together.
'debug''debug'string(default "")globalThese values can be used:msgError messages that would otherwise be omitted will be givenanyway.throwError messages that would otherwise be omitted will be givenanyway and also throw an exception and set
v:errmsg.beepA message will be given when otherwise only a beep would beproduced.The values can be combined, separated by a comma."msg" and "throw" are useful for debugging
'foldexpr',
'formatexpr' or
'indentexpr'.
'define''def''define''def'string(default "")global or local to buffer
global-localPattern to be used to find a macro definition. It is a searchpattern, just like for the "/" command. This option is used for thecommands like "[i" and "[d"
include-search. The
'isident' option isused to recognize the defined name after the match:
{match with 'define'}{non-ID chars}{defined name}{non-ID char} See
option-backslash about inserting backslashes to include a spaceor backslash.For C++ this value would be useful, to include const type declarations:
^\(#\s*define\|[a-z]*\s*const\s*[a-z]*\)
You can also use "\ze" just before the name and continue the patternto check what is following. E.g. for Javascript, if a function isdefined with
func_name = function(args):
^\s*\ze\i\+\s*=\s*function(
If the function is defined with
func_name : function() {...:
^\s*\ze\i\+\s*[:]\s*(*function\s*(
When using the ":set" command, you need to double the backslashes!To avoid that use
:let with a single quote string:
let &l:define = '^\s*\ze\k\+\s*=\s*function('
'delcombine''deco''nodelcombine''nodeco''delcombine''deco'boolean(default off)globalIf editing Unicode and this option is set, backspace and Normal mode"x" delete each combining character on its own. When it is off (thedefault) the character along with its combining characters aredeleted.
Note: When
'delcombine' is set "xx" may work differently from "2x"!
This is useful for Arabic, Hebrew and many other languages where onemay have combining characters overtop of base characters, and wantto remove only the combining ones.
'dictionary''dict''dictionary''dict'string(default "")global or local to buffer
global-localList of file names, separated by commas, that are used to lookup wordsfor keyword completion commands
i_CTRL-X_CTRL-K. Each file shouldcontain a list of words. This can be one word per line, or severalwords per line, separated by non-keyword characters (white space ispreferred). Maximum line length is 510 bytes.
When this option is empty or an entry "spell" is present, and spellchecking is enabled, words in the word lists for the currently active
'spelllang' are used. See
spell.
To include a comma in a file name precede it with a backslash. Spacesafter a comma are ignored, otherwise spaces are included in the filename. See
option-backslash about using backslashes.This has nothing to do with the
Dictionary variable type.Where to find a list of words?
BSD/macOS include the "/usr/share/dict/words" file.
Try "apt install spell" to get the "/usr/share/dict/words" file on apt-managed systems (Debian/Ubuntu).The use of
:set+= and
:set-= is preferred when adding or removingdirectories from the list. This avoids problems when a future versionuses another default.Backticks cannot be used in this option for security reasons.
'diff''nodiff''diff'boolean(default off)local to windowJoin the current window in the group of windows that shows differencesbetween files. See
diff-mode.
'diffopt''dip''diffopt''dip'string(default "internal,filler,closeoff,inline:simple,linematch:40")globalOption settings for diff mode. It can consist of the following items.All are optional. Items must be separated by a comma.
algorithm:{text} Use the specified diff algorithm with theinternal diff engine. Currently supportedalgorithms are:myers the default algorithmminimal spend extra time to generate the smallest possible diffpatience patience diff algorithmhistogram histogram diff algorithm
closeoffWhen a window is closed where
'diff' is setand there is only one window remaining in thesame tab page with
'diff' set, execute
:diffoff in that window. This undoes a
:diffsplit command.
context:{n}Use a context of
{n} lines between a changeand a fold that contains unchanged lines.When omitted a context of six lines is used.When using zero the context is actually one,since folds require a line in between, alsofor a deleted line. Set it to a very largevalue (999999) to disable folding completely.See
fold-diff.
fillerShow filler lines, to keep the textsynchronized with a window that has insertedlines at the same position. Mostly usefulwhen windows are side-by-side and
'scrollbind'is set.
foldcolumn:{n}Set the
'foldcolumn' option to
{n} whenstarting diff mode. Without this 2 is used.
followwrapFollow the
'wrap' option and leave as it is.
horizontalStart diff mode with horizontal splits (unlessexplicitly specified otherwise).
hiddenoffDo not use diff mode for a buffer when itbecomes hidden.
iblankIgnore changes where lines are all blank. Addsthe "-B" flag to the "diff" command if
'diffexpr' is empty. Check the documentationof the "diff" command for what this doesexactly.
NOTE: the diff windows will get out of sync,because no differences between blank lines aretaken into account.
icaseIgnore changes in case of text. "a" and "A"are considered the same. Adds the "-i" flagto the "diff" command if
'diffexpr' is empty.
indent-heuristicUse the indent heuristic for the internaldiff library.
inline:{text}Highlight inline differences within a change.See
view-diffs. Supported values are:
none Do not perform inline highlighting.simple Highlight from first differentcharacter to the last one in eachline. This is the default if no
inline: value is set.char Use internal diff to perform acharacter-wise diff and highlight thedifference.word Use internal diff to perform a
word-wise diff and highlight thedifference. Non-alphanumericmulti-byte characters such as emojiand CJK characters are consideredindividual words.
internalUse the internal diff library. This isignored when
'diffexpr' is set.
E960When running out of memory when writing abuffer this item will be ignored for diffsinvolving that buffer. Set the
'verbose'option to see when this happens.
iwhiteIgnore changes in amount of white space. Addsthe "-b" flag to the "diff" command if
'diffexpr' is empty. Check the documentationof the "diff" command for what this doesexactly. It should ignore adding trailingwhite space, but not leading white space.
iwhiteallIgnore all white space changes. Addsthe "-w" flag to the "diff" command if
'diffexpr' is empty. Check the documentationof the "diff" command for what this doesexactly.
iwhiteeolIgnore white space changes at end of line.Adds the "-Z" flag to the "diff" command if
'diffexpr' is empty. Check the documentationof the "diff" command for what this doesexactly.
linematch:{n} Align and mark changes between the mostsimilar lines between the buffers. When thetotal number of lines in the diff hunk exceeds{n}, the lines will not be aligned because forvery large diff hunks there will be anoticeable lag. A reasonable setting is"linematch:60", as this will enable alignmentfor a 2 buffer diff hunk of 30 lines each,or a 3 buffer diff hunk of 20 lines each.
verticalStart diff mode with vertical splits (unlessexplicitly specified otherwise).
Examples:
set diffopt=internal,filler,context:4set diffopt=set diffopt=internal,filler,foldcolumn:3set diffopt-=internal " do NOT use the internal diff parser
Possible items:
The swap file will be created in the first directory where this is possible. If it is not possible in any directory, but last directory listed in the option does not exist, it is created.
Empty means that no swap file will be used (recovery is impossible!) and no
E303 error will be given.
A directory "." means to put the swap file in the same directory as the edited file. On Unix, a dot is prepended to the file name, so it doesn't show in a directory listing. On MS-Windows the "hidden" attribute is set and a dot prepended if possible.
A directory starting with "./" (or ".\" for MS-Windows) means to put the swap file relative to where the edited file is. The leading "." is replaced with the path name of the edited file.
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 replaced by percent '%' signs (including the colon following the drive letter on Win32). This will ensure file name uniqueness in the preserve 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 '\\'.
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 ':' or '/'.
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:
set dir=c:\\tmp,\ dir\\,with\\,commas,\\\ dir\ with\ spaces
Editing the same file twice will result in a warning. Using "/tmp" onis discouraged: if the system crashes you lose the swap file. Andothers on the computer may be able to see the files.Use
:set+= and
:set-= when adding or removing directories from thelist, this avoids problems if the Nvim default is changed.
This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
'display''dy''display''dy'string(default "lastline")globalChange the way text is displayed. This is a comma-separated list offlags:lastlineWhen included, as much as possible of the last linein a window will be displayed. "@@@" is put in thelast columns of the last screen line to indicate therest of the line is not displayed.truncateLike "lastline", but "@@@" is displayed in the firstcolumn of the last screen line. Overrules "lastline".uhexShow unprintable characters hexadecimal as
<xx>instead of using ^C and ~C.msgsepObsolete flag. Allowed but takes no effect.
msgsep When neither "lastline" nor "truncate" is included, a last line thatdoesn't fit is replaced with "@" lines.
The "@" character can be changed by setting the "lastline" item in
'fillchars'. The character is highlighted with
hl-NonText.
'eadirection''ead''eadirection''ead'string(default "both")globalTells when the
'equalalways' option applies:ververtically, width of windows is not affectedhorhorizontally, height of windows is not affectedbothwidth and height of windows is affected
'emoji''emo''noemoji''noemo''emoji''emo'boolean(default on)globalWhen on all Unicode emoji characters are considered to be full width.This excludes "text emoji" characters, which are normally displayed assingle width. However, such "text emoji" are treated as full-widthemoji if they are followed by the U+FE0F variant selector.
Unfortunately there is no good specification for this and it has beendetermined on trial-and-error basis. Use the
setcellwidths()function to change the behavior.
'endofline''eol''noendofline''noeol''endofline''eol'boolean(default on)local to bufferWhen writing a file and this option is off and the
'binary' optionis on, or
'fixeol' option is off, no
<EOL> will be written for thelast line in the file. This option is automatically set or reset whenstarting to edit a new file, depending on whether file has an
<EOL>for the last line in the file. Normally you don't have to set orreset this option.When
'binary' is off and
'fixeol' is on the value is not used whenwriting the file. When
'binary' is on or
'fixeol' is off it is usedto remember the presence of a
<EOL> for the last line in the file, sothat when you write the file the situation from the original file canbe kept. But you can change it if you want to.See
eol-and-eof for example settings.
'equalalways''ea''noequalalways''noea''equalalways''ea'boolean(default on)globalWhen on, all the windows are automatically made the same size aftersplitting or closing a window. This also happens the moment theoption is switched on. When off, splitting a window will reduce thesize of the current window and leave the other windows the same. Whenclosing a window the extra lines are given to the window next to it(depending on
'splitbelow' and
'splitright').When mixing vertically and horizontally split windows, a minimal sizeis computed and some windows may be larger if there is room. The
'eadirection' option tells in which direction the size is affected.Changing the height and width of a window can be avoided by setting
'winfixheight' and
'winfixwidth', respectively.If a window size is specified when creating a new window sizes arecurrently not equalized (it's complicated, but may be implemented inthe future).
'errorbells''eb''noerrorbells''noeb''errorbells''eb'boolean(default off)globalRing the bell (beep or screen flash) for error messages. This onlymakes a difference for error messages, the bell will be used alwaysfor a lot of errors without a message (e.g., hitting
<Esc> in Normalmode). See
'visualbell' to make the bell behave like a screen flashor do nothing. See
'belloff' to finetune when to ring the bell.
'eventignore''ei''eventignore''ei'string(default "")globalA list of autocommand event names, which are to be ignored.When set to "all" or when "all" is one of the items, all autocommandevents are ignored, autocommands will not be executed.Otherwise this is a comma-separated list of event names. Example:
set ei=WinEnter,WinLeave
To ignore all but some events, a "-" prefix can be used:
:set ei=all,-WinLeave
Note: The following events are considered to happen outside of awindow context and thus cannot be ignored by
'eventignorewin':
ChanInfo,
ChanOpen,
CmdUndefined,
CmdlineChanged,
CmdlineEnter,
CmdlineLeave,
CmdlineLeavePre,
CmdwinEnter,
CmdwinLeave,
ColorScheme,
ColorSchemePre,
CompleteChanged,
CompleteDone,
CompleteDonePre,
DiagnosticChanged,
DiffUpdated,
DirChanged,
DirChangedPre,
ExitPre,
FocusGained,
FocusLost,
FuncUndefined,
LspAttach,
LspDetach,
LspNotify,
LspProgress,
LspRequest,
LspTokenUpdate,
MenuPopup,
ModeChanged,
OptionSet,
PackChanged,
PackChangedPre,
QuickFixCmdPost,
QuickFixCmdPre,
QuitPre,
RemoteReply,
SafeState,
SessionLoadPost,
SessionWritePost,
ShellCmdPost,
Signal,
SourceCmd,
SourcePost,
SourcePre,
SpellFileMissing,
StdinReadPost,
StdinReadPre,
SwapExists,
Syntax,
TabClosed,
TabEnter,
TabLeave,
TabNew,
TabNewEntered,
TermClose,
TermEnter,
TermLeave,
TermOpen,
TermRequest,
TermResponse,
UIEnter,
UILeave,
User,
VimEnter,
VimLeave,
VimLeavePre,
VimResized,
VimResume,
VimSuspend,
WinNew Compare
'exrc' to
editorconfig:
'exrc' can execute any code; editorconfig only specifies settings.
'exrc' is Nvim-specific; editorconfig works in other editors.
To achieve project-local LSP configuration:1. Enable
'exrc'.2. Place LSP configs at ".nvim/lsp/*.lua" in your project root.3. Create ".nvim.lua" in your project root directory with this line:
vim.cmd[[set runtimepath+=.nvim]]
This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
When
'fileencoding' is not UTF-8, conversion will be done whenwriting the file. For reading see below.When
'fileencoding' is empty, the file will be saved with UTF-8encoding (no conversion when reading or writing a file).
WARNING: Conversion to a non-Unicode encoding can cause loss ofinformation!
Prepending "8bit-" and "2byte-" has no meaning here, they are ignored.When the option is set, the value is converted to lowercase. Thusyou can set it with uppercase values too. '_' characters arereplaced with '-'. If a name is recognized from the list at
encoding-names, it is replaced by the standard name. For example"ISO8859-2" becomes "iso-8859-2".
When this option is set, after starting to edit a file, the
'modified'option is set, because the file would be different when written.
Keep in mind that changing
'fenc' from a modeline happensAFTER the text has been read, thus it applies to when the file will bewritten. If you do set
'fenc' in a modeline, you might want to set
'nomodified' to avoid not being able to ":q".
'fileencodings''fencs''fileencodings''fencs'string(default "ucs-bom,utf-8,default,latin1")globalThis is a list of character encodings considered when starting to editan existing file. When a file is read, Vim tries to use the firstmentioned character encoding. If an error is detected, the next onein the list is tried. When an encoding is found that works,
'fileencoding' is set to it. If all fail,
'fileencoding' is set toan empty string, which means that UTF-8 is used.
WARNING: Conversion can cause loss of information! You can usethe
++bad argument to specify what is done with charactersthat can't be converted.For an empty file or a file with only ASCII characters most encodingswill work and the first entry of
'fileencodings' will be used (except"ucs-bom", which requires the BOM to be present). If you preferanother encoding use an BufReadPost autocommand event to test if yourpreferred encoding is to be used. Example:
au BufReadPost * if search('\S', 'w') == 0 | \ set fenc=iso-2022-jp | endif
This means that a non-existing file may get a different encoding thanan empty file.The special value "ucs-bom" can be used to check for a Unicode BOM(Byte Order Mark) at the start of the file. It must not be precededby "utf-8" or another Unicode encoding for this to work properly.An entry for an 8-bit encoding (e.g., "latin1") should be the last,because Vim cannot detect an error, thus the encoding is alwaysaccepted.The special value "default" can be used for the encoding from theenvironment. It is useful when your environment uses a non-latin1encoding, such as Russian.When a file contains an illegal UTF-8 byte sequence it won't berecognized as "utf-8". You can use the
8g8 command to find theillegal byte sequence.WRONG VALUES:WHAT'S WRONG:latin1,utf-8"latin1" will always be usedutf-8,ucs-bom,latin1BOM won't be recognized in an utf-8filecp1250,latin1"cp1250" will always be usedIf
'fileencodings' is empty,
'fileencoding' is not modified.See
'fileencoding' for the possible values.Setting this option does not have an effect until the next time a fileis read.
'fileformat''ff''fileformat''ff'string(default Windows: "dos", Unix: "unix")local to bufferThis gives the
<EOL> of the current buffer, which is used forreading/writing the buffer from/to a file: dos
<CR><NL> unix
<NL> mac
<CR>When "dos" is used,
CTRL-Z at the end of a file is ignored.See
file-formats and
file-read.For the character encoding of the file see
'fileencoding'.When
'binary' is set, the value of
'fileformat' is ignored, file I/Oworks like it was set to "unix".This option is set automatically when starting to edit a file and
'fileformats' is not empty and
'binary' is off.When this option is set, after starting to edit a file, the
'modified'option is set, because the file would be different when written.This option cannot be changed when
'modifiable' is off.
'fileformats''ffs''fileformats''ffs'string(default Windows: "dos,unix", Unix: "unix,dos")globalThis gives the end-of-line (
<EOL>) formats that will be tried whenstarting to edit a new buffer and when reading a file into an existingbuffer:
When empty, the format defined with
'fileformat' will be used always. It is not set automatically.
When set to one name, that format will be used whenever a new buffer is opened.
'fileformat' is set accordingly for that buffer. The
'fileformats' name will be used when a file is read into an existing buffer, no matter what
'fileformat' for that buffer is set to.
When more than one name is present, separated by commas, automatic
<EOL> detection will be done when reading a file. When starting to edit a file, a check is done for the
<EOL>: 1. If all lines end in
<CR><NL>, and
'fileformats' includes "dos",
'fileformat' is set to "dos". 2. If a
<NL> is found and
'fileformats' includes "unix",
'fileformat' is set to "unix". Note that when a
<NL> is found without a preceding
<CR>, "unix" is preferred over "dos". 3. If
'fileformat' has not yet been set, and if a
<CR> is found, and if
'fileformats' includes "mac",
'fileformat' is set to "mac". This means that "mac" is only chosen when: "unix" is not present or no
<NL> is found in the file, and "dos" is not present or no
<CR><NL> is found in the file. Except: if "unix" was chosen, but there is a
<CR> before the first
<NL>, and there appear to be more
<CR>s than
<NL>s in the first few lines, "mac" is used. 4. If
'fileformat' is still not set, the first name from
'fileformats' is used. When reading a file into an existing buffer, the same is done, but this happens like
'fileformat' has been set appropriately for that file only, the option is not changed.When
'binary' is set, the value of
'fileformats' is not used.
When Vim starts up with an empty buffer the first item is used. Youcan overrule this by setting
'fileformat' in your .vimrc.
For systems with a Dos-like
<EOL> (
<CR><NL>), when reading files thatare ":source"ed and for vimrc files, automatic
<EOL> detection may bedone:
When
'fileformats' is empty, there is no automatic detection. Dos format will be used.
When
'fileformats' is set to one or more names, automatic detection is done. This is based on the first
<NL> in the file: If there is a
<CR> in front of it, Dos format is used, otherwise Unix format is used.Also see
file-formats.
'filetype''ft''filetype''ft'string(default "")local to buffer
local-noglobalWhen this option is set, the FileType autocommand event is triggered.All autocommands that match with the value of this option will beexecuted. Thus the value of
'filetype' is used in place of the filename.Otherwise this option does not always reflect the current file type.This option is normally set when the file type is detected. To enablethis use the ":filetype on" command.
:filetypeSetting this option to a different value is most useful in a modeline,for a file for which the file type is not automatically recognized.Example, for in an IDL file:
/* vim: set filetype=idl : */
FileTypefiletypesWhen a dot appears in the value then this separates two filetypenames, it should therefore not be used for a filetype. Example:
/* vim: set filetype=c.doxygen : */
This will use the "c" filetype first, then the "doxygen" filetype.This works both for filetype plugins and for syntax files. More thanone dot may appear.This option is not copied to another buffer, independent of the 's' or'S' flag in
'cpoptions'.Only alphanumeric characters, '-' and '_' can be used (and a '.' isallowed as delimiter when combining different filetypes).
itemdefaultUsed for
stl' 'statusline of the current window stlnc' 'statusline of the non-current windows wbr' 'window bar horiz'─' or '-'horizontal separators
:split horizup'┴' or '-'upwards facing horizontal separator horizdown'┬' or '-'downwards facing horizontal separator vert'│' or '|'vertical separators
:vsplit vertleft'┤' or '|'left facing vertical separator vertright'├' or '|'right facing vertical separator verthoriz'┼' or '+'overlapping vertical and horizontalseparator fold'·' or '-'filling
'foldtext' foldopen'-'mark the beginning of a fold foldclose'+'show a closed fold foldsep'│' or '|' open fold middle marker diff'-'deleted lines of the
'diff' option msgsep' 'message separator
'display' eob'~'empty lines at the end of a buffer lastline'@'
'display' contains lastline/truncate trunc'>'truncated text in the
ins-completion-menu. truncrl'<'same as "trunc" in
'rightleft' mode
Any one that is omitted will fall back to the default.
Note that "horiz", "horizup", "horizdown", "vertleft", "vertright" and"verthoriz" are only used when
'laststatus' is 3, since only verticalwindow separators are used otherwise.
If
'ambiwidth' is "double" then "horiz", "horizup", "horizdown","vert", "vertleft", "vertright", "verthoriz", "foldsep" and "fold"default to single-byte alternatives.
Example:
set fillchars=stl:\ ,stlnc:\ ,vert:│,fold:·,diff:-
All items support single-byte and multibyte characters. Butdouble-width characters are not supported.
E1512The function is called with two arguments. The first argument is a
String and is the
:find command argument. The second argument isa
Boolean and is set to
v:true when the function is called to geta List of command-line completion matches for the
:find command.The function should return a List of strings.
The function is called only once per
:find command invocation.The function can process all the directories specified in
'path'.
If a match is found, the function should return a
List containingone or more file names. If a match is not found, the functionshould return an empty List.
If any errors are encountered during the function invocation, anempty List is used as the return value.
It is not allowed to change text or jump to another window whileexecuting the
'findfunc'textlock.
This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
Examples:
" Use glob()func FindFuncGlob(cmdarg, cmdcomplete) let pat = a:cmdcomplete ? $'{a:cmdarg}*' : a:cmdarg return glob(pat, v:false, v:true)endfuncset findfunc=FindFuncGlob" Use the 'git ls-files' outputfunc FindGitFiles(cmdarg, cmdcomplete) let fnames = systemlist('git ls-files') return fnames->filter('v:val =~? a:cmdarg')endfuncset findfunc=FindGitFiles
'foldclose''fcl''foldclose''fcl'string(default "")globalWhen set to "all", a fold is closed when the cursor isn't in it andits level is higher than
'foldlevel'. Useful if you want folds toautomatically close when moving out of them.
'foldcolumn''fdc''foldcolumn''fdc'string(default "0")local to windowWhen and how to draw the foldcolumn. Valid values are: "auto": resize to the minimum amount of folds to display. "auto:[1-9]": resize to accommodate multiple folds up to the selected level "0": to disable foldcolumn "[1-9]": to display a fixed number of columnsSee
folding.
'foldenable''fen''nofoldenable''nofen''foldenable''fen'boolean(default on)local to windowWhen off, all folds are open. This option can be used to quicklyswitch between showing all text unfolded and viewing the text withfolds (including manually opened or closed folds). It can be toggledwith the
zi command. The
'foldcolumn' will remain blank when
'foldenable' is off.This option is set by commands that create a new fold or close a fold.See
folding.
It is not allowed to change text or jump to another window whileevaluating
'foldexpr'textlock.
'foldlevel''fdl''foldlevel''fdl'number(default 0)local to windowSets the fold level: Folds with a higher level will be closed.Setting this option to zero will close all folds. Higher numbers willclose fewer folds.This option is set by commands like
zm,
zM and
zR.See
fold-foldlevel.
'foldlevelstart''fdls''foldlevelstart''fdls'number(default -1)globalSets
'foldlevel' when starting to edit another buffer in a window.Useful to always start editing with all folds closed (value zero),some folds closed (one) or no folds closed (99).This is done before reading any modeline, thus a setting in a modelineoverrules this option. Starting to edit a file for
diff-mode alsoignores this option and closes all folds.It is also done before BufReadPre autocommands, to allow an autocmd tooverrule the
'foldlevel' value for specific files.When the value is negative, it is not used.
'foldminlines''fml''foldminlines''fml'number(default 1)local to windowSets the number of screen lines above which a fold can be displayedclosed. Also for manually closed folds. With the default value ofone a fold can only be closed if it takes up two or more screen lines.Set to zero to be able to close folds of just one screen line.Note that this only has an effect on what is displayed. After using"zc" to close a fold, which is displayed open because it's smallerthan
'foldminlines', a following "zc" may close a containing fold.
'foldnestmax''fdn''foldnestmax''fdn'number(default 20)local to windowSets the maximum nesting of folds for the "indent" and "syntax"methods. This avoids that too many folds will be created. Using morethan 20 doesn't work, because the internal limit is 20.
'foldopen''fdo''foldopen''fdo'string(default "block,hor,mark,percent,quickfix,search,tag,undo")globalSpecifies for which type of commands folds will be opened, if thecommand moves the cursor into a closed fold. It is a comma-separatedlist of items.
NOTE: When the command is part of a mapping this option is not used.Add the
zv command to the mapping to get the same effect.(rationale: the mapping may want to control opening folds itself)
itemcommands
allanyblock(, {, [[, [{, etc.horhorizontal movements: "l", "w", "fx", etc.insertany command in Insert modejumpfar jumps: "G", "gg", etc.markjumping to a mark: "'m",
CTRL-O, etc.percent"%"quickfix":cn", ":crew", ":make", etc.searchsearch for a pattern: "/", "n", "*", "gd", etc.(not for a search pattern in a ":" command)Also for
[s and
]s.tagjumping to a tag: ":ta",
CTRL-T, etc.undoundo or redo: "u" and
CTRL-RWhen a movement command is used for an operator (e.g., "dl" or "y%")this option is not used. This means the operator will include thewhole closed fold.Note that vertical movements are not here, because it would make itvery difficult to move onto a closed fold.In insert mode the folds containing the cursor will always be openwhen text is inserted.To close folds you can re-apply
'foldlevel' with the
zx command orset the
'foldclose' option to "all".
'foldtext''fdt''foldtext''fdt'string(default "foldtext()")local to windowAn expression which is used to specify the text displayed for a closedfold. The context is set to the script where
'foldexpr' was set,script-local items can be accessed. See
fold-foldtext for theusage.
It is not allowed to change text or jump to another window whileevaluating
'foldtext'textlock.
When set to an empty string, foldtext is disabled, and the lineis displayed normally with highlighting and no line wrapping.
The
v:lnum variable holds the first line to be formatted.The
v:count variable holds the number of lines to be formatted.The
v:char variable holds the character that is going to be inserted if the expression is being evaluated due to automatic formatting. This can be empty. Don't insert it yet!
Example:
set formatexpr=mylang#Format()
The advantage of using a function call without arguments is that it isfaster, see
expr-option-function.
The expression is also evaluated when
'textwidth' is set and addingtext beyond that limit. This happens under the same conditions aswhen internal formatting is used. Make sure the cursor is kept in thesame spot relative to the text then! The
mode() function willreturn "i" or "R" in this situation.
When the expression evaluates to non-zero Vim will fall back to usingthe internal format mechanism.
If the expression starts with s: or
<SID>, then it is replaced withthe script ID (
local-function). Example:
set formatexpr=s:MyFormatExpr()set formatexpr=<SID>SomeFormatExpr()
Otherwise, the expression is evaluated in the context of the scriptwhere the option was set, thus script-local items are available.
The expression will be evaluated in the
sandbox when set from amodeline, see
sandbox-option. That stops the option from working,since changing the buffer text is not allowed.This option cannot be set in a modeline when
'modelineexpr' is off.
NOTE: This option is set to "" when
'compatible' is set.
'formatlistpat''flp''formatlistpat''flp'string(default "^\s*\d\+[\]:.)}\t ]\s*")local to bufferA pattern that is used to recognize a list header. This is used forthe "n" flag in
'formatoptions'.The pattern must match exactly the text that will be the indent forthe line below it. You can use
/\ze to mark the end of the matchwhile still checking more characters. There must be a characterfollowing the pattern, when it matches the whole line it is handledlike there is no match.The default recognizes a number, followed by an optional punctuationcharacter and white space.
'formatoptions''fo''formatoptions''fo'string(default "tcqj")local to bufferThis is a sequence of letters which describes how automaticformatting is to be done.See
fo-table for possible values and
gq for how to format text.Commas can be inserted for readability.To avoid problems with flags that are added in the future, use the"+=" and "-=" feature of ":set"
add-option-flags.
'formatprg''fp''formatprg''fp'string(default "")global or local to buffer
global-localThe name of an external program that will be used to format the linesselected with the
gq operator. The program must take the input onstdin and produce the output on stdout. The Unix program "fmt" issuch a program.If the
'formatexpr' option is not empty it will be used instead.Otherwise, if
'formatprg' option is an empty string, the internalformat function will be used
C-indenting.Environment variables are expanded
:set_env. See
option-backslashabout including spaces and backslashes.This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
Files are ALWAYS flushed (
'fsync' is ignored) when:
system signals low battery life
Nvim exits abnormally
This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
'gdefault''gd''nogdefault''nogd''gdefault''gd'boolean(default off)globalWhen on, the ":substitute" flag 'g' is default on. This means thatall matches in a line are substituted instead of one. When a 'g' flagis given to a ":substitute" command, this will toggle the substitutionof all or one match. See
complex-change.
:s/// subst. all subst. one:s///g subst. one subst. all:s///gg subst. all subst. one
NOTE: Setting this option may break plugins that rely on the defaultbehavior of the 'g' flag. This will also make the 'g' flag have theopposite effect of that documented in
:s_g.
If ripgrep (
'grepprg') is available, this option defaults to
%f:%l:%c:%m.
'grepprg''gp''grepprg''gp'string(default see below)global or local to buffer
global-localProgram to use for the
:grep command. This option may contain '%'and '#' characters, which are expanded like when used in a command-line. The placeholder "$*" is allowed to specify where the argumentswill be included. Environment variables are expanded
:set_env. See
option-backslash about including spaces and backslashes.Special value: When
'grepprg' is set to "internal" the
:grep commandworks like
:vimgrep,
:lgrep like
:lvimgrep,
:grepadd like
:vimgrepadd and
:lgrepadd like
:lvimgrepadd.See also the section
:make_makeprg, since most of the comments thereapply equally to
'grepprg'.This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.This option defaults to:
grep -HIn $* /dev/null on Unix,
findstr /n $* nul on Windows.Ripgrep can perform additional filtering such as using .gitignore rulesand skipping hidden files. This is disabled by default (see the -u option)to more closely match the behaviour of standard grep.You can make ripgrep match Vim's case handling using the-i/--ignore-case and -S/--smart-case options.An
OptionSet autocmd can be used to set it up to match automatically.
To disable cursor-styling, reset the option:
set guicursor=
To enable mode shapes, "Cursor" highlight, and blinking:
set guicursor=n-v-c:block,i-ci-ve:ver25,r-cr:hor20,o:hor50 \,a:blinkwait700-blinkoff400-blinkon250-Cursor/lCursor \,sm:block-blinkwait175-blinkoff150-blinkon175
The option is a comma-separated list of parts. Each part consists of amode-list and an argument-list:mode-list:argument-list,mode-list:argument-list,..The mode-list is a dash separated list of these modes:nNormal modevVisual modeveVisual mode with
'selection' "exclusive" (same as 'v',if not specified)oOperator-pending modeiInsert moderReplace modecCommand-line Normal (append) modeciCommand-line Insert modecrCommand-line Replace modesmshowmatch in Insert modetTerminal modeaall modesThe argument-list is a dash separated list of these arguments:hor{N}horizontal bar,
{N} percent of the character heightver{N}vertical bar,
{N} percent of the character widthblockblock cursor, fills the whole character
Only one of the above three should be present.
Default is "block" for each mode.blinkwait{N}
cursor-blinkingblinkon{N}blinkoff{N}blink times for cursor: blinkwait is the delay beforethe cursor starts blinking, blinkon is the time thatthe cursor is shown and blinkoff is the time that thecursor is not shown. Times are in msec. When one ofthe numbers is zero, there is no blinking. E.g.:
set guicursor=n:blinkon0
Default is "blinkon0" for each mode.
{group-name}Highlight group that decides the color and font of thecursor.In the
TUI:
inverse/reverse and no group-name are interpreted as "host-terminal default cursor colors" which typically means "inverted bg and fg colors".
ctermfg and
guifg are ignored.
{group-name}/{group-name}Two highlight group names, the first is used whenno language mappings are used, the other when theyare.
language-mapping Examples of parts: n-c-v:block-nCursorIn Normal, Command-line and Visual mode, use ablock cursor with colors from the "nCursor"highlight group n-v-c-sm:block,i-ci-ve:ver25-Cursor,r-cr-o:hor20In Normal et al. modes, use a block cursorwith the default colors defined by the hostterminal. In Insert-like modes, usea vertical bar cursor with colors from"Cursor" highlight group. In Replace-likemodes, use an underline cursor withdefault colors. i-ci:ver30-iCursor-blinkwait300-blinkon200-blinkoff150In Insert and Command-line Insert mode, use a30% vertical bar cursor with colors from the"iCursor" highlight group. Blink a bitfaster.
The 'a' mode is different. It will set the given argument-list forall modes. It does not reset anything to defaults. This can be usedto do a common setting for all modes. For example, to switch offblinking: "a:blinkon0"
Examples of cursor highlighting:
highlight Cursor gui=reverse guifg=NONE guibg=NONEhighlight Cursor gui=NONE guifg=bg guibg=fg
'guifont''gfn'E235E596'guifont''gfn'string(default "")globalThis is a list of fonts which will be used for the GUI version of Vim.In its simplest form the value is just one font name. Whenthe font cannot be found you will get an error message. To try otherfont names a list can be specified, font names separated with commas.The first valid font is used.
Spaces after a comma are ignored. To include a comma in a font nameprecede it with a backslash. Setting an option requires an extrabackslash before a space and a backslash. See also
option-backslash. For example:
set guifont=Screen15,\ 7x13,font\\,with\\,commas
will make Vim try to use the font "Screen15" first, and if it fails itwill try to use "7x13" and then "font,with,commas" instead.
If none of the fonts can be loaded, Vim will keep the current setting.If an empty font list is given, Vim will try using other resourcesettings (for X, it will use the Vim.font resource), and finally itwill try some builtin default which should always be there ("7x13" inthe case of X). The font names given should be "normal" fonts. Vimwill try to find the related bold and italic fonts.
For Win32 and Mac OS:
set guifont=*
will bring up a font requester, where you can pick the font you want.
The font name depends on the GUI used.
For Mac OSX you can use something like this:
set guifont=Monaco:h10
E236Note that the fonts must be mono-spaced (all characters have the samewidth).
To preview a font on X11, you might be able to use the "xfontsel"program. The "xlsfonts" program gives a list of all available fonts.
For the Win32 GUI
E244E245 takes these options in the font name:hXX - height is XX (points, can be floating-point)wXX - width is XX (points, can be floating-point)b - boldi - italicu - underlines - strikeoutcXX - character set XX. Valid charsets are: ANSI, ARABIC, BALTIC, CHINESEBIG5, DEFAULT, EASTEUROPE, GB2312, GREEK, HANGEUL, HEBREW, JOHAB, MAC, OEM, RUSSIAN, SHIFTJIS, SYMBOL, THAI, TURKISH, VIETNAMESE ANSI and BALTIC. Normally you would use "cDEFAULT".
Use a ':' to separate the options.
A '_' can be used in the place of a space, so you don't need to use backslashes to escape the spaces.
Examples:
set guifont=courier_new:h12:w5:b:cRUSSIANset guifont=Andale_Mono:h7.5:w4.5
'guifontwide''gfw'E231E533E534'guifontwide''gfw'string(default "")globalComma-separated list of fonts to be used for double-width characters.The first font that can be loaded is used.
Note: The size of these fonts must be exactly twice as wide as the onespecified with
'guifont' and the same height.
'helpfile''hf''helpfile''hf'string(default (MS-Windows) "$VIMRUNTIME\doc\help.txt" (others) "$VIMRUNTIME/doc/help.txt")globalName of the main help file. All distributed help files should beplaced together in one directory. Additionally, all "doc" directoriesin
'runtimepath' will be used.Environment variables are expanded
:set_env. For example:"$VIMRUNTIME/doc/help.txt". If $VIMRUNTIME is not set, $VIM is alsotried. Also see
$VIMRUNTIME and
option-backslash about includingspaces and backslashes.This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
'helpheight''hh''helpheight''hh'number(default 20)globalMinimal initial height of the help window when it is opened with the":help" command. The initial height of the help window is half of thecurrent window, or (when the
'ea' option is on) the same as otherwindows. When the height is less than
'helpheight', the height isset to
'helpheight'. Set to zero to disable.
'helplang''hlg''helplang''hlg'string(default messages language or empty)globalComma-separated list of languages. Vim will use the first languagefor which the desired help can be found. The English help will alwaysbe used as a last resort. You can add "en" to prefer English overanother language, but that will only find tags that exist in thatlanguage and not in the English help.Example:
set helplang=de,it
This will first search German, then Italian and finally English helpfiles.When using
CTRL-] and ":help!" in a non-English help file Vim willtry to find the tag in the current language before using this option.See
help-translated.
Commands that move through the buffer list sometimes hide a bufferalthough the
'hidden' option is off when these three are true:
the buffer is modified
the '!' flag was usedAlso see
windows.
'history''hi''history''hi'number(default 10000)globalA history of ":" commands, and a history of previous search patternsis remembered. This option decides how many entries may be stored ineach of these histories (see
cmdline-editing and
'messagesopt' forthe number of messages to remember).The maximum value is 10000.
'hlsearch''hls''nohlsearch''nohls''hlsearch''hls'boolean(default on)globalWhen there is a previous search pattern, highlight all its matches.The
hl-Search highlight group determines the highlighting for allmatches not under the cursor while the
hl-CurSearch highlight group(if defined) determines the highlighting for the match under thecursor. If
hl-CurSearch is not defined, then
hl-Search is used forboth. Note that only the matching text is highlighted, any offsetsare not applied.See also:
'incsearch' and
:match.When you get bored looking at the highlighted matches, you can turn itoff with
:nohlsearch. This does not change the option value, assoon as you use a search command, the highlighting comes back.
'redrawtime' specifies the maximum time spent on finding matches.When the search pattern can match an end-of-line, Vim will try tohighlight all of the matched text. However, this depends on where thesearch starts. This will be the first line in the window or the firstline below a closed fold. A match in a previous line which is notdrawn may not continue in a newly drawn line.You can specify whether the highlight status is restored on startupwith the 'h' flag in
'shada'shada-h.
'icon''noicon''icon'boolean(default off, on when title can be restored)globalWhen on, the icon text of the window will be set to the value of
'iconstring' (if it is not empty), or to the name of the filecurrently being edited. Only the last part of the name is used.Overridden by the
'iconstring' option.Only works if the terminal supports setting window icons.
'iconstring''iconstring'string(default "")globalWhen this option is not empty, it will be used for the icon text ofthe window. This happens only when the
'icon' option is on.Only works if the terminal supports setting window icon textWhen this option contains printf-style '%' items, they will beexpanded according to the rules used for
'statusline'. See
'titlestring' for example settings.This option cannot be set in a modeline when
'modelineexpr' is off.
'iminsert''imi''iminsert''imi'number(default 0)local to bufferSpecifies whether :lmap or an Input Method (IM) is to be used inInsert mode. Valid values:0:lmap is off and IM is off1:lmap is ON and IM is off2:lmap is off and IM is ONTo always reset the option to zero when leaving Insert mode with
<Esc>this can be used:
inoremap <ESC> <ESC>:set iminsert=0<CR>
This makes :lmap and IM turn off automatically when leaving Insertmode.Note that this option changes when using
CTRL-^ in Insert mode
i_CTRL-^.The value is set to 1 when setting
'keymap' to a valid keymap name.It is also used for the argument of commands like "r" and "f".
'imsearch''ims''imsearch''ims'number(default -1)local to bufferSpecifies whether :lmap or an Input Method (IM) is to be used whenentering a search pattern. Valid values:-1the value of
'iminsert' is used, makes it look like
'iminsert' is also used when typing a search pattern0:lmap is off and IM is off1:lmap is ON and IM is off2:lmap is off and IM is ONNote that this option changes when using
CTRL-^ in Command-line mode
c_CTRL-^.The value is set to 1 when it is not -1 and setting the
'keymap'option to a valid keymap name.
Possible values:nosplitShows the effects of a command incrementally in thebuffer.splitLike "nosplit", but also shows partial off-screenresults in a preview window.
'include''inc''include''inc'string(default "")global or local to buffer
global-localPattern to be used to find an include command. It is a searchpattern, just like for the "/" command (See
pattern). This optionis used for the commands "[i", "]I", "[d", etc.Normally the
'isfname' option is used to recognize the file name thatcomes after the matched pattern. But if "\zs" appears in the patternthen the text matched from "\zs" to the end, or until "\ze" if itappears, is used as the file name. Use this to include charactersthat are not in
'isfname', such as a space. You can then use
'includeexpr' to process the matched text.See
option-backslash about including spaces and backslashes.
'includeexpr''inex''includeexpr''inex'string(default "")local to bufferExpression to be used to transform the string found with the
'include'option to a file name. Mostly useful to change "." to "/" for Java:
setlocal includeexpr=substitute(v:fname,'\\.','/','g')
The "v:fname" variable will be set to the file name that was detected.Note the double backslash: the
:set command first halves them, thenone remains in the value, where "\." matches a dot literally. Forsimple character replacements
tr() avoids the need for escaping:
setlocal includeexpr=tr(v:fname,'.','/')
Also used for the
gf command if an unmodified file name can't befound. Allows doing "gf" on the name after an
'include' statement.
Note: Not used for
<cfile>.
If the expression starts with s: or
<SID>, then it is replaced withthe script ID (
local-function). Example:
setlocal includeexpr=s:MyIncludeExpr()setlocal includeexpr=<SID>SomeIncludeExpr()
Otherwise, the expression is evaluated in the context of the scriptwhere the option was set, thus script-local items are available.
It is more efficient if the value is just a function call withoutarguments, see
expr-option-function.
'incsearch''is''noincsearch''nois''incsearch''is'boolean(default on)globalWhile typing a search command, show where the pattern, as it was typedso far, matches. The matched string is highlighted. If the patternis invalid or not found, nothing is shown. The screen will be updatedoften, this is only useful on fast terminals.Note that the match will be shown, but the cursor will return to itsoriginal position when no match is found and when pressing
<Esc>. Youstill need to finish the search command with
<Enter> to move thecursor to the match.You can use the
CTRL-G and
CTRL-T keys to move to the next andprevious match.
c_CTRL-Gc_CTRL-TVim only searches for about half a second. With a complicatedpattern and/or a lot of text the match may not be found. This is toavoid that Vim hangs while you are typing the pattern.The
hl-IncSearch highlight group determines the highlighting.When
'hlsearch' is on, all matched strings are highlighted too whiletyping a search command. See also:
'hlsearch'.If you don't want to turn
'hlsearch' on, but want to highlight allmatches while searching, you can turn on and off
'hlsearch' withautocmd. Example:
augroup vimrc-incsearch-highlight autocmd! autocmd CmdlineEnter /,\? :set hlsearch autocmd CmdlineLeave /,\? :set nohlsearchaugroup END
CTRL-L can be used to add one character from after the current matchto the command line. If
'ignorecase' and
'smartcase' are set and thecommand line has no uppercase characters, the added character isconverted to lowercase.
CTRL-RCTRL-W can be used to add the word at the end of the currentmatch, excluding the characters that were already typed.
'indentexpr''inde''indentexpr''inde'string(default "")local to bufferExpression which is evaluated to obtain the proper indent for a line.It is used when a new line is created, for the
= operator andin Insert mode as specified with the
'indentkeys' option.When this option is not empty, it overrules the
'cindent' and
'smartindent' indenting. When
'lisp' is set, this option isonly used when
'lispoptions' contains "expr:1".The expression is evaluated with
v:lnum set to the line number forwhich the indent is to be computed. The cursor is also in this linewhen the expression is evaluated (but it may be moved around).
If the expression starts with s: or
<SID>, then it is replaced withthe script ID (
local-function). Example:
set indentexpr=s:MyIndentExpr()set indentexpr=<SID>SomeIndentExpr()
Otherwise, the expression is evaluated in the context of the scriptwhere the option was set, thus script-local items are available.
The advantage of using a function call without arguments is that it isfaster, see
expr-option-function.
The expression must return the number of spaces worth of indent. Itcan return "-1" to keep the current indent (this means
'autoindent' isused for the indent).Functions useful for computing the indent are
indent(),
cindent()and
lispindent().The evaluation of the expression must not have side effects! It mustnot change the text, jump to another window, etc. Afterwards thecursor position is always restored, thus the cursor may be moved.Normally this option would be set to call a function:
set indentexpr=GetMyIndent()
'indentkeys''indk''indentkeys''indk'string(default "0{,0},0),0],:,0#,!^F,o,O,e")local to bufferA list of keys that, when typed in Insert mode, cause reindenting ofthe current line. Only happens if
'indentexpr' isn't empty.The format is identical to
'cinkeys', see
indentkeys-format.See
C-indenting and
indent-expression.
'infercase''inf''noinfercase''noinf''infercase''inf'boolean(default off)local to bufferWhen doing keyword completion in insert mode
ins-completion, and
'ignorecase' is also on, the case of the match is adjusted dependingon the typed text. If the typed text contains a lowercase letterwhere the match has an upper case letter, the completed part is madelowercase. If the typed text has no lowercase letters and the matchhas a lowercase letter where the typed text has an uppercase letter,and there is a letter before it, the completed part is made uppercase.With
'noinfercase' the match is used as-is.
'isexpand''ise''isexpand''ise'string(default "")global or local to buffer
global-localDefines characters and patterns for completion in insert mode. Usedby the
complete_match() function to determine the starting positionfor completion. This is a comma-separated list of triggers. Eachtrigger can be:
A single character like "." or "/"
A sequence of characters like "->", "/*", or "/**"
Note: Use "\\," to add a literal comma as trigger character, see
option-backslash.
Examples:
set isexpand=.,->,/*,\\,
'isfname''isf''isfname''isf'string(default for Windows: "@,48-57,/,\,.,-,_,+,,,#,$,%,{,},[,],@-@,!,~,=" otherwise: "@,48-57,/,.,-,_,+,,,#,$,%,~,=")globalThe characters specified by this option are included in file names andpath names. Filenames are used for commands like "gf", "[i" and inthe tags file. It is also used for "\f" in a
pattern.Multi-byte characters 256 and above are always included, only thecharacters up to 255 are specified with this option.For UTF-8 the characters 0xa0 to 0xff are included as well.Think twice before adding white space to this option. Although aspace may appear inside a file name, the effect will be that Vimdoesn't know where a file name starts or ends when doing completion.It most likely works better without a space in
'isfname'.
Note that on systems using a backslash as path separator, Vim tries todo its best to make it work as you would expect. That is a bittricky, since Vi originally used the backslash to escape specialcharacters. Vim will not remove a backslash in front of a normal filename character on these systems, but it will on Unix and alikes. The'&' and '^' are not included by default, because these are special forcmd.exe.
The format of this option is a list of parts, separated with commas.Each part can be a single character number or a range. A range is twocharacter numbers with '-' in between. A character number can be adecimal number between 0 and 255 or the ASCII character itself (doesnot work for digits). Example:"_,-,128-140,#-43"(include '_' and '-' and the range128 to 140 and '#' to 43)If a part starts with '^', the following character number or rangewill be excluded from the option. The option is interpreted from leftto right. Put the excluded character after the range where it isincluded. To include '^' itself use it as the last character of theoption or the end of a range. Example:"^a-z,#,^"(exclude 'a' to 'z', include '#' and '^')If the character is '@', all characters where isalpha() returns TRUEare included. Normally these are the characters a to z and A to Z,plus accented characters. To include '@' itself use "@-@". Examples:"@,^a-z"All alphabetic characters, excluding lowercase ASCII letters."a-z,A-Z,@-@"All letters plus the '@' character.A comma can be included by using it where a character number isexpected. Example:"48-57,,,_"Digits, comma and underscore.A comma can be excluded by prepending a '^'. Example:" -~,^,,9"All characters from space to '~', excludingcomma, plus
<Tab>.See
option-backslash about including spaces and backslashes.
'isident''isi''isident''isi'string(default for Windows: "@,48-57,_,128-167,224-235" otherwise: "@,48-57,_,192-255")globalThe characters given by this option are included in identifiers.Identifiers are used in recognizing environment variables and after amatch of the
'define' option. It is also used for "\i" in a
pattern. See
'isfname' for a description of the format of thisoption. For '@' only characters up to 255 are used.Careful: If you change this option, it might break expandingenvironment variables. E.g., when '/' is included and Vim tries toexpand "$HOME/.local/state/nvim/shada/main.shada". Maybe you shouldchange
'iskeyword' instead.
'iskeyword''isk''iskeyword''isk'string(default "@,48-57,_,192-255")local to bufferKeywords are used in searching and recognizing with many commands:"w", "*", "[i", etc. It is also used for "\k" in a
pattern. See
'isfname' for a description of the format of this option. For '@'characters above 255 check the "word" character class (any characterthat is not white space or punctuation).For C programs you could use "a-z,A-Z,48-57,_,.,-,>".For a help file it is set to all non-blank printable characters except"*", '"' and '|' (so that
CTRL-] on a command finds the help for thatcommand).When the
'lisp' option is on the '-' character is always included.This option also influences syntax highlighting, unless the syntaxuses
:syn-iskeyword.
'isprint''isp''isprint''isp'string(default "@,161-255")globalThe characters given by this option are displayed directly on thescreen. It is also used for "\p" in a
pattern. The characters fromspace (ASCII 32) to '~' (ASCII 126) are always displayed directly,even when they are not included in
'isprint' or excluded. See
'isfname' for a description of the format of this option.
Non-printable characters are displayed with two characters: 0 - 31"^@" - "^_" 32 - 126always single characters 127"^?"128 - 159"~@" - "~_"160 - 254"| " - "|~" 255"~?"Illegal bytes from 128 to 255 (invalid UTF-8) aredisplayed as
<xx>, with the hexadecimal value of the byte.When
'display' contains "uhex" all unprintable characters aredisplayed as
<xx>.The SpecialKey highlighting will be used for unprintable characters.
hl-SpecialKeyMulti-byte characters 256 and above are always included, only thecharacters up to 255 are specified with this option. When a characteris printable but it is not available in the current font, areplacement character will be shown.Unprintable and zero-width Unicode characters are displayed as<xxxx>.There is no option to specify these characters.
'jumpoptions''jop''jumpoptions''jop'string(default "clean")globalList of words that change the behavior of the
jumplist. stack Make the jumplist behave like the tagstack.Relative location of entries in the jumplist ispreserved at the cost of discarding subsequent entrieswhen navigating backwards in the jumplist and thenjumping to a location.
jumplist-stack clean Remove unloaded buffers from the jumplist.EXPERIMENTAL: this flag may change in the future.
'keymap''kmp''keymap''kmp'string(default "")local to bufferName of a keyboard mapping. See
mbyte-keymap.Setting this option to a valid keymap name has the side effect ofsetting
'iminsert' to one, so that the keymap becomes effective.
'imsearch' is also set to one, unless it was -1Only alphanumeric characters, '.', '-' and '_' can be used.
'keymodel''km''keymodel''km'string(default "")globalList of comma-separated words, which enable special things that keyscan do. These values can be used: startselUsing a shifted special key starts selection (eitherSelect mode or Visual mode, depending on "key" beingpresent in
'selectmode'). stopselUsing a not-shifted special key stops selection.Special keys in this context are the cursor keys,
<End>,
<Home>,
<PageUp> and
<PageDown>.
'keywordprg''kp''keywordprg''kp'string(default ":Man", Windows: ":help")global or local to buffer
global-localProgram to use for the
K command. Environment variables areexpanded
:set_env. ":help" may be used to access the Vim internalhelp. (Note that previously setting the global option to the emptyvalue did this, which is now deprecated.)When the first character is ":", the command is invoked as a VimEx command prefixed with [count].When "man" or "man -s" is used, Vim will automatically translatea [count] for the "K" command to a section number.See
option-backslash about including spaces and backslashes.Example:
set keywordprg=man\ -sset keywordprg=:Man
This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
'langmap''lmap'E357E358'langmap''lmap'string(default "")globalThis option allows switching your keyboard into a special languagemode. When you are typing text in Insert mode the characters areinserted directly. When in Normal mode the
'langmap' option takescare of translating these special characters to the original meaningof the key. This means you don't have to change the keyboard mode tobe able to execute Normal mode commands.This is the opposite of the
'keymap' option, where characters aremapped in Insert mode.Also consider setting
'langremap' to off, to prevent
'langmap' fromapplying to characters resulting from a mapping.This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
Example (for Greek, in UTF-8):
greekset langmap=ΑA,ΒB,ΨC,ΔD,ΕE,ΦF,ΓG,ΗH,ΙI,ΞJ,ΚK,ΛL,ΜM,ΝN,ΟO,ΠP,QQ,ΡR,ΣS,ΤT,ΘU,ΩV,WW,ΧX,ΥY,ΖZ,αa,βb,ψc,δd,εe,φf,γg,ηh,ιi,ξj,κk,λl,μm,νn,οo,πp,qq,ρr,σs,τt,θu,ωv,ςw,χx,υy,ζz
Example (exchanges meaning of z and y for commands):
set langmap=zy,yz,ZY,YZ
The
'langmap' option is a list of parts, separated with commas. Eachpart can be in one of two forms:1. A list of pairs. Each pair is a "from" character immediately followed by the "to" character. Examples: "aA", "aAbBcC".2. A list of "from" characters, a semicolon and a list of "to" characters. Example: "abc;ABC"Example: "aA,fgh;FGH,cCdDeE"Special characters need to be preceded with a backslash. These are";", ',', '"', '|' and backslash itself.
This will allow you to activate vim actions without having to switchback and forth between the languages. Your language characters willbe understood as normal vim English characters (according to thelangmap mappings) in the following cases: o Normal/Visual mode (commands, buffer/register names, user mappings) o Insert/Replace Mode: Register names afterCTRL-R o Insert/Replace Mode: MappingsCharacters entered in Command-line mode will NOT be affected bythis option. Note that this option can be changed at any timeallowing to switch between mappings for different languages/encodings.Use a mapping to avoid having to type it each time!
(without the spaces). For example, to always use the Dutch menus, nomatter what $LANG is set to:
set langmenu=nl_NL.ISO_8859-1
When
'langmenu' is empty,
v:lang is used.Only normal file name characters can be used,
/\*?[|<> are illegal.If your $LANG is set to a non-English language but you do want to usethe English menus:
set langmenu=none
This option must be set before loading menus, switching on filetypedetection or syntax highlighting. Once the menus are defined settingthis option has no effect. But you could do this:
source $VIMRUNTIME/delmenu.vimset langmenu=de_DE.ISO_8859-1source $VIMRUNTIME/menu.vim
Warning: This deletes all menus that you defined yourself!
'laststatus''ls''laststatus''ls'number(default 2)globalThe value of this option influences when the last window will have astatus line:0: never1: only if there are at least two windows2: always3: always and ONLY the last windowThe screen looks nicer with a status line if you have severalwindows, but it takes another screen line.
status-line 'lazyredraw''lz''nolazyredraw''nolz''lazyredraw''lz'boolean(default off)globalWhen this option is set, the screen will not be redrawn whileexecuting macros, registers and other commands that have not beentyped. Also, updating the window title is postponed. To force anupdate use
:redraw.This may occasionally cause display errors. It is only meant to be settemporarily when performing an operation where redrawing may causeflickering or cause a slowdown.
'lhistory''lhi''lhistory''lhi'number(default 10)local to windowLike
'chistory', but for the location list stack associated with awindow. If the option is changed in either the location list windowitself or the window that is associated with the location list stack,the new value will also be applied to the other one. This means thisvalue will always be the same for a given location list window and itscorresponding window. See
quickfix-stack for additional info.
'linebreak''lbr''nolinebreak''nolbr''linebreak''lbr'boolean(default off)local to windowIf on, Vim will wrap long lines at a character in
'breakat' ratherthan at the last character that fits on the screen. Unlike
'wrapmargin' and
'textwidth', this does not insert
<EOL>s in the file,it only affects the way the file is displayed, not its contents.If
'breakindent' is set, line is visually indented. Then, the valueof
'showbreak' is used to put in front of wrapped lines. This optionis not used when the
'wrap' option is off.Note that
<Tab> characters after an
<EOL> are mostly not displayedwith the right amount of white space.
'lines'E593'lines'number(default 24 or terminal height)globalNumber of lines of the Vim window.Normally you don't need to set this. It is done automatically by theterminal initialization code.When Vim is running in the GUI or in a resizable window, setting thisoption will cause the window size to be changed. When you only wantto use the size for the GUI, put the command in your
gvimrc file.Vim limits the number of lines to what fits on the screen. You canuse this command to get the tallest window possible:
set lines=999
Minimum value is 2, maximum value is 1000.
'linespace''lsp''linespace''lsp'number(default 0)globalonly in the GUINumber of pixel lines inserted between characters. Useful if the fontuses the full character cell height, making lines touch each other.When non-zero there is room for underlining.With some fonts there can be too much room between lines (to havespace for ascents and descents). Then it makes sense to set
'linespace' to a negative value. This may cause display problemsthough!
'lisp''nolisp''lisp'boolean(default off)local to bufferLisp mode: When
<Enter> is typed in insert mode set the indent forthe next line to Lisp standards (well, sort of). Also happens with"cc" or "S".
'autoindent' must also be on for this to work. The 'p'flag in
'cpoptions' changes the method of indenting: Vi compatible orbetter. Also see
'lispwords'.The '-' character is included in keyword characters. Redefines the"=" operator to use this same indentation algorithm rather thancalling an external program if
'equalprg' is empty.
'lispoptions''lop''lispoptions''lop'string(default "")local to bufferComma-separated list of items that influence the Lisp indenting whenenabled with the
'lisp' option. Currently only one item issupported:expr:1use
'indentexpr' for Lisp indenting when it is setexpr:0do not use
'indentexpr' for Lisp indenting (default)Note that when using
'indentexpr' the
= operator indents all thelines, otherwise the first line is not indented (Vi-compatible).
'list''nolist''list'boolean(default off)local to windowList mode: By default, show tabs as ">", trailing spaces as "-", andnon-breakable space characters as "+". Useful to see the differencebetween tabs and spaces and for trailing blanks. Further changed bythe
'listchars' option.
When
'listchars' does not contain "tab" field, tabs are shown as "^I"or "<09>", like how unprintable characters are displayed.
The cursor is displayed at the start of the space a Tab characteroccupies, not at the end as usual in Normal mode. To get this cursorposition while displaying Tabs with spaces, use:
set list lcs=tab:\ \
lcs-eol eol:cCharacter to show at the end of each line. Whenomitted, there is no extra character at the end of theline.
lcs-tab tab:xy[z]Two or three characters to be used to show a tab.The third character is optional.
tab:xyThe 'x' is always used, then 'y' as many times as willfit. Thus "tab:>-" displays:
>>->--etc.
tab:xyzThe 'z' is always used, then 'x' is prepended, andthen 'y' is used as many times as will fit. Thus"tab:<->" displays:
><><-><-->etc.
When "tab:" is omitted, a tab is shown as ^I.
lcs-space space:cCharacter to show for a space. When omitted, spacesare left blank.
lcs-multispace multispace:c...One or more characters to use cyclically to show formultiple consecutive spaces. Overrides the "space"setting, except for single spaces. When omitted, the"space" setting is used. For example,
:set listchars=multispace:---+ shows ten consecutivespaces as:
---+---+--
lcs-lead lead:cCharacter to show for leading spaces. When omitted,leading spaces are blank. Overrides the "space" and"multispace" settings for leading spaces. You cancombine it with "tab:", for example:
set listchars+=tab:>-,lead:.
lcs-leadmultispace leadmultispace:c...Like the
lcs-multispace value, but for leadingspaces only. Also overrides
lcs-lead for leadingmultiple spaces.
:set listchars=leadmultispace:---+ shows tenconsecutive leading spaces as:
---+---+--XXX
Where "XXX" denotes the first non-blank characters inthe line.
lcs-trail trail:cCharacter to show for trailing spaces. When omitted,trailing spaces are blank. Overrides the "space" and"multispace" settings for trailing spaces.
lcs-extends extends:cCharacter to show in the last column, when
'wrap' isoff and the line continues beyond the right of thescreen.
lcs-precedes precedes:cCharacter to show in the first visible column of thephysical line, when there is text preceding thecharacter visible in the first column.
lcs-conceal conceal:cCharacter to show in place of concealed text, when
'conceallevel' is set to 1. A space when omitted.
lcs-nbsp nbsp:cCharacter to show for a non-breakable space character(0xA0 (160 decimal) and U+202F). Left blank whenomitted.
The characters ':' and ',' should not be used. UTF-8 characters canbe used. All characters must be single width.
E1512Each character can be specified as hex:
set listchars=eol:\\x24set listchars=eol:\\u21b5set listchars=eol:\\U000021b5
Note that a double backslash is used. The number of hex charactersmust be exactly 2 for \\x, 4 for \\u and 8 for \\U.
Examples:
set lcs=tab:>-,trail:-set lcs=tab:>-,eol:<,nbsp:%set lcs=extends:>,precedes:<
hl-NonText highlighting will be used for "eol", "extends" and"precedes".
hl-Whitespace for "nbsp", "space", "tab", "multispace","lead" and "trail".
'magic''nomagic''magic'boolean(default on)globalChanges the special characters that can be used in search patterns.See
pattern.
WARNING: Switching this option off most likely breaks plugins! Thatis because many patterns assume it's on and will fail when it's off.Only switch it off when working with old Vi scripts. In any othersituation write patterns that work when
'magic' is on. Include "\M"when you want to
/\M.
'makeef''mef''makeef''mef'string(default "")globalName of the errorfile for the
:make command (see
:make_makeprg)and the
:grep command.When it is empty, an internally generated temp file will be used.When "##" is included, it is replaced by a number to make the nameunique. This makes sure that the ":make" command doesn't overwrite anexisting file.NOT used for the ":cf" command. See
'errorfile' for that.Environment variables are expanded
:set_env.See
option-backslash about including spaces and backslashes.This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
'makeencoding''menc''makeencoding''menc'string(default "")global or local to buffer
global-localEncoding used for reading the output of external commands. When empty,encoding is not converted.This is used for
:make,
:lmake,
:grep,
:lgrep,
:grepadd,
:lgrepadd,
:cfile,
:cgetfile,
:caddfile,
:lfile,
:lgetfile,and
:laddfile.
This would be mostly useful when you use MS-Windows. If iconv isenabled, setting
'makeencoding' to "char" has the same effect assetting to the system locale encoding. Example:
set makeencoding=char" system locale is used
'makeprg''mp''makeprg''mp'string(default "make")global or local to buffer
global-localProgram to use for the ":make" command. See
:make_makeprg.This option may contain '%' and '#' characters (see
:_% and
:_#),which are expanded to the current and alternate file name. Use
::Sto escape file names in case they contain special characters.Environment variables are expanded
:set_env. See
option-backslashabout including spaces and backslashes.Note that a '|' must be escaped twice: once for ":set" and once forthe interpretation of a command. When you use a filter called"myfilter" do it like this:
set makeprg=gmake\ \\\|\ myfilter
The placeholder "$*" can be given (even multiple times) to specifywhere the arguments will be included, for example:
set makeprg=latex\ \\\\nonstopmode\ \\\\input\\{$*}
This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
'matchpairs''mps''matchpairs''mps'string(default "(:),
{:},[:]")local to bufferCharacters that form pairs. The
% command jumps from one to theother.Only character pairs are allowed that are different, thus you cannotjump between two double quotes.The characters must be separated by a colon.The pairs must be separated by a comma. Example for including '<' and'>' (for HTML):
set mps+=<:>
A more exotic example, to jump between the '=' and ';' in anassignment, useful for languages like C and Java:
au FileType c,cpp,java set mps+==:;
For a more advanced way of using "%", see the matchit.vim plugin inthe $VIMRUNTIME/plugin directory.
add-local-help'matchtime''mat''matchtime''mat'number(default 5)globalTenths of a second to show the matching paren, when
'showmatch' isset. Note that this is not in milliseconds, like other options thatset a time. This is to be compatible with Nvi.
'maxfuncdepth''mfd''maxfuncdepth''mfd'number(default 100)globalMaximum depth of function calls for user functions. This normallycatches endless recursion. When using a recursive function withmore depth, set
'maxfuncdepth' to a bigger number. But this will usemore memory, there is the danger of failing when memory is exhausted.Increasing this limit above 200 also changes the maximum for Excommand recursion, see
E169.See also
:function.Also used for maximum depth of callback functions.
'maxmapdepth''mmd'E223'maxmapdepth''mmd'number(default 1000)globalMaximum number of times a mapping is done without resulting in acharacter to be used. This normally catches endless mappings, like":map x y" with ":map y x". It still does not catch ":map g wg",because the 'w' is used before the next mapping is done. See also
key-mapping.
'maxmempattern''mmp''maxmempattern''mmp'number(default 1000)globalMaximum amount of memory (in Kbyte) to use for pattern matching.The maximum value is about 2000000. Use this to work without a limit.
E363When Vim runs into the limit it gives an error message and mostlybehaves like
CTRL-C was typed.Running into the limit often means that the pattern is veryinefficient or too complex. This may already happen with the pattern"\(.\)*" on a very long line. ".*" works much better.Might also happen on redraw, when syntax rules try to match a complextext structure.Vim may run out of memory before hitting the
'maxmempattern' limit, inwhich case you get an "Out of memory" error instead.
'maxsearchcount''msc''maxsearchcount''msc'number(default 999)globalMaximum number of matches shown for the search count status
shm-SWhen the number of matches exceeds this value, Vim shows ">" insteadof the exact count to keep searching fast.
Note: larger values may impact performance.The value must be between 1 and 9999.
'menuitems''mis''menuitems''mis'number(default 25)globalMaximum number of items to use in a menu. Used for menus that aregenerated from a list of items, e.g., the Buffers menu. Changing thisoption has no direct effect, the menu must be refreshed first.
'messagesopt''mopt''messagesopt''mopt'string(default "hit-enter,history:500")globalOption settings for outputting messages. It can consist of thefollowing items. Items must be separated by a comma.
wait:{n}Instead of using a
hit-enter prompt, simply wait for
{n} milliseconds so that the user has a chance to readthe message. The maximum value of
{n} is 10000. Use0 to disable the wait (but then the user may miss animportant message).This item is ignored when "hit-enter" is present, butrequired when "hit-enter" is not present.
history:{n}Determines how many entries are remembered in the
:messages history. The maximum value is 10000.Setting it to zero clears the message history.This item must always be present.
'mkspellmem''msm''mkspellmem''msm'string(default "460000,2000,500")globalParameters for
:mkspell. This tunes when to start compressing theword tree. Compression can be slow when there are many words, butit's needed to avoid running out of memory. The amount of memory usedper word depends very much on how similar the words are, that's whythis tuning is complicated.
There are three numbers, separated by commas:
{start},{inc},{added}For most languages the uncompressed word tree fits in memory.{start}gives the amount of memory in Kbyte that can be used before anycompression is done. It should be a bit smaller than the amount ofmemory that is available to Vim.
When going over the{start} limit the{inc} number specifies theamount of memory in Kbyte that can be allocated before anothercompression is done. A low number means compression is done afterless words are added, which is slow. A high number means more memorywill be allocated.
After doing compression,{added} times 1024 words can be added beforethe{inc} limit is ignored and compression is done when any extraamount of memory is needed. A low number means there is a smallerchance of hitting the{inc} limit, less memory is used but it'sslower.
The languages for which these numbers are important are Italian andHungarian. The default works for when you have about 512 Mbyte. Ifyou have 1 Gbyte you could use:
set mkspellmem=900000,3000,800
If you have less than 512 Mbyte
:mkspell may fail for somelanguages, no matter what you set
'mkspellmem' to.
This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
'modified''mod''nomodified''nomod''modified''mod'boolean(default off)local to buffer
local-noglobalWhen on, the buffer is considered to be modified. This option is setwhen:1. A change was made to the text since it was last written. Using the
undo command to go back to the original text will reset the option. But undoing changes that were made before writing the buffer will set the option again, since the text is different from when it was written.2.
'fileformat' or
'fileencoding' is different from its original value. The original value is set when the buffer is read or written. A ":set nomodified" command also resets the original values to the current values and the
'modified' option will be reset. Similarly for
'eol' and
'bomb'.This option is not set when a change is made to the buffer as theresult of a BufNewFile, BufRead/BufReadPost, BufWritePost,FileAppendPost or VimLeave autocommand event. See
gzip-example foran explanation.When
'buftype' is "nowrite" or "nofile" this option may be set, butwill be ignored.Note that the text may actually be the same, e.g.
'modified' is setwhen using "rA" on an "A".
'more''nomore''more'boolean(default on)globalWhen on, listings pause when the whole screen is filled. You will getthe
more-prompt. When this option is off there are no pauses, thelisting continues until finished.
'mouse''mouse'string(default "nvi")globalEnables mouse support. For example, to enable the mouse in Normal modeand Visual mode:
set mouse=nv
To temporarily disable mouse support, hold the shift key while usingthe mouse.
Mouse support can be enabled for different modes:nNormal modevVisual modeiInsert modecCommand-line modehall previous modes when editing a help fileaall previous modesrfor
hit-enter and
more-prompt prompt
Left-click anywhere in a text buffer to place the cursor there. Thisworks with operators too, e.g. type
d then left-click to delete textfrom the current cursor position to the position where you clicked.
Drag the
status-line or vertical separator of a window to resize it.
If enabled for "v" (Visual mode) then double-click selects word-wise,triple-click makes it line-wise, and quadruple-click makes itrectangular block-wise.
Note: When enabling the mouse in a terminal, copy/paste will use the"* register if possible. See also
'clipboard'.
'mousefocus''mousef''nomousefocus''nomousef''mousefocus''mousef'boolean(default off)globalThe window that the mouse pointer is on is automatically activated.When changing the window layout or window focus in another way, themouse pointer is moved to the window with keyboard focus. Off is thedefault because it makes using the pull down menus a little goofy, asa pointer transit may activate a window unintentionally.
'mousemodel''mousem''mousemodel''mousem'string(default "popup_setpos")globalSets the model to use for the mouse. The name mostly specifies whatthe right mouse button is used for: extendRight mouse button extends a selection. This workslike in an xterm. popupRight mouse button pops up a menu. The shifted leftmouse button extends a selection. This works likewith Microsoft Windows. popup_setpos Like "popup", but the cursor will be moved to theposition where the mouse was clicked, and thus theselected operation will act upon the clicked object.If clicking inside a selection, that selection willbe acted upon, i.e. no cursor move. This implies ofcourse, that right clicking outside a selection willend Visual mode.Overview of what button does what for each model:
mouse extendpopup(_setpos)
left click place cursorplace cursorleft drag start selectionstart selectionshift-left search wordextend selectionright click extend selectionpopup menu (place cursor)right drag extend selection-middle click pastepaste
In the "popup" model the right mouse button produces a pop-up menu.Nvim creates a default
popup-menu but you can redefine it.
Note that you can further refine the meaning of buttons with mappings.See
mouse-overview. But mappings are NOT used for modeless selection.
Example:
map <S-LeftMouse> <RightMouse>map <S-LeftDrag> <RightDrag>map <S-LeftRelease> <RightRelease>map <2-S-LeftMouse> <2-RightMouse>map <2-S-LeftDrag> <2-RightDrag>map <2-S-LeftRelease> <2-RightRelease>map <3-S-LeftMouse> <3-RightMouse>map <3-S-LeftDrag> <3-RightDrag>map <3-S-LeftRelease> <3-RightRelease>map <4-S-LeftMouse> <4-RightMouse>map <4-S-LeftDrag> <4-RightDrag>map <4-S-LeftRelease> <4-RightRelease>
Mouse commands requiring the CTRL modifier can be simulated by typingthe "g" key before using the mouse: "g<LeftMouse>" is "<C-LeftMouse>(jump to tag under mouse click) "g<RightMouse>" is "<C-RightMouse>("CTRL-T")
'mousescroll'E5080'mousescroll'string(default "ver:3,hor:6")globalThis option controls the number of lines / columns to scroll by whenscrolling with a mouse wheel (
scroll-mouse-wheel). The option isa comma-separated list. Each part consists of a direction and a countas follows:direction:count,direction:countDirection is one of either "hor" or "ver". "hor" controls horizontalscrolling and "ver" controls vertical scrolling. Count sets the amountto scroll by for the given direction, it should be a non negativeinteger. Each direction should be set at most once. If a directionis omitted, a default value is used (6 for horizontal scrolling and 3for vertical scrolling). You can disable mouse scrolling by usinga count of 0.
Example:
set mousescroll=ver:5,hor:2
Will make Nvim scroll 5 lines at a time when scrolling vertically, andscroll 2 columns at a time when scrolling horizontally.
'nrformats''nf''nrformats''nf'string(default "bin,hex")local to bufferThis defines what bases Vim will consider for numbers when using the
CTRL-A and
CTRL-X commands for adding to and subtracting from a numberrespectively; see
CTRL-A for more info on these commands.alphaIf included, single alphabetical characters will beincremented or decremented. This is useful for a list with aletter index a), b), etc.
octal-nrformatsoctalIf included, numbers that start with a zero will be consideredto be octal. Example: Using
CTRL-A on "007" results in "010".hexIf included, numbers starting with "0x" or "0X" will beconsidered to be hexadecimal. Example: Using
CTRL-X on"0x100" results in "0x0ff".binIf included, numbers starting with "0b" or "0B" will beconsidered to be binary. Example: Using
CTRL-X on"0b1000" subtracts one, resulting in "0b0111".unsigned If included, numbers are recognized as unsigned. Thus aleading dash or negative sign won't be considered as part ofthe number. Examples: Using
CTRL-X on "2020" in "9-2020" results in "9-2019" (without "unsigned" it would become "9-2021"). Using
CTRL-A on "2020" in "9-2020" results in "9-2021" (without "unsigned" it would become "9-2019"). Using
CTRL-X on "0" or
CTRL-A on "18446744073709551615" (2^64 - 1) has no effect, overflow is prevented.blankIf included, treat numbers as signed or unsigned based onpreceding whitespace. If a number with a leading dash has itsdash immediately preceded by a non-whitespace character (i.e.,not a tab or a " "), the negative sign won't be considered aspart of the number. For example: Using
CTRL-A on "14" in "Carbon-14" results in "Carbon-15" (without "blank" it would become "Carbon-13"). Using
CTRL-X on "8" in "Carbon -8" results in "Carbon -9" (because -8 is preceded by whitespace. If "unsigned" was set, it would result in "Carbon -7").If this format is included, overflow is prevented as if"unsigned" were set. If both this format and "unsigned" areincluded, "unsigned" will take precedence.
Numbers which simply begin with a digit in the range 1-9 are alwaysconsidered decimal. This also happens for numbers that are notrecognized as octal or hex.
'numberwidth''nuw''numberwidth''nuw'number(default 4)local to windowMinimal number of columns to use for the line number. Only relevantwhen the
'number' or
'relativenumber' option is set or printing lineswith a line number. Since one space is always between the number andthe text, there is one less character for the number itself.The value is the minimum width. A bigger width is used when needed tofit the highest line number in the buffer respectively the number ofrows in the window, depending on whether
'number' or
'relativenumber'is set. Thus with the Vim default of 4 there is room for a line numberup to 999. When the buffer has 1000 lines five columns will be used.The minimum value is 1, the maximum value is 20.
This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
'patchmode''pm'E205E206'patchmode''pm'string(default "")globalWhen non-empty the oldest version of a file is kept. This can be usedto keep the original version of a file if you are changing files in asource distribution. Only the first time that a file is written acopy of the original file will be kept. The name of the copy is thename of the original file with the string in the
'patchmode' optionappended. This option should start with a dot. Use a string like".orig" or ".org".
'backupdir' must not be empty for this to work(Detail: The backup file is renamed to the patchmode file after thenew file has been successfully written, that's why it must be possibleto write a backup file). If there was no file to be backed up, anempty file is created.When the
'backupskip' pattern matches, a patchmode file is not made.Using
'patchmode' for compressed files appends the extension at theend (e.g., "file.gz.orig"), thus the resulting name isn't alwaysrecognized as a compressed file.Only normal file name characters can be used,
/\*?[|<> are illegal.
'path''pa'E343E345E347E854'path''pa'string(default ".,,")global or local to buffer
global-localThis is a list of directories which will be searched when using the
gf, [f, ]f, ^Wf,
:find,
:sfind,
:tabfind and other commands,provided that the file being searched for has a relative path (notstarting with "/", "./" or "../"). The directories in the
'path'option may be relative or absolute.
Use commas to separate directory names:
set path=.,/usr/local/include,/usr/include
Spaces can also be used to separate directory names. To have a space in a directory name, precede it with an extra backslash, and escape the space:
set path=.,/dir/with\\\ space
To include a comma in a directory name precede it with an extra backslash:
set path=.,/dir/with\\,comma
To search relative to the directory of the current file, use:
set path=.
To search in the current directory use an empty string between two commas:
set path=,,
A directory name may end in a ':' or '/'.
Environment variables are expanded
:set_env.
When using
netrw URLs can be used. For example, adding "https://www.vim.org" will make ":find index.html" work.
Search upwards and downwards in a directory tree using "*", "**" and ";". See
file-searching for info and syntax.
Careful with '\' characters, type two to get one in the option:
set path=.,c:\\include
Or just use '/' instead:
set path=.,c:/include
Don't forget "." or files won't even be found in the same directory asthe file!The maximum length is limited. How much depends on the system, mostlyit is something like 256 or 1024 characters.You can check if all the include files are found, using the value of
'path', see
:checkpath.The use of
:set+= and
:set-= is preferred when adding or removingdirectories from the list. This avoids problems when a future versionuses another default. To remove the current directory use:
set path-=
To add the current directory use:
set path+=
To use an environment variable, you probably need to replace theseparator. Here is an example to append $INCL, in which directorynames are separated with a semicolon:
let &path = &path .. "," .. substitute($INCL, ';', ',', 'g')
Replace the ';' with a ':' or whatever separator is used. Note thatthis doesn't work when $INCL contains a comma or white space.
'preserveindent''pi''nopreserveindent''nopi''preserveindent''pi'boolean(default off)local to bufferWhen changing the indent of the current line, preserve as much of theindent structure as possible. Normally the indent is replaced by aseries of tabs followed by spaces as required (unless
'expandtab' isenabled, in which case only spaces are used). Enabling this optionmeans the indent will preserve as many existing characters as possiblefor indenting, and only add additional tabs or spaces as required.
'expandtab' does not apply to the preserved white space, a Tab remainsa Tab.
NOTE: When using ">>" multiple times the resulting indent is a mix oftabs and spaces. You might not like this.Also see
'copyindent'.Use
:retab to clean up white space.
'pumblend''pb''pumblend''pb'number(default 0)globalEnables pseudo-transparency for the
popup-menu. Valid values are inthe range of 0 for fully opaque popupmenu (disabled) to 100 for fullytransparent background. Values between 0-30 are typically most useful.
It is possible to override the level for individual highlights withinthe popupmenu using
highlight-blend. For instance, to enabletransparency but force the current selected element to be fully opaque:
set pumblend=15hi PmenuSel blend=0
'pyxversion''pyx''pyxversion''pyx'number(default 3)globalSpecifies the python version used for pyx* functions and commands
python_x. As only Python 3 is supported, this always has the value
3. Setting any other value is an error.
This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
'quickfixtextfunc''qftf''quickfixtextfunc''qftf'string(default "")globalThis option specifies a function to be used to get the text to displayin the quickfix and location list windows. This can be used tocustomize the information displayed in the quickfix or location windowfor each entry in the corresponding quickfix or location list. See
quickfix-window-function for an explanation of how to write thefunction and an example. The value can be the name of a function, a
lambda or a
Funcref. See
option-value-function for moreinformation.
This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
'quoteescape''qe''quoteescape''qe'string(default "\")local to bufferThe characters that are used to escape quotes in a string. Used forobjects like a', a" and a`
a'.When one of the characters in this option is found inside a string,the following character will be skipped. The default value makes thetext "foo\"bar\\" considered to be one string.
'readonly''ro''noreadonly''noro''readonly''ro'boolean(default off)local to buffer
local-noglobalIf on, writes fail unless you use a '!'. Protects you fromaccidentally overwriting a file. Default on when Vim is startedin read-only mode ("vim -R") or when the executable is called "view".When using ":w!" the
'readonly' option is reset for the currentbuffer, unless the 'Z' flag is in
'cpoptions'.When using the ":view" command the
'readonly' option is set for thenewly edited buffer.See
'modifiable' for disallowing changes to the buffer.
'redrawdebug''rdb''redrawdebug''rdb'string(default "")globalFlags to change the way redrawing works, for debugging purposes.Most useful with
'writedelay' set to some reasonable value.Supports the following flags: compositorIndicate each redraw event handled by the compositorby briefly flashing the redrawn regions in colorsindicating the redraw type. These are the highlightgroups used (and their default colors):RedrawDebugNormal gui=reverse normal redraw passed throughRedrawDebugClear guibg=Yellow clear event passed throughRedrawDebugComposed guibg=Green redraw event modified by the compositor (due to overlapping grids, etc)RedrawDebugRecompose guibg=Red redraw generated by the compositor itself, due to a grid being moved or deleted. lineintroduce a delay after each line drawn on the screen.When using the TUI or another single-grid UI, "compositor"gives more information and should be preferred (everyline is processed as a separate event by the compositor) flushintroduce a delay after each "flush" event. nothrottleTurn off throttling of the message grid. This is anoptimization that joins many small scrolls to onelarger scroll when drawing the message area (with
'display' msgsep flag active). invalidEnable stricter checking (abort) of inconsistenciesof the internal screen state. This is mostlyuseful when running nvim inside a debugger (andthe test suite). nodeltaSend all internally redrawn cells to the UI, even ifthey are unchanged from the already displayed state.
'redrawtime''rdt''redrawtime''rdt'number(default 2000)globalTime in milliseconds for redrawing the display. Applies to
'hlsearch',
'inccommand',
:match highlighting, syntax highlighting,and async
LanguageTree:parse().When redrawing takes more than this many milliseconds no furthermatches will be highlighted.For syntax highlighting the time applies per window. When over thelimit syntax highlighting is disabled until
CTRL-L is used.This is used to avoid that Vim hangs when using a very complicatedpattern.
'regexpengine''re''regexpengine''re'number(default 0)globalThis selects the default regexp engine.
two-enginesThe possible values are:0automatic selection1old engine2NFA engineNote that when using the NFA engine and the pattern contains somethingthat is not supported the pattern will not match. This is only usefulfor debugging the regexp engine.Using automatic selection enables Vim to switch the engine, if thedefault engine becomes too costly. E.g., when the NFA engine uses toomany states. This should prevent Vim from hanging on a combination ofa complex pattern with long text.
'relativenumber''rnu''norelativenumber''nornu''relativenumber''rnu'boolean(default off)local to windowShow the line number relative to the line with the cursor in front ofeach line. Relative line numbers help you use the
count you canprecede some vertical motion commands (e.g. j k + -) with, withouthaving to calculate it yourself. Especially useful in combination withother commands (e.g. y d c < > gq gw =).When the 'n' option is excluded from
'cpoptions' a wrappedline will not use the column of line numbers.The
'numberwidth' option can be used to set the room used for the linenumber.When a long, wrapped line doesn't start with the first character, '-'characters are put before the number.See
hl-LineNr and
hl-CursorLineNr for the highlighting used forthe number.
'report''report'number(default 2)globalThreshold for reporting number of lines changed. When the number ofchanged lines is more than
'report' a message will be given for most":" commands. If you want it always, set
'report' to 0.For the ":substitute" command the number of substitutions is usedinstead of the number of lines.
'rightleft''rl''norightleft''norl''rightleft''rl'boolean(default off)local to windowWhen on, display orientation becomes right-to-left, i.e., charactersthat are stored in the file appear from the right to the left.Using this option, it is possible to edit files for languages thatare written from the right to the left such as Hebrew and Arabic.This option is per window, so it is possible to edit mixed filessimultaneously, or to view the same file in both ways (this isuseful whenever you have a mixed text file with both right-to-leftand left-to-right strings so that both sets are displayed properlyin different windows). Also see
rileft.txt.
search"/" and "?" commands
This is useful for languages such as Hebrew, Arabic and Farsi.The
'rightleft' option must be set for
'rightleftcmd' to take effect.
'ruler''ru''noruler''noru''ruler''ru'boolean(default on)globalShow the line and column number of the cursor position, separated by acomma. When there is room, the relative position of the displayedtext in the file is shown on the far right:Topfirst line is visibleBotlast line is visibleAllfirst and last line are visible45%relative position in the fileIf
'rulerformat' is set, it will determine the contents of the ruler.Each window has its own ruler. If a window has a status line, theruler is shown there. If a window doesn't have a status line and
'cmdheight' is zero, the ruler is not shown. Otherwise it is shown inthe last line of the screen. If the statusline is given by
'statusline' (i.e. not empty), this option takes precedence over
'ruler' and
'rulerformat'.If the number of characters displayed is different from the number ofbytes in the text (e.g., for a TAB or a multibyte character), boththe text column (byte number) and the screen column are shown,separated with a dash.For an empty line "0-1" is shown.For an empty buffer the line number will also be zero: "0,0-1".If you don't want to see the ruler all the time but want to know whereyou are, use "g
CTRL-G"
g_CTRL-G.
The default ruler width is 17 characters. To make the ruler 15characters wide, put "%15(" at the start and "%)" at the end.Example:
set rulerformat=%15(%c%V\ %p%%%)
'runtimepath''rtp'vimfiles'runtimepath''rtp'string(default "$XDG_CONFIG_HOME/nvim, $XDG_CONFIG_DIRS[1]/nvim, $XDG_CONFIG_DIRS[2]/nvim, … $XDG_DATA_HOME/nvim[-data]/site, $XDG_DATA_DIRS[1]/nvim/site, $XDG_DATA_DIRS[2]/nvim/site, … $VIMRUNTIME, … $XDG_DATA_DIRS[2]/nvim/site/after, $XDG_DATA_DIRS[1]/nvim/site/after, $XDG_DATA_HOME/nvim[-data]/site/after, … $XDG_CONFIG_DIRS[2]/nvim/after, $XDG_CONFIG_DIRS[1]/nvim/after, $XDG_CONFIG_HOME/nvim/after")globalList of directories to be searched for these runtime files: filetype.luafiletypes
new-filetype autoload/automatically loaded scripts
autoload-functions colors/color scheme files
:colorscheme compiler/compiler files
:compiler doc/documentation
write-local-help ftplugin/filetype plugins
write-filetype-plugin indent/indent scripts
indent-expression keymap/key mapping files
mbyte-keymap lang/menu translations
:menutrans lsp/LSP client configurations
lsp-config lua/
Lua plugins menu.vimGUI menus
menu.vim pack/packages
:packadd parser/
treesitter syntax parsers plugin/plugin scripts
write-plugin queries/
treesitter queries rplugin/
remote-plugin scripts spell/spell checking files
spell syntax/syntax files
mysyntaxfile tutor/tutorial files
:Tutor And any other file searched for with the
:runtime command.
Defaults are setup to search these locations:1. Your home directory, for personal preferences. Given by
stdpath("config").
$XDG_CONFIG_HOME2. Directories which must contain configuration files according to
xdg ($XDG_CONFIG_DIRS, defaults to /etc/xdg). This also contains preferences from system administrator.3. Data home directory, for plugins installed by user. Given by
stdpath("data")/site.
$XDG_DATA_HOME4. nvim/site subdirectories for each directory in $XDG_DATA_DIRS. This is for plugins which were installed by system administrator, but are not part of the Nvim distribution. XDG_DATA_DIRS defaults to /usr/local/share/:/usr/share/, so system administrators are expected to install site plugins to /usr/share/nvim/site.5. Session state directory, for state data such as swap, backupdir, viewdir, undodir, etc. Given by
stdpath("state").
$XDG_STATE_HOME6. $VIMRUNTIME, for files distributed with Nvim.
after-directory7, 8, 9, 10. In after/ subdirectories of 1, 2, 3 and 4, with reverse ordering. This is for preferences to overrule or add to the distributed defaults or system-wide settings (rarely needed).
packages-runtimepath"start" packages will also be searched (
runtime-search-path) forruntime files after these, though such packages are not explicitlyreported in &runtimepath. But "opt" packages are explicitly added to&runtimepath by
:packadd.
Note that, unlike
'path', no wildcards like "**" are allowed. Normalwildcards are allowed, but can significantly slow down searching forruntime files. For speed, use as few items as possible and avoidwildcards.See
:runtime.Example:
set runtimepath=~/vimruntime,/mygroup/vim,$VIMRUNTIME
This will use the directory "~/vimruntime" first (containing yourpersonal Nvim runtime files), then "/mygroup/vim", and finally"$VIMRUNTIME" (the default runtime files).You can put a directory before $VIMRUNTIME to find files which replacedistributed runtime files. You can put a directory after $VIMRUNTIMEto find files which add to distributed runtime files.
With
--clean the home directory entries are not included.
'scroll''scr''scroll''scr'number(default half the window height)local to window
local-noglobalNumber of lines to scroll with
CTRL-U and
CTRL-D commands. Will beset to half the number of lines in the window when the window sizechanges. This may happen when enabling the
status-line or
'tabline' option after setting the
'scroll' option.If you give a count to the
CTRL-U or
CTRL-D command it willbe used as the new value for
'scroll'. Reset to half the windowheight with ":set scroll=0".
'scrollback''scbk''scrollback''scbk'number(default 10000)local to bufferMaximum number of lines kept beyond the visible screen. Lines at thetop are deleted if new lines exceed this limit.Minimum is 1, maximum is 100000.Only in
terminal buffers.
Note: Lines that are not visible and kept in scrollback are notreflown when the terminal buffer is resized horizontally.
'scrollbind''scb''noscrollbind''noscb''scrollbind''scb'boolean(default off)local to windowSee also
scroll-binding. When this option is set, scrolling thecurrent window also scrolls other scrollbind windows (windows thatalso have this option set). This option is useful for viewing thedifferences between two versions of a file, see
'diff'.See
'scrollopt' for options that determine how this option should beinterpreted.This option is mostly reset when splitting a window to edit anotherfile. This means that ":split | edit file" results in two windowswith scroll-binding, but ":split file" does not.
'scrolljump''sj''scrolljump''sj'number(default 1)globalMinimal number of lines to scroll when the cursor gets off thescreen (e.g., with "j"). Not used for scroll commands (e.g.,
CTRL-E,
CTRL-D). Useful if your terminal scrolls very slowly.When set to a negative number from -1 to -100 this is used as thepercentage of the window height. Thus -50 scrolls half the windowheight.
'scrolloff''so''scrolloff''so'number(default 0)global or local to window
global-localMinimal number of screen lines to keep above and below the cursor.This will make some context visible around where you are working. Ifyou set it to a very large value (999) the cursor line will always bein the middle of the window (except at the start or end of the file orwhen long lines wrap).After using the local value, go back the global value with one ofthese two:
setlocal scrolloff<setlocal scrolloff=-1
'scrollopt''sbo''scrollopt''sbo'string(default "ver,jump")globalThis is a comma-separated list of words that specifies how
'scrollbind' windows should behave.
'sbo' stands for ScrollBindOptions.The following words are available: verBind vertical scrolling for
'scrollbind' windows horBind horizontal scrolling for
'scrollbind' windows jumpApplies to the offset between two windows for verticalscrolling. This offset is the difference in the firstdisplayed line of the bound windows. When movingaround in a window, another
'scrollbind' window mayreach a position before the start or after the end ofthe buffer. The offset is not changed though, whenmoving back the
'scrollbind' window will try to scrollto the desired position when possible.When now making that window the current one, twothings can be done with the relative offset:1. When "jump" is not included, the relative offset is adjusted for the scroll position in the new current window. When going back to the other window, the new relative offset will be used.2. When "jump" is included, the other windows are scrolled to keep the same relative offset. When going back to the other window, it still uses the same relative offset.Also see
scroll-binding.When
'diff' mode is active there always is vertical scroll binding,even when "ver" isn't there.
'sections''sect''sections''sect'string(default "SHNHH HUnhsh")globalSpecifies the nroff macros that separate sections. These are pairs oftwo letters (See
object-motions). The default makes a section startat the nroff macros ".SH", ".NH", ".H", ".HU", ".nh" and ".sh".
'selection''sel''selection''sel'string(default "inclusive")globalThis option defines the behavior of the selection. It is only usedin Visual and Select mode.Possible values:
valuepast line inclusive
old noyes inclusive yesyes exclusive yesno"past line" means that the cursor is allowed to be positioned onecharacter past the line."inclusive" means that the last character of the selection is includedin an operation. For example, when "x" is used to delete theselection.When "old" is used and
'virtualedit' allows the cursor to move pastthe end of line the line break still isn't included.When "exclusive" is used, cursor position in visual mode will beadjusted for inclusive motions
inclusive-motion-selection-exclusive.
Note: When "exclusive" is used and selecting from the end backwards, you cannot include the last character of a line, when starting in Normal mode and
'virtualedit' empty.
when "exclusive" is used with a single character visual selection, Vim will behave as if the
'selection' is inclusive (in other words, you cannot visually select an empty region).
'selectmode''slm''selectmode''slm'string(default "")globalThis is a comma-separated list of words, which specifies when to startSelect mode instead of Visual mode, when a selection is started.Possible values: mousewhen using the mouse keywhen using shifted special keys cmdwhen using "v", "V" or
CTRL-VSee
Select-mode.
'sessionoptions''ssop''sessionoptions''ssop'string(default "blank,buffers,curdir,folds,help,tabpages,winsize,terminal")globalChanges the effect of the
:mksession command. It is a comma-separated list of words. Each word enables saving and restoringsomething:
wordsave and restore
blankempty windows buffershidden and unloaded buffers, not just those in windows curdirthe current directory foldsmanually created folds, opened/closed folds and localfold options globalsglobal variables that start with an uppercase letterand contain at least one lowercase letter. OnlyString and Number types are stored. helpthe help window localoptionsoptions and mappings local to a window or buffer (notglobal values for local options) optionsall options and mappings (also global values for localoptions) skiprtpexclude
'runtimepath' and
'packpath' from the options resizesize of the Vim window:
'lines' and
'columns' sesdirthe directory in which the session file is locatedwill become the current directory (useful withprojects accessed over a network from differentsystems) tabpagesall tab pages; without this only the current tab pageis restored, so that you can make a session for eachtab page separately terminalinclude terminal windows where the command can berestored winposposition of the whole Vim window winsizewindow sizes slash
deprecated Always enabled. Uses "/" in filenames. unix
deprecated Always enabled. Uses "\n" line endings.
Don't include both "curdir" and "sesdir". When neither is includedfilenames are stored as absolute paths.If you leave out "options" many things won't work well after restoringthe session.
'shada''sd'E526E527E528'shada''sd'string(default for Win32: !,'100,<50,s10,h,rA:,rB: others: !,'100,<50,s10,h)globalWhen non-empty, the shada file is read upon startup and writtenwhen exiting Vim (see
shada-file). The string should be a comma-separated list of parameters, each consisting of a single characteridentifying the particular parameter, followed by a number or stringwhich specifies the value of that parameter. If a particularcharacter is left out, then the default value is used for thatparameter. The following is a list of the identifying characters andthe effect of their value.
CHARVALUE
shada-!!When included, save and restore global variables that startwith an uppercase letter, and don't contain a lowercaseletter. Thus "KEEPTHIS and "K_L_M" are stored, but "KeepThis"and "_K_L_M" are not. Nested List and Dict items may not beread back correctly, you end up with an empty item.
shada-quote"Maximum number of lines saved for each register. Old name ofthe '<' item, with the disadvantage that you need to put abackslash before the ", otherwise it will be recognized as thestart of a comment!
shada-%%When included, save and restore the buffer list. If Vim isstarted with a file name argument, the buffer list is notrestored. If Vim is started without a file name argument, thebuffer list is restored from the shada file. Quickfix(
'buftype'), unlisted (
'buflisted'), unnamed and buffers onremovable media (
shada-r) are not saved.When followed by a number, the number specifies the maximumnumber of buffers that are stored. Without a number allbuffers are stored.
shada-''Maximum number of previously edited files for which the marksare remembered. This parameter must always be included when
'shada' is non-empty.If non-zero, then the
jumplist and the
changelist are alsostored in the shada file.
shada-//Maximum number of items in the search pattern history to besaved. If non-zero, then the previous search and substitutepatterns are also saved. When not included, the value of
'history' is used.
shada-::Maximum number of items in the command-line history to besaved. When not included, the value of
'history' is used.
shada-<<Maximum number of lines saved for each register. If zero thenregisters are not saved. When not included, all lines aresaved. '"' is the old name for this item.Also see the 's' item below: limit specified in KiB.
shada-@@Maximum number of items in the input-line history to besaved. When not included, the value of
'history' is used.
shada-ccDummy option, kept for compatibility reasons. Has no actualeffect: ShaDa always uses UTF-8 and
'encoding' value is fixedto UTF-8 as well.
shada-ffWhether file marks need to be stored. If zero, file marks ('0to '9, 'A to 'Z) are not stored. When not present or whennon-zero, they are all stored. '0 is used for the currentcursor position (when exiting or when doing
:wshada).
shada-hhDisable the effect of
'hlsearch' when loading the shadafile. When not included, it depends on whether ":nohlsearch"has been used since the last search command.
shada-nnName of the shada file. The name must immediately followthe 'n'. Must be at the end of the option! If the
'shadafile' option is set, that file name overrides the onegiven here with
'shada'. Environment variables areexpanded when opening the file, not when setting the option.
shada-rrRemovable media. The argument is a string (up to the next','). This parameter can be given several times. Eachspecifies the start of a path for which no marks will bestored. This is to avoid removable media. For Windows youcould use "ra:,rb:". You can also use it for temp files,e.g., for Unix: "r/tmp". Case is ignored.
shada-ssMaximum size of an item contents in KiB. If zero then nothingis saved. Unlike Vim this applies to all items, except forthe buffer list and header. Full item size is off by threeunsigned integers: with
s10 maximum item size may be 1 byte(type: 7-bit integer) + 9 bytes (timestamp: up to 64-bitinteger) + 3 bytes (item size: up to 16-bit integer because2^8 < 10240 < 2^16) + 10240 bytes (requested maximum itemcontents size) = 10253 bytes.
Example:
set shada='50,<1000,s100,:0,n~/nvim/shada
'50Marks will be remembered for the last 50 files youedited.<1000Contents of registers (up to 1000 lines each) will beremembered.s100Items with contents occupying more then 100 KiB areskipped.:0Command-line history will not be saved.n~/nvim/shadaThe name of the file to use is "~/nvim/shada".no /Since '/' is not specified, the default will be used,that is, save all of the search history, and also theprevious search and substitute patterns.no %The buffer list will not be saved nor read back.no h
'hlsearch' highlighting will be restored.
When setting
'shada' from an empty value you can use
:rshada toload the contents of the file, this is not done automatically.
This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
'shadafile''sdf''shadafile''sdf'string(default "")globalWhen non-empty, overrides the file name used for
shada (viminfo).When equal to "NONE" no shada file will be read or written.This option can be set with the
-i command line flag. The
--cleancommand line flag sets it to "NONE".This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
If the name of the shell contains a space, you need to enclose it inquotes. Example with quotes:
set shell=\"c:\program\ files\unix\sh.exe\"\ -f
Note the backslash before each quote (to avoid starting a comment) andeach space (to avoid ending the option value), so better use
:let-&like this:
let &shell='"C:\Program Files\unix\sh.exe" -f'
Also note that the "-f" is not inside the quotes, because it is notpart of the command name.
shell-unquotingRules regarding quotes:1. Option is split on space and tab characters that are not inside quotes: "abc def" runs shell named "abc" with additional argument "def", '"abc def"' runs shell named "abc def" with no additional arguments (here and below: additional means “additional to
'shellcmdflag'”).2. Quotes in option may be present in any position and any number: '"abc"', '"a"bc', 'a"b"c', 'ab"c"' and '"a"b"c"' are all equivalent to just "abc".3. Inside quotes backslash preceding backslash means one backslash. Backslash preceding quote means one quote. Backslash preceding anything else means backslash and next character literally: '"a\\b"' is the same as "a\b", '"a\\"b"' runs shell named literally 'a"b', '"a\b"' is the same as "a\b" again.4. Outside of quotes backslash always means itself, it cannot be used to escape quote: 'a\"b"' is the same as "a\b".Note that such processing is done after
:set did its own round ofunescaping, so to keep yourself sane use
:let-& like shown above.
shell-powershellTo use PowerShell:
let &shell = executable('pwsh') ? 'pwsh' : 'powershell'let &shellcmdflag = '-NoLogo -NonInteractive -ExecutionPolicy RemoteSigned -Command [Console]::InputEncoding=[Console]::OutputEncoding=[System.Text.UTF8Encoding]::new();$PSDefaultParameterValues[''Out-File:Encoding'']=''utf8'';$PSStyle.OutputRendering=''plaintext'';Remove-Alias -Force -ErrorAction SilentlyContinue tee;'let &shellredir = '2>&1 | %%{ "$_" } | Out-File %s; exit $LastExitCode'let &shellpipe = '2>&1 | %%{ "$_" } | tee %s; exit $LastExitCode'set shellquote= shellxquote=
This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
'shellcmdflag''shcf''shellcmdflag''shcf'string(default "-c"; Windows: "/s /c")globalFlag passed to the shell to execute "!" and ":!" commands; e.g.,
bash.exe -c ls or
cmd.exe /s /c "dir". For MS-Windows, thedefault is set according to the value of
'shell', to reduce the needto set this option by the user.On Unix it can have more than one flag. Each white space separatedpart is passed as an argument to the shell command.See
option-backslash about including spaces and backslashes.See
shell-unquoting which talks about separating this option intomultiple arguments.This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
'shellpipe''sp''shellpipe''sp'string(default ">", "| tee", "|& tee" or "2>&1| tee")globalString to be used to put the output of the ":make" command in theerror file. See also
:make_makeprg. See
option-backslash aboutincluding spaces and backslashes.The name of the temporary file can be represented by "%s" if necessary(the file name is appended automatically if no %s appears in the valueof this option).For MS-Windows the default is "2>&1| tee". The stdout and stderr aresaved in a file and echoed to the screen.For Unix the default is "| tee". The stdout of the compiler is savedin a file and echoed to the screen. If the
'shell' option is "csh" or"tcsh" after initializations, the default becomes "|& tee". If the
'shell' option is "sh", "ksh", "mksh", "pdksh", "zsh", "zsh-beta","bash", "fish", "ash" or "dash" the default becomes "2>&1| tee". Thismeans that stderr is also included. Before using the
'shell' option apath is removed, thus "/bin/sh" uses "sh".The initialization of this option is done after reading the vimrcand the other initializations, so that when the
'shell' option is setthere, the
'shellpipe' option changes automatically, unless it wasexplicitly set before.When
'shellpipe' is set to an empty string, no redirection of the":make" output will be done. This is useful if you use a
'makeprg'that writes to
'makeef' by itself. If you want no piping, but dowant to include the
'makeef', set
'shellpipe' to a single space.Don't forget to precede the space with a backslash: ":set sp=\ ".In the future pipes may be used for filtering and this option willbecome obsolete (at least for Unix).This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
'shellquote''shq''shellquote''shq'string(default ""; Windows, when
'shell' contains "sh" somewhere: "\"")globalQuoting character(s), put around the command passed to the shell, forthe "!" and ":!" commands. The redirection is kept outside of thequoting. See
'shellxquote' to include the redirection. It'sprobably not useful to set both options.This is an empty string by default. Only known to be useful forthird-party shells on Windows systems, such as the MKS Korn Shellor bash, where it should be "\"". The default is adjusted accordingthe value of
'shell', to reduce the need to set this option by theuser.This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
'shellredir''srr''shellredir''srr'string(default ">", ">&" or ">%s 2>&1")globalString to be used to put the output of a filter command in a temporaryfile. See also
:!. See
option-backslash about including spacesand backslashes.The name of the temporary file can be represented by "%s" if necessary(the file name is appended automatically if no %s appears in the valueof this option).The default is ">". For Unix, if the
'shell' option is "csh" or"tcsh" during initializations, the default becomes ">&". If the
'shell' option is "sh", "ksh", "mksh", "pdksh", "zsh", "zsh-beta","bash" or "fish", the default becomes ">%s 2>&1". This means thatstderr is also included. For Win32, the Unix checks are done andadditionally "cmd" is checked for, which makes the default ">%s 2>&1".Also, the same names with ".exe" appended are checked for.The initialization of this option is done after reading the vimrcand the other initializations, so that when the
'shell' option is setthere, the
'shellredir' option changes automatically unless it wasexplicitly set before.In the future pipes may be used for filtering and this option willbecome obsolete (at least for Unix).This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
'shellslash''ssl''noshellslash''nossl''shellslash''ssl'boolean(default on, Windows: off)globalonly modifiable in MS-WindowsWhen set, a forward slash is used when expanding file names. This isuseful when a Unix-like shell is used instead of cmd.exe. Backwardslashes can still be typed, but they are changed to forward slashes byVim.Note that setting or resetting this option has no effect for someexisting file names, thus this option needs to be set before openingany file for best results. This might change in the future.
'shellslash' only works when a backslash can be used as a pathseparator. To test if this is so use:
if exists('+shellslash')
'shellxquote''sxq''shellxquote''sxq'string(default "", Windows: "\"")globalQuoting character(s), put around the command passed to the shell, forthe "!" and ":!" commands. Includes the redirection. See
'shellquote' to exclude the redirection. It's probably not usefulto set both options.When the value is '(' then ')' is appended. When the value is '"('then ')"' is appended.When the value is '(' then also see
'shellxescape'.This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
'shortmess''shm'E1336'shortmess''shm'string(default "ltToOCF")globalThis option helps to avoid all the
hit-enter prompts caused by filemessages, for example with
CTRL-G, and to avoid some other messages.It is a list of flags:
flagmeaning when present
luse "999L, 888B" instead of "999 lines, 888 bytes"
shm-l muse "[+]" instead of "[Modified]"
shm-m ruse "[RO]" instead of "[readonly]"
shm-r wuse "[w]" instead of "written" for file write message
shm-w and "[a]" instead of "appended" for ':w >> file' command aall of the above abbreviations
shm-a ooverwrite message for writing a file with subsequent
shm-o message for reading a file (useful for ":wn" or when
'autowrite' on) Omessage for reading a file overwrites any previous
shm-O message; also for quickfix message (e.g., ":cn") sdon't give "search hit BOTTOM, continuing at TOP" or
shm-s "search hit TOP, continuing at BOTTOM" messages; when usingthe search count do not show "W" before the count message(see
shm-S below) ttruncate file message at the start if it is too long
shm-t to fit on the command-line, "<" will appear in the left mostcolumn; ignored in Ex mode Ttruncate other messages in the middle if they are too
shm-T long to fit on the command line; "..." will appear in themiddle; ignored in Ex mode Wdon't give "written" or "[w]" when writing a file
shm-W Adon't give the "ATTENTION" message when an existing
shm-A swap file is found Idon't give the intro message when starting Vim,
shm-Isee
:intro cdon't give
ins-completion-menu messages; for
shm-cexample, "-- XXX completion (YYY)", "match 1 of 2", "The onlymatch", "Pattern not found", "Back at original", etc. Cdon't give messages while scanning for ins-completion
shm-C items, for instance "scanning tags" qdo not show "recording @a" when recording a macro
shm-q Fdon't give the file info when editing a file, like
shm-F:silent was used for the command; note that this alsoaffects messages from
'autoread' reloading Sdo not show search count message when searching, e.g.
shm-S "[1/5]". When the "S" flag is not present (e.g. search countis shown), the "search hit BOTTOM, continuing at TOP" and"search hit TOP, continuing at BOTTOM" messages are onlyindicated by a "W" (Mnemonic: Wrapped) letter before thesearch count statistics. The maximum limit can be set withthe
'maxsearchcount' option.
This gives you the opportunity to avoid that a change between buffersrequires you to hit
<Enter>, but still gives as useful a message aspossible for the space available. To get the whole message that youwould have got with
'shm' empty, use ":file!"Useful values: shm=No abbreviation of message. shm=aAbbreviation, but no loss of information. shm=atAbbreviation, and truncate message when necessary.
Only printable single-cell characters are allowed, excluding
<Tab> andcomma (in a future version the comma might be used to separate thepart that is shown at the end and at the start of a line).The
hl-NonText highlight group determines the highlighting.Note that tabs after the showbreak will be displayed differently.If you want the
'showbreak' to appear in between line numbers, add the"n" flag to
'cpoptions'.A window-local value overrules a global value. If the global value isset and you want no value in the current window use NONE:
setlocal showbreak=NONE
'showcmd''sc''noshowcmd''nosc''showcmd''sc'boolean(default on)globalShow (partial) command in the last line of the screen. Set thisoption off if your terminal is slow.In Visual mode the size of the selected area is shown:
When selecting characters within a line, the number of characters. If the number of bytes is different it is also displayed: "2-6" means two characters and six bytes.
When selecting more than one line, the number of lines.
When selecting a block, the size in screen characters:
{lines}x{columns}.This information can be displayed in an alternative location using the
'showcmdloc' option, useful when
'cmdheight' is 0.
'showcmdloc''sloc''showcmdloc''sloc'string(default "last")globalThis option can be used to display the (partially) entered command inanother location. Possible values are: lastLast line of the screen (default). statuslineStatus line of the current window. tablineFirst line of the screen if
'showtabline' is enabled.Setting this option to "statusline" or "tabline" means that these willbe redrawn whenever the command changes, which can be on every keypressed.The %S
'statusline' item can be used in
'statusline' or
'tabline' toplace the text. Without a custom
'statusline' or
'tabline' it will bedisplayed in a convenient location.
'showfulltag''sft''noshowfulltag''nosft''showfulltag''sft'boolean(default off)globalWhen completing a word in insert mode (see
ins-completion) from thetags file, show both the tag name and a tidied-up form of the searchpattern (if there is one) as possible matches. Thus, if you havematched a C function, you can see a template for what arguments arerequired (coding style permitting).Note that this doesn't work well together with having "longest" in
'completeopt', because the completion from the search pattern may notmatch the typed text.
'showmatch''sm''noshowmatch''nosm''showmatch''sm'boolean(default off)globalWhen a bracket is inserted, briefly jump to the matching one. Thejump is only done if the match can be seen on the screen. The time toshow the match can be set with
'matchtime'.A Beep is given if there is no match (no matter if the match can beseen or not).When the 'm' flag is not included in
'cpoptions', typing a characterwill immediately move the cursor back to where it belongs.See the "sm" field in
'guicursor' for setting the cursor shape andblinking when showing the match.The
'matchpairs' option can be used to specify the characters to showmatches for.
'rightleft' and
'revins' are used to look for oppositematches.Also see the matchparen plugin for highlighting the match when movingaround
pi_paren.txt.
Note: Use of the short form is rated PG.
'showtabline''stal''showtabline''stal'number(default 1)globalThe value of this option specifies when the line with tab page labelswill be displayed:0: never1: only if there are at least two tab pages2: alwaysThis is both for the GUI and non-GUI implementation of the tab pagesline.See
tab-page for more information about tab pages.
'sidescroll''ss''sidescroll''ss'number(default 1)globalThe minimal number of columns to scroll horizontally. Used only whenthe
'wrap' option is off and the cursor is moved off of the screen.When it is zero the cursor will be put in the middle of the screen.When using a slow terminal set it to a large number or 0. Not usedfor "zh" and "zl" commands.
'sidescrolloff''siso''sidescrolloff''siso'number(default 0)global or local to window
global-localThe minimal number of screen columns to keep to the left and to theright of the cursor if
'nowrap' is set. Setting this option to avalue greater than 0 while having
'sidescroll' also at a non-zerovalue makes some context visible in the line you are scrolling inhorizontally (except at beginning of the line). Setting this optionto a large value (like 999) has the effect of keeping the cursorhorizontally centered in the window, as long as one does not come tooclose to the beginning of the line.After using the local value, go back the global value with one ofthese two:
setlocal sidescrolloff<setlocal sidescrolloff=-1
Example: Try this together with
'sidescroll' and
'listchars' as in the following example to never allow the cursor to move onto the "extends" character:
set nowrap sidescroll=1 listchars=extends:>,precedes:<set sidescrolloff=1
'signcolumn''scl''signcolumn''scl'string(default "auto")local to windowWhen and how to draw the signcolumn. Valid values are: "auto"only when there is a sign to display "auto:[1-9]" resize to accommodate multiple signs up to the given number (maximum 9), e.g. "auto:4" "auto:[1-8]-[2-9]" resize to accommodate multiple signs up to thegiven maximum number (maximum 9) while keepingat least the given minimum (maximum 8) fixedspace. The minimum number should always be lessthan the maximum number, e.g. "auto:2-5" "no"never "yes"always "yes:[1-9]" always, with fixed space for signs up to the given number (maximum 9), e.g. "yes:3" "number"display signs in the
'number' column. If the numbercolumn is not present, then behaves like "auto".
'smartcase''scs''nosmartcase''noscs''smartcase''scs'boolean(default off)globalOverride the
'ignorecase' option if the search pattern contains uppercase characters. Only used when the search pattern is typed and
'ignorecase' option is on. Used for the commands "/", "?", "n", "N",":g" and ":s" and when filtering matches for the completion menu
compl-states.Not used for "*", "#", "gd", tag search, etc. After "*" and "#" youcan make
'smartcase' used by doing a "/" command, recalling the searchpattern from history and hitting
<Enter>.
'smartindent''si''nosmartindent''nosi''smartindent''si'boolean(default off)local to bufferDo smart autoindenting when starting a new line. Works for C-likeprograms, but can also be used for other languages.
'cindent' doessomething like this, works better in most cases, but is more strict,see
C-indenting. When
'cindent' is on or
'indentexpr' is set,setting
'si' has no effect.
'indentexpr' is a more advancedalternative.Normally
'autoindent' should also be on when using
'smartindent'.An indent is automatically inserted:
After a line ending in "{".
After a line starting with a keyword from
'cinwords'.
Before a line starting with "}" (only with the "O" command).When typing '}' as the first character in a new line, that line isgiven the same indent as the matching "{".When typing '#' as the first character in a new line, the indent forthat line is removed, the '#' is put in the first column. The indentis restored for the next line. If you don't want this, use thismapping: ":inoremap # X^H#", where ^H is entered withCTRL-VCTRL-H.When using the ">>" command, lines starting with '#' are not shiftedright.
'smoothscroll''sms''nosmoothscroll''nosms''smoothscroll''sms'boolean(default off)local to windowScrolling works with screen lines. When
'wrap' is set and the firstline in the window wraps part of it may not be visible, as if it isabove the window. "<<<" is displayed at the start of the first line,highlighted with
hl-NonText.You may also want to add "lastline" to the
'display' option to show asmuch of the last line as possible.
NOTE: partly implemented, doesn't work yet for
gj and
gk.
'softtabstop''sts''softtabstop''sts'number(default 0)local to bufferCreate soft tab stops, separated by
'softtabstop' number of columns.In Insert mode, pressing the
<Tab> key will move the cursor to thenext soft tab stop, instead of inserting a literal tab.
<BS> behavessimilarly in reverse. Vim inserts a minimal mix of tab and spacecharacters to produce the visual effect.
This setting does not affect the display of existing tab characters.
'spellcapcheck''spc''spellcapcheck''spc'string(default "[.?!]\_[\])'"\t ]\+")local to bufferPattern to locate the end of a sentence. The following word will bechecked to start with a capital letter. If not then it is highlightedwith SpellCap
hl-SpellCap (unless the word is also badly spelled).When this check is not wanted make this option empty.Only used when
'spell' is set.Be careful with special characters, see
option-backslash aboutincluding spaces and backslashes.To set this option automatically depending on the language, see
set-spc-auto.
'spellfile''spf''spellfile''spf'string(default "")local to bufferName of the word list file where words are added for the
zg and
zwcommands. It must end in ".{encoding}.add". You need to include thepath, otherwise the file is placed in the current directory.The path may include characters from
'isfname', ' ', ',', '@' and ':'.
E765It may also be a comma-separated list of names. A count before the
zg and
zw commands can be used to access each. This allows usinga personal word list file and a project word list file.When a word is added while this option is empty Nvim will use(and auto-create)
stdpath('data')/site/spell/. For the file name thefirst language name that appears in
'spelllang' is used, ignoring theregion.The resulting ".spl" file will be used for spell checking, it does nothave to appear in
'spelllang'.Normally one file is used for all regions, but you can add the regionname if you want to. However, it will then only be used when
'spellfile' is set to it, for entries in
'spelllang' only fileswithout region name will be found.This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
'spelllang''spl''spelllang''spl'string(default "en")local to bufferA comma-separated list of word list names. When the
'spell' option ison spellchecking will be done for these languages. Example:
set spelllang=en_us,nl,medical
This means US English, Dutch and medical words are recognized. Wordsthat are not recognized will be highlighted.The word list name must consist of alphanumeric characters, a dash oran underscore. It should not include a comma or dot. Using a dash isrecommended to separate the two letter language name from aspecification. Thus "en-rare" is used for rare English words.A region name must come last and have the form "_xx", where "xx" isthe two-letter, lower case region name. You can use more than oneregion by listing them: "en_us,en_ca" supports both US and CanadianEnglish, but not words specific for Australia, New Zealand or GreatBritain. (
Note: currently en_au and en_nz dictionaries are older thanen_ca, en_gb and en_us).If the name "cjk" is included East Asian characters are excluded fromspell checking. This is useful when editing text that also has Asianwords.Note that the "medical" dictionary does not exist, it is just anexample of a longer name.
E757As a special case the name of a .spl file can be given as-is. Thefirst "_xx" in the name is removed and used as the region name(_xx is an underscore, two letters and followed by a non-letter).This is mainly for testing purposes. You must make sure the correctencoding is used, Vim doesn't check it.How the related spell files are found is explained here:
spell-load.
If the
spellfile.vim plugin is active and you use a language namefor which Vim cannot find the .spl file in
'runtimepath' the pluginwill ask you if you want to download the file.
After this option has been set successfully, Vim will source the files"spell/LANG.vim" in
'runtimepath'. "LANG" is the value of
'spelllang'up to the first character that is not an ASCII letter or number andnot a dash. Also see
set-spc-auto.
'spelloptions''spo''spelloptions''spo'string(default "")local to bufferA comma-separated list of options for spell checking:camelWhen a word is CamelCased, assume "Cased" is aseparate word: every upper-case character in a wordthat comes after a lower case character indicates thestart of a new word.noplainbufferOnly spellcheck a buffer when
'syntax' is enabled,or when extmarks are set within the buffer. Onlydesignated regions of the buffer are spellchecked inthis case.
bestInternal method that works best for English. Findschanges like "fast" and uses a bit of sound-a-likescoring to improve the ordering.
doubleInternal method that uses two methods and mixes theresults. The first method is "fast", the other methodcomputes how much the suggestion sounds like the badword. That only works when the language specifiessound folding. Can be slow and doesn't always givebetter results.
fastInternal method that only checks for simple changes:character inserts/deletes/swaps. Works well forsimple typing mistakes.
{number}The maximum number of suggestions listed for
z=.Not used for
spellsuggest(). The number ofsuggestions is never more than the value of
'lines'minus two.
timeout:{millisec} Limit the time searching for suggestions to{millisec} milliseconds. Applies to the followingmethods. When omitted the limit is 5000. Whennegative there is no limit.
file:{filename} Read file
{filename}, which must have two columns,separated by a slash. The first column contains thebad word, the second column the suggested good word.Example:
theribal/terrible
Use this for common mistakes that do not appear at thetop of the suggestion list with the internal methods.Lines without a slash are ignored, use this forcomments.The word in the second column must be correct,otherwise it will not be used. Add the word to an".add" file if it is currently flagged as a spellingmistake.The file is used for all languages.
expr:{expr}Evaluate expression
{expr}. Use a function to avoidtrouble with spaces. Best is to call a functionwithout arguments, see
expr-option-function.
v:val holds the badly spelled word. The expressionmust evaluate to a List of Lists, each with asuggestion and a score.Example:
[[the, 33], [that, 44]]
Set
'verbose' and use
z= to see the scores that theinternal methods use. A lower score is better.This may invoke
spellsuggest() if you temporarilyset
'spellsuggest' to exclude the "expr:" part.Errors are silently ignored, unless you set the
'verbose' option to a non-zero value.
Only one of "best", "double" or "fast" may be used. The others mayappear several times in any order. Example:
set sps=file:~/.config/nvim/sugg,best,expr:MySuggest()
This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
'splitkeep''spk''splitkeep''spk'string(default "cursor")globalThe value of this option determines the scroll behavior when opening,closing or resizing horizontal splits.
Possible values are: cursorKeep the same relative cursor position. screenKeep the text on the same screen line. toplineKeep the topline the same.
For the "screen" and "topline" values, the cursor position will bechanged when necessary. In this case, the jumplist will be populatedwith the previous cursor position. For "screen", the text cannot alwaysbe kept on the same screen line when
'wrap' is enabled.
'startofline''sol''nostartofline''nosol''startofline''sol'boolean(default off)globalWhen "on" the commands listed below move the cursor to the firstnon-blank of the line. When off the cursor is kept in the same column(if possible). This applies to the commands:
CTRL-D,CTRL-U,CTRL-B,CTRL-F, "G", "H", "M", "L", "gg"
"%" with a count
buffer changing commands (CTRL-^, :bnext, :bNext, etc.)
Ex commands that only have a line number, e.g., ":25" or ":+".In case of buffer changing commands the cursor is placed at the columnwhere it was the last time the buffer was edited.
'statuscolumn''stc''statuscolumn''stc'string(default "")local to windowWhen non-empty, this option determines the content of the area to theside of a window, normally containing the fold, sign and number columns.The format of this option is like that of
'statusline'.
%lline number column for currently drawn line%ssign column for currently drawn line%Cfold column for currently drawn line
The
'statuscolumn' width follows that of the default columns andadapts to the
'numberwidth',
'signcolumn' and
'foldcolumn' optionvalues (regardless of whether the sign and fold items are present).Additionally, the
'statuscolumn' grows with the size of the evaluatedformat string, up to a point (following the maximum size of the defaultfold, sign and number columns). Shrinking only happens when the numberof lines in a buffer changes, or the
'statuscolumn' option is set.
The
v:lnum variable holds the line number to be drawn.The
v:relnum variable holds the relative line number to be drawn.The
v:virtnum variable is negative when drawing virtual lines, zero when drawing the actual buffer line, and positive when drawing the wrapped part of a buffer line.
NOTE: The %@ click execute function item is supported as well but thespecified function will be the same for each row in the same column.It cannot be switched out through a dynamic
'statuscolumn' format, thehandler should be written with this in mind.
Examples:
" Line number with bar separator and click handlers:set statuscolumn=%@SignCb@%s%=%T%@NumCb@%l│%T" Line numbers in hexadecimal for non wrapped part of lines:let &stc='%=%{v:virtnum>0?"":printf("%x",v:lnum)} '" Human readable line numbers with thousands separator:let &stc='%{substitute(v:lnum,"\\d\\zs\\ze\\' . '%(\\d\\d\\d\\)\\+$",",","g")}'" Both relative and absolute line numbers with different" highlighting for odd and even relative numbers:let &stc='%#NonText#%{&nu?v:lnum:""}' . '%=%{&rnu&&(v:lnum%2)?"\ ".v:relnum:""}' . '%#LineNr#%{&rnu&&!(v:lnum%2)?"\ ".v:relnum:""}'
WARNING: this expression is evaluated for each screen line so definingan expensive expression can negatively affect render performance.
The option consists of printf style '%' items interspersed withnormal text. Each status line item is of the form: %-0{minwid}.{maxwid}{item}All fields except the{item} are optional. A single percent sign canbe given as "%%".
stl-%!When the option starts with "%!" then it is used as an expression,evaluated and the result is used as the option value. Example:
set statusline=%!MyStatusLine()
The
g:statusline_winid variable will be set to the
window-ID of thewindow that the status line belongs to.The result can contain %{} items that will be evaluated too.Note that the "%!" expression is evaluated in the context of thecurrent window and buffer, while %{} items are evaluated in thecontext of the window that the statusline belongs to.
When there is error while evaluating the option then it will be madeempty to avoid further errors. Otherwise screen updating would loop.When the result contains unprintable characters the result isunpredictable.
field meaning
- Left justify the item. The default is right justified when minwid is larger than the length of the item.0 Leading zeroes in numeric items. Overridden by "-".minwid Minimum width of the item, padding as set by "-" & "0". Value must be 50 or less.maxwid Maximum width of the item. Truncation occurs with a "<" on the left for text items. Numeric items will be shifted down to maxwid-2 digits followed by ">"number where number is the amount of missing digits, much like an exponential notation.item A one letter code as described below.
Following is a description of the possible statusline items. Thesecond character in "item" is the type:N for numberS for stringF for flags as described below
not applicable
item meaning
f S Path to the file in the buffer, as typed or relative to current directory.F S Full path to the file in the buffer.t S File name (tail) of file in the buffer.m F Modified flag, text is "[+]"; "[-]" if
'modifiable' is off.M F Modified flag, text is ",+" or ",-".r F Readonly flag, text is "[RO]".R F Readonly flag, text is ",RO".h F Help buffer flag, text is "[help]".H F Help buffer flag, text is ",HLP".w F Preview window flag, text is "[Preview]".W F Preview window flag, text is ",PRV".y F Type of file in the buffer, e.g., "[vim]". See
'filetype'.Y F Type of file in the buffer, e.g., ",VIM". See
'filetype'.q S "[Quickfix List]", "[Location List]" or empty.k S Value of "b:keymap_name" or
'keymap' when
:lmap mappings are being used: "<keymap>"n N Buffer number.b N Value of character under cursor.B N As above, in hexadecimal.o N Byte number in file of byte under cursor, first byte is 1. Mnemonic: Offset from start of file (with one added)O N As above, in hexadecimal.l N Line number.L N Number of lines in buffer.c N Column number (byte index).v N Virtual column number (screen column).V N Virtual column number as -{num}. Not displayed if equal to 'c'.p N Percentage through file in lines as in
CTRL-G.P S Percentage through file of displayed window. This is like the percentage described for
'ruler'. Always 3 in length, unless translated.S S
'showcmd' content, see
'showcmdloc'.a S Argument list status as in default title. (
{current} of
{max}) Empty if the argument file count is zero or one.{ NF Evaluate expression between "%{" and "}" and substitute result. Note that there is no "%" before the closing "}". The expression cannot contain a "}" character, call a function to work around that. See
stl-%{ below.
{% - This is almost same as "{" except the result of the expression is re-evaluated as a statusline format string. Thus if the return value of expr contains "%" items they will get expanded. The expression can contain the "}" character, the end of expression is denoted by "%}". For example:
func! Stl_filename() abort return "%t"endfunc
stl=%{Stl_filename()} results in
"%t"stl=%{%Stl_filename()%} results in
"Name of current file"%} - End of "{%" expression( - Start of item group. Can be used for setting the width and alignment of a section. Must be followed by %) somewhere.) - End of item group. No width fields allowed.T N For
'tabline': start of tab page N label. Use %T or %X to end the label. Clicking this label with left mouse button switches to the specified tab page, while clicking it with middle mouse button closes the specified tab page.X N For
'tabline': start of close tab N label. Use %X or %T to end the label, e.g.: %3Xclose%X. Use %999X for a "close current tab" label. Clicking this label with left mouse button closes the specified tab page.@ N Start of execute function label. Use %X or %T to end the label, e.g.: %10@
[email protected]%X. Clicking this label runs the specified function: in the example when clicking once using left mouse button on "foo.c", a
SwitchBuffer(10, 1, 'l', ' ') expression will be run. The specified function receives the following arguments in order: 1. minwid field value or zero if no N was specified 2. number of mouse clicks to detect multiple clicks 3. mouse button used: "l", "r" or "m" for left, right or middle button respectively; one should not rely on third argument being only "l", "r" or "m": any other non-empty string value that contains only ASCII lower case letters may be expected for other mouse buttons 4. modifiers pressed: string which contains "s" if shift modifier was pressed, "c" for control, "a" for alt and "m" for meta; currently if modifier is not pressed string contains space instead, but one should not rely on presence of spaces or specific order of modifiers: use
stridx() to test whether some modifier is present; string is guaranteed to contain only ASCII letters and spaces, one letter per modifier; "?" modifier may also be present, but its presence is a bug that denotes that new mouse button recognition was added without modifying code that reacts on mouse clicks on this label. Use
getmousepos().winid in the specified function to get the corresponding window id of the clicked item.< - Where to truncate line if too long. Default is at the start. No width fields allowed.= - Separation point between alignment sections. Each section will be separated by an equal number of spaces. With one %= what comes after it will be right-aligned. With two %= there is a middle part, with white space left and right of it. No width fields allowed.# - Set highlight group. The name must follow and then a # again. Thus use %#HLname# for highlight group HLname. The same highlighting is used, also for the statusline of non-current windows.* - Set highlight group to User{N}, where
{N} is taken from the minwid field, e.g. %1*. Restore normal highlight with %* or %0*. The difference between User{N} and StatusLine will be applied to StatusLineNC for the statusline of non-current windows. The number N must be between 1 and 9. See
hl-User1..9When displaying a flag, Vim removes the leading comma, if any, whenthat flag comes right after plaintext. This will make a nice displaywhen flags are used like in the examples below.
When all items in a group becomes an empty string (i.e. flags that arenot set) and a minwid is not set for the group, the whole group willbecome empty. This will make a group like the following disappearcompletely from the statusline when none of the flags are set.
set statusline=...%(\ [%M%R%H]%)...
Beware that an expression is evaluated each and every time the statusline is displayed.
stl-%{g:actual_curbufg:actual_curwinWhile evaluating %{} the current buffer and current window will be settemporarily to that of the window (and buffer) whose statusline iscurrently being drawn. The expression will evaluate in this context.The variable "g:actual_curbuf" is set to the
bufnr() number of thereal current buffer and "g:actual_curwin" to the
window-ID of thereal current window. These values are strings.
If the statusline is not updated when you want it (e.g., after settinga variable that's used in an expression), you can force an update byusing:redrawstatus.
A result of all digits is regarded a number for display purposes.Otherwise the result is taken as flag text and applied to the rulesdescribed above.
Watch out for errors in expressions. They may render Vim unusable!If you are stuck, hold down ':' or 'Q' to get a prompt, then quit andedit your vimrc or whatever with "vim --clean" to get it right.
Examples:Emulate standard status line with
'ruler' set
set statusline=%<%f\ %h%w%m%r%=%-14.(%l,%c%V%)\ %P
Similar, but add ASCII value of char under the cursor (like "ga")
set statusline=%<%f%h%m%r%=%b\ 0x%B\ \ %l,%c%V\ %P
Display byte count and byte value, modified flag in red.
set statusline=%<%f%=\ [%1*%M%*%n%R%H]\ %-19(%3l,%02c%03V%)%O'%02b'hi User1 term=inverse,bold cterm=inverse,bold ctermfg=red
Display a ,GZ flag if a compressed file is loaded
set statusline=...%r%{VarExists('b:gzflag','\ [GZ]')}%h...
And define this function:
function VarExists(var, val) if exists(a:var) | return a:val | else | return '' | endifendfunction
'suffixes''su''suffixes''su'string(default ".bak,~,.o,.h,.info,.swp,.obj")globalFiles with these suffixes get a lower priority when multiple filesmatch a wildcard. See
suffixes. Commas can be used to separate thesuffixes. Spaces after the comma are ignored. A dot is also seen asthe start of a suffix. To avoid a dot or comma being recognized as aseparator, precede it with a backslash (see
option-backslash aboutincluding spaces and backslashes).See
'wildignore' for completely ignoring files.The use of
:set+= and
:set-= is preferred when adding or removingsuffixes from the list. This avoids problems when a future versionuses another default.
'suffixesadd''sua''suffixesadd''sua'string(default "")local to bufferComma-separated list of suffixes, which are used when searching for afile for the "gf", "[I", etc. commands. Example:
set suffixesadd=.java
'swapfile''swf''noswapfile''noswf''swapfile''swf'boolean(default on)local to bufferUse a swapfile for the buffer. This option can be reset when aswapfile is not wanted for a specific buffer. For example, withconfidential information that even root must not be able to access.Careful: All text will be in memory:
Don't use this for big files.
Recovery will be impossible!A swapfile will only be present when
'updatecount' is non-zero and
'swapfile' is set.When
'swapfile' is reset, the swap file for the current buffer isimmediately deleted. When
'swapfile' is set, and
'updatecount' isnon-zero, a swap file is immediately created.Also see
swap-file.If you want to open a new buffer without creating a swap file for it,use the
:noswapfile modifier.See
'directory' for where the swap file is created.
'switchbuf''swb''switchbuf''swb'string(default "uselast")globalThis option controls the behavior when switching between buffers.This option is checked, when
jumping to a tag using the
:stag command.
jumping to a buffer using a buffer split command (e.g.
:sbuffer,
:sbnext, or
:sbrewind).Possible values (comma-separated list): useopenIf included, jump to the first open window in thecurrent tab page that contains the specified buffer(if there is one). Otherwise: Do not examine otherwindows. usetabLike "useopen", but also consider windows in other tabpages. splitIf included, split the current window before loadinga buffer for a
quickfix command that display errors.Otherwise: do not split, use current window (when usedin the quickfix window: the previously used window orsplit if there is no other window). vsplitJust like "split" but split vertically. newtabLike "split", but open a new tab page. Overrules"split" when both are present. uselastIf included, jump to the previously used window whenjumping to errors with
quickfix commands.If a window has
'winfixbuf' enabled,
'switchbuf' is currently notapplied to the split window.
'synmaxcol''smc''synmaxcol''smc'number(default 3000)local to bufferMaximum column in which to search for syntax items. In long lines thetext after this column is not highlighted and following lines may notbe highlighted correctly, because the syntax state is cleared.This helps to avoid very slow redrawing for an XML file that is onelong line.Set to zero to remove the limit.
'syntax''syn''syntax''syn'string(default "")local to buffer
local-noglobalWhen this option is set, the syntax with this name is loaded, unlesssyntax highlighting has been switched off with ":syntax off".Otherwise this option does not always reflect the current syntax (theb:current_syntax variable does).This option is most useful in a modeline, for a file which syntax isnot automatically recognized. Example, in an IDL file:
/* vim: set syntax=idl : */
When a dot appears in the value then this separates two filetypenames. Example:
/* vim: set syntax=c.doxygen : */
This will use the "c" syntax first, then the "doxygen" syntax.Note that the second one must be prepared to be loaded as an addition,otherwise it will be skipped. More than one dot may appear.To switch off syntax highlighting for the current file, use:
set syntax=OFF
To switch syntax highlighting on according to the current value of the
'filetype' option:
set syntax=ON
What actually happens when setting the
'syntax' option is that theSyntax autocommand event is triggered with the value as argument.This option is not copied to another buffer, independent of the 's' or'S' flag in
'cpoptions'.Only alphanumeric characters, '.', '-' and '_' can be used.
Possible values (comma-separated list): leftIf included, go to the previous tab page instead ofthe next one. uselastIf included, go to the previously used tab page ifpossible. This option takes precedence over theothers.
'tabline''tal''tabline''tal'string(default "")globalWhen non-empty, this option determines the content of the tab pagesline at the top of the Vim window. When empty Vim will use a defaulttab pages line. See
setting-tabline for more info.
The tab pages line only appears as specified with the
'showtabline'option and only when there is no GUI tab line. When 'e' is in
'guioptions' and the GUI supports a tab line
'guitablabel' is usedinstead. Note that the two tab pages lines are very different.
Keep in mind that only one of the tab pages is the current one, othersare invisible and you can't jump to their windows.
'tabstop''ts''tabstop''ts'number(default 8)local to bufferDefines the column multiple used to display the Horizontal Tabcharacter (ASCII 9); a Horizontal Tab always advances to the next tabstop.The value must be at least 1 and at most 9999.If
'vartabstop' is set, this option is ignored.Leave it at 8 unless you have a strong reason (see usr
30.5).
'tagbsearch''tbs''notagbsearch''notbs''tagbsearch''tbs'boolean(default on)globalWhen searching for a tag (e.g., for the
:ta command), Vim can eitheruse a binary search or a linear search in a tags file. Binarysearching makes searching for a tag a LOT faster, but a linear searchwill find more tags if the tags file wasn't properly sorted.Vim normally assumes that your tags files are sorted, or indicate thatthey are not sorted. Only when this is not the case does the
'tagbsearch' option need to be switched off.
When
'tagbsearch' is on, binary searching is first used in the tagsfiles. In certain situations, Vim will do a linear search instead forcertain files, or retry all files with a linear search. When
'tagbsearch' is off, only a linear search is done.
Linear searching is done anyway, for one file, when Vim finds a lineat the start of the file indicating that it's not sorted:
!_TAG_FILE_SORTED0/some comment/
[The whitespace before and after the '0' must be a single<Tab>]
When a binary search was done and no match was found in any of thefiles listed in
'tags', and case is ignored or a pattern is usedinstead of a normal tag name, a retry is done with a linear search.Tags in unsorted tags files, and matches with different case will onlybe found in the retry.
If a tag file indicates that it is case-fold sorted, the second,linear search can be avoided when case is ignored. Use a value of '2'in the "!_TAG_FILE_SORTED" line for this. A tag file can be case-foldsorted with the -f switch to "sort" in most unices, as in the command:"sort -f -o tags tags". For Universal ctags and Exuberant ctagsversion 5.x or higher (at least 5.5) the --sort=foldcase switch can beused for this as well. Note that case must be folded to uppercase forthis to work.
When
'tagbsearch' is off, tags searching is slower when a full matchexists, but faster when no full match exists. Tags in unsorted tagsfiles may only be found with
'tagbsearch' off.When the tags file is not sorted, or sorted in a wrong way (not onASCII byte value),
'tagbsearch' should be off, or the line given abovemust be included in the tags file.This option doesn't affect commands that find all matching tags (e.g.,command-line completion and ":help").
'tagfunc''tfu''tagfunc''tfu'string(default "")local to bufferThis option specifies a function to be used to perform tag searches(including
taglist()).The function gets the tag pattern and should return a List of matchingtags. See
tag-function for an explanation of how to write thefunction and an example. The value can be the name of a function, a
lambda or a
Funcref. See
option-value-function for moreinformation.This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
'tags''tag'E433'tags''tag'string(default "./tags;,tags")global or local to buffer
global-localFilenames for the tag command, separated by spaces or commas. Toinclude a space or comma in a file name, precede it with backslashes(see
option-backslash about including spaces/commas and backslashes).When a file name starts with "./", the '.' is replaced with the pathof the current file. But only when the 'd' flag is not included in
'cpoptions'. Environment variables are expanded
:set_env. Also see
tags-option."*", "**" and other wildcards can be used to search for tags files ina directory tree. See
file-searching. E.g., "/lib/**/tags" willfind all files named "tags" below "/lib". The filename itself cannotcontain wildcards, it is used as-is. E.g., "/lib/**/tags?" will findfiles called "tags?".The
tagfiles() function can be used to get a list of the file namesactually used.The use of
:set+= and
:set-= is preferred when adding or removingfile names from the list. This avoids problems when a future versionuses another default.
'tagstack''tgst''notagstack''notgst''tagstack''tgst'boolean(default on)globalWhen on, the
tagstack is used normally. When off, a ":tag" or":tselect" command with an argument will not push the tag onto thetagstack. A following ":tag" without an argument, a ":pop" command orany other command that uses the tagstack will use the unmodifiedtagstack, but does change the pointer to the active entry.Resetting this option is useful when using a ":tag" command in amapping which should not change the tagstack.
Nvim will automatically attempt to determine if the host terminalsupports 24-bit color and will enable this option if it does(unless explicitly disabled by the user).
'termpastefilter''tpf''termpastefilter''tpf'string(default "BS,HT,ESC,DEL")globalA comma-separated list of options for specifying control charactersto be removed from the text pasted into the terminal window. Thesupported values are:
BS Backspace
HT TAB
FF Form feed
ESC Escape
DEL DEL
C0 Other control characters, excluding Line feed and Carriage return < ' '
C1 Control characters 0x80...0x9F
'termsync''notermsync''termsync'boolean(default on)globalIf the host terminal supports it, buffer all screen updatesmade during a redraw cycle so that each screen is displayed inthe terminal all at once. This can prevent tearing or flickeringwhen the terminal updates faster than Nvim can redraw.
This option is not used if
'thesaurusfunc' is set, either for thebuffer or globally.
To include a comma in a file name precede it with a backslash. Spacesafter a comma are ignored, otherwise spaces are included in the filename. See
option-backslash about using backslashes. The use of
:set+= and
:set-= is preferred when adding or removing directoriesfrom the list. This avoids problems when a future version usesanother default. Backticks cannot be used in this option for securityreasons.
This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
'title''notitle''title'boolean(default off)globalWhen on, the title of the window will be set to the value of
'titlestring' (if it is not empty), or to:filename [+=-] (path) - NvimWhere:filenamethe name of the file being edited-indicates the file cannot be modified,
'ma' off+indicates the file was modified=indicates the file is read-only=+indicates the file is read-only and modified(path)is the path of the file being edited
'titlelen''titlelen'number(default 85)globalGives the percentage of
'columns' to use for the length of the windowtitle. When the title is longer, only the end of the path name isshown. A '<' character before the path name is used to indicate this.Using a percentage makes this adapt to the width of the window. Butit won't work perfectly, because the actual number of charactersavailable also depends on the font used and other things in the titlebar. When
'titlelen' is zero the full path is used. Otherwise,values from 1 to 30000 percent can be used.
'titlelen' is also used for the
'titlestring' option.
'titleold''titleold'string(default "")globalIf not empty, this option will be used to set the window title whenexiting. Only if
'title' is enabled.This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
'titlestring''titlestring'string(default "")globalWhen this option is not empty, it will be used for the title of thewindow. This happens only when the
'title' option is on.
When this option contains printf-style '%' items, they will beexpanded according to the rules used for
'statusline'. If it containsan invalid '%' format, the value is used as-is and no error or warningwill be given when the value is set.
The default behaviour is equivalent to:
set titlestring=%t%(\ %M%)%(\ \(%{expand(\"%:~:h\")}\)%)%a\ -\ Nvim
Example:
auto BufEnter * let &titlestring = hostname() .. "/" .. expand("%:p")set title titlestring=%<%F%=%l/%L-%P titlelen=70
The value of
'titlelen' is used to align items in the middle or rightof the available space.Some people prefer to have the file name first:
set titlestring=%t%(\ %M%)%(\ (%{expand(\"%:~:.:h\")})%)%(\ %a%)
Note the use of "%{ }" and an expression to get the path of the file,without the file name. The "%( %)" constructs are used to add aseparating space only when needed.
NOTE: Use of special characters in
'titlestring' may cause the displayto be garbled (e.g., when it contains a CR or NL character).
For example if
<Esc> (the \x1b byte) is received and
'ttimeout' isset, Nvim waits
'ttimeoutlen' milliseconds for the terminal tocomplete a key code sequence. If no input arrives before the timeout,a single
<Esc> is assumed. Many TUI cursor key codes start with
<Esc>.
On very slow systems this may fail, causing cursor keys not to worksometimes. If you discover this problem you can ":set ttimeoutlen=9999".Nvim will wait for the next character to arrive after an<Esc>.
'ttimeoutlen''ttm''ttimeoutlen''ttm'number(default 50)globalTime in milliseconds to wait for a key code sequence to complete. Alsoused for
CTRL-\CTRL-N and
CTRL-\CTRL-G when part of a command hasbeen typed.
'undodir''udir'E5003'undodir''udir'string(default "$XDG_STATE_HOME/nvim/undo//")globalList of directory names for undo files, separated with commas.See
'backupdir' for details of the format."." means using the directory of the file. The undo file name for"file.txt" is ".file.txt.un~".For other directories the file name is the full path of the editedfile, with path separators replaced with "%".When writing: The first directory that exists is used. "." alwaysworks, no directories after "." will be used for writing. If none ofthe directories exist Nvim will attempt to create the last directory inthe list.When reading all entries are tried to find an undo file. The firstundo file that exists is used. When it cannot be read an error isgiven, no further entry is used.See
undo-persistence.This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
'undofile''udf''noundofile''noudf''undofile''udf'boolean(default off)local to bufferWhen on, Vim automatically saves undo history to an undo file whenwriting a buffer to a file, and restores undo history from the samefile on buffer read.The directory where the undo file is stored is specified by
'undodir'.For more information about this feature see
undo-persistence.The undo file is not read when
'undoreload' causes the buffer frombefore a reload to be saved for undo.When
'undofile' is turned off the undo file is NOT deleted.
'undolevels''ul''undolevels''ul'number(default 1000)global or local to buffer
global-localMaximum number of changes that can be undone. Since undo informationis kept in memory, higher numbers will cause more memory to be used.Nevertheless, a single change can already use a large amount of memory.Set to 0 for Vi compatibility: One level of undo and "u" undoesitself:
set ul=0
But you can also get Vi compatibility by including the 'u' flag in
'cpoptions', and still be able to use
CTRL-R to repeat undo.Also see
undo-two-ways.Set to -1 for no undo at all. You might want to do this only for thecurrent buffer:
setlocal ul=-1
This helps when you run out of memory for a single change.
The local value is set to -123456 when the global value is to be used.
'undoreload''ur''undoreload''ur'number(default 10000)globalSave the whole buffer for undo when reloading it. This applies to the":e!" command and reloading for when the buffer changed outside ofVim.
FileChangedShellThe save only happens when this option is negative or when the numberof lines is smaller than the value of this option.Set this option to zero to disable undo for a reload.
When saving undo for a reload, any undo file is not read.
Note that this causes the whole buffer to be stored in memory. Setthis option to a lower value if you run out of memory.
'updatecount''uc''updatecount''uc'number(default 200)globalAfter typing this many characters the swap file will be written todisk. When zero, no swap file will be created at all (see chapter onrecovery
crash-recovery).
'updatecount' is set to zero by startingVim with the "-n" option, see
startup. When editing in readonlymode this option will be initialized to 10000.The swapfile can be disabled per buffer with
'swapfile'.When
'updatecount' is set from zero to non-zero, swap files arecreated for all buffers that have
'swapfile' set. When
'updatecount'is set to zero, existing swap files are not deleted.This option has no meaning in buffers where
'buftype' is "nofile"or "nowrite".
'varsofttabstop''vsts''varsofttabstop''vsts'string(default "")local to bufferDefines variable-width soft tab stops. The value is a comma-separatedlist of widths in columns. Each width defines the number of columnsbefore the next soft tab stop. The last value repeats indefinitely.
For example, when editing assembly language files where statementsstart in the 9th column and comments in the 41st, it may be usefulto use the following:
set varsofttabstop=8,32,8
This sets soft tab stops at column 8, then at column 40 (8 + 32), andevery 8 columns thereafter.
Note: this setting overrides
'softtabstop'.See section
30.5 of the user manual for detailed explanations on howVim works with tabs and spaces.
'vartabstop''vts''vartabstop''vts'string(default "")local to bufferDefines variable-width tab stops. The value is a comma-separated listof widths in columns. Each width defines the number of columnsbefore the next tab stop; the last value repeats indefinitely.
For example:
:set vartabstop=4,8
This places the first tab stop 4 columns from the start of the lineand each subsequent tab stop 8 columns apart.
Note: this setting overrides
'tabstop'.On UNIX, it is recommended to keep the default tabstop value of 8.Consider setting
'varsofttabstop' instead.See section
30.5 of the user manual for detailed explanations on howVim works with tabs and spaces.
Tracing of assignments to options, mappings, etc. in Lua scripts isenabled at level 1; Lua scripts are not traced when
'verbose' is 0,for performance.
If greater than or equal to a given level, Nvim produces the followingmessages:
Level Messages
----------------------------------------------------------------------1Enables Lua tracing (see above). Does not produce messages.2When a file is ":source"'ed, or
shada file is read or written.3UI info, terminal capabilities.4Shell commands.5Every searched tags file and include file.8Files for which a group of autocommands is executed.9Executed autocommands.11Finding items in a path.12Vimscript function calls.13When an exception is thrown, caught, finished, or discarded.14Anything pending in a ":finally" clause.15Ex commands from a script (truncated at 200 characters).16Ex commands.
If
'verbosefile' is set then the verbose messages are not displayed.
'verbosefile''vfile''verbosefile''vfile'string(default "")globalWhen not empty all messages are written in a file with this name.When the file exists messages are appended.Writing to the file ends when Vim exits or when
'verbosefile' is madeempty. Writes are buffered, thus may not show up for some time.Setting
'verbosefile' to a new value is like making it empty first.The difference with
:redir is that verbose messages are notdisplayed when
'verbosefile' is set.This option cannot be set from a
modeline or in the
sandbox, forsecurity reasons.
'viewoptions''vop''viewoptions''vop'string(default "folds,cursor,curdir")globalChanges the effect of the
:mkview command. It is a comma-separatedlist of words. Each word enables saving and restoring something:
wordsave and restore
cursorcursor position in file and in window curdirlocal current directory, if set with
:lcd foldsmanually created folds, opened/closed folds and localfold options optionsoptions and mappings local to a window or buffer (notglobal values for local options) localoptions same as "options" slash
deprecated Always enabled. Uses "/" in filenames. unix
deprecated Always enabled. Uses "\n" line endings.
'virtualedit''ve''virtualedit''ve'string(default "")global or local to window
global-localA comma-separated list of these words: blockAllow virtual editing in Visual block mode. insertAllow virtual editing in Insert mode. allAllow virtual editing in all modes. onemoreAllow the cursor to move just past the end of the line noneWhen used as the local value, do not allow virtualediting even when the global value is set. When usedas the global value, "none" is the same as "". NONEAlternative spelling of "none".
Virtual editing means that the cursor can be positioned where there isno actual character. This can be halfway into a tab or beyond the endof the line. Useful for selecting a rectangle in Visual mode andediting a table."onemore" is not the same, it will only allow moving the cursor justafter the last character of the line. This makes some commands moreconsistent. Previously the cursor was always past the end of the lineif the line was empty. But it is far from Vi compatible. It may alsobreak some plugins or Vim scripts. For example because
l can movethe cursor after the last character. Use with care!Using the
$ command will move to the last character in the line, notpast it. This may actually move the cursor to the left!The
g$ command will move to the end of the screen line.It doesn't make sense to combine "all" with "onemore", but you willnot get a warning for it.When combined with other words, "none" is ignored.
'warn''nowarn''warn'boolean(default on)globalGive a warning message when a shell command is used while the bufferhas been changed.
'whichwrap''ww''whichwrap''ww'string(default "b,s")globalAllow specified keys that move the cursor left/right to move to theprevious/next line when the cursor is on the first/last character inthe line. Concatenate characters to allow this for these keys:
char key mode
b
<BS> Normal and Visual s
<Space> Normal and Visual h "h" Normal and Visual (not recommended) l "l" Normal and Visual (not recommended) <
<Left> Normal and Visual >
<Right> Normal and Visual ~ "~" Normal [
<Left> Insert and Replace ]
<Right> Insert and ReplaceFor example:
set ww=<,>,[,]
allows wrap only when cursor keys are used.When the movement keys are used in combination with a delete or changeoperator, the<EOL> also counts for a character. This makes "3h"different from "3dh" when the cursor crosses the end of a line. Thisis also true for "x" and "X", because they do the same as "dl" and"dh". If you use this, you may also want to use the mapping":map<BS> X" to make backspace delete the character in front of thecursor.When 'l' is included and it is used after an operator at the end of aline (not an empty line) then it will not move to the next line. Thismakes "dl", "cl", "yl" etc. work normally.
'wildchar''wc''wildchar''wc'number(default
<Tab>)globalCharacter you have to type to start wildcard expansion in thecommand-line, as specified with
'wildmode'.More info here:
cmdline-completion.The character is not recognized when used inside a macro. See
'wildcharm' for that.Some keys will not work, such as
CTRL-C,
<CR> and Enter.
<Esc> can be used, but hitting it twice in a row will still exitcommand-line as a failsafe measure.Although
'wc' is a number option, it can be specified as a number, asingle character, a
key-notation (e.g.
<Up>,
<C-F>) or a letterpreceded with a caret (e.g.
^F is
CTRL-F):
:set wc=27:set wc=X:set wc=^Iset wc=<Tab>
'wildchar' also enables completion in search pattern contexts such as
/,
?,
:s,
:g,
:v, and
:vim. To insert a literal
<Tab>instead of triggering completion, type
<C-V><Tab> or "\t".See also
'wildoptions'.
'wildcharm''wcm''wildcharm''wcm'number(default 0)global
'wildcharm' works exactly like
'wildchar', except that it isrecognized when used inside a macro. You can find "spare" command-linekeys suitable for this option by looking at
ex-edit-index. Normallyyou'll never actually type
'wildcharm', just use it in mappings thatautomatically invoke completion mode, e.g.:
set wcm=<C-Z>cnoremap ss so $vim/sessions/*.vim<C-Z>
Then after typing :ss you can useCTRL-P &CTRL-N.
The use of
:set+= and
:set-= is preferred when adding or removinga pattern from the list. This avoids problems when a future versionuses another default.
'wildmenu''wmnu''nowildmenu''nowmnu''wildmenu''wmnu'boolean(default on)globalWhen
'wildmenu' is on, command-line completion operates in an enhancedmode. On pressing
'wildchar' (usually
<Tab>) to invoke completion,the possible matches are shown.When
'wildoptions' contains "pum", then the completion matches areshown in a popup menu. Otherwise they are displayed just above thecommand line, with the first match highlighted (overwriting the statusline, if there is one).Keys that show the previous/next match, such as
<Tab> or
CTRL-P/CTRL-N, cause the highlight to move to the appropriate match.
'wildmode' must specify "full": "longest" and "list" do not start
'wildmenu' mode. You can check the current mode with
wildmenumode().The menu is cancelled when a key is hit that is not used for selectinga completion.
While the menu is active these keys have special meanings:CTRL-P- go to the previous entryCTRL-N- go to the next entry<Left><Right>- select previous/next match (likeCTRL-P/CTRL-N)<PageUp>- select a match several entries back<PageDown>- select a match several entries further<Up>- in filename/menu name completion: move up into parent directory or parent menu.<Down>- in filename/menu name completion: move into a subdirectory or submenu.<CR>- in menu completion, when the cursor is just after a dot: move into a submenu.CTRL-E- end completion, go back to what was there before selecting a match.CTRL-Y- accept the currently selected match and stop completion.
If you want
<Left> and
<Right> to move the cursor instead of selectinga different match, use this:
cnoremap <Left> <Space><BS><Left>cnoremap <Right> <Space><BS><Right>
'wildmode''wim''wildmode''wim'string(default "full")globalCompletion mode used for the character specified with
'wildchar'.This option is a comma-separated list of up to four parts,corresponding to the first, second, third, and fourth presses of
'wildchar'. Each part is a colon-separated list of completionbehaviors, which are applied simultaneously during that phase.
The possible behavior values are:""Only complete (insert) the first match. No furthermatches are cycled or listed."full"Complete the next full match. Cycles through allmatches, returning to the original input after thelast match. If
'wildmenu' is enabled, it will beshown."longest"Complete to the longest common substring. If thisdoesn't extend the input, the next
'wildmode' part isused."list"If multiple matches are found, list all of them."lastused"When completing buffer names, sort them by mostrecently used (excluding the current buffer). Onlyapplies to buffer name completion."noselect"If
'wildmenu' is enabled, show the menu but do notpreselect the first item.If only one match exists, it is completed fully, unless "noselect" isspecified.
Some useful combinations of colon-separated values:"longest:full"Start with the longest common string and show
'wildmenu' (if enabled). Does not cyclethrough full matches."list:full"List all matches and complete first match."list:longest"List all matches and complete till the longestcommon prefix."list:lastused"List all matches. When completing buffers,sort them by most recently used (excluding thecurrent buffer)."noselect:lastused"Do not preselect the first item in
'wildmenu'if it is active. When completing buffers,sort them by most recently used (excluding thecurrent buffer).
Examples:
set wildmode=full
Complete full match on every press (default behavior)
set wildmode=longest,full
First press: longest common substringSecond press: cycle through full matches
set wildmode=list:full
First press: list all matches and complete the first one
set wildmode=list,full
First press: list matches onlySecond press: complete full matches
set wildmode=longest,list
First press: longest common substringSecond press: list all matches
set wildmode=noselect:full
First press: show
'wildmenu' without completing or selectingSecond press: cycle full matches
set wildmode=noselect:lastused,full
Same as above, but buffer matches are sorted by time last usedMore info here:
cmdline-completion.
'wildoptions''wop''wildoptions''wop'string(default "pum,tagfile")globalA list of words that change how
cmdline-completion is done.The following values are supported: exacttextWhen this flag is present, search pattern completion(e.g., in
/,
?,
:s,
:g,
:v, and
:vim)shows exact buffer text as menu items, withoutpreserving regex artifacts like positionanchors (e.g.,
/\<). This provides more intuitivemenu items that match the actual buffer text.However, searches may be less accurate since thepattern is not preserved exactly.By default, Vim preserves the typed pattern (withanchors) and appends the matched word. This preservessearch correctness, especially when using regularexpressions or with
'smartcase' enabled. However, thecase of the appended matched word may not exactlymatch the case of the word in the buffer. fuzzyUse
fuzzy-matching to find completion matches. Whenthis value is specified, wildcard expansion will notbe used for completion. The matches will be sorted bythe "best match" rather than alphabetically sorted.This will find more matches than the wildcardexpansion. Currently fuzzy matching based completionis not supported for file and directory names andinstead wildcard expansion is used. pumDisplay the completion matches using the popup menuin the same style as the
ins-completion-menu. tagfileWhen using
CTRL-D to list matching tags, the kind oftag and the file of the tag is listed.Only one matchis displayed per line. Often used tag kinds are:d#defineffunction
'winaltkeys''wak''winaltkeys''wak'string(default "menu")globalonly used in Win32Some GUI versions allow the access to menu entries by using the ALTkey in combination with a character that appears underlined in themenu. This conflicts with the use of the ALT key for mappings andentering special characters. This option tells what to do: noDon't use ALT keys for menus. ALT key combinations can bemapped, but there is no automatic handling. yesALT key handling is done by the windowing system. ALT keycombinations cannot be mapped. menuUsing ALT in combination with a character that is a menushortcut key, will be handled by the windowing system. Otherkeys can be mapped.If the menu is disabled by excluding 'm' from
'guioptions', the ALTkey is never used for the menu.This option is not used for
<F10>; on Win32.
'winbar''wbr''winbar''wbr'string(default "")global or local to window
global-localWhen non-empty, this option enables the window bar and determines itscontents. The window bar is a bar that's shown at the top of everywindow with it enabled. The value of
'winbar' is evaluated like with
'statusline'.
Floating windows do not use the global value of
'winbar'. Thewindow-local value of
'winbar' must be set for a floating window tohave a window bar.
'winblend''winbl''winblend''winbl'number(default 0)local to windowEnables pseudo-transparency for a floating window. Valid values are inthe range of 0 for fully opaque window (disabled) to 100 for fullytransparent background. Values between 0-30 are typically most useful.
'winborder''winborder'string(default "")globalDefines the default border style of floating windows. The default valueis empty, which is equivalent to "none". Valid values include:
"bold": Bold line box.
"double": Double-line box.
"none": No border.
"rounded": Like "single", but with rounded corners ("╭" etc.).
"shadow": Drop shadow effect, by blending with the background.
"single": Single-line box.
"solid": Adds padding by a single whitespace cell.
custom: comma-separated list of exactly 8 characters in clockwise order starting from topleft. Example:
vim.o.winborder='+,-,+,|,+,-,+,|'
'window''wi''window''wi'number(default screen height - 1)globalWindow height used for
CTRL-F and
CTRL-B when there is only onewindow and the value is smaller than
'lines' minus one. The screenwill scroll
'window' minus two lines, with a minimum of one.When
'window' is equal to
'lines' minus one
CTRL-F and
CTRL-B scrollin a much smarter way, taking care of wrapping lines.When resizing the Vim window, and the value is smaller than 1 or morethan or equal to
'lines' it will be set to
'lines' minus 1.
Note: Do not confuse this with the height of the Vim window, use
'lines' for that.
'winfixbuf''wfb''nowinfixbuf''nowfb''winfixbuf''wfb'boolean(default off)local to windowIf enabled, the window and the buffer it is displaying are paired.For example, attempting to change the buffer with
:edit will fail.Other commands which change a window's buffer such as
:cnext willalso skip any window with
'winfixbuf' enabled. However if an Excommand has a "!" modifier, it can force switching buffers.
'winheight''wh'E591'winheight''wh'number(default 1)globalMinimal number of lines for the current window. This is not a hardminimum, Vim will use fewer lines if there is not enough room. If thefocus goes to a window that is smaller, its size is increased, at thecost of the height of other windows.Set
'winheight' to a small number for normal editing.Set it to 999 to make the current window fill most of the screen.Other windows will be only
'winminheight' high. This has the drawbackthat ":all" will create only two windows. To avoid "vim -o 1 2 3 4"to create only two windows, set the option after startup is done,using the
VimEnter event:
au VimEnter * set winheight=999
Minimum value is 1.The height is not adjusted after one of the commands that change theheight of the current window.
'winheight' applies to the current window. Use
'winminheight' to setthe minimal height for other windows.
Highlights of vertical separators are determined by the window to theleft of the separator. The
'tabline' highlight of a tabpage isdecided by the last-focused window of the tabpage. Highlights ofthe popupmenu are determined by the current window. Highlights in themessage area cannot be overridden.
Example: show a different color for non-current windows:
set winhighlight=Normal:MyNormal,NormalNC:MyNormalNC
'winminheight''wmh''winminheight''wmh'number(default 1)globalThe minimal height of a window, when it's not the current window.This is a hard minimum, windows will never become smaller.When set to zero, windows may be "squashed" to zero lines (i.e. just astatus bar) if necessary. They will return to at least one line whenthey become active (since the cursor has to have somewhere to go.)Use
'winheight' to set the minimal height of the current window.This option is only checked when making a window smaller. Don't use alarge number, it will cause errors when opening more than a fewwindows. A value of 0 to 3 is reasonable.
'winminwidth''wmw''winminwidth''wmw'number(default 1)globalThe minimal width of a window, when it's not the current window.This is a hard minimum, windows will never become smaller.When set to zero, windows may be "squashed" to zero columns (i.e. justa vertical separator) if necessary. They will return to at least oneline when they become active (since the cursor has to have somewhereto go.)Use
'winwidth' to set the minimal width of the current window.This option is only checked when making a window smaller. Don't use alarge number, it will cause errors when opening more than a fewwindows. A value of 0 to 12 is reasonable.
'winwidth''wiw'E592'winwidth''wiw'number(default 20)globalMinimal number of columns for the current window. This is not a hardminimum, Vim will use fewer columns if there is not enough room. Ifthe current window is smaller, its size is increased, at the cost ofthe width of other windows. Set it to 999 to make the current windowalways fill the screen. Set it to a small number for normal editing.The width is not adjusted after one of the commands to change thewidth of the current window.
'winwidth' applies to the current window. Use
'winminwidth' to setthe minimal width for other windows.
'wrap''nowrap''wrap'boolean(default on)local to windowThis option changes how text is displayed. It doesn't change the textin the buffer, see
'textwidth' for that.When on, lines longer than the width of the window will wrap anddisplaying continues on the next line. When off lines will not wrapand only part of long lines will be displayed. When the cursor ismoved to a part that is not shown, the screen will scrollhorizontally.The line will be broken in the middle of a word if necessary. See
'linebreak' to get the break at a word boundary.To make scrolling horizontally a bit more useful, try this:
set sidescroll=5set listchars+=precedes:<,extends:>
'write''nowrite''write'boolean(default on)globalAllows writing files. When not set, writing a file is not allowed.Can be used for a view-only mode, where modifications to the text arestill allowed. Can be reset with the
-m or
-M command lineargument. Filtering text is still possible, even though this requireswriting a temporary file.
'writebackup''wb''nowritebackup''nowb''writebackup''wb'boolean(default on)globalMake a backup before overwriting a file. The backup is removed afterthe file was successfully written, unless the
'backup' option isalso on.
WARNING: Switching this option off means that when Vim fails to writeyour buffer correctly and then, for whatever reason, Vim exits, youlose both the original file and what you were writing. Only resetthis option if your file system is almost full and it makes the writefail (and make sure not to exit Vim until the write was successful).See
backup-table for another explanation.When the
'backupskip' pattern matches, a backup is not made anyway.Depending on
'backupcopy' the backup is a new file or the originalfile renamed (and a new file is written).