codekingpro/portable-devtools
114k
1*options.txt* For Vim version 9.2. Last change: 2026 Apr 152 3 4 VIM REFERENCE MANUAL by Bram Moolenaar5 6 7Options *options*8 91. Setting options |set-option|102. Automatically setting options |auto-setting|113. Options summary |option-summary|12 13For an overview of options see quickref.txt |option-list|.14 15Vim has a number of internal variables and switches which can be set to16achieve special effects. These options come in three forms:17 boolean can only be on or off *boolean* *toggle*18 number has a numeric value19 string has a string value20 21==============================================================================221. Setting options *set-option* *E764*23 24 *:se* *:set*25:se[t][!] Show all options that differ from their default value.26 When [!] is present every option is on a separate27 line.28 29:se[t][!] all Show all but terminal options.30 When [!] is present every option is on a separate31 line.32 33:se[t] termcap Show all terminal options. Note that in the GUI the34 key codes are not shown, because they are generated35 internally and can't be changed. Changing the36 terminal codes in the GUI is not useful either...37 The options have the form t_AB, see38 |terminal-options|.39 40:se[t]! termcap Idem, but don't use multiple columns.41 42 *E518* *E519*43:se[t] {option}? Show value of {option}.44 45:se[t] {option} Toggle option: set, switch it on.46 Number option: show value.47 String option: show value.48 49:se[t] no{option} Toggle option: Reset, switch it off.50 51 *:set-!* *:set-inv*52:se[t] {option}! or53:se[t] inv{option} Toggle option: Invert value.54 55 *:set-default* *:set-&* *:set-&vi* *:set-&vim*56:se[t] {option}& Reset option to its default value. May depend on the57 current value of 'compatible'.58:se[t] {option}&vi Reset option to its Vi default value.59:se[t] {option}&vim Reset option to its Vim default value.60 61:se[t] all& Set all options to their default value. The values of62 these options are not changed:63 all terminal options, starting with t_64 'columns'65 'cryptmethod'66 'encoding'67 'key'68 'lines'69 'term'70 'ttymouse'71 'ttytype'72 Warning: This may have a lot of side effects.73 74 *:set-args* *:set=* *E487* *E521*75:se[t] {option}={value} or76:se[t] {option}:{value}77 Set string or number option to {value}.78 For numeric options the value can be given in decimal,79 hex (preceded with 0x) or octal (preceded with '0' or80 '0o').81 The old value can be inserted by typing 'wildchar' (by82 default this is a <Tab> or CTRL-E if 'compatible' is83 set). Many string options with fixed syntax and names84 also support completing known values. See85 |cmdline-completion| and |complete-set-option|.86 White space between {option} and '=' is allowed and87 will be ignored. White space between '=' and {value}88 is not allowed.89 See |option-backslash| for using white space and90 backslashes in {value}.91 92:se[t] {option}+={value} *:set+=*93 Add the {value} to a number option, or append the94 {value} to a string option. When the option is a95 comma-separated list, a comma is added, unless the96 value was empty.97 If the option is a list of flags, superfluous flags98 are removed. When adding a flag that was already99 present the option value doesn't change.100 When the option supports "key:value" items and {value}101 contains a "key:value" item or multiple102 comma-separated items, each item is processed103 individually:104 - A "key:value" item where the key already exists with105 a different value: the old item is removed and the106 new item is appended to the end.107 - A "key:value" item that is an exact duplicate is108 left unchanged.109 - Other items that already exist are left unchanged.110 - New items are appended to the end.111 Also see |:set-args| above.112 113:se[t] {option}^={value} *:set^=*114 Multiply the {value} to a number option, or prepend115 the {value} to a string option. When the option is a116 comma-separated list, a comma is added, unless the117 value was empty.118 When the option supports "key:value" items and {value}119 contains a "key:value" item or multiple120 comma-separated items, each item is processed121 individually. Works like |:set+=| but new items are122 prepended to the beginning instead of appended.123 Also see |:set-args| above.124 125:se[t] {option}-={value} *:set-=*126 Subtract the {value} from a number option, or remove127 the {value} from a string option, if it is there.128 If the {value} is not found in a string option, there129 is no error or warning. When the option is a comma130 separated list, a comma is deleted, unless the option131 becomes empty.132 When the option is a list of flags, {value} must be133 exactly as they appear in the option. Remove flags134 one by one to avoid problems.135 When the option supports "key:value" items and {value}136 contains a "key:value" item or multiple137 comma-separated items, each item is processed138 individually. A "key:value" item removes the existing139 item with that key regardless of its value. A "key:"140 item also removes by key match.141 The individual values from a comma separated list or142 list of flags can be inserted by typing 'wildchar'.143 See |complete-set-option|.144 Also see |:set-args| above.145 146The {option} arguments to ":set" may be repeated. For example: >147 :set ai nosi sw=3 ts=3148If you make an error in one of the arguments, an error message will be given149and the following arguments will be ignored.150 151 *:set-verbose*152When 'verbose' is non-zero, displaying an option value will also tell where it153was last set. Example: >154 :verbose set shiftwidth cindent?155< shiftwidth=4 ~156 Last set from modeline line 1 ~157 cindent ~158 Last set from /usr/local/share/vim/vim60/ftplugin/c.vim line 30 ~159This is only done when specific option values are requested, not for ":verbose160set all" or ":verbose set" without an argument.161When the option was set by hand there is no "Last set" message.162When the option was set while executing a function, user command or163autocommand, the script in which it was defined is reported.164Note that an option may also have been set as a side effect of setting165'compatible'.166A few special texts:167 Last set from modeline line 1 ~168 Option was set in a |modeline|.169 Last set from --cmd argument ~170 Option was set with command line argument |--cmd| or +.171 Last set from -c argument ~172 Option was set with command line argument |-c|, +, |-S| or173 |-q|.174 Last set from environment variable ~175 Option was set from an environment variable, $VIMINIT,176 $GVIMINIT or $EXINIT.177 Last set from error handler ~178 Option was cleared when evaluating it resulted in an error.179 180{not available when compiled without the |+eval| feature}181 182 *:set-termcap* *E522*183For {option} the form "t_xx" may be used to set a terminal option. This will184override the value from the termcap. You can then use it in a mapping. If185the "xx" part contains special characters, use the <t_xx> form: >186 :set <t_#4>=^[Ot187This can also be used to translate a special code for a normal key. For188example, if Alt-b produces <Esc>b, use this: >189 :set <M-b>=^[b190(the ^[ is a real <Esc> here, use CTRL-V <Esc> to enter it)191The advantage over a mapping is that it works in all situations.192 193You can define any key codes, e.g.: >194 :set t_xy=^[foo;195There is no warning for using a name that isn't recognized. You can map these196codes as you like: >197 :map <t_xy> something198< *E846*199When a key code is not set, it's like it does not exist. Trying to get its200value will result in an error: >201 :set t_kb=202 :set t_kb203< E846: Key code not set: t_kb ~204 205The t_xx options cannot be set from a |modeline| or in the |sandbox|, for206security reasons.207 208The listing from ":set" looks different from Vi. Long string options are put209at the end of the list. The number of options is quite large. The output of210"set all" probably does not fit on the screen, causing Vim to give the211|more-prompt|.212 213 *option-backslash*214To include white space in a string option value it has to be preceded with a215backslash. To include a backslash you have to use two. Effectively this216means that the number of backslashes in an option value is halved (rounded217down).218In options 'path', 'cdpath', and 'tags', spaces have to be preceded with three219backslashes instead for compatibility with version 3.0 where the options can220be separated by either commas or spaces.221Comma-separated options like 'backupdir' and 'tags' will also require commas222to be escaped with two backslashes, whereas this is not needed for223non-comma-separated ones like 'makeprg'.224When setting options using |:let| and |literal-string|, you need to use one225fewer layer of backslash.226A few examples: >227 :set makeprg=make\ file results in "make file"228 :let &makeprg='make file' (same as above)229 :set makeprg=make\\\ file results in "make\ file"230 :set tags=tags\ /usr/tags results in "tags" and "/usr/tags"231 :set tags=tags\\\ file results in "tags file"232 :let &tags='tags\ file' (same as above)233 234 :set makeprg=make,file results in "make,file"235 :set makeprg=make\\,file results in "make\,file"236 :set tags=tags,file results in "tags" and "file"237 :set tags=tags\\,file results in "tags\,file"238 :let &tags='tags\,file' (same as above)239 240The "|" character separates a ":set" command from a following command. To241include the "|" in the option value, use "\|" instead. This example sets the242'titlestring' option to "hi|there": >243 :set titlestring=hi\|there244This sets the 'titlestring' option to "hi" and 'iconstring' to "there": >245 :set titlestring=hi|set iconstring=there246 247Similarly, in legacy script the double quote character starts a comment. To248include the '"' in the option value, use '\"' instead. This example sets the249'titlestring' option to 'hi "there"': >250 :set titlestring=hi\ \"there\"251 252In |Vim9| script it's simpler, comments start with a '#' character, and only253when preceded by white space. A backslash is needed less often: >254 vim9script255 set titlestring=hi\ "there"256 set titlestring=hi#there#257 set titlestring=hi\ \#there#258 259For Win32 backslashes in file names are mostly not removed. More precise: For260options that expect a file name (those where environment variables are261expanded) a backslash before a normal file name character is not removed. But262a backslash before a special character (space, backslash, comma, etc.) is used263like explained above.264There is one special situation, when the value starts with "\\": >265 :set dir=\\machine\path results in "\\machine\path"266 :set dir=\\\\machine\\path results in "\\machine\path"267 :set dir=\\path\\file results in "\\path\file" (wrong!)268For the first one the start is kept, but for the second one the backslashes269are halved. This makes sure it works both when you expect backslashes to be270halved and when you expect the backslashes to be kept. The third gives a271result which is probably not what you want. Avoid it.272 273 *add-option-flags* *remove-option-flags*274 *E539* *E550* *E551* *E552*275Some options are a list of flags. When you want to add a flag to such an276option, without changing the existing ones, you can do it like this: >277 :set guioptions+=a278Remove a flag from an option like this: >279 :set guioptions-=a280This removes the 'a' flag from 'guioptions'.281Note that you should add or remove one flag at a time. If 'guioptions' has282the value "ab", using "set guioptions-=ba" won't work, because the string "ba"283doesn't appear.284 285 *:set_env* *expand-env* *expand-environment-var*286Environment variables in specific string options will be expanded. If the287environment variable exists the '$' and the following environment variable288name is replaced with its value. If it does not exist the '$' and the name289are not modified. Any non-id character (not a letter, digit or '_') may290follow the environment variable name. That character and what follows is291appended to the value of the environment variable. Examples: >292 :set term=$TERM.new293 :set path=/usr/$INCLUDE,$HOME/include,.294When adding or removing a string from an option with ":set opt-=val" or ":set295opt+=val" the expansion is done before the adding or removing.296 297 298Handling of local options *local-options*299 300Note: The following also applies to |global-local| options.301 302Some of the options only apply to a window or buffer. Each window or buffer303has its own copy of this option, thus each can have its own value. This304allows you to set 'list' in one window but not in another. And set305'shiftwidth' to 3 in one buffer and 4 in another.306 307The following explains what happens to these local options in specific308situations. You don't really need to know all of this, since Vim mostly uses309the option values you would expect. Unfortunately, doing what the user310expects is a bit complicated...311 312When splitting a window, the local options are copied to the new window. Thus313right after the split the contents of the two windows look the same.314 315When editing a new buffer, its local option values must be initialized. Since316the local options of the current buffer might be specifically for that buffer,317these are not used. Instead, for each buffer-local option there also is a318global value, which is used for new buffers. With ":set" both the local and319global value is changed. With "setlocal" only the local value is changed,320thus this value is not used when editing a new buffer.321 322When editing a buffer that has been edited before, the options from the window323that was last closed are used again. If this buffer has been edited in this324window, the values from back then are used. Otherwise the values from the325last closed window where the buffer was edited last are used.326 327It's possible to set a local window option specifically for a type of buffer.328When you edit another buffer in the same window, you don't want to keep329using these local window options. Therefore Vim keeps a global value of the330local window options, which is used when editing another buffer. Each window331has its own copy of these values. Thus these are local to the window, but332global to all buffers in the window. With this you can do: >333 :e one334 :set list335 :e two336Now the 'list' option will also be set in "two", since with the ":set list"337command you have also set the global value. >338 :set nolist339 :e one340 :setlocal list341 :e two342Now the 'list' option is not set, because ":set nolist" resets the global343value, ":setlocal list" only changes the local value and ":e two" gets the344global value. Note that if you do this next: >345 :e one346You will get back the 'list' value as it was the last time you edited "one".347The options local to a window are remembered for each buffer. This also348happens when the buffer is not loaded, but they are lost when the buffer is349wiped out |:bwipe|.350 351Special local window options *local-noglobal*352 353The following local window options won't be copied over when new windows are354created, thus they behave slightly differently:355 356 Option Reason ~357 'previewwindow' there can only be a single one358 'scroll' specific to existing window359 'winfixbuf' specific to existing window360 'winfixheight' specific to existing window361 'winfixwidth' specific to existing window362 363Special local buffer options364 365The following local buffer options won't be copied over when new buffers are366created, thus they behave slightly differently:367 368 Option Reason ~369 'filetype' explicitly set by autocommands370 'syntax' explicitly set by autocommands371 'bufhidden' denote |special-buffers|372 'buftype' denote |special-buffers|373 'readonly' will be detected automatically374 'modified' will be detected automatically375 376 *:setl* *:setlocal*377:setl[ocal][!] ... Like ":set" but set only the value local to the378 current buffer or window. Not all options have a379 local value. If the option does not have a local380 value the global value is set.381 With the "all" argument: display local values for all382 local options.383 Without argument: Display local values for all local384 options which are different from the default.385 When displaying a specific local option, show the386 local value. For a global/local boolean option, when387 the global value is being used, "--" is displayed388 before the option name.389 For a global option the global value is390 shown (but that might change in the future).391 392:se[t] {option}< Set the effective value of {option} to its global393 value.394 For string |global-local| options, the local value is395 removed, so that the global value will be used.396 For all other options, the global value is copied to397 the local value.398 399:setl[ocal] {option}< Set the effective value of {option} to its global400 value.401 For number and boolean |global-local| options, the402 local value is removed, so that the global value will403 be used.404 For all other options, including string |global-local|405 options, the global value is copied to the local406 value.407 408Note that the behaviour for |global-local| options is slightly different409between string and number-based options.410 411 *:setg* *:setglobal*412:setg[lobal][!] ... Like ":set" but set only the global value for a local413 option without changing the local value.414 When displaying an option, the global value is shown.415 With the "all" argument: display global values for all416 local options.417 Without argument: display global values for all local418 options which are different from the default.419 420For buffer-local and window-local options:421 Command global value local value condition ~422 :set option=value set set423 :setlocal option=value - set424:setglobal option=value set -425 :set option? - display local value is set426 :set option? display - local value is not set427 :setlocal option? - display428:setglobal option? display -429 430 431Global options with a local value *global-local*432 433Options are global when you mostly use one value for all buffers and windows.434For some global options it's useful to sometimes have a different local value.435You can set the local value with ":setlocal". That buffer or window will then436use the local value, while other buffers and windows continue using the global437value.438 439For example, you have two windows, both on C source code. They use the global440'makeprg' option. If you do this in one of the two windows: >441 :set makeprg=gmake442then the other window will switch to the same value. There is no need to set443the 'makeprg' option in the other C source window too.444However, if you start editing a Perl file in a new window, you want to use445another 'makeprg' for it, without changing the value used for the C source446files. You use this command: >447 :setlocal makeprg=perlmake448You can switch back to using the global value by making the local value empty: >449 :setlocal makeprg=450This only works for a string option. For a number or boolean option you need451to use the "<" flag, like this: >452 :setlocal autoread<453Note that for non-boolean and non-number options using "<" copies the global454value to the local value, it doesn't switch back to using the global value455(that matters when the global value changes later). You can also use: >456 :set path<457This will make the local value of 'path' empty, so that the global value is458used. Thus it does the same as: >459 :setlocal path=460Note: In the future more global options can be made |global-local|. Using461":setlocal" on a global option might work differently then.462 463 *option-value-function*464Some options ('completefunc', 'findfunc', 'imactivatefunc', 'imstatusfunc',465'omnifunc', 'operatorfunc', 'quickfixtextfunc', 'tagfunc' and 'thesaurusfunc')466are set to a function name or a function reference or a lambda function. When467using a lambda it will be converted to the name, e.g. "<lambda>123".468Examples:469>470 set opfunc=MyOpFunc471 set opfunc=function('MyOpFunc')472 set opfunc=funcref('MyOpFunc')473 set opfunc={a\ ->\ MyOpFunc(a)}474 475Set to a script-local function: >476 set opfunc=s:MyLocalFunc477 set opfunc=<SID>MyLocalFunc478In |Vim9| script the "s:" and "<SID>" can be omitted if the function exists in479the script: >480 set opfunc=MyLocalFunc481 482Set using a funcref variable: >483 let Fn = function('MyTagFunc')484 let &tagfunc = Fn485 486Set using a lambda expression: >487 let &tagfunc = {t -> MyTagFunc(t)}488 489Set using a variable with lambda expression: >490 let L = {a, b, c -> MyTagFunc(a, b , c)}491 let &tagfunc = L492 493In Vim9 script, in a compiled function, you can use a lambda, but a494closure does not work, because the function will be called without the495context of where it was defined.496 497 498Setting the filetype499 500:setf[iletype] [FALLBACK] {filetype} *:setf* *:setfiletype*501 Set the 'filetype' option to {filetype}, but only if502 not done yet in a sequence of (nested) autocommands.503 This is short for: >504 :if !did_filetype()505 : setlocal filetype={filetype}506 :endif507< This command is used in a filetype.vim file to avoid508 setting the 'filetype' option twice, causing different509 settings and syntax files to be loaded.510 511 When the optional FALLBACK argument is present, a512 later :setfiletype command will override the513 'filetype'. This is to be used for filetype514 detections that are just a guess. |did_filetype()|515 will return false after this command.516 517 *option-window* *optwin*518:bro[wse] se[t] *:set-browse* *:browse-set* *:opt* *:options*519:opt[ions] Open a window for viewing and setting all options.520 Options are grouped by function.521 Offers short help for each option. Hit <CR> on the522 short help to open a help window with more help for523 the option.524 Modify the value of the option and hit <CR> on the525 "set" line to set the new value. For window and526 buffer specific options, the last accessed window is527 used to set the option value in, unless this is a help528 window, in which case the window below help window is529 used (skipping the option-window).530 {not available when compiled without the |+eval|531 feature}532 533 *$HOME*534Using "~" is like using "$HOME", but it is only recognized at the start of an535option and after a space or comma.536 537On Unix systems "~user" can be used too. It is replaced by the home directory538of user "user". Example: >539 :set path=~mool/include,/usr/include,.540 541On Unix systems the form "${HOME}" can be used too. The name between {} can542contain non-id characters then. Note that if you want to use this for the543"gf" command, you need to add the '{' and '}' characters to 'isfname'.544 545NOTE: expanding environment variables and "~/" is only done with the ":set"546command, not when assigning a value to an option with ":let".547 548 *$HOME-windows*549On MS-Windows, if $HOME is not defined as an environment variable, then550at runtime Vim will set it to the expansion of $HOMEDRIVE$HOMEPATH.551If $HOMEDRIVE is not set then $USERPROFILE is used.552 553This expanded value is not exported to the environment, this matters when554running an external command: >555 :echo system('set | findstr ^HOME=')556and >557 :echo luaeval('os.getenv("HOME")')558should echo nothing (an empty string) despite exists('$HOME') being true.559When setting $HOME to a non-empty string it will be exported to the560subprocesses.561 562 563Note the maximum length of an expanded option is limited. How much depends on564the system, mostly it is something like 256 or 1024 characters.565 566 *:fix* *:fixdel*567:fix[del] Set the value of 't_kD':568 't_kb' is 't_kD' becomes ~569 CTRL-? CTRL-H570 not CTRL-? CTRL-?571 572 (CTRL-? is 0o177 octal, 0x7f hex)573 574 If your delete key terminal code is wrong, but the575 code for backspace is alright, you can put this in576 your .vimrc: >577 :fixdel578< This works no matter what the actual code for579 backspace is.580 581 If the backspace key terminal code is wrong you can582 use this: >583 :if &term == "termname"584 : set t_kb=^V<BS>585 : fixdel586 :endif587< Where "^V" is CTRL-V and "<BS>" is the backspace key588 (don't type four characters!). Replace "termname"589 with your terminal name.590 591 If your <Delete> key sends a strange key sequence (not592 CTRL-? or CTRL-H) you cannot use ":fixdel". Then use: >593 :if &term == "termname"594 : set t_kD=^V<Delete>595 :endif596< Where "^V" is CTRL-V and "<Delete>" is the delete key597 (don't type eight characters!). Replace "termname"598 with your terminal name.599 600 *Linux-backspace*601 Note about Linux: By default the backspace key602 produces CTRL-?, which is wrong. You can fix it by603 putting this line in your rc.local: >604 echo "keycode 14 = BackSpace" | loadkeys605<606 *NetBSD-backspace*607 Note about NetBSD: If your backspace doesn't produce608 the right code, try this: >609 xmodmap -e "keycode 22 = BackSpace"610< If this works, add this in your .Xmodmap file: >611 keysym 22 = BackSpace612< You need to restart for this to take effect.613 614==============================================================================6152. Automatically setting options *auto-setting*616 617Besides changing options with the ":set" command, there are three alternatives618to set options automatically for one or more files:619 6201. When starting Vim initializations are read from various places. See621 |initialization|. Most of them are performed for all editing sessions,622 and some of them depend on the directory where Vim is started.623 You can create an initialization file with |:mkvimrc|, |:mkview| and624 |:mksession|.6252. If you start editing a new file, the automatic commands are executed.626 This can be used to set options for files matching a particular pattern and627 many other things. See |autocommand|.6283. If you start editing a new file, and the 'modeline' option is on, a629 number of lines at the beginning and end of the file are checked for630 modelines. This is explained here.631 632 *modeline* *vim:* *vi:* *ex:* *E520*633There are two forms of modelines. The first form:634 [text{white}]{vi:|vim:|ex:}[white]{options}635 636[text{white}] empty or any text followed by at least one blank637 character (<Space> or <Tab>); "ex:" always requires at638 least one blank character639{vi:|vim:|ex:} the string "vi:", "vim:" or "ex:"640[white] optional white space641{options} a list of option settings, separated with white space642 or ':', where each part between ':' is the argument643 for a ":set" command (can be empty)644 645Examples:646 vi:noai:sw=3 ts=6 ~647 vim: tw=77 ~648 649The second form (this is compatible with some versions of Vi):650 651 [text{white}]{vi:|vim:|Vim:|ex:}[white]se[t] {options}:[text]652 653[text{white}] empty or any text followed by at least one blank654 character (<Space> or <Tab>); "ex:" always requires at655 least one blank character656{vi:|vim:|Vim:|ex:} the string "vi:", "vim:", "Vim:" or "ex:"657[white] optional white space658se[t] the string "set " or "se " (note the space); When659 "Vim" is used it must be "set".660{options} a list of options, separated with white space, which661 is the argument for a ":set" command662: a colon663[text] any text or empty664 665Examples:666 /* vim: set ai tw=75: */ ~667 /* Vim: set ai tw=75: */ ~668 669The white space before {vi:|vim:|Vim:|ex:} is required. This minimizes the670chance that a normal word like "lex:" is caught. There is one exception:671"vi:" and "vim:" can also be at the start of the line (for compatibility with672version 3.0). Using "ex:" at the start of the line will be ignored (this673could be short for "example:").674 675If the modeline is disabled within a modeline, subsequent modelines will be676ignored. This is to allow turning off modeline on a per-file basis. This is677useful when a line looks like a modeline but isn't. For example, it would be678good to start a YAML file containing strings like "vim:" with679 # vim: nomodeline ~680so as to avoid modeline misdetection. Following options on the same line681after modeline deactivation, if any, are still evaluated (but you would682normally not have any).683 684 *modeline-local*685The options are set like with ":setlocal": The new value only applies to the686buffer and window that contain the file. Although it's possible to set global687options from a modeline, this is unusual. If you have two windows open and688the files in it set the same global option to a different value, the result689depends on which one was opened last.690 691When editing a file that was already loaded, only the window-local options692from the modeline are used. Thus if you manually changed a buffer-local693option after opening the file, it won't be changed if you edit the same buffer694in another window. But window-local options will be set.695 696 *modeline-version*697If the modeline is only to be used for some versions of Vim, the version698number can be specified where "vim:" or "Vim:" is used:699 vim{vers}: version {vers} or later700 vim<{vers}: version before {vers}701 vim={vers}: version {vers}702 vim>{vers}: version after {vers}703{vers} is 700 for Vim 7.0 (hundred times the major version plus minor).704For example, to use a modeline only for Vim 7.0:705 /* vim700: set foldmethod=marker */ ~706To use a modeline for Vim after version 7.2:707 /* vim>702: set cole=2: */ ~708There can be no blanks between "vim" and the ":".709 710 711The number of lines that are checked can be set with the 'modelines' option.712If 'modeline' is off or 'modelines' is 0 no lines are checked.713 714Note that for the first form all of the rest of the line is used, thus a line715like:716 /* vi:ts=4: */ ~717will give an error message for the trailing "*/". This line is OK:718 /* vi:set ts=4: */ ~719 720If an error is detected the rest of the line is skipped.721 722If you want to include a ':' in a set command precede it with a '\'. The723backslash in front of the ':' will be removed. Example:724 /* vi:set fillchars=stl\:^,vert\:\|: */ ~725This sets the 'fillchars' option to "stl:^,vert:\|". Only a single backslash726before the ':' is removed. Thus to include "\:" you have to specify "\\:".727 *E992*728No other commands than "set" are supported, for security reasons (somebody729might create a Trojan horse text file with modelines). And not all options730can be set. For some options a flag is set, so that when the value is used731the |sandbox| is effective. Some options can only be set from the modeline732when 'modelineexpr' is set (the default is off).733 734Still, there is always a small risk that a modeline causes trouble. E.g.,735when some joker sets 'textwidth' to 5 all your lines are wrapped unexpectedly.736So disable modelines before editing untrusted text. The mail ftplugin does737this, for example.738 739Hint: If you would like to do something else than setting an option, you could740define an autocommand that checks the file for a specific string. For741example: >742 au BufReadPost * if getline(1) =~ "VAR" | call SetVar() | endif743And define a function SetVar() that does something with the line containing744"VAR".745 746==============================================================================7473. Options summary *option-summary*748 749In the list below all the options are mentioned with their full name and with750an abbreviation if there is one. Both forms may be used.751 752In this document when a boolean option is "set" that means that ":set option"753is entered. When an option is "reset", ":set nooption" is used.754 755For some options there are two default values: The "Vim default", which is756used when 'compatible' is not set, and the "Vi default", which is used when757'compatible' is set.758 759Most options are the same in all windows and buffers. There are a few that760are specific to how the text is presented in a window. These can be set to a761different value in each window. For example the 'list' option can be set in762one window and reset in another for the same text, giving both types of view763at the same time. There are a few options that are specific to a certain764file. These can have a different value for each file or buffer. For example765the 'textwidth' option can be 78 for a normal text file and 0 for a C766program.767 768 global one option for all buffers and windows769 local to window each window has its own copy of this option770 local to buffer each buffer has its own copy of this option771 772When creating a new window the option values from the currently active window773are used as a default value for the window-specific options. For the774buffer-specific options this depends on the 's' and 'S' flags in the775'cpoptions' option. If 's' is included (which is the default) the values for776buffer options are copied from the currently active buffer when a buffer is777first entered. If 'S' is present the options are copied each time the buffer778is entered, this is almost like having global options. If 's' and 'S' are not779present, the options are copied from the currently active buffer when the780buffer is created.781 782Hidden options *hidden-options*783 784Not all options are supported in all versions. This depends on the supported785features and sometimes on the system. A remark about this is in curly braces786below. When an option is not supported it may still be set without getting an787error, this is called a hidden option. You can't get the value of a hidden788option though, it is not stored.789 790To test if option "foo" can be used with ":set" use something like this: >791 if exists('&foo')792This also returns true for a hidden option. To test if option "foo" is really793supported use something like this: >794 if exists('+foo')795<796 *E355*797A jump table for the options with a short description can be found at |Q_op|.798 799 *'aleph'* *'al'* *aleph* *Aleph*800'aleph' 'al' number (default 128 for MS-Windows, 224 otherwise)801 global802 {only available when compiled with the |+rightleft|803 feature}804 The ASCII code for the first letter of the Hebrew alphabet. The805 routine that maps the keyboard in Hebrew mode, both in Insert mode806 (when hkmap is set) and on the command-line (when hitting CTRL-_)807 outputs the Hebrew characters in the range [aleph..aleph+26].808 aleph=128 applies to PC code, and aleph=224 applies to ISO 8859-8.809 See |rileft.txt|.810 811 *'allowrevins'* *'ari'* *'noallowrevins'* *'noari'*812'allowrevins' 'ari' boolean (default off)813 global814 {only available when compiled with the |+rightleft|815 feature}816 Allow CTRL-_ in Insert and Command-line mode. This is default off, to817 avoid that users that accidentally type CTRL-_ instead of SHIFT-_ get818 into reverse Insert mode, and don't know how to get out. See819 'revins'.820 NOTE: This option is reset when 'compatible' is set.821 822 *'altkeymap'* *'akm'* *'noaltkeymap'* *'noakm'*823'altkeymap' 'akm' boolean (default off)824 global825 {only available when compiled with the |+farsi|826 feature}827 This option was for using Farsi, which has been removed. See828 |farsi.txt|.829 830 *'ambiwidth'* *'ambw'*831'ambiwidth' 'ambw' string (default: "single")832 global833 Only effective when 'encoding' is "utf-8" or another Unicode encoding.834 Tells Vim what to do with characters with East Asian Width Class835 Ambiguous (such as Euro, Registered Sign, Copyright Sign, Greek836 letters, Cyrillic letters).837 838 There are currently two possible values:839 "single": Use the same width as characters in US-ASCII. This is840 expected by most users.841 "double": Use twice the width of ASCII characters.842 *E834* *E835*843 The value "double" cannot be used if 'listchars' or 'fillchars'844 contains a character that would be double width. These errors may845 also be given when calling setcellwidths().846 847 The values are overruled for characters specified with848 |setcellwidths()|.849 850 There are a number of CJK fonts for which the width of glyphs for851 those characters are solely based on how many octets they take in852 legacy/traditional CJK encodings. In those encodings, Euro,853 Registered sign, Greek/Cyrillic letters are represented by two octets,854 therefore those fonts have "wide" glyphs for them. This is also855 true of some line drawing characters used to make tables in text856 file. Therefore, when a CJK font is used for GUI Vim or857 Vim is running inside a terminal (emulators) that uses a CJK font858 (or Vim is run inside an xterm invoked with "-cjkwidth" option.),859 this option should be set to "double" to match the width perceived860 by Vim with the width of glyphs in the font. Perhaps it also has861 to be set to "double" under CJK MS-Windows when the system locale is862 set to one of CJK locales. See Unicode Standard Annex #11863 (http://www.unicode.org/reports/tr11).864 865 Vim may set this option automatically at startup time when Vim is866 compiled with the |+termresponse| feature and if |t_u7| is set to the867 escape sequence to request cursor position report. The response can868 be found in |v:termu7resp|.869 870 *'antialias'* *'anti'* *'noantialias'* *'noanti'*871'antialias' 'anti' boolean (default: off)872 global873 {only available when compiled with GUI enabled874 on macOS}875 This option only has an effect in the GUI version of Vim on macOS876 v10.2 or later. When on, Vim will use smooth ("antialiased") fonts,877 which can be easier to read at certain sizes on certain displays.878 Setting this option can sometimes cause problems if 'guifont' is set879 to its default (empty string).880 NOTE: This option is reset when 'compatible' is set.881 882 *'arabic'* *'arab'* *'noarabic'* *'noarab'*883'arabic' 'arab' boolean (default off)884 local to window885 {only available when compiled with the |+arabic|886 feature}887 This option can be set to start editing Arabic text.888 Setting this option will:889 - Set the 'rightleft' option, unless 'termbidi' is set.890 - Set the 'arabicshape' option, unless 'termbidi' is set.891 - Set the 'keymap' option to "arabic"; in Insert mode CTRL-^ toggles892 between typing English and Arabic key mapping.893 - Set the 'delcombine' option894 Note that 'encoding' must be "utf-8" for working with Arabic text.895 896 Resetting this option will:897 - Reset the 'rightleft' option.898 - Disable the use of 'keymap' (without changing its value).899 Note that 'arabicshape' and 'delcombine' are not reset (it is a global900 option).901 NOTE: This option is reset when 'compatible' is set.902 Also see |arabic.txt|.903 904 *'arabicshape'* *'arshape'*905 *'noarabicshape'* *'noarshape'*906'arabicshape' 'arshape' boolean (default on)907 global908 {only available when compiled with the |+arabic|909 feature}910 When on and 'termbidi' is off, the required visual character911 corrections that need to take place for displaying the Arabic language912 take effect. Shaping, in essence, gets enabled; the term is a broad913 one which encompasses:914 a) the changing/morphing of characters based on their location915 within a word (initial, medial, final and stand-alone).916 b) the enabling of the ability to compose characters917 c) the enabling of the required combining of some characters918 When disabled the display shows each character's true stand-alone919 form.920 Arabic is a complex language which requires other settings, for921 further details see |arabic.txt|.922 NOTE: This option is set when 'compatible' is set.923 924 *'autochdir'* *'acd'* *'noautochdir'* *'noacd'*925'autochdir' 'acd' boolean (default off)926 global927 {only available when compiled with it, use928 exists("+autochdir") to check}929 When on, Vim will change the current working directory whenever you930 open a file, switch buffers, delete a buffer or open/close a window.931 It will change to the directory containing the file which was opened932 or selected. When a buffer has no name it also has no directory, thus933 the current directory won't change when navigating to it.934 Note: When this option is on some plugins may not work.935 936 *'autocomplete'* *'ac'* *'noautocomplete'* *'noac'*937'autocomplete' 'ac' boolean (default off)938 global or local to buffer |global-local|939 {only available on platforms with timing support}940 When on, Vim shows a completion menu as you type, similar to using941 |i_CTRL-N|, but triggered automatically. See |ins-autocompletion|.942 943 *'autocompletedelay'* *'acl'*944'autocompletedelay' 'acl' number (default 0)945 global946 Delay in milliseconds before the autocomplete menu appears after947 typing. If you prefer it not to open too quickly, set this value948 slightly above your typing speed. See |ins-autocompletion|.949 950 *'autocompletetimeout'* *'act'*951'autocompletetimeout' 'act' number (default 80)952 global953 Initial timeout (in milliseconds) for the decaying time-sliced954 completion algorithm. Starts at this value, halves for each slower955 source until a minimum is reached. All sources run, but slower ones956 are quickly de-prioritized. The default is tuned so the popup menu957 opens within ~200ms even with multiple slow sources on a slow system.958 Changing this value is rarely needed. Only 80 or higher is valid.959 Special case: when 'complete' contains "F" or "o" (function sources),960 a longer timeout is used, allowing up to ~1s for sources such as LSP961 servers that may sometimes take longer (e.g., while loading modules).962 See |ins-autocompletion|.963 964 *'autoindent'* *'ai'* *'noautoindent'* *'noai'*965'autoindent' 'ai' boolean (default off)966 local to buffer967 Copy indent from current line when starting a new line (typing <CR>968 in Insert mode or when using the "o" or "O" command). If you do not969 type anything on the new line except <BS> or CTRL-D and then type970 <Esc>, CTRL-O or <CR>, the indent is deleted again. Moving the cursor971 to another line has the same effect, unless the 'I' flag is included972 in 'cpoptions'.973 When autoindent is on, formatting (with the "gq" command or when you974 reach 'textwidth' in Insert mode) uses the indentation of the first975 line.976 When 'smartindent' or 'cindent' is on the indent is changed in977 a different way.978 The 'autoindent' option is reset when the 'paste' option is set and979 restored when 'paste' is reset.980 981 *'autoread'* *'ar'* *'noautoread'* *'noar'*982'autoread' 'ar' boolean (default off)983 global or local to buffer |global-local|984 When a file has been detected to have been changed outside of Vim and985 it has not been changed inside of Vim, automatically read it again.986 When the file has been deleted this is not done, so you have the text987 from before it was deleted. When it appears again then it is read.988 |timestamp|989 If this option has a local value, use this command to switch back to990 using the global value: >991 :set autoread<992<993 994 *'autoshelldir'* *'asd'* *'noautoshelldir'* *'noasd'*995'autoshelldir' 'asd' boolean (default off)996 global997 When on, Vim will change the current working directory whenever you998 change the directory of the shell running in a terminal window. You999 need proper setting-up, so whenever the shell's pwd changes an OSC 71000 escape sequence will be emitted. For example, on Linux, you can1001 source /etc/profile.d/vte.sh in your shell profile if you use bash or1002 zsh. For bash this should work (put it in a bash init file): >1003 if [[ -n "$VIM_TERMINAL" ]]; then1004 PROMPT_COMMAND='_vim_sync_PWD'1005 function _vim_sync_PWD() {1006 printf '\033]7;file://%s\033\\' "$PWD"1007 }1008 fi1009<1010 Or, in a zsh init file: >1011 if [[ -n "$VIM_TERMINAL" ]]; then1012 autoload -Uz add-zsh-hook1013 add-zsh-hook -Uz chpwd _vim_sync_PWD1014 function _vim_sync_PWD() {1015 printf '\033]7;file://%s\033\\' "$PWD"1016 }1017 fi1018<1019 In a fish init file: >1020 if test -n "$VIM_TERMINAL"1021 function _vim_sync_PWD --on-variable=PWD1022 printf '\033]7;file://%s\033\\' "$PWD"1023 end1024 end1025<1026 You can find an alternative method at |terminal-autoshelldir|.1027 When the parsing of the OSC sequence fails you get *E1179* .1028 1029 *'autowrite'* *'aw'* *'noautowrite'* *'noaw'*1030'autowrite' 'aw' boolean (default off)1031 global1032 Write the contents of the file, if it has been modified, on each1033 `:next`, `:rewind`, `:last`, `:first`, `:previous`, `:tag`, `:stop`,1034 `:suspend`, `:!`, `:make`, `:terminal`, CTRL-] or CTRL-^ command; and1035 when a `:buffer`, CTRL-O, CTRL-I, '{A-Z0-9}, or `{A-Z0-9} command1036 switches to another file.1037 A buffer is not written if it becomes hidden, e.g. when 'bufhidden' is1038 set to "hide" and `:next` is used.1039 Note that for some commands the 'autowrite' option is not used, see1040 'autowriteall' for that.1041 Some buffers will not be written, specifically when 'buftype' is1042 "nowrite", "nofile", "terminal" or "prompt".1043 USE WITH CARE: If you make temporary changes to a buffer that you1044 don't want to be saved this option may cause it to be saved anyway.1045 Renaming the buffer with ":file {name}" may help avoid this.1046 1047 *'autowriteall'* *'awa'* *'noautowriteall'* *'noawa'*1048'autowriteall' 'awa' boolean (default off)1049 global1050 Like 'autowrite', but also used for commands `:edit`, `:enew`,1051 `:quit`, `:qall`, `:exit`, `:xit`, `:recover` and closing the Vim1052 window.1053 Setting this option also implies that Vim behaves like 'autowrite' has1054 been set.1055 1056 *'background'* *'bg'*1057'background' 'bg' string (default "dark" or "light", see below)1058 global1059 When set to "dark", Vim will try to use colors that look good on a1060 dark background. When set to "light", Vim will try to use colors that1061 look good on a light background. Any other value is illegal.1062 Vim tries to set the default value according to the terminal used.1063 This will not always be correct.1064 Setting this option does not change the background color, it tells Vim1065 what the background color looks like. For changing the background1066 color, see |:hi-normal|.1067 1068 When 'background' is changed Vim will adjust the default color groups1069 for the new value. But the colors used for syntax highlighting will1070 not change. *g:colors_name*1071 When a color scheme is loaded (the "g:colors_name" variable is set)1072 changing 'background' will cause the color scheme to be reloaded. If1073 the color scheme adjusts to the value of 'background' this will work.1074 However, if the color scheme sets 'background' itself the effect may1075 be undone. First delete the "g:colors_name" variable when needed.1076 1077 When setting 'background' to the default value with: >1078 :set background&1079< Vim will guess the value. In the GUI this should work correctly,1080 in other cases Vim might not be able to guess the right value.1081 If the GUI supports a dark theme, you can use the "d" flag in1082 'guioptions', see |'go-d'|.1083 1084 When the |t_RB| option is set, Vim will use it to request the background1085 color from the terminal. If the returned RGB value is dark/light and1086 'background' is not dark/light, 'background' will be set and the1087 screen is redrawn. This may have side effects, make |t_RB| empty in1088 your .vimrc if you suspect this problem. The response to |t_RB| can1089 be found in |v:termrbgresp|.1090 1091 When starting the GUI, the default value for 'background' will be1092 "light". When the value is not set in the .gvimrc, and Vim detects1093 that the background is actually quite dark, 'background' is set to1094 "dark". But this happens only AFTER the .gvimrc file has been read1095 (because the window needs to be opened to find the actual background1096 color). To get around this, force the GUI window to be opened by1097 putting a ":gui" command in the .gvimrc file, before where the value1098 of 'background' is used (e.g., before ":syntax on").1099 1100 For MS-Windows the default is "dark".1101 For other systems "dark" is used when 'term' is "linux",1102 "screen.linux", "cygwin" or "putty", or $COLORFGBG suggests a dark1103 background. Otherwise the default is "light".1104 1105 The |:terminal| command and the |term_start()| function use the1106 'background' value to decide whether the terminal window will start1107 with a white or black background.1108 1109 Normally this option would be set in the .vimrc file. Possibly1110 depending on the terminal name. Example: >1111 :if &term == "pcterm"1112 : set background=dark1113 :endif1114< When this option is set, the default settings for the highlight groups1115 will change. To use other settings, place ":highlight" commands AFTER1116 the setting of the 'background' option.1117 This option is also used in the "$VIMRUNTIME/syntax/syntax.vim" file1118 to select the colors for syntax highlighting. After changing this1119 option, you must load syntax.vim again to see the result. This can be1120 done with ":syntax on".1121 1122 *'backspace'* *'bs'*1123'backspace' 'bs' string (Vim default: "indent,eol,start",1124 Vi default: "")1125 global1126 Influences the working of <BS>, <Del>, CTRL-W and CTRL-U in Insert1127 mode. This is a list of items, separated by commas. Each item allows1128 a way to backspace over something:1129 value effect ~1130 indent allow backspacing over autoindent1131 eol allow backspacing over line breaks (join lines)1132 start allow backspacing over the start of insert; CTRL-W and CTRL-U1133 stop once at the start of insert.1134 nostop like start, except CTRL-W and CTRL-U do not stop at the start1135 of insert.1136 1137 When the value is empty, Vi compatible backspacing is used, none of1138 the ways mentioned for the items above are possible.1139 1140 For backwards compatibility with version 5.4 and earlier:1141 value effect ~1142 0 same as ":set backspace=" (Vi compatible)1143 1 same as ":set backspace=indent,eol"1144 2 same as ":set backspace=indent,eol,start"1145 3 same as ":set backspace=indent,eol,nostop"1146 1147 See |:fixdel| if your <BS> or <Del> key does not do what you want.1148 NOTE: This option is set to "" when 'compatible' is set.1149 1150 *'backup'* *'bk'* *'nobackup'* *'nobk'*1151'backup' 'bk' boolean (default off)1152 global1153 Make a backup before overwriting a file. Leave it around after the1154 file has been successfully written. If you do not want to keep the1155 backup file, but you do want a backup while the file is being1156 written, reset this option and set the 'writebackup' option (this is1157 the default). If you do not want a backup file at all reset both1158 options (use this if your file system is almost full). See the1159 |backup-table| for more explanations.1160 When the 'backupskip' pattern matches, a backup is not made anyway.1161 When 'patchmode' is set, the backup may be renamed to become the1162 oldest version of a file.1163 NOTE: This option is reset when 'compatible' is set.1164 1165 *'backupcopy'* *'bkc'*1166'backupcopy' 'bkc' string (Vi default for Unix: "yes", otherwise: "auto")1167 global or local to buffer |global-local|1168 When writing a file and a backup is made, this option tells how it's1169 done. This is a comma-separated list of words.1170 1171 The main values are:1172 "yes" make a copy of the file and overwrite the original one1173 "no" rename the file and write a new one1174 "auto" one of the previous, what works best1175 1176 Extra values that can be combined with the ones above are:1177 "breaksymlink" always break symlinks when writing1178 "breakhardlink" always break hardlinks when writing1179 1180 Making a copy and overwriting the original file:1181 - Takes extra time to copy the file.1182 + When the file has special attributes, is a (hard/symbolic) link or1183 has a resource fork, all this is preserved.1184 - When the file is a link the backup will have the name of the link,1185 not of the real file.1186 1187 Renaming the file and writing a new one:1188 + It's fast.1189 - Sometimes not all attributes of the file can be copied to the new1190 file.1191 - When the file is a link the new file will not be a link.1192 1193 The "auto" value is the middle way: When Vim sees that renaming the1194 file is possible without side effects (the attributes can be passed on1195 and the file is not a link) that is used. When problems are expected,1196 a copy will be made.1197 1198 The "breaksymlink" and "breakhardlink" values can be used in1199 combination with any of "yes", "no" and "auto". When included, they1200 force Vim to always break either symbolic or hard links by doing