blob: 9fa2bfb3ad07f1a0f0cfef72b91d956b332a785f [file] [log] [blame]
Bram Moolenaar8fe10002019-09-11 22:56:44 +02001*options.txt* For Vim version 8.1. Last change: 2019 Sep 09
Bram Moolenaar071d4272004-06-13 20:20:40 +00002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
7Options *options*
8
91. Setting options |set-option|
102. Automatically setting options |auto-setting|
113. Options summary |option-summary|
12
Bram Moolenaar2ec618c2016-10-01 14:47:05 +020013For an overview of options see quickref.txt |option-list|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000014
15Vim has a number of internal variables and switches which can be set to
16achieve special effects. These options come in three forms:
17 boolean can only be on or off *boolean* *toggle*
18 number has a numeric value
19 string has a string value
20
21==============================================================================
Bram Moolenaarf75a9632005-09-13 21:20:47 +0000221. Setting options *set-option* *E764*
Bram Moolenaar071d4272004-06-13 20:20:40 +000023
24 *:se* *:set*
25:se[t] Show all options that differ from their default value.
26
27:se[t] all Show all but terminal options.
28
29:se[t] termcap Show all terminal options. Note that in the GUI the
30 key codes are not shown, because they are generated
31 internally and can't be changed. Changing the terminal
32 codes in the GUI is not useful either...
33
34 *E518* *E519*
35:se[t] {option}? Show value of {option}.
36
37:se[t] {option} Toggle option: set, switch it on.
38 Number option: show value.
39 String option: show value.
40
41:se[t] no{option} Toggle option: Reset, switch it off.
42
Bram Moolenaar00a927d2010-05-14 23:24:24 +020043 *:set-!* *:set-inv*
Bram Moolenaar071d4272004-06-13 20:20:40 +000044:se[t] {option}! or
Bram Moolenaar6c60f472019-04-28 16:00:35 +020045:se[t] inv{option} Toggle option: Invert value.
Bram Moolenaar071d4272004-06-13 20:20:40 +000046
47 *:set-default* *:set-&* *:set-&vi* *:set-&vim*
48:se[t] {option}& Reset option to its default value. May depend on the
Bram Moolenaar6c60f472019-04-28 16:00:35 +020049 current value of 'compatible'.
50:se[t] {option}&vi Reset option to its Vi default value.
51:se[t] {option}&vim Reset option to its Vim default value.
Bram Moolenaar071d4272004-06-13 20:20:40 +000052
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +010053:se[t] all& Set all options to their default value. The values of
Bram Moolenaar88774fd2015-08-25 19:52:04 +020054 these options are not changed:
55 all terminal options, starting with t_
56 'columns'
57 'cryptmethod'
58 'encoding'
59 'key'
60 'lines'
61 'term'
62 'ttymouse'
63 'ttytype'
64 Warning: This may have a lot of side effects.
Bram Moolenaar071d4272004-06-13 20:20:40 +000065
66 *:set-args* *E487* *E521*
67:se[t] {option}={value} or
68:se[t] {option}:{value}
69 Set string or number option to {value}.
70 For numeric options the value can be given in decimal,
Bram Moolenaar3848e002016-03-19 18:42:29 +010071 hex (preceded with 0x) or octal (preceded with '0').
Bram Moolenaar071d4272004-06-13 20:20:40 +000072 The old value can be inserted by typing 'wildchar' (by
73 default this is a <Tab> or CTRL-E if 'compatible' is
74 set). See |cmdline-completion|.
75 White space between {option} and '=' is allowed and
76 will be ignored. White space between '=' and {value}
77 is not allowed.
78 See |option-backslash| for using white space and
79 backslashes in {value}.
80
81:se[t] {option}+={value} *:set+=*
82 Add the {value} to a number option, or append the
83 {value} to a string option. When the option is a
84 comma separated list, a comma is added, unless the
85 value was empty.
86 If the option is a list of flags, superfluous flags
Bram Moolenaara5792f52005-11-23 21:25:05 +000087 are removed. When adding a flag that was already
88 present the option value doesn't change.
Bram Moolenaar899dddf2006-03-26 21:06:50 +000089 Also see |:set-args| above.
Bram Moolenaar071d4272004-06-13 20:20:40 +000090
91:se[t] {option}^={value} *:set^=*
92 Multiply the {value} to a number option, or prepend
93 the {value} to a string option. When the option is a
94 comma separated list, a comma is added, unless the
95 value was empty.
96 Also see |:set-args| above.
Bram Moolenaar071d4272004-06-13 20:20:40 +000097
98:se[t] {option}-={value} *:set-=*
99 Subtract the {value} from a number option, or remove
100 the {value} from a string option, if it is there.
101 If the {value} is not found in a string option, there
102 is no error or warning. When the option is a comma
103 separated list, a comma is deleted, unless the option
104 becomes empty.
105 When the option is a list of flags, {value} must be
106 exactly as they appear in the option. Remove flags
107 one by one to avoid problems.
108 Also see |:set-args| above.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000109
110The {option} arguments to ":set" may be repeated. For example: >
111 :set ai nosi sw=3 ts=3
112If you make an error in one of the arguments, an error message will be given
113and the following arguments will be ignored.
114
115 *:set-verbose*
116When 'verbose' is non-zero, displaying an option value will also tell where it
117was last set. Example: >
118 :verbose set shiftwidth cindent?
Bram Moolenaar95bafa22018-10-02 13:26:25 +0200119< shiftwidth=4 ~
120 Last set from modeline line 1 ~
121 cindent ~
122 Last set from /usr/local/share/vim/vim60/ftplugin/c.vim line 30 ~
Bram Moolenaar446cb832008-06-24 21:56:24 +0000123This is only done when specific option values are requested, not for ":verbose
124set all" or ":verbose set" without an argument.
125When the option was set by hand there is no "Last set" message.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000126When the option was set while executing a function, user command or
127autocommand, the script in which it was defined is reported.
128Note that an option may also have been set as a side effect of setting
129'compatible'.
Bram Moolenaar446cb832008-06-24 21:56:24 +0000130A few special texts:
Bram Moolenaar95bafa22018-10-02 13:26:25 +0200131 Last set from modeline line 1 ~
Bram Moolenaar446cb832008-06-24 21:56:24 +0000132 Option was set in a |modeline|.
133 Last set from --cmd argument ~
134 Option was set with command line argument |--cmd| or +.
135 Last set from -c argument ~
136 Option was set with command line argument |-c|, +, |-S| or
137 |-q|.
138 Last set from environment variable ~
139 Option was set from an environment variable, $VIMINIT,
140 $GVIMINIT or $EXINIT.
141 Last set from error handler ~
142 Option was cleared when evaluating it resulted in an error.
143
Bram Moolenaardb84e452010-08-15 13:50:43 +0200144{not available when compiled without the |+eval| feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +0000145
146 *:set-termcap* *E522*
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +0000147For {option} the form "t_xx" may be used to set a terminal option. This will
Bram Moolenaar071d4272004-06-13 20:20:40 +0000148override the value from the termcap. You can then use it in a mapping. If
149the "xx" part contains special characters, use the <t_xx> form: >
150 :set <t_#4>=^[Ot
151This can also be used to translate a special code for a normal key. For
152example, if Alt-b produces <Esc>b, use this: >
153 :set <M-b>=^[b
154(the ^[ is a real <Esc> here, use CTRL-V <Esc> to enter it)
155The advantage over a mapping is that it works in all situations.
156
Bram Moolenaar0b2f94d2011-03-22 14:35:05 +0100157You can define any key codes, e.g.: >
158 :set t_xy=^[foo;
159There is no warning for using a name that isn't recognized. You can map these
160codes as you like: >
161 :map <t_xy> something
162< *E846*
163When a key code is not set, it's like it does not exist. Trying to get its
164value will result in an error: >
165 :set t_kb=
166 :set t_kb
167 E846: Key code not set: t_kb
168
Bram Moolenaar293ee4d2004-12-09 21:34:53 +0000169The t_xx options cannot be set from a |modeline| or in the |sandbox|, for
170security reasons.
171
Bram Moolenaar071d4272004-06-13 20:20:40 +0000172The listing from ":set" looks different from Vi. Long string options are put
Bram Moolenaarf4b8e572004-06-24 15:53:16 +0000173at the end of the list. The number of options is quite large. The output of
Bram Moolenaar071d4272004-06-13 20:20:40 +0000174"set all" probably does not fit on the screen, causing Vim to give the
175|more-prompt|.
176
177 *option-backslash*
178To include white space in a string option value it has to be preceded with a
179backslash. To include a backslash you have to use two. Effectively this
180means that the number of backslashes in an option value is halved (rounded
181down).
182A few examples: >
183 :set tags=tags\ /usr/tags results in "tags /usr/tags"
184 :set tags=tags\\,file results in "tags\,file"
185 :set tags=tags\\\ file results in "tags\ file"
186
Bram Moolenaarf4b8e572004-06-24 15:53:16 +0000187The "|" character separates a ":set" command from a following command. To
188include the "|" in the option value, use "\|" instead. This example sets the
Bram Moolenaar071d4272004-06-13 20:20:40 +0000189'titlestring' option to "hi|there": >
190 :set titlestring=hi\|there
191This sets the 'titlestring' option to "hi" and 'iconstring' to "there": >
192 :set titlestring=hi|set iconstring=there
193
Bram Moolenaar7df351e2006-01-23 22:30:28 +0000194Similarly, the double quote character starts a comment. To include the '"' in
195the option value, use '\"' instead. This example sets the 'titlestring'
196option to 'hi "there"': >
197 :set titlestring=hi\ \"there\"
198
Bram Moolenaarf4b8e572004-06-24 15:53:16 +0000199For MS-DOS and WIN32 backslashes in file names are mostly not removed. More
Bram Moolenaar071d4272004-06-13 20:20:40 +0000200precise: For options that expect a file name (those where environment
201variables are expanded) a backslash before a normal file name character is not
202removed. But a backslash before a special character (space, backslash, comma,
203etc.) is used like explained above.
204There is one special situation, when the value starts with "\\": >
205 :set dir=\\machine\path results in "\\machine\path"
206 :set dir=\\\\machine\\path results in "\\machine\path"
207 :set dir=\\path\\file results in "\\path\file" (wrong!)
208For the first one the start is kept, but for the second one the backslashes
209are halved. This makes sure it works both when you expect backslashes to be
Bram Moolenaarf4b8e572004-06-24 15:53:16 +0000210halved and when you expect the backslashes to be kept. The third gives a
Bram Moolenaar071d4272004-06-13 20:20:40 +0000211result which is probably not what you want. Avoid it.
212
213 *add-option-flags* *remove-option-flags*
214 *E539* *E550* *E551* *E552*
215Some options are a list of flags. When you want to add a flag to such an
216option, without changing the existing ones, you can do it like this: >
217 :set guioptions+=a
218Remove a flag from an option like this: >
219 :set guioptions-=a
220This removes the 'a' flag from 'guioptions'.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +0000221Note that you should add or remove one flag at a time. If 'guioptions' has
Bram Moolenaar071d4272004-06-13 20:20:40 +0000222the value "ab", using "set guioptions-=ba" won't work, because the string "ba"
223doesn't appear.
224
225 *:set_env* *expand-env* *expand-environment-var*
Bram Moolenaard4755bb2004-09-02 19:12:26 +0000226Environment variables in specific string options will be expanded. If the
Bram Moolenaar071d4272004-06-13 20:20:40 +0000227environment variable exists the '$' and the following environment variable
228name is replaced with its value. If it does not exist the '$' and the name
229are not modified. Any non-id character (not a letter, digit or '_') may
230follow the environment variable name. That character and what follows is
231appended to the value of the environment variable. Examples: >
232 :set term=$TERM.new
233 :set path=/usr/$INCLUDE,$HOME/include,.
234When adding or removing a string from an option with ":set opt-=val" or ":set
235opt+=val" the expansion is done before the adding or removing.
236
237
238Handling of local options *local-options*
239
240Some of the options only apply to a window or buffer. Each window or buffer
Bram Moolenaar51628222016-12-01 23:03:28 +0100241has its own copy of this option, thus each can have its own value. This
Bram Moolenaar071d4272004-06-13 20:20:40 +0000242allows you to set 'list' in one window but not in another. And set
243'shiftwidth' to 3 in one buffer and 4 in another.
244
245The following explains what happens to these local options in specific
246situations. You don't really need to know all of this, since Vim mostly uses
247the option values you would expect. Unfortunately, doing what the user
248expects is a bit complicated...
249
250When splitting a window, the local options are copied to the new window. Thus
251right after the split the contents of the two windows look the same.
252
253When editing a new buffer, its local option values must be initialized. Since
254the local options of the current buffer might be specifically for that buffer,
255these are not used. Instead, for each buffer-local option there also is a
256global value, which is used for new buffers. With ":set" both the local and
257global value is changed. With "setlocal" only the local value is changed,
258thus this value is not used when editing a new buffer.
259
Bram Moolenaar95ec9d62016-08-12 18:29:59 +0200260When editing a buffer that has been edited before, the options from the window
261that was last closed are used again. If this buffer has been edited in this
262window, the values from back then are used. Otherwise the values from the
263last closed window where the buffer was edited last are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000264
265It's possible to set a local window option specifically for a type of buffer.
266When you edit another buffer in the same window, you don't want to keep
267using these local window options. Therefore Vim keeps a global value of the
268local window options, which is used when editing another buffer. Each window
269has its own copy of these values. Thus these are local to the window, but
270global to all buffers in the window. With this you can do: >
271 :e one
272 :set list
273 :e two
274Now the 'list' option will also be set in "two", since with the ":set list"
275command you have also set the global value. >
276 :set nolist
277 :e one
278 :setlocal list
279 :e two
280Now the 'list' option is not set, because ":set nolist" resets the global
281value, ":setlocal list" only changes the local value and ":e two" gets the
282global value. Note that if you do this next: >
283 :e one
Bram Moolenaar531da592013-05-06 05:58:55 +0200284You will get back the 'list' value as it was the last time you edited "one".
285The options local to a window are remembered for each buffer. This also
286happens when the buffer is not loaded, but they are lost when the buffer is
287wiped out |:bwipe|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000288
289 *:setl* *:setlocal*
290:setl[ocal] ... Like ":set" but set only the value local to the
291 current buffer or window. Not all options have a
292 local value. If the option does not have a local
293 value the global value is set.
Bram Moolenaarc3301872010-07-25 20:53:06 +0200294 With the "all" argument: display local values for all
295 local options.
296 Without argument: Display local values for all local
297 options which are different from the default.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000298 When displaying a specific local option, show the
Bram Moolenaar446cb832008-06-24 21:56:24 +0000299 local value. For a global/local boolean option, when
300 the global value is being used, "--" is displayed
301 before the option name.
302 For a global option the global value is
Bram Moolenaar071d4272004-06-13 20:20:40 +0000303 shown (but that might change in the future).
Bram Moolenaar071d4272004-06-13 20:20:40 +0000304
Bram Moolenaar899dddf2006-03-26 21:06:50 +0000305:setl[ocal] {option}< Set the local value of {option} to its global value by
306 copying the value.
Bram Moolenaar899dddf2006-03-26 21:06:50 +0000307
Bram Moolenaar6be7f872012-01-20 21:08:56 +0100308:se[t] {option}< For |global-local| options: Remove the local value of
309 {option}, so that the global value will be used.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000310
311 *:setg* *:setglobal*
312:setg[lobal] ... Like ":set" but set only the global value for a local
313 option without changing the local value.
314 When displaying an option, the global value is shown.
Bram Moolenaarc3301872010-07-25 20:53:06 +0200315 With the "all" argument: display global values for all
316 local options.
317 Without argument: display global values for all local
318 options which are different from the default.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000319
320For buffer-local and window-local options:
321 Command global value local value ~
322 :set option=value set set
323 :setlocal option=value - set
324:setglobal option=value set -
325 :set option? - display
326 :setlocal option? - display
327:setglobal option? display -
328
329
330Global options with a local value *global-local*
331
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +0000332Options are global when you mostly use one value for all buffers and windows.
333For some global options it's useful to sometimes have a different local value.
334You can set the local value with ":setlocal". That buffer or window will then
335use the local value, while other buffers and windows continue using the global
336value.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000337
338For example, you have two windows, both on C source code. They use the global
339'makeprg' option. If you do this in one of the two windows: >
340 :set makeprg=gmake
341then the other window will switch to the same value. There is no need to set
342the 'makeprg' option in the other C source window too.
343However, if you start editing a Perl file in a new window, you want to use
Bram Moolenaar02467872007-05-06 13:22:01 +0000344another 'makeprg' for it, without changing the value used for the C source
Bram Moolenaarf4b8e572004-06-24 15:53:16 +0000345files. You use this command: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000346 :setlocal makeprg=perlmake
347You can switch back to using the global value by making the local value empty: >
348 :setlocal makeprg=
Bram Moolenaar314dd792019-02-03 15:27:20 +0100349This only works for a string option. For a number or boolean option you need
350to use the "<" flag, like this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000351 :setlocal autoread<
Bram Moolenaar314dd792019-02-03 15:27:20 +0100352Note that for non-boolean and non-number options using "<" copies the global
353value to the local value, it doesn't switch back to using the global value
354(that matters when the global value changes later). You can also use: >
Bram Moolenaar899dddf2006-03-26 21:06:50 +0000355 :set path<
356This will make the local value of 'path' empty, so that the global value is
357used. Thus it does the same as: >
358 :setlocal path=
Bram Moolenaar071d4272004-06-13 20:20:40 +0000359Note: In the future more global options can be made global-local. Using
360":setlocal" on a global option might work differently then.
361
362
363Setting the filetype
364
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +0200365:setf[iletype] [FALLBACK] {filetype} *:setf* *:setfiletype*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000366 Set the 'filetype' option to {filetype}, but only if
367 not done yet in a sequence of (nested) autocommands.
368 This is short for: >
369 :if !did_filetype()
370 : setlocal filetype={filetype}
371 :endif
372< This command is used in a filetype.vim file to avoid
373 setting the 'filetype' option twice, causing different
374 settings and syntax files to be loaded.
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +0200375
376 When the optional FALLBACK argument is present, a
377 later :setfiletype command will override the
Bram Moolenaar26967612019-03-17 17:13:16 +0100378 'filetype'. This is to be used for filetype
379 detections that are just a guess. |did_filetype()|
380 will return false after this command.
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +0200381
Bram Moolenaard58e9292011-02-09 17:07:58 +0100382 *option-window* *optwin*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000383:bro[wse] se[t] *:set-browse* *:browse-set* *:opt* *:options*
384:opt[ions] Open a window for viewing and setting all options.
385 Options are grouped by function.
386 Offers short help for each option. Hit <CR> on the
387 short help to open a help window with more help for
388 the option.
389 Modify the value of the option and hit <CR> on the
390 "set" line to set the new value. For window and
391 buffer specific options, the last accessed window is
392 used to set the option value in, unless this is a help
393 window, in which case the window below help window is
394 used (skipping the option-window).
Bram Moolenaarb5b75622018-03-09 22:22:21 +0100395 {not available when compiled without the |+eval|
396 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +0000397
398 *$HOME*
399Using "~" is like using "$HOME", but it is only recognized at the start of an
400option and after a space or comma.
401
402On Unix systems "~user" can be used too. It is replaced by the home directory
403of user "user". Example: >
404 :set path=~mool/include,/usr/include,.
405
406On Unix systems the form "${HOME}" can be used too. The name between {} can
407contain non-id characters then. Note that if you want to use this for the
408"gf" command, you need to add the '{' and '}' characters to 'isfname'.
409
410NOTE: expanding environment variables and "~/" is only done with the ":set"
411command, not when assigning a value to an option with ":let".
412
Bram Moolenaarc572da52017-08-27 16:52:01 +0200413 *$HOME-windows*
414On MS-Windows, if $HOME is not defined as an environment variable, then
415at runtime Vim will set it to the expansion of $HOMEDRIVE$HOMEPATH.
Bram Moolenaar37c64c72017-09-19 22:06:03 +0200416If $HOMEDRIVE is not set then $USERPROFILE is used.
417
418This expanded value is not exported to the environment, this matters when
419running an external command: >
420 :echo system('set | findstr ^HOME=')
421and >
422 :echo luaeval('os.getenv("HOME")')
423should echo nothing (an empty string) despite exists('$HOME') being true.
424When setting $HOME to a non-empty string it will be exported to the
425subprocesses.
Bram Moolenaarc572da52017-08-27 16:52:01 +0200426
Bram Moolenaar071d4272004-06-13 20:20:40 +0000427
428Note the maximum length of an expanded option is limited. How much depends on
429the system, mostly it is something like 256 or 1024 characters.
430
431 *:fix* *:fixdel*
432:fix[del] Set the value of 't_kD':
433 't_kb' is 't_kD' becomes ~
434 CTRL-? CTRL-H
435 not CTRL-? CTRL-?
436
Bram Moolenaar6c60f472019-04-28 16:00:35 +0200437 (CTRL-? is 0177 octal, 0x7f hex)
Bram Moolenaar071d4272004-06-13 20:20:40 +0000438
439 If your delete key terminal code is wrong, but the
440 code for backspace is alright, you can put this in
441 your .vimrc: >
442 :fixdel
443< This works no matter what the actual code for
444 backspace is.
445
446 If the backspace key terminal code is wrong you can
447 use this: >
448 :if &term == "termname"
449 : set t_kb=^V<BS>
450 : fixdel
451 :endif
452< Where "^V" is CTRL-V and "<BS>" is the backspace key
Bram Moolenaarf4b8e572004-06-24 15:53:16 +0000453 (don't type four characters!). Replace "termname"
Bram Moolenaar071d4272004-06-13 20:20:40 +0000454 with your terminal name.
455
456 If your <Delete> key sends a strange key sequence (not
457 CTRL-? or CTRL-H) you cannot use ":fixdel". Then use: >
458 :if &term == "termname"
459 : set t_kD=^V<Delete>
460 :endif
461< Where "^V" is CTRL-V and "<Delete>" is the delete key
462 (don't type eight characters!). Replace "termname"
463 with your terminal name.
464
465 *Linux-backspace*
466 Note about Linux: By default the backspace key
467 produces CTRL-?, which is wrong. You can fix it by
468 putting this line in your rc.local: >
469 echo "keycode 14 = BackSpace" | loadkeys
470<
471 *NetBSD-backspace*
472 Note about NetBSD: If your backspace doesn't produce
473 the right code, try this: >
474 xmodmap -e "keycode 22 = BackSpace"
475< If this works, add this in your .Xmodmap file: >
476 keysym 22 = BackSpace
477< You need to restart for this to take effect.
478
479==============================================================================
4802. Automatically setting options *auto-setting*
481
482Besides changing options with the ":set" command, there are three alternatives
483to set options automatically for one or more files:
484
4851. When starting Vim initializations are read from various places. See
486 |initialization|. Most of them are performed for all editing sessions,
487 and some of them depend on the directory where Vim is started.
488 You can create an initialization file with |:mkvimrc|, |:mkview| and
489 |:mksession|.
4902. If you start editing a new file, the automatic commands are executed.
491 This can be used to set options for files matching a particular pattern and
492 many other things. See |autocommand|.
4933. If you start editing a new file, and the 'modeline' option is on, a
494 number of lines at the beginning and end of the file are checked for
495 modelines. This is explained here.
496
497 *modeline* *vim:* *vi:* *ex:* *E520*
498There are two forms of modelines. The first form:
Bram Moolenaar14b69452013-06-29 23:05:20 +0200499 [text]{white}{vi:|vim:|ex:}[white]{options}
Bram Moolenaar071d4272004-06-13 20:20:40 +0000500
Bram Moolenaar22dbc772013-06-28 18:44:48 +0200501[text] any text or empty
502{white} at least one blank character (<Space> or <Tab>)
Bram Moolenaar14b69452013-06-29 23:05:20 +0200503{vi:|vim:|ex:} the string "vi:", "vim:" or "ex:"
Bram Moolenaar22dbc772013-06-28 18:44:48 +0200504[white] optional white space
505{options} a list of option settings, separated with white space
506 or ':', where each part between ':' is the argument
507 for a ":set" command (can be empty)
Bram Moolenaar071d4272004-06-13 20:20:40 +0000508
Bram Moolenaar14b69452013-06-29 23:05:20 +0200509Examples:
Bram Moolenaar97b2ad32006-03-18 21:40:56 +0000510 vi:noai:sw=3 ts=6 ~
Bram Moolenaar14b69452013-06-29 23:05:20 +0200511 vim: tw=77 ~
Bram Moolenaar071d4272004-06-13 20:20:40 +0000512
513The second form (this is compatible with some versions of Vi):
514
Bram Moolenaar22dbc772013-06-28 18:44:48 +0200515 [text]{white}{vi:|vim:|Vim:|ex:}[white]se[t] {options}:[text]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000516
Bram Moolenaar22dbc772013-06-28 18:44:48 +0200517[text] any text or empty
518{white} at least one blank character (<Space> or <Tab>)
519{vi:|vim:|Vim:|ex:} the string "vi:", "vim:", "Vim:" or "ex:"
520[white] optional white space
Bram Moolenaar14b69452013-06-29 23:05:20 +0200521se[t] the string "set " or "se " (note the space); When
522 "Vim" is used it must be "set".
Bram Moolenaar22dbc772013-06-28 18:44:48 +0200523{options} a list of options, separated with white space, which
524 is the argument for a ":set" command
525: a colon
526[text] any text or empty
Bram Moolenaar071d4272004-06-13 20:20:40 +0000527
Bram Moolenaar14b69452013-06-29 23:05:20 +0200528Examples:
Bram Moolenaar97b2ad32006-03-18 21:40:56 +0000529 /* vim: set ai tw=75: */ ~
Bram Moolenaar14b69452013-06-29 23:05:20 +0200530 /* Vim: set ai tw=75: */ ~
Bram Moolenaar071d4272004-06-13 20:20:40 +0000531
Bram Moolenaar22dbc772013-06-28 18:44:48 +0200532The white space before {vi:|vim:|Vim:|ex:} is required. This minimizes the
533chance that a normal word like "lex:" is caught. There is one exception:
534"vi:" and "vim:" can also be at the start of the line (for compatibility with
535version 3.0). Using "ex:" at the start of the line will be ignored (this
536could be short for "example:").
Bram Moolenaar071d4272004-06-13 20:20:40 +0000537
538 *modeline-local*
539The options are set like with ":setlocal": The new value only applies to the
Bram Moolenaar843ee412004-06-30 16:16:41 +0000540buffer and window that contain the file. Although it's possible to set global
541options from a modeline, this is unusual. If you have two windows open and
542the files in it set the same global option to a different value, the result
543depends on which one was opened last.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000544
Bram Moolenaar15d0a8c2004-09-06 17:44:46 +0000545When editing a file that was already loaded, only the window-local options
546from the modeline are used. Thus if you manually changed a buffer-local
547option after opening the file, it won't be changed if you edit the same buffer
548in another window. But window-local options will be set.
549
Bram Moolenaar071d4272004-06-13 20:20:40 +0000550 *modeline-version*
551If the modeline is only to be used for some versions of Vim, the version
Bram Moolenaar22dbc772013-06-28 18:44:48 +0200552number can be specified where "vim:" or "Vim:" is used:
Bram Moolenaar071d4272004-06-13 20:20:40 +0000553 vim{vers}: version {vers} or later
554 vim<{vers}: version before {vers}
555 vim={vers}: version {vers}
556 vim>{vers}: version after {vers}
Bram Moolenaar2b8388b2015-02-28 13:11:45 +0100557{vers} is 700 for Vim 7.0 (hundred times the major version plus minor).
558For example, to use a modeline only for Vim 7.0:
559 /* vim700: set foldmethod=marker */ ~
560To use a modeline for Vim after version 7.2:
561 /* vim>702: set cole=2: */ ~
Bram Moolenaar071d4272004-06-13 20:20:40 +0000562There can be no blanks between "vim" and the ":".
563
564
565The number of lines that are checked can be set with the 'modelines' option.
566If 'modeline' is off or 'modelines' is 0 no lines are checked.
567
568Note that for the first form all of the rest of the line is used, thus a line
Bram Moolenaar97b2ad32006-03-18 21:40:56 +0000569like:
570 /* vi:ts=4: */ ~
571will give an error message for the trailing "*/". This line is OK:
572 /* vi:set ts=4: */ ~
Bram Moolenaar071d4272004-06-13 20:20:40 +0000573
574If an error is detected the rest of the line is skipped.
575
576If you want to include a ':' in a set command precede it with a '\'. The
Bram Moolenaar97b2ad32006-03-18 21:40:56 +0000577backslash in front of the ':' will be removed. Example:
578 /* vi:set dir=c\:\tmp: */ ~
Bram Moolenaar071d4272004-06-13 20:20:40 +0000579This sets the 'dir' option to "c:\tmp". Only a single backslash before the
580':' is removed. Thus to include "\:" you have to specify "\\:".
Bram Moolenaar110289e2019-05-23 15:38:06 +0200581 *E992*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000582No other commands than "set" are supported, for security reasons (somebody
Bram Moolenaar8243a792007-05-01 17:05:03 +0000583might create a Trojan horse text file with modelines). And not all options
Bram Moolenaar110289e2019-05-23 15:38:06 +0200584can be set. For some options a flag is set, so that when the value is used
585the |sandbox| is effective. Some options can only be set from the modeline
586when 'modelineexpr' is set (the default is off).
587
588Still, there is always a small risk that a modeline causes trouble. E.g.,
589when some joker sets 'textwidth' to 5 all your lines are wrapped unexpectedly.
590So disable modelines before editing untrusted text. The mail ftplugin does
591this, for example.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000592
593Hint: If you would like to do something else than setting an option, you could
594define an autocommand that checks the file for a specific string. For
595example: >
596 au BufReadPost * if getline(1) =~ "VAR" | call SetVar() | endif
597And define a function SetVar() that does something with the line containing
598"VAR".
599
600==============================================================================
6013. Options summary *option-summary*
602
603In the list below all the options are mentioned with their full name and with
604an abbreviation if there is one. Both forms may be used.
605
606In this document when a boolean option is "set" that means that ":set option"
607is entered. When an option is "reset", ":set nooption" is used.
608
609For some options there are two default values: The "Vim default", which is
610used when 'compatible' is not set, and the "Vi default", which is used when
611'compatible' is set.
612
613Most options are the same in all windows and buffers. There are a few that
Bram Moolenaarf4b8e572004-06-24 15:53:16 +0000614are specific to how the text is presented in a window. These can be set to a
Bram Moolenaar071d4272004-06-13 20:20:40 +0000615different value in each window. For example the 'list' option can be set in
616one window and reset in another for the same text, giving both types of view
617at the same time. There are a few options that are specific to a certain
618file. These can have a different value for each file or buffer. For example
619the 'textwidth' option can be 78 for a normal text file and 0 for a C
620program.
621
622 global one option for all buffers and windows
623 local to window each window has its own copy of this option
624 local to buffer each buffer has its own copy of this option
625
626When creating a new window the option values from the currently active window
627are used as a default value for the window-specific options. For the
628buffer-specific options this depends on the 's' and 'S' flags in the
629'cpoptions' option. If 's' is included (which is the default) the values for
630buffer options are copied from the currently active buffer when a buffer is
Bram Moolenaarf4b8e572004-06-24 15:53:16 +0000631first entered. If 'S' is present the options are copied each time the buffer
632is entered, this is almost like having global options. If 's' and 'S' are not
Bram Moolenaar071d4272004-06-13 20:20:40 +0000633present, the options are copied from the currently active buffer when the
634buffer is created.
635
Bram Moolenaar578b49e2005-09-10 19:22:57 +0000636Hidden options *hidden-options*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000637
Bram Moolenaar578b49e2005-09-10 19:22:57 +0000638Not all options are supported in all versions. This depends on the supported
639features and sometimes on the system. A remark about this is in curly braces
640below. When an option is not supported it may still be set without getting an
641error, this is called a hidden option. You can't get the value of a hidden
642option though, it is not stored.
643
644To test if option "foo" can be used with ":set" use something like this: >
645 if exists('&foo')
646This also returns true for a hidden option. To test if option "foo" is really
647supported use something like this: >
648 if exists('+foo')
649<
Bram Moolenaar071d4272004-06-13 20:20:40 +0000650 *E355*
651A jump table for the options with a short description can be found at |Q_op|.
652
653 *'aleph'* *'al'* *aleph* *Aleph*
654'aleph' 'al' number (default 128 for MS-DOS, 224 otherwise)
655 global
Bram Moolenaar071d4272004-06-13 20:20:40 +0000656 {only available when compiled with the |+rightleft|
657 feature}
658 The ASCII code for the first letter of the Hebrew alphabet. The
659 routine that maps the keyboard in Hebrew mode, both in Insert mode
660 (when hkmap is set) and on the command-line (when hitting CTRL-_)
661 outputs the Hebrew characters in the range [aleph..aleph+26].
662 aleph=128 applies to PC code, and aleph=224 applies to ISO 8859-8.
663 See |rileft.txt|.
664
665 *'allowrevins'* *'ari'* *'noallowrevins'* *'noari'*
666'allowrevins' 'ari' boolean (default off)
667 global
Bram Moolenaar071d4272004-06-13 20:20:40 +0000668 {only available when compiled with the |+rightleft|
669 feature}
670 Allow CTRL-_ in Insert and Command-line mode. This is default off, to
671 avoid that users that accidentally type CTRL-_ instead of SHIFT-_ get
672 into reverse Insert mode, and don't know how to get out. See
673 'revins'.
674 NOTE: This option is reset when 'compatible' is set.
675
676 *'altkeymap'* *'akm'* *'noaltkeymap'* *'noakm'*
677'altkeymap' 'akm' boolean (default off)
678 global
Bram Moolenaar071d4272004-06-13 20:20:40 +0000679 {only available when compiled with the |+farsi|
680 feature}
Bram Moolenaar14184a32019-02-16 15:10:30 +0100681 This option was for using Farsi, which has been removed. See
682 |farsi.txt|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000683
684 *'ambiwidth'* *'ambw'*
685'ambiwidth' 'ambw' string (default: "single")
686 global
Bram Moolenaar071d4272004-06-13 20:20:40 +0000687 Only effective when 'encoding' is "utf-8" or another Unicode encoding.
688 Tells Vim what to do with characters with East Asian Width Class
689 Ambiguous (such as Euro, Registered Sign, Copyright Sign, Greek
690 letters, Cyrillic letters).
691
692 There are currently two possible values:
Bram Moolenaar582fd852005-03-28 20:58:01 +0000693 "single": Use the same width as characters in US-ASCII. This is
Bram Moolenaar071d4272004-06-13 20:20:40 +0000694 expected by most users.
695 "double": Use twice the width of ASCII characters.
Bram Moolenaar5c3bd0a2010-08-04 20:55:44 +0200696 *E834* *E835*
697 The value "double" cannot be used if 'listchars' or 'fillchars'
698 contains a character that would be double width.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000699
700 There are a number of CJK fonts for which the width of glyphs for
701 those characters are solely based on how many octets they take in
702 legacy/traditional CJK encodings. In those encodings, Euro,
703 Registered sign, Greek/Cyrillic letters are represented by two octets,
Bram Moolenaar582fd852005-03-28 20:58:01 +0000704 therefore those fonts have "wide" glyphs for them. This is also
Bram Moolenaar071d4272004-06-13 20:20:40 +0000705 true of some line drawing characters used to make tables in text
Bram Moolenaar582fd852005-03-28 20:58:01 +0000706 file. Therefore, when a CJK font is used for GUI Vim or
Bram Moolenaar071d4272004-06-13 20:20:40 +0000707 Vim is running inside a terminal (emulators) that uses a CJK font
708 (or Vim is run inside an xterm invoked with "-cjkwidth" option.),
709 this option should be set to "double" to match the width perceived
710 by Vim with the width of glyphs in the font. Perhaps it also has
711 to be set to "double" under CJK Windows 9x/ME or Windows 2k/XP
712 when the system locale is set to one of CJK locales. See Unicode
713 Standard Annex #11 (http://www.unicode.org/reports/tr11).
714
Bram Moolenaarac7bd632013-03-19 11:35:58 +0100715 Vim may set this option automatically at startup time when Vim is
716 compiled with the |+termresponse| feature and if |t_u7| is set to the
Bram Moolenaar37c64c72017-09-19 22:06:03 +0200717 escape sequence to request cursor position report. The response can
718 be found in |v:termu7resp|.
Bram Moolenaarac7bd632013-03-19 11:35:58 +0100719
Bram Moolenaar071d4272004-06-13 20:20:40 +0000720 *'antialias'* *'anti'* *'noantialias'* *'noanti'*
721'antialias' 'anti' boolean (default: off)
722 global
Bram Moolenaar071d4272004-06-13 20:20:40 +0000723 {only available when compiled with GUI enabled
724 on Mac OS X}
725 This option only has an effect in the GUI version of Vim on Mac OS X
726 v10.2 or later. When on, Vim will use smooth ("antialiased") fonts,
727 which can be easier to read at certain sizes on certain displays.
728 Setting this option can sometimes cause problems if 'guifont' is set
729 to its default (empty string).
Bram Moolenaar036986f2017-03-16 17:41:02 +0100730 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000731
732 *'autochdir'* *'acd'* *'noautochdir'* *'noacd'*
733'autochdir' 'acd' boolean (default off)
734 global
Bram Moolenaar00a927d2010-05-14 23:24:24 +0200735 {only available when compiled with it, use
736 exists("+autochdir") to check}
Bram Moolenaard8c00872005-07-22 21:52:15 +0000737 When on, Vim will change the current working directory whenever you
738 open a file, switch buffers, delete a buffer or open/close a window.
739 It will change to the directory containing the file which was opened
740 or selected.
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000741 Note: When this option is on some plugins may not work.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000742
743 *'arabic'* *'arab'* *'noarabic'* *'noarab'*
744'arabic' 'arab' boolean (default off)
745 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +0000746 {only available when compiled with the |+arabic|
747 feature}
748 This option can be set to start editing Arabic text.
749 Setting this option will:
750 - Set the 'rightleft' option, unless 'termbidi' is set.
751 - Set the 'arabicshape' option, unless 'termbidi' is set.
752 - Set the 'keymap' option to "arabic"; in Insert mode CTRL-^ toggles
753 between typing English and Arabic key mapping.
754 - Set the 'delcombine' option
755 Note that 'encoding' must be "utf-8" for working with Arabic text.
756
757 Resetting this option will:
758 - Reset the 'rightleft' option.
759 - Disable the use of 'keymap' (without changing its value).
760 Note that 'arabicshape' and 'delcombine' are not reset (it is a global
Bram Moolenaarc8734422012-06-01 22:38:45 +0200761 option).
Bram Moolenaar036986f2017-03-16 17:41:02 +0100762 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000763 Also see |arabic.txt|.
764
765 *'arabicshape'* *'arshape'*
766 *'noarabicshape'* *'noarshape'*
767'arabicshape' 'arshape' boolean (default on)
768 global
Bram Moolenaar071d4272004-06-13 20:20:40 +0000769 {only available when compiled with the |+arabic|
770 feature}
771 When on and 'termbidi' is off, the required visual character
772 corrections that need to take place for displaying the Arabic language
Bram Moolenaar3a0d8092012-10-21 03:02:54 +0200773 take effect. Shaping, in essence, gets enabled; the term is a broad
Bram Moolenaar071d4272004-06-13 20:20:40 +0000774 one which encompasses:
775 a) the changing/morphing of characters based on their location
776 within a word (initial, medial, final and stand-alone).
777 b) the enabling of the ability to compose characters
778 c) the enabling of the required combining of some characters
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100779 When disabled the display shows each character's true stand-alone
780 form.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000781 Arabic is a complex language which requires other settings, for
782 further details see |arabic.txt|.
Bram Moolenaar036986f2017-03-16 17:41:02 +0100783 NOTE: This option is set when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000784
785 *'autoindent'* *'ai'* *'noautoindent'* *'noai'*
786'autoindent' 'ai' boolean (default off)
787 local to buffer
788 Copy indent from current line when starting a new line (typing <CR>
789 in Insert mode or when using the "o" or "O" command). If you do not
790 type anything on the new line except <BS> or CTRL-D and then type
Bram Moolenaar02467872007-05-06 13:22:01 +0000791 <Esc>, CTRL-O or <CR>, the indent is deleted again. Moving the cursor
792 to another line has the same effect, unless the 'I' flag is included
793 in 'cpoptions'.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +0000794 When autoindent is on, formatting (with the "gq" command or when you
795 reach 'textwidth' in Insert mode) uses the indentation of the first
796 line.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000797 When 'smartindent' or 'cindent' is on the indent is changed in
798 a different way.
Bram Moolenaarca635012015-09-25 20:34:21 +0200799 The 'autoindent' option is reset when the 'paste' option is set and
800 restored when 'paste' is reset.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000801
802 *'autoread'* *'ar'* *'noautoread'* *'noar'*
803'autoread' 'ar' boolean (default off)
804 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000805 When a file has been detected to have been changed outside of Vim and
806 it has not been changed inside of Vim, automatically read it again.
Bram Moolenaarfd358112018-07-07 23:21:31 +0200807 When the file has been deleted this is not done, so you have the text
808 from before it was deleted. When it appears again then it is read.
809 |timestamp|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000810 If this option has a local value, use this command to switch back to
811 using the global value: >
812 :set autoread<
813<
814 *'autowrite'* *'aw'* *'noautowrite'* *'noaw'*
815'autowrite' 'aw' boolean (default off)
816 global
817 Write the contents of the file, if it has been modified, on each
818 :next, :rewind, :last, :first, :previous, :stop, :suspend, :tag, :!,
Bram Moolenaar14716812006-05-04 21:54:08 +0000819 :make, CTRL-] and CTRL-^ command; and when a :buffer, CTRL-O, CTRL-I,
Bram Moolenaar071d4272004-06-13 20:20:40 +0000820 '{A-Z0-9}, or `{A-Z0-9} command takes one to another file.
821 Note that for some commands the 'autowrite' option is not used, see
822 'autowriteall' for that.
Bram Moolenaar93a1df22018-09-10 11:51:50 +0200823 Some buffers will not be written, specifically when 'buftype' is
Bram Moolenaar20aac6c2018-09-02 21:07:30 +0200824 "nowrite", "nofile", "terminal" or "prompt".
Bram Moolenaar071d4272004-06-13 20:20:40 +0000825
826 *'autowriteall'* *'awa'* *'noautowriteall'* *'noawa'*
827'autowriteall' 'awa' boolean (default off)
828 global
Bram Moolenaar071d4272004-06-13 20:20:40 +0000829 Like 'autowrite', but also used for commands ":edit", ":enew", ":quit",
830 ":qall", ":exit", ":xit", ":recover" and closing the Vim window.
831 Setting this option also implies that Vim behaves like 'autowrite' has
832 been set.
833
834 *'background'* *'bg'*
Bram Moolenaar446beb42011-05-10 17:18:44 +0200835'background' 'bg' string (default "dark" or "light", see below)
Bram Moolenaar071d4272004-06-13 20:20:40 +0000836 global
Bram Moolenaar071d4272004-06-13 20:20:40 +0000837 When set to "dark", Vim will try to use colors that look good on a
838 dark background. When set to "light", Vim will try to use colors that
839 look good on a light background. Any other value is illegal.
840 Vim tries to set the default value according to the terminal used.
841 This will not always be correct.
842 Setting this option does not change the background color, it tells Vim
843 what the background color looks like. For changing the background
844 color, see |:hi-normal|.
845
846 When 'background' is set Vim will adjust the default color groups for
Bram Moolenaarf4b8e572004-06-24 15:53:16 +0000847 the new value. But the colors used for syntax highlighting will not
Bram Moolenaar446cb832008-06-24 21:56:24 +0000848 change. *g:colors_name*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100849 When a color scheme is loaded (the "g:colors_name" variable is set)
Bram Moolenaar071d4272004-06-13 20:20:40 +0000850 setting 'background' will cause the color scheme to be reloaded. If
851 the color scheme adjusts to the value of 'background' this will work.
852 However, if the color scheme sets 'background' itself the effect may
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100853 be undone. First delete the "g:colors_name" variable when needed.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000854
855 When setting 'background' to the default value with: >
856 :set background&
857< Vim will guess the value. In the GUI this should work correctly,
858 in other cases Vim might not be able to guess the right value.
859
Bram Moolenaar37c64c72017-09-19 22:06:03 +0200860 When the |t_RB| option is set, Vim will use it to request the background
Bram Moolenaarb4d6c3e2017-05-27 16:45:17 +0200861 color from the terminal. If the returned RGB value is dark/light and
862 'background' is not dark/light, 'background' will be set and the
863 screen is redrawn. This may have side effects, make t_BG empty in
Bram Moolenaar37c64c72017-09-19 22:06:03 +0200864 your .vimrc if you suspect this problem. The response to |t_RB| can
Bram Moolenaar01164a62017-11-02 22:58:42 +0100865 be found in |v:termrbgresp|.
Bram Moolenaarb4d6c3e2017-05-27 16:45:17 +0200866
Bram Moolenaar071d4272004-06-13 20:20:40 +0000867 When starting the GUI, the default value for 'background' will be
868 "light". When the value is not set in the .gvimrc, and Vim detects
869 that the background is actually quite dark, 'background' is set to
870 "dark". But this happens only AFTER the .gvimrc file has been read
871 (because the window needs to be opened to find the actual background
872 color). To get around this, force the GUI window to be opened by
873 putting a ":gui" command in the .gvimrc file, before where the value
874 of 'background' is used (e.g., before ":syntax on").
Bram Moolenaar446beb42011-05-10 17:18:44 +0200875
876 For MS-DOS, Windows and OS/2 the default is "dark".
877 For other systems "dark" is used when 'term' is "linux",
878 "screen.linux", "cygwin" or "putty", or $COLORFGBG suggests a dark
879 background. Otherwise the default is "light".
880
Bram Moolenaarc572da52017-08-27 16:52:01 +0200881 The |:terminal| command and the |term_start()| function use the
882 'background' value to decide whether the terminal window will start
883 with a white or black background.
884
Bram Moolenaar071d4272004-06-13 20:20:40 +0000885 Normally this option would be set in the .vimrc file. Possibly
886 depending on the terminal name. Example: >
887 :if &term == "pcterm"
888 : set background=dark
889 :endif
890< When this option is set, the default settings for the highlight groups
891 will change. To use other settings, place ":highlight" commands AFTER
892 the setting of the 'background' option.
893 This option is also used in the "$VIMRUNTIME/syntax/syntax.vim" file
894 to select the colors for syntax highlighting. After changing this
895 option, you must load syntax.vim again to see the result. This can be
896 done with ":syntax on".
897
898 *'backspace'* *'bs'*
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +0200899'backspace' 'bs' string (default "", set to "indent,eol,start"
900 in |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +0000901 global
Bram Moolenaar071d4272004-06-13 20:20:40 +0000902 Influences the working of <BS>, <Del>, CTRL-W and CTRL-U in Insert
903 mode. This is a list of items, separated by commas. Each item allows
904 a way to backspace over something:
905 value effect ~
906 indent allow backspacing over autoindent
907 eol allow backspacing over line breaks (join lines)
908 start allow backspacing over the start of insert; CTRL-W and CTRL-U
909 stop once at the start of insert.
910
911 When the value is empty, Vi compatible backspacing is used.
912
913 For backwards compatibility with version 5.4 and earlier:
914 value effect ~
915 0 same as ":set backspace=" (Vi compatible)
916 1 same as ":set backspace=indent,eol"
917 2 same as ":set backspace=indent,eol,start"
918
919 See |:fixdel| if your <BS> or <Del> key does not do what you want.
920 NOTE: This option is set to "" when 'compatible' is set.
921
922 *'backup'* *'bk'* *'nobackup'* *'nobk'*
923'backup' 'bk' boolean (default off)
924 global
Bram Moolenaar071d4272004-06-13 20:20:40 +0000925 Make a backup before overwriting a file. Leave it around after the
926 file has been successfully written. If you do not want to keep the
927 backup file, but you do want a backup while the file is being
928 written, reset this option and set the 'writebackup' option (this is
929 the default). If you do not want a backup file at all reset both
Bram Moolenaarf4b8e572004-06-24 15:53:16 +0000930 options (use this if your file system is almost full). See the
Bram Moolenaar071d4272004-06-13 20:20:40 +0000931 |backup-table| for more explanations.
932 When the 'backupskip' pattern matches, a backup is not made anyway.
933 When 'patchmode' is set, the backup may be renamed to become the
934 oldest version of a file.
935 NOTE: This option is reset when 'compatible' is set.
936
937 *'backupcopy'* *'bkc'*
938'backupcopy' 'bkc' string (Vi default for Unix: "yes", otherwise: "auto")
Bram Moolenaarb8ee25a2014-09-23 15:45:08 +0200939 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000940 When writing a file and a backup is made, this option tells how it's
941 done. This is a comma separated list of words.
942
943 The main values are:
944 "yes" make a copy of the file and overwrite the original one
945 "no" rename the file and write a new one
946 "auto" one of the previous, what works best
947
948 Extra values that can be combined with the ones above are:
949 "breaksymlink" always break symlinks when writing
950 "breakhardlink" always break hardlinks when writing
951
952 Making a copy and overwriting the original file:
953 - Takes extra time to copy the file.
954 + When the file has special attributes, is a (hard/symbolic) link or
955 has a resource fork, all this is preserved.
956 - When the file is a link the backup will have the name of the link,
957 not of the real file.
958
959 Renaming the file and writing a new one:
960 + It's fast.
961 - Sometimes not all attributes of the file can be copied to the new
962 file.
963 - When the file is a link the new file will not be a link.
964
965 The "auto" value is the middle way: When Vim sees that renaming file
966 is possible without side effects (the attributes can be passed on and
Bram Moolenaar02467872007-05-06 13:22:01 +0000967 the file is not a link) that is used. When problems are expected, a
968 copy will be made.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000969
970 The "breaksymlink" and "breakhardlink" values can be used in
971 combination with any of "yes", "no" and "auto". When included, they
972 force Vim to always break either symbolic or hard links by doing
973 exactly what the "no" option does, renaming the original file to
974 become the backup and writing a new file in its place. This can be
975 useful for example in source trees where all the files are symbolic or
976 hard links and any changes should stay in the local source tree, not
977 be propagated back to the original source.
978 *crontab*
979 One situation where "no" and "auto" will cause problems: A program
980 that opens a file, invokes Vim to edit that file, and then tests if
981 the open file was changed (through the file descriptor) will check the
Bram Moolenaarf4b8e572004-06-24 15:53:16 +0000982 backup file instead of the newly created file. "crontab -e" is an
Bram Moolenaar071d4272004-06-13 20:20:40 +0000983 example.
984
985 When a copy is made, the original file is truncated and then filled
986 with the new text. This means that protection bits, owner and
987 symbolic links of the original file are unmodified. The backup file
Bram Moolenaarf4b8e572004-06-24 15:53:16 +0000988 however, is a new file, owned by the user who edited the file. The
Bram Moolenaar071d4272004-06-13 20:20:40 +0000989 group of the backup is set to the group of the original file. If this
990 fails, the protection bits for the group are made the same as for
991 others.
992
993 When the file is renamed this is the other way around: The backup has
994 the same attributes of the original file, and the newly written file
995 is owned by the current user. When the file was a (hard/symbolic)
996 link, the new file will not! That's why the "auto" value doesn't
997 rename when the file is a link. The owner and group of the newly
998 written file will be set to the same ones as the original file, but
999 the system may refuse to do this. In that case the "auto" value will
1000 again not rename the file.
1001
Bram Moolenaar036986f2017-03-16 17:41:02 +01001002 NOTE: This option is set to the Vi default value when 'compatible' is
1003 set and to the Vim default value when 'compatible' is reset.
1004
Bram Moolenaar071d4272004-06-13 20:20:40 +00001005 *'backupdir'* *'bdir'*
1006'backupdir' 'bdir' string (default for Amiga: ".,t:",
Bram Moolenaardfb18412013-12-11 18:53:29 +01001007 for MS-DOS and Win32: ".,$TEMP,c:/tmp,c:/temp"
Bram Moolenaar071d4272004-06-13 20:20:40 +00001008 for Unix: ".,~/tmp,~/")
1009 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001010 List of directories for the backup file, separated with commas.
1011 - The backup file will be created in the first directory in the list
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001012 where this is possible. The directory must exist, Vim will not
1013 create it for you.
Bram Moolenaar3848e002016-03-19 18:42:29 +01001014 - Empty means that no backup file will be created ('patchmode' is
Bram Moolenaar071d4272004-06-13 20:20:40 +00001015 impossible!). Writing may fail because of this.
1016 - A directory "." means to put the backup file in the same directory
1017 as the edited file.
Bram Moolenaar009b2592004-10-24 19:18:58 +00001018 - A directory starting with "./" (or ".\" for MS-DOS et al.) means to
Bram Moolenaar071d4272004-06-13 20:20:40 +00001019 put the backup file relative to where the edited file is. The
1020 leading "." is replaced with the path name of the edited file.
1021 ("." inside a directory name has no special meaning).
1022 - Spaces after the comma are ignored, other spaces are considered part
1023 of the directory name. To have a space at the start of a directory
1024 name, precede it with a backslash.
1025 - To include a comma in a directory name precede it with a backslash.
1026 - A directory name may end in an '/'.
Bram Moolenaarb782ba42018-08-07 21:39:28 +02001027 - For Unix and Win32, if a directory ends in two path separators "//",
Bram Moolenaarf0d58ef2018-11-16 16:13:44 +01001028 the backup file name will be built from the complete path to the
1029 file with all path separators changed to percent '%' signs. This
1030 will ensure file name uniqueness in the backup directory.
Bram Moolenaarb782ba42018-08-07 21:39:28 +02001031 On Win32, it is also possible to end with "\\". However, When a
1032 separating comma is following, you must use "//", since "\\" will
1033 include the comma in the file name. Therefore it is recommended to
1034 use '//', instead of '\\'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001035 - Environment variables are expanded |:set_env|.
1036 - Careful with '\' characters, type one before a space, type two to
1037 get one in the option (see |option-backslash|), for example: >
1038 :set bdir=c:\\tmp,\ dir\\,with\\,commas,\\\ dir\ with\ spaces
1039< - For backwards compatibility with Vim version 3.0 a '>' at the start
1040 of the option is removed.
1041 See also 'backup' and 'writebackup' options.
1042 If you want to hide your backup files on Unix, consider this value: >
1043 :set backupdir=./.backup,~/.backup,.,/tmp
1044< You must create a ".backup" directory in each directory and in your
1045 home directory for this to work properly.
1046 The use of |:set+=| and |:set-=| is preferred when adding or removing
1047 directories from the list. This avoids problems when a future version
1048 uses another default.
1049 This option cannot be set from a |modeline| or in the |sandbox|, for
1050 security reasons.
1051
1052 *'backupext'* *'bex'* *E589*
1053'backupext' 'bex' string (default "~", for VMS: "_")
1054 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001055 String which is appended to a file name to make the name of the
1056 backup file. The default is quite unusual, because this avoids
1057 accidentally overwriting existing files with a backup file. You might
1058 prefer using ".bak", but make sure that you don't have files with
1059 ".bak" that you want to keep.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00001060 Only normal file name characters can be used, "/\*?[|<>" are illegal.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001061
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001062 If you like to keep a lot of backups, you could use a BufWritePre
1063 autocommand to change 'backupext' just before writing the file to
1064 include a timestamp. >
1065 :au BufWritePre * let &bex = '-' . strftime("%Y%b%d%X") . '~'
1066< Use 'backupdir' to put the backup in a different directory.
1067
Bram Moolenaar071d4272004-06-13 20:20:40 +00001068 *'backupskip'* *'bsk'*
Bram Moolenaarb8e22a02018-04-12 21:37:34 +02001069'backupskip' 'bsk' string (default: "$TMPDIR/*,$TMP/*,$TEMP/*"
1070 Unix: "/tmp/*,$TMPDIR/*,$TMP/*,$TEMP/*"
1071 Mac: "/private/tmp/*,$TMPDIR/*,$TMP/*,$TEMP/*")
Bram Moolenaar071d4272004-06-13 20:20:40 +00001072 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001073 {not available when compiled without the |+wildignore|
1074 feature}
1075 A list of file patterns. When one of the patterns matches with the
1076 name of the file which is written, no backup file is created. Both
1077 the specified file name and the full path name of the file are used.
1078 The pattern is used like with |:autocmd|, see |autocmd-patterns|.
1079 Watch out for special characters, see |option-backslash|.
1080 When $TMPDIR, $TMP or $TEMP is not defined, it is not used for the
Bram Moolenaar582fd852005-03-28 20:58:01 +00001081 default value. "/tmp/*" is only used for Unix.
Bram Moolenaar02467872007-05-06 13:22:01 +00001082
Bram Moolenaar1aeaf8c2012-05-18 13:46:39 +02001083 WARNING: Not having a backup file means that when Vim fails to write
1084 your buffer correctly and then, for whatever reason, Vim exits, you
1085 lose both the original file and what you were writing. Only disable
1086 backups if you don't care about losing the file.
1087
Bram Moolenaar02467872007-05-06 13:22:01 +00001088 Note that environment variables are not expanded. If you want to use
1089 $HOME you must expand it explicitly, e.g.: >
Bram Moolenaar7c1c6db2016-04-03 22:08:05 +02001090 :let &backupskip = escape(expand('$HOME'), '\') . '/tmp/*'
Bram Moolenaar02467872007-05-06 13:22:01 +00001091
1092< Note that the default also makes sure that "crontab -e" works (when a
Bram Moolenaara5792f52005-11-23 21:25:05 +00001093 backup would be made by renaming the original file crontab won't see
1094 the newly created file). Also see 'backupcopy' and |crontab|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001095
1096 *'balloondelay'* *'bdlay'*
1097'balloondelay' 'bdlay' number (default: 600)
1098 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001099 {only available when compiled with the |+balloon_eval|
1100 feature}
1101 Delay in milliseconds before a balloon may pop up. See |balloon-eval|.
1102
1103 *'ballooneval'* *'beval'* *'noballooneval'* *'nobeval'*
1104'ballooneval' 'beval' boolean (default off)
1105 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001106 {only available when compiled with the |+balloon_eval|
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001107 feature}
Bram Moolenaar51b0f372017-11-18 18:52:04 +01001108 Switch on the |balloon-eval| functionality for the GUI.
1109
1110 *'balloonevalterm'* *'bevalterm'* *'noballoonevalterm'*
1111 *'nobevalterm'*
1112'balloonevalterm' 'bevalterm' boolean (default off)
1113 global
Bram Moolenaar51b0f372017-11-18 18:52:04 +01001114 {only available when compiled with the
1115 |+balloon_eval_term| feature}
1116 Switch on the |balloon-eval| functionality for the terminal.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001117
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001118 *'balloonexpr'* *'bexpr'*
1119'balloonexpr' 'bexpr' string (default "")
Bram Moolenaar9b2200a2006-03-20 21:55:45 +00001120 global or local to buffer |global-local|
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001121 {only available when compiled with the |+balloon_eval|
1122 feature}
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00001123 Expression for text to show in evaluation balloon. It is only used
Bram Moolenaara6c27c42019-05-09 19:16:22 +02001124 when 'ballooneval' or 'balloonevalterm' is on. These variables can be
1125 used:
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001126
1127 v:beval_bufnr number of the buffer in which balloon is going to show
1128 v:beval_winnr number of the window
Bram Moolenaar82af8712016-06-04 20:20:29 +02001129 v:beval_winid ID of the window
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001130 v:beval_lnum line number
1131 v:beval_col column number (byte index)
1132 v:beval_text word under or after the mouse pointer
1133
Bram Moolenaar54775062019-07-31 21:07:14 +02001134 Instead of showing a balloon, which is limited to plain text, consider
1135 using a popup window, see |popup_beval_example|. A popup window can
1136 use highlighting and show a border.
1137
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001138 The evaluation of the expression must not have side effects!
1139 Example: >
Bram Moolenaara6c27c42019-05-09 19:16:22 +02001140 function MyBalloonExpr()
Bram Moolenaar45360022005-07-21 21:08:21 +00001141 return 'Cursor is at line ' . v:beval_lnum .
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001142 \', column ' . v:beval_col .
1143 \ ' of file ' . bufname(v:beval_bufnr) .
1144 \ ' on word "' . v:beval_text . '"'
1145 endfunction
1146 set bexpr=MyBalloonExpr()
1147 set ballooneval
1148<
Bram Moolenaar396e8292019-07-13 23:04:31 +02001149 Also see |balloon_show()|, it can be used if the content of the balloon
1150 is to be fetched asynchronously. In that case evaluating
1151 'balloonexpr' should result in an empty string. If you get a balloon
1152 with only "0" you probably didn't return anything from your function.
Bram Moolenaar214641f2017-03-05 17:04:09 +01001153
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001154 NOTE: The balloon is displayed only if the cursor is on a text
1155 character. If the result of evaluating 'balloonexpr' is not empty,
1156 Vim does not try to send a message to an external debugger (Netbeans
1157 or Sun Workshop).
1158
Bram Moolenaar30b65812012-07-12 22:01:11 +02001159 The expression will be evaluated in the |sandbox| when set from a
1160 modeline, see |sandbox-option|.
Bram Moolenaar110289e2019-05-23 15:38:06 +02001161 This option cannot be set in a modeline when 'modelineexpr' is off.
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00001162
1163 It is not allowed to change text or jump to another window while
Bram Moolenaar396e8292019-07-13 23:04:31 +02001164 evaluating 'balloonexpr', see |textlock|.
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00001165
Bram Moolenaar87e25fd2005-07-27 21:13:01 +00001166 To check whether line breaks in the balloon text work use this check: >
Bram Moolenaar45360022005-07-21 21:08:21 +00001167 if has("balloon_multiline")
Bram Moolenaar362e1a32006-03-06 23:29:24 +00001168< When they are supported "\n" characters will start a new line. If the
1169 expression evaluates to a |List| this is equal to using each List item
1170 as a string and putting "\n" in between them.
Bram Moolenaar036986f2017-03-16 17:41:02 +01001171 NOTE: This option is set to "" when 'compatible' is set.
Bram Moolenaar362e1a32006-03-06 23:29:24 +00001172
Bram Moolenaar165bc692015-07-21 17:53:25 +02001173 *'belloff'* *'bo'*
1174'belloff' 'bo' string (default "")
1175 global
Bram Moolenaar165bc692015-07-21 17:53:25 +02001176 Specifies for which events the bell will not be rung. It is a comma
1177 separated list of items. For each item that is present, the bell
1178 will be silenced. This is most useful to specify specific events in
1179 insert mode to be silenced.
1180
1181 item meaning when present ~
1182 all All events.
1183 backspace When hitting <BS> or <Del> and deleting results in an
1184 error.
1185 cursor Fail to move around using the cursor keys or
1186 <PageUp>/<PageDown> in |Insert-mode|.
1187 complete Error occurred when using |i_CTRL-X_CTRL-K| or
1188 |i_CTRL-X_CTRL-T|.
1189 copy Cannot copy char from insert mode using |i_CTRL-Y| or
1190 |i_CTRL-E|.
1191 ctrlg Unknown Char after <C-G> in Insert mode.
1192 error Other Error occurred (e.g. try to join last line)
1193 (mostly used in |Normal-mode| or |Cmdline-mode|).
1194 esc hitting <Esc> in |Normal-mode|.
1195 ex In |Visual-mode|, hitting |Q| results in an error.
1196 hangul Error occurred when using hangul input.
1197 insertmode Pressing <Esc> in 'insertmode'.
1198 lang Calling the beep module for Lua/Mzscheme/TCL.
1199 mess No output available for |g<|.
1200 showmatch Error occurred for 'showmatch' function.
1201 operator Empty region error |cpo-E|.
1202 register Unknown register after <C-R> in |Insert-mode|.
1203 shell Bell from shell output |:!|.
1204 spell Error happened on spell suggest.
1205 wildmode More matches in |cmdline-completion| available
1206 (depends on the 'wildmode' setting).
1207
Bram Moolenaar036986f2017-03-16 17:41:02 +01001208 This is most useful to fine tune when in Insert mode the bell should
1209 be rung. For Normal mode and Ex commands, the bell is often rung to
Bram Moolenaar165bc692015-07-21 17:53:25 +02001210 indicate that an error occurred. It can be silenced by adding the
1211 "error" keyword.
1212
Bram Moolenaar071d4272004-06-13 20:20:40 +00001213 *'binary'* *'bin'* *'nobinary'* *'nobin'*
1214'binary' 'bin' boolean (default off)
1215 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001216 This option should be set before editing a binary file. You can also
1217 use the |-b| Vim argument. When this option is switched on a few
1218 options will be changed (also when it already was on):
1219 'textwidth' will be set to 0
1220 'wrapmargin' will be set to 0
1221 'modeline' will be off
1222 'expandtab' will be off
1223 Also, 'fileformat' and 'fileformats' options will not be used, the
1224 file is read and written like 'fileformat' was "unix" (a single <NL>
1225 separates lines).
1226 The 'fileencoding' and 'fileencodings' options will not be used, the
1227 file is read without conversion.
1228 NOTE: When you start editing a(nother) file while the 'bin' option is
1229 on, settings from autocommands may change the settings again (e.g.,
1230 'textwidth'), causing trouble when editing. You might want to set
1231 'bin' again when the file has been loaded.
1232 The previous values of these options are remembered and restored when
1233 'bin' is switched from on to off. Each buffer has its own set of
1234 saved option values.
1235 To edit a file with 'binary' set you can use the |++bin| argument.
1236 This avoids you have to do ":set bin", which would have effect for all
1237 files you edit.
1238 When writing a file the <EOL> for the last line is only written if
1239 there was one in the original file (normally Vim appends an <EOL> to
1240 the last line if there is none; this would make the file longer). See
1241 the 'endofline' option.
1242
1243 *'bioskey'* *'biosk'* *'nobioskey'* *'nobiosk'*
1244'bioskey' 'biosk' boolean (default on)
1245 global
Bram Moolenaar6c60f472019-04-28 16:00:35 +02001246 {only for MS-DOS}
Bram Moolenaarf3913272016-02-25 00:00:01 +01001247 This was for MS-DOS and is no longer supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001248
1249 *'bomb'* *'nobomb'*
1250'bomb' boolean (default off)
1251 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001252 When writing a file and the following conditions are met, a BOM (Byte
1253 Order Mark) is prepended to the file:
1254 - this option is on
1255 - the 'binary' option is off
1256 - 'fileencoding' is "utf-8", "ucs-2", "ucs-4" or one of the little/big
1257 endian variants.
1258 Some applications use the BOM to recognize the encoding of the file.
1259 Often used for UCS-2 files on MS-Windows. For other applications it
1260 causes trouble, for example: "cat file1 file2" makes the BOM of file2
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001261 appear halfway the resulting file. Gcc doesn't accept a BOM.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001262 When Vim reads a file and 'fileencodings' starts with "ucs-bom", a
1263 check for the presence of the BOM is done and 'bomb' set accordingly.
1264 Unless 'binary' is set, it is removed from the first line, so that you
1265 don't see it when editing. When you don't change the options, the BOM
1266 will be restored when writing the file.
1267
1268 *'breakat'* *'brk'*
1269'breakat' 'brk' string (default " ^I!@*-+;:,./?")
1270 global
Bram Moolenaardb84e452010-08-15 13:50:43 +02001271 {not available when compiled without the |+linebreak|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001272 feature}
1273 This option lets you choose which characters might cause a line
Bram Moolenaarac6e65f2005-08-29 22:25:38 +00001274 break if 'linebreak' is on. Only works for ASCII and also for 8-bit
1275 characters when 'encoding' is an 8-bit encoding.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001276
Bram Moolenaar7c1c6db2016-04-03 22:08:05 +02001277 *'breakindent'* *'bri'* *'nobreakindent'* *'nobri'*
Bram Moolenaar946e27a2014-06-25 18:50:27 +02001278'breakindent' 'bri' boolean (default off)
1279 local to window
Bram Moolenaar946e27a2014-06-25 18:50:27 +02001280 {not available when compiled without the |+linebreak|
1281 feature}
1282 Every wrapped line will continue visually indented (same amount of
1283 space as the beginning of that line), thus preserving horizontal blocks
1284 of text.
Bram Moolenaar036986f2017-03-16 17:41:02 +01001285 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaar946e27a2014-06-25 18:50:27 +02001286
1287 *'breakindentopt'* *'briopt'*
1288'breakindentopt' 'briopt' string (default empty)
1289 local to window
Bram Moolenaar946e27a2014-06-25 18:50:27 +02001290 {not available when compiled without the |+linebreak|
1291 feature}
1292 Settings for 'breakindent'. It can consist of the following optional
Bram Moolenaar86b17e92014-07-02 20:00:47 +02001293 items and must be separated by a comma:
Bram Moolenaar946e27a2014-06-25 18:50:27 +02001294 min:{n} Minimum text width that will be kept after
1295 applying 'breakindent', even if the resulting
1296 text should normally be narrower. This prevents
1297 text indented almost to the right window border
1298 occupying lot of vertical space when broken.
Bram Moolenaar86b17e92014-07-02 20:00:47 +02001299 shift:{n} After applying 'breakindent', the wrapped line's
1300 beginning will be shifted by the given number of
1301 characters. It permits dynamic French paragraph
Bram Moolenaar946e27a2014-06-25 18:50:27 +02001302 indentation (negative) or emphasizing the line
1303 continuation (positive).
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01001304 sbr Display the 'showbreak' value before applying the
Bram Moolenaar946e27a2014-06-25 18:50:27 +02001305 additional indent.
1306 The default value for min is 20 and shift is 0.
1307
Bram Moolenaar071d4272004-06-13 20:20:40 +00001308 *'browsedir'* *'bsdir'*
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001309'browsedir' 'bsdir' string (default: "last")
Bram Moolenaar071d4272004-06-13 20:20:40 +00001310 global
Bram Moolenaar6c60f472019-04-28 16:00:35 +02001311 {only for Motif, Athena, GTK, Mac and Win32 GUI}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001312 Which directory to use for the file browser:
Bram Moolenaar446cb832008-06-24 21:56:24 +00001313 last Use same directory as with last file browser, where a
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02001314 file was opened or saved.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001315 buffer Use the directory of the related buffer.
1316 current Use the current directory.
1317 {path} Use the specified directory
1318
1319 *'bufhidden'* *'bh'*
1320'bufhidden' 'bh' string (default: "")
1321 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001322 This option specifies what happens when a buffer is no longer
1323 displayed in a window:
1324 <empty> follow the global 'hidden' option
1325 hide hide the buffer (don't unload it), also when 'hidden'
1326 is not set
1327 unload unload the buffer, also when 'hidden' is set or using
1328 |:hide|
1329 delete delete the buffer from the buffer list, also when
1330 'hidden' is set or using |:hide|, like using
1331 |:bdelete|
1332 wipe wipe out the buffer from the buffer list, also when
1333 'hidden' is set or using |:hide|, like using
1334 |:bwipeout|
1335
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001336 CAREFUL: when "unload", "delete" or "wipe" is used changes in a buffer
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01001337 are lost without a warning. Also, these values may break autocommands
1338 that switch between buffers temporarily.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001339 This option is used together with 'buftype' and 'swapfile' to specify
1340 special kinds of buffers. See |special-buffers|.
1341
1342 *'buflisted'* *'bl'* *'nobuflisted'* *'nobl'* *E85*
1343'buflisted' 'bl' boolean (default: on)
1344 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001345 When this option is set, the buffer shows up in the buffer list. If
1346 it is reset it is not used for ":bnext", "ls", the Buffers menu, etc.
1347 This option is reset by Vim for buffers that are only used to remember
1348 a file name or marks. Vim sets it when starting to edit a buffer.
1349 But not when moving to a buffer with ":buffer".
1350
1351 *'buftype'* *'bt'* *E382*
1352'buftype' 'bt' string (default: "")
1353 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001354 The value of this option specifies the type of a buffer:
1355 <empty> normal buffer
1356 nofile buffer which is not related to a file and will not be
1357 written
1358 nowrite buffer which will not be written
Bram Moolenaar21cf8232004-07-16 20:18:37 +00001359 acwrite buffer which will always be written with BufWriteCmd
Bram Moolenaarb5b75622018-03-09 22:22:21 +01001360 autocommands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001361 quickfix quickfix buffer, contains list of errors |:cwindow|
Bram Moolenaar280f1262006-01-30 00:14:18 +00001362 or list of locations |:lwindow|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001363 help help buffer (you are not supposed to set this
1364 manually)
Bram Moolenaar1f2903c2017-07-23 19:51:01 +02001365 terminal buffer for a |terminal| (you are not supposed to set
1366 this manually)
Bram Moolenaarf2732452018-06-03 14:47:35 +02001367 prompt buffer where only the last line can be edited, meant
1368 to be used by a plugin, see |prompt-buffer|
1369 {only when compiled with the |+channel| feature}
Bram Moolenaar4d784b22019-05-25 19:51:39 +02001370 popup buffer used in a popup window, see |popup|.
1371 {only when compiled with the |+textprop| feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001372
1373 This option is used together with 'bufhidden' and 'swapfile' to
1374 specify special kinds of buffers. See |special-buffers|.
1375
1376 Be careful with changing this option, it can have many side effects!
1377
Bram Moolenaar280f1262006-01-30 00:14:18 +00001378 A "quickfix" buffer is only used for the error list and the location
1379 list. This value is set by the |:cwindow| and |:lwindow| commands and
1380 you are not supposed to change it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001381
1382 "nofile" and "nowrite" buffers are similar:
1383 both: The buffer is not to be written to disk, ":w" doesn't
1384 work (":w filename" does work though).
1385 both: The buffer is never considered to be |'modified'|.
1386 There is no warning when the changes will be lost, for
1387 example when you quit Vim.
1388 both: A swap file is only created when using too much memory
1389 (when 'swapfile' has been reset there is never a swap
1390 file).
1391 nofile only: The buffer name is fixed, it is not handled like a
1392 file name. It is not modified in response to a |:cd|
1393 command.
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01001394 both: When using ":e bufname" and already editing "bufname"
1395 the buffer is made empty and autocommands are
1396 triggered as usual for |:edit|.
Bram Moolenaar21cf8232004-07-16 20:18:37 +00001397 *E676*
1398 "acwrite" implies that the buffer name is not related to a file, like
1399 "nofile", but it will be written. Thus, in contrast to "nofile" and
1400 "nowrite", ":w" does work and a modified buffer can't be abandoned
1401 without saving. For writing there must be matching |BufWriteCmd|,
1402 |FileWriteCmd| or |FileAppendCmd| autocommands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001403
1404 *'casemap'* *'cmp'*
1405'casemap' 'cmp' string (default: "internal,keepascii")
1406 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001407 Specifies details about changing the case of letters. It may contain
1408 these words, separated by a comma:
1409 internal Use internal case mapping functions, the current
1410 locale does not change the case mapping. This only
Bram Moolenaar6f16eb82005-08-23 21:02:42 +00001411 matters when 'encoding' is a Unicode encoding,
1412 "latin1" or "iso-8859-15". When "internal" is
1413 omitted, the towupper() and towlower() system library
1414 functions are used when available.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001415 keepascii For the ASCII characters (0x00 to 0x7f) use the US
1416 case mapping, the current locale is not effective.
1417 This probably only matters for Turkish.
1418
1419 *'cdpath'* *'cd'* *E344* *E346*
1420'cdpath' 'cd' string (default: equivalent to $CDPATH or ",,")
1421 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001422 {not available when compiled without the
1423 |+file_in_path| feature}
1424 This is a list of directories which will be searched when using the
Bram Moolenaar00aa0692019-04-27 20:37:57 +02001425 |:cd|, |:tcd| and |:lcd| commands, provided that the directory being
1426 searched for has a relative path, not an absolute part starting with
1427 "/", "./" or "../", the 'cdpath' option is not used then.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001428 The 'cdpath' option's value has the same form and semantics as
1429 |'path'|. Also see |file-searching|.
1430 The default value is taken from $CDPATH, with a "," prepended to look
1431 in the current directory first.
1432 If the default value taken from $CDPATH is not what you want, include
1433 a modified version of the following command in your vimrc file to
1434 override it: >
1435 :let &cdpath = ',' . substitute(substitute($CDPATH, '[, ]', '\\\0', 'g'), ':', ',', 'g')
1436< This option cannot be set from a |modeline| or in the |sandbox|, for
1437 security reasons.
1438 (parts of 'cdpath' can be passed to the shell to expand file names).
1439
1440 *'cedit'*
1441'cedit' string (Vi default: "", Vim default: CTRL-F)
1442 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001443 The key used in Command-line Mode to open the command-line window.
1444 The default is CTRL-F when 'compatible' is off.
1445 Only non-printable keys are allowed.
1446 The key can be specified as a single character, but it is difficult to
1447 type. The preferred way is to use the <> notation. Examples: >
Bram Moolenaare18dbe82016-07-02 21:42:23 +02001448 :exe "set cedit=\<C-Y>"
1449 :exe "set cedit=\<Esc>"
Bram Moolenaar071d4272004-06-13 20:20:40 +00001450< |Nvi| also has this option, but it only uses the first character.
1451 See |cmdwin|.
Bram Moolenaar036986f2017-03-16 17:41:02 +01001452 NOTE: This option is set to the Vim default value when 'compatible'
1453 is reset.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001454
1455 *'charconvert'* *'ccv'* *E202* *E214* *E513*
1456'charconvert' 'ccv' string (default "")
1457 global
Bram Moolenaar4c92e752019-02-17 21:18:32 +01001458 {only available when compiled with the |+eval| feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001459 An expression that is used for character encoding conversion. It is
1460 evaluated when a file that is to be read or has been written has a
1461 different encoding from what is desired.
1462 'charconvert' is not used when the internal iconv() function is
1463 supported and is able to do the conversion. Using iconv() is
1464 preferred, because it is much faster.
1465 'charconvert' is not used when reading stdin |--|, because there is no
1466 file to convert from. You will have to save the text in a file first.
1467 The expression must return zero or an empty string for success,
1468 non-zero for failure.
1469 The possible encoding names encountered are in 'encoding'.
1470 Additionally, names given in 'fileencodings' and 'fileencoding' are
1471 used.
1472 Conversion between "latin1", "unicode", "ucs-2", "ucs-4" and "utf-8"
1473 is done internally by Vim, 'charconvert' is not used for this.
1474 'charconvert' is also used to convert the viminfo file, if the 'c'
1475 flag is present in 'viminfo'. Also used for Unicode conversion.
1476 Example: >
1477 set charconvert=CharConvert()
1478 fun CharConvert()
1479 system("recode "
1480 \ . v:charconvert_from . ".." . v:charconvert_to
1481 \ . " <" . v:fname_in . " >" v:fname_out)
1482 return v:shell_error
1483 endfun
1484< The related Vim variables are:
1485 v:charconvert_from name of the current encoding
1486 v:charconvert_to name of the desired encoding
1487 v:fname_in name of the input file
1488 v:fname_out name of the output file
1489 Note that v:fname_in and v:fname_out will never be the same.
1490 Note that v:charconvert_from and v:charconvert_to may be different
1491 from 'encoding'. Vim internally uses UTF-8 instead of UCS-2 or UCS-4.
1492 Encryption is not done by Vim when using 'charconvert'. If you want
1493 to encrypt the file after conversion, 'charconvert' should take care
1494 of this.
1495 This option cannot be set from a |modeline| or in the |sandbox|, for
1496 security reasons.
1497
1498 *'cindent'* *'cin'* *'nocindent'* *'nocin'*
1499'cindent' 'cin' boolean (default off)
1500 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001501 {not available when compiled without the |+cindent|
1502 feature}
Bram Moolenaar446cb832008-06-24 21:56:24 +00001503 Enables automatic C program indenting. See 'cinkeys' to set the keys
Bram Moolenaar071d4272004-06-13 20:20:40 +00001504 that trigger reindenting in insert mode and 'cinoptions' to set your
1505 preferred indent style.
1506 If 'indentexpr' is not empty, it overrules 'cindent'.
1507 If 'lisp' is not on and both 'indentexpr' and 'equalprg' are empty,
1508 the "=" operator indents using this algorithm rather than calling an
1509 external program.
1510 See |C-indenting|.
1511 When you don't like the way 'cindent' works, try the 'smartindent'
1512 option or 'indentexpr'.
1513 This option is not used when 'paste' is set.
1514 NOTE: This option is reset when 'compatible' is set.
1515
1516 *'cinkeys'* *'cink'*
Bram Moolenaarce655742019-01-31 14:12:57 +01001517'cinkeys' 'cink' string (default "0{,0},0),0],:,0#,!^F,o,O,e")
Bram Moolenaar071d4272004-06-13 20:20:40 +00001518 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001519 {not available when compiled without the |+cindent|
1520 feature}
1521 A list of keys that, when typed in Insert mode, cause reindenting of
1522 the current line. Only used if 'cindent' is on and 'indentexpr' is
1523 empty.
1524 For the format of this option see |cinkeys-format|.
1525 See |C-indenting|.
1526
1527 *'cinoptions'* *'cino'*
1528'cinoptions' 'cino' string (default "")
1529 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001530 {not available when compiled without the |+cindent|
1531 feature}
1532 The 'cinoptions' affect the way 'cindent' reindents lines in a C
1533 program. See |cinoptions-values| for the values of this option, and
1534 |C-indenting| for info on C indenting in general.
1535
1536
1537 *'cinwords'* *'cinw'*
1538'cinwords' 'cinw' string (default "if,else,while,do,for,switch")
1539 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001540 {not available when compiled without both the
1541 |+cindent| and the |+smartindent| features}
1542 These keywords start an extra indent in the next line when
1543 'smartindent' or 'cindent' is set. For 'cindent' this is only done at
1544 an appropriate place (inside {}).
1545 Note that 'ignorecase' isn't used for 'cinwords'. If case doesn't
1546 matter, include the keyword both the uppercase and lowercase:
1547 "if,If,IF".
1548
1549 *'clipboard'* *'cb'*
1550'clipboard' 'cb' string (default "autoselect,exclude:cons\|linux"
1551 for X-windows, "" otherwise)
1552 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001553 {only in GUI versions or when the |+xterm_clipboard|
1554 feature is included}
1555 This option is a list of comma separated names.
1556 These names are recognized:
1557
Bram Moolenaarc0885aa2012-07-10 16:49:23 +02001558 *clipboard-unnamed*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001559 unnamed When included, Vim will use the clipboard register '*'
1560 for all yank, delete, change and put operations which
1561 would normally go to the unnamed register. When a
1562 register is explicitly specified, it will always be
1563 used regardless of whether "unnamed" is in 'clipboard'
1564 or not. The clipboard register can always be
1565 explicitly accessed using the "* notation. Also see
1566 |gui-clipboard|.
1567
Bram Moolenaar30b65812012-07-12 22:01:11 +02001568 *clipboard-unnamedplus*
Bram Moolenaar00154502013-02-13 16:15:55 +01001569 unnamedplus A variant of the "unnamed" flag which uses the
1570 clipboard register '+' (|quoteplus|) instead of
1571 register '*' for all yank, delete, change and put
1572 operations which would normally go to the unnamed
1573 register. When "unnamed" is also included to the
1574 option, yank operations (but not delete, change or
1575 put) will additionally copy the text into register
1576 '*'.
Bram Moolenaar81af9252010-12-10 20:35:50 +01001577 Only available with the |+X11| feature.
Bram Moolenaarbf9680e2010-12-02 21:43:16 +01001578 Availability can be checked with: >
1579 if has('unnamedplus')
1580<
Bram Moolenaar30b65812012-07-12 22:01:11 +02001581 *clipboard-autoselect*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001582 autoselect Works like the 'a' flag in 'guioptions': If present,
1583 then whenever Visual mode is started, or the Visual
1584 area extended, Vim tries to become the owner of the
1585 windowing system's global selection or put the
1586 selected text on the clipboard used by the selection
Bram Moolenaarba3ff532018-11-04 14:45:49 +01001587 register "*. See |'go-a'| and |quotestar| for details.
1588 When the GUI is active, the 'a' flag in 'guioptions'
1589 is used, when the GUI is not active, this "autoselect"
1590 flag is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001591 Also applies to the modeless selection.
1592
Bram Moolenaarc0885aa2012-07-10 16:49:23 +02001593 *clipboard-autoselectplus*
1594 autoselectplus Like "autoselect" but using the + register instead of
1595 the * register. Compare to the 'P' flag in
1596 'guioptions'.
1597
1598 *clipboard-autoselectml*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001599 autoselectml Like "autoselect", but for the modeless selection
1600 only. Compare to the 'A' flag in 'guioptions'.
1601
Bram Moolenaarc0885aa2012-07-10 16:49:23 +02001602 *clipboard-html*
Bram Moolenaar3a6eaa52009-06-16 13:23:06 +00001603 html When the clipboard contains HTML, use this when
1604 pasting. When putting text on the clipboard, mark it
1605 as HTML. This works to copy rendered HTML from
1606 Firefox, paste it as raw HTML in Vim, select the HTML
1607 in Vim and paste it in a rich edit box in Firefox.
Bram Moolenaar20a825a2010-05-31 21:27:30 +02001608 You probably want to add this only temporarily,
1609 possibly use BufEnter autocommands.
Bram Moolenaar3a6eaa52009-06-16 13:23:06 +00001610 Only supported for GTK version 2 and later.
Bram Moolenaar3a6eaa52009-06-16 13:23:06 +00001611
Bram Moolenaarc0885aa2012-07-10 16:49:23 +02001612 *clipboard-exclude*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001613 exclude:{pattern}
1614 Defines a pattern that is matched against the name of
1615 the terminal 'term'. If there is a match, no
1616 connection will be made to the X server. This is
1617 useful in this situation:
1618 - Running Vim in a console.
1619 - $DISPLAY is set to start applications on another
1620 display.
1621 - You do not want to connect to the X server in the
1622 console, but do want this in a terminal emulator.
1623 To never connect to the X server use: >
1624 exclude:.*
1625< This has the same effect as using the |-X| argument.
1626 Note that when there is no connection to the X server
1627 the window title won't be restored and the clipboard
1628 cannot be accessed.
1629 The value of 'magic' is ignored, {pattern} is
1630 interpreted as if 'magic' was on.
1631 The rest of the option value will be used for
1632 {pattern}, this must be the last entry.
1633
1634 *'cmdheight'* *'ch'*
1635'cmdheight' 'ch' number (default 1)
1636 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001637 Number of screen lines to use for the command-line. Helps avoiding
1638 |hit-enter| prompts.
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001639 The value of this option is stored with the tab page, so that each tab
1640 page can have a different value.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001641
1642 *'cmdwinheight'* *'cwh'*
1643'cmdwinheight' 'cwh' number (default 7)
1644 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001645 Number of screen lines to use for the command-line window. |cmdwin|
1646
Bram Moolenaar483c5d82010-10-20 18:45:33 +02001647 *'colorcolumn'* *'cc'*
1648'colorcolumn' 'cc' string (default "")
1649 local to window
Bram Moolenaar483c5d82010-10-20 18:45:33 +02001650 {not available when compiled without the |+syntax|
1651 feature}
1652 'colorcolumn' is a comma separated list of screen columns that are
1653 highlighted with ColorColumn |hl-ColorColumn|. Useful to align
1654 text. Will make screen redrawing slower.
1655 The screen column can be an absolute number, or a number preceded with
1656 '+' or '-', which is added to or subtracted from 'textwidth'. >
1657
1658 :set cc=+1 " highlight column after 'textwidth'
1659 :set cc=+1,+2,+3 " highlight three columns after 'textwidth'
1660 :hi ColorColumn ctermbg=lightgrey guibg=lightgrey
1661<
1662 When 'textwidth' is zero then the items with '-' and '+' are not used.
1663 A maximum of 256 columns are highlighted.
1664
Bram Moolenaar071d4272004-06-13 20:20:40 +00001665 *'columns'* *'co'* *E594*
1666'columns' 'co' number (default 80 or terminal width)
1667 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001668 Number of columns of the screen. Normally this is set by the terminal
Bram Moolenaar7c626922005-02-07 22:01:03 +00001669 initialization and does not have to be set by hand. Also see
1670 |posix-screen-size|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001671 When Vim is running in the GUI or in a resizable window, setting this
1672 option will cause the window size to be changed. When you only want
1673 to use the size for the GUI, put the command in your |gvimrc| file.
1674 When you set this option and Vim is unable to change the physical
Bram Moolenaar02467872007-05-06 13:22:01 +00001675 number of columns of the display, the display may be messed up. For
1676 the GUI it is always possible and Vim limits the number of columns to
1677 what fits on the screen. You can use this command to get the widest
1678 window possible: >
1679 :set columns=9999
1680< Minimum value is 12, maximum value is 10000.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001681
1682 *'comments'* *'com'* *E524* *E525*
1683'comments' 'com' string (default
1684 "s1:/*,mb:*,ex:*/,://,b:#,:%,:XCOMM,n:>,fb:-")
1685 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001686 {not available when compiled without the |+comments|
1687 feature}
1688 A comma separated list of strings that can start a comment line. See
1689 |format-comments|. See |option-backslash| about using backslashes to
1690 insert a space.
1691
1692 *'commentstring'* *'cms'* *E537*
1693'commentstring' 'cms' string (default "/*%s*/")
1694 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001695 {not available when compiled without the |+folding|
1696 feature}
1697 A template for a comment. The "%s" in the value is replaced with the
1698 comment text. Currently only used to add markers for folding, see
1699 |fold-marker|.
1700
1701 *'compatible'* *'cp'* *'nocompatible'* *'nocp'*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001702'compatible' 'cp' boolean (default on, off when a |vimrc| or |gvimrc|
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +02001703 file is found, reset in |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001704 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001705 This option has the effect of making Vim either more Vi-compatible, or
1706 make Vim behave in a more useful way.
Bram Moolenaar214641f2017-03-05 17:04:09 +01001707
Bram Moolenaar071d4272004-06-13 20:20:40 +00001708 This is a special kind of option, because when it's set or reset,
Bram Moolenaar214641f2017-03-05 17:04:09 +01001709 other options are also changed as a side effect.
1710 NOTE: Setting or resetting this option can have a lot of unexpected
1711 effects: Mappings are interpreted in another way, undo behaves
1712 differently, etc. If you set this option in your vimrc file, you
1713 should probably put it at the very start.
1714
Bram Moolenaar071d4272004-06-13 20:20:40 +00001715 By default this option is on and the Vi defaults are used for the
1716 options. This default was chosen for those people who want to use Vim
1717 just like Vi, and don't even (want to) know about the 'compatible'
1718 option.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001719 When a |vimrc| or |gvimrc| file is found while Vim is starting up,
Bram Moolenaard042c562005-06-30 22:04:15 +00001720 this option is switched off, and all options that have not been
1721 modified will be set to the Vim defaults. Effectively, this means
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001722 that when a |vimrc| or |gvimrc| file exists, Vim will use the Vim
Bram Moolenaard042c562005-06-30 22:04:15 +00001723 defaults, otherwise it will use the Vi defaults. (Note: This doesn't
Bram Moolenaar02467872007-05-06 13:22:01 +00001724 happen for the system-wide vimrc or gvimrc file, nor for a file given
1725 with the |-u| argument). Also see |compatible-default| and
1726 |posix-compliance|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001727 You can also set this option with the "-C" argument, and reset it with
1728 "-N". See |-C| and |-N|.
Bram Moolenaar214641f2017-03-05 17:04:09 +01001729 See 'cpoptions' for more fine tuning of Vi compatibility.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001730
Bram Moolenaar214641f2017-03-05 17:04:09 +01001731 When this option is set, numerous other options are set to make Vim as
1732 Vi-compatible as possible. When this option is unset, various options
1733 are set to make Vim more useful. The table below lists all the
1734 options affected.
1735 The {?} column indicates when the options are affected:
1736 + Means that the option is set to the value given in {set value} when
1737 'compatible' is set.
1738 & Means that the option is set to the value given in {set value} when
1739 'compatible' is set AND is set to its Vim default value when
1740 'compatible' is unset.
1741 - Means the option is NOT changed when setting 'compatible' but IS
1742 set to its Vim default when 'compatible' is unset.
1743 The {effect} column summarises the change when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001744
Bram Moolenaar036986f2017-03-16 17:41:02 +01001745 option ? set value effect ~
Bram Moolenaar214641f2017-03-05 17:04:09 +01001746
1747 'allowrevins' + off no CTRL-_ command
1748 'antialias' + off don't use antialiased fonts
1749 'arabic' + off reset arabic-related options
1750 'arabicshape' + on correct character shapes
1751 'backspace' + "" normal backspace
1752 'backup' + off no backup file
1753 'backupcopy' & Unix: "yes" backup file is a copy
1754 else: "auto" copy or rename backup file
1755 'balloonexpr' + "" text to show in evaluation balloon
1756 'breakindent' + off don't indent when wrapping lines
1757 'cedit' - {unchanged} {set vim default only on resetting 'cp'}
1758 'cindent' + off no C code indentation
1759 'compatible' - {unchanged} {set vim default only on resetting 'cp'}
1760 'copyindent' + off don't copy indent structure
1761 'cpoptions' & (all flags) Vi-compatible flags
1762 'cscopepathcomp'+ 0 don't show directories in tags list
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01001763 'cscoperelative'+ off don't use basename of path as prefix
Bram Moolenaar214641f2017-03-05 17:04:09 +01001764 'cscopetag' + off don't use cscope for ":tag"
Bram Moolenaar036986f2017-03-16 17:41:02 +01001765 'cscopetagorder'+ 0 see |cscopetagorder|
Bram Moolenaar214641f2017-03-05 17:04:09 +01001766 'cscopeverbose' + off see |cscopeverbose|
1767 'delcombine' + off unicode: delete whole char combination
1768 'digraph' + off no digraphs
1769 'esckeys' & off no <Esc>-keys in Insert mode
1770 'expandtab' + off tabs not expanded to spaces
1771 'fileformats' & "" no automatic file format detection,
Bram Moolenaar071d4272004-06-13 20:20:40 +00001772 "dos,unix" except for DOS, Windows and OS/2
Bram Moolenaar214641f2017-03-05 17:04:09 +01001773 'formatexpr' + "" use 'formatprg' for auto-formatting
1774 'formatoptions' & "vt" Vi compatible formatting
1775 'gdefault' + off no default 'g' flag for ":s"
1776 'history' & 0 no commandline history
1777 'hkmap' + off no Hebrew keyboard mapping
1778 'hkmapp' + off no phonetic Hebrew keyboard mapping
1779 'hlsearch' + off no highlighting of search matches
1780 'incsearch' + off no incremental searching
1781 'indentexpr' + "" no indenting by expression
1782 'insertmode' + off do not start in Insert mode
1783 'iskeyword' & "@,48-57,_" keywords contain alphanumeric
Bram Moolenaar071d4272004-06-13 20:20:40 +00001784 characters and '_'
Bram Moolenaar214641f2017-03-05 17:04:09 +01001785 'joinspaces' + on insert 2 spaces after period
1786 'modeline' & off no modelines
1787 'more' & off no pauses in listings
1788 'mzquantum' - {unchanged} {set vim default only on resetting 'cp'}
1789 'numberwidth' & 8 min number of columns for line number
1790 'preserveindent'+ off don't preserve current indent structure
1791 when changing it
1792 'revins' + off no reverse insert
1793 'ruler' + off no ruler
1794 'scrolljump' + 1 no jump scroll
1795 'scrolloff' + 0 no scroll offset
1796 'shelltemp' - {unchanged} {set vim default only on resetting 'cp'}
1797 'shiftround' + off indent not rounded to shiftwidth
Bram Moolenaar9dfa3132019-05-04 21:08:40 +02001798 'shortmess' & "S" no shortening of messages
Bram Moolenaar214641f2017-03-05 17:04:09 +01001799 'showcmd' & off command characters not shown
1800 'showmode' & off current mode not shown
1801 'sidescrolloff' + 0 cursor moves to edge of screen in scroll
1802 'smartcase' + off no automatic ignore case switch
1803 'smartindent' + off no smart indentation
1804 'smarttab' + off no smart tab size
1805 'softtabstop' + 0 tabs are always 'tabstop' positions
1806 'startofline' + on goto startofline with some commands
1807 'tagcase' & "followic" 'ignorecase' when searching tags file
1808 'tagrelative' & off tag file names are not relative
1809 'termguicolors' + off don't use highlight-(guifg|guibg)
1810 'textauto' & off no automatic textmode detection
1811 'textwidth' + 0 no automatic line wrap
1812 'tildeop' + off tilde is not an operator
1813 'ttimeout' + off no terminal timeout
1814 'undofile' + off don't use an undo file
Bram Moolenaar036986f2017-03-16 17:41:02 +01001815 'viminfo' - {unchanged} {set Vim default only on resetting 'cp'}
Bram Moolenaar214641f2017-03-05 17:04:09 +01001816 'virtualedit' + "" cursor can only be placed on characters
1817 'whichwrap' & "" left-right movements don't wrap
1818 'wildchar' & CTRL-E only when the current value is <Tab>
Bram Moolenaar071d4272004-06-13 20:20:40 +00001819 use CTRL-E for cmdline completion
Bram Moolenaar214641f2017-03-05 17:04:09 +01001820 'writebackup' + on or off depends on the |+writebackup| feature
Bram Moolenaar071d4272004-06-13 20:20:40 +00001821
1822 *'complete'* *'cpt'* *E535*
1823'complete' 'cpt' string (default: ".,w,b,u,t,i")
1824 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001825 This option specifies how keyword completion |ins-completion| works
1826 when CTRL-P or CTRL-N are used. It is also used for whole-line
1827 completion |i_CTRL-X_CTRL-L|. It indicates the type of completion
1828 and the places to scan. It is a comma separated list of flags:
Bram Moolenaar3848e002016-03-19 18:42:29 +01001829 . scan the current buffer ('wrapscan' is ignored)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001830 w scan buffers from other windows
1831 b scan other loaded buffers that are in the buffer list
1832 u scan the unloaded buffers that are in the buffer list
1833 U scan the buffers that are not in the buffer list
1834 k scan the files given with the 'dictionary' option
Bram Moolenaar0b238792006-03-02 22:49:12 +00001835 kspell use the currently active spell checking |spell|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001836 k{dict} scan the file {dict}. Several "k" flags can be given,
1837 patterns are valid too. For example: >
1838 :set cpt=k/usr/dict/*,k~/spanish
1839< s scan the files given with the 'thesaurus' option
1840 s{tsr} scan the file {tsr}. Several "s" flags can be given, patterns
1841 are valid too.
1842 i scan current and included files
1843 d scan current and included files for defined name or macro
1844 |i_CTRL-X_CTRL-D|
1845 ] tag completion
1846 t same as "]"
1847
1848 Unloaded buffers are not loaded, thus their autocmds |:autocmd| are
1849 not executed, this may lead to unexpected completions from some files
1850 (gzipped files for example). Unloaded buffers are not scanned for
1851 whole-line completion.
1852
1853 The default is ".,w,b,u,t,i", which means to scan:
1854 1. the current buffer
1855 2. buffers in other windows
1856 3. other loaded buffers
1857 4. unloaded buffers
1858 5. tags
1859 6. included files
1860
1861 As you can see, CTRL-N and CTRL-P can be used to do any 'iskeyword'-
Bram Moolenaar582fd852005-03-28 20:58:01 +00001862 based expansion (e.g., dictionary |i_CTRL-X_CTRL-K|, included patterns
1863 |i_CTRL-X_CTRL-I|, tags |i_CTRL-X_CTRL-]| and normal expansions).
Bram Moolenaar071d4272004-06-13 20:20:40 +00001864
Bram Moolenaarcfbc5ee2004-07-02 15:38:35 +00001865 *'completefunc'* *'cfu'*
1866'completefunc' 'cfu' string (default: empty)
1867 local to buffer
Bram Moolenaardb84e452010-08-15 13:50:43 +02001868 {not available when compiled without the |+eval|
Bram Moolenaare2c453d2019-08-21 14:37:09 +02001869 feature}
Bram Moolenaarc7486e02005-12-29 22:48:26 +00001870 This option specifies a function to be used for Insert mode completion
1871 with CTRL-X CTRL-U. |i_CTRL-X_CTRL-U|
Bram Moolenaar280f1262006-01-30 00:14:18 +00001872 See |complete-functions| for an explanation of how the function is
1873 invoked and what it should return.
Bram Moolenaar166af9b2010-11-16 20:34:40 +01001874 This option cannot be set from a |modeline| or in the |sandbox|, for
1875 security reasons.
Bram Moolenaar325b7a22004-07-05 15:58:32 +00001876
Bram Moolenaarac3150d2019-07-28 16:36:39 +02001877 *'completeslash'* *'csl'*
1878'completeslash' 'csl' string (default: "")
1879 local to buffer
1880 {not in Vi} {only for MS-Windows}
1881 When this option is set it overrules 'shellslash' for completion:
1882 - When this option is set to "slash", a forward slash is used for path
1883 completion in insert mode. This is useful when editing HTML tag, or
1884 Makefile with 'noshellslash' on Windows.
1885 - When this option is set to "backslash", backslash is used. This is
1886 useful when editing a batch file with 'shellslash' set on Windows.
1887 - When this option is empty, same character is used as for
1888 'shellslash'.
1889 For Insert mode completion the buffer-local value is used. For
1890 command line completion the global value is used.
1891
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001892 *'completeopt'* *'cot'*
Bram Moolenaar96d2c5b2006-03-11 21:27:59 +00001893'completeopt' 'cot' string (default: "menu,preview")
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001894 global
Bram Moolenaarc7453f52006-02-10 23:20:28 +00001895 A comma separated list of options for Insert mode completion
1896 |ins-completion|. The supported values are:
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001897
1898 menu Use a popup menu to show the possible completions. The
1899 menu is only shown when there is more than one match and
1900 sufficient colors are available. |ins-completion-menu|
1901
Bram Moolenaar65c923a2006-03-03 22:56:30 +00001902 menuone Use the popup menu also when there is only one match.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001903 Useful when there is additional information about the
Bram Moolenaar65c923a2006-03-03 22:56:30 +00001904 match, e.g., what file it comes from.
1905
Bram Moolenaarc1e37902006-04-18 21:55:01 +00001906 longest Only insert the longest common text of the matches. If
1907 the menu is displayed you can use CTRL-L to add more
1908 characters. Whether case is ignored depends on the kind
1909 of completion. For buffer text the 'ignorecase' option is
1910 used.
Bram Moolenaarc7453f52006-02-10 23:20:28 +00001911
Bram Moolenaar96d2c5b2006-03-11 21:27:59 +00001912 preview Show extra information about the currently selected
Bram Moolenaar02467872007-05-06 13:22:01 +00001913 completion in the preview window. Only works in
1914 combination with "menu" or "menuone".
1915
Bram Moolenaar576a4a62019-08-18 15:25:17 +02001916 popup Show extra information about the currently selected
1917 completion in a popup window. Only works in combination
1918 with "menu" or "menuone". Overrides "preview".
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02001919 See |'completepopup'| for specifying properties.
Bram Moolenaar576a4a62019-08-18 15:25:17 +02001920 {only works when compiled with the +textprop feature}
1921
Bram Moolenaarb6be1e22015-07-10 18:18:40 +02001922 noinsert Do not insert any text for a match until the user selects
1923 a match from the menu. Only works in combination with
1924 "menu" or "menuone". No effect if "longest" is present.
1925
1926 noselect Do not select a match in the menu, force the user to
1927 select one from the menu. Only works in combination with
1928 "menu" or "menuone".
1929
Bram Moolenaar96d2c5b2006-03-11 21:27:59 +00001930
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02001931 *'completepopup'* *'cpp'*
1932'completepopup' 'cpp' string (default empty)
1933 global
1934 {not available when compiled without the |+textprop|
1935 or |+quickfix| feature}
1936 When 'completeopt' contains "popup" then this option is used for the
Bram Moolenaar06fe74a2019-08-31 16:20:32 +02001937 properties of the info popup when it is created. You can also use
1938 |popup_findinfo()| and then set properties for an existing info popup
1939 with |popup_setoptions()|. See |complete-popup|.
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02001940
1941
Bram Moolenaarf5963f72010-07-23 22:10:27 +02001942 *'concealcursor'* *'cocu'*
1943'concealcursor' 'cocu' string (default: "")
1944 local to window
Bram Moolenaarf5963f72010-07-23 22:10:27 +02001945 {not available when compiled without the |+conceal|
1946 feature}
1947 Sets the modes in which text in the cursor line can also be concealed.
1948 When the current mode is listed then concealing happens just like in
1949 other lines.
1950 n Normal mode
1951 v Visual mode
1952 i Insert mode
Bram Moolenaarca8c9862010-07-24 15:00:38 +02001953 c Command line editing, for 'incsearch'
Bram Moolenaarf5963f72010-07-23 22:10:27 +02001954
Bram Moolenaare6dc5732010-07-24 23:52:26 +02001955 'v' applies to all lines in the Visual area, not only the cursor.
Bram Moolenaarca8c9862010-07-24 15:00:38 +02001956 A useful value is "nc". This is used in help files. So long as you
Bram Moolenaarf5963f72010-07-23 22:10:27 +02001957 are moving around text is concealed, but when starting to insert text
1958 or selecting a Visual area the concealed text is displayed, so that
1959 you can see what you are doing.
Bram Moolenaarf70e3d62010-07-24 13:15:07 +02001960 Keep in mind that the cursor position is not always where it's
1961 displayed. E.g., when moving vertically it may change column.
Bram Moolenaarf5963f72010-07-23 22:10:27 +02001962
1963
Bram Moolenaar95bafa22018-10-02 13:26:25 +02001964 *'conceallevel'* *'cole'*
1965'conceallevel' 'cole' number (default 0)
Bram Moolenaar860cae12010-06-05 23:22:07 +02001966 local to window
Bram Moolenaar860cae12010-06-05 23:22:07 +02001967 {not available when compiled without the |+conceal|
1968 feature}
Bram Moolenaar6df6f472010-07-18 18:04:50 +02001969 Determine how text with the "conceal" syntax attribute |:syn-conceal|
1970 is shown:
Bram Moolenaar860cae12010-06-05 23:22:07 +02001971
Bram Moolenaar6df6f472010-07-18 18:04:50 +02001972 Value Effect ~
Bram Moolenaar860cae12010-06-05 23:22:07 +02001973 0 Text is shown normally
Bram Moolenaar477db062010-07-28 18:17:41 +02001974 1 Each block of concealed text is replaced with one
1975 character. If the syntax item does not have a custom
1976 replacement character defined (see |:syn-cchar|) the
1977 character defined in 'listchars' is used (default is a
1978 space).
1979 It is highlighted with the "Conceal" highlight group.
Bram Moolenaar860cae12010-06-05 23:22:07 +02001980 2 Concealed text is completely hidden unless it has a
1981 custom replacement character defined (see
Bram Moolenaar477db062010-07-28 18:17:41 +02001982 |:syn-cchar|).
Bram Moolenaara7781e02010-07-19 20:13:22 +02001983 3 Concealed text is completely hidden.
Bram Moolenaar860cae12010-06-05 23:22:07 +02001984
Bram Moolenaara7781e02010-07-19 20:13:22 +02001985 Note: in the cursor line concealed text is not hidden, so that you can
Bram Moolenaarf5963f72010-07-23 22:10:27 +02001986 edit and copy the text. This can be changed with the 'concealcursor'
1987 option.
Bram Moolenaar860cae12010-06-05 23:22:07 +02001988
Bram Moolenaar071d4272004-06-13 20:20:40 +00001989 *'confirm'* *'cf'* *'noconfirm'* *'nocf'*
1990'confirm' 'cf' boolean (default off)
1991 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001992 When 'confirm' is on, certain operations that would normally
1993 fail because of unsaved changes to a buffer, e.g. ":q" and ":e",
1994 instead raise a |dialog| asking if you wish to save the current
1995 file(s). You can still use a ! to unconditionally |abandon| a buffer.
1996 If 'confirm' is off you can still activate confirmation for one
1997 command only (this is most useful in mappings) with the |:confirm|
1998 command.
1999 Also see the |confirm()| function and the 'v' flag in 'guioptions'.
2000
2001 *'conskey'* *'consk'* *'noconskey'* *'noconsk'*
2002'conskey' 'consk' boolean (default off)
2003 global
Bram Moolenaarf3913272016-02-25 00:00:01 +01002004 This was for MS-DOS and is no longer supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002005
2006 *'copyindent'* *'ci'* *'nocopyindent'* *'noci'*
2007'copyindent' 'ci' boolean (default off)
2008 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00002009 Copy the structure of the existing lines indent when autoindenting a
2010 new line. Normally the new indent is reconstructed by a series of
2011 tabs followed by spaces as required (unless |'expandtab'| is enabled,
2012 in which case only spaces are used). Enabling this option makes the
2013 new line copy whatever characters were used for indenting on the
Bram Moolenaar446cb832008-06-24 21:56:24 +00002014 existing line. 'expandtab' has no effect on these characters, a Tab
2015 remains a Tab. If the new indent is greater than on the existing
Bram Moolenaar071d4272004-06-13 20:20:40 +00002016 line, the remaining space is filled in the normal manner.
Bram Moolenaar036986f2017-03-16 17:41:02 +01002017 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002018 Also see 'preserveindent'.
2019
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002020 *'cpoptions'* *'cpo'* *cpo*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002021'cpoptions' 'cpo' string (Vim default: "aABceFs",
2022 Vi default: all flags)
2023 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00002024 A sequence of single character flags. When a character is present
Bram Moolenaar7cba6c02013-09-05 22:13:31 +02002025 this indicates Vi-compatible behavior. This is used for things where
2026 not being Vi-compatible is mostly or sometimes preferred.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002027 'cpoptions' stands for "compatible-options".
2028 Commas can be added for readability.
2029 To avoid problems with flags that are added in the future, use the
2030 "+=" and "-=" feature of ":set" |add-option-flags|.
2031 NOTE: This option is set to the Vi default value when 'compatible' is
2032 set and to the Vim default value when 'compatible' is reset.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002033 NOTE: This option is set to the POSIX default value at startup when
2034 the Vi default value would be used and the $VIM_POSIX environment
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002035 variable exists |posix|. This means Vim tries to behave like the
2036 POSIX specification.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002037
2038 contains behavior ~
2039 *cpo-a*
2040 a When included, a ":read" command with a file name
2041 argument will set the alternate file name for the
2042 current window.
2043 *cpo-A*
2044 A When included, a ":write" command with a file name
2045 argument will set the alternate file name for the
2046 current window.
2047 *cpo-b*
2048 b "\|" in a ":map" command is recognized as the end of
2049 the map command. The '\' is included in the mapping,
2050 the text after the '|' is interpreted as the next
2051 command. Use a CTRL-V instead of a backslash to
2052 include the '|' in the mapping. Applies to all
2053 mapping, abbreviation, menu and autocmd commands.
2054 See also |map_bar|.
2055 *cpo-B*
2056 B A backslash has no special meaning in mappings,
Bram Moolenaara9604e62018-07-21 05:56:22 +02002057 abbreviations, user commands and the "to" part of the
2058 menu commands. Remove this flag to be able to use a
2059 backslash like a CTRL-V. For example, the command
2060 ":map X \<Esc>" results in X being mapped to:
Bram Moolenaar071d4272004-06-13 20:20:40 +00002061 'B' included: "\^[" (^[ is a real <Esc>)
2062 'B' excluded: "<Esc>" (5 characters)
2063 ('<' excluded in both cases)
2064 *cpo-c*
2065 c Searching continues at the end of any match at the
2066 cursor position, but not further than the start of the
2067 next line. When not present searching continues
2068 one character from the cursor position. With 'c'
2069 "abababababab" only gets three matches when repeating
2070 "/abab", without 'c' there are five matches.
2071 *cpo-C*
2072 C Do not concatenate sourced lines that start with a
2073 backslash. See |line-continuation|.
2074 *cpo-d*
2075 d Using "./" in the 'tags' option doesn't mean to use
2076 the tags file relative to the current file, but the
2077 tags file in the current directory.
2078 *cpo-D*
2079 D Can't use CTRL-K to enter a digraph after Normal mode
2080 commands with a character argument, like |r|, |f| and
2081 |t|.
2082 *cpo-e*
2083 e When executing a register with ":@r", always add a
2084 <CR> to the last line, also when the register is not
2085 linewise. If this flag is not present, the register
2086 is not linewise and the last line does not end in a
2087 <CR>, then the last line is put on the command-line
2088 and can be edited before hitting <CR>.
2089 *cpo-E*
2090 E It is an error when using "y", "d", "c", "g~", "gu" or
2091 "gU" on an Empty region. The operators only work when
Bram Moolenaar15142e22018-04-30 22:19:58 +02002092 at least one character is to be operated on. Example:
Bram Moolenaar071d4272004-06-13 20:20:40 +00002093 This makes "y0" fail in the first column.
2094 *cpo-f*
2095 f When included, a ":read" command with a file name
2096 argument will set the file name for the current buffer,
2097 if the current buffer doesn't have a file name yet.
2098 *cpo-F*
2099 F When included, a ":write" command with a file name
2100 argument will set the file name for the current
2101 buffer, if the current buffer doesn't have a file name
Bram Moolenaarb3480382005-12-11 21:33:32 +00002102 yet. Also see |cpo-P|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002103 *cpo-g*
2104 g Goto line 1 when using ":edit" without argument.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002105 *cpo-H*
2106 H When using "I" on a line with only blanks, insert
2107 before the last blank. Without this flag insert after
2108 the last blank.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002109 *cpo-i*
2110 i When included, interrupting the reading of a file will
2111 leave it modified.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002112 *cpo-I*
2113 I When moving the cursor up or down just after inserting
2114 indent for 'autoindent', do not delete the indent.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002115 *cpo-j*
2116 j When joining lines, only add two spaces after a '.',
2117 not after '!' or '?'. Also see 'joinspaces'.
2118 *cpo-J*
2119 J A |sentence| has to be followed by two spaces after
Bram Moolenaar582fd852005-03-28 20:58:01 +00002120 the '.', '!' or '?'. A <Tab> is not recognized as
Bram Moolenaar071d4272004-06-13 20:20:40 +00002121 white space.
2122 *cpo-k*
2123 k Disable the recognition of raw key codes in
2124 mappings, abbreviations, and the "to" part of menu
2125 commands. For example, if <Key> sends ^[OA (where ^[
2126 is <Esc>), the command ":map X ^[OA" results in X
2127 being mapped to:
2128 'k' included: "^[OA" (3 characters)
2129 'k' excluded: "<Key>" (one key code)
2130 Also see the '<' flag below.
2131 *cpo-K*
2132 K Don't wait for a key code to complete when it is
2133 halfway a mapping. This breaks mapping <F1><F1> when
2134 only part of the second <F1> has been read. It
2135 enables cancelling the mapping by typing <F1><Esc>.
2136 *cpo-l*
2137 l Backslash in a [] range in a search pattern is taken
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002138 literally, only "\]", "\^", "\-" and "\\" are special.
2139 See |/[]|
Bram Moolenaar071d4272004-06-13 20:20:40 +00002140 'l' included: "/[ \t]" finds <Space>, '\' and 't'
2141 'l' excluded: "/[ \t]" finds <Space> and <Tab>
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002142 Also see |cpo-\|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002143 *cpo-L*
2144 L When the 'list' option is set, 'wrapmargin',
2145 'textwidth', 'softtabstop' and Virtual Replace mode
2146 (see |gR|) count a <Tab> as two characters, instead of
2147 the normal behavior of a <Tab>.
2148 *cpo-m*
2149 m When included, a showmatch will always wait half a
2150 second. When not included, a showmatch will wait half
2151 a second or until a character is typed. |'showmatch'|
2152 *cpo-M*
2153 M When excluded, "%" matching will take backslashes into
2154 account. Thus in "( \( )" and "\( ( \)" the outer
2155 parenthesis match. When included "%" ignores
2156 backslashes, which is Vi compatible.
2157 *cpo-n*
Bram Moolenaar64486672010-05-16 15:46:46 +02002158 n When included, the column used for 'number' and
2159 'relativenumber' will also be used for text of wrapped
2160 lines.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002161 *cpo-o*
2162 o Line offset to search command is not remembered for
2163 next search.
2164 *cpo-O*
2165 O Don't complain if a file is being overwritten, even
2166 when it didn't exist when editing it. This is a
2167 protection against a file unexpectedly created by
2168 someone else. Vi didn't complain about this.
2169 *cpo-p*
2170 p Vi compatible Lisp indenting. When not present, a
2171 slightly better algorithm is used.
Bram Moolenaarb3480382005-12-11 21:33:32 +00002172 *cpo-P*
2173 P When included, a ":write" command that appends to a
2174 file will set the file name for the current buffer, if
2175 the current buffer doesn't have a file name yet and
2176 the 'F' flag is also included |cpo-F|.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002177 *cpo-q*
2178 q When joining multiple lines leave the cursor at the
2179 position where it would be when joining two lines.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002180 *cpo-r*
2181 r Redo ("." command) uses "/" to repeat a search
2182 command, instead of the actually used search string.
2183 *cpo-R*
2184 R Remove marks from filtered lines. Without this flag
2185 marks are kept like |:keepmarks| was used.
2186 *cpo-s*
2187 s Set buffer options when entering the buffer for the
2188 first time. This is like it is in Vim version 3.0.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002189 And it is the default. If not present the options are
Bram Moolenaar071d4272004-06-13 20:20:40 +00002190 set when the buffer is created.
2191 *cpo-S*
2192 S Set buffer options always when entering a buffer
2193 (except 'readonly', 'fileformat', 'filetype' and
2194 'syntax'). This is the (most) Vi compatible setting.
2195 The options are set to the values in the current
2196 buffer. When you change an option and go to another
2197 buffer, the value is copied. Effectively makes the
2198 buffer options global to all buffers.
2199
2200 's' 'S' copy buffer options
2201 no no when buffer created
2202 yes no when buffer first entered (default)
2203 X yes each time when buffer entered (vi comp.)
2204 *cpo-t*
2205 t Search pattern for the tag command is remembered for
2206 "n" command. Otherwise Vim only puts the pattern in
2207 the history for search pattern, but doesn't change the
2208 last used search pattern.
2209 *cpo-u*
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002210 u Undo is Vi compatible. See |undo-two-ways|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002211 *cpo-v*
2212 v Backspaced characters remain visible on the screen in
2213 Insert mode. Without this flag the characters are
2214 erased from the screen right away. With this flag the
2215 screen newly typed text overwrites backspaced
2216 characters.
2217 *cpo-w*
2218 w When using "cw" on a blank character, only change one
2219 character and not all blanks until the start of the
2220 next word.
2221 *cpo-W*
2222 W Don't overwrite a readonly file. When omitted, ":w!"
2223 overwrites a readonly file, if possible.
2224 *cpo-x*
2225 x <Esc> on the command-line executes the command-line.
2226 The default in Vim is to abandon the command-line,
2227 because <Esc> normally aborts a command. |c_<Esc>|
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002228 *cpo-X*
2229 X When using a count with "R" the replaced text is
2230 deleted only once. Also when repeating "R" with "."
2231 and a count.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002232 *cpo-y*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002233 y A yank command can be redone with ".". Think twice if
2234 you really want to use this, it may break some
2235 plugins, since most people expect "." to only repeat a
2236 change.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002237 *cpo-Z*
2238 Z When using "w!" while the 'readonly' option is set,
2239 don't reset 'readonly'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002240 *cpo-!*
2241 ! When redoing a filter command, use the last used
2242 external command, whatever it was. Otherwise the last
2243 used -filter- command is used.
2244 *cpo-$*
2245 $ When making a change to one line, don't redisplay the
2246 line, but put a '$' at the end of the changed text.
2247 The changed text will be overwritten when you type the
2248 new text. The line is redisplayed if you type any
2249 command that moves the cursor from the insertion
2250 point.
2251 *cpo-%*
2252 % Vi-compatible matching is done for the "%" command.
2253 Does not recognize "#if", "#endif", etc.
2254 Does not recognize "/*" and "*/".
2255 Parens inside single and double quotes are also
2256 counted, causing a string that contains a paren to
2257 disturb the matching. For example, in a line like
2258 "if (strcmp("foo(", s))" the first paren does not
2259 match the last one. When this flag is not included,
2260 parens inside single and double quotes are treated
2261 specially. When matching a paren outside of quotes,
2262 everything inside quotes is ignored. When matching a
2263 paren inside quotes, it will find the matching one (if
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002264 there is one). This works very well for C programs.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00002265 This flag is also used for other features, such as
2266 C-indenting.
Bram Moolenaar7c626922005-02-07 22:01:03 +00002267 *cpo--*
2268 - When included, a vertical movement command fails when
Bram Moolenaar8ada17c2006-01-19 22:16:24 +00002269 it would go above the first line or below the last
2270 line. Without it the cursor moves to the first or
2271 last line, unless it already was in that line.
Bram Moolenaar7c626922005-02-07 22:01:03 +00002272 Applies to the commands "-", "k", CTRL-P, "+", "j",
Bram Moolenaar8ada17c2006-01-19 22:16:24 +00002273 CTRL-N, CTRL-J and ":1234".
Bram Moolenaar1cd871b2004-12-19 22:46:22 +00002274 *cpo-+*
2275 + When included, a ":write file" command will reset the
2276 'modified' flag of the buffer, even though the buffer
2277 itself may still be different from its file.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00002278 *cpo-star*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002279 * Use ":*" in the same way as ":@". When not included,
2280 ":*" is an alias for ":'<,'>", select the Visual area.
2281 *cpo-<*
2282 < Disable the recognition of special key codes in |<>|
2283 form in mappings, abbreviations, and the "to" part of
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002284 menu commands. For example, the command
Bram Moolenaar071d4272004-06-13 20:20:40 +00002285 ":map X <Tab>" results in X being mapped to:
2286 '<' included: "<Tab>" (5 characters)
2287 '<' excluded: "^I" (^I is a real <Tab>)
2288 Also see the 'k' flag above.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002289 *cpo->*
2290 > When appending to a register, put a line break before
2291 the appended text.
Bram Moolenaar8b3e0332011-06-26 05:36:34 +02002292 *cpo-;*
2293 ; When using |,| or |;| to repeat the last |t| search
2294 and the cursor is right in front of the searched
2295 character, the cursor won't move. When not included,
2296 the cursor would skip over it and jump to the
Bram Moolenaarc8734422012-06-01 22:38:45 +02002297 following occurrence.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002298
2299 POSIX flags. These are not included in the Vi default value, except
2300 when $VIM_POSIX was set on startup. |posix|
2301
2302 contains behavior ~
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00002303 *cpo-#*
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002304 # A count before "D", "o" and "O" has no effect.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002305 *cpo-&*
2306 & When ":preserve" was used keep the swap file when
2307 exiting normally while this buffer is still loaded.
2308 This flag is tested when exiting.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002309 *cpo-\*
2310 \ Backslash in a [] range in a search pattern is taken
2311 literally, only "\]" is special See |/[]|
Bram Moolenaar90915b52005-08-21 22:17:52 +00002312 '\' included: "/[ \-]" finds <Space>, '\' and '-'
2313 '\' excluded: "/[ \-]" finds <Space> and '-'
2314 Also see |cpo-l|.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002315 *cpo-/*
2316 / When "%" is used as the replacement string in a |:s|
2317 command, use the previous replacement string. |:s%|
2318 *cpo-{*
2319 { The |{| and |}| commands also stop at a "{" character
2320 at the start of a line.
2321 *cpo-.*
2322 . The ":chdir" and ":cd" commands fail if the current
2323 buffer is modified, unless ! is used. Vim doesn't
2324 need this, since it remembers the full path of an
2325 opened file.
2326 *cpo-bar*
2327 | The value of the $LINES and $COLUMNS environment
2328 variables overrule the terminal size values obtained
2329 with system specific functions.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002330
Bram Moolenaar071d4272004-06-13 20:20:40 +00002331
Bram Moolenaar40e6a712010-05-16 22:32:54 +02002332 *'cryptmethod'* *'cm'*
Bram Moolenaara86187b2018-12-16 18:20:00 +01002333'cryptmethod' 'cm' string (default "blowfish2")
Bram Moolenaar49771f42010-07-20 17:32:38 +02002334 global or local to buffer |global-local|
Bram Moolenaar40e6a712010-05-16 22:32:54 +02002335 Method used for encryption when the buffer is written to a file:
Bram Moolenaar0bbabe82010-05-17 20:32:55 +02002336 *pkzip*
Bram Moolenaar49771f42010-07-20 17:32:38 +02002337 zip PkZip compatible method. A weak kind of encryption.
Bram Moolenaarf50a2532010-05-21 15:36:08 +02002338 Backwards compatible with Vim 7.2 and older.
Bram Moolenaar0bbabe82010-05-17 20:32:55 +02002339 *blowfish*
Bram Moolenaar8f4ac012014-08-10 13:38:34 +02002340 blowfish Blowfish method. Medium strong encryption but it has
2341 an implementation flaw. Requires Vim 7.3 or later,
2342 files can NOT be read by Vim 7.2 and older. This adds
2343 a "seed" to the file, every time you write the file
2344 the encrypted bytes will be different.
2345 *blowfish2*
2346 blowfish2 Blowfish method. Medium strong encryption. Requires
Bram Moolenaar5e9b2fa2016-02-01 22:37:05 +01002347 Vim 7.4.401 or later, files can NOT be read by Vim 7.3
Bram Moolenaar8f4ac012014-08-10 13:38:34 +02002348 and older. This adds a "seed" to the file, every time
2349 you write the file the encrypted bytes will be
2350 different. The whole undo file is encrypted, not just
2351 the pieces of text.
Bram Moolenaarf50a2532010-05-21 15:36:08 +02002352
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01002353 You should use "blowfish2", also to re-encrypt older files.
2354
Bram Moolenaar40e6a712010-05-16 22:32:54 +02002355 When reading an encrypted file 'cryptmethod' will be set automatically
Bram Moolenaarf50a2532010-05-21 15:36:08 +02002356 to the detected method of the file being read. Thus if you write it
2357 without changing 'cryptmethod' the same method will be used.
2358 Changing 'cryptmethod' does not mark the file as modified, you have to
Bram Moolenaar49771f42010-07-20 17:32:38 +02002359 explicitly write it, you don't get a warning unless there are other
2360 modifications. Also see |:X|.
2361
2362 When setting the global value to an empty string, it will end up with
Bram Moolenaara86187b2018-12-16 18:20:00 +01002363 the value "blowfish2". When setting the local value to an empty
2364 string the buffer will use the global value.
Bram Moolenaar49771f42010-07-20 17:32:38 +02002365
Bram Moolenaarf50a2532010-05-21 15:36:08 +02002366 When a new encryption method is added in a later version of Vim, and
2367 the current version does not recognize it, you will get *E821* .
Bram Moolenaar49771f42010-07-20 17:32:38 +02002368 You need to edit this file with the later version of Vim.
Bram Moolenaar40e6a712010-05-16 22:32:54 +02002369
2370
Bram Moolenaar071d4272004-06-13 20:20:40 +00002371 *'cscopepathcomp'* *'cspc'*
2372'cscopepathcomp' 'cspc' number (default 0)
2373 global
2374 {not available when compiled without the |+cscope|
2375 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002376 Determines how many components of the path to show in a list of tags.
2377 See |cscopepathcomp|.
Bram Moolenaar036986f2017-03-16 17:41:02 +01002378 NOTE: This option is set to 0 when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002379
2380 *'cscopeprg'* *'csprg'*
2381'cscopeprg' 'csprg' string (default "cscope")
2382 global
2383 {not available when compiled without the |+cscope|
2384 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002385 Specifies the command to execute cscope. See |cscopeprg|.
2386 This option cannot be set from a |modeline| or in the |sandbox|, for
2387 security reasons.
2388
2389 *'cscopequickfix'* *'csqf'*
2390'cscopequickfix' 'csqf' string (default "")
2391 global
2392 {not available when compiled without the |+cscope|
2393 or |+quickfix| features}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002394 Specifies whether to use quickfix window to show cscope results.
2395 See |cscopequickfix|.
2396
Bram Moolenaarec7944a2013-06-12 21:29:15 +02002397 *'cscoperelative'* *'csre'* *'nocscoperelative'* *'nocsre'*
Bram Moolenaar2f982e42011-06-12 20:42:22 +02002398'cscoperelative' 'csre' boolean (default off)
2399 global
2400 {not available when compiled without the |+cscope|
2401 feature}
Bram Moolenaar2f982e42011-06-12 20:42:22 +02002402 In the absence of a prefix (-P) for cscope. setting this option enables
2403 to use the basename of cscope.out path as the prefix.
2404 See |cscoperelative|.
Bram Moolenaar036986f2017-03-16 17:41:02 +01002405 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaar2f982e42011-06-12 20:42:22 +02002406
Bram Moolenaar071d4272004-06-13 20:20:40 +00002407 *'cscopetag'* *'cst'* *'nocscopetag'* *'nocst'*
2408'cscopetag' 'cst' boolean (default off)
2409 global
2410 {not available when compiled without the |+cscope|
2411 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002412 Use cscope for tag commands. See |cscope-options|.
2413 NOTE: This option is reset when 'compatible' is set.
2414
2415 *'cscopetagorder'* *'csto'*
2416'cscopetagorder' 'csto' number (default 0)
2417 global
2418 {not available when compiled without the |+cscope|
2419 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002420 Determines the order in which ":cstag" performs a search. See
2421 |cscopetagorder|.
2422 NOTE: This option is set to 0 when 'compatible' is set.
2423
2424 *'cscopeverbose'* *'csverb'*
2425 *'nocscopeverbose'* *'nocsverb'*
2426'cscopeverbose' 'csverb' boolean (default off)
2427 global
2428 {not available when compiled without the |+cscope|
2429 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002430 Give messages when adding a cscope database. See |cscopeverbose|.
2431 NOTE: This option is reset when 'compatible' is set.
2432
Bram Moolenaar860cae12010-06-05 23:22:07 +02002433 *'cursorbind'* *'crb'* *'nocursorbind'* *'nocrb'*
2434'cursorbind' 'crb' boolean (default off)
2435 local to window
Bram Moolenaar860cae12010-06-05 23:22:07 +02002436 When this option is set, as the cursor in the current
2437 window moves other cursorbound windows (windows that also have
2438 this option set) move their cursors to the corresponding line and
2439 column. This option is useful for viewing the
2440 differences between two versions of a file (see 'diff'); in diff mode,
2441 inserted and deleted lines (though not characters within a line) are
Bram Moolenaar1a384422010-07-14 19:53:30 +02002442 taken into account.
Bram Moolenaar860cae12010-06-05 23:22:07 +02002443
Bram Moolenaar600dddc2006-03-12 22:05:10 +00002444
2445 *'cursorcolumn'* *'cuc'* *'nocursorcolumn'* *'nocuc'*
2446'cursorcolumn' 'cuc' boolean (default off)
2447 local to window
Bram Moolenaardb84e452010-08-15 13:50:43 +02002448 {not available when compiled without the |+syntax|
Bram Moolenaar600dddc2006-03-12 22:05:10 +00002449 feature}
2450 Highlight the screen column of the cursor with CursorColumn
2451 |hl-CursorColumn|. Useful to align text. Will make screen redrawing
2452 slower.
Bram Moolenaar4c3f5362006-04-11 21:38:50 +00002453 If you only want the highlighting in the current window you can use
2454 these autocommands: >
2455 au WinLeave * set nocursorline nocursorcolumn
2456 au WinEnter * set cursorline cursorcolumn
2457<
Bram Moolenaar600dddc2006-03-12 22:05:10 +00002458
2459 *'cursorline'* *'cul'* *'nocursorline'* *'nocul'*
2460'cursorline' 'cul' boolean (default off)
2461 local to window
Bram Moolenaardb84e452010-08-15 13:50:43 +02002462 {not available when compiled without the |+syntax|
Bram Moolenaar600dddc2006-03-12 22:05:10 +00002463 feature}
Bram Moolenaar410e98a2019-09-09 22:05:49 +02002464 Highlight the text line of the cursor with CursorLine |hl-CursorLine|.
2465 Useful to easily spot the cursor. Will make screen redrawing slower.
Bram Moolenaare2f98b92006-03-29 21:18:24 +00002466 When Visual mode is active the highlighting isn't used to make it
Bram Moolenaar779b74b2006-04-10 14:55:34 +00002467 easier to see the selected text.
Bram Moolenaar600dddc2006-03-12 22:05:10 +00002468
2469
Bram Moolenaar410e98a2019-09-09 22:05:49 +02002470 *'cursorlineopt'* *'culopt'*
Bram Moolenaar017ba072019-09-14 21:01:23 +02002471'cursorlineopt' 'culopt' string (default: "number,line")
Bram Moolenaar410e98a2019-09-09 22:05:49 +02002472 local to window
2473 {not in Vi}
2474 {not available when compiled without the |+syntax|
2475 feature}
Bram Moolenaar017ba072019-09-14 21:01:23 +02002476 Comma separated list of settings for how 'cursorline' is displayed.
2477 Valid values:
2478 "line" Highlight the text line of the cursor with
Bram Moolenaar410e98a2019-09-09 22:05:49 +02002479 CursorLine |hl-CursorLine|.
Bram Moolenaar017ba072019-09-14 21:01:23 +02002480 "screenline" Highlight only the screen line of the cursor with
2481 CursorLine |hl-CursorLine|.
2482 "number" Highlight the line number of the cursor with
Bram Moolenaar410e98a2019-09-09 22:05:49 +02002483 CursorLineNr |hl-CursorLineNr|.
Bram Moolenaar017ba072019-09-14 21:01:23 +02002484
2485 Special value:
2486 "both" Alias for the values "line,number".
2487
2488 "line" and "screenline" cannot be used together.
Bram Moolenaar410e98a2019-09-09 22:05:49 +02002489
2490
Bram Moolenaar071d4272004-06-13 20:20:40 +00002491 *'debug'*
2492'debug' string (default "")
2493 global
Bram Moolenaar57657d82006-04-21 22:12:41 +00002494 These values can be used:
2495 msg Error messages that would otherwise be omitted will be given
2496 anyway.
2497 throw Error messages that would otherwise be omitted will be given
2498 anyway and also throw an exception and set |v:errmsg|.
2499 beep A message will be given when otherwise only a beep would be
2500 produced.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002501 The values can be combined, separated by a comma.
Bram Moolenaar57657d82006-04-21 22:12:41 +00002502 "msg" and "throw" are useful for debugging 'foldexpr', 'formatexpr' or
2503 'indentexpr'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002504
2505 *'define'* *'def'*
2506'define' 'def' string (default "^\s*#\s*define")
2507 global or local to buffer |global-local|
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002508 Pattern to be used to find a macro definition. It is a search
Bram Moolenaar071d4272004-06-13 20:20:40 +00002509 pattern, just like for the "/" command. This option is used for the
2510 commands like "[i" and "[d" |include-search|. The 'isident' option is
2511 used to recognize the defined name after the match:
2512 {match with 'define'}{non-ID chars}{defined name}{non-ID char}
2513 See |option-backslash| about inserting backslashes to include a space
2514 or backslash.
2515 The default value is for C programs. For C++ this value would be
2516 useful, to include const type declarations: >
2517 ^\(#\s*define\|[a-z]*\s*const\s*[a-z]*\)
Bram Moolenaar63b74a82019-03-24 15:09:13 +01002518< You can also use "\ze" just before the name and continue the pattern
2519 to check what is following. E.g. for Javascript, if a function is
2520 defined with "func_name = function(args)": >
2521 ^\s*\ze\i\+\s*=\s*function(
2522< If the function is defined with "func_name : function() {...": >
2523 ^\s*\ze\i\+\s*[:]\s*(*function\s*(
Bram Moolenaar071d4272004-06-13 20:20:40 +00002524< When using the ":set" command, you need to double the backslashes!
Bram Moolenaar63b74a82019-03-24 15:09:13 +01002525 To avoid that use `:let` with a single quote string: >
2526 let &l:define = '^\s*\ze\k\+\s*=\s*function('
Bram Moolenaar911ead12019-04-21 00:03:35 +02002527<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002528
2529 *'delcombine'* *'deco'* *'nodelcombine'* *'nodeco'*
2530'delcombine' 'deco' boolean (default off)
2531 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00002532 If editing Unicode and this option is set, backspace and Normal mode
2533 "x" delete each combining character on its own. When it is off (the
2534 default) the character along with its combining characters are
2535 deleted.
2536 Note: When 'delcombine' is set "xx" may work different from "2x"!
2537
2538 This is useful for Arabic, Hebrew and many other languages where one
2539 may have combining characters overtop of base characters, and want
2540 to remove only the combining ones.
Bram Moolenaar036986f2017-03-16 17:41:02 +01002541 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002542
2543 *'dictionary'* *'dict'*
2544'dictionary' 'dict' string (default "")
2545 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00002546 List of file names, separated by commas, that are used to lookup words
2547 for keyword completion commands |i_CTRL-X_CTRL-K|. Each file should
2548 contain a list of words. This can be one word per line, or several
2549 words per line, separated by non-keyword characters (white space is
2550 preferred). Maximum line length is 510 bytes.
Bram Moolenaar259f26a2018-05-15 22:25:40 +02002551
2552 When this option is empty or an entry "spell" is present, and spell
2553 checking is enabled, words in the word lists for the currently active
2554 'spelllang' are used. See |spell|.
2555
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002556 To include a comma in a file name precede it with a backslash. Spaces
Bram Moolenaar071d4272004-06-13 20:20:40 +00002557 after a comma are ignored, otherwise spaces are included in the file
2558 name. See |option-backslash| about using backslashes.
Bram Moolenaard8b02732005-01-14 21:48:43 +00002559 This has nothing to do with the |Dictionary| variable type.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002560 Where to find a list of words?
2561 - On FreeBSD, there is the file "/usr/share/dict/words".
2562 - In the Simtel archive, look in the "msdos/linguist" directory.
2563 - In "miscfiles" of the GNU collection.
2564 The use of |:set+=| and |:set-=| is preferred when adding or removing
2565 directories from the list. This avoids problems when a future version
2566 uses another default.
2567 Backticks cannot be used in this option for security reasons.
2568
2569 *'diff'* *'nodiff'*
2570'diff' boolean (default off)
2571 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00002572 {not available when compiled without the |+diff|
2573 feature}
2574 Join the current window in the group of windows that shows differences
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002575 between files. See |vimdiff|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002576
2577 *'dex'* *'diffexpr'*
2578'diffexpr' 'dex' string (default "")
2579 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00002580 {not available when compiled without the |+diff|
2581 feature}
Bram Moolenaare828b762018-09-10 17:51:58 +02002582 Expression which is evaluated to obtain a diff file (either ed-style
2583 or unified-style) from two versions of a file. See |diff-diffexpr|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002584 This option cannot be set from a |modeline| or in the |sandbox|, for
2585 security reasons.
2586
2587 *'dip'* *'diffopt'*
Bram Moolenaarc93262b2018-09-10 21:15:40 +02002588'diffopt' 'dip' string (default "internal,filler")
Bram Moolenaar071d4272004-06-13 20:20:40 +00002589 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00002590 {not available when compiled without the |+diff|
2591 feature}
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002592 Option settings for diff mode. It can consist of the following items.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002593 All are optional. Items must be separated by a comma.
2594
2595 filler Show filler lines, to keep the text
2596 synchronized with a window that has inserted
2597 lines at the same position. Mostly useful
2598 when windows are side-by-side and 'scrollbind'
2599 is set.
2600
2601 context:{n} Use a context of {n} lines between a change
2602 and a fold that contains unchanged lines.
2603 When omitted a context of six lines is used.
Bram Moolenaarf6b40102019-02-22 15:24:03 +01002604 When using zero the context is actually one,
2605 since folds require a line in between, also
2606 for a deleted line.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002607 See |fold-diff|.
2608
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002609 iblank Ignore changes where lines are all blank. Adds
2610 the "-B" flag to the "diff" command if
2611 'diffexpr' is empty. Check the documentation
2612 of the "diff" command for what this does
2613 exactly.
2614 NOTE: the diff windows will get out of sync,
2615 because no differences between blank lines are
2616 taken into account.
2617
Bram Moolenaar071d4272004-06-13 20:20:40 +00002618 icase Ignore changes in case of text. "a" and "A"
2619 are considered the same. Adds the "-i" flag
2620 to the "diff" command if 'diffexpr' is empty.
2621
2622 iwhite Ignore changes in amount of white space. Adds
2623 the "-b" flag to the "diff" command if
2624 'diffexpr' is empty. Check the documentation
2625 of the "diff" command for what this does
2626 exactly. It should ignore adding trailing
2627 white space, but not leading white space.
2628
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002629 iwhiteall Ignore all white space changes. Adds
2630 the "-w" flag to the "diff" command if
2631 'diffexpr' is empty. Check the documentation
2632 of the "diff" command for what this does
2633 exactly.
2634
2635 iwhiteeol Ignore white space changes at end of line.
2636 Adds the "-Z" flag to the "diff" command if
2637 'diffexpr' is empty. Check the documentation
2638 of the "diff" command for what this does
2639 exactly.
2640
Bram Moolenaar7d47b6e2006-03-15 22:59:18 +00002641 horizontal Start diff mode with horizontal splits (unless
2642 explicitly specified otherwise).
2643
2644 vertical Start diff mode with vertical splits (unless
2645 explicitly specified otherwise).
2646
Bram Moolenaar97ce4192017-12-01 20:35:58 +01002647 hiddenoff Do not use diff mode for a buffer when it
2648 becomes hidden.
2649
Bram Moolenaar7d47b6e2006-03-15 22:59:18 +00002650 foldcolumn:{n} Set the 'foldcolumn' option to {n} when
2651 starting diff mode. Without this 2 is used.
2652
Bram Moolenaare828b762018-09-10 17:51:58 +02002653 internal Use the internal diff library. This is
2654 ignored when 'diffexpr' is set. *E960*
2655 When running out of memory when writing a
2656 buffer this item will be ignored for diffs
2657 involving that buffer. Set the 'verbose'
2658 option to see when this happens.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002659
Bram Moolenaare828b762018-09-10 17:51:58 +02002660 indent-heuristic
Bram Moolenaarf0d58ef2018-11-16 16:13:44 +01002661 Use the indent heuristic for the internal
2662 diff library.
Bram Moolenaare828b762018-09-10 17:51:58 +02002663
2664 algorithm:{text} Use the specified diff algorithm with the
Bram Moolenaarf0d58ef2018-11-16 16:13:44 +01002665 internal diff engine. Currently supported
Bram Moolenaare828b762018-09-10 17:51:58 +02002666 algorithms are:
2667 myers the default algorithm
2668 minimal spend extra time to generate the
2669 smallest possible diff
2670 patience patience diff algorithm
2671 histogram histogram diff algorithm
2672
2673 Examples: >
2674 :set diffopt=internal,filler,context:4
Bram Moolenaar071d4272004-06-13 20:20:40 +00002675 :set diffopt=
Bram Moolenaare828b762018-09-10 17:51:58 +02002676 :set diffopt=internal,filler,foldcolumn:3
2677 :set diffopt-=internal " do NOT use the internal diff parser
Bram Moolenaar071d4272004-06-13 20:20:40 +00002678<
2679 *'digraph'* *'dg'* *'nodigraph'* *'nodg'*
2680'digraph' 'dg' boolean (default off)
2681 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00002682 {not available when compiled without the |+digraphs|
2683 feature}
2684 Enable the entering of digraphs in Insert mode with {char1} <BS>
2685 {char2}. See |digraphs|.
2686 NOTE: This option is reset when 'compatible' is set.
2687
2688 *'directory'* *'dir'*
2689'directory' 'dir' string (default for Amiga: ".,t:",
Bram Moolenaardfb18412013-12-11 18:53:29 +01002690 for MS-DOS and Win32: ".,$TEMP,c:\tmp,c:\temp"
Bram Moolenaar071d4272004-06-13 20:20:40 +00002691 for Unix: ".,~/tmp,/var/tmp,/tmp")
2692 global
2693 List of directory names for the swap file, separated with commas.
2694 - The swap file will be created in the first directory where this is
2695 possible.
2696 - Empty means that no swap file will be used (recovery is
2697 impossible!).
2698 - A directory "." means to put the swap file in the same directory as
2699 the edited file. On Unix, a dot is prepended to the file name, so
2700 it doesn't show in a directory listing. On MS-Windows the "hidden"
2701 attribute is set and a dot prepended if possible.
Bram Moolenaar009b2592004-10-24 19:18:58 +00002702 - A directory starting with "./" (or ".\" for MS-DOS et al.) means to
Bram Moolenaar071d4272004-06-13 20:20:40 +00002703 put the swap file relative to where the edited file is. The leading
2704 "." is replaced with the path name of the edited file.
Bram Moolenaarb782ba42018-08-07 21:39:28 +02002705 - For Unix and Win32, if a directory ends in two path separators "//",
2706 the swap file name will be built from the complete path to the file
2707 with all path separators substituted to percent '%' signs. This will
2708 ensure file name uniqueness in the preserve directory.
2709 On Win32, it is also possible to end with "\\". However, When a
2710 separating comma is following, you must use "//", since "\\" will
2711 include the comma in the file name. Therefore it is recommended to
2712 use '//', instead of '\\'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002713 - Spaces after the comma are ignored, other spaces are considered part
2714 of the directory name. To have a space at the start of a directory
2715 name, precede it with a backslash.
2716 - To include a comma in a directory name precede it with a backslash.
2717 - A directory name may end in an ':' or '/'.
2718 - Environment variables are expanded |:set_env|.
2719 - Careful with '\' characters, type one before a space, type two to
2720 get one in the option (see |option-backslash|), for example: >
2721 :set dir=c:\\tmp,\ dir\\,with\\,commas,\\\ dir\ with\ spaces
2722< - For backwards compatibility with Vim version 3.0 a '>' at the start
2723 of the option is removed.
2724 Using "." first in the list is recommended. This means that editing
2725 the same file twice will result in a warning. Using "/tmp" on Unix is
2726 discouraged: When the system crashes you lose the swap file.
2727 "/var/tmp" is often not cleared when rebooting, thus is a better
2728 choice than "/tmp". But it can contain a lot of files, your swap
2729 files get lost in the crowd. That is why a "tmp" directory in your
2730 home directory is tried first.
2731 The use of |:set+=| and |:set-=| is preferred when adding or removing
2732 directories from the list. This avoids problems when a future version
2733 uses another default.
2734 This option cannot be set from a |modeline| or in the |sandbox|, for
2735 security reasons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002736
2737 *'display'* *'dy'*
Bram Moolenaarbc8801c2016-08-02 21:04:33 +02002738'display' 'dy' string (default "", set to "truncate" in
2739 |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00002740 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00002741 Change the way text is displayed. This is comma separated list of
2742 flags:
2743 lastline When included, as much as possible of the last line
Bram Moolenaarad9c2a02016-07-27 23:26:04 +02002744 in a window will be displayed. "@@@" is put in the
2745 last columns of the last screen line to indicate the
2746 rest of the line is not displayed.
2747 truncate Like "lastline", but "@@@" is displayed in the first
2748 column of the last screen line. Overrules "lastline".
Bram Moolenaar071d4272004-06-13 20:20:40 +00002749 uhex Show unprintable characters hexadecimal as <xx>
2750 instead of using ^C and ~C.
2751
Bram Moolenaard0796902016-09-16 20:02:31 +02002752 When neither "lastline" nor "truncate" is included, a last line that
Bram Moolenaarad9c2a02016-07-27 23:26:04 +02002753 doesn't fit is replaced with "@" lines.
2754
Bram Moolenaar071d4272004-06-13 20:20:40 +00002755 *'eadirection'* *'ead'*
2756'eadirection' 'ead' string (default "both")
2757 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00002758 Tells when the 'equalalways' option applies:
2759 ver vertically, width of windows is not affected
2760 hor horizontally, height of windows is not affected
2761 both width and height of windows is affected
2762
2763 *'ed'* *'edcompatible'* *'noed'* *'noedcompatible'*
2764'edcompatible' 'ed' boolean (default off)
2765 global
2766 Makes the 'g' and 'c' flags of the ":substitute" command to be
2767 toggled each time the flag is given. See |complex-change|. See
2768 also 'gdefault' option.
Bram Moolenaarb4d6c3e2017-05-27 16:45:17 +02002769 Switching this option on may break plugins!
Bram Moolenaar071d4272004-06-13 20:20:40 +00002770
Bram Moolenaar03413f42016-04-12 21:07:15 +02002771 *'emoji'* *'emo'* *'noemoji'* *'noemo'*
Bram Moolenaar3848e002016-03-19 18:42:29 +01002772'emoji' 'emo' boolean (default: on)
2773 global
Bram Moolenaar3848e002016-03-19 18:42:29 +01002774 When on all Unicode emoji characters are considered to be full width.
2775
2776
Bram Moolenaar071d4272004-06-13 20:20:40 +00002777 *'encoding'* *'enc'* *E543*
2778'encoding' 'enc' string (default: "latin1" or value from $LANG)
2779 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00002780 Sets the character encoding used inside Vim. It applies to text in
2781 the buffers, registers, Strings in expressions, text stored in the
2782 viminfo file, etc. It sets the kind of characters which Vim can work
2783 with. See |encoding-names| for the possible values.
2784
2785 NOTE: Changing this option will not change the encoding of the
Bram Moolenaar1cd871b2004-12-19 22:46:22 +00002786 existing text in Vim. It may cause non-ASCII text to become invalid.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002787 It should normally be kept at its default value, or set when Vim
Bram Moolenaar02467872007-05-06 13:22:01 +00002788 starts up. See |multibyte|. To reload the menus see |:menutrans|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002789
Bram Moolenaar865242e2010-07-14 21:12:05 +02002790 This option cannot be set from a |modeline|. It would most likely
2791 corrupt the text.
2792
Bram Moolenaar3df01732017-02-17 22:47:16 +01002793 NOTE: For GTK+ 2 or later, it is highly recommended to set 'encoding'
2794 to "utf-8". Although care has been taken to allow different values of
Bram Moolenaar071d4272004-06-13 20:20:40 +00002795 'encoding', "utf-8" is the natural choice for the environment and
2796 avoids unnecessary conversion overhead. "utf-8" has not been made
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002797 the default to prevent different behavior of the GUI and terminal
Bram Moolenaar071d4272004-06-13 20:20:40 +00002798 versions, and to avoid changing the encoding of newly created files
2799 without your knowledge (in case 'fileencodings' is empty).
2800
2801 The character encoding of files can be different from 'encoding'.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002802 This is specified with 'fileencoding'. The conversion is done with
Bram Moolenaar071d4272004-06-13 20:20:40 +00002803 iconv() or as specified with 'charconvert'.
2804
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002805 If you need to know whether 'encoding' is a multi-byte encoding, you
2806 can use: >
2807 if has("multi_byte_encoding")
2808<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002809 Normally 'encoding' will be equal to your current locale. This will
2810 be the default if Vim recognizes your environment settings. If
2811 'encoding' is not set to the current locale, 'termencoding' must be
2812 set to convert typed and displayed text. See |encoding-table|.
2813
2814 When you set this option, it fires the |EncodingChanged| autocommand
2815 event so that you can set up fonts if necessary.
2816
2817 When the option is set, the value is converted to lowercase. Thus
2818 you can set it with uppercase values too. Underscores are translated
2819 to '-' signs.
2820 When the encoding is recognized, it is changed to the standard name.
2821 For example "Latin-1" becomes "latin1", "ISO_88592" becomes
2822 "iso-8859-2" and "utf8" becomes "utf-8".
2823
2824 Note: "latin1" is also used when the encoding could not be detected.
2825 This only works when editing files in the same encoding! When the
2826 actual character set is not latin1, make sure 'fileencoding' and
2827 'fileencodings' are empty. When conversion is needed, switch to using
2828 utf-8.
2829
2830 When "unicode", "ucs-2" or "ucs-4" is used, Vim internally uses utf-8.
2831 You don't notice this while editing, but it does matter for the
2832 |viminfo-file|. And Vim expects the terminal to use utf-8 too. Thus
2833 setting 'encoding' to one of these values instead of utf-8 only has
2834 effect for encoding used for files when 'fileencoding' is empty.
2835
Bram Moolenaar661b1822005-07-28 22:36:45 +00002836 When 'encoding' is set to a Unicode encoding, and 'fileencodings' was
2837 not set yet, the default for 'fileencodings' is changed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002838
2839 *'endofline'* *'eol'* *'noendofline'* *'noeol'*
2840'endofline' 'eol' boolean (default on)
2841 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00002842 When writing a file and this option is off and the 'binary' option
Bram Moolenaar34d72d42015-07-17 14:18:08 +02002843 is on, or 'fixeol' option is off, no <EOL> will be written for the
2844 last line in the file. This option is automatically set or reset when
2845 starting to edit a new file, depending on whether file has an <EOL>
2846 for the last line in the file. Normally you don't have to set or
2847 reset this option.
2848 When 'binary' is off and 'fixeol' is on the value is not used when
2849 writing the file. When 'binary' is on or 'fixeol' is off it is used
2850 to remember the presence of a <EOL> for the last line in the file, so
2851 that when you write the file the situation from the original file can
2852 be kept. But you can change it if you want to.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002853
2854 *'equalalways'* *'ea'* *'noequalalways'* *'noea'*
2855'equalalways' 'ea' boolean (default on)
2856 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00002857 When on, all the windows are automatically made the same size after
Bram Moolenaar009b2592004-10-24 19:18:58 +00002858 splitting or closing a window. This also happens the moment the
2859 option is switched on. When off, splitting a window will reduce the
2860 size of the current window and leave the other windows the same. When
2861 closing a window the extra lines are given to the window next to it
2862 (depending on 'splitbelow' and 'splitright').
Bram Moolenaar071d4272004-06-13 20:20:40 +00002863 When mixing vertically and horizontally split windows, a minimal size
2864 is computed and some windows may be larger if there is room. The
2865 'eadirection' option tells in which direction the size is affected.
Bram Moolenaar67f71312007-08-12 14:55:56 +00002866 Changing the height and width of a window can be avoided by setting
2867 'winfixheight' and 'winfixwidth', respectively.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002868 If a window size is specified when creating a new window sizes are
2869 currently not equalized (it's complicated, but may be implemented in
2870 the future).
Bram Moolenaar071d4272004-06-13 20:20:40 +00002871
2872 *'equalprg'* *'ep'*
2873'equalprg' 'ep' string (default "")
2874 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00002875 External program to use for "=" command. When this option is empty
Bram Moolenaar446cb832008-06-24 21:56:24 +00002876 the internal formatting functions are used; either 'lisp', 'cindent'
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002877 or 'indentexpr'. When Vim was compiled without internal formatting,
2878 the "indent" program is used.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002879 Environment variables are expanded |:set_env|. See |option-backslash|
Bram Moolenaar071d4272004-06-13 20:20:40 +00002880 about including spaces and backslashes.
2881 This option cannot be set from a |modeline| or in the |sandbox|, for
2882 security reasons.
2883
2884 *'errorbells'* *'eb'* *'noerrorbells'* *'noeb'*
2885'errorbells' 'eb' boolean (default off)
2886 global
2887 Ring the bell (beep or screen flash) for error messages. This only
2888 makes a difference for error messages, the bell will be used always
2889 for a lot of errors without a message (e.g., hitting <Esc> in Normal
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002890 mode). See 'visualbell' on how to make the bell behave like a beep,
Bram Moolenaar165bc692015-07-21 17:53:25 +02002891 screen flash or do nothing. See 'belloff' to finetune when to ring the
2892 bell.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002893
2894 *'errorfile'* *'ef'*
2895'errorfile' 'ef' string (Amiga default: "AztecC.Err",
2896 others: "errors.err")
2897 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00002898 {not available when compiled without the |+quickfix|
2899 feature}
2900 Name of the errorfile for the QuickFix mode (see |:cf|).
2901 When the "-q" command-line argument is used, 'errorfile' is set to the
2902 following argument. See |-q|.
2903 NOT used for the ":make" command. See 'makeef' for that.
2904 Environment variables are expanded |:set_env|.
2905 See |option-backslash| about including spaces and backslashes.
2906 This option cannot be set from a |modeline| or in the |sandbox|, for
2907 security reasons.
2908
2909 *'errorformat'* *'efm'*
2910'errorformat' 'efm' string (default is very long)
2911 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00002912 {not available when compiled without the |+quickfix|
2913 feature}
2914 Scanf-like description of the format for the lines in the error file
2915 (see |errorformat|).
2916
2917 *'esckeys'* *'ek'* *'noesckeys'* *'noek'*
2918'esckeys' 'ek' boolean (Vim default: on, Vi default: off)
2919 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00002920 Function keys that start with an <Esc> are recognized in Insert
2921 mode. When this option is off, the cursor and function keys cannot be
2922 used in Insert mode if they start with an <Esc>. The advantage of
2923 this is that the single <Esc> is recognized immediately, instead of
2924 after one second. Instead of resetting this option, you might want to
2925 try changing the values for 'timeoutlen' and 'ttimeoutlen'. Note that
2926 when 'esckeys' is off, you can still map anything, but the cursor keys
2927 won't work by default.
2928 NOTE: This option is set to the Vi default value when 'compatible' is
2929 set and to the Vim default value when 'compatible' is reset.
2930
2931 *'eventignore'* *'ei'*
2932'eventignore' 'ei' string (default "")
2933 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00002934 A list of autocommand event names, which are to be ignored.
Bram Moolenaarf193fff2006-04-27 00:02:13 +00002935 When set to "all" or when "all" is one of the items, all autocommand
2936 events are ignored, autocommands will not be executed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002937 Otherwise this is a comma separated list of event names. Example: >
2938 :set ei=WinEnter,WinLeave
2939<
2940 *'expandtab'* *'et'* *'noexpandtab'* *'noet'*
2941'expandtab' 'et' boolean (default off)
2942 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00002943 In Insert mode: Use the appropriate number of spaces to insert a
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002944 <Tab>. Spaces are used in indents with the '>' and '<' commands and
Bram Moolenaar071d4272004-06-13 20:20:40 +00002945 when 'autoindent' is on. To insert a real tab when 'expandtab' is
2946 on, use CTRL-V<Tab>. See also |:retab| and |ins-expandtab|.
Bram Moolenaarca635012015-09-25 20:34:21 +02002947 This option is reset when the 'paste' option is set and restored when
2948 the 'paste' option is reset.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002949 NOTE: This option is reset when 'compatible' is set.
2950
2951 *'exrc'* *'ex'* *'noexrc'* *'noex'*
2952'exrc' 'ex' boolean (default off)
2953 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00002954 Enables the reading of .vimrc, .exrc and .gvimrc in the current
Bram Moolenaar36f44c22016-08-28 18:17:20 +02002955 directory.
2956
2957 Setting this option is a potential security leak. E.g., consider
2958 unpacking a package or fetching files from github, a .vimrc in there
2959 might be a trojan horse. BETTER NOT SET THIS OPTION!
2960 Instead, define an autocommand in your .vimrc to set options for a
2961 matching directory.
2962
2963 If you do switch this option on you should also consider setting the
2964 'secure' option (see |initialization|).
2965 Also see |.vimrc| and |gui-init|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002966 This option cannot be set from a |modeline| or in the |sandbox|, for
2967 security reasons.
2968
2969 *'fileencoding'* *'fenc'* *E213*
2970'fileencoding' 'fenc' string (default: "")
2971 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00002972 Sets the character encoding for the file of this buffer.
Bram Moolenaar865242e2010-07-14 21:12:05 +02002973
Bram Moolenaar071d4272004-06-13 20:20:40 +00002974 When 'fileencoding' is different from 'encoding', conversion will be
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002975 done when writing the file. For reading see below.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002976 When 'fileencoding' is empty, the same value as 'encoding' will be
2977 used (no conversion when reading or writing a file).
Bram Moolenaar214641f2017-03-05 17:04:09 +01002978 No error will be given when the value is set, only when it is used,
2979 only when writing a file.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002980 Conversion will also be done when 'encoding' and 'fileencoding' are
2981 both a Unicode encoding and 'fileencoding' is not utf-8. That's
2982 because internally Unicode is always stored as utf-8.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002983 WARNING: Conversion can cause loss of information! When
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002984 'encoding' is "utf-8" or another Unicode encoding, conversion
2985 is most likely done in a way that the reverse conversion
2986 results in the same text. When 'encoding' is not "utf-8" some
2987 characters may be lost!
Bram Moolenaar865242e2010-07-14 21:12:05 +02002988
Bram Moolenaar071d4272004-06-13 20:20:40 +00002989 See 'encoding' for the possible values. Additionally, values may be
2990 specified that can be handled by the converter, see
2991 |mbyte-conversion|.
Bram Moolenaar865242e2010-07-14 21:12:05 +02002992
Bram Moolenaar071d4272004-06-13 20:20:40 +00002993 When reading a file 'fileencoding' will be set from 'fileencodings'.
2994 To read a file in a certain encoding it won't work by setting
Bram Moolenaar02467872007-05-06 13:22:01 +00002995 'fileencoding', use the |++enc| argument. One exception: when
2996 'fileencodings' is empty the value of 'fileencoding' is used.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00002997 For a new file the global value of 'fileencoding' is used.
Bram Moolenaar865242e2010-07-14 21:12:05 +02002998
Bram Moolenaar071d4272004-06-13 20:20:40 +00002999 Prepending "8bit-" and "2byte-" has no meaning here, they are ignored.
3000 When the option is set, the value is converted to lowercase. Thus
3001 you can set it with uppercase values too. '_' characters are
3002 replaced with '-'. If a name is recognized from the list for
3003 'encoding', it is replaced by the standard name. For example
3004 "ISO8859-2" becomes "iso-8859-2".
Bram Moolenaar865242e2010-07-14 21:12:05 +02003005
Bram Moolenaar071d4272004-06-13 20:20:40 +00003006 When this option is set, after starting to edit a file, the 'modified'
3007 option is set, because the file would be different when written.
Bram Moolenaar865242e2010-07-14 21:12:05 +02003008
3009 Keep in mind that changing 'fenc' from a modeline happens
3010 AFTER the text has been read, thus it applies to when the file will be
3011 written. If you do set 'fenc' in a modeline, you might want to set
3012 'nomodified' to avoid not being able to ":q".
3013
Bram Moolenaar071d4272004-06-13 20:20:40 +00003014 This option can not be changed when 'modifiable' is off.
3015
3016 *'fe'*
3017 NOTE: Before version 6.0 this option specified the encoding for the
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003018 whole of Vim, this was a mistake. Now use 'encoding' instead. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00003019 old short name was 'fe', which is no longer used.
3020
3021 *'fileencodings'* *'fencs'*
Bram Moolenaar1cd871b2004-12-19 22:46:22 +00003022'fileencodings' 'fencs' string (default: "ucs-bom",
3023 "ucs-bom,utf-8,default,latin1" when
3024 'encoding' is set to a Unicode value)
Bram Moolenaar071d4272004-06-13 20:20:40 +00003025 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003026 This is a list of character encodings considered when starting to edit
3027 an existing file. When a file is read, Vim tries to use the first
3028 mentioned character encoding. If an error is detected, the next one
3029 in the list is tried. When an encoding is found that works,
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003030 'fileencoding' is set to it. If all fail, 'fileencoding' is set to
Bram Moolenaar071d4272004-06-13 20:20:40 +00003031 an empty string, which means the value of 'encoding' is used.
3032 WARNING: Conversion can cause loss of information! When
3033 'encoding' is "utf-8" (or one of the other Unicode variants)
3034 conversion is most likely done in a way that the reverse
3035 conversion results in the same text. When 'encoding' is not
Bram Moolenaarc6d8db72005-12-13 20:04:55 +00003036 "utf-8" some non-ASCII characters may be lost! You can use
3037 the |++bad| argument to specify what is done with characters
3038 that can't be converted.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003039 For an empty file or a file with only ASCII characters most encodings
3040 will work and the first entry of 'fileencodings' will be used (except
3041 "ucs-bom", which requires the BOM to be present). If you prefer
3042 another encoding use an BufReadPost autocommand event to test if your
3043 preferred encoding is to be used. Example: >
3044 au BufReadPost * if search('\S', 'w') == 0 |
3045 \ set fenc=iso-2022-jp | endif
3046< This sets 'fileencoding' to "iso-2022-jp" if the file does not contain
3047 non-blank characters.
Bram Moolenaarc6d8db72005-12-13 20:04:55 +00003048 When the |++enc| argument is used then the value of 'fileencodings' is
3049 not used.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003050 Note that 'fileencodings' is not used for a new file, the global value
3051 of 'fileencoding' is used instead. You can set it with: >
3052 :setglobal fenc=iso-8859-2
3053< This means that a non-existing file may get a different encoding than
3054 an empty file.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003055 The special value "ucs-bom" can be used to check for a Unicode BOM
3056 (Byte Order Mark) at the start of the file. It must not be preceded
3057 by "utf-8" or another Unicode encoding for this to work properly.
3058 An entry for an 8-bit encoding (e.g., "latin1") should be the last,
3059 because Vim cannot detect an error, thus the encoding is always
3060 accepted.
Bram Moolenaar1cd871b2004-12-19 22:46:22 +00003061 The special value "default" can be used for the encoding from the
3062 environment. This is the default value for 'encoding'. It is useful
3063 when 'encoding' is set to "utf-8" and your environment uses a
3064 non-latin1 encoding, such as Russian.
Bram Moolenaarca003e12006-03-17 23:19:38 +00003065 When 'encoding' is "utf-8" and a file contains an illegal byte
3066 sequence it won't be recognized as UTF-8. You can use the |8g8|
3067 command to find the illegal byte sequence.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003068 WRONG VALUES: WHAT'S WRONG:
3069 latin1,utf-8 "latin1" will always be used
3070 utf-8,ucs-bom,latin1 BOM won't be recognized in an utf-8
3071 file
3072 cp1250,latin1 "cp1250" will always be used
3073 If 'fileencodings' is empty, 'fileencoding' is not modified.
3074 See 'fileencoding' for the possible values.
3075 Setting this option does not have an effect until the next time a file
3076 is read.
3077
3078 *'fileformat'* *'ff'*
Bram Moolenaar00590742019-02-15 21:06:09 +01003079'fileformat' 'ff' string (MS-Windows default: "dos",
3080 Unix, macOS default: "unix")
Bram Moolenaar071d4272004-06-13 20:20:40 +00003081 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00003082 This gives the <EOL> of the current buffer, which is used for
3083 reading/writing the buffer from/to a file:
3084 dos <CR> <NL>
3085 unix <NL>
3086 mac <CR>
3087 When "dos" is used, CTRL-Z at the end of a file is ignored.
3088 See |file-formats| and |file-read|.
3089 For the character encoding of the file see 'fileencoding'.
3090 When 'binary' is set, the value of 'fileformat' is ignored, file I/O
Bram Moolenaarbf884932013-04-05 22:26:15 +02003091 works like it was set to "unix".
Bram Moolenaar071d4272004-06-13 20:20:40 +00003092 This option is set automatically when starting to edit a file and
3093 'fileformats' is not empty and 'binary' is off.
3094 When this option is set, after starting to edit a file, the 'modified'
3095 option is set, because the file would be different when written.
3096 This option can not be changed when 'modifiable' is off.
3097 For backwards compatibility: When this option is set to "dos",
3098 'textmode' is set, otherwise 'textmode' is reset.
3099
3100 *'fileformats'* *'ffs'*
3101'fileformats' 'ffs' string (default:
Bram Moolenaar00590742019-02-15 21:06:09 +01003102 Vim+Vi MS-Windows: "dos,unix",
3103 Vim Unix, macOS: "unix,dos",
Bram Moolenaar071d4272004-06-13 20:20:40 +00003104 Vi Cygwin: "unix,dos",
3105 Vi others: "")
3106 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003107 This gives the end-of-line (<EOL>) formats that will be tried when
3108 starting to edit a new buffer and when reading a file into an existing
3109 buffer:
3110 - When empty, the format defined with 'fileformat' will be used
3111 always. It is not set automatically.
3112 - When set to one name, that format will be used whenever a new buffer
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003113 is opened. 'fileformat' is set accordingly for that buffer. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00003114 'fileformats' name will be used when a file is read into an existing
3115 buffer, no matter what 'fileformat' for that buffer is set to.
3116 - When more than one name is present, separated by commas, automatic
3117 <EOL> detection will be done when reading a file. When starting to
3118 edit a file, a check is done for the <EOL>:
3119 1. If all lines end in <CR><NL>, and 'fileformats' includes "dos",
3120 'fileformat' is set to "dos".
3121 2. If a <NL> is found and 'fileformats' includes "unix", 'fileformat'
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003122 is set to "unix". Note that when a <NL> is found without a
Bram Moolenaar071d4272004-06-13 20:20:40 +00003123 preceding <CR>, "unix" is preferred over "dos".
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01003124 3. If 'fileformat' has not yet been set, and if a <CR> is found, and
3125 if 'fileformats' includes "mac", 'fileformat' is set to "mac".
Bram Moolenaar00659062010-09-21 22:34:02 +02003126 This means that "mac" is only chosen when:
3127 "unix" is not present or no <NL> is found in the file, and
3128 "dos" is not present or no <CR><NL> is found in the file.
3129 Except: if "unix" was chosen, but there is a <CR> before
3130 the first <NL>, and there appear to be more <CR>s than <NL>s in
Bram Moolenaar166af9b2010-11-16 20:34:40 +01003131 the first few lines, "mac" is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003132 4. If 'fileformat' is still not set, the first name from
3133 'fileformats' is used.
3134 When reading a file into an existing buffer, the same is done, but
3135 this happens like 'fileformat' has been set appropriately for that
3136 file only, the option is not changed.
3137 When 'binary' is set, the value of 'fileformats' is not used.
3138
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01003139 When Vim starts up with an empty buffer the first item is used. You
3140 can overrule this by setting 'fileformat' in your .vimrc.
Bram Moolenaar81af9252010-12-10 20:35:50 +01003141
Bram Moolenaar071d4272004-06-13 20:20:40 +00003142 For systems with a Dos-like <EOL> (<CR><NL>), when reading files that
3143 are ":source"ed and for vimrc files, automatic <EOL> detection may be
3144 done:
3145 - When 'fileformats' is empty, there is no automatic detection. Dos
3146 format will be used.
3147 - When 'fileformats' is set to one or more names, automatic detection
3148 is done. This is based on the first <NL> in the file: If there is a
3149 <CR> in front of it, Dos format is used, otherwise Unix format is
3150 used.
3151 Also see |file-formats|.
3152 For backwards compatibility: When this option is set to an empty
3153 string or one format (no comma is included), 'textauto' is reset,
3154 otherwise 'textauto' is set.
3155 NOTE: This option is set to the Vi default value when 'compatible' is
3156 set and to the Vim default value when 'compatible' is reset.
3157
Bram Moolenaarbf884932013-04-05 22:26:15 +02003158 *'fileignorecase'* *'fic'* *'nofileignorecase'* *'nofic'*
3159'fileignorecase' 'fic' boolean (default on for systems where case in file
3160 names is normally ignored)
Bram Moolenaar71afbfe2013-03-19 16:49:16 +01003161 global
Bram Moolenaar71afbfe2013-03-19 16:49:16 +01003162 When set case is ignored when using file names and directories.
3163 See 'wildignorecase' for only ignoring case when doing completion.
3164
Bram Moolenaar071d4272004-06-13 20:20:40 +00003165 *'filetype'* *'ft'*
3166'filetype' 'ft' string (default: "")
3167 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00003168 When this option is set, the FileType autocommand event is triggered.
3169 All autocommands that match with the value of this option will be
3170 executed. Thus the value of 'filetype' is used in place of the file
3171 name.
3172 Otherwise this option does not always reflect the current file type.
3173 This option is normally set when the file type is detected. To enable
3174 this use the ":filetype on" command. |:filetype|
3175 Setting this option to a different value is most useful in a modeline,
3176 for a file for which the file type is not automatically recognized.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00003177 Example, for in an IDL file:
3178 /* vim: set filetype=idl : */ ~
3179 |FileType| |filetypes|
3180 When a dot appears in the value then this separates two filetype
3181 names. Example:
3182 /* vim: set filetype=c.doxygen : */ ~
3183 This will use the "c" filetype first, then the "doxygen" filetype.
3184 This works both for filetype plugins and for syntax files. More than
3185 one dot may appear.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003186 This option is not copied to another buffer, independent of the 's' or
3187 'S' flag in 'cpoptions'.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00003188 Only normal file name characters can be used, "/\*?[|<>" are illegal.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003189
3190 *'fillchars'* *'fcs'*
3191'fillchars' 'fcs' string (default "vert:|,fold:-")
3192 global
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02003193 {not available when compiled without the |+folding|
3194 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00003195 Characters to fill the statuslines and vertical separators.
3196 It is a comma separated list of items:
3197
3198 item default Used for ~
3199 stl:c ' ' or '^' statusline of the current window
Bram Moolenaar38a55632016-02-15 22:07:32 +01003200 stlnc:c ' ' or '=' statusline of the non-current windows
Bram Moolenaar071d4272004-06-13 20:20:40 +00003201 vert:c '|' vertical separators |:vsplit|
3202 fold:c '-' filling 'foldtext'
3203 diff:c '-' deleted lines of the 'diff' option
3204
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003205 Any one that is omitted will fall back to the default. For "stl" and
Bram Moolenaar38a55632016-02-15 22:07:32 +01003206 "stlnc" the space will be used when there is highlighting, '^' or '='
Bram Moolenaar071d4272004-06-13 20:20:40 +00003207 otherwise.
3208
3209 Example: >
Bram Moolenaar38a55632016-02-15 22:07:32 +01003210 :set fillchars=stl:^,stlnc:=,vert:\|,fold:-,diff:-
Bram Moolenaar071d4272004-06-13 20:20:40 +00003211< This is similar to the default, except that these characters will also
3212 be used when there is highlighting.
3213
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003214 for "stl" and "stlnc" only single-byte values are supported.
3215
Bram Moolenaar071d4272004-06-13 20:20:40 +00003216 The highlighting used for these items:
3217 item highlight group ~
3218 stl:c StatusLine |hl-StatusLine|
3219 stlnc:c StatusLineNC |hl-StatusLineNC|
3220 vert:c VertSplit |hl-VertSplit|
3221 fold:c Folded |hl-Folded|
3222 diff:c DiffDelete |hl-DiffDelete|
3223
Bram Moolenaar34d72d42015-07-17 14:18:08 +02003224 *'fixendofline'* *'fixeol'* *'nofixendofline'* *'nofixeol'*
3225'fixendofline' 'fixeol' boolean (default on)
3226 local to buffer
Bram Moolenaar34d72d42015-07-17 14:18:08 +02003227 When writing a file and this option is on, <EOL> at the end of file
3228 will be restored if missing. Turn this option off if you want to
3229 preserve the situation from the original file.
3230 When the 'binary' option is set the value of this option doesn't
3231 matter.
3232 See the 'endofline' option.
3233
Bram Moolenaar071d4272004-06-13 20:20:40 +00003234 *'fkmap'* *'fk'* *'nofkmap'* *'nofk'*
3235'fkmap' 'fk' boolean (default off) *E198*
3236 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003237 {only available when compiled with the |+rightleft|
3238 feature}
Bram Moolenaar14184a32019-02-16 15:10:30 +01003239 This option was for using Farsi, which has been removed. See
3240 |farsi.txt|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003241
3242 *'foldclose'* *'fcl'*
3243'foldclose' 'fcl' string (default "")
3244 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003245 {not available when compiled without the |+folding|
3246 feature}
3247 When set to "all", a fold is closed when the cursor isn't in it and
3248 its level is higher than 'foldlevel'. Useful if you want folds to
3249 automatically close when moving out of them.
3250
3251 *'foldcolumn'* *'fdc'*
3252'foldcolumn' 'fdc' number (default 0)
3253 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003254 {not available when compiled without the |+folding|
3255 feature}
3256 When non-zero, a column with the specified width is shown at the side
3257 of the window which indicates open and closed folds. The maximum
3258 value is 12.
3259 See |folding|.
3260
3261 *'foldenable'* *'fen'* *'nofoldenable'* *'nofen'*
3262'foldenable' 'fen' boolean (default on)
3263 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003264 {not available when compiled without the |+folding|
3265 feature}
3266 When off, all folds are open. This option can be used to quickly
3267 switch between showing all text unfolded and viewing the text with
3268 folds (including manually opened or closed folds). It can be toggled
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003269 with the |zi| command. The 'foldcolumn' will remain blank when
Bram Moolenaar071d4272004-06-13 20:20:40 +00003270 'foldenable' is off.
3271 This option is set by commands that create a new fold or close a fold.
3272 See |folding|.
3273
3274 *'foldexpr'* *'fde'*
3275'foldexpr' 'fde' string (default: "0")
3276 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003277 {not available when compiled without the |+folding|
Bram Moolenaardb84e452010-08-15 13:50:43 +02003278 or |+eval| features}
Bram Moolenaar071d4272004-06-13 20:20:40 +00003279 The expression used for when 'foldmethod' is "expr". It is evaluated
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00003280 for each line to obtain its fold level. See |fold-expr|.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00003281
Bram Moolenaar30b65812012-07-12 22:01:11 +02003282 The expression will be evaluated in the |sandbox| if set from a
3283 modeline, see |sandbox-option|.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003284 This option can't be set from a |modeline| when the 'diff' option is
Bram Moolenaar110289e2019-05-23 15:38:06 +02003285 on or the 'modelineexpr' option is off.
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00003286
3287 It is not allowed to change text or jump to another window while
3288 evaluating 'foldexpr' |textlock|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003289
3290 *'foldignore'* *'fdi'*
3291'foldignore' 'fdi' string (default: "#")
3292 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003293 {not available when compiled without the |+folding|
3294 feature}
3295 Used only when 'foldmethod' is "indent". Lines starting with
3296 characters in 'foldignore' will get their fold level from surrounding
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003297 lines. White space is skipped before checking for this character.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003298 The default "#" works well for C programs. See |fold-indent|.
3299
3300 *'foldlevel'* *'fdl'*
3301'foldlevel' 'fdl' number (default: 0)
3302 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003303 {not available when compiled without the |+folding|
3304 feature}
3305 Sets the fold level: Folds with a higher level will be closed.
3306 Setting this option to zero will close all folds. Higher numbers will
3307 close fewer folds.
3308 This option is set by commands like |zm|, |zM| and |zR|.
3309 See |fold-foldlevel|.
3310
3311 *'foldlevelstart'* *'fdls'*
3312'foldlevelstart' 'fdls' number (default: -1)
3313 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003314 {not available when compiled without the |+folding|
3315 feature}
3316 Sets 'foldlevel' when starting to edit another buffer in a window.
3317 Useful to always start editing with all folds closed (value zero),
3318 some folds closed (one) or no folds closed (99).
3319 This is done before reading any modeline, thus a setting in a modeline
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003320 overrules this option. Starting to edit a file for |diff-mode| also
Bram Moolenaar071d4272004-06-13 20:20:40 +00003321 ignores this option and closes all folds.
3322 It is also done before BufReadPre autocommands, to allow an autocmd to
3323 overrule the 'foldlevel' value for specific files.
3324 When the value is negative, it is not used.
3325
3326 *'foldmarker'* *'fmr'* *E536*
3327'foldmarker' 'fmr' string (default: "{{{,}}}")
3328 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003329 {not available when compiled without the |+folding|
3330 feature}
3331 The start and end marker used when 'foldmethod' is "marker". There
3332 must be one comma, which separates the start and end marker. The
3333 marker is a literal string (a regular expression would be too slow).
3334 See |fold-marker|.
3335
3336 *'foldmethod'* *'fdm'*
3337'foldmethod' 'fdm' string (default: "manual")
3338 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003339 {not available when compiled without the |+folding|
3340 feature}
3341 The kind of folding used for the current window. Possible values:
3342 |fold-manual| manual Folds are created manually.
3343 |fold-indent| indent Lines with equal indent form a fold.
3344 |fold-expr| expr 'foldexpr' gives the fold level of a line.
3345 |fold-marker| marker Markers are used to specify folds.
3346 |fold-syntax| syntax Syntax highlighting items specify folds.
3347 |fold-diff| diff Fold text that is not changed.
3348
3349 *'foldminlines'* *'fml'*
3350'foldminlines' 'fml' number (default: 1)
3351 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003352 {not available when compiled without the |+folding|
3353 feature}
Bram Moolenaar00654022011-02-25 14:42:19 +01003354 Sets the number of screen lines above which a fold can be displayed
3355 closed. Also for manually closed folds. With the default value of
3356 one a fold can only be closed if it takes up two or more screen lines.
3357 Set to zero to be able to close folds of just one screen line.
Bram Moolenaar446beb42011-05-10 17:18:44 +02003358 Note that this only has an effect on what is displayed. After using
Bram Moolenaar071d4272004-06-13 20:20:40 +00003359 "zc" to close a fold, which is displayed open because it's smaller
3360 than 'foldminlines', a following "zc" may close a containing fold.
3361
3362 *'foldnestmax'* *'fdn'*
3363'foldnestmax' 'fdn' number (default: 20)
3364 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003365 {not available when compiled without the |+folding|
3366 feature}
3367 Sets the maximum nesting of folds for the "indent" and "syntax"
3368 methods. This avoids that too many folds will be created. Using more
3369 than 20 doesn't work, because the internal limit is 20.
3370
3371 *'foldopen'* *'fdo'*
3372'foldopen' 'fdo' string (default: "block,hor,mark,percent,quickfix,
3373 search,tag,undo")
3374 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003375 {not available when compiled without the |+folding|
3376 feature}
3377 Specifies for which type of commands folds will be opened, if the
3378 command moves the cursor into a closed fold. It is a comma separated
3379 list of items.
Bram Moolenaar05365702010-10-27 18:34:44 +02003380 NOTE: When the command is part of a mapping this option is not used.
3381 Add the |zv| command to the mapping to get the same effect.
3382 (rationale: the mapping may want to control opening folds itself)
3383
Bram Moolenaar071d4272004-06-13 20:20:40 +00003384 item commands ~
3385 all any
3386 block "(", "{", "[[", "[{", etc.
3387 hor horizontal movements: "l", "w", "fx", etc.
3388 insert any command in Insert mode
3389 jump far jumps: "G", "gg", etc.
3390 mark jumping to a mark: "'m", CTRL-O, etc.
3391 percent "%"
3392 quickfix ":cn", ":crew", ":make", etc.
3393 search search for a pattern: "/", "n", "*", "gd", etc.
3394 (not for a search pattern in a ":" command)
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003395 Also for |[s| and |]s|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003396 tag jumping to a tag: ":ta", CTRL-T, etc.
3397 undo undo or redo: "u" and CTRL-R
Bram Moolenaar071d4272004-06-13 20:20:40 +00003398 When a movement command is used for an operator (e.g., "dl" or "y%")
3399 this option is not used. This means the operator will include the
3400 whole closed fold.
3401 Note that vertical movements are not here, because it would make it
3402 very difficult to move onto a closed fold.
3403 In insert mode the folds containing the cursor will always be open
3404 when text is inserted.
3405 To close folds you can re-apply 'foldlevel' with the |zx| command or
3406 set the 'foldclose' option to "all".
3407
3408 *'foldtext'* *'fdt'*
3409'foldtext' 'fdt' string (default: "foldtext()")
3410 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003411 {not available when compiled without the |+folding|
3412 feature}
3413 An expression which is used to specify the text displayed for a closed
3414 fold. See |fold-foldtext|.
3415
Bram Moolenaar30b65812012-07-12 22:01:11 +02003416 The expression will be evaluated in the |sandbox| if set from a
3417 modeline, see |sandbox-option|.
Bram Moolenaar110289e2019-05-23 15:38:06 +02003418 This option cannot be set in a modeline when 'modelineexpr' is off.
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00003419
3420 It is not allowed to change text or jump to another window while
3421 evaluating 'foldtext' |textlock|.
3422
Bram Moolenaarc95a3022016-06-12 23:01:46 +02003423 *'formatexpr'* *'fex'*
3424'formatexpr' 'fex' string (default "")
3425 local to buffer
Bram Moolenaarc95a3022016-06-12 23:01:46 +02003426 {not available when compiled without the |+eval|
3427 feature}
3428 Expression which is evaluated to format a range of lines for the |gq|
3429 operator or automatic formatting (see 'formatoptions'). When this
3430 option is empty 'formatprg' is used.
3431
3432 The |v:lnum| variable holds the first line to be formatted.
3433 The |v:count| variable holds the number of lines to be formatted.
3434 The |v:char| variable holds the character that is going to be
3435 inserted if the expression is being evaluated due to
3436 automatic formatting. This can be empty. Don't insert
3437 it yet!
3438
3439 Example: >
3440 :set formatexpr=mylang#Format()
3441< This will invoke the mylang#Format() function in the
3442 autoload/mylang.vim file in 'runtimepath'. |autoload|
3443
3444 The expression is also evaluated when 'textwidth' is set and adding
3445 text beyond that limit. This happens under the same conditions as
3446 when internal formatting is used. Make sure the cursor is kept in the
3447 same spot relative to the text then! The |mode()| function will
3448 return "i" or "R" in this situation.
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01003449
Bram Moolenaarc95a3022016-06-12 23:01:46 +02003450 When the expression evaluates to non-zero Vim will fall back to using
3451 the internal format mechanism.
3452
3453 The expression will be evaluated in the |sandbox| when set from a
3454 modeline, see |sandbox-option|. That stops the option from working,
3455 since changing the buffer text is not allowed.
Bram Moolenaar110289e2019-05-23 15:38:06 +02003456 This option cannot be set in a modeline when 'modelineexpr' is off.
Bram Moolenaar036986f2017-03-16 17:41:02 +01003457 NOTE: This option is set to "" when 'compatible' is set.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02003458
Bram Moolenaar86b68352004-12-27 21:59:20 +00003459 *'formatlistpat'* *'flp'*
3460'formatlistpat' 'flp' string (default: "^\s*\d\+[\]:.)}\t ]\s*")
3461 local to buffer
Bram Moolenaar86b68352004-12-27 21:59:20 +00003462 A pattern that is used to recognize a list header. This is used for
3463 the "n" flag in 'formatoptions'.
3464 The pattern must match exactly the text that will be the indent for
Bram Moolenaar677ee682005-01-27 14:41:15 +00003465 the line below it. You can use |/\ze| to mark the end of the match
Bram Moolenaar86b68352004-12-27 21:59:20 +00003466 while still checking more characters. There must be a character
3467 following the pattern, when it matches the whole line it is handled
3468 like there is no match.
3469 The default recognizes a number, followed by an optional punctuation
3470 character and white space.
3471
Bram Moolenaar6c60f472019-04-28 16:00:35 +02003472 *'formatoptions'* *'fo'*
3473'formatoptions' 'fo' string (Vim default: "tcq", Vi default: "vt")
3474 local to buffer
3475 This is a sequence of letters which describes how automatic
3476 formatting is to be done. See |fo-table|. When the 'paste' option is
3477 on, no formatting is done (like 'formatoptions' is empty). Commas can
3478 be inserted for readability.
3479 To avoid problems with flags that are added in the future, use the
3480 "+=" and "-=" feature of ":set" |add-option-flags|.
3481 NOTE: This option is set to the Vi default value when 'compatible' is
3482 set and to the Vim default value when 'compatible' is reset.
3483
Bram Moolenaar071d4272004-06-13 20:20:40 +00003484 *'formatprg'* *'fp'*
3485'formatprg' 'fp' string (default "")
Bram Moolenaar9be7c042017-01-14 14:28:30 +01003486 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00003487 The name of an external program that will be used to format the lines
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00003488 selected with the |gq| operator. The program must take the input on
Bram Moolenaar071d4272004-06-13 20:20:40 +00003489 stdin and produce the output on stdout. The Unix program "fmt" is
Bram Moolenaara5792f52005-11-23 21:25:05 +00003490 such a program.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00003491 If the 'formatexpr' option is not empty it will be used instead.
3492 Otherwise, if 'formatprg' option is an empty string, the internal
3493 format function will be used |C-indenting|.
Bram Moolenaara5792f52005-11-23 21:25:05 +00003494 Environment variables are expanded |:set_env|. See |option-backslash|
3495 about including spaces and backslashes.
Bram Moolenaar30b65812012-07-12 22:01:11 +02003496 This option cannot be set from a |modeline| or in the |sandbox|, for
3497 security reasons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003498
Bram Moolenaard94464e2015-11-02 15:28:18 +01003499 *'fsync'* *'fs'* *'nofsync'* *'nofs'*
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00003500'fsync' 'fs' boolean (default on)
3501 global
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00003502 When on, the library function fsync() will be called after writing a
3503 file. This will flush a file to disk, ensuring that it is safely
3504 written even on filesystems which do metadata-only journaling. This
3505 will force the harddrive to spin up on Linux systems running in laptop
3506 mode, so it may be undesirable in some situations. Be warned that
3507 turning this off increases the chances of data loss after a crash. On
3508 systems without an fsync() implementation, this variable is always
3509 off.
3510 Also see 'swapsync' for controlling fsync() on swap files.
Bram Moolenaar51b0f372017-11-18 18:52:04 +01003511 'fsync' also applies to |writefile()|, unless a flag is used to
3512 overrule it.
Bram Moolenaar110289e2019-05-23 15:38:06 +02003513 This option cannot be set from a |modeline| or in the |sandbox|, for
3514 security reasons.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00003515
Bram Moolenaar071d4272004-06-13 20:20:40 +00003516 *'gdefault'* *'gd'* *'nogdefault'* *'nogd'*
3517'gdefault' 'gd' boolean (default off)
3518 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003519 When on, the ":substitute" flag 'g' is default on. This means that
3520 all matches in a line are substituted instead of one. When a 'g' flag
3521 is given to a ":substitute" command, this will toggle the substitution
3522 of all or one match. See |complex-change|.
3523
3524 command 'gdefault' on 'gdefault' off ~
3525 :s/// subst. all subst. one
3526 :s///g subst. one subst. all
3527 :s///gg subst. all subst. one
3528
3529 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaar21020352017-06-13 17:21:04 +02003530 DEPRECATED: Setting this option may break plugins that are not aware
3531 of this option. Also, many users get confused that adding the /g flag
3532 has the opposite effect of that it normally does.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003533
3534 *'grepformat'* *'gfm'*
Bram Moolenaar6e932462014-09-09 18:48:09 +02003535'grepformat' 'gfm' string (default "%f:%l:%m,%f:%l%m,%f %l%m")
Bram Moolenaar071d4272004-06-13 20:20:40 +00003536 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003537 Format to recognize for the ":grep" command output.
3538 This is a scanf-like string that uses the same format as the
3539 'errorformat' option: see |errorformat|.
3540
3541 *'grepprg'* *'gp'*
3542'grepprg' 'gp' string (default "grep -n ",
3543 Unix: "grep -n $* /dev/null",
3544 Win32: "findstr /n" or "grep -n",
3545 VMS: "SEARCH/NUMBERS ")
3546 global or local to buffer |global-local|
Bram Moolenaar582fd852005-03-28 20:58:01 +00003547 Program to use for the |:grep| command. This option may contain '%'
Bram Moolenaar071d4272004-06-13 20:20:40 +00003548 and '#' characters, which are expanded like when used in a command-
3549 line. The placeholder "$*" is allowed to specify where the arguments
3550 will be included. Environment variables are expanded |:set_env|. See
3551 |option-backslash| about including spaces and backslashes.
3552 When your "grep" accepts the "-H" argument, use this to make ":grep"
3553 also work well with a single file: >
3554 :set grepprg=grep\ -nH
Bram Moolenaar7c626922005-02-07 22:01:03 +00003555< Special value: When 'grepprg' is set to "internal" the |:grep| command
Bram Moolenaara6557602006-02-04 22:43:20 +00003556 works like |:vimgrep|, |:lgrep| like |:lvimgrep|, |:grepadd| like
3557 |:vimgrepadd| and |:lgrepadd| like |:lvimgrepadd|.
Bram Moolenaar86b68352004-12-27 21:59:20 +00003558 See also the section |:make_makeprg|, since most of the comments there
Bram Moolenaar071d4272004-06-13 20:20:40 +00003559 apply equally to 'grepprg'.
3560 For Win32, the default is "findstr /n" if "findstr.exe" can be found,
3561 otherwise it's "grep -n".
3562 This option cannot be set from a |modeline| or in the |sandbox|, for
3563 security reasons.
3564
3565 *'guicursor'* *'gcr'* *E545* *E546* *E548* *E549*
3566'guicursor' 'gcr' string (default "n-v-c:block-Cursor/lCursor,
3567 ve:ver35-Cursor,
3568 o:hor50-Cursor,
3569 i-ci:ver25-Cursor/lCursor,
3570 r-cr:hor20-Cursor/lCursor,
3571 sm:block-Cursor
3572 -blinkwait175-blinkoff150-blinkon175",
3573 for MS-DOS and Win32 console:
3574 "n-v-c:block,o:hor50,i-ci:hor15,
3575 r-cr:hor30,sm:block")
3576 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003577 {only available when compiled with GUI enabled, and
3578 for MS-DOS and Win32 console}
3579 This option tells Vim what the cursor should look like in different
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003580 modes. It fully works in the GUI. In an MSDOS or Win32 console, only
Bram Moolenaar071d4272004-06-13 20:20:40 +00003581 the height of the cursor can be changed. This can be done by
3582 specifying a block cursor, or a percentage for a vertical or
3583 horizontal cursor.
Bram Moolenaar1e7813a2015-03-31 18:31:03 +02003584 For a console the 't_SI', 't_SR', and 't_EI' escape sequences are
3585 used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003586
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003587 The option is a comma separated list of parts. Each part consist of a
Bram Moolenaar071d4272004-06-13 20:20:40 +00003588 mode-list and an argument-list:
3589 mode-list:argument-list,mode-list:argument-list,..
3590 The mode-list is a dash separated list of these modes:
3591 n Normal mode
3592 v Visual mode
3593 ve Visual mode with 'selection' "exclusive" (same as 'v',
3594 if not specified)
3595 o Operator-pending mode
3596 i Insert mode
3597 r Replace mode
3598 c Command-line Normal (append) mode
3599 ci Command-line Insert mode
3600 cr Command-line Replace mode
3601 sm showmatch in Insert mode
3602 a all modes
3603 The argument-list is a dash separated list of these arguments:
3604 hor{N} horizontal bar, {N} percent of the character height
3605 ver{N} vertical bar, {N} percent of the character width
3606 block block cursor, fills the whole character
3607 [only one of the above three should be present]
3608 blinkwait{N} *cursor-blinking*
3609 blinkon{N}
3610 blinkoff{N}
3611 blink times for cursor: blinkwait is the delay before
3612 the cursor starts blinking, blinkon is the time that
3613 the cursor is shown and blinkoff is the time that the
3614 cursor is not shown. The times are in msec. When one
3615 of the numbers is zero, there is no blinking. The
3616 default is: "blinkwait700-blinkon400-blinkoff250".
3617 These numbers are used for a missing entry. This
3618 means that blinking is enabled by default. To switch
3619 blinking off you can use "blinkon0". The cursor only
3620 blinks when Vim is waiting for input, not while
3621 executing a command.
3622 To make the cursor blink in an xterm, see
3623 |xterm-blink|.
3624 {group-name}
3625 a highlight group name, that sets the color and font
3626 for the cursor
3627 {group-name}/{group-name}
3628 Two highlight group names, the first is used when
3629 no language mappings are used, the other when they
3630 are. |language-mapping|
3631
3632 Examples of parts:
3633 n-c-v:block-nCursor in Normal, Command-line and Visual mode, use a
3634 block cursor with colors from the "nCursor"
3635 highlight group
3636 i-ci:ver30-iCursor-blinkwait300-blinkon200-blinkoff150
3637 In Insert and Command-line Insert mode, use a
3638 30% vertical bar cursor with colors from the
3639 "iCursor" highlight group. Blink a bit
3640 faster.
3641
3642 The 'a' mode is different. It will set the given argument-list for
3643 all modes. It does not reset anything to defaults. This can be used
3644 to do a common setting for all modes. For example, to switch off
3645 blinking: "a:blinkon0"
3646
3647 Examples of cursor highlighting: >
3648 :highlight Cursor gui=reverse guifg=NONE guibg=NONE
3649 :highlight Cursor gui=NONE guifg=bg guibg=fg
3650<
3651 *'guifont'* *'gfn'*
Bram Moolenaar251e1912011-06-19 05:09:16 +02003652 *E235* *E596*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003653'guifont' 'gfn' string (default "")
3654 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003655 {only available when compiled with GUI enabled}
3656 This is a list of fonts which will be used for the GUI version of Vim.
Bram Moolenaarf720d0a2019-04-28 14:02:47 +02003657 In its simplest form the value is just one font name.
3658 See |gui-font| for the details.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003659
3660 *'guifontset'* *'gfs'*
3661 *E250* *E252* *E234* *E597* *E598*
3662'guifontset' 'gfs' string (default "")
3663 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003664 {only available when compiled with GUI enabled and
3665 with the |+xfontset| feature}
Bram Moolenaar3df01732017-02-17 22:47:16 +01003666 {not available in the GTK+ GUI}
Bram Moolenaar071d4272004-06-13 20:20:40 +00003667 When not empty, specifies two (or more) fonts to be used. The first
3668 one for normal English, the second one for your special language. See
3669 |xfontset|.
Bram Moolenaarf720d0a2019-04-28 14:02:47 +02003670
Bram Moolenaar071d4272004-06-13 20:20:40 +00003671 *'guifontwide'* *'gfw'* *E231* *E533* *E534*
3672'guifontwide' 'gfw' string (default "")
3673 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003674 {only available when compiled with GUI enabled}
3675 When not empty, specifies a comma-separated list of fonts to be used
3676 for double-width characters. The first font that can be loaded is
Bram Moolenaarf720d0a2019-04-28 14:02:47 +02003677 used. See |gui-fontwide|.
Bram Moolenaar0f272122013-01-23 18:37:40 +01003678
Bram Moolenaar071d4272004-06-13 20:20:40 +00003679 *'guiheadroom'* *'ghr'*
3680'guiheadroom' 'ghr' number (default 50)
3681 global
Bram Moolenaar110289e2019-05-23 15:38:06 +02003682 {only for GTK and X11 GUI}
Bram Moolenaar071d4272004-06-13 20:20:40 +00003683 The number of pixels subtracted from the screen height when fitting
3684 the GUI window on the screen. Set this before the GUI is started,
3685 e.g., in your |gvimrc| file. When zero, the whole screen height will
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003686 be used by the window. When positive, the specified number of pixel
Bram Moolenaar071d4272004-06-13 20:20:40 +00003687 lines will be left for window decorations and other items on the
3688 screen. Set it to a negative value to allow windows taller than the
3689 screen.
3690
3691 *'guioptions'* *'go'*
Bram Moolenaar2c64ca12018-10-19 16:22:31 +02003692'guioptions' 'go' string (default "egmrLtT" (MS-Windows,
3693 "t" is removed in |defaults.vim|),
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +02003694 "aegimrLtT" (GTK, Motif and Athena),
3695 )
Bram Moolenaar071d4272004-06-13 20:20:40 +00003696 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003697 {only available when compiled with GUI enabled}
Bram Moolenaared203462004-06-16 11:19:22 +00003698 This option only has an effect in the GUI version of Vim. It is a
Bram Moolenaar071d4272004-06-13 20:20:40 +00003699 sequence of letters which describes what components and options of the
3700 GUI should be used.
3701 To avoid problems with flags that are added in the future, use the
3702 "+=" and "-=" feature of ":set" |add-option-flags|.
3703
Bram Moolenaar13568252018-03-16 20:46:58 +01003704 Valid characters are as follows:
3705 *'go-!'*
3706 '!' External commands are executed in a terminal window. Without
3707 this flag the MS-Windows GUI will open a console window to
3708 execute the command. The Unix GUI will simulate a dumb
3709 terminal to list the command output.
3710 The terminal window will be positioned at the bottom, and grow
3711 upwards as needed.
Bram Moolenaarba3ff532018-11-04 14:45:49 +01003712 *'go-a'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003713 'a' Autoselect: If present, then whenever VISUAL mode is started,
3714 or the Visual area extended, Vim tries to become the owner of
3715 the windowing system's global selection. This means that the
3716 Visually highlighted text is available for pasting into other
3717 applications as well as into Vim itself. When the Visual mode
3718 ends, possibly due to an operation on the text, or when an
3719 application wants to paste the selection, the highlighted text
3720 is automatically yanked into the "* selection register.
3721 Thus the selection is still available for pasting into other
3722 applications after the VISUAL mode has ended.
3723 If not present, then Vim won't become the owner of the
3724 windowing system's global selection unless explicitly told to
3725 by a yank or delete operation for the "* register.
3726 The same applies to the modeless selection.
Bram Moolenaarc0885aa2012-07-10 16:49:23 +02003727 *'go-P'*
3728 'P' Like autoselect but using the "+ register instead of the "*
Bram Moolenaar3848e002016-03-19 18:42:29 +01003729 register.
Bram Moolenaar02467872007-05-06 13:22:01 +00003730 *'go-A'*
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003731 'A' Autoselect for the modeless selection. Like 'a', but only
Bram Moolenaar071d4272004-06-13 20:20:40 +00003732 applies to the modeless selection.
3733
3734 'guioptions' autoselect Visual autoselect modeless ~
3735 "" - -
3736 "a" yes yes
3737 "A" - yes
3738 "aA" yes yes
3739
Bram Moolenaar02467872007-05-06 13:22:01 +00003740 *'go-c'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003741 'c' Use console dialogs instead of popup dialogs for simple
3742 choices.
Bram Moolenaar02467872007-05-06 13:22:01 +00003743 *'go-e'*
Bram Moolenaare224ffa2006-03-01 00:01:28 +00003744 'e' Add tab pages when indicated with 'showtabline'.
Bram Moolenaar5c8837f2006-02-25 21:52:33 +00003745 'guitablabel' can be used to change the text in the labels.
3746 When 'e' is missing a non-GUI tab pages line may be used.
Bram Moolenaard68071d2006-05-02 22:08:30 +00003747 The GUI tabs are only supported on some systems, currently
Bram Moolenaar446cb832008-06-24 21:56:24 +00003748 GTK, Motif, Mac OS/X and MS-Windows.
Bram Moolenaar02467872007-05-06 13:22:01 +00003749 *'go-f'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003750 'f' Foreground: Don't use fork() to detach the GUI from the shell
3751 where it was started. Use this for programs that wait for the
3752 editor to finish (e.g., an e-mail program). Alternatively you
3753 can use "gvim -f" or ":gui -f" to start the GUI in the
3754 foreground. |gui-fork|
3755 Note: Set this option in the vimrc file. The forking may have
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003756 happened already when the |gvimrc| file is read.
Bram Moolenaar02467872007-05-06 13:22:01 +00003757 *'go-i'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003758 'i' Use a Vim icon. For GTK with KDE it is used in the left-upper
3759 corner of the window. It's black&white on non-GTK, because of
3760 limitations of X11. For a color icon, see |X11-icon|.
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02003761 *'go-m'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003762 'm' Menu bar is present.
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02003763 *'go-M'*
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003764 'M' The system menu "$VIMRUNTIME/menu.vim" is not sourced. Note
Bram Moolenaar071d4272004-06-13 20:20:40 +00003765 that this flag must be added in the .vimrc file, before
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003766 switching on syntax or filetype recognition (when the |gvimrc|
Bram Moolenaar071d4272004-06-13 20:20:40 +00003767 file is sourced the system menu has already been loaded; the
Bram Moolenaar01164a62017-11-02 22:58:42 +01003768 `:syntax on` and `:filetype on` commands load the menu too).
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02003769 *'go-g'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003770 'g' Grey menu items: Make menu items that are not active grey. If
3771 'g' is not included inactive menu items are not shown at all.
3772 Exception: Athena will always use grey menu items.
Bram Moolenaar02467872007-05-06 13:22:01 +00003773 *'go-t'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003774 't' Include tearoff menu items. Currently only works for Win32,
3775 GTK+, and Motif 1.2 GUI.
Bram Moolenaar02467872007-05-06 13:22:01 +00003776 *'go-T'*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00003777 'T' Include Toolbar. Currently only in Win32, GTK+, Motif, Photon
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00003778 and Athena GUIs.
Bram Moolenaar02467872007-05-06 13:22:01 +00003779 *'go-r'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003780 'r' Right-hand scrollbar is always present.
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02003781 *'go-R'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003782 'R' Right-hand scrollbar is present when there is a vertically
3783 split window.
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02003784 *'go-l'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003785 'l' Left-hand scrollbar is always present.
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02003786 *'go-L'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003787 'L' Left-hand scrollbar is present when there is a vertically
3788 split window.
Bram Moolenaar02467872007-05-06 13:22:01 +00003789 *'go-b'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003790 'b' Bottom (horizontal) scrollbar is present. Its size depends on
3791 the longest visible line, or on the cursor line if the 'h'
3792 flag is included. |gui-horiz-scroll|
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02003793 *'go-h'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003794 'h' Limit horizontal scrollbar size to the length of the cursor
3795 line. Reduces computations. |gui-horiz-scroll|
3796
3797 And yes, you may even have scrollbars on the left AND the right if
3798 you really want to :-). See |gui-scrollbars| for more information.
3799
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02003800 *'go-v'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003801 'v' Use a vertical button layout for dialogs. When not included,
3802 a horizontal layout is preferred, but when it doesn't fit a
3803 vertical layout is used anyway.
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02003804 *'go-p'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003805 'p' Use Pointer callbacks for X11 GUI. This is required for some
3806 window managers. If the cursor is not blinking or hollow at
3807 the right moment, try adding this flag. This must be done
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003808 before starting the GUI. Set it in your |gvimrc|. Adding or
Bram Moolenaar071d4272004-06-13 20:20:40 +00003809 removing it after the GUI has started has no effect.
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02003810 *'go-F'*
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003811 'F' Add a footer. Only for Motif. See |gui-footer|.
Bram Moolenaar8ac44152017-11-09 18:33:29 +01003812 *'go-k'*
3813 'k' Keep the GUI window size when adding/removing a scrollbar, or
3814 toolbar, tabline, etc. Instead, the behavior is similar to
3815 when the window is maximized and will adjust 'lines' and
3816 'columns' to fit to the window. Without the 'k' flag Vim will
Bram Moolenaar51b0f372017-11-18 18:52:04 +01003817 try to keep 'lines' and 'columns' the same when adding and
Bram Moolenaar8ac44152017-11-09 18:33:29 +01003818 removing GUI components.
Bram Moolenaar02467872007-05-06 13:22:01 +00003819
Bram Moolenaar071d4272004-06-13 20:20:40 +00003820 *'guipty'* *'noguipty'*
3821'guipty' boolean (default on)
3822 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003823 {only available when compiled with GUI enabled}
3824 Only in the GUI: If on, an attempt is made to open a pseudo-tty for
3825 I/O to/from shell commands. See |gui-pty|.
3826
Bram Moolenaar5c8837f2006-02-25 21:52:33 +00003827 *'guitablabel'* *'gtl'*
3828'guitablabel' 'gtl' string (default empty)
3829 global
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02003830 {only available when compiled with GUI enabled}
Bram Moolenaar5c8837f2006-02-25 21:52:33 +00003831 When nonempty describes the text to use in a label of the GUI tab
Bram Moolenaard68071d2006-05-02 22:08:30 +00003832 pages line. When empty and when the result is empty Vim will use a
3833 default label. See |setting-guitablabel| for more info.
Bram Moolenaar5c8837f2006-02-25 21:52:33 +00003834
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003835 The format of this option is like that of 'statusline'.
Bram Moolenaar57657d82006-04-21 22:12:41 +00003836 'guitabtooltip' is used for the tooltip, see below.
Bram Moolenaar51628222016-12-01 23:03:28 +01003837 The expression will be evaluated in the |sandbox| when set from a
3838 modeline, see |sandbox-option|.
Bram Moolenaar110289e2019-05-23 15:38:06 +02003839 This option cannot be set in a modeline when 'modelineexpr' is off.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003840
Bram Moolenaar5c8837f2006-02-25 21:52:33 +00003841 Only used when the GUI tab pages line is displayed. 'e' must be
3842 present in 'guioptions'. For the non-GUI tab pages line 'tabline' is
3843 used.
3844
Bram Moolenaar57657d82006-04-21 22:12:41 +00003845 *'guitabtooltip'* *'gtt'*
3846'guitabtooltip' 'gtt' string (default empty)
3847 global
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02003848 {only available when compiled with GUI enabled}
Bram Moolenaar57657d82006-04-21 22:12:41 +00003849 When nonempty describes the text to use in a tooltip for the GUI tab
3850 pages line. When empty Vim will use a default tooltip.
3851 This option is otherwise just like 'guitablabel' above.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003852 You can include a line break. Simplest method is to use |:let|: >
3853 :let &guitabtooltip = "line one\nline two"
3854<
Bram Moolenaar57657d82006-04-21 22:12:41 +00003855
Bram Moolenaar071d4272004-06-13 20:20:40 +00003856 *'helpfile'* *'hf'*
3857'helpfile' 'hf' string (default (MSDOS) "$VIMRUNTIME\doc\help.txt"
3858 (others) "$VIMRUNTIME/doc/help.txt")
3859 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003860 Name of the main help file. All distributed help files should be
3861 placed together in one directory. Additionally, all "doc" directories
3862 in 'runtimepath' will be used.
3863 Environment variables are expanded |:set_env|. For example:
3864 "$VIMRUNTIME/doc/help.txt". If $VIMRUNTIME is not set, $VIM is also
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003865 tried. Also see |$VIMRUNTIME| and |option-backslash| about including
Bram Moolenaar071d4272004-06-13 20:20:40 +00003866 spaces and backslashes.
3867 This option cannot be set from a |modeline| or in the |sandbox|, for
3868 security reasons.
3869
3870 *'helpheight'* *'hh'*
3871'helpheight' 'hh' number (default 20)
3872 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003873 Minimal initial height of the help window when it is opened with the
3874 ":help" command. The initial height of the help window is half of the
3875 current window, or (when the 'ea' option is on) the same as other
3876 windows. When the height is less than 'helpheight', the height is
3877 set to 'helpheight'. Set to zero to disable.
3878
3879 *'helplang'* *'hlg'*
3880'helplang' 'hlg' string (default: messages language or empty)
3881 global
3882 {only available when compiled with the |+multi_lang|
3883 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00003884 Comma separated list of languages. Vim will use the first language
3885 for which the desired help can be found. The English help will always
3886 be used as a last resort. You can add "en" to prefer English over
3887 another language, but that will only find tags that exist in that
3888 language and not in the English help.
3889 Example: >
3890 :set helplang=de,it
3891< This will first search German, then Italian and finally English help
3892 files.
3893 When using |CTRL-]| and ":help!" in a non-English help file Vim will
3894 try to find the tag in the current language before using this option.
3895 See |help-translated|.
3896
3897 *'hidden'* *'hid'* *'nohidden'* *'nohid'*
3898'hidden' 'hid' boolean (default off)
3899 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003900 When off a buffer is unloaded when it is |abandon|ed. When on a
3901 buffer becomes hidden when it is |abandon|ed. If the buffer is still
3902 displayed in another window, it does not become hidden, of course.
3903 The commands that move through the buffer list sometimes make a buffer
3904 hidden although the 'hidden' option is off: When the buffer is
3905 modified, 'autowrite' is off or writing is not possible, and the '!'
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003906 flag was used. See also |windows.txt|.
Bram Moolenaarcfbc5ee2004-07-02 15:38:35 +00003907 To only make one buffer hidden use the 'bufhidden' option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003908 This option is set for one command with ":hide {command}" |:hide|.
3909 WARNING: It's easy to forget that you have changes in hidden buffers.
3910 Think twice when using ":q!" or ":qa!".
3911
3912 *'highlight'* *'hl'*
3913'highlight' 'hl' string (default (as a single string):
Bram Moolenaar58b85342016-08-14 19:54:54 +02003914 "8:SpecialKey,~:EndOfBuffer,@:NonText,
3915 d:Directory,e:ErrorMsg,i:IncSearch,
3916 l:Search,m:MoreMsg,M:ModeMsg,n:LineNr,
3917 N:CursorLineNr,r:Question,s:StatusLine,
3918 S:StatusLineNC,c:VertSplit,t:Title,
Bram Moolenaar9d87a372018-12-18 21:41:50 +01003919 v:Visual,V:VisualNOS,w:WarningMsg,
3920 W:WildMenu,f:Folded,F:FoldColumn,
3921 A:DiffAdd,C:DiffChange,D:DiffDelete,
3922 T:DiffText,>:SignColumn,-:Conceal,
Bram Moolenaarc8c88492018-12-27 23:59:26 +01003923 B:SpellBad,P:SpellCap,R:SpellRare,
Bram Moolenaar9d87a372018-12-18 21:41:50 +01003924 L:SpellLocal,+:Pmenu,=:PmenuSel,
Bram Moolenaar21020352017-06-13 17:21:04 +02003925 x:PmenuSbar,X:PmenuThumb,*:TabLine,
3926 #:TabLineSel,_:TabLineFill,!:CursorColumn,
Bram Moolenaarf55e4c82017-08-01 20:44:53 +02003927 .:CursorLine,o:ColorColumn,q:QuickFixLine,
Bram Moolenaarc572da52017-08-27 16:52:01 +02003928 z:StatusLineTerm,Z:StatusLineTermNC")
Bram Moolenaar071d4272004-06-13 20:20:40 +00003929 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003930 This option can be used to set highlighting mode for various
3931 occasions. It is a comma separated list of character pairs. The
3932 first character in a pair gives the occasion, the second the mode to
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003933 use for that occasion. The occasions are:
Bram Moolenaar071d4272004-06-13 20:20:40 +00003934 |hl-SpecialKey| 8 Meta and special keys listed with ":map"
Bram Moolenaar58b85342016-08-14 19:54:54 +02003935 |hl-EndOfBuffer| ~ lines after the last line in the buffer
3936 |hl-NonText| @ '@' at the end of the window and
Bram Moolenaar071d4272004-06-13 20:20:40 +00003937 characters from 'showbreak'
3938 |hl-Directory| d directories in CTRL-D listing and other special
3939 things in listings
3940 |hl-ErrorMsg| e error messages
3941 h (obsolete, ignored)
3942 |hl-IncSearch| i 'incsearch' highlighting
3943 |hl-Search| l last search pattern highlighting (see 'hlsearch')
3944 |hl-MoreMsg| m |more-prompt|
3945 |hl-ModeMsg| M Mode (e.g., "-- INSERT --")
Bram Moolenaar64486672010-05-16 15:46:46 +02003946 |hl-LineNr| n line number for ":number" and ":#" commands, and
3947 when 'number' or 'relativenumber' option is set.
Bram Moolenaara3e6bc92013-01-30 14:18:00 +01003948 |hl-CursorLineNr| N like n for when 'cursorline' or 'relativenumber' is
3949 set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003950 |hl-Question| r |hit-enter| prompt and yes/no questions
3951 |hl-StatusLine| s status line of current window |status-line|
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01003952 |hl-StatusLineNC| S status lines of not-current windows
Bram Moolenaar071d4272004-06-13 20:20:40 +00003953 |hl-Title| t Titles for output from ":set all", ":autocmd" etc.
3954 |hl-VertSplit| c column used to separate vertically split windows
3955 |hl-Visual| v Visual mode
3956 |hl-VisualNOS| V Visual mode when Vim does is "Not Owning the
3957 Selection" Only X11 Gui's |gui-x11| and
3958 |xterm-clipboard|.
3959 |hl-WarningMsg| w warning messages
3960 |hl-WildMenu| W wildcard matches displayed for 'wildmenu'
3961 |hl-Folded| f line used for closed folds
3962 |hl-FoldColumn| F 'foldcolumn'
Bram Moolenaar0d9c26d2005-07-02 23:19:16 +00003963 |hl-DiffAdd| A added line in diff mode
3964 |hl-DiffChange| C changed line in diff mode
3965 |hl-DiffDelete| D deleted line in diff mode
3966 |hl-DiffText| T inserted text in diff mode
Bram Moolenaar071d4272004-06-13 20:20:40 +00003967 |hl-SignColumn| > column used for |signs|
Bram Moolenaar9d87a372018-12-18 21:41:50 +01003968 |hl-Conceal| - the placeholders used for concealed characters
3969 (see 'conceallevel')
Bram Moolenaar217ad922005-03-20 22:37:15 +00003970 |hl-SpellBad| B misspelled word |spell|
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02003971 |hl-SpellCap| P word that should start with capital |spell|
Bram Moolenaar217ad922005-03-20 22:37:15 +00003972 |hl-SpellRare| R rare word |spell|
3973 |hl-SpellLocal| L word from other region |spell|
Bram Moolenaar9d87a372018-12-18 21:41:50 +01003974 |hl-Pmenu| + popup menu normal line
3975 |hl-PmenuSel| = popup menu selected line
3976 |hl-PmenuSbar| x popup menu scrollbar
3977 |hl-PmenuThumb| X popup menu scrollbar thumb
Bram Moolenaar071d4272004-06-13 20:20:40 +00003978
3979 The display modes are:
3980 r reverse (termcap entry "mr" and "me")
3981 i italic (termcap entry "ZH" and "ZR")
3982 b bold (termcap entry "md" and "me")
3983 s standout (termcap entry "so" and "se")
3984 u underline (termcap entry "us" and "ue")
Bram Moolenaare2cc9702005-03-15 22:43:58 +00003985 c undercurl (termcap entry "Cs" and "Ce")
Bram Moolenaarcf4b00c2017-09-02 18:33:56 +02003986 t strikethrough (termcap entry "Ts" and "Te")
Bram Moolenaar071d4272004-06-13 20:20:40 +00003987 n no highlighting
3988 - no highlighting
3989 : use a highlight group
3990 The default is used for occasions that are not included.
3991 If you want to change what the display modes do, see |dos-colors|
3992 for an example.
3993 When using the ':' display mode, this must be followed by the name of
3994 a highlight group. A highlight group can be used to define any type
3995 of highlighting, including using color. See |:highlight| on how to
3996 define one. The default uses a different group for each occasion.
3997 See |highlight-default| for the default highlight groups.
3998
Bram Moolenaar071d4272004-06-13 20:20:40 +00003999 *'history'* *'hi'*
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +02004000'history' 'hi' number (Vim default: 50, Vi default: 0,
4001 set to 200 in |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004002 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004003 A history of ":" commands, and a history of previous search patterns
Bram Moolenaar78159bb2014-06-25 11:48:54 +02004004 is remembered. This option decides how many entries may be stored in
Bram Moolenaar071d4272004-06-13 20:20:40 +00004005 each of these histories (see |cmdline-editing|).
Bram Moolenaar78159bb2014-06-25 11:48:54 +02004006 The maximum value is 10000.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004007 NOTE: This option is set to the Vi default value when 'compatible' is
4008 set and to the Vim default value when 'compatible' is reset.
4009
4010 *'hkmap'* *'hk'* *'nohkmap'* *'nohk'*
4011'hkmap' 'hk' boolean (default off)
4012 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004013 {only available when compiled with the |+rightleft|
4014 feature}
4015 When on, the keyboard is mapped for the Hebrew character set.
4016 Normally you would set 'allowrevins' and use CTRL-_ in insert mode to
4017 toggle this option. See |rileft.txt|.
4018 NOTE: This option is reset when 'compatible' is set.
4019
4020 *'hkmapp'* *'hkp'* *'nohkmapp'* *'nohkp'*
4021'hkmapp' 'hkp' boolean (default off)
4022 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004023 {only available when compiled with the |+rightleft|
4024 feature}
4025 When on, phonetic keyboard mapping is used. 'hkmap' must also be on.
4026 This is useful if you have a non-Hebrew keyboard.
4027 See |rileft.txt|.
4028 NOTE: This option is reset when 'compatible' is set.
4029
Bram Moolenaar036986f2017-03-16 17:41:02 +01004030 *'hlsearch'* *'hls'* *'nohlsearch'* *'nohls'*
4031'hlsearch' 'hls' boolean (default off)
4032 global
Bram Moolenaar036986f2017-03-16 17:41:02 +01004033 {not available when compiled without the
4034 |+extra_search| feature}
4035 When there is a previous search pattern, highlight all its matches.
4036 The type of highlighting used can be set with the 'l' occasion in the
4037 'highlight' option. This uses the "Search" highlight group by
4038 default. Note that only the matching text is highlighted, any offsets
4039 are not applied.
4040 See also: 'incsearch' and |:match|.
4041 When you get bored looking at the highlighted matches, you can turn it
4042 off with |:nohlsearch|. This does not change the option value, as
4043 soon as you use a search command, the highlighting comes back.
4044 'redrawtime' specifies the maximum time spent on finding matches.
4045 When the search pattern can match an end-of-line, Vim will try to
4046 highlight all of the matched text. However, this depends on where the
4047 search starts. This will be the first line in the window or the first
4048 line below a closed fold. A match in a previous line which is not
4049 drawn may not continue in a newly drawn line.
4050 You can specify whether the highlight status is restored on startup
4051 with the 'h' flag in 'viminfo' |viminfo-h|.
4052 NOTE: This option is reset when 'compatible' is set.
4053
Bram Moolenaar071d4272004-06-13 20:20:40 +00004054 *'icon'* *'noicon'*
4055'icon' boolean (default off, on when title can be restored)
4056 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004057 {not available when compiled without the |+title|
4058 feature}
4059 When on, the icon text of the window will be set to the value of
4060 'iconstring' (if it is not empty), or to the name of the file
4061 currently being edited. Only the last part of the name is used.
4062 Overridden by the 'iconstring' option.
4063 Only works if the terminal supports setting window icons (currently
4064 only X11 GUI and terminals with a non-empty 't_IS' option - these are
4065 Unix xterm and iris-ansi by default, where 't_IS' is taken from the
4066 builtin termcap).
4067 When Vim was compiled with HAVE_X11 defined, the original icon will be
Bram Moolenaar582fd852005-03-28 20:58:01 +00004068 restored if possible |X11|. See |X11-icon| for changing the icon on
Bram Moolenaar071d4272004-06-13 20:20:40 +00004069 X11.
Bram Moolenaar3a991dd2014-10-02 01:41:41 +02004070 For MS-Windows the icon can be changed, see |windows-icon|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004071
4072 *'iconstring'*
4073'iconstring' string (default "")
4074 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004075 {not available when compiled without the |+title|
4076 feature}
4077 When this option is not empty, it will be used for the icon text of
4078 the window. This happens only when the 'icon' option is on.
4079 Only works if the terminal supports setting window icon text
4080 (currently only X11 GUI and terminals with a non-empty 't_IS' option).
4081 Does not work for MS Windows.
4082 When Vim was compiled with HAVE_X11 defined, the original icon will be
4083 restored if possible |X11|.
4084 When this option contains printf-style '%' items, they will be
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004085 expanded according to the rules used for 'statusline'. See
Bram Moolenaar071d4272004-06-13 20:20:40 +00004086 'titlestring' for example settings.
Bram Moolenaar110289e2019-05-23 15:38:06 +02004087 This option cannot be set in a modeline when 'modelineexpr' is off.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004088 {not available when compiled without the |+statusline| feature}
4089
4090 *'ignorecase'* *'ic'* *'noignorecase'* *'noic'*
4091'ignorecase' 'ic' boolean (default off)
4092 global
4093 Ignore case in search patterns. Also used when searching in the tags
4094 file.
Bram Moolenaar0f6562e2015-11-24 18:48:14 +01004095 Also see 'smartcase' and 'tagcase'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004096 Can be overruled by using "\c" or "\C" in the pattern, see
4097 |/ignorecase|.
4098
Bram Moolenaarabab85a2013-06-26 19:18:05 +02004099 *'imactivatefunc'* *'imaf'*
4100'imactivatefunc' 'imaf' string (default "")
4101 global
Bram Moolenaarabab85a2013-06-26 19:18:05 +02004102 This option specifies a function that will be called to
Bram Moolenaar2877d332017-11-26 14:56:16 +01004103 activate or deactivate the Input Method.
4104 It is not used in the GUI.
Bram Moolenaar110289e2019-05-23 15:38:06 +02004105 The expression will be evaluated in the |sandbox| when set from a
4106 modeline, see |sandbox-option|.
Bram Moolenaarabab85a2013-06-26 19:18:05 +02004107
4108 Example: >
4109 function ImActivateFunc(active)
4110 if a:active
4111 ... do something
4112 else
4113 ... do something
4114 endif
4115 " return value is not used
4116 endfunction
4117 set imactivatefunc=ImActivateFunc
4118<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004119 *'imactivatekey'* *'imak'*
4120'imactivatekey' 'imak' string (default "")
4121 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004122 {only available when compiled with |+xim| and
Bram Moolenaar67c53842010-05-22 18:28:27 +02004123 |+GUI_GTK|} *E599*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004124 Specifies the key that your Input Method in X-Windows uses for
4125 activation. When this is specified correctly, vim can fully control
4126 IM with 'imcmdline', 'iminsert' and 'imsearch'.
4127 You can't use this option to change the activation key, the option
4128 tells Vim what the key is.
4129 Format:
4130 [MODIFIER_FLAG-]KEY_STRING
4131
4132 These characters can be used for MODIFIER_FLAG (case is ignored):
4133 S Shift key
4134 L Lock key
4135 C Control key
4136 1 Mod1 key
4137 2 Mod2 key
4138 3 Mod3 key
4139 4 Mod4 key
4140 5 Mod5 key
4141 Combinations are allowed, for example "S-C-space" or "SC-space" are
4142 both shift+ctrl+space.
4143 See <X11/keysymdef.h> and XStringToKeysym for KEY_STRING.
4144
4145 Example: >
4146 :set imactivatekey=S-space
4147< "S-space" means shift+space. This is the activation key for kinput2 +
4148 canna (Japanese), and ami (Korean).
4149
4150 *'imcmdline'* *'imc'* *'noimcmdline'* *'noimc'*
4151'imcmdline' 'imc' boolean (default off)
4152 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004153 When set the Input Method is always on when starting to edit a command
4154 line, unless entering a search pattern (see 'imsearch' for that).
4155 Setting this option is useful when your input method allows entering
4156 English characters directly, e.g., when it's used to type accented
4157 characters with dead keys.
4158
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004159 *'imdisable'* *'imd'* *'noimdisable'* *'noimd'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004160'imdisable' 'imd' boolean (default off, on for some systems (SGI))
4161 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004162 When set the Input Method is never used. This is useful to disable
4163 the IM when it doesn't work properly.
4164 Currently this option is on by default for SGI/IRIX machines. This
4165 may change in later releases.
4166
4167 *'iminsert'* *'imi'*
Bram Moolenaar4cf56bb2017-09-16 15:50:32 +02004168'iminsert' 'imi' number (default 0)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004169 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00004170 Specifies whether :lmap or an Input Method (IM) is to be used in
4171 Insert mode. Valid values:
4172 0 :lmap is off and IM is off
4173 1 :lmap is ON and IM is off
4174 2 :lmap is off and IM is ON
Bram Moolenaar071d4272004-06-13 20:20:40 +00004175 To always reset the option to zero when leaving Insert mode with <Esc>
4176 this can be used: >
4177 :inoremap <ESC> <ESC>:set iminsert=0<CR>
4178< This makes :lmap and IM turn off automatically when leaving Insert
4179 mode.
4180 Note that this option changes when using CTRL-^ in Insert mode
4181 |i_CTRL-^|.
4182 The value is set to 1 when setting 'keymap' to a valid keymap name.
4183 It is also used for the argument of commands like "r" and "f".
4184 The value 0 may not work correctly with Athena and Motif with some XIM
4185 methods. Use 'imdisable' to disable XIM then.
4186
Bram Moolenaar6315a9a2017-11-25 15:20:02 +01004187 You can set 'imactivatefunc' and 'imstatusfunc' to handle IME/XIM
Bram Moolenaard473c8c2018-08-11 18:00:22 +02004188 via external command if Vim is not compiled with the |+xim|,
Bram Moolenaar6315a9a2017-11-25 15:20:02 +01004189 |+multi_byte_ime| or |global-ime|.
4190
Bram Moolenaar071d4272004-06-13 20:20:40 +00004191 *'imsearch'* *'ims'*
Bram Moolenaar4cf56bb2017-09-16 15:50:32 +02004192'imsearch' 'ims' number (default -1)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004193 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00004194 Specifies whether :lmap or an Input Method (IM) is to be used when
4195 entering a search pattern. Valid values:
4196 -1 the value of 'iminsert' is used, makes it look like
4197 'iminsert' is also used when typing a search pattern
4198 0 :lmap is off and IM is off
4199 1 :lmap is ON and IM is off
4200 2 :lmap is off and IM is ON
4201 Note that this option changes when using CTRL-^ in Command-line mode
4202 |c_CTRL-^|.
4203 The value is set to 1 when it is not -1 and setting the 'keymap'
4204 option to a valid keymap name.
4205 The value 0 may not work correctly with Athena and Motif with some XIM
4206 methods. Use 'imdisable' to disable XIM then.
4207
Bram Moolenaarabab85a2013-06-26 19:18:05 +02004208 *'imstatusfunc'* *'imsf'*
4209'imstatusfunc' 'imsf' string (default "")
4210 global
Bram Moolenaarabab85a2013-06-26 19:18:05 +02004211 This option specifies a function that is called to obtain the status
4212 of Input Method. It must return a positive number when IME is active.
Bram Moolenaar2877d332017-11-26 14:56:16 +01004213 It is not used in the GUI.
Bram Moolenaarabab85a2013-06-26 19:18:05 +02004214
4215 Example: >
4216 function ImStatusFunc()
4217 let is_active = ...do something
4218 return is_active ? 1 : 0
4219 endfunction
4220 set imstatusfunc=ImStatusFunc
4221<
4222 NOTE: This function is invoked very often. Keep it fast.
Bram Moolenaar110289e2019-05-23 15:38:06 +02004223 The expression will be evaluated in the |sandbox| when set from a
4224 modeline, see |sandbox-option|.
Bram Moolenaarabab85a2013-06-26 19:18:05 +02004225
Bram Moolenaar5c6dbcb2017-08-30 22:00:20 +02004226 *'imstyle'* *'imst'*
4227'imstyle' 'imst' number (default 1)
4228 global
Bram Moolenaar5c6dbcb2017-08-30 22:00:20 +02004229 {only available when compiled with |+xim| and
4230 |+GUI_GTK|}
Bram Moolenaar37c64c72017-09-19 22:06:03 +02004231 This option specifies the input style of Input Method:
4232 0 use on-the-spot style
4233 1 over-the-spot style
Bram Moolenaar5c6dbcb2017-08-30 22:00:20 +02004234 See: |xim-input-style|
4235
Bram Moolenaar24a98a02017-09-27 22:23:55 +02004236 For a long time on-the-spot style had been used in the GTK version of
4237 vim, however, it is known that it causes troubles when using mappings,
Bram Moolenaar5c6dbcb2017-08-30 22:00:20 +02004238 |single-repeat|, etc. Therefore over-the-spot style becomes the
4239 default now. This should work fine for most people, however if you
4240 have any problem with it, try using on-the-spot style.
Bram Moolenaar110289e2019-05-23 15:38:06 +02004241 The expression will be evaluated in the |sandbox| when set from a
4242 modeline, see |sandbox-option|.
Bram Moolenaar5c6dbcb2017-08-30 22:00:20 +02004243
Bram Moolenaar071d4272004-06-13 20:20:40 +00004244 *'include'* *'inc'*
4245'include' 'inc' string (default "^\s*#\s*include")
4246 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004247 {not available when compiled without the
4248 |+find_in_path| feature}
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004249 Pattern to be used to find an include command. It is a search
Bram Moolenaar071d4272004-06-13 20:20:40 +00004250 pattern, just like for the "/" command (See |pattern|). The default
4251 value is for C programs. This option is used for the commands "[i",
Bram Moolenaar1e015462005-09-25 22:16:38 +00004252 "]I", "[d", etc.
4253 Normally the 'isfname' option is used to recognize the file name that
Bram Moolenaar482aaeb2005-09-29 18:26:07 +00004254 comes after the matched pattern. But if "\zs" appears in the pattern
4255 then the text matched from "\zs" to the end, or until "\ze" if it
4256 appears, is used as the file name. Use this to include characters
4257 that are not in 'isfname', such as a space. You can then use
4258 'includeexpr' to process the matched text.
Bram Moolenaar1e015462005-09-25 22:16:38 +00004259 See |option-backslash| about including spaces and backslashes.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004260
4261 *'includeexpr'* *'inex'*
4262'includeexpr' 'inex' string (default "")
4263 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00004264 {not available when compiled without the
Bram Moolenaardb84e452010-08-15 13:50:43 +02004265 |+find_in_path| or |+eval| features}
Bram Moolenaar071d4272004-06-13 20:20:40 +00004266 Expression to be used to transform the string found with the 'include'
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004267 option to a file name. Mostly useful to change "." to "/" for Java: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004268 :set includeexpr=substitute(v:fname,'\\.','/','g')
4269< The "v:fname" variable will be set to the file name that was detected.
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00004270
Bram Moolenaar071d4272004-06-13 20:20:40 +00004271 Also used for the |gf| command if an unmodified file name can't be
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004272 found. Allows doing "gf" on the name after an 'include' statement.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004273 Also used for |<cfile>|.
4274
Bram Moolenaar30b65812012-07-12 22:01:11 +02004275 The expression will be evaluated in the |sandbox| when set from a
4276 modeline, see |sandbox-option|.
Bram Moolenaar110289e2019-05-23 15:38:06 +02004277 This option cannot be set in a modeline when 'modelineexpr' is off.
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00004278
4279 It is not allowed to change text or jump to another window while
4280 evaluating 'includeexpr' |textlock|.
4281
Bram Moolenaar071d4272004-06-13 20:20:40 +00004282 *'incsearch'* *'is'* *'noincsearch'* *'nois'*
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +02004283'incsearch' 'is' boolean (default off, set in |defaults.vim| if the
4284 +reltime feature is supported)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004285 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004286 {not available when compiled without the
Bram Moolenaardb84e452010-08-15 13:50:43 +02004287 |+extra_search| features}
Bram Moolenaar21cf8232004-07-16 20:18:37 +00004288 While typing a search command, show where the pattern, as it was typed
4289 so far, matches. The matched string is highlighted. If the pattern
4290 is invalid or not found, nothing is shown. The screen will be updated
4291 often, this is only useful on fast terminals.
Bram Moolenaarfc65cab2018-08-28 22:58:02 +02004292 Also applies to the pattern in commands: >
4293 :global
4294 :lvimgrep
4295 :lvimgrepadd
4296 :smagic
4297 :snomagic
4298 :sort
4299 :substitute
4300 :vglobal
4301 :vimgrep
4302 :vimgrepadd
4303< Note that the match will be shown, but the cursor will return to its
Bram Moolenaar21cf8232004-07-16 20:18:37 +00004304 original position when no match is found and when pressing <Esc>. You
4305 still need to finish the search command with <Enter> to move the
4306 cursor to the match.
Bram Moolenaardc083282016-10-11 08:57:33 +02004307 You can use the CTRL-G and CTRL-T keys to move to the next and
4308 previous match. |c_CTRL-G| |c_CTRL-T|
Bram Moolenaar91a4e822008-01-19 14:59:58 +00004309 When compiled with the |+reltime| feature Vim only searches for about
4310 half a second. With a complicated pattern and/or a lot of text the
4311 match may not be found. This is to avoid that Vim hangs while you
4312 are typing the pattern.
Bram Moolenaar21cf8232004-07-16 20:18:37 +00004313 The highlighting can be set with the 'i' flag in 'highlight'.
Bram Moolenaar2f058492017-11-30 20:27:52 +01004314 When 'hlsearch' is on, all matched strings are highlighted too while
4315 typing a search command. See also: 'hlsearch'.
Bram Moolenaard473c8c2018-08-11 18:00:22 +02004316 If you don't want to turn 'hlsearch' on, but want to highlight all
4317 matches while searching, you can turn on and off 'hlsearch' with
4318 autocmd. Example: >
Bram Moolenaar2e51d9a2017-10-29 16:40:30 +01004319 augroup vimrc-incsearch-highlight
4320 autocmd!
Bram Moolenaarf8f8b2e2017-11-02 19:08:48 +01004321 autocmd CmdlineEnter /,\? :set hlsearch
4322 autocmd CmdlineLeave /,\? :set nohlsearch
Bram Moolenaar2e51d9a2017-10-29 16:40:30 +01004323 augroup END
4324<
Bram Moolenaarefd2bf12006-03-16 21:41:35 +00004325 CTRL-L can be used to add one character from after the current match
Bram Moolenaara9dc3752010-07-11 20:46:53 +02004326 to the command line. If 'ignorecase' and 'smartcase' are set and the
4327 command line has no uppercase characters, the added character is
4328 converted to lowercase.
Bram Moolenaarefd2bf12006-03-16 21:41:35 +00004329 CTRL-R CTRL-W can be used to add the word at the end of the current
4330 match, excluding the characters that were already typed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004331 NOTE: This option is reset when 'compatible' is set.
4332
4333 *'indentexpr'* *'inde'*
4334'indentexpr' 'inde' string (default "")
4335 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00004336 {not available when compiled without the |+cindent|
4337 or |+eval| features}
4338 Expression which is evaluated to obtain the proper indent for a line.
4339 It is used when a new line is created, for the |=| operator and
4340 in Insert mode as specified with the 'indentkeys' option.
4341 When this option is not empty, it overrules the 'cindent' and
Bram Moolenaar20f90cf2011-05-19 12:22:51 +02004342 'smartindent' indenting. When 'lisp' is set, this option is
4343 overridden by the Lisp indentation algorithm.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004344 When 'paste' is set this option is not used for indenting.
4345 The expression is evaluated with |v:lnum| set to the line number for
Bram Moolenaar482aaeb2005-09-29 18:26:07 +00004346 which the indent is to be computed. The cursor is also in this line
Bram Moolenaar071d4272004-06-13 20:20:40 +00004347 when the expression is evaluated (but it may be moved around).
4348 The expression must return the number of spaces worth of indent. It
4349 can return "-1" to keep the current indent (this means 'autoindent' is
4350 used for the indent).
4351 Functions useful for computing the indent are |indent()|, |cindent()|
4352 and |lispindent()|.
4353 The evaluation of the expression must not have side effects! It must
4354 not change the text, jump to another window, etc. Afterwards the
4355 cursor position is always restored, thus the cursor may be moved.
4356 Normally this option would be set to call a function: >
4357 :set indentexpr=GetMyIndent()
4358< Error messages will be suppressed, unless the 'debug' option contains
4359 "msg".
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00004360 See |indent-expression|.
Bram Moolenaar036986f2017-03-16 17:41:02 +01004361 NOTE: This option is set to "" when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004362
Bram Moolenaar30b65812012-07-12 22:01:11 +02004363 The expression will be evaluated in the |sandbox| when set from a
4364 modeline, see |sandbox-option|.
Bram Moolenaar110289e2019-05-23 15:38:06 +02004365 This option cannot be set in a modeline when 'modelineexpr' is off.
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00004366
4367 It is not allowed to change text or jump to another window while
4368 evaluating 'indentexpr' |textlock|.
4369
4370
Bram Moolenaar071d4272004-06-13 20:20:40 +00004371 *'indentkeys'* *'indk'*
Bram Moolenaarce655742019-01-31 14:12:57 +01004372'indentkeys' 'indk' string (default "0{,0},0),0],:,0#,!^F,o,O,e")
Bram Moolenaar071d4272004-06-13 20:20:40 +00004373 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00004374 {not available when compiled without the |+cindent|
4375 feature}
4376 A list of keys that, when typed in Insert mode, cause reindenting of
4377 the current line. Only happens if 'indentexpr' isn't empty.
4378 The format is identical to 'cinkeys', see |indentkeys-format|.
4379 See |C-indenting| and |indent-expression|.
4380
4381 *'infercase'* *'inf'* *'noinfercase'* *'noinf'*
4382'infercase' 'inf' boolean (default off)
4383 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00004384 When doing keyword completion in insert mode |ins-completion|, and
Bram Moolenaar446cb832008-06-24 21:56:24 +00004385 'ignorecase' is also on, the case of the match is adjusted depending
4386 on the typed text. If the typed text contains a lowercase letter
4387 where the match has an upper case letter, the completed part is made
4388 lowercase. If the typed text has no lowercase letters and the match
4389 has a lowercase letter where the typed text has an uppercase letter,
4390 and there is a letter before it, the completed part is made uppercase.
4391 With 'noinfercase' the match is used as-is.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004392
4393 *'insertmode'* *'im'* *'noinsertmode'* *'noim'*
4394'insertmode' 'im' boolean (default off)
4395 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004396 Makes Vim work in a way that Insert mode is the default mode. Useful
4397 if you want to use Vim as a modeless editor. Used for |evim|.
4398 These Insert mode commands will be useful:
4399 - Use the cursor keys to move around.
Bram Moolenaardc1f1642016-08-16 18:33:43 +02004400 - Use CTRL-O to execute one Normal mode command |i_CTRL-O|. When
Bram Moolenaar071d4272004-06-13 20:20:40 +00004401 this is a mapping, it is executed as if 'insertmode' was off.
4402 Normal mode remains active until the mapping is finished.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004403 - Use CTRL-L to execute a number of Normal mode commands, then use
Bram Moolenaar488c6512005-08-11 20:09:58 +00004404 <Esc> to get back to Insert mode. Note that CTRL-L moves the cursor
4405 left, like <Esc> does when 'insertmode' isn't set. |i_CTRL-L|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004406
4407 These items change when 'insertmode' is set:
4408 - when starting to edit of a file, Vim goes to Insert mode.
4409 - <Esc> in Insert mode is a no-op and beeps.
4410 - <Esc> in Normal mode makes Vim go to Insert mode.
4411 - CTRL-L in Insert mode is a command, it is not inserted.
4412 - CTRL-Z in Insert mode suspends Vim, see |CTRL-Z|. *i_CTRL-Z*
4413 However, when <Esc> is used inside a mapping, it behaves like
4414 'insertmode' was not set. This was done to be able to use the same
4415 mappings with 'insertmode' set or not set.
4416 When executing commands with |:normal| 'insertmode' is not used.
4417
4418 NOTE: This option is reset when 'compatible' is set.
4419
4420 *'isfname'* *'isf'*
4421'isfname' 'isf' string (default for MS-DOS, Win32 and OS/2:
4422 "@,48-57,/,\,.,-,_,+,,,#,$,%,{,},[,],:,@-@,!,~,="
4423 for AMIGA: "@,48-57,/,.,-,_,+,,,$,:"
4424 for VMS: "@,48-57,/,.,-,_,+,,,#,$,%,<,>,[,],:,;,~"
4425 for OS/390: "@,240-249,/,.,-,_,+,,,#,$,%,~,="
4426 otherwise: "@,48-57,/,.,-,_,+,,,#,$,%,~,=")
4427 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004428 The characters specified by this option are included in file names and
4429 path names. Filenames are used for commands like "gf", "[i" and in
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004430 the tags file. It is also used for "\f" in a |pattern|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004431 Multi-byte characters 256 and above are always included, only the
4432 characters up to 255 are specified with this option.
4433 For UTF-8 the characters 0xa0 to 0xff are included as well.
Bram Moolenaar446cb832008-06-24 21:56:24 +00004434 Think twice before adding white space to this option. Although a
4435 space may appear inside a file name, the effect will be that Vim
4436 doesn't know where a file name starts or ends when doing completion.
4437 It most likely works better without a space in 'isfname'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004438
4439 Note that on systems using a backslash as path separator, Vim tries to
4440 do its best to make it work as you would expect. That is a bit
4441 tricky, since Vi originally used the backslash to escape special
4442 characters. Vim will not remove a backslash in front of a normal file
4443 name character on these systems, but it will on Unix and alikes. The
4444 '&' and '^' are not included by default, because these are special for
4445 cmd.exe.
4446
4447 The format of this option is a list of parts, separated with commas.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004448 Each part can be a single character number or a range. A range is two
4449 character numbers with '-' in between. A character number can be a
Bram Moolenaar071d4272004-06-13 20:20:40 +00004450 decimal number between 0 and 255 or the ASCII character itself (does
4451 not work for digits). Example:
4452 "_,-,128-140,#-43" (include '_' and '-' and the range
4453 128 to 140 and '#' to 43)
4454 If a part starts with '^', the following character number or range
4455 will be excluded from the option. The option is interpreted from left
4456 to right. Put the excluded character after the range where it is
4457 included. To include '^' itself use it as the last character of the
4458 option or the end of a range. Example:
4459 "^a-z,#,^" (exclude 'a' to 'z', include '#' and '^')
4460 If the character is '@', all characters where isalpha() returns TRUE
4461 are included. Normally these are the characters a to z and A to Z,
4462 plus accented characters. To include '@' itself use "@-@". Examples:
4463 "@,^a-z" All alphabetic characters, excluding lower
Bram Moolenaar446cb832008-06-24 21:56:24 +00004464 case ASCII letters.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004465 "a-z,A-Z,@-@" All letters plus the '@' character.
4466 A comma can be included by using it where a character number is
4467 expected. Example:
4468 "48-57,,,_" Digits, comma and underscore.
4469 A comma can be excluded by prepending a '^'. Example:
4470 " -~,^,,9" All characters from space to '~', excluding
4471 comma, plus <Tab>.
4472 See |option-backslash| about including spaces and backslashes.
4473
4474 *'isident'* *'isi'*
4475'isident' 'isi' string (default for MS-DOS, Win32 and OS/2:
4476 "@,48-57,_,128-167,224-235"
4477 otherwise: "@,48-57,_,192-255")
4478 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004479 The characters given by this option are included in identifiers.
4480 Identifiers are used in recognizing environment variables and after a
4481 match of the 'define' option. It is also used for "\i" in a
Bram Moolenaar582fd852005-03-28 20:58:01 +00004482 |pattern|. See 'isfname' for a description of the format of this
Bram Moolenaar95bafa22018-10-02 13:26:25 +02004483 option. For '@' only characters up to 255 are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004484 Careful: If you change this option, it might break expanding
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004485 environment variables. E.g., when '/' is included and Vim tries to
Bram Moolenaar071d4272004-06-13 20:20:40 +00004486 expand "$HOME/.viminfo". Maybe you should change 'iskeyword' instead.
4487
4488 *'iskeyword'* *'isk'*
4489'iskeyword' 'isk' string (Vim default for MS-DOS and Win32:
4490 "@,48-57,_,128-167,224-235"
4491 otherwise: "@,48-57,_,192-255"
4492 Vi default: "@,48-57,_")
4493 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00004494 Keywords are used in searching and recognizing with many commands:
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004495 "w", "*", "[i", etc. It is also used for "\k" in a |pattern|. See
Bram Moolenaar95bafa22018-10-02 13:26:25 +02004496 'isfname' for a description of the format of this option. For '@'
4497 characters above 255 check the "word" character class.
4498 For C programs you could use "a-z,A-Z,48-57,_,.,-,>".
Bram Moolenaar071d4272004-06-13 20:20:40 +00004499 For a help file it is set to all non-blank printable characters except
4500 '*', '"' and '|' (so that CTRL-] on a command finds the help for that
4501 command).
4502 When the 'lisp' option is on the '-' character is always included.
Bram Moolenaarb8060fe2016-01-19 22:29:28 +01004503 This option also influences syntax highlighting, unless the syntax
4504 uses |:syn-iskeyword|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004505 NOTE: This option is set to the Vi default value when 'compatible' is
4506 set and to the Vim default value when 'compatible' is reset.
4507
4508 *'isprint'* *'isp'*
4509'isprint' 'isp' string (default for MS-DOS, Win32, OS/2 and Macintosh:
4510 "@,~-255"; otherwise: "@,161-255")
4511 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004512 The characters given by this option are displayed directly on the
4513 screen. It is also used for "\p" in a |pattern|. The characters from
4514 space (ASCII 32) to '~' (ASCII 126) are always displayed directly,
4515 even when they are not included in 'isprint' or excluded. See
4516 'isfname' for a description of the format of this option.
4517
4518 Non-printable characters are displayed with two characters:
4519 0 - 31 "^@" - "^_"
4520 32 - 126 always single characters
4521 127 "^?"
4522 128 - 159 "~@" - "~_"
4523 160 - 254 "| " - "|~"
4524 255 "~?"
4525 When 'encoding' is a Unicode one, illegal bytes from 128 to 255 are
4526 displayed as <xx>, with the hexadecimal value of the byte.
4527 When 'display' contains "uhex" all unprintable characters are
4528 displayed as <xx>.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004529 The SpecialKey highlighting will be used for unprintable characters.
4530 |hl-SpecialKey|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004531
4532 Multi-byte characters 256 and above are always included, only the
4533 characters up to 255 are specified with this option. When a character
4534 is printable but it is not available in the current font, a
4535 replacement character will be shown.
4536 Unprintable and zero-width Unicode characters are displayed as <xxxx>.
4537 There is no option to specify these characters.
4538
4539 *'joinspaces'* *'js'* *'nojoinspaces'* *'nojs'*
4540'joinspaces' 'js' boolean (default on)
4541 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004542 Insert two spaces after a '.', '?' and '!' with a join command.
4543 When 'cpoptions' includes the 'j' flag, only do this after a '.'.
4544 Otherwise only one space is inserted.
4545 NOTE: This option is set when 'compatible' is set.
4546
4547 *'key'*
4548'key' string (default "")
4549 local to buffer
Bram Moolenaar996343d2010-07-04 22:20:21 +02004550 {only available when compiled with the |+cryptv|
4551 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00004552 The key that is used for encrypting and decrypting the current buffer.
Bram Moolenaar40e6a712010-05-16 22:32:54 +02004553 See |encryption| and 'cryptmethod'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004554 Careful: Do not set the key value by hand, someone might see the typed
4555 key. Use the |:X| command. But you can make 'key' empty: >
4556 :set key=
4557< It is not possible to get the value of this option with ":set key" or
4558 "echo &key". This is to avoid showing it to someone who shouldn't
4559 know. It also means you cannot see it yourself once you have set it,
4560 be careful not to make a typing error!
Bram Moolenaard58e9292011-02-09 17:07:58 +01004561 You can use "&key" in an expression to detect whether encryption is
4562 enabled. When 'key' is set it returns "*****" (five stars).
Bram Moolenaar071d4272004-06-13 20:20:40 +00004563
4564 *'keymap'* *'kmp'* *E544*
4565'keymap' 'kmp' string (default "")
4566 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00004567 {only available when compiled with the |+keymap|
4568 feature}
4569 Name of a keyboard mapping. See |mbyte-keymap|.
4570 Setting this option to a valid keymap name has the side effect of
4571 setting 'iminsert' to one, so that the keymap becomes effective.
4572 'imsearch' is also set to one, unless it was -1
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00004573 Only normal file name characters can be used, "/\*?[|<>" are illegal.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004574
4575 *'keymodel'* *'km'*
4576'keymodel' 'km' string (default "")
4577 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004578 List of comma separated words, which enable special things that keys
4579 can do. These values can be used:
4580 startsel Using a shifted special key starts selection (either
4581 Select mode or Visual mode, depending on "key" being
4582 present in 'selectmode').
4583 stopsel Using a not-shifted special key stops selection.
4584 Special keys in this context are the cursor keys, <End>, <Home>,
4585 <PageUp> and <PageDown>.
4586 The 'keymodel' option is set by the |:behave| command.
4587
4588 *'keywordprg'* *'kp'*
4589'keywordprg' 'kp' string (default "man" or "man -s", DOS: ":help",
Bram Moolenaar2ff8b642016-05-24 10:46:45 +02004590 VMS: "help")
Bram Moolenaar071d4272004-06-13 20:20:40 +00004591 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004592 Program to use for the |K| command. Environment variables are
4593 expanded |:set_env|. ":help" may be used to access the Vim internal
4594 help. (Note that previously setting the global option to the empty
4595 value did this, which is now deprecated.)
Bram Moolenaar2ff8b642016-05-24 10:46:45 +02004596 When the first character is ":", the command is invoked as a Vim
4597 Ex command prefixed with [count].
4598 When "man", "man -s" or an Ex command is used, Vim will automatically
4599 translate a count for the "K" command and pass it as the first
4600 argument. For "man -s" the "-s" is removed when there is no count.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004601 See |option-backslash| about including spaces and backslashes.
4602 Example: >
4603 :set keywordprg=man\ -s
4604< This option cannot be set from a |modeline| or in the |sandbox|, for
4605 security reasons.
4606
4607 *'langmap'* *'lmap'* *E357* *E358*
4608'langmap' 'lmap' string (default "")
4609 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004610 {only available when compiled with the |+langmap|
4611 feature}
4612 This option allows switching your keyboard into a special language
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004613 mode. When you are typing text in Insert mode the characters are
Bram Moolenaarfa735342016-01-03 22:14:44 +01004614 inserted directly. When in Normal mode the 'langmap' option takes
Bram Moolenaar071d4272004-06-13 20:20:40 +00004615 care of translating these special characters to the original meaning
4616 of the key. This means you don't have to change the keyboard mode to
4617 be able to execute Normal mode commands.
4618 This is the opposite of the 'keymap' option, where characters are
4619 mapped in Insert mode.
Bram Moolenaare4a3bcf2016-08-26 19:52:37 +02004620 Also consider resetting 'langremap' to avoid 'langmap' applies to
Bram Moolenaarc2299672014-11-13 14:25:38 +01004621 characters resulting from a mapping.
Bram Moolenaare968e362014-05-13 20:23:24 +02004622 This option cannot be set from a |modeline| or in the |sandbox|, for
4623 security reasons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004624
Bram Moolenaarfd2ac762006-03-01 22:09:21 +00004625 Example (for Greek, in UTF-8): *greek* >
4626 :set 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
Bram Moolenaar071d4272004-06-13 20:20:40 +00004627< Example (exchanges meaning of z and y for commands): >
4628 :set langmap=zy,yz,ZY,YZ
4629<
4630 The 'langmap' option is a list of parts, separated with commas. Each
4631 part can be in one of two forms:
4632 1. A list of pairs. Each pair is a "from" character immediately
4633 followed by the "to" character. Examples: "aA", "aAbBcC".
4634 2. A list of "from" characters, a semi-colon and a list of "to"
4635 characters. Example: "abc;ABC"
4636 Example: "aA,fgh;FGH,cCdDeE"
4637 Special characters need to be preceded with a backslash. These are
4638 ";", ',' and backslash itself.
4639
4640 This will allow you to activate vim actions without having to switch
4641 back and forth between the languages. Your language characters will
4642 be understood as normal vim English characters (according to the
4643 langmap mappings) in the following cases:
4644 o Normal/Visual mode (commands, buffer/register names, user mappings)
4645 o Insert/Replace Mode: Register names after CTRL-R
4646 o Insert/Replace Mode: Mappings
4647 Characters entered in Command-line mode will NOT be affected by
4648 this option. Note that this option can be changed at any time
4649 allowing to switch between mappings for different languages/encodings.
4650 Use a mapping to avoid having to type it each time!
4651
4652 *'langmenu'* *'lm'*
4653'langmenu' 'lm' string (default "")
4654 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004655 {only available when compiled with the |+menu| and
4656 |+multi_lang| features}
4657 Language to use for menu translation. Tells which file is loaded
4658 from the "lang" directory in 'runtimepath': >
4659 "lang/menu_" . &langmenu . ".vim"
4660< (without the spaces). For example, to always use the Dutch menus, no
4661 matter what $LANG is set to: >
4662 :set langmenu=nl_NL.ISO_8859-1
4663< When 'langmenu' is empty, |v:lang| is used.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00004664 Only normal file name characters can be used, "/\*?[|<>" are illegal.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004665 If your $LANG is set to a non-English language but you do want to use
4666 the English menus: >
4667 :set langmenu=none
4668< This option must be set before loading menus, switching on filetype
4669 detection or syntax highlighting. Once the menus are defined setting
4670 this option has no effect. But you could do this: >
4671 :source $VIMRUNTIME/delmenu.vim
4672 :set langmenu=de_DE.ISO_8859-1
4673 :source $VIMRUNTIME/menu.vim
4674< Warning: This deletes all menus that you defined yourself!
4675
Bram Moolenaard94464e2015-11-02 15:28:18 +01004676 *'langnoremap'* *'lnr'* *'nolangnoremap'* *'nolnr'*
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +02004677'langnoremap' 'lnr' boolean (default off, set in |defaults.vim|)
Bram Moolenaar4391cf92014-11-05 17:44:52 +01004678 global
Bram Moolenaar4391cf92014-11-05 17:44:52 +01004679 {only available when compiled with the |+langmap|
4680 feature}
Bram Moolenaare4a3bcf2016-08-26 19:52:37 +02004681 This is just like 'langremap' but with the value inverted. It only
4682 exists for backwards compatibility. When setting 'langremap' then
4683 'langnoremap' is set to the inverted value, and the other way around.
4684
4685 *'langremap'* *'lrm'* *'nolangremap'* *'nolrm'*
4686'langremap' 'lrm' boolean (default on, reset in |defaults.vim|)
4687 global
Bram Moolenaare4a3bcf2016-08-26 19:52:37 +02004688 {only available when compiled with the |+langmap|
4689 feature}
4690 When off, setting 'langmap' does not apply to characters resulting from
Bram Moolenaar4391cf92014-11-05 17:44:52 +01004691 a mapping. This basically means, if you noticed that setting
Bram Moolenaare4a3bcf2016-08-26 19:52:37 +02004692 'langmap' disables some of your mappings, try resetting this option.
4693 This option defaults to on for backwards compatibility. Set it off if
Bram Moolenaar4391cf92014-11-05 17:44:52 +01004694 that works for you to avoid mappings to break.
4695
Bram Moolenaar071d4272004-06-13 20:20:40 +00004696 *'laststatus'* *'ls'*
4697'laststatus' 'ls' number (default 1)
4698 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004699 The value of this option influences when the last window will have a
4700 status line:
4701 0: never
4702 1: only if there are at least two windows
4703 2: always
4704 The screen looks nicer with a status line if you have several
4705 windows, but it takes another screen line. |status-line|
4706
4707 *'lazyredraw'* *'lz'* *'nolazyredraw'* *'nolz'*
4708'lazyredraw' 'lz' boolean (default off)
4709 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004710 When this option is set, the screen will not be redrawn while
4711 executing macros, registers and other commands that have not been
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004712 typed. Also, updating the window title is postponed. To force an
Bram Moolenaar071d4272004-06-13 20:20:40 +00004713 update use |:redraw|.
4714
4715 *'linebreak'* *'lbr'* *'nolinebreak'* *'nolbr'*
4716'linebreak' 'lbr' boolean (default off)
4717 local to window
Bram Moolenaardb84e452010-08-15 13:50:43 +02004718 {not available when compiled without the |+linebreak|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004719 feature}
Bram Moolenaar946e27a2014-06-25 18:50:27 +02004720 If on, Vim will wrap long lines at a character in 'breakat' rather
Bram Moolenaar071d4272004-06-13 20:20:40 +00004721 than at the last character that fits on the screen. Unlike
4722 'wrapmargin' and 'textwidth', this does not insert <EOL>s in the file,
Bram Moolenaar946e27a2014-06-25 18:50:27 +02004723 it only affects the way the file is displayed, not its contents.
4724 If 'breakindent' is set, line is visually indented. Then, the value
4725 of 'showbreak' is used to put in front of wrapped lines. This option
Bram Moolenaar86b17e92014-07-02 20:00:47 +02004726 is not used when the 'wrap' option is off.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004727 Note that <Tab> characters after an <EOL> are mostly not displayed
4728 with the right amount of white space.
4729
4730 *'lines'* *E593*
4731'lines' number (default 24 or terminal height)
4732 global
4733 Number of lines of the Vim window.
4734 Normally you don't need to set this. It is done automatically by the
Bram Moolenaar7c626922005-02-07 22:01:03 +00004735 terminal initialization code. Also see |posix-screen-size|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004736 When Vim is running in the GUI or in a resizable window, setting this
4737 option will cause the window size to be changed. When you only want
4738 to use the size for the GUI, put the command in your |gvimrc| file.
4739 Vim limits the number of lines to what fits on the screen. You can
4740 use this command to get the tallest window possible: >
4741 :set lines=999
Bram Moolenaarf4d11452005-12-02 00:46:37 +00004742< Minimum value is 2, maximum value is 1000.
Bram Moolenaardc1f1642016-08-16 18:33:43 +02004743 If you get fewer lines than expected, check the 'guiheadroom' option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004744 When you set this option and Vim is unable to change the physical
4745 number of lines of the display, the display may be messed up.
4746
4747 *'linespace'* *'lsp'*
4748'linespace' 'lsp' number (default 0, 1 for Win32 GUI)
4749 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004750 {only in the GUI}
4751 Number of pixel lines inserted between characters. Useful if the font
4752 uses the full character cell height, making lines touch each other.
4753 When non-zero there is room for underlining.
Bram Moolenaarbc7aa852005-03-06 23:38:09 +00004754 With some fonts there can be too much room between lines (to have
4755 space for ascents and descents). Then it makes sense to set
4756 'linespace' to a negative value. This may cause display problems
4757 though!
Bram Moolenaar071d4272004-06-13 20:20:40 +00004758
4759 *'lisp'* *'nolisp'*
4760'lisp' boolean (default off)
4761 local to buffer
4762 {not available when compiled without the |+lispindent|
4763 feature}
4764 Lisp mode: When <Enter> is typed in insert mode set the indent for
4765 the next line to Lisp standards (well, sort of). Also happens with
4766 "cc" or "S". 'autoindent' must also be on for this to work. The 'p'
4767 flag in 'cpoptions' changes the method of indenting: Vi compatible or
4768 better. Also see 'lispwords'.
4769 The '-' character is included in keyword characters. Redefines the
4770 "=" operator to use this same indentation algorithm rather than
4771 calling an external program if 'equalprg' is empty.
4772 This option is not used when 'paste' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004773
4774 *'lispwords'* *'lw'*
4775'lispwords' 'lw' string (default is very long)
Bram Moolenaaraf6c1312014-03-12 18:55:58 +01004776 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004777 {not available when compiled without the |+lispindent|
4778 feature}
4779 Comma separated list of words that influence the Lisp indenting.
4780 |'lisp'|
4781
4782 *'list'* *'nolist'*
4783'list' boolean (default off)
4784 local to window
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004785 List mode: Show tabs as CTRL-I is displayed, display $ after end of
4786 line. Useful to see the difference between tabs and spaces and for
4787 trailing blanks. Further changed by the 'listchars' option.
4788
4789 The cursor is displayed at the start of the space a Tab character
4790 occupies, not at the end as usual in Normal mode. To get this cursor
4791 position while displaying Tabs with spaces, use: >
Bram Moolenaardd007ed2013-07-09 15:44:17 +02004792 :set list lcs=tab:\ \
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004793<
4794 Note that list mode will also affect formatting (set with 'textwidth'
4795 or 'wrapmargin') when 'cpoptions' includes 'L'. See 'listchars' for
Bram Moolenaar071d4272004-06-13 20:20:40 +00004796 changing the way tabs are displayed.
4797
4798 *'listchars'* *'lcs'*
4799'listchars' 'lcs' string (default "eol:$")
4800 global
Bram Moolenaarf9d5ca12010-08-01 16:13:51 +02004801 Strings to use in 'list' mode and for the |:list| command. It is a
4802 comma separated list of string settings.
Bram Moolenaar79278362015-04-21 18:33:48 +02004803 *lcs-eol*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004804 eol:c Character to show at the end of each line. When
4805 omitted, there is no extra character at the end of the
4806 line.
Bram Moolenaar79278362015-04-21 18:33:48 +02004807 *lcs-tab*
Bram Moolenaar83a52172019-01-16 22:41:54 +01004808 tab:xy[z] Two or three characters to be used to show a tab.
4809 The third character is optional.
4810
4811 tab:xy The 'x' is always used, then 'y' as many times as will
4812 fit. Thus "tab:>-" displays:
4813 >
4814 >-
4815 >--
4816 etc.
4817
4818 tab:xyz The 'z' is always used, then 'x' is prepended, and
4819 then 'y' is used as many times as will fit. Thus
4820 "tab:<->" displays:
4821 >
4822 <>
4823 <->
4824 <-->
4825 etc.
4826
4827 When "tab:" is omitted, a tab is shown as ^I.
Bram Moolenaar79278362015-04-21 18:33:48 +02004828 *lcs-space*
4829 space:c Character to show for a space. When omitted, spaces
4830 are left blank.
4831 *lcs-trail*
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004832 trail:c Character to show for trailing spaces. When omitted,
Bram Moolenaar79278362015-04-21 18:33:48 +02004833 trailing spaces are blank. Overrides the "space"
4834 setting for trailing spaces.
4835 *lcs-extends*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004836 extends:c Character to show in the last column, when 'wrap' is
4837 off and the line continues beyond the right of the
4838 screen.
Bram Moolenaar79278362015-04-21 18:33:48 +02004839 *lcs-precedes*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004840 precedes:c Character to show in the first column, when 'wrap'
4841 is off and there is text preceding the character
4842 visible in the first column.
Bram Moolenaar79278362015-04-21 18:33:48 +02004843 *lcs-conceal*
Bram Moolenaar860cae12010-06-05 23:22:07 +02004844 conceal:c Character to show in place of concealed text, when
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02004845 'conceallevel' is set to 1.
Bram Moolenaar79278362015-04-21 18:33:48 +02004846 *lcs-nbsp*
Bram Moolenaar73284b92015-05-04 17:28:22 +02004847 nbsp:c Character to show for a non-breakable space character
4848 (0xA0 (160 decimal) and U+202F). Left blank when
4849 omitted.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004850
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004851 The characters ':' and ',' should not be used. UTF-8 characters can
Bram Moolenaar071d4272004-06-13 20:20:40 +00004852 be used when 'encoding' is "utf-8", otherwise only printable
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004853 characters are allowed. All characters must be single width.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004854
4855 Examples: >
4856 :set lcs=tab:>-,trail:-
Bram Moolenaarcfbc5ee2004-07-02 15:38:35 +00004857 :set lcs=tab:>-,eol:<,nbsp:%
Bram Moolenaar071d4272004-06-13 20:20:40 +00004858 :set lcs=extends:>,precedes:<
4859< The "NonText" highlighting will be used for "eol", "extends" and
Bram Moolenaar79278362015-04-21 18:33:48 +02004860 "precedes". "SpecialKey" for "nbsp", "space", "tab" and "trail".
Bram Moolenaar02467872007-05-06 13:22:01 +00004861 |hl-NonText| |hl-SpecialKey|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004862
4863 *'lpl'* *'nolpl'* *'loadplugins'* *'noloadplugins'*
4864'loadplugins' 'lpl' boolean (default on)
4865 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004866 When on the plugin scripts are loaded when starting up |load-plugins|.
4867 This option can be reset in your |vimrc| file to disable the loading
4868 of plugins.
Bram Moolenaarc4da1132017-07-15 19:39:43 +02004869 Note that using the "-u NONE", "-u DEFAULTS" and "--noplugin" command
4870 line arguments reset this option. See |-u| and |--noplugin|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004871
Bram Moolenaard94464e2015-11-02 15:28:18 +01004872 *'luadll'*
Bram Moolenaar3848e002016-03-19 18:42:29 +01004873'luadll' string (default depends on the build)
Bram Moolenaard94464e2015-11-02 15:28:18 +01004874 global
Bram Moolenaard94464e2015-11-02 15:28:18 +01004875 {only available when compiled with the |+lua/dyn|
4876 feature}
Bram Moolenaar25e4fcd2016-01-09 14:57:47 +01004877 Specifies the name of the Lua shared library. The default is
4878 DYNAMIC_LUA_DLL, which was specified at compile time.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02004879 Environment variables are expanded |:set_env|.
Bram Moolenaard94464e2015-11-02 15:28:18 +01004880 This option cannot be set from a |modeline| or in the |sandbox|, for
4881 security reasons.
4882
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00004883 *'macatsui'* *'nomacatsui'*
4884'macatsui' boolean (default on)
4885 global
4886 {only available in Mac GUI version}
4887 This is a workaround for when drawing doesn't work properly. When set
4888 and compiled with multi-byte support ATSUI text drawing is used. When
4889 not set ATSUI text drawing is not used. Switch this option off when
4890 you experience drawing problems. In a future version the problems may
4891 be solved and this option becomes obsolete. Therefore use this method
4892 to unset it: >
4893 if exists('&macatsui')
4894 set nomacatsui
4895 endif
Bram Moolenaar02467872007-05-06 13:22:01 +00004896< Another option to check if you have drawing problems is
4897 'termencoding'.
4898
Bram Moolenaar071d4272004-06-13 20:20:40 +00004899 *'magic'* *'nomagic'*
4900'magic' boolean (default on)
4901 global
4902 Changes the special characters that can be used in search patterns.
4903 See |pattern|.
Bram Moolenaar64d8e252016-09-06 22:12:34 +02004904 WARNING: Switching this option off most likely breaks plugins! That
4905 is because many patterns assume it's on and will fail when it's off.
4906 Only switch it off when working with old Vi scripts. In any other
4907 situation write patterns that work when 'magic' is on. Include "\M"
4908 when you want to |/\M|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004909
4910 *'makeef'* *'mef'*
4911'makeef' 'mef' string (default: "")
4912 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004913 {not available when compiled without the |+quickfix|
4914 feature}
4915 Name of the errorfile for the |:make| command (see |:make_makeprg|)
4916 and the |:grep| command.
4917 When it is empty, an internally generated temp file will be used.
4918 When "##" is included, it is replaced by a number to make the name
4919 unique. This makes sure that the ":make" command doesn't overwrite an
4920 existing file.
4921 NOT used for the ":cf" command. See 'errorfile' for that.
4922 Environment variables are expanded |:set_env|.
4923 See |option-backslash| about including spaces and backslashes.
4924 This option cannot be set from a |modeline| or in the |sandbox|, for
4925 security reasons.
4926
Bram Moolenaar2c7292d2017-03-05 17:43:31 +01004927 *'makeencoding'* *'menc'*
4928'makeencoding' 'menc' string (default "")
4929 global or local to buffer |global-local|
Bram Moolenaar2c7292d2017-03-05 17:43:31 +01004930 Encoding used for reading the output of external commands. When empty,
4931 encoding is not converted.
4932 This is used for `:make`, `:lmake`, `:grep`, `:lgrep`, `:grepadd`,
4933 `:lgrepadd`, `:cfile`, `:cgetfile`, `:caddfile`, `:lfile`, `:lgetfile`,
4934 and `:laddfile`.
4935
4936 This would be mostly useful when you use MS-Windows and set 'encoding'
4937 to "utf-8". If |+iconv| is enabled and GNU libiconv is used, setting
4938 'makeencoding' to "char" has the same effect as setting to the system
4939 locale encoding. Example: >
4940 :set encoding=utf-8
4941 :set makeencoding=char " system locale is used
4942<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004943 *'makeprg'* *'mp'*
4944'makeprg' 'mp' string (default "make", VMS: "MMS")
4945 global or local to buffer |global-local|
Bram Moolenaar02467872007-05-06 13:22:01 +00004946 Program to use for the ":make" command. See |:make_makeprg|.
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01004947 This option may contain '%' and '#' characters (see |:_%| and |:_#|),
4948 which are expanded to the current and alternate file name. Use |::S|
Bram Moolenaar26df0922014-02-23 23:39:13 +01004949 to escape file names in case they contain special characters.
Bram Moolenaar02467872007-05-06 13:22:01 +00004950 Environment variables are expanded |:set_env|. See |option-backslash|
4951 about including spaces and backslashes.
4952 Note that a '|' must be escaped twice: once for ":set" and once for
4953 the interpretation of a command. When you use a filter called
4954 "myfilter" do it like this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004955 :set makeprg=gmake\ \\\|\ myfilter
4956< The placeholder "$*" can be given (even multiple times) to specify
4957 where the arguments will be included, for example: >
4958 :set makeprg=latex\ \\\\nonstopmode\ \\\\input\\{$*}
4959< This option cannot be set from a |modeline| or in the |sandbox|, for
4960 security reasons.
4961
4962 *'matchpairs'* *'mps'*
4963'matchpairs' 'mps' string (default "(:),{:},[:]")
4964 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00004965 Characters that form pairs. The |%| command jumps from one to the
Bram Moolenaara3e6bc92013-01-30 14:18:00 +01004966 other.
4967 Only character pairs are allowed that are different, thus you cannot
4968 jump between two double quotes.
4969 The characters must be separated by a colon.
Bram Moolenaar02467872007-05-06 13:22:01 +00004970 The pairs must be separated by a comma. Example for including '<' and
4971 '>' (HTML): >
Bram Moolenaar071d4272004-06-13 20:20:40 +00004972 :set mps+=<:>
4973
4974< A more exotic example, to jump between the '=' and ';' in an
4975 assignment, useful for languages like C and Java: >
4976 :au FileType c,cpp,java set mps+==:;
4977
4978< For a more advanced way of using "%", see the matchit.vim plugin in
Bram Moolenaar01164a62017-11-02 22:58:42 +01004979 the $VIMRUNTIME/pack/dist/opt/matchit directory. |add-local-help|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004980
4981 *'matchtime'* *'mat'*
4982'matchtime' 'mat' number (default 5)
4983 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004984 Tenths of a second to show the matching paren, when 'showmatch' is
4985 set. Note that this is not in milliseconds, like other options that
4986 set a time. This is to be compatible with Nvi.
4987
Bram Moolenaar362e1a32006-03-06 23:29:24 +00004988 *'maxcombine'* *'mco'*
4989'maxcombine' 'mco' number (default 2)
4990 global
Bram Moolenaar362e1a32006-03-06 23:29:24 +00004991 The maximum number of combining characters supported for displaying.
4992 Only used when 'encoding' is "utf-8".
4993 The default is OK for most languages. Hebrew may require 4.
4994 Maximum value is 6.
4995 Even when this option is set to 2 you can still edit text with more
4996 combining characters, you just can't see them. Use |g8| or |ga|.
4997 See |mbyte-combining|.
4998
Bram Moolenaar071d4272004-06-13 20:20:40 +00004999 *'maxfuncdepth'* *'mfd'*
5000'maxfuncdepth' 'mfd' number (default 100)
5001 global
Bram Moolenaardb84e452010-08-15 13:50:43 +02005002 {not available when compiled without the |+eval|
Bram Moolenaar02467872007-05-06 13:22:01 +00005003 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00005004 Maximum depth of function calls for user functions. This normally
5005 catches endless recursion. When using a recursive function with
5006 more depth, set 'maxfuncdepth' to a bigger number. But this will use
5007 more memory, there is the danger of failing when memory is exhausted.
Bram Moolenaarbc2eada2017-01-02 21:27:47 +01005008 Increasing this limit above 200 also changes the maximum for Ex
Bram Moolenaar0b0f0992018-05-22 21:41:30 +02005009 command recursion, see |E169|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005010 See also |:function|.
5011
5012 *'maxmapdepth'* *'mmd'* *E223*
5013'maxmapdepth' 'mmd' number (default 1000)
5014 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005015 Maximum number of times a mapping is done without resulting in a
5016 character to be used. This normally catches endless mappings, like
5017 ":map x y" with ":map y x". It still does not catch ":map g wg",
5018 because the 'w' is used before the next mapping is done. See also
5019 |key-mapping|.
5020
5021 *'maxmem'* *'mm'*
5022'maxmem' 'mm' number (default between 256 to 5120 (system
5023 dependent) or half the amount of memory
5024 available)
5025 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005026 Maximum amount of memory (in Kbyte) to use for one buffer. When this
5027 limit is reached allocating extra memory for a buffer will cause
Bram Moolenaarcafafb32018-02-22 21:07:09 +01005028 other memory to be freed.
5029 The maximum usable value is about 2000000. Use this to work without a
5030 limit.
5031 The value is ignored when 'swapfile' is off.
5032 Also see 'maxmemtot'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005033
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00005034 *'maxmempattern'* *'mmp'*
5035'maxmempattern' 'mmp' number (default 1000)
5036 global
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00005037 Maximum amount of memory (in Kbyte) to use for pattern matching.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005038 The maximum value is about 2000000. Use this to work without a limit.
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00005039 *E363*
Bram Moolenaar02467872007-05-06 13:22:01 +00005040 When Vim runs into the limit it gives an error message and mostly
5041 behaves like CTRL-C was typed.
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00005042 Running into the limit often means that the pattern is very
5043 inefficient or too complex. This may already happen with the pattern
5044 "\(.\)*" on a very long line. ".*" works much better.
Bram Moolenaarfd358112018-07-07 23:21:31 +02005045 Might also happen on redraw, when syntax rules try to match a complex
5046 text structure.
5047 Vim may run out of memory before hitting the 'maxmempattern' limit, in
5048 which case you get an "Out of memory" error instead.
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00005049
Bram Moolenaar071d4272004-06-13 20:20:40 +00005050 *'maxmemtot'* *'mmt'*
5051'maxmemtot' 'mmt' number (default between 2048 and 10240 (system
5052 dependent) or half the amount of memory
5053 available)
5054 global
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005055 Maximum amount of memory in Kbyte to use for all buffers together.
5056 The maximum usable value is about 2000000 (2 Gbyte). Use this to work
Bram Moolenaarfa735342016-01-03 22:14:44 +01005057 without a limit.
5058 On 64 bit machines higher values might work. But hey, do you really
5059 need more than 2 Gbyte for text editing? Keep in mind that text is
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02005060 stored in the swap file, one can edit files > 2 Gbyte anyway. We do
Bram Moolenaarfa735342016-01-03 22:14:44 +01005061 need the memory to store undo info.
Bram Moolenaarcafafb32018-02-22 21:07:09 +01005062 Buffers with 'swapfile' off still count to the total amount of memory
5063 used.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005064 Also see 'maxmem'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005065
5066 *'menuitems'* *'mis'*
5067'menuitems' 'mis' number (default 25)
5068 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005069 {not available when compiled without the |+menu|
5070 feature}
5071 Maximum number of items to use in a menu. Used for menus that are
5072 generated from a list of items, e.g., the Buffers menu. Changing this
5073 option has no direct effect, the menu must be refreshed first.
5074
Bram Moolenaar8aff23a2005-08-19 20:40:30 +00005075 *'mkspellmem'* *'msm'*
5076'mkspellmem' 'msm' string (default "460000,2000,500")
5077 global
Bram Moolenaar8aff23a2005-08-19 20:40:30 +00005078 {not available when compiled without the |+syntax|
5079 feature}
5080 Parameters for |:mkspell|. This tunes when to start compressing the
5081 word tree. Compression can be slow when there are many words, but
5082 it's needed to avoid running out of memory. The amount of memory used
5083 per word depends very much on how similar the words are, that's why
5084 this tuning is complicated.
5085
5086 There are three numbers, separated by commas:
5087 {start},{inc},{added}
5088
5089 For most languages the uncompressed word tree fits in memory. {start}
5090 gives the amount of memory in Kbyte that can be used before any
5091 compression is done. It should be a bit smaller than the amount of
5092 memory that is available to Vim.
5093
5094 When going over the {start} limit the {inc} number specifies the
5095 amount of memory in Kbyte that can be allocated before another
5096 compression is done. A low number means compression is done after
5097 less words are added, which is slow. A high number means more memory
5098 will be allocated.
5099
5100 After doing compression, {added} times 1024 words can be added before
5101 the {inc} limit is ignored and compression is done when any extra
5102 amount of memory is needed. A low number means there is a smaller
5103 chance of hitting the {inc} limit, less memory is used but it's
5104 slower.
5105
5106 The languages for which these numbers are important are Italian and
5107 Hungarian. The default works for when you have about 512 Mbyte. If
5108 you have 1 Gbyte you could use: >
5109 :set mkspellmem=900000,3000,800
5110< If you have less than 512 Mbyte |:mkspell| may fail for some
5111 languages, no matter what you set 'mkspellmem' to.
5112
Bram Moolenaar07607392019-05-26 19:20:43 +02005113 This option cannot be set from a |modeline| or in the |sandbox|.
5114
Bram Moolenaar071d4272004-06-13 20:20:40 +00005115 *'modeline'* *'ml'* *'nomodeline'* *'noml'*
Bram Moolenaar8243a792007-05-01 17:05:03 +00005116'modeline' 'ml' boolean (Vim default: on (off for root),
5117 Vi default: off)
Bram Moolenaar071d4272004-06-13 20:20:40 +00005118 local to buffer
Bram Moolenaar110289e2019-05-23 15:38:06 +02005119 If 'modeline' is on 'modelines' gives the number of lines that is
5120 checked for set commands. If 'modeline' is off or 'modelines' is zero
5121 no lines are checked. See |modeline|.
5122
5123 *'modelineexpr'* *'mle'* *'nomodelineexpr'* *'nomle'*
5124'modelineexpr' 'mle' boolean (default: off)
5125 global
5126 When on allow some options that are an expression to be set in the
5127 modeline. Check the option for whether it is affected by
5128 'modelineexpr'. Also see |modeline|.
Bram Moolenaar1c6fd1e2019-05-23 22:11:59 +02005129 This option cannot be set from a |modeline| or in the |sandbox|, for
5130 security reasons.
Bram Moolenaar110289e2019-05-23 15:38:06 +02005131
Bram Moolenaar071d4272004-06-13 20:20:40 +00005132 *'modelines'* *'mls'*
5133'modelines' 'mls' number (default 5)
5134 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005135 If 'modeline' is on 'modelines' gives the number of lines that is
5136 checked for set commands. If 'modeline' is off or 'modelines' is zero
5137 no lines are checked. See |modeline|.
5138 NOTE: 'modeline' is set to the Vi default value when 'compatible' is
5139 set and to the Vim default value when 'compatible' is reset.
5140
5141 *'modifiable'* *'ma'* *'nomodifiable'* *'noma'*
Bram Moolenaar110289e2019-05-23 15:38:06 +02005142 *E21*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005143'modifiable' 'ma' boolean (default on)
5144 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00005145 When off the buffer contents cannot be changed. The 'fileformat' and
5146 'fileencoding' options also can't be changed.
Bram Moolenaar369b6f52017-01-17 12:22:32 +01005147 Can be reset on startup with the |-M| command line argument.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005148
5149 *'modified'* *'mod'* *'nomodified'* *'nomod'*
5150'modified' 'mod' boolean (default off)
5151 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00005152 When on, the buffer is considered to be modified. This option is set
5153 when:
5154 1. A change was made to the text since it was last written. Using the
5155 |undo| command to go back to the original text will reset the
5156 option. But undoing changes that were made before writing the
5157 buffer will set the option again, since the text is different from
5158 when it was written.
5159 2. 'fileformat' or 'fileencoding' is different from its original
5160 value. The original value is set when the buffer is read or
5161 written. A ":set nomodified" command also resets the original
5162 values to the current values and the 'modified' option will be
5163 reset.
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01005164 Similarly for 'eol' and 'bomb'.
Bram Moolenaar5302d9e2011-09-14 17:55:08 +02005165 This option is not set when a change is made to the buffer as the
5166 result of a BufNewFile, BufRead/BufReadPost, BufWritePost,
5167 FileAppendPost or VimLeave autocommand event. See |gzip-example| for
5168 an explanation.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005169 When 'buftype' is "nowrite" or "nofile" this option may be set, but
5170 will be ignored.
Bram Moolenaarb5b75622018-03-09 22:22:21 +01005171 Note that the text may actually be the same, e.g. 'modified' is set
5172 when using "rA" on an "A".
Bram Moolenaar071d4272004-06-13 20:20:40 +00005173
5174 *'more'* *'nomore'*
5175'more' boolean (Vim default: on, Vi default: off)
5176 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005177 When on, listings pause when the whole screen is filled. You will get
5178 the |more-prompt|. When this option is off there are no pauses, the
5179 listing continues until finished.
5180 NOTE: This option is set to the Vi default value when 'compatible' is
5181 set and to the Vim default value when 'compatible' is reset.
5182
5183 *'mouse'* *E538*
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +02005184'mouse' string (default "", "a" for GUI, MS-DOS and Win32,
5185 set to "a" in |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00005186 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005187 Enable the use of the mouse. Only works for certain terminals
Bram Moolenaar446cb832008-06-24 21:56:24 +00005188 (xterm, MS-DOS, Win32 |win32-mouse|, QNX pterm, *BSD console with
5189 sysmouse and Linux console with gpm). For using the mouse in the
5190 GUI, see |gui-mouse|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005191 The mouse can be enabled for different modes:
Bram Moolenaar7f2e9d72017-11-11 20:58:53 +01005192 n Normal mode and Terminal modes
Bram Moolenaar071d4272004-06-13 20:20:40 +00005193 v Visual mode
5194 i Insert mode
5195 c Command-line mode
5196 h all previous modes when editing a help file
5197 a all previous modes
5198 r for |hit-enter| and |more-prompt| prompt
Bram Moolenaar95bafa22018-10-02 13:26:25 +02005199 Normally you would enable the mouse in all five modes with: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005200 :set mouse=a
5201< When the mouse is not enabled, the GUI will still use the mouse for
5202 modeless selection. This doesn't move the text cursor.
5203
5204 See |mouse-using|. Also see |'clipboard'|.
5205
5206 Note: When enabling the mouse in a terminal, copy/paste will use the
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00005207 "* register if there is access to an X-server. The xterm handling of
Bram Moolenaar071d4272004-06-13 20:20:40 +00005208 the mouse buttons can still be used by keeping the shift key pressed.
5209 Also see the 'clipboard' option.
5210
5211 *'mousefocus'* *'mousef'* *'nomousefocus'* *'nomousef'*
5212'mousefocus' 'mousef' boolean (default off)
5213 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005214 {only works in the GUI}
5215 The window that the mouse pointer is on is automatically activated.
5216 When changing the window layout or window focus in another way, the
5217 mouse pointer is moved to the window with keyboard focus. Off is the
5218 default because it makes using the pull down menus a little goofy, as
5219 a pointer transit may activate a window unintentionally.
5220
5221 *'mousehide'* *'mh'* *'nomousehide'* *'nomh'*
5222'mousehide' 'mh' boolean (default on)
5223 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005224 {only works in the GUI}
5225 When on, the mouse pointer is hidden when characters are typed.
5226 The mouse pointer is restored when the mouse is moved.
5227
5228 *'mousemodel'* *'mousem'*
5229'mousemodel' 'mousem' string (default "extend", "popup" for MS-DOS and Win32)
5230 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005231 Sets the model to use for the mouse. The name mostly specifies what
5232 the right mouse button is used for:
5233 extend Right mouse button extends a selection. This works
5234 like in an xterm.
5235 popup Right mouse button pops up a menu. The shifted left
5236 mouse button extends a selection. This works like
Bram Moolenaar582fd852005-03-28 20:58:01 +00005237 with Microsoft Windows.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005238 popup_setpos Like "popup", but the cursor will be moved to the
5239 position where the mouse was clicked, and thus the
5240 selected operation will act upon the clicked object.
5241 If clicking inside a selection, that selection will
Bram Moolenaar582fd852005-03-28 20:58:01 +00005242 be acted upon, i.e. no cursor move. This implies of
Bram Moolenaar071d4272004-06-13 20:20:40 +00005243 course, that right clicking outside a selection will
5244 end Visual mode.
5245 Overview of what button does what for each model:
5246 mouse extend popup(_setpos) ~
5247 left click place cursor place cursor
5248 left drag start selection start selection
5249 shift-left search word extend selection
5250 right click extend selection popup menu (place cursor)
5251 right drag extend selection -
5252 middle click paste paste
5253
5254 In the "popup" model the right mouse button produces a pop-up menu.
5255 You need to define this first, see |popup-menu|.
5256
5257 Note that you can further refine the meaning of buttons with mappings.
5258 See |gui-mouse-mapping|. But mappings are NOT used for modeless
5259 selection (because that's handled in the GUI code directly).
5260
5261 The 'mousemodel' option is set by the |:behave| command.
5262
5263 *'mouseshape'* *'mouses'* *E547*
Bram Moolenaarf6b40102019-02-22 15:24:03 +01005264'mouseshape' 'mouses' string (default "i-r:beam,s:updown,sd:udsizing,
5265 vs:leftright,vd:lrsizing,m:no,
5266 ml:up-arrow,v:rightup-arrow")
Bram Moolenaar071d4272004-06-13 20:20:40 +00005267 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005268 {only available when compiled with the |+mouseshape|
5269 feature}
5270 This option tells Vim what the mouse pointer should look like in
5271 different modes. The option is a comma separated list of parts, much
5272 like used for 'guicursor'. Each part consist of a mode/location-list
5273 and an argument-list:
5274 mode-list:shape,mode-list:shape,..
5275 The mode-list is a dash separated list of these modes/locations:
5276 In a normal window: ~
5277 n Normal mode
5278 v Visual mode
5279 ve Visual mode with 'selection' "exclusive" (same as 'v',
5280 if not specified)
5281 o Operator-pending mode
5282 i Insert mode
5283 r Replace mode
5284
5285 Others: ~
5286 c appending to the command-line
5287 ci inserting in the command-line
5288 cr replacing in the command-line
5289 m at the 'Hit ENTER' or 'More' prompts
5290 ml idem, but cursor in the last line
5291 e any mode, pointer below last window
5292 s any mode, pointer on a status line
5293 sd any mode, while dragging a status line
5294 vs any mode, pointer on a vertical separator line
5295 vd any mode, while dragging a vertical separator line
5296 a everywhere
5297
5298 The shape is one of the following:
5299 avail name looks like ~
5300 w x arrow Normal mouse pointer
5301 w x blank no pointer at all (use with care!)
5302 w x beam I-beam
5303 w x updown up-down sizing arrows
5304 w x leftright left-right sizing arrows
5305 w x busy The system's usual busy pointer
5306 w x no The system's usual 'no input' pointer
5307 x udsizing indicates up-down resizing
5308 x lrsizing indicates left-right resizing
5309 x crosshair like a big thin +
5310 x hand1 black hand
5311 x hand2 white hand
5312 x pencil what you write with
5313 x question big ?
5314 x rightup-arrow arrow pointing right-up
5315 w x up-arrow arrow pointing up
5316 x <number> any X11 pointer number (see X11/cursorfont.h)
5317
5318 The "avail" column contains a 'w' if the shape is available for Win32,
5319 x for X11.
5320 Any modes not specified or shapes not available use the normal mouse
5321 pointer.
5322
5323 Example: >
5324 :set mouseshape=s:udsizing,m:no
5325< will make the mouse turn to a sizing arrow over the status lines and
5326 indicate no input when the hit-enter prompt is displayed (since
5327 clicking the mouse has no effect in this state.)
5328
5329 *'mousetime'* *'mouset'*
5330'mousetime' 'mouset' number (default 500)
5331 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005332 Only for GUI, MS-DOS, Win32 and Unix with xterm. Defines the maximum
5333 time in msec between two mouse clicks for the second click to be
5334 recognized as a multi click.
5335
Bram Moolenaar0ab35b22017-10-08 17:41:37 +02005336 *'mzschemedll'*
5337'mzschemedll' string (default depends on the build)
5338 global
Bram Moolenaar0ab35b22017-10-08 17:41:37 +02005339 {only available when compiled with the |+mzscheme/dyn|
5340 feature}
5341 Specifies the name of the MzScheme shared library. The default is
5342 DYNAMIC_MZSCH_DLL which was specified at compile time.
5343 Environment variables are expanded |:set_env|.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01005344 The value must be set in the |vimrc| script or earlier. In the
Bram Moolenaar01164a62017-11-02 22:58:42 +01005345 startup, before the |load-plugins| step.
Bram Moolenaar0ab35b22017-10-08 17:41:37 +02005346 This option cannot be set from a |modeline| or in the |sandbox|, for
5347 security reasons.
5348
5349 *'mzschemegcdll'*
5350'mzschemegcdll' string (default depends on the build)
5351 global
Bram Moolenaar0ab35b22017-10-08 17:41:37 +02005352 {only available when compiled with the |+mzscheme/dyn|
5353 feature}
5354 Specifies the name of the MzScheme GC shared library. The default is
5355 DYNAMIC_MZGC_DLL which was specified at compile time.
5356 The value can be equal to 'mzschemedll' if it includes the GC code.
5357 Environment variables are expanded |:set_env|.
5358 This option cannot be set from a |modeline| or in the |sandbox|, for
5359 security reasons.
5360
Bram Moolenaar325b7a22004-07-05 15:58:32 +00005361 *'mzquantum'* *'mzq'*
5362'mzquantum' 'mzq' number (default 100)
5363 global
Bram Moolenaar325b7a22004-07-05 15:58:32 +00005364 {not available when compiled without the |+mzscheme|
5365 feature}
5366 The number of milliseconds between polls for MzScheme threads.
5367 Negative or zero value means no thread scheduling.
Bram Moolenaar036986f2017-03-16 17:41:02 +01005368 NOTE: This option is set to the Vim default value when 'compatible'
5369 is reset.
Bram Moolenaar325b7a22004-07-05 15:58:32 +00005370
Bram Moolenaar071d4272004-06-13 20:20:40 +00005371 *'nrformats'* *'nf'*
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +02005372'nrformats' 'nf' string (default "bin,octal,hex",
5373 set to "bin,hex" in |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00005374 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00005375 This defines what bases Vim will consider for numbers when using the
5376 CTRL-A and CTRL-X commands for adding to and subtracting from a number
5377 respectively; see |CTRL-A| for more info on these commands.
Bram Moolenaar4770d092006-01-12 23:22:24 +00005378 alpha If included, single alphabetical characters will be
Bram Moolenaar071d4272004-06-13 20:20:40 +00005379 incremented or decremented. This is useful for a list with a
Bram Moolenaar3848e002016-03-19 18:42:29 +01005380 letter index a), b), etc. *octal-nrformats*
Bram Moolenaar4770d092006-01-12 23:22:24 +00005381 octal If included, numbers that start with a zero will be considered
Bram Moolenaar071d4272004-06-13 20:20:40 +00005382 to be octal. Example: Using CTRL-A on "007" results in "010".
Bram Moolenaar4770d092006-01-12 23:22:24 +00005383 hex If included, numbers starting with "0x" or "0X" will be
Bram Moolenaar071d4272004-06-13 20:20:40 +00005384 considered to be hexadecimal. Example: Using CTRL-X on
5385 "0x100" results in "0x0ff".
Bram Moolenaar25e4fcd2016-01-09 14:57:47 +01005386 bin If included, numbers starting with "0b" or "0B" will be
5387 considered to be binary. Example: Using CTRL-X on
5388 "0b1000" subtracts one, resulting in "0b0111".
Bram Moolenaar071d4272004-06-13 20:20:40 +00005389 Numbers which simply begin with a digit in the range 1-9 are always
5390 considered decimal. This also happens for numbers that are not
5391 recognized as octal or hex.
5392
5393 *'number'* *'nu'* *'nonumber'* *'nonu'*
5394'number' 'nu' boolean (default off)
5395 local to window
5396 Print the line number in front of each line. When the 'n' option is
5397 excluded from 'cpoptions' a wrapped line will not use the column of
5398 line numbers (this is the default when 'compatible' isn't set).
Bram Moolenaar592e0a22004-07-03 16:05:59 +00005399 The 'numberwidth' option can be used to set the room used for the line
5400 number.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005401 When a long, wrapped line doesn't start with the first character, '-'
5402 characters are put before the number.
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02005403 See |hl-LineNr| and |hl-CursorLineNr| for the highlighting used for
5404 the number.
Bram Moolenaar203d04d2013-06-06 21:36:40 +02005405 *number_relativenumber*
5406 The 'relativenumber' option changes the displayed number to be
5407 relative to the cursor. Together with 'number' there are these
5408 four combinations (cursor in line 3):
5409
Bram Moolenaar3848e002016-03-19 18:42:29 +01005410 'nonu' 'nu' 'nonu' 'nu'
Bram Moolenaar203d04d2013-06-06 21:36:40 +02005411 'nornu' 'nornu' 'rnu' 'rnu'
5412
5413 |apple | 1 apple | 2 apple | 2 apple
5414 |pear | 2 pear | 1 pear | 1 pear
5415 |nobody | 3 nobody | 0 nobody |3 nobody
5416 |there | 4 there | 1 there | 1 there
Bram Moolenaar071d4272004-06-13 20:20:40 +00005417
Bram Moolenaar592e0a22004-07-03 16:05:59 +00005418 *'numberwidth'* *'nuw'*
5419'numberwidth' 'nuw' number (Vim default: 4 Vi default: 8)
5420 local to window
Bram Moolenaar325b7a22004-07-05 15:58:32 +00005421 {only available when compiled with the |+linebreak|
5422 feature}
Bram Moolenaar592e0a22004-07-03 16:05:59 +00005423 Minimal number of columns to use for the line number. Only relevant
Bram Moolenaar64486672010-05-16 15:46:46 +02005424 when the 'number' or 'relativenumber' option is set or printing lines
5425 with a line number. Since one space is always between the number and
5426 the text, there is one less character for the number itself.
Bram Moolenaar592e0a22004-07-03 16:05:59 +00005427 The value is the minimum width. A bigger width is used when needed to
Bram Moolenaar64486672010-05-16 15:46:46 +02005428 fit the highest line number in the buffer respectively the number of
5429 rows in the window, depending on whether 'number' or 'relativenumber'
5430 is set. Thus with the Vim default of 4 there is room for a line number
5431 up to 999. When the buffer has 1000 lines five columns will be used.
Bram Moolenaarf8a07122019-07-01 22:06:07 +02005432 The minimum value is 1, the maximum value is 20.
Bram Moolenaar036986f2017-03-16 17:41:02 +01005433 NOTE: This option is set to the Vi default value when 'compatible' is
5434 set and to the Vim default value when 'compatible' is reset.
Bram Moolenaar592e0a22004-07-03 16:05:59 +00005435
Bram Moolenaarf75a9632005-09-13 21:20:47 +00005436 *'omnifunc'* *'ofu'*
5437'omnifunc' 'ofu' string (default: empty)
Bram Moolenaare344bea2005-09-01 20:46:49 +00005438 local to buffer
Bram Moolenaardb84e452010-08-15 13:50:43 +02005439 {not available when compiled without the |+eval|
Bram Moolenaare2c453d2019-08-21 14:37:09 +02005440 feature}
Bram Moolenaarc7486e02005-12-29 22:48:26 +00005441 This option specifies a function to be used for Insert mode omni
5442 completion with CTRL-X CTRL-O. |i_CTRL-X_CTRL-O|
Bram Moolenaar280f1262006-01-30 00:14:18 +00005443 See |complete-functions| for an explanation of how the function is
5444 invoked and what it should return.
Bram Moolenaar043545e2006-10-10 16:44:07 +00005445 This option is usually set by a filetype plugin:
Bram Moolenaar9c102382006-05-03 21:26:49 +00005446 |:filetype-plugin-on|
Bram Moolenaar30b65812012-07-12 22:01:11 +02005447 This option cannot be set from a |modeline| or in the |sandbox|, for
5448 security reasons.
Bram Moolenaare344bea2005-09-01 20:46:49 +00005449
5450
Bram Moolenaar02467872007-05-06 13:22:01 +00005451 *'opendevice'* *'odev'* *'noopendevice'* *'noodev'*
Bram Moolenaar043545e2006-10-10 16:44:07 +00005452'opendevice' 'odev' boolean (default off)
5453 global
Bram Moolenaar043545e2006-10-10 16:44:07 +00005454 {only for MS-DOS, MS-Windows and OS/2}
5455 Enable reading and writing from devices. This may get Vim stuck on a
5456 device that can be opened but doesn't actually do the I/O. Therefore
5457 it is off by default.
5458 Note that on MS-Windows editing "aux.h", "lpt1.txt" and the like also
5459 result in editing a device.
5460
5461
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00005462 *'operatorfunc'* *'opfunc'*
5463'operatorfunc' 'opfunc' string (default: empty)
5464 global
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00005465 This option specifies a function to be called by the |g@| operator.
5466 See |:map-operator| for more info and an example.
5467
5468 This option cannot be set from a |modeline| or in the |sandbox|, for
5469 security reasons.
5470
5471
Bram Moolenaar251e1912011-06-19 05:09:16 +02005472 *'osfiletype'* *'oft'*
5473'osfiletype' 'oft' string (default: "")
Bram Moolenaar071d4272004-06-13 20:20:40 +00005474 local to buffer
Bram Moolenaar251e1912011-06-19 05:09:16 +02005475 This option was supported on RISC OS, which has been removed.
5476
Bram Moolenaar071d4272004-06-13 20:20:40 +00005477
Bram Moolenaarf6fee0e2016-02-21 23:02:49 +01005478 *'packpath'* *'pp'*
5479'packpath' 'pp' string (default: see 'runtimepath')
Bram Moolenaarf6fee0e2016-02-21 23:02:49 +01005480 Directories used to find packages. See |packages|.
5481
5482
Bram Moolenaar071d4272004-06-13 20:20:40 +00005483 *'paragraphs'* *'para'*
Bram Moolenaar57e48462008-03-12 16:38:55 +00005484'paragraphs' 'para' string (default "IPLPPPQPP TPHPLIPpLpItpplpipbp")
Bram Moolenaar071d4272004-06-13 20:20:40 +00005485 global
5486 Specifies the nroff macros that separate paragraphs. These are pairs
5487 of two letters (see |object-motions|).
5488
5489 *'paste'* *'nopaste'*
5490'paste' boolean (default off)
5491 global
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00005492 Put Vim in Paste mode. This is useful if you want to cut or copy
5493 some text from one window and paste it in Vim. This will avoid
Bram Moolenaar071d4272004-06-13 20:20:40 +00005494 unexpected effects.
5495 Setting this option is useful when using Vim in a terminal, where Vim
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00005496 cannot distinguish between typed text and pasted text. In the GUI, Vim
Bram Moolenaar071d4272004-06-13 20:20:40 +00005497 knows about pasting and will mostly do the right thing without 'paste'
5498 being set. The same is true for a terminal where Vim handles the
5499 mouse clicks itself.
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00005500 This option is reset when starting the GUI. Thus if you set it in
5501 your .vimrc it will work in a terminal, but not in the GUI. Setting
5502 'paste' in the GUI has side effects: e.g., the Paste toolbar button
5503 will no longer work in Insert mode, because it uses a mapping.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005504 When the 'paste' option is switched on (also when it was already on):
5505 - mapping in Insert mode and Command-line mode is disabled
5506 - abbreviations are disabled
Bram Moolenaar071d4272004-06-13 20:20:40 +00005507 - 'autoindent' is reset
Bram Moolenaarca635012015-09-25 20:34:21 +02005508 - 'expandtab' is reset
5509 - 'formatoptions' is used like it is empty
Bram Moolenaar071d4272004-06-13 20:20:40 +00005510 - 'revins' is reset
5511 - 'ruler' is reset
5512 - 'showmatch' is reset
Bram Moolenaarca635012015-09-25 20:34:21 +02005513 - 'smartindent' is reset
5514 - 'smarttab' is reset
5515 - 'softtabstop' is set to 0
5516 - 'textwidth' is set to 0
5517 - 'wrapmargin' is set to 0
Bram Moolenaar071d4272004-06-13 20:20:40 +00005518 These options keep their value, but their effect is disabled:
Bram Moolenaar071d4272004-06-13 20:20:40 +00005519 - 'cindent'
Bram Moolenaarca635012015-09-25 20:34:21 +02005520 - 'indentexpr'
5521 - 'lisp'
Bram Moolenaar071d4272004-06-13 20:20:40 +00005522 NOTE: When you start editing another file while the 'paste' option is
5523 on, settings from the modelines or autocommands may change the
5524 settings again, causing trouble when pasting text. You might want to
5525 set the 'paste' option again.
5526 When the 'paste' option is reset the mentioned options are restored to
5527 the value before the moment 'paste' was switched from off to on.
5528 Resetting 'paste' before ever setting it does not have any effect.
5529 Since mapping doesn't work while 'paste' is active, you need to use
5530 the 'pastetoggle' option to toggle the 'paste' option with some key.
5531
5532 *'pastetoggle'* *'pt'*
5533'pastetoggle' 'pt' string (default "")
5534 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005535 When non-empty, specifies the key sequence that toggles the 'paste'
5536 option. This is like specifying a mapping: >
5537 :map {keys} :set invpaste<CR>
5538< Where {keys} is the value of 'pastetoggle'.
5539 The difference is that it will work even when 'paste' is set.
5540 'pastetoggle' works in Insert mode and Normal mode, but not in
5541 Command-line mode.
5542 Mappings are checked first, thus overrule 'pastetoggle'. However,
5543 when 'paste' is on mappings are ignored in Insert mode, thus you can do
5544 this: >
5545 :map <F10> :set paste<CR>
5546 :map <F11> :set nopaste<CR>
5547 :imap <F10> <C-O>:set paste<CR>
5548 :imap <F11> <nop>
5549 :set pastetoggle=<F11>
5550< This will make <F10> start paste mode and <F11> stop paste mode.
5551 Note that typing <F10> in paste mode inserts "<F10>", since in paste
5552 mode everything is inserted literally, except the 'pastetoggle' key
5553 sequence.
Bram Moolenaar446cb832008-06-24 21:56:24 +00005554 When the value has several bytes 'ttimeoutlen' applies.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005555
5556 *'pex'* *'patchexpr'*
5557'patchexpr' 'pex' string (default "")
5558 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005559 {not available when compiled without the |+diff|
5560 feature}
5561 Expression which is evaluated to apply a patch to a file and generate
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00005562 the resulting new version of the file. See |diff-patchexpr|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005563
Bram Moolenaardbc28022014-07-26 13:40:44 +02005564 *'patchmode'* *'pm'* *E205* *E206*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005565'patchmode' 'pm' string (default "")
5566 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005567 When non-empty the oldest version of a file is kept. This can be used
5568 to keep the original version of a file if you are changing files in a
5569 source distribution. Only the first time that a file is written a
5570 copy of the original file will be kept. The name of the copy is the
5571 name of the original file with the string in the 'patchmode' option
5572 appended. This option should start with a dot. Use a string like
Bram Moolenaardf980db2017-12-24 13:22:00 +01005573 ".orig" or ".org". 'backupdir' must not be empty for this to work
5574 (Detail: The backup file is renamed to the patchmode file after the
5575 new file has been successfully written, that's why it must be possible
5576 to write a backup file). If there was no file to be backed up, an
5577 empty file is created.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005578 When the 'backupskip' pattern matches, a patchmode file is not made.
5579 Using 'patchmode' for compressed files appends the extension at the
5580 end (e.g., "file.gz.orig"), thus the resulting name isn't always
5581 recognized as a compressed file.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00005582 Only normal file name characters can be used, "/\*?[|<>" are illegal.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005583
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01005584 *'path'* *'pa'* *E343* *E345* *E347* *E854*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005585'path' 'pa' string (default on Unix: ".,/usr/include,,"
5586 on OS/2: ".,/emx/include,,"
5587 other systems: ".,,")
5588 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00005589 This is a list of directories which will be searched when using the
Bram Moolenaarc236c162008-07-13 17:41:49 +00005590 |gf|, [f, ]f, ^Wf, |:find|, |:sfind|, |:tabfind| and other commands,
5591 provided that the file being searched for has a relative path (not
5592 starting with "/", "./" or "../"). The directories in the 'path'
5593 option may be relative or absolute.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005594 - Use commas to separate directory names: >
5595 :set path=.,/usr/local/include,/usr/include
5596< - Spaces can also be used to separate directory names (for backwards
5597 compatibility with version 3.0). To have a space in a directory
5598 name, precede it with an extra backslash, and escape the space: >
5599 :set path=.,/dir/with\\\ space
5600< - To include a comma in a directory name precede it with an extra
5601 backslash: >
5602 :set path=.,/dir/with\\,comma
5603< - To search relative to the directory of the current file, use: >
5604 :set path=.
5605< - To search in the current directory use an empty string between two
5606 commas: >
5607 :set path=,,
5608< - A directory name may end in a ':' or '/'.
5609 - Environment variables are expanded |:set_env|.
5610 - When using |netrw.vim| URLs can be used. For example, adding
5611 "http://www.vim.org" will make ":find index.html" work.
Bram Moolenaarc236c162008-07-13 17:41:49 +00005612 - Search upwards and downwards in a directory tree using "*", "**" and
5613 ";". See |file-searching| for info and syntax.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005614 {not available when compiled without the |+path_extra| feature}
5615 - Careful with '\' characters, type two to get one in the option: >
5616 :set path=.,c:\\include
5617< Or just use '/' instead: >
5618 :set path=.,c:/include
5619< Don't forget "." or files won't even be found in the same directory as
5620 the file!
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00005621 The maximum length is limited. How much depends on the system, mostly
Bram Moolenaar071d4272004-06-13 20:20:40 +00005622 it is something like 256 or 1024 characters.
5623 You can check if all the include files are found, using the value of
5624 'path', see |:checkpath|.
5625 The use of |:set+=| and |:set-=| is preferred when adding or removing
5626 directories from the list. This avoids problems when a future version
5627 uses another default. To remove the current directory use: >
5628 :set path-=
5629< To add the current directory use: >
5630 :set path+=
5631< To use an environment variable, you probably need to replace the
5632 separator. Here is an example to append $INCL, in which directory
5633 names are separated with a semi-colon: >
5634 :let &path = &path . "," . substitute($INCL, ';', ',', 'g')
5635< Replace the ';' with a ':' or whatever separator is used. Note that
5636 this doesn't work when $INCL contains a comma or white space.
5637
Bram Moolenaar37c64c72017-09-19 22:06:03 +02005638 *'perldll'*
5639'perldll' string (default depends on the build)
5640 global
Bram Moolenaar37c64c72017-09-19 22:06:03 +02005641 {only available when compiled with the |+perl/dyn|
5642 feature}
5643 Specifies the name of the Perl shared library. The default is
5644 DYNAMIC_PERL_DLL, which was specified at compile time.
5645 Environment variables are expanded |:set_env|.
5646 This option cannot be set from a |modeline| or in the |sandbox|, for
5647 security reasons.
5648
Bram Moolenaar071d4272004-06-13 20:20:40 +00005649 *'preserveindent'* *'pi'* *'nopreserveindent'* *'nopi'*
5650'preserveindent' 'pi' boolean (default off)
5651 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00005652 When changing the indent of the current line, preserve as much of the
5653 indent structure as possible. Normally the indent is replaced by a
5654 series of tabs followed by spaces as required (unless |'expandtab'| is
5655 enabled, in which case only spaces are used). Enabling this option
5656 means the indent will preserve as many existing characters as possible
5657 for indenting, and only add additional tabs or spaces as required.
Bram Moolenaar446cb832008-06-24 21:56:24 +00005658 'expandtab' does not apply to the preserved white space, a Tab remains
5659 a Tab.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005660 NOTE: When using ">>" multiple times the resulting indent is a mix of
5661 tabs and spaces. You might not like this.
Bram Moolenaar036986f2017-03-16 17:41:02 +01005662 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005663 Also see 'copyindent'.
5664 Use |:retab| to clean up white space.
5665
5666 *'previewheight'* *'pvh'*
5667'previewheight' 'pvh' number (default 12)
5668 global
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02005669 {not available when compiled without the |+quickfix|
5670 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00005671 Default height for a preview window. Used for |:ptag| and associated
Bram Moolenaar79648732019-07-18 21:43:07 +02005672 commands. Used for |CTRL-W_}| when no count is given. Not used when
5673 'previewpopup' is set.
5674
5675 *'previewpopup'* *'pvp'*
5676'previewpopup' 'pvp' string (default empty)
5677 global
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02005678 {not available when compiled without the |+textprop|
5679 or |+quickfix| feature}
Bram Moolenaar79648732019-07-18 21:43:07 +02005680 When not empty a popup window is used for commands that would open a
5681 preview window. See |preview-popup|.
Bram Moolenaar576a4a62019-08-18 15:25:17 +02005682 Not used for the insert completion info, add "popup" to
5683 'completeopt' for that.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005684
5685 *'previewwindow'* *'nopreviewwindow'*
5686 *'pvw'* *'nopvw'* *E590*
5687'previewwindow' 'pvw' boolean (default off)
5688 local to window
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02005689 {not available when compiled without the |+quickfix|
5690 feature}
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00005691 Identifies the preview window. Only one window can have this option
Bram Moolenaar071d4272004-06-13 20:20:40 +00005692 set. It's normally not set directly, but by using one of the commands
5693 |:ptag|, |:pedit|, etc.
5694
5695 *'printdevice'* *'pdev'*
5696'printdevice' 'pdev' string (default empty)
5697 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005698 {only available when compiled with the |+printer|
5699 feature}
Bram Moolenaar8299df92004-07-10 09:47:34 +00005700 The name of the printer to be used for |:hardcopy|.
5701 See |pdev-option|.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00005702 This option cannot be set from a |modeline| or in the |sandbox|, for
5703 security reasons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005704
Bram Moolenaar8299df92004-07-10 09:47:34 +00005705 *'printencoding'* *'penc'*
Bram Moolenaar95bafa22018-10-02 13:26:25 +02005706'printencoding' 'penc' string (default empty, except for some systems)
Bram Moolenaar071d4272004-06-13 20:20:40 +00005707 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005708 {only available when compiled with the |+printer|
5709 and |+postscript| features}
Bram Moolenaar8299df92004-07-10 09:47:34 +00005710 Sets the character encoding used when printing.
5711 See |penc-option|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005712
5713 *'printexpr'* *'pexpr'*
Bram Moolenaar95bafa22018-10-02 13:26:25 +02005714'printexpr' 'pexpr' string (default: see below)
Bram Moolenaar071d4272004-06-13 20:20:40 +00005715 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005716 {only available when compiled with the |+printer|
5717 and |+postscript| features}
Bram Moolenaar8299df92004-07-10 09:47:34 +00005718 Expression used to print the PostScript produced with |:hardcopy|.
5719 See |pexpr-option|.
Bram Moolenaar51628222016-12-01 23:03:28 +01005720 This option cannot be set from a |modeline| or in the |sandbox|, for
5721 security reasons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005722
Bram Moolenaar8299df92004-07-10 09:47:34 +00005723 *'printfont'* *'pfn'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005724'printfont' 'pfn' string (default "courier")
5725 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005726 {only available when compiled with the |+printer|
5727 feature}
Bram Moolenaar8299df92004-07-10 09:47:34 +00005728 The name of the font that will be used for |:hardcopy|.
5729 See |pfn-option|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005730
5731 *'printheader'* *'pheader'*
5732'printheader' 'pheader' string (default "%<%f%h%m%=Page %N")
5733 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005734 {only available when compiled with the |+printer|
5735 feature}
Bram Moolenaar8299df92004-07-10 09:47:34 +00005736 The format of the header produced in |:hardcopy| output.
5737 See |pheader-option|.
5738
5739 *'printmbcharset'* *'pmbcs'*
5740'printmbcharset' 'pmbcs' string (default "")
5741 global
Bram Moolenaar4c92e752019-02-17 21:18:32 +01005742 {only available when compiled with the |+printer|
5743 and |+postscript| features}
Bram Moolenaar8299df92004-07-10 09:47:34 +00005744 The CJK character set to be used for CJK output from |:hardcopy|.
5745 See |pmbcs-option|.
5746
5747 *'printmbfont'* *'pmbfn'*
5748'printmbfont' 'pmbfn' string (default "")
5749 global
Bram Moolenaar4c92e752019-02-17 21:18:32 +01005750 {only available when compiled with the |+printer|
5751 and |+postscript| features}
Bram Moolenaar8299df92004-07-10 09:47:34 +00005752 List of font names to be used for CJK output from |:hardcopy|.
5753 See |pmbfn-option|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005754
5755 *'printoptions'* *'popt'*
5756'printoptions' 'popt' string (default "")
5757 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005758 {only available when compiled with |+printer| feature}
Bram Moolenaar8299df92004-07-10 09:47:34 +00005759 List of items that control the format of the output of |:hardcopy|.
5760 See |popt-option|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005761
Bram Moolenaar26a60b42005-02-22 08:49:11 +00005762 *'prompt'* *'noprompt'*
5763'prompt' boolean (default on)
5764 global
5765 When on a ":" prompt is used in Ex mode.
5766
Bram Moolenaar7d47b6e2006-03-15 22:59:18 +00005767 *'pumheight'* *'ph'*
5768'pumheight' 'ph' number (default 0)
5769 global
Bram Moolenaar06a89a52006-04-29 22:01:03 +00005770 Determines the maximum number of items to show in the popup menu for
5771 Insert mode completion. When zero as much space as available is used.
Bram Moolenaar7d47b6e2006-03-15 22:59:18 +00005772 |ins-completion-menu|.
5773
Bram Moolenaara8f04aa2018-02-10 15:36:55 +01005774 *'pumwidth'* *'pw'*
Bram Moolenaarcafafb32018-02-22 21:07:09 +01005775'pumwidth' 'pw' number (default 15)
Bram Moolenaara8f04aa2018-02-10 15:36:55 +01005776 global
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01005777 Determines the minimum width to use for the popup menu for Insert mode
Bram Moolenaarcafafb32018-02-22 21:07:09 +01005778 completion. |ins-completion-menu|.
Bram Moolenaara8f04aa2018-02-10 15:36:55 +01005779
Bram Moolenaard94464e2015-11-02 15:28:18 +01005780 *'pythondll'*
Bram Moolenaar3848e002016-03-19 18:42:29 +01005781'pythondll' string (default depends on the build)
Bram Moolenaard94464e2015-11-02 15:28:18 +01005782 global
Bram Moolenaard94464e2015-11-02 15:28:18 +01005783 {only available when compiled with the |+python/dyn|
5784 feature}
Bram Moolenaar25e4fcd2016-01-09 14:57:47 +01005785 Specifies the name of the Python 2.x shared library. The default is
5786 DYNAMIC_PYTHON_DLL, which was specified at compile time.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02005787 Environment variables are expanded |:set_env|.
Bram Moolenaard94464e2015-11-02 15:28:18 +01005788 This option cannot be set from a |modeline| or in the |sandbox|, for
5789 security reasons.
Bram Moolenaar7d47b6e2006-03-15 22:59:18 +00005790
Bram Moolenaar94073162018-01-31 21:49:05 +01005791 *'pythonhome'*
5792'pythonhome' string (default "")
5793 global
Bram Moolenaar94073162018-01-31 21:49:05 +01005794 {only available when compiled with the |+python/dyn|
5795 feature}
5796 Specifies the name of the Python 2.x home directory. When 'pythonhome'
5797 and the PYTHONHOME environment variable are not set, PYTHON_HOME,
5798 which was specified at compile time, will be used for the Python 2.x
5799 home directory.
5800 Environment variables are expanded |:set_env|.
5801 This option cannot be set from a |modeline| or in the |sandbox|, for
5802 security reasons.
5803
Bram Moolenaarb4ff5182015-11-10 21:15:48 +01005804 *'pythonthreedll'*
Bram Moolenaar25e4fcd2016-01-09 14:57:47 +01005805'pythonthreedll' string (default depends on the build)
Bram Moolenaarb4ff5182015-11-10 21:15:48 +01005806 global
Bram Moolenaarb4ff5182015-11-10 21:15:48 +01005807 {only available when compiled with the |+python3/dyn|
5808 feature}
Bram Moolenaar25e4fcd2016-01-09 14:57:47 +01005809 Specifies the name of the Python 3 shared library. The default is
5810 DYNAMIC_PYTHON3_DLL, which was specified at compile time.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02005811 Environment variables are expanded |:set_env|.
Bram Moolenaarb4ff5182015-11-10 21:15:48 +01005812 This option cannot be set from a |modeline| or in the |sandbox|, for
5813 security reasons.
5814
Bram Moolenaar94073162018-01-31 21:49:05 +01005815 *'pythonthreehome'*
5816'pythonthreehome' string (default "")
5817 global
Bram Moolenaar94073162018-01-31 21:49:05 +01005818 {only available when compiled with the |+python3/dyn|
5819 feature}
5820 Specifies the name of the Python 3 home directory. When
5821 'pythonthreehome' and the PYTHONHOME environment variable are not set,
5822 PYTHON3_HOME, which was specified at compile time, will be used for
5823 the Python 3 home directory.
5824 Environment variables are expanded |:set_env|.
5825 This option cannot be set from a |modeline| or in the |sandbox|, for
5826 security reasons.
5827
Bram Moolenaarf42dd3c2017-01-28 16:06:38 +01005828 *'pyxversion'* *'pyx'*
5829'pyxversion' 'pyx' number (default depends on the build)
5830 global
Bram Moolenaarf42dd3c2017-01-28 16:06:38 +01005831 {only available when compiled with the |+python| or
5832 the |+python3| feature}
5833 Specifies the python version used for pyx* functions and commands
5834 |python_x|. The default value is as follows:
5835
5836 Compiled with Default ~
5837 |+python| and |+python3| 0
5838 only |+python| 2
5839 only |+python3| 3
5840
5841 Available values are 0, 2 and 3.
5842 If 'pyxversion' is 0, it is set to 2 or 3 after the first execution of
5843 any python2/3 commands or functions. E.g. `:py` sets to 2, and `:py3`
5844 sets to 3. `:pyx` sets it to 3 if Python 3 is available, otherwise sets
5845 to 2 if Python 2 is available.
5846 See also: |has-pythonx|
5847
5848 If Vim is compiled with only |+python| or |+python3| setting
5849 'pyxversion' has no effect. The pyx* functions and commands are
5850 always the same as the compiled version.
5851
5852 This option cannot be set from a |modeline| or in the |sandbox|, for
5853 security reasons.
5854
Bram Moolenaar677ee682005-01-27 14:41:15 +00005855 *'quoteescape'* *'qe'*
Bram Moolenaarcfbc5ee2004-07-02 15:38:35 +00005856'quoteescape' 'qe' string (default "\")
5857 local to buffer
Bram Moolenaarcfbc5ee2004-07-02 15:38:35 +00005858 The characters that are used to escape quotes in a string. Used for
5859 objects like a', a" and a` |a'|.
5860 When one of the characters in this option is found inside a string,
5861 the following character will be skipped. The default value makes the
5862 text "foo\"bar\\" considered to be one string.
5863
Bram Moolenaar071d4272004-06-13 20:20:40 +00005864 *'readonly'* *'ro'* *'noreadonly'* *'noro'*
5865'readonly' 'ro' boolean (default off)
5866 local to buffer
5867 If on, writes fail unless you use a '!'. Protects you from
5868 accidentally overwriting a file. Default on when Vim is started
5869 in read-only mode ("vim -R") or when the executable is called "view".
Bram Moolenaar4399ef42005-02-12 14:29:27 +00005870 When using ":w!" the 'readonly' option is reset for the current
5871 buffer, unless the 'Z' flag is in 'cpoptions'.
Bram Moolenaar6c60f472019-04-28 16:00:35 +02005872 When using the ":view" command the 'readonly' option is set for the
5873 newly edited buffer.
Bram Moolenaar369b6f52017-01-17 12:22:32 +01005874 See 'modifiable' for disallowing changes to the buffer.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005875
Bram Moolenaar91a4e822008-01-19 14:59:58 +00005876 *'redrawtime'* *'rdt'*
5877'redrawtime' 'rdt' number (default 2000)
5878 global
Bram Moolenaar91a4e822008-01-19 14:59:58 +00005879 {only available when compiled with the |+reltime|
5880 feature}
5881 The time in milliseconds for redrawing the display. This applies to
Bram Moolenaar15142e22018-04-30 22:19:58 +02005882 searching for patterns for 'hlsearch', |:match| highlighting and syntax
Bram Moolenaar06f1ed22017-06-18 22:41:03 +02005883 highlighting.
Bram Moolenaar91a4e822008-01-19 14:59:58 +00005884 When redrawing takes more than this many milliseconds no further
Bram Moolenaar06f1ed22017-06-18 22:41:03 +02005885 matches will be highlighted.
5886 For syntax highlighting the time applies per window. When over the
5887 limit syntax highlighting is disabled until |CTRL-L| is used.
5888 This is used to avoid that Vim hangs when using a very complicated
5889 pattern.
Bram Moolenaar91a4e822008-01-19 14:59:58 +00005890
Bram Moolenaar543b7ef2013-06-01 14:50:56 +02005891 *'regexpengine'* *'re'*
Bram Moolenaare6ae6222013-05-21 21:01:10 +02005892'regexpengine' 're' number (default 0)
5893 global
Bram Moolenaare6ae6222013-05-21 21:01:10 +02005894 This selects the default regexp engine. |two-engines|
5895 The possible values are:
5896 0 automatic selection
5897 1 old engine
5898 2 NFA engine
5899 Note that when using the NFA engine and the pattern contains something
5900 that is not supported the pattern will not match. This is only useful
5901 for debugging the regexp engine.
Bram Moolenaarfda37292014-11-05 14:27:36 +01005902 Using automatic selection enables Vim to switch the engine, if the
5903 default engine becomes too costly. E.g., when the NFA engine uses too
5904 many states. This should prevent Vim from hanging on a combination of
5905 a complex pattern with long text.
Bram Moolenaare6ae6222013-05-21 21:01:10 +02005906
Bram Moolenaar64486672010-05-16 15:46:46 +02005907 *'relativenumber'* *'rnu'* *'norelativenumber'* *'nornu'*
5908'relativenumber' 'rnu' boolean (default off)
5909 local to window
Bram Moolenaar64486672010-05-16 15:46:46 +02005910 Show the line number relative to the line with the cursor in front of
Bram Moolenaar06b5d512010-05-22 15:37:44 +02005911 each line. Relative line numbers help you use the |count| you can
Bram Moolenaar64486672010-05-16 15:46:46 +02005912 precede some vertical motion commands (e.g. j k + -) with, without
5913 having to calculate it yourself. Especially useful in combination with
5914 other commands (e.g. y d c < > gq gw =).
5915 When the 'n' option is excluded from 'cpoptions' a wrapped
5916 line will not use the column of line numbers (this is the default when
5917 'compatible' isn't set).
5918 The 'numberwidth' option can be used to set the room used for the line
5919 number.
5920 When a long, wrapped line doesn't start with the first character, '-'
5921 characters are put before the number.
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02005922 See |hl-LineNr| and |hl-CursorLineNr| for the highlighting used for
5923 the number.
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01005924
Bram Moolenaar203d04d2013-06-06 21:36:40 +02005925 The number in front of the cursor line also depends on the value of
5926 'number', see |number_relativenumber| for all combinations of the two
5927 options.
Bram Moolenaar64486672010-05-16 15:46:46 +02005928
Bram Moolenaar071d4272004-06-13 20:20:40 +00005929 *'remap'* *'noremap'*
5930'remap' boolean (default on)
5931 global
5932 Allows for mappings to work recursively. If you do not want this for
5933 a single entry, use the :noremap[!] command.
Bram Moolenaara3227e22006-03-08 21:32:40 +00005934 NOTE: To avoid portability problems with Vim scripts, always keep
5935 this option at the default "on". Only switch it off when working with
5936 old Vi scripts.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005937
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02005938 *'renderoptions'* *'rop'*
5939'renderoptions' 'rop' string (default: empty)
5940 global
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02005941 {only available when compiled with GUI and DIRECTX on
5942 MS-Windows}
5943 Select a text renderer and set its options. The options depend on the
5944 renderer.
5945
5946 Syntax: >
5947 set rop=type:{renderer}(,{name}:{value})*
5948<
5949 Currently, only one optional renderer is available.
5950
5951 render behavior ~
5952 directx Vim will draw text using DirectX (DirectWrite). It makes
5953 drawn glyphs more beautiful than default GDI.
5954 It requires 'encoding' is "utf-8", and only works on
5955 MS-Windows Vista or newer version.
5956
5957 Options:
5958 name meaning type value ~
5959 gamma gamma float 1.0 - 2.2 (maybe)
5960 contrast enhancedContrast float (unknown)
5961 level clearTypeLevel float (unknown)
5962 geom pixelGeometry int 0 - 2 (see below)
5963 renmode renderingMode int 0 - 6 (see below)
5964 taamode textAntialiasMode int 0 - 3 (see below)
Bram Moolenaara338adc2018-01-31 20:51:47 +01005965 scrlines Scroll Lines int (deprecated)
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02005966
Bram Moolenaar92467d32017-12-05 13:22:16 +01005967 See this URL for detail (except for scrlines):
5968 https://msdn.microsoft.com/en-us/library/dd368190.aspx
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02005969
5970 For geom: structure of a device pixel.
5971 0 - DWRITE_PIXEL_GEOMETRY_FLAT
5972 1 - DWRITE_PIXEL_GEOMETRY_RGB
5973 2 - DWRITE_PIXEL_GEOMETRY_BGR
5974
5975 See this URL for detail:
Bram Moolenaar92467d32017-12-05 13:22:16 +01005976 https://msdn.microsoft.com/en-us/library/dd368114.aspx
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02005977
5978 For renmode: method of rendering glyphs.
5979 0 - DWRITE_RENDERING_MODE_DEFAULT
5980 1 - DWRITE_RENDERING_MODE_ALIASED
5981 2 - DWRITE_RENDERING_MODE_GDI_CLASSIC
5982 3 - DWRITE_RENDERING_MODE_GDI_NATURAL
5983 4 - DWRITE_RENDERING_MODE_NATURAL
5984 5 - DWRITE_RENDERING_MODE_NATURAL_SYMMETRIC
5985 6 - DWRITE_RENDERING_MODE_OUTLINE
5986
5987 See this URL for detail:
Bram Moolenaar92467d32017-12-05 13:22:16 +01005988 https://msdn.microsoft.com/en-us/library/dd368118.aspx
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02005989
5990 For taamode: antialiasing mode used for drawing text.
5991 0 - D2D1_TEXT_ANTIALIAS_MODE_DEFAULT
5992 1 - D2D1_TEXT_ANTIALIAS_MODE_CLEARTYPE
5993 2 - D2D1_TEXT_ANTIALIAS_MODE_GRAYSCALE
5994 3 - D2D1_TEXT_ANTIALIAS_MODE_ALIASED
5995
5996 See this URL for detail:
Bram Moolenaar92467d32017-12-05 13:22:16 +01005997 https://msdn.microsoft.com/en-us/library/dd368170.aspx
5998
Bram Moolenaara338adc2018-01-31 20:51:47 +01005999 For scrlines:
6000 This was used for optimizing scrolling behavior, however this
6001 is now deprecated. If specified, it is simply ignored.
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02006002
6003 Example: >
6004 set encoding=utf-8
Bram Moolenaard7ccc4d2017-11-26 14:29:32 +01006005 set gfn=Ricty_Diminished:h12
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02006006 set rop=type:directx
6007<
Bram Moolenaard7ccc4d2017-11-26 14:29:32 +01006008 If select a raster font (Courier, Terminal or FixedSys which
6009 have ".fon" extension in file name) to 'guifont', it will be
Bram Moolenaar92467d32017-12-05 13:22:16 +01006010 drawn by GDI as a fallback.
Bram Moolenaard7ccc4d2017-11-26 14:29:32 +01006011
6012 NOTE: It is known that some fonts and options combination
6013 causes trouble on drawing glyphs.
6014
Bram Moolenaar92467d32017-12-05 13:22:16 +01006015 - 'renmode:5' and 'renmode:6' will not work with some
Bram Moolenaard7ccc4d2017-11-26 14:29:32 +01006016 special made fonts (True-Type fonts which includes only
6017 bitmap glyphs).
6018 - 'taamode:3' will not work with some vector fonts.
6019
6020 NOTE: With this option, you can display colored emoji
6021 (emoticon) in Windows 8.1 or later. To display colored emoji,
6022 there are some conditions which you should notice.
6023
6024 - If your font includes non-colored emoji already, it will
6025 be used.
6026 - If your font doesn't have emoji, the system chooses an
6027 alternative symbol font. On Windows 10, "Segoe UI Emoji"
6028 will be used.
6029 - When this alternative font didn't have fixed width glyph,
6030 emoji might be rendered beyond the bounding box of drawing
6031 cell.
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02006032
6033 Other render types are currently not supported.
6034
Bram Moolenaar071d4272004-06-13 20:20:40 +00006035 *'report'*
6036'report' number (default 2)
6037 global
6038 Threshold for reporting number of lines changed. When the number of
6039 changed lines is more than 'report' a message will be given for most
6040 ":" commands. If you want it always, set 'report' to 0.
6041 For the ":substitute" command the number of substitutions is used
6042 instead of the number of lines.
6043
6044 *'restorescreen'* *'rs'* *'norestorescreen'* *'nors'*
6045'restorescreen' 'rs' boolean (default on)
6046 global
Bram Moolenaar6c60f472019-04-28 16:00:35 +02006047 {only in Windows 95/NT console version}
Bram Moolenaar071d4272004-06-13 20:20:40 +00006048 When set, the screen contents is restored when exiting Vim. This also
6049 happens when executing external commands.
6050
6051 For non-Windows Vim: You can set or reset the 't_ti' and 't_te'
6052 options in your .vimrc. To disable restoring:
6053 set t_ti= t_te=
6054 To enable restoring (for an xterm):
6055 set t_ti=^[7^[[r^[[?47h t_te=^[[?47l^[8
6056 (Where ^[ is an <Esc>, type CTRL-V <Esc> to insert it)
6057
6058 *'revins'* *'ri'* *'norevins'* *'nori'*
6059'revins' 'ri' boolean (default off)
6060 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006061 {only available when compiled with the |+rightleft|
6062 feature}
6063 Inserting characters in Insert mode will work backwards. See "typing
6064 backwards" |ins-reverse|. This option can be toggled with the CTRL-_
6065 command in Insert mode, when 'allowrevins' is set.
Bram Moolenaarca635012015-09-25 20:34:21 +02006066 NOTE: This option is reset when 'compatible' is set.
6067 This option is reset when 'paste' is set and restored when 'paste' is
6068 reset.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006069
6070 *'rightleft'* *'rl'* *'norightleft'* *'norl'*
6071'rightleft' 'rl' boolean (default off)
6072 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00006073 {only available when compiled with the |+rightleft|
6074 feature}
6075 When on, display orientation becomes right-to-left, i.e., characters
6076 that are stored in the file appear from the right to the left.
6077 Using this option, it is possible to edit files for languages that
6078 are written from the right to the left such as Hebrew and Arabic.
6079 This option is per window, so it is possible to edit mixed files
6080 simultaneously, or to view the same file in both ways (this is
6081 useful whenever you have a mixed text file with both right-to-left
6082 and left-to-right strings so that both sets are displayed properly
6083 in different windows). Also see |rileft.txt|.
6084
Bram Moolenaar607cc1e2010-07-18 18:47:44 +02006085 *'rightleftcmd'* *'rlc'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006086'rightleftcmd' 'rlc' string (default "search")
6087 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00006088 {only available when compiled with the |+rightleft|
6089 feature}
6090 Each word in this option enables the command line editing to work in
6091 right-to-left mode for a group of commands:
6092
6093 search "/" and "?" commands
6094
6095 This is useful for languages such as Hebrew, Arabic and Farsi.
6096 The 'rightleft' option must be set for 'rightleftcmd' to take effect.
6097
Bram Moolenaard94464e2015-11-02 15:28:18 +01006098 *'rubydll'*
Bram Moolenaar3848e002016-03-19 18:42:29 +01006099'rubydll' string (default: depends on the build)
Bram Moolenaard94464e2015-11-02 15:28:18 +01006100 global
Bram Moolenaard94464e2015-11-02 15:28:18 +01006101 {only available when compiled with the |+ruby/dyn|
6102 feature}
Bram Moolenaar25e4fcd2016-01-09 14:57:47 +01006103 Specifies the name of the Ruby shared library. The default is
6104 DYNAMIC_RUBY_DLL, which was specified at compile time.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02006105 Environment variables are expanded |:set_env|.
Bram Moolenaard94464e2015-11-02 15:28:18 +01006106 This option cannot be set from a |modeline| or in the |sandbox|, for
6107 security reasons.
6108
Bram Moolenaar071d4272004-06-13 20:20:40 +00006109 *'ruler'* *'ru'* *'noruler'* *'noru'*
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +02006110'ruler' 'ru' boolean (default off, set in |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006111 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006112 {not available when compiled without the
6113 |+cmdline_info| feature}
6114 Show the line and column number of the cursor position, separated by a
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006115 comma. When there is room, the relative position of the displayed
Bram Moolenaar071d4272004-06-13 20:20:40 +00006116 text in the file is shown on the far right:
6117 Top first line is visible
6118 Bot last line is visible
6119 All first and last line are visible
6120 45% relative position in the file
6121 If 'rulerformat' is set, it will determine the contents of the ruler.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006122 Each window has its own ruler. If a window has a status line, the
Bram Moolenaar071d4272004-06-13 20:20:40 +00006123 ruler is shown there. Otherwise it is shown in the last line of the
Bram Moolenaar582fd852005-03-28 20:58:01 +00006124 screen. If the statusline is given by 'statusline' (i.e. not empty),
Bram Moolenaar071d4272004-06-13 20:20:40 +00006125 this option takes precedence over 'ruler' and 'rulerformat'
6126 If the number of characters displayed is different from the number of
6127 bytes in the text (e.g., for a TAB or a multi-byte character), both
6128 the text column (byte number) and the screen column are shown,
6129 separated with a dash.
6130 For an empty line "0-1" is shown.
6131 For an empty buffer the line number will also be zero: "0,0-1".
Bram Moolenaarca635012015-09-25 20:34:21 +02006132 This option is reset when 'paste' is set and restored when 'paste' is
6133 reset.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006134 If you don't want to see the ruler all the time but want to know where
6135 you are, use "g CTRL-G" |g_CTRL-G|.
6136 NOTE: This option is reset when 'compatible' is set.
6137
6138 *'rulerformat'* *'ruf'*
6139'rulerformat' 'ruf' string (default empty)
6140 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006141 {not available when compiled without the |+statusline|
6142 feature}
6143 When this option is not empty, it determines the content of the ruler
6144 string, as displayed for the 'ruler' option.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00006145 The format of this option is like that of 'statusline'.
Bram Moolenaar110289e2019-05-23 15:38:06 +02006146 This option cannot be set in a modeline when 'modelineexpr' is off.
6147
Bram Moolenaar071d4272004-06-13 20:20:40 +00006148 The default ruler width is 17 characters. To make the ruler 15
6149 characters wide, put "%15(" at the start and "%)" at the end.
6150 Example: >
6151 :set rulerformat=%15(%c%V\ %p%%%)
6152<
6153 *'runtimepath'* *'rtp'* *vimfiles*
6154'runtimepath' 'rtp' string (default:
6155 Unix: "$HOME/.vim,
6156 $VIM/vimfiles,
6157 $VIMRUNTIME,
6158 $VIM/vimfiles/after,
6159 $HOME/.vim/after"
6160 Amiga: "home:vimfiles,
6161 $VIM/vimfiles,
6162 $VIMRUNTIME,
6163 $VIM/vimfiles/after,
6164 home:vimfiles/after"
6165 PC, OS/2: "$HOME/vimfiles,
6166 $VIM/vimfiles,
6167 $VIMRUNTIME,
6168 $VIM/vimfiles/after,
6169 $HOME/vimfiles/after"
6170 Macintosh: "$VIM:vimfiles,
6171 $VIMRUNTIME,
6172 $VIM:vimfiles:after"
6173 RISC-OS: "Choices:vimfiles,
6174 $VIMRUNTIME,
6175 Choices:vimfiles/after"
6176 VMS: "sys$login:vimfiles,
6177 $VIM/vimfiles,
6178 $VIMRUNTIME,
6179 $VIM/vimfiles/after,
Bram Moolenaar582fd852005-03-28 20:58:01 +00006180 sys$login:vimfiles/after")
Bram Moolenaar071d4272004-06-13 20:20:40 +00006181 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006182 This is a list of directories which will be searched for runtime
6183 files:
6184 filetype.vim filetypes by file name |new-filetype|
6185 scripts.vim filetypes by file contents |new-filetype-scripts|
Bram Moolenaar4399ef42005-02-12 14:29:27 +00006186 autoload/ automatically loaded scripts |autoload-functions|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006187 colors/ color scheme files |:colorscheme|
6188 compiler/ compiler files |:compiler|
6189 doc/ documentation |write-local-help|
6190 ftplugin/ filetype plugins |write-filetype-plugin|
6191 indent/ indent scripts |indent-expression|
6192 keymap/ key mapping files |mbyte-keymap|
6193 lang/ menu translations |:menutrans|
6194 menu.vim GUI menus |menu.vim|
Bram Moolenaar26852122016-05-24 20:02:38 +02006195 pack/ packages |:packadd|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006196 plugin/ plugin scripts |write-plugin|
6197 print/ files for printing |postscript-print-encoding|
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +00006198 spell/ spell checking files |spell|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006199 syntax/ syntax files |mysyntaxfile|
6200 tutor/ files for vimtutor |tutor|
6201
6202 And any other file searched for with the |:runtime| command.
6203
6204 The defaults for most systems are setup to search five locations:
6205 1. In your home directory, for your personal preferences.
6206 2. In a system-wide Vim directory, for preferences from the system
6207 administrator.
6208 3. In $VIMRUNTIME, for files distributed with Vim.
6209 *after-directory*
6210 4. In the "after" directory in the system-wide Vim directory. This is
6211 for the system administrator to overrule or add to the distributed
6212 defaults (rarely needed)
6213 5. In the "after" directory in your home directory. This is for
6214 personal preferences to overrule or add to the distributed defaults
6215 or system-wide settings (rarely needed).
6216
Bram Moolenaard0796902016-09-16 20:02:31 +02006217 More entries are added when using |packages|. If it gets very long
6218 then `:set rtp` will be truncated, use `:echo &rtp` to see the full
6219 string.
Bram Moolenaar26852122016-05-24 20:02:38 +02006220
Bram Moolenaar071d4272004-06-13 20:20:40 +00006221 Note that, unlike 'path', no wildcards like "**" are allowed. Normal
6222 wildcards are allowed, but can significantly slow down searching for
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006223 runtime files. For speed, use as few items as possible and avoid
Bram Moolenaar071d4272004-06-13 20:20:40 +00006224 wildcards.
6225 See |:runtime|.
6226 Example: >
6227 :set runtimepath=~/vimruntime,/mygroup/vim,$VIMRUNTIME
6228< This will use the directory "~/vimruntime" first (containing your
6229 personal Vim runtime files), then "/mygroup/vim" (shared between a
6230 group of people) and finally "$VIMRUNTIME" (the distributed runtime
6231 files).
6232 You probably should always include $VIMRUNTIME somewhere, to use the
6233 distributed runtime files. You can put a directory before $VIMRUNTIME
6234 to find files which replace a distributed runtime files. You can put
6235 a directory after $VIMRUNTIME to find files which add to distributed
6236 runtime files.
Bram Moolenaarb5b75622018-03-09 22:22:21 +01006237 When Vim is started with |--clean| the home directory entries are not
6238 included.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006239 This option cannot be set from a |modeline| or in the |sandbox|, for
6240 security reasons.
6241
6242 *'scroll'* *'scr'*
6243'scroll' 'scr' number (default: half the window height)
6244 local to window
6245 Number of lines to scroll with CTRL-U and CTRL-D commands. Will be
6246 set to half the number of lines in the window when the window size
6247 changes. If you give a count to the CTRL-U or CTRL-D command it will
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006248 be used as the new value for 'scroll'. Reset to half the window
Bram Moolenaar25c9c682019-05-05 18:13:34 +02006249 height with ":set scroll=0".
Bram Moolenaar071d4272004-06-13 20:20:40 +00006250
6251 *'scrollbind'* *'scb'* *'noscrollbind'* *'noscb'*
6252'scrollbind' 'scb' boolean (default off)
6253 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00006254 See also |scroll-binding|. When this option is set, the current
6255 window scrolls as other scrollbind windows (windows that also have
6256 this option set) scroll. This option is useful for viewing the
6257 differences between two versions of a file, see 'diff'.
6258 See |'scrollopt'| for options that determine how this option should be
6259 interpreted.
6260 This option is mostly reset when splitting a window to edit another
6261 file. This means that ":split | edit file" results in two windows
6262 with scroll-binding, but ":split file" does not.
6263
6264 *'scrolljump'* *'sj'*
6265'scrolljump' 'sj' number (default 1)
6266 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006267 Minimal number of lines to scroll when the cursor gets off the
6268 screen (e.g., with "j"). Not used for scroll commands (e.g., CTRL-E,
6269 CTRL-D). Useful if your terminal scrolls very slowly.
Bram Moolenaar1e015462005-09-25 22:16:38 +00006270 When set to a negative number from -1 to -100 this is used as the
6271 percentage of the window height. Thus -50 scrolls half the window
6272 height.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006273 NOTE: This option is set to 1 when 'compatible' is set.
6274
6275 *'scrolloff'* *'so'*
Bram Moolenaar50ba5262016-09-22 22:33:02 +02006276'scrolloff' 'so' number (default 0, set to 5 in |defaults.vim|)
Bram Moolenaar375e3392019-01-31 18:26:10 +01006277 global or local to window |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006278 Minimal number of screen lines to keep above and below the cursor.
6279 This will make some context visible around where you are working. If
6280 you set it to a very large value (999) the cursor line will always be
6281 in the middle of the window (except at the start or end of the file or
6282 when long lines wrap).
Bram Moolenaar375e3392019-01-31 18:26:10 +01006283 After using the local value, go back the global value with one of
6284 these two: >
6285 setlocal scrolloff<
6286 setlocal scrolloff=-1
6287< For scrolling horizontally see 'sidescrolloff'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006288 NOTE: This option is set to 0 when 'compatible' is set.
6289
6290 *'scrollopt'* *'sbo'*
6291'scrollopt' 'sbo' string (default "ver,jump")
6292 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006293 This is a comma-separated list of words that specifies how
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006294 'scrollbind' windows should behave. 'sbo' stands for ScrollBind
6295 Options.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006296 The following words are available:
6297 ver Bind vertical scrolling for 'scrollbind' windows
6298 hor Bind horizontal scrolling for 'scrollbind' windows
6299 jump Applies to the offset between two windows for vertical
6300 scrolling. This offset is the difference in the first
6301 displayed line of the bound windows. When moving
6302 around in a window, another 'scrollbind' window may
6303 reach a position before the start or after the end of
6304 the buffer. The offset is not changed though, when
6305 moving back the 'scrollbind' window will try to scroll
6306 to the desired position when possible.
6307 When now making that window the current one, two
6308 things can be done with the relative offset:
6309 1. When "jump" is not included, the relative offset is
6310 adjusted for the scroll position in the new current
6311 window. When going back to the other window, the
Bram Moolenaar02467872007-05-06 13:22:01 +00006312 new relative offset will be used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006313 2. When "jump" is included, the other windows are
6314 scrolled to keep the same relative offset. When
6315 going back to the other window, it still uses the
6316 same relative offset.
6317 Also see |scroll-binding|.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006318 When 'diff' mode is active there always is vertical scroll binding,
6319 even when "ver" isn't there.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006320
6321 *'sections'* *'sect'*
6322'sections' 'sect' string (default "SHNHH HUnhsh")
6323 global
6324 Specifies the nroff macros that separate sections. These are pairs of
6325 two letters (See |object-motions|). The default makes a section start
6326 at the nroff macros ".SH", ".NH", ".H", ".HU", ".nh" and ".sh".
6327
6328 *'secure'* *'nosecure'* *E523*
6329'secure' boolean (default off)
6330 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006331 When on, ":autocmd", shell and write commands are not allowed in
6332 ".vimrc" and ".exrc" in the current directory and map commands are
6333 displayed. Switch it off only if you know that you will not run into
6334 problems, or when the 'exrc' option is off. On Unix this option is
6335 only used if the ".vimrc" or ".exrc" is not owned by you. This can be
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006336 dangerous if the systems allows users to do a "chown". You better set
Bram Moolenaar071d4272004-06-13 20:20:40 +00006337 'secure' at the end of your ~/.vimrc then.
6338 This option cannot be set from a |modeline| or in the |sandbox|, for
6339 security reasons.
6340
6341 *'selection'* *'sel'*
6342'selection' 'sel' string (default "inclusive")
6343 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006344 This option defines the behavior of the selection. It is only used
6345 in Visual and Select mode.
6346 Possible values:
6347 value past line inclusive ~
6348 old no yes
6349 inclusive yes yes
6350 exclusive yes no
6351 "past line" means that the cursor is allowed to be positioned one
6352 character past the line.
6353 "inclusive" means that the last character of the selection is included
6354 in an operation. For example, when "x" is used to delete the
6355 selection.
Bram Moolenaare4a3bcf2016-08-26 19:52:37 +02006356 When "old" is used and 'virtualedit' allows the cursor to move past
6357 the end of line the line break still isn't included.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006358 Note that when "exclusive" is used and selecting from the end
6359 backwards, you cannot include the last character of a line, when
6360 starting in Normal mode and 'virtualedit' empty.
6361
6362 The 'selection' option is set by the |:behave| command.
6363
6364 *'selectmode'* *'slm'*
6365'selectmode' 'slm' string (default "")
6366 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006367 This is a comma separated list of words, which specifies when to start
6368 Select mode instead of Visual mode, when a selection is started.
6369 Possible values:
6370 mouse when using the mouse
6371 key when using shifted special keys
6372 cmd when using "v", "V" or CTRL-V
6373 See |Select-mode|.
6374 The 'selectmode' option is set by the |:behave| command.
6375
6376 *'sessionoptions'* *'ssop'*
6377'sessionoptions' 'ssop' string (default: "blank,buffers,curdir,folds,
Bram Moolenaarb5b75622018-03-09 22:22:21 +01006378 help,options,tabpages,winsize,terminal")
Bram Moolenaar071d4272004-06-13 20:20:40 +00006379 global
Bram Moolenaardb84e452010-08-15 13:50:43 +02006380 {not available when compiled without the |+mksession|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006381 feature}
6382 Changes the effect of the |:mksession| command. It is a comma
6383 separated list of words. Each word enables saving and restoring
6384 something:
6385 word save and restore ~
6386 blank empty windows
6387 buffers hidden and unloaded buffers, not just those in windows
6388 curdir the current directory
6389 folds manually created folds, opened/closed folds and local
6390 fold options
6391 globals global variables that start with an uppercase letter
Bram Moolenaar12805862005-01-05 22:16:17 +00006392 and contain at least one lowercase letter. Only
6393 String and Number types are stored.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006394 help the help window
6395 localoptions options and mappings local to a window or buffer (not
6396 global values for local options)
6397 options all options and mappings (also global values for local
6398 options)
6399 resize size of the Vim window: 'lines' and 'columns'
6400 sesdir the directory in which the session file is located
6401 will become the current directory (useful with
6402 projects accessed over a network from different
6403 systems)
6404 slash backslashes in file names replaced with forward
6405 slashes
Bram Moolenaar18144c82006-04-12 21:52:12 +00006406 tabpages all tab pages; without this only the current tab page
6407 is restored, so that you can make a session for each
6408 tab page separately
Bram Moolenaard473c8c2018-08-11 18:00:22 +02006409 terminal include terminal windows where the command can be
6410 restored
Bram Moolenaar071d4272004-06-13 20:20:40 +00006411 unix with Unix end-of-line format (single <NL>), even when
6412 on Windows or DOS
6413 winpos position of the whole Vim window
6414 winsize window sizes
6415
6416 Don't include both "curdir" and "sesdir".
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006417 When neither "curdir" nor "sesdir" is included, file names are stored
6418 with absolute paths.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006419 "slash" and "unix" are useful on Windows when sharing session files
6420 with Unix. The Unix version of Vim cannot source dos format scripts,
6421 but the Windows version of Vim can source unix format scripts.
6422
6423 *'shell'* *'sh'* *E91*
6424'shell' 'sh' string (default $SHELL or "sh",
6425 MS-DOS and Win32: "command.com" or
6426 "cmd.exe", OS/2: "cmd")
6427 global
6428 Name of the shell to use for ! and :! commands. When changing the
6429 value also check these options: 'shelltype', 'shellpipe', 'shellslash'
6430 'shellredir', 'shellquote', 'shellxquote' and 'shellcmdflag'.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006431 It is allowed to give an argument to the command, e.g. "csh -f".
Bram Moolenaar071d4272004-06-13 20:20:40 +00006432 See |option-backslash| about including spaces and backslashes.
6433 Environment variables are expanded |:set_env|.
Bram Moolenaar4bfa8af2018-02-03 15:14:46 +01006434
Bram Moolenaar071d4272004-06-13 20:20:40 +00006435 If the name of the shell contains a space, you might need to enclose
Bram Moolenaar4bfa8af2018-02-03 15:14:46 +01006436 it in quotes or escape the space. Example with quotes: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006437 :set shell=\"c:\program\ files\unix\sh.exe\"\ -f
6438< Note the backslash before each quote (to avoid starting a comment) and
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006439 each space (to avoid ending the option value). Also note that the
Bram Moolenaar071d4272004-06-13 20:20:40 +00006440 "-f" is not inside the quotes, because it is not part of the command
Bram Moolenaar4bfa8af2018-02-03 15:14:46 +01006441 name. Vim automagically recognizes the backslashes that are path
Bram Moolenaar071d4272004-06-13 20:20:40 +00006442 separators.
Bram Moolenaar4bfa8af2018-02-03 15:14:46 +01006443 Example with escaped space (Vim will do this when initializing the
6444 option from $SHELL): >
6445 :set shell=/bin/with\\\ space/sh
Bram Moolenaard473c8c2018-08-11 18:00:22 +02006446< The resulting value of 'shell' is "/bin/with\ space/sh", two
Bram Moolenaar4bfa8af2018-02-03 15:14:46 +01006447 backslashes are consumed by `:set`.
6448
Bram Moolenaar071d4272004-06-13 20:20:40 +00006449 Under MS-Windows, when the executable ends in ".com" it must be
6450 included. Thus setting the shell to "command.com" or "4dos.com"
6451 works, but "command" and "4dos" do not work for all commands (e.g.,
6452 filtering).
6453 For unknown reasons, when using "4dos.com" the current directory is
6454 changed to "C:\". To avoid this set 'shell' like this: >
6455 :set shell=command.com\ /c\ 4dos
6456< This option cannot be set from a |modeline| or in the |sandbox|, for
6457 security reasons.
6458
6459 *'shellcmdflag'* *'shcf'*
Bram Moolenaar5dc62522012-02-13 00:05:22 +01006460'shellcmdflag' 'shcf' string (default: "-c";
Bram Moolenaardb7207e2012-02-22 17:30:19 +01006461 MS-DOS and Win32, when 'shell' does not
6462 contain "sh" somewhere: "/c")
Bram Moolenaar071d4272004-06-13 20:20:40 +00006463 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006464 Flag passed to the shell to execute "!" and ":!" commands; e.g.,
6465 "bash.exe -c ls" or "command.com /c dir". For the MS-DOS-like
6466 systems, the default is set according to the value of 'shell', to
Bram Moolenaare0720cb2017-03-29 13:48:40 +02006467 reduce the need to set this option by the user.
Bram Moolenaar5302d9e2011-09-14 17:55:08 +02006468 On Unix it can have more than one flag. Each white space separated
6469 part is passed as an argument to the shell command.
6470 See |option-backslash| about including spaces and backslashes.
6471 Also see |dos-shell| for MS-DOS and MS-Windows.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006472 This option cannot be set from a |modeline| or in the |sandbox|, for
6473 security reasons.
6474
6475 *'shellpipe'* *'sp'*
6476'shellpipe' 'sp' string (default ">", "| tee", "|& tee" or "2>&1| tee")
6477 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006478 {not available when compiled without the |+quickfix|
6479 feature}
6480 String to be used to put the output of the ":make" command in the
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006481 error file. See also |:make_makeprg|. See |option-backslash| about
Bram Moolenaar071d4272004-06-13 20:20:40 +00006482 including spaces and backslashes.
6483 The name of the temporary file can be represented by "%s" if necessary
6484 (the file name is appended automatically if no %s appears in the value
6485 of this option).
6486 For the Amiga and MS-DOS the default is ">". The output is directly
6487 saved in a file and not echoed to the screen.
6488 For Unix the default it "| tee". The stdout of the compiler is saved
6489 in a file and echoed to the screen. If the 'shell' option is "csh" or
6490 "tcsh" after initializations, the default becomes "|& tee". If the
Bram Moolenaar8e5af3e2011-04-28 19:02:44 +02006491 'shell' option is "sh", "ksh", "mksh", "pdksh", "zsh" or "bash" the
6492 default becomes "2>&1| tee". This means that stderr is also included.
6493 Before using the 'shell' option a path is removed, thus "/bin/sh" uses
6494 "sh".
Bram Moolenaar071d4272004-06-13 20:20:40 +00006495 The initialization of this option is done after reading the ".vimrc"
6496 and the other initializations, so that when the 'shell' option is set
6497 there, the 'shellpipe' option changes automatically, unless it was
6498 explicitly set before.
6499 When 'shellpipe' is set to an empty string, no redirection of the
6500 ":make" output will be done. This is useful if you use a 'makeprg'
6501 that writes to 'makeef' by itself. If you want no piping, but do
6502 want to include the 'makeef', set 'shellpipe' to a single space.
6503 Don't forget to precede the space with a backslash: ":set sp=\ ".
6504 In the future pipes may be used for filtering and this option will
6505 become obsolete (at least for Unix).
6506 This option cannot be set from a |modeline| or in the |sandbox|, for
6507 security reasons.
6508
6509 *'shellquote'* *'shq'*
6510'shellquote' 'shq' string (default: ""; MS-DOS and Win32, when 'shell'
6511 contains "sh" somewhere: "\"")
6512 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006513 Quoting character(s), put around the command passed to the shell, for
6514 the "!" and ":!" commands. The redirection is kept outside of the
6515 quoting. See 'shellxquote' to include the redirection. It's
6516 probably not useful to set both options.
6517 This is an empty string by default. Only known to be useful for
6518 third-party shells on MS-DOS-like systems, such as the MKS Korn Shell
6519 or bash, where it should be "\"". The default is adjusted according
6520 the value of 'shell', to reduce the need to set this option by the
6521 user. See |dos-shell|.
6522 This option cannot be set from a |modeline| or in the |sandbox|, for
6523 security reasons.
6524
6525 *'shellredir'* *'srr'*
6526'shellredir' 'srr' string (default ">", ">&" or ">%s 2>&1")
6527 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006528 String to be used to put the output of a filter command in a temporary
6529 file. See also |:!|. See |option-backslash| about including spaces
6530 and backslashes.
6531 The name of the temporary file can be represented by "%s" if necessary
6532 (the file name is appended automatically if no %s appears in the value
6533 of this option).
6534 The default is ">". For Unix, if the 'shell' option is "csh", "tcsh"
6535 or "zsh" during initializations, the default becomes ">&". If the
6536 'shell' option is "sh", "ksh" or "bash" the default becomes
6537 ">%s 2>&1". This means that stderr is also included.
6538 For Win32, the Unix checks are done and additionally "cmd" is checked
6539 for, which makes the default ">%s 2>&1". Also, the same names with
6540 ".exe" appended are checked for.
6541 The initialization of this option is done after reading the ".vimrc"
6542 and the other initializations, so that when the 'shell' option is set
6543 there, the 'shellredir' option changes automatically unless it was
6544 explicitly set before.
6545 In the future pipes may be used for filtering and this option will
6546 become obsolete (at least for Unix).
6547 This option cannot be set from a |modeline| or in the |sandbox|, for
6548 security reasons.
6549
6550 *'shellslash'* *'ssl'* *'noshellslash'* *'nossl'*
6551'shellslash' 'ssl' boolean (default off)
6552 global
Bram Moolenaar6c60f472019-04-28 16:00:35 +02006553 {only for MSDOS, MS-Windows and OS/2}
Bram Moolenaar071d4272004-06-13 20:20:40 +00006554 When set, a forward slash is used when expanding file names. This is
6555 useful when a Unix-like shell is used instead of command.com or
6556 cmd.exe. Backward slashes can still be typed, but they are changed to
6557 forward slashes by Vim.
6558 Note that setting or resetting this option has no effect for some
6559 existing file names, thus this option needs to be set before opening
6560 any file for best results. This might change in the future.
6561 'shellslash' only works when a backslash can be used as a path
6562 separator. To test if this is so use: >
6563 if exists('+shellslash')
Bram Moolenaarac3150d2019-07-28 16:36:39 +02006564< Also see 'completeslash'.
6565
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006566 *'shelltemp'* *'stmp'* *'noshelltemp'* *'nostmp'*
6567'shelltemp' 'stmp' boolean (Vi default off, Vim default on)
6568 global
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006569 When on, use temp files for shell commands. When off use a pipe.
6570 When using a pipe is not possible temp files are used anyway.
Bram Moolenaar97293012011-07-18 19:40:27 +02006571 Currently a pipe is only supported on Unix and MS-Windows 2K and
6572 later. You can check it with: >
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006573 :if has("filterpipe")
6574< The advantage of using a pipe is that nobody can read the temp file
6575 and the 'shell' command does not need to support redirection.
6576 The advantage of using a temp file is that the file type and encoding
6577 can be detected.
6578 The |FilterReadPre|, |FilterReadPost| and |FilterWritePre|,
6579 |FilterWritePost| autocommands event are not triggered when
6580 'shelltemp' is off.
Bram Moolenaar269f5952016-07-15 22:54:41 +02006581 The `system()` function does not respect this option and always uses
6582 temp files.
Bram Moolenaar036986f2017-03-16 17:41:02 +01006583 NOTE: This option is set to the Vim default value when 'compatible'
6584 is reset.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006585
Bram Moolenaar071d4272004-06-13 20:20:40 +00006586 *'shelltype'* *'st'*
6587'shelltype' 'st' number (default 0)
6588 global
Bram Moolenaar6c60f472019-04-28 16:00:35 +02006589 {only for the Amiga}
Bram Moolenaar071d4272004-06-13 20:20:40 +00006590 On the Amiga this option influences the way how the commands work
6591 which use a shell.
6592 0 and 1: always use the shell
6593 2 and 3: use the shell only to filter lines
6594 4 and 5: use shell only for ':sh' command
6595 When not using the shell, the command is executed directly.
6596
6597 0 and 2: use "shell 'shellcmdflag' cmd" to start external commands
6598 1 and 3: use "shell cmd" to start external commands
6599
Bram Moolenaardb7207e2012-02-22 17:30:19 +01006600 *'shellxescape'* *'sxe'*
6601'shellxescape' 'sxe' string (default: "";
6602 for MS-DOS and MS-Windows: "\"&|<>()@^")
6603 global
Bram Moolenaardb7207e2012-02-22 17:30:19 +01006604 When 'shellxquote' is set to "(" then the characters listed in this
6605 option will be escaped with a '^' character. This makes it possible
6606 to execute most external commands with cmd.exe.
6607
Bram Moolenaar071d4272004-06-13 20:20:40 +00006608 *'shellxquote'* *'sxq'*
6609'shellxquote' 'sxq' string (default: "";
Bram Moolenaarf66b3fc2012-02-20 22:18:30 +01006610 for Win32, when 'shell' is cmd.exe: "("
6611 for Win32, when 'shell' contains "sh"
6612 somewhere: "\""
Bram Moolenaar071d4272004-06-13 20:20:40 +00006613 for Unix, when using system(): "\"")
6614 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006615 Quoting character(s), put around the command passed to the shell, for
6616 the "!" and ":!" commands. Includes the redirection. See
6617 'shellquote' to exclude the redirection. It's probably not useful
6618 to set both options.
Bram Moolenaarf66b3fc2012-02-20 22:18:30 +01006619 When the value is '(' then ')' is appended. When the value is '"('
6620 then ')"' is appended.
6621 When the value is '(' then also see 'shellxescape'.
Bram Moolenaara64ba222012-02-12 23:23:31 +01006622 This is an empty string by default on most systems, but is known to be
6623 useful for on Win32 version, either for cmd.exe which automatically
6624 strips off the first and last quote on a command, or 3rd-party shells
6625 such as the MKS Korn Shell or bash, where it should be "\"". The
6626 default is adjusted according the value of 'shell', to reduce the need
6627 to set this option by the user. See |dos-shell|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006628 This option cannot be set from a |modeline| or in the |sandbox|, for
6629 security reasons.
6630
6631 *'shiftround'* *'sr'* *'noshiftround'* *'nosr'*
6632'shiftround' 'sr' boolean (default off)
6633 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006634 Round indent to multiple of 'shiftwidth'. Applies to > and <
6635 commands. CTRL-T and CTRL-D in Insert mode always round the indent to
6636 a multiple of 'shiftwidth' (this is Vi compatible).
6637 NOTE: This option is reset when 'compatible' is set.
6638
6639 *'shiftwidth'* *'sw'*
6640'shiftwidth' 'sw' number (default 8)
6641 local to buffer
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006642 Number of spaces to use for each step of (auto)indent. Used for
Bram Moolenaar071d4272004-06-13 20:20:40 +00006643 |'cindent'|, |>>|, |<<|, etc.
Bram Moolenaar3a0d8092012-10-21 03:02:54 +02006644 When zero the 'ts' value will be used. Use the |shiftwidth()|
6645 function to get the effective shiftwidth value.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006646
6647 *'shortmess'* *'shm'*
Bram Moolenaar9dfa3132019-05-04 21:08:40 +02006648'shortmess' 'shm' string (Vim default "filnxtToOS", Vi default: "S",
6649 POSIX default: "AS")
Bram Moolenaar071d4272004-06-13 20:20:40 +00006650 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006651 This option helps to avoid all the |hit-enter| prompts caused by file
6652 messages, for example with CTRL-G, and to avoid some other messages.
6653 It is a list of flags:
6654 flag meaning when present ~
6655 f use "(3 of 5)" instead of "(file 3 of 5)"
6656 i use "[noeol]" instead of "[Incomplete last line]"
6657 l use "999L, 888C" instead of "999 lines, 888 characters"
6658 m use "[+]" instead of "[Modified]"
6659 n use "[New]" instead of "[New File]"
6660 r use "[RO]" instead of "[readonly]"
6661 w use "[w]" instead of "written" for file write message
6662 and "[a]" instead of "appended" for ':w >> file' command
6663 x use "[dos]" instead of "[dos format]", "[unix]" instead of
6664 "[unix format]" and "[mac]" instead of "[mac format]".
6665 a all of the above abbreviations
6666
6667 o overwrite message for writing a file with subsequent message
6668 for reading a file (useful for ":wn" or when 'autowrite' on)
6669 O message for reading a file overwrites any previous message.
6670 Also for quickfix message (e.g., ":cn").
6671 s don't give "search hit BOTTOM, continuing at TOP" or "search
Bram Moolenaara6c27c42019-05-09 19:16:22 +02006672 hit TOP, continuing at BOTTOM" messages; when using the search
6673 count do not show "W" after the count message (see S below)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006674 t truncate file message at the start if it is too long to fit
6675 on the command-line, "<" will appear in the left most column.
6676 Ignored in Ex mode.
6677 T truncate other messages in the middle if they are too long to
Bram Moolenaar582fd852005-03-28 20:58:01 +00006678 fit on the command line. "..." will appear in the middle.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006679 Ignored in Ex mode.
6680 W don't give "written" or "[w]" when writing a file
6681 A don't give the "ATTENTION" message when an existing swap file
6682 is found.
6683 I don't give the intro message when starting Vim |:intro|.
Bram Moolenaarea389e92014-05-28 21:40:52 +02006684 c don't give |ins-completion-menu| messages. For example,
6685 "-- XXX completion (YYY)", "match 1 of 2", "The only match",
6686 "Pattern not found", "Back at original", etc.
Bram Moolenaar426dd022016-03-15 15:09:29 +01006687 q use "recording" instead of "recording @a"
6688 F don't give the file info when editing a file, like `:silent`
Bram Moolenaar110289e2019-05-23 15:38:06 +02006689 was used for the command; note that this also affects messages
6690 from autocommands
Bram Moolenaar9dfa3132019-05-04 21:08:40 +02006691 S do not show search count message when searching, e.g.
6692 "[1/5]"
Bram Moolenaar071d4272004-06-13 20:20:40 +00006693
6694 This gives you the opportunity to avoid that a change between buffers
6695 requires you to hit <Enter>, but still gives as useful a message as
6696 possible for the space available. To get the whole message that you
6697 would have got with 'shm' empty, use ":file!"
6698 Useful values:
6699 shm= No abbreviation of message.
6700 shm=a Abbreviation, but no loss of information.
6701 shm=at Abbreviation, and truncate message when necessary.
6702
6703 NOTE: This option is set to the Vi default value when 'compatible' is
6704 set and to the Vim default value when 'compatible' is reset.
6705
6706 *'shortname'* *'sn'* *'noshortname'* *'nosn'*
6707'shortname' 'sn' boolean (default off)
6708 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00006709 Filenames are assumed to be 8 characters plus one extension of 3
6710 characters. Multiple dots in file names are not allowed. When this
6711 option is on, dots in file names are replaced with underscores when
6712 adding an extension (".~" or ".swp"). This option is not available
6713 for MS-DOS, because then it would always be on. This option is useful
6714 when editing files on an MS-DOS compatible filesystem, e.g., messydos
6715 or crossdos. When running the Win32 GUI version under Win32s, this
6716 option is always on by default.
6717
6718 *'showbreak'* *'sbr'* *E595*
6719'showbreak' 'sbr' string (default "")
6720 global
Bram Moolenaardb84e452010-08-15 13:50:43 +02006721 {not available when compiled without the |+linebreak|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006722 feature}
6723 String to put at the start of lines that have been wrapped. Useful
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006724 values are "> " or "+++ ": >
6725 :set showbreak=>\
6726< Note the backslash to escape the trailing space. It's easier like
6727 this: >
Bram Moolenaar1a384422010-07-14 19:53:30 +02006728 :let &showbreak = '+++ '
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006729< Only printable single-cell characters are allowed, excluding <Tab> and
Bram Moolenaar071d4272004-06-13 20:20:40 +00006730 comma (in a future version the comma might be used to separate the
6731 part that is shown at the end and at the start of a line).
6732 The characters are highlighted according to the '@' flag in
6733 'highlight'.
6734 Note that tabs after the showbreak will be displayed differently.
6735 If you want the 'showbreak' to appear in between line numbers, add the
6736 "n" flag to 'cpoptions'.
6737
6738 *'showcmd'* *'sc'* *'noshowcmd'* *'nosc'*
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +02006739'showcmd' 'sc' boolean (Vim default: on, off for Unix,
6740 Vi default: off, set in |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006741 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006742 {not available when compiled without the
6743 |+cmdline_info| feature}
Bram Moolenaar02467872007-05-06 13:22:01 +00006744 Show (partial) command in the last line of the screen. Set this
6745 option off if your terminal is slow.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006746 In Visual mode the size of the selected area is shown:
6747 - When selecting characters within a line, the number of characters.
Bram Moolenaarf91787c2010-07-17 12:47:16 +02006748 If the number of bytes is different it is also displayed: "2-6"
6749 means two characters and six bytes.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006750 - When selecting more than one line, the number of lines.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006751 - When selecting a block, the size in screen characters:
6752 {lines}x{columns}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006753 NOTE: This option is set to the Vi default value when 'compatible' is
6754 set and to the Vim default value when 'compatible' is reset.
6755
6756 *'showfulltag'* *'sft'* *'noshowfulltag'* *'nosft'*
6757'showfulltag' 'sft' boolean (default off)
6758 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006759 When completing a word in insert mode (see |ins-completion|) from the
6760 tags file, show both the tag name and a tidied-up form of the search
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006761 pattern (if there is one) as possible matches. Thus, if you have
Bram Moolenaar071d4272004-06-13 20:20:40 +00006762 matched a C function, you can see a template for what arguments are
6763 required (coding style permitting).
Bram Moolenaar446cb832008-06-24 21:56:24 +00006764 Note that this doesn't work well together with having "longest" in
6765 'completeopt', because the completion from the search pattern may not
6766 match the typed text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006767
6768 *'showmatch'* *'sm'* *'noshowmatch'* *'nosm'*
6769'showmatch' 'sm' boolean (default off)
6770 global
6771 When a bracket is inserted, briefly jump to the matching one. The
6772 jump is only done if the match can be seen on the screen. The time to
6773 show the match can be set with 'matchtime'.
6774 A Beep is given if there is no match (no matter if the match can be
Bram Moolenaarca635012015-09-25 20:34:21 +02006775 seen or not).
6776 This option is reset when 'paste' is set and restored when 'paste' is
6777 reset.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006778 When the 'm' flag is not included in 'cpoptions', typing a character
6779 will immediately move the cursor back to where it belongs.
6780 See the "sm" field in 'guicursor' for setting the cursor shape and
6781 blinking when showing the match.
6782 The 'matchpairs' option can be used to specify the characters to show
6783 matches for. 'rightleft' and 'revins' are used to look for opposite
6784 matches.
Bram Moolenaarfd2ac762006-03-01 22:09:21 +00006785 Also see the matchparen plugin for highlighting the match when moving
6786 around |pi_paren.txt|.
6787 Note: Use of the short form is rated PG.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006788
6789 *'showmode'* *'smd'* *'noshowmode'* *'nosmd'*
6790'showmode' 'smd' boolean (Vim default: on, Vi default: off)
6791 global
6792 If in Insert, Replace or Visual mode put a message on the last line.
6793 Use the 'M' flag in 'highlight' to set the type of highlighting for
6794 this message.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006795 When |XIM| may be used the message will include "XIM". But this
Bram Moolenaar071d4272004-06-13 20:20:40 +00006796 doesn't mean XIM is really active, especially when 'imactivatekey' is
6797 not set.
6798 NOTE: This option is set to the Vi default value when 'compatible' is
6799 set and to the Vim default value when 'compatible' is reset.
6800
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00006801 *'showtabline'* *'stal'*
6802'showtabline' 'stal' number (default 1)
6803 global
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00006804 The value of this option specifies when the line with tab page labels
6805 will be displayed:
6806 0: never
6807 1: only if there are at least two tab pages
6808 2: always
6809 This is both for the GUI and non-GUI implementation of the tab pages
6810 line.
6811 See |tab-page| for more information about tab pages.
6812
Bram Moolenaar071d4272004-06-13 20:20:40 +00006813 *'sidescroll'* *'ss'*
6814'sidescroll' 'ss' number (default 0)
6815 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006816 The minimal number of columns to scroll horizontally. Used only when
6817 the 'wrap' option is off and the cursor is moved off of the screen.
6818 When it is zero the cursor will be put in the middle of the screen.
6819 When using a slow terminal set it to a large number or 0. When using
6820 a fast terminal use a small number or 1. Not used for "zh" and "zl"
6821 commands.
6822
6823 *'sidescrolloff'* *'siso'*
6824'sidescrolloff' 'siso' number (default 0)
Bram Moolenaar375e3392019-01-31 18:26:10 +01006825 global or local to window |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006826 The minimal number of screen columns to keep to the left and to the
Bram Moolenaar482aaeb2005-09-29 18:26:07 +00006827 right of the cursor if 'nowrap' is set. Setting this option to a
6828 value greater than 0 while having |'sidescroll'| also at a non-zero
6829 value makes some context visible in the line you are scrolling in
6830 horizontally (except at beginning of the line). Setting this option
6831 to a large value (like 999) has the effect of keeping the cursor
6832 horizontally centered in the window, as long as one does not come too
6833 close to the beginning of the line.
Bram Moolenaar375e3392019-01-31 18:26:10 +01006834 After using the local value, go back the global value with one of
6835 these two: >
6836 setlocal sidescrolloff<
6837 setlocal sidescrolloff=-1
6838< NOTE: This option is set to 0 when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006839
6840 Example: Try this together with 'sidescroll' and 'listchars' as
6841 in the following example to never allow the cursor to move
Bram Moolenaar95ec9d62016-08-12 18:29:59 +02006842 onto the "extends" character: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006843
6844 :set nowrap sidescroll=1 listchars=extends:>,precedes:<
6845 :set sidescrolloff=1
Bram Moolenaar95ec9d62016-08-12 18:29:59 +02006846<
6847 *'signcolumn'* *'scl'*
6848'signcolumn' 'scl' string (default "auto")
6849 local to window
Bram Moolenaar95ec9d62016-08-12 18:29:59 +02006850 {not available when compiled without the |+signs|
6851 feature}
Bram Moolenaar09521312016-08-12 22:54:35 +02006852 Whether or not to draw the signcolumn. Valid values are:
6853 "auto" only when there is a sign to display
6854 "no" never
6855 "yes" always
Bram Moolenaar394c5d82019-06-17 21:48:05 +02006856 "number" display signs in the 'number' column. If the number
Bram Moolenaar6c1e1572019-06-22 02:13:00 +02006857 column is not present, then behaves like "auto".
Bram Moolenaar071d4272004-06-13 20:20:40 +00006858
6859
6860 *'smartcase'* *'scs'* *'nosmartcase'* *'noscs'*
6861'smartcase' 'scs' boolean (default off)
6862 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006863 Override the 'ignorecase' option if the search pattern contains upper
6864 case characters. Only used when the search pattern is typed and
6865 'ignorecase' option is on. Used for the commands "/", "?", "n", "N",
Bram Moolenaarc8734422012-06-01 22:38:45 +02006866 ":g" and ":s". Not used for "*", "#", "gd", tag search, etc. After
Bram Moolenaar071d4272004-06-13 20:20:40 +00006867 "*" and "#" you can make 'smartcase' used by doing a "/" command,
6868 recalling the search pattern from history and hitting <Enter>.
6869 NOTE: This option is reset when 'compatible' is set.
6870
6871 *'smartindent'* *'si'* *'nosmartindent'* *'nosi'*
6872'smartindent' 'si' boolean (default off)
6873 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00006874 {not available when compiled without the
6875 |+smartindent| feature}
6876 Do smart autoindenting when starting a new line. Works for C-like
6877 programs, but can also be used for other languages. 'cindent' does
6878 something like this, works better in most cases, but is more strict,
Bram Moolenaar81af9252010-12-10 20:35:50 +01006879 see |C-indenting|. When 'cindent' is on or 'indentexpr' is set,
Bram Moolenaar166af9b2010-11-16 20:34:40 +01006880 setting 'si' has no effect. 'indentexpr' is a more advanced
6881 alternative.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006882 Normally 'autoindent' should also be on when using 'smartindent'.
6883 An indent is automatically inserted:
6884 - After a line ending in '{'.
6885 - After a line starting with a keyword from 'cinwords'.
6886 - Before a line starting with '}' (only with the "O" command).
6887 When typing '}' as the first character in a new line, that line is
6888 given the same indent as the matching '{'.
6889 When typing '#' as the first character in a new line, the indent for
6890 that line is removed, the '#' is put in the first column. The indent
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006891 is restored for the next line. If you don't want this, use this
Bram Moolenaar071d4272004-06-13 20:20:40 +00006892 mapping: ":inoremap # X^H#", where ^H is entered with CTRL-V CTRL-H.
6893 When using the ">>" command, lines starting with '#' are not shifted
6894 right.
Bram Moolenaar036986f2017-03-16 17:41:02 +01006895 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaarca635012015-09-25 20:34:21 +02006896 This option is reset when 'paste' is set and restored when 'paste' is
6897 reset.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006898
6899 *'smarttab'* *'sta'* *'nosmarttab'* *'nosta'*
6900'smarttab' 'sta' boolean (default off)
6901 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006902 When on, a <Tab> in front of a line inserts blanks according to
Bram Moolenaar280f1262006-01-30 00:14:18 +00006903 'shiftwidth'. 'tabstop' or 'softtabstop' is used in other places. A
6904 <BS> will delete a 'shiftwidth' worth of space at the start of the
6905 line.
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +00006906 When off, a <Tab> always inserts blanks according to 'tabstop' or
Bram Moolenaar280f1262006-01-30 00:14:18 +00006907 'softtabstop'. 'shiftwidth' is only used for shifting text left or
6908 right |shift-left-right|.
Bram Moolenaarebcbd022007-05-12 14:28:25 +00006909 What gets inserted (a <Tab> or spaces) depends on the 'expandtab'
Bram Moolenaar071d4272004-06-13 20:20:40 +00006910 option. Also see |ins-expandtab|. When 'expandtab' is not set, the
Bram Moolenaar843ee412004-06-30 16:16:41 +00006911 number of spaces is minimized by using <Tab>s.
Bram Moolenaarca635012015-09-25 20:34:21 +02006912 This option is reset when 'paste' is set and restored when 'paste' is
6913 reset.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006914 NOTE: This option is reset when 'compatible' is set.
6915
6916 *'softtabstop'* *'sts'*
6917'softtabstop' 'sts' number (default 0)
6918 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00006919 Number of spaces that a <Tab> counts for while performing editing
6920 operations, like inserting a <Tab> or using <BS>. It "feels" like
6921 <Tab>s are being inserted, while in fact a mix of spaces and <Tab>s is
6922 used. This is useful to keep the 'ts' setting at its standard value
6923 of 8, while being able to edit like it is set to 'sts'. However,
6924 commands like "x" still work on the actual characters.
6925 When 'sts' is zero, this feature is off.
Bram Moolenaar3a0d8092012-10-21 03:02:54 +02006926 When 'sts' is negative, the value of 'shiftwidth' is used.
Bram Moolenaarca635012015-09-25 20:34:21 +02006927 'softtabstop' is set to 0 when the 'paste' option is set and restored
6928 when 'paste' is reset.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006929 See also |ins-expandtab|. When 'expandtab' is not set, the number of
6930 spaces is minimized by using <Tab>s.
6931 The 'L' flag in 'cpoptions' changes how tabs are used when 'list' is
6932 set.
6933 NOTE: This option is set to 0 when 'compatible' is set.
6934
Bram Moolenaar04958cb2018-06-23 19:23:02 +02006935 If Vim is compiled with the |+vartabs| feature then the value of
6936 'softtabstop' will be ignored if |'varsofttabstop'| is set to
6937 anything other than an empty string.
6938
Bram Moolenaar217ad922005-03-20 22:37:15 +00006939 *'spell'* *'nospell'*
6940'spell' boolean (default off)
6941 local to window
Bram Moolenaar217ad922005-03-20 22:37:15 +00006942 {not available when compiled without the |+syntax|
6943 feature}
6944 When on spell checking will be done. See |spell|.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006945 The languages are specified with 'spelllang'.
Bram Moolenaar217ad922005-03-20 22:37:15 +00006946
Bram Moolenaar0d9c26d2005-07-02 23:19:16 +00006947 *'spellcapcheck'* *'spc'*
Bram Moolenaar0dc065e2005-07-04 22:49:24 +00006948'spellcapcheck' 'spc' string (default "[.?!]\_[\])'" \t]\+")
Bram Moolenaar0d9c26d2005-07-02 23:19:16 +00006949 local to buffer
Bram Moolenaar0d9c26d2005-07-02 23:19:16 +00006950 {not available when compiled without the |+syntax|
6951 feature}
6952 Pattern to locate the end of a sentence. The following word will be
6953 checked to start with a capital letter. If not then it is highlighted
Bram Moolenaar8aff23a2005-08-19 20:40:30 +00006954 with SpellCap |hl-SpellCap| (unless the word is also badly spelled).
Bram Moolenaar0d9c26d2005-07-02 23:19:16 +00006955 When this check is not wanted make this option empty.
6956 Only used when 'spell' is set.
Bram Moolenaar0dc065e2005-07-04 22:49:24 +00006957 Be careful with special characters, see |option-backslash| about
6958 including spaces and backslashes.
Bram Moolenaar90cfdbe2005-08-12 19:59:19 +00006959 To set this option automatically depending on the language, see
6960 |set-spc-auto|.
Bram Moolenaar0d9c26d2005-07-02 23:19:16 +00006961
Bram Moolenaar82cf9b62005-06-07 21:09:25 +00006962 *'spellfile'* *'spf'*
6963'spellfile' 'spf' string (default empty)
6964 local to buffer
Bram Moolenaar82cf9b62005-06-07 21:09:25 +00006965 {not available when compiled without the |+syntax|
6966 feature}
6967 Name of the word list file where words are added for the |zg| and |zw|
Bram Moolenaar045e82d2005-07-08 22:25:33 +00006968 commands. It must end in ".{encoding}.add". You need to include the
6969 path, otherwise the file is placed in the current directory.
Bram Moolenaar0d9c26d2005-07-02 23:19:16 +00006970 *E765*
6971 It may also be a comma separated list of names. A count before the
6972 |zg| and |zw| commands can be used to access each. This allows using
6973 a personal word list file and a project word list file.
Bram Moolenaar82cf9b62005-06-07 21:09:25 +00006974 When a word is added while this option is empty Vim will set it for
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006975 you: Using the first directory in 'runtimepath' that is writable. If
6976 there is no "spell" directory yet it will be created. For the file
6977 name the first language name that appears in 'spelllang' is used,
Bram Moolenaar3b506942005-06-23 22:36:45 +00006978 ignoring the region.
6979 The resulting ".spl" file will be used for spell checking, it does not
6980 have to appear in 'spelllang'.
6981 Normally one file is used for all regions, but you can add the region
6982 name if you want to. However, it will then only be used when
6983 'spellfile' is set to it, for entries in 'spelllang' only files
6984 without region name will be found.
Bram Moolenaare7566042005-06-17 22:00:15 +00006985 This option cannot be set from a |modeline| or in the |sandbox|, for
6986 security reasons.
Bram Moolenaar82cf9b62005-06-07 21:09:25 +00006987
Bram Moolenaar217ad922005-03-20 22:37:15 +00006988 *'spelllang'* *'spl'*
Bram Moolenaar82cf9b62005-06-07 21:09:25 +00006989'spelllang' 'spl' string (default "en")
Bram Moolenaar217ad922005-03-20 22:37:15 +00006990 local to buffer
Bram Moolenaar217ad922005-03-20 22:37:15 +00006991 {not available when compiled without the |+syntax|
6992 feature}
Bram Moolenaar3b506942005-06-23 22:36:45 +00006993 A comma separated list of word list names. When the 'spell' option is
6994 on spellchecking will be done for these languages. Example: >
6995 set spelllang=en_us,nl,medical
6996< This means US English, Dutch and medical words are recognized. Words
6997 that are not recognized will be highlighted.
Bram Moolenaar911ead12019-04-21 00:03:35 +02006998 The word list name must consist of alphanumeric characters, a dash or
6999 an underscore. It should not include a comma or dot. Using a dash is
Bram Moolenaar3b506942005-06-23 22:36:45 +00007000 recommended to separate the two letter language name from a
7001 specification. Thus "en-rare" is used for rare English words.
7002 A region name must come last and have the form "_xx", where "xx" is
7003 the two-letter, lower case region name. You can use more than one
7004 region by listing them: "en_us,en_ca" supports both US and Canadian
7005 English, but not words specific for Australia, New Zealand or Great
Bram Moolenaarfa735342016-01-03 22:14:44 +01007006 Britain. (Note: currently en_au and en_nz dictionaries are older than
7007 en_ca, en_gb and en_us).
Bram Moolenaarcc63c642013-11-12 04:44:01 +01007008 If the name "cjk" is included East Asian characters are excluded from
7009 spell checking. This is useful when editing text that also has Asian
7010 words.
Bram Moolenaar8aff23a2005-08-19 20:40:30 +00007011 *E757*
Bram Moolenaarce0842a2005-07-18 21:58:11 +00007012 As a special case the name of a .spl file can be given as-is. The
7013 first "_xx" in the name is removed and used as the region name
7014 (_xx is an underscore, two letters and followed by a non-letter).
7015 This is mainly for testing purposes. You must make sure the correct
7016 encoding is used, Vim doesn't check it.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00007017 When 'encoding' is set the word lists are reloaded. Thus it's a good
Bram Moolenaarce0842a2005-07-18 21:58:11 +00007018 idea to set 'spelllang' after setting 'encoding' to avoid loading the
7019 files twice.
Bram Moolenaar3b506942005-06-23 22:36:45 +00007020 How the related spell files are found is explained here: |spell-load|.
Bram Moolenaar217ad922005-03-20 22:37:15 +00007021
Bram Moolenaar98692072006-02-04 00:57:42 +00007022 If the |spellfile.vim| plugin is active and you use a language name
7023 for which Vim cannot find the .spl file in 'runtimepath' the plugin
7024 will ask you if you want to download the file.
7025
Bram Moolenaar90cfdbe2005-08-12 19:59:19 +00007026 After this option has been set successfully, Vim will source the files
7027 "spell/LANG.vim" in 'runtimepath'. "LANG" is the value of 'spelllang'
Bram Moolenaarb730f0c2018-11-25 03:56:26 +01007028 up to the first character that is not an ASCII letter or number and
7029 not a dash. Also see |set-spc-auto|.
Bram Moolenaar90cfdbe2005-08-12 19:59:19 +00007030
7031
Bram Moolenaard857f0e2005-06-21 22:37:39 +00007032 *'spellsuggest'* *'sps'*
7033'spellsuggest' 'sps' string (default "best")
7034 global
Bram Moolenaard857f0e2005-06-21 22:37:39 +00007035 {not available when compiled without the |+syntax|
7036 feature}
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00007037 Methods used for spelling suggestions. Both for the |z=| command and
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00007038 the |spellsuggest()| function. This is a comma-separated list of
7039 items:
Bram Moolenaard857f0e2005-06-21 22:37:39 +00007040
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00007041 best Internal method that works best for English. Finds
7042 changes like "fast" and uses a bit of sound-a-like
7043 scoring to improve the ordering.
7044
7045 double Internal method that uses two methods and mixes the
7046 results. The first method is "fast", the other method
Bram Moolenaard857f0e2005-06-21 22:37:39 +00007047 computes how much the suggestion sounds like the bad
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00007048 word. That only works when the language specifies
7049 sound folding. Can be slow and doesn't always give
7050 better results.
7051
7052 fast Internal method that only checks for simple changes:
7053 character inserts/deletes/swaps. Works well for
7054 simple typing mistakes.
7055
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00007056 {number} The maximum number of suggestions listed for |z=|.
Bram Moolenaar8aff23a2005-08-19 20:40:30 +00007057 Not used for |spellsuggest()|. The number of
7058 suggestions is never more than the value of 'lines'
7059 minus two.
7060
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00007061 file:{filename} Read file {filename}, which must have two columns,
7062 separated by a slash. The first column contains the
7063 bad word, the second column the suggested good word.
7064 Example:
7065 theribal/terrible ~
7066 Use this for common mistakes that do not appear at the
7067 top of the suggestion list with the internal methods.
7068 Lines without a slash are ignored, use this for
7069 comments.
Bram Moolenaarbcb98982014-05-01 14:08:19 +02007070 The word in the second column must be correct,
7071 otherwise it will not be used. Add the word to an
7072 ".add" file if it is currently flagged as a spelling
7073 mistake.
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00007074 The file is used for all languages.
7075
7076 expr:{expr} Evaluate expression {expr}. Use a function to avoid
7077 trouble with spaces. |v:val| holds the badly spelled
7078 word. The expression must evaluate to a List of
7079 Lists, each with a suggestion and a score.
7080 Example:
Bram Moolenaar214641f2017-03-05 17:04:09 +01007081 [['the', 33], ['that', 44]] ~
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00007082 Set 'verbose' and use |z=| to see the scores that the
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00007083 internal methods use. A lower score is better.
7084 This may invoke |spellsuggest()| if you temporarily
7085 set 'spellsuggest' to exclude the "expr:" part.
7086 Errors are silently ignored, unless you set the
7087 'verbose' option to a non-zero value.
7088
7089 Only one of "best", "double" or "fast" may be used. The others may
7090 appear several times in any order. Example: >
7091 :set sps=file:~/.vim/sugg,best,expr:MySuggest()
7092<
7093 This option cannot be set from a |modeline| or in the |sandbox|, for
7094 security reasons.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00007095
7096
Bram Moolenaar071d4272004-06-13 20:20:40 +00007097 *'splitbelow'* *'sb'* *'nosplitbelow'* *'nosb'*
7098'splitbelow' 'sb' boolean (default off)
7099 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007100 When on, splitting a window will put the new window below the current
7101 one. |:split|
7102
7103 *'splitright'* *'spr'* *'nosplitright'* *'nospr'*
7104'splitright' 'spr' boolean (default off)
7105 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007106 When on, splitting a window will put the new window right of the
7107 current one. |:vsplit|
7108
7109 *'startofline'* *'sol'* *'nostartofline'* *'nosol'*
7110'startofline' 'sol' boolean (default on)
7111 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007112 When "on" the commands listed below move the cursor to the first
Bram Moolenaar843ee412004-06-30 16:16:41 +00007113 non-blank of the line. When off the cursor is kept in the same column
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007114 (if possible). This applies to the commands: CTRL-D, CTRL-U, CTRL-B,
Bram Moolenaar843ee412004-06-30 16:16:41 +00007115 CTRL-F, "G", "H", "M", "L", gg, and to the commands "d", "<<" and ">>"
Bram Moolenaar071d4272004-06-13 20:20:40 +00007116 with a linewise operator, with "%" with a count and to buffer changing
7117 commands (CTRL-^, :bnext, :bNext, etc.). Also for an Ex command that
7118 only has a line number, e.g., ":25" or ":+".
7119 In case of buffer changing commands the cursor is placed at the column
7120 where it was the last time the buffer was edited.
7121 NOTE: This option is set when 'compatible' is set.
7122
Bram Moolenaar00654022011-02-25 14:42:19 +01007123 *'statusline'* *'stl'* *E540* *E542*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007124'statusline' 'stl' string (default empty)
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00007125 global or local to window |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00007126 {not available when compiled without the |+statusline|
7127 feature}
7128 When nonempty, this option determines the content of the status line.
7129 Also see |status-line|.
7130
7131 The option consists of printf style '%' items interspersed with
7132 normal text. Each status line item is of the form:
7133 %-0{minwid}.{maxwid}{item}
Bram Moolenaar5e9b2fa2016-02-01 22:37:05 +01007134 All fields except the {item} are optional. A single percent sign can
Bram Moolenaar00654022011-02-25 14:42:19 +01007135 be given as "%%". Up to 80 items can be specified. *E541*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007136
Bram Moolenaar238a5642006-02-21 22:12:05 +00007137 When the option starts with "%!" then it is used as an expression,
7138 evaluated and the result is used as the option value. Example: >
7139 :set statusline=%!MyStatusLine()
Bram Moolenaar1c6fd1e2019-05-23 22:11:59 +02007140< The *g:statusline_winid* variable will be set to the |window-ID| of the
7141 window that the status line belongs to.
7142 The result can contain %{} items that will be evaluated too.
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02007143 Note that the "%!" expression is evaluated in the context of the
7144 current window and buffer, while %{} items are evaluated in the
7145 context of the window that the statusline belongs to.
Bram Moolenaar238a5642006-02-21 22:12:05 +00007146
7147 When there is error while evaluating the option then it will be made
7148 empty to avoid further errors. Otherwise screen updating would loop.
7149
Bram Moolenaar071d4272004-06-13 20:20:40 +00007150 Note that the only effect of 'ruler' when this option is set (and
7151 'laststatus' is 2) is controlling the output of |CTRL-G|.
7152
7153 field meaning ~
Bram Moolenaar582fd852005-03-28 20:58:01 +00007154 - Left justify the item. The default is right justified
Bram Moolenaar071d4272004-06-13 20:20:40 +00007155 when minwid is larger than the length of the item.
Bram Moolenaar582fd852005-03-28 20:58:01 +00007156 0 Leading zeroes in numeric items. Overridden by '-'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007157 minwid Minimum width of the item, padding as set by '-' & '0'.
7158 Value must be 50 or less.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007159 maxwid Maximum width of the item. Truncation occurs with a '<'
Bram Moolenaar071d4272004-06-13 20:20:40 +00007160 on the left for text items. Numeric items will be
7161 shifted down to maxwid-2 digits followed by '>'number
7162 where number is the amount of missing digits, much like
7163 an exponential notation.
7164 item A one letter code as described below.
7165
7166 Following is a description of the possible statusline items. The
7167 second character in "item" is the type:
7168 N for number
7169 S for string
7170 F for flags as described below
7171 - not applicable
7172
7173 item meaning ~
Bram Moolenaar02467872007-05-06 13:22:01 +00007174 f S Path to the file in the buffer, as typed or relative to current
7175 directory.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007176 F S Full path to the file in the buffer.
7177 t S File name (tail) of file in the buffer.
Bram Moolenaare37d50a2008-08-06 17:06:04 +00007178 m F Modified flag, text is "[+]"; "[-]" if 'modifiable' is off.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007179 M F Modified flag, text is ",+" or ",-".
Bram Moolenaare37d50a2008-08-06 17:06:04 +00007180 r F Readonly flag, text is "[RO]".
Bram Moolenaar071d4272004-06-13 20:20:40 +00007181 R F Readonly flag, text is ",RO".
Bram Moolenaare37d50a2008-08-06 17:06:04 +00007182 h F Help buffer flag, text is "[help]".
Bram Moolenaar071d4272004-06-13 20:20:40 +00007183 H F Help buffer flag, text is ",HLP".
Bram Moolenaare37d50a2008-08-06 17:06:04 +00007184 w F Preview window flag, text is "[Preview]".
Bram Moolenaar071d4272004-06-13 20:20:40 +00007185 W F Preview window flag, text is ",PRV".
Bram Moolenaare37d50a2008-08-06 17:06:04 +00007186 y F Type of file in the buffer, e.g., "[vim]". See 'filetype'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007187 Y F Type of file in the buffer, e.g., ",VIM". See 'filetype'.
Bram Moolenaar7fd73202010-07-25 16:58:46 +02007188 q S "[Quickfix List]", "[Location List]" or empty.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007189 k S Value of "b:keymap_name" or 'keymap' when |:lmap| mappings are
7190 being used: "<keymap>"
7191 n N Buffer number.
Bram Moolenaar00654022011-02-25 14:42:19 +01007192 b N Value of character under cursor.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007193 B N As above, in hexadecimal.
7194 o N Byte number in file of byte under cursor, first byte is 1.
7195 Mnemonic: Offset from start of file (with one added)
7196 {not available when compiled without |+byte_offset| feature}
7197 O N As above, in hexadecimal.
Bram Moolenaar582fd852005-03-28 20:58:01 +00007198 N N Printer page number. (Only works in the 'printheader' option.)
Bram Moolenaar071d4272004-06-13 20:20:40 +00007199 l N Line number.
7200 L N Number of lines in buffer.
7201 c N Column number.
7202 v N Virtual column number.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007203 V N Virtual column number as -{num}. Not displayed if equal to 'c'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007204 p N Percentage through file in lines as in |CTRL-G|.
7205 P S Percentage through file of displayed window. This is like the
Bram Moolenaar14b69452013-06-29 23:05:20 +02007206 percentage described for 'ruler'. Always 3 in length, unless
7207 translated.
Bram Moolenaar582fd852005-03-28 20:58:01 +00007208 a S Argument list status as in default title. ({current} of {max})
Bram Moolenaar071d4272004-06-13 20:20:40 +00007209 Empty if the argument file count is zero or one.
Bram Moolenaar238a5642006-02-21 22:12:05 +00007210 { NF Evaluate expression between '%{' and '}' and substitute result.
Bram Moolenaar6d150f72018-04-21 20:03:20 +02007211 Note that there is no '%' before the closing '}'. The
7212 expression cannot contain a '}' character, call a function to
7213 work around that.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007214 ( - Start of item group. Can be used for setting the width and
7215 alignment of a section. Must be followed by %) somewhere.
7216 ) - End of item group. No width fields allowed.
Bram Moolenaard1f56e62006-02-22 21:25:37 +00007217 T N For 'tabline': start of tab page N label. Use %T after the last
7218 label. This information is used for mouse clicks.
7219 X N For 'tabline': start of close tab N label. Use %X after the
7220 label, e.g.: %3Xclose%X. Use %999X for a "close current tab"
7221 mark. This information is used for mouse clicks.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007222 < - Where to truncate line if too long. Default is at the start.
7223 No width fields allowed.
7224 = - Separation point between left and right aligned items.
7225 No width fields allowed.
Bram Moolenaar238a5642006-02-21 22:12:05 +00007226 # - Set highlight group. The name must follow and then a # again.
7227 Thus use %#HLname# for highlight group HLname. The same
7228 highlighting is used, also for the statusline of non-current
7229 windows.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007230 * - Set highlight group to User{N}, where {N} is taken from the
Bram Moolenaar582fd852005-03-28 20:58:01 +00007231 minwid field, e.g. %1*. Restore normal highlight with %* or %0*.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007232 The difference between User{N} and StatusLine will be applied
7233 to StatusLineNC for the statusline of non-current windows.
7234 The number N must be between 1 and 9. See |hl-User1..9|
7235
Bram Moolenaare37d50a2008-08-06 17:06:04 +00007236 When displaying a flag, Vim removes the leading comma, if any, when
7237 that flag comes right after plaintext. This will make a nice display
7238 when flags are used like in the examples below.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007239
Bram Moolenaar582fd852005-03-28 20:58:01 +00007240 When all items in a group becomes an empty string (i.e. flags that are
Bram Moolenaar071d4272004-06-13 20:20:40 +00007241 not set) and a minwid is not set for the group, the whole group will
7242 become empty. This will make a group like the following disappear
7243 completely from the statusline when none of the flags are set. >
7244 :set statusline=...%(\ [%M%R%H]%)...
Bram Moolenaar1c6fd1e2019-05-23 22:11:59 +02007245< Beware that an expression is evaluated each and every time the status
7246 line is displayed.
7247 *g:actual_curbuf* *g:actual_curwin*
7248 The current buffer and current window will be set temporarily to that
7249 of the window (and buffer) whose statusline is currently being drawn.
7250 The expression will evaluate in this context. The variable
7251 "g:actual_curbuf" is set to the `bufnr()` number of the real current
7252 buffer and "g:actual_curwin" to the |window-ID| of the real current
7253 window. These values are strings.
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00007254
Bram Moolenaar30b65812012-07-12 22:01:11 +02007255 The 'statusline' option will be evaluated in the |sandbox| if set from
7256 a modeline, see |sandbox-option|.
Bram Moolenaar110289e2019-05-23 15:38:06 +02007257 This option cannot be set in a modeline when 'modelineexpr' is off.
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00007258
7259 It is not allowed to change text or jump to another window while
7260 evaluating 'statusline' |textlock|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007261
7262 If the statusline is not updated when you want it (e.g., after setting
7263 a variable that's used in an expression), you can force an update by
7264 setting an option without changing its value. Example: >
7265 :let &ro = &ro
7266
7267< A result of all digits is regarded a number for display purposes.
7268 Otherwise the result is taken as flag text and applied to the rules
7269 described above.
7270
Bram Moolenaarcd71fa32005-03-11 22:46:48 +00007271 Watch out for errors in expressions. They may render Vim unusable!
Bram Moolenaar071d4272004-06-13 20:20:40 +00007272 If you are stuck, hold down ':' or 'Q' to get a prompt, then quit and
Bram Moolenaarc4da1132017-07-15 19:39:43 +02007273 edit your .vimrc or whatever with "vim --clean" to get it right.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007274
7275 Examples:
7276 Emulate standard status line with 'ruler' set >
7277 :set statusline=%<%f\ %h%m%r%=%-14.(%l,%c%V%)\ %P
7278< Similar, but add ASCII value of char under the cursor (like "ga") >
7279 :set statusline=%<%f%h%m%r%=%b\ 0x%B\ \ %l,%c%V\ %P
7280< Display byte count and byte value, modified flag in red. >
7281 :set statusline=%<%f%=\ [%1*%M%*%n%R%H]\ %-19(%3l,%02c%03V%)%O'%02b'
7282 :hi User1 term=inverse,bold cterm=inverse,bold ctermfg=red
7283< Display a ,GZ flag if a compressed file is loaded >
7284 :set statusline=...%r%{VarExists('b:gzflag','\ [GZ]')}%h...
7285< In the |:autocmd|'s: >
7286 :let b:gzflag = 1
7287< And: >
7288 :unlet b:gzflag
7289< And define this function: >
7290 :function VarExists(var, val)
7291 : if exists(a:var) | return a:val | else | return '' | endif
7292 :endfunction
7293<
7294 *'suffixes'* *'su'*
7295'suffixes' 'su' string (default ".bak,~,.o,.h,.info,.swp,.obj")
7296 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007297 Files with these suffixes get a lower priority when multiple files
7298 match a wildcard. See |suffixes|. Commas can be used to separate the
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007299 suffixes. Spaces after the comma are ignored. A dot is also seen as
7300 the start of a suffix. To avoid a dot or comma being recognized as a
Bram Moolenaar071d4272004-06-13 20:20:40 +00007301 separator, precede it with a backslash (see |option-backslash| about
7302 including spaces and backslashes).
7303 See 'wildignore' for completely ignoring files.
7304 The use of |:set+=| and |:set-=| is preferred when adding or removing
7305 suffixes from the list. This avoids problems when a future version
7306 uses another default.
7307
7308 *'suffixesadd'* *'sua'*
7309'suffixesadd' 'sua' string (default "")
7310 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00007311 {not available when compiled without the
7312 |+file_in_path| feature}
7313 Comma separated list of suffixes, which are used when searching for a
7314 file for the "gf", "[I", etc. commands. Example: >
7315 :set suffixesadd=.java
7316<
7317 *'swapfile'* *'swf'* *'noswapfile'* *'noswf'*
7318'swapfile' 'swf' boolean (default on)
7319 local to buffer
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007320 Use a swapfile for the buffer. This option can be reset when a
Bram Moolenaar071d4272004-06-13 20:20:40 +00007321 swapfile is not wanted for a specific buffer. For example, with
7322 confidential information that even root must not be able to access.
7323 Careful: All text will be in memory:
7324 - Don't use this for big files.
7325 - Recovery will be impossible!
7326 A swapfile will only be present when |'updatecount'| is non-zero and
7327 'swapfile' is set.
7328 When 'swapfile' is reset, the swap file for the current buffer is
7329 immediately deleted. When 'swapfile' is set, and 'updatecount' is
7330 non-zero, a swap file is immediately created.
7331 Also see |swap-file| and |'swapsync'|.
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +01007332 If you want to open a new buffer without creating a swap file for it,
7333 use the |:noswapfile| modifier.
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01007334 See 'directory' for where the swap file is created.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007335
7336 This option is used together with 'bufhidden' and 'buftype' to
7337 specify special kinds of buffers. See |special-buffers|.
7338
7339 *'swapsync'* *'sws'*
7340'swapsync' 'sws' string (default "fsync")
7341 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007342 When this option is not empty a swap file is synced to disk after
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007343 writing to it. This takes some time, especially on busy unix systems.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007344 When this option is empty parts of the swap file may be in memory and
7345 not written to disk. When the system crashes you may lose more work.
7346 On Unix the system does a sync now and then without Vim asking for it,
7347 so the disadvantage of setting this option off is small. On some
7348 systems the swap file will not be written at all. For a unix system
7349 setting it to "sync" will use the sync() call instead of the default
7350 fsync(), which may work better on some systems.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00007351 The 'fsync' option is used for the actual file.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007352
7353 *'switchbuf'* *'swb'*
7354'switchbuf' 'swb' string (default "")
7355 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007356 This option controls the behavior when switching between buffers.
7357 Possible values (comma separated list):
7358 useopen If included, jump to the first open window that
7359 contains the specified buffer (if there is one).
7360 Otherwise: Do not examine other windows.
7361 This setting is checked with |quickfix| commands, when
7362 jumping to errors (":cc", ":cn", "cp", etc.). It is
7363 also used in all buffer related split commands, for
7364 example ":sbuffer", ":sbnext", or ":sbrewind".
Bram Moolenaar779b74b2006-04-10 14:55:34 +00007365 usetab Like "useopen", but also consider windows in other tab
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00007366 pages.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007367 split If included, split the current window before loading
Bram Moolenaar15146672011-10-20 22:22:38 +02007368 a buffer for a |quickfix| command that display errors.
Bram Moolenaar63b74a82019-03-24 15:09:13 +01007369 Otherwise: do not split, use current window (when used
7370 in the quickfix window: the previously used window or
7371 split if there is no other window).
Bram Moolenaara594d772015-06-19 14:41:49 +02007372 vsplit Just like "split" but split vertically.
Bram Moolenaar446cb832008-06-24 21:56:24 +00007373 newtab Like "split", but open a new tab page. Overrules
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02007374 "split" when both are present.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007375
Bram Moolenaar3b56eb32005-07-11 22:40:32 +00007376 *'synmaxcol'* *'smc'*
7377'synmaxcol' 'smc' number (default 3000)
7378 local to buffer
Bram Moolenaar3b56eb32005-07-11 22:40:32 +00007379 {not available when compiled without the |+syntax|
7380 feature}
Bram Moolenaarce0842a2005-07-18 21:58:11 +00007381 Maximum column in which to search for syntax items. In long lines the
7382 text after this column is not highlighted and following lines may not
7383 be highlighted correctly, because the syntax state is cleared.
Bram Moolenaar3b56eb32005-07-11 22:40:32 +00007384 This helps to avoid very slow redrawing for an XML file that is one
7385 long line.
7386 Set to zero to remove the limit.
7387
Bram Moolenaar071d4272004-06-13 20:20:40 +00007388 *'syntax'* *'syn'*
7389'syntax' 'syn' string (default empty)
7390 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00007391 {not available when compiled without the |+syntax|
7392 feature}
7393 When this option is set, the syntax with this name is loaded, unless
7394 syntax highlighting has been switched off with ":syntax off".
7395 Otherwise this option does not always reflect the current syntax (the
7396 b:current_syntax variable does).
7397 This option is most useful in a modeline, for a file which syntax is
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00007398 not automatically recognized. Example, in an IDL file:
7399 /* vim: set syntax=idl : */ ~
7400 When a dot appears in the value then this separates two filetype
7401 names. Example:
7402 /* vim: set syntax=c.doxygen : */ ~
7403 This will use the "c" syntax first, then the "doxygen" syntax.
7404 Note that the second one must be prepared to be loaded as an addition,
7405 otherwise it will be skipped. More than one dot may appear.
7406 To switch off syntax highlighting for the current file, use: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00007407 :set syntax=OFF
7408< To switch syntax highlighting on according to the current value of the
7409 'filetype' option: >
7410 :set syntax=ON
7411< What actually happens when setting the 'syntax' option is that the
7412 Syntax autocommand event is triggered with the value as argument.
7413 This option is not copied to another buffer, independent of the 's' or
7414 'S' flag in 'cpoptions'.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00007415 Only normal file name characters can be used, "/\*?[|<>" are illegal.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007416
Bram Moolenaarfd2ac762006-03-01 22:09:21 +00007417 *'tabline'* *'tal'*
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00007418'tabline' 'tal' string (default empty)
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00007419 global
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00007420 When nonempty, this option determines the content of the tab pages
7421 line at the top of the Vim window. When empty Vim will use a default
Bram Moolenaard1f56e62006-02-22 21:25:37 +00007422 tab pages line. See |setting-tabline| for more info.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00007423
7424 The tab pages line only appears as specified with the 'showtabline'
Bram Moolenaar5c8837f2006-02-25 21:52:33 +00007425 option and only when there is no GUI tab line. When 'e' is in
7426 'guioptions' and the GUI supports a tab line 'guitablabel' is used
Bram Moolenaar7f036442010-08-15 15:24:20 +02007427 instead. Note that the two tab pages lines are very different.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00007428
7429 The value is evaluated like with 'statusline'. You can use
7430 |tabpagenr()|, |tabpagewinnr()| and |tabpagebuflist()| to figure out
Bram Moolenaard1f56e62006-02-22 21:25:37 +00007431 the text to be displayed. Use "%1T" for the first label, "%2T" for
7432 the second one, etc. Use "%X" items for closing labels.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00007433
Bram Moolenaare12bab32019-01-08 22:02:56 +01007434 When changing something that is used in 'tabline' that does not
7435 trigger it to be updated, use |:redrawtabline|.
Bram Moolenaar110289e2019-05-23 15:38:06 +02007436 This option cannot be set in a modeline when 'modelineexpr' is off.
Bram Moolenaare12bab32019-01-08 22:02:56 +01007437
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00007438 Keep in mind that only one of the tab pages is the current one, others
7439 are invisible and you can't jump to their windows.
7440
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00007441
Bram Moolenaarfd2ac762006-03-01 22:09:21 +00007442 *'tabpagemax'* *'tpm'*
7443'tabpagemax' 'tpm' number (default 10)
7444 global
Bram Moolenaarfd2ac762006-03-01 22:09:21 +00007445 Maximum number of tab pages to be opened by the |-p| command line
7446 argument or the ":tab all" command. |tabpage|
7447
7448
7449 *'tabstop'* *'ts'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007450'tabstop' 'ts' number (default 8)
7451 local to buffer
7452 Number of spaces that a <Tab> in the file counts for. Also see
7453 |:retab| command, and 'softtabstop' option.
7454
7455 Note: Setting 'tabstop' to any other value than 8 can make your file
7456 appear wrong in many places (e.g., when printing it).
7457
7458 There are four main ways to use tabs in Vim:
7459 1. Always keep 'tabstop' at 8, set 'softtabstop' and 'shiftwidth' to 4
7460 (or 3 or whatever you prefer) and use 'noexpandtab'. Then Vim
Bram Moolenaarebcbd022007-05-12 14:28:25 +00007461 will use a mix of tabs and spaces, but typing <Tab> and <BS> will
Bram Moolenaar071d4272004-06-13 20:20:40 +00007462 behave like a tab appears every 4 (or 3) characters.
7463 2. Set 'tabstop' and 'shiftwidth' to whatever you prefer and use
7464 'expandtab'. This way you will always insert spaces. The
7465 formatting will never be messed up when 'tabstop' is changed.
7466 3. Set 'tabstop' and 'shiftwidth' to whatever you prefer and use a
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007467 |modeline| to set these values when editing the file again. Only
Bram Moolenaar071d4272004-06-13 20:20:40 +00007468 works when using Vim to edit the file.
7469 4. Always set 'tabstop' and 'shiftwidth' to the same value, and
7470 'noexpandtab'. This should then work (for initial indents only)
7471 for any tabstop setting that people use. It might be nice to have
7472 tabs after the first non-blank inserted as spaces if you do this
7473 though. Otherwise aligned comments will be wrong when 'tabstop' is
7474 changed.
7475
Bram Moolenaar04958cb2018-06-23 19:23:02 +02007476 If Vim is compiled with the |+vartabs| feature then the value of
7477 'tabstop' will be ignored if |'vartabstop'| is set to anything other
7478 than an empty string.
7479
Bram Moolenaar071d4272004-06-13 20:20:40 +00007480 *'tagbsearch'* *'tbs'* *'notagbsearch'* *'notbs'*
7481'tagbsearch' 'tbs' boolean (default on)
7482 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007483 When searching for a tag (e.g., for the |:ta| command), Vim can either
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007484 use a binary search or a linear search in a tags file. Binary
Bram Moolenaar071d4272004-06-13 20:20:40 +00007485 searching makes searching for a tag a LOT faster, but a linear search
7486 will find more tags if the tags file wasn't properly sorted.
7487 Vim normally assumes that your tags files are sorted, or indicate that
7488 they are not sorted. Only when this is not the case does the
7489 'tagbsearch' option need to be switched off.
7490
7491 When 'tagbsearch' is on, binary searching is first used in the tags
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007492 files. In certain situations, Vim will do a linear search instead for
Bram Moolenaar071d4272004-06-13 20:20:40 +00007493 certain files, or retry all files with a linear search. When
7494 'tagbsearch' is off, only a linear search is done.
7495
7496 Linear searching is done anyway, for one file, when Vim finds a line
7497 at the start of the file indicating that it's not sorted: >
Bram Moolenaar446cb832008-06-24 21:56:24 +00007498 !_TAG_FILE_SORTED 0 /some comment/
Bram Moolenaar071d4272004-06-13 20:20:40 +00007499< [The whitespace before and after the '0' must be a single <Tab>]
7500
7501 When a binary search was done and no match was found in any of the
Bram Moolenaar0f6562e2015-11-24 18:48:14 +01007502 files listed in 'tags', and case is ignored or a pattern is used
Bram Moolenaar071d4272004-06-13 20:20:40 +00007503 instead of a normal tag name, a retry is done with a linear search.
7504 Tags in unsorted tags files, and matches with different case will only
7505 be found in the retry.
7506
Bram Moolenaard4755bb2004-09-02 19:12:26 +00007507 If a tag file indicates that it is case-fold sorted, the second,
Bram Moolenaar0f6562e2015-11-24 18:48:14 +01007508 linear search can be avoided when case is ignored. Use a value of '2'
7509 in the "!_TAG_FILE_SORTED" line for this. A tag file can be case-fold
7510 sorted with the -f switch to "sort" in most unices, as in the command:
7511 "sort -f -o tags tags". For "Exuberant ctags" version 5.x or higher
7512 (at least 5.5) the --sort=foldcase switch can be used for this as
7513 well. Note that case must be folded to uppercase for this to work.
7514
7515 By default, tag searches are case-sensitive. Case is ignored when
7516 'ignorecase' is set and 'tagcase' is "followic", or when 'tagcase' is
7517 "ignore".
Bram Moolenaar66e29d72016-08-20 16:57:02 +02007518 Also when 'tagcase' is "followscs" and 'smartcase' is set, or
7519 'tagcase' is "smart", and the pattern contains only lowercase
7520 characters.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007521
7522 When 'tagbsearch' is off, tags searching is slower when a full match
7523 exists, but faster when no full match exists. Tags in unsorted tags
7524 files may only be found with 'tagbsearch' off.
7525 When the tags file is not sorted, or sorted in a wrong way (not on
7526 ASCII byte value), 'tagbsearch' should be off, or the line given above
7527 must be included in the tags file.
7528 This option doesn't affect commands that find all matching tags (e.g.,
7529 command-line completion and ":help").
Bram Moolenaar071d4272004-06-13 20:20:40 +00007530
Bram Moolenaar0f6562e2015-11-24 18:48:14 +01007531 *'tagcase'* *'tc'*
7532'tagcase' 'tc' string (default "followic")
7533 global or local to buffer |global-local|
Bram Moolenaar0f6562e2015-11-24 18:48:14 +01007534 This option specifies how case is handled when searching the tags
7535 file:
7536 followic Follow the 'ignorecase' option
Bram Moolenaar66e29d72016-08-20 16:57:02 +02007537 followscs Follow the 'smartcase' and 'ignorecase' options
Bram Moolenaar0f6562e2015-11-24 18:48:14 +01007538 ignore Ignore case
7539 match Match case
Bram Moolenaar66e29d72016-08-20 16:57:02 +02007540 smart Ignore case unless an upper case letter is used
Bram Moolenaar036986f2017-03-16 17:41:02 +01007541 NOTE: This option is set to the Vi default value when 'compatible' is
7542 set and to the Vim default value when 'compatible' is reset.
Bram Moolenaar0f6562e2015-11-24 18:48:14 +01007543
Bram Moolenaar45e18cb2019-04-28 18:05:35 +02007544 *'tagfunc'* *'tfu'*
7545'tagfunc' 'tfu' string (default: empty)
7546 local to buffer
7547 {not available when compiled without the |+eval|
7548 feature}
7549 This option specifies a function to be used to perform tag searches.
7550 The function gets the tag pattern and should return a List of matching
7551 tags. See |tag-function| for an explanation of how to write the
7552 function and an example.
7553
Bram Moolenaar071d4272004-06-13 20:20:40 +00007554 *'taglength'* *'tl'*
7555'taglength' 'tl' number (default 0)
7556 global
7557 If non-zero, tags are significant up to this number of characters.
7558
7559 *'tagrelative'* *'tr'* *'notagrelative'* *'notr'*
7560'tagrelative' 'tr' boolean (Vim default: on, Vi default: off)
7561 global
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00007562 If on and using a tags file in another directory, file names in that
7563 tags file are relative to the directory where the tags file is.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007564 NOTE: This option is set to the Vi default value when 'compatible' is
7565 set and to the Vim default value when 'compatible' is reset.
7566
7567 *'tags'* *'tag'* *E433*
7568'tags' 'tag' string (default "./tags,tags", when compiled with
7569 |+emacs_tags|: "./tags,./TAGS,tags,TAGS")
7570 global or local to buffer |global-local|
7571 Filenames for the tag command, separated by spaces or commas. To
7572 include a space or comma in a file name, precede it with a backslash
7573 (see |option-backslash| about including spaces and backslashes).
7574 When a file name starts with "./", the '.' is replaced with the path
7575 of the current file. But only when the 'd' flag is not included in
7576 'cpoptions'. Environment variables are expanded |:set_env|. Also see
7577 |tags-option|.
7578 "*", "**" and other wildcards can be used to search for tags files in
Bram Moolenaare2b590e2010-08-08 18:29:48 +02007579 a directory tree. See |file-searching|. E.g., "/lib/**/tags" will
7580 find all files named "tags" below "/lib". The filename itself cannot
7581 contain wildcards, it is used as-is. E.g., "/lib/**/tags?" will find
7582 files called "tags?". {not available when compiled without the
7583 |+path_extra| feature}
Bram Moolenaare7eb9df2005-09-09 19:49:30 +00007584 The |tagfiles()| function can be used to get a list of the file names
7585 actually used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007586 If Vim was compiled with the |+emacs_tags| feature, Emacs-style tag
7587 files are also supported. They are automatically recognized. The
7588 default value becomes "./tags,./TAGS,tags,TAGS", unless case
7589 differences are ignored (MS-Windows). |emacs-tags|
7590 The use of |:set+=| and |:set-=| is preferred when adding or removing
7591 file names from the list. This avoids problems when a future version
7592 uses another default.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007593
7594 *'tagstack'* *'tgst'* *'notagstack'* *'notgst'*
7595'tagstack' 'tgst' boolean (default on)
7596 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007597 When on, the |tagstack| is used normally. When off, a ":tag" or
7598 ":tselect" command with an argument will not push the tag onto the
7599 tagstack. A following ":tag" without an argument, a ":pop" command or
7600 any other command that uses the tagstack will use the unmodified
7601 tagstack, but does change the pointer to the active entry.
7602 Resetting this option is useful when using a ":tag" command in a
7603 mapping which should not change the tagstack.
7604
Bram Moolenaar8a5115c2016-01-09 19:41:11 +01007605 *'tcldll'*
Bram Moolenaar3848e002016-03-19 18:42:29 +01007606'tcldll' string (default depends on the build)
Bram Moolenaar8a5115c2016-01-09 19:41:11 +01007607 global
Bram Moolenaar8a5115c2016-01-09 19:41:11 +01007608 {only available when compiled with the |+tcl/dyn|
7609 feature}
7610 Specifies the name of the Tcl shared library. The default is
7611 DYNAMIC_TCL_DLL, which was specified at compile time.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02007612 Environment variables are expanded |:set_env|.
Bram Moolenaar8a5115c2016-01-09 19:41:11 +01007613 This option cannot be set from a |modeline| or in the |sandbox|, for
7614 security reasons.
7615
Bram Moolenaar071d4272004-06-13 20:20:40 +00007616 *'term'* *E529* *E530* *E531*
7617'term' string (default is $TERM, if that fails:
7618 in the GUI: "builtin_gui"
7619 on Amiga: "amiga"
7620 on BeOS: "beos-ansi"
7621 on Mac: "mac-ansi"
7622 on MiNT: "vt52"
7623 on MS-DOS: "pcterm"
7624 on OS/2: "os2ansi"
7625 on Unix: "ansi"
7626 on VMS: "ansi"
7627 on Win 32: "win32")
7628 global
7629 Name of the terminal. Used for choosing the terminal control
7630 characters. Environment variables are expanded |:set_env|.
7631 For example: >
7632 :set term=$TERM
7633< See |termcap|.
7634
7635 *'termbidi'* *'tbidi'*
7636 *'notermbidi'* *'notbidi'*
7637'termbidi' 'tbidi' boolean (default off, on for "mlterm")
7638 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007639 {only available when compiled with the |+arabic|
7640 feature}
7641 The terminal is in charge of Bi-directionality of text (as specified
7642 by Unicode). The terminal is also expected to do the required shaping
7643 that some languages (such as Arabic) require.
7644 Setting this option implies that 'rightleft' will not be set when
7645 'arabic' is set and the value of 'arabicshape' will be ignored.
7646 Note that setting 'termbidi' has the immediate effect that
7647 'arabicshape' is ignored, but 'rightleft' isn't changed automatically.
7648 This option is reset when the GUI is started.
7649 For further details see |arabic.txt|.
7650
7651 *'termencoding'* *'tenc'*
Bram Moolenaar3df01732017-02-17 22:47:16 +01007652'termencoding' 'tenc' string (default ""; with GTK+ GUI: "utf-8"; with
Bram Moolenaar071d4272004-06-13 20:20:40 +00007653 Macintosh GUI: "macroman")
7654 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007655 Encoding used for the terminal. This specifies what character
7656 encoding the keyboard produces and the display will understand. For
Bram Moolenaar3848e002016-03-19 18:42:29 +01007657 the GUI it only applies to the keyboard ('encoding' is used for the
Bram Moolenaar02467872007-05-06 13:22:01 +00007658 display). Except for the Mac when 'macatsui' is off, then
7659 'termencoding' should be "macroman".
Bram Moolenaar071d4272004-06-13 20:20:40 +00007660 *E617*
Bram Moolenaar3df01732017-02-17 22:47:16 +01007661 Note: This does not apply to the GTK+ GUI. After the GUI has been
Bram Moolenaar071d4272004-06-13 20:20:40 +00007662 successfully initialized, 'termencoding' is forcibly set to "utf-8".
7663 Any attempts to set a different value will be rejected, and an error
7664 message is shown.
Bram Moolenaarac360bf2015-09-01 20:31:20 +02007665 For the Win32 GUI and console versions 'termencoding' is not used,
Bram Moolenaar071d4272004-06-13 20:20:40 +00007666 because the Win32 system always passes Unicode characters.
7667 When empty, the same encoding is used as for the 'encoding' option.
7668 This is the normal value.
7669 Not all combinations for 'termencoding' and 'encoding' are valid. See
7670 |encoding-table|.
7671 The value for this option must be supported by internal conversions or
7672 iconv(). When this is not possible no conversion will be done and you
7673 will probably experience problems with non-ASCII characters.
7674 Example: You are working with the locale set to euc-jp (Japanese) and
7675 want to edit a UTF-8 file: >
7676 :let &termencoding = &encoding
7677 :set encoding=utf-8
7678< You need to do this when your system has no locale support for UTF-8.
7679
Bram Moolenaarcafafb32018-02-22 21:07:09 +01007680 *'termguicolors'* *'tgc'* *E954*
Bram Moolenaar61be73b2016-04-29 22:59:22 +02007681'termguicolors' 'tgc' boolean (default off)
7682 global
Bram Moolenaar61be73b2016-04-29 22:59:22 +02007683 {not available when compiled without the
7684 |+termguicolors| feature}
7685 When on, uses |highlight-guifg| and |highlight-guibg| attributes in
Bram Moolenaarcafafb32018-02-22 21:07:09 +01007686 the terminal (thus using 24-bit color).
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01007687
Bram Moolenaarcafafb32018-02-22 21:07:09 +01007688 Requires a ISO-8613-3 compatible terminal. If setting this option
7689 does not work (produces a colorless UI) reading |xterm-true-color|
7690 might help.
7691
7692 For Win32 console, Windows 10 version 1703 (Creators Update) or later
7693 is required. Use this check to find out: >
7694 if has('vcon')
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01007695< This requires Vim to be built with the |+vtp| feature.
7696
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +02007697 Note that the "cterm" attributes are still used, not the "gui" ones.
Bram Moolenaar036986f2017-03-16 17:41:02 +01007698 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaar61be73b2016-04-29 22:59:22 +02007699
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02007700 *'termwinkey'* *'twk'*
7701'termwinkey' 'twk' string (default "")
Bram Moolenaar74675a62017-07-15 13:53:23 +02007702 local to window
Bram Moolenaarf55e4c82017-08-01 20:44:53 +02007703 The key that starts a CTRL-W command in a terminal window. Other keys
Bram Moolenaar74675a62017-07-15 13:53:23 +02007704 are sent to the job running in the window.
Bram Moolenaarf55e4c82017-08-01 20:44:53 +02007705 The <> notation can be used, e.g.: >
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02007706 :set termwinkey=<C-L>
Bram Moolenaarf55e4c82017-08-01 20:44:53 +02007707< The string must be one key stroke but can be multiple bytes.
7708 When not set CTRL-W is used, so that CTRL-W : gets you to the command
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02007709 line. If 'termwinkey' is set to CTRL-L then CTRL-L : gets you to the
Bram Moolenaarf55e4c82017-08-01 20:44:53 +02007710 command line.
Bram Moolenaar74675a62017-07-15 13:53:23 +02007711
Bram Moolenaar6c60f472019-04-28 16:00:35 +02007712 *'termwinscroll'* *'twsl'*
7713'termwinscroll' 'twsl' number (default 10000)
7714 local to buffer
7715 {not available when compiled without the
7716 |+terminal| feature}
7717 Number of scrollback lines to keep. When going over this limit the
7718 first 10% of the scrollback lines are deleted. This is just to reduce
7719 the memory usage. See |Terminal-Normal|.
7720
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02007721 *'termwinsize'* *'tws'*
7722'termwinsize' 'tws' string (default "")
Bram Moolenaar74675a62017-07-15 13:53:23 +02007723 local to window
Bram Moolenaar498c2562018-04-15 23:45:15 +02007724 Size of the |terminal| window. Format: {rows}x{columns} or
7725 {rows}*{columns}.
Bram Moolenaar74675a62017-07-15 13:53:23 +02007726 - When empty the terminal gets the size from the window.
Bram Moolenaar498c2562018-04-15 23:45:15 +02007727 - When set with a "x" (e.g., "24x80") the terminal size is not
7728 adjusted to the window size. If the window is smaller only the
7729 top-left part is displayed.
7730 - When set with a "*" (e.g., "10*50") the terminal size follows the
7731 window size, but will not be smaller than the specified rows and/or
7732 columns.
7733 - When rows is zero then use the height of the window.
7734 - When columns is zero then use the width of the window.
7735 - Using "0x0" or "0*0" is the same as empty.
7736
7737 Examples:
7738 "30x0" uses 30 rows and the current window width.
7739 "20*0" uses at least 20 rows and the current window width.
7740 "0*40" uses the current window height and at least 40 columns.
Bram Moolenaar1f2903c2017-07-23 19:51:01 +02007741 Note that the command running in the terminal window may still change
7742 the size of the terminal. In that case the Vim window will be
7743 adjusted to that size, if possible.
Bram Moolenaar74675a62017-07-15 13:53:23 +02007744
Bram Moolenaarc6ddce32019-02-08 12:47:03 +01007745 *'termwintype'* *'twt'*
7746'termwintype' 'twt' string (default "")
7747 global
Bram Moolenaarc6ddce32019-02-08 12:47:03 +01007748 {only available when compiled with the |terminal|
7749 feature on MS-Windows}
7750 Specify the virtual console (pty) used when opening the terminal
7751 window.
7752
7753 Possible values are:
Bram Moolenaard9ef1b82019-02-13 19:23:10 +01007754 "" use ConPTY if it is stable, winpty otherwise
Bram Moolenaarc6ddce32019-02-08 12:47:03 +01007755 "winpty" use winpty, fail if not supported
7756 "conpty" use |ConPTY|, fail if not supported
7757
Bram Moolenaard9ef1b82019-02-13 19:23:10 +01007758 |ConPTY| support depends on the platform. Windows 10 October 2018
7759 Update is the first version that supports ConPTY, however it is still
7760 considered unstable. ConPTY might become stable in the next release
7761 of Windows 10. winpty support needs to be installed. If neither is
Bram Moolenaarc6ddce32019-02-08 12:47:03 +01007762 supported then you cannot open a terminal window.
7763
Bram Moolenaar071d4272004-06-13 20:20:40 +00007764 *'terse'* *'noterse'*
7765'terse' boolean (default off)
7766 global
7767 When set: Add 's' flag to 'shortmess' option (this makes the message
7768 for a search that hits the start or end of the file not being
7769 displayed). When reset: Remove 's' flag from 'shortmess' option. {Vi
7770 shortens a lot of messages}
7771
7772 *'textauto'* *'ta'* *'notextauto'* *'nota'*
7773'textauto' 'ta' boolean (Vim default: on, Vi default: off)
7774 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007775 This option is obsolete. Use 'fileformats'.
7776 For backwards compatibility, when 'textauto' is set, 'fileformats' is
7777 set to the default value for the current system. When 'textauto' is
7778 reset, 'fileformats' is made empty.
7779 NOTE: This option is set to the Vi default value when 'compatible' is
7780 set and to the Vim default value when 'compatible' is reset.
7781
7782 *'textmode'* *'tx'* *'notextmode'* *'notx'*
7783'textmode' 'tx' boolean (MS-DOS, Win32 and OS/2: default on,
7784 others: default off)
7785 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00007786 This option is obsolete. Use 'fileformat'.
7787 For backwards compatibility, when 'textmode' is set, 'fileformat' is
7788 set to "dos". When 'textmode' is reset, 'fileformat' is set to
7789 "unix".
7790
7791 *'textwidth'* *'tw'*
7792'textwidth' 'tw' number (default 0)
7793 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00007794 Maximum width of text that is being inserted. A longer line will be
7795 broken after white space to get this width. A zero value disables
Bram Moolenaarca635012015-09-25 20:34:21 +02007796 this.
7797 'textwidth' is set to 0 when the 'paste' option is set and restored
7798 when 'paste' is reset.
7799 When 'textwidth' is zero, 'wrapmargin' may be used. See also
Bram Moolenaar071d4272004-06-13 20:20:40 +00007800 'formatoptions' and |ins-textwidth|.
Bram Moolenaarfc1421e2006-04-20 22:17:20 +00007801 When 'formatexpr' is set it will be used to break the line.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007802 NOTE: This option is set to 0 when 'compatible' is set.
7803
7804 *'thesaurus'* *'tsr'*
7805'thesaurus' 'tsr' string (default "")
7806 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00007807 List of file names, separated by commas, that are used to lookup words
Bram Moolenaarf0d58ef2018-11-16 16:13:44 +01007808 for thesaurus completion commands |i_CTRL-X_CTRL-T|.
7809
7810 Each line in the file should contain words with similar meaning,
7811 separated by non-keyword characters (white space is preferred).
7812 Maximum line length is 510 bytes.
7813
Bram Moolenaard47d5222018-12-09 20:43:55 +01007814 An English word list was added to this github issue:
7815 https://github.com/vim/vim/issues/629#issuecomment-443293282
7816 Unpack thesaurus_pkg.zip, put the thesaurus.txt file somewhere, e.g.
7817 ~/.vim/thesaurus/english.txt, and the 'thesaurus' option to this file
7818 name.
Bram Moolenaarf0d58ef2018-11-16 16:13:44 +01007819
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007820 To include a comma in a file name precede it with a backslash. Spaces
Bram Moolenaar071d4272004-06-13 20:20:40 +00007821 after a comma are ignored, otherwise spaces are included in the file
7822 name. See |option-backslash| about using backslashes.
7823 The use of |:set+=| and |:set-=| is preferred when adding or removing
7824 directories from the list. This avoids problems when a future version
7825 uses another default.
7826 Backticks cannot be used in this option for security reasons.
7827
7828 *'tildeop'* *'top'* *'notildeop'* *'notop'*
7829'tildeop' 'top' boolean (default off)
7830 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007831 When on: The tilde command "~" behaves like an operator.
7832 NOTE: This option is reset when 'compatible' is set.
7833
7834 *'timeout'* *'to'* *'notimeout'* *'noto'*
7835'timeout' 'to' boolean (default on)
7836 global
7837 *'ttimeout'* *'nottimeout'*
Bram Moolenaar94237492017-04-23 18:40:21 +02007838'ttimeout' boolean (default off, set in |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00007839 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007840 These two options together determine the behavior when part of a
7841 mapped key sequence or keyboard code has been received:
7842
7843 'timeout' 'ttimeout' action ~
7844 off off do not time out
7845 on on or off time out on :mappings and key codes
7846 off on time out on key codes
7847
7848 If both options are off, Vim will wait until either the complete
7849 mapping or key sequence has been received, or it is clear that there
7850 is no mapping or key sequence for the received characters. For
7851 example: if you have mapped "vl" and Vim has received 'v', the next
7852 character is needed to see if the 'v' is followed by an 'l'.
7853 When one of the options is on, Vim will wait for about 1 second for
7854 the next character to arrive. After that the already received
7855 characters are interpreted as single characters. The waiting time can
7856 be changed with the 'timeoutlen' option.
7857 On slow terminals or very busy systems timing out may cause
7858 malfunctioning cursor keys. If both options are off, Vim waits
7859 forever after an entered <Esc> if there are key codes that start
7860 with <Esc>. You will have to type <Esc> twice. If you do not have
7861 problems with key codes, but would like to have :mapped key
7862 sequences not timing out in 1 second, set the 'ttimeout' option and
7863 reset the 'timeout' option.
7864
7865 NOTE: 'ttimeout' is reset when 'compatible' is set.
7866
7867 *'timeoutlen'* *'tm'*
7868'timeoutlen' 'tm' number (default 1000)
7869 global
Bram Moolenaar25c9c682019-05-05 18:13:34 +02007870
Bram Moolenaar071d4272004-06-13 20:20:40 +00007871 *'ttimeoutlen'* *'ttm'*
Bram Moolenaar94237492017-04-23 18:40:21 +02007872'ttimeoutlen' 'ttm' number (default -1, set to 100 in |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00007873 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007874 The time in milliseconds that is waited for a key code or mapped key
7875 sequence to complete. Also used for CTRL-\ CTRL-N and CTRL-\ CTRL-G
7876 when part of a command has been typed.
7877 Normally only 'timeoutlen' is used and 'ttimeoutlen' is -1. When a
7878 different timeout value for key codes is desired set 'ttimeoutlen' to
7879 a non-negative number.
7880
7881 ttimeoutlen mapping delay key code delay ~
7882 < 0 'timeoutlen' 'timeoutlen'
7883 >= 0 'timeoutlen' 'ttimeoutlen'
7884
7885 The timeout only happens when the 'timeout' and 'ttimeout' options
7886 tell so. A useful setting would be >
7887 :set timeout timeoutlen=3000 ttimeoutlen=100
7888< (time out on mapping after three seconds, time out on key codes after
7889 a tenth of a second).
7890
7891 *'title'* *'notitle'*
7892'title' boolean (default off, on when title can be restored)
7893 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007894 {not available when compiled without the |+title|
7895 feature}
7896 When on, the title of the window will be set to the value of
7897 'titlestring' (if it is not empty), or to:
7898 filename [+=-] (path) - VIM
7899 Where:
7900 filename the name of the file being edited
7901 - indicates the file cannot be modified, 'ma' off
7902 + indicates the file was modified
7903 = indicates the file is read-only
7904 =+ indicates the file is read-only and modified
7905 (path) is the path of the file being edited
7906 - VIM the server name |v:servername| or "VIM"
7907 Only works if the terminal supports setting window titles
7908 (currently Amiga console, Win32 console, all GUI versions and
7909 terminals with a non- empty 't_ts' option - these are Unix xterm and
7910 iris-ansi by default, where 't_ts' is taken from the builtin termcap).
7911 *X11*
7912 When Vim was compiled with HAVE_X11 defined, the original title will
7913 be restored if possible. The output of ":version" will include "+X11"
7914 when HAVE_X11 was defined, otherwise it will be "-X11". This also
7915 works for the icon name |'icon'|.
7916 But: When Vim was started with the |-X| argument, restoring the title
7917 will not work (except in the GUI).
7918 If the title cannot be restored, it is set to the value of 'titleold'.
7919 You might want to restore the title outside of Vim then.
7920 When using an xterm from a remote machine you can use this command:
7921 rsh machine_name xterm -display $DISPLAY &
7922 then the WINDOWID environment variable should be inherited and the
7923 title of the window should change back to what it should be after
7924 exiting Vim.
7925
7926 *'titlelen'*
7927'titlelen' number (default 85)
7928 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007929 {not available when compiled without the |+title|
7930 feature}
7931 Gives the percentage of 'columns' to use for the length of the window
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007932 title. When the title is longer, only the end of the path name is
7933 shown. A '<' character before the path name is used to indicate this.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007934 Using a percentage makes this adapt to the width of the window. But
7935 it won't work perfectly, because the actual number of characters
7936 available also depends on the font used and other things in the title
7937 bar. When 'titlelen' is zero the full path is used. Otherwise,
7938 values from 1 to 30000 percent can be used.
7939 'titlelen' is also used for the 'titlestring' option.
7940
7941 *'titleold'*
7942'titleold' string (default "Thanks for flying Vim")
7943 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007944 {only available when compiled with the |+title|
7945 feature}
7946 This option will be used for the window title when exiting Vim if the
7947 original title cannot be restored. Only happens if 'title' is on or
7948 'titlestring' is not empty.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00007949 This option cannot be set from a |modeline| or in the |sandbox|, for
7950 security reasons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007951 *'titlestring'*
7952'titlestring' string (default "")
7953 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007954 {not available when compiled without the |+title|
7955 feature}
7956 When this option is not empty, it will be used for the title of the
7957 window. This happens only when the 'title' option is on.
7958 Only works if the terminal supports setting window titles (currently
7959 Amiga console, Win32 console, all GUI versions and terminals with a
7960 non-empty 't_ts' option).
7961 When Vim was compiled with HAVE_X11 defined, the original title will
Bram Moolenaar51628222016-12-01 23:03:28 +01007962 be restored if possible, see |X11|.
Bram Moolenaar110289e2019-05-23 15:38:06 +02007963
Bram Moolenaar071d4272004-06-13 20:20:40 +00007964 When this option contains printf-style '%' items, they will be
7965 expanded according to the rules used for 'statusline'.
Bram Moolenaar110289e2019-05-23 15:38:06 +02007966 This option cannot be set in a modeline when 'modelineexpr' is off.
7967
Bram Moolenaar071d4272004-06-13 20:20:40 +00007968 Example: >
7969 :auto BufEnter * let &titlestring = hostname() . "/" . expand("%:p")
7970 :set title titlestring=%<%F%=%l/%L-%P titlelen=70
7971< The value of 'titlelen' is used to align items in the middle or right
7972 of the available space.
7973 Some people prefer to have the file name first: >
7974 :set titlestring=%t%(\ %M%)%(\ (%{expand(\"%:~:.:h\")})%)%(\ %a%)
7975< Note the use of "%{ }" and an expression to get the path of the file,
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007976 without the file name. The "%( %)" constructs are used to add a
Bram Moolenaar071d4272004-06-13 20:20:40 +00007977 separating space only when needed.
7978 NOTE: Use of special characters in 'titlestring' may cause the display
7979 to be garbled (e.g., when it contains a CR or NL character).
7980 {not available when compiled without the |+statusline| feature}
7981
7982 *'toolbar'* *'tb'*
7983'toolbar' 'tb' string (default "icons,tooltips")
7984 global
7985 {only for |+GUI_GTK|, |+GUI_Athena|, |+GUI_Motif| and
7986 |+GUI_Photon|}
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007987 The contents of this option controls various toolbar settings. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00007988 possible values are:
7989 icons Toolbar buttons are shown with icons.
7990 text Toolbar buttons shown with text.
7991 horiz Icon and text of a toolbar button are
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007992 horizontally arranged. {only in GTK+ 2 GUI}
Bram Moolenaar071d4272004-06-13 20:20:40 +00007993 tooltips Tooltips are active for toolbar buttons.
7994 Tooltips refer to the popup help text which appears after the mouse
7995 cursor is placed over a toolbar button for a brief moment.
7996
7997 If you want the toolbar to be shown with icons as well as text, do the
7998 following: >
7999 :set tb=icons,text
8000< Motif and Athena cannot display icons and text at the same time. They
8001 will show icons if both are requested.
8002
8003 If none of the strings specified in 'toolbar' are valid or if
8004 'toolbar' is empty, this option is ignored. If you want to disable
8005 the toolbar, you need to set the 'guioptions' option. For example: >
8006 :set guioptions-=T
8007< Also see |gui-toolbar|.
8008
8009 *'toolbariconsize'* *'tbis'*
8010'toolbariconsize' 'tbis' string (default "small")
8011 global
Bram Moolenaar3df01732017-02-17 22:47:16 +01008012 {only in the GTK+ GUI}
Bram Moolenaar071d4272004-06-13 20:20:40 +00008013 Controls the size of toolbar icons. The possible values are:
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01008014 tiny Use tiny icons.
8015 small Use small icons (default).
8016 medium Use medium-sized icons.
8017 large Use large icons.
8018 huge Use even larger icons.
8019 giant Use very big icons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008020 The exact dimensions in pixels of the various icon sizes depend on
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01008021 the current theme. Common dimensions are giant=48x48, huge=32x32,
8022 large=24x24, medium=24x24, small=20x20 and tiny=16x16.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008023
8024 If 'toolbariconsize' is empty, the global default size as determined
8025 by user preferences or the current theme is used.
8026
8027 *'ttybuiltin'* *'tbi'* *'nottybuiltin'* *'notbi'*
8028'ttybuiltin' 'tbi' boolean (default on)
8029 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008030 When on, the builtin termcaps are searched before the external ones.
8031 When off the builtin termcaps are searched after the external ones.
8032 When this option is changed, you should set the 'term' option next for
8033 the change to take effect, for example: >
8034 :set notbi term=$TERM
8035< See also |termcap|.
8036 Rationale: The default for this option is "on", because the builtin
8037 termcap entries are generally better (many systems contain faulty
8038 xterm entries...).
8039
8040 *'ttyfast'* *'tf'* *'nottyfast'* *'notf'*
8041'ttyfast' 'tf' boolean (default off, on when 'term' is xterm, hpterm,
8042 sun-cmd, screen, rxvt, dtterm or
8043 iris-ansi; also on when running Vim in
8044 a DOS console)
8045 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008046 Indicates a fast terminal connection. More characters will be sent to
8047 the screen for redrawing, instead of using insert/delete line
8048 commands. Improves smoothness of redrawing when there are multiple
8049 windows and the terminal does not support a scrolling region.
8050 Also enables the extra writing of characters at the end of each screen
8051 line for lines that wrap. This helps when using copy/paste with the
8052 mouse in an xterm and other terminals.
8053
8054 *'ttymouse'* *'ttym'*
8055'ttymouse' 'ttym' string (default depends on 'term')
8056 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008057 {only in Unix and VMS, doesn't work in the GUI; not
8058 available when compiled without |+mouse|}
8059 Name of the terminal type for which mouse codes are to be recognized.
Bram Moolenaar2c7a7632007-05-10 18:19:11 +00008060 Currently these strings are valid:
Bram Moolenaar071d4272004-06-13 20:20:40 +00008061 *xterm-mouse*
8062 xterm xterm-like mouse handling. The mouse generates
8063 "<Esc>[Mscr", where "scr" is three bytes:
8064 "s" = button state
8065 "c" = column plus 33
8066 "r" = row plus 33
Bram Moolenaare968e362014-05-13 20:23:24 +02008067 This only works up to 223 columns! See "dec",
8068 "urxvt", and "sgr" for solutions.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008069 xterm2 Works like "xterm", but with the xterm reporting the
8070 mouse position while the mouse is dragged. This works
8071 much faster and more precise. Your xterm must at
Bram Moolenaarbc7aa852005-03-06 23:38:09 +00008072 least at patchlevel 88 / XFree 3.3.3 for this to
Bram Moolenaar071d4272004-06-13 20:20:40 +00008073 work. See below for how Vim detects this
8074 automatically.
8075 *netterm-mouse*
Bram Moolenaar25c9c682019-05-05 18:13:34 +02008076 netterm NetTerm mouse handling. A left mouse click generates
Bram Moolenaar071d4272004-06-13 20:20:40 +00008077 "<Esc>}r,c<CR>", where "r,c" are two decimal numbers
Bram Moolenaar25c9c682019-05-05 18:13:34 +02008078 for the row and column. No other mouse events are
8079 supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008080 *dec-mouse*
8081 dec DEC terminal mouse handling. The mouse generates a
8082 rather complex sequence, starting with "<Esc>[".
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00008083 This is also available for an Xterm, if it was
8084 configured with "--enable-dec-locator".
Bram Moolenaar071d4272004-06-13 20:20:40 +00008085 *jsbterm-mouse*
8086 jsbterm JSB term mouse handling.
8087 *pterm-mouse*
8088 pterm QNX pterm mouse handling.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01008089 *urxvt-mouse*
8090 urxvt Mouse handling for the urxvt (rxvt-unicode) terminal.
Bram Moolenaare968e362014-05-13 20:23:24 +02008091 The mouse works only if the terminal supports this
8092 encoding style, but it does not have 223 columns limit
8093 unlike "xterm" or "xterm2".
Bram Moolenaar9b451252012-08-15 17:43:31 +02008094 *sgr-mouse*
8095 sgr Mouse handling for the terminal that emits SGR-styled
Bram Moolenaare968e362014-05-13 20:23:24 +02008096 mouse reporting. The mouse works even in columns
8097 beyond 223. This option is backward compatible with
8098 "xterm2" because it can also decode "xterm2" style
8099 mouse codes.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008100
8101 The mouse handling must be enabled at compile time |+mouse_xterm|
Bram Moolenaare968e362014-05-13 20:23:24 +02008102 |+mouse_dec| |+mouse_netterm| |+mouse_jsbterm| |+mouse_urxvt|
8103 |+mouse_sgr|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008104 Only "xterm"(2) is really recognized. NetTerm mouse codes are always
8105 recognized, if enabled at compile time. DEC terminal mouse codes
8106 are recognized if enabled at compile time, and 'ttymouse' is not
Bram Moolenaare968e362014-05-13 20:23:24 +02008107 "xterm", "xterm2", "urxvt" or "sgr" (because dec mouse codes conflict
8108 with them).
Bram Moolenaar071d4272004-06-13 20:20:40 +00008109 This option is automatically set to "xterm", when the 'term' option is
Bram Moolenaar45758762016-10-12 23:08:06 +02008110 set to a name that starts with "xterm", "mlterm", "screen", "tmux",
8111 "st" (full match only), "st-" or "stterm", and 'ttymouse' is not set
8112 already.
Bram Moolenaare968e362014-05-13 20:23:24 +02008113 Additionally, if vim is compiled with the |+termresponse| feature and
8114 |t_RV| is set to the escape sequence to request the xterm version
Bram Moolenaarf8a07122019-07-01 22:06:07 +02008115 number, more intelligent detection is done.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008116 The "xterm2" value will be set if the xterm version is reported to be
Bram Moolenaard47d5222018-12-09 20:43:55 +01008117 from 95 to 276. The "sgr" value will be set if Vim detects Mac
8118 Terminal.app, iTerm2 or mintty, and when the xterm version is 277 or
8119 higher.
Bram Moolenaare968e362014-05-13 20:23:24 +02008120 If you do not want 'ttymouse' to be set to "xterm2" or "sgr"
8121 automatically, set t_RV to an empty string: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00008122 :set t_RV=
8123<
8124 *'ttyscroll'* *'tsl'*
8125'ttyscroll' 'tsl' number (default 999)
8126 global
8127 Maximum number of lines to scroll the screen. If there are more lines
8128 to scroll the window is redrawn. For terminals where scrolling is
8129 very slow and redrawing is not slow this can be set to a small number,
8130 e.g., 3, to speed up displaying.
8131
8132 *'ttytype'* *'tty'*
8133'ttytype' 'tty' string (default from $TERM)
8134 global
8135 Alias for 'term', see above.
8136
Bram Moolenaar55debbe2010-05-23 23:34:36 +02008137 *'undodir'* *'udir'*
8138'undodir' 'udir' string (default ".")
8139 global
Bram Moolenaardb84e452010-08-15 13:50:43 +02008140 {only when compiled with the |+persistent_undo| feature}
Bram Moolenaar55debbe2010-05-23 23:34:36 +02008141 List of directory names for undo files, separated with commas.
Bram Moolenaarb230bd52010-05-25 21:02:00 +02008142 See |'backupdir'| for details of the format.
Bram Moolenaar6a244fe2010-05-24 22:02:24 +02008143 "." means using the directory of the file. The undo file name for
8144 "file.txt" is ".file.txt.un~".
8145 For other directories the file name is the full path of the edited
8146 file, with path separators replaced with "%".
Bram Moolenaar55debbe2010-05-23 23:34:36 +02008147 When writing: The first directory that exists is used. "." always
8148 works, no directories after "." will be used for writing.
8149 When reading all entries are tried to find an undo file. The first
8150 undo file that exists is used. When it cannot be read an error is
8151 given, no further entry is used.
8152 See |undo-persistence|.
Bram Moolenaar110289e2019-05-23 15:38:06 +02008153 This option cannot be set from a |modeline| or in the |sandbox|, for
8154 security reasons.
Bram Moolenaar55debbe2010-05-23 23:34:36 +02008155
Bram Moolenaar543b7ef2013-06-01 14:50:56 +02008156 *'undofile'* *'noundofile'* *'udf'* *'noudf'*
Bram Moolenaar55debbe2010-05-23 23:34:36 +02008157'undofile' 'udf' boolean (default off)
8158 local to buffer
Bram Moolenaardb84e452010-08-15 13:50:43 +02008159 {only when compiled with the |+persistent_undo| feature}
Bram Moolenaar55debbe2010-05-23 23:34:36 +02008160 When on, Vim automatically saves undo history to an undo file when
8161 writing a buffer to a file, and restores undo history from the same
8162 file on buffer read.
Bram Moolenaarb230bd52010-05-25 21:02:00 +02008163 The directory where the undo file is stored is specified by 'undodir'.
8164 For more information about this feature see |undo-persistence|.
Bram Moolenaar59f931e2010-07-24 20:27:03 +02008165 The undo file is not read when 'undoreload' causes the buffer from
8166 before a reload to be saved for undo.
Bram Moolenaar97d62492012-11-15 21:28:22 +01008167 When 'undofile' is turned off the undo file is NOT deleted.
Bram Moolenaar036986f2017-03-16 17:41:02 +01008168 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaar55debbe2010-05-23 23:34:36 +02008169
Bram Moolenaar071d4272004-06-13 20:20:40 +00008170 *'undolevels'* *'ul'*
8171'undolevels' 'ul' number (default 100, 1000 for Unix, VMS,
8172 Win32 and OS/2)
Bram Moolenaarf5a2fd82013-11-06 05:26:15 +01008173 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00008174 Maximum number of changes that can be undone. Since undo information
8175 is kept in memory, higher numbers will cause more memory to be used
8176 (nevertheless, a single change can use an unlimited amount of memory).
8177 Set to 0 for Vi compatibility: One level of undo and "u" undoes
8178 itself: >
8179 set ul=0
8180< But you can also get Vi compatibility by including the 'u' flag in
8181 'cpoptions', and still be able to use CTRL-R to repeat undo.
Bram Moolenaar945e2db2010-06-05 17:43:32 +02008182 Also see |undo-two-ways|.
Bram Moolenaarf5a2fd82013-11-06 05:26:15 +01008183 Set to -1 for no undo at all. You might want to do this only for the
8184 current buffer: >
8185 setlocal ul=-1
Bram Moolenaar071d4272004-06-13 20:20:40 +00008186< This helps when you run out of memory for a single change.
Bram Moolenaar32efaf62014-11-05 17:02:17 +01008187
8188 The local value is set to -123456 when the global value is to be used.
8189
Bram Moolenaar945e2db2010-06-05 17:43:32 +02008190 Also see |clear-undo|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008191
Bram Moolenaar59f931e2010-07-24 20:27:03 +02008192 *'undoreload'* *'ur'*
8193'undoreload' 'ur' number (default 10000)
8194 global
Bram Moolenaar59f931e2010-07-24 20:27:03 +02008195 Save the whole buffer for undo when reloading it. This applies to the
8196 ":e!" command and reloading for when the buffer changed outside of
8197 Vim. |FileChangedShell|
Bram Moolenaar24a98a02017-09-27 22:23:55 +02008198 The save only happens when this option is negative or when the number
Bram Moolenaar59f931e2010-07-24 20:27:03 +02008199 of lines is smaller than the value of this option.
8200 Set this option to zero to disable undo for a reload.
8201
8202 When saving undo for a reload, any undo file is not read.
8203
8204 Note that this causes the whole buffer to be stored in memory. Set
8205 this option to a lower value if you run out of memory.
8206
Bram Moolenaar071d4272004-06-13 20:20:40 +00008207 *'updatecount'* *'uc'*
8208'updatecount' 'uc' number (default: 200)
8209 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008210 After typing this many characters the swap file will be written to
8211 disk. When zero, no swap file will be created at all (see chapter on
8212 recovery |crash-recovery|). 'updatecount' is set to zero by starting
8213 Vim with the "-n" option, see |startup|. When editing in readonly
8214 mode this option will be initialized to 10000.
8215 The swapfile can be disabled per buffer with |'swapfile'|.
8216 When 'updatecount' is set from zero to non-zero, swap files are
8217 created for all buffers that have 'swapfile' set. When 'updatecount'
8218 is set to zero, existing swap files are not deleted.
8219 Also see |'swapsync'|.
8220 This option has no meaning in buffers where |'buftype'| is "nofile"
8221 or "nowrite".
8222
8223 *'updatetime'* *'ut'*
8224'updatetime' 'ut' number (default 4000)
8225 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008226 If this many milliseconds nothing is typed the swap file will be
8227 written to disk (see |crash-recovery|). Also used for the
8228 |CursorHold| autocommand event.
8229
Bram Moolenaar04958cb2018-06-23 19:23:02 +02008230 *'varsofttabstop'* *'vsts'*
8231'varsofttabstop' 'vsts' string (default "")
8232 local to buffer
8233 {only available when compiled with the |+vartabs|
8234 feature}
Bram Moolenaar04958cb2018-06-23 19:23:02 +02008235 A list of the number of spaces that a <Tab> counts for while editing,
8236 such as inserting a <Tab> or using <BS>. It "feels" like variable-
8237 width <Tab>s are being inserted, while in fact a mixture of spaces
8238 and <Tab>s is used. Tab widths are separated with commas, with the
8239 final value applying to all subsequent tabs.
8240
8241 For example, when editing assembly language files where statements
Bram Moolenaar6dc819b2018-07-03 16:42:19 +02008242 start in the 9th column and comments in the 41st, it may be useful
Bram Moolenaar04958cb2018-06-23 19:23:02 +02008243 to use the following: >
8244 :set varsofttabstop=8,32,8
Bram Moolenaar6dc819b2018-07-03 16:42:19 +02008245< This will set soft tabstops with 8 and 8 + 32 spaces, and 8 more
8246 for every column thereafter.
Bram Moolenaar04958cb2018-06-23 19:23:02 +02008247
8248 Note that the value of |'softtabstop'| will be ignored while
8249 'varsofttabstop' is set.
8250
8251 *'vartabstop'* *'vts'*
8252'vartabstop' 'vts' string (default "")
8253 local to buffer
8254 {only available when compiled with the |+vartabs|
8255 feature}
Bram Moolenaar04958cb2018-06-23 19:23:02 +02008256 A list of the number of spaces that a <Tab> in the file counts for,
8257 separated by commas. Each value corresponds to one tab, with the
8258 final value applying to all subsequent tabs. For example: >
8259 :set vartabstop=4,20,10,8
8260< This will make the first tab 4 spaces wide, the second 20 spaces,
8261 the third 10 spaces, and all following tabs 8 spaces.
8262
8263 Note that the value of |'tabstop'| will be ignored while 'vartabstop'
8264 is set.
8265
Bram Moolenaar071d4272004-06-13 20:20:40 +00008266 *'verbose'* *'vbs'*
8267'verbose' 'vbs' number (default 0)
8268 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008269 When bigger than zero, Vim will give messages about what it is doing.
8270 Currently, these messages are given:
8271 >= 1 When the viminfo file is read or written.
8272 >= 2 When a file is ":source"'ed.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00008273 >= 5 Every searched tags file and include file.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008274 >= 8 Files for which a group of autocommands is executed.
8275 >= 9 Every executed autocommand.
8276 >= 12 Every executed function.
8277 >= 13 When an exception is thrown, caught, finished, or discarded.
8278 >= 14 Anything pending in a ":finally" clause.
8279 >= 15 Every executed Ex command (truncated at 200 characters).
8280
8281 This option can also be set with the "-V" argument. See |-V|.
8282 This option is also set by the |:verbose| command.
8283
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +00008284 When the 'verbosefile' option is set then the verbose messages are not
8285 displayed.
8286
8287 *'verbosefile'* *'vfile'*
8288'verbosefile' 'vfile' string (default empty)
8289 global
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +00008290 When not empty all messages are written in a file with this name.
8291 When the file exists messages are appended.
8292 Writing to the file ends when Vim exits or when 'verbosefile' is made
Bram Moolenaar80794b12010-06-13 05:20:42 +02008293 empty. Writes are buffered, thus may not show up for some time.
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +00008294 Setting 'verbosefile' to a new value is like making it empty first.
8295 The difference with |:redir| is that verbose messages are not
8296 displayed when 'verbosefile' is set.
8297
Bram Moolenaar071d4272004-06-13 20:20:40 +00008298 *'viewdir'* *'vdir'*
8299'viewdir' 'vdir' string (default for Amiga, MS-DOS, OS/2 and Win32:
8300 "$VIM/vimfiles/view",
8301 for Unix: "~/.vim/view",
8302 for Macintosh: "$VIM:vimfiles:view"
8303 for VMS: "sys$login:vimfiles/view"
8304 for RiscOS: "Choices:vimfiles/view")
8305 global
Bram Moolenaardb84e452010-08-15 13:50:43 +02008306 {not available when compiled without the |+mksession|
Bram Moolenaar071d4272004-06-13 20:20:40 +00008307 feature}
8308 Name of the directory where to store files for |:mkview|.
8309 This option cannot be set from a |modeline| or in the |sandbox|, for
8310 security reasons.
8311
8312 *'viewoptions'* *'vop'*
Bram Moolenaar13e90412017-11-11 18:16:48 +01008313'viewoptions' 'vop' string (default: "folds,options,cursor,curdir")
Bram Moolenaar071d4272004-06-13 20:20:40 +00008314 global
Bram Moolenaardb84e452010-08-15 13:50:43 +02008315 {not available when compiled without the |+mksession|
Bram Moolenaar071d4272004-06-13 20:20:40 +00008316 feature}
8317 Changes the effect of the |:mkview| command. It is a comma separated
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00008318 list of words. Each word enables saving and restoring something:
Bram Moolenaar071d4272004-06-13 20:20:40 +00008319 word save and restore ~
8320 cursor cursor position in file and in window
8321 folds manually created folds, opened/closed folds and local
8322 fold options
8323 options options and mappings local to a window or buffer (not
8324 global values for local options)
Bram Moolenaar6e932462014-09-09 18:48:09 +02008325 localoptions same as "options"
Bram Moolenaar071d4272004-06-13 20:20:40 +00008326 slash backslashes in file names replaced with forward
8327 slashes
8328 unix with Unix end-of-line format (single <NL>), even when
8329 on Windows or DOS
Bram Moolenaar13e90412017-11-11 18:16:48 +01008330 curdir the window-local directory, if set with `:lcd`
Bram Moolenaar071d4272004-06-13 20:20:40 +00008331
8332 "slash" and "unix" are useful on Windows when sharing view files
8333 with Unix. The Unix version of Vim cannot source dos format scripts,
8334 but the Windows version of Vim can source unix format scripts.
8335
8336 *'viminfo'* *'vi'* *E526* *E527* *E528*
8337'viminfo' 'vi' string (Vi default: "", Vim default for MS-DOS,
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008338 Windows and OS/2: '100,<50,s10,h,rA:,rB:,
8339 for Amiga: '100,<50,s10,h,rdf0:,rdf1:,rdf2:
8340 for others: '100,<50,s10,h)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008341 global
Bram Moolenaardb84e452010-08-15 13:50:43 +02008342 {not available when compiled without the |+viminfo|
Bram Moolenaar071d4272004-06-13 20:20:40 +00008343 feature}
8344 When non-empty, the viminfo file is read upon startup and written
Bram Moolenaarc4da1132017-07-15 19:39:43 +02008345 when exiting Vim (see |viminfo-file|). Except when 'viminfofile' is
8346 "NONE".
8347 The string should be a comma separated list of parameters, each
8348 consisting of a single character identifying the particular parameter,
8349 followed by a number or string which specifies the value of that
8350 parameter. If a particular character is left out, then the default
8351 value is used for that parameter. The following is a list of the
8352 identifying characters and the effect of their value.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008353 CHAR VALUE ~
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01008354 *viminfo-!*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008355 ! When included, save and restore global variables that start
8356 with an uppercase letter, and don't contain a lowercase
8357 letter. Thus "KEEPTHIS and "K_L_M" are stored, but "KeepThis"
Bram Moolenaar680eeca2010-10-20 17:44:42 +02008358 and "_K_L_M" are not. Nested List and Dict items may not be
Bram Moolenaar166af9b2010-11-16 20:34:40 +01008359 read back correctly, you end up with an empty item.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01008360 *viminfo-quote*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008361 " Maximum number of lines saved for each register. Old name of
8362 the '<' item, with the disadvantage that you need to put a
8363 backslash before the ", otherwise it will be recognized as the
8364 start of a comment!
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01008365 *viminfo-%*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008366 % When included, save and restore the buffer list. If Vim is
8367 started with a file name argument, the buffer list is not
8368 restored. If Vim is started without a file name argument, the
Bram Moolenaard042dc82015-11-24 19:18:36 +01008369 buffer list is restored from the viminfo file. Quickfix
8370 ('buftype'), unlisted ('buflisted'), unnamed and buffers on
8371 removable media (|viminfo-r|) are not saved.
Bram Moolenaar15d0a8c2004-09-06 17:44:46 +00008372 When followed by a number, the number specifies the maximum
8373 number of buffers that are stored. Without a number all
8374 buffers are stored.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01008375 *viminfo-'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008376 ' Maximum number of previously edited files for which the marks
8377 are remembered. This parameter must always be included when
8378 'viminfo' is non-empty.
8379 Including this item also means that the |jumplist| and the
8380 |changelist| are stored in the viminfo file.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01008381 *viminfo-/*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008382 / Maximum number of items in the search pattern history to be
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00008383 saved. If non-zero, then the previous search and substitute
Bram Moolenaar071d4272004-06-13 20:20:40 +00008384 patterns are also saved. When not included, the value of
8385 'history' is used.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01008386 *viminfo-:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008387 : Maximum number of items in the command-line history to be
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00008388 saved. When not included, the value of 'history' is used.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01008389 *viminfo-<*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008390 < Maximum number of lines saved for each register. If zero then
8391 registers are not saved. When not included, all lines are
8392 saved. '"' is the old name for this item.
8393 Also see the 's' item below: limit specified in Kbyte.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01008394 *viminfo-@*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008395 @ Maximum number of items in the input-line history to be
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00008396 saved. When not included, the value of 'history' is used.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01008397 *viminfo-c*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008398 c When included, convert the text in the viminfo file from the
8399 'encoding' used when writing the file to the current
Bram Moolenaar582fd852005-03-28 20:58:01 +00008400 'encoding'. See |viminfo-encoding|.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01008401 *viminfo-f*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008402 f Whether file marks need to be stored. If zero, file marks ('0
8403 to '9, 'A to 'Z) are not stored. When not present or when
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00008404 non-zero, they are all stored. '0 is used for the current
Bram Moolenaar071d4272004-06-13 20:20:40 +00008405 cursor position (when exiting or when doing ":wviminfo").
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01008406 *viminfo-h*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008407 h Disable the effect of 'hlsearch' when loading the viminfo
8408 file. When not included, it depends on whether ":nohlsearch"
8409 has been used since the last search command.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01008410 *viminfo-n*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008411 n Name of the viminfo file. The name must immediately follow
Bram Moolenaarc4da1132017-07-15 19:39:43 +02008412 the 'n'. Must be at the end of the option! If the
8413 'viminfofile' option is set, that file name overrides the one
8414 given here with 'viminfo'. Environment variables are
Bram Moolenaar063b9d12016-07-09 20:21:48 +02008415 expanded when opening the file, not when setting the option.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01008416 *viminfo-r*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008417 r Removable media. The argument is a string (up to the next
8418 ','). This parameter can be given several times. Each
8419 specifies the start of a path for which no marks will be
8420 stored. This is to avoid removable media. For MS-DOS you
8421 could use "ra:,rb:", for Amiga "rdf0:,rdf1:,rdf2:". You can
8422 also use it for temp files, e.g., for Unix: "r/tmp". Case is
8423 ignored. Maximum length of each 'r' argument is 50
8424 characters.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01008425 *viminfo-s*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008426 s Maximum size of an item in Kbyte. If zero then registers are
8427 not saved. Currently only applies to registers. The default
8428 "s10" will exclude registers with more than 10 Kbyte of text.
8429 Also see the '<' item above: line count limit.
8430
8431 Example: >
8432 :set viminfo='50,<1000,s100,:0,n~/vim/viminfo
8433<
8434 '50 Marks will be remembered for the last 50 files you
8435 edited.
8436 <1000 Contents of registers (up to 1000 lines each) will be
8437 remembered.
8438 s100 Registers with more than 100 Kbyte text are skipped.
8439 :0 Command-line history will not be saved.
8440 n~/vim/viminfo The name of the file to use is "~/vim/viminfo".
8441 no / Since '/' is not specified, the default will be used,
8442 that is, save all of the search history, and also the
8443 previous search and substitute patterns.
8444 no % The buffer list will not be saved nor read back.
8445 no h 'hlsearch' highlighting will be restored.
8446
8447 When setting 'viminfo' from an empty value you can use |:rviminfo| to
8448 load the contents of the file, this is not done automatically.
8449
8450 This option cannot be set from a |modeline| or in the |sandbox|, for
8451 security reasons.
Bram Moolenaar036986f2017-03-16 17:41:02 +01008452 NOTE: This option is set to the Vim default value when 'compatible'
8453 is reset.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008454
Bram Moolenaarc4da1132017-07-15 19:39:43 +02008455 *'viminfofile'* *'vif'*
8456'viminfofile' 'vif' string (default: "")
8457 global
Bram Moolenaarc4da1132017-07-15 19:39:43 +02008458 {not available when compiled without the |+viminfo|
8459 feature}
8460 When non-empty, overrides the file name used for viminfo.
8461 When equal to "NONE" no viminfo file will be read or written.
8462 This option can be set with the |-i| command line flag. The |--clean|
8463 command line flag sets it to "NONE".
Bram Moolenaar110289e2019-05-23 15:38:06 +02008464 This option cannot be set from a |modeline| or in the |sandbox|, for
8465 security reasons.
Bram Moolenaarc4da1132017-07-15 19:39:43 +02008466
Bram Moolenaar071d4272004-06-13 20:20:40 +00008467 *'virtualedit'* *'ve'*
8468'virtualedit' 've' string (default "")
8469 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008470 {not available when compiled without the
8471 |+virtualedit| feature}
8472 A comma separated list of these words:
8473 block Allow virtual editing in Visual block mode.
8474 insert Allow virtual editing in Insert mode.
8475 all Allow virtual editing in all modes.
Bram Moolenaarefd2bf12006-03-16 21:41:35 +00008476 onemore Allow the cursor to move just past the end of the line
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00008477
Bram Moolenaar071d4272004-06-13 20:20:40 +00008478 Virtual editing means that the cursor can be positioned where there is
Bram Moolenaarebcbd022007-05-12 14:28:25 +00008479 no actual character. This can be halfway into a tab or beyond the end
Bram Moolenaar071d4272004-06-13 20:20:40 +00008480 of the line. Useful for selecting a rectangle in Visual mode and
8481 editing a table.
Bram Moolenaarefd2bf12006-03-16 21:41:35 +00008482 "onemore" is not the same, it will only allow moving the cursor just
8483 after the last character of the line. This makes some commands more
8484 consistent. Previously the cursor was always past the end of the line
8485 if the line was empty. But it is far from Vi compatible. It may also
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00008486 break some plugins or Vim scripts. For example because |l| can move
8487 the cursor after the last character. Use with care!
Bram Moolenaar9ba7e172013-07-17 22:37:26 +02008488 Using the `$` command will move to the last character in the line, not
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00008489 past it. This may actually move the cursor to the left!
Bram Moolenaar9ba7e172013-07-17 22:37:26 +02008490 The `g$` command will move to the end of the screen line.
Bram Moolenaarefd2bf12006-03-16 21:41:35 +00008491 It doesn't make sense to combine "all" with "onemore", but you will
8492 not get a warning for it.
Bram Moolenaar036986f2017-03-16 17:41:02 +01008493 NOTE: This option is set to "" when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008494
8495 *'visualbell'* *'vb'* *'novisualbell'* *'novb'* *beep*
8496'visualbell' 'vb' boolean (default off)
8497 global
Bram Moolenaar74675a62017-07-15 13:53:23 +02008498 Use a visual bell instead of beeping. The terminal code to display the
Bram Moolenaar071d4272004-06-13 20:20:40 +00008499 visual bell is given with 't_vb'. When no beep or flash is wanted,
Bram Moolenaar74675a62017-07-15 13:53:23 +02008500 use: >
8501 :set vb t_vb=
8502< If you want a short flash, you can use this on many terminals: >
8503 :set vb t_vb=[?5h$<100>[?5l
8504< Here $<100> specifies the time, you can use a smaller or bigger value
8505 to get a shorter or longer flash.
8506
8507 Note: Vim will limit the bell to once per half a second. This avoids
8508 having to wait for the flashing to finish when there are lots of
8509 bells, e.g. on key repeat. This also happens without 'visualbell'
8510 set.
8511
Bram Moolenaar071d4272004-06-13 20:20:40 +00008512 In the GUI, 't_vb' defaults to "<Esc>|f", which inverts the display
8513 for 20 msec. If you want to use a different time, use "<Esc>|40f",
8514 where 40 is the time in msec.
Bram Moolenaar74675a62017-07-15 13:53:23 +02008515
8516 Note: When the GUI starts, 't_vb' is reset to its default value. You
8517 might want to set it again in your |gvimrc|.
8518
Bram Moolenaar071d4272004-06-13 20:20:40 +00008519 Does not work on the Amiga, you always get a screen flash.
8520 Also see 'errorbells'.
8521
8522 *'warn'* *'nowarn'*
8523'warn' boolean (default on)
8524 global
8525 Give a warning message when a shell command is used while the buffer
8526 has been changed.
8527
8528 *'weirdinvert'* *'wiv'* *'noweirdinvert'* *'nowiv'*
8529'weirdinvert' 'wiv' boolean (default off)
8530 global
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00008531 This option has the same effect as the 't_xs' terminal option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008532 It is provided for backwards compatibility with version 4.x.
8533 Setting 'weirdinvert' has the effect of making 't_xs' non-empty, and
8534 vice versa. Has no effect when the GUI is running.
8535
8536 *'whichwrap'* *'ww'*
8537'whichwrap' 'ww' string (Vim default: "b,s", Vi default: "")
8538 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008539 Allow specified keys that move the cursor left/right to move to the
8540 previous/next line when the cursor is on the first/last character in
8541 the line. Concatenate characters to allow this for these keys:
8542 char key mode ~
8543 b <BS> Normal and Visual
8544 s <Space> Normal and Visual
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00008545 h "h" Normal and Visual (not recommended)
8546 l "l" Normal and Visual (not recommended)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008547 < <Left> Normal and Visual
8548 > <Right> Normal and Visual
8549 ~ "~" Normal
8550 [ <Left> Insert and Replace
8551 ] <Right> Insert and Replace
8552 For example: >
8553 :set ww=<,>,[,]
8554< allows wrap only when cursor keys are used.
8555 When the movement keys are used in combination with a delete or change
8556 operator, the <EOL> also counts for a character. This makes "3h"
8557 different from "3dh" when the cursor crosses the end of a line. This
8558 is also true for "x" and "X", because they do the same as "dl" and
8559 "dh". If you use this, you may also want to use the mapping
8560 ":map <BS> X" to make backspace delete the character in front of the
8561 cursor.
Bram Moolenaar362e1a32006-03-06 23:29:24 +00008562 When 'l' is included and it is used after an operator at the end of a
8563 line then it will not move to the next line. This makes "dl", "cl",
8564 "yl" etc. work normally.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008565 NOTE: This option is set to the Vi default value when 'compatible' is
8566 set and to the Vim default value when 'compatible' is reset.
8567
8568 *'wildchar'* *'wc'*
8569'wildchar' 'wc' number (Vim default: <Tab>, Vi default: CTRL-E)
8570 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008571 Character you have to type to start wildcard expansion in the
8572 command-line, as specified with 'wildmode'.
Bram Moolenaar446cb832008-06-24 21:56:24 +00008573 More info here: |cmdline-completion|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008574 The character is not recognized when used inside a macro. See
8575 'wildcharm' for that.
8576 Although 'wc' is a number option, you can set it to a special key: >
8577 :set wc=<Esc>
8578< NOTE: This option is set to the Vi default value when 'compatible' is
8579 set and to the Vim default value when 'compatible' is reset.
8580
8581 *'wildcharm'* *'wcm'*
8582'wildcharm' 'wcm' number (default: none (0))
8583 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008584 'wildcharm' works exactly like 'wildchar', except that it is
Bram Moolenaar582fd852005-03-28 20:58:01 +00008585 recognized when used inside a macro. You can find "spare" command-line
8586 keys suitable for this option by looking at |ex-edit-index|. Normally
Bram Moolenaar071d4272004-06-13 20:20:40 +00008587 you'll never actually type 'wildcharm', just use it in mappings that
8588 automatically invoke completion mode, e.g.: >
8589 :set wcm=<C-Z>
Bram Moolenaar446cb832008-06-24 21:56:24 +00008590 :cnoremap ss so $vim/sessions/*.vim<C-Z>
Bram Moolenaar071d4272004-06-13 20:20:40 +00008591< Then after typing :ss you can use CTRL-P & CTRL-N.
8592
8593 *'wildignore'* *'wig'*
8594'wildignore' 'wig' string (default "")
8595 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008596 {not available when compiled without the |+wildignore|
8597 feature}
8598 A list of file patterns. A file that matches with one of these
Bram Moolenaar30b65812012-07-12 22:01:11 +02008599 patterns is ignored when expanding |wildcards|, completing file or
8600 directory names, and influences the result of |expand()|, |glob()| and
8601 |globpath()| unless a flag is passed to disable this.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008602 The pattern is used like with |:autocmd|, see |autocmd-patterns|.
8603 Also see 'suffixes'.
8604 Example: >
8605 :set wildignore=*.o,*.obj
8606< The use of |:set+=| and |:set-=| is preferred when adding or removing
8607 a pattern from the list. This avoids problems when a future version
8608 uses another default.
8609
Bram Moolenaar94950a92010-12-02 16:01:29 +01008610
Bram Moolenaar81af9252010-12-10 20:35:50 +01008611 *'wildignorecase'* *'wic'* *'nowildignorecase'* *'nowic'*
Bram Moolenaar94950a92010-12-02 16:01:29 +01008612'wildignorecase' 'wic' boolean (default off)
8613 global
Bram Moolenaar94950a92010-12-02 16:01:29 +01008614 When set case is ignored when completing file names and directories.
Bram Moolenaar71afbfe2013-03-19 16:49:16 +01008615 Has no effect when 'fileignorecase' is set.
Bram Moolenaar94950a92010-12-02 16:01:29 +01008616 Does not apply when the shell is used to expand wildcards, which
8617 happens when there are special characters.
8618
8619
Bram Moolenaar071d4272004-06-13 20:20:40 +00008620 *'wildmenu'* *'wmnu'* *'nowildmenu'* *'nowmnu'*
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +02008621'wildmenu' 'wmnu' boolean (default off, set in |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008622 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008623 {not available if compiled without the |+wildmenu|
8624 feature}
8625 When 'wildmenu' is on, command-line completion operates in an enhanced
8626 mode. On pressing 'wildchar' (usually <Tab>) to invoke completion,
8627 the possible matches are shown just above the command line, with the
8628 first match highlighted (overwriting the status line, if there is
8629 one). Keys that show the previous/next match, such as <Tab> or
8630 CTRL-P/CTRL-N, cause the highlight to move to the appropriate match.
8631 When 'wildmode' is used, "wildmenu" mode is used where "full" is
8632 specified. "longest" and "list" do not start "wildmenu" mode.
Bram Moolenaar26402cb2013-02-20 21:26:00 +01008633 You can check the current mode with |wildmenumode()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008634 If there are more matches than can fit in the line, a ">" is shown on
8635 the right and/or a "<" is shown on the left. The status line scrolls
8636 as needed.
8637 The "wildmenu" mode is abandoned when a key is hit that is not used
8638 for selecting a completion.
8639 While the "wildmenu" is active the following keys have special
8640 meanings:
8641
8642 <Left> <Right> - select previous/next match (like CTRL-P/CTRL-N)
8643 <Down> - in filename/menu name completion: move into a
8644 subdirectory or submenu.
8645 <CR> - in menu completion, when the cursor is just after a
8646 dot: move into a submenu.
8647 <Up> - in filename/menu name completion: move up into
8648 parent directory or parent menu.
8649
8650 This makes the menus accessible from the console |console-menus|.
8651
8652 If you prefer the <Left> and <Right> keys to move the cursor instead
8653 of selecting a different match, use this: >
8654 :cnoremap <Left> <Space><BS><Left>
8655 :cnoremap <Right> <Space><BS><Right>
8656<
8657 The "WildMenu" highlighting is used for displaying the current match
8658 |hl-WildMenu|.
8659
8660 *'wildmode'* *'wim'*
8661'wildmode' 'wim' string (Vim default: "full")
8662 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008663 Completion mode that is used for the character specified with
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00008664 'wildchar'. It is a comma separated list of up to four parts. Each
Bram Moolenaar02467872007-05-06 13:22:01 +00008665 part specifies what to do for each consecutive use of 'wildchar'. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00008666 first part specifies the behavior for the first use of 'wildchar',
8667 The second part for the second use, etc.
8668 These are the possible values for each part:
8669 "" Complete only the first match.
8670 "full" Complete the next full match. After the last match,
8671 the original string is used and then the first match
8672 again.
8673 "longest" Complete till longest common string. If this doesn't
8674 result in a longer string, use the next part.
8675 "longest:full" Like "longest", but also start 'wildmenu' if it is
8676 enabled.
8677 "list" When more than one match, list all matches.
8678 "list:full" When more than one match, list all matches and
8679 complete first match.
8680 "list:longest" When more than one match, list all matches and
8681 complete till longest common string.
8682 When there is only a single match, it is fully completed in all cases.
8683
8684 Examples: >
8685 :set wildmode=full
Bram Moolenaar582fd852005-03-28 20:58:01 +00008686< Complete first full match, next match, etc. (the default) >
Bram Moolenaar071d4272004-06-13 20:20:40 +00008687 :set wildmode=longest,full
8688< Complete longest common string, then each full match >
8689 :set wildmode=list:full
8690< List all matches and complete each full match >
8691 :set wildmode=list,full
8692< List all matches without completing, then each full match >
8693 :set wildmode=longest,list
8694< Complete longest common string, then list alternatives.
Bram Moolenaar446cb832008-06-24 21:56:24 +00008695 More info here: |cmdline-completion|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008696
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00008697 *'wildoptions'* *'wop'*
8698'wildoptions' 'wop' string (default "")
8699 global
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00008700 {not available when compiled without the |+wildignore|
8701 feature}
8702 A list of words that change how command line completion is done.
8703 Currently only one word is allowed:
8704 tagfile When using CTRL-D to list matching tags, the kind of
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00008705 tag and the file of the tag is listed. Only one match
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00008706 is displayed per line. Often used tag kinds are:
8707 d #define
8708 f function
8709 Also see |cmdline-completion|.
8710
Bram Moolenaar071d4272004-06-13 20:20:40 +00008711 *'winaltkeys'* *'wak'*
8712'winaltkeys' 'wak' string (default "menu")
8713 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008714 {only used in Win32, Motif, GTK and Photon GUI}
8715 Some GUI versions allow the access to menu entries by using the ALT
8716 key in combination with a character that appears underlined in the
8717 menu. This conflicts with the use of the ALT key for mappings and
8718 entering special characters. This option tells what to do:
8719 no Don't use ALT keys for menus. ALT key combinations can be
8720 mapped, but there is no automatic handling. This can then be
8721 done with the |:simalt| command.
8722 yes ALT key handling is done by the windowing system. ALT key
8723 combinations cannot be mapped.
8724 menu Using ALT in combination with a character that is a menu
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00008725 shortcut key, will be handled by the windowing system. Other
Bram Moolenaar071d4272004-06-13 20:20:40 +00008726 keys can be mapped.
8727 If the menu is disabled by excluding 'm' from 'guioptions', the ALT
8728 key is never used for the menu.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00008729 This option is not used for <F10>; on Win32 and with GTK <F10> will
8730 select the menu, unless it has been mapped.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008731
Bram Moolenaar4d784b22019-05-25 19:51:39 +02008732 *'wincolor'* *'wcr'*
8733'wincolor' 'wcr' string (default empty)
8734 local to window
8735 Highlight group name to use for this window instead of the Normal
8736 color |hl-Normal|.
8737
Bram Moolenaar4399ef42005-02-12 14:29:27 +00008738 *'window'* *'wi'*
8739'window' 'wi' number (default screen height - 1)
8740 global
8741 Window height. Do not confuse this with the height of the Vim window,
8742 use 'lines' for that.
Bram Moolenaar19a09a12005-03-04 23:39:37 +00008743 Used for |CTRL-F| and |CTRL-B| when there is only one window and the
8744 value is smaller than 'lines' minus one. The screen will scroll
8745 'window' minus two lines, with a minimum of one.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00008746 When 'window' is equal to 'lines' minus one CTRL-F and CTRL-B scroll
8747 in a much smarter way, taking care of wrapping lines.
8748 When resizing the Vim window, the value is smaller than 1 or more than
8749 or equal to 'lines' it will be set to 'lines' minus 1.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00008750
Bram Moolenaar071d4272004-06-13 20:20:40 +00008751 *'winheight'* *'wh'* *E591*
8752'winheight' 'wh' number (default 1)
8753 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008754 Minimal number of lines for the current window. This is not a hard
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00008755 minimum, Vim will use fewer lines if there is not enough room. If the
Bram Moolenaar446cb832008-06-24 21:56:24 +00008756 focus goes to a window that is smaller, its size is increased, at the
8757 cost of the height of other windows.
8758 Set 'winheight' to a small number for normal editing.
8759 Set it to 999 to make the current window fill most of the screen.
8760 Other windows will be only 'winminheight' high. This has the drawback
8761 that ":all" will create only two windows. To avoid "vim -o 1 2 3 4"
8762 to create only two windows, set the option after startup is done,
8763 using the |VimEnter| event: >
8764 au VimEnter * set winheight=999
8765< Minimum value is 1.
8766 The height is not adjusted after one of the commands that change the
Bram Moolenaar071d4272004-06-13 20:20:40 +00008767 height of the current window.
8768 'winheight' applies to the current window. Use 'winminheight' to set
8769 the minimal height for other windows.
8770
8771 *'winfixheight'* *'wfh'* *'nowinfixheight'* *'nowfh'*
8772'winfixheight' 'wfh' boolean (default off)
8773 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00008774 Keep the window height when windows are opened or closed and
Bram Moolenaar02467872007-05-06 13:22:01 +00008775 'equalalways' is set. Also for |CTRL-W_=|. Set by default for the
8776 |preview-window| and |quickfix-window|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008777 The height may be changed anyway when running out of room.
8778
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00008779 *'winfixwidth'* *'wfw'* *'nowinfixwidth'* *'nowfw'*
8780'winfixwidth' 'wfw' boolean (default off)
8781 local to window
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00008782 Keep the window width when windows are opened or closed and
Bram Moolenaar02467872007-05-06 13:22:01 +00008783 'equalalways' is set. Also for |CTRL-W_=|.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00008784 The width may be changed anyway when running out of room.
8785
Bram Moolenaar071d4272004-06-13 20:20:40 +00008786 *'winminheight'* *'wmh'*
8787'winminheight' 'wmh' number (default 1)
8788 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008789 The minimal height of a window, when it's not the current window.
8790 This is a hard minimum, windows will never become smaller.
8791 When set to zero, windows may be "squashed" to zero lines (i.e. just a
8792 status bar) if necessary. They will return to at least one line when
8793 they become active (since the cursor has to have somewhere to go.)
8794 Use 'winheight' to set the minimal height of the current window.
8795 This option is only checked when making a window smaller. Don't use a
8796 large number, it will cause errors when opening more than a few
8797 windows. A value of 0 to 3 is reasonable.
8798
8799 *'winminwidth'* *'wmw'*
8800'winminwidth' 'wmw' number (default 1)
8801 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008802 The minimal width of a window, when it's not the current window.
8803 This is a hard minimum, windows will never become smaller.
8804 When set to zero, windows may be "squashed" to zero columns (i.e. just
8805 a vertical separator) if necessary. They will return to at least one
8806 line when they become active (since the cursor has to have somewhere
8807 to go.)
8808 Use 'winwidth' to set the minimal width of the current window.
8809 This option is only checked when making a window smaller. Don't use a
8810 large number, it will cause errors when opening more than a few
8811 windows. A value of 0 to 12 is reasonable.
8812
Bram Moolenaar9e13aa72017-08-16 23:14:08 +02008813 *'winptydll'*
8814'winptydll' string (default "winpty32.dll" or "winpty64.dll")
8815 global
Bram Moolenaar9e13aa72017-08-16 23:14:08 +02008816 {only available when compiled with the |terminal|
8817 feature on MS-Windows}
8818 Specifies the name of the winpty shared library, used for the
8819 |:terminal| command. The default depends on whether was build as a
Bram Moolenaarc572da52017-08-27 16:52:01 +02008820 32-bit or 64-bit executable. If not found, "winpty.dll" is tried as
Bram Moolenaar9e13aa72017-08-16 23:14:08 +02008821 a fallback.
8822 Environment variables are expanded |:set_env|.
8823 This option cannot be set from a |modeline| or in the |sandbox|, for
8824 security reasons.
8825
Bram Moolenaar071d4272004-06-13 20:20:40 +00008826 *'winwidth'* *'wiw'* *E592*
8827'winwidth' 'wiw' number (default 20)
8828 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008829 Minimal number of columns for the current window. This is not a hard
8830 minimum, Vim will use fewer columns if there is not enough room. If
8831 the current window is smaller, its size is increased, at the cost of
8832 the width of other windows. Set it to 999 to make the current window
8833 always fill the screen. Set it to a small number for normal editing.
8834 The width is not adjusted after one of the commands to change the
8835 width of the current window.
8836 'winwidth' applies to the current window. Use 'winminwidth' to set
8837 the minimal width for other windows.
8838
8839 *'wrap'* *'nowrap'*
8840'wrap' boolean (default on)
8841 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00008842 This option changes how text is displayed. It doesn't change the text
8843 in the buffer, see 'textwidth' for that.
8844 When on, lines longer than the width of the window will wrap and
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00008845 displaying continues on the next line. When off lines will not wrap
8846 and only part of long lines will be displayed. When the cursor is
Bram Moolenaar071d4272004-06-13 20:20:40 +00008847 moved to a part that is not shown, the screen will scroll
8848 horizontally.
8849 The line will be broken in the middle of a word if necessary. See
8850 'linebreak' to get the break at a word boundary.
8851 To make scrolling horizontally a bit more useful, try this: >
8852 :set sidescroll=5
8853 :set listchars+=precedes:<,extends:>
8854< See 'sidescroll', 'listchars' and |wrap-off|.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01008855 This option can't be set from a |modeline| when the 'diff' option is
8856 on.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008857
8858 *'wrapmargin'* *'wm'*
8859'wrapmargin' 'wm' number (default 0)
8860 local to buffer
8861 Number of characters from the right window border where wrapping
8862 starts. When typing text beyond this limit, an <EOL> will be inserted
8863 and inserting continues on the next line.
8864 Options that add a margin, such as 'number' and 'foldcolumn', cause
8865 the text width to be further reduced. This is Vi compatible.
8866 When 'textwidth' is non-zero, this option is not used.
Bram Moolenaarca635012015-09-25 20:34:21 +02008867 This option is set to 0 when 'paste' is set and restored when 'paste'
8868 is reset.
Bram Moolenaara6c27c42019-05-09 19:16:22 +02008869 See also 'formatoptions' and |ins-textwidth|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008870
8871 *'wrapscan'* *'ws'* *'nowrapscan'* *'nows'*
8872'wrapscan' 'ws' boolean (default on) *E384* *E385*
8873 global
Bram Moolenaarac6e65f2005-08-29 22:25:38 +00008874 Searches wrap around the end of the file. Also applies to |]s| and
8875 |[s|, searching for spelling mistakes.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008876
8877 *'write'* *'nowrite'*
8878'write' boolean (default on)
8879 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008880 Allows writing files. When not set, writing a file is not allowed.
8881 Can be used for a view-only mode, where modifications to the text are
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00008882 still allowed. Can be reset with the |-m| or |-M| command line
Bram Moolenaar071d4272004-06-13 20:20:40 +00008883 argument. Filtering text is still possible, even though this requires
8884 writing a temporary file.
8885
8886 *'writeany'* *'wa'* *'nowriteany'* *'nowa'*
8887'writeany' 'wa' boolean (default off)
8888 global
8889 Allows writing to any file with no need for "!" override.
8890
8891 *'writebackup'* *'wb'* *'nowritebackup'* *'nowb'*
8892'writebackup' 'wb' boolean (default on with |+writebackup| feature, off
8893 otherwise)
8894 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008895 Make a backup before overwriting a file. The backup is removed after
8896 the file was successfully written, unless the 'backup' option is
Bram Moolenaar1aeaf8c2012-05-18 13:46:39 +02008897 also on.
8898 WARNING: Switching this option off means that when Vim fails to write
8899 your buffer correctly and then, for whatever reason, Vim exits, you
8900 lose both the original file and what you were writing. Only reset
8901 this option if your file system is almost full and it makes the write
8902 fail (and make sure not to exit Vim until the write was successful).
8903 See |backup-table| for another explanation.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008904 When the 'backupskip' pattern matches, a backup is not made anyway.
8905 NOTE: This option is set to the default value when 'compatible' is
8906 set.
8907
8908 *'writedelay'* *'wd'*
8909'writedelay' 'wd' number (default 0)
8910 global
Bram Moolenaar802a0d92016-06-26 16:17:58 +02008911 The number of milliseconds to wait for each character sent to the
Bram Moolenaar071d4272004-06-13 20:20:40 +00008912 screen. When non-zero, characters are sent to the terminal one by
8913 one. For MS-DOS pcterm this does not work. For debugging purposes.
8914
Bram Moolenaar91f84f62018-07-29 15:07:52 +02008915 vim:tw=78:ts=8:noet:ft=help:norl: