blob: a11c1f1a1a5b732bbf42f961500e32634d0da67a [file] [log] [blame]
Christian Brabandt5f5131d2023-10-25 21:44:26 +02001*options.txt* For Vim version 9.0. Last change: 2023 Oct 23
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*
Bram Moolenaar6b915c02020-01-18 15:53:19 +010025:se[t][!] Show all options that differ from their default value.
26 When [!] is present every option is on a separate
27 line.
Bram Moolenaar071d4272004-06-13 20:20:40 +000028
Bram Moolenaar6b915c02020-01-18 15:53:19 +010029:se[t][!] all Show all but terminal options.
30 When [!] is present every option is on a separate
31 line.
Bram Moolenaar071d4272004-06-13 20:20:40 +000032
33:se[t] termcap Show all terminal options. Note that in the GUI the
34 key codes are not shown, because they are generated
35 internally and can't be changed. Changing the terminal
36 codes in the GUI is not useful either...
Bram Moolenaarf1dcd142022-12-31 15:30:45 +000037 The options have the form t_AB, see
38 |terminal-options|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000039
Bram Moolenaar47003982021-12-05 21:54:04 +000040:se[t]! termcap Idem, but don't use multiple columns.
41
Bram Moolenaar071d4272004-06-13 20:20:40 +000042 *E518* *E519*
43:se[t] {option}? Show value of {option}.
44
45:se[t] {option} Toggle option: set, switch it on.
46 Number option: show value.
47 String option: show value.
48
49:se[t] no{option} Toggle option: Reset, switch it off.
50
Bram Moolenaar00a927d2010-05-14 23:24:24 +020051 *:set-!* *:set-inv*
Bram Moolenaar071d4272004-06-13 20:20:40 +000052:se[t] {option}! or
Bram Moolenaar6c60f472019-04-28 16:00:35 +020053:se[t] inv{option} Toggle option: Invert value.
Bram Moolenaar071d4272004-06-13 20:20:40 +000054
55 *:set-default* *:set-&* *:set-&vi* *:set-&vim*
56:se[t] {option}& Reset option to its default value. May depend on the
Bram Moolenaar6c60f472019-04-28 16:00:35 +020057 current value of 'compatible'.
58:se[t] {option}&vi Reset option to its Vi default value.
59:se[t] {option}&vim Reset option to its Vim default value.
Bram Moolenaar071d4272004-06-13 20:20:40 +000060
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +010061:se[t] all& Set all options to their default value. The values of
Bram Moolenaar88774fd2015-08-25 19:52:04 +020062 these options are not changed:
63 all terminal options, starting with t_
64 'columns'
65 'cryptmethod'
66 'encoding'
67 'key'
68 'lines'
69 'term'
70 'ttymouse'
71 'ttytype'
72 Warning: This may have a lot of side effects.
Bram Moolenaar071d4272004-06-13 20:20:40 +000073
h_east59858792023-10-25 22:47:05 +090074 *:set-args* *:set=* *E487* *E521*
Bram Moolenaar071d4272004-06-13 20:20:40 +000075:se[t] {option}={value} or
76:se[t] {option}:{value}
77 Set string or number option to {value}.
78 For numeric options the value can be given in decimal,
Bram Moolenaar3848e002016-03-19 18:42:29 +010079 hex (preceded with 0x) or octal (preceded with '0').
Bram Moolenaar071d4272004-06-13 20:20:40 +000080 The old value can be inserted by typing 'wildchar' (by
81 default this is a <Tab> or CTRL-E if 'compatible' is
Yee Cheng Chin900894b2023-09-29 20:42:32 +020082 set). Many string options with fixed syntax and names
83 also support completing known values. See
84 |cmdline-completion| and |complete-set-option|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000085 White space between {option} and '=' is allowed and
86 will be ignored. White space between '=' and {value}
87 is not allowed.
88 See |option-backslash| for using white space and
89 backslashes in {value}.
90
91:se[t] {option}+={value} *:set+=*
92 Add the {value} to a number option, or append the
93 {value} to a string option. When the option is a
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +010094 comma-separated list, a comma is added, unless the
Bram Moolenaar071d4272004-06-13 20:20:40 +000095 value was empty.
96 If the option is a list of flags, superfluous flags
Bram Moolenaara5792f52005-11-23 21:25:05 +000097 are removed. When adding a flag that was already
98 present the option value doesn't change.
Bram Moolenaar899dddf2006-03-26 21:06:50 +000099 Also see |:set-args| above.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000100
101:se[t] {option}^={value} *:set^=*
102 Multiply the {value} to a number option, or prepend
103 the {value} to a string option. When the option is a
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +0100104 comma-separated list, a comma is added, unless the
Bram Moolenaar071d4272004-06-13 20:20:40 +0000105 value was empty.
106 Also see |:set-args| above.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000107
108:se[t] {option}-={value} *:set-=*
109 Subtract the {value} from a number option, or remove
110 the {value} from a string option, if it is there.
111 If the {value} is not found in a string option, there
112 is no error or warning. When the option is a comma
113 separated list, a comma is deleted, unless the option
114 becomes empty.
115 When the option is a list of flags, {value} must be
116 exactly as they appear in the option. Remove flags
117 one by one to avoid problems.
Yee Cheng Chin900894b2023-09-29 20:42:32 +0200118 The individual values from a comma separated list or
119 list of flags can be inserted by typing 'wildchar'.
120 See |complete-set-option|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000121 Also see |:set-args| above.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000122
123The {option} arguments to ":set" may be repeated. For example: >
124 :set ai nosi sw=3 ts=3
125If you make an error in one of the arguments, an error message will be given
126and the following arguments will be ignored.
127
128 *:set-verbose*
129When 'verbose' is non-zero, displaying an option value will also tell where it
130was last set. Example: >
131 :verbose set shiftwidth cindent?
Bram Moolenaar95bafa22018-10-02 13:26:25 +0200132< shiftwidth=4 ~
133 Last set from modeline line 1 ~
134 cindent ~
135 Last set from /usr/local/share/vim/vim60/ftplugin/c.vim line 30 ~
Bram Moolenaar446cb832008-06-24 21:56:24 +0000136This is only done when specific option values are requested, not for ":verbose
137set all" or ":verbose set" without an argument.
138When the option was set by hand there is no "Last set" message.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000139When the option was set while executing a function, user command or
140autocommand, the script in which it was defined is reported.
141Note that an option may also have been set as a side effect of setting
142'compatible'.
Bram Moolenaar446cb832008-06-24 21:56:24 +0000143A few special texts:
Bram Moolenaar95bafa22018-10-02 13:26:25 +0200144 Last set from modeline line 1 ~
Bram Moolenaar446cb832008-06-24 21:56:24 +0000145 Option was set in a |modeline|.
146 Last set from --cmd argument ~
147 Option was set with command line argument |--cmd| or +.
148 Last set from -c argument ~
149 Option was set with command line argument |-c|, +, |-S| or
150 |-q|.
151 Last set from environment variable ~
152 Option was set from an environment variable, $VIMINIT,
153 $GVIMINIT or $EXINIT.
154 Last set from error handler ~
155 Option was cleared when evaluating it resulted in an error.
156
Bram Moolenaardb84e452010-08-15 13:50:43 +0200157{not available when compiled without the |+eval| feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +0000158
159 *:set-termcap* *E522*
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +0000160For {option} the form "t_xx" may be used to set a terminal option. This will
Bram Moolenaar071d4272004-06-13 20:20:40 +0000161override the value from the termcap. You can then use it in a mapping. If
162the "xx" part contains special characters, use the <t_xx> form: >
163 :set <t_#4>=^[Ot
164This can also be used to translate a special code for a normal key. For
165example, if Alt-b produces <Esc>b, use this: >
166 :set <M-b>=^[b
167(the ^[ is a real <Esc> here, use CTRL-V <Esc> to enter it)
168The advantage over a mapping is that it works in all situations.
169
Bram Moolenaar0b2f94d2011-03-22 14:35:05 +0100170You can define any key codes, e.g.: >
171 :set t_xy=^[foo;
172There is no warning for using a name that isn't recognized. You can map these
173codes as you like: >
174 :map <t_xy> something
175< *E846*
176When a key code is not set, it's like it does not exist. Trying to get its
177value will result in an error: >
178 :set t_kb=
179 :set t_kb
Bram Moolenaar6f4754b2022-01-23 12:07:04 +0000180< E846: Key code not set: t_kb ~
Bram Moolenaar0b2f94d2011-03-22 14:35:05 +0100181
Bram Moolenaar293ee4d2004-12-09 21:34:53 +0000182The t_xx options cannot be set from a |modeline| or in the |sandbox|, for
183security reasons.
184
Bram Moolenaar071d4272004-06-13 20:20:40 +0000185The listing from ":set" looks different from Vi. Long string options are put
Bram Moolenaarf4b8e572004-06-24 15:53:16 +0000186at the end of the list. The number of options is quite large. The output of
Bram Moolenaar071d4272004-06-13 20:20:40 +0000187"set all" probably does not fit on the screen, causing Vim to give the
188|more-prompt|.
189
190 *option-backslash*
191To include white space in a string option value it has to be preceded with a
192backslash. To include a backslash you have to use two. Effectively this
193means that the number of backslashes in an option value is halved (rounded
194down).
Yee Cheng Chin54844852023-10-09 18:12:31 +0200195In options 'path', 'cdpath', and 'tags', spaces have to be preceded with three
196backslashes instead for compatibility with version 3.0 where the options can
197be separated by either commas or spaces.
198Comma-separated options like 'backupdir' and 'tags' will also require commas
199to be escaped with two backslashes, whereas this is not needed for
200non-comma-separated ones like 'makeprg'.
201When setting options using |:let| and |literal-string|, you need to use one
202fewer layer of backslash.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000203A few examples: >
Yee Cheng Chin54844852023-10-09 18:12:31 +0200204 :set makeprg=make\ file results in "make file"
205 :let &makeprg='make file' (same as above)
206 :set makeprg=make\\\ file results in "make\ file"
207 :set tags=tags\ /usr/tags results in "tags" and "/usr/tags"
208 :set tags=tags\\\ file results in "tags file"
209 :let &tags='tags\ file' (same as above)
210
211 :set makeprg=make,file results in "make,file"
212 :set makeprg=make\\,file results in "make\,file"
213 :set tags=tags,file results in "tags" and "file"
214 :set tags=tags\\,file results in "tags,file"
215 :let &tags='tags\,file' (same as above)
Bram Moolenaar071d4272004-06-13 20:20:40 +0000216
Bram Moolenaarf4b8e572004-06-24 15:53:16 +0000217The "|" character separates a ":set" command from a following command. To
218include the "|" in the option value, use "\|" instead. This example sets the
Bram Moolenaar071d4272004-06-13 20:20:40 +0000219'titlestring' option to "hi|there": >
220 :set titlestring=hi\|there
221This sets the 'titlestring' option to "hi" and 'iconstring' to "there": >
222 :set titlestring=hi|set iconstring=there
223
Bram Moolenaar89a9c152021-08-29 21:55:35 +0200224Similarly, in legacy script the double quote character starts a comment. To
225include the '"' in the option value, use '\"' instead. This example sets the
226'titlestring' option to 'hi "there"': >
Bram Moolenaar7df351e2006-01-23 22:30:28 +0000227 :set titlestring=hi\ \"there\"
228
Bram Moolenaar89a9c152021-08-29 21:55:35 +0200229In |Vim9| script it's simpler, comments start with a '#' character, and only
230when preceded by white space. A backslash is needed less often: >
231 vim9script
232 set titlestring=hi\ "there"
233 set titlestring=hi#there#
234 set titlestring=hi\ \#there#
235
Bram Moolenaar5666fcd2019-12-26 14:35:26 +0100236For Win32 backslashes in file names are mostly not removed. More precise: For
237options that expect a file name (those where environment variables are
238expanded) a backslash before a normal file name character is not removed. But
239a backslash before a special character (space, backslash, comma, etc.) is used
240like explained above.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000241There is one special situation, when the value starts with "\\": >
242 :set dir=\\machine\path results in "\\machine\path"
243 :set dir=\\\\machine\\path results in "\\machine\path"
244 :set dir=\\path\\file results in "\\path\file" (wrong!)
245For the first one the start is kept, but for the second one the backslashes
246are halved. This makes sure it works both when you expect backslashes to be
Bram Moolenaarf4b8e572004-06-24 15:53:16 +0000247halved and when you expect the backslashes to be kept. The third gives a
Bram Moolenaar071d4272004-06-13 20:20:40 +0000248result which is probably not what you want. Avoid it.
249
250 *add-option-flags* *remove-option-flags*
251 *E539* *E550* *E551* *E552*
252Some options are a list of flags. When you want to add a flag to such an
253option, without changing the existing ones, you can do it like this: >
254 :set guioptions+=a
255Remove a flag from an option like this: >
256 :set guioptions-=a
257This removes the 'a' flag from 'guioptions'.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +0000258Note that you should add or remove one flag at a time. If 'guioptions' has
Bram Moolenaar071d4272004-06-13 20:20:40 +0000259the value "ab", using "set guioptions-=ba" won't work, because the string "ba"
260doesn't appear.
261
262 *:set_env* *expand-env* *expand-environment-var*
Bram Moolenaard4755bb2004-09-02 19:12:26 +0000263Environment variables in specific string options will be expanded. If the
Bram Moolenaar071d4272004-06-13 20:20:40 +0000264environment variable exists the '$' and the following environment variable
265name is replaced with its value. If it does not exist the '$' and the name
266are not modified. Any non-id character (not a letter, digit or '_') may
267follow the environment variable name. That character and what follows is
268appended to the value of the environment variable. Examples: >
269 :set term=$TERM.new
270 :set path=/usr/$INCLUDE,$HOME/include,.
271When adding or removing a string from an option with ":set opt-=val" or ":set
272opt+=val" the expansion is done before the adding or removing.
273
274
275Handling of local options *local-options*
276
Christian Brabandt4a8eb6e2023-08-13 19:43:42 +0200277Note: The following also applies to |global-local| options.
278
Bram Moolenaar071d4272004-06-13 20:20:40 +0000279Some of the options only apply to a window or buffer. Each window or buffer
Bram Moolenaar51628222016-12-01 23:03:28 +0100280has its own copy of this option, thus each can have its own value. This
Bram Moolenaar071d4272004-06-13 20:20:40 +0000281allows you to set 'list' in one window but not in another. And set
282'shiftwidth' to 3 in one buffer and 4 in another.
283
284The following explains what happens to these local options in specific
285situations. You don't really need to know all of this, since Vim mostly uses
286the option values you would expect. Unfortunately, doing what the user
287expects is a bit complicated...
288
289When splitting a window, the local options are copied to the new window. Thus
290right after the split the contents of the two windows look the same.
291
292When editing a new buffer, its local option values must be initialized. Since
293the local options of the current buffer might be specifically for that buffer,
294these are not used. Instead, for each buffer-local option there also is a
295global value, which is used for new buffers. With ":set" both the local and
296global value is changed. With "setlocal" only the local value is changed,
297thus this value is not used when editing a new buffer.
298
Bram Moolenaar95ec9d62016-08-12 18:29:59 +0200299When editing a buffer that has been edited before, the options from the window
300that was last closed are used again. If this buffer has been edited in this
301window, the values from back then are used. Otherwise the values from the
302last closed window where the buffer was edited last are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000303
304It's possible to set a local window option specifically for a type of buffer.
305When you edit another buffer in the same window, you don't want to keep
306using these local window options. Therefore Vim keeps a global value of the
307local window options, which is used when editing another buffer. Each window
308has its own copy of these values. Thus these are local to the window, but
309global to all buffers in the window. With this you can do: >
310 :e one
311 :set list
312 :e two
313Now the 'list' option will also be set in "two", since with the ":set list"
314command you have also set the global value. >
315 :set nolist
316 :e one
317 :setlocal list
318 :e two
319Now the 'list' option is not set, because ":set nolist" resets the global
320value, ":setlocal list" only changes the local value and ":e two" gets the
321global value. Note that if you do this next: >
322 :e one
Bram Moolenaar531da592013-05-06 05:58:55 +0200323You will get back the 'list' value as it was the last time you edited "one".
324The options local to a window are remembered for each buffer. This also
325happens when the buffer is not loaded, but they are lost when the buffer is
326wiped out |:bwipe|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000327
Christian Brabandt596ad662023-08-16 00:11:09 +0200328Special local window options *local-noglobal*
Christian Brabandt4a8eb6e2023-08-13 19:43:42 +0200329
330The following local window options won't be copied over when new windows are
331created, thus they behave slightly differently:
332
333 Option Reason ~
334 'previewwindow' there can only be a single one
335 'scroll' specific to existing window
336 'winfixheight' specific to existing window
337 'winfixwidth' specific to existing window
338
Christian Brabandt596ad662023-08-16 00:11:09 +0200339Special local buffer options
Christian Brabandt4a8eb6e2023-08-13 19:43:42 +0200340
341The following local buffer options won't be copied over when new buffers are
342created, thus they behave slightly differently:
343
344 Option Reason ~
345 'filetype' explicitly set by autocommands
346 'syntax' explicitly set by autocommands
347 'bufhidden' denote |special-buffers|
348 'buftype' denote |special-buffers|
349 'readonly' will be detected automatically
350 'modified' will be detected automatically
351
Bram Moolenaar071d4272004-06-13 20:20:40 +0000352 *:setl* *:setlocal*
Bram Moolenaar6b915c02020-01-18 15:53:19 +0100353:setl[ocal][!] ... Like ":set" but set only the value local to the
Bram Moolenaar071d4272004-06-13 20:20:40 +0000354 current buffer or window. Not all options have a
355 local value. If the option does not have a local
356 value the global value is set.
Bram Moolenaarc3301872010-07-25 20:53:06 +0200357 With the "all" argument: display local values for all
358 local options.
359 Without argument: Display local values for all local
360 options which are different from the default.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000361 When displaying a specific local option, show the
Bram Moolenaar446cb832008-06-24 21:56:24 +0000362 local value. For a global/local boolean option, when
363 the global value is being used, "--" is displayed
364 before the option name.
365 For a global option the global value is
Bram Moolenaar071d4272004-06-13 20:20:40 +0000366 shown (but that might change in the future).
Bram Moolenaar071d4272004-06-13 20:20:40 +0000367
Bram Moolenaar899dddf2006-03-26 21:06:50 +0000368:setl[ocal] {option}< Set the local value of {option} to its global value by
369 copying the value.
Bram Moolenaar899dddf2006-03-26 21:06:50 +0000370
Bram Moolenaar6be7f872012-01-20 21:08:56 +0100371:se[t] {option}< For |global-local| options: Remove the local value of
372 {option}, so that the global value will be used.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000373
374 *:setg* *:setglobal*
Bram Moolenaar6b915c02020-01-18 15:53:19 +0100375:setg[lobal][!] ... Like ":set" but set only the global value for a local
Bram Moolenaar071d4272004-06-13 20:20:40 +0000376 option without changing the local value.
377 When displaying an option, the global value is shown.
Bram Moolenaarc3301872010-07-25 20:53:06 +0200378 With the "all" argument: display global values for all
379 local options.
380 Without argument: display global values for all local
381 options which are different from the default.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000382
383For buffer-local and window-local options:
384 Command global value local value ~
385 :set option=value set set
386 :setlocal option=value - set
387:setglobal option=value set -
388 :set option? - display
389 :setlocal option? - display
390:setglobal option? display -
391
392
393Global options with a local value *global-local*
394
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +0000395Options are global when you mostly use one value for all buffers and windows.
396For some global options it's useful to sometimes have a different local value.
397You can set the local value with ":setlocal". That buffer or window will then
398use the local value, while other buffers and windows continue using the global
399value.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000400
401For example, you have two windows, both on C source code. They use the global
402'makeprg' option. If you do this in one of the two windows: >
403 :set makeprg=gmake
404then the other window will switch to the same value. There is no need to set
405the 'makeprg' option in the other C source window too.
406However, if you start editing a Perl file in a new window, you want to use
Bram Moolenaar02467872007-05-06 13:22:01 +0000407another 'makeprg' for it, without changing the value used for the C source
Bram Moolenaarf4b8e572004-06-24 15:53:16 +0000408files. You use this command: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000409 :setlocal makeprg=perlmake
410You can switch back to using the global value by making the local value empty: >
411 :setlocal makeprg=
Bram Moolenaar314dd792019-02-03 15:27:20 +0100412This only works for a string option. For a number or boolean option you need
413to use the "<" flag, like this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000414 :setlocal autoread<
Bram Moolenaar314dd792019-02-03 15:27:20 +0100415Note that for non-boolean and non-number options using "<" copies the global
416value to the local value, it doesn't switch back to using the global value
417(that matters when the global value changes later). You can also use: >
Bram Moolenaar899dddf2006-03-26 21:06:50 +0000418 :set path<
419This will make the local value of 'path' empty, so that the global value is
420used. Thus it does the same as: >
421 :setlocal path=
Bram Moolenaar2f0936c2022-01-08 21:51:59 +0000422Note: In the future more global options can be made |global-local|. Using
Bram Moolenaar071d4272004-06-13 20:20:40 +0000423":setlocal" on a global option might work differently then.
424
Yegappan Lakshmanan777175b2021-11-18 22:08:57 +0000425 *option-value-function*
426Some options ('completefunc', 'imactivatefunc', 'imstatusfunc', 'omnifunc',
Yegappan Lakshmanan8658c752021-12-03 11:09:29 +0000427'operatorfunc', 'quickfixtextfunc', 'tagfunc' and 'thesaurusfunc') are set to
Yegappan Lakshmanan64095532021-12-06 11:03:55 +0000428a function name or a function reference or a lambda function. When using a
429lambda it will be converted to the name, e.g. "<lambda>123". Examples:
Yegappan Lakshmanan777175b2021-11-18 22:08:57 +0000430>
431 set opfunc=MyOpFunc
Yegappan Lakshmanan19916a82021-11-24 16:32:55 +0000432 set opfunc=function('MyOpFunc')
433 set opfunc=funcref('MyOpFunc')
Yegappan Lakshmanan05e59e32021-12-01 10:30:07 +0000434 set opfunc={a\ ->\ MyOpFunc(a)}
Bram Moolenaar1fca5f32022-02-18 17:50:47 +0000435
436Set to a script-local function: >
437 set opfunc=s:MyLocalFunc
438 set opfunc=<SID>MyLocalFunc
439In |Vim9| script the "s:" and "<SID>" can be omitted if the function exists in
440the script: >
441 set opfunc=MyLocalFunc
442
443Set using a funcref variable: >
Yegappan Lakshmanan05e59e32021-12-01 10:30:07 +0000444 let Fn = function('MyTagFunc')
Bram Moolenaarfa3b7232021-12-24 13:18:38 +0000445 let &tagfunc = Fn
Bram Moolenaar1fca5f32022-02-18 17:50:47 +0000446
447Set using a lambda expression: >
Yegappan Lakshmanan64095532021-12-06 11:03:55 +0000448 let &tagfunc = {t -> MyTagFunc(t)}
Bram Moolenaar1fca5f32022-02-18 17:50:47 +0000449
450Set using a variable with lambda expression: >
Yegappan Lakshmanan05e59e32021-12-01 10:30:07 +0000451 let L = {a, b, c -> MyTagFunc(a, b , c)}
Yegappan Lakshmanan64095532021-12-06 11:03:55 +0000452 let &tagfunc = L
Bram Moolenaar7b1463b2021-12-11 17:24:39 +0000453
454In Vim9 script, in a compiled function, you can use a lambda, but a
Aliaksei Budaveib043ff32023-10-03 17:39:53 +0300455closure does not work, because the function will be called without the
Bram Moolenaar7b1463b2021-12-11 17:24:39 +0000456context of where it was defined.
457
Yegappan Lakshmanan777175b2021-11-18 22:08:57 +0000458
Bram Moolenaar071d4272004-06-13 20:20:40 +0000459Setting the filetype
460
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +0200461:setf[iletype] [FALLBACK] {filetype} *:setf* *:setfiletype*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000462 Set the 'filetype' option to {filetype}, but only if
463 not done yet in a sequence of (nested) autocommands.
464 This is short for: >
465 :if !did_filetype()
466 : setlocal filetype={filetype}
467 :endif
468< This command is used in a filetype.vim file to avoid
469 setting the 'filetype' option twice, causing different
470 settings and syntax files to be loaded.
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +0200471
472 When the optional FALLBACK argument is present, a
473 later :setfiletype command will override the
Bram Moolenaar26967612019-03-17 17:13:16 +0100474 'filetype'. This is to be used for filetype
475 detections that are just a guess. |did_filetype()|
476 will return false after this command.
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +0200477
Bram Moolenaard58e9292011-02-09 17:07:58 +0100478 *option-window* *optwin*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000479:bro[wse] se[t] *:set-browse* *:browse-set* *:opt* *:options*
480:opt[ions] Open a window for viewing and setting all options.
481 Options are grouped by function.
482 Offers short help for each option. Hit <CR> on the
483 short help to open a help window with more help for
484 the option.
485 Modify the value of the option and hit <CR> on the
486 "set" line to set the new value. For window and
487 buffer specific options, the last accessed window is
488 used to set the option value in, unless this is a help
489 window, in which case the window below help window is
490 used (skipping the option-window).
Bram Moolenaarb5b75622018-03-09 22:22:21 +0100491 {not available when compiled without the |+eval|
492 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +0000493
494 *$HOME*
495Using "~" is like using "$HOME", but it is only recognized at the start of an
496option and after a space or comma.
497
498On Unix systems "~user" can be used too. It is replaced by the home directory
499of user "user". Example: >
500 :set path=~mool/include,/usr/include,.
501
502On Unix systems the form "${HOME}" can be used too. The name between {} can
503contain non-id characters then. Note that if you want to use this for the
504"gf" command, you need to add the '{' and '}' characters to 'isfname'.
505
506NOTE: expanding environment variables and "~/" is only done with the ":set"
507command, not when assigning a value to an option with ":let".
508
Bram Moolenaarc572da52017-08-27 16:52:01 +0200509 *$HOME-windows*
510On MS-Windows, if $HOME is not defined as an environment variable, then
511at runtime Vim will set it to the expansion of $HOMEDRIVE$HOMEPATH.
Bram Moolenaar37c64c72017-09-19 22:06:03 +0200512If $HOMEDRIVE is not set then $USERPROFILE is used.
513
514This expanded value is not exported to the environment, this matters when
515running an external command: >
516 :echo system('set | findstr ^HOME=')
517and >
518 :echo luaeval('os.getenv("HOME")')
519should echo nothing (an empty string) despite exists('$HOME') being true.
520When setting $HOME to a non-empty string it will be exported to the
521subprocesses.
Bram Moolenaarc572da52017-08-27 16:52:01 +0200522
Bram Moolenaar071d4272004-06-13 20:20:40 +0000523
524Note the maximum length of an expanded option is limited. How much depends on
525the system, mostly it is something like 256 or 1024 characters.
526
527 *:fix* *:fixdel*
528:fix[del] Set the value of 't_kD':
529 't_kb' is 't_kD' becomes ~
530 CTRL-? CTRL-H
531 not CTRL-? CTRL-?
532
Bram Moolenaar82be4842021-01-11 19:40:15 +0100533 (CTRL-? is 0o177 octal, 0x7f hex)
Bram Moolenaar071d4272004-06-13 20:20:40 +0000534
535 If your delete key terminal code is wrong, but the
536 code for backspace is alright, you can put this in
537 your .vimrc: >
538 :fixdel
539< This works no matter what the actual code for
540 backspace is.
541
542 If the backspace key terminal code is wrong you can
543 use this: >
544 :if &term == "termname"
545 : set t_kb=^V<BS>
546 : fixdel
547 :endif
548< Where "^V" is CTRL-V and "<BS>" is the backspace key
Bram Moolenaarf4b8e572004-06-24 15:53:16 +0000549 (don't type four characters!). Replace "termname"
Bram Moolenaar071d4272004-06-13 20:20:40 +0000550 with your terminal name.
551
552 If your <Delete> key sends a strange key sequence (not
553 CTRL-? or CTRL-H) you cannot use ":fixdel". Then use: >
554 :if &term == "termname"
555 : set t_kD=^V<Delete>
556 :endif
557< Where "^V" is CTRL-V and "<Delete>" is the delete key
558 (don't type eight characters!). Replace "termname"
559 with your terminal name.
560
561 *Linux-backspace*
562 Note about Linux: By default the backspace key
563 produces CTRL-?, which is wrong. You can fix it by
564 putting this line in your rc.local: >
565 echo "keycode 14 = BackSpace" | loadkeys
566<
567 *NetBSD-backspace*
568 Note about NetBSD: If your backspace doesn't produce
569 the right code, try this: >
570 xmodmap -e "keycode 22 = BackSpace"
571< If this works, add this in your .Xmodmap file: >
572 keysym 22 = BackSpace
573< You need to restart for this to take effect.
574
575==============================================================================
5762. Automatically setting options *auto-setting*
577
578Besides changing options with the ":set" command, there are three alternatives
579to set options automatically for one or more files:
580
5811. When starting Vim initializations are read from various places. See
582 |initialization|. Most of them are performed for all editing sessions,
583 and some of them depend on the directory where Vim is started.
584 You can create an initialization file with |:mkvimrc|, |:mkview| and
585 |:mksession|.
5862. If you start editing a new file, the automatic commands are executed.
587 This can be used to set options for files matching a particular pattern and
588 many other things. See |autocommand|.
5893. If you start editing a new file, and the 'modeline' option is on, a
590 number of lines at the beginning and end of the file are checked for
591 modelines. This is explained here.
592
593 *modeline* *vim:* *vi:* *ex:* *E520*
594There are two forms of modelines. The first form:
Bram Moolenaar664f3cf2019-12-07 16:03:51 +0100595 [text{white}]{vi:|vim:|ex:}[white]{options}
Bram Moolenaar071d4272004-06-13 20:20:40 +0000596
Bram Moolenaar664f3cf2019-12-07 16:03:51 +0100597[text{white}] empty or any text followed by at least one blank
598 character (<Space> or <Tab>); "ex:" always requires at
599 least one blank character
Bram Moolenaar14b69452013-06-29 23:05:20 +0200600{vi:|vim:|ex:} the string "vi:", "vim:" or "ex:"
Bram Moolenaar22dbc772013-06-28 18:44:48 +0200601[white] optional white space
602{options} a list of option settings, separated with white space
603 or ':', where each part between ':' is the argument
604 for a ":set" command (can be empty)
Bram Moolenaar071d4272004-06-13 20:20:40 +0000605
Bram Moolenaar14b69452013-06-29 23:05:20 +0200606Examples:
Bram Moolenaar97b2ad32006-03-18 21:40:56 +0000607 vi:noai:sw=3 ts=6 ~
Bram Moolenaar14b69452013-06-29 23:05:20 +0200608 vim: tw=77 ~
Bram Moolenaar071d4272004-06-13 20:20:40 +0000609
610The second form (this is compatible with some versions of Vi):
611
Bram Moolenaarade0d392020-01-21 22:33:58 +0100612 [text{white}]{vi:|vim:|Vim:|ex:}[white]se[t] {options}:[text]
Bram Moolenaar071d4272004-06-13 20:20:40 +0000613
Bram Moolenaarade0d392020-01-21 22:33:58 +0100614[text{white}] empty or any text followed by at least one blank
615 character (<Space> or <Tab>); "ex:" always requires at
616 least one blank character
Bram Moolenaar22dbc772013-06-28 18:44:48 +0200617{vi:|vim:|Vim:|ex:} the string "vi:", "vim:", "Vim:" or "ex:"
618[white] optional white space
Bram Moolenaar14b69452013-06-29 23:05:20 +0200619se[t] the string "set " or "se " (note the space); When
620 "Vim" is used it must be "set".
Bram Moolenaar22dbc772013-06-28 18:44:48 +0200621{options} a list of options, separated with white space, which
622 is the argument for a ":set" command
623: a colon
624[text] any text or empty
Bram Moolenaar071d4272004-06-13 20:20:40 +0000625
Bram Moolenaar14b69452013-06-29 23:05:20 +0200626Examples:
Bram Moolenaar97b2ad32006-03-18 21:40:56 +0000627 /* vim: set ai tw=75: */ ~
Bram Moolenaar14b69452013-06-29 23:05:20 +0200628 /* Vim: set ai tw=75: */ ~
Bram Moolenaar071d4272004-06-13 20:20:40 +0000629
Bram Moolenaar22dbc772013-06-28 18:44:48 +0200630The white space before {vi:|vim:|Vim:|ex:} is required. This minimizes the
631chance that a normal word like "lex:" is caught. There is one exception:
632"vi:" and "vim:" can also be at the start of the line (for compatibility with
633version 3.0). Using "ex:" at the start of the line will be ignored (this
634could be short for "example:").
Bram Moolenaar071d4272004-06-13 20:20:40 +0000635
Hu Jialun9dcd3492021-08-28 20:42:50 +0200636If the modeline is disabled within a modeline, subsequent modelines will be
637ignored. This is to allow turning off modeline on a per-file basis. This is
638useful when a line looks like a modeline but isn't. For example, it would be
639good to start a YAML file containing strings like "vim:" with
640 # vim: nomodeline ~
641so as to avoid modeline misdetection. Following options on the same line
642after modeline deactivation, if any, are still evaluated (but you would
643normally not have any).
644
Bram Moolenaar071d4272004-06-13 20:20:40 +0000645 *modeline-local*
646The options are set like with ":setlocal": The new value only applies to the
Bram Moolenaar843ee412004-06-30 16:16:41 +0000647buffer and window that contain the file. Although it's possible to set global
648options from a modeline, this is unusual. If you have two windows open and
649the files in it set the same global option to a different value, the result
650depends on which one was opened last.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000651
Bram Moolenaar15d0a8c2004-09-06 17:44:46 +0000652When editing a file that was already loaded, only the window-local options
653from the modeline are used. Thus if you manually changed a buffer-local
654option after opening the file, it won't be changed if you edit the same buffer
655in another window. But window-local options will be set.
656
Bram Moolenaar071d4272004-06-13 20:20:40 +0000657 *modeline-version*
658If the modeline is only to be used for some versions of Vim, the version
Bram Moolenaar22dbc772013-06-28 18:44:48 +0200659number can be specified where "vim:" or "Vim:" is used:
Bram Moolenaar071d4272004-06-13 20:20:40 +0000660 vim{vers}: version {vers} or later
661 vim<{vers}: version before {vers}
662 vim={vers}: version {vers}
663 vim>{vers}: version after {vers}
Bram Moolenaar2b8388b2015-02-28 13:11:45 +0100664{vers} is 700 for Vim 7.0 (hundred times the major version plus minor).
665For example, to use a modeline only for Vim 7.0:
666 /* vim700: set foldmethod=marker */ ~
667To use a modeline for Vim after version 7.2:
668 /* vim>702: set cole=2: */ ~
Bram Moolenaar071d4272004-06-13 20:20:40 +0000669There can be no blanks between "vim" and the ":".
670
671
672The number of lines that are checked can be set with the 'modelines' option.
673If 'modeline' is off or 'modelines' is 0 no lines are checked.
674
675Note that for the first form all of the rest of the line is used, thus a line
Bram Moolenaar97b2ad32006-03-18 21:40:56 +0000676like:
677 /* vi:ts=4: */ ~
678will give an error message for the trailing "*/". This line is OK:
679 /* vi:set ts=4: */ ~
Bram Moolenaar071d4272004-06-13 20:20:40 +0000680
681If an error is detected the rest of the line is skipped.
682
683If you want to include a ':' in a set command precede it with a '\'. The
Bram Moolenaar97b2ad32006-03-18 21:40:56 +0000684backslash in front of the ':' will be removed. Example:
Bram Moolenaar95a9dd12019-12-19 22:12:03 +0100685 /* vi:set fillchars=stl\:^,vert\:\|: */ ~
686This sets the 'fillchars' option to "stl:^,vert:\|". Only a single backslash
687before the ':' is removed. Thus to include "\:" you have to specify "\\:".
Bram Moolenaar110289e2019-05-23 15:38:06 +0200688 *E992*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000689No other commands than "set" are supported, for security reasons (somebody
Bram Moolenaar8243a792007-05-01 17:05:03 +0000690might create a Trojan horse text file with modelines). And not all options
Bram Moolenaar110289e2019-05-23 15:38:06 +0200691can be set. For some options a flag is set, so that when the value is used
692the |sandbox| is effective. Some options can only be set from the modeline
693when 'modelineexpr' is set (the default is off).
694
695Still, there is always a small risk that a modeline causes trouble. E.g.,
696when some joker sets 'textwidth' to 5 all your lines are wrapped unexpectedly.
697So disable modelines before editing untrusted text. The mail ftplugin does
698this, for example.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000699
700Hint: If you would like to do something else than setting an option, you could
701define an autocommand that checks the file for a specific string. For
702example: >
703 au BufReadPost * if getline(1) =~ "VAR" | call SetVar() | endif
704And define a function SetVar() that does something with the line containing
705"VAR".
706
707==============================================================================
7083. Options summary *option-summary*
709
710In the list below all the options are mentioned with their full name and with
711an abbreviation if there is one. Both forms may be used.
712
713In this document when a boolean option is "set" that means that ":set option"
714is entered. When an option is "reset", ":set nooption" is used.
715
716For some options there are two default values: The "Vim default", which is
717used when 'compatible' is not set, and the "Vi default", which is used when
718'compatible' is set.
719
720Most options are the same in all windows and buffers. There are a few that
Bram Moolenaarf4b8e572004-06-24 15:53:16 +0000721are specific to how the text is presented in a window. These can be set to a
Bram Moolenaar071d4272004-06-13 20:20:40 +0000722different value in each window. For example the 'list' option can be set in
723one window and reset in another for the same text, giving both types of view
724at the same time. There are a few options that are specific to a certain
725file. These can have a different value for each file or buffer. For example
726the 'textwidth' option can be 78 for a normal text file and 0 for a C
727program.
728
729 global one option for all buffers and windows
730 local to window each window has its own copy of this option
731 local to buffer each buffer has its own copy of this option
732
733When creating a new window the option values from the currently active window
734are used as a default value for the window-specific options. For the
735buffer-specific options this depends on the 's' and 'S' flags in the
736'cpoptions' option. If 's' is included (which is the default) the values for
737buffer options are copied from the currently active buffer when a buffer is
Bram Moolenaarf4b8e572004-06-24 15:53:16 +0000738first entered. If 'S' is present the options are copied each time the buffer
739is entered, this is almost like having global options. If 's' and 'S' are not
Bram Moolenaar071d4272004-06-13 20:20:40 +0000740present, the options are copied from the currently active buffer when the
741buffer is created.
742
Bram Moolenaar578b49e2005-09-10 19:22:57 +0000743Hidden options *hidden-options*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000744
Bram Moolenaar578b49e2005-09-10 19:22:57 +0000745Not all options are supported in all versions. This depends on the supported
746features and sometimes on the system. A remark about this is in curly braces
747below. When an option is not supported it may still be set without getting an
748error, this is called a hidden option. You can't get the value of a hidden
749option though, it is not stored.
750
751To test if option "foo" can be used with ":set" use something like this: >
752 if exists('&foo')
753This also returns true for a hidden option. To test if option "foo" is really
754supported use something like this: >
755 if exists('+foo')
756<
Bram Moolenaar071d4272004-06-13 20:20:40 +0000757 *E355*
758A jump table for the options with a short description can be found at |Q_op|.
759
760 *'aleph'* *'al'* *aleph* *Aleph*
Bram Moolenaar5666fcd2019-12-26 14:35:26 +0100761'aleph' 'al' number (default 128 for MS-Windows, 224 otherwise)
Bram Moolenaar071d4272004-06-13 20:20:40 +0000762 global
Bram Moolenaar071d4272004-06-13 20:20:40 +0000763 {only available when compiled with the |+rightleft|
764 feature}
765 The ASCII code for the first letter of the Hebrew alphabet. The
766 routine that maps the keyboard in Hebrew mode, both in Insert mode
767 (when hkmap is set) and on the command-line (when hitting CTRL-_)
768 outputs the Hebrew characters in the range [aleph..aleph+26].
769 aleph=128 applies to PC code, and aleph=224 applies to ISO 8859-8.
770 See |rileft.txt|.
771
772 *'allowrevins'* *'ari'* *'noallowrevins'* *'noari'*
773'allowrevins' 'ari' boolean (default off)
774 global
Bram Moolenaar071d4272004-06-13 20:20:40 +0000775 {only available when compiled with the |+rightleft|
776 feature}
777 Allow CTRL-_ in Insert and Command-line mode. This is default off, to
778 avoid that users that accidentally type CTRL-_ instead of SHIFT-_ get
779 into reverse Insert mode, and don't know how to get out. See
780 'revins'.
781 NOTE: This option is reset when 'compatible' is set.
782
783 *'altkeymap'* *'akm'* *'noaltkeymap'* *'noakm'*
784'altkeymap' 'akm' boolean (default off)
785 global
Bram Moolenaar071d4272004-06-13 20:20:40 +0000786 {only available when compiled with the |+farsi|
787 feature}
Bram Moolenaar14184a32019-02-16 15:10:30 +0100788 This option was for using Farsi, which has been removed. See
789 |farsi.txt|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000790
791 *'ambiwidth'* *'ambw'*
792'ambiwidth' 'ambw' string (default: "single")
793 global
Bram Moolenaar071d4272004-06-13 20:20:40 +0000794 Only effective when 'encoding' is "utf-8" or another Unicode encoding.
795 Tells Vim what to do with characters with East Asian Width Class
796 Ambiguous (such as Euro, Registered Sign, Copyright Sign, Greek
797 letters, Cyrillic letters).
798
799 There are currently two possible values:
Bram Moolenaar582fd852005-03-28 20:58:01 +0000800 "single": Use the same width as characters in US-ASCII. This is
Bram Moolenaar071d4272004-06-13 20:20:40 +0000801 expected by most users.
802 "double": Use twice the width of ASCII characters.
Bram Moolenaar5c3bd0a2010-08-04 20:55:44 +0200803 *E834* *E835*
804 The value "double" cannot be used if 'listchars' or 'fillchars'
Bram Moolenaar079ba762021-10-23 12:08:41 +0100805 contains a character that would be double width. These errors may
806 also be given when calling setcellwidths().
Bram Moolenaar08aac3c2020-08-28 21:04:24 +0200807
808 The values are overruled for characters specified with
809 |setcellwidths()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000810
811 There are a number of CJK fonts for which the width of glyphs for
812 those characters are solely based on how many octets they take in
813 legacy/traditional CJK encodings. In those encodings, Euro,
814 Registered sign, Greek/Cyrillic letters are represented by two octets,
Bram Moolenaar582fd852005-03-28 20:58:01 +0000815 therefore those fonts have "wide" glyphs for them. This is also
Bram Moolenaar071d4272004-06-13 20:20:40 +0000816 true of some line drawing characters used to make tables in text
Bram Moolenaar582fd852005-03-28 20:58:01 +0000817 file. Therefore, when a CJK font is used for GUI Vim or
Bram Moolenaar071d4272004-06-13 20:20:40 +0000818 Vim is running inside a terminal (emulators) that uses a CJK font
819 (or Vim is run inside an xterm invoked with "-cjkwidth" option.),
820 this option should be set to "double" to match the width perceived
821 by Vim with the width of glyphs in the font. Perhaps it also has
Bram Moolenaar8024f932020-01-14 19:29:13 +0100822 to be set to "double" under CJK MS-Windows when the system locale is
823 set to one of CJK locales. See Unicode Standard Annex #11
824 (http://www.unicode.org/reports/tr11).
Bram Moolenaar071d4272004-06-13 20:20:40 +0000825
Bram Moolenaarac7bd632013-03-19 11:35:58 +0100826 Vim may set this option automatically at startup time when Vim is
827 compiled with the |+termresponse| feature and if |t_u7| is set to the
Bram Moolenaar37c64c72017-09-19 22:06:03 +0200828 escape sequence to request cursor position report. The response can
829 be found in |v:termu7resp|.
Bram Moolenaarac7bd632013-03-19 11:35:58 +0100830
Bram Moolenaar071d4272004-06-13 20:20:40 +0000831 *'antialias'* *'anti'* *'noantialias'* *'noanti'*
832'antialias' 'anti' boolean (default: off)
833 global
Bram Moolenaar071d4272004-06-13 20:20:40 +0000834 {only available when compiled with GUI enabled
Bram Moolenaar3d1cde82020-08-15 18:55:18 +0200835 on macOS}
836 This option only has an effect in the GUI version of Vim on macOS
Bram Moolenaar071d4272004-06-13 20:20:40 +0000837 v10.2 or later. When on, Vim will use smooth ("antialiased") fonts,
838 which can be easier to read at certain sizes on certain displays.
839 Setting this option can sometimes cause problems if 'guifont' is set
840 to its default (empty string).
Bram Moolenaar036986f2017-03-16 17:41:02 +0100841 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000842
843 *'autochdir'* *'acd'* *'noautochdir'* *'noacd'*
844'autochdir' 'acd' boolean (default off)
845 global
Bram Moolenaar00a927d2010-05-14 23:24:24 +0200846 {only available when compiled with it, use
847 exists("+autochdir") to check}
Bram Moolenaard8c00872005-07-22 21:52:15 +0000848 When on, Vim will change the current working directory whenever you
849 open a file, switch buffers, delete a buffer or open/close a window.
850 It will change to the directory containing the file which was opened
Bram Moolenaare8008642022-08-19 17:15:35 +0100851 or selected. When a buffer has no name it also has no directory, thus
852 the current directory won't change when navigating to it.
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000853 Note: When this option is on some plugins may not work.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000854
Bram Moolenaar8b9abfd2021-03-29 20:49:05 +0200855 *'autoshelldir'* *'asd'* *'noautoshelldir'* *'noasd'*
856'autoshelldir' 'asd' boolean (default off)
857 global
858 When on, Vim will change the current working directory whenever you
859 change the directory of the shell running in a terminal window. You
860 need proper setting-up, so whenever the shell's pwd changes an OSC 7
Bram Moolenaar48c3f4e2022-08-08 15:42:38 +0100861 escape sequence will be emitted. For example, on Linux, you can
862 source /etc/profile.d/vte.sh in your shell profile if you use bash or
863 zsh. For bash this should work (put it in a bash init file): >
864 if [[ -n "$VIM_TERMINAL" ]]; then
865 PROMPT_COMMAND='_vim_sync_PWD'
866 function _vim_sync_PWD() {
Bram Moolenaare1f3fd12022-08-15 18:51:32 +0100867 printf '\033]7;file://%s\033\\' "$PWD"
Bram Moolenaar48c3f4e2022-08-08 15:42:38 +0100868 }
869 fi
870<
871 Or, in a zsh init file: >
872 if [[ -n "$VIM_TERMINAL" ]]; then
873 autoload -Uz add-zsh-hook
874 add-zsh-hook -Uz chpwd _vim_sync_PWD
875 function _vim_sync_PWD() {
Bram Moolenaare1f3fd12022-08-15 18:51:32 +0100876 printf '\033]7;file://%s\033\\' "$PWD"
Bram Moolenaar48c3f4e2022-08-08 15:42:38 +0100877 }
878 fi
879<
880 In a fish init file: >
881 if test -n "$VIM_TERMINAL"
882 function _vim_sync_PWD --on-variable=PWD
Bram Moolenaare1f3fd12022-08-15 18:51:32 +0100883 printf '\033]7;file://%s\033\\' "$PWD"
Bram Moolenaar48c3f4e2022-08-08 15:42:38 +0100884 end
885 end
886<
887 You can find an alternative method at |terminal-autoshelldir|.
Bram Moolenaara2baa732022-02-04 16:09:54 +0000888 When the parsing of the OSC sequence fails you get *E1179* .
Bram Moolenaar8b9abfd2021-03-29 20:49:05 +0200889
Bram Moolenaar071d4272004-06-13 20:20:40 +0000890 *'arabic'* *'arab'* *'noarabic'* *'noarab'*
891'arabic' 'arab' boolean (default off)
892 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +0000893 {only available when compiled with the |+arabic|
894 feature}
895 This option can be set to start editing Arabic text.
896 Setting this option will:
897 - Set the 'rightleft' option, unless 'termbidi' is set.
898 - Set the 'arabicshape' option, unless 'termbidi' is set.
899 - Set the 'keymap' option to "arabic"; in Insert mode CTRL-^ toggles
900 between typing English and Arabic key mapping.
901 - Set the 'delcombine' option
902 Note that 'encoding' must be "utf-8" for working with Arabic text.
903
904 Resetting this option will:
905 - Reset the 'rightleft' option.
906 - Disable the use of 'keymap' (without changing its value).
907 Note that 'arabicshape' and 'delcombine' are not reset (it is a global
Bram Moolenaarc8734422012-06-01 22:38:45 +0200908 option).
Bram Moolenaar036986f2017-03-16 17:41:02 +0100909 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000910 Also see |arabic.txt|.
911
912 *'arabicshape'* *'arshape'*
913 *'noarabicshape'* *'noarshape'*
914'arabicshape' 'arshape' boolean (default on)
915 global
Bram Moolenaar071d4272004-06-13 20:20:40 +0000916 {only available when compiled with the |+arabic|
917 feature}
918 When on and 'termbidi' is off, the required visual character
919 corrections that need to take place for displaying the Arabic language
Bram Moolenaar3a0d8092012-10-21 03:02:54 +0200920 take effect. Shaping, in essence, gets enabled; the term is a broad
Bram Moolenaar071d4272004-06-13 20:20:40 +0000921 one which encompasses:
922 a) the changing/morphing of characters based on their location
923 within a word (initial, medial, final and stand-alone).
924 b) the enabling of the ability to compose characters
925 c) the enabling of the required combining of some characters
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100926 When disabled the display shows each character's true stand-alone
927 form.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000928 Arabic is a complex language which requires other settings, for
929 further details see |arabic.txt|.
Bram Moolenaar036986f2017-03-16 17:41:02 +0100930 NOTE: This option is set when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000931
932 *'autoindent'* *'ai'* *'noautoindent'* *'noai'*
933'autoindent' 'ai' boolean (default off)
934 local to buffer
935 Copy indent from current line when starting a new line (typing <CR>
936 in Insert mode or when using the "o" or "O" command). If you do not
937 type anything on the new line except <BS> or CTRL-D and then type
Bram Moolenaar02467872007-05-06 13:22:01 +0000938 <Esc>, CTRL-O or <CR>, the indent is deleted again. Moving the cursor
939 to another line has the same effect, unless the 'I' flag is included
940 in 'cpoptions'.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +0000941 When autoindent is on, formatting (with the "gq" command or when you
942 reach 'textwidth' in Insert mode) uses the indentation of the first
943 line.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000944 When 'smartindent' or 'cindent' is on the indent is changed in
945 a different way.
Bram Moolenaarca635012015-09-25 20:34:21 +0200946 The 'autoindent' option is reset when the 'paste' option is set and
947 restored when 'paste' is reset.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000948
949 *'autoread'* *'ar'* *'noautoread'* *'noar'*
950'autoread' 'ar' boolean (default off)
951 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000952 When a file has been detected to have been changed outside of Vim and
953 it has not been changed inside of Vim, automatically read it again.
Bram Moolenaarfd358112018-07-07 23:21:31 +0200954 When the file has been deleted this is not done, so you have the text
955 from before it was deleted. When it appears again then it is read.
956 |timestamp|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000957 If this option has a local value, use this command to switch back to
958 using the global value: >
959 :set autoread<
960<
961 *'autowrite'* *'aw'* *'noautowrite'* *'noaw'*
962'autowrite' 'aw' boolean (default off)
963 global
964 Write the contents of the file, if it has been modified, on each
Bram Moolenaar47003982021-12-05 21:54:04 +0000965 `:next`, `:rewind`, `:last`, `:first`, `:previous`, `:stop`,
Bram Moolenaar2f0936c2022-01-08 21:51:59 +0000966 `:suspend`, `:tag`, `:!`, `:make`, CTRL-] and CTRL-^ command; and when
967 a `:buffer`, CTRL-O, CTRL-I, '{A-Z0-9}, or `{A-Z0-9} command takes one
Bram Moolenaar47003982021-12-05 21:54:04 +0000968 to another file.
969 A buffer is not written if it becomes hidden, e.g. when 'bufhidden' is
Bram Moolenaar2f0936c2022-01-08 21:51:59 +0000970 set to "hide" and `:next` is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000971 Note that for some commands the 'autowrite' option is not used, see
972 'autowriteall' for that.
Bram Moolenaar93a1df22018-09-10 11:51:50 +0200973 Some buffers will not be written, specifically when 'buftype' is
Bram Moolenaar20aac6c2018-09-02 21:07:30 +0200974 "nowrite", "nofile", "terminal" or "prompt".
Bram Moolenaarb7398fe2023-05-14 18:50:25 +0100975 USE WITH CARE: If you make temporary changes to a buffer that you
976 don't want to be saved this option may cause it to be saved anyway.
977 Renaming the buffer with ":file {name}" may help avoid this.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000978
979 *'autowriteall'* *'awa'* *'noautowriteall'* *'noawa'*
980'autowriteall' 'awa' boolean (default off)
981 global
Bram Moolenaar071d4272004-06-13 20:20:40 +0000982 Like 'autowrite', but also used for commands ":edit", ":enew", ":quit",
983 ":qall", ":exit", ":xit", ":recover" and closing the Vim window.
984 Setting this option also implies that Vim behaves like 'autowrite' has
985 been set.
986
987 *'background'* *'bg'*
Bram Moolenaar446beb42011-05-10 17:18:44 +0200988'background' 'bg' string (default "dark" or "light", see below)
Bram Moolenaar071d4272004-06-13 20:20:40 +0000989 global
Bram Moolenaar071d4272004-06-13 20:20:40 +0000990 When set to "dark", Vim will try to use colors that look good on a
991 dark background. When set to "light", Vim will try to use colors that
992 look good on a light background. Any other value is illegal.
993 Vim tries to set the default value according to the terminal used.
994 This will not always be correct.
995 Setting this option does not change the background color, it tells Vim
996 what the background color looks like. For changing the background
997 color, see |:hi-normal|.
998
999 When 'background' is set Vim will adjust the default color groups for
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00001000 the new value. But the colors used for syntax highlighting will not
Bram Moolenaar446cb832008-06-24 21:56:24 +00001001 change. *g:colors_name*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001002 When a color scheme is loaded (the "g:colors_name" variable is set)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001003 setting 'background' will cause the color scheme to be reloaded. If
1004 the color scheme adjusts to the value of 'background' this will work.
1005 However, if the color scheme sets 'background' itself the effect may
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001006 be undone. First delete the "g:colors_name" variable when needed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001007
1008 When setting 'background' to the default value with: >
1009 :set background&
1010< Vim will guess the value. In the GUI this should work correctly,
1011 in other cases Vim might not be able to guess the right value.
Bram Moolenaar2e693a82019-10-16 22:35:02 +02001012 If the GUI supports a dark theme, you can use the "d" flag in
Bram Moolenaar50bf7ce2019-09-15 13:17:00 +02001013 'guioptions', see 'go-d'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001014
Bram Moolenaar37c64c72017-09-19 22:06:03 +02001015 When the |t_RB| option is set, Vim will use it to request the background
Bram Moolenaarb4d6c3e2017-05-27 16:45:17 +02001016 color from the terminal. If the returned RGB value is dark/light and
1017 'background' is not dark/light, 'background' will be set and the
1018 screen is redrawn. This may have side effects, make t_BG empty in
Bram Moolenaar37c64c72017-09-19 22:06:03 +02001019 your .vimrc if you suspect this problem. The response to |t_RB| can
Bram Moolenaar01164a62017-11-02 22:58:42 +01001020 be found in |v:termrbgresp|.
Bram Moolenaarb4d6c3e2017-05-27 16:45:17 +02001021
Bram Moolenaar071d4272004-06-13 20:20:40 +00001022 When starting the GUI, the default value for 'background' will be
1023 "light". When the value is not set in the .gvimrc, and Vim detects
1024 that the background is actually quite dark, 'background' is set to
1025 "dark". But this happens only AFTER the .gvimrc file has been read
1026 (because the window needs to be opened to find the actual background
1027 color). To get around this, force the GUI window to be opened by
1028 putting a ":gui" command in the .gvimrc file, before where the value
1029 of 'background' is used (e.g., before ":syntax on").
Bram Moolenaar446beb42011-05-10 17:18:44 +02001030
Bram Moolenaar6f345a12019-12-17 21:27:18 +01001031 For MS-Windows the default is "dark".
Bram Moolenaar446beb42011-05-10 17:18:44 +02001032 For other systems "dark" is used when 'term' is "linux",
1033 "screen.linux", "cygwin" or "putty", or $COLORFGBG suggests a dark
1034 background. Otherwise the default is "light".
1035
Bram Moolenaarc572da52017-08-27 16:52:01 +02001036 The |:terminal| command and the |term_start()| function use the
1037 'background' value to decide whether the terminal window will start
1038 with a white or black background.
1039
Bram Moolenaar071d4272004-06-13 20:20:40 +00001040 Normally this option would be set in the .vimrc file. Possibly
1041 depending on the terminal name. Example: >
1042 :if &term == "pcterm"
1043 : set background=dark
1044 :endif
1045< When this option is set, the default settings for the highlight groups
1046 will change. To use other settings, place ":highlight" commands AFTER
1047 the setting of the 'background' option.
1048 This option is also used in the "$VIMRUNTIME/syntax/syntax.vim" file
1049 to select the colors for syntax highlighting. After changing this
1050 option, you must load syntax.vim again to see the result. This can be
1051 done with ":syntax on".
1052
1053 *'backspace'* *'bs'*
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +02001054'backspace' 'bs' string (default "", set to "indent,eol,start"
1055 in |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001056 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001057 Influences the working of <BS>, <Del>, CTRL-W and CTRL-U in Insert
1058 mode. This is a list of items, separated by commas. Each item allows
1059 a way to backspace over something:
1060 value effect ~
1061 indent allow backspacing over autoindent
1062 eol allow backspacing over line breaks (join lines)
1063 start allow backspacing over the start of insert; CTRL-W and CTRL-U
1064 stop once at the start of insert.
Bram Moolenaaraa0489e2020-04-17 19:41:21 +02001065 nostop like start, except CTRL-W and CTRL-U do not stop at the start of
1066 insert.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001067
Bram Moolenaar46eea442022-03-30 10:51:39 +01001068 When the value is empty, Vi compatible backspacing is used, none of
1069 the ways mentioned for the items above are possible.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001070
1071 For backwards compatibility with version 5.4 and earlier:
1072 value effect ~
1073 0 same as ":set backspace=" (Vi compatible)
1074 1 same as ":set backspace=indent,eol"
1075 2 same as ":set backspace=indent,eol,start"
Bram Moolenaaraa0489e2020-04-17 19:41:21 +02001076 3 same as ":set backspace=indent,eol,nostop"
Bram Moolenaar071d4272004-06-13 20:20:40 +00001077
1078 See |:fixdel| if your <BS> or <Del> key does not do what you want.
1079 NOTE: This option is set to "" when 'compatible' is set.
1080
1081 *'backup'* *'bk'* *'nobackup'* *'nobk'*
1082'backup' 'bk' boolean (default off)
1083 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001084 Make a backup before overwriting a file. Leave it around after the
1085 file has been successfully written. If you do not want to keep the
1086 backup file, but you do want a backup while the file is being
1087 written, reset this option and set the 'writebackup' option (this is
1088 the default). If you do not want a backup file at all reset both
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00001089 options (use this if your file system is almost full). See the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001090 |backup-table| for more explanations.
1091 When the 'backupskip' pattern matches, a backup is not made anyway.
1092 When 'patchmode' is set, the backup may be renamed to become the
1093 oldest version of a file.
1094 NOTE: This option is reset when 'compatible' is set.
1095
1096 *'backupcopy'* *'bkc'*
1097'backupcopy' 'bkc' string (Vi default for Unix: "yes", otherwise: "auto")
Bram Moolenaarb8ee25a2014-09-23 15:45:08 +02001098 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001099 When writing a file and a backup is made, this option tells how it's
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01001100 done. This is a comma-separated list of words.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001101
1102 The main values are:
1103 "yes" make a copy of the file and overwrite the original one
1104 "no" rename the file and write a new one
1105 "auto" one of the previous, what works best
1106
1107 Extra values that can be combined with the ones above are:
1108 "breaksymlink" always break symlinks when writing
1109 "breakhardlink" always break hardlinks when writing
1110
1111 Making a copy and overwriting the original file:
1112 - Takes extra time to copy the file.
1113 + When the file has special attributes, is a (hard/symbolic) link or
1114 has a resource fork, all this is preserved.
1115 - When the file is a link the backup will have the name of the link,
1116 not of the real file.
1117
1118 Renaming the file and writing a new one:
1119 + It's fast.
1120 - Sometimes not all attributes of the file can be copied to the new
1121 file.
1122 - When the file is a link the new file will not be a link.
1123
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01001124 The "auto" value is the middle way: When Vim sees that renaming the
1125 file is possible without side effects (the attributes can be passed on
1126 and the file is not a link) that is used. When problems are expected,
1127 a copy will be made.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001128
1129 The "breaksymlink" and "breakhardlink" values can be used in
1130 combination with any of "yes", "no" and "auto". When included, they
1131 force Vim to always break either symbolic or hard links by doing
1132 exactly what the "no" option does, renaming the original file to
1133 become the backup and writing a new file in its place. This can be
1134 useful for example in source trees where all the files are symbolic or
1135 hard links and any changes should stay in the local source tree, not
1136 be propagated back to the original source.
1137 *crontab*
1138 One situation where "no" and "auto" will cause problems: A program
1139 that opens a file, invokes Vim to edit that file, and then tests if
1140 the open file was changed (through the file descriptor) will check the
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00001141 backup file instead of the newly created file. "crontab -e" is an
Bram Moolenaar071d4272004-06-13 20:20:40 +00001142 example.
1143
1144 When a copy is made, the original file is truncated and then filled
1145 with the new text. This means that protection bits, owner and
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01001146 symbolic links of the original file are unmodified. The backup file,
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00001147 however, is a new file, owned by the user who edited the file. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00001148 group of the backup is set to the group of the original file. If this
1149 fails, the protection bits for the group are made the same as for
1150 others.
1151
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01001152 When the file is renamed, this is the other way around: The backup has
Bram Moolenaar071d4272004-06-13 20:20:40 +00001153 the same attributes of the original file, and the newly written file
1154 is owned by the current user. When the file was a (hard/symbolic)
1155 link, the new file will not! That's why the "auto" value doesn't
1156 rename when the file is a link. The owner and group of the newly
1157 written file will be set to the same ones as the original file, but
1158 the system may refuse to do this. In that case the "auto" value will
1159 again not rename the file.
1160
Bram Moolenaar036986f2017-03-16 17:41:02 +01001161 NOTE: This option is set to the Vi default value when 'compatible' is
1162 set and to the Vim default value when 'compatible' is reset.
1163
Bram Moolenaar071d4272004-06-13 20:20:40 +00001164 *'backupdir'* *'bdir'*
1165'backupdir' 'bdir' string (default for Amiga: ".,t:",
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01001166 for Win32: ".,$TEMP,c:/tmp,c:/temp"
Bram Moolenaar071d4272004-06-13 20:20:40 +00001167 for Unix: ".,~/tmp,~/")
1168 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001169 List of directories for the backup file, separated with commas.
1170 - The backup file will be created in the first directory in the list
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001171 where this is possible. The directory must exist, Vim will not
1172 create it for you.
Bram Moolenaar3848e002016-03-19 18:42:29 +01001173 - Empty means that no backup file will be created ('patchmode' is
Bram Moolenaar071d4272004-06-13 20:20:40 +00001174 impossible!). Writing may fail because of this.
1175 - A directory "." means to put the backup file in the same directory
1176 as the edited file.
Bram Moolenaar8024f932020-01-14 19:29:13 +01001177 - A directory starting with "./" (or ".\" for MS-Windows) means to put
1178 the backup file relative to where the edited file is. The leading
1179 "." is replaced with the path name of the edited file.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001180 ("." inside a directory name has no special meaning).
1181 - Spaces after the comma are ignored, other spaces are considered part
1182 of the directory name. To have a space at the start of a directory
1183 name, precede it with a backslash.
1184 - To include a comma in a directory name precede it with a backslash.
1185 - A directory name may end in an '/'.
Bram Moolenaarb782ba42018-08-07 21:39:28 +02001186 - For Unix and Win32, if a directory ends in two path separators "//",
Bram Moolenaarf0d58ef2018-11-16 16:13:44 +01001187 the backup file name will be built from the complete path to the
1188 file with all path separators changed to percent '%' signs. This
1189 will ensure file name uniqueness in the backup directory.
Bram Moolenaarb782ba42018-08-07 21:39:28 +02001190 On Win32, it is also possible to end with "\\". However, When a
1191 separating comma is following, you must use "//", since "\\" will
1192 include the comma in the file name. Therefore it is recommended to
1193 use '//', instead of '\\'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001194 - Environment variables are expanded |:set_env|.
1195 - Careful with '\' characters, type one before a space, type two to
1196 get one in the option (see |option-backslash|), for example: >
1197 :set bdir=c:\\tmp,\ dir\\,with\\,commas,\\\ dir\ with\ spaces
1198< - For backwards compatibility with Vim version 3.0 a '>' at the start
1199 of the option is removed.
1200 See also 'backup' and 'writebackup' options.
1201 If you want to hide your backup files on Unix, consider this value: >
1202 :set backupdir=./.backup,~/.backup,.,/tmp
1203< You must create a ".backup" directory in each directory and in your
1204 home directory for this to work properly.
1205 The use of |:set+=| and |:set-=| is preferred when adding or removing
1206 directories from the list. This avoids problems when a future version
1207 uses another default.
1208 This option cannot be set from a |modeline| or in the |sandbox|, for
1209 security reasons.
1210
1211 *'backupext'* *'bex'* *E589*
1212'backupext' 'bex' string (default "~", for VMS: "_")
1213 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001214 String which is appended to a file name to make the name of the
1215 backup file. The default is quite unusual, because this avoids
1216 accidentally overwriting existing files with a backup file. You might
1217 prefer using ".bak", but make sure that you don't have files with
1218 ".bak" that you want to keep.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01001219 Only normal file name characters can be used; "/\*?[|<>" are illegal.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001220
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001221 If you like to keep a lot of backups, you could use a BufWritePre
1222 autocommand to change 'backupext' just before writing the file to
1223 include a timestamp. >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001224 :au BufWritePre * let &bex = '-' .. strftime("%Y%b%d%X") .. '~'
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001225< Use 'backupdir' to put the backup in a different directory.
1226
Bram Moolenaar071d4272004-06-13 20:20:40 +00001227 *'backupskip'* *'bsk'*
Bram Moolenaarb8e22a02018-04-12 21:37:34 +02001228'backupskip' 'bsk' string (default: "$TMPDIR/*,$TMP/*,$TEMP/*"
1229 Unix: "/tmp/*,$TMPDIR/*,$TMP/*,$TEMP/*"
1230 Mac: "/private/tmp/*,$TMPDIR/*,$TMP/*,$TEMP/*")
Bram Moolenaar071d4272004-06-13 20:20:40 +00001231 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001232 A list of file patterns. When one of the patterns matches with the
1233 name of the file which is written, no backup file is created. Both
1234 the specified file name and the full path name of the file are used.
1235 The pattern is used like with |:autocmd|, see |autocmd-patterns|.
1236 Watch out for special characters, see |option-backslash|.
1237 When $TMPDIR, $TMP or $TEMP is not defined, it is not used for the
Bram Moolenaar582fd852005-03-28 20:58:01 +00001238 default value. "/tmp/*" is only used for Unix.
Bram Moolenaar02467872007-05-06 13:22:01 +00001239
Bram Moolenaar1aeaf8c2012-05-18 13:46:39 +02001240 WARNING: Not having a backup file means that when Vim fails to write
1241 your buffer correctly and then, for whatever reason, Vim exits, you
1242 lose both the original file and what you were writing. Only disable
1243 backups if you don't care about losing the file.
1244
Bram Moolenaar02467872007-05-06 13:22:01 +00001245 Note that environment variables are not expanded. If you want to use
1246 $HOME you must expand it explicitly, e.g.: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001247 :let &backupskip = escape(expand('$HOME'), '\') .. '/tmp/*'
Bram Moolenaar02467872007-05-06 13:22:01 +00001248
1249< Note that the default also makes sure that "crontab -e" works (when a
Bram Moolenaara5792f52005-11-23 21:25:05 +00001250 backup would be made by renaming the original file crontab won't see
1251 the newly created file). Also see 'backupcopy' and |crontab|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001252
1253 *'balloondelay'* *'bdlay'*
1254'balloondelay' 'bdlay' number (default: 600)
1255 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001256 {only available when compiled with the |+balloon_eval|
1257 feature}
1258 Delay in milliseconds before a balloon may pop up. See |balloon-eval|.
1259
1260 *'ballooneval'* *'beval'* *'noballooneval'* *'nobeval'*
1261'ballooneval' 'beval' boolean (default off)
1262 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001263 {only available when compiled with the |+balloon_eval|
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001264 feature}
Bram Moolenaar51b0f372017-11-18 18:52:04 +01001265 Switch on the |balloon-eval| functionality for the GUI.
1266
1267 *'balloonevalterm'* *'bevalterm'* *'noballoonevalterm'*
1268 *'nobevalterm'*
1269'balloonevalterm' 'bevalterm' boolean (default off)
1270 global
Bram Moolenaar51b0f372017-11-18 18:52:04 +01001271 {only available when compiled with the
1272 |+balloon_eval_term| feature}
1273 Switch on the |balloon-eval| functionality for the terminal.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001274
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001275 *'balloonexpr'* *'bexpr'*
1276'balloonexpr' 'bexpr' string (default "")
Bram Moolenaar9b2200a2006-03-20 21:55:45 +00001277 global or local to buffer |global-local|
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001278 {only available when compiled with the |+balloon_eval|
1279 feature}
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00001280 Expression for text to show in evaluation balloon. It is only used
Bram Moolenaara6c27c42019-05-09 19:16:22 +02001281 when 'ballooneval' or 'balloonevalterm' is on. These variables can be
1282 used:
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001283
1284 v:beval_bufnr number of the buffer in which balloon is going to show
1285 v:beval_winnr number of the window
Bram Moolenaar82af8712016-06-04 20:20:29 +02001286 v:beval_winid ID of the window
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001287 v:beval_lnum line number
1288 v:beval_col column number (byte index)
1289 v:beval_text word under or after the mouse pointer
1290
Bram Moolenaar54775062019-07-31 21:07:14 +02001291 Instead of showing a balloon, which is limited to plain text, consider
1292 using a popup window, see |popup_beval_example|. A popup window can
1293 use highlighting and show a border.
1294
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001295 The evaluation of the expression must not have side effects!
1296 Example: >
Bram Moolenaara6c27c42019-05-09 19:16:22 +02001297 function MyBalloonExpr()
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001298 return 'Cursor is at line ' .. v:beval_lnum ..
1299 \ ', column ' .. v:beval_col ..
1300 \ ' of file ' .. bufname(v:beval_bufnr) ..
1301 \ ' on word "' .. v:beval_text .. '"'
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001302 endfunction
1303 set bexpr=MyBalloonExpr()
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00001304 set ballooneval balloonevalterm
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001305<
Bram Moolenaar396e8292019-07-13 23:04:31 +02001306 Also see |balloon_show()|, it can be used if the content of the balloon
1307 is to be fetched asynchronously. In that case evaluating
1308 'balloonexpr' should result in an empty string. If you get a balloon
1309 with only "0" you probably didn't return anything from your function.
Bram Moolenaar214641f2017-03-05 17:04:09 +01001310
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00001311 NOTE: The balloon is displayed only if the cursor is on a text
1312 character. If the result of evaluating 'balloonexpr' is not empty,
1313 Vim does not try to send a message to an external debugger (Netbeans
1314 or Sun Workshop).
1315
Yegappan Lakshmanan8bb65f22021-12-26 10:51:39 +00001316 If the expression starts with s: or |<SID>|, then it is replaced with
1317 the script ID (|local-function|). Example: >
1318 set bexpr=s:MyBalloonExpr()
1319 set bexpr=<SID>SomeBalloonExpr()
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00001320< Otherwise, the expression is evaluated in the context of the script
1321 where the option was set, thus script-local items are available.
1322
Bram Moolenaar30b65812012-07-12 22:01:11 +02001323 The expression will be evaluated in the |sandbox| when set from a
1324 modeline, see |sandbox-option|.
Bram Moolenaar110289e2019-05-23 15:38:06 +02001325 This option cannot be set in a modeline when 'modelineexpr' is off.
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00001326
1327 It is not allowed to change text or jump to another window while
Bram Moolenaar396e8292019-07-13 23:04:31 +02001328 evaluating 'balloonexpr', see |textlock|.
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00001329
Bram Moolenaar87e25fd2005-07-27 21:13:01 +00001330 To check whether line breaks in the balloon text work use this check: >
Bram Moolenaar45360022005-07-21 21:08:21 +00001331 if has("balloon_multiline")
Bram Moolenaar362e1a32006-03-06 23:29:24 +00001332< When they are supported "\n" characters will start a new line. If the
1333 expression evaluates to a |List| this is equal to using each List item
1334 as a string and putting "\n" in between them.
Bram Moolenaar036986f2017-03-16 17:41:02 +01001335 NOTE: This option is set to "" when 'compatible' is set.
Bram Moolenaar362e1a32006-03-06 23:29:24 +00001336
Bram Moolenaar165bc692015-07-21 17:53:25 +02001337 *'belloff'* *'bo'*
1338'belloff' 'bo' string (default "")
1339 global
Bram Moolenaar165bc692015-07-21 17:53:25 +02001340 Specifies for which events the bell will not be rung. It is a comma
1341 separated list of items. For each item that is present, the bell
1342 will be silenced. This is most useful to specify specific events in
1343 insert mode to be silenced.
LemonBoy77771d32022-04-13 11:47:25 +01001344 You can also make it flash by using 'visualbell'.
Bram Moolenaar165bc692015-07-21 17:53:25 +02001345
1346 item meaning when present ~
1347 all All events.
1348 backspace When hitting <BS> or <Del> and deleting results in an
1349 error.
1350 cursor Fail to move around using the cursor keys or
1351 <PageUp>/<PageDown> in |Insert-mode|.
1352 complete Error occurred when using |i_CTRL-X_CTRL-K| or
1353 |i_CTRL-X_CTRL-T|.
1354 copy Cannot copy char from insert mode using |i_CTRL-Y| or
1355 |i_CTRL-E|.
1356 ctrlg Unknown Char after <C-G> in Insert mode.
1357 error Other Error occurred (e.g. try to join last line)
1358 (mostly used in |Normal-mode| or |Cmdline-mode|).
1359 esc hitting <Esc> in |Normal-mode|.
1360 ex In |Visual-mode|, hitting |Q| results in an error.
Bram Moolenaar0c0734d2019-11-26 21:44:46 +01001361 hangul Ignored.
Bram Moolenaar165bc692015-07-21 17:53:25 +02001362 insertmode Pressing <Esc> in 'insertmode'.
1363 lang Calling the beep module for Lua/Mzscheme/TCL.
1364 mess No output available for |g<|.
1365 showmatch Error occurred for 'showmatch' function.
1366 operator Empty region error |cpo-E|.
1367 register Unknown register after <C-R> in |Insert-mode|.
1368 shell Bell from shell output |:!|.
1369 spell Error happened on spell suggest.
LemonBoy77771d32022-04-13 11:47:25 +01001370 term Bell from |:terminal| output.
Bram Moolenaar165bc692015-07-21 17:53:25 +02001371 wildmode More matches in |cmdline-completion| available
1372 (depends on the 'wildmode' setting).
1373
Bram Moolenaar036986f2017-03-16 17:41:02 +01001374 This is most useful to fine tune when in Insert mode the bell should
1375 be rung. For Normal mode and Ex commands, the bell is often rung to
Bram Moolenaar165bc692015-07-21 17:53:25 +02001376 indicate that an error occurred. It can be silenced by adding the
1377 "error" keyword.
1378
Bram Moolenaar071d4272004-06-13 20:20:40 +00001379 *'binary'* *'bin'* *'nobinary'* *'nobin'*
1380'binary' 'bin' boolean (default off)
1381 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001382 This option should be set before editing a binary file. You can also
1383 use the |-b| Vim argument. When this option is switched on a few
1384 options will be changed (also when it already was on):
1385 'textwidth' will be set to 0
1386 'wrapmargin' will be set to 0
1387 'modeline' will be off
1388 'expandtab' will be off
1389 Also, 'fileformat' and 'fileformats' options will not be used, the
1390 file is read and written like 'fileformat' was "unix" (a single <NL>
1391 separates lines).
1392 The 'fileencoding' and 'fileencodings' options will not be used, the
1393 file is read without conversion.
1394 NOTE: When you start editing a(nother) file while the 'bin' option is
1395 on, settings from autocommands may change the settings again (e.g.,
1396 'textwidth'), causing trouble when editing. You might want to set
1397 'bin' again when the file has been loaded.
1398 The previous values of these options are remembered and restored when
1399 'bin' is switched from on to off. Each buffer has its own set of
1400 saved option values.
1401 To edit a file with 'binary' set you can use the |++bin| argument.
1402 This avoids you have to do ":set bin", which would have effect for all
1403 files you edit.
1404 When writing a file the <EOL> for the last line is only written if
1405 there was one in the original file (normally Vim appends an <EOL> to
1406 the last line if there is none; this would make the file longer). See
1407 the 'endofline' option.
1408
1409 *'bioskey'* *'biosk'* *'nobioskey'* *'nobiosk'*
1410'bioskey' 'biosk' boolean (default on)
1411 global
Bram Moolenaar6c60f472019-04-28 16:00:35 +02001412 {only for MS-DOS}
Bram Moolenaarf3913272016-02-25 00:00:01 +01001413 This was for MS-DOS and is no longer supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001414
1415 *'bomb'* *'nobomb'*
1416'bomb' boolean (default off)
1417 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001418 When writing a file and the following conditions are met, a BOM (Byte
1419 Order Mark) is prepended to the file:
1420 - this option is on
1421 - the 'binary' option is off
1422 - 'fileencoding' is "utf-8", "ucs-2", "ucs-4" or one of the little/big
1423 endian variants.
1424 Some applications use the BOM to recognize the encoding of the file.
1425 Often used for UCS-2 files on MS-Windows. For other applications it
1426 causes trouble, for example: "cat file1 file2" makes the BOM of file2
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001427 appear halfway the resulting file. Gcc doesn't accept a BOM.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001428 When Vim reads a file and 'fileencodings' starts with "ucs-bom", a
1429 check for the presence of the BOM is done and 'bomb' set accordingly.
1430 Unless 'binary' is set, it is removed from the first line, so that you
1431 don't see it when editing. When you don't change the options, the BOM
1432 will be restored when writing the file.
1433
1434 *'breakat'* *'brk'*
1435'breakat' 'brk' string (default " ^I!@*-+;:,./?")
1436 global
Bram Moolenaardb84e452010-08-15 13:50:43 +02001437 {not available when compiled without the |+linebreak|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001438 feature}
1439 This option lets you choose which characters might cause a line
Bram Moolenaarac6e65f2005-08-29 22:25:38 +00001440 break if 'linebreak' is on. Only works for ASCII and also for 8-bit
1441 characters when 'encoding' is an 8-bit encoding.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001442
Bram Moolenaar7c1c6db2016-04-03 22:08:05 +02001443 *'breakindent'* *'bri'* *'nobreakindent'* *'nobri'*
Bram Moolenaar946e27a2014-06-25 18:50:27 +02001444'breakindent' 'bri' boolean (default off)
1445 local to window
Bram Moolenaar946e27a2014-06-25 18:50:27 +02001446 {not available when compiled without the |+linebreak|
1447 feature}
1448 Every wrapped line will continue visually indented (same amount of
1449 space as the beginning of that line), thus preserving horizontal blocks
1450 of text.
Bram Moolenaar036986f2017-03-16 17:41:02 +01001451 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaar946e27a2014-06-25 18:50:27 +02001452
1453 *'breakindentopt'* *'briopt'*
1454'breakindentopt' 'briopt' string (default empty)
1455 local to window
Bram Moolenaar946e27a2014-06-25 18:50:27 +02001456 {not available when compiled without the |+linebreak|
1457 feature}
1458 Settings for 'breakindent'. It can consist of the following optional
Bram Moolenaar86b17e92014-07-02 20:00:47 +02001459 items and must be separated by a comma:
Bram Moolenaar946e27a2014-06-25 18:50:27 +02001460 min:{n} Minimum text width that will be kept after
1461 applying 'breakindent', even if the resulting
1462 text should normally be narrower. This prevents
1463 text indented almost to the right window border
1464 occupying lot of vertical space when broken.
Christian Brabandtc53b4672022-01-15 10:01:05 +00001465 (default: 20)
Bram Moolenaar86b17e92014-07-02 20:00:47 +02001466 shift:{n} After applying 'breakindent', the wrapped line's
1467 beginning will be shifted by the given number of
1468 characters. It permits dynamic French paragraph
Bram Moolenaar946e27a2014-06-25 18:50:27 +02001469 indentation (negative) or emphasizing the line
1470 continuation (positive).
Christian Brabandte7d6dbc2022-05-06 12:21:04 +01001471 (default: 0)
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01001472 sbr Display the 'showbreak' value before applying the
Bram Moolenaar946e27a2014-06-25 18:50:27 +02001473 additional indent.
Christian Brabandte7d6dbc2022-05-06 12:21:04 +01001474 (default: off)
Maxim Kimf674b352021-07-22 11:46:59 +02001475 list:{n} Adds an additional indent for lines that match a
Christian Brabandt4a0b85a2021-07-14 20:00:27 +02001476 numbered or bulleted list (using the
1477 'formatlistpat' setting).
Maxim Kimf674b352021-07-22 11:46:59 +02001478 list:-1 Uses the length of a match with 'formatlistpat'
1479 for indentation.
Christian Brabandte7d6dbc2022-05-06 12:21:04 +01001480 (default: 0)
1481 column:{n} Indent at column {n}. Will overrule the other
1482 sub-options. Note: an additional indent may be
1483 added for the 'showbreak' setting.
1484 (default: off)
Bram Moolenaar946e27a2014-06-25 18:50:27 +02001485
Bram Moolenaar071d4272004-06-13 20:20:40 +00001486 *'browsedir'* *'bsdir'*
Bram Moolenaar7b0294c2004-10-11 10:16:09 +00001487'browsedir' 'bsdir' string (default: "last")
Bram Moolenaar071d4272004-06-13 20:20:40 +00001488 global
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01001489 {only for Motif, GTK, Mac and Win32 GUI}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001490 Which directory to use for the file browser:
Bram Moolenaar446cb832008-06-24 21:56:24 +00001491 last Use same directory as with last file browser, where a
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02001492 file was opened or saved.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001493 buffer Use the directory of the related buffer.
1494 current Use the current directory.
1495 {path} Use the specified directory
1496
1497 *'bufhidden'* *'bh'*
1498'bufhidden' 'bh' string (default: "")
Christian Brabandt596ad662023-08-16 00:11:09 +02001499 local to buffer |local-noglobal|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001500 This option specifies what happens when a buffer is no longer
1501 displayed in a window:
1502 <empty> follow the global 'hidden' option
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01001503 hide hide the buffer (don't unload it), even if 'hidden' is
1504 not set
1505 unload unload the buffer, even if 'hidden' is set; the
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01001506 |:hide| command will also unload the buffer
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01001507 delete delete the buffer from the buffer list, even if
1508 'hidden' is set; the |:hide| command will also delete
1509 the buffer, making it behave like |:bdelete|
1510 wipe wipe the buffer from the buffer list, even if
1511 'hidden' is set; the |:hide| command will also wipe
1512 out the buffer, making it behave like |:bwipeout|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001513
Bram Moolenaara14de3d2005-01-07 21:48:26 +00001514 CAREFUL: when "unload", "delete" or "wipe" is used changes in a buffer
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01001515 are lost without a warning. Also, these values may break autocommands
1516 that switch between buffers temporarily.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001517 This option is used together with 'buftype' and 'swapfile' to specify
1518 special kinds of buffers. See |special-buffers|.
1519
1520 *'buflisted'* *'bl'* *'nobuflisted'* *'nobl'* *E85*
1521'buflisted' 'bl' boolean (default: on)
1522 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001523 When this option is set, the buffer shows up in the buffer list. If
1524 it is reset it is not used for ":bnext", "ls", the Buffers menu, etc.
1525 This option is reset by Vim for buffers that are only used to remember
1526 a file name or marks. Vim sets it when starting to edit a buffer.
1527 But not when moving to a buffer with ":buffer".
1528
1529 *'buftype'* *'bt'* *E382*
1530'buftype' 'bt' string (default: "")
Christian Brabandt596ad662023-08-16 00:11:09 +02001531 local to buffer |local-noglobal|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001532 The value of this option specifies the type of a buffer:
1533 <empty> normal buffer
1534 nofile buffer which is not related to a file and will not be
1535 written
1536 nowrite buffer which will not be written
Bram Moolenaar21cf8232004-07-16 20:18:37 +00001537 acwrite buffer which will always be written with BufWriteCmd
Bram Moolenaarb5b75622018-03-09 22:22:21 +01001538 autocommands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001539 quickfix quickfix buffer, contains list of errors |:cwindow|
Bram Moolenaar280f1262006-01-30 00:14:18 +00001540 or list of locations |:lwindow|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001541 help help buffer (you are not supposed to set this
1542 manually)
Bram Moolenaar1f2903c2017-07-23 19:51:01 +02001543 terminal buffer for a |terminal| (you are not supposed to set
1544 this manually)
Bram Moolenaarf2732452018-06-03 14:47:35 +02001545 prompt buffer where only the last line can be edited, meant
1546 to be used by a plugin, see |prompt-buffer|
1547 {only when compiled with the |+channel| feature}
Bram Moolenaar4d784b22019-05-25 19:51:39 +02001548 popup buffer used in a popup window, see |popup|.
1549 {only when compiled with the |+textprop| feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001550
1551 This option is used together with 'bufhidden' and 'swapfile' to
1552 specify special kinds of buffers. See |special-buffers|.
Bram Moolenaarebdf3c92020-02-15 21:41:42 +01001553 Also see |win_gettype()|, which returns the type of the window.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001554
1555 Be careful with changing this option, it can have many side effects!
Bram Moolenaar113cb512021-11-07 20:27:04 +00001556 One such effect is that Vim will not check the timestamp of the file,
1557 if the file is changed by another program this will not be noticed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001558
Bram Moolenaar280f1262006-01-30 00:14:18 +00001559 A "quickfix" buffer is only used for the error list and the location
1560 list. This value is set by the |:cwindow| and |:lwindow| commands and
1561 you are not supposed to change it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001562
1563 "nofile" and "nowrite" buffers are similar:
1564 both: The buffer is not to be written to disk, ":w" doesn't
1565 work (":w filename" does work though).
1566 both: The buffer is never considered to be |'modified'|.
1567 There is no warning when the changes will be lost, for
1568 example when you quit Vim.
1569 both: A swap file is only created when using too much memory
1570 (when 'swapfile' has been reset there is never a swap
1571 file).
1572 nofile only: The buffer name is fixed, it is not handled like a
1573 file name. It is not modified in response to a |:cd|
1574 command.
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01001575 both: When using ":e bufname" and already editing "bufname"
1576 the buffer is made empty and autocommands are
1577 triggered as usual for |:edit|.
Bram Moolenaar21cf8232004-07-16 20:18:37 +00001578 *E676*
1579 "acwrite" implies that the buffer name is not related to a file, like
1580 "nofile", but it will be written. Thus, in contrast to "nofile" and
1581 "nowrite", ":w" does work and a modified buffer can't be abandoned
1582 without saving. For writing there must be matching |BufWriteCmd|,
1583 |FileWriteCmd| or |FileAppendCmd| autocommands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001584
1585 *'casemap'* *'cmp'*
1586'casemap' 'cmp' string (default: "internal,keepascii")
1587 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001588 Specifies details about changing the case of letters. It may contain
1589 these words, separated by a comma:
1590 internal Use internal case mapping functions, the current
1591 locale does not change the case mapping. This only
Bram Moolenaar6f16eb82005-08-23 21:02:42 +00001592 matters when 'encoding' is a Unicode encoding,
1593 "latin1" or "iso-8859-15". When "internal" is
1594 omitted, the towupper() and towlower() system library
1595 functions are used when available.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001596 keepascii For the ASCII characters (0x00 to 0x7f) use the US
1597 case mapping, the current locale is not effective.
1598 This probably only matters for Turkish.
1599
Bram Moolenaar938ae282023-02-20 20:44:55 +00001600 *'cdhome'* *'cdh'* *'nocdhome'* *'nocdh'*
Bram Moolenaar7b1463b2021-12-11 17:24:39 +00001601'cdhome' 'cdh' boolean (default: off)
1602 global
1603 When on, |:cd|, |:tcd| and |:lcd| without an argument changes the
1604 current working directory to the |$HOME| directory like in Unix.
1605 When off, those commands just print the current directory name.
1606 On Unix this option has no effect.
1607 NOTE: This option is reset when 'compatible' is set.
1608
Bram Moolenaar071d4272004-06-13 20:20:40 +00001609 *'cdpath'* *'cd'* *E344* *E346*
1610'cdpath' 'cd' string (default: equivalent to $CDPATH or ",,")
1611 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001612 This is a list of directories which will be searched when using the
Bram Moolenaar00aa0692019-04-27 20:37:57 +02001613 |:cd|, |:tcd| and |:lcd| commands, provided that the directory being
1614 searched for has a relative path, not an absolute part starting with
1615 "/", "./" or "../", the 'cdpath' option is not used then.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001616 The 'cdpath' option's value has the same form and semantics as
1617 |'path'|. Also see |file-searching|.
1618 The default value is taken from $CDPATH, with a "," prepended to look
1619 in the current directory first.
1620 If the default value taken from $CDPATH is not what you want, include
1621 a modified version of the following command in your vimrc file to
1622 override it: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001623 :let &cdpath = ',' .. substitute(substitute($CDPATH, '[, ]', '\\\0', 'g'), ':', ',', 'g')
Bram Moolenaar071d4272004-06-13 20:20:40 +00001624< This option cannot be set from a |modeline| or in the |sandbox|, for
1625 security reasons.
1626 (parts of 'cdpath' can be passed to the shell to expand file names).
1627
1628 *'cedit'*
1629'cedit' string (Vi default: "", Vim default: CTRL-F)
1630 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001631 The key used in Command-line Mode to open the command-line window.
1632 The default is CTRL-F when 'compatible' is off.
1633 Only non-printable keys are allowed.
1634 The key can be specified as a single character, but it is difficult to
1635 type. The preferred way is to use the <> notation. Examples: >
Bram Moolenaare18dbe82016-07-02 21:42:23 +02001636 :exe "set cedit=\<C-Y>"
1637 :exe "set cedit=\<Esc>"
Bram Moolenaar071d4272004-06-13 20:20:40 +00001638< |Nvi| also has this option, but it only uses the first character.
1639 See |cmdwin|.
Bram Moolenaar036986f2017-03-16 17:41:02 +01001640 NOTE: This option is set to the Vim default value when 'compatible'
1641 is reset.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001642
1643 *'charconvert'* *'ccv'* *E202* *E214* *E513*
1644'charconvert' 'ccv' string (default "")
1645 global
Bram Moolenaar4c92e752019-02-17 21:18:32 +01001646 {only available when compiled with the |+eval| feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001647 An expression that is used for character encoding conversion. It is
1648 evaluated when a file that is to be read or has been written has a
1649 different encoding from what is desired.
1650 'charconvert' is not used when the internal iconv() function is
1651 supported and is able to do the conversion. Using iconv() is
1652 preferred, because it is much faster.
1653 'charconvert' is not used when reading stdin |--|, because there is no
1654 file to convert from. You will have to save the text in a file first.
Bram Moolenaarf10911e2022-01-29 22:20:48 +00001655 The expression must return zero, false or an empty string for success,
1656 non-zero or true for failure.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001657 The possible encoding names encountered are in 'encoding'.
1658 Additionally, names given in 'fileencodings' and 'fileencoding' are
1659 used.
1660 Conversion between "latin1", "unicode", "ucs-2", "ucs-4" and "utf-8"
1661 is done internally by Vim, 'charconvert' is not used for this.
1662 'charconvert' is also used to convert the viminfo file, if the 'c'
1663 flag is present in 'viminfo'. Also used for Unicode conversion.
1664 Example: >
1665 set charconvert=CharConvert()
1666 fun CharConvert()
1667 system("recode "
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001668 \ .. v:charconvert_from .. ".." .. v:charconvert_to
1669 \ .. " <" .. v:fname_in .. " >" .. v:fname_out)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001670 return v:shell_error
1671 endfun
1672< The related Vim variables are:
1673 v:charconvert_from name of the current encoding
1674 v:charconvert_to name of the desired encoding
1675 v:fname_in name of the input file
1676 v:fname_out name of the output file
1677 Note that v:fname_in and v:fname_out will never be the same.
1678 Note that v:charconvert_from and v:charconvert_to may be different
1679 from 'encoding'. Vim internally uses UTF-8 instead of UCS-2 or UCS-4.
Bram Moolenaarf10911e2022-01-29 22:20:48 +00001680
Bram Moolenaara4e0b972022-10-01 19:43:52 +01001681 The advantage of using a function call without arguments is that it is
1682 faster, see |expr-option-function|.
1683
Bram Moolenaar071d4272004-06-13 20:20:40 +00001684 Encryption is not done by Vim when using 'charconvert'. If you want
1685 to encrypt the file after conversion, 'charconvert' should take care
1686 of this.
Bram Moolenaarf10911e2022-01-29 22:20:48 +00001687
1688 If the 'charconvert' expression starts with s: or |<SID>|, then it is
1689 replaced with the script ID (|local-function|). Example: >
1690 set charconvert=s:MyConvert()
1691 set charconvert=<SID>SomeConvert()
1692< Otherwise the expression is evaluated in the context of the script
1693 where the option was set, thus script-local items are available.
1694
Bram Moolenaar071d4272004-06-13 20:20:40 +00001695 This option cannot be set from a |modeline| or in the |sandbox|, for
1696 security reasons.
1697
1698 *'cindent'* *'cin'* *'nocindent'* *'nocin'*
1699'cindent' 'cin' boolean (default off)
1700 local to buffer
Bram Moolenaar446cb832008-06-24 21:56:24 +00001701 Enables automatic C program indenting. See 'cinkeys' to set the keys
Bram Moolenaar071d4272004-06-13 20:20:40 +00001702 that trigger reindenting in insert mode and 'cinoptions' to set your
1703 preferred indent style.
1704 If 'indentexpr' is not empty, it overrules 'cindent'.
1705 If 'lisp' is not on and both 'indentexpr' and 'equalprg' are empty,
1706 the "=" operator indents using this algorithm rather than calling an
1707 external program.
1708 See |C-indenting|.
1709 When you don't like the way 'cindent' works, try the 'smartindent'
1710 option or 'indentexpr'.
1711 This option is not used when 'paste' is set.
1712 NOTE: This option is reset when 'compatible' is set.
1713
1714 *'cinkeys'* *'cink'*
Bram Moolenaarce655742019-01-31 14:12:57 +01001715'cinkeys' 'cink' string (default "0{,0},0),0],:,0#,!^F,o,O,e")
Bram Moolenaar071d4272004-06-13 20:20:40 +00001716 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001717 A list of keys that, when typed in Insert mode, cause reindenting of
1718 the current line. Only used if 'cindent' is on and 'indentexpr' is
1719 empty.
1720 For the format of this option see |cinkeys-format|.
1721 See |C-indenting|.
1722
1723 *'cinoptions'* *'cino'*
1724'cinoptions' 'cino' string (default "")
1725 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001726 The 'cinoptions' affect the way 'cindent' reindents lines in a C
1727 program. See |cinoptions-values| for the values of this option, and
1728 |C-indenting| for info on C indenting in general.
1729
1730
1731 *'cinwords'* *'cinw'*
1732'cinwords' 'cinw' string (default "if,else,while,do,for,switch")
1733 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001734 These keywords start an extra indent in the next line when
1735 'smartindent' or 'cindent' is set. For 'cindent' this is only done at
1736 an appropriate place (inside {}).
1737 Note that 'ignorecase' isn't used for 'cinwords'. If case doesn't
1738 matter, include the keyword both the uppercase and lowercase:
1739 "if,If,IF".
1740
Tom Praschan3506cf32022-04-07 12:39:08 +01001741 *'cinscopedecls'* *'cinsd'*
1742'cinscopedecls' 'cinsd' string (default "public,protected,private")
1743 local to buffer
Tom Praschan3506cf32022-04-07 12:39:08 +01001744 Keywords that are interpreted as a C++ scope declaration by |cino-g|.
1745 Useful e.g. for working with the Qt framework that defines additional
1746 scope declarations "signals", "public slots" and "private slots": >
1747 set cinscopedecls+=signals,public\ slots,private\ slots
1748
1749< *'clipboard'* *'cb'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001750'clipboard' 'cb' string (default "autoselect,exclude:cons\|linux"
1751 for X-windows, "" otherwise)
1752 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001753 {only in GUI versions or when the |+xterm_clipboard|
1754 feature is included}
Tom Praschan3506cf32022-04-07 12:39:08 +01001755 This option is a list of comma-separated names.
Bram Moolenaar942db232021-02-13 18:14:48 +01001756 Note: if one of the items is "exclude:", then you can't add an item
Bram Moolenaar5ed11532022-07-06 13:18:11 +01001757 after that. Therefore do not append an item with += but use ^= to
Bram Moolenaar942db232021-02-13 18:14:48 +01001758 prepend, e.g.: >
1759 set clipboard^=unnamed
Bram Moolenaar9fbdbb82022-09-27 17:30:34 +01001760< When using the GUI see |'go-A'|.
1761 These names are recognized:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001762
Bram Moolenaarc0885aa2012-07-10 16:49:23 +02001763 *clipboard-unnamed*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001764 unnamed When included, Vim will use the clipboard register '*'
1765 for all yank, delete, change and put operations which
1766 would normally go to the unnamed register. When a
1767 register is explicitly specified, it will always be
1768 used regardless of whether "unnamed" is in 'clipboard'
1769 or not. The clipboard register can always be
1770 explicitly accessed using the "* notation. Also see
1771 |gui-clipboard|.
1772
Bram Moolenaar30b65812012-07-12 22:01:11 +02001773 *clipboard-unnamedplus*
Bram Moolenaar00154502013-02-13 16:15:55 +01001774 unnamedplus A variant of the "unnamed" flag which uses the
1775 clipboard register '+' (|quoteplus|) instead of
1776 register '*' for all yank, delete, change and put
1777 operations which would normally go to the unnamed
1778 register. When "unnamed" is also included to the
1779 option, yank operations (but not delete, change or
1780 put) will additionally copy the text into register
1781 '*'.
Bram Moolenaar81af9252010-12-10 20:35:50 +01001782 Only available with the |+X11| feature.
Bram Moolenaarbf9680e2010-12-02 21:43:16 +01001783 Availability can be checked with: >
1784 if has('unnamedplus')
1785<
Bram Moolenaar30b65812012-07-12 22:01:11 +02001786 *clipboard-autoselect*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001787 autoselect Works like the 'a' flag in 'guioptions': If present,
1788 then whenever Visual mode is started, or the Visual
1789 area extended, Vim tries to become the owner of the
1790 windowing system's global selection or put the
1791 selected text on the clipboard used by the selection
Bram Moolenaarba3ff532018-11-04 14:45:49 +01001792 register "*. See |'go-a'| and |quotestar| for details.
1793 When the GUI is active, the 'a' flag in 'guioptions'
1794 is used, when the GUI is not active, this "autoselect"
1795 flag is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001796 Also applies to the modeless selection.
1797
Bram Moolenaarc0885aa2012-07-10 16:49:23 +02001798 *clipboard-autoselectplus*
1799 autoselectplus Like "autoselect" but using the + register instead of
1800 the * register. Compare to the 'P' flag in
1801 'guioptions'.
1802
1803 *clipboard-autoselectml*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001804 autoselectml Like "autoselect", but for the modeless selection
1805 only. Compare to the 'A' flag in 'guioptions'.
1806
Bram Moolenaarc0885aa2012-07-10 16:49:23 +02001807 *clipboard-html*
Bram Moolenaar3a6eaa52009-06-16 13:23:06 +00001808 html When the clipboard contains HTML, use this when
1809 pasting. When putting text on the clipboard, mark it
1810 as HTML. This works to copy rendered HTML from
1811 Firefox, paste it as raw HTML in Vim, select the HTML
1812 in Vim and paste it in a rich edit box in Firefox.
Bram Moolenaar20a825a2010-05-31 21:27:30 +02001813 You probably want to add this only temporarily,
1814 possibly use BufEnter autocommands.
Bram Moolenaar3a6eaa52009-06-16 13:23:06 +00001815 Only supported for GTK version 2 and later.
Bram Moolenaar3a6eaa52009-06-16 13:23:06 +00001816
Bram Moolenaarc0885aa2012-07-10 16:49:23 +02001817 *clipboard-exclude*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001818 exclude:{pattern}
1819 Defines a pattern that is matched against the name of
1820 the terminal 'term'. If there is a match, no
1821 connection will be made to the X server. This is
1822 useful in this situation:
1823 - Running Vim in a console.
1824 - $DISPLAY is set to start applications on another
1825 display.
1826 - You do not want to connect to the X server in the
1827 console, but do want this in a terminal emulator.
1828 To never connect to the X server use: >
1829 exclude:.*
1830< This has the same effect as using the |-X| argument.
1831 Note that when there is no connection to the X server
1832 the window title won't be restored and the clipboard
1833 cannot be accessed.
1834 The value of 'magic' is ignored, {pattern} is
1835 interpreted as if 'magic' was on.
1836 The rest of the option value will be used for
1837 {pattern}, this must be the last entry.
1838
1839 *'cmdheight'* *'ch'*
1840'cmdheight' 'ch' number (default 1)
Shougo Matsushitaf39cfb72022-07-30 16:54:05 +01001841 global or local to tab page
Bram Moolenaara2a89732022-08-31 14:46:18 +01001842 Number of screen lines to use for the command-line. A larger value
1843 helps avoiding |hit-enter| prompts.
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001844 The value of this option is stored with the tab page, so that each tab
1845 page can have a different value.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001846
1847 *'cmdwinheight'* *'cwh'*
1848'cmdwinheight' 'cwh' number (default 7)
1849 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001850 Number of screen lines to use for the command-line window. |cmdwin|
1851
Bram Moolenaar483c5d82010-10-20 18:45:33 +02001852 *'colorcolumn'* *'cc'*
1853'colorcolumn' 'cc' string (default "")
1854 local to window
Bram Moolenaar483c5d82010-10-20 18:45:33 +02001855 {not available when compiled without the |+syntax|
1856 feature}
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01001857 'colorcolumn' is a comma-separated list of screen columns that are
Bram Moolenaar483c5d82010-10-20 18:45:33 +02001858 highlighted with ColorColumn |hl-ColorColumn|. Useful to align
1859 text. Will make screen redrawing slower.
1860 The screen column can be an absolute number, or a number preceded with
1861 '+' or '-', which is added to or subtracted from 'textwidth'. >
1862
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01001863 :set cc=+1 " highlight column after 'textwidth'
Bram Moolenaar483c5d82010-10-20 18:45:33 +02001864 :set cc=+1,+2,+3 " highlight three columns after 'textwidth'
1865 :hi ColorColumn ctermbg=lightgrey guibg=lightgrey
1866<
1867 When 'textwidth' is zero then the items with '-' and '+' are not used.
1868 A maximum of 256 columns are highlighted.
1869
Bram Moolenaar071d4272004-06-13 20:20:40 +00001870 *'columns'* *'co'* *E594*
1871'columns' 'co' number (default 80 or terminal width)
1872 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001873 Number of columns of the screen. Normally this is set by the terminal
Bram Moolenaar7c626922005-02-07 22:01:03 +00001874 initialization and does not have to be set by hand. Also see
1875 |posix-screen-size|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001876 When Vim is running in the GUI or in a resizable window, setting this
1877 option will cause the window size to be changed. When you only want
1878 to use the size for the GUI, put the command in your |gvimrc| file.
1879 When you set this option and Vim is unable to change the physical
Bram Moolenaar02467872007-05-06 13:22:01 +00001880 number of columns of the display, the display may be messed up. For
1881 the GUI it is always possible and Vim limits the number of columns to
1882 what fits on the screen. You can use this command to get the widest
1883 window possible: >
1884 :set columns=9999
1885< Minimum value is 12, maximum value is 10000.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001886
1887 *'comments'* *'com'* *E524* *E525*
1888'comments' 'com' string (default
1889 "s1:/*,mb:*,ex:*/,://,b:#,:%,:XCOMM,n:>,fb:-")
1890 local to buffer
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01001891 A comma-separated list of strings that can start a comment line. See
Bram Moolenaar071d4272004-06-13 20:20:40 +00001892 |format-comments|. See |option-backslash| about using backslashes to
1893 insert a space.
1894
1895 *'commentstring'* *'cms'* *E537*
1896'commentstring' 'cms' string (default "/*%s*/")
1897 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001898 {not available when compiled without the |+folding|
1899 feature}
1900 A template for a comment. The "%s" in the value is replaced with the
1901 comment text. Currently only used to add markers for folding, see
1902 |fold-marker|.
1903
1904 *'compatible'* *'cp'* *'nocompatible'* *'nocp'*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001905'compatible' 'cp' boolean (default on, off when a |vimrc| or |gvimrc|
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +02001906 file is found, reset in |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001907 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001908 This option has the effect of making Vim either more Vi-compatible, or
1909 make Vim behave in a more useful way.
Bram Moolenaar214641f2017-03-05 17:04:09 +01001910
Bram Moolenaar071d4272004-06-13 20:20:40 +00001911 This is a special kind of option, because when it's set or reset,
Bram Moolenaar214641f2017-03-05 17:04:09 +01001912 other options are also changed as a side effect.
1913 NOTE: Setting or resetting this option can have a lot of unexpected
1914 effects: Mappings are interpreted in another way, undo behaves
1915 differently, etc. If you set this option in your vimrc file, you
1916 should probably put it at the very start.
1917
Bram Moolenaar071d4272004-06-13 20:20:40 +00001918 By default this option is on and the Vi defaults are used for the
1919 options. This default was chosen for those people who want to use Vim
1920 just like Vi, and don't even (want to) know about the 'compatible'
1921 option.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001922 When a |vimrc| or |gvimrc| file is found while Vim is starting up,
Bram Moolenaard042c562005-06-30 22:04:15 +00001923 this option is switched off, and all options that have not been
1924 modified will be set to the Vim defaults. Effectively, this means
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001925 that when a |vimrc| or |gvimrc| file exists, Vim will use the Vim
Bram Moolenaard042c562005-06-30 22:04:15 +00001926 defaults, otherwise it will use the Vi defaults. (Note: This doesn't
Bram Moolenaar02467872007-05-06 13:22:01 +00001927 happen for the system-wide vimrc or gvimrc file, nor for a file given
1928 with the |-u| argument). Also see |compatible-default| and
1929 |posix-compliance|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001930 You can also set this option with the "-C" argument, and reset it with
1931 "-N". See |-C| and |-N|.
Bram Moolenaar214641f2017-03-05 17:04:09 +01001932 See 'cpoptions' for more fine tuning of Vi compatibility.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001933
Bram Moolenaar214641f2017-03-05 17:04:09 +01001934 When this option is set, numerous other options are set to make Vim as
1935 Vi-compatible as possible. When this option is unset, various options
1936 are set to make Vim more useful. The table below lists all the
1937 options affected.
1938 The {?} column indicates when the options are affected:
1939 + Means that the option is set to the value given in {set value} when
1940 'compatible' is set.
1941 & Means that the option is set to the value given in {set value} when
1942 'compatible' is set AND is set to its Vim default value when
1943 'compatible' is unset.
1944 - Means the option is NOT changed when setting 'compatible' but IS
1945 set to its Vim default when 'compatible' is unset.
1946 The {effect} column summarises the change when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001947
Bram Moolenaar036986f2017-03-16 17:41:02 +01001948 option ? set value effect ~
Bram Moolenaar214641f2017-03-05 17:04:09 +01001949
1950 'allowrevins' + off no CTRL-_ command
1951 'antialias' + off don't use antialiased fonts
Bram Moolenaarbe4e0162023-02-02 13:59:48 +00001952 'arabic' + off reset arabic-related options
Bram Moolenaar214641f2017-03-05 17:04:09 +01001953 'arabicshape' + on correct character shapes
1954 'backspace' + "" normal backspace
1955 'backup' + off no backup file
1956 'backupcopy' & Unix: "yes" backup file is a copy
1957 else: "auto" copy or rename backup file
1958 'balloonexpr' + "" text to show in evaluation balloon
1959 'breakindent' + off don't indent when wrapping lines
1960 'cedit' - {unchanged} {set vim default only on resetting 'cp'}
Bram Moolenaar7b1463b2021-12-11 17:24:39 +00001961 'cdhome' + off ":cd" don't chdir to home on non-Unix
Bram Moolenaar214641f2017-03-05 17:04:09 +01001962 'cindent' + off no C code indentation
1963 'compatible' - {unchanged} {set vim default only on resetting 'cp'}
1964 'copyindent' + off don't copy indent structure
1965 'cpoptions' & (all flags) Vi-compatible flags
1966 'cscopepathcomp'+ 0 don't show directories in tags list
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01001967 'cscoperelative'+ off don't use basename of path as prefix
Bram Moolenaar214641f2017-03-05 17:04:09 +01001968 'cscopetag' + off don't use cscope for ":tag"
Bram Moolenaar036986f2017-03-16 17:41:02 +01001969 'cscopetagorder'+ 0 see |cscopetagorder|
Bram Moolenaar214641f2017-03-05 17:04:09 +01001970 'cscopeverbose' + off see |cscopeverbose|
1971 'delcombine' + off unicode: delete whole char combination
1972 'digraph' + off no digraphs
1973 'esckeys' & off no <Esc>-keys in Insert mode
Christian Brabandt5f5131d2023-10-25 21:44:26 +02001974 this also disables |modifyOtherKeys|
1975 and |xterm-bracketed-paste|
Bram Moolenaar214641f2017-03-05 17:04:09 +01001976 'expandtab' + off tabs not expanded to spaces
1977 'fileformats' & "" no automatic file format detection,
Bram Moolenaar6f345a12019-12-17 21:27:18 +01001978 "dos,unix" except for MS-Windows
Bram Moolenaar214641f2017-03-05 17:04:09 +01001979 'formatexpr' + "" use 'formatprg' for auto-formatting
1980 'formatoptions' & "vt" Vi compatible formatting
1981 'gdefault' + off no default 'g' flag for ":s"
1982 'history' & 0 no commandline history
1983 'hkmap' + off no Hebrew keyboard mapping
1984 'hkmapp' + off no phonetic Hebrew keyboard mapping
1985 'hlsearch' + off no highlighting of search matches
1986 'incsearch' + off no incremental searching
1987 'indentexpr' + "" no indenting by expression
1988 'insertmode' + off do not start in Insert mode
1989 'iskeyword' & "@,48-57,_" keywords contain alphanumeric
Bram Moolenaar071d4272004-06-13 20:20:40 +00001990 characters and '_'
Bram Moolenaar214641f2017-03-05 17:04:09 +01001991 'joinspaces' + on insert 2 spaces after period
1992 'modeline' & off no modelines
1993 'more' & off no pauses in listings
1994 'mzquantum' - {unchanged} {set vim default only on resetting 'cp'}
1995 'numberwidth' & 8 min number of columns for line number
1996 'preserveindent'+ off don't preserve current indent structure
1997 when changing it
1998 'revins' + off no reverse insert
1999 'ruler' + off no ruler
2000 'scrolljump' + 1 no jump scroll
2001 'scrolloff' + 0 no scroll offset
2002 'shelltemp' - {unchanged} {set vim default only on resetting 'cp'}
2003 'shiftround' + off indent not rounded to shiftwidth
Bram Moolenaar9dfa3132019-05-04 21:08:40 +02002004 'shortmess' & "S" no shortening of messages
Bram Moolenaar214641f2017-03-05 17:04:09 +01002005 'showcmd' & off command characters not shown
2006 'showmode' & off current mode not shown
2007 'sidescrolloff' + 0 cursor moves to edge of screen in scroll
2008 'smartcase' + off no automatic ignore case switch
2009 'smartindent' + off no smart indentation
2010 'smarttab' + off no smart tab size
2011 'softtabstop' + 0 tabs are always 'tabstop' positions
2012 'startofline' + on goto startofline with some commands
2013 'tagcase' & "followic" 'ignorecase' when searching tags file
2014 'tagrelative' & off tag file names are not relative
2015 'termguicolors' + off don't use highlight-(guifg|guibg)
2016 'textauto' & off no automatic textmode detection
2017 'textwidth' + 0 no automatic line wrap
2018 'tildeop' + off tilde is not an operator
2019 'ttimeout' + off no terminal timeout
2020 'undofile' + off don't use an undo file
Bram Moolenaar036986f2017-03-16 17:41:02 +01002021 'viminfo' - {unchanged} {set Vim default only on resetting 'cp'}
Bram Moolenaar214641f2017-03-05 17:04:09 +01002022 'virtualedit' + "" cursor can only be placed on characters
2023 'whichwrap' & "" left-right movements don't wrap
2024 'wildchar' & CTRL-E only when the current value is <Tab>
Bram Moolenaar071d4272004-06-13 20:20:40 +00002025 use CTRL-E for cmdline completion
Bram Moolenaar214641f2017-03-05 17:04:09 +01002026 'writebackup' + on or off depends on the |+writebackup| feature
Bram Moolenaar071d4272004-06-13 20:20:40 +00002027
2028 *'complete'* *'cpt'* *E535*
2029'complete' 'cpt' string (default: ".,w,b,u,t,i")
2030 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00002031 This option specifies how keyword completion |ins-completion| works
2032 when CTRL-P or CTRL-N are used. It is also used for whole-line
2033 completion |i_CTRL-X_CTRL-L|. It indicates the type of completion
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01002034 and the places to scan. It is a comma-separated list of flags:
Bram Moolenaar3848e002016-03-19 18:42:29 +01002035 . scan the current buffer ('wrapscan' is ignored)
Bram Moolenaar071d4272004-06-13 20:20:40 +00002036 w scan buffers from other windows
2037 b scan other loaded buffers that are in the buffer list
2038 u scan the unloaded buffers that are in the buffer list
2039 U scan the buffers that are not in the buffer list
2040 k scan the files given with the 'dictionary' option
Bram Moolenaar0b238792006-03-02 22:49:12 +00002041 kspell use the currently active spell checking |spell|
Bram Moolenaar071d4272004-06-13 20:20:40 +00002042 k{dict} scan the file {dict}. Several "k" flags can be given,
2043 patterns are valid too. For example: >
2044 :set cpt=k/usr/dict/*,k~/spanish
2045< s scan the files given with the 'thesaurus' option
2046 s{tsr} scan the file {tsr}. Several "s" flags can be given, patterns
2047 are valid too.
2048 i scan current and included files
2049 d scan current and included files for defined name or macro
2050 |i_CTRL-X_CTRL-D|
2051 ] tag completion
2052 t same as "]"
2053
2054 Unloaded buffers are not loaded, thus their autocmds |:autocmd| are
2055 not executed, this may lead to unexpected completions from some files
2056 (gzipped files for example). Unloaded buffers are not scanned for
2057 whole-line completion.
2058
2059 The default is ".,w,b,u,t,i", which means to scan:
2060 1. the current buffer
2061 2. buffers in other windows
2062 3. other loaded buffers
2063 4. unloaded buffers
2064 5. tags
2065 6. included files
2066
2067 As you can see, CTRL-N and CTRL-P can be used to do any 'iskeyword'-
Bram Moolenaar582fd852005-03-28 20:58:01 +00002068 based expansion (e.g., dictionary |i_CTRL-X_CTRL-K|, included patterns
2069 |i_CTRL-X_CTRL-I|, tags |i_CTRL-X_CTRL-]| and normal expansions).
Bram Moolenaar071d4272004-06-13 20:20:40 +00002070
Bram Moolenaarcfbc5ee2004-07-02 15:38:35 +00002071 *'completefunc'* *'cfu'*
2072'completefunc' 'cfu' string (default: empty)
2073 local to buffer
Bram Moolenaardb84e452010-08-15 13:50:43 +02002074 {not available when compiled without the |+eval|
Bram Moolenaare2c453d2019-08-21 14:37:09 +02002075 feature}
Bram Moolenaarc7486e02005-12-29 22:48:26 +00002076 This option specifies a function to be used for Insert mode completion
2077 with CTRL-X CTRL-U. |i_CTRL-X_CTRL-U|
Bram Moolenaar280f1262006-01-30 00:14:18 +00002078 See |complete-functions| for an explanation of how the function is
Yegappan Lakshmanan8658c752021-12-03 11:09:29 +00002079 invoked and what it should return. The value can be the name of a
2080 function, a |lambda| or a |Funcref|. See |option-value-function| for
2081 more information.
Bram Moolenaar166af9b2010-11-16 20:34:40 +01002082 This option cannot be set from a |modeline| or in the |sandbox|, for
2083 security reasons.
Bram Moolenaar325b7a22004-07-05 15:58:32 +00002084
Bram Moolenaarac3150d2019-07-28 16:36:39 +02002085 *'completeslash'* *'csl'*
2086'completeslash' 'csl' string (default: "")
2087 local to buffer
Bram Moolenaar2e693a82019-10-16 22:35:02 +02002088 {only for MS-Windows}
Bram Moolenaarac3150d2019-07-28 16:36:39 +02002089 When this option is set it overrules 'shellslash' for completion:
2090 - When this option is set to "slash", a forward slash is used for path
2091 completion in insert mode. This is useful when editing HTML tag, or
Bram Moolenaar6f345a12019-12-17 21:27:18 +01002092 Makefile with 'noshellslash' on MS-Windows.
Bram Moolenaarac3150d2019-07-28 16:36:39 +02002093 - When this option is set to "backslash", backslash is used. This is
Bram Moolenaar6f345a12019-12-17 21:27:18 +01002094 useful when editing a batch file with 'shellslash' set on MS-Windows.
Bram Moolenaarac3150d2019-07-28 16:36:39 +02002095 - When this option is empty, same character is used as for
2096 'shellslash'.
2097 For Insert mode completion the buffer-local value is used. For
2098 command line completion the global value is used.
2099
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00002100 *'completeopt'* *'cot'*
Bram Moolenaar96d2c5b2006-03-11 21:27:59 +00002101'completeopt' 'cot' string (default: "menu,preview")
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00002102 global
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01002103 A comma-separated list of options for Insert mode completion
Bram Moolenaarc7453f52006-02-10 23:20:28 +00002104 |ins-completion|. The supported values are:
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00002105
2106 menu Use a popup menu to show the possible completions. The
2107 menu is only shown when there is more than one match and
2108 sufficient colors are available. |ins-completion-menu|
2109
Bram Moolenaar65c923a2006-03-03 22:56:30 +00002110 menuone Use the popup menu also when there is only one match.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00002111 Useful when there is additional information about the
Bram Moolenaar65c923a2006-03-03 22:56:30 +00002112 match, e.g., what file it comes from.
2113
Bram Moolenaarc1e37902006-04-18 21:55:01 +00002114 longest Only insert the longest common text of the matches. If
2115 the menu is displayed you can use CTRL-L to add more
2116 characters. Whether case is ignored depends on the kind
2117 of completion. For buffer text the 'ignorecase' option is
2118 used.
Bram Moolenaarc7453f52006-02-10 23:20:28 +00002119
Bram Moolenaar96d2c5b2006-03-11 21:27:59 +00002120 preview Show extra information about the currently selected
Bram Moolenaar02467872007-05-06 13:22:01 +00002121 completion in the preview window. Only works in
2122 combination with "menu" or "menuone".
2123
Bram Moolenaar576a4a62019-08-18 15:25:17 +02002124 popup Show extra information about the currently selected
2125 completion in a popup window. Only works in combination
2126 with "menu" or "menuone". Overrides "preview".
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02002127 See |'completepopup'| for specifying properties.
Bram Moolenaar2e693a82019-10-16 22:35:02 +02002128 {only works when compiled with the |+textprop| feature}
Bram Moolenaar576a4a62019-08-18 15:25:17 +02002129
Bram Moolenaardca7abe2019-10-20 18:17:57 +02002130 popuphidden
Bram Moolenaar0c0734d2019-11-26 21:44:46 +01002131 Just like "popup" but initially hide the popup. Use a
Bram Moolenaardca7abe2019-10-20 18:17:57 +02002132 |CompleteChanged| autocommand to fetch the info and call
2133 |popup_show()| once the popup has been filled.
2134 See the example at |complete-popuphidden|.
2135 {only works when compiled with the |+textprop| feature}
2136
Bram Moolenaarb6be1e22015-07-10 18:18:40 +02002137 noinsert Do not insert any text for a match until the user selects
2138 a match from the menu. Only works in combination with
2139 "menu" or "menuone". No effect if "longest" is present.
2140
2141 noselect Do not select a match in the menu, force the user to
2142 select one from the menu. Only works in combination with
2143 "menu" or "menuone".
2144
Bram Moolenaar96d2c5b2006-03-11 21:27:59 +00002145
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02002146 *'completepopup'* *'cpp'*
2147'completepopup' 'cpp' string (default empty)
2148 global
2149 {not available when compiled without the |+textprop|
2150 or |+quickfix| feature}
2151 When 'completeopt' contains "popup" then this option is used for the
Bram Moolenaar447bfba2020-07-18 16:07:16 +02002152 properties of the info popup when it is created. If an info popup
2153 window already exists it is closed, so that the option value is
2154 applied when it is created again.
2155 You can also use |popup_findinfo()| and then set properties for an
2156 existing info popup with |popup_setoptions()|. See |complete-popup|.
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02002157
2158
Bram Moolenaarf5963f72010-07-23 22:10:27 +02002159 *'concealcursor'* *'cocu'*
2160'concealcursor' 'cocu' string (default: "")
2161 local to window
Bram Moolenaarf5963f72010-07-23 22:10:27 +02002162 {not available when compiled without the |+conceal|
2163 feature}
2164 Sets the modes in which text in the cursor line can also be concealed.
2165 When the current mode is listed then concealing happens just like in
2166 other lines.
2167 n Normal mode
2168 v Visual mode
2169 i Insert mode
Bram Moolenaarca8c9862010-07-24 15:00:38 +02002170 c Command line editing, for 'incsearch'
Bram Moolenaarf5963f72010-07-23 22:10:27 +02002171
Bram Moolenaare6dc5732010-07-24 23:52:26 +02002172 'v' applies to all lines in the Visual area, not only the cursor.
Bram Moolenaarca8c9862010-07-24 15:00:38 +02002173 A useful value is "nc". This is used in help files. So long as you
Bram Moolenaarf5963f72010-07-23 22:10:27 +02002174 are moving around text is concealed, but when starting to insert text
2175 or selecting a Visual area the concealed text is displayed, so that
2176 you can see what you are doing.
Bram Moolenaarf70e3d62010-07-24 13:15:07 +02002177 Keep in mind that the cursor position is not always where it's
2178 displayed. E.g., when moving vertically it may change column.
Bram Moolenaarf5963f72010-07-23 22:10:27 +02002179
2180
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002181 *'conceallevel'* *'cole'*
2182'conceallevel' 'cole' number (default 0)
Bram Moolenaar860cae12010-06-05 23:22:07 +02002183 local to window
Bram Moolenaar860cae12010-06-05 23:22:07 +02002184 {not available when compiled without the |+conceal|
2185 feature}
Bram Moolenaar6df6f472010-07-18 18:04:50 +02002186 Determine how text with the "conceal" syntax attribute |:syn-conceal|
2187 is shown:
Bram Moolenaar860cae12010-06-05 23:22:07 +02002188
Bram Moolenaar6df6f472010-07-18 18:04:50 +02002189 Value Effect ~
Bram Moolenaar860cae12010-06-05 23:22:07 +02002190 0 Text is shown normally
Bram Moolenaar477db062010-07-28 18:17:41 +02002191 1 Each block of concealed text is replaced with one
2192 character. If the syntax item does not have a custom
2193 replacement character defined (see |:syn-cchar|) the
2194 character defined in 'listchars' is used (default is a
2195 space).
2196 It is highlighted with the "Conceal" highlight group.
Bram Moolenaar860cae12010-06-05 23:22:07 +02002197 2 Concealed text is completely hidden unless it has a
2198 custom replacement character defined (see
Bram Moolenaar477db062010-07-28 18:17:41 +02002199 |:syn-cchar|).
Bram Moolenaara7781e02010-07-19 20:13:22 +02002200 3 Concealed text is completely hidden.
Bram Moolenaar860cae12010-06-05 23:22:07 +02002201
Bram Moolenaara7781e02010-07-19 20:13:22 +02002202 Note: in the cursor line concealed text is not hidden, so that you can
Bram Moolenaarf5963f72010-07-23 22:10:27 +02002203 edit and copy the text. This can be changed with the 'concealcursor'
2204 option.
Bram Moolenaar860cae12010-06-05 23:22:07 +02002205
Bram Moolenaar071d4272004-06-13 20:20:40 +00002206 *'confirm'* *'cf'* *'noconfirm'* *'nocf'*
2207'confirm' 'cf' boolean (default off)
2208 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00002209 When 'confirm' is on, certain operations that would normally
2210 fail because of unsaved changes to a buffer, e.g. ":q" and ":e",
2211 instead raise a |dialog| asking if you wish to save the current
2212 file(s). You can still use a ! to unconditionally |abandon| a buffer.
2213 If 'confirm' is off you can still activate confirmation for one
2214 command only (this is most useful in mappings) with the |:confirm|
2215 command.
2216 Also see the |confirm()| function and the 'v' flag in 'guioptions'.
2217
2218 *'conskey'* *'consk'* *'noconskey'* *'noconsk'*
2219'conskey' 'consk' boolean (default off)
2220 global
Bram Moolenaarf3913272016-02-25 00:00:01 +01002221 This was for MS-DOS and is no longer supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002222
2223 *'copyindent'* *'ci'* *'nocopyindent'* *'noci'*
2224'copyindent' 'ci' boolean (default off)
2225 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00002226 Copy the structure of the existing lines indent when autoindenting a
2227 new line. Normally the new indent is reconstructed by a series of
2228 tabs followed by spaces as required (unless |'expandtab'| is enabled,
2229 in which case only spaces are used). Enabling this option makes the
2230 new line copy whatever characters were used for indenting on the
Bram Moolenaar446cb832008-06-24 21:56:24 +00002231 existing line. 'expandtab' has no effect on these characters, a Tab
2232 remains a Tab. If the new indent is greater than on the existing
Bram Moolenaar071d4272004-06-13 20:20:40 +00002233 line, the remaining space is filled in the normal manner.
Bram Moolenaar036986f2017-03-16 17:41:02 +01002234 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002235 Also see 'preserveindent'.
2236
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002237 *'cpoptions'* *'cpo'* *cpo*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002238'cpoptions' 'cpo' string (Vim default: "aABceFs",
2239 Vi default: all flags)
2240 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00002241 A sequence of single character flags. When a character is present
Bram Moolenaar7cba6c02013-09-05 22:13:31 +02002242 this indicates Vi-compatible behavior. This is used for things where
2243 not being Vi-compatible is mostly or sometimes preferred.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002244 'cpoptions' stands for "compatible-options".
2245 Commas can be added for readability.
2246 To avoid problems with flags that are added in the future, use the
2247 "+=" and "-=" feature of ":set" |add-option-flags|.
Bram Moolenaar71eb3ad2021-12-26 12:07:30 +00002248
Bram Moolenaar071d4272004-06-13 20:20:40 +00002249 NOTE: This option is set to the Vi default value when 'compatible' is
2250 set and to the Vim default value when 'compatible' is reset.
Bram Moolenaar71eb3ad2021-12-26 12:07:30 +00002251
2252 NOTE: In a |Vim9| script, when `vim9script` is encountered, the value
2253 is saved, 'cpoptions' is set to the Vim default, and the saved value
2254 is restored at the end of the script. Changes to the value of
2255 'cpoptions' will be applied to the saved value, but keep in mind that
2256 removing a flag that is not present when 'cpoptions' is changed has no
2257 effect. In the |.vimrc| file the value is not restored, thus using
2258 `vim9script` in the |.vimrc| file results in using the Vim default.
2259
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002260 NOTE: This option is set to the POSIX default value at startup when
2261 the Vi default value would be used and the $VIM_POSIX environment
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002262 variable exists |posix|. This means Vim tries to behave like the
2263 POSIX specification.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002264
2265 contains behavior ~
2266 *cpo-a*
2267 a When included, a ":read" command with a file name
2268 argument will set the alternate file name for the
2269 current window.
2270 *cpo-A*
2271 A When included, a ":write" command with a file name
2272 argument will set the alternate file name for the
2273 current window.
2274 *cpo-b*
2275 b "\|" in a ":map" command is recognized as the end of
2276 the map command. The '\' is included in the mapping,
2277 the text after the '|' is interpreted as the next
2278 command. Use a CTRL-V instead of a backslash to
2279 include the '|' in the mapping. Applies to all
2280 mapping, abbreviation, menu and autocmd commands.
2281 See also |map_bar|.
2282 *cpo-B*
2283 B A backslash has no special meaning in mappings,
Bram Moolenaara9604e62018-07-21 05:56:22 +02002284 abbreviations, user commands and the "to" part of the
2285 menu commands. Remove this flag to be able to use a
2286 backslash like a CTRL-V. For example, the command
2287 ":map X \<Esc>" results in X being mapped to:
Bram Moolenaar071d4272004-06-13 20:20:40 +00002288 'B' included: "\^[" (^[ is a real <Esc>)
2289 'B' excluded: "<Esc>" (5 characters)
2290 ('<' excluded in both cases)
2291 *cpo-c*
2292 c Searching continues at the end of any match at the
2293 cursor position, but not further than the start of the
2294 next line. When not present searching continues
2295 one character from the cursor position. With 'c'
2296 "abababababab" only gets three matches when repeating
2297 "/abab", without 'c' there are five matches.
2298 *cpo-C*
2299 C Do not concatenate sourced lines that start with a
2300 backslash. See |line-continuation|.
2301 *cpo-d*
2302 d Using "./" in the 'tags' option doesn't mean to use
2303 the tags file relative to the current file, but the
2304 tags file in the current directory.
2305 *cpo-D*
2306 D Can't use CTRL-K to enter a digraph after Normal mode
2307 commands with a character argument, like |r|, |f| and
2308 |t|.
2309 *cpo-e*
2310 e When executing a register with ":@r", always add a
2311 <CR> to the last line, also when the register is not
2312 linewise. If this flag is not present, the register
2313 is not linewise and the last line does not end in a
2314 <CR>, then the last line is put on the command-line
2315 and can be edited before hitting <CR>.
2316 *cpo-E*
2317 E It is an error when using "y", "d", "c", "g~", "gu" or
2318 "gU" on an Empty region. The operators only work when
Bram Moolenaar15142e22018-04-30 22:19:58 +02002319 at least one character is to be operated on. Example:
Bram Moolenaar071d4272004-06-13 20:20:40 +00002320 This makes "y0" fail in the first column.
2321 *cpo-f*
2322 f When included, a ":read" command with a file name
2323 argument will set the file name for the current buffer,
2324 if the current buffer doesn't have a file name yet.
2325 *cpo-F*
2326 F When included, a ":write" command with a file name
2327 argument will set the file name for the current
2328 buffer, if the current buffer doesn't have a file name
Bram Moolenaarb3480382005-12-11 21:33:32 +00002329 yet. Also see |cpo-P|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002330 *cpo-g*
2331 g Goto line 1 when using ":edit" without argument.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002332 *cpo-H*
2333 H When using "I" on a line with only blanks, insert
2334 before the last blank. Without this flag insert after
2335 the last blank.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002336 *cpo-i*
2337 i When included, interrupting the reading of a file will
2338 leave it modified.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002339 *cpo-I*
2340 I When moving the cursor up or down just after inserting
2341 indent for 'autoindent', do not delete the indent.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002342 *cpo-j*
2343 j When joining lines, only add two spaces after a '.',
2344 not after '!' or '?'. Also see 'joinspaces'.
2345 *cpo-J*
2346 J A |sentence| has to be followed by two spaces after
Bram Moolenaar582fd852005-03-28 20:58:01 +00002347 the '.', '!' or '?'. A <Tab> is not recognized as
Bram Moolenaar071d4272004-06-13 20:20:40 +00002348 white space.
2349 *cpo-k*
2350 k Disable the recognition of raw key codes in
2351 mappings, abbreviations, and the "to" part of menu
2352 commands. For example, if <Key> sends ^[OA (where ^[
2353 is <Esc>), the command ":map X ^[OA" results in X
2354 being mapped to:
2355 'k' included: "^[OA" (3 characters)
2356 'k' excluded: "<Key>" (one key code)
2357 Also see the '<' flag below.
2358 *cpo-K*
2359 K Don't wait for a key code to complete when it is
2360 halfway a mapping. This breaks mapping <F1><F1> when
2361 only part of the second <F1> has been read. It
2362 enables cancelling the mapping by typing <F1><Esc>.
2363 *cpo-l*
2364 l Backslash in a [] range in a search pattern is taken
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002365 literally, only "\]", "\^", "\-" and "\\" are special.
2366 See |/[]|
Bram Moolenaar071d4272004-06-13 20:20:40 +00002367 'l' included: "/[ \t]" finds <Space>, '\' and 't'
2368 'l' excluded: "/[ \t]" finds <Space> and <Tab>
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002369 Also see |cpo-\|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002370 *cpo-L*
2371 L When the 'list' option is set, 'wrapmargin',
2372 'textwidth', 'softtabstop' and Virtual Replace mode
2373 (see |gR|) count a <Tab> as two characters, instead of
2374 the normal behavior of a <Tab>.
2375 *cpo-m*
2376 m When included, a showmatch will always wait half a
2377 second. When not included, a showmatch will wait half
2378 a second or until a character is typed. |'showmatch'|
2379 *cpo-M*
2380 M When excluded, "%" matching will take backslashes into
2381 account. Thus in "( \( )" and "\( ( \)" the outer
2382 parenthesis match. When included "%" ignores
2383 backslashes, which is Vi compatible.
2384 *cpo-n*
Bram Moolenaar64486672010-05-16 15:46:46 +02002385 n When included, the column used for 'number' and
2386 'relativenumber' will also be used for text of wrapped
2387 lines.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002388 *cpo-o*
2389 o Line offset to search command is not remembered for
2390 next search.
2391 *cpo-O*
2392 O Don't complain if a file is being overwritten, even
2393 when it didn't exist when editing it. This is a
2394 protection against a file unexpectedly created by
2395 someone else. Vi didn't complain about this.
2396 *cpo-p*
2397 p Vi compatible Lisp indenting. When not present, a
2398 slightly better algorithm is used.
Bram Moolenaarb3480382005-12-11 21:33:32 +00002399 *cpo-P*
2400 P When included, a ":write" command that appends to a
2401 file will set the file name for the current buffer, if
2402 the current buffer doesn't have a file name yet and
2403 the 'F' flag is also included |cpo-F|.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002404 *cpo-q*
2405 q When joining multiple lines leave the cursor at the
2406 position where it would be when joining two lines.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002407 *cpo-r*
2408 r Redo ("." command) uses "/" to repeat a search
2409 command, instead of the actually used search string.
2410 *cpo-R*
2411 R Remove marks from filtered lines. Without this flag
2412 marks are kept like |:keepmarks| was used.
2413 *cpo-s*
2414 s Set buffer options when entering the buffer for the
2415 first time. This is like it is in Vim version 3.0.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002416 And it is the default. If not present the options are
Bram Moolenaar071d4272004-06-13 20:20:40 +00002417 set when the buffer is created.
2418 *cpo-S*
2419 S Set buffer options always when entering a buffer
2420 (except 'readonly', 'fileformat', 'filetype' and
2421 'syntax'). This is the (most) Vi compatible setting.
2422 The options are set to the values in the current
2423 buffer. When you change an option and go to another
2424 buffer, the value is copied. Effectively makes the
2425 buffer options global to all buffers.
2426
2427 's' 'S' copy buffer options
2428 no no when buffer created
2429 yes no when buffer first entered (default)
2430 X yes each time when buffer entered (vi comp.)
2431 *cpo-t*
2432 t Search pattern for the tag command is remembered for
2433 "n" command. Otherwise Vim only puts the pattern in
2434 the history for search pattern, but doesn't change the
2435 last used search pattern.
2436 *cpo-u*
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002437 u Undo is Vi compatible. See |undo-two-ways|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002438 *cpo-v*
2439 v Backspaced characters remain visible on the screen in
2440 Insert mode. Without this flag the characters are
2441 erased from the screen right away. With this flag the
2442 screen newly typed text overwrites backspaced
2443 characters.
2444 *cpo-w*
2445 w When using "cw" on a blank character, only change one
2446 character and not all blanks until the start of the
2447 next word.
2448 *cpo-W*
2449 W Don't overwrite a readonly file. When omitted, ":w!"
2450 overwrites a readonly file, if possible.
2451 *cpo-x*
2452 x <Esc> on the command-line executes the command-line.
2453 The default in Vim is to abandon the command-line,
2454 because <Esc> normally aborts a command. |c_<Esc>|
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002455 *cpo-X*
2456 X When using a count with "R" the replaced text is
2457 deleted only once. Also when repeating "R" with "."
2458 and a count.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002459 *cpo-y*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002460 y A yank command can be redone with ".". Think twice if
2461 you really want to use this, it may break some
2462 plugins, since most people expect "." to only repeat a
2463 change.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002464 *cpo-Z*
2465 Z When using "w!" while the 'readonly' option is set,
2466 don't reset 'readonly'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002467 *cpo-!*
2468 ! When redoing a filter command, use the last used
2469 external command, whatever it was. Otherwise the last
2470 used -filter- command is used.
2471 *cpo-$*
2472 $ When making a change to one line, don't redisplay the
2473 line, but put a '$' at the end of the changed text.
2474 The changed text will be overwritten when you type the
2475 new text. The line is redisplayed if you type any
2476 command that moves the cursor from the insertion
2477 point.
2478 *cpo-%*
2479 % Vi-compatible matching is done for the "%" command.
2480 Does not recognize "#if", "#endif", etc.
2481 Does not recognize "/*" and "*/".
2482 Parens inside single and double quotes are also
2483 counted, causing a string that contains a paren to
2484 disturb the matching. For example, in a line like
2485 "if (strcmp("foo(", s))" the first paren does not
2486 match the last one. When this flag is not included,
2487 parens inside single and double quotes are treated
2488 specially. When matching a paren outside of quotes,
2489 everything inside quotes is ignored. When matching a
2490 paren inside quotes, it will find the matching one (if
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002491 there is one). This works very well for C programs.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00002492 This flag is also used for other features, such as
2493 C-indenting.
Bram Moolenaar7c626922005-02-07 22:01:03 +00002494 *cpo--*
2495 - When included, a vertical movement command fails when
Bram Moolenaar8ada17c2006-01-19 22:16:24 +00002496 it would go above the first line or below the last
2497 line. Without it the cursor moves to the first or
2498 last line, unless it already was in that line.
Bram Moolenaar7c626922005-02-07 22:01:03 +00002499 Applies to the commands "-", "k", CTRL-P, "+", "j",
Bram Moolenaar8ada17c2006-01-19 22:16:24 +00002500 CTRL-N, CTRL-J and ":1234".
Bram Moolenaar1cd871b2004-12-19 22:46:22 +00002501 *cpo-+*
2502 + When included, a ":write file" command will reset the
2503 'modified' flag of the buffer, even though the buffer
2504 itself may still be different from its file.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00002505 *cpo-star*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002506 * Use ":*" in the same way as ":@". When not included,
2507 ":*" is an alias for ":'<,'>", select the Visual area.
2508 *cpo-<*
2509 < Disable the recognition of special key codes in |<>|
2510 form in mappings, abbreviations, and the "to" part of
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002511 menu commands. For example, the command
Bram Moolenaar071d4272004-06-13 20:20:40 +00002512 ":map X <Tab>" results in X being mapped to:
2513 '<' included: "<Tab>" (5 characters)
2514 '<' excluded: "^I" (^I is a real <Tab>)
2515 Also see the 'k' flag above.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002516 *cpo->*
2517 > When appending to a register, put a line break before
2518 the appended text.
Bram Moolenaar8b3e0332011-06-26 05:36:34 +02002519 *cpo-;*
2520 ; When using |,| or |;| to repeat the last |t| search
2521 and the cursor is right in front of the searched
2522 character, the cursor won't move. When not included,
2523 the cursor would skip over it and jump to the
Bram Moolenaarc8734422012-06-01 22:38:45 +02002524 following occurrence.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002525
2526 POSIX flags. These are not included in the Vi default value, except
2527 when $VIM_POSIX was set on startup. |posix|
2528
2529 contains behavior ~
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00002530 *cpo-#*
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002531 # A count before "D", "o" and "O" has no effect.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002532 *cpo-&*
2533 & When ":preserve" was used keep the swap file when
2534 exiting normally while this buffer is still loaded.
2535 This flag is tested when exiting.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002536 *cpo-\*
2537 \ Backslash in a [] range in a search pattern is taken
2538 literally, only "\]" is special See |/[]|
Bram Moolenaar90915b52005-08-21 22:17:52 +00002539 '\' included: "/[ \-]" finds <Space>, '\' and '-'
2540 '\' excluded: "/[ \-]" finds <Space> and '-'
2541 Also see |cpo-l|.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002542 *cpo-/*
2543 / When "%" is used as the replacement string in a |:s|
2544 command, use the previous replacement string. |:s%|
2545 *cpo-{*
2546 { The |{| and |}| commands also stop at a "{" character
2547 at the start of a line.
2548 *cpo-.*
2549 . The ":chdir" and ":cd" commands fail if the current
2550 buffer is modified, unless ! is used. Vim doesn't
2551 need this, since it remembers the full path of an
2552 opened file.
2553 *cpo-bar*
2554 | The value of the $LINES and $COLUMNS environment
2555 variables overrule the terminal size values obtained
2556 with system specific functions.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002557
Bram Moolenaar071d4272004-06-13 20:20:40 +00002558
Bram Moolenaar40e6a712010-05-16 22:32:54 +02002559 *'cryptmethod'* *'cm'*
Bram Moolenaara86187b2018-12-16 18:20:00 +01002560'cryptmethod' 'cm' string (default "blowfish2")
Bram Moolenaar49771f42010-07-20 17:32:38 +02002561 global or local to buffer |global-local|
Bram Moolenaar40e6a712010-05-16 22:32:54 +02002562 Method used for encryption when the buffer is written to a file:
Bram Moolenaar0bbabe82010-05-17 20:32:55 +02002563 *pkzip*
Bram Moolenaar49771f42010-07-20 17:32:38 +02002564 zip PkZip compatible method. A weak kind of encryption.
Bram Moolenaarf50a2532010-05-21 15:36:08 +02002565 Backwards compatible with Vim 7.2 and older.
Christian Brabandtaae58342023-04-23 17:50:22 +01002566 Only use if you need to be backwards compatible.
Bram Moolenaar0bbabe82010-05-17 20:32:55 +02002567 *blowfish*
Bram Moolenaar8f4ac012014-08-10 13:38:34 +02002568 blowfish Blowfish method. Medium strong encryption but it has
2569 an implementation flaw. Requires Vim 7.3 or later,
2570 files can NOT be read by Vim 7.2 and older. This adds
2571 a "seed" to the file, every time you write the file
2572 the encrypted bytes will be different.
Christian Brabandtaae58342023-04-23 17:50:22 +01002573 Obsolete, please do no longer use.
Bram Moolenaar8f4ac012014-08-10 13:38:34 +02002574 *blowfish2*
2575 blowfish2 Blowfish method. Medium strong encryption. Requires
Bram Moolenaar5e9b2fa2016-02-01 22:37:05 +01002576 Vim 7.4.401 or later, files can NOT be read by Vim 7.3
Bram Moolenaar8f4ac012014-08-10 13:38:34 +02002577 and older. This adds a "seed" to the file, every time
2578 you write the file the encrypted bytes will be
2579 different. The whole undo file is encrypted, not just
2580 the pieces of text.
Bram Moolenaara2baa732022-02-04 16:09:54 +00002581 *E1193* *E1194* *E1195* *E1196* *E1230*
Christian Brabandtf573c6e2021-06-20 14:02:16 +02002582 *E1197* *E1198* *E1199* *E1200* *E1201*
2583 xchacha20 XChaCha20 Cipher with Poly1305 Message Authentication
2584 Code. Medium strong till strong encryption.
2585 Encryption is provided by the libsodium library, it
Bram Moolenaar22863042021-10-16 15:23:36 +01002586 requires Vim to be built with |+sodium|.
Christian Brabandtf573c6e2021-06-20 14:02:16 +02002587 It adds a seed and a message authentication code (MAC)
2588 to the file. This needs at least a Vim 8.2.3022 to
2589 read the encrypted file.
2590 Encryption of swap files is not supported, therefore
2591 no swap file will be used when xchacha20 encryption is
2592 enabled.
2593 Encryption of undo files is not yet supported,
2594 therefore no undo file will currently be written.
Christian Brabandtaae58342023-04-23 17:50:22 +01002595 CAREFUL: Files written with this method might have to
2596 be read back with the same version of Vim if the
2597 binary format changes later.
2598 Obsolete, please do no longer use.
2599 xchacha20v2 Same algorithm as with "xchacha20" that correctly
2600 stores the key derivation parameters together with the
2601 encrypted file. Should work better in case the
2602 parameters in the libsodium library ever change.
2603 STILL EXPERIMENTAL: Files written with this method
Christian Brabandtf573c6e2021-06-20 14:02:16 +02002604 might have to be read back with the same version of
2605 Vim if the binary format changes later.
Bram Moolenaarf50a2532010-05-21 15:36:08 +02002606
Christian Brabandtaae58342023-04-23 17:50:22 +01002607 You should use "blowfish2", also to re-encrypt older files. The
2608 "xchacha20" method provides better encryption, but it does not work
2609 with all versions of Vim.
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01002610
Bram Moolenaar40e6a712010-05-16 22:32:54 +02002611 When reading an encrypted file 'cryptmethod' will be set automatically
Bram Moolenaarf50a2532010-05-21 15:36:08 +02002612 to the detected method of the file being read. Thus if you write it
2613 without changing 'cryptmethod' the same method will be used.
2614 Changing 'cryptmethod' does not mark the file as modified, you have to
Bram Moolenaar49771f42010-07-20 17:32:38 +02002615 explicitly write it, you don't get a warning unless there are other
2616 modifications. Also see |:X|.
2617
2618 When setting the global value to an empty string, it will end up with
Bram Moolenaara86187b2018-12-16 18:20:00 +01002619 the value "blowfish2". When setting the local value to an empty
2620 string the buffer will use the global value.
Bram Moolenaar49771f42010-07-20 17:32:38 +02002621
Bram Moolenaarf50a2532010-05-21 15:36:08 +02002622 When a new encryption method is added in a later version of Vim, and
2623 the current version does not recognize it, you will get *E821* .
Bram Moolenaar49771f42010-07-20 17:32:38 +02002624 You need to edit this file with the later version of Vim.
Bram Moolenaar40e6a712010-05-16 22:32:54 +02002625
2626
Bram Moolenaar071d4272004-06-13 20:20:40 +00002627 *'cscopepathcomp'* *'cspc'*
2628'cscopepathcomp' 'cspc' number (default 0)
2629 global
2630 {not available when compiled without the |+cscope|
2631 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002632 Determines how many components of the path to show in a list of tags.
2633 See |cscopepathcomp|.
Bram Moolenaar036986f2017-03-16 17:41:02 +01002634 NOTE: This option is set to 0 when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002635
2636 *'cscopeprg'* *'csprg'*
2637'cscopeprg' 'csprg' string (default "cscope")
2638 global
2639 {not available when compiled without the |+cscope|
2640 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002641 Specifies the command to execute cscope. See |cscopeprg|.
2642 This option cannot be set from a |modeline| or in the |sandbox|, for
2643 security reasons.
2644
2645 *'cscopequickfix'* *'csqf'*
2646'cscopequickfix' 'csqf' string (default "")
2647 global
2648 {not available when compiled without the |+cscope|
2649 or |+quickfix| features}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002650 Specifies whether to use quickfix window to show cscope results.
2651 See |cscopequickfix|.
2652
Bram Moolenaarec7944a2013-06-12 21:29:15 +02002653 *'cscoperelative'* *'csre'* *'nocscoperelative'* *'nocsre'*
Bram Moolenaar2f982e42011-06-12 20:42:22 +02002654'cscoperelative' 'csre' boolean (default off)
2655 global
2656 {not available when compiled without the |+cscope|
2657 feature}
Bram Moolenaar2f982e42011-06-12 20:42:22 +02002658 In the absence of a prefix (-P) for cscope. setting this option enables
2659 to use the basename of cscope.out path as the prefix.
2660 See |cscoperelative|.
Bram Moolenaar036986f2017-03-16 17:41:02 +01002661 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaar2f982e42011-06-12 20:42:22 +02002662
Bram Moolenaar071d4272004-06-13 20:20:40 +00002663 *'cscopetag'* *'cst'* *'nocscopetag'* *'nocst'*
2664'cscopetag' 'cst' boolean (default off)
2665 global
2666 {not available when compiled without the |+cscope|
2667 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002668 Use cscope for tag commands. See |cscope-options|.
2669 NOTE: This option is reset when 'compatible' is set.
2670
2671 *'cscopetagorder'* *'csto'*
2672'cscopetagorder' 'csto' number (default 0)
2673 global
2674 {not available when compiled without the |+cscope|
2675 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002676 Determines the order in which ":cstag" performs a search. See
2677 |cscopetagorder|.
2678 NOTE: This option is set to 0 when 'compatible' is set.
2679
2680 *'cscopeverbose'* *'csverb'*
2681 *'nocscopeverbose'* *'nocsverb'*
2682'cscopeverbose' 'csverb' boolean (default off)
2683 global
2684 {not available when compiled without the |+cscope|
2685 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002686 Give messages when adding a cscope database. See |cscopeverbose|.
2687 NOTE: This option is reset when 'compatible' is set.
2688
Bram Moolenaar860cae12010-06-05 23:22:07 +02002689 *'cursorbind'* *'crb'* *'nocursorbind'* *'nocrb'*
2690'cursorbind' 'crb' boolean (default off)
2691 local to window
Bram Moolenaar860cae12010-06-05 23:22:07 +02002692 When this option is set, as the cursor in the current
2693 window moves other cursorbound windows (windows that also have
2694 this option set) move their cursors to the corresponding line and
2695 column. This option is useful for viewing the
2696 differences between two versions of a file (see 'diff'); in diff mode,
2697 inserted and deleted lines (though not characters within a line) are
Bram Moolenaar1a384422010-07-14 19:53:30 +02002698 taken into account.
Bram Moolenaar860cae12010-06-05 23:22:07 +02002699
Bram Moolenaar600dddc2006-03-12 22:05:10 +00002700
2701 *'cursorcolumn'* *'cuc'* *'nocursorcolumn'* *'nocuc'*
2702'cursorcolumn' 'cuc' boolean (default off)
2703 local to window
Bram Moolenaardb84e452010-08-15 13:50:43 +02002704 {not available when compiled without the |+syntax|
Bram Moolenaar600dddc2006-03-12 22:05:10 +00002705 feature}
2706 Highlight the screen column of the cursor with CursorColumn
2707 |hl-CursorColumn|. Useful to align text. Will make screen redrawing
2708 slower.
Bram Moolenaar4c3f5362006-04-11 21:38:50 +00002709 If you only want the highlighting in the current window you can use
2710 these autocommands: >
2711 au WinLeave * set nocursorline nocursorcolumn
2712 au WinEnter * set cursorline cursorcolumn
2713<
Bram Moolenaar600dddc2006-03-12 22:05:10 +00002714
2715 *'cursorline'* *'cul'* *'nocursorline'* *'nocul'*
2716'cursorline' 'cul' boolean (default off)
2717 local to window
Bram Moolenaardb84e452010-08-15 13:50:43 +02002718 {not available when compiled without the |+syntax|
Bram Moolenaar600dddc2006-03-12 22:05:10 +00002719 feature}
Bram Moolenaar410e98a2019-09-09 22:05:49 +02002720 Highlight the text line of the cursor with CursorLine |hl-CursorLine|.
2721 Useful to easily spot the cursor. Will make screen redrawing slower.
Bram Moolenaare2f98b92006-03-29 21:18:24 +00002722 When Visual mode is active the highlighting isn't used to make it
Bram Moolenaar779b74b2006-04-10 14:55:34 +00002723 easier to see the selected text.
Bram Moolenaar600dddc2006-03-12 22:05:10 +00002724
2725
Bram Moolenaar410e98a2019-09-09 22:05:49 +02002726 *'cursorlineopt'* *'culopt'*
Bram Moolenaar017ba072019-09-14 21:01:23 +02002727'cursorlineopt' 'culopt' string (default: "number,line")
Bram Moolenaar410e98a2019-09-09 22:05:49 +02002728 local to window
Bram Moolenaar410e98a2019-09-09 22:05:49 +02002729 {not available when compiled without the |+syntax|
2730 feature}
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01002731 Comma-separated list of settings for how 'cursorline' is displayed.
Bram Moolenaar017ba072019-09-14 21:01:23 +02002732 Valid values:
2733 "line" Highlight the text line of the cursor with
Bram Moolenaar410e98a2019-09-09 22:05:49 +02002734 CursorLine |hl-CursorLine|.
Bram Moolenaar017ba072019-09-14 21:01:23 +02002735 "screenline" Highlight only the screen line of the cursor with
2736 CursorLine |hl-CursorLine|.
2737 "number" Highlight the line number of the cursor with
Bram Moolenaar410e98a2019-09-09 22:05:49 +02002738 CursorLineNr |hl-CursorLineNr|.
Bram Moolenaar017ba072019-09-14 21:01:23 +02002739
2740 Special value:
2741 "both" Alias for the values "line,number".
2742
2743 "line" and "screenline" cannot be used together.
Bram Moolenaar410e98a2019-09-09 22:05:49 +02002744
2745
Bram Moolenaar071d4272004-06-13 20:20:40 +00002746 *'debug'*
2747'debug' string (default "")
2748 global
Bram Moolenaar57657d82006-04-21 22:12:41 +00002749 These values can be used:
2750 msg Error messages that would otherwise be omitted will be given
2751 anyway.
2752 throw Error messages that would otherwise be omitted will be given
2753 anyway and also throw an exception and set |v:errmsg|.
2754 beep A message will be given when otherwise only a beep would be
2755 produced.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002756 The values can be combined, separated by a comma.
Bram Moolenaar57657d82006-04-21 22:12:41 +00002757 "msg" and "throw" are useful for debugging 'foldexpr', 'formatexpr' or
2758 'indentexpr'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002759
2760 *'define'* *'def'*
2761'define' 'def' string (default "^\s*#\s*define")
2762 global or local to buffer |global-local|
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002763 Pattern to be used to find a macro definition. It is a search
Bram Moolenaar071d4272004-06-13 20:20:40 +00002764 pattern, just like for the "/" command. This option is used for the
2765 commands like "[i" and "[d" |include-search|. The 'isident' option is
2766 used to recognize the defined name after the match:
2767 {match with 'define'}{non-ID chars}{defined name}{non-ID char}
2768 See |option-backslash| about inserting backslashes to include a space
2769 or backslash.
2770 The default value is for C programs. For C++ this value would be
2771 useful, to include const type declarations: >
2772 ^\(#\s*define\|[a-z]*\s*const\s*[a-z]*\)
Bram Moolenaar63b74a82019-03-24 15:09:13 +01002773< You can also use "\ze" just before the name and continue the pattern
2774 to check what is following. E.g. for Javascript, if a function is
2775 defined with "func_name = function(args)": >
2776 ^\s*\ze\i\+\s*=\s*function(
2777< If the function is defined with "func_name : function() {...": >
2778 ^\s*\ze\i\+\s*[:]\s*(*function\s*(
Bram Moolenaar071d4272004-06-13 20:20:40 +00002779< When using the ":set" command, you need to double the backslashes!
Bram Moolenaar63b74a82019-03-24 15:09:13 +01002780 To avoid that use `:let` with a single quote string: >
2781 let &l:define = '^\s*\ze\k\+\s*=\s*function('
Bram Moolenaar911ead12019-04-21 00:03:35 +02002782<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002783
2784 *'delcombine'* *'deco'* *'nodelcombine'* *'nodeco'*
2785'delcombine' 'deco' boolean (default off)
2786 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00002787 If editing Unicode and this option is set, backspace and Normal mode
2788 "x" delete each combining character on its own. When it is off (the
2789 default) the character along with its combining characters are
2790 deleted.
Bram Moolenaar4f4d51a2020-10-11 13:57:40 +02002791 Note: When 'delcombine' is set "xx" may work differently from "2x"!
Bram Moolenaar071d4272004-06-13 20:20:40 +00002792
2793 This is useful for Arabic, Hebrew and many other languages where one
2794 may have combining characters overtop of base characters, and want
2795 to remove only the combining ones.
Bram Moolenaar036986f2017-03-16 17:41:02 +01002796 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002797
2798 *'dictionary'* *'dict'*
2799'dictionary' 'dict' string (default "")
2800 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00002801 List of file names, separated by commas, that are used to lookup words
2802 for keyword completion commands |i_CTRL-X_CTRL-K|. Each file should
2803 contain a list of words. This can be one word per line, or several
2804 words per line, separated by non-keyword characters (white space is
2805 preferred). Maximum line length is 510 bytes.
Bram Moolenaar259f26a2018-05-15 22:25:40 +02002806
2807 When this option is empty or an entry "spell" is present, and spell
2808 checking is enabled, words in the word lists for the currently active
2809 'spelllang' are used. See |spell|.
2810
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002811 To include a comma in a file name precede it with a backslash. Spaces
Bram Moolenaar071d4272004-06-13 20:20:40 +00002812 after a comma are ignored, otherwise spaces are included in the file
2813 name. See |option-backslash| about using backslashes.
Bram Moolenaard8b02732005-01-14 21:48:43 +00002814 This has nothing to do with the |Dictionary| variable type.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002815 Where to find a list of words?
2816 - On FreeBSD, there is the file "/usr/share/dict/words".
2817 - In the Simtel archive, look in the "msdos/linguist" directory.
2818 - In "miscfiles" of the GNU collection.
2819 The use of |:set+=| and |:set-=| is preferred when adding or removing
2820 directories from the list. This avoids problems when a future version
2821 uses another default.
2822 Backticks cannot be used in this option for security reasons.
2823
2824 *'diff'* *'nodiff'*
2825'diff' boolean (default off)
2826 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00002827 {not available when compiled without the |+diff|
2828 feature}
2829 Join the current window in the group of windows that shows differences
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002830 between files. See |vimdiff|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002831
2832 *'dex'* *'diffexpr'*
2833'diffexpr' 'dex' string (default "")
2834 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00002835 {not available when compiled without the |+diff|
2836 feature}
Bram Moolenaare828b762018-09-10 17:51:58 +02002837 Expression which is evaluated to obtain a diff file (either ed-style
2838 or unified-style) from two versions of a file. See |diff-diffexpr|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002839 This option cannot be set from a |modeline| or in the |sandbox|, for
2840 security reasons.
2841
2842 *'dip'* *'diffopt'*
Bram Moolenaarc8234772019-11-10 21:00:27 +01002843'diffopt' 'dip' string (default "internal,filler,closeoff")
Bram Moolenaar071d4272004-06-13 20:20:40 +00002844 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00002845 {not available when compiled without the |+diff|
2846 feature}
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002847 Option settings for diff mode. It can consist of the following items.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002848 All are optional. Items must be separated by a comma.
2849
2850 filler Show filler lines, to keep the text
2851 synchronized with a window that has inserted
2852 lines at the same position. Mostly useful
2853 when windows are side-by-side and 'scrollbind'
2854 is set.
2855
2856 context:{n} Use a context of {n} lines between a change
2857 and a fold that contains unchanged lines.
2858 When omitted a context of six lines is used.
Bram Moolenaarf6b40102019-02-22 15:24:03 +01002859 When using zero the context is actually one,
2860 since folds require a line in between, also
dundargoc20f48d52023-10-02 21:49:23 +02002861 for a deleted line. Set it to a very large
2862 value (999999) to disable folding completely.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002863 See |fold-diff|.
2864
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002865 iblank Ignore changes where lines are all blank. Adds
2866 the "-B" flag to the "diff" command if
2867 'diffexpr' is empty. Check the documentation
2868 of the "diff" command for what this does
2869 exactly.
2870 NOTE: the diff windows will get out of sync,
2871 because no differences between blank lines are
2872 taken into account.
2873
Bram Moolenaar071d4272004-06-13 20:20:40 +00002874 icase Ignore changes in case of text. "a" and "A"
2875 are considered the same. Adds the "-i" flag
2876 to the "diff" command if 'diffexpr' is empty.
2877
2878 iwhite Ignore changes in amount of white space. Adds
2879 the "-b" flag to the "diff" command if
2880 'diffexpr' is empty. Check the documentation
2881 of the "diff" command for what this does
2882 exactly. It should ignore adding trailing
2883 white space, but not leading white space.
2884
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002885 iwhiteall Ignore all white space changes. Adds
2886 the "-w" flag to the "diff" command if
2887 'diffexpr' is empty. Check the documentation
2888 of the "diff" command for what this does
2889 exactly.
2890
2891 iwhiteeol Ignore white space changes at end of line.
2892 Adds the "-Z" flag to the "diff" command if
2893 'diffexpr' is empty. Check the documentation
2894 of the "diff" command for what this does
2895 exactly.
2896
Bram Moolenaar7d47b6e2006-03-15 22:59:18 +00002897 horizontal Start diff mode with horizontal splits (unless
2898 explicitly specified otherwise).
2899
2900 vertical Start diff mode with vertical splits (unless
2901 explicitly specified otherwise).
2902
Bram Moolenaarc8234772019-11-10 21:00:27 +01002903 closeoff When a window is closed where 'diff' is set
2904 and there is only one window remaining in the
2905 same tab page with 'diff' set, execute
2906 `:diffoff` in that window. This undoes a
2907 `:diffsplit` command.
2908
Bram Moolenaar97ce4192017-12-01 20:35:58 +01002909 hiddenoff Do not use diff mode for a buffer when it
2910 becomes hidden.
2911
Bram Moolenaar7d47b6e2006-03-15 22:59:18 +00002912 foldcolumn:{n} Set the 'foldcolumn' option to {n} when
2913 starting diff mode. Without this 2 is used.
2914
Bram Moolenaar4223d432021-02-10 13:18:17 +01002915 followwrap Follow the 'wrap' option and leave as it is.
2916
Bram Moolenaare828b762018-09-10 17:51:58 +02002917 internal Use the internal diff library. This is
2918 ignored when 'diffexpr' is set. *E960*
2919 When running out of memory when writing a
2920 buffer this item will be ignored for diffs
2921 involving that buffer. Set the 'verbose'
2922 option to see when this happens.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002923
Bram Moolenaare828b762018-09-10 17:51:58 +02002924 indent-heuristic
Bram Moolenaarf0d58ef2018-11-16 16:13:44 +01002925 Use the indent heuristic for the internal
2926 diff library.
Bram Moolenaare828b762018-09-10 17:51:58 +02002927
2928 algorithm:{text} Use the specified diff algorithm with the
Bram Moolenaarf0d58ef2018-11-16 16:13:44 +01002929 internal diff engine. Currently supported
Bram Moolenaare828b762018-09-10 17:51:58 +02002930 algorithms are:
2931 myers the default algorithm
2932 minimal spend extra time to generate the
2933 smallest possible diff
2934 patience patience diff algorithm
2935 histogram histogram diff algorithm
2936
2937 Examples: >
2938 :set diffopt=internal,filler,context:4
Bram Moolenaar071d4272004-06-13 20:20:40 +00002939 :set diffopt=
Bram Moolenaare828b762018-09-10 17:51:58 +02002940 :set diffopt=internal,filler,foldcolumn:3
2941 :set diffopt-=internal " do NOT use the internal diff parser
Bram Moolenaar071d4272004-06-13 20:20:40 +00002942<
2943 *'digraph'* *'dg'* *'nodigraph'* *'nodg'*
2944'digraph' 'dg' boolean (default off)
2945 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00002946 {not available when compiled without the |+digraphs|
2947 feature}
2948 Enable the entering of digraphs in Insert mode with {char1} <BS>
2949 {char2}. See |digraphs|.
2950 NOTE: This option is reset when 'compatible' is set.
2951
2952 *'directory'* *'dir'*
2953'directory' 'dir' string (default for Amiga: ".,t:",
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01002954 for Win32: ".,$TEMP,c:\tmp,c:\temp"
Bram Moolenaar071d4272004-06-13 20:20:40 +00002955 for Unix: ".,~/tmp,/var/tmp,/tmp")
2956 global
2957 List of directory names for the swap file, separated with commas.
Bram Moolenaare7b1ea02020-08-07 19:54:59 +02002958 Recommended value: ".,~/vimswap//" - this will put the swap file next
2959 to the edited file if possible, and in your personal swap directory
2960 otherwise. Make sure "~/vimswap//" is only readable for you.
2961
2962 Possible items:
Bram Moolenaar071d4272004-06-13 20:20:40 +00002963 - The swap file will be created in the first directory where this is
2964 possible.
2965 - Empty means that no swap file will be used (recovery is
Bram Moolenaar00e192b2019-10-19 17:01:28 +02002966 impossible!) and no |E303| error will be given.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002967 - A directory "." means to put the swap file in the same directory as
2968 the edited file. On Unix, a dot is prepended to the file name, so
2969 it doesn't show in a directory listing. On MS-Windows the "hidden"
2970 attribute is set and a dot prepended if possible.
Bram Moolenaar8024f932020-01-14 19:29:13 +01002971 - A directory starting with "./" (or ".\" for MS-Windows) means to put
2972 the swap file relative to where the edited file is. The leading "."
2973 is replaced with the path name of the edited file.
Bram Moolenaarb782ba42018-08-07 21:39:28 +02002974 - For Unix and Win32, if a directory ends in two path separators "//",
2975 the swap file name will be built from the complete path to the file
Bram Moolenaar207f0092020-08-30 17:20:20 +02002976 with all path separators replaced by percent '%' signs (including
2977 the colon following the drive letter on Win32). This will ensure
2978 file name uniqueness in the preserve directory.
Bram Moolenaarb782ba42018-08-07 21:39:28 +02002979 On Win32, it is also possible to end with "\\". However, When a
2980 separating comma is following, you must use "//", since "\\" will
2981 include the comma in the file name. Therefore it is recommended to
2982 use '//', instead of '\\'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002983 - Spaces after the comma are ignored, other spaces are considered part
2984 of the directory name. To have a space at the start of a directory
2985 name, precede it with a backslash.
2986 - To include a comma in a directory name precede it with a backslash.
2987 - A directory name may end in an ':' or '/'.
2988 - Environment variables are expanded |:set_env|.
2989 - Careful with '\' characters, type one before a space, type two to
2990 get one in the option (see |option-backslash|), for example: >
2991 :set dir=c:\\tmp,\ dir\\,with\\,commas,\\\ dir\ with\ spaces
2992< - For backwards compatibility with Vim version 3.0 a '>' at the start
2993 of the option is removed.
2994 Using "." first in the list is recommended. This means that editing
2995 the same file twice will result in a warning. Using "/tmp" on Unix is
2996 discouraged: When the system crashes you lose the swap file.
2997 "/var/tmp" is often not cleared when rebooting, thus is a better
Bram Moolenaare7b1ea02020-08-07 19:54:59 +02002998 choice than "/tmp". But others on the computer may be able to see the
2999 files, and it can contain a lot of files, your swap files get lost in
3000 the crowd. That is why a "tmp" directory in your home directory is
3001 tried first.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003002 The use of |:set+=| and |:set-=| is preferred when adding or removing
3003 directories from the list. This avoids problems when a future version
3004 uses another default.
3005 This option cannot be set from a |modeline| or in the |sandbox|, for
3006 security reasons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003007
3008 *'display'* *'dy'*
Bram Moolenaarbc8801c2016-08-02 21:04:33 +02003009'display' 'dy' string (default "", set to "truncate" in
3010 |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00003011 global
Bram Moolenaarf269eab2022-10-03 18:04:35 +01003012 Change the way text is displayed. This is a comma-separated list of
Bram Moolenaar071d4272004-06-13 20:20:40 +00003013 flags:
3014 lastline When included, as much as possible of the last line
Bram Moolenaarad9c2a02016-07-27 23:26:04 +02003015 in a window will be displayed. "@@@" is put in the
3016 last columns of the last screen line to indicate the
3017 rest of the line is not displayed.
3018 truncate Like "lastline", but "@@@" is displayed in the first
3019 column of the last screen line. Overrules "lastline".
Bram Moolenaar071d4272004-06-13 20:20:40 +00003020 uhex Show unprintable characters hexadecimal as <xx>
3021 instead of using ^C and ~C.
3022
Bram Moolenaard0796902016-09-16 20:02:31 +02003023 When neither "lastline" nor "truncate" is included, a last line that
Bram Moolenaarad9c2a02016-07-27 23:26:04 +02003024 doesn't fit is replaced with "@" lines.
3025
Bram Moolenaar4ba5f1d2022-10-04 14:36:29 +01003026 The "@" character can be changed by setting the "lastline" item in
3027 'fillchars'. The character is highlighted with |hl-NonText|.
3028
Bram Moolenaar071d4272004-06-13 20:20:40 +00003029 *'eadirection'* *'ead'*
3030'eadirection' 'ead' string (default "both")
3031 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003032 Tells when the 'equalalways' option applies:
3033 ver vertically, width of windows is not affected
3034 hor horizontally, height of windows is not affected
3035 both width and height of windows is affected
3036
3037 *'ed'* *'edcompatible'* *'noed'* *'noedcompatible'*
3038'edcompatible' 'ed' boolean (default off)
3039 global
3040 Makes the 'g' and 'c' flags of the ":substitute" command to be
3041 toggled each time the flag is given. See |complex-change|. See
3042 also 'gdefault' option.
Bram Moolenaarb4d6c3e2017-05-27 16:45:17 +02003043 Switching this option on may break plugins!
Bram Moolenaar4072ba52020-12-23 13:56:35 +01003044 This option is not used in |Vim9| script.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003045
Bram Moolenaar03413f42016-04-12 21:07:15 +02003046 *'emoji'* *'emo'* *'noemoji'* *'noemo'*
Bram Moolenaar3848e002016-03-19 18:42:29 +01003047'emoji' 'emo' boolean (default: on)
3048 global
Bram Moolenaar3848e002016-03-19 18:42:29 +01003049 When on all Unicode emoji characters are considered to be full width.
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02003050 This excludes "text emoji" characters, which are normally displayed as
3051 single width. Unfortunately there is no good specification for this
3052 and it has been determined on trial-and-error basis. Use the
3053 |setcellwidths()| function to change the behavior.
Bram Moolenaar3848e002016-03-19 18:42:29 +01003054
Bram Moolenaar071d4272004-06-13 20:20:40 +00003055 *'encoding'* *'enc'* *E543*
K.Takataf883d902021-05-30 18:04:19 +02003056'encoding' 'enc' string (default for MS-Windows: "utf-8",
3057 otherwise: value from $LANG or "latin1")
Bram Moolenaar071d4272004-06-13 20:20:40 +00003058 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003059 Sets the character encoding used inside Vim. It applies to text in
3060 the buffers, registers, Strings in expressions, text stored in the
3061 viminfo file, etc. It sets the kind of characters which Vim can work
3062 with. See |encoding-names| for the possible values.
3063
3064 NOTE: Changing this option will not change the encoding of the
Bram Moolenaar1cd871b2004-12-19 22:46:22 +00003065 existing text in Vim. It may cause non-ASCII text to become invalid.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003066 It should normally be kept at its default value, or set when Vim
Bram Moolenaar02467872007-05-06 13:22:01 +00003067 starts up. See |multibyte|. To reload the menus see |:menutrans|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003068
Bram Moolenaar865242e2010-07-14 21:12:05 +02003069 This option cannot be set from a |modeline|. It would most likely
3070 corrupt the text.
3071
Bram Moolenaar3df01732017-02-17 22:47:16 +01003072 NOTE: For GTK+ 2 or later, it is highly recommended to set 'encoding'
3073 to "utf-8". Although care has been taken to allow different values of
Bram Moolenaar071d4272004-06-13 20:20:40 +00003074 'encoding', "utf-8" is the natural choice for the environment and
3075 avoids unnecessary conversion overhead. "utf-8" has not been made
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003076 the default to prevent different behavior of the GUI and terminal
Bram Moolenaar071d4272004-06-13 20:20:40 +00003077 versions, and to avoid changing the encoding of newly created files
3078 without your knowledge (in case 'fileencodings' is empty).
3079
3080 The character encoding of files can be different from 'encoding'.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003081 This is specified with 'fileencoding'. The conversion is done with
Bram Moolenaar071d4272004-06-13 20:20:40 +00003082 iconv() or as specified with 'charconvert'.
3083
Bram Moolenaar207f0092020-08-30 17:20:20 +02003084 If you need to know whether 'encoding' is a multibyte encoding, you
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003085 can use: >
3086 if has("multi_byte_encoding")
3087<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003088 Normally 'encoding' will be equal to your current locale. This will
3089 be the default if Vim recognizes your environment settings. If
3090 'encoding' is not set to the current locale, 'termencoding' must be
3091 set to convert typed and displayed text. See |encoding-table|.
3092
3093 When you set this option, it fires the |EncodingChanged| autocommand
3094 event so that you can set up fonts if necessary.
3095
3096 When the option is set, the value is converted to lowercase. Thus
3097 you can set it with uppercase values too. Underscores are translated
3098 to '-' signs.
3099 When the encoding is recognized, it is changed to the standard name.
3100 For example "Latin-1" becomes "latin1", "ISO_88592" becomes
3101 "iso-8859-2" and "utf8" becomes "utf-8".
3102
3103 Note: "latin1" is also used when the encoding could not be detected.
3104 This only works when editing files in the same encoding! When the
3105 actual character set is not latin1, make sure 'fileencoding' and
3106 'fileencodings' are empty. When conversion is needed, switch to using
3107 utf-8.
3108
3109 When "unicode", "ucs-2" or "ucs-4" is used, Vim internally uses utf-8.
3110 You don't notice this while editing, but it does matter for the
3111 |viminfo-file|. And Vim expects the terminal to use utf-8 too. Thus
3112 setting 'encoding' to one of these values instead of utf-8 only has
3113 effect for encoding used for files when 'fileencoding' is empty.
3114
Bram Moolenaar661b1822005-07-28 22:36:45 +00003115 When 'encoding' is set to a Unicode encoding, and 'fileencodings' was
3116 not set yet, the default for 'fileencodings' is changed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003117
Bram Moolenaar6ebe4f92022-10-28 20:47:54 +01003118 *'endoffile'* *'eof'* *'noendoffile'* *'noeof'*
Bram Moolenaar0aad88f2022-11-12 11:54:26 +00003119'endoffile' 'eof' boolean (default off)
Bram Moolenaar071d4272004-06-13 20:20:40 +00003120 local to buffer
Bram Moolenaar6ebe4f92022-10-28 20:47:54 +01003121 Indicates that a CTRL-Z character was found at the end of the file
3122 when reading it. Normally only happens when 'fileformat' is "dos".
Bram Moolenaar071d4272004-06-13 20:20:40 +00003123 When writing a file and this option is off and the 'binary' option
Bram Moolenaar6ebe4f92022-10-28 20:47:54 +01003124 is on, or 'fixeol' option is off, no CTRL-Z will be written at the
Bram Moolenaarfb0cf232022-10-22 11:25:19 +01003125 end of the file.
K.Takata3af98212022-11-01 20:36:19 +00003126 See |eol-and-eof| for example settings.
Bram Moolenaarfb0cf232022-10-22 11:25:19 +01003127
3128 *'endofline'* *'eol'* *'noendofline'* *'noeol'*
3129'endofline' 'eol' boolean (default on)
3130 local to buffer
3131 When writing a file and this option is off and the 'binary' option
Bram Moolenaar34d72d42015-07-17 14:18:08 +02003132 is on, or 'fixeol' option is off, no <EOL> will be written for the
3133 last line in the file. This option is automatically set or reset when
3134 starting to edit a new file, depending on whether file has an <EOL>
3135 for the last line in the file. Normally you don't have to set or
3136 reset this option.
3137 When 'binary' is off and 'fixeol' is on the value is not used when
3138 writing the file. When 'binary' is on or 'fixeol' is off it is used
3139 to remember the presence of a <EOL> for the last line in the file, so
3140 that when you write the file the situation from the original file can
3141 be kept. But you can change it if you want to.
K.Takata3af98212022-11-01 20:36:19 +00003142 See |eol-and-eof| for example settings.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003143
3144 *'equalalways'* *'ea'* *'noequalalways'* *'noea'*
3145'equalalways' 'ea' boolean (default on)
3146 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003147 When on, all the windows are automatically made the same size after
Bram Moolenaar009b2592004-10-24 19:18:58 +00003148 splitting or closing a window. This also happens the moment the
3149 option is switched on. When off, splitting a window will reduce the
3150 size of the current window and leave the other windows the same. When
3151 closing a window the extra lines are given to the window next to it
3152 (depending on 'splitbelow' and 'splitright').
Bram Moolenaar071d4272004-06-13 20:20:40 +00003153 When mixing vertically and horizontally split windows, a minimal size
3154 is computed and some windows may be larger if there is room. The
3155 'eadirection' option tells in which direction the size is affected.
Bram Moolenaar67f71312007-08-12 14:55:56 +00003156 Changing the height and width of a window can be avoided by setting
3157 'winfixheight' and 'winfixwidth', respectively.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003158 If a window size is specified when creating a new window sizes are
3159 currently not equalized (it's complicated, but may be implemented in
3160 the future).
Bram Moolenaar071d4272004-06-13 20:20:40 +00003161
3162 *'equalprg'* *'ep'*
3163'equalprg' 'ep' string (default "")
3164 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00003165 External program to use for "=" command. When this option is empty
Bram Moolenaar446cb832008-06-24 21:56:24 +00003166 the internal formatting functions are used; either 'lisp', 'cindent'
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003167 or 'indentexpr'. When Vim was compiled without internal formatting,
3168 the "indent" program is used.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003169 Environment variables are expanded |:set_env|. See |option-backslash|
Bram Moolenaar071d4272004-06-13 20:20:40 +00003170 about including spaces and backslashes.
3171 This option cannot be set from a |modeline| or in the |sandbox|, for
3172 security reasons.
3173
3174 *'errorbells'* *'eb'* *'noerrorbells'* *'noeb'*
3175'errorbells' 'eb' boolean (default off)
3176 global
3177 Ring the bell (beep or screen flash) for error messages. This only
3178 makes a difference for error messages, the bell will be used always
3179 for a lot of errors without a message (e.g., hitting <Esc> in Normal
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003180 mode). See 'visualbell' on how to make the bell behave like a beep,
Bram Moolenaar165bc692015-07-21 17:53:25 +02003181 screen flash or do nothing. See 'belloff' to finetune when to ring the
3182 bell.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003183
3184 *'errorfile'* *'ef'*
3185'errorfile' 'ef' string (Amiga default: "AztecC.Err",
3186 others: "errors.err")
3187 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003188 {not available when compiled without the |+quickfix|
3189 feature}
3190 Name of the errorfile for the QuickFix mode (see |:cf|).
3191 When the "-q" command-line argument is used, 'errorfile' is set to the
3192 following argument. See |-q|.
3193 NOT used for the ":make" command. See 'makeef' for that.
3194 Environment variables are expanded |:set_env|.
3195 See |option-backslash| about including spaces and backslashes.
3196 This option cannot be set from a |modeline| or in the |sandbox|, for
3197 security reasons.
3198
3199 *'errorformat'* *'efm'*
3200'errorformat' 'efm' string (default is very long)
3201 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00003202 {not available when compiled without the |+quickfix|
3203 feature}
3204 Scanf-like description of the format for the lines in the error file
3205 (see |errorformat|).
3206
3207 *'esckeys'* *'ek'* *'noesckeys'* *'noek'*
3208'esckeys' 'ek' boolean (Vim default: on, Vi default: off)
3209 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003210 Function keys that start with an <Esc> are recognized in Insert
3211 mode. When this option is off, the cursor and function keys cannot be
3212 used in Insert mode if they start with an <Esc>. The advantage of
3213 this is that the single <Esc> is recognized immediately, instead of
3214 after one second. Instead of resetting this option, you might want to
3215 try changing the values for 'timeoutlen' and 'ttimeoutlen'. Note that
3216 when 'esckeys' is off, you can still map anything, but the cursor keys
3217 won't work by default.
3218 NOTE: This option is set to the Vi default value when 'compatible' is
3219 set and to the Vim default value when 'compatible' is reset.
Christian Brabandt5f5131d2023-10-25 21:44:26 +02003220 NOTE: when this option is off then the |modifyOtherKeys| and
3221 |xterm-bracketed-paste| functionality is disabled while in Insert mode
3222 to avoid ending Insert mode with any key that has a modifier.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003223
3224 *'eventignore'* *'ei'*
3225'eventignore' 'ei' string (default "")
3226 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003227 A list of autocommand event names, which are to be ignored.
Bram Moolenaarf193fff2006-04-27 00:02:13 +00003228 When set to "all" or when "all" is one of the items, all autocommand
3229 events are ignored, autocommands will not be executed.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01003230 Otherwise this is a comma-separated list of event names. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003231 :set ei=WinEnter,WinLeave
3232<
3233 *'expandtab'* *'et'* *'noexpandtab'* *'noet'*
3234'expandtab' 'et' boolean (default off)
3235 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00003236 In Insert mode: Use the appropriate number of spaces to insert a
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003237 <Tab>. Spaces are used in indents with the '>' and '<' commands and
Bram Moolenaar071d4272004-06-13 20:20:40 +00003238 when 'autoindent' is on. To insert a real tab when 'expandtab' is
3239 on, use CTRL-V<Tab>. See also |:retab| and |ins-expandtab|.
Bram Moolenaarca635012015-09-25 20:34:21 +02003240 This option is reset when the 'paste' option is set and restored when
3241 the 'paste' option is reset.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003242 NOTE: This option is reset when 'compatible' is set.
3243
3244 *'exrc'* *'ex'* *'noexrc'* *'noex'*
3245'exrc' 'ex' boolean (default off)
3246 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003247 Enables the reading of .vimrc, .exrc and .gvimrc in the current
Bram Moolenaar36f44c22016-08-28 18:17:20 +02003248 directory.
3249
3250 Setting this option is a potential security leak. E.g., consider
3251 unpacking a package or fetching files from github, a .vimrc in there
3252 might be a trojan horse. BETTER NOT SET THIS OPTION!
3253 Instead, define an autocommand in your .vimrc to set options for a
3254 matching directory.
3255
3256 If you do switch this option on you should also consider setting the
3257 'secure' option (see |initialization|).
3258 Also see |.vimrc| and |gui-init|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003259 This option cannot be set from a |modeline| or in the |sandbox|, for
3260 security reasons.
3261
3262 *'fileencoding'* *'fenc'* *E213*
3263'fileencoding' 'fenc' string (default: "")
3264 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00003265 Sets the character encoding for the file of this buffer.
Bram Moolenaar865242e2010-07-14 21:12:05 +02003266
Bram Moolenaar071d4272004-06-13 20:20:40 +00003267 When 'fileencoding' is different from 'encoding', conversion will be
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003268 done when writing the file. For reading see below.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003269 When 'fileencoding' is empty, the same value as 'encoding' will be
3270 used (no conversion when reading or writing a file).
Bram Moolenaar214641f2017-03-05 17:04:09 +01003271 No error will be given when the value is set, only when it is used,
3272 only when writing a file.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003273 Conversion will also be done when 'encoding' and 'fileencoding' are
3274 both a Unicode encoding and 'fileencoding' is not utf-8. That's
3275 because internally Unicode is always stored as utf-8.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003276 WARNING: Conversion can cause loss of information! When
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003277 'encoding' is "utf-8" or another Unicode encoding, conversion
3278 is most likely done in a way that the reverse conversion
3279 results in the same text. When 'encoding' is not "utf-8" some
3280 characters may be lost!
Bram Moolenaar865242e2010-07-14 21:12:05 +02003281
Bram Moolenaar071d4272004-06-13 20:20:40 +00003282 See 'encoding' for the possible values. Additionally, values may be
3283 specified that can be handled by the converter, see
3284 |mbyte-conversion|.
Bram Moolenaar865242e2010-07-14 21:12:05 +02003285
Bram Moolenaar071d4272004-06-13 20:20:40 +00003286 When reading a file 'fileencoding' will be set from 'fileencodings'.
3287 To read a file in a certain encoding it won't work by setting
Bram Moolenaar02467872007-05-06 13:22:01 +00003288 'fileencoding', use the |++enc| argument. One exception: when
3289 'fileencodings' is empty the value of 'fileencoding' is used.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003290 For a new file the global value of 'fileencoding' is used.
Bram Moolenaar865242e2010-07-14 21:12:05 +02003291
Bram Moolenaar071d4272004-06-13 20:20:40 +00003292 Prepending "8bit-" and "2byte-" has no meaning here, they are ignored.
3293 When the option is set, the value is converted to lowercase. Thus
3294 you can set it with uppercase values too. '_' characters are
3295 replaced with '-'. If a name is recognized from the list for
3296 'encoding', it is replaced by the standard name. For example
3297 "ISO8859-2" becomes "iso-8859-2".
Bram Moolenaar865242e2010-07-14 21:12:05 +02003298
Bram Moolenaar071d4272004-06-13 20:20:40 +00003299 When this option is set, after starting to edit a file, the 'modified'
3300 option is set, because the file would be different when written.
Bram Moolenaar865242e2010-07-14 21:12:05 +02003301
3302 Keep in mind that changing 'fenc' from a modeline happens
3303 AFTER the text has been read, thus it applies to when the file will be
3304 written. If you do set 'fenc' in a modeline, you might want to set
3305 'nomodified' to avoid not being able to ":q".
3306
Bram Moolenaar071d4272004-06-13 20:20:40 +00003307 This option can not be changed when 'modifiable' is off.
3308
3309 *'fe'*
3310 NOTE: Before version 6.0 this option specified the encoding for the
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003311 whole of Vim, this was a mistake. Now use 'encoding' instead. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00003312 old short name was 'fe', which is no longer used.
3313
3314 *'fileencodings'* *'fencs'*
Bram Moolenaar1cd871b2004-12-19 22:46:22 +00003315'fileencodings' 'fencs' string (default: "ucs-bom",
3316 "ucs-bom,utf-8,default,latin1" when
3317 'encoding' is set to a Unicode value)
Bram Moolenaar071d4272004-06-13 20:20:40 +00003318 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003319 This is a list of character encodings considered when starting to edit
3320 an existing file. When a file is read, Vim tries to use the first
3321 mentioned character encoding. If an error is detected, the next one
3322 in the list is tried. When an encoding is found that works,
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003323 'fileencoding' is set to it. If all fail, 'fileencoding' is set to
Bram Moolenaar071d4272004-06-13 20:20:40 +00003324 an empty string, which means the value of 'encoding' is used.
3325 WARNING: Conversion can cause loss of information! When
3326 'encoding' is "utf-8" (or one of the other Unicode variants)
3327 conversion is most likely done in a way that the reverse
3328 conversion results in the same text. When 'encoding' is not
Bram Moolenaarc6d8db72005-12-13 20:04:55 +00003329 "utf-8" some non-ASCII characters may be lost! You can use
3330 the |++bad| argument to specify what is done with characters
3331 that can't be converted.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003332 For an empty file or a file with only ASCII characters most encodings
3333 will work and the first entry of 'fileencodings' will be used (except
3334 "ucs-bom", which requires the BOM to be present). If you prefer
3335 another encoding use an BufReadPost autocommand event to test if your
3336 preferred encoding is to be used. Example: >
3337 au BufReadPost * if search('\S', 'w') == 0 |
3338 \ set fenc=iso-2022-jp | endif
3339< This sets 'fileencoding' to "iso-2022-jp" if the file does not contain
3340 non-blank characters.
Bram Moolenaarc6d8db72005-12-13 20:04:55 +00003341 When the |++enc| argument is used then the value of 'fileencodings' is
3342 not used.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003343 Note that 'fileencodings' is not used for a new file, the global value
3344 of 'fileencoding' is used instead. You can set it with: >
3345 :setglobal fenc=iso-8859-2
3346< This means that a non-existing file may get a different encoding than
3347 an empty file.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003348 The special value "ucs-bom" can be used to check for a Unicode BOM
3349 (Byte Order Mark) at the start of the file. It must not be preceded
3350 by "utf-8" or another Unicode encoding for this to work properly.
3351 An entry for an 8-bit encoding (e.g., "latin1") should be the last,
3352 because Vim cannot detect an error, thus the encoding is always
3353 accepted.
Bram Moolenaar1cd871b2004-12-19 22:46:22 +00003354 The special value "default" can be used for the encoding from the
K.Takataef8706f2021-05-31 18:40:49 +02003355 environment. On MS-Windows this is the system encoding. Otherwise
3356 this is the default value for 'encoding'. It is useful when
3357 'encoding' is set to "utf-8" and your environment uses a non-latin1
3358 encoding, such as Russian.
Bram Moolenaarca003e12006-03-17 23:19:38 +00003359 When 'encoding' is "utf-8" and a file contains an illegal byte
3360 sequence it won't be recognized as UTF-8. You can use the |8g8|
3361 command to find the illegal byte sequence.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003362 WRONG VALUES: WHAT'S WRONG:
3363 latin1,utf-8 "latin1" will always be used
3364 utf-8,ucs-bom,latin1 BOM won't be recognized in an utf-8
3365 file
3366 cp1250,latin1 "cp1250" will always be used
3367 If 'fileencodings' is empty, 'fileencoding' is not modified.
3368 See 'fileencoding' for the possible values.
3369 Setting this option does not have an effect until the next time a file
3370 is read.
3371
3372 *'fileformat'* *'ff'*
Bram Moolenaar00590742019-02-15 21:06:09 +01003373'fileformat' 'ff' string (MS-Windows default: "dos",
3374 Unix, macOS default: "unix")
Bram Moolenaar071d4272004-06-13 20:20:40 +00003375 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00003376 This gives the <EOL> of the current buffer, which is used for
3377 reading/writing the buffer from/to a file:
Bram Moolenaar4072ba52020-12-23 13:56:35 +01003378 dos <CR><NL>
Bram Moolenaar071d4272004-06-13 20:20:40 +00003379 unix <NL>
3380 mac <CR>
3381 When "dos" is used, CTRL-Z at the end of a file is ignored.
3382 See |file-formats| and |file-read|.
3383 For the character encoding of the file see 'fileencoding'.
3384 When 'binary' is set, the value of 'fileformat' is ignored, file I/O
Bram Moolenaarbf884932013-04-05 22:26:15 +02003385 works like it was set to "unix".
Bram Moolenaar071d4272004-06-13 20:20:40 +00003386 This option is set automatically when starting to edit a file and
3387 'fileformats' is not empty and 'binary' is off.
3388 When this option is set, after starting to edit a file, the 'modified'
3389 option is set, because the file would be different when written.
3390 This option can not be changed when 'modifiable' is off.
3391 For backwards compatibility: When this option is set to "dos",
3392 'textmode' is set, otherwise 'textmode' is reset.
3393
3394 *'fileformats'* *'ffs'*
3395'fileformats' 'ffs' string (default:
Bram Moolenaar00590742019-02-15 21:06:09 +01003396 Vim+Vi MS-Windows: "dos,unix",
3397 Vim Unix, macOS: "unix,dos",
Bram Moolenaar071d4272004-06-13 20:20:40 +00003398 Vi Cygwin: "unix,dos",
3399 Vi others: "")
3400 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003401 This gives the end-of-line (<EOL>) formats that will be tried when
3402 starting to edit a new buffer and when reading a file into an existing
3403 buffer:
3404 - When empty, the format defined with 'fileformat' will be used
3405 always. It is not set automatically.
3406 - When set to one name, that format will be used whenever a new buffer
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003407 is opened. 'fileformat' is set accordingly for that buffer. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00003408 'fileformats' name will be used when a file is read into an existing
3409 buffer, no matter what 'fileformat' for that buffer is set to.
3410 - When more than one name is present, separated by commas, automatic
3411 <EOL> detection will be done when reading a file. When starting to
3412 edit a file, a check is done for the <EOL>:
3413 1. If all lines end in <CR><NL>, and 'fileformats' includes "dos",
3414 'fileformat' is set to "dos".
3415 2. If a <NL> is found and 'fileformats' includes "unix", 'fileformat'
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003416 is set to "unix". Note that when a <NL> is found without a
Bram Moolenaar071d4272004-06-13 20:20:40 +00003417 preceding <CR>, "unix" is preferred over "dos".
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01003418 3. If 'fileformat' has not yet been set, and if a <CR> is found, and
3419 if 'fileformats' includes "mac", 'fileformat' is set to "mac".
Bram Moolenaar00659062010-09-21 22:34:02 +02003420 This means that "mac" is only chosen when:
3421 "unix" is not present or no <NL> is found in the file, and
3422 "dos" is not present or no <CR><NL> is found in the file.
3423 Except: if "unix" was chosen, but there is a <CR> before
3424 the first <NL>, and there appear to be more <CR>s than <NL>s in
Bram Moolenaar166af9b2010-11-16 20:34:40 +01003425 the first few lines, "mac" is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003426 4. If 'fileformat' is still not set, the first name from
3427 'fileformats' is used.
3428 When reading a file into an existing buffer, the same is done, but
3429 this happens like 'fileformat' has been set appropriately for that
3430 file only, the option is not changed.
3431 When 'binary' is set, the value of 'fileformats' is not used.
3432
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01003433 When Vim starts up with an empty buffer the first item is used. You
3434 can overrule this by setting 'fileformat' in your .vimrc.
Bram Moolenaar81af9252010-12-10 20:35:50 +01003435
Bram Moolenaar071d4272004-06-13 20:20:40 +00003436 For systems with a Dos-like <EOL> (<CR><NL>), when reading files that
3437 are ":source"ed and for vimrc files, automatic <EOL> detection may be
3438 done:
3439 - When 'fileformats' is empty, there is no automatic detection. Dos
3440 format will be used.
3441 - When 'fileformats' is set to one or more names, automatic detection
3442 is done. This is based on the first <NL> in the file: If there is a
3443 <CR> in front of it, Dos format is used, otherwise Unix format is
3444 used.
3445 Also see |file-formats|.
3446 For backwards compatibility: When this option is set to an empty
3447 string or one format (no comma is included), 'textauto' is reset,
3448 otherwise 'textauto' is set.
3449 NOTE: This option is set to the Vi default value when 'compatible' is
3450 set and to the Vim default value when 'compatible' is reset.
3451
Bram Moolenaarbf884932013-04-05 22:26:15 +02003452 *'fileignorecase'* *'fic'* *'nofileignorecase'* *'nofic'*
3453'fileignorecase' 'fic' boolean (default on for systems where case in file
3454 names is normally ignored)
Bram Moolenaar71afbfe2013-03-19 16:49:16 +01003455 global
Bram Moolenaar71afbfe2013-03-19 16:49:16 +01003456 When set case is ignored when using file names and directories.
3457 See 'wildignorecase' for only ignoring case when doing completion.
3458
Bram Moolenaar071d4272004-06-13 20:20:40 +00003459 *'filetype'* *'ft'*
3460'filetype' 'ft' string (default: "")
Christian Brabandt596ad662023-08-16 00:11:09 +02003461 local to buffer |local-noglobal|
Bram Moolenaar071d4272004-06-13 20:20:40 +00003462 When this option is set, the FileType autocommand event is triggered.
3463 All autocommands that match with the value of this option will be
3464 executed. Thus the value of 'filetype' is used in place of the file
3465 name.
3466 Otherwise this option does not always reflect the current file type.
3467 This option is normally set when the file type is detected. To enable
3468 this use the ":filetype on" command. |:filetype|
3469 Setting this option to a different value is most useful in a modeline,
3470 for a file for which the file type is not automatically recognized.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00003471 Example, for in an IDL file:
3472 /* vim: set filetype=idl : */ ~
3473 |FileType| |filetypes|
3474 When a dot appears in the value then this separates two filetype
3475 names. Example:
3476 /* vim: set filetype=c.doxygen : */ ~
3477 This will use the "c" filetype first, then the "doxygen" filetype.
3478 This works both for filetype plugins and for syntax files. More than
3479 one dot may appear.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003480 This option is not copied to another buffer, independent of the 's' or
3481 'S' flag in 'cpoptions'.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00003482 Only normal file name characters can be used, "/\*?[|<>" are illegal.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003483
3484 *'fillchars'* *'fcs'*
Bram Moolenaara98f8a22021-02-13 18:24:23 +01003485'fillchars' 'fcs' string (default "vert:|,fold:-,eob:~")
Bram Moolenaar96ba25a2022-07-04 17:34:33 +01003486 global or local to window |global-local|
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02003487 {not available when compiled without the |+folding|
3488 feature}
Bram Moolenaar96ba25a2022-07-04 17:34:33 +01003489 Characters to fill the statuslines, vertical separators and special
3490 lines in the window.
3491 It is a comma-separated list of items. Each item has a name, a colon
3492 and the value of that item:
Bram Moolenaar071d4272004-06-13 20:20:40 +00003493
Bram Moolenaar96ba25a2022-07-04 17:34:33 +01003494 item name default Used for ~
3495 stl ' ' or '^' statusline of the current window
3496 stlnc ' ' or '=' statusline of the non-current windows
3497 vert '|' vertical separators |:vsplit|
3498 fold '-' filling 'foldtext'
3499 foldopen '-' mark the beginning of a fold
3500 foldclose '+' show a closed fold
3501 foldsep '|' open fold middle character
3502 diff '-' deleted lines of the 'diff' option
3503 eob '~' empty lines below the end of a buffer
Bram Moolenaar4ba5f1d2022-10-04 14:36:29 +01003504 lastline '@' 'display' contains lastline/truncate
Bram Moolenaar071d4272004-06-13 20:20:40 +00003505
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003506 Any one that is omitted will fall back to the default. For "stl" and
Bram Moolenaar38a55632016-02-15 22:07:32 +01003507 "stlnc" the space will be used when there is highlighting, '^' or '='
Bram Moolenaar071d4272004-06-13 20:20:40 +00003508 otherwise.
3509
3510 Example: >
Bram Moolenaar38a55632016-02-15 22:07:32 +01003511 :set fillchars=stl:^,stlnc:=,vert:\|,fold:-,diff:-
Bram Moolenaar071d4272004-06-13 20:20:40 +00003512< This is similar to the default, except that these characters will also
3513 be used when there is highlighting.
3514
Bram Moolenaar8cc5b552022-06-23 13:04:20 +01003515 For the "stl", "stlnc", "foldopen", "foldclose" and "foldsep" items
3516 single-byte and multibyte characters are supported. But double-width
3517 characters are not supported.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003518
Bram Moolenaar071d4272004-06-13 20:20:40 +00003519 The highlighting used for these items:
Bram Moolenaar96ba25a2022-07-04 17:34:33 +01003520 item name highlight group ~
3521 stl StatusLine |hl-StatusLine|
3522 stlnc StatusLineNC |hl-StatusLineNC|
3523 vert VertSplit |hl-VertSplit|
3524 fold Folded |hl-Folded|
3525 diff DiffDelete |hl-DiffDelete|
3526 eob EndOfBuffer |hl-EndOfBuffer|
Bram Moolenaar4ba5f1d2022-10-04 14:36:29 +01003527 lastline NonText |hl-NonText|
Bram Moolenaar071d4272004-06-13 20:20:40 +00003528
Bram Moolenaar34d72d42015-07-17 14:18:08 +02003529 *'fixendofline'* *'fixeol'* *'nofixendofline'* *'nofixeol'*
3530'fixendofline' 'fixeol' boolean (default on)
3531 local to buffer
Bram Moolenaar34d72d42015-07-17 14:18:08 +02003532 When writing a file and this option is on, <EOL> at the end of file
Bram Moolenaarfb0cf232022-10-22 11:25:19 +01003533 will be restored if missing. Turn this option off if you want to
Bram Moolenaar34d72d42015-07-17 14:18:08 +02003534 preserve the situation from the original file.
3535 When the 'binary' option is set the value of this option doesn't
3536 matter.
3537 See the 'endofline' option.
K.Takata3af98212022-11-01 20:36:19 +00003538 See |eol-and-eof| for example settings.
Bram Moolenaar34d72d42015-07-17 14:18:08 +02003539
Bram Moolenaar071d4272004-06-13 20:20:40 +00003540 *'fkmap'* *'fk'* *'nofkmap'* *'nofk'*
Bram Moolenaar98a29d02021-01-18 19:55:44 +01003541'fkmap' 'fk' boolean (default off)
Bram Moolenaar071d4272004-06-13 20:20:40 +00003542 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003543 {only available when compiled with the |+rightleft|
3544 feature}
Bram Moolenaar14184a32019-02-16 15:10:30 +01003545 This option was for using Farsi, which has been removed. See
3546 |farsi.txt|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003547
3548 *'foldclose'* *'fcl'*
3549'foldclose' 'fcl' string (default "")
3550 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003551 {not available when compiled without the |+folding|
3552 feature}
3553 When set to "all", a fold is closed when the cursor isn't in it and
3554 its level is higher than 'foldlevel'. Useful if you want folds to
3555 automatically close when moving out of them.
3556
3557 *'foldcolumn'* *'fdc'*
3558'foldcolumn' 'fdc' number (default 0)
3559 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003560 {not available when compiled without the |+folding|
3561 feature}
3562 When non-zero, a column with the specified width is shown at the side
3563 of the window which indicates open and closed folds. The maximum
3564 value is 12.
3565 See |folding|.
3566
3567 *'foldenable'* *'fen'* *'nofoldenable'* *'nofen'*
3568'foldenable' 'fen' boolean (default on)
3569 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003570 {not available when compiled without the |+folding|
3571 feature}
3572 When off, all folds are open. This option can be used to quickly
3573 switch between showing all text unfolded and viewing the text with
3574 folds (including manually opened or closed folds). It can be toggled
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003575 with the |zi| command. The 'foldcolumn' will remain blank when
Bram Moolenaar071d4272004-06-13 20:20:40 +00003576 'foldenable' is off.
3577 This option is set by commands that create a new fold or close a fold.
3578 See |folding|.
3579
3580 *'foldexpr'* *'fde'*
3581'foldexpr' 'fde' string (default: "0")
3582 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003583 {not available when compiled without the |+folding|
Bram Moolenaardb84e452010-08-15 13:50:43 +02003584 or |+eval| features}
Bram Moolenaar071d4272004-06-13 20:20:40 +00003585 The expression used for when 'foldmethod' is "expr". It is evaluated
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00003586 for each line to obtain its fold level. The context is set to the
3587 script where 'foldexpr' was set, script-local items can be accessed.
3588 See |fold-expr| for the usage.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00003589
Bram Moolenaar30b65812012-07-12 22:01:11 +02003590 The expression will be evaluated in the |sandbox| if set from a
3591 modeline, see |sandbox-option|.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003592 This option can't be set from a |modeline| when the 'diff' option is
Bram Moolenaar110289e2019-05-23 15:38:06 +02003593 on or the 'modelineexpr' option is off.
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00003594
3595 It is not allowed to change text or jump to another window while
3596 evaluating 'foldexpr' |textlock|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003597
3598 *'foldignore'* *'fdi'*
3599'foldignore' 'fdi' string (default: "#")
3600 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003601 {not available when compiled without the |+folding|
3602 feature}
3603 Used only when 'foldmethod' is "indent". Lines starting with
3604 characters in 'foldignore' will get their fold level from surrounding
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003605 lines. White space is skipped before checking for this character.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003606 The default "#" works well for C programs. See |fold-indent|.
3607
3608 *'foldlevel'* *'fdl'*
3609'foldlevel' 'fdl' number (default: 0)
3610 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003611 {not available when compiled without the |+folding|
3612 feature}
3613 Sets the fold level: Folds with a higher level will be closed.
3614 Setting this option to zero will close all folds. Higher numbers will
3615 close fewer folds.
3616 This option is set by commands like |zm|, |zM| and |zR|.
3617 See |fold-foldlevel|.
3618
3619 *'foldlevelstart'* *'fdls'*
3620'foldlevelstart' 'fdls' number (default: -1)
3621 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003622 {not available when compiled without the |+folding|
3623 feature}
3624 Sets 'foldlevel' when starting to edit another buffer in a window.
3625 Useful to always start editing with all folds closed (value zero),
3626 some folds closed (one) or no folds closed (99).
3627 This is done before reading any modeline, thus a setting in a modeline
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003628 overrules this option. Starting to edit a file for |diff-mode| also
Bram Moolenaar071d4272004-06-13 20:20:40 +00003629 ignores this option and closes all folds.
3630 It is also done before BufReadPre autocommands, to allow an autocmd to
3631 overrule the 'foldlevel' value for specific files.
3632 When the value is negative, it is not used.
3633
3634 *'foldmarker'* *'fmr'* *E536*
3635'foldmarker' 'fmr' string (default: "{{{,}}}")
3636 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003637 {not available when compiled without the |+folding|
3638 feature}
3639 The start and end marker used when 'foldmethod' is "marker". There
3640 must be one comma, which separates the start and end marker. The
3641 marker is a literal string (a regular expression would be too slow).
3642 See |fold-marker|.
3643
3644 *'foldmethod'* *'fdm'*
3645'foldmethod' 'fdm' string (default: "manual")
3646 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003647 {not available when compiled without the |+folding|
3648 feature}
3649 The kind of folding used for the current window. Possible values:
3650 |fold-manual| manual Folds are created manually.
3651 |fold-indent| indent Lines with equal indent form a fold.
3652 |fold-expr| expr 'foldexpr' gives the fold level of a line.
3653 |fold-marker| marker Markers are used to specify folds.
3654 |fold-syntax| syntax Syntax highlighting items specify folds.
3655 |fold-diff| diff Fold text that is not changed.
3656
3657 *'foldminlines'* *'fml'*
3658'foldminlines' 'fml' number (default: 1)
3659 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003660 {not available when compiled without the |+folding|
3661 feature}
Bram Moolenaar00654022011-02-25 14:42:19 +01003662 Sets the number of screen lines above which a fold can be displayed
3663 closed. Also for manually closed folds. With the default value of
3664 one a fold can only be closed if it takes up two or more screen lines.
3665 Set to zero to be able to close folds of just one screen line.
Bram Moolenaar446beb42011-05-10 17:18:44 +02003666 Note that this only has an effect on what is displayed. After using
Bram Moolenaar071d4272004-06-13 20:20:40 +00003667 "zc" to close a fold, which is displayed open because it's smaller
3668 than 'foldminlines', a following "zc" may close a containing fold.
3669
3670 *'foldnestmax'* *'fdn'*
3671'foldnestmax' 'fdn' number (default: 20)
3672 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003673 {not available when compiled without the |+folding|
3674 feature}
3675 Sets the maximum nesting of folds for the "indent" and "syntax"
3676 methods. This avoids that too many folds will be created. Using more
3677 than 20 doesn't work, because the internal limit is 20.
3678
3679 *'foldopen'* *'fdo'*
3680'foldopen' 'fdo' string (default: "block,hor,mark,percent,quickfix,
3681 search,tag,undo")
3682 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003683 {not available when compiled without the |+folding|
3684 feature}
3685 Specifies for which type of commands folds will be opened, if the
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01003686 command moves the cursor into a closed fold. It is a comma-separated
Bram Moolenaar071d4272004-06-13 20:20:40 +00003687 list of items.
Bram Moolenaar05365702010-10-27 18:34:44 +02003688 NOTE: When the command is part of a mapping this option is not used.
3689 Add the |zv| command to the mapping to get the same effect.
3690 (rationale: the mapping may want to control opening folds itself)
3691
Bram Moolenaar071d4272004-06-13 20:20:40 +00003692 item commands ~
3693 all any
3694 block "(", "{", "[[", "[{", etc.
3695 hor horizontal movements: "l", "w", "fx", etc.
3696 insert any command in Insert mode
3697 jump far jumps: "G", "gg", etc.
3698 mark jumping to a mark: "'m", CTRL-O, etc.
3699 percent "%"
3700 quickfix ":cn", ":crew", ":make", etc.
3701 search search for a pattern: "/", "n", "*", "gd", etc.
3702 (not for a search pattern in a ":" command)
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003703 Also for |[s| and |]s|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003704 tag jumping to a tag: ":ta", CTRL-T, etc.
3705 undo undo or redo: "u" and CTRL-R
Bram Moolenaar071d4272004-06-13 20:20:40 +00003706 When a movement command is used for an operator (e.g., "dl" or "y%")
3707 this option is not used. This means the operator will include the
3708 whole closed fold.
3709 Note that vertical movements are not here, because it would make it
3710 very difficult to move onto a closed fold.
3711 In insert mode the folds containing the cursor will always be open
3712 when text is inserted.
3713 To close folds you can re-apply 'foldlevel' with the |zx| command or
3714 set the 'foldclose' option to "all".
3715
3716 *'foldtext'* *'fdt'*
3717'foldtext' 'fdt' string (default: "foldtext()")
3718 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003719 {not available when compiled without the |+folding|
3720 feature}
3721 An expression which is used to specify the text displayed for a closed
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00003722 fold. The context is set to the script where 'foldexpr' was set,
3723 script-local items can be accessed. See |fold-foldtext| for the
3724 usage.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003725
Bram Moolenaar30b65812012-07-12 22:01:11 +02003726 The expression will be evaluated in the |sandbox| if set from a
3727 modeline, see |sandbox-option|.
Bram Moolenaar110289e2019-05-23 15:38:06 +02003728 This option cannot be set in a modeline when 'modelineexpr' is off.
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00003729
3730 It is not allowed to change text or jump to another window while
3731 evaluating 'foldtext' |textlock|.
3732
Bram Moolenaarc95a3022016-06-12 23:01:46 +02003733 *'formatexpr'* *'fex'*
3734'formatexpr' 'fex' string (default "")
3735 local to buffer
Bram Moolenaarc95a3022016-06-12 23:01:46 +02003736 {not available when compiled without the |+eval|
3737 feature}
3738 Expression which is evaluated to format a range of lines for the |gq|
3739 operator or automatic formatting (see 'formatoptions'). When this
3740 option is empty 'formatprg' is used.
3741
3742 The |v:lnum| variable holds the first line to be formatted.
3743 The |v:count| variable holds the number of lines to be formatted.
3744 The |v:char| variable holds the character that is going to be
3745 inserted if the expression is being evaluated due to
3746 automatic formatting. This can be empty. Don't insert
3747 it yet!
3748
3749 Example: >
3750 :set formatexpr=mylang#Format()
3751< This will invoke the mylang#Format() function in the
3752 autoload/mylang.vim file in 'runtimepath'. |autoload|
3753
Bram Moolenaara4e0b972022-10-01 19:43:52 +01003754 The advantage of using a function call without arguments is that it is
3755 faster, see |expr-option-function|.
3756
Bram Moolenaarc95a3022016-06-12 23:01:46 +02003757 The expression is also evaluated when 'textwidth' is set and adding
3758 text beyond that limit. This happens under the same conditions as
3759 when internal formatting is used. Make sure the cursor is kept in the
3760 same spot relative to the text then! The |mode()| function will
3761 return "i" or "R" in this situation.
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01003762
Bram Moolenaarc95a3022016-06-12 23:01:46 +02003763 When the expression evaluates to non-zero Vim will fall back to using
3764 the internal format mechanism.
3765
Yegappan Lakshmanan8bb65f22021-12-26 10:51:39 +00003766 If the expression starts with s: or |<SID>|, then it is replaced with
3767 the script ID (|local-function|). Example: >
3768 set formatexpr=s:MyFormatExpr()
3769 set formatexpr=<SID>SomeFormatExpr()
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00003770< Otherwise, the expression is evaluated in the context of the script
3771 where the option was set, thus script-local items are available.
3772
Bram Moolenaarc95a3022016-06-12 23:01:46 +02003773 The expression will be evaluated in the |sandbox| when set from a
3774 modeline, see |sandbox-option|. That stops the option from working,
3775 since changing the buffer text is not allowed.
Bram Moolenaar110289e2019-05-23 15:38:06 +02003776 This option cannot be set in a modeline when 'modelineexpr' is off.
Bram Moolenaar036986f2017-03-16 17:41:02 +01003777 NOTE: This option is set to "" when 'compatible' is set.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02003778
Bram Moolenaar86b68352004-12-27 21:59:20 +00003779 *'formatlistpat'* *'flp'*
3780'formatlistpat' 'flp' string (default: "^\s*\d\+[\]:.)}\t ]\s*")
3781 local to buffer
Bram Moolenaar86b68352004-12-27 21:59:20 +00003782 A pattern that is used to recognize a list header. This is used for
3783 the "n" flag in 'formatoptions'.
3784 The pattern must match exactly the text that will be the indent for
Bram Moolenaar677ee682005-01-27 14:41:15 +00003785 the line below it. You can use |/\ze| to mark the end of the match
Bram Moolenaar86b68352004-12-27 21:59:20 +00003786 while still checking more characters. There must be a character
3787 following the pattern, when it matches the whole line it is handled
3788 like there is no match.
3789 The default recognizes a number, followed by an optional punctuation
3790 character and white space.
3791
Bram Moolenaar6c60f472019-04-28 16:00:35 +02003792 *'formatoptions'* *'fo'*
3793'formatoptions' 'fo' string (Vim default: "tcq", Vi default: "vt")
3794 local to buffer
3795 This is a sequence of letters which describes how automatic
3796 formatting is to be done. See |fo-table|. When the 'paste' option is
3797 on, no formatting is done (like 'formatoptions' is empty). Commas can
3798 be inserted for readability.
3799 To avoid problems with flags that are added in the future, use the
3800 "+=" and "-=" feature of ":set" |add-option-flags|.
3801 NOTE: This option is set to the Vi default value when 'compatible' is
3802 set and to the Vim default value when 'compatible' is reset.
3803
Bram Moolenaar071d4272004-06-13 20:20:40 +00003804 *'formatprg'* *'fp'*
3805'formatprg' 'fp' string (default "")
Bram Moolenaar9be7c042017-01-14 14:28:30 +01003806 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00003807 The name of an external program that will be used to format the lines
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00003808 selected with the |gq| operator. The program must take the input on
Bram Moolenaar071d4272004-06-13 20:20:40 +00003809 stdin and produce the output on stdout. The Unix program "fmt" is
Bram Moolenaara5792f52005-11-23 21:25:05 +00003810 such a program.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00003811 If the 'formatexpr' option is not empty it will be used instead.
3812 Otherwise, if 'formatprg' option is an empty string, the internal
3813 format function will be used |C-indenting|.
Bram Moolenaara5792f52005-11-23 21:25:05 +00003814 Environment variables are expanded |:set_env|. See |option-backslash|
3815 about including spaces and backslashes.
Bram Moolenaar30b65812012-07-12 22:01:11 +02003816 This option cannot be set from a |modeline| or in the |sandbox|, for
3817 security reasons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003818
Bram Moolenaard94464e2015-11-02 15:28:18 +01003819 *'fsync'* *'fs'* *'nofsync'* *'nofs'*
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00003820'fsync' 'fs' boolean (default on)
3821 global
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00003822 When on, the library function fsync() will be called after writing a
3823 file. This will flush a file to disk, ensuring that it is safely
3824 written even on filesystems which do metadata-only journaling. This
3825 will force the harddrive to spin up on Linux systems running in laptop
3826 mode, so it may be undesirable in some situations. Be warned that
3827 turning this off increases the chances of data loss after a crash. On
3828 systems without an fsync() implementation, this variable is always
3829 off.
3830 Also see 'swapsync' for controlling fsync() on swap files.
Bram Moolenaar340dd0f2021-10-14 17:52:23 +01003831 'fsync' also applies to |writefile()| (unless a flag is used to
3832 overrule it) and when writing undo files (see |undo-persistence|).
Bram Moolenaar110289e2019-05-23 15:38:06 +02003833 This option cannot be set from a |modeline| or in the |sandbox|, for
3834 security reasons.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00003835
Bram Moolenaar071d4272004-06-13 20:20:40 +00003836 *'gdefault'* *'gd'* *'nogdefault'* *'nogd'*
3837'gdefault' 'gd' boolean (default off)
3838 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003839 When on, the ":substitute" flag 'g' is default on. This means that
3840 all matches in a line are substituted instead of one. When a 'g' flag
3841 is given to a ":substitute" command, this will toggle the substitution
3842 of all or one match. See |complex-change|.
3843
3844 command 'gdefault' on 'gdefault' off ~
3845 :s/// subst. all subst. one
3846 :s///g subst. one subst. all
3847 :s///gg subst. all subst. one
3848
3849 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaar21020352017-06-13 17:21:04 +02003850 DEPRECATED: Setting this option may break plugins that are not aware
3851 of this option. Also, many users get confused that adding the /g flag
3852 has the opposite effect of that it normally does.
Bram Moolenaar4072ba52020-12-23 13:56:35 +01003853 This option is not used in |Vim9| script.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003854
3855 *'grepformat'* *'gfm'*
Bram Moolenaar6e932462014-09-09 18:48:09 +02003856'grepformat' 'gfm' string (default "%f:%l:%m,%f:%l%m,%f %l%m")
Bram Moolenaar071d4272004-06-13 20:20:40 +00003857 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003858 Format to recognize for the ":grep" command output.
3859 This is a scanf-like string that uses the same format as the
3860 'errorformat' option: see |errorformat|.
3861
3862 *'grepprg'* *'gp'*
3863'grepprg' 'gp' string (default "grep -n ",
3864 Unix: "grep -n $* /dev/null",
3865 Win32: "findstr /n" or "grep -n",
3866 VMS: "SEARCH/NUMBERS ")
3867 global or local to buffer |global-local|
Bram Moolenaar582fd852005-03-28 20:58:01 +00003868 Program to use for the |:grep| command. This option may contain '%'
Bram Moolenaar071d4272004-06-13 20:20:40 +00003869 and '#' characters, which are expanded like when used in a command-
3870 line. The placeholder "$*" is allowed to specify where the arguments
3871 will be included. Environment variables are expanded |:set_env|. See
3872 |option-backslash| about including spaces and backslashes.
3873 When your "grep" accepts the "-H" argument, use this to make ":grep"
3874 also work well with a single file: >
3875 :set grepprg=grep\ -nH
Bram Moolenaar7c626922005-02-07 22:01:03 +00003876< Special value: When 'grepprg' is set to "internal" the |:grep| command
Bram Moolenaara6557602006-02-04 22:43:20 +00003877 works like |:vimgrep|, |:lgrep| like |:lvimgrep|, |:grepadd| like
3878 |:vimgrepadd| and |:lgrepadd| like |:lvimgrepadd|.
Bram Moolenaar86b68352004-12-27 21:59:20 +00003879 See also the section |:make_makeprg|, since most of the comments there
Bram Moolenaar071d4272004-06-13 20:20:40 +00003880 apply equally to 'grepprg'.
3881 For Win32, the default is "findstr /n" if "findstr.exe" can be found,
3882 otherwise it's "grep -n".
3883 This option cannot be set from a |modeline| or in the |sandbox|, for
3884 security reasons.
3885
3886 *'guicursor'* *'gcr'* *E545* *E546* *E548* *E549*
3887'guicursor' 'gcr' string (default "n-v-c:block-Cursor/lCursor,
3888 ve:ver35-Cursor,
3889 o:hor50-Cursor,
3890 i-ci:ver25-Cursor/lCursor,
3891 r-cr:hor20-Cursor/lCursor,
3892 sm:block-Cursor
3893 -blinkwait175-blinkoff150-blinkon175",
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01003894 for Win32 console:
Bram Moolenaar071d4272004-06-13 20:20:40 +00003895 "n-v-c:block,o:hor50,i-ci:hor15,
3896 r-cr:hor30,sm:block")
3897 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003898 {only available when compiled with GUI enabled, and
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01003899 for Win32 console}
Bram Moolenaar071d4272004-06-13 20:20:40 +00003900 This option tells Vim what the cursor should look like in different
Bram Moolenaar8024f932020-01-14 19:29:13 +01003901 modes. It fully works in the GUI. In a Win32 console, only the
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01003902 height of the cursor can be changed. This can be done by specifying a
3903 block cursor, or a percentage for a vertical or horizontal cursor.
Bram Moolenaar1e7813a2015-03-31 18:31:03 +02003904 For a console the 't_SI', 't_SR', and 't_EI' escape sequences are
3905 used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003906
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01003907 The option is a comma-separated list of parts. Each part consist of a
Bram Moolenaar071d4272004-06-13 20:20:40 +00003908 mode-list and an argument-list:
3909 mode-list:argument-list,mode-list:argument-list,..
3910 The mode-list is a dash separated list of these modes:
3911 n Normal mode
3912 v Visual mode
3913 ve Visual mode with 'selection' "exclusive" (same as 'v',
3914 if not specified)
3915 o Operator-pending mode
3916 i Insert mode
3917 r Replace mode
3918 c Command-line Normal (append) mode
3919 ci Command-line Insert mode
3920 cr Command-line Replace mode
3921 sm showmatch in Insert mode
3922 a all modes
3923 The argument-list is a dash separated list of these arguments:
3924 hor{N} horizontal bar, {N} percent of the character height
3925 ver{N} vertical bar, {N} percent of the character width
3926 block block cursor, fills the whole character
3927 [only one of the above three should be present]
3928 blinkwait{N} *cursor-blinking*
3929 blinkon{N}
3930 blinkoff{N}
3931 blink times for cursor: blinkwait is the delay before
3932 the cursor starts blinking, blinkon is the time that
3933 the cursor is shown and blinkoff is the time that the
3934 cursor is not shown. The times are in msec. When one
3935 of the numbers is zero, there is no blinking. The
3936 default is: "blinkwait700-blinkon400-blinkoff250".
3937 These numbers are used for a missing entry. This
3938 means that blinking is enabled by default. To switch
3939 blinking off you can use "blinkon0". The cursor only
3940 blinks when Vim is waiting for input, not while
3941 executing a command.
3942 To make the cursor blink in an xterm, see
3943 |xterm-blink|.
3944 {group-name}
3945 a highlight group name, that sets the color and font
3946 for the cursor
3947 {group-name}/{group-name}
3948 Two highlight group names, the first is used when
3949 no language mappings are used, the other when they
3950 are. |language-mapping|
3951
3952 Examples of parts:
3953 n-c-v:block-nCursor in Normal, Command-line and Visual mode, use a
3954 block cursor with colors from the "nCursor"
3955 highlight group
3956 i-ci:ver30-iCursor-blinkwait300-blinkon200-blinkoff150
3957 In Insert and Command-line Insert mode, use a
3958 30% vertical bar cursor with colors from the
3959 "iCursor" highlight group. Blink a bit
3960 faster.
3961
3962 The 'a' mode is different. It will set the given argument-list for
3963 all modes. It does not reset anything to defaults. This can be used
3964 to do a common setting for all modes. For example, to switch off
3965 blinking: "a:blinkon0"
3966
3967 Examples of cursor highlighting: >
3968 :highlight Cursor gui=reverse guifg=NONE guibg=NONE
3969 :highlight Cursor gui=NONE guifg=bg guibg=fg
3970<
3971 *'guifont'* *'gfn'*
Bram Moolenaar251e1912011-06-19 05:09:16 +02003972 *E235* *E596*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003973'guifont' 'gfn' string (default "")
3974 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003975 {only available when compiled with GUI enabled}
3976 This is a list of fonts which will be used for the GUI version of Vim.
Bram Moolenaarf720d0a2019-04-28 14:02:47 +02003977 In its simplest form the value is just one font name.
3978 See |gui-font| for the details.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003979
3980 *'guifontset'* *'gfs'*
3981 *E250* *E252* *E234* *E597* *E598*
3982'guifontset' 'gfs' string (default "")
3983 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003984 {only available when compiled with GUI enabled and
3985 with the |+xfontset| feature}
Bram Moolenaar3df01732017-02-17 22:47:16 +01003986 {not available in the GTK+ GUI}
Bram Moolenaar071d4272004-06-13 20:20:40 +00003987 When not empty, specifies two (or more) fonts to be used. The first
3988 one for normal English, the second one for your special language. See
3989 |xfontset|.
Bram Moolenaarf720d0a2019-04-28 14:02:47 +02003990
Bram Moolenaar071d4272004-06-13 20:20:40 +00003991 *'guifontwide'* *'gfw'* *E231* *E533* *E534*
3992'guifontwide' 'gfw' string (default "")
3993 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003994 {only available when compiled with GUI enabled}
3995 When not empty, specifies a comma-separated list of fonts to be used
3996 for double-width characters. The first font that can be loaded is
Bram Moolenaarf720d0a2019-04-28 14:02:47 +02003997 used. See |gui-fontwide|.
Bram Moolenaar0f272122013-01-23 18:37:40 +01003998
Bram Moolenaar071d4272004-06-13 20:20:40 +00003999 *'guiheadroom'* *'ghr'*
4000'guiheadroom' 'ghr' number (default 50)
4001 global
Bram Moolenaar110289e2019-05-23 15:38:06 +02004002 {only for GTK and X11 GUI}
Bram Moolenaar071d4272004-06-13 20:20:40 +00004003 The number of pixels subtracted from the screen height when fitting
4004 the GUI window on the screen. Set this before the GUI is started,
4005 e.g., in your |gvimrc| file. When zero, the whole screen height will
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004006 be used by the window. When positive, the specified number of pixel
Bram Moolenaar071d4272004-06-13 20:20:40 +00004007 lines will be left for window decorations and other items on the
4008 screen. Set it to a negative value to allow windows taller than the
4009 screen.
4010
Dusan Popovic4eeedc02021-10-16 20:52:05 +01004011 *'guiligatures'* *'gli'* *E1243*
4012'guiligatures' 'gli' string (default "")
4013 global
4014 {only for GTK GUI}
4015 List of ASCII characters that, when combined together, can create more
4016 complex shapes. Each character must be a printable ASCII character
4017 with a value in the 32-127 range.
4018 Example: >
4019 :set guiligatures=!\"#$%&()*+-./:<=>?@[]^_{\|~
4020< Changing this option updates screen output immediately. Set it to an
4021 empty string to disable ligatures.
4022
Bram Moolenaar071d4272004-06-13 20:20:40 +00004023 *'guioptions'* *'go'*
Bram Moolenaar2c64ca12018-10-19 16:22:31 +02004024'guioptions' 'go' string (default "egmrLtT" (MS-Windows,
4025 "t" is removed in |defaults.vim|),
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01004026 "aegimrLtT" (GTK and Motif),
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +02004027 )
Bram Moolenaar071d4272004-06-13 20:20:40 +00004028 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004029 {only available when compiled with GUI enabled}
Bram Moolenaared203462004-06-16 11:19:22 +00004030 This option only has an effect in the GUI version of Vim. It is a
Bram Moolenaar071d4272004-06-13 20:20:40 +00004031 sequence of letters which describes what components and options of the
4032 GUI should be used.
4033 To avoid problems with flags that are added in the future, use the
4034 "+=" and "-=" feature of ":set" |add-option-flags|.
4035
Bram Moolenaar13568252018-03-16 20:46:58 +01004036 Valid characters are as follows:
4037 *'go-!'*
4038 '!' External commands are executed in a terminal window. Without
4039 this flag the MS-Windows GUI will open a console window to
4040 execute the command. The Unix GUI will simulate a dumb
4041 terminal to list the command output.
4042 The terminal window will be positioned at the bottom, and grow
4043 upwards as needed.
Bram Moolenaarba3ff532018-11-04 14:45:49 +01004044 *'go-a'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004045 'a' Autoselect: If present, then whenever VISUAL mode is started,
4046 or the Visual area extended, Vim tries to become the owner of
4047 the windowing system's global selection. This means that the
4048 Visually highlighted text is available for pasting into other
4049 applications as well as into Vim itself. When the Visual mode
4050 ends, possibly due to an operation on the text, or when an
4051 application wants to paste the selection, the highlighted text
4052 is automatically yanked into the "* selection register.
4053 Thus the selection is still available for pasting into other
4054 applications after the VISUAL mode has ended.
4055 If not present, then Vim won't become the owner of the
4056 windowing system's global selection unless explicitly told to
4057 by a yank or delete operation for the "* register.
4058 The same applies to the modeless selection.
Bram Moolenaarc0885aa2012-07-10 16:49:23 +02004059 *'go-P'*
4060 'P' Like autoselect but using the "+ register instead of the "*
Bram Moolenaar3848e002016-03-19 18:42:29 +01004061 register.
Bram Moolenaar02467872007-05-06 13:22:01 +00004062 *'go-A'*
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004063 'A' Autoselect for the modeless selection. Like 'a', but only
Bram Moolenaar071d4272004-06-13 20:20:40 +00004064 applies to the modeless selection.
4065
4066 'guioptions' autoselect Visual autoselect modeless ~
4067 "" - -
4068 "a" yes yes
4069 "A" - yes
4070 "aA" yes yes
4071
Bram Moolenaar9fbdbb82022-09-27 17:30:34 +01004072 When using a terminal see the 'clipboard' option.
4073
Bram Moolenaar02467872007-05-06 13:22:01 +00004074 *'go-c'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004075 'c' Use console dialogs instead of popup dialogs for simple
4076 choices.
Bram Moolenaar50bf7ce2019-09-15 13:17:00 +02004077 *'go-d'*
4078 'd' Use dark theme variant if available. Currently only works for
4079 GTK+ GUI.
Bram Moolenaar02467872007-05-06 13:22:01 +00004080 *'go-e'*
Bram Moolenaare224ffa2006-03-01 00:01:28 +00004081 'e' Add tab pages when indicated with 'showtabline'.
Bram Moolenaar5c8837f2006-02-25 21:52:33 +00004082 'guitablabel' can be used to change the text in the labels.
4083 When 'e' is missing a non-GUI tab pages line may be used.
Bram Moolenaard68071d2006-05-02 22:08:30 +00004084 The GUI tabs are only supported on some systems, currently
Bram Moolenaarb3f74062020-02-26 16:16:53 +01004085 GTK, Motif, Mac OS/X, Haiku, and MS-Windows.
Bram Moolenaar02467872007-05-06 13:22:01 +00004086 *'go-f'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004087 'f' Foreground: Don't use fork() to detach the GUI from the shell
4088 where it was started. Use this for programs that wait for the
4089 editor to finish (e.g., an e-mail program). Alternatively you
4090 can use "gvim -f" or ":gui -f" to start the GUI in the
4091 foreground. |gui-fork|
4092 Note: Set this option in the vimrc file. The forking may have
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004093 happened already when the |gvimrc| file is read.
Bram Moolenaar02467872007-05-06 13:22:01 +00004094 *'go-i'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004095 'i' Use a Vim icon. For GTK with KDE it is used in the left-upper
4096 corner of the window. It's black&white on non-GTK, because of
4097 limitations of X11. For a color icon, see |X11-icon|.
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02004098 *'go-m'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004099 'm' Menu bar is present.
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02004100 *'go-M'*
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004101 'M' The system menu "$VIMRUNTIME/menu.vim" is not sourced. Note
Bram Moolenaar071d4272004-06-13 20:20:40 +00004102 that this flag must be added in the .vimrc file, before
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004103 switching on syntax or filetype recognition (when the |gvimrc|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004104 file is sourced the system menu has already been loaded; the
Bram Moolenaar01164a62017-11-02 22:58:42 +01004105 `:syntax on` and `:filetype on` commands load the menu too).
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02004106 *'go-g'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004107 'g' Grey menu items: Make menu items that are not active grey. If
4108 'g' is not included inactive menu items are not shown at all.
Bram Moolenaar02467872007-05-06 13:22:01 +00004109 *'go-t'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004110 't' Include tearoff menu items. Currently only works for Win32,
4111 GTK+, and Motif 1.2 GUI.
Bram Moolenaar02467872007-05-06 13:22:01 +00004112 *'go-T'*
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01004113 'T' Include Toolbar. Currently only in Win32, GTK+, Motif and
4114 Photon GUIs.
Bram Moolenaar02467872007-05-06 13:22:01 +00004115 *'go-r'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004116 'r' Right-hand scrollbar is always present.
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02004117 *'go-R'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004118 'R' Right-hand scrollbar is present when there is a vertically
4119 split window.
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02004120 *'go-l'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004121 'l' Left-hand scrollbar is always present.
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02004122 *'go-L'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004123 'L' Left-hand scrollbar is present when there is a vertically
4124 split window.
Bram Moolenaar02467872007-05-06 13:22:01 +00004125 *'go-b'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004126 'b' Bottom (horizontal) scrollbar is present. Its size depends on
4127 the longest visible line, or on the cursor line if the 'h'
4128 flag is included. |gui-horiz-scroll|
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02004129 *'go-h'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004130 'h' Limit horizontal scrollbar size to the length of the cursor
4131 line. Reduces computations. |gui-horiz-scroll|
4132
4133 And yes, you may even have scrollbars on the left AND the right if
4134 you really want to :-). See |gui-scrollbars| for more information.
4135
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02004136 *'go-v'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004137 'v' Use a vertical button layout for dialogs. When not included,
4138 a horizontal layout is preferred, but when it doesn't fit a
Bram Moolenaardad44732021-03-31 20:07:33 +02004139 vertical layout is used anyway. Not supported in GTK 3.
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02004140 *'go-p'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004141 'p' Use Pointer callbacks for X11 GUI. This is required for some
4142 window managers. If the cursor is not blinking or hollow at
4143 the right moment, try adding this flag. This must be done
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004144 before starting the GUI. Set it in your |gvimrc|. Adding or
Bram Moolenaar071d4272004-06-13 20:20:40 +00004145 removing it after the GUI has started has no effect.
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02004146 *'go-F'*
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004147 'F' Add a footer. Only for Motif. See |gui-footer|.
Bram Moolenaar8ac44152017-11-09 18:33:29 +01004148 *'go-k'*
4149 'k' Keep the GUI window size when adding/removing a scrollbar, or
4150 toolbar, tabline, etc. Instead, the behavior is similar to
4151 when the window is maximized and will adjust 'lines' and
4152 'columns' to fit to the window. Without the 'k' flag Vim will
Bram Moolenaar51b0f372017-11-18 18:52:04 +01004153 try to keep 'lines' and 'columns' the same when adding and
Bram Moolenaar8ac44152017-11-09 18:33:29 +01004154 removing GUI components.
Bram Moolenaar02467872007-05-06 13:22:01 +00004155
Bram Moolenaar071d4272004-06-13 20:20:40 +00004156 *'guipty'* *'noguipty'*
4157'guipty' boolean (default on)
4158 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004159 {only available when compiled with GUI enabled}
4160 Only in the GUI: If on, an attempt is made to open a pseudo-tty for
4161 I/O to/from shell commands. See |gui-pty|.
4162
Bram Moolenaar5c8837f2006-02-25 21:52:33 +00004163 *'guitablabel'* *'gtl'*
4164'guitablabel' 'gtl' string (default empty)
4165 global
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02004166 {only available when compiled with GUI enabled}
Bram Moolenaar944697a2022-02-20 19:48:20 +00004167 When non-empty describes the text to use in a label of the GUI tab
Bram Moolenaard68071d2006-05-02 22:08:30 +00004168 pages line. When empty and when the result is empty Vim will use a
4169 default label. See |setting-guitablabel| for more info.
Bram Moolenaar5c8837f2006-02-25 21:52:33 +00004170
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004171 The format of this option is like that of 'statusline'.
Bram Moolenaar57657d82006-04-21 22:12:41 +00004172 'guitabtooltip' is used for the tooltip, see below.
Bram Moolenaar51628222016-12-01 23:03:28 +01004173 The expression will be evaluated in the |sandbox| when set from a
4174 modeline, see |sandbox-option|.
Bram Moolenaar110289e2019-05-23 15:38:06 +02004175 This option cannot be set in a modeline when 'modelineexpr' is off.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004176
Bram Moolenaar5c8837f2006-02-25 21:52:33 +00004177 Only used when the GUI tab pages line is displayed. 'e' must be
4178 present in 'guioptions'. For the non-GUI tab pages line 'tabline' is
4179 used.
4180
Bram Moolenaar57657d82006-04-21 22:12:41 +00004181 *'guitabtooltip'* *'gtt'*
4182'guitabtooltip' 'gtt' string (default empty)
4183 global
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02004184 {only available when compiled with GUI enabled}
Bram Moolenaar944697a2022-02-20 19:48:20 +00004185 When non-empty describes the text to use in a tooltip for the GUI tab
Bram Moolenaar57657d82006-04-21 22:12:41 +00004186 pages line. When empty Vim will use a default tooltip.
4187 This option is otherwise just like 'guitablabel' above.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004188 You can include a line break. Simplest method is to use |:let|: >
4189 :let &guitabtooltip = "line one\nline two"
4190<
Bram Moolenaar57657d82006-04-21 22:12:41 +00004191
Bram Moolenaar071d4272004-06-13 20:20:40 +00004192 *'helpfile'* *'hf'*
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01004193'helpfile' 'hf' string (default (MS-Windows) "$VIMRUNTIME\doc\help.txt"
Bram Moolenaar071d4272004-06-13 20:20:40 +00004194 (others) "$VIMRUNTIME/doc/help.txt")
4195 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004196 Name of the main help file. All distributed help files should be
4197 placed together in one directory. Additionally, all "doc" directories
4198 in 'runtimepath' will be used.
4199 Environment variables are expanded |:set_env|. For example:
4200 "$VIMRUNTIME/doc/help.txt". If $VIMRUNTIME is not set, $VIM is also
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004201 tried. Also see |$VIMRUNTIME| and |option-backslash| about including
Bram Moolenaar071d4272004-06-13 20:20:40 +00004202 spaces and backslashes.
4203 This option cannot be set from a |modeline| or in the |sandbox|, for
4204 security reasons.
4205
4206 *'helpheight'* *'hh'*
4207'helpheight' 'hh' number (default 20)
4208 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004209 Minimal initial height of the help window when it is opened with the
4210 ":help" command. The initial height of the help window is half of the
4211 current window, or (when the 'ea' option is on) the same as other
4212 windows. When the height is less than 'helpheight', the height is
4213 set to 'helpheight'. Set to zero to disable.
4214
4215 *'helplang'* *'hlg'*
4216'helplang' 'hlg' string (default: messages language or empty)
4217 global
4218 {only available when compiled with the |+multi_lang|
4219 feature}
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01004220 Comma-separated list of languages. Vim will use the first language
Bram Moolenaar071d4272004-06-13 20:20:40 +00004221 for which the desired help can be found. The English help will always
4222 be used as a last resort. You can add "en" to prefer English over
4223 another language, but that will only find tags that exist in that
4224 language and not in the English help.
4225 Example: >
4226 :set helplang=de,it
4227< This will first search German, then Italian and finally English help
4228 files.
4229 When using |CTRL-]| and ":help!" in a non-English help file Vim will
4230 try to find the tag in the current language before using this option.
4231 See |help-translated|.
4232
4233 *'hidden'* *'hid'* *'nohidden'* *'nohid'*
4234'hidden' 'hid' boolean (default off)
4235 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004236 When off a buffer is unloaded when it is |abandon|ed. When on a
4237 buffer becomes hidden when it is |abandon|ed. If the buffer is still
4238 displayed in another window, it does not become hidden, of course.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01004239
Bram Moolenaar071d4272004-06-13 20:20:40 +00004240 The commands that move through the buffer list sometimes make a buffer
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01004241 hidden even if the 'hidden' option is off when these three are true:
4242 - the buffer is modified
4243 - 'autowrite' is off or writing is not possible
4244 - the '!' flag was used
4245 Also see |windows.txt|.
4246
Bram Moolenaarcfbc5ee2004-07-02 15:38:35 +00004247 To only make one buffer hidden use the 'bufhidden' option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004248 This option is set for one command with ":hide {command}" |:hide|.
4249 WARNING: It's easy to forget that you have changes in hidden buffers.
4250 Think twice when using ":q!" or ":qa!".
4251
4252 *'highlight'* *'hl'*
4253'highlight' 'hl' string (default (as a single string):
Bram Moolenaar58b85342016-08-14 19:54:54 +02004254 "8:SpecialKey,~:EndOfBuffer,@:NonText,
4255 d:Directory,e:ErrorMsg,i:IncSearch,
4256 l:Search,m:MoreMsg,M:ModeMsg,n:LineNr,
Bram Moolenaarefae76a2019-10-27 22:54:58 +01004257 a:LineNrAbove,b:LineNrBelow,
Bram Moolenaar58b85342016-08-14 19:54:54 +02004258 N:CursorLineNr,r:Question,s:StatusLine,
4259 S:StatusLineNC,c:VertSplit,t:Title,
Bram Moolenaar9d87a372018-12-18 21:41:50 +01004260 v:Visual,V:VisualNOS,w:WarningMsg,
4261 W:WildMenu,f:Folded,F:FoldColumn,
4262 A:DiffAdd,C:DiffChange,D:DiffDelete,
4263 T:DiffText,>:SignColumn,-:Conceal,
Bram Moolenaarc8c88492018-12-27 23:59:26 +01004264 B:SpellBad,P:SpellCap,R:SpellRare,
Bram Moolenaar9d87a372018-12-18 21:41:50 +01004265 L:SpellLocal,+:Pmenu,=:PmenuSel,
Gianmaria Bajo6a7c7742023-03-10 16:35:53 +00004266 [:PmenuKind,]:PmenuKindSel,
4267 {:PmenuExtra,}:PmenuExtraSel,
Bram Moolenaar21020352017-06-13 17:21:04 +02004268 x:PmenuSbar,X:PmenuThumb,*:TabLine,
4269 #:TabLineSel,_:TabLineFill,!:CursorColumn,
Bram Moolenaarf55e4c82017-08-01 20:44:53 +02004270 .:CursorLine,o:ColorColumn,q:QuickFixLine,
Bram Moolenaarc572da52017-08-27 16:52:01 +02004271 z:StatusLineTerm,Z:StatusLineTermNC")
Bram Moolenaar071d4272004-06-13 20:20:40 +00004272 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004273 This option can be used to set highlighting mode for various
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01004274 occasions. It is a comma-separated list of character pairs. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00004275 first character in a pair gives the occasion, the second the mode to
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004276 use for that occasion. The occasions are:
Bram Moolenaar071d4272004-06-13 20:20:40 +00004277 |hl-SpecialKey| 8 Meta and special keys listed with ":map"
Bram Moolenaar58b85342016-08-14 19:54:54 +02004278 |hl-EndOfBuffer| ~ lines after the last line in the buffer
4279 |hl-NonText| @ '@' at the end of the window and
Bram Moolenaar071d4272004-06-13 20:20:40 +00004280 characters from 'showbreak'
4281 |hl-Directory| d directories in CTRL-D listing and other special
4282 things in listings
4283 |hl-ErrorMsg| e error messages
4284 h (obsolete, ignored)
4285 |hl-IncSearch| i 'incsearch' highlighting
LemonBoya4399382022-04-09 21:04:08 +01004286 |hl-CurSearch| y current instance of last search pattern
Bram Moolenaar071d4272004-06-13 20:20:40 +00004287 |hl-Search| l last search pattern highlighting (see 'hlsearch')
4288 |hl-MoreMsg| m |more-prompt|
4289 |hl-ModeMsg| M Mode (e.g., "-- INSERT --")
Bram Moolenaar64486672010-05-16 15:46:46 +02004290 |hl-LineNr| n line number for ":number" and ":#" commands, and
4291 when 'number' or 'relativenumber' option is set.
Bram Moolenaarefae76a2019-10-27 22:54:58 +01004292 |hl-LineNrAbove| a line number above the cursor for when the
4293 'relativenumber' option is set.
4294 |hl-LineNrBelow| b line number below the cursor for when the
4295 'relativenumber' option is set.
Bram Moolenaara3e6bc92013-01-30 14:18:00 +01004296 |hl-CursorLineNr| N like n for when 'cursorline' or 'relativenumber' is
4297 set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004298 |hl-Question| r |hit-enter| prompt and yes/no questions
4299 |hl-StatusLine| s status line of current window |status-line|
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004300 |hl-StatusLineNC| S status lines of not-current windows
Bram Moolenaar071d4272004-06-13 20:20:40 +00004301 |hl-Title| t Titles for output from ":set all", ":autocmd" etc.
4302 |hl-VertSplit| c column used to separate vertically split windows
4303 |hl-Visual| v Visual mode
4304 |hl-VisualNOS| V Visual mode when Vim does is "Not Owning the
4305 Selection" Only X11 Gui's |gui-x11| and
4306 |xterm-clipboard|.
4307 |hl-WarningMsg| w warning messages
4308 |hl-WildMenu| W wildcard matches displayed for 'wildmenu'
4309 |hl-Folded| f line used for closed folds
4310 |hl-FoldColumn| F 'foldcolumn'
Bram Moolenaar0d9c26d2005-07-02 23:19:16 +00004311 |hl-DiffAdd| A added line in diff mode
4312 |hl-DiffChange| C changed line in diff mode
4313 |hl-DiffDelete| D deleted line in diff mode
4314 |hl-DiffText| T inserted text in diff mode
Bram Moolenaar071d4272004-06-13 20:20:40 +00004315 |hl-SignColumn| > column used for |signs|
Bram Moolenaar9d87a372018-12-18 21:41:50 +01004316 |hl-Conceal| - the placeholders used for concealed characters
4317 (see 'conceallevel')
Bram Moolenaar217ad922005-03-20 22:37:15 +00004318 |hl-SpellBad| B misspelled word |spell|
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02004319 |hl-SpellCap| P word that should start with capital |spell|
Bram Moolenaar217ad922005-03-20 22:37:15 +00004320 |hl-SpellRare| R rare word |spell|
4321 |hl-SpellLocal| L word from other region |spell|
Bram Moolenaar9d87a372018-12-18 21:41:50 +01004322 |hl-Pmenu| + popup menu normal line
4323 |hl-PmenuSel| = popup menu selected line
Gianmaria Bajo6a7c7742023-03-10 16:35:53 +00004324 |hl-PmenuKind| [ popup menu "kind" normal line
4325 |hl-PmenuKindSel| ] popup menu "kind" selected line
h_east59858792023-10-25 22:47:05 +09004326 |hl-PmenuExtra| { popup menu "extra" normal line
4327 |hl-PmenuExtraSel| } popup menu "extra" selected line
Bram Moolenaar9d87a372018-12-18 21:41:50 +01004328 |hl-PmenuSbar| x popup menu scrollbar
4329 |hl-PmenuThumb| X popup menu scrollbar thumb
Bram Moolenaar071d4272004-06-13 20:20:40 +00004330
4331 The display modes are:
4332 r reverse (termcap entry "mr" and "me")
4333 i italic (termcap entry "ZH" and "ZR")
4334 b bold (termcap entry "md" and "me")
4335 s standout (termcap entry "so" and "se")
4336 u underline (termcap entry "us" and "ue")
Bram Moolenaar84f54632022-06-29 18:39:11 +01004337 c undercurl (termcap entry "Us" and "Ce")
4338 2 double underline (termcap entry "Ds" and "Ce")
4339 d dotted underline (termcap entry "ds" and "Ce")
4340 = dashed underline (termcap entry "Ds" and "Ce")
Bram Moolenaarcf4b00c2017-09-02 18:33:56 +02004341 t strikethrough (termcap entry "Ts" and "Te")
Bram Moolenaar071d4272004-06-13 20:20:40 +00004342 n no highlighting
4343 - no highlighting
4344 : use a highlight group
4345 The default is used for occasions that are not included.
4346 If you want to change what the display modes do, see |dos-colors|
4347 for an example.
4348 When using the ':' display mode, this must be followed by the name of
4349 a highlight group. A highlight group can be used to define any type
4350 of highlighting, including using color. See |:highlight| on how to
4351 define one. The default uses a different group for each occasion.
4352 See |highlight-default| for the default highlight groups.
4353
Bram Moolenaar071d4272004-06-13 20:20:40 +00004354 *'history'* *'hi'*
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +02004355'history' 'hi' number (Vim default: 50, Vi default: 0,
4356 set to 200 in |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004357 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004358 A history of ":" commands, and a history of previous search patterns
Bram Moolenaar78159bb2014-06-25 11:48:54 +02004359 is remembered. This option decides how many entries may be stored in
Bram Moolenaar071d4272004-06-13 20:20:40 +00004360 each of these histories (see |cmdline-editing|).
Bram Moolenaar78159bb2014-06-25 11:48:54 +02004361 The maximum value is 10000.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004362 NOTE: This option is set to the Vi default value when 'compatible' is
4363 set and to the Vim default value when 'compatible' is reset.
4364
4365 *'hkmap'* *'hk'* *'nohkmap'* *'nohk'*
4366'hkmap' 'hk' boolean (default off)
4367 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004368 {only available when compiled with the |+rightleft|
4369 feature}
4370 When on, the keyboard is mapped for the Hebrew character set.
4371 Normally you would set 'allowrevins' and use CTRL-_ in insert mode to
4372 toggle this option. See |rileft.txt|.
4373 NOTE: This option is reset when 'compatible' is set.
4374
4375 *'hkmapp'* *'hkp'* *'nohkmapp'* *'nohkp'*
4376'hkmapp' 'hkp' boolean (default off)
4377 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004378 {only available when compiled with the |+rightleft|
4379 feature}
4380 When on, phonetic keyboard mapping is used. 'hkmap' must also be on.
4381 This is useful if you have a non-Hebrew keyboard.
4382 See |rileft.txt|.
4383 NOTE: This option is reset when 'compatible' is set.
4384
Bram Moolenaar036986f2017-03-16 17:41:02 +01004385 *'hlsearch'* *'hls'* *'nohlsearch'* *'nohls'*
4386'hlsearch' 'hls' boolean (default off)
4387 global
Bram Moolenaar036986f2017-03-16 17:41:02 +01004388 {not available when compiled without the
4389 |+extra_search| feature}
4390 When there is a previous search pattern, highlight all its matches.
4391 The type of highlighting used can be set with the 'l' occasion in the
4392 'highlight' option. This uses the "Search" highlight group by
4393 default. Note that only the matching text is highlighted, any offsets
Bram Moolenaarcfa8f9a2022-06-03 21:59:47 +01004394 are not applied. If the "CurSearch" highlight group is set then the
4395 current match is highlighted with that.
Bram Moolenaar036986f2017-03-16 17:41:02 +01004396 See also: 'incsearch' and |:match|.
4397 When you get bored looking at the highlighted matches, you can turn it
4398 off with |:nohlsearch|. This does not change the option value, as
4399 soon as you use a search command, the highlighting comes back.
4400 'redrawtime' specifies the maximum time spent on finding matches.
4401 When the search pattern can match an end-of-line, Vim will try to
4402 highlight all of the matched text. However, this depends on where the
4403 search starts. This will be the first line in the window or the first
4404 line below a closed fold. A match in a previous line which is not
4405 drawn may not continue in a newly drawn line.
4406 You can specify whether the highlight status is restored on startup
4407 with the 'h' flag in 'viminfo' |viminfo-h|.
4408 NOTE: This option is reset when 'compatible' is set.
4409
Bram Moolenaar071d4272004-06-13 20:20:40 +00004410 *'icon'* *'noicon'*
4411'icon' boolean (default off, on when title can be restored)
4412 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004413 When on, the icon text of the window will be set to the value of
4414 'iconstring' (if it is not empty), or to the name of the file
4415 currently being edited. Only the last part of the name is used.
4416 Overridden by the 'iconstring' option.
4417 Only works if the terminal supports setting window icons (currently
4418 only X11 GUI and terminals with a non-empty 't_IS' option - these are
4419 Unix xterm and iris-ansi by default, where 't_IS' is taken from the
4420 builtin termcap).
4421 When Vim was compiled with HAVE_X11 defined, the original icon will be
Bram Moolenaar582fd852005-03-28 20:58:01 +00004422 restored if possible |X11|. See |X11-icon| for changing the icon on
Bram Moolenaar071d4272004-06-13 20:20:40 +00004423 X11.
Bram Moolenaar3a991dd2014-10-02 01:41:41 +02004424 For MS-Windows the icon can be changed, see |windows-icon|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004425
4426 *'iconstring'*
4427'iconstring' string (default "")
4428 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004429 When this option is not empty, it will be used for the icon text of
4430 the window. This happens only when the 'icon' option is on.
4431 Only works if the terminal supports setting window icon text
4432 (currently only X11 GUI and terminals with a non-empty 't_IS' option).
Bram Moolenaar130cbfc2021-04-07 21:07:20 +02004433 Does not work for MS-Windows.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004434 When Vim was compiled with HAVE_X11 defined, the original icon will be
4435 restored if possible |X11|.
4436 When this option contains printf-style '%' items, they will be
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004437 expanded according to the rules used for 'statusline'. See
Bram Moolenaar071d4272004-06-13 20:20:40 +00004438 'titlestring' for example settings.
Bram Moolenaar110289e2019-05-23 15:38:06 +02004439 This option cannot be set in a modeline when 'modelineexpr' is off.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004440 {not available when compiled without the |+statusline| feature}
4441
4442 *'ignorecase'* *'ic'* *'noignorecase'* *'noic'*
4443'ignorecase' 'ic' boolean (default off)
4444 global
Yee Cheng Chin2bbd0d32023-10-14 02:23:45 -07004445 Ignore case in search patterns, |cmdline-completion|, when
4446 searching in the tags file, and non-|Vim9| |expr-==|.
Bram Moolenaar0f6562e2015-11-24 18:48:14 +01004447 Also see 'smartcase' and 'tagcase'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004448 Can be overruled by using "\c" or "\C" in the pattern, see
4449 |/ignorecase|.
4450
Bram Moolenaarabab85a2013-06-26 19:18:05 +02004451 *'imactivatefunc'* *'imaf'*
4452'imactivatefunc' 'imaf' string (default "")
4453 global
Bram Moolenaarabab85a2013-06-26 19:18:05 +02004454 This option specifies a function that will be called to
Yegappan Lakshmanan7645da52021-12-04 14:02:30 +00004455 activate or deactivate the Input Method. The value can be the name of
4456 a function, a |lambda| or a |Funcref|. See |option-value-function| for
4457 more information.
Bram Moolenaaref8c6172020-07-01 15:12:44 +02004458 It is not used in the MS-Windows GUI version.
Bram Moolenaar110289e2019-05-23 15:38:06 +02004459 The expression will be evaluated in the |sandbox| when set from a
4460 modeline, see |sandbox-option|.
Bram Moolenaarabab85a2013-06-26 19:18:05 +02004461
4462 Example: >
4463 function ImActivateFunc(active)
4464 if a:active
4465 ... do something
4466 else
4467 ... do something
4468 endif
4469 " return value is not used
4470 endfunction
4471 set imactivatefunc=ImActivateFunc
4472<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004473 *'imactivatekey'* *'imak'*
4474'imactivatekey' 'imak' string (default "")
4475 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004476 {only available when compiled with |+xim| and
Bram Moolenaar67c53842010-05-22 18:28:27 +02004477 |+GUI_GTK|} *E599*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004478 Specifies the key that your Input Method in X-Windows uses for
4479 activation. When this is specified correctly, vim can fully control
4480 IM with 'imcmdline', 'iminsert' and 'imsearch'.
4481 You can't use this option to change the activation key, the option
4482 tells Vim what the key is.
4483 Format:
4484 [MODIFIER_FLAG-]KEY_STRING
4485
4486 These characters can be used for MODIFIER_FLAG (case is ignored):
4487 S Shift key
4488 L Lock key
4489 C Control key
4490 1 Mod1 key
4491 2 Mod2 key
4492 3 Mod3 key
4493 4 Mod4 key
4494 5 Mod5 key
4495 Combinations are allowed, for example "S-C-space" or "SC-space" are
4496 both shift+ctrl+space.
4497 See <X11/keysymdef.h> and XStringToKeysym for KEY_STRING.
4498
4499 Example: >
4500 :set imactivatekey=S-space
4501< "S-space" means shift+space. This is the activation key for kinput2 +
4502 canna (Japanese), and ami (Korean).
4503
4504 *'imcmdline'* *'imc'* *'noimcmdline'* *'noimc'*
4505'imcmdline' 'imc' boolean (default off)
4506 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004507 When set the Input Method is always on when starting to edit a command
4508 line, unless entering a search pattern (see 'imsearch' for that).
4509 Setting this option is useful when your input method allows entering
4510 English characters directly, e.g., when it's used to type accented
4511 characters with dead keys.
4512
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004513 *'imdisable'* *'imd'* *'noimdisable'* *'noimd'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004514'imdisable' 'imd' boolean (default off, on for some systems (SGI))
4515 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004516 When set the Input Method is never used. This is useful to disable
4517 the IM when it doesn't work properly.
4518 Currently this option is on by default for SGI/IRIX machines. This
4519 may change in later releases.
4520
4521 *'iminsert'* *'imi'*
Bram Moolenaar4cf56bb2017-09-16 15:50:32 +02004522'iminsert' 'imi' number (default 0)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004523 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00004524 Specifies whether :lmap or an Input Method (IM) is to be used in
4525 Insert mode. Valid values:
4526 0 :lmap is off and IM is off
4527 1 :lmap is ON and IM is off
4528 2 :lmap is off and IM is ON
Bram Moolenaar071d4272004-06-13 20:20:40 +00004529 To always reset the option to zero when leaving Insert mode with <Esc>
4530 this can be used: >
4531 :inoremap <ESC> <ESC>:set iminsert=0<CR>
4532< This makes :lmap and IM turn off automatically when leaving Insert
4533 mode.
4534 Note that this option changes when using CTRL-^ in Insert mode
4535 |i_CTRL-^|.
4536 The value is set to 1 when setting 'keymap' to a valid keymap name.
4537 It is also used for the argument of commands like "r" and "f".
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01004538 The value 0 may not work correctly with Motif with some XIM
Bram Moolenaar071d4272004-06-13 20:20:40 +00004539 methods. Use 'imdisable' to disable XIM then.
4540
Bram Moolenaar6315a9a2017-11-25 15:20:02 +01004541 You can set 'imactivatefunc' and 'imstatusfunc' to handle IME/XIM
Bram Moolenaard473c8c2018-08-11 18:00:22 +02004542 via external command if Vim is not compiled with the |+xim|,
Bram Moolenaar6315a9a2017-11-25 15:20:02 +01004543 |+multi_byte_ime| or |global-ime|.
4544
Bram Moolenaar071d4272004-06-13 20:20:40 +00004545 *'imsearch'* *'ims'*
Bram Moolenaar4cf56bb2017-09-16 15:50:32 +02004546'imsearch' 'ims' number (default -1)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004547 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00004548 Specifies whether :lmap or an Input Method (IM) is to be used when
4549 entering a search pattern. Valid values:
4550 -1 the value of 'iminsert' is used, makes it look like
4551 'iminsert' is also used when typing a search pattern
4552 0 :lmap is off and IM is off
4553 1 :lmap is ON and IM is off
4554 2 :lmap is off and IM is ON
4555 Note that this option changes when using CTRL-^ in Command-line mode
4556 |c_CTRL-^|.
4557 The value is set to 1 when it is not -1 and setting the 'keymap'
4558 option to a valid keymap name.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01004559 The value 0 may not work correctly with Motif with some XIM
Bram Moolenaar071d4272004-06-13 20:20:40 +00004560 methods. Use 'imdisable' to disable XIM then.
4561
Bram Moolenaarabab85a2013-06-26 19:18:05 +02004562 *'imstatusfunc'* *'imsf'*
4563'imstatusfunc' 'imsf' string (default "")
4564 global
Bram Moolenaarabab85a2013-06-26 19:18:05 +02004565 This option specifies a function that is called to obtain the status
4566 of Input Method. It must return a positive number when IME is active.
Yegappan Lakshmanan7645da52021-12-04 14:02:30 +00004567 The value can be the name of a function, a |lambda| or a |Funcref|.
4568 See |option-value-function| for more information.
Bram Moolenaaref8c6172020-07-01 15:12:44 +02004569 It is not used in the MS-Windows GUI version.
Bram Moolenaarabab85a2013-06-26 19:18:05 +02004570
4571 Example: >
4572 function ImStatusFunc()
4573 let is_active = ...do something
4574 return is_active ? 1 : 0
4575 endfunction
4576 set imstatusfunc=ImStatusFunc
4577<
4578 NOTE: This function is invoked very often. Keep it fast.
Bram Moolenaar110289e2019-05-23 15:38:06 +02004579 The expression will be evaluated in the |sandbox| when set from a
4580 modeline, see |sandbox-option|.
Bram Moolenaarabab85a2013-06-26 19:18:05 +02004581
Bram Moolenaar5c6dbcb2017-08-30 22:00:20 +02004582 *'imstyle'* *'imst'*
4583'imstyle' 'imst' number (default 1)
4584 global
Bram Moolenaar5c6dbcb2017-08-30 22:00:20 +02004585 {only available when compiled with |+xim| and
4586 |+GUI_GTK|}
Bram Moolenaar37c64c72017-09-19 22:06:03 +02004587 This option specifies the input style of Input Method:
4588 0 use on-the-spot style
4589 1 over-the-spot style
Bram Moolenaar5c6dbcb2017-08-30 22:00:20 +02004590 See: |xim-input-style|
4591
Bram Moolenaar24a98a02017-09-27 22:23:55 +02004592 For a long time on-the-spot style had been used in the GTK version of
4593 vim, however, it is known that it causes troubles when using mappings,
Bram Moolenaar5c6dbcb2017-08-30 22:00:20 +02004594 |single-repeat|, etc. Therefore over-the-spot style becomes the
4595 default now. This should work fine for most people, however if you
4596 have any problem with it, try using on-the-spot style.
Bram Moolenaar110289e2019-05-23 15:38:06 +02004597 The expression will be evaluated in the |sandbox| when set from a
4598 modeline, see |sandbox-option|.
Bram Moolenaar5c6dbcb2017-08-30 22:00:20 +02004599
Bram Moolenaar071d4272004-06-13 20:20:40 +00004600 *'include'* *'inc'*
4601'include' 'inc' string (default "^\s*#\s*include")
4602 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004603 {not available when compiled without the
4604 |+find_in_path| feature}
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004605 Pattern to be used to find an include command. It is a search
Bram Moolenaar071d4272004-06-13 20:20:40 +00004606 pattern, just like for the "/" command (See |pattern|). The default
4607 value is for C programs. This option is used for the commands "[i",
Bram Moolenaar1e015462005-09-25 22:16:38 +00004608 "]I", "[d", etc.
4609 Normally the 'isfname' option is used to recognize the file name that
Bram Moolenaar482aaeb2005-09-29 18:26:07 +00004610 comes after the matched pattern. But if "\zs" appears in the pattern
4611 then the text matched from "\zs" to the end, or until "\ze" if it
4612 appears, is used as the file name. Use this to include characters
4613 that are not in 'isfname', such as a space. You can then use
4614 'includeexpr' to process the matched text.
Bram Moolenaar1e015462005-09-25 22:16:38 +00004615 See |option-backslash| about including spaces and backslashes.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004616
4617 *'includeexpr'* *'inex'*
4618'includeexpr' 'inex' string (default "")
4619 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00004620 {not available when compiled without the
Bram Moolenaardb84e452010-08-15 13:50:43 +02004621 |+find_in_path| or |+eval| features}
Bram Moolenaar071d4272004-06-13 20:20:40 +00004622 Expression to be used to transform the string found with the 'include'
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004623 option to a file name. Mostly useful to change "." to "/" for Java: >
Bram Moolenaarb59ae592022-11-23 23:46:31 +00004624 :setlocal includeexpr=substitute(v:fname,'\\.','/','g')
Bram Moolenaar071d4272004-06-13 20:20:40 +00004625< The "v:fname" variable will be set to the file name that was detected.
Bram Moolenaarb59ae592022-11-23 23:46:31 +00004626 Note the double backslash: the `:set` command first halves them, then
4627 one remains it the value, where "\." matches a dot literally. For
4628 simple character replacements `tr()` avoids the need for escaping: >
4629 :setlocal includeexpr=tr(v:fname,'.','/')
4630<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004631 Also used for the |gf| command if an unmodified file name can't be
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004632 found. Allows doing "gf" on the name after an 'include' statement.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004633 Also used for |<cfile>|.
4634
Yegappan Lakshmanan8bb65f22021-12-26 10:51:39 +00004635 If the expression starts with s: or |<SID>|, then it is replaced with
4636 the script ID (|local-function|). Example: >
Bram Moolenaarb59ae592022-11-23 23:46:31 +00004637 setlocal includeexpr=s:MyIncludeExpr()
4638 setlocal includeexpr=<SID>SomeIncludeExpr()
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00004639< Otherwise, the expression is evaluated in the context of the script
4640 where the option was set, thus script-local items are available.
4641
Bram Moolenaara4e0b972022-10-01 19:43:52 +01004642 It is more efficient if the value is just a function call without
4643 arguments, see |expr-option-function|.
4644
Bram Moolenaar30b65812012-07-12 22:01:11 +02004645 The expression will be evaluated in the |sandbox| when set from a
4646 modeline, see |sandbox-option|.
Bram Moolenaar110289e2019-05-23 15:38:06 +02004647 This option cannot be set in a modeline when 'modelineexpr' is off.
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00004648
4649 It is not allowed to change text or jump to another window while
4650 evaluating 'includeexpr' |textlock|.
4651
Bram Moolenaar071d4272004-06-13 20:20:40 +00004652 *'incsearch'* *'is'* *'noincsearch'* *'nois'*
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +02004653'incsearch' 'is' boolean (default off, set in |defaults.vim| if the
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01004654 |+reltime| feature is supported)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004655 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004656 {not available when compiled without the
Bram Moolenaardb84e452010-08-15 13:50:43 +02004657 |+extra_search| features}
Bram Moolenaar21cf8232004-07-16 20:18:37 +00004658 While typing a search command, show where the pattern, as it was typed
4659 so far, matches. The matched string is highlighted. If the pattern
4660 is invalid or not found, nothing is shown. The screen will be updated
4661 often, this is only useful on fast terminals.
Bram Moolenaarfc65cab2018-08-28 22:58:02 +02004662 Also applies to the pattern in commands: >
4663 :global
4664 :lvimgrep
4665 :lvimgrepadd
4666 :smagic
4667 :snomagic
4668 :sort
4669 :substitute
4670 :vglobal
4671 :vimgrep
4672 :vimgrepadd
4673< Note that the match will be shown, but the cursor will return to its
Bram Moolenaar21cf8232004-07-16 20:18:37 +00004674 original position when no match is found and when pressing <Esc>. You
4675 still need to finish the search command with <Enter> to move the
4676 cursor to the match.
Bram Moolenaardc083282016-10-11 08:57:33 +02004677 You can use the CTRL-G and CTRL-T keys to move to the next and
4678 previous match. |c_CTRL-G| |c_CTRL-T|
Bram Moolenaar91a4e822008-01-19 14:59:58 +00004679 When compiled with the |+reltime| feature Vim only searches for about
4680 half a second. With a complicated pattern and/or a lot of text the
4681 match may not be found. This is to avoid that Vim hangs while you
4682 are typing the pattern.
Bram Moolenaar21cf8232004-07-16 20:18:37 +00004683 The highlighting can be set with the 'i' flag in 'highlight'.
Bram Moolenaar2f058492017-11-30 20:27:52 +01004684 When 'hlsearch' is on, all matched strings are highlighted too while
4685 typing a search command. See also: 'hlsearch'.
Bram Moolenaard473c8c2018-08-11 18:00:22 +02004686 If you don't want to turn 'hlsearch' on, but want to highlight all
4687 matches while searching, you can turn on and off 'hlsearch' with
4688 autocmd. Example: >
Bram Moolenaar2e51d9a2017-10-29 16:40:30 +01004689 augroup vimrc-incsearch-highlight
4690 autocmd!
Bram Moolenaarf8f8b2e2017-11-02 19:08:48 +01004691 autocmd CmdlineEnter /,\? :set hlsearch
4692 autocmd CmdlineLeave /,\? :set nohlsearch
Bram Moolenaar2e51d9a2017-10-29 16:40:30 +01004693 augroup END
4694<
Bram Moolenaarefd2bf12006-03-16 21:41:35 +00004695 CTRL-L can be used to add one character from after the current match
Bram Moolenaara9dc3752010-07-11 20:46:53 +02004696 to the command line. If 'ignorecase' and 'smartcase' are set and the
4697 command line has no uppercase characters, the added character is
4698 converted to lowercase.
Bram Moolenaarefd2bf12006-03-16 21:41:35 +00004699 CTRL-R CTRL-W can be used to add the word at the end of the current
4700 match, excluding the characters that were already typed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004701 NOTE: This option is reset when 'compatible' is set.
4702
4703 *'indentexpr'* *'inde'*
4704'indentexpr' 'inde' string (default "")
4705 local to buffer
Bram Moolenaar8e145b82022-05-21 20:17:31 +01004706 {not available when compiled without the |+eval|
4707 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00004708 Expression which is evaluated to obtain the proper indent for a line.
4709 It is used when a new line is created, for the |=| operator and
4710 in Insert mode as specified with the 'indentkeys' option.
4711 When this option is not empty, it overrules the 'cindent' and
Bram Moolenaar20f90cf2011-05-19 12:22:51 +02004712 'smartindent' indenting. When 'lisp' is set, this option is
Bram Moolenaar49846fb2022-10-15 16:05:33 +01004713 is only used when 'lispoptions' contains "expr:1".
Bram Moolenaar071d4272004-06-13 20:20:40 +00004714 When 'paste' is set this option is not used for indenting.
4715 The expression is evaluated with |v:lnum| set to the line number for
Bram Moolenaar482aaeb2005-09-29 18:26:07 +00004716 which the indent is to be computed. The cursor is also in this line
Bram Moolenaar071d4272004-06-13 20:20:40 +00004717 when the expression is evaluated (but it may be moved around).
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00004718
Yegappan Lakshmanan8bb65f22021-12-26 10:51:39 +00004719 If the expression starts with s: or |<SID>|, then it is replaced with
4720 the script ID (|local-function|). Example: >
4721 set indentexpr=s:MyIndentExpr()
4722 set indentexpr=<SID>SomeIndentExpr()
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00004723< Otherwise, the expression is evaluated in the context of the script
4724 where the option was set, thus script-local items are available.
4725
Bram Moolenaara4e0b972022-10-01 19:43:52 +01004726 The advantage of using a function call without arguments is that it is
4727 faster, see |expr-option-function|.
4728
Bram Moolenaar071d4272004-06-13 20:20:40 +00004729 The expression must return the number of spaces worth of indent. It
4730 can return "-1" to keep the current indent (this means 'autoindent' is
4731 used for the indent).
4732 Functions useful for computing the indent are |indent()|, |cindent()|
4733 and |lispindent()|.
4734 The evaluation of the expression must not have side effects! It must
4735 not change the text, jump to another window, etc. Afterwards the
4736 cursor position is always restored, thus the cursor may be moved.
4737 Normally this option would be set to call a function: >
4738 :set indentexpr=GetMyIndent()
4739< Error messages will be suppressed, unless the 'debug' option contains
4740 "msg".
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00004741 See |indent-expression|.
Bram Moolenaar036986f2017-03-16 17:41:02 +01004742 NOTE: This option is set to "" when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004743
Bram Moolenaar30b65812012-07-12 22:01:11 +02004744 The expression will be evaluated in the |sandbox| when set from a
4745 modeline, see |sandbox-option|.
Bram Moolenaar110289e2019-05-23 15:38:06 +02004746 This option cannot be set in a modeline when 'modelineexpr' is off.
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00004747
4748 It is not allowed to change text or jump to another window while
4749 evaluating 'indentexpr' |textlock|.
4750
4751
Bram Moolenaar071d4272004-06-13 20:20:40 +00004752 *'indentkeys'* *'indk'*
Bram Moolenaarce655742019-01-31 14:12:57 +01004753'indentkeys' 'indk' string (default "0{,0},0),0],:,0#,!^F,o,O,e")
Bram Moolenaar071d4272004-06-13 20:20:40 +00004754 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00004755 A list of keys that, when typed in Insert mode, cause reindenting of
4756 the current line. Only happens if 'indentexpr' isn't empty.
4757 The format is identical to 'cinkeys', see |indentkeys-format|.
4758 See |C-indenting| and |indent-expression|.
4759
4760 *'infercase'* *'inf'* *'noinfercase'* *'noinf'*
4761'infercase' 'inf' boolean (default off)
4762 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00004763 When doing keyword completion in insert mode |ins-completion|, and
Bram Moolenaar446cb832008-06-24 21:56:24 +00004764 'ignorecase' is also on, the case of the match is adjusted depending
4765 on the typed text. If the typed text contains a lowercase letter
4766 where the match has an upper case letter, the completed part is made
4767 lowercase. If the typed text has no lowercase letters and the match
4768 has a lowercase letter where the typed text has an uppercase letter,
4769 and there is a letter before it, the completed part is made uppercase.
4770 With 'noinfercase' the match is used as-is.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004771
4772 *'insertmode'* *'im'* *'noinsertmode'* *'noim'*
4773'insertmode' 'im' boolean (default off)
4774 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004775 Makes Vim work in a way that Insert mode is the default mode. Useful
4776 if you want to use Vim as a modeless editor. Used for |evim|.
4777 These Insert mode commands will be useful:
4778 - Use the cursor keys to move around.
Bram Moolenaardc1f1642016-08-16 18:33:43 +02004779 - Use CTRL-O to execute one Normal mode command |i_CTRL-O|. When
Bram Moolenaar071d4272004-06-13 20:20:40 +00004780 this is a mapping, it is executed as if 'insertmode' was off.
4781 Normal mode remains active until the mapping is finished.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004782 - Use CTRL-L to execute a number of Normal mode commands, then use
Bram Moolenaar488c6512005-08-11 20:09:58 +00004783 <Esc> to get back to Insert mode. Note that CTRL-L moves the cursor
4784 left, like <Esc> does when 'insertmode' isn't set. |i_CTRL-L|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004785
4786 These items change when 'insertmode' is set:
4787 - when starting to edit of a file, Vim goes to Insert mode.
4788 - <Esc> in Insert mode is a no-op and beeps.
4789 - <Esc> in Normal mode makes Vim go to Insert mode.
4790 - CTRL-L in Insert mode is a command, it is not inserted.
4791 - CTRL-Z in Insert mode suspends Vim, see |CTRL-Z|. *i_CTRL-Z*
4792 However, when <Esc> is used inside a mapping, it behaves like
4793 'insertmode' was not set. This was done to be able to use the same
4794 mappings with 'insertmode' set or not set.
4795 When executing commands with |:normal| 'insertmode' is not used.
4796
4797 NOTE: This option is reset when 'compatible' is set.
4798
4799 *'isfname'* *'isf'*
Bram Moolenaar6f345a12019-12-17 21:27:18 +01004800'isfname' 'isf' string (default for Win32:
Bram Moolenaar071d4272004-06-13 20:20:40 +00004801 "@,48-57,/,\,.,-,_,+,,,#,$,%,{,},[,],:,@-@,!,~,="
4802 for AMIGA: "@,48-57,/,.,-,_,+,,,$,:"
4803 for VMS: "@,48-57,/,.,-,_,+,,,#,$,%,<,>,[,],:,;,~"
4804 for OS/390: "@,240-249,/,.,-,_,+,,,#,$,%,~,="
4805 otherwise: "@,48-57,/,.,-,_,+,,,#,$,%,~,=")
4806 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004807 The characters specified by this option are included in file names and
4808 path names. Filenames are used for commands like "gf", "[i" and in
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004809 the tags file. It is also used for "\f" in a |pattern|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004810 Multi-byte characters 256 and above are always included, only the
4811 characters up to 255 are specified with this option.
4812 For UTF-8 the characters 0xa0 to 0xff are included as well.
Bram Moolenaar446cb832008-06-24 21:56:24 +00004813 Think twice before adding white space to this option. Although a
4814 space may appear inside a file name, the effect will be that Vim
4815 doesn't know where a file name starts or ends when doing completion.
4816 It most likely works better without a space in 'isfname'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004817
4818 Note that on systems using a backslash as path separator, Vim tries to
4819 do its best to make it work as you would expect. That is a bit
4820 tricky, since Vi originally used the backslash to escape special
4821 characters. Vim will not remove a backslash in front of a normal file
4822 name character on these systems, but it will on Unix and alikes. The
4823 '&' and '^' are not included by default, because these are special for
4824 cmd.exe.
4825
4826 The format of this option is a list of parts, separated with commas.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004827 Each part can be a single character number or a range. A range is two
4828 character numbers with '-' in between. A character number can be a
Bram Moolenaar071d4272004-06-13 20:20:40 +00004829 decimal number between 0 and 255 or the ASCII character itself (does
4830 not work for digits). Example:
4831 "_,-,128-140,#-43" (include '_' and '-' and the range
4832 128 to 140 and '#' to 43)
4833 If a part starts with '^', the following character number or range
4834 will be excluded from the option. The option is interpreted from left
4835 to right. Put the excluded character after the range where it is
4836 included. To include '^' itself use it as the last character of the
4837 option or the end of a range. Example:
4838 "^a-z,#,^" (exclude 'a' to 'z', include '#' and '^')
4839 If the character is '@', all characters where isalpha() returns TRUE
4840 are included. Normally these are the characters a to z and A to Z,
4841 plus accented characters. To include '@' itself use "@-@". Examples:
4842 "@,^a-z" All alphabetic characters, excluding lower
Bram Moolenaar446cb832008-06-24 21:56:24 +00004843 case ASCII letters.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004844 "a-z,A-Z,@-@" All letters plus the '@' character.
4845 A comma can be included by using it where a character number is
4846 expected. Example:
4847 "48-57,,,_" Digits, comma and underscore.
4848 A comma can be excluded by prepending a '^'. Example:
4849 " -~,^,,9" All characters from space to '~', excluding
4850 comma, plus <Tab>.
4851 See |option-backslash| about including spaces and backslashes.
4852
4853 *'isident'* *'isi'*
Bram Moolenaar6f345a12019-12-17 21:27:18 +01004854'isident' 'isi' string (default for Win32:
Bram Moolenaar071d4272004-06-13 20:20:40 +00004855 "@,48-57,_,128-167,224-235"
4856 otherwise: "@,48-57,_,192-255")
4857 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004858 The characters given by this option are included in identifiers.
4859 Identifiers are used in recognizing environment variables and after a
4860 match of the 'define' option. It is also used for "\i" in a
Bram Moolenaar582fd852005-03-28 20:58:01 +00004861 |pattern|. See 'isfname' for a description of the format of this
Bram Moolenaar95bafa22018-10-02 13:26:25 +02004862 option. For '@' only characters up to 255 are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004863 Careful: If you change this option, it might break expanding
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004864 environment variables. E.g., when '/' is included and Vim tries to
Bram Moolenaar071d4272004-06-13 20:20:40 +00004865 expand "$HOME/.viminfo". Maybe you should change 'iskeyword' instead.
4866
4867 *'iskeyword'* *'isk'*
Bram Moolenaar6f345a12019-12-17 21:27:18 +01004868'iskeyword' 'isk' string (Vim default for Win32:
Bram Moolenaar071d4272004-06-13 20:20:40 +00004869 "@,48-57,_,128-167,224-235"
4870 otherwise: "@,48-57,_,192-255"
4871 Vi default: "@,48-57,_")
4872 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00004873 Keywords are used in searching and recognizing with many commands:
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004874 "w", "*", "[i", etc. It is also used for "\k" in a |pattern|. See
Bram Moolenaar95bafa22018-10-02 13:26:25 +02004875 'isfname' for a description of the format of this option. For '@'
Bram Moolenaar4c295022021-05-02 17:19:11 +02004876 characters above 255 check the "word" character class (any character
4877 that is not white space or punctuation).
Bram Moolenaar95bafa22018-10-02 13:26:25 +02004878 For C programs you could use "a-z,A-Z,48-57,_,.,-,>".
Bram Moolenaar071d4272004-06-13 20:20:40 +00004879 For a help file it is set to all non-blank printable characters except
4880 '*', '"' and '|' (so that CTRL-] on a command finds the help for that
4881 command).
4882 When the 'lisp' option is on the '-' character is always included.
Bram Moolenaarb8060fe2016-01-19 22:29:28 +01004883 This option also influences syntax highlighting, unless the syntax
4884 uses |:syn-iskeyword|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004885 NOTE: This option is set to the Vi default value when 'compatible' is
4886 set and to the Vim default value when 'compatible' is reset.
4887
4888 *'isprint'* *'isp'*
Bram Moolenaar3d1cde82020-08-15 18:55:18 +02004889'isprint' 'isp' string (default for Win32 and macOS:
Bram Moolenaar071d4272004-06-13 20:20:40 +00004890 "@,~-255"; otherwise: "@,161-255")
4891 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004892 The characters given by this option are displayed directly on the
4893 screen. It is also used for "\p" in a |pattern|. The characters from
4894 space (ASCII 32) to '~' (ASCII 126) are always displayed directly,
4895 even when they are not included in 'isprint' or excluded. See
4896 'isfname' for a description of the format of this option.
4897
4898 Non-printable characters are displayed with two characters:
4899 0 - 31 "^@" - "^_"
4900 32 - 126 always single characters
4901 127 "^?"
4902 128 - 159 "~@" - "~_"
4903 160 - 254 "| " - "|~"
4904 255 "~?"
4905 When 'encoding' is a Unicode one, illegal bytes from 128 to 255 are
4906 displayed as <xx>, with the hexadecimal value of the byte.
4907 When 'display' contains "uhex" all unprintable characters are
4908 displayed as <xx>.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004909 The SpecialKey highlighting will be used for unprintable characters.
4910 |hl-SpecialKey|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004911
4912 Multi-byte characters 256 and above are always included, only the
4913 characters up to 255 are specified with this option. When a character
4914 is printable but it is not available in the current font, a
4915 replacement character will be shown.
4916 Unprintable and zero-width Unicode characters are displayed as <xxxx>.
4917 There is no option to specify these characters.
4918
4919 *'joinspaces'* *'js'* *'nojoinspaces'* *'nojs'*
4920'joinspaces' 'js' boolean (default on)
4921 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004922 Insert two spaces after a '.', '?' and '!' with a join command.
4923 When 'cpoptions' includes the 'j' flag, only do this after a '.'.
4924 Otherwise only one space is inserted.
4925 NOTE: This option is set when 'compatible' is set.
4926
Yegappan Lakshmanan87018252023-09-20 20:20:04 +02004927 *'jumpoptions'* *'jop'*
4928'jumpoptions' 'jop' string (default "")
4929 global
4930 List of words that change the behavior of the |jumplist|.
4931 stack Make the jumplist behave like the tagstack.
4932 Relative location of entries in the jumplist is
4933 preserved at the cost of discarding subsequent entries
4934 when navigating backwards in the jumplist and then
4935 jumping to a location. |jumplist-stack|
4936
Bram Moolenaar071d4272004-06-13 20:20:40 +00004937 *'key'*
4938'key' string (default "")
4939 local to buffer
Bram Moolenaar996343d2010-07-04 22:20:21 +02004940 {only available when compiled with the |+cryptv|
4941 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00004942 The key that is used for encrypting and decrypting the current buffer.
Bram Moolenaar40e6a712010-05-16 22:32:54 +02004943 See |encryption| and 'cryptmethod'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004944 Careful: Do not set the key value by hand, someone might see the typed
4945 key. Use the |:X| command. But you can make 'key' empty: >
4946 :set key=
4947< It is not possible to get the value of this option with ":set key" or
4948 "echo &key". This is to avoid showing it to someone who shouldn't
4949 know. It also means you cannot see it yourself once you have set it,
4950 be careful not to make a typing error!
Yee Cheng Chin6ee7b522023-10-01 09:13:22 +02004951 You also cannot use |:set-=|, |:set+=|, |:set^=| on this option to
4952 prevent an attacker from guessing substrings in your key.
Bram Moolenaard58e9292011-02-09 17:07:58 +01004953 You can use "&key" in an expression to detect whether encryption is
4954 enabled. When 'key' is set it returns "*****" (five stars).
Bram Moolenaar071d4272004-06-13 20:20:40 +00004955
4956 *'keymap'* *'kmp'* *E544*
4957'keymap' 'kmp' string (default "")
4958 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00004959 {only available when compiled with the |+keymap|
4960 feature}
4961 Name of a keyboard mapping. See |mbyte-keymap|.
4962 Setting this option to a valid keymap name has the side effect of
4963 setting 'iminsert' to one, so that the keymap becomes effective.
4964 'imsearch' is also set to one, unless it was -1
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00004965 Only normal file name characters can be used, "/\*?[|<>" are illegal.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004966
4967 *'keymodel'* *'km'*
4968'keymodel' 'km' string (default "")
4969 global
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01004970 List of comma-separated words, which enable special things that keys
Bram Moolenaar071d4272004-06-13 20:20:40 +00004971 can do. These values can be used:
4972 startsel Using a shifted special key starts selection (either
4973 Select mode or Visual mode, depending on "key" being
4974 present in 'selectmode').
4975 stopsel Using a not-shifted special key stops selection.
4976 Special keys in this context are the cursor keys, <End>, <Home>,
4977 <PageUp> and <PageDown>.
4978 The 'keymodel' option is set by the |:behave| command.
4979
Bram Moolenaar63a2e362022-11-23 20:20:18 +00004980 *'keyprotocol'* *'kpc'*
4981'keyprotocol' 'kpc' string (default: see below)
4982 global
4983 Specifies what keyboard protocol to use depending on the value of
4984 'term'. The supported keyboard protocols names are:
4985 none whatever the terminal uses
4986 mok2 modifyOtherKeys level 2, as supported by xterm
4987 kitty Kitty keyboard protocol, as supported by Kitty
4988
Bram Moolenaara87749e2022-11-30 10:23:17 +00004989 The option value is a list of comma separated items. Each item has
Bram Moolenaar63a2e362022-11-23 20:20:18 +00004990 a pattern that is matched against the 'term' option, a colon and the
4991 protocol name to be used. To illustrate this, the default value would
4992 be set with: >
4993 set keyprotocol=kitty:kitty,foot:kitty,wezterm:kitty,xterm:mok2
4994
4995< This means that when 'term' contains "kitty, "foot" or "wezterm"
4996 somewhere then the "kitty" protocol is used. When 'term' contains
Bram Moolenaar938ae282023-02-20 20:44:55 +00004997 "xterm" somewhere, then the "mok2" protocol is used.
Bram Moolenaar63a2e362022-11-23 20:20:18 +00004998
4999 The first match is used, thus if you want to have "kitty" use the
5000 kitty protocol, but "badkitty" not, then you should match "badkitty"
5001 first and use the "none" value: >
5002 set keyprotocol=badkitty:none,kitty:kitty
5003<
5004 The option is used after 'term' has been changed. First the termcap
5005 entries are set, possibly using the builtin list, see |builtin-terms|.
5006 Then this option is inspected and if there is a match and a protocol
5007 is specified the following happens:
5008 none Nothing, the regular t_TE and t_TI values remain
5009
5010 mok2 The t_TE value is changed to:
5011 CSI >4;m disables modifyOtherKeys
5012 The t_TI value is changed to:
5013 CSI >4;2m enables modifyOtherKeys
Bram Moolenaara87749e2022-11-30 10:23:17 +00005014 CSI ?4m request the modifyOtherKeys state
Bram Moolenaar63a2e362022-11-23 20:20:18 +00005015
5016 kitty The t_TE value is changed to:
5017 CSI >4;m disables modifyOtherKeys
Bram Moolenaara87749e2022-11-30 10:23:17 +00005018 CSI =0;1u disables the kitty keyboard protocol
Bram Moolenaar63a2e362022-11-23 20:20:18 +00005019 The t_TI value is changed to:
Bram Moolenaara87749e2022-11-30 10:23:17 +00005020 CSI =1;1u enables the kitty keyboard protocol
Bram Moolenaar63a2e362022-11-23 20:20:18 +00005021 CSI ?u request kitty keyboard protocol state
5022 CSI >c request the termresponse
5023
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00005024 If you notice problems, such as characters being displayed that
5025 disappear after `CTRL-L`, you might want to try making this option
5026 empty. Then set the 'term' option to have it take effect: >
5027 set keyprotocol=
5028 let &term = &term
Bram Moolenaarbe4e0162023-02-02 13:59:48 +00005029<
Bram Moolenaar63a2e362022-11-23 20:20:18 +00005030
Bram Moolenaar071d4272004-06-13 20:20:40 +00005031 *'keywordprg'* *'kp'*
5032'keywordprg' 'kp' string (default "man" or "man -s", DOS: ":help",
Bram Moolenaar2ff8b642016-05-24 10:46:45 +02005033 VMS: "help")
Bram Moolenaar071d4272004-06-13 20:20:40 +00005034 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00005035 Program to use for the |K| command. Environment variables are
5036 expanded |:set_env|. ":help" may be used to access the Vim internal
5037 help. (Note that previously setting the global option to the empty
5038 value did this, which is now deprecated.)
Bram Moolenaar2ff8b642016-05-24 10:46:45 +02005039 When the first character is ":", the command is invoked as a Vim
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01005040 Ex command with [count] added as an argument if it is not zero.
Bram Moolenaar2ff8b642016-05-24 10:46:45 +02005041 When "man", "man -s" or an Ex command is used, Vim will automatically
5042 translate a count for the "K" command and pass it as the first
5043 argument. For "man -s" the "-s" is removed when there is no count.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005044 See |option-backslash| about including spaces and backslashes.
5045 Example: >
5046 :set keywordprg=man\ -s
5047< This option cannot be set from a |modeline| or in the |sandbox|, for
5048 security reasons.
5049
5050 *'langmap'* *'lmap'* *E357* *E358*
5051'langmap' 'lmap' string (default "")
5052 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005053 {only available when compiled with the |+langmap|
5054 feature}
5055 This option allows switching your keyboard into a special language
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00005056 mode. When you are typing text in Insert mode the characters are
Bram Moolenaarfa735342016-01-03 22:14:44 +01005057 inserted directly. When in Normal mode the 'langmap' option takes
Bram Moolenaar071d4272004-06-13 20:20:40 +00005058 care of translating these special characters to the original meaning
5059 of the key. This means you don't have to change the keyboard mode to
5060 be able to execute Normal mode commands.
5061 This is the opposite of the 'keymap' option, where characters are
5062 mapped in Insert mode.
Bram Moolenaarb17893a2020-03-14 08:19:51 +01005063 Also consider setting 'langremap' to off, to prevent 'langmap' from
5064 applying to characters resulting from a mapping.
Bram Moolenaare968e362014-05-13 20:23:24 +02005065 This option cannot be set from a |modeline| or in the |sandbox|, for
5066 security reasons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005067
Bram Moolenaarfd2ac762006-03-01 22:09:21 +00005068 Example (for Greek, in UTF-8): *greek* >
5069 :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 +00005070< Example (exchanges meaning of z and y for commands): >
5071 :set langmap=zy,yz,ZY,YZ
5072<
5073 The 'langmap' option is a list of parts, separated with commas. Each
5074 part can be in one of two forms:
5075 1. A list of pairs. Each pair is a "from" character immediately
5076 followed by the "to" character. Examples: "aA", "aAbBcC".
5077 2. A list of "from" characters, a semi-colon and a list of "to"
5078 characters. Example: "abc;ABC"
5079 Example: "aA,fgh;FGH,cCdDeE"
5080 Special characters need to be preceded with a backslash. These are
Bram Moolenaar4f4d51a2020-10-11 13:57:40 +02005081 ";", ',', '"', '|' and backslash itself.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005082
5083 This will allow you to activate vim actions without having to switch
5084 back and forth between the languages. Your language characters will
5085 be understood as normal vim English characters (according to the
5086 langmap mappings) in the following cases:
5087 o Normal/Visual mode (commands, buffer/register names, user mappings)
5088 o Insert/Replace Mode: Register names after CTRL-R
5089 o Insert/Replace Mode: Mappings
5090 Characters entered in Command-line mode will NOT be affected by
5091 this option. Note that this option can be changed at any time
5092 allowing to switch between mappings for different languages/encodings.
5093 Use a mapping to avoid having to type it each time!
5094
5095 *'langmenu'* *'lm'*
5096'langmenu' 'lm' string (default "")
5097 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005098 {only available when compiled with the |+menu| and
5099 |+multi_lang| features}
5100 Language to use for menu translation. Tells which file is loaded
5101 from the "lang" directory in 'runtimepath': >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005102 "lang/menu_" .. &langmenu .. ".vim"
Bram Moolenaar071d4272004-06-13 20:20:40 +00005103< (without the spaces). For example, to always use the Dutch menus, no
5104 matter what $LANG is set to: >
5105 :set langmenu=nl_NL.ISO_8859-1
5106< When 'langmenu' is empty, |v:lang| is used.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00005107 Only normal file name characters can be used, "/\*?[|<>" are illegal.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005108 If your $LANG is set to a non-English language but you do want to use
5109 the English menus: >
5110 :set langmenu=none
5111< This option must be set before loading menus, switching on filetype
5112 detection or syntax highlighting. Once the menus are defined setting
5113 this option has no effect. But you could do this: >
5114 :source $VIMRUNTIME/delmenu.vim
5115 :set langmenu=de_DE.ISO_8859-1
5116 :source $VIMRUNTIME/menu.vim
5117< Warning: This deletes all menus that you defined yourself!
5118
Bram Moolenaard94464e2015-11-02 15:28:18 +01005119 *'langnoremap'* *'lnr'* *'nolangnoremap'* *'nolnr'*
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +02005120'langnoremap' 'lnr' boolean (default off, set in |defaults.vim|)
Bram Moolenaar4391cf92014-11-05 17:44:52 +01005121 global
Bram Moolenaar4391cf92014-11-05 17:44:52 +01005122 {only available when compiled with the |+langmap|
5123 feature}
Bram Moolenaare4a3bcf2016-08-26 19:52:37 +02005124 This is just like 'langremap' but with the value inverted. It only
5125 exists for backwards compatibility. When setting 'langremap' then
5126 'langnoremap' is set to the inverted value, and the other way around.
5127
5128 *'langremap'* *'lrm'* *'nolangremap'* *'nolrm'*
Bram Moolenaarb17893a2020-03-14 08:19:51 +01005129'langremap' 'lrm' boolean (default on, set to off in |defaults.vim|)
Bram Moolenaare4a3bcf2016-08-26 19:52:37 +02005130 global
Bram Moolenaare4a3bcf2016-08-26 19:52:37 +02005131 {only available when compiled with the |+langmap|
5132 feature}
5133 When off, setting 'langmap' does not apply to characters resulting from
Bram Moolenaar4391cf92014-11-05 17:44:52 +01005134 a mapping. This basically means, if you noticed that setting
Bram Moolenaare4a3bcf2016-08-26 19:52:37 +02005135 'langmap' disables some of your mappings, try resetting this option.
5136 This option defaults to on for backwards compatibility. Set it off if
Bram Moolenaar4391cf92014-11-05 17:44:52 +01005137 that works for you to avoid mappings to break.
5138
Bram Moolenaar071d4272004-06-13 20:20:40 +00005139 *'laststatus'* *'ls'*
5140'laststatus' 'ls' number (default 1)
5141 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005142 The value of this option influences when the last window will have a
5143 status line:
5144 0: never
5145 1: only if there are at least two windows
5146 2: always
5147 The screen looks nicer with a status line if you have several
5148 windows, but it takes another screen line. |status-line|
5149
5150 *'lazyredraw'* *'lz'* *'nolazyredraw'* *'nolz'*
5151'lazyredraw' 'lz' boolean (default off)
5152 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005153 When this option is set, the screen will not be redrawn while
5154 executing macros, registers and other commands that have not been
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00005155 typed. Also, updating the window title is postponed. To force an
Bram Moolenaar071d4272004-06-13 20:20:40 +00005156 update use |:redraw|.
Bram Moolenaara57b5532022-06-24 11:48:03 +01005157 This may occasionally cause display errors. It is only meant to be set
5158 temporarily when performing an operation where redrawing may cause
Bram Moolenaar8cc5b552022-06-23 13:04:20 +01005159 flickering or cause a slow down.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005160
5161 *'linebreak'* *'lbr'* *'nolinebreak'* *'nolbr'*
5162'linebreak' 'lbr' boolean (default off)
5163 local to window
Bram Moolenaardb84e452010-08-15 13:50:43 +02005164 {not available when compiled without the |+linebreak|
Bram Moolenaar071d4272004-06-13 20:20:40 +00005165 feature}
Bram Moolenaar946e27a2014-06-25 18:50:27 +02005166 If on, Vim will wrap long lines at a character in 'breakat' rather
Bram Moolenaar071d4272004-06-13 20:20:40 +00005167 than at the last character that fits on the screen. Unlike
5168 'wrapmargin' and 'textwidth', this does not insert <EOL>s in the file,
Bram Moolenaar946e27a2014-06-25 18:50:27 +02005169 it only affects the way the file is displayed, not its contents.
5170 If 'breakindent' is set, line is visually indented. Then, the value
5171 of 'showbreak' is used to put in front of wrapped lines. This option
Bram Moolenaar86b17e92014-07-02 20:00:47 +02005172 is not used when the 'wrap' option is off.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005173 Note that <Tab> characters after an <EOL> are mostly not displayed
5174 with the right amount of white space.
5175
5176 *'lines'* *E593*
5177'lines' number (default 24 or terminal height)
5178 global
5179 Number of lines of the Vim window.
5180 Normally you don't need to set this. It is done automatically by the
Bram Moolenaar7c626922005-02-07 22:01:03 +00005181 terminal initialization code. Also see |posix-screen-size|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005182 When Vim is running in the GUI or in a resizable window, setting this
5183 option will cause the window size to be changed. When you only want
5184 to use the size for the GUI, put the command in your |gvimrc| file.
5185 Vim limits the number of lines to what fits on the screen. You can
5186 use this command to get the tallest window possible: >
5187 :set lines=999
Bram Moolenaarf4d11452005-12-02 00:46:37 +00005188< Minimum value is 2, maximum value is 1000.
Bram Moolenaardc1f1642016-08-16 18:33:43 +02005189 If you get fewer lines than expected, check the 'guiheadroom' option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005190 When you set this option and Vim is unable to change the physical
5191 number of lines of the display, the display may be messed up.
5192
5193 *'linespace'* *'lsp'*
5194'linespace' 'lsp' number (default 0, 1 for Win32 GUI)
5195 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005196 {only in the GUI}
5197 Number of pixel lines inserted between characters. Useful if the font
5198 uses the full character cell height, making lines touch each other.
5199 When non-zero there is room for underlining.
Bram Moolenaarbc7aa852005-03-06 23:38:09 +00005200 With some fonts there can be too much room between lines (to have
5201 space for ascents and descents). Then it makes sense to set
5202 'linespace' to a negative value. This may cause display problems
5203 though!
Bram Moolenaar071d4272004-06-13 20:20:40 +00005204
5205 *'lisp'* *'nolisp'*
5206'lisp' boolean (default off)
5207 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00005208 Lisp mode: When <Enter> is typed in insert mode set the indent for
5209 the next line to Lisp standards (well, sort of). Also happens with
5210 "cc" or "S". 'autoindent' must also be on for this to work. The 'p'
5211 flag in 'cpoptions' changes the method of indenting: Vi compatible or
5212 better. Also see 'lispwords'.
5213 The '-' character is included in keyword characters. Redefines the
5214 "=" operator to use this same indentation algorithm rather than
5215 calling an external program if 'equalprg' is empty.
5216 This option is not used when 'paste' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005217
Bram Moolenaar49846fb2022-10-15 16:05:33 +01005218 *'lispoptions'* *'lop'*
5219'lispoptions' 'lop' string (default "")
5220 local to buffer
5221 Comma-separated list of items that influence the Lisp indenting when
5222 enabled with the |'lisp'| option. Currently only one item is
5223 supported:
5224 expr:1 use 'indentexpr' for Lisp indenting when it is set
5225 expr:0 do not use 'indentexpr' for Lisp indenting (default)
5226 Note that when using 'indentexpr' the `=` operator indents all the
5227 lines, otherwise the first line is not indented (Vi-compatible).
5228
Bram Moolenaar071d4272004-06-13 20:20:40 +00005229 *'lispwords'* *'lw'*
5230'lispwords' 'lw' string (default is very long)
Bram Moolenaaraf6c1312014-03-12 18:55:58 +01005231 global or local to buffer |global-local|
Bram Moolenaar48c3f4e2022-08-08 15:42:38 +01005232 Comma-separated list of words that influence the Lisp indenting when
5233 enabled with the |'lisp'| option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005234
5235 *'list'* *'nolist'*
5236'list' boolean (default off)
5237 local to window
Bram Moolenaar113cb512021-11-07 20:27:04 +00005238 List mode: By default show tabs as CTRL-I is displayed, display $
5239 after end of line. Useful to see the difference between tabs and
5240 spaces and for trailing blanks. Further changed by the 'listchars'
5241 option.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005242
5243 The cursor is displayed at the start of the space a Tab character
5244 occupies, not at the end as usual in Normal mode. To get this cursor
5245 position while displaying Tabs with spaces, use: >
Bram Moolenaardd007ed2013-07-09 15:44:17 +02005246 :set list lcs=tab:\ \
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005247<
5248 Note that list mode will also affect formatting (set with 'textwidth'
5249 or 'wrapmargin') when 'cpoptions' includes 'L'. See 'listchars' for
Bram Moolenaar071d4272004-06-13 20:20:40 +00005250 changing the way tabs are displayed.
5251
5252 *'listchars'* *'lcs'*
5253'listchars' 'lcs' string (default "eol:$")
Bram Moolenaareed9d462021-02-15 20:38:25 +01005254 global or local to window |global-local|
Bram Moolenaarf9d5ca12010-08-01 16:13:51 +02005255 Strings to use in 'list' mode and for the |:list| command. It is a
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01005256 comma-separated list of string settings.
Bram Moolenaar79278362015-04-21 18:33:48 +02005257 *lcs-eol*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005258 eol:c Character to show at the end of each line. When
5259 omitted, there is no extra character at the end of the
5260 line.
Bram Moolenaar79278362015-04-21 18:33:48 +02005261 *lcs-tab*
Bram Moolenaar83a52172019-01-16 22:41:54 +01005262 tab:xy[z] Two or three characters to be used to show a tab.
5263 The third character is optional.
5264
5265 tab:xy The 'x' is always used, then 'y' as many times as will
5266 fit. Thus "tab:>-" displays:
5267 >
5268 >-
5269 >--
5270 etc.
5271
5272 tab:xyz The 'z' is always used, then 'x' is prepended, and
5273 then 'y' is used as many times as will fit. Thus
5274 "tab:<->" displays:
5275 >
5276 <>
5277 <->
5278 <-->
5279 etc.
5280
5281 When "tab:" is omitted, a tab is shown as ^I.
Bram Moolenaar79278362015-04-21 18:33:48 +02005282 *lcs-space*
5283 space:c Character to show for a space. When omitted, spaces
5284 are left blank.
zeertzjqf14b8ba2021-09-10 16:58:30 +02005285 *lcs-multispace*
5286 multispace:c...
Bram Moolenaarbe4e0162023-02-02 13:59:48 +00005287 One or more characters to use cyclically to show for
5288 multiple consecutive spaces. Overrides the "space"
zeertzjqf14b8ba2021-09-10 16:58:30 +02005289 setting, except for single spaces. When omitted, the
5290 "space" setting is used. For example,
5291 `:set listchars=multispace:---+` shows ten consecutive
5292 spaces as:
Bram Moolenaaraca12fd2022-06-07 10:16:15 +01005293 ---+---+-- ~
Bram Moolenaar91478ae2021-02-03 15:58:13 +01005294 *lcs-lead*
5295 lead:c Character to show for leading spaces. When omitted,
zeertzjqf14b8ba2021-09-10 16:58:30 +02005296 leading spaces are blank. Overrides the "space" and
5297 "multispace" settings for leading spaces. You can
5298 combine it with "tab:", for example: >
Bram Moolenaar942db232021-02-13 18:14:48 +01005299 :set listchars+=tab:>-,lead:.
Bram Moolenaaraca12fd2022-06-07 10:16:15 +01005300< *lcs-leadmultispace*
5301 leadmultispace:c...
Bram Moolenaar069a7d52022-06-27 22:16:08 +01005302 Like the |lcs-multispace| value, but for leading
5303 spaces only. Also overrides |lcs-lead| for leading
5304 multiple spaces.
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01005305 `:set listchars=leadmultispace:---+` shows ten
5306 consecutive leading spaces as:
Bram Moolenaaraca12fd2022-06-07 10:16:15 +01005307 ---+---+--XXX ~
5308 Where "XXX" denotes the first non-blank characters in
5309 the line.
5310 *lcs-trail*
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00005311 trail:c Character to show for trailing spaces. When omitted,
zeertzjqf14b8ba2021-09-10 16:58:30 +02005312 trailing spaces are blank. Overrides the "space" and
5313 "multispace" settings for trailing spaces.
Bram Moolenaar79278362015-04-21 18:33:48 +02005314 *lcs-extends*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005315 extends:c Character to show in the last column, when 'wrap' is
5316 off and the line continues beyond the right of the
5317 screen.
Bram Moolenaar79278362015-04-21 18:33:48 +02005318 *lcs-precedes*
Bram Moolenaarbffba7f2019-09-20 17:00:17 +02005319 precedes:c Character to show in the first visible column of the
5320 physical line, when there is text preceding the
5321 character visible in the first column.
Bram Moolenaar79278362015-04-21 18:33:48 +02005322 *lcs-conceal*
Bram Moolenaar860cae12010-06-05 23:22:07 +02005323 conceal:c Character to show in place of concealed text, when
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02005324 'conceallevel' is set to 1.
Bram Moolenaar79278362015-04-21 18:33:48 +02005325 *lcs-nbsp*
Bram Moolenaar73284b92015-05-04 17:28:22 +02005326 nbsp:c Character to show for a non-breakable space character
5327 (0xA0 (160 decimal) and U+202F). Left blank when
5328 omitted.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005329
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00005330 The characters ':' and ',' should not be used. UTF-8 characters can
Bram Moolenaar071d4272004-06-13 20:20:40 +00005331 be used when 'encoding' is "utf-8", otherwise only printable
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005332 characters are allowed. All characters must be single width.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005333
Bram Moolenaar93ff6722021-10-16 17:51:40 +01005334 Each character can be specified as hex: >
5335 set listchars=eol:\\x24
5336 set listchars=eol:\\u21b5
5337 set listchars=eol:\\U000021b5
5338< Note that a double backslash is used. The number of hex characters
5339 must be exactly 2 for \\x, 4 for \\u and 8 for \\U.
5340
Bram Moolenaar071d4272004-06-13 20:20:40 +00005341 Examples: >
5342 :set lcs=tab:>-,trail:-
Bram Moolenaarcfbc5ee2004-07-02 15:38:35 +00005343 :set lcs=tab:>-,eol:<,nbsp:%
Bram Moolenaar071d4272004-06-13 20:20:40 +00005344 :set lcs=extends:>,precedes:<
5345< The "NonText" highlighting will be used for "eol", "extends" and
Bram Moolenaar34cc7d82021-09-21 20:09:51 +02005346 "precedes". "SpecialKey" will be used for "tab", "nbsp", "space",
5347 "multispace", "lead" and "trail".
Bram Moolenaar02467872007-05-06 13:22:01 +00005348 |hl-NonText| |hl-SpecialKey|
Bram Moolenaar071d4272004-06-13 20:20:40 +00005349
5350 *'lpl'* *'nolpl'* *'loadplugins'* *'noloadplugins'*
5351'loadplugins' 'lpl' boolean (default on)
5352 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005353 When on the plugin scripts are loaded when starting up |load-plugins|.
5354 This option can be reset in your |vimrc| file to disable the loading
5355 of plugins.
Bram Moolenaarc4da1132017-07-15 19:39:43 +02005356 Note that using the "-u NONE", "-u DEFAULTS" and "--noplugin" command
5357 line arguments reset this option. See |-u| and |--noplugin|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005358
Bram Moolenaard94464e2015-11-02 15:28:18 +01005359 *'luadll'*
Bram Moolenaar3848e002016-03-19 18:42:29 +01005360'luadll' string (default depends on the build)
Bram Moolenaard94464e2015-11-02 15:28:18 +01005361 global
Bram Moolenaard94464e2015-11-02 15:28:18 +01005362 {only available when compiled with the |+lua/dyn|
5363 feature}
Bram Moolenaar25e4fcd2016-01-09 14:57:47 +01005364 Specifies the name of the Lua shared library. The default is
5365 DYNAMIC_LUA_DLL, which was specified at compile time.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02005366 Environment variables are expanded |:set_env|.
Bram Moolenaard94464e2015-11-02 15:28:18 +01005367 This option cannot be set from a |modeline| or in the |sandbox|, for
5368 security reasons.
5369
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00005370 *'macatsui'* *'nomacatsui'*
5371'macatsui' boolean (default on)
5372 global
Bram Moolenaar3d1cde82020-08-15 18:55:18 +02005373 {not supported}
5374 No longer supported, as the Mac OS X GUI code was removed.
Bram Moolenaar02467872007-05-06 13:22:01 +00005375
Bram Moolenaar071d4272004-06-13 20:20:40 +00005376 *'magic'* *'nomagic'*
5377'magic' boolean (default on)
5378 global
5379 Changes the special characters that can be used in search patterns.
5380 See |pattern|.
Bram Moolenaar64d8e252016-09-06 22:12:34 +02005381 WARNING: Switching this option off most likely breaks plugins! That
5382 is because many patterns assume it's on and will fail when it's off.
5383 Only switch it off when working with old Vi scripts. In any other
5384 situation write patterns that work when 'magic' is on. Include "\M"
5385 when you want to |/\M|.
Bram Moolenaar4072ba52020-12-23 13:56:35 +01005386 In |Vim9| script the value of 'magic' is ignored, patterns behave like
5387 it is always set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005388
5389 *'makeef'* *'mef'*
5390'makeef' 'mef' string (default: "")
5391 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005392 {not available when compiled without the |+quickfix|
5393 feature}
5394 Name of the errorfile for the |:make| command (see |:make_makeprg|)
5395 and the |:grep| command.
5396 When it is empty, an internally generated temp file will be used.
5397 When "##" is included, it is replaced by a number to make the name
5398 unique. This makes sure that the ":make" command doesn't overwrite an
5399 existing file.
5400 NOT used for the ":cf" command. See 'errorfile' for that.
5401 Environment variables are expanded |:set_env|.
5402 See |option-backslash| about including spaces and backslashes.
5403 This option cannot be set from a |modeline| or in the |sandbox|, for
5404 security reasons.
5405
Bram Moolenaar2c7292d2017-03-05 17:43:31 +01005406 *'makeencoding'* *'menc'*
5407'makeencoding' 'menc' string (default "")
5408 global or local to buffer |global-local|
Bram Moolenaar2c7292d2017-03-05 17:43:31 +01005409 Encoding used for reading the output of external commands. When empty,
5410 encoding is not converted.
5411 This is used for `:make`, `:lmake`, `:grep`, `:lgrep`, `:grepadd`,
5412 `:lgrepadd`, `:cfile`, `:cgetfile`, `:caddfile`, `:lfile`, `:lgetfile`,
5413 and `:laddfile`.
5414
5415 This would be mostly useful when you use MS-Windows and set 'encoding'
5416 to "utf-8". If |+iconv| is enabled and GNU libiconv is used, setting
5417 'makeencoding' to "char" has the same effect as setting to the system
5418 locale encoding. Example: >
5419 :set encoding=utf-8
5420 :set makeencoding=char " system locale is used
5421<
Bram Moolenaar071d4272004-06-13 20:20:40 +00005422 *'makeprg'* *'mp'*
5423'makeprg' 'mp' string (default "make", VMS: "MMS")
5424 global or local to buffer |global-local|
Bram Moolenaar02467872007-05-06 13:22:01 +00005425 Program to use for the ":make" command. See |:make_makeprg|.
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01005426 This option may contain '%' and '#' characters (see |:_%| and |:_#|),
5427 which are expanded to the current and alternate file name. Use |::S|
Bram Moolenaar26df0922014-02-23 23:39:13 +01005428 to escape file names in case they contain special characters.
Bram Moolenaar02467872007-05-06 13:22:01 +00005429 Environment variables are expanded |:set_env|. See |option-backslash|
5430 about including spaces and backslashes.
5431 Note that a '|' must be escaped twice: once for ":set" and once for
5432 the interpretation of a command. When you use a filter called
5433 "myfilter" do it like this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005434 :set makeprg=gmake\ \\\|\ myfilter
5435< The placeholder "$*" can be given (even multiple times) to specify
5436 where the arguments will be included, for example: >
5437 :set makeprg=latex\ \\\\nonstopmode\ \\\\input\\{$*}
5438< This option cannot be set from a |modeline| or in the |sandbox|, for
5439 security reasons.
5440
5441 *'matchpairs'* *'mps'*
5442'matchpairs' 'mps' string (default "(:),{:},[:]")
5443 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00005444 Characters that form pairs. The |%| command jumps from one to the
Bram Moolenaara3e6bc92013-01-30 14:18:00 +01005445 other.
5446 Only character pairs are allowed that are different, thus you cannot
5447 jump between two double quotes.
5448 The characters must be separated by a colon.
Bram Moolenaar02467872007-05-06 13:22:01 +00005449 The pairs must be separated by a comma. Example for including '<' and
Bram Moolenaar130cbfc2021-04-07 21:07:20 +02005450 '>' (for HTML): >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005451 :set mps+=<:>
5452
5453< A more exotic example, to jump between the '=' and ';' in an
5454 assignment, useful for languages like C and Java: >
5455 :au FileType c,cpp,java set mps+==:;
5456
5457< For a more advanced way of using "%", see the matchit.vim plugin in
Bram Moolenaar01164a62017-11-02 22:58:42 +01005458 the $VIMRUNTIME/pack/dist/opt/matchit directory. |add-local-help|
Bram Moolenaar071d4272004-06-13 20:20:40 +00005459
5460 *'matchtime'* *'mat'*
5461'matchtime' 'mat' number (default 5)
5462 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005463 Tenths of a second to show the matching paren, when 'showmatch' is
5464 set. Note that this is not in milliseconds, like other options that
5465 set a time. This is to be compatible with Nvi.
5466
Bram Moolenaar362e1a32006-03-06 23:29:24 +00005467 *'maxcombine'* *'mco'*
5468'maxcombine' 'mco' number (default 2)
5469 global
Bram Moolenaar362e1a32006-03-06 23:29:24 +00005470 The maximum number of combining characters supported for displaying.
5471 Only used when 'encoding' is "utf-8".
5472 The default is OK for most languages. Hebrew may require 4.
5473 Maximum value is 6.
5474 Even when this option is set to 2 you can still edit text with more
5475 combining characters, you just can't see them. Use |g8| or |ga|.
5476 See |mbyte-combining|.
5477
Bram Moolenaar071d4272004-06-13 20:20:40 +00005478 *'maxfuncdepth'* *'mfd'*
5479'maxfuncdepth' 'mfd' number (default 100)
5480 global
Bram Moolenaardb84e452010-08-15 13:50:43 +02005481 {not available when compiled without the |+eval|
Bram Moolenaar02467872007-05-06 13:22:01 +00005482 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00005483 Maximum depth of function calls for user functions. This normally
5484 catches endless recursion. When using a recursive function with
5485 more depth, set 'maxfuncdepth' to a bigger number. But this will use
5486 more memory, there is the danger of failing when memory is exhausted.
Bram Moolenaarbc2eada2017-01-02 21:27:47 +01005487 Increasing this limit above 200 also changes the maximum for Ex
Bram Moolenaar0b0f0992018-05-22 21:41:30 +02005488 command recursion, see |E169|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005489 See also |:function|.
Christian Brabandt47510f32023-10-15 09:56:16 +02005490 Also used for maximum depth of callback functions.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005491
5492 *'maxmapdepth'* *'mmd'* *E223*
5493'maxmapdepth' 'mmd' number (default 1000)
5494 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005495 Maximum number of times a mapping is done without resulting in a
5496 character to be used. This normally catches endless mappings, like
5497 ":map x y" with ":map y x". It still does not catch ":map g wg",
5498 because the 'w' is used before the next mapping is done. See also
5499 |key-mapping|.
5500
5501 *'maxmem'* *'mm'*
5502'maxmem' 'mm' number (default between 256 to 5120 (system
5503 dependent) or half the amount of memory
5504 available)
5505 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005506 Maximum amount of memory (in Kbyte) to use for one buffer. When this
5507 limit is reached allocating extra memory for a buffer will cause
Bram Moolenaarcafafb32018-02-22 21:07:09 +01005508 other memory to be freed.
5509 The maximum usable value is about 2000000. Use this to work without a
5510 limit.
5511 The value is ignored when 'swapfile' is off.
5512 Also see 'maxmemtot'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005513
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00005514 *'maxmempattern'* *'mmp'*
5515'maxmempattern' 'mmp' number (default 1000)
5516 global
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00005517 Maximum amount of memory (in Kbyte) to use for pattern matching.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005518 The maximum value is about 2000000. Use this to work without a limit.
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00005519 *E363*
Bram Moolenaar02467872007-05-06 13:22:01 +00005520 When Vim runs into the limit it gives an error message and mostly
5521 behaves like CTRL-C was typed.
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00005522 Running into the limit often means that the pattern is very
5523 inefficient or too complex. This may already happen with the pattern
5524 "\(.\)*" on a very long line. ".*" works much better.
Bram Moolenaarfd358112018-07-07 23:21:31 +02005525 Might also happen on redraw, when syntax rules try to match a complex
5526 text structure.
5527 Vim may run out of memory before hitting the 'maxmempattern' limit, in
5528 which case you get an "Out of memory" error instead.
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00005529
Bram Moolenaar071d4272004-06-13 20:20:40 +00005530 *'maxmemtot'* *'mmt'*
5531'maxmemtot' 'mmt' number (default between 2048 and 10240 (system
5532 dependent) or half the amount of memory
5533 available)
5534 global
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005535 Maximum amount of memory in Kbyte to use for all buffers together.
5536 The maximum usable value is about 2000000 (2 Gbyte). Use this to work
Bram Moolenaarfa735342016-01-03 22:14:44 +01005537 without a limit.
5538 On 64 bit machines higher values might work. But hey, do you really
5539 need more than 2 Gbyte for text editing? Keep in mind that text is
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02005540 stored in the swap file, one can edit files > 2 Gbyte anyway. We do
Bram Moolenaarfa735342016-01-03 22:14:44 +01005541 need the memory to store undo info.
Bram Moolenaarcafafb32018-02-22 21:07:09 +01005542 Buffers with 'swapfile' off still count to the total amount of memory
5543 used.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005544 Also see 'maxmem'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005545
5546 *'menuitems'* *'mis'*
5547'menuitems' 'mis' number (default 25)
5548 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005549 {not available when compiled without the |+menu|
5550 feature}
5551 Maximum number of items to use in a menu. Used for menus that are
5552 generated from a list of items, e.g., the Buffers menu. Changing this
5553 option has no direct effect, the menu must be refreshed first.
5554
Bram Moolenaar8aff23a2005-08-19 20:40:30 +00005555 *'mkspellmem'* *'msm'*
5556'mkspellmem' 'msm' string (default "460000,2000,500")
5557 global
Bram Moolenaar8aff23a2005-08-19 20:40:30 +00005558 {not available when compiled without the |+syntax|
5559 feature}
5560 Parameters for |:mkspell|. This tunes when to start compressing the
5561 word tree. Compression can be slow when there are many words, but
5562 it's needed to avoid running out of memory. The amount of memory used
5563 per word depends very much on how similar the words are, that's why
5564 this tuning is complicated.
5565
5566 There are three numbers, separated by commas:
5567 {start},{inc},{added}
5568
5569 For most languages the uncompressed word tree fits in memory. {start}
5570 gives the amount of memory in Kbyte that can be used before any
5571 compression is done. It should be a bit smaller than the amount of
5572 memory that is available to Vim.
5573
5574 When going over the {start} limit the {inc} number specifies the
5575 amount of memory in Kbyte that can be allocated before another
5576 compression is done. A low number means compression is done after
5577 less words are added, which is slow. A high number means more memory
5578 will be allocated.
5579
5580 After doing compression, {added} times 1024 words can be added before
5581 the {inc} limit is ignored and compression is done when any extra
5582 amount of memory is needed. A low number means there is a smaller
5583 chance of hitting the {inc} limit, less memory is used but it's
5584 slower.
5585
5586 The languages for which these numbers are important are Italian and
5587 Hungarian. The default works for when you have about 512 Mbyte. If
5588 you have 1 Gbyte you could use: >
5589 :set mkspellmem=900000,3000,800
5590< If you have less than 512 Mbyte |:mkspell| may fail for some
5591 languages, no matter what you set 'mkspellmem' to.
5592
Bram Moolenaar07607392019-05-26 19:20:43 +02005593 This option cannot be set from a |modeline| or in the |sandbox|.
5594
Bram Moolenaar071d4272004-06-13 20:20:40 +00005595 *'modeline'* *'ml'* *'nomodeline'* *'noml'*
Bram Moolenaar8243a792007-05-01 17:05:03 +00005596'modeline' 'ml' boolean (Vim default: on (off for root),
5597 Vi default: off)
Bram Moolenaar071d4272004-06-13 20:20:40 +00005598 local to buffer
Bram Moolenaar110289e2019-05-23 15:38:06 +02005599 If 'modeline' is on 'modelines' gives the number of lines that is
5600 checked for set commands. If 'modeline' is off or 'modelines' is zero
5601 no lines are checked. See |modeline|.
5602
5603 *'modelineexpr'* *'mle'* *'nomodelineexpr'* *'nomle'*
5604'modelineexpr' 'mle' boolean (default: off)
5605 global
5606 When on allow some options that are an expression to be set in the
5607 modeline. Check the option for whether it is affected by
5608 'modelineexpr'. Also see |modeline|.
Bram Moolenaar1c6fd1e2019-05-23 22:11:59 +02005609 This option cannot be set from a |modeline| or in the |sandbox|, for
5610 security reasons.
Bram Moolenaar110289e2019-05-23 15:38:06 +02005611
Bram Moolenaar071d4272004-06-13 20:20:40 +00005612 *'modelines'* *'mls'*
5613'modelines' 'mls' number (default 5)
5614 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005615 If 'modeline' is on 'modelines' gives the number of lines that is
5616 checked for set commands. If 'modeline' is off or 'modelines' is zero
5617 no lines are checked. See |modeline|.
5618 NOTE: 'modeline' is set to the Vi default value when 'compatible' is
5619 set and to the Vim default value when 'compatible' is reset.
5620
5621 *'modifiable'* *'ma'* *'nomodifiable'* *'noma'*
Bram Moolenaar110289e2019-05-23 15:38:06 +02005622 *E21*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005623'modifiable' 'ma' boolean (default on)
5624 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00005625 When off the buffer contents cannot be changed. The 'fileformat' and
5626 'fileencoding' options also can't be changed.
Bram Moolenaar369b6f52017-01-17 12:22:32 +01005627 Can be reset on startup with the |-M| command line argument.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005628
5629 *'modified'* *'mod'* *'nomodified'* *'nomod'*
5630'modified' 'mod' boolean (default off)
Christian Brabandt596ad662023-08-16 00:11:09 +02005631 local to buffer |local-noglobal|
Bram Moolenaar071d4272004-06-13 20:20:40 +00005632 When on, the buffer is considered to be modified. This option is set
5633 when:
5634 1. A change was made to the text since it was last written. Using the
5635 |undo| command to go back to the original text will reset the
5636 option. But undoing changes that were made before writing the
5637 buffer will set the option again, since the text is different from
5638 when it was written.
5639 2. 'fileformat' or 'fileencoding' is different from its original
5640 value. The original value is set when the buffer is read or
5641 written. A ":set nomodified" command also resets the original
5642 values to the current values and the 'modified' option will be
5643 reset.
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01005644 Similarly for 'eol' and 'bomb'.
Bram Moolenaar5302d9e2011-09-14 17:55:08 +02005645 This option is not set when a change is made to the buffer as the
5646 result of a BufNewFile, BufRead/BufReadPost, BufWritePost,
5647 FileAppendPost or VimLeave autocommand event. See |gzip-example| for
5648 an explanation.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005649 When 'buftype' is "nowrite" or "nofile" this option may be set, but
5650 will be ignored.
Bram Moolenaarb5b75622018-03-09 22:22:21 +01005651 Note that the text may actually be the same, e.g. 'modified' is set
5652 when using "rA" on an "A".
Bram Moolenaar071d4272004-06-13 20:20:40 +00005653
5654 *'more'* *'nomore'*
5655'more' boolean (Vim default: on, Vi default: off)
5656 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005657 When on, listings pause when the whole screen is filled. You will get
5658 the |more-prompt|. When this option is off there are no pauses, the
5659 listing continues until finished.
5660 NOTE: This option is set to the Vi default value when 'compatible' is
5661 set and to the Vim default value when 'compatible' is reset.
5662
Bram Moolenaar98a29d02021-01-18 19:55:44 +01005663 *'mouse'*
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01005664'mouse' string (default "", "a" for GUI and Win32,
Bram Moolenaar5b418992019-10-27 18:50:25 +01005665 set to "a" or "nvi" in |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00005666 global
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01005667 Enable the use of the mouse. Works for most terminals (xterm, Win32
5668 |win32-mouse|, QNX pterm, *BSD console with sysmouse and Linux console
5669 with gpm). For using the mouse in the GUI, see |gui-mouse|. The
5670 mouse can be enabled for different modes:
Bram Moolenaar7f2e9d72017-11-11 20:58:53 +01005671 n Normal mode and Terminal modes
Bram Moolenaar071d4272004-06-13 20:20:40 +00005672 v Visual mode
5673 i Insert mode
5674 c Command-line mode
5675 h all previous modes when editing a help file
5676 a all previous modes
5677 r for |hit-enter| and |more-prompt| prompt
Bram Moolenaar95bafa22018-10-02 13:26:25 +02005678 Normally you would enable the mouse in all five modes with: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005679 :set mouse=a
Bram Moolenaar5b418992019-10-27 18:50:25 +01005680< If your terminal can't overrule the mouse events going to the
5681 application, use: >
5682 :set mouse=nvi
Bram Moolenaar65e0d772020-06-14 17:29:55 +02005683< Then you can press ":", select text for the system, and press Esc to go
Bram Moolenaar5b418992019-10-27 18:50:25 +01005684 back to Vim using the mouse events.
5685 In |defaults.vim| "nvi" is used if the 'term' option is not matching
5686 "xterm".
5687
5688 When the mouse is not enabled, the GUI will still use the mouse for
Bram Moolenaar071d4272004-06-13 20:20:40 +00005689 modeless selection. This doesn't move the text cursor.
5690
5691 See |mouse-using|. Also see |'clipboard'|.
5692
5693 Note: When enabling the mouse in a terminal, copy/paste will use the
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00005694 "* register if there is access to an X-server. The xterm handling of
Bram Moolenaar071d4272004-06-13 20:20:40 +00005695 the mouse buttons can still be used by keeping the shift key pressed.
5696 Also see the 'clipboard' option.
5697
5698 *'mousefocus'* *'mousef'* *'nomousefocus'* *'nomousef'*
5699'mousefocus' 'mousef' boolean (default off)
5700 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005701 {only works in the GUI}
5702 The window that the mouse pointer is on is automatically activated.
5703 When changing the window layout or window focus in another way, the
5704 mouse pointer is moved to the window with keyboard focus. Off is the
5705 default because it makes using the pull down menus a little goofy, as
5706 a pointer transit may activate a window unintentionally.
Bram Moolenaar5ef1c6a2019-11-10 22:09:11 +01005707 MS-Windows: Also see 'scrollfocus' for what window is scrolled when
Bram Moolenaar1d9215b2020-01-25 13:27:42 +01005708 using the mouse scroll wheel.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005709
5710 *'mousehide'* *'mh'* *'nomousehide'* *'nomh'*
5711'mousehide' 'mh' boolean (default on)
5712 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005713 {only works in the GUI}
5714 When on, the mouse pointer is hidden when characters are typed.
5715 The mouse pointer is restored when the mouse is moved.
5716
5717 *'mousemodel'* *'mousem'*
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01005718'mousemodel' 'mousem' string (default "extend", "popup" for Win32)
Bram Moolenaar071d4272004-06-13 20:20:40 +00005719 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005720 Sets the model to use for the mouse. The name mostly specifies what
5721 the right mouse button is used for:
5722 extend Right mouse button extends a selection. This works
5723 like in an xterm.
5724 popup Right mouse button pops up a menu. The shifted left
5725 mouse button extends a selection. This works like
Bram Moolenaar582fd852005-03-28 20:58:01 +00005726 with Microsoft Windows.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005727 popup_setpos Like "popup", but the cursor will be moved to the
5728 position where the mouse was clicked, and thus the
5729 selected operation will act upon the clicked object.
5730 If clicking inside a selection, that selection will
Bram Moolenaar582fd852005-03-28 20:58:01 +00005731 be acted upon, i.e. no cursor move. This implies of
Bram Moolenaar071d4272004-06-13 20:20:40 +00005732 course, that right clicking outside a selection will
5733 end Visual mode.
5734 Overview of what button does what for each model:
5735 mouse extend popup(_setpos) ~
5736 left click place cursor place cursor
5737 left drag start selection start selection
5738 shift-left search word extend selection
5739 right click extend selection popup menu (place cursor)
5740 right drag extend selection -
5741 middle click paste paste
5742
5743 In the "popup" model the right mouse button produces a pop-up menu.
5744 You need to define this first, see |popup-menu|.
5745
5746 Note that you can further refine the meaning of buttons with mappings.
5747 See |gui-mouse-mapping|. But mappings are NOT used for modeless
5748 selection (because that's handled in the GUI code directly).
5749
5750 The 'mousemodel' option is set by the |:behave| command.
5751
h_east59858792023-10-25 22:47:05 +09005752 *'mousemoveevent'* *'mousemev'* *'nomousemoveevent'* *'nomousemev'*
Ernie Raelc4cb5442022-04-03 15:47:28 +01005753'mousemoveevent' 'mousemev' boolean (default off)
5754 global
5755 {only works in the GUI}
5756 When on, mouse move events are delivered to the input queue and are
5757 available for mapping. The default, off, avoids the mouse movement
5758 overhead except when needed. See |gui-mouse-mapping|.
5759 Warning: Setting this option can make pending mappings to be aborted
5760 when the mouse is moved.
5761 Currently only works in the GUI, may be made to work in a terminal
5762 later.
5763
Bram Moolenaar071d4272004-06-13 20:20:40 +00005764 *'mouseshape'* *'mouses'* *E547*
Bram Moolenaarf6b40102019-02-22 15:24:03 +01005765'mouseshape' 'mouses' string (default "i-r:beam,s:updown,sd:udsizing,
5766 vs:leftright,vd:lrsizing,m:no,
5767 ml:up-arrow,v:rightup-arrow")
Bram Moolenaar071d4272004-06-13 20:20:40 +00005768 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005769 {only available when compiled with the |+mouseshape|
5770 feature}
5771 This option tells Vim what the mouse pointer should look like in
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01005772 different modes. The option is a comma-separated list of parts, much
Bram Moolenaar071d4272004-06-13 20:20:40 +00005773 like used for 'guicursor'. Each part consist of a mode/location-list
5774 and an argument-list:
5775 mode-list:shape,mode-list:shape,..
5776 The mode-list is a dash separated list of these modes/locations:
5777 In a normal window: ~
5778 n Normal mode
5779 v Visual mode
5780 ve Visual mode with 'selection' "exclusive" (same as 'v',
5781 if not specified)
5782 o Operator-pending mode
5783 i Insert mode
5784 r Replace mode
5785
5786 Others: ~
5787 c appending to the command-line
5788 ci inserting in the command-line
5789 cr replacing in the command-line
5790 m at the 'Hit ENTER' or 'More' prompts
5791 ml idem, but cursor in the last line
5792 e any mode, pointer below last window
5793 s any mode, pointer on a status line
5794 sd any mode, while dragging a status line
5795 vs any mode, pointer on a vertical separator line
5796 vd any mode, while dragging a vertical separator line
5797 a everywhere
5798
5799 The shape is one of the following:
5800 avail name looks like ~
5801 w x arrow Normal mouse pointer
5802 w x blank no pointer at all (use with care!)
5803 w x beam I-beam
5804 w x updown up-down sizing arrows
5805 w x leftright left-right sizing arrows
5806 w x busy The system's usual busy pointer
5807 w x no The system's usual 'no input' pointer
5808 x udsizing indicates up-down resizing
5809 x lrsizing indicates left-right resizing
5810 x crosshair like a big thin +
5811 x hand1 black hand
5812 x hand2 white hand
5813 x pencil what you write with
5814 x question big ?
5815 x rightup-arrow arrow pointing right-up
5816 w x up-arrow arrow pointing up
5817 x <number> any X11 pointer number (see X11/cursorfont.h)
5818
5819 The "avail" column contains a 'w' if the shape is available for Win32,
5820 x for X11.
5821 Any modes not specified or shapes not available use the normal mouse
5822 pointer.
5823
5824 Example: >
5825 :set mouseshape=s:udsizing,m:no
5826< will make the mouse turn to a sizing arrow over the status lines and
5827 indicate no input when the hit-enter prompt is displayed (since
5828 clicking the mouse has no effect in this state.)
5829
5830 *'mousetime'* *'mouset'*
5831'mousetime' 'mouset' number (default 500)
5832 global
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01005833 Only for GUI, Win32 and Unix with xterm. Defines the maximum
Bram Moolenaar071d4272004-06-13 20:20:40 +00005834 time in msec between two mouse clicks for the second click to be
5835 recognized as a multi click.
5836
Bram Moolenaar0ab35b22017-10-08 17:41:37 +02005837 *'mzschemedll'*
5838'mzschemedll' string (default depends on the build)
5839 global
Bram Moolenaar0ab35b22017-10-08 17:41:37 +02005840 {only available when compiled with the |+mzscheme/dyn|
5841 feature}
5842 Specifies the name of the MzScheme shared library. The default is
5843 DYNAMIC_MZSCH_DLL which was specified at compile time.
5844 Environment variables are expanded |:set_env|.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01005845 The value must be set in the |vimrc| script or earlier. In the
Bram Moolenaar01164a62017-11-02 22:58:42 +01005846 startup, before the |load-plugins| step.
Bram Moolenaar0ab35b22017-10-08 17:41:37 +02005847 This option cannot be set from a |modeline| or in the |sandbox|, for
5848 security reasons.
5849
5850 *'mzschemegcdll'*
5851'mzschemegcdll' string (default depends on the build)
5852 global
Bram Moolenaar0ab35b22017-10-08 17:41:37 +02005853 {only available when compiled with the |+mzscheme/dyn|
5854 feature}
5855 Specifies the name of the MzScheme GC shared library. The default is
5856 DYNAMIC_MZGC_DLL which was specified at compile time.
5857 The value can be equal to 'mzschemedll' if it includes the GC code.
5858 Environment variables are expanded |:set_env|.
5859 This option cannot be set from a |modeline| or in the |sandbox|, for
5860 security reasons.
5861
Bram Moolenaar325b7a22004-07-05 15:58:32 +00005862 *'mzquantum'* *'mzq'*
5863'mzquantum' 'mzq' number (default 100)
5864 global
Bram Moolenaar325b7a22004-07-05 15:58:32 +00005865 {not available when compiled without the |+mzscheme|
5866 feature}
5867 The number of milliseconds between polls for MzScheme threads.
5868 Negative or zero value means no thread scheduling.
Bram Moolenaar036986f2017-03-16 17:41:02 +01005869 NOTE: This option is set to the Vim default value when 'compatible'
5870 is reset.
Bram Moolenaar325b7a22004-07-05 15:58:32 +00005871
Bram Moolenaar071d4272004-06-13 20:20:40 +00005872 *'nrformats'* *'nf'*
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +02005873'nrformats' 'nf' string (default "bin,octal,hex",
5874 set to "bin,hex" in |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00005875 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00005876 This defines what bases Vim will consider for numbers when using the
5877 CTRL-A and CTRL-X commands for adding to and subtracting from a number
5878 respectively; see |CTRL-A| for more info on these commands.
Bram Moolenaar4770d092006-01-12 23:22:24 +00005879 alpha If included, single alphabetical characters will be
Bram Moolenaar071d4272004-06-13 20:20:40 +00005880 incremented or decremented. This is useful for a list with a
Bram Moolenaar3848e002016-03-19 18:42:29 +01005881 letter index a), b), etc. *octal-nrformats*
Bram Moolenaar4770d092006-01-12 23:22:24 +00005882 octal If included, numbers that start with a zero will be considered
Bram Moolenaar071d4272004-06-13 20:20:40 +00005883 to be octal. Example: Using CTRL-A on "007" results in "010".
Bram Moolenaar4770d092006-01-12 23:22:24 +00005884 hex If included, numbers starting with "0x" or "0X" will be
Bram Moolenaar071d4272004-06-13 20:20:40 +00005885 considered to be hexadecimal. Example: Using CTRL-X on
5886 "0x100" results in "0x0ff".
Bram Moolenaar25e4fcd2016-01-09 14:57:47 +01005887 bin If included, numbers starting with "0b" or "0B" will be
5888 considered to be binary. Example: Using CTRL-X on
5889 "0b1000" subtracts one, resulting in "0b0111".
Bram Moolenaaraaad9952020-05-31 15:08:59 +02005890 unsigned If included, numbers are recognized as unsigned. Thus a
5891 leading dash or negative sign won't be considered as part of
5892 the number. Examples:
5893 Using CTRL-X on "2020" in "9-2020" results in "9-2019"
5894 (without "unsigned" it would become "9-2021").
5895 Using CTRL-A on "2020" in "9-2020" results in "9-2021"
5896 (without "unsigned" it would become "9-2019").
Bram Moolenaaracc22402020-06-07 21:07:18 +02005897 Using CTRL-X on "0" or CTRL-A on "18446744073709551615"
5898 (2^64 - 1) has no effect, overflow is prevented.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005899 Numbers which simply begin with a digit in the range 1-9 are always
5900 considered decimal. This also happens for numbers that are not
5901 recognized as octal or hex.
5902
5903 *'number'* *'nu'* *'nonumber'* *'nonu'*
5904'number' 'nu' boolean (default off)
5905 local to window
5906 Print the line number in front of each line. When the 'n' option is
5907 excluded from 'cpoptions' a wrapped line will not use the column of
5908 line numbers (this is the default when 'compatible' isn't set).
Bram Moolenaar592e0a22004-07-03 16:05:59 +00005909 The 'numberwidth' option can be used to set the room used for the line
5910 number.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005911 When a long, wrapped line doesn't start with the first character, '-'
5912 characters are put before the number.
James McCoya80aad72021-12-22 19:45:28 +00005913 For highlighting see |hl-LineNr|, and |hl-CursorLineNr|, and the
5914 |:sign-define| "numhl" argument.
Bram Moolenaar203d04d2013-06-06 21:36:40 +02005915 *number_relativenumber*
5916 The 'relativenumber' option changes the displayed number to be
5917 relative to the cursor. Together with 'number' there are these
5918 four combinations (cursor in line 3):
5919
Bram Moolenaar3848e002016-03-19 18:42:29 +01005920 'nonu' 'nu' 'nonu' 'nu'
Bram Moolenaar203d04d2013-06-06 21:36:40 +02005921 'nornu' 'nornu' 'rnu' 'rnu'
5922
5923 |apple | 1 apple | 2 apple | 2 apple
5924 |pear | 2 pear | 1 pear | 1 pear
5925 |nobody | 3 nobody | 0 nobody |3 nobody
5926 |there | 4 there | 1 there | 1 there
Bram Moolenaar071d4272004-06-13 20:20:40 +00005927
Bram Moolenaar592e0a22004-07-03 16:05:59 +00005928 *'numberwidth'* *'nuw'*
5929'numberwidth' 'nuw' number (Vim default: 4 Vi default: 8)
5930 local to window
Bram Moolenaar325b7a22004-07-05 15:58:32 +00005931 {only available when compiled with the |+linebreak|
5932 feature}
Bram Moolenaar592e0a22004-07-03 16:05:59 +00005933 Minimal number of columns to use for the line number. Only relevant
Bram Moolenaar64486672010-05-16 15:46:46 +02005934 when the 'number' or 'relativenumber' option is set or printing lines
5935 with a line number. Since one space is always between the number and
5936 the text, there is one less character for the number itself.
Bram Moolenaar592e0a22004-07-03 16:05:59 +00005937 The value is the minimum width. A bigger width is used when needed to
Bram Moolenaar64486672010-05-16 15:46:46 +02005938 fit the highest line number in the buffer respectively the number of
5939 rows in the window, depending on whether 'number' or 'relativenumber'
5940 is set. Thus with the Vim default of 4 there is room for a line number
5941 up to 999. When the buffer has 1000 lines five columns will be used.
Bram Moolenaarf8a07122019-07-01 22:06:07 +02005942 The minimum value is 1, the maximum value is 20.
Bram Moolenaar036986f2017-03-16 17:41:02 +01005943 NOTE: This option is set to the Vi default value when 'compatible' is
5944 set and to the Vim default value when 'compatible' is reset.
Bram Moolenaar592e0a22004-07-03 16:05:59 +00005945
Bram Moolenaarf75a9632005-09-13 21:20:47 +00005946 *'omnifunc'* *'ofu'*
5947'omnifunc' 'ofu' string (default: empty)
Bram Moolenaare344bea2005-09-01 20:46:49 +00005948 local to buffer
Bram Moolenaardb84e452010-08-15 13:50:43 +02005949 {not available when compiled without the |+eval|
Bram Moolenaare2c453d2019-08-21 14:37:09 +02005950 feature}
Bram Moolenaarc7486e02005-12-29 22:48:26 +00005951 This option specifies a function to be used for Insert mode omni
5952 completion with CTRL-X CTRL-O. |i_CTRL-X_CTRL-O|
Bram Moolenaar280f1262006-01-30 00:14:18 +00005953 See |complete-functions| for an explanation of how the function is
Yegappan Lakshmanan8658c752021-12-03 11:09:29 +00005954 invoked and what it should return. The value can be the name of a
5955 function, a |lambda| or a |Funcref|. See |option-value-function| for
5956 more information.
Bram Moolenaar043545e2006-10-10 16:44:07 +00005957 This option is usually set by a filetype plugin:
Bram Moolenaar9c102382006-05-03 21:26:49 +00005958 |:filetype-plugin-on|
Bram Moolenaar30b65812012-07-12 22:01:11 +02005959 This option cannot be set from a |modeline| or in the |sandbox|, for
5960 security reasons.
Bram Moolenaare344bea2005-09-01 20:46:49 +00005961
5962
Bram Moolenaar02467872007-05-06 13:22:01 +00005963 *'opendevice'* *'odev'* *'noopendevice'* *'noodev'*
Bram Moolenaar043545e2006-10-10 16:44:07 +00005964'opendevice' 'odev' boolean (default off)
5965 global
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00005966 {only for MS-Windows} *E796*
Bram Moolenaar043545e2006-10-10 16:44:07 +00005967 Enable reading and writing from devices. This may get Vim stuck on a
5968 device that can be opened but doesn't actually do the I/O. Therefore
5969 it is off by default.
5970 Note that on MS-Windows editing "aux.h", "lpt1.txt" and the like also
5971 result in editing a device.
5972
5973
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00005974 *'operatorfunc'* *'opfunc'*
5975'operatorfunc' 'opfunc' string (default: empty)
5976 global
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00005977 This option specifies a function to be called by the |g@| operator.
Yegappan Lakshmanan777175b2021-11-18 22:08:57 +00005978 See |:map-operator| for more info and an example. The value can be
5979 the name of a function, a |lambda| or a |Funcref|. See
5980 |option-value-function| for more information.
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00005981
5982 This option cannot be set from a |modeline| or in the |sandbox|, for
5983 security reasons.
5984
5985
Bram Moolenaar251e1912011-06-19 05:09:16 +02005986 *'osfiletype'* *'oft'*
5987'osfiletype' 'oft' string (default: "")
Bram Moolenaar071d4272004-06-13 20:20:40 +00005988 local to buffer
Bram Moolenaar251e1912011-06-19 05:09:16 +02005989 This option was supported on RISC OS, which has been removed.
5990
Bram Moolenaar071d4272004-06-13 20:20:40 +00005991
Bram Moolenaarf6fee0e2016-02-21 23:02:49 +01005992 *'packpath'* *'pp'*
5993'packpath' 'pp' string (default: see 'runtimepath')
Bram Moolenaarf6fee0e2016-02-21 23:02:49 +01005994 Directories used to find packages. See |packages|.
5995
5996
Bram Moolenaar071d4272004-06-13 20:20:40 +00005997 *'paragraphs'* *'para'*
Bram Moolenaar57e48462008-03-12 16:38:55 +00005998'paragraphs' 'para' string (default "IPLPPPQPP TPHPLIPpLpItpplpipbp")
Bram Moolenaar071d4272004-06-13 20:20:40 +00005999 global
6000 Specifies the nroff macros that separate paragraphs. These are pairs
6001 of two letters (see |object-motions|).
6002
6003 *'paste'* *'nopaste'*
6004'paste' boolean (default off)
6005 global
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006006 Put Vim in Paste mode. This is useful if you want to cut or copy
6007 some text from one window and paste it in Vim. This will avoid
Bram Moolenaar071d4272004-06-13 20:20:40 +00006008 unexpected effects.
6009 Setting this option is useful when using Vim in a terminal, where Vim
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006010 cannot distinguish between typed text and pasted text. In the GUI, Vim
Bram Moolenaar071d4272004-06-13 20:20:40 +00006011 knows about pasting and will mostly do the right thing without 'paste'
6012 being set. The same is true for a terminal where Vim handles the
6013 mouse clicks itself.
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00006014 This option is reset when starting the GUI. Thus if you set it in
6015 your .vimrc it will work in a terminal, but not in the GUI. Setting
6016 'paste' in the GUI has side effects: e.g., the Paste toolbar button
6017 will no longer work in Insert mode, because it uses a mapping.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006018 When the 'paste' option is switched on (also when it was already on):
6019 - mapping in Insert mode and Command-line mode is disabled
6020 - abbreviations are disabled
Bram Moolenaar071d4272004-06-13 20:20:40 +00006021 - 'autoindent' is reset
Bram Moolenaarca635012015-09-25 20:34:21 +02006022 - 'expandtab' is reset
Bram Moolenaar4d8f4762021-06-27 15:18:56 +02006023 - 'hkmap' is reset
Bram Moolenaar071d4272004-06-13 20:20:40 +00006024 - 'revins' is reset
6025 - 'ruler' is reset
6026 - 'showmatch' is reset
Bram Moolenaarca635012015-09-25 20:34:21 +02006027 - 'smarttab' is reset
6028 - 'softtabstop' is set to 0
6029 - 'textwidth' is set to 0
6030 - 'wrapmargin' is set to 0
Bram Moolenaar4d8f4762021-06-27 15:18:56 +02006031 - 'varsofttabstop' is made empty
Bram Moolenaar071d4272004-06-13 20:20:40 +00006032 These options keep their value, but their effect is disabled:
Bram Moolenaar071d4272004-06-13 20:20:40 +00006033 - 'cindent'
Bram Moolenaar4d8f4762021-06-27 15:18:56 +02006034 - 'formatoptions' is used like it is empty
Bram Moolenaarca635012015-09-25 20:34:21 +02006035 - 'indentexpr'
6036 - 'lisp'
Bram Moolenaar4d8f4762021-06-27 15:18:56 +02006037 - 'smartindent'
Bram Moolenaar071d4272004-06-13 20:20:40 +00006038 NOTE: When you start editing another file while the 'paste' option is
6039 on, settings from the modelines or autocommands may change the
6040 settings again, causing trouble when pasting text. You might want to
6041 set the 'paste' option again.
6042 When the 'paste' option is reset the mentioned options are restored to
6043 the value before the moment 'paste' was switched from off to on.
6044 Resetting 'paste' before ever setting it does not have any effect.
6045 Since mapping doesn't work while 'paste' is active, you need to use
6046 the 'pastetoggle' option to toggle the 'paste' option with some key.
6047
6048 *'pastetoggle'* *'pt'*
6049'pastetoggle' 'pt' string (default "")
6050 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006051 When non-empty, specifies the key sequence that toggles the 'paste'
6052 option. This is like specifying a mapping: >
6053 :map {keys} :set invpaste<CR>
6054< Where {keys} is the value of 'pastetoggle'.
6055 The difference is that it will work even when 'paste' is set.
6056 'pastetoggle' works in Insert mode and Normal mode, but not in
6057 Command-line mode.
6058 Mappings are checked first, thus overrule 'pastetoggle'. However,
6059 when 'paste' is on mappings are ignored in Insert mode, thus you can do
6060 this: >
6061 :map <F10> :set paste<CR>
6062 :map <F11> :set nopaste<CR>
6063 :imap <F10> <C-O>:set paste<CR>
6064 :imap <F11> <nop>
6065 :set pastetoggle=<F11>
6066< This will make <F10> start paste mode and <F11> stop paste mode.
6067 Note that typing <F10> in paste mode inserts "<F10>", since in paste
6068 mode everything is inserted literally, except the 'pastetoggle' key
6069 sequence.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006070 When the value has several bytes 'ttimeoutlen' applies.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006071
6072 *'pex'* *'patchexpr'*
6073'patchexpr' 'pex' string (default "")
6074 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006075 {not available when compiled without the |+diff|
6076 feature}
6077 Expression which is evaluated to apply a patch to a file and generate
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006078 the resulting new version of the file. See |diff-patchexpr|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006079
Bram Moolenaardbc28022014-07-26 13:40:44 +02006080 *'patchmode'* *'pm'* *E205* *E206*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006081'patchmode' 'pm' string (default "")
6082 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006083 When non-empty the oldest version of a file is kept. This can be used
6084 to keep the original version of a file if you are changing files in a
6085 source distribution. Only the first time that a file is written a
6086 copy of the original file will be kept. The name of the copy is the
6087 name of the original file with the string in the 'patchmode' option
6088 appended. This option should start with a dot. Use a string like
Bram Moolenaardf980db2017-12-24 13:22:00 +01006089 ".orig" or ".org". 'backupdir' must not be empty for this to work
6090 (Detail: The backup file is renamed to the patchmode file after the
6091 new file has been successfully written, that's why it must be possible
6092 to write a backup file). If there was no file to be backed up, an
6093 empty file is created.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006094 When the 'backupskip' pattern matches, a patchmode file is not made.
6095 Using 'patchmode' for compressed files appends the extension at the
6096 end (e.g., "file.gz.orig"), thus the resulting name isn't always
6097 recognized as a compressed file.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00006098 Only normal file name characters can be used, "/\*?[|<>" are illegal.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006099
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01006100 *'path'* *'pa'* *E343* *E345* *E347* *E854*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006101'path' 'pa' string (default on Unix: ".,/usr/include,,"
Bram Moolenaar071d4272004-06-13 20:20:40 +00006102 other systems: ".,,")
6103 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006104 This is a list of directories which will be searched when using the
Bram Moolenaarc236c162008-07-13 17:41:49 +00006105 |gf|, [f, ]f, ^Wf, |:find|, |:sfind|, |:tabfind| and other commands,
6106 provided that the file being searched for has a relative path (not
6107 starting with "/", "./" or "../"). The directories in the 'path'
6108 option may be relative or absolute.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006109 - Use commas to separate directory names: >
6110 :set path=.,/usr/local/include,/usr/include
6111< - Spaces can also be used to separate directory names (for backwards
6112 compatibility with version 3.0). To have a space in a directory
6113 name, precede it with an extra backslash, and escape the space: >
6114 :set path=.,/dir/with\\\ space
6115< - To include a comma in a directory name precede it with an extra
6116 backslash: >
6117 :set path=.,/dir/with\\,comma
6118< - To search relative to the directory of the current file, use: >
6119 :set path=.
6120< - To search in the current directory use an empty string between two
6121 commas: >
6122 :set path=,,
6123< - A directory name may end in a ':' or '/'.
6124 - Environment variables are expanded |:set_env|.
6125 - When using |netrw.vim| URLs can be used. For example, adding
6126 "http://www.vim.org" will make ":find index.html" work.
Bram Moolenaarc236c162008-07-13 17:41:49 +00006127 - Search upwards and downwards in a directory tree using "*", "**" and
6128 ";". See |file-searching| for info and syntax.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006129 - Careful with '\' characters, type two to get one in the option: >
6130 :set path=.,c:\\include
6131< Or just use '/' instead: >
6132 :set path=.,c:/include
6133< Don't forget "." or files won't even be found in the same directory as
6134 the file!
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006135 The maximum length is limited. How much depends on the system, mostly
Bram Moolenaar071d4272004-06-13 20:20:40 +00006136 it is something like 256 or 1024 characters.
6137 You can check if all the include files are found, using the value of
6138 'path', see |:checkpath|.
6139 The use of |:set+=| and |:set-=| is preferred when adding or removing
6140 directories from the list. This avoids problems when a future version
6141 uses another default. To remove the current directory use: >
6142 :set path-=
6143< To add the current directory use: >
6144 :set path+=
6145< To use an environment variable, you probably need to replace the
6146 separator. Here is an example to append $INCL, in which directory
6147 names are separated with a semi-colon: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006148 :let &path = &path .. "," .. substitute($INCL, ';', ',', 'g')
Bram Moolenaar071d4272004-06-13 20:20:40 +00006149< Replace the ';' with a ':' or whatever separator is used. Note that
6150 this doesn't work when $INCL contains a comma or white space.
6151
Bram Moolenaar37c64c72017-09-19 22:06:03 +02006152 *'perldll'*
6153'perldll' string (default depends on the build)
6154 global
Bram Moolenaar37c64c72017-09-19 22:06:03 +02006155 {only available when compiled with the |+perl/dyn|
6156 feature}
6157 Specifies the name of the Perl shared library. The default is
6158 DYNAMIC_PERL_DLL, which was specified at compile time.
6159 Environment variables are expanded |:set_env|.
6160 This option cannot be set from a |modeline| or in the |sandbox|, for
6161 security reasons.
6162
Bram Moolenaar071d4272004-06-13 20:20:40 +00006163 *'preserveindent'* *'pi'* *'nopreserveindent'* *'nopi'*
6164'preserveindent' 'pi' boolean (default off)
6165 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00006166 When changing the indent of the current line, preserve as much of the
6167 indent structure as possible. Normally the indent is replaced by a
6168 series of tabs followed by spaces as required (unless |'expandtab'| is
6169 enabled, in which case only spaces are used). Enabling this option
6170 means the indent will preserve as many existing characters as possible
6171 for indenting, and only add additional tabs or spaces as required.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006172 'expandtab' does not apply to the preserved white space, a Tab remains
6173 a Tab.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006174 NOTE: When using ">>" multiple times the resulting indent is a mix of
6175 tabs and spaces. You might not like this.
Bram Moolenaar036986f2017-03-16 17:41:02 +01006176 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006177 Also see 'copyindent'.
6178 Use |:retab| to clean up white space.
6179
6180 *'previewheight'* *'pvh'*
6181'previewheight' 'pvh' number (default 12)
6182 global
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02006183 {not available when compiled without the |+quickfix|
6184 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00006185 Default height for a preview window. Used for |:ptag| and associated
Bram Moolenaar79648732019-07-18 21:43:07 +02006186 commands. Used for |CTRL-W_}| when no count is given. Not used when
6187 'previewpopup' is set.
6188
6189 *'previewpopup'* *'pvp'*
6190'previewpopup' 'pvp' string (default empty)
6191 global
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02006192 {not available when compiled without the |+textprop|
6193 or |+quickfix| feature}
Bram Moolenaar79648732019-07-18 21:43:07 +02006194 When not empty a popup window is used for commands that would open a
6195 preview window. See |preview-popup|.
Bram Moolenaar576a4a62019-08-18 15:25:17 +02006196 Not used for the insert completion info, add "popup" to
6197 'completeopt' for that.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006198
6199 *'previewwindow'* *'nopreviewwindow'*
6200 *'pvw'* *'nopvw'* *E590*
6201'previewwindow' 'pvw' boolean (default off)
Christian Brabandt596ad662023-08-16 00:11:09 +02006202 local to window |local-noglobal|
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02006203 {not available when compiled without the |+quickfix|
6204 feature}
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006205 Identifies the preview window. Only one window can have this option
Bram Moolenaar071d4272004-06-13 20:20:40 +00006206 set. It's normally not set directly, but by using one of the commands
6207 |:ptag|, |:pedit|, etc.
6208
6209 *'printdevice'* *'pdev'*
6210'printdevice' 'pdev' string (default empty)
6211 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006212 {only available when compiled with the |+printer|
6213 feature}
Bram Moolenaar8299df92004-07-10 09:47:34 +00006214 The name of the printer to be used for |:hardcopy|.
6215 See |pdev-option|.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00006216 This option cannot be set from a |modeline| or in the |sandbox|, for
6217 security reasons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006218
Bram Moolenaar8299df92004-07-10 09:47:34 +00006219 *'printencoding'* *'penc'*
Bram Moolenaar95bafa22018-10-02 13:26:25 +02006220'printencoding' 'penc' string (default empty, except for some systems)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006221 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006222 {only available when compiled with the |+printer|
6223 and |+postscript| features}
Bram Moolenaar8299df92004-07-10 09:47:34 +00006224 Sets the character encoding used when printing.
6225 See |penc-option|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006226
6227 *'printexpr'* *'pexpr'*
Bram Moolenaar95bafa22018-10-02 13:26:25 +02006228'printexpr' 'pexpr' string (default: see below)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006229 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006230 {only available when compiled with the |+printer|
6231 and |+postscript| features}
Bram Moolenaar8299df92004-07-10 09:47:34 +00006232 Expression used to print the PostScript produced with |:hardcopy|.
6233 See |pexpr-option|.
Bram Moolenaar51628222016-12-01 23:03:28 +01006234 This option cannot be set from a |modeline| or in the |sandbox|, for
6235 security reasons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006236
Bram Moolenaar8299df92004-07-10 09:47:34 +00006237 *'printfont'* *'pfn'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006238'printfont' 'pfn' string (default "courier")
6239 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006240 {only available when compiled with the |+printer|
6241 feature}
Bram Moolenaar8299df92004-07-10 09:47:34 +00006242 The name of the font that will be used for |:hardcopy|.
6243 See |pfn-option|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006244
6245 *'printheader'* *'pheader'*
6246'printheader' 'pheader' string (default "%<%f%h%m%=Page %N")
6247 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006248 {only available when compiled with the |+printer|
6249 feature}
Bram Moolenaar8299df92004-07-10 09:47:34 +00006250 The format of the header produced in |:hardcopy| output.
6251 See |pheader-option|.
6252
6253 *'printmbcharset'* *'pmbcs'*
6254'printmbcharset' 'pmbcs' string (default "")
6255 global
Bram Moolenaar4c92e752019-02-17 21:18:32 +01006256 {only available when compiled with the |+printer|
6257 and |+postscript| features}
Bram Moolenaar8299df92004-07-10 09:47:34 +00006258 The CJK character set to be used for CJK output from |:hardcopy|.
6259 See |pmbcs-option|.
6260
6261 *'printmbfont'* *'pmbfn'*
6262'printmbfont' 'pmbfn' string (default "")
6263 global
Bram Moolenaar4c92e752019-02-17 21:18:32 +01006264 {only available when compiled with the |+printer|
6265 and |+postscript| features}
Bram Moolenaar8299df92004-07-10 09:47:34 +00006266 List of font names to be used for CJK output from |:hardcopy|.
6267 See |pmbfn-option|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006268
6269 *'printoptions'* *'popt'*
6270'printoptions' 'popt' string (default "")
6271 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006272 {only available when compiled with |+printer| feature}
Bram Moolenaar8299df92004-07-10 09:47:34 +00006273 List of items that control the format of the output of |:hardcopy|.
6274 See |popt-option|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006275
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006276 *'prompt'* *'noprompt'*
6277'prompt' boolean (default on)
6278 global
6279 When on a ":" prompt is used in Ex mode.
6280
Bram Moolenaar7d47b6e2006-03-15 22:59:18 +00006281 *'pumheight'* *'ph'*
6282'pumheight' 'ph' number (default 0)
6283 global
Bram Moolenaar06a89a52006-04-29 22:01:03 +00006284 Determines the maximum number of items to show in the popup menu for
6285 Insert mode completion. When zero as much space as available is used.
Bram Moolenaar7d47b6e2006-03-15 22:59:18 +00006286 |ins-completion-menu|.
6287
Bram Moolenaara8f04aa2018-02-10 15:36:55 +01006288 *'pumwidth'* *'pw'*
Bram Moolenaarcafafb32018-02-22 21:07:09 +01006289'pumwidth' 'pw' number (default 15)
Bram Moolenaara8f04aa2018-02-10 15:36:55 +01006290 global
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01006291 Determines the minimum width to use for the popup menu for Insert mode
Bram Moolenaarcafafb32018-02-22 21:07:09 +01006292 completion. |ins-completion-menu|.
Bram Moolenaara8f04aa2018-02-10 15:36:55 +01006293
Bram Moolenaard94464e2015-11-02 15:28:18 +01006294 *'pythondll'*
Bram Moolenaar3848e002016-03-19 18:42:29 +01006295'pythondll' string (default depends on the build)
Bram Moolenaard94464e2015-11-02 15:28:18 +01006296 global
Bram Moolenaard94464e2015-11-02 15:28:18 +01006297 {only available when compiled with the |+python/dyn|
6298 feature}
Bram Moolenaar25e4fcd2016-01-09 14:57:47 +01006299 Specifies the name of the Python 2.x shared library. The default is
6300 DYNAMIC_PYTHON_DLL, which was specified at compile time.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02006301 Environment variables are expanded |:set_env|.
Bram Moolenaard94464e2015-11-02 15:28:18 +01006302 This option cannot be set from a |modeline| or in the |sandbox|, for
6303 security reasons.
Bram Moolenaar7d47b6e2006-03-15 22:59:18 +00006304
Bram Moolenaar94073162018-01-31 21:49:05 +01006305 *'pythonhome'*
6306'pythonhome' string (default "")
6307 global
Bram Moolenaar94073162018-01-31 21:49:05 +01006308 {only available when compiled with the |+python/dyn|
6309 feature}
6310 Specifies the name of the Python 2.x home directory. When 'pythonhome'
6311 and the PYTHONHOME environment variable are not set, PYTHON_HOME,
6312 which was specified at compile time, will be used for the Python 2.x
6313 home directory.
6314 Environment variables are expanded |:set_env|.
6315 This option cannot be set from a |modeline| or in the |sandbox|, for
6316 security reasons.
6317
Bram Moolenaarb4ff5182015-11-10 21:15:48 +01006318 *'pythonthreedll'*
Bram Moolenaar25e4fcd2016-01-09 14:57:47 +01006319'pythonthreedll' string (default depends on the build)
Bram Moolenaarb4ff5182015-11-10 21:15:48 +01006320 global
Bram Moolenaarb4ff5182015-11-10 21:15:48 +01006321 {only available when compiled with the |+python3/dyn|
6322 feature}
Bram Moolenaar25e4fcd2016-01-09 14:57:47 +01006323 Specifies the name of the Python 3 shared library. The default is
6324 DYNAMIC_PYTHON3_DLL, which was specified at compile time.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02006325 Environment variables are expanded |:set_env|.
Bram Moolenaarb4ff5182015-11-10 21:15:48 +01006326 This option cannot be set from a |modeline| or in the |sandbox|, for
6327 security reasons.
6328
Bram Moolenaar94073162018-01-31 21:49:05 +01006329 *'pythonthreehome'*
6330'pythonthreehome' string (default "")
6331 global
Bram Moolenaar94073162018-01-31 21:49:05 +01006332 {only available when compiled with the |+python3/dyn|
6333 feature}
6334 Specifies the name of the Python 3 home directory. When
6335 'pythonthreehome' and the PYTHONHOME environment variable are not set,
6336 PYTHON3_HOME, which was specified at compile time, will be used for
6337 the Python 3 home directory.
6338 Environment variables are expanded |:set_env|.
6339 This option cannot be set from a |modeline| or in the |sandbox|, for
6340 security reasons.
6341
Bram Moolenaarf42dd3c2017-01-28 16:06:38 +01006342 *'pyxversion'* *'pyx'*
6343'pyxversion' 'pyx' number (default depends on the build)
6344 global
Bram Moolenaarf42dd3c2017-01-28 16:06:38 +01006345 {only available when compiled with the |+python| or
6346 the |+python3| feature}
6347 Specifies the python version used for pyx* functions and commands
6348 |python_x|. The default value is as follows:
6349
6350 Compiled with Default ~
6351 |+python| and |+python3| 0
6352 only |+python| 2
6353 only |+python3| 3
6354
6355 Available values are 0, 2 and 3.
6356 If 'pyxversion' is 0, it is set to 2 or 3 after the first execution of
6357 any python2/3 commands or functions. E.g. `:py` sets to 2, and `:py3`
6358 sets to 3. `:pyx` sets it to 3 if Python 3 is available, otherwise sets
6359 to 2 if Python 2 is available.
6360 See also: |has-pythonx|
6361
6362 If Vim is compiled with only |+python| or |+python3| setting
6363 'pyxversion' has no effect. The pyx* functions and commands are
6364 always the same as the compiled version.
6365
6366 This option cannot be set from a |modeline| or in the |sandbox|, for
6367 security reasons.
6368
Bram Moolenaar858ba062020-05-31 23:11:59 +02006369 *'quickfixtextfunc'* *'qftf'*
6370'quickfixtextfunc' 'qftf' string (default "")
6371 global
6372 {only available when compiled with the |+quickfix|
6373 feature}
6374 This option specifies a function to be used to get the text to display
6375 in the quickfix and location list windows. This can be used to
6376 customize the information displayed in the quickfix or location window
6377 for each entry in the corresponding quickfix or location list. See
6378 |quickfix-window-function| for an explanation of how to write the
Yegappan Lakshmanan777175b2021-11-18 22:08:57 +00006379 function and an example. The value can be the name of a function, a
6380 |lambda| or a |Funcref|. See |option-value-function| for more
6381 information.
Bram Moolenaar858ba062020-05-31 23:11:59 +02006382
6383 This option cannot be set from a |modeline| or in the |sandbox|, for
6384 security reasons.
6385
Bram Moolenaar677ee682005-01-27 14:41:15 +00006386 *'quoteescape'* *'qe'*
Bram Moolenaarcfbc5ee2004-07-02 15:38:35 +00006387'quoteescape' 'qe' string (default "\")
6388 local to buffer
Bram Moolenaarcfbc5ee2004-07-02 15:38:35 +00006389 The characters that are used to escape quotes in a string. Used for
6390 objects like a', a" and a` |a'|.
6391 When one of the characters in this option is found inside a string,
6392 the following character will be skipped. The default value makes the
6393 text "foo\"bar\\" considered to be one string.
6394
Bram Moolenaar071d4272004-06-13 20:20:40 +00006395 *'readonly'* *'ro'* *'noreadonly'* *'noro'*
6396'readonly' 'ro' boolean (default off)
Christian Brabandt596ad662023-08-16 00:11:09 +02006397 local to buffer |local-noglobal|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006398 If on, writes fail unless you use a '!'. Protects you from
6399 accidentally overwriting a file. Default on when Vim is started
6400 in read-only mode ("vim -R") or when the executable is called "view".
Bram Moolenaar4399ef42005-02-12 14:29:27 +00006401 When using ":w!" the 'readonly' option is reset for the current
6402 buffer, unless the 'Z' flag is in 'cpoptions'.
Bram Moolenaar6c60f472019-04-28 16:00:35 +02006403 When using the ":view" command the 'readonly' option is set for the
6404 newly edited buffer.
Bram Moolenaar369b6f52017-01-17 12:22:32 +01006405 See 'modifiable' for disallowing changes to the buffer.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006406
Bram Moolenaar91a4e822008-01-19 14:59:58 +00006407 *'redrawtime'* *'rdt'*
6408'redrawtime' 'rdt' number (default 2000)
6409 global
Bram Moolenaar91a4e822008-01-19 14:59:58 +00006410 {only available when compiled with the |+reltime|
6411 feature}
6412 The time in milliseconds for redrawing the display. This applies to
Bram Moolenaar15142e22018-04-30 22:19:58 +02006413 searching for patterns for 'hlsearch', |:match| highlighting and syntax
Bram Moolenaar06f1ed22017-06-18 22:41:03 +02006414 highlighting.
Bram Moolenaar91a4e822008-01-19 14:59:58 +00006415 When redrawing takes more than this many milliseconds no further
Bram Moolenaar06f1ed22017-06-18 22:41:03 +02006416 matches will be highlighted.
6417 For syntax highlighting the time applies per window. When over the
6418 limit syntax highlighting is disabled until |CTRL-L| is used.
6419 This is used to avoid that Vim hangs when using a very complicated
6420 pattern.
Bram Moolenaar91a4e822008-01-19 14:59:58 +00006421
Bram Moolenaar543b7ef2013-06-01 14:50:56 +02006422 *'regexpengine'* *'re'*
Bram Moolenaare6ae6222013-05-21 21:01:10 +02006423'regexpengine' 're' number (default 0)
6424 global
Bram Moolenaare6ae6222013-05-21 21:01:10 +02006425 This selects the default regexp engine. |two-engines|
6426 The possible values are:
6427 0 automatic selection
6428 1 old engine
6429 2 NFA engine
6430 Note that when using the NFA engine and the pattern contains something
6431 that is not supported the pattern will not match. This is only useful
6432 for debugging the regexp engine.
Bram Moolenaarfda37292014-11-05 14:27:36 +01006433 Using automatic selection enables Vim to switch the engine, if the
6434 default engine becomes too costly. E.g., when the NFA engine uses too
6435 many states. This should prevent Vim from hanging on a combination of
6436 a complex pattern with long text.
Bram Moolenaare6ae6222013-05-21 21:01:10 +02006437
Bram Moolenaar64486672010-05-16 15:46:46 +02006438 *'relativenumber'* *'rnu'* *'norelativenumber'* *'nornu'*
6439'relativenumber' 'rnu' boolean (default off)
6440 local to window
Bram Moolenaar64486672010-05-16 15:46:46 +02006441 Show the line number relative to the line with the cursor in front of
Bram Moolenaar06b5d512010-05-22 15:37:44 +02006442 each line. Relative line numbers help you use the |count| you can
Bram Moolenaar64486672010-05-16 15:46:46 +02006443 precede some vertical motion commands (e.g. j k + -) with, without
6444 having to calculate it yourself. Especially useful in combination with
6445 other commands (e.g. y d c < > gq gw =).
6446 When the 'n' option is excluded from 'cpoptions' a wrapped
6447 line will not use the column of line numbers (this is the default when
6448 'compatible' isn't set).
6449 The 'numberwidth' option can be used to set the room used for the line
6450 number.
6451 When a long, wrapped line doesn't start with the first character, '-'
6452 characters are put before the number.
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02006453 See |hl-LineNr| and |hl-CursorLineNr| for the highlighting used for
6454 the number.
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01006455
Bram Moolenaar203d04d2013-06-06 21:36:40 +02006456 The number in front of the cursor line also depends on the value of
6457 'number', see |number_relativenumber| for all combinations of the two
6458 options.
Bram Moolenaar64486672010-05-16 15:46:46 +02006459
Bram Moolenaar071d4272004-06-13 20:20:40 +00006460 *'remap'* *'noremap'*
6461'remap' boolean (default on)
6462 global
6463 Allows for mappings to work recursively. If you do not want this for
6464 a single entry, use the :noremap[!] command.
Bram Moolenaara3227e22006-03-08 21:32:40 +00006465 NOTE: To avoid portability problems with Vim scripts, always keep
6466 this option at the default "on". Only switch it off when working with
6467 old Vi scripts.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006468
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02006469 *'renderoptions'* *'rop'*
6470'renderoptions' 'rop' string (default: empty)
6471 global
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02006472 {only available when compiled with GUI and DIRECTX on
6473 MS-Windows}
6474 Select a text renderer and set its options. The options depend on the
6475 renderer.
6476
6477 Syntax: >
6478 set rop=type:{renderer}(,{name}:{value})*
6479<
6480 Currently, only one optional renderer is available.
6481
6482 render behavior ~
6483 directx Vim will draw text using DirectX (DirectWrite). It makes
6484 drawn glyphs more beautiful than default GDI.
6485 It requires 'encoding' is "utf-8", and only works on
6486 MS-Windows Vista or newer version.
6487
6488 Options:
6489 name meaning type value ~
6490 gamma gamma float 1.0 - 2.2 (maybe)
6491 contrast enhancedContrast float (unknown)
6492 level clearTypeLevel float (unknown)
6493 geom pixelGeometry int 0 - 2 (see below)
6494 renmode renderingMode int 0 - 6 (see below)
6495 taamode textAntialiasMode int 0 - 3 (see below)
Bram Moolenaara338adc2018-01-31 20:51:47 +01006496 scrlines Scroll Lines int (deprecated)
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02006497
Bram Moolenaar92467d32017-12-05 13:22:16 +01006498 See this URL for detail (except for scrlines):
6499 https://msdn.microsoft.com/en-us/library/dd368190.aspx
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02006500
6501 For geom: structure of a device pixel.
6502 0 - DWRITE_PIXEL_GEOMETRY_FLAT
6503 1 - DWRITE_PIXEL_GEOMETRY_RGB
6504 2 - DWRITE_PIXEL_GEOMETRY_BGR
6505
6506 See this URL for detail:
Bram Moolenaar92467d32017-12-05 13:22:16 +01006507 https://msdn.microsoft.com/en-us/library/dd368114.aspx
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02006508
6509 For renmode: method of rendering glyphs.
6510 0 - DWRITE_RENDERING_MODE_DEFAULT
6511 1 - DWRITE_RENDERING_MODE_ALIASED
6512 2 - DWRITE_RENDERING_MODE_GDI_CLASSIC
6513 3 - DWRITE_RENDERING_MODE_GDI_NATURAL
6514 4 - DWRITE_RENDERING_MODE_NATURAL
6515 5 - DWRITE_RENDERING_MODE_NATURAL_SYMMETRIC
6516 6 - DWRITE_RENDERING_MODE_OUTLINE
6517
6518 See this URL for detail:
Bram Moolenaar92467d32017-12-05 13:22:16 +01006519 https://msdn.microsoft.com/en-us/library/dd368118.aspx
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02006520
6521 For taamode: antialiasing mode used for drawing text.
6522 0 - D2D1_TEXT_ANTIALIAS_MODE_DEFAULT
6523 1 - D2D1_TEXT_ANTIALIAS_MODE_CLEARTYPE
6524 2 - D2D1_TEXT_ANTIALIAS_MODE_GRAYSCALE
6525 3 - D2D1_TEXT_ANTIALIAS_MODE_ALIASED
6526
6527 See this URL for detail:
Bram Moolenaar92467d32017-12-05 13:22:16 +01006528 https://msdn.microsoft.com/en-us/library/dd368170.aspx
6529
Bram Moolenaara338adc2018-01-31 20:51:47 +01006530 For scrlines:
6531 This was used for optimizing scrolling behavior, however this
6532 is now deprecated. If specified, it is simply ignored.
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02006533
6534 Example: >
6535 set encoding=utf-8
Bram Moolenaard7ccc4d2017-11-26 14:29:32 +01006536 set gfn=Ricty_Diminished:h12
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02006537 set rop=type:directx
6538<
Bram Moolenaard7ccc4d2017-11-26 14:29:32 +01006539 If select a raster font (Courier, Terminal or FixedSys which
6540 have ".fon" extension in file name) to 'guifont', it will be
Bram Moolenaar92467d32017-12-05 13:22:16 +01006541 drawn by GDI as a fallback.
Bram Moolenaard7ccc4d2017-11-26 14:29:32 +01006542
6543 NOTE: It is known that some fonts and options combination
6544 causes trouble on drawing glyphs.
6545
Bram Moolenaar92467d32017-12-05 13:22:16 +01006546 - 'renmode:5' and 'renmode:6' will not work with some
Bram Moolenaard7ccc4d2017-11-26 14:29:32 +01006547 special made fonts (True-Type fonts which includes only
6548 bitmap glyphs).
6549 - 'taamode:3' will not work with some vector fonts.
6550
6551 NOTE: With this option, you can display colored emoji
6552 (emoticon) in Windows 8.1 or later. To display colored emoji,
6553 there are some conditions which you should notice.
6554
6555 - If your font includes non-colored emoji already, it will
6556 be used.
6557 - If your font doesn't have emoji, the system chooses an
6558 alternative symbol font. On Windows 10, "Segoe UI Emoji"
6559 will be used.
6560 - When this alternative font didn't have fixed width glyph,
6561 emoji might be rendered beyond the bounding box of drawing
6562 cell.
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02006563
6564 Other render types are currently not supported.
6565
Bram Moolenaar071d4272004-06-13 20:20:40 +00006566 *'report'*
6567'report' number (default 2)
6568 global
6569 Threshold for reporting number of lines changed. When the number of
6570 changed lines is more than 'report' a message will be given for most
6571 ":" commands. If you want it always, set 'report' to 0.
6572 For the ":substitute" command the number of substitutions is used
6573 instead of the number of lines.
6574
6575 *'restorescreen'* *'rs'* *'norestorescreen'* *'nors'*
6576'restorescreen' 'rs' boolean (default on)
6577 global
Bram Moolenaar8024f932020-01-14 19:29:13 +01006578 {only in MS-Windows console version}
Bram Moolenaar071d4272004-06-13 20:20:40 +00006579 When set, the screen contents is restored when exiting Vim. This also
6580 happens when executing external commands.
6581
6582 For non-Windows Vim: You can set or reset the 't_ti' and 't_te'
6583 options in your .vimrc. To disable restoring:
6584 set t_ti= t_te=
6585 To enable restoring (for an xterm):
6586 set t_ti=^[7^[[r^[[?47h t_te=^[[?47l^[8
6587 (Where ^[ is an <Esc>, type CTRL-V <Esc> to insert it)
6588
6589 *'revins'* *'ri'* *'norevins'* *'nori'*
6590'revins' 'ri' boolean (default off)
6591 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006592 {only available when compiled with the |+rightleft|
6593 feature}
6594 Inserting characters in Insert mode will work backwards. See "typing
6595 backwards" |ins-reverse|. This option can be toggled with the CTRL-_
6596 command in Insert mode, when 'allowrevins' is set.
Bram Moolenaarca635012015-09-25 20:34:21 +02006597 NOTE: This option is reset when 'compatible' is set.
6598 This option is reset when 'paste' is set and restored when 'paste' is
6599 reset.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006600
6601 *'rightleft'* *'rl'* *'norightleft'* *'norl'*
6602'rightleft' 'rl' boolean (default off)
6603 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00006604 {only available when compiled with the |+rightleft|
6605 feature}
6606 When on, display orientation becomes right-to-left, i.e., characters
6607 that are stored in the file appear from the right to the left.
6608 Using this option, it is possible to edit files for languages that
6609 are written from the right to the left such as Hebrew and Arabic.
6610 This option is per window, so it is possible to edit mixed files
6611 simultaneously, or to view the same file in both ways (this is
6612 useful whenever you have a mixed text file with both right-to-left
6613 and left-to-right strings so that both sets are displayed properly
6614 in different windows). Also see |rileft.txt|.
6615
Bram Moolenaar607cc1e2010-07-18 18:47:44 +02006616 *'rightleftcmd'* *'rlc'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006617'rightleftcmd' 'rlc' string (default "search")
6618 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00006619 {only available when compiled with the |+rightleft|
6620 feature}
6621 Each word in this option enables the command line editing to work in
6622 right-to-left mode for a group of commands:
6623
6624 search "/" and "?" commands
6625
6626 This is useful for languages such as Hebrew, Arabic and Farsi.
6627 The 'rightleft' option must be set for 'rightleftcmd' to take effect.
6628
Bram Moolenaard94464e2015-11-02 15:28:18 +01006629 *'rubydll'*
Bram Moolenaar3848e002016-03-19 18:42:29 +01006630'rubydll' string (default: depends on the build)
Bram Moolenaard94464e2015-11-02 15:28:18 +01006631 global
Bram Moolenaard94464e2015-11-02 15:28:18 +01006632 {only available when compiled with the |+ruby/dyn|
6633 feature}
Bram Moolenaar25e4fcd2016-01-09 14:57:47 +01006634 Specifies the name of the Ruby shared library. The default is
6635 DYNAMIC_RUBY_DLL, which was specified at compile time.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02006636 Environment variables are expanded |:set_env|.
Bram Moolenaard94464e2015-11-02 15:28:18 +01006637 This option cannot be set from a |modeline| or in the |sandbox|, for
6638 security reasons.
6639
Bram Moolenaar071d4272004-06-13 20:20:40 +00006640 *'ruler'* *'ru'* *'noruler'* *'noru'*
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +02006641'ruler' 'ru' boolean (default off, set in |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006642 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006643 Show the line and column number of the cursor position, separated by a
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006644 comma. When there is room, the relative position of the displayed
Bram Moolenaar071d4272004-06-13 20:20:40 +00006645 text in the file is shown on the far right:
6646 Top first line is visible
6647 Bot last line is visible
6648 All first and last line are visible
6649 45% relative position in the file
6650 If 'rulerformat' is set, it will determine the contents of the ruler.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006651 Each window has its own ruler. If a window has a status line, the
Bram Moolenaara2a89732022-08-31 14:46:18 +01006652 ruler is shown there. Otherwise it is shown in the last line of the
6653 screen. If the statusline is given by 'statusline' (i.e. not empty),
6654 this option takes precedence over 'ruler' and 'rulerformat'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006655 If the number of characters displayed is different from the number of
Bram Moolenaar207f0092020-08-30 17:20:20 +02006656 bytes in the text (e.g., for a TAB or a multibyte character), both
Bram Moolenaar071d4272004-06-13 20:20:40 +00006657 the text column (byte number) and the screen column are shown,
6658 separated with a dash.
6659 For an empty line "0-1" is shown.
6660 For an empty buffer the line number will also be zero: "0,0-1".
Bram Moolenaarca635012015-09-25 20:34:21 +02006661 This option is reset when 'paste' is set and restored when 'paste' is
6662 reset.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006663 If you don't want to see the ruler all the time but want to know where
6664 you are, use "g CTRL-G" |g_CTRL-G|.
6665 NOTE: This option is reset when 'compatible' is set.
6666
6667 *'rulerformat'* *'ruf'*
6668'rulerformat' 'ruf' string (default empty)
6669 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006670 {not available when compiled without the |+statusline|
6671 feature}
6672 When this option is not empty, it determines the content of the ruler
6673 string, as displayed for the 'ruler' option.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00006674 The format of this option is like that of 'statusline'.
Bram Moolenaar110289e2019-05-23 15:38:06 +02006675 This option cannot be set in a modeline when 'modelineexpr' is off.
6676
Bram Moolenaar071d4272004-06-13 20:20:40 +00006677 The default ruler width is 17 characters. To make the ruler 15
6678 characters wide, put "%15(" at the start and "%)" at the end.
6679 Example: >
6680 :set rulerformat=%15(%c%V\ %p%%%)
6681<
6682 *'runtimepath'* *'rtp'* *vimfiles*
6683'runtimepath' 'rtp' string (default:
Bram Moolenaar942db232021-02-13 18:14:48 +01006684 Unix: "$HOME/.vim,
Bram Moolenaar071d4272004-06-13 20:20:40 +00006685 $VIM/vimfiles,
6686 $VIMRUNTIME,
6687 $VIM/vimfiles/after,
6688 $HOME/.vim/after"
6689 Amiga: "home:vimfiles,
6690 $VIM/vimfiles,
6691 $VIMRUNTIME,
6692 $VIM/vimfiles/after,
6693 home:vimfiles/after"
Bram Moolenaar942db232021-02-13 18:14:48 +01006694 MS-Windows: "$HOME/vimfiles,
Bram Moolenaar071d4272004-06-13 20:20:40 +00006695 $VIM/vimfiles,
6696 $VIMRUNTIME,
6697 $VIM/vimfiles/after,
6698 $HOME/vimfiles/after"
Bram Moolenaar3d1cde82020-08-15 18:55:18 +02006699 macOS: "$VIM:vimfiles,
Bram Moolenaar071d4272004-06-13 20:20:40 +00006700 $VIMRUNTIME,
6701 $VIM:vimfiles:after"
Bram Moolenaarb3f74062020-02-26 16:16:53 +01006702 Haiku: "$BE_USER_SETTINGS/vim,
6703 $VIM/vimfiles,
6704 $VIMRUNTIME,
6705 $VIM/vimfiles/after,
Bram Moolenaar942db232021-02-13 18:14:48 +01006706 $BE_USER_SETTINGS/vim/after"
6707 VMS: "sys$login:vimfiles,
Bram Moolenaar071d4272004-06-13 20:20:40 +00006708 $VIM/vimfiles,
6709 $VIMRUNTIME,
6710 $VIM/vimfiles/after,
Bram Moolenaar582fd852005-03-28 20:58:01 +00006711 sys$login:vimfiles/after")
Bram Moolenaar071d4272004-06-13 20:20:40 +00006712 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006713 This is a list of directories which will be searched for runtime
6714 files:
6715 filetype.vim filetypes by file name |new-filetype|
6716 scripts.vim filetypes by file contents |new-filetype-scripts|
Bram Moolenaar4399ef42005-02-12 14:29:27 +00006717 autoload/ automatically loaded scripts |autoload-functions|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006718 colors/ color scheme files |:colorscheme|
6719 compiler/ compiler files |:compiler|
6720 doc/ documentation |write-local-help|
6721 ftplugin/ filetype plugins |write-filetype-plugin|
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01006722 import/ files that are found by `:import`
Bram Moolenaar071d4272004-06-13 20:20:40 +00006723 indent/ indent scripts |indent-expression|
6724 keymap/ key mapping files |mbyte-keymap|
6725 lang/ menu translations |:menutrans|
6726 menu.vim GUI menus |menu.vim|
Bram Moolenaar26852122016-05-24 20:02:38 +02006727 pack/ packages |:packadd|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006728 plugin/ plugin scripts |write-plugin|
6729 print/ files for printing |postscript-print-encoding|
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +00006730 spell/ spell checking files |spell|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006731 syntax/ syntax files |mysyntaxfile|
6732 tutor/ files for vimtutor |tutor|
6733
6734 And any other file searched for with the |:runtime| command.
6735
6736 The defaults for most systems are setup to search five locations:
6737 1. In your home directory, for your personal preferences.
6738 2. In a system-wide Vim directory, for preferences from the system
6739 administrator.
6740 3. In $VIMRUNTIME, for files distributed with Vim.
6741 *after-directory*
6742 4. In the "after" directory in the system-wide Vim directory. This is
6743 for the system administrator to overrule or add to the distributed
6744 defaults (rarely needed)
6745 5. In the "after" directory in your home directory. This is for
6746 personal preferences to overrule or add to the distributed defaults
6747 or system-wide settings (rarely needed).
6748
Bram Moolenaard0796902016-09-16 20:02:31 +02006749 More entries are added when using |packages|. If it gets very long
6750 then `:set rtp` will be truncated, use `:echo &rtp` to see the full
6751 string.
Bram Moolenaar26852122016-05-24 20:02:38 +02006752
Bram Moolenaar071d4272004-06-13 20:20:40 +00006753 Note that, unlike 'path', no wildcards like "**" are allowed. Normal
6754 wildcards are allowed, but can significantly slow down searching for
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006755 runtime files. For speed, use as few items as possible and avoid
Bram Moolenaar071d4272004-06-13 20:20:40 +00006756 wildcards.
6757 See |:runtime|.
6758 Example: >
6759 :set runtimepath=~/vimruntime,/mygroup/vim,$VIMRUNTIME
6760< This will use the directory "~/vimruntime" first (containing your
6761 personal Vim runtime files), then "/mygroup/vim" (shared between a
6762 group of people) and finally "$VIMRUNTIME" (the distributed runtime
6763 files).
6764 You probably should always include $VIMRUNTIME somewhere, to use the
6765 distributed runtime files. You can put a directory before $VIMRUNTIME
6766 to find files which replace a distributed runtime files. You can put
6767 a directory after $VIMRUNTIME to find files which add to distributed
6768 runtime files.
Bram Moolenaarb5b75622018-03-09 22:22:21 +01006769 When Vim is started with |--clean| the home directory entries are not
6770 included.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006771 This option cannot be set from a |modeline| or in the |sandbox|, for
6772 security reasons.
6773
6774 *'scroll'* *'scr'*
6775'scroll' 'scr' number (default: half the window height)
Christian Brabandt596ad662023-08-16 00:11:09 +02006776 local to window |local-noglobal|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006777 Number of lines to scroll with CTRL-U and CTRL-D commands. Will be
6778 set to half the number of lines in the window when the window size
Bram Moolenaar74667062020-12-28 15:41:41 +01006779 changes. This may happen when enabling the |status-line| or
6780 'tabline' option after setting the 'scroll' option.
6781 If you give a count to the CTRL-U or CTRL-D command it will
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006782 be used as the new value for 'scroll'. Reset to half the window
Bram Moolenaar25c9c682019-05-05 18:13:34 +02006783 height with ":set scroll=0".
Bram Moolenaar071d4272004-06-13 20:20:40 +00006784
6785 *'scrollbind'* *'scb'* *'noscrollbind'* *'noscb'*
6786'scrollbind' 'scb' boolean (default off)
6787 local to window
zeertzjq5277cfa2023-09-28 01:00:12 +08006788 See also |scroll-binding|. When this option is set, scrolling the
6789 current window also scrolls other scrollbind windows (windows that
6790 also have this option set). This option is useful for viewing the
Bram Moolenaar071d4272004-06-13 20:20:40 +00006791 differences between two versions of a file, see 'diff'.
6792 See |'scrollopt'| for options that determine how this option should be
6793 interpreted.
6794 This option is mostly reset when splitting a window to edit another
6795 file. This means that ":split | edit file" results in two windows
6796 with scroll-binding, but ":split file" does not.
6797
Bram Moolenaarae20f342019-11-05 21:09:23 +01006798 *'scrollfocus'* *'scf'* *'noscrollfocus'* *'noscf'*
6799'scrollfocus' 'scf' boolean (default off)
6800 global
6801 {only for MS-Windows GUI}
6802 When using the scroll wheel and this option is set, the window under
6803 the mouse pointer is scrolled. With this option off the current
6804 window is scrolled.
Bram Moolenaar5ef1c6a2019-11-10 22:09:11 +01006805 Systems other than MS-Windows always behave like this option is on.
Bram Moolenaarae20f342019-11-05 21:09:23 +01006806
Bram Moolenaar071d4272004-06-13 20:20:40 +00006807 *'scrolljump'* *'sj'*
6808'scrolljump' 'sj' number (default 1)
6809 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006810 Minimal number of lines to scroll when the cursor gets off the
6811 screen (e.g., with "j"). Not used for scroll commands (e.g., CTRL-E,
6812 CTRL-D). Useful if your terminal scrolls very slowly.
Bram Moolenaar1e015462005-09-25 22:16:38 +00006813 When set to a negative number from -1 to -100 this is used as the
6814 percentage of the window height. Thus -50 scrolls half the window
6815 height.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006816 NOTE: This option is set to 1 when 'compatible' is set.
6817
6818 *'scrolloff'* *'so'*
Bram Moolenaar50ba5262016-09-22 22:33:02 +02006819'scrolloff' 'so' number (default 0, set to 5 in |defaults.vim|)
Bram Moolenaar375e3392019-01-31 18:26:10 +01006820 global or local to window |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006821 Minimal number of screen lines to keep above and below the cursor.
6822 This will make some context visible around where you are working. If
6823 you set it to a very large value (999) the cursor line will always be
6824 in the middle of the window (except at the start or end of the file or
6825 when long lines wrap).
Bram Moolenaar375e3392019-01-31 18:26:10 +01006826 After using the local value, go back the global value with one of
6827 these two: >
6828 setlocal scrolloff<
6829 setlocal scrolloff=-1
6830< For scrolling horizontally see 'sidescrolloff'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006831 NOTE: This option is set to 0 when 'compatible' is set.
6832
6833 *'scrollopt'* *'sbo'*
6834'scrollopt' 'sbo' string (default "ver,jump")
6835 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006836 This is a comma-separated list of words that specifies how
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006837 'scrollbind' windows should behave. 'sbo' stands for ScrollBind
6838 Options.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006839 The following words are available:
6840 ver Bind vertical scrolling for 'scrollbind' windows
6841 hor Bind horizontal scrolling for 'scrollbind' windows
6842 jump Applies to the offset between two windows for vertical
6843 scrolling. This offset is the difference in the first
6844 displayed line of the bound windows. When moving
6845 around in a window, another 'scrollbind' window may
6846 reach a position before the start or after the end of
6847 the buffer. The offset is not changed though, when
6848 moving back the 'scrollbind' window will try to scroll
6849 to the desired position when possible.
6850 When now making that window the current one, two
6851 things can be done with the relative offset:
6852 1. When "jump" is not included, the relative offset is
6853 adjusted for the scroll position in the new current
6854 window. When going back to the other window, the
Bram Moolenaar02467872007-05-06 13:22:01 +00006855 new relative offset will be used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006856 2. When "jump" is included, the other windows are
6857 scrolled to keep the same relative offset. When
6858 going back to the other window, it still uses the
6859 same relative offset.
6860 Also see |scroll-binding|.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006861 When 'diff' mode is active there always is vertical scroll binding,
6862 even when "ver" isn't there.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006863
6864 *'sections'* *'sect'*
6865'sections' 'sect' string (default "SHNHH HUnhsh")
6866 global
6867 Specifies the nroff macros that separate sections. These are pairs of
6868 two letters (See |object-motions|). The default makes a section start
6869 at the nroff macros ".SH", ".NH", ".H", ".HU", ".nh" and ".sh".
6870
6871 *'secure'* *'nosecure'* *E523*
6872'secure' boolean (default off)
6873 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006874 When on, ":autocmd", shell and write commands are not allowed in
6875 ".vimrc" and ".exrc" in the current directory and map commands are
6876 displayed. Switch it off only if you know that you will not run into
6877 problems, or when the 'exrc' option is off. On Unix this option is
6878 only used if the ".vimrc" or ".exrc" is not owned by you. This can be
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006879 dangerous if the systems allows users to do a "chown". You better set
Bram Moolenaar071d4272004-06-13 20:20:40 +00006880 'secure' at the end of your ~/.vimrc then.
6881 This option cannot be set from a |modeline| or in the |sandbox|, for
6882 security reasons.
6883
6884 *'selection'* *'sel'*
6885'selection' 'sel' string (default "inclusive")
6886 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006887 This option defines the behavior of the selection. It is only used
6888 in Visual and Select mode.
6889 Possible values:
6890 value past line inclusive ~
6891 old no yes
6892 inclusive yes yes
6893 exclusive yes no
6894 "past line" means that the cursor is allowed to be positioned one
6895 character past the line.
6896 "inclusive" means that the last character of the selection is included
6897 in an operation. For example, when "x" is used to delete the
6898 selection.
Bram Moolenaare4a3bcf2016-08-26 19:52:37 +02006899 When "old" is used and 'virtualedit' allows the cursor to move past
6900 the end of line the line break still isn't included.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006901 Note that when "exclusive" is used and selecting from the end
6902 backwards, you cannot include the last character of a line, when
6903 starting in Normal mode and 'virtualedit' empty.
6904
6905 The 'selection' option is set by the |:behave| command.
6906
6907 *'selectmode'* *'slm'*
6908'selectmode' 'slm' string (default "")
6909 global
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01006910 This is a comma-separated list of words, which specifies when to start
Bram Moolenaar071d4272004-06-13 20:20:40 +00006911 Select mode instead of Visual mode, when a selection is started.
6912 Possible values:
6913 mouse when using the mouse
6914 key when using shifted special keys
6915 cmd when using "v", "V" or CTRL-V
6916 See |Select-mode|.
6917 The 'selectmode' option is set by the |:behave| command.
6918
6919 *'sessionoptions'* *'ssop'*
6920'sessionoptions' 'ssop' string (default: "blank,buffers,curdir,folds,
Bram Moolenaarb5b75622018-03-09 22:22:21 +01006921 help,options,tabpages,winsize,terminal")
Bram Moolenaar071d4272004-06-13 20:20:40 +00006922 global
Bram Moolenaardb84e452010-08-15 13:50:43 +02006923 {not available when compiled without the |+mksession|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006924 feature}
6925 Changes the effect of the |:mksession| command. It is a comma
6926 separated list of words. Each word enables saving and restoring
6927 something:
6928 word save and restore ~
6929 blank empty windows
6930 buffers hidden and unloaded buffers, not just those in windows
6931 curdir the current directory
6932 folds manually created folds, opened/closed folds and local
6933 fold options
6934 globals global variables that start with an uppercase letter
Bram Moolenaar12805862005-01-05 22:16:17 +00006935 and contain at least one lowercase letter. Only
6936 String and Number types are stored.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006937 help the help window
6938 localoptions options and mappings local to a window or buffer (not
6939 global values for local options)
6940 options all options and mappings (also global values for local
6941 options)
Bram Moolenaard23b7142021-04-17 21:04:34 +02006942 skiprtp exclude 'runtimepath' and 'packpath' from the options
Bram Moolenaar071d4272004-06-13 20:20:40 +00006943 resize size of the Vim window: 'lines' and 'columns'
6944 sesdir the directory in which the session file is located
6945 will become the current directory (useful with
6946 projects accessed over a network from different
6947 systems)
6948 slash backslashes in file names replaced with forward
6949 slashes
Bram Moolenaar18144c82006-04-12 21:52:12 +00006950 tabpages all tab pages; without this only the current tab page
6951 is restored, so that you can make a session for each
6952 tab page separately
Bram Moolenaard473c8c2018-08-11 18:00:22 +02006953 terminal include terminal windows where the command can be
6954 restored
Bram Moolenaar071d4272004-06-13 20:20:40 +00006955 unix with Unix end-of-line format (single <NL>), even when
6956 on Windows or DOS
6957 winpos position of the whole Vim window
6958 winsize window sizes
6959
6960 Don't include both "curdir" and "sesdir".
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006961 When neither "curdir" nor "sesdir" is included, file names are stored
6962 with absolute paths.
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00006963 If you leave out "options" many things won't work well after restoring
6964 the session.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006965 "slash" and "unix" are useful on Windows when sharing session files
6966 with Unix. The Unix version of Vim cannot source dos format scripts,
6967 but the Windows version of Vim can source unix format scripts.
6968
6969 *'shell'* *'sh'* *E91*
Bram Moolenaar95a9dd12019-12-19 22:12:03 +01006970'shell' 'sh' string (default $SHELL or "sh", Win32: "cmd.exe")
Bram Moolenaar071d4272004-06-13 20:20:40 +00006971 global
6972 Name of the shell to use for ! and :! commands. When changing the
6973 value also check these options: 'shelltype', 'shellpipe', 'shellslash'
6974 'shellredir', 'shellquote', 'shellxquote' and 'shellcmdflag'.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006975 It is allowed to give an argument to the command, e.g. "csh -f".
Bram Moolenaar071d4272004-06-13 20:20:40 +00006976 See |option-backslash| about including spaces and backslashes.
6977 Environment variables are expanded |:set_env|.
Bram Moolenaar4bfa8af2018-02-03 15:14:46 +01006978
Bram Moolenaara2baa732022-02-04 16:09:54 +00006979 In |restricted-mode| shell commands will not be possible. This mode
6980 is used if the value of $SHELL ends in "false" or "nologin".
6981
Bram Moolenaar1ff14ba2019-11-02 14:09:23 +01006982 If the name of the shell contains a space, you need to enclose it in
Bram Moolenaar5ef1c6a2019-11-10 22:09:11 +01006983 quotes and escape the space. Example with quotes: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006984 :set shell=\"c:\program\ files\unix\sh.exe\"\ -f
6985< Note the backslash before each quote (to avoid starting a comment) and
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006986 each space (to avoid ending the option value). Also note that the
Bram Moolenaar071d4272004-06-13 20:20:40 +00006987 "-f" is not inside the quotes, because it is not part of the command
Bram Moolenaar4bfa8af2018-02-03 15:14:46 +01006988 name. Vim automagically recognizes the backslashes that are path
Bram Moolenaar071d4272004-06-13 20:20:40 +00006989 separators.
Bram Moolenaar4bfa8af2018-02-03 15:14:46 +01006990 Example with escaped space (Vim will do this when initializing the
6991 option from $SHELL): >
6992 :set shell=/bin/with\\\ space/sh
Bram Moolenaard473c8c2018-08-11 18:00:22 +02006993< The resulting value of 'shell' is "/bin/with\ space/sh", two
Bram Moolenaar4bfa8af2018-02-03 15:14:46 +01006994 backslashes are consumed by `:set`.
6995
Bram Moolenaar071d4272004-06-13 20:20:40 +00006996 Under MS-Windows, when the executable ends in ".com" it must be
6997 included. Thus setting the shell to "command.com" or "4dos.com"
6998 works, but "command" and "4dos" do not work for all commands (e.g.,
6999 filtering).
7000 For unknown reasons, when using "4dos.com" the current directory is
7001 changed to "C:\". To avoid this set 'shell' like this: >
7002 :set shell=command.com\ /c\ 4dos
7003< This option cannot be set from a |modeline| or in the |sandbox|, for
7004 security reasons.
7005
7006 *'shellcmdflag'* *'shcf'*
Bram Moolenaar5dc62522012-02-13 00:05:22 +01007007'shellcmdflag' 'shcf' string (default: "-c";
Mike Williams12795022021-06-28 20:53:58 +02007008 Win32, when 'shell' contains "powershell":
7009 "-Command", or when it does not contain "sh"
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01007010 somewhere: "/c")
Bram Moolenaar071d4272004-06-13 20:20:40 +00007011 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007012 Flag passed to the shell to execute "!" and ":!" commands; e.g.,
Mike Williams12795022021-06-28 20:53:58 +02007013 "bash.exe -c ls", "powershell.exe -Command dir", or "cmd.exe /c dir".
7014 For MS-Windows, the default is set according to the value of 'shell',
7015 to reduce the need to set this option by the user.
Bram Moolenaar5302d9e2011-09-14 17:55:08 +02007016 On Unix it can have more than one flag. Each white space separated
7017 part is passed as an argument to the shell command.
7018 See |option-backslash| about including spaces and backslashes.
Mike Williams12795022021-06-28 20:53:58 +02007019 Also see |dos-shell| and |dos-powershell| for MS-Windows.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007020 This option cannot be set from a |modeline| or in the |sandbox|, for
7021 security reasons.
7022
7023 *'shellpipe'* *'sp'*
Mike Williams12795022021-06-28 20:53:58 +02007024'shellpipe' 'sp' string (default ">", ">%s 2>&1", "| tee", "|& tee"
7025 "2>&1| tee", or
7026 "2>&1 | Out-File -Encoding default")
Bram Moolenaar071d4272004-06-13 20:20:40 +00007027 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007028 {not available when compiled without the |+quickfix|
7029 feature}
7030 String to be used to put the output of the ":make" command in the
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007031 error file. See also |:make_makeprg|. See |option-backslash| about
Bram Moolenaar071d4272004-06-13 20:20:40 +00007032 including spaces and backslashes.
7033 The name of the temporary file can be represented by "%s" if necessary
7034 (the file name is appended automatically if no %s appears in the value
7035 of this option).
Mike Williams12795022021-06-28 20:53:58 +02007036 For the Amiga the default is ">". For MS-Windows using powershell the
7037 default is "2>&1 | Out-File -Encoding default", otherwise the default
7038 is ">%s 2>&1". The output is directly saved in a file and not echoed
7039 to the screen.
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02007040 For Unix the default is "| tee". The stdout of the compiler is saved
Bram Moolenaar071d4272004-06-13 20:20:40 +00007041 in a file and echoed to the screen. If the 'shell' option is "csh" or
7042 "tcsh" after initializations, the default becomes "|& tee". If the
Bram Moolenaar96f45c02019-10-26 19:53:45 +02007043 'shell' option is "sh", "ksh", "mksh", "pdksh", "zsh", "zsh-beta",
Natanael Copa56318362021-05-06 18:46:35 +02007044 "bash", "fish", "ash" or "dash" the default becomes "2>&1| tee". This
7045 means that stderr is also included. Before using the 'shell' option a
7046 path is removed, thus "/bin/sh" uses "sh".
Mike Williamsa3d1b292021-06-30 20:56:00 +02007047 For Unix and MS-Windows, when the 'shell' option is "pwsh" the default
7048 becomes ">%s 2>&1" and the output is not echoed to the screen.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007049 The initialization of this option is done after reading the ".vimrc"
7050 and the other initializations, so that when the 'shell' option is set
7051 there, the 'shellpipe' option changes automatically, unless it was
7052 explicitly set before.
7053 When 'shellpipe' is set to an empty string, no redirection of the
7054 ":make" output will be done. This is useful if you use a 'makeprg'
7055 that writes to 'makeef' by itself. If you want no piping, but do
7056 want to include the 'makeef', set 'shellpipe' to a single space.
7057 Don't forget to precede the space with a backslash: ":set sp=\ ".
7058 In the future pipes may be used for filtering and this option will
7059 become obsolete (at least for Unix).
7060 This option cannot be set from a |modeline| or in the |sandbox|, for
7061 security reasons.
7062
7063 *'shellquote'* *'shq'*
Mike Williamsa3d1b292021-06-30 20:56:00 +02007064'shellquote' 'shq' string (default: "")
Bram Moolenaar071d4272004-06-13 20:20:40 +00007065 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007066 Quoting character(s), put around the command passed to the shell, for
7067 the "!" and ":!" commands. The redirection is kept outside of the
7068 quoting. See 'shellxquote' to include the redirection. It's
7069 probably not useful to set both options.
7070 This is an empty string by default. Only known to be useful for
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01007071 third-party shells on MS-Windows-like systems, such as the MKS Korn
Mike Williamsa3d1b292021-06-30 20:56:00 +02007072 Shell or bash, where it should be "\"". See |dos-shell|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007073 This option cannot be set from a |modeline| or in the |sandbox|, for
7074 security reasons.
7075
7076 *'shellredir'* *'srr'*
Mike Williams12795022021-06-28 20:53:58 +02007077'shellredir' 'srr' string (default ">", ">&", ">%s 2>&1", or
7078 "2>&1 | Out-File -Encoding default")
Bram Moolenaar071d4272004-06-13 20:20:40 +00007079 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007080 String to be used to put the output of a filter command in a temporary
7081 file. See also |:!|. See |option-backslash| about including spaces
7082 and backslashes.
7083 The name of the temporary file can be represented by "%s" if necessary
7084 (the file name is appended automatically if no %s appears in the value
7085 of this option).
Bram Moolenaar96f45c02019-10-26 19:53:45 +02007086 The default is ">". For Unix, if the 'shell' option is "csh" or
7087 "tcsh" during initializations, the default becomes ">&". If the
Bram Moolenaar0c0734d2019-11-26 21:44:46 +01007088 'shell' option is "sh", "ksh", "mksh", "pdksh", "zsh", "zsh-beta",
Mike Williamsa3d1b292021-06-30 20:56:00 +02007089 "bash", "fish", or "pwsh", the default becomes ">%s 2>&1". This means
7090 that stderr is also included. For Win32, the Unix checks are done and
Mike Williams12795022021-06-28 20:53:58 +02007091 additionally "cmd" is checked for, which makes the default ">%s 2>&1",
7092 and "powershell" is checked for which makes the default
Mike Williamsa3d1b292021-06-30 20:56:00 +02007093 "2>&1 | Out-File -Encoding default" (see |dos-powershell|). Also, the
7094 same names with ".exe" appended are checked for.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007095 The initialization of this option is done after reading the ".vimrc"
7096 and the other initializations, so that when the 'shell' option is set
7097 there, the 'shellredir' option changes automatically unless it was
7098 explicitly set before.
7099 In the future pipes may be used for filtering and this option will
7100 become obsolete (at least for Unix).
7101 This option cannot be set from a |modeline| or in the |sandbox|, for
7102 security reasons.
7103
7104 *'shellslash'* *'ssl'* *'noshellslash'* *'nossl'*
7105'shellslash' 'ssl' boolean (default off)
7106 global
Bram Moolenaar6f345a12019-12-17 21:27:18 +01007107 {only for MS-Windows}
Bram Moolenaar071d4272004-06-13 20:20:40 +00007108 When set, a forward slash is used when expanding file names. This is
Mike Williamsa3d1b292021-06-30 20:56:00 +02007109 useful when a Unix-like shell is used instead of cmd.exe, pwsh.exe, or
Mike Williams12795022021-06-28 20:53:58 +02007110 powershell.exe. Backward slashes can still be typed, but they are
7111 changed to forward slashes by Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007112 Note that setting or resetting this option has no effect for some
7113 existing file names, thus this option needs to be set before opening
7114 any file for best results. This might change in the future.
7115 'shellslash' only works when a backslash can be used as a path
7116 separator. To test if this is so use: >
7117 if exists('+shellslash')
Bram Moolenaarac3150d2019-07-28 16:36:39 +02007118< Also see 'completeslash'.
7119
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007120 *'shelltemp'* *'stmp'* *'noshelltemp'* *'nostmp'*
7121'shelltemp' 'stmp' boolean (Vi default off, Vim default on)
7122 global
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007123 When on, use temp files for shell commands. When off use a pipe.
7124 When using a pipe is not possible temp files are used anyway.
Bram Moolenaar97293012011-07-18 19:40:27 +02007125 Currently a pipe is only supported on Unix and MS-Windows 2K and
7126 later. You can check it with: >
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007127 :if has("filterpipe")
7128< The advantage of using a pipe is that nobody can read the temp file
7129 and the 'shell' command does not need to support redirection.
7130 The advantage of using a temp file is that the file type and encoding
7131 can be detected.
7132 The |FilterReadPre|, |FilterReadPost| and |FilterWritePre|,
7133 |FilterWritePost| autocommands event are not triggered when
7134 'shelltemp' is off.
Bram Moolenaar269f5952016-07-15 22:54:41 +02007135 The `system()` function does not respect this option and always uses
7136 temp files.
Bram Moolenaar036986f2017-03-16 17:41:02 +01007137 NOTE: This option is set to the Vim default value when 'compatible'
7138 is reset.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007139
Bram Moolenaar071d4272004-06-13 20:20:40 +00007140 *'shelltype'* *'st'*
7141'shelltype' 'st' number (default 0)
7142 global
Bram Moolenaar6c60f472019-04-28 16:00:35 +02007143 {only for the Amiga}
Bram Moolenaar071d4272004-06-13 20:20:40 +00007144 On the Amiga this option influences the way how the commands work
7145 which use a shell.
7146 0 and 1: always use the shell
7147 2 and 3: use the shell only to filter lines
7148 4 and 5: use shell only for ':sh' command
7149 When not using the shell, the command is executed directly.
7150
7151 0 and 2: use "shell 'shellcmdflag' cmd" to start external commands
7152 1 and 3: use "shell cmd" to start external commands
7153
Bram Moolenaardb7207e2012-02-22 17:30:19 +01007154 *'shellxescape'* *'sxe'*
7155'shellxescape' 'sxe' string (default: "";
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01007156 for MS-Windows: "\"&|<>()@^")
Bram Moolenaardb7207e2012-02-22 17:30:19 +01007157 global
Bram Moolenaardb7207e2012-02-22 17:30:19 +01007158 When 'shellxquote' is set to "(" then the characters listed in this
7159 option will be escaped with a '^' character. This makes it possible
7160 to execute most external commands with cmd.exe.
7161
Bram Moolenaar071d4272004-06-13 20:20:40 +00007162 *'shellxquote'* *'sxq'*
7163'shellxquote' 'sxq' string (default: "";
Bram Moolenaarf66b3fc2012-02-20 22:18:30 +01007164 for Win32, when 'shell' is cmd.exe: "("
Mike Williams12795022021-06-28 20:53:58 +02007165 for Win32, when 'shell' is
7166 powershell.exe: "\""
Bram Moolenaarf66b3fc2012-02-20 22:18:30 +01007167 for Win32, when 'shell' contains "sh"
7168 somewhere: "\""
Bram Moolenaar071d4272004-06-13 20:20:40 +00007169 for Unix, when using system(): "\"")
7170 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007171 Quoting character(s), put around the command passed to the shell, for
7172 the "!" and ":!" commands. Includes the redirection. See
7173 'shellquote' to exclude the redirection. It's probably not useful
7174 to set both options.
Bram Moolenaarf66b3fc2012-02-20 22:18:30 +01007175 When the value is '(' then ')' is appended. When the value is '"('
7176 then ')"' is appended.
7177 When the value is '(' then also see 'shellxescape'.
Bram Moolenaara64ba222012-02-12 23:23:31 +01007178 This is an empty string by default on most systems, but is known to be
Mike Williamsa3d1b292021-06-30 20:56:00 +02007179 useful for on Win32 version, either for cmd.exe, powershell.exe, or
7180 pwsh.exe which automatically strips off the first and last quote on a
7181 command, or 3rd-party shells such as the MKS Korn Shell or bash, where
7182 it should be "\"". The default is adjusted according the value of
Mike Williams12795022021-06-28 20:53:58 +02007183 'shell', to reduce the need to set this option by the user. See
7184 |dos-shell|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007185 This option cannot be set from a |modeline| or in the |sandbox|, for
7186 security reasons.
7187
7188 *'shiftround'* *'sr'* *'noshiftround'* *'nosr'*
7189'shiftround' 'sr' boolean (default off)
7190 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007191 Round indent to multiple of 'shiftwidth'. Applies to > and <
7192 commands. CTRL-T and CTRL-D in Insert mode always round the indent to
7193 a multiple of 'shiftwidth' (this is Vi compatible).
7194 NOTE: This option is reset when 'compatible' is set.
7195
7196 *'shiftwidth'* *'sw'*
7197'shiftwidth' 'sw' number (default 8)
7198 local to buffer
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007199 Number of spaces to use for each step of (auto)indent. Used for
Bram Moolenaar071d4272004-06-13 20:20:40 +00007200 |'cindent'|, |>>|, |<<|, etc.
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01007201 When zero the 'tabstop' value will be used. Use the |shiftwidth()|
Bram Moolenaar3a0d8092012-10-21 03:02:54 +02007202 function to get the effective shiftwidth value.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007203
7204 *'shortmess'* *'shm'*
Bram Moolenaar9dfa3132019-05-04 21:08:40 +02007205'shortmess' 'shm' string (Vim default "filnxtToOS", Vi default: "S",
7206 POSIX default: "AS")
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00007207 global *E1336*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007208 This option helps to avoid all the |hit-enter| prompts caused by file
7209 messages, for example with CTRL-G, and to avoid some other messages.
7210 It is a list of flags:
7211 flag meaning when present ~
Bram Moolenaar7db29e42022-12-11 15:53:04 +00007212 f use "(3 of 5)" instead of "(file 3 of 5)" *shm-f*
7213 i use "[noeol]" instead of "[Incomplete last line]" *shm-i*
7214 l use "999L, 888B" instead of "999 lines, 888 bytes" *shm-l*
7215 m use "[+]" instead of "[Modified]" *shm-m*
7216 n use "[New]" instead of "[New File]" *shm-n*
7217 r use "[RO]" instead of "[readonly]" *shm-r*
7218 w use "[w]" instead of "written" for file write message *shm-w*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007219 and "[a]" instead of "appended" for ':w >> file' command
Bram Moolenaar7db29e42022-12-11 15:53:04 +00007220 x use "[dos]" instead of "[dos format]", "[unix]" *shm-x*
7221 instead of "[unix format]" and "[mac]" instead of "[mac
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00007222 format]"
Bram Moolenaar7db29e42022-12-11 15:53:04 +00007223 a all of the above abbreviations *shm-a*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007224
Bram Moolenaar7db29e42022-12-11 15:53:04 +00007225 o overwrite message for writing a file with subsequent *shm-o*
7226 message for reading a file (useful for ":wn" or when
7227 'autowrite' on)
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00007228 O message for reading a file overwrites any previous *shm-O*
7229 message; also for quickfix message (e.g., ":cn")
Bram Moolenaar7db29e42022-12-11 15:53:04 +00007230 s don't give "search hit BOTTOM, continuing at TOP" or *shm-s*
7231 "search hit TOP, continuing at BOTTOM" messages; when using
7232 the search count do not show "W" after the count message (see
7233 S below)
7234 t truncate file message at the start if it is too long *shm-t*
7235 to fit on the command-line, "<" will appear in the left most
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00007236 column; ignored in Ex mode
Bram Moolenaar7db29e42022-12-11 15:53:04 +00007237 T truncate other messages in the middle if they are too *shm-T*
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00007238 long to fit on the command line; "..." will appear in the
7239 middle; ignored in Ex mode
Bram Moolenaar7db29e42022-12-11 15:53:04 +00007240 W don't give "written" or "[w]" when writing a file *shm-W*
7241 A don't give the "ATTENTION" message when an existing *shm-A*
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00007242 swap file is found
Bram Moolenaar7db29e42022-12-11 15:53:04 +00007243 I don't give the intro message when starting Vim, *shm-I*
Bram Moolenaar938ae282023-02-20 20:44:55 +00007244 see |:intro|
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00007245 c don't give |ins-completion-menu| messages; for *shm-c*
Bram Moolenaar7db29e42022-12-11 15:53:04 +00007246 example, "-- XXX completion (YYY)", "match 1 of 2", "The only
7247 match", "Pattern not found", "Back at original", etc.
7248 C don't give messages while scanning for ins-completion *shm-C*
7249 items, for instance "scanning tags"
7250 q use "recording" instead of "recording @a" *shm-q*
7251 F don't give the file info when editing a file, like *shm-F*
7252 `:silent` was used for the command; note that this also
7253 affects messages from autocommands
Bram Moolenaar938ae282023-02-20 20:44:55 +00007254 S do not show search count message when searching, e.g. *shm-S*
7255 "[1/5]"
Bram Moolenaar071d4272004-06-13 20:20:40 +00007256
7257 This gives you the opportunity to avoid that a change between buffers
7258 requires you to hit <Enter>, but still gives as useful a message as
7259 possible for the space available. To get the whole message that you
7260 would have got with 'shm' empty, use ":file!"
7261 Useful values:
7262 shm= No abbreviation of message.
7263 shm=a Abbreviation, but no loss of information.
7264 shm=at Abbreviation, and truncate message when necessary.
7265
7266 NOTE: This option is set to the Vi default value when 'compatible' is
7267 set and to the Vim default value when 'compatible' is reset.
7268
7269 *'shortname'* *'sn'* *'noshortname'* *'nosn'*
7270'shortname' 'sn' boolean (default off)
7271 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00007272 Filenames are assumed to be 8 characters plus one extension of 3
7273 characters. Multiple dots in file names are not allowed. When this
7274 option is on, dots in file names are replaced with underscores when
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01007275 adding an extension (".~" or ".swp"). This option is useful
Bram Moolenaar071d4272004-06-13 20:20:40 +00007276 when editing files on an MS-DOS compatible filesystem, e.g., messydos
Bram Moolenaarade0d392020-01-21 22:33:58 +01007277 or crossdos.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007278
7279 *'showbreak'* *'sbr'* *E595*
7280'showbreak' 'sbr' string (default "")
Bram Moolenaaree857022019-11-09 23:26:40 +01007281 global or local to window |global-local|
Bram Moolenaardb84e452010-08-15 13:50:43 +02007282 {not available when compiled without the |+linebreak|
Bram Moolenaar071d4272004-06-13 20:20:40 +00007283 feature}
7284 String to put at the start of lines that have been wrapped. Useful
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007285 values are "> " or "+++ ": >
7286 :set showbreak=>\
7287< Note the backslash to escape the trailing space. It's easier like
7288 this: >
Bram Moolenaar1a384422010-07-14 19:53:30 +02007289 :let &showbreak = '+++ '
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007290< Only printable single-cell characters are allowed, excluding <Tab> and
Bram Moolenaar071d4272004-06-13 20:20:40 +00007291 comma (in a future version the comma might be used to separate the
7292 part that is shown at the end and at the start of a line).
7293 The characters are highlighted according to the '@' flag in
7294 'highlight'.
7295 Note that tabs after the showbreak will be displayed differently.
7296 If you want the 'showbreak' to appear in between line numbers, add the
7297 "n" flag to 'cpoptions'.
Bram Moolenaaree857022019-11-09 23:26:40 +01007298 A window-local value overrules a global value. If the global value is
7299 set and you want no value in the current window use NONE: >
7300 :setlocal showbreak=NONE
7301<
Bram Moolenaar071d4272004-06-13 20:20:40 +00007302 *'showcmd'* *'sc'* *'noshowcmd'* *'nosc'*
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +02007303'showcmd' 'sc' boolean (Vim default: on, off for Unix,
7304 Vi default: off, set in |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00007305 global
Bram Moolenaar02467872007-05-06 13:22:01 +00007306 Show (partial) command in the last line of the screen. Set this
7307 option off if your terminal is slow.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007308 In Visual mode the size of the selected area is shown:
7309 - When selecting characters within a line, the number of characters.
Bram Moolenaarf91787c2010-07-17 12:47:16 +02007310 If the number of bytes is different it is also displayed: "2-6"
7311 means two characters and six bytes.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007312 - When selecting more than one line, the number of lines.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007313 - When selecting a block, the size in screen characters:
7314 {lines}x{columns}.
Luuk van Baalba936f62022-12-15 13:15:39 +00007315 This information can be displayed in an alternative location using the
7316 'showcmdloc' option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007317 NOTE: This option is set to the Vi default value when 'compatible' is
7318 set and to the Vim default value when 'compatible' is reset.
7319
Luuk van Baalba936f62022-12-15 13:15:39 +00007320 *'showcmdloc'* *'sloc'*
7321'showcmdloc' 'sloc' string (default "last")
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00007322 global
Luuk van Baalba936f62022-12-15 13:15:39 +00007323 This option can be used to display the (partially) entered command in
7324 another location. Possible values are:
7325 last Last line of the screen (default).
7326 statusline Status line of the current window.
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00007327 tabline First line of the screen if 'showtabline' is enabled.
Luuk van Baalba936f62022-12-15 13:15:39 +00007328 Setting this option to "statusline" or "tabline" means that these will
7329 be redrawn whenever the command changes, which can be on every key
7330 pressed.
7331 The %S 'statusline' item can be used in 'statusline' or 'tabline' to
7332 place the text. Without a custom 'statusline' or 'tabline' it will be
7333 displayed in a convenient location.
7334
Bram Moolenaar071d4272004-06-13 20:20:40 +00007335 *'showfulltag'* *'sft'* *'noshowfulltag'* *'nosft'*
7336'showfulltag' 'sft' boolean (default off)
7337 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007338 When completing a word in insert mode (see |ins-completion|) from the
7339 tags file, show both the tag name and a tidied-up form of the search
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007340 pattern (if there is one) as possible matches. Thus, if you have
Bram Moolenaar071d4272004-06-13 20:20:40 +00007341 matched a C function, you can see a template for what arguments are
7342 required (coding style permitting).
Bram Moolenaar446cb832008-06-24 21:56:24 +00007343 Note that this doesn't work well together with having "longest" in
7344 'completeopt', because the completion from the search pattern may not
7345 match the typed text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007346
7347 *'showmatch'* *'sm'* *'noshowmatch'* *'nosm'*
7348'showmatch' 'sm' boolean (default off)
7349 global
7350 When a bracket is inserted, briefly jump to the matching one. The
7351 jump is only done if the match can be seen on the screen. The time to
7352 show the match can be set with 'matchtime'.
7353 A Beep is given if there is no match (no matter if the match can be
Bram Moolenaarca635012015-09-25 20:34:21 +02007354 seen or not).
7355 This option is reset when 'paste' is set and restored when 'paste' is
7356 reset.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007357 When the 'm' flag is not included in 'cpoptions', typing a character
7358 will immediately move the cursor back to where it belongs.
7359 See the "sm" field in 'guicursor' for setting the cursor shape and
7360 blinking when showing the match.
7361 The 'matchpairs' option can be used to specify the characters to show
7362 matches for. 'rightleft' and 'revins' are used to look for opposite
7363 matches.
Bram Moolenaarfd2ac762006-03-01 22:09:21 +00007364 Also see the matchparen plugin for highlighting the match when moving
7365 around |pi_paren.txt|.
7366 Note: Use of the short form is rated PG.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007367
7368 *'showmode'* *'smd'* *'noshowmode'* *'nosmd'*
7369'showmode' 'smd' boolean (Vim default: on, Vi default: off)
7370 global
7371 If in Insert, Replace or Visual mode put a message on the last line.
7372 Use the 'M' flag in 'highlight' to set the type of highlighting for
7373 this message.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007374 When |XIM| may be used the message will include "XIM". But this
Bram Moolenaar071d4272004-06-13 20:20:40 +00007375 doesn't mean XIM is really active, especially when 'imactivatekey' is
7376 not set.
7377 NOTE: This option is set to the Vi default value when 'compatible' is
7378 set and to the Vim default value when 'compatible' is reset.
7379
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00007380 *'showtabline'* *'stal'*
7381'showtabline' 'stal' number (default 1)
7382 global
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00007383 The value of this option specifies when the line with tab page labels
7384 will be displayed:
7385 0: never
7386 1: only if there are at least two tab pages
7387 2: always
7388 This is both for the GUI and non-GUI implementation of the tab pages
7389 line.
7390 See |tab-page| for more information about tab pages.
7391
Bram Moolenaar071d4272004-06-13 20:20:40 +00007392 *'sidescroll'* *'ss'*
7393'sidescroll' 'ss' number (default 0)
7394 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007395 The minimal number of columns to scroll horizontally. Used only when
7396 the 'wrap' option is off and the cursor is moved off of the screen.
7397 When it is zero the cursor will be put in the middle of the screen.
7398 When using a slow terminal set it to a large number or 0. When using
7399 a fast terminal use a small number or 1. Not used for "zh" and "zl"
7400 commands.
7401
7402 *'sidescrolloff'* *'siso'*
7403'sidescrolloff' 'siso' number (default 0)
Bram Moolenaar375e3392019-01-31 18:26:10 +01007404 global or local to window |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00007405 The minimal number of screen columns to keep to the left and to the
Bram Moolenaar482aaeb2005-09-29 18:26:07 +00007406 right of the cursor if 'nowrap' is set. Setting this option to a
7407 value greater than 0 while having |'sidescroll'| also at a non-zero
7408 value makes some context visible in the line you are scrolling in
7409 horizontally (except at beginning of the line). Setting this option
7410 to a large value (like 999) has the effect of keeping the cursor
7411 horizontally centered in the window, as long as one does not come too
7412 close to the beginning of the line.
Bram Moolenaar375e3392019-01-31 18:26:10 +01007413 After using the local value, go back the global value with one of
7414 these two: >
7415 setlocal sidescrolloff<
7416 setlocal sidescrolloff=-1
7417< NOTE: This option is set to 0 when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007418
7419 Example: Try this together with 'sidescroll' and 'listchars' as
7420 in the following example to never allow the cursor to move
Bram Moolenaar95ec9d62016-08-12 18:29:59 +02007421 onto the "extends" character: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00007422
7423 :set nowrap sidescroll=1 listchars=extends:>,precedes:<
7424 :set sidescrolloff=1
Bram Moolenaar95ec9d62016-08-12 18:29:59 +02007425<
7426 *'signcolumn'* *'scl'*
7427'signcolumn' 'scl' string (default "auto")
7428 local to window
Bram Moolenaar95ec9d62016-08-12 18:29:59 +02007429 {not available when compiled without the |+signs|
7430 feature}
Bram Moolenaar09521312016-08-12 22:54:35 +02007431 Whether or not to draw the signcolumn. Valid values are:
Bram Moolenaar938ae282023-02-20 20:44:55 +00007432 "auto" only when there is a sign to display
7433 "no" never
7434 "yes" always
Bram Moolenaar394c5d82019-06-17 21:48:05 +02007435 "number" display signs in the 'number' column. If the number
Bram Moolenaar6c1e1572019-06-22 02:13:00 +02007436 column is not present, then behaves like "auto".
Bram Moolenaar071d4272004-06-13 20:20:40 +00007437
7438
7439 *'smartcase'* *'scs'* *'nosmartcase'* *'noscs'*
7440'smartcase' 'scs' boolean (default off)
7441 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007442 Override the 'ignorecase' option if the search pattern contains upper
7443 case characters. Only used when the search pattern is typed and
7444 'ignorecase' option is on. Used for the commands "/", "?", "n", "N",
Bram Moolenaarc8734422012-06-01 22:38:45 +02007445 ":g" and ":s". Not used for "*", "#", "gd", tag search, etc. After
Bram Moolenaar071d4272004-06-13 20:20:40 +00007446 "*" and "#" you can make 'smartcase' used by doing a "/" command,
7447 recalling the search pattern from history and hitting <Enter>.
7448 NOTE: This option is reset when 'compatible' is set.
7449
7450 *'smartindent'* *'si'* *'nosmartindent'* *'nosi'*
7451'smartindent' 'si' boolean (default off)
7452 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00007453 Do smart autoindenting when starting a new line. Works for C-like
7454 programs, but can also be used for other languages. 'cindent' does
7455 something like this, works better in most cases, but is more strict,
Bram Moolenaar81af9252010-12-10 20:35:50 +01007456 see |C-indenting|. When 'cindent' is on or 'indentexpr' is set,
Bram Moolenaar166af9b2010-11-16 20:34:40 +01007457 setting 'si' has no effect. 'indentexpr' is a more advanced
7458 alternative.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007459 Normally 'autoindent' should also be on when using 'smartindent'.
7460 An indent is automatically inserted:
7461 - After a line ending in '{'.
7462 - After a line starting with a keyword from 'cinwords'.
7463 - Before a line starting with '}' (only with the "O" command).
7464 When typing '}' as the first character in a new line, that line is
7465 given the same indent as the matching '{'.
7466 When typing '#' as the first character in a new line, the indent for
7467 that line is removed, the '#' is put in the first column. The indent
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007468 is restored for the next line. If you don't want this, use this
Bram Moolenaar071d4272004-06-13 20:20:40 +00007469 mapping: ":inoremap # X^H#", where ^H is entered with CTRL-V CTRL-H.
7470 When using the ">>" command, lines starting with '#' are not shifted
7471 right.
Bram Moolenaar036986f2017-03-16 17:41:02 +01007472 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaarca635012015-09-25 20:34:21 +02007473 This option is reset when 'paste' is set and restored when 'paste' is
7474 reset.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007475
7476 *'smarttab'* *'sta'* *'nosmarttab'* *'nosta'*
7477'smarttab' 'sta' boolean (default off)
7478 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007479 When on, a <Tab> in front of a line inserts blanks according to
Bram Moolenaar280f1262006-01-30 00:14:18 +00007480 'shiftwidth'. 'tabstop' or 'softtabstop' is used in other places. A
7481 <BS> will delete a 'shiftwidth' worth of space at the start of the
7482 line.
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +00007483 When off, a <Tab> always inserts blanks according to 'tabstop' or
Bram Moolenaar280f1262006-01-30 00:14:18 +00007484 'softtabstop'. 'shiftwidth' is only used for shifting text left or
7485 right |shift-left-right|.
Bram Moolenaarebcbd022007-05-12 14:28:25 +00007486 What gets inserted (a <Tab> or spaces) depends on the 'expandtab'
Bram Moolenaar071d4272004-06-13 20:20:40 +00007487 option. Also see |ins-expandtab|. When 'expandtab' is not set, the
Bram Moolenaar843ee412004-06-30 16:16:41 +00007488 number of spaces is minimized by using <Tab>s.
Bram Moolenaarca635012015-09-25 20:34:21 +02007489 This option is reset when 'paste' is set and restored when 'paste' is
7490 reset.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007491 NOTE: This option is reset when 'compatible' is set.
7492
Bram Moolenaarf6196f42022-10-02 21:29:55 +01007493 *'smoothscroll'* *'sms'* *'nosmoothscroll'* *'nosms'*
7494'smoothscroll' 'sms' boolean (default off)
7495 local to window
7496 Scrolling works with screen lines. When 'wrap' is set and the first
7497 line in the window wraps part of it may not be visible, as if it is
Bram Moolenaarf269eab2022-10-03 18:04:35 +01007498 above the window. "<<<" is displayed at the start of the first line,
7499 highlighted with |hl-NonText|.
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01007500 You may also want to add "lastline" to the 'display' option to show as
7501 much of the last line as possible.
Bram Moolenaarf269eab2022-10-03 18:04:35 +01007502 NOTE: only partly implemented, currently works with CTRL-E, CTRL-Y
7503 and scrolling with the mouse.
Bram Moolenaarf6196f42022-10-02 21:29:55 +01007504
Bram Moolenaar071d4272004-06-13 20:20:40 +00007505 *'softtabstop'* *'sts'*
7506'softtabstop' 'sts' number (default 0)
7507 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00007508 Number of spaces that a <Tab> counts for while performing editing
7509 operations, like inserting a <Tab> or using <BS>. It "feels" like
7510 <Tab>s are being inserted, while in fact a mix of spaces and <Tab>s is
7511 used. This is useful to keep the 'ts' setting at its standard value
7512 of 8, while being able to edit like it is set to 'sts'. However,
7513 commands like "x" still work on the actual characters.
7514 When 'sts' is zero, this feature is off.
Bram Moolenaar3a0d8092012-10-21 03:02:54 +02007515 When 'sts' is negative, the value of 'shiftwidth' is used.
Bram Moolenaarca635012015-09-25 20:34:21 +02007516 'softtabstop' is set to 0 when the 'paste' option is set and restored
7517 when 'paste' is reset.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007518 See also |ins-expandtab|. When 'expandtab' is not set, the number of
7519 spaces is minimized by using <Tab>s.
7520 The 'L' flag in 'cpoptions' changes how tabs are used when 'list' is
7521 set.
7522 NOTE: This option is set to 0 when 'compatible' is set.
7523
Bram Moolenaar04958cb2018-06-23 19:23:02 +02007524 If Vim is compiled with the |+vartabs| feature then the value of
7525 'softtabstop' will be ignored if |'varsofttabstop'| is set to
7526 anything other than an empty string.
7527
Bram Moolenaar217ad922005-03-20 22:37:15 +00007528 *'spell'* *'nospell'*
7529'spell' boolean (default off)
7530 local to window
Bram Moolenaar217ad922005-03-20 22:37:15 +00007531 {not available when compiled without the |+syntax|
7532 feature}
7533 When on spell checking will be done. See |spell|.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00007534 The languages are specified with 'spelllang'.
Bram Moolenaar217ad922005-03-20 22:37:15 +00007535
Bram Moolenaar0d9c26d2005-07-02 23:19:16 +00007536 *'spellcapcheck'* *'spc'*
Bram Moolenaar0dc065e2005-07-04 22:49:24 +00007537'spellcapcheck' 'spc' string (default "[.?!]\_[\])'" \t]\+")
Bram Moolenaar0d9c26d2005-07-02 23:19:16 +00007538 local to buffer
Bram Moolenaar0d9c26d2005-07-02 23:19:16 +00007539 {not available when compiled without the |+syntax|
7540 feature}
7541 Pattern to locate the end of a sentence. The following word will be
7542 checked to start with a capital letter. If not then it is highlighted
Bram Moolenaar8aff23a2005-08-19 20:40:30 +00007543 with SpellCap |hl-SpellCap| (unless the word is also badly spelled).
Bram Moolenaar0d9c26d2005-07-02 23:19:16 +00007544 When this check is not wanted make this option empty.
7545 Only used when 'spell' is set.
Bram Moolenaar0dc065e2005-07-04 22:49:24 +00007546 Be careful with special characters, see |option-backslash| about
7547 including spaces and backslashes.
Bram Moolenaar90cfdbe2005-08-12 19:59:19 +00007548 To set this option automatically depending on the language, see
7549 |set-spc-auto|.
Bram Moolenaar0d9c26d2005-07-02 23:19:16 +00007550
Bram Moolenaar82cf9b62005-06-07 21:09:25 +00007551 *'spellfile'* *'spf'*
7552'spellfile' 'spf' string (default empty)
7553 local to buffer
Bram Moolenaar82cf9b62005-06-07 21:09:25 +00007554 {not available when compiled without the |+syntax|
7555 feature}
7556 Name of the word list file where words are added for the |zg| and |zw|
Bram Moolenaar045e82d2005-07-08 22:25:33 +00007557 commands. It must end in ".{encoding}.add". You need to include the
7558 path, otherwise the file is placed in the current directory.
Bram Moolenaar48c3f4e2022-08-08 15:42:38 +01007559 The path may include characters from 'isfname', space, comma and '@'.
Bram Moolenaar0d9c26d2005-07-02 23:19:16 +00007560 *E765*
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01007561 It may also be a comma-separated list of names. A count before the
Bram Moolenaar0d9c26d2005-07-02 23:19:16 +00007562 |zg| and |zw| commands can be used to access each. This allows using
7563 a personal word list file and a project word list file.
Bram Moolenaar82cf9b62005-06-07 21:09:25 +00007564 When a word is added while this option is empty Vim will set it for
Bram Moolenaar910f66f2006-04-05 20:41:53 +00007565 you: Using the first directory in 'runtimepath' that is writable. If
7566 there is no "spell" directory yet it will be created. For the file
7567 name the first language name that appears in 'spelllang' is used,
Bram Moolenaar3b506942005-06-23 22:36:45 +00007568 ignoring the region.
7569 The resulting ".spl" file will be used for spell checking, it does not
7570 have to appear in 'spelllang'.
7571 Normally one file is used for all regions, but you can add the region
7572 name if you want to. However, it will then only be used when
7573 'spellfile' is set to it, for entries in 'spelllang' only files
7574 without region name will be found.
Bram Moolenaare7566042005-06-17 22:00:15 +00007575 This option cannot be set from a |modeline| or in the |sandbox|, for
7576 security reasons.
Bram Moolenaar82cf9b62005-06-07 21:09:25 +00007577
Bram Moolenaar217ad922005-03-20 22:37:15 +00007578 *'spelllang'* *'spl'*
Bram Moolenaar82cf9b62005-06-07 21:09:25 +00007579'spelllang' 'spl' string (default "en")
Bram Moolenaar217ad922005-03-20 22:37:15 +00007580 local to buffer
Bram Moolenaar217ad922005-03-20 22:37:15 +00007581 {not available when compiled without the |+syntax|
7582 feature}
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01007583 A comma-separated list of word list names. When the 'spell' option is
Bram Moolenaar3b506942005-06-23 22:36:45 +00007584 on spellchecking will be done for these languages. Example: >
7585 set spelllang=en_us,nl,medical
7586< This means US English, Dutch and medical words are recognized. Words
7587 that are not recognized will be highlighted.
Bram Moolenaar911ead12019-04-21 00:03:35 +02007588 The word list name must consist of alphanumeric characters, a dash or
7589 an underscore. It should not include a comma or dot. Using a dash is
Bram Moolenaar3b506942005-06-23 22:36:45 +00007590 recommended to separate the two letter language name from a
7591 specification. Thus "en-rare" is used for rare English words.
7592 A region name must come last and have the form "_xx", where "xx" is
7593 the two-letter, lower case region name. You can use more than one
7594 region by listing them: "en_us,en_ca" supports both US and Canadian
7595 English, but not words specific for Australia, New Zealand or Great
Bram Moolenaarfa735342016-01-03 22:14:44 +01007596 Britain. (Note: currently en_au and en_nz dictionaries are older than
7597 en_ca, en_gb and en_us).
Bram Moolenaarcc63c642013-11-12 04:44:01 +01007598 If the name "cjk" is included East Asian characters are excluded from
7599 spell checking. This is useful when editing text that also has Asian
7600 words.
Bram Moolenaar6c391a72021-09-09 21:55:11 +02007601 Note that the "medical" dictionary does not exist, it is just an
7602 example of a longer name.
Bram Moolenaar8aff23a2005-08-19 20:40:30 +00007603 *E757*
Bram Moolenaarce0842a2005-07-18 21:58:11 +00007604 As a special case the name of a .spl file can be given as-is. The
7605 first "_xx" in the name is removed and used as the region name
7606 (_xx is an underscore, two letters and followed by a non-letter).
7607 This is mainly for testing purposes. You must make sure the correct
7608 encoding is used, Vim doesn't check it.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00007609 When 'encoding' is set the word lists are reloaded. Thus it's a good
Bram Moolenaarce0842a2005-07-18 21:58:11 +00007610 idea to set 'spelllang' after setting 'encoding' to avoid loading the
7611 files twice.
Bram Moolenaar3b506942005-06-23 22:36:45 +00007612 How the related spell files are found is explained here: |spell-load|.
Bram Moolenaar217ad922005-03-20 22:37:15 +00007613
Bram Moolenaar98692072006-02-04 00:57:42 +00007614 If the |spellfile.vim| plugin is active and you use a language name
7615 for which Vim cannot find the .spl file in 'runtimepath' the plugin
7616 will ask you if you want to download the file.
7617
Bram Moolenaar90cfdbe2005-08-12 19:59:19 +00007618 After this option has been set successfully, Vim will source the files
7619 "spell/LANG.vim" in 'runtimepath'. "LANG" is the value of 'spelllang'
Bram Moolenaarb730f0c2018-11-25 03:56:26 +01007620 up to the first character that is not an ASCII letter or number and
7621 not a dash. Also see |set-spc-auto|.
Bram Moolenaar90cfdbe2005-08-12 19:59:19 +00007622
Bram Moolenaar362b44b2020-06-10 21:47:00 +02007623 *'spelloptions'* *'spo'*
7624'spelloptions' 'spo' string (default "")
7625 local to buffer
7626 {not available when compiled without the |+syntax|
7627 feature}
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01007628 A comma-separated list of options for spell checking:
Bram Moolenaar362b44b2020-06-10 21:47:00 +02007629 camel When a word is CamelCased, assume "Cased" is a
7630 separate word: every upper-case character in a word
7631 that comes after a lower case character indicates the
7632 start of a new word.
Bram Moolenaar90cfdbe2005-08-12 19:59:19 +00007633
Bram Moolenaard857f0e2005-06-21 22:37:39 +00007634 *'spellsuggest'* *'sps'*
7635'spellsuggest' 'sps' string (default "best")
7636 global
Bram Moolenaard857f0e2005-06-21 22:37:39 +00007637 {not available when compiled without the |+syntax|
7638 feature}
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00007639 Methods used for spelling suggestions. Both for the |z=| command and
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00007640 the |spellsuggest()| function. This is a comma-separated list of
7641 items:
Bram Moolenaard857f0e2005-06-21 22:37:39 +00007642
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00007643 best Internal method that works best for English. Finds
7644 changes like "fast" and uses a bit of sound-a-like
7645 scoring to improve the ordering.
7646
7647 double Internal method that uses two methods and mixes the
7648 results. The first method is "fast", the other method
Bram Moolenaard857f0e2005-06-21 22:37:39 +00007649 computes how much the suggestion sounds like the bad
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00007650 word. That only works when the language specifies
7651 sound folding. Can be slow and doesn't always give
7652 better results.
7653
7654 fast Internal method that only checks for simple changes:
7655 character inserts/deletes/swaps. Works well for
7656 simple typing mistakes.
7657
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00007658 {number} The maximum number of suggestions listed for |z=|.
Bram Moolenaar8aff23a2005-08-19 20:40:30 +00007659 Not used for |spellsuggest()|. The number of
7660 suggestions is never more than the value of 'lines'
7661 minus two.
7662
Bram Moolenaar585ee072022-01-29 11:22:17 +00007663 timeout:{millisec} Limit the time searching for suggestions to
7664 {millisec} milli seconds. Applies to the following
7665 methods. When omitted the limit is 5000. When
7666 negative there is no limit. {only works when built
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01007667 with the |+reltime| feature}
Bram Moolenaar585ee072022-01-29 11:22:17 +00007668
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00007669 file:{filename} Read file {filename}, which must have two columns,
7670 separated by a slash. The first column contains the
7671 bad word, the second column the suggested good word.
7672 Example:
7673 theribal/terrible ~
7674 Use this for common mistakes that do not appear at the
7675 top of the suggestion list with the internal methods.
7676 Lines without a slash are ignored, use this for
7677 comments.
Bram Moolenaarbcb98982014-05-01 14:08:19 +02007678 The word in the second column must be correct,
7679 otherwise it will not be used. Add the word to an
7680 ".add" file if it is currently flagged as a spelling
7681 mistake.
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00007682 The file is used for all languages.
7683
7684 expr:{expr} Evaluate expression {expr}. Use a function to avoid
Bram Moolenaara4e0b972022-10-01 19:43:52 +01007685 trouble with spaces. Best is to call a function
7686 without arguments, see |expr-option-function|.
7687 |v:val| holds the badly spelled word. The expression
7688 must evaluate to a List of Lists, each with a
7689 suggestion and a score.
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00007690 Example:
Bram Moolenaar214641f2017-03-05 17:04:09 +01007691 [['the', 33], ['that', 44]] ~
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00007692 Set 'verbose' and use |z=| to see the scores that the
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00007693 internal methods use. A lower score is better.
7694 This may invoke |spellsuggest()| if you temporarily
7695 set 'spellsuggest' to exclude the "expr:" part.
7696 Errors are silently ignored, unless you set the
7697 'verbose' option to a non-zero value.
7698
7699 Only one of "best", "double" or "fast" may be used. The others may
7700 appear several times in any order. Example: >
7701 :set sps=file:~/.vim/sugg,best,expr:MySuggest()
7702<
7703 This option cannot be set from a |modeline| or in the |sandbox|, for
7704 security reasons.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00007705
7706
Bram Moolenaar071d4272004-06-13 20:20:40 +00007707 *'splitbelow'* *'sb'* *'nosplitbelow'* *'nosb'*
7708'splitbelow' 'sb' boolean (default off)
7709 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007710 When on, splitting a window will put the new window below the current
7711 one. |:split|
7712
Bram Moolenaar3c053a12022-10-16 13:11:12 +01007713 *'splitkeep'* *'spk'*
Luuk van Baal13ece2a2022-10-03 15:28:08 +01007714'splitkeep' 'spk' string (default "cursor")
7715 global
7716 The value of this option determines the scroll behavior when opening,
7717 closing or resizing horizontal splits.
7718
7719 Possible values are:
7720 cursor Keep the same relative cursor position.
7721 screen Keep the text on the same screen line.
7722 topline Keep the topline the same.
7723
7724 For the "screen" and "topline" values, the cursor position will be
7725 changed when necessary. In this case, the jumplist will be populated
7726 with the previous cursor position. For "screen", the text cannot always
Bram Moolenaar3c053a12022-10-16 13:11:12 +01007727 be kept on the same screen line when 'wrap' is enabled.
Luuk van Baal13ece2a2022-10-03 15:28:08 +01007728
Bram Moolenaar071d4272004-06-13 20:20:40 +00007729 *'splitright'* *'spr'* *'nosplitright'* *'nospr'*
7730'splitright' 'spr' boolean (default off)
7731 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007732 When on, splitting a window will put the new window right of the
7733 current one. |:vsplit|
7734
7735 *'startofline'* *'sol'* *'nostartofline'* *'nosol'*
7736'startofline' 'sol' boolean (default on)
7737 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007738 When "on" the commands listed below move the cursor to the first
Bram Moolenaar843ee412004-06-30 16:16:41 +00007739 non-blank of the line. When off the cursor is kept in the same column
Bram Moolenaar71badf92023-04-22 22:40:14 +01007740 (if possible). This applies to the commands:
7741 - CTRL-D, CTRL-U, CTRL-B, CTRL-F, "G", "H", "M", "L", "gg"
7742 - "d", "<<" and ">>" with a linewise operator
7743 - "%" with a count
7744 - buffer changing commands (CTRL-^, :bnext, :bNext, etc.)
7745 - Ex commands that only has a line number, e.g., ":25" or ":+".
Bram Moolenaar071d4272004-06-13 20:20:40 +00007746 In case of buffer changing commands the cursor is placed at the column
7747 where it was the last time the buffer was edited.
7748 NOTE: This option is set when 'compatible' is set.
7749
Bram Moolenaar00654022011-02-25 14:42:19 +01007750 *'statusline'* *'stl'* *E540* *E542*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007751'statusline' 'stl' string (default empty)
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00007752 global or local to window |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00007753 {not available when compiled without the |+statusline|
7754 feature}
Bram Moolenaar944697a2022-02-20 19:48:20 +00007755 When non-empty, this option determines the content of the status line.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007756 Also see |status-line|.
7757
7758 The option consists of printf style '%' items interspersed with
7759 normal text. Each status line item is of the form:
7760 %-0{minwid}.{maxwid}{item}
Bram Moolenaar5e9b2fa2016-02-01 22:37:05 +01007761 All fields except the {item} are optional. A single percent sign can
Bram Moolenaar8133cc62020-10-26 21:05:27 +01007762 be given as "%%".
Bram Moolenaar071d4272004-06-13 20:20:40 +00007763
Bram Moolenaar238a5642006-02-21 22:12:05 +00007764 When the option starts with "%!" then it is used as an expression,
7765 evaluated and the result is used as the option value. Example: >
7766 :set statusline=%!MyStatusLine()
Bram Moolenaar1c6fd1e2019-05-23 22:11:59 +02007767< The *g:statusline_winid* variable will be set to the |window-ID| of the
7768 window that the status line belongs to.
7769 The result can contain %{} items that will be evaluated too.
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02007770 Note that the "%!" expression is evaluated in the context of the
7771 current window and buffer, while %{} items are evaluated in the
7772 context of the window that the statusline belongs to.
Bram Moolenaar238a5642006-02-21 22:12:05 +00007773
7774 When there is error while evaluating the option then it will be made
7775 empty to avoid further errors. Otherwise screen updating would loop.
Bram Moolenaar1b5f03e2023-01-09 20:12:45 +00007776 When the result contains unprintable characters the result is
7777 unpredictable.
Bram Moolenaar238a5642006-02-21 22:12:05 +00007778
Bram Moolenaar071d4272004-06-13 20:20:40 +00007779 Note that the only effect of 'ruler' when this option is set (and
7780 'laststatus' is 2) is controlling the output of |CTRL-G|.
7781
7782 field meaning ~
Bram Moolenaar582fd852005-03-28 20:58:01 +00007783 - Left justify the item. The default is right justified
Bram Moolenaar071d4272004-06-13 20:20:40 +00007784 when minwid is larger than the length of the item.
Bram Moolenaar582fd852005-03-28 20:58:01 +00007785 0 Leading zeroes in numeric items. Overridden by '-'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007786 minwid Minimum width of the item, padding as set by '-' & '0'.
7787 Value must be 50 or less.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007788 maxwid Maximum width of the item. Truncation occurs with a '<'
Bram Moolenaar071d4272004-06-13 20:20:40 +00007789 on the left for text items. Numeric items will be
7790 shifted down to maxwid-2 digits followed by '>'number
7791 where number is the amount of missing digits, much like
7792 an exponential notation.
7793 item A one letter code as described below.
7794
7795 Following is a description of the possible statusline items. The
7796 second character in "item" is the type:
7797 N for number
7798 S for string
7799 F for flags as described below
7800 - not applicable
7801
7802 item meaning ~
Bram Moolenaar02467872007-05-06 13:22:01 +00007803 f S Path to the file in the buffer, as typed or relative to current
7804 directory.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007805 F S Full path to the file in the buffer.
7806 t S File name (tail) of file in the buffer.
Bram Moolenaare37d50a2008-08-06 17:06:04 +00007807 m F Modified flag, text is "[+]"; "[-]" if 'modifiable' is off.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007808 M F Modified flag, text is ",+" or ",-".
Bram Moolenaare37d50a2008-08-06 17:06:04 +00007809 r F Readonly flag, text is "[RO]".
Bram Moolenaar071d4272004-06-13 20:20:40 +00007810 R F Readonly flag, text is ",RO".
Bram Moolenaare37d50a2008-08-06 17:06:04 +00007811 h F Help buffer flag, text is "[help]".
Bram Moolenaar071d4272004-06-13 20:20:40 +00007812 H F Help buffer flag, text is ",HLP".
Bram Moolenaare37d50a2008-08-06 17:06:04 +00007813 w F Preview window flag, text is "[Preview]".
Bram Moolenaar071d4272004-06-13 20:20:40 +00007814 W F Preview window flag, text is ",PRV".
Bram Moolenaare37d50a2008-08-06 17:06:04 +00007815 y F Type of file in the buffer, e.g., "[vim]". See 'filetype'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007816 Y F Type of file in the buffer, e.g., ",VIM". See 'filetype'.
Bram Moolenaar7fd73202010-07-25 16:58:46 +02007817 q S "[Quickfix List]", "[Location List]" or empty.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007818 k S Value of "b:keymap_name" or 'keymap' when |:lmap| mappings are
7819 being used: "<keymap>"
7820 n N Buffer number.
Bram Moolenaar00654022011-02-25 14:42:19 +01007821 b N Value of character under cursor.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007822 B N As above, in hexadecimal.
7823 o N Byte number in file of byte under cursor, first byte is 1.
7824 Mnemonic: Offset from start of file (with one added)
7825 {not available when compiled without |+byte_offset| feature}
7826 O N As above, in hexadecimal.
Bram Moolenaar582fd852005-03-28 20:58:01 +00007827 N N Printer page number. (Only works in the 'printheader' option.)
Bram Moolenaar071d4272004-06-13 20:20:40 +00007828 l N Line number.
7829 L N Number of lines in buffer.
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02007830 c N Column number (byte index).
7831 v N Virtual column number (screen column).
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007832 V N Virtual column number as -{num}. Not displayed if equal to 'c'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007833 p N Percentage through file in lines as in |CTRL-G|.
7834 P S Percentage through file of displayed window. This is like the
Bram Moolenaar14b69452013-06-29 23:05:20 +02007835 percentage described for 'ruler'. Always 3 in length, unless
7836 translated.
Luuk van Baalba936f62022-12-15 13:15:39 +00007837 S S 'showcmd' content, see 'showcmdloc'.
Bram Moolenaar582fd852005-03-28 20:58:01 +00007838 a S Argument list status as in default title. ({current} of {max})
Bram Moolenaar071d4272004-06-13 20:20:40 +00007839 Empty if the argument file count is zero or one.
Bram Moolenaar238a5642006-02-21 22:12:05 +00007840 { NF Evaluate expression between '%{' and '}' and substitute result.
Bram Moolenaar6d150f72018-04-21 20:03:20 +02007841 Note that there is no '%' before the closing '}'. The
7842 expression cannot contain a '}' character, call a function to
Bram Moolenaar0c0734d2019-11-26 21:44:46 +01007843 work around that. See |stl-%{| below.
shadmansaleh30e3de22021-05-15 17:23:28 +02007844 {% - This is almost same as { except the result of the expression is
7845 re-evaluated as a statusline format string. Thus if the
7846 return value of expr contains % items they will get expanded.
7847 The expression can contain the } character, the end of
7848 expression is denoted by %}.
Bram Moolenaar22863042021-10-16 15:23:36 +01007849 For example: >
shadmansaleh30e3de22021-05-15 17:23:28 +02007850 func! Stl_filename() abort
7851 return "%t"
7852 endfunc
7853< `stl=%{Stl_filename()}` results in `"%t"`
7854 `stl=%{%Stl_filename()%}` results in `"Name of current file"`
Bram Moolenaar22863042021-10-16 15:23:36 +01007855 %} - End of `{%` expression
Bram Moolenaar071d4272004-06-13 20:20:40 +00007856 ( - Start of item group. Can be used for setting the width and
7857 alignment of a section. Must be followed by %) somewhere.
7858 ) - End of item group. No width fields allowed.
Bram Moolenaard1f56e62006-02-22 21:25:37 +00007859 T N For 'tabline': start of tab page N label. Use %T after the last
7860 label. This information is used for mouse clicks.
7861 X N For 'tabline': start of close tab N label. Use %X after the
7862 label, e.g.: %3Xclose%X. Use %999X for a "close current tab"
7863 mark. This information is used for mouse clicks.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007864 < - Where to truncate line if too long. Default is at the start.
7865 No width fields allowed.
Yegappan Lakshmanan3ec78f92023-02-11 11:15:25 +00007866 = - Separation point between alignment sections. Each section will
7867 be separated by an equal number of spaces. With one %= what
7868 comes after it will be right-aligned. With two %= there is a
7869 middle part, with white space left and right of it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007870 No width fields allowed.
Bram Moolenaar238a5642006-02-21 22:12:05 +00007871 # - Set highlight group. The name must follow and then a # again.
7872 Thus use %#HLname# for highlight group HLname. The same
7873 highlighting is used, also for the statusline of non-current
7874 windows.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007875 * - Set highlight group to User{N}, where {N} is taken from the
Bram Moolenaar582fd852005-03-28 20:58:01 +00007876 minwid field, e.g. %1*. Restore normal highlight with %* or %0*.
Bram Moolenaarbe4e0162023-02-02 13:59:48 +00007877 The difference between User{N} and StatusLine will be applied to
7878 StatusLineNC for the statusline of non-current windows.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007879 The number N must be between 1 and 9. See |hl-User1..9|
7880
Bram Moolenaare37d50a2008-08-06 17:06:04 +00007881 When displaying a flag, Vim removes the leading comma, if any, when
7882 that flag comes right after plaintext. This will make a nice display
7883 when flags are used like in the examples below.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007884
Bram Moolenaar582fd852005-03-28 20:58:01 +00007885 When all items in a group becomes an empty string (i.e. flags that are
Bram Moolenaar071d4272004-06-13 20:20:40 +00007886 not set) and a minwid is not set for the group, the whole group will
7887 become empty. This will make a group like the following disappear
7888 completely from the statusline when none of the flags are set. >
7889 :set statusline=...%(\ [%M%R%H]%)...
Bram Moolenaar1c6fd1e2019-05-23 22:11:59 +02007890< Beware that an expression is evaluated each and every time the status
7891 line is displayed.
Bram Moolenaar0c0734d2019-11-26 21:44:46 +01007892 *stl-%{* *g:actual_curbuf* *g:actual_curwin*
Bram Moolenaarade0d392020-01-21 22:33:58 +01007893 While evaluating %{} the current buffer and current window will be set
7894 temporarily to that of the window (and buffer) whose statusline is
Bram Moolenaar0c0734d2019-11-26 21:44:46 +01007895 currently being drawn. The expression will evaluate in this context.
7896 The variable "g:actual_curbuf" is set to the `bufnr()` number of the
7897 real current buffer and "g:actual_curwin" to the |window-ID| of the
7898 real current window. These values are strings.
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00007899
Bram Moolenaar30b65812012-07-12 22:01:11 +02007900 The 'statusline' option will be evaluated in the |sandbox| if set from
7901 a modeline, see |sandbox-option|.
Bram Moolenaar110289e2019-05-23 15:38:06 +02007902 This option cannot be set in a modeline when 'modelineexpr' is off.
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00007903
7904 It is not allowed to change text or jump to another window while
7905 evaluating 'statusline' |textlock|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007906
7907 If the statusline is not updated when you want it (e.g., after setting
7908 a variable that's used in an expression), you can force an update by
Bram Moolenaarcfa8f9a2022-06-03 21:59:47 +01007909 using `:redrawstatus`.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007910
Bram Moolenaarcfa8f9a2022-06-03 21:59:47 +01007911 A result of all digits is regarded a number for display purposes.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007912 Otherwise the result is taken as flag text and applied to the rules
7913 described above.
7914
Bram Moolenaarcd71fa32005-03-11 22:46:48 +00007915 Watch out for errors in expressions. They may render Vim unusable!
Bram Moolenaar071d4272004-06-13 20:20:40 +00007916 If you are stuck, hold down ':' or 'Q' to get a prompt, then quit and
Bram Moolenaarc4da1132017-07-15 19:39:43 +02007917 edit your .vimrc or whatever with "vim --clean" to get it right.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007918
7919 Examples:
7920 Emulate standard status line with 'ruler' set >
7921 :set statusline=%<%f\ %h%m%r%=%-14.(%l,%c%V%)\ %P
7922< Similar, but add ASCII value of char under the cursor (like "ga") >
7923 :set statusline=%<%f%h%m%r%=%b\ 0x%B\ \ %l,%c%V\ %P
7924< Display byte count and byte value, modified flag in red. >
7925 :set statusline=%<%f%=\ [%1*%M%*%n%R%H]\ %-19(%3l,%02c%03V%)%O'%02b'
7926 :hi User1 term=inverse,bold cterm=inverse,bold ctermfg=red
7927< Display a ,GZ flag if a compressed file is loaded >
7928 :set statusline=...%r%{VarExists('b:gzflag','\ [GZ]')}%h...
7929< In the |:autocmd|'s: >
7930 :let b:gzflag = 1
7931< And: >
7932 :unlet b:gzflag
7933< And define this function: >
7934 :function VarExists(var, val)
7935 : if exists(a:var) | return a:val | else | return '' | endif
7936 :endfunction
7937<
7938 *'suffixes'* *'su'*
7939'suffixes' 'su' string (default ".bak,~,.o,.h,.info,.swp,.obj")
7940 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007941 Files with these suffixes get a lower priority when multiple files
7942 match a wildcard. See |suffixes|. Commas can be used to separate the
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007943 suffixes. Spaces after the comma are ignored. A dot is also seen as
7944 the start of a suffix. To avoid a dot or comma being recognized as a
Bram Moolenaar071d4272004-06-13 20:20:40 +00007945 separator, precede it with a backslash (see |option-backslash| about
7946 including spaces and backslashes).
7947 See 'wildignore' for completely ignoring files.
7948 The use of |:set+=| and |:set-=| is preferred when adding or removing
7949 suffixes from the list. This avoids problems when a future version
7950 uses another default.
7951
7952 *'suffixesadd'* *'sua'*
7953'suffixesadd' 'sua' string (default "")
7954 local to buffer
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01007955 Comma-separated list of suffixes, which are used when searching for a
Bram Moolenaar071d4272004-06-13 20:20:40 +00007956 file for the "gf", "[I", etc. commands. Example: >
7957 :set suffixesadd=.java
7958<
7959 *'swapfile'* *'swf'* *'noswapfile'* *'noswf'*
7960'swapfile' 'swf' boolean (default on)
7961 local to buffer
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007962 Use a swapfile for the buffer. This option can be reset when a
Bram Moolenaar071d4272004-06-13 20:20:40 +00007963 swapfile is not wanted for a specific buffer. For example, with
7964 confidential information that even root must not be able to access.
7965 Careful: All text will be in memory:
7966 - Don't use this for big files.
7967 - Recovery will be impossible!
7968 A swapfile will only be present when |'updatecount'| is non-zero and
7969 'swapfile' is set.
7970 When 'swapfile' is reset, the swap file for the current buffer is
7971 immediately deleted. When 'swapfile' is set, and 'updatecount' is
7972 non-zero, a swap file is immediately created.
7973 Also see |swap-file| and |'swapsync'|.
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +01007974 If you want to open a new buffer without creating a swap file for it,
7975 use the |:noswapfile| modifier.
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01007976 See 'directory' for where the swap file is created.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007977
7978 This option is used together with 'bufhidden' and 'buftype' to
7979 specify special kinds of buffers. See |special-buffers|.
7980
7981 *'swapsync'* *'sws'*
7982'swapsync' 'sws' string (default "fsync")
7983 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007984 When this option is not empty a swap file is synced to disk after
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007985 writing to it. This takes some time, especially on busy unix systems.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007986 When this option is empty parts of the swap file may be in memory and
7987 not written to disk. When the system crashes you may lose more work.
7988 On Unix the system does a sync now and then without Vim asking for it,
7989 so the disadvantage of setting this option off is small. On some
7990 systems the swap file will not be written at all. For a unix system
7991 setting it to "sync" will use the sync() call instead of the default
7992 fsync(), which may work better on some systems.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00007993 The 'fsync' option is used for the actual file.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007994
7995 *'switchbuf'* *'swb'*
7996'switchbuf' 'swb' string (default "")
7997 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007998 This option controls the behavior when switching between buffers.
Yegappan Lakshmanan54be5fb2023-05-12 17:49:13 +01007999 This option is checked, when
8000 - jumping to errors with the |quickfix| commands (|:cc|, |:cn|, |:cp|,
h_east59858792023-10-25 22:47:05 +09008001 etc.).
Yegappan Lakshmanan54be5fb2023-05-12 17:49:13 +01008002 - jumping to a tag using the |:stag| command.
8003 - opening a file using the |CTRL-W_f| or |CTRL-W_F| command.
8004 - jumping to a buffer using a buffer split command (e.g. |:sbuffer|,
8005 |:sbnext|, or |:sbrewind|).
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01008006 Possible values (comma-separated list):
Yegappan Lakshmanan54be5fb2023-05-12 17:49:13 +01008007 useopen If included, jump to the first open window in the
8008 current tab page that contains the specified buffer
8009 (if there is one). Otherwise: Do not examine other
8010 windows.
Bram Moolenaar779b74b2006-04-10 14:55:34 +00008011 usetab Like "useopen", but also consider windows in other tab
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00008012 pages.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008013 split If included, split the current window before loading
Bram Moolenaar15146672011-10-20 22:22:38 +02008014 a buffer for a |quickfix| command that display errors.
Bram Moolenaar63b74a82019-03-24 15:09:13 +01008015 Otherwise: do not split, use current window (when used
8016 in the quickfix window: the previously used window or
8017 split if there is no other window).
Bram Moolenaara594d772015-06-19 14:41:49 +02008018 vsplit Just like "split" but split vertically.
Bram Moolenaar446cb832008-06-24 21:56:24 +00008019 newtab Like "split", but open a new tab page. Overrules
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02008020 "split" when both are present.
Bram Moolenaar539aa6b2019-11-17 18:09:38 +01008021 uselast If included, jump to the previously used window when
8022 jumping to errors with |quickfix| commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008023
Bram Moolenaar3b56eb32005-07-11 22:40:32 +00008024 *'synmaxcol'* *'smc'*
8025'synmaxcol' 'smc' number (default 3000)
8026 local to buffer
Bram Moolenaar3b56eb32005-07-11 22:40:32 +00008027 {not available when compiled without the |+syntax|
8028 feature}
Bram Moolenaarce0842a2005-07-18 21:58:11 +00008029 Maximum column in which to search for syntax items. In long lines the
8030 text after this column is not highlighted and following lines may not
8031 be highlighted correctly, because the syntax state is cleared.
Bram Moolenaar3b56eb32005-07-11 22:40:32 +00008032 This helps to avoid very slow redrawing for an XML file that is one
8033 long line.
8034 Set to zero to remove the limit.
8035
Bram Moolenaar071d4272004-06-13 20:20:40 +00008036 *'syntax'* *'syn'*
8037'syntax' 'syn' string (default empty)
Christian Brabandt596ad662023-08-16 00:11:09 +02008038 local to buffer |local-noglobal|
Bram Moolenaar071d4272004-06-13 20:20:40 +00008039 {not available when compiled without the |+syntax|
8040 feature}
8041 When this option is set, the syntax with this name is loaded, unless
8042 syntax highlighting has been switched off with ":syntax off".
8043 Otherwise this option does not always reflect the current syntax (the
8044 b:current_syntax variable does).
8045 This option is most useful in a modeline, for a file which syntax is
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00008046 not automatically recognized. Example, in an IDL file:
8047 /* vim: set syntax=idl : */ ~
8048 When a dot appears in the value then this separates two filetype
8049 names. Example:
8050 /* vim: set syntax=c.doxygen : */ ~
8051 This will use the "c" syntax first, then the "doxygen" syntax.
8052 Note that the second one must be prepared to be loaded as an addition,
8053 otherwise it will be skipped. More than one dot may appear.
8054 To switch off syntax highlighting for the current file, use: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00008055 :set syntax=OFF
8056< To switch syntax highlighting on according to the current value of the
8057 'filetype' option: >
8058 :set syntax=ON
8059< What actually happens when setting the 'syntax' option is that the
8060 Syntax autocommand event is triggered with the value as argument.
8061 This option is not copied to another buffer, independent of the 's' or
8062 'S' flag in 'cpoptions'.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00008063 Only normal file name characters can be used, "/\*?[|<>" are illegal.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008064
Bram Moolenaarfd2ac762006-03-01 22:09:21 +00008065 *'tabline'* *'tal'*
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00008066'tabline' 'tal' string (default empty)
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00008067 global
Bram Moolenaar944697a2022-02-20 19:48:20 +00008068 When non-empty, this option determines the content of the tab pages
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00008069 line at the top of the Vim window. When empty Vim will use a default
Bram Moolenaard1f56e62006-02-22 21:25:37 +00008070 tab pages line. See |setting-tabline| for more info.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00008071
8072 The tab pages line only appears as specified with the 'showtabline'
Bram Moolenaar5c8837f2006-02-25 21:52:33 +00008073 option and only when there is no GUI tab line. When 'e' is in
8074 'guioptions' and the GUI supports a tab line 'guitablabel' is used
Bram Moolenaar7f036442010-08-15 15:24:20 +02008075 instead. Note that the two tab pages lines are very different.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00008076
8077 The value is evaluated like with 'statusline'. You can use
8078 |tabpagenr()|, |tabpagewinnr()| and |tabpagebuflist()| to figure out
Bram Moolenaard1f56e62006-02-22 21:25:37 +00008079 the text to be displayed. Use "%1T" for the first label, "%2T" for
8080 the second one, etc. Use "%X" items for closing labels.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00008081
Bram Moolenaare12bab32019-01-08 22:02:56 +01008082 When changing something that is used in 'tabline' that does not
8083 trigger it to be updated, use |:redrawtabline|.
Bram Moolenaar110289e2019-05-23 15:38:06 +02008084 This option cannot be set in a modeline when 'modelineexpr' is off.
Bram Moolenaare12bab32019-01-08 22:02:56 +01008085
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00008086 Keep in mind that only one of the tab pages is the current one, others
8087 are invisible and you can't jump to their windows.
8088
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00008089
Bram Moolenaarfd2ac762006-03-01 22:09:21 +00008090 *'tabpagemax'* *'tpm'*
8091'tabpagemax' 'tpm' number (default 10)
8092 global
Bram Moolenaarfd2ac762006-03-01 22:09:21 +00008093 Maximum number of tab pages to be opened by the |-p| command line
8094 argument or the ":tab all" command. |tabpage|
8095
8096
8097 *'tabstop'* *'ts'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008098'tabstop' 'ts' number (default 8)
8099 local to buffer
8100 Number of spaces that a <Tab> in the file counts for. Also see
Bram Moolenaarf10911e2022-01-29 22:20:48 +00008101 the |:retab| command, and the 'softtabstop' option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008102
8103 Note: Setting 'tabstop' to any other value than 8 can make your file
Bram Moolenaarf10911e2022-01-29 22:20:48 +00008104 appear wrong in many places, e.g., when printing it.
8105 The value must be more than 0 and less than 10000.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008106
8107 There are four main ways to use tabs in Vim:
8108 1. Always keep 'tabstop' at 8, set 'softtabstop' and 'shiftwidth' to 4
8109 (or 3 or whatever you prefer) and use 'noexpandtab'. Then Vim
Bram Moolenaarebcbd022007-05-12 14:28:25 +00008110 will use a mix of tabs and spaces, but typing <Tab> and <BS> will
Bram Moolenaar071d4272004-06-13 20:20:40 +00008111 behave like a tab appears every 4 (or 3) characters.
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01008112 This is the recommended way, the file will look the same with other
8113 tools and when listing it in a terminal.
8114 2. Set 'softtabstop' and 'shiftwidth' to whatever you prefer and use
8115 'expandtab'. This way you will always insert spaces. The
8116 formatting will never be messed up when 'tabstop' is changed (leave
8117 it at 8 just in case). The file will be a bit larger.
8118 You do need to check if no Tabs exist in the file. You can get rid
8119 of them by first setting 'expandtab' and using `%retab!`, making
8120 sure the value of 'tabstop' is set correctly.
8121 3. Set 'tabstop' and 'shiftwidth' to whatever you prefer and use
Bram Moolenaar071d4272004-06-13 20:20:40 +00008122 'expandtab'. This way you will always insert spaces. The
8123 formatting will never be messed up when 'tabstop' is changed.
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01008124 You do need to check if no Tabs exist in the file, just like in the
8125 item just above.
8126 4. Set 'tabstop' and 'shiftwidth' to whatever you prefer and use a
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00008127 |modeline| to set these values when editing the file again. Only
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01008128 works when using Vim to edit the file, other tools assume a tabstop
8129 is worth 8 spaces.
8130 5. Always set 'tabstop' and 'shiftwidth' to the same value, and
Bram Moolenaar071d4272004-06-13 20:20:40 +00008131 'noexpandtab'. This should then work (for initial indents only)
8132 for any tabstop setting that people use. It might be nice to have
8133 tabs after the first non-blank inserted as spaces if you do this
8134 though. Otherwise aligned comments will be wrong when 'tabstop' is
8135 changed.
8136
Bram Moolenaar04958cb2018-06-23 19:23:02 +02008137 If Vim is compiled with the |+vartabs| feature then the value of
8138 'tabstop' will be ignored if |'vartabstop'| is set to anything other
8139 than an empty string.
8140
Bram Moolenaar071d4272004-06-13 20:20:40 +00008141 *'tagbsearch'* *'tbs'* *'notagbsearch'* *'notbs'*
8142'tagbsearch' 'tbs' boolean (default on)
8143 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008144 When searching for a tag (e.g., for the |:ta| command), Vim can either
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00008145 use a binary search or a linear search in a tags file. Binary
Bram Moolenaar071d4272004-06-13 20:20:40 +00008146 searching makes searching for a tag a LOT faster, but a linear search
8147 will find more tags if the tags file wasn't properly sorted.
8148 Vim normally assumes that your tags files are sorted, or indicate that
8149 they are not sorted. Only when this is not the case does the
8150 'tagbsearch' option need to be switched off.
8151
8152 When 'tagbsearch' is on, binary searching is first used in the tags
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00008153 files. In certain situations, Vim will do a linear search instead for
Bram Moolenaar071d4272004-06-13 20:20:40 +00008154 certain files, or retry all files with a linear search. When
8155 'tagbsearch' is off, only a linear search is done.
8156
8157 Linear searching is done anyway, for one file, when Vim finds a line
8158 at the start of the file indicating that it's not sorted: >
Bram Moolenaar446cb832008-06-24 21:56:24 +00008159 !_TAG_FILE_SORTED 0 /some comment/
Bram Moolenaar071d4272004-06-13 20:20:40 +00008160< [The whitespace before and after the '0' must be a single <Tab>]
8161
8162 When a binary search was done and no match was found in any of the
Bram Moolenaar0f6562e2015-11-24 18:48:14 +01008163 files listed in 'tags', and case is ignored or a pattern is used
Bram Moolenaar071d4272004-06-13 20:20:40 +00008164 instead of a normal tag name, a retry is done with a linear search.
8165 Tags in unsorted tags files, and matches with different case will only
8166 be found in the retry.
8167
Bram Moolenaard4755bb2004-09-02 19:12:26 +00008168 If a tag file indicates that it is case-fold sorted, the second,
Bram Moolenaar0f6562e2015-11-24 18:48:14 +01008169 linear search can be avoided when case is ignored. Use a value of '2'
8170 in the "!_TAG_FILE_SORTED" line for this. A tag file can be case-fold
8171 sorted with the -f switch to "sort" in most unices, as in the command:
Bram Moolenaar47c532e2022-03-19 15:18:53 +00008172 "sort -f -o tags tags". For Universal ctags and Exuberant ctags
8173 version 5.x or higher (at least 5.5) the --sort=foldcase switch can be
8174 used for this as well. Note that case must be folded to uppercase for
8175 this to work.
Bram Moolenaar0f6562e2015-11-24 18:48:14 +01008176
8177 By default, tag searches are case-sensitive. Case is ignored when
8178 'ignorecase' is set and 'tagcase' is "followic", or when 'tagcase' is
8179 "ignore".
Bram Moolenaar66e29d72016-08-20 16:57:02 +02008180 Also when 'tagcase' is "followscs" and 'smartcase' is set, or
8181 'tagcase' is "smart", and the pattern contains only lowercase
8182 characters.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008183
8184 When 'tagbsearch' is off, tags searching is slower when a full match
8185 exists, but faster when no full match exists. Tags in unsorted tags
8186 files may only be found with 'tagbsearch' off.
8187 When the tags file is not sorted, or sorted in a wrong way (not on
8188 ASCII byte value), 'tagbsearch' should be off, or the line given above
8189 must be included in the tags file.
8190 This option doesn't affect commands that find all matching tags (e.g.,
8191 command-line completion and ":help").
Bram Moolenaar071d4272004-06-13 20:20:40 +00008192
Bram Moolenaar0f6562e2015-11-24 18:48:14 +01008193 *'tagcase'* *'tc'*
8194'tagcase' 'tc' string (default "followic")
8195 global or local to buffer |global-local|
Bram Moolenaar0f6562e2015-11-24 18:48:14 +01008196 This option specifies how case is handled when searching the tags
8197 file:
8198 followic Follow the 'ignorecase' option
Bram Moolenaar66e29d72016-08-20 16:57:02 +02008199 followscs Follow the 'smartcase' and 'ignorecase' options
Bram Moolenaar0f6562e2015-11-24 18:48:14 +01008200 ignore Ignore case
8201 match Match case
Bram Moolenaar66e29d72016-08-20 16:57:02 +02008202 smart Ignore case unless an upper case letter is used
Bram Moolenaar036986f2017-03-16 17:41:02 +01008203 NOTE: This option is set to the Vi default value when 'compatible' is
8204 set and to the Vim default value when 'compatible' is reset.
Bram Moolenaar0f6562e2015-11-24 18:48:14 +01008205
Bram Moolenaar45e18cb2019-04-28 18:05:35 +02008206 *'tagfunc'* *'tfu'*
8207'tagfunc' 'tfu' string (default: empty)
8208 local to buffer
8209 {not available when compiled without the |+eval|
8210 feature}
8211 This option specifies a function to be used to perform tag searches.
8212 The function gets the tag pattern and should return a List of matching
8213 tags. See |tag-function| for an explanation of how to write the
Yegappan Lakshmanan19916a82021-11-24 16:32:55 +00008214 function and an example. The value can be the name of a function, a
8215 |lambda| or a |Funcref|. See |option-value-function| for more
8216 information.
Bram Moolenaar45e18cb2019-04-28 18:05:35 +02008217
Bram Moolenaar071d4272004-06-13 20:20:40 +00008218 *'taglength'* *'tl'*
8219'taglength' 'tl' number (default 0)
8220 global
8221 If non-zero, tags are significant up to this number of characters.
8222
8223 *'tagrelative'* *'tr'* *'notagrelative'* *'notr'*
8224'tagrelative' 'tr' boolean (Vim default: on, Vi default: off)
8225 global
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00008226 If on and using a tags file in another directory, file names in that
8227 tags file are relative to the directory where the tags file is.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008228 NOTE: This option is set to the Vi default value when 'compatible' is
8229 set and to the Vim default value when 'compatible' is reset.
8230
8231 *'tags'* *'tag'* *E433*
8232'tags' 'tag' string (default "./tags,tags", when compiled with
8233 |+emacs_tags|: "./tags,./TAGS,tags,TAGS")
8234 global or local to buffer |global-local|
8235 Filenames for the tag command, separated by spaces or commas. To
Yee Cheng Chin54844852023-10-09 18:12:31 +02008236 include a space or comma in a file name, precede it with backslashes
8237 (see |option-backslash| about including spaces/commas and backslashes).
Bram Moolenaar071d4272004-06-13 20:20:40 +00008238 When a file name starts with "./", the '.' is replaced with the path
8239 of the current file. But only when the 'd' flag is not included in
8240 'cpoptions'. Environment variables are expanded |:set_env|. Also see
8241 |tags-option|.
8242 "*", "**" and other wildcards can be used to search for tags files in
Bram Moolenaare2b590e2010-08-08 18:29:48 +02008243 a directory tree. See |file-searching|. E.g., "/lib/**/tags" will
8244 find all files named "tags" below "/lib". The filename itself cannot
8245 contain wildcards, it is used as-is. E.g., "/lib/**/tags?" will find
Bram Moolenaar2bd9dbc2022-08-25 18:12:06 +01008246 files called "tags?".
Bram Moolenaare7eb9df2005-09-09 19:49:30 +00008247 The |tagfiles()| function can be used to get a list of the file names
8248 actually used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008249 If Vim was compiled with the |+emacs_tags| feature, Emacs-style tag
8250 files are also supported. They are automatically recognized. The
8251 default value becomes "./tags,./TAGS,tags,TAGS", unless case
8252 differences are ignored (MS-Windows). |emacs-tags|
8253 The use of |:set+=| and |:set-=| is preferred when adding or removing
8254 file names from the list. This avoids problems when a future version
8255 uses another default.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008256
8257 *'tagstack'* *'tgst'* *'notagstack'* *'notgst'*
8258'tagstack' 'tgst' boolean (default on)
8259 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008260 When on, the |tagstack| is used normally. When off, a ":tag" or
8261 ":tselect" command with an argument will not push the tag onto the
8262 tagstack. A following ":tag" without an argument, a ":pop" command or
8263 any other command that uses the tagstack will use the unmodified
8264 tagstack, but does change the pointer to the active entry.
8265 Resetting this option is useful when using a ":tag" command in a
8266 mapping which should not change the tagstack.
8267
Bram Moolenaar8a5115c2016-01-09 19:41:11 +01008268 *'tcldll'*
Bram Moolenaar3848e002016-03-19 18:42:29 +01008269'tcldll' string (default depends on the build)
Bram Moolenaar8a5115c2016-01-09 19:41:11 +01008270 global
Bram Moolenaar8a5115c2016-01-09 19:41:11 +01008271 {only available when compiled with the |+tcl/dyn|
8272 feature}
8273 Specifies the name of the Tcl shared library. The default is
8274 DYNAMIC_TCL_DLL, which was specified at compile time.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02008275 Environment variables are expanded |:set_env|.
Bram Moolenaar8a5115c2016-01-09 19:41:11 +01008276 This option cannot be set from a |modeline| or in the |sandbox|, for
8277 security reasons.
8278
Bram Moolenaar071d4272004-06-13 20:20:40 +00008279 *'term'* *E529* *E530* *E531*
8280'term' string (default is $TERM, if that fails:
8281 in the GUI: "builtin_gui"
8282 on Amiga: "amiga"
Bram Moolenaarb3f74062020-02-26 16:16:53 +01008283 on Haiku: "xterm"
Bram Moolenaar071d4272004-06-13 20:20:40 +00008284 on Mac: "mac-ansi"
Bram Moolenaar071d4272004-06-13 20:20:40 +00008285 on Unix: "ansi"
8286 on VMS: "ansi"
8287 on Win 32: "win32")
8288 global
8289 Name of the terminal. Used for choosing the terminal control
8290 characters. Environment variables are expanded |:set_env|.
8291 For example: >
8292 :set term=$TERM
8293< See |termcap|.
8294
8295 *'termbidi'* *'tbidi'*
8296 *'notermbidi'* *'notbidi'*
8297'termbidi' 'tbidi' boolean (default off, on for "mlterm")
8298 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008299 {only available when compiled with the |+arabic|
8300 feature}
8301 The terminal is in charge of Bi-directionality of text (as specified
8302 by Unicode). The terminal is also expected to do the required shaping
8303 that some languages (such as Arabic) require.
8304 Setting this option implies that 'rightleft' will not be set when
8305 'arabic' is set and the value of 'arabicshape' will be ignored.
8306 Note that setting 'termbidi' has the immediate effect that
8307 'arabicshape' is ignored, but 'rightleft' isn't changed automatically.
8308 This option is reset when the GUI is started.
8309 For further details see |arabic.txt|.
8310
8311 *'termencoding'* *'tenc'*
Bram Moolenaar3d1cde82020-08-15 18:55:18 +02008312'termencoding' 'tenc' string (default ""; with GTK+ GUI: "utf-8")
Bram Moolenaar071d4272004-06-13 20:20:40 +00008313 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008314 Encoding used for the terminal. This specifies what character
8315 encoding the keyboard produces and the display will understand. For
Bram Moolenaar3848e002016-03-19 18:42:29 +01008316 the GUI it only applies to the keyboard ('encoding' is used for the
Bram Moolenaar3d1cde82020-08-15 18:55:18 +02008317 display).
Bram Moolenaar4b7cdca2020-01-01 16:18:38 +01008318 *E617* *E950*
Bram Moolenaar3df01732017-02-17 22:47:16 +01008319 Note: This does not apply to the GTK+ GUI. After the GUI has been
Bram Moolenaar071d4272004-06-13 20:20:40 +00008320 successfully initialized, 'termencoding' is forcibly set to "utf-8".
8321 Any attempts to set a different value will be rejected, and an error
8322 message is shown.
Bram Moolenaarac360bf2015-09-01 20:31:20 +02008323 For the Win32 GUI and console versions 'termencoding' is not used,
Bram Moolenaar071d4272004-06-13 20:20:40 +00008324 because the Win32 system always passes Unicode characters.
8325 When empty, the same encoding is used as for the 'encoding' option.
8326 This is the normal value.
8327 Not all combinations for 'termencoding' and 'encoding' are valid. See
8328 |encoding-table|.
8329 The value for this option must be supported by internal conversions or
8330 iconv(). When this is not possible no conversion will be done and you
8331 will probably experience problems with non-ASCII characters.
8332 Example: You are working with the locale set to euc-jp (Japanese) and
8333 want to edit a UTF-8 file: >
8334 :let &termencoding = &encoding
8335 :set encoding=utf-8
8336< You need to do this when your system has no locale support for UTF-8.
8337
Bram Moolenaar938ae282023-02-20 20:44:55 +00008338 *'termguicolors'* *'tgc'* *'notermguicolors'* *'notgc'* *E954*
Bram Moolenaar61be73b2016-04-29 22:59:22 +02008339'termguicolors' 'tgc' boolean (default off)
8340 global
Bram Moolenaar61be73b2016-04-29 22:59:22 +02008341 {not available when compiled without the
8342 |+termguicolors| feature}
8343 When on, uses |highlight-guifg| and |highlight-guibg| attributes in
Bram Moolenaarcafafb32018-02-22 21:07:09 +01008344 the terminal (thus using 24-bit color).
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01008345
Bram Moolenaarcafafb32018-02-22 21:07:09 +01008346 Requires a ISO-8613-3 compatible terminal. If setting this option
8347 does not work (produces a colorless UI) reading |xterm-true-color|
8348 might help.
8349
8350 For Win32 console, Windows 10 version 1703 (Creators Update) or later
8351 is required. Use this check to find out: >
8352 if has('vcon')
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01008353< This requires Vim to be built with the |+vtp| feature.
8354
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +02008355 Note that the "cterm" attributes are still used, not the "gui" ones.
Yasuhiro Matsumotoaa04e1b2022-05-07 14:09:19 +01008356
8357 When using Vim with Windows Terminal, the background of Windows
8358 Terminal is normally filled with the Vim background color. Setting
8359 'termguicolors' and the guibg of the Normal highlight group to NONE
8360 will make the background transparent: >
8361 :hi Normal guibg=NONE
8362<
Bram Moolenaar036986f2017-03-16 17:41:02 +01008363 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaar61be73b2016-04-29 22:59:22 +02008364
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02008365 *'termwinkey'* *'twk'*
8366'termwinkey' 'twk' string (default "")
Bram Moolenaar74675a62017-07-15 13:53:23 +02008367 local to window
Bram Moolenaarf55e4c82017-08-01 20:44:53 +02008368 The key that starts a CTRL-W command in a terminal window. Other keys
Bram Moolenaar74675a62017-07-15 13:53:23 +02008369 are sent to the job running in the window.
Bram Moolenaarf55e4c82017-08-01 20:44:53 +02008370 The <> notation can be used, e.g.: >
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02008371 :set termwinkey=<C-L>
Bram Moolenaarf55e4c82017-08-01 20:44:53 +02008372< The string must be one key stroke but can be multiple bytes.
8373 When not set CTRL-W is used, so that CTRL-W : gets you to the command
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02008374 line. If 'termwinkey' is set to CTRL-L then CTRL-L : gets you to the
Bram Moolenaarf55e4c82017-08-01 20:44:53 +02008375 command line.
Bram Moolenaar74675a62017-07-15 13:53:23 +02008376
Bram Moolenaar6c60f472019-04-28 16:00:35 +02008377 *'termwinscroll'* *'twsl'*
8378'termwinscroll' 'twsl' number (default 10000)
8379 local to buffer
8380 {not available when compiled without the
8381 |+terminal| feature}
8382 Number of scrollback lines to keep. When going over this limit the
8383 first 10% of the scrollback lines are deleted. This is just to reduce
8384 the memory usage. See |Terminal-Normal|.
Bram Moolenaar36968af2021-11-15 17:13:11 +00008385 Also used as a limit for text sent to the terminal in one write,
8386 multiplied by the number of columns times 3 (average number of bytes
8387 per cell).
Bram Moolenaar6c60f472019-04-28 16:00:35 +02008388
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02008389 *'termwinsize'* *'tws'*
8390'termwinsize' 'tws' string (default "")
Bram Moolenaar74675a62017-07-15 13:53:23 +02008391 local to window
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02008392 Size used when opening the |terminal| window. Format:
8393 {rows}x{columns} or {rows}*{columns}.
Bram Moolenaar74675a62017-07-15 13:53:23 +02008394 - When empty the terminal gets the size from the window.
Bram Moolenaar498c2562018-04-15 23:45:15 +02008395 - When set with a "x" (e.g., "24x80") the terminal size is not
8396 adjusted to the window size. If the window is smaller only the
8397 top-left part is displayed.
8398 - When set with a "*" (e.g., "10*50") the terminal size follows the
8399 window size, but will not be smaller than the specified rows and/or
8400 columns.
8401 - When rows is zero then use the height of the window.
8402 - When columns is zero then use the width of the window.
8403 - Using "0x0" or "0*0" is the same as empty.
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02008404 - Can be overruled in the |term_start()| options with "term_rows" and
8405 "term_cols".
Bram Moolenaar498c2562018-04-15 23:45:15 +02008406
8407 Examples:
8408 "30x0" uses 30 rows and the current window width.
8409 "20*0" uses at least 20 rows and the current window width.
8410 "0*40" uses the current window height and at least 40 columns.
Bram Moolenaar1f2903c2017-07-23 19:51:01 +02008411 Note that the command running in the terminal window may still change
8412 the size of the terminal. In that case the Vim window will be
8413 adjusted to that size, if possible.
Bram Moolenaar74675a62017-07-15 13:53:23 +02008414
Bram Moolenaarc6ddce32019-02-08 12:47:03 +01008415 *'termwintype'* *'twt'*
8416'termwintype' 'twt' string (default "")
8417 global
Bram Moolenaarc6ddce32019-02-08 12:47:03 +01008418 {only available when compiled with the |terminal|
8419 feature on MS-Windows}
8420 Specify the virtual console (pty) used when opening the terminal
8421 window.
8422
8423 Possible values are:
Bram Moolenaard9ef1b82019-02-13 19:23:10 +01008424 "" use ConPTY if it is stable, winpty otherwise
Bram Moolenaarc6ddce32019-02-08 12:47:03 +01008425 "winpty" use winpty, fail if not supported
8426 "conpty" use |ConPTY|, fail if not supported
8427
Bram Moolenaard9ef1b82019-02-13 19:23:10 +01008428 |ConPTY| support depends on the platform. Windows 10 October 2018
8429 Update is the first version that supports ConPTY, however it is still
8430 considered unstable. ConPTY might become stable in the next release
8431 of Windows 10. winpty support needs to be installed. If neither is
Bram Moolenaarc6ddce32019-02-08 12:47:03 +01008432 supported then you cannot open a terminal window.
8433
Bram Moolenaar071d4272004-06-13 20:20:40 +00008434 *'terse'* *'noterse'*
8435'terse' boolean (default off)
8436 global
8437 When set: Add 's' flag to 'shortmess' option (this makes the message
8438 for a search that hits the start or end of the file not being
8439 displayed). When reset: Remove 's' flag from 'shortmess' option. {Vi
8440 shortens a lot of messages}
8441
8442 *'textauto'* *'ta'* *'notextauto'* *'nota'*
8443'textauto' 'ta' boolean (Vim default: on, Vi default: off)
8444 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008445 This option is obsolete. Use 'fileformats'.
8446 For backwards compatibility, when 'textauto' is set, 'fileformats' is
8447 set to the default value for the current system. When 'textauto' is
8448 reset, 'fileformats' is made empty.
8449 NOTE: This option is set to the Vi default value when 'compatible' is
8450 set and to the Vim default value when 'compatible' is reset.
8451
8452 *'textmode'* *'tx'* *'notextmode'* *'notx'*
Bram Moolenaar6f345a12019-12-17 21:27:18 +01008453'textmode' 'tx' boolean (Win32: default on,
Bram Moolenaar071d4272004-06-13 20:20:40 +00008454 others: default off)
8455 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00008456 This option is obsolete. Use 'fileformat'.
8457 For backwards compatibility, when 'textmode' is set, 'fileformat' is
8458 set to "dos". When 'textmode' is reset, 'fileformat' is set to
8459 "unix".
8460
8461 *'textwidth'* *'tw'*
8462'textwidth' 'tw' number (default 0)
8463 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00008464 Maximum width of text that is being inserted. A longer line will be
8465 broken after white space to get this width. A zero value disables
Bram Moolenaarca635012015-09-25 20:34:21 +02008466 this.
8467 'textwidth' is set to 0 when the 'paste' option is set and restored
8468 when 'paste' is reset.
8469 When 'textwidth' is zero, 'wrapmargin' may be used. See also
Bram Moolenaar071d4272004-06-13 20:20:40 +00008470 'formatoptions' and |ins-textwidth|.
Bram Moolenaarfc1421e2006-04-20 22:17:20 +00008471 When 'formatexpr' is set it will be used to break the line.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008472 NOTE: This option is set to 0 when 'compatible' is set.
8473
8474 *'thesaurus'* *'tsr'*
8475'thesaurus' 'tsr' string (default "")
8476 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00008477 List of file names, separated by commas, that are used to lookup words
Bram Moolenaarf4d8b762021-10-17 14:13:09 +01008478 for thesaurus completion commands |i_CTRL-X_CTRL-T|. See
8479 |compl-thesaurus|.
Bram Moolenaarf0d58ef2018-11-16 16:13:44 +01008480
Bram Moolenaarf4d8b762021-10-17 14:13:09 +01008481 This option is not used if 'thesaurusfunc' is set, either for the
8482 buffer or globally.
Bram Moolenaarf0d58ef2018-11-16 16:13:44 +01008483
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00008484 To include a comma in a file name precede it with a backslash. Spaces
Bram Moolenaar071d4272004-06-13 20:20:40 +00008485 after a comma are ignored, otherwise spaces are included in the file
Bram Moolenaarf4d8b762021-10-17 14:13:09 +01008486 name. See |option-backslash| about using backslashes. The use of
8487 |:set+=| and |:set-=| is preferred when adding or removing directories
8488 from the list. This avoids problems when a future version uses
8489 another default. Backticks cannot be used in this option for security
8490 reasons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008491
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00008492 *'thesaurusfunc'* *'tsrfu'*
Yegappan Lakshmanan160e9942021-10-16 15:41:29 +01008493'thesaurusfunc' 'tsrfu' string (default: empty)
Bram Moolenaarf4d8b762021-10-17 14:13:09 +01008494 global or local to buffer |global-local|
Yegappan Lakshmanan160e9942021-10-16 15:41:29 +01008495 {not available when compiled without the |+eval|
8496 feature}
8497 This option specifies a function to be used for thesaurus completion
Bram Moolenaarf4d8b762021-10-17 14:13:09 +01008498 with CTRL-X CTRL-T. |i_CTRL-X_CTRL-T| See |compl-thesaurusfunc|.
Yegappan Lakshmanan8658c752021-12-03 11:09:29 +00008499 The value can be the name of a function, a |lambda| or a |Funcref|.
8500 See |option-value-function| for more information.
Bram Moolenaarf4d8b762021-10-17 14:13:09 +01008501
Yegappan Lakshmanan160e9942021-10-16 15:41:29 +01008502 This option cannot be set from a |modeline| or in the |sandbox|, for
8503 security reasons.
8504
Bram Moolenaar071d4272004-06-13 20:20:40 +00008505 *'tildeop'* *'top'* *'notildeop'* *'notop'*
8506'tildeop' 'top' boolean (default off)
8507 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008508 When on: The tilde command "~" behaves like an operator.
8509 NOTE: This option is reset when 'compatible' is set.
8510
8511 *'timeout'* *'to'* *'notimeout'* *'noto'*
8512'timeout' 'to' boolean (default on)
8513 global
8514 *'ttimeout'* *'nottimeout'*
Bram Moolenaar94237492017-04-23 18:40:21 +02008515'ttimeout' boolean (default off, set in |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008516 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008517 These two options together determine the behavior when part of a
8518 mapped key sequence or keyboard code has been received:
8519
8520 'timeout' 'ttimeout' action ~
8521 off off do not time out
8522 on on or off time out on :mappings and key codes
8523 off on time out on key codes
8524
8525 If both options are off, Vim will wait until either the complete
8526 mapping or key sequence has been received, or it is clear that there
8527 is no mapping or key sequence for the received characters. For
8528 example: if you have mapped "vl" and Vim has received 'v', the next
8529 character is needed to see if the 'v' is followed by an 'l'.
8530 When one of the options is on, Vim will wait for about 1 second for
8531 the next character to arrive. After that the already received
8532 characters are interpreted as single characters. The waiting time can
8533 be changed with the 'timeoutlen' option.
8534 On slow terminals or very busy systems timing out may cause
8535 malfunctioning cursor keys. If both options are off, Vim waits
8536 forever after an entered <Esc> if there are key codes that start
8537 with <Esc>. You will have to type <Esc> twice. If you do not have
8538 problems with key codes, but would like to have :mapped key
8539 sequences not timing out in 1 second, set the 'ttimeout' option and
8540 reset the 'timeout' option.
8541
8542 NOTE: 'ttimeout' is reset when 'compatible' is set.
8543
8544 *'timeoutlen'* *'tm'*
8545'timeoutlen' 'tm' number (default 1000)
8546 global
Bram Moolenaar25c9c682019-05-05 18:13:34 +02008547
Bram Moolenaar071d4272004-06-13 20:20:40 +00008548 *'ttimeoutlen'* *'ttm'*
Bram Moolenaar94237492017-04-23 18:40:21 +02008549'ttimeoutlen' 'ttm' number (default -1, set to 100 in |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008550 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008551 The time in milliseconds that is waited for a key code or mapped key
8552 sequence to complete. Also used for CTRL-\ CTRL-N and CTRL-\ CTRL-G
8553 when part of a command has been typed.
8554 Normally only 'timeoutlen' is used and 'ttimeoutlen' is -1. When a
8555 different timeout value for key codes is desired set 'ttimeoutlen' to
8556 a non-negative number.
8557
8558 ttimeoutlen mapping delay key code delay ~
8559 < 0 'timeoutlen' 'timeoutlen'
8560 >= 0 'timeoutlen' 'ttimeoutlen'
8561
8562 The timeout only happens when the 'timeout' and 'ttimeout' options
8563 tell so. A useful setting would be >
8564 :set timeout timeoutlen=3000 ttimeoutlen=100
8565< (time out on mapping after three seconds, time out on key codes after
8566 a tenth of a second).
8567
8568 *'title'* *'notitle'*
8569'title' boolean (default off, on when title can be restored)
8570 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008571 When on, the title of the window will be set to the value of
8572 'titlestring' (if it is not empty), or to:
8573 filename [+=-] (path) - VIM
8574 Where:
8575 filename the name of the file being edited
8576 - indicates the file cannot be modified, 'ma' off
8577 + indicates the file was modified
8578 = indicates the file is read-only
8579 =+ indicates the file is read-only and modified
8580 (path) is the path of the file being edited
8581 - VIM the server name |v:servername| or "VIM"
8582 Only works if the terminal supports setting window titles
8583 (currently Amiga console, Win32 console, all GUI versions and
Bram Moolenaard1caa942020-04-10 22:10:56 +02008584 terminals with a non-empty 't_ts' option - these are Unix xterm and
Bram Moolenaar071d4272004-06-13 20:20:40 +00008585 iris-ansi by default, where 't_ts' is taken from the builtin termcap).
8586 *X11*
8587 When Vim was compiled with HAVE_X11 defined, the original title will
8588 be restored if possible. The output of ":version" will include "+X11"
8589 when HAVE_X11 was defined, otherwise it will be "-X11". This also
8590 works for the icon name |'icon'|.
8591 But: When Vim was started with the |-X| argument, restoring the title
8592 will not work (except in the GUI).
8593 If the title cannot be restored, it is set to the value of 'titleold'.
8594 You might want to restore the title outside of Vim then.
8595 When using an xterm from a remote machine you can use this command:
8596 rsh machine_name xterm -display $DISPLAY &
8597 then the WINDOWID environment variable should be inherited and the
8598 title of the window should change back to what it should be after
8599 exiting Vim.
8600
8601 *'titlelen'*
8602'titlelen' number (default 85)
8603 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008604 Gives the percentage of 'columns' to use for the length of the window
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00008605 title. When the title is longer, only the end of the path name is
8606 shown. A '<' character before the path name is used to indicate this.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008607 Using a percentage makes this adapt to the width of the window. But
8608 it won't work perfectly, because the actual number of characters
8609 available also depends on the font used and other things in the title
8610 bar. When 'titlelen' is zero the full path is used. Otherwise,
8611 values from 1 to 30000 percent can be used.
8612 'titlelen' is also used for the 'titlestring' option.
8613
8614 *'titleold'*
8615'titleold' string (default "Thanks for flying Vim")
8616 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008617 This option will be used for the window title when exiting Vim if the
8618 original title cannot be restored. Only happens if 'title' is on or
8619 'titlestring' is not empty.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00008620 This option cannot be set from a |modeline| or in the |sandbox|, for
8621 security reasons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008622 *'titlestring'*
8623'titlestring' string (default "")
8624 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008625 When this option is not empty, it will be used for the title of the
8626 window. This happens only when the 'title' option is on.
8627 Only works if the terminal supports setting window titles (currently
8628 Amiga console, Win32 console, all GUI versions and terminals with a
8629 non-empty 't_ts' option).
8630 When Vim was compiled with HAVE_X11 defined, the original title will
Bram Moolenaar51628222016-12-01 23:03:28 +01008631 be restored if possible, see |X11|.
Bram Moolenaar110289e2019-05-23 15:38:06 +02008632
Bram Moolenaar071d4272004-06-13 20:20:40 +00008633 When this option contains printf-style '%' items, they will be
8634 expanded according to the rules used for 'statusline'.
Bram Moolenaar110289e2019-05-23 15:38:06 +02008635 This option cannot be set in a modeline when 'modelineexpr' is off.
8636
Bram Moolenaar071d4272004-06-13 20:20:40 +00008637 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008638 :auto BufEnter * let &titlestring = hostname() .. "/" .. expand("%:p")
Bram Moolenaar071d4272004-06-13 20:20:40 +00008639 :set title titlestring=%<%F%=%l/%L-%P titlelen=70
8640< The value of 'titlelen' is used to align items in the middle or right
8641 of the available space.
8642 Some people prefer to have the file name first: >
8643 :set titlestring=%t%(\ %M%)%(\ (%{expand(\"%:~:.:h\")})%)%(\ %a%)
8644< Note the use of "%{ }" and an expression to get the path of the file,
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00008645 without the file name. The "%( %)" constructs are used to add a
Bram Moolenaar071d4272004-06-13 20:20:40 +00008646 separating space only when needed.
8647 NOTE: Use of special characters in 'titlestring' may cause the display
8648 to be garbled (e.g., when it contains a CR or NL character).
8649 {not available when compiled without the |+statusline| feature}
8650
8651 *'toolbar'* *'tb'*
8652'toolbar' 'tb' string (default "icons,tooltips")
8653 global
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01008654 {only for |+GUI_GTK|, |+GUI_Motif| and |+GUI_Photon|}
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00008655 The contents of this option controls various toolbar settings. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00008656 possible values are:
8657 icons Toolbar buttons are shown with icons.
8658 text Toolbar buttons shown with text.
8659 horiz Icon and text of a toolbar button are
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00008660 horizontally arranged. {only in GTK+ 2 GUI}
Bram Moolenaar071d4272004-06-13 20:20:40 +00008661 tooltips Tooltips are active for toolbar buttons.
8662 Tooltips refer to the popup help text which appears after the mouse
8663 cursor is placed over a toolbar button for a brief moment.
8664
8665 If you want the toolbar to be shown with icons as well as text, do the
8666 following: >
8667 :set tb=icons,text
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01008668< Motif cannot display icons and text at the same time. They
Bram Moolenaar071d4272004-06-13 20:20:40 +00008669 will show icons if both are requested.
8670
8671 If none of the strings specified in 'toolbar' are valid or if
8672 'toolbar' is empty, this option is ignored. If you want to disable
8673 the toolbar, you need to set the 'guioptions' option. For example: >
8674 :set guioptions-=T
8675< Also see |gui-toolbar|.
8676
8677 *'toolbariconsize'* *'tbis'*
8678'toolbariconsize' 'tbis' string (default "small")
8679 global
Bram Moolenaar3df01732017-02-17 22:47:16 +01008680 {only in the GTK+ GUI}
Bram Moolenaar071d4272004-06-13 20:20:40 +00008681 Controls the size of toolbar icons. The possible values are:
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01008682 tiny Use tiny icons.
8683 small Use small icons (default).
8684 medium Use medium-sized icons.
8685 large Use large icons.
8686 huge Use even larger icons.
8687 giant Use very big icons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008688 The exact dimensions in pixels of the various icon sizes depend on
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01008689 the current theme. Common dimensions are giant=48x48, huge=32x32,
8690 large=24x24, medium=24x24, small=20x20 and tiny=16x16.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008691
8692 If 'toolbariconsize' is empty, the global default size as determined
8693 by user preferences or the current theme is used.
8694
8695 *'ttybuiltin'* *'tbi'* *'nottybuiltin'* *'notbi'*
8696'ttybuiltin' 'tbi' boolean (default on)
8697 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008698 When on, the builtin termcaps are searched before the external ones.
8699 When off the builtin termcaps are searched after the external ones.
8700 When this option is changed, you should set the 'term' option next for
8701 the change to take effect, for example: >
8702 :set notbi term=$TERM
8703< See also |termcap|.
8704 Rationale: The default for this option is "on", because the builtin
8705 termcap entries are generally better (many systems contain faulty
8706 xterm entries...).
8707
8708 *'ttyfast'* *'tf'* *'nottyfast'* *'notf'*
Bram Moolenaarc1cf4c92022-11-25 15:09:35 +00008709'ttyfast' 'tf' boolean (default on)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008710 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008711 Indicates a fast terminal connection. More characters will be sent to
8712 the screen for redrawing, instead of using insert/delete line
8713 commands. Improves smoothness of redrawing when there are multiple
8714 windows and the terminal does not support a scrolling region.
8715 Also enables the extra writing of characters at the end of each screen
8716 line for lines that wrap. This helps when using copy/paste with the
8717 mouse in an xterm and other terminals.
8718
Bram Moolenaarc1cf4c92022-11-25 15:09:35 +00008719 The default used to be set only for some terminal names, but these
8720 days nearly all terminals are fast, therefore the default is now "on".
8721 If you have a slow connection you may want to set this option off,
8722 e.g. depending on the host name: >
8723 if hostname() =~ 'faraway'
8724 set nottyfast
8725 endif
8726<
Bram Moolenaar071d4272004-06-13 20:20:40 +00008727 *'ttymouse'* *'ttym'*
8728'ttymouse' 'ttym' string (default depends on 'term')
8729 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008730 {only in Unix and VMS, doesn't work in the GUI; not
8731 available when compiled without |+mouse|}
8732 Name of the terminal type for which mouse codes are to be recognized.
Bram Moolenaar2c7a7632007-05-10 18:19:11 +00008733 Currently these strings are valid:
Bram Moolenaar071d4272004-06-13 20:20:40 +00008734 *xterm-mouse*
8735 xterm xterm-like mouse handling. The mouse generates
8736 "<Esc>[Mscr", where "scr" is three bytes:
8737 "s" = button state
8738 "c" = column plus 33
8739 "r" = row plus 33
Bram Moolenaare968e362014-05-13 20:23:24 +02008740 This only works up to 223 columns! See "dec",
8741 "urxvt", and "sgr" for solutions.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008742 xterm2 Works like "xterm", but with the xterm reporting the
8743 mouse position while the mouse is dragged. This works
8744 much faster and more precise. Your xterm must at
Bram Moolenaarbc7aa852005-03-06 23:38:09 +00008745 least at patchlevel 88 / XFree 3.3.3 for this to
Bram Moolenaar071d4272004-06-13 20:20:40 +00008746 work. See below for how Vim detects this
8747 automatically.
8748 *netterm-mouse*
Bram Moolenaar25c9c682019-05-05 18:13:34 +02008749 netterm NetTerm mouse handling. A left mouse click generates
Bram Moolenaar071d4272004-06-13 20:20:40 +00008750 "<Esc>}r,c<CR>", where "r,c" are two decimal numbers
Bram Moolenaar25c9c682019-05-05 18:13:34 +02008751 for the row and column. No other mouse events are
8752 supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008753 *dec-mouse*
8754 dec DEC terminal mouse handling. The mouse generates a
8755 rather complex sequence, starting with "<Esc>[".
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00008756 This is also available for an Xterm, if it was
8757 configured with "--enable-dec-locator".
Bram Moolenaar071d4272004-06-13 20:20:40 +00008758 *jsbterm-mouse*
8759 jsbterm JSB term mouse handling.
8760 *pterm-mouse*
8761 pterm QNX pterm mouse handling.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01008762 *urxvt-mouse*
8763 urxvt Mouse handling for the urxvt (rxvt-unicode) terminal.
Bram Moolenaare968e362014-05-13 20:23:24 +02008764 The mouse works only if the terminal supports this
8765 encoding style, but it does not have 223 columns limit
8766 unlike "xterm" or "xterm2".
Bram Moolenaar9b451252012-08-15 17:43:31 +02008767 *sgr-mouse*
8768 sgr Mouse handling for the terminal that emits SGR-styled
Bram Moolenaare968e362014-05-13 20:23:24 +02008769 mouse reporting. The mouse works even in columns
8770 beyond 223. This option is backward compatible with
8771 "xterm2" because it can also decode "xterm2" style
8772 mouse codes.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008773
8774 The mouse handling must be enabled at compile time |+mouse_xterm|
Bram Moolenaare968e362014-05-13 20:23:24 +02008775 |+mouse_dec| |+mouse_netterm| |+mouse_jsbterm| |+mouse_urxvt|
8776 |+mouse_sgr|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008777 Only "xterm"(2) is really recognized. NetTerm mouse codes are always
8778 recognized, if enabled at compile time. DEC terminal mouse codes
8779 are recognized if enabled at compile time, and 'ttymouse' is not
Bram Moolenaare968e362014-05-13 20:23:24 +02008780 "xterm", "xterm2", "urxvt" or "sgr" (because dec mouse codes conflict
8781 with them).
Bram Moolenaar071d4272004-06-13 20:20:40 +00008782 This option is automatically set to "xterm", when the 'term' option is
Bram Moolenaar45758762016-10-12 23:08:06 +02008783 set to a name that starts with "xterm", "mlterm", "screen", "tmux",
8784 "st" (full match only), "st-" or "stterm", and 'ttymouse' is not set
8785 already.
Bram Moolenaar06cd14d2023-01-10 12:37:38 +00008786 If the terminfo/termcap entry "XM" exists and the first number is
8787 "1006" then 'ttymouse' will be set to "sgr". This works for many
8788 modern terminals.
Bram Moolenaare968e362014-05-13 20:23:24 +02008789 Additionally, if vim is compiled with the |+termresponse| feature and
8790 |t_RV| is set to the escape sequence to request the xterm version
Bram Moolenaarf8a07122019-07-01 22:06:07 +02008791 number, more intelligent detection is done.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008792 The "xterm2" value will be set if the xterm version is reported to be
Bram Moolenaard47d5222018-12-09 20:43:55 +01008793 from 95 to 276. The "sgr" value will be set if Vim detects Mac
8794 Terminal.app, iTerm2 or mintty, and when the xterm version is 277 or
8795 higher.
Bram Moolenaare968e362014-05-13 20:23:24 +02008796 If you do not want 'ttymouse' to be set to "xterm2" or "sgr"
8797 automatically, set t_RV to an empty string: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00008798 :set t_RV=
8799<
8800 *'ttyscroll'* *'tsl'*
8801'ttyscroll' 'tsl' number (default 999)
8802 global
8803 Maximum number of lines to scroll the screen. If there are more lines
8804 to scroll the window is redrawn. For terminals where scrolling is
8805 very slow and redrawing is not slow this can be set to a small number,
8806 e.g., 3, to speed up displaying.
8807
8808 *'ttytype'* *'tty'*
8809'ttytype' 'tty' string (default from $TERM)
8810 global
8811 Alias for 'term', see above.
8812
Bram Moolenaar55debbe2010-05-23 23:34:36 +02008813 *'undodir'* *'udir'*
8814'undodir' 'udir' string (default ".")
8815 global
Bram Moolenaardb84e452010-08-15 13:50:43 +02008816 {only when compiled with the |+persistent_undo| feature}
Bram Moolenaar55debbe2010-05-23 23:34:36 +02008817 List of directory names for undo files, separated with commas.
Bram Moolenaarb230bd52010-05-25 21:02:00 +02008818 See |'backupdir'| for details of the format.
Bram Moolenaar6a244fe2010-05-24 22:02:24 +02008819 "." means using the directory of the file. The undo file name for
8820 "file.txt" is ".file.txt.un~".
8821 For other directories the file name is the full path of the edited
8822 file, with path separators replaced with "%".
Bram Moolenaar55debbe2010-05-23 23:34:36 +02008823 When writing: The first directory that exists is used. "." always
8824 works, no directories after "." will be used for writing.
8825 When reading all entries are tried to find an undo file. The first
8826 undo file that exists is used. When it cannot be read an error is
8827 given, no further entry is used.
8828 See |undo-persistence|.
Bram Moolenaar110289e2019-05-23 15:38:06 +02008829 This option cannot be set from a |modeline| or in the |sandbox|, for
8830 security reasons.
Bram Moolenaar55debbe2010-05-23 23:34:36 +02008831
Bram Moolenaar543b7ef2013-06-01 14:50:56 +02008832 *'undofile'* *'noundofile'* *'udf'* *'noudf'*
Bram Moolenaar55debbe2010-05-23 23:34:36 +02008833'undofile' 'udf' boolean (default off)
8834 local to buffer
Bram Moolenaardb84e452010-08-15 13:50:43 +02008835 {only when compiled with the |+persistent_undo| feature}
Bram Moolenaar55debbe2010-05-23 23:34:36 +02008836 When on, Vim automatically saves undo history to an undo file when
8837 writing a buffer to a file, and restores undo history from the same
8838 file on buffer read.
Bram Moolenaarb230bd52010-05-25 21:02:00 +02008839 The directory where the undo file is stored is specified by 'undodir'.
8840 For more information about this feature see |undo-persistence|.
Bram Moolenaar59f931e2010-07-24 20:27:03 +02008841 The undo file is not read when 'undoreload' causes the buffer from
8842 before a reload to be saved for undo.
Bram Moolenaar97d62492012-11-15 21:28:22 +01008843 When 'undofile' is turned off the undo file is NOT deleted.
Bram Moolenaar036986f2017-03-16 17:41:02 +01008844 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaar55debbe2010-05-23 23:34:36 +02008845
Bram Moolenaar071d4272004-06-13 20:20:40 +00008846 *'undolevels'* *'ul'*
Bram Moolenaar8024f932020-01-14 19:29:13 +01008847'undolevels' 'ul' number (default 100, 1000 for Unix, VMS and Win32)
Bram Moolenaarf5a2fd82013-11-06 05:26:15 +01008848 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00008849 Maximum number of changes that can be undone. Since undo information
Bram Moolenaar5be4cee2019-09-27 19:34:08 +02008850 is kept in memory, higher numbers will cause more memory to be used.
8851 Nevertheless, a single change can already use a large amount of memory.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008852 Set to 0 for Vi compatibility: One level of undo and "u" undoes
8853 itself: >
8854 set ul=0
8855< But you can also get Vi compatibility by including the 'u' flag in
8856 'cpoptions', and still be able to use CTRL-R to repeat undo.
Bram Moolenaar945e2db2010-06-05 17:43:32 +02008857 Also see |undo-two-ways|.
Bram Moolenaarf5a2fd82013-11-06 05:26:15 +01008858 Set to -1 for no undo at all. You might want to do this only for the
8859 current buffer: >
8860 setlocal ul=-1
Bram Moolenaar071d4272004-06-13 20:20:40 +00008861< This helps when you run out of memory for a single change.
Bram Moolenaar32efaf62014-11-05 17:02:17 +01008862
8863 The local value is set to -123456 when the global value is to be used.
8864
Bram Moolenaar945e2db2010-06-05 17:43:32 +02008865 Also see |clear-undo|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008866
Bram Moolenaar59f931e2010-07-24 20:27:03 +02008867 *'undoreload'* *'ur'*
8868'undoreload' 'ur' number (default 10000)
8869 global
Bram Moolenaar59f931e2010-07-24 20:27:03 +02008870 Save the whole buffer for undo when reloading it. This applies to the
8871 ":e!" command and reloading for when the buffer changed outside of
8872 Vim. |FileChangedShell|
Bram Moolenaar24a98a02017-09-27 22:23:55 +02008873 The save only happens when this option is negative or when the number
Bram Moolenaar59f931e2010-07-24 20:27:03 +02008874 of lines is smaller than the value of this option.
8875 Set this option to zero to disable undo for a reload.
8876
8877 When saving undo for a reload, any undo file is not read.
8878
8879 Note that this causes the whole buffer to be stored in memory. Set
8880 this option to a lower value if you run out of memory.
8881
Bram Moolenaar071d4272004-06-13 20:20:40 +00008882 *'updatecount'* *'uc'*
8883'updatecount' 'uc' number (default: 200)
8884 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008885 After typing this many characters the swap file will be written to
8886 disk. When zero, no swap file will be created at all (see chapter on
8887 recovery |crash-recovery|). 'updatecount' is set to zero by starting
8888 Vim with the "-n" option, see |startup|. When editing in readonly
8889 mode this option will be initialized to 10000.
8890 The swapfile can be disabled per buffer with |'swapfile'|.
8891 When 'updatecount' is set from zero to non-zero, swap files are
8892 created for all buffers that have 'swapfile' set. When 'updatecount'
8893 is set to zero, existing swap files are not deleted.
8894 Also see |'swapsync'|.
8895 This option has no meaning in buffers where |'buftype'| is "nofile"
8896 or "nowrite".
8897
8898 *'updatetime'* *'ut'*
8899'updatetime' 'ut' number (default 4000)
8900 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008901 If this many milliseconds nothing is typed the swap file will be
8902 written to disk (see |crash-recovery|). Also used for the
8903 |CursorHold| autocommand event.
8904
Bram Moolenaar04958cb2018-06-23 19:23:02 +02008905 *'varsofttabstop'* *'vsts'*
8906'varsofttabstop' 'vsts' string (default "")
8907 local to buffer
8908 {only available when compiled with the |+vartabs|
8909 feature}
Bram Moolenaar04958cb2018-06-23 19:23:02 +02008910 A list of the number of spaces that a <Tab> counts for while editing,
8911 such as inserting a <Tab> or using <BS>. It "feels" like variable-
8912 width <Tab>s are being inserted, while in fact a mixture of spaces
8913 and <Tab>s is used. Tab widths are separated with commas, with the
8914 final value applying to all subsequent tabs.
8915
8916 For example, when editing assembly language files where statements
Bram Moolenaar6dc819b2018-07-03 16:42:19 +02008917 start in the 9th column and comments in the 41st, it may be useful
Bram Moolenaar04958cb2018-06-23 19:23:02 +02008918 to use the following: >
8919 :set varsofttabstop=8,32,8
Bram Moolenaar6dc819b2018-07-03 16:42:19 +02008920< This will set soft tabstops with 8 and 8 + 32 spaces, and 8 more
8921 for every column thereafter.
Bram Moolenaar04958cb2018-06-23 19:23:02 +02008922
8923 Note that the value of |'softtabstop'| will be ignored while
8924 'varsofttabstop' is set.
8925
8926 *'vartabstop'* *'vts'*
8927'vartabstop' 'vts' string (default "")
8928 local to buffer
8929 {only available when compiled with the |+vartabs|
8930 feature}
Bram Moolenaar04958cb2018-06-23 19:23:02 +02008931 A list of the number of spaces that a <Tab> in the file counts for,
8932 separated by commas. Each value corresponds to one tab, with the
8933 final value applying to all subsequent tabs. For example: >
8934 :set vartabstop=4,20,10,8
8935< This will make the first tab 4 spaces wide, the second 20 spaces,
8936 the third 10 spaces, and all following tabs 8 spaces.
8937
8938 Note that the value of |'tabstop'| will be ignored while 'vartabstop'
8939 is set.
8940
Bram Moolenaar071d4272004-06-13 20:20:40 +00008941 *'verbose'* *'vbs'*
8942'verbose' 'vbs' number (default 0)
8943 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008944 When bigger than zero, Vim will give messages about what it is doing.
8945 Currently, these messages are given:
8946 >= 1 When the viminfo file is read or written.
8947 >= 2 When a file is ":source"'ed.
Bram Moolenaar647a5302020-05-03 17:01:24 +02008948 >= 4 Shell commands.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00008949 >= 5 Every searched tags file and include file.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008950 >= 8 Files for which a group of autocommands is executed.
8951 >= 9 Every executed autocommand.
Bram Moolenaar647a5302020-05-03 17:01:24 +02008952 >= 11 Finding items in a path
Bram Moolenaar071d4272004-06-13 20:20:40 +00008953 >= 12 Every executed function.
8954 >= 13 When an exception is thrown, caught, finished, or discarded.
8955 >= 14 Anything pending in a ":finally" clause.
Bram Moolenaar823654b2020-05-29 23:03:09 +02008956 >= 15 Every executed Ex command from a script (truncated at 200
8957 characters).
Bram Moolenaare7b1ea02020-08-07 19:54:59 +02008958 >= 16 Every executed Ex command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008959
8960 This option can also be set with the "-V" argument. See |-V|.
8961 This option is also set by the |:verbose| command.
8962
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +00008963 When the 'verbosefile' option is set then the verbose messages are not
8964 displayed.
8965
8966 *'verbosefile'* *'vfile'*
8967'verbosefile' 'vfile' string (default empty)
8968 global
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +00008969 When not empty all messages are written in a file with this name.
8970 When the file exists messages are appended.
8971 Writing to the file ends when Vim exits or when 'verbosefile' is made
Bram Moolenaar80794b12010-06-13 05:20:42 +02008972 empty. Writes are buffered, thus may not show up for some time.
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +00008973 Setting 'verbosefile' to a new value is like making it empty first.
8974 The difference with |:redir| is that verbose messages are not
8975 displayed when 'verbosefile' is set.
8976
Bram Moolenaar071d4272004-06-13 20:20:40 +00008977 *'viewdir'* *'vdir'*
h_east59858792023-10-25 22:47:05 +09008978'viewdir' 'vdir' string (default for Amiga: "home:vimfiles/view",
Bram Moolenaar801961d2023-06-23 16:15:13 +01008979 for Win32: "$HOME/vimfiles/view",
Christian Brabandtb8b1c8e2023-06-23 22:23:01 +01008980 for Unix: "$HOME/.vim/view",
h_east59858792023-10-25 22:47:05 +09008981 for macOS: "$VIM/vimfiles/view",
Bram Moolenaar801961d2023-06-23 16:15:13 +01008982 for VMS: "sys$login:vimfiles/view")
Bram Moolenaar071d4272004-06-13 20:20:40 +00008983 global
Bram Moolenaardb84e452010-08-15 13:50:43 +02008984 {not available when compiled without the |+mksession|
Bram Moolenaar071d4272004-06-13 20:20:40 +00008985 feature}
8986 Name of the directory where to store files for |:mkview|.
8987 This option cannot be set from a |modeline| or in the |sandbox|, for
8988 security reasons.
8989
8990 *'viewoptions'* *'vop'*
Bram Moolenaar13e90412017-11-11 18:16:48 +01008991'viewoptions' 'vop' string (default: "folds,options,cursor,curdir")
Bram Moolenaar071d4272004-06-13 20:20:40 +00008992 global
Bram Moolenaardb84e452010-08-15 13:50:43 +02008993 {not available when compiled without the |+mksession|
Bram Moolenaar071d4272004-06-13 20:20:40 +00008994 feature}
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01008995 Changes the effect of the |:mkview| command. It is a comma-separated
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00008996 list of words. Each word enables saving and restoring something:
Bram Moolenaar071d4272004-06-13 20:20:40 +00008997 word save and restore ~
8998 cursor cursor position in file and in window
8999 folds manually created folds, opened/closed folds and local
9000 fold options
9001 options options and mappings local to a window or buffer (not
9002 global values for local options)
Bram Moolenaar6e932462014-09-09 18:48:09 +02009003 localoptions same as "options"
Bram Moolenaar071d4272004-06-13 20:20:40 +00009004 slash backslashes in file names replaced with forward
9005 slashes
9006 unix with Unix end-of-line format (single <NL>), even when
Bram Moolenaar6f345a12019-12-17 21:27:18 +01009007 on MS-Windows
Bram Moolenaar13e90412017-11-11 18:16:48 +01009008 curdir the window-local directory, if set with `:lcd`
Bram Moolenaar071d4272004-06-13 20:20:40 +00009009
Bram Moolenaar6f345a12019-12-17 21:27:18 +01009010 "slash" and "unix" are useful on MS-Windows when sharing view files
Bram Moolenaar071d4272004-06-13 20:20:40 +00009011 with Unix. The Unix version of Vim cannot source dos format scripts,
Bram Moolenaar6f345a12019-12-17 21:27:18 +01009012 but the MS-Windows version of Vim can source unix format scripts.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009013
9014 *'viminfo'* *'vi'* *E526* *E527* *E528*
Bram Moolenaar6f345a12019-12-17 21:27:18 +01009015'viminfo' 'vi' string (Vi default: "", Vim default for
9016 MS-Windows: '100,<50,s10,h,rA:,rB:,
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01009017 for Amiga: '100,<50,s10,h,rdf0:,rdf1:,rdf2:
9018 for others: '100,<50,s10,h)
Bram Moolenaar071d4272004-06-13 20:20:40 +00009019 global
Bram Moolenaardb84e452010-08-15 13:50:43 +02009020 {not available when compiled without the |+viminfo|
Bram Moolenaar071d4272004-06-13 20:20:40 +00009021 feature}
9022 When non-empty, the viminfo file is read upon startup and written
Bram Moolenaarc4da1132017-07-15 19:39:43 +02009023 when exiting Vim (see |viminfo-file|). Except when 'viminfofile' is
9024 "NONE".
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01009025 The string should be a comma-separated list of parameters, each
Bram Moolenaarc4da1132017-07-15 19:39:43 +02009026 consisting of a single character identifying the particular parameter,
9027 followed by a number or string which specifies the value of that
9028 parameter. If a particular character is left out, then the default
9029 value is used for that parameter. The following is a list of the
9030 identifying characters and the effect of their value.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009031 CHAR VALUE ~
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01009032 *viminfo-!*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009033 ! When included, save and restore global variables that start
9034 with an uppercase letter, and don't contain a lowercase
9035 letter. Thus "KEEPTHIS and "K_L_M" are stored, but "KeepThis"
Bram Moolenaar680eeca2010-10-20 17:44:42 +02009036 and "_K_L_M" are not. Nested List and Dict items may not be
Bram Moolenaar166af9b2010-11-16 20:34:40 +01009037 read back correctly, you end up with an empty item.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01009038 *viminfo-quote*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009039 " Maximum number of lines saved for each register. Old name of
9040 the '<' item, with the disadvantage that you need to put a
9041 backslash before the ", otherwise it will be recognized as the
9042 start of a comment!
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01009043 *viminfo-%*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009044 % When included, save and restore the buffer list. If Vim is
9045 started with a file name argument, the buffer list is not
9046 restored. If Vim is started without a file name argument, the
Bram Moolenaard042dc82015-11-24 19:18:36 +01009047 buffer list is restored from the viminfo file. Quickfix
9048 ('buftype'), unlisted ('buflisted'), unnamed and buffers on
9049 removable media (|viminfo-r|) are not saved.
Bram Moolenaar15d0a8c2004-09-06 17:44:46 +00009050 When followed by a number, the number specifies the maximum
9051 number of buffers that are stored. Without a number all
9052 buffers are stored.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01009053 *viminfo-'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009054 ' Maximum number of previously edited files for which the marks
9055 are remembered. This parameter must always be included when
9056 'viminfo' is non-empty.
9057 Including this item also means that the |jumplist| and the
9058 |changelist| are stored in the viminfo file.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01009059 *viminfo-/*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009060 / Maximum number of items in the search pattern history to be
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00009061 saved. If non-zero, then the previous search and substitute
Bram Moolenaar071d4272004-06-13 20:20:40 +00009062 patterns are also saved. When not included, the value of
9063 'history' is used.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01009064 *viminfo-:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009065 : Maximum number of items in the command-line history to be
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00009066 saved. When not included, the value of 'history' is used.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01009067 *viminfo-<*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009068 < Maximum number of lines saved for each register. If zero then
9069 registers are not saved. When not included, all lines are
9070 saved. '"' is the old name for this item.
9071 Also see the 's' item below: limit specified in Kbyte.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01009072 *viminfo-@*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009073 @ Maximum number of items in the input-line history to be
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00009074 saved. When not included, the value of 'history' is used.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01009075 *viminfo-c*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009076 c When included, convert the text in the viminfo file from the
9077 'encoding' used when writing the file to the current
Bram Moolenaar582fd852005-03-28 20:58:01 +00009078 'encoding'. See |viminfo-encoding|.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01009079 *viminfo-f*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009080 f Whether file marks need to be stored. If zero, file marks ('0
9081 to '9, 'A to 'Z) are not stored. When not present or when
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00009082 non-zero, they are all stored. '0 is used for the current
Bram Moolenaar071d4272004-06-13 20:20:40 +00009083 cursor position (when exiting or when doing ":wviminfo").
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01009084 *viminfo-h*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009085 h Disable the effect of 'hlsearch' when loading the viminfo
9086 file. When not included, it depends on whether ":nohlsearch"
9087 has been used since the last search command.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01009088 *viminfo-n*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009089 n Name of the viminfo file. The name must immediately follow
Bram Moolenaarc4da1132017-07-15 19:39:43 +02009090 the 'n'. Must be at the end of the option! If the
9091 'viminfofile' option is set, that file name overrides the one
9092 given here with 'viminfo'. Environment variables are
Bram Moolenaar063b9d12016-07-09 20:21:48 +02009093 expanded when opening the file, not when setting the option.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01009094 *viminfo-r*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009095 r Removable media. The argument is a string (up to the next
9096 ','). This parameter can be given several times. Each
9097 specifies the start of a path for which no marks will be
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01009098 stored. This is to avoid removable media. For MS-Windows you
Bram Moolenaar071d4272004-06-13 20:20:40 +00009099 could use "ra:,rb:", for Amiga "rdf0:,rdf1:,rdf2:". You can
9100 also use it for temp files, e.g., for Unix: "r/tmp". Case is
9101 ignored. Maximum length of each 'r' argument is 50
9102 characters.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01009103 *viminfo-s*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009104 s Maximum size of an item in Kbyte. If zero then registers are
9105 not saved. Currently only applies to registers. The default
9106 "s10" will exclude registers with more than 10 Kbyte of text.
9107 Also see the '<' item above: line count limit.
9108
9109 Example: >
9110 :set viminfo='50,<1000,s100,:0,n~/vim/viminfo
9111<
9112 '50 Marks will be remembered for the last 50 files you
9113 edited.
9114 <1000 Contents of registers (up to 1000 lines each) will be
9115 remembered.
9116 s100 Registers with more than 100 Kbyte text are skipped.
9117 :0 Command-line history will not be saved.
9118 n~/vim/viminfo The name of the file to use is "~/vim/viminfo".
9119 no / Since '/' is not specified, the default will be used,
9120 that is, save all of the search history, and also the
9121 previous search and substitute patterns.
9122 no % The buffer list will not be saved nor read back.
9123 no h 'hlsearch' highlighting will be restored.
9124
9125 When setting 'viminfo' from an empty value you can use |:rviminfo| to
9126 load the contents of the file, this is not done automatically.
9127
9128 This option cannot be set from a |modeline| or in the |sandbox|, for
9129 security reasons.
Bram Moolenaar036986f2017-03-16 17:41:02 +01009130 NOTE: This option is set to the Vim default value when 'compatible'
9131 is reset.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009132
Bram Moolenaarc4da1132017-07-15 19:39:43 +02009133 *'viminfofile'* *'vif'*
9134'viminfofile' 'vif' string (default: "")
9135 global
Bram Moolenaarc4da1132017-07-15 19:39:43 +02009136 {not available when compiled without the |+viminfo|
9137 feature}
9138 When non-empty, overrides the file name used for viminfo.
9139 When equal to "NONE" no viminfo file will be read or written.
9140 This option can be set with the |-i| command line flag. The |--clean|
9141 command line flag sets it to "NONE".
Bram Moolenaar110289e2019-05-23 15:38:06 +02009142 This option cannot be set from a |modeline| or in the |sandbox|, for
9143 security reasons.
Bram Moolenaarc4da1132017-07-15 19:39:43 +02009144
Bram Moolenaar071d4272004-06-13 20:20:40 +00009145 *'virtualedit'* *'ve'*
9146'virtualedit' 've' string (default "")
Gary Johnson51ad8502021-08-03 18:33:08 +02009147 global or local to window |global-local|
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01009148 A comma-separated list of these words:
Bram Moolenaar071d4272004-06-13 20:20:40 +00009149 block Allow virtual editing in Visual block mode.
9150 insert Allow virtual editing in Insert mode.
9151 all Allow virtual editing in all modes.
Bram Moolenaarefd2bf12006-03-16 21:41:35 +00009152 onemore Allow the cursor to move just past the end of the line
Gary Johnson53ba05b2021-07-26 22:19:10 +02009153 none When used as the local value, do not allow virtual
9154 editing even when the global value is set. When used
9155 as the global value, "none" is the same as "".
9156 NONE Alternative spelling of "none".
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00009157
Bram Moolenaar071d4272004-06-13 20:20:40 +00009158 Virtual editing means that the cursor can be positioned where there is
Bram Moolenaarebcbd022007-05-12 14:28:25 +00009159 no actual character. This can be halfway into a tab or beyond the end
Bram Moolenaar071d4272004-06-13 20:20:40 +00009160 of the line. Useful for selecting a rectangle in Visual mode and
9161 editing a table.
Bram Moolenaarefd2bf12006-03-16 21:41:35 +00009162 "onemore" is not the same, it will only allow moving the cursor just
9163 after the last character of the line. This makes some commands more
9164 consistent. Previously the cursor was always past the end of the line
9165 if the line was empty. But it is far from Vi compatible. It may also
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00009166 break some plugins or Vim scripts. For example because |l| can move
9167 the cursor after the last character. Use with care!
Bram Moolenaar9ba7e172013-07-17 22:37:26 +02009168 Using the `$` command will move to the last character in the line, not
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00009169 past it. This may actually move the cursor to the left!
Bram Moolenaar9ba7e172013-07-17 22:37:26 +02009170 The `g$` command will move to the end of the screen line.
Bram Moolenaarefd2bf12006-03-16 21:41:35 +00009171 It doesn't make sense to combine "all" with "onemore", but you will
9172 not get a warning for it.
Bram Moolenaar53f7fcc2021-07-28 20:10:16 +02009173 When combined with other words, "none" is ignored.
Bram Moolenaar036986f2017-03-16 17:41:02 +01009174 NOTE: This option is set to "" when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009175
9176 *'visualbell'* *'vb'* *'novisualbell'* *'novb'* *beep*
9177'visualbell' 'vb' boolean (default off)
9178 global
Bram Moolenaar74675a62017-07-15 13:53:23 +02009179 Use a visual bell instead of beeping. The terminal code to display the
Bram Moolenaar071d4272004-06-13 20:20:40 +00009180 visual bell is given with 't_vb'. When no beep or flash is wanted,
Bram Moolenaar74675a62017-07-15 13:53:23 +02009181 use: >
9182 :set vb t_vb=
9183< If you want a short flash, you can use this on many terminals: >
9184 :set vb t_vb=[?5h$<100>[?5l
9185< Here $<100> specifies the time, you can use a smaller or bigger value
9186 to get a shorter or longer flash.
9187
9188 Note: Vim will limit the bell to once per half a second. This avoids
9189 having to wait for the flashing to finish when there are lots of
9190 bells, e.g. on key repeat. This also happens without 'visualbell'
9191 set.
9192
Bram Moolenaar071d4272004-06-13 20:20:40 +00009193 In the GUI, 't_vb' defaults to "<Esc>|f", which inverts the display
9194 for 20 msec. If you want to use a different time, use "<Esc>|40f",
9195 where 40 is the time in msec.
Bram Moolenaar74675a62017-07-15 13:53:23 +02009196
9197 Note: When the GUI starts, 't_vb' is reset to its default value. You
9198 might want to set it again in your |gvimrc|.
9199
Bram Moolenaar071d4272004-06-13 20:20:40 +00009200 Does not work on the Amiga, you always get a screen flash.
9201 Also see 'errorbells'.
9202
9203 *'warn'* *'nowarn'*
9204'warn' boolean (default on)
9205 global
9206 Give a warning message when a shell command is used while the buffer
9207 has been changed.
9208
9209 *'weirdinvert'* *'wiv'* *'noweirdinvert'* *'nowiv'*
9210'weirdinvert' 'wiv' boolean (default off)
9211 global
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00009212 This option has the same effect as the 't_xs' terminal option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009213 It is provided for backwards compatibility with version 4.x.
9214 Setting 'weirdinvert' has the effect of making 't_xs' non-empty, and
9215 vice versa. Has no effect when the GUI is running.
9216
9217 *'whichwrap'* *'ww'*
9218'whichwrap' 'ww' string (Vim default: "b,s", Vi default: "")
9219 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00009220 Allow specified keys that move the cursor left/right to move to the
9221 previous/next line when the cursor is on the first/last character in
9222 the line. Concatenate characters to allow this for these keys:
9223 char key mode ~
9224 b <BS> Normal and Visual
9225 s <Space> Normal and Visual
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00009226 h "h" Normal and Visual (not recommended)
9227 l "l" Normal and Visual (not recommended)
Bram Moolenaar071d4272004-06-13 20:20:40 +00009228 < <Left> Normal and Visual
9229 > <Right> Normal and Visual
9230 ~ "~" Normal
9231 [ <Left> Insert and Replace
9232 ] <Right> Insert and Replace
9233 For example: >
9234 :set ww=<,>,[,]
9235< allows wrap only when cursor keys are used.
9236 When the movement keys are used in combination with a delete or change
9237 operator, the <EOL> also counts for a character. This makes "3h"
9238 different from "3dh" when the cursor crosses the end of a line. This
9239 is also true for "x" and "X", because they do the same as "dl" and
9240 "dh". If you use this, you may also want to use the mapping
9241 ":map <BS> X" to make backspace delete the character in front of the
9242 cursor.
Bram Moolenaar362e1a32006-03-06 23:29:24 +00009243 When 'l' is included and it is used after an operator at the end of a
Bram Moolenaar589edb32019-09-20 14:38:13 +02009244 line (not an empty line) then it will not move to the next line. This
9245 makes "dl", "cl", "yl" etc. work normally.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009246 NOTE: This option is set to the Vi default value when 'compatible' is
9247 set and to the Vim default value when 'compatible' is reset.
9248
9249 *'wildchar'* *'wc'*
9250'wildchar' 'wc' number (Vim default: <Tab>, Vi default: CTRL-E)
9251 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00009252 Character you have to type to start wildcard expansion in the
9253 command-line, as specified with 'wildmode'.
Bram Moolenaar446cb832008-06-24 21:56:24 +00009254 More info here: |cmdline-completion|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009255 The character is not recognized when used inside a macro. See
9256 'wildcharm' for that.
Bram Moolenaar34cc7d82021-09-21 20:09:51 +02009257 Some keys will not work, such as CTRL-C, <CR> and Enter.
Yee Cheng Chin8f4fb002023-10-17 10:06:56 +02009258 <Esc> can be used, but hitting it twice in a row will still exit
9259 command-line as a failsafe measure.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009260 Although 'wc' is a number option, you can set it to a special key: >
Bram Moolenaar34cc7d82021-09-21 20:09:51 +02009261 :set wc=<Tab>
Bram Moolenaar071d4272004-06-13 20:20:40 +00009262< NOTE: This option is set to the Vi default value when 'compatible' is
9263 set and to the Vim default value when 'compatible' is reset.
9264
9265 *'wildcharm'* *'wcm'*
9266'wildcharm' 'wcm' number (default: none (0))
9267 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00009268 'wildcharm' works exactly like 'wildchar', except that it is
Bram Moolenaar582fd852005-03-28 20:58:01 +00009269 recognized when used inside a macro. You can find "spare" command-line
9270 keys suitable for this option by looking at |ex-edit-index|. Normally
Bram Moolenaar071d4272004-06-13 20:20:40 +00009271 you'll never actually type 'wildcharm', just use it in mappings that
9272 automatically invoke completion mode, e.g.: >
9273 :set wcm=<C-Z>
Bram Moolenaar446cb832008-06-24 21:56:24 +00009274 :cnoremap ss so $vim/sessions/*.vim<C-Z>
Bram Moolenaar071d4272004-06-13 20:20:40 +00009275< Then after typing :ss you can use CTRL-P & CTRL-N.
9276
9277 *'wildignore'* *'wig'*
9278'wildignore' 'wig' string (default "")
9279 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00009280 A list of file patterns. A file that matches with one of these
Bram Moolenaar30b65812012-07-12 22:01:11 +02009281 patterns is ignored when expanding |wildcards|, completing file or
9282 directory names, and influences the result of |expand()|, |glob()| and
9283 |globpath()| unless a flag is passed to disable this.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009284 The pattern is used like with |:autocmd|, see |autocmd-patterns|.
9285 Also see 'suffixes'.
9286 Example: >
9287 :set wildignore=*.o,*.obj
9288< The use of |:set+=| and |:set-=| is preferred when adding or removing
9289 a pattern from the list. This avoids problems when a future version
9290 uses another default.
9291
Bram Moolenaar94950a92010-12-02 16:01:29 +01009292
Bram Moolenaar81af9252010-12-10 20:35:50 +01009293 *'wildignorecase'* *'wic'* *'nowildignorecase'* *'nowic'*
Bram Moolenaar94950a92010-12-02 16:01:29 +01009294'wildignorecase' 'wic' boolean (default off)
9295 global
Bram Moolenaar94950a92010-12-02 16:01:29 +01009296 When set case is ignored when completing file names and directories.
Bram Moolenaar71afbfe2013-03-19 16:49:16 +01009297 Has no effect when 'fileignorecase' is set.
Bram Moolenaar94950a92010-12-02 16:01:29 +01009298 Does not apply when the shell is used to expand wildcards, which
9299 happens when there are special characters.
9300
9301
Bram Moolenaar071d4272004-06-13 20:20:40 +00009302 *'wildmenu'* *'wmnu'* *'nowildmenu'* *'nowmnu'*
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +02009303'wildmenu' 'wmnu' boolean (default off, set in |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00009304 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00009305 When 'wildmenu' is on, command-line completion operates in an enhanced
9306 mode. On pressing 'wildchar' (usually <Tab>) to invoke completion,
Bram Moolenaar54162322022-08-26 16:58:51 +01009307 the possible matches are shown.
9308 When 'wildoptions' contains "pum", then the completion matches are
9309 shown in a popup menu. Otherwise they are displayed just above the
9310 command line, with the first match highlighted (overwriting the status
9311 line, if there is one).
Yegappan Lakshmanan3908ef52022-02-08 12:08:07 +00009312 Keys that show the previous/next match, such as <Tab> or
Bram Moolenaar071d4272004-06-13 20:20:40 +00009313 CTRL-P/CTRL-N, cause the highlight to move to the appropriate match.
9314 When 'wildmode' is used, "wildmenu" mode is used where "full" is
9315 specified. "longest" and "list" do not start "wildmenu" mode.
Bram Moolenaar26402cb2013-02-20 21:26:00 +01009316 You can check the current mode with |wildmenumode()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009317 If there are more matches than can fit in the line, a ">" is shown on
9318 the right and/or a "<" is shown on the left. The status line scrolls
9319 as needed.
9320 The "wildmenu" mode is abandoned when a key is hit that is not used
9321 for selecting a completion.
Yee Cheng Chin2bbd0d32023-10-14 02:23:45 -07009322 While the "wildmenu" is active, the following keys have special
9323 meanings:
9324 CTRL-P - go to the previous entry
9325 CTRL-N - go to the next entry
Bram Moolenaar071d4272004-06-13 20:20:40 +00009326 <CR> - in menu completion, when the cursor is just after a
9327 dot: move into a submenu.
Yee Cheng Chin209ec902023-10-17 10:56:25 +02009328 CTRL-E - end completion, go back to what was there before
9329 selecting a match.
9330 CTRL-Y - accept the currently selected match and stop
9331 completion.
Yee Cheng Chin2bbd0d32023-10-14 02:23:45 -07009332
9333 When not using the popup menu for command line completion, the
9334 following keys have special meanings:
9335 <Left> <Right> - select previous/next match (like CTRL-P/CTRL-N)
Bram Moolenaar071d4272004-06-13 20:20:40 +00009336 <Up> - in filename/menu name completion: move up into
9337 parent directory or parent menu.
Yee Cheng Chin2bbd0d32023-10-14 02:23:45 -07009338 <Down> - in filename/menu name completion: move into a
9339 subdirectory or submenu.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009340
Yegappan Lakshmanan3908ef52022-02-08 12:08:07 +00009341 When using the popup menu for command line completion, the following
9342 keys have special meanings:
Yee Cheng Chin2bbd0d32023-10-14 02:23:45 -07009343 <Up> <Down> - select previous/next match (like CTRL-P/CTRL-N)
zeertzjq3c81f472023-10-15 16:02:08 +08009344 <PageUp> - select a match several entries back
9345 <PageDown> - select a match several entries further
Yegappan Lakshmanan3908ef52022-02-08 12:08:07 +00009346 <Left> - in filename/menu name completion: move up into
9347 parent directory or parent menu.
9348 <Right> - in filename/menu name completion: move into a
9349 subdirectory or submenu.
Yegappan Lakshmanan3908ef52022-02-08 12:08:07 +00009350
Bram Moolenaar071d4272004-06-13 20:20:40 +00009351 This makes the menus accessible from the console |console-menus|.
9352
9353 If you prefer the <Left> and <Right> keys to move the cursor instead
9354 of selecting a different match, use this: >
9355 :cnoremap <Left> <Space><BS><Left>
9356 :cnoremap <Right> <Space><BS><Right>
9357<
9358 The "WildMenu" highlighting is used for displaying the current match
9359 |hl-WildMenu|.
9360
9361 *'wildmode'* *'wim'*
9362'wildmode' 'wim' string (Vim default: "full")
9363 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00009364 Completion mode that is used for the character specified with
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01009365 'wildchar'. It is a comma-separated list of up to four parts. Each
Bram Moolenaar02467872007-05-06 13:22:01 +00009366 part specifies what to do for each consecutive use of 'wildchar'. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00009367 first part specifies the behavior for the first use of 'wildchar',
9368 The second part for the second use, etc.
Bram Moolenaar130cbfc2021-04-07 21:07:20 +02009369
9370 Each part consists of a colon separated list consisting of the
9371 following possible values:
Bram Moolenaar071d4272004-06-13 20:20:40 +00009372 "" Complete only the first match.
9373 "full" Complete the next full match. After the last match,
9374 the original string is used and then the first match
Bram Moolenaar130cbfc2021-04-07 21:07:20 +02009375 again. Will also start 'wildmenu' if it is enabled.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009376 "longest" Complete till longest common string. If this doesn't
9377 result in a longer string, use the next part.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009378 "list" When more than one match, list all matches.
Bram Moolenaar130cbfc2021-04-07 21:07:20 +02009379 "lastused" When completing buffer names and more than one buffer
9380 matches, sort buffers by time last used (other than
9381 the current buffer).
9382 When there is only a single match, it is fully completed in all cases.
9383
9384 Examples of useful colon-separated values:
9385 "longest:full" Like "longest", but also start 'wildmenu' if it is
9386 enabled. Will not complete to the next full match.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009387 "list:full" When more than one match, list all matches and
9388 complete first match.
9389 "list:longest" When more than one match, list all matches and
9390 complete till longest common string.
Bram Moolenaar130cbfc2021-04-07 21:07:20 +02009391 "list:lastused" When more than one buffer matches, list all matches
9392 and sort buffers by time last used (other than the
9393 current buffer).
Bram Moolenaar071d4272004-06-13 20:20:40 +00009394
9395 Examples: >
9396 :set wildmode=full
Bram Moolenaar582fd852005-03-28 20:58:01 +00009397< Complete first full match, next match, etc. (the default) >
Bram Moolenaar071d4272004-06-13 20:20:40 +00009398 :set wildmode=longest,full
9399< Complete longest common string, then each full match >
9400 :set wildmode=list:full
9401< List all matches and complete each full match >
9402 :set wildmode=list,full
9403< List all matches without completing, then each full match >
9404 :set wildmode=longest,list
9405< Complete longest common string, then list alternatives.
Bram Moolenaar446cb832008-06-24 21:56:24 +00009406 More info here: |cmdline-completion|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009407
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00009408 *'wildoptions'* *'wop'*
9409'wildoptions' 'wop' string (default "")
9410 global
Yegappan Lakshmanan3908ef52022-02-08 12:08:07 +00009411 A list of words that change how |cmdline-completion| is done.
9412 The following values are supported:
Bram Moolenaar1588bc82022-03-08 21:35:07 +00009413 fuzzy Use |fuzzy-matching| to find completion matches. When
Yegappan Lakshmanan38b85cb2022-02-24 13:28:41 +00009414 this value is specified, wildcard expansion will not
9415 be used for completion. The matches will be sorted by
9416 the "best match" rather than alphabetically sorted.
9417 This will find more matches than the wildcard
9418 expansion. Currently fuzzy matching based completion
9419 is not supported for file and directory names and
9420 instead wildcard expansion is used.
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01009421 pum Display the completion matches using the popup menu
Yegappan Lakshmanan3908ef52022-02-08 12:08:07 +00009422 in the same style as the |ins-completion-menu|.
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00009423 tagfile When using CTRL-D to list matching tags, the kind of
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00009424 tag and the file of the tag is listed. Only one match
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00009425 is displayed per line. Often used tag kinds are:
9426 d #define
9427 f function
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00009428
Bram Moolenaar071d4272004-06-13 20:20:40 +00009429 *'winaltkeys'* *'wak'*
9430'winaltkeys' 'wak' string (default "menu")
9431 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00009432 {only used in Win32, Motif, GTK and Photon GUI}
9433 Some GUI versions allow the access to menu entries by using the ALT
9434 key in combination with a character that appears underlined in the
9435 menu. This conflicts with the use of the ALT key for mappings and
9436 entering special characters. This option tells what to do:
9437 no Don't use ALT keys for menus. ALT key combinations can be
9438 mapped, but there is no automatic handling. This can then be
9439 done with the |:simalt| command.
9440 yes ALT key handling is done by the windowing system. ALT key
9441 combinations cannot be mapped.
9442 menu Using ALT in combination with a character that is a menu
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00009443 shortcut key, will be handled by the windowing system. Other
Bram Moolenaar071d4272004-06-13 20:20:40 +00009444 keys can be mapped.
9445 If the menu is disabled by excluding 'm' from 'guioptions', the ALT
9446 key is never used for the menu.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00009447 This option is not used for <F10>; on Win32 and with GTK <F10> will
9448 select the menu, unless it has been mapped.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009449
Bram Moolenaar4d784b22019-05-25 19:51:39 +02009450 *'wincolor'* *'wcr'*
9451'wincolor' 'wcr' string (default empty)
9452 local to window
9453 Highlight group name to use for this window instead of the Normal
9454 color |hl-Normal|.
9455
Bram Moolenaar4399ef42005-02-12 14:29:27 +00009456 *'window'* *'wi'*
9457'window' 'wi' number (default screen height - 1)
9458 global
Bram Moolenaardad44732021-03-31 20:07:33 +02009459 Window height used for |CTRL-F| and |CTRL-B| when there is only one
9460 window and the value is smaller than 'lines' minus one. The screen
9461 will scroll 'window' minus two lines, with a minimum of one.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00009462 When 'window' is equal to 'lines' minus one CTRL-F and CTRL-B scroll
9463 in a much smarter way, taking care of wrapping lines.
9464 When resizing the Vim window, the value is smaller than 1 or more than
9465 or equal to 'lines' it will be set to 'lines' minus 1.
Bram Moolenaardad44732021-03-31 20:07:33 +02009466 Note: Do not confuse this with the height of the Vim window, use
9467 'lines' for that.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00009468
Bram Moolenaar071d4272004-06-13 20:20:40 +00009469 *'winheight'* *'wh'* *E591*
9470'winheight' 'wh' number (default 1)
9471 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00009472 Minimal number of lines for the current window. This is not a hard
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00009473 minimum, Vim will use fewer lines if there is not enough room. If the
Bram Moolenaar446cb832008-06-24 21:56:24 +00009474 focus goes to a window that is smaller, its size is increased, at the
9475 cost of the height of other windows.
9476 Set 'winheight' to a small number for normal editing.
9477 Set it to 999 to make the current window fill most of the screen.
9478 Other windows will be only 'winminheight' high. This has the drawback
9479 that ":all" will create only two windows. To avoid "vim -o 1 2 3 4"
9480 to create only two windows, set the option after startup is done,
9481 using the |VimEnter| event: >
9482 au VimEnter * set winheight=999
9483< Minimum value is 1.
9484 The height is not adjusted after one of the commands that change the
Bram Moolenaar071d4272004-06-13 20:20:40 +00009485 height of the current window.
9486 'winheight' applies to the current window. Use 'winminheight' to set
9487 the minimal height for other windows.
9488
9489 *'winfixheight'* *'wfh'* *'nowinfixheight'* *'nowfh'*
9490'winfixheight' 'wfh' boolean (default off)
Christian Brabandt596ad662023-08-16 00:11:09 +02009491 local to window |local-noglobal|
Bram Moolenaar071d4272004-06-13 20:20:40 +00009492 Keep the window height when windows are opened or closed and
Bram Moolenaar02467872007-05-06 13:22:01 +00009493 'equalalways' is set. Also for |CTRL-W_=|. Set by default for the
9494 |preview-window| and |quickfix-window|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009495 The height may be changed anyway when running out of room.
9496
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00009497 *'winfixwidth'* *'wfw'* *'nowinfixwidth'* *'nowfw'*
9498'winfixwidth' 'wfw' boolean (default off)
Christian Brabandt596ad662023-08-16 00:11:09 +02009499 local to window |local-noglobal|
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00009500 Keep the window width when windows are opened or closed and
Bram Moolenaar02467872007-05-06 13:22:01 +00009501 'equalalways' is set. Also for |CTRL-W_=|.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00009502 The width may be changed anyway when running out of room.
9503
Bram Moolenaar071d4272004-06-13 20:20:40 +00009504 *'winminheight'* *'wmh'*
9505'winminheight' 'wmh' number (default 1)
9506 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00009507 The minimal height of a window, when it's not the current window.
9508 This is a hard minimum, windows will never become smaller.
9509 When set to zero, windows may be "squashed" to zero lines (i.e. just a
9510 status bar) if necessary. They will return to at least one line when
9511 they become active (since the cursor has to have somewhere to go.)
9512 Use 'winheight' to set the minimal height of the current window.
9513 This option is only checked when making a window smaller. Don't use a
9514 large number, it will cause errors when opening more than a few
9515 windows. A value of 0 to 3 is reasonable.
9516
9517 *'winminwidth'* *'wmw'*
9518'winminwidth' 'wmw' number (default 1)
9519 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00009520 The minimal width of a window, when it's not the current window.
9521 This is a hard minimum, windows will never become smaller.
9522 When set to zero, windows may be "squashed" to zero columns (i.e. just
9523 a vertical separator) if necessary. They will return to at least one
9524 line when they become active (since the cursor has to have somewhere
9525 to go.)
9526 Use 'winwidth' to set the minimal width of the current window.
9527 This option is only checked when making a window smaller. Don't use a
9528 large number, it will cause errors when opening more than a few
9529 windows. A value of 0 to 12 is reasonable.
9530
Bram Moolenaar9e13aa72017-08-16 23:14:08 +02009531 *'winptydll'*
9532'winptydll' string (default "winpty32.dll" or "winpty64.dll")
9533 global
Bram Moolenaar9e13aa72017-08-16 23:14:08 +02009534 {only available when compiled with the |terminal|
9535 feature on MS-Windows}
9536 Specifies the name of the winpty shared library, used for the
Bram Moolenaare7b1ea02020-08-07 19:54:59 +02009537 |:terminal| command. The default depends on whether Vim was built as a
Bram Moolenaarc572da52017-08-27 16:52:01 +02009538 32-bit or 64-bit executable. If not found, "winpty.dll" is tried as
Bram Moolenaar9e13aa72017-08-16 23:14:08 +02009539 a fallback.
9540 Environment variables are expanded |:set_env|.
9541 This option cannot be set from a |modeline| or in the |sandbox|, for
9542 security reasons.
9543
Bram Moolenaar071d4272004-06-13 20:20:40 +00009544 *'winwidth'* *'wiw'* *E592*
9545'winwidth' 'wiw' number (default 20)
9546 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00009547 Minimal number of columns for the current window. This is not a hard
9548 minimum, Vim will use fewer columns if there is not enough room. If
9549 the current window is smaller, its size is increased, at the cost of
9550 the width of other windows. Set it to 999 to make the current window
9551 always fill the screen. Set it to a small number for normal editing.
9552 The width is not adjusted after one of the commands to change the
9553 width of the current window.
9554 'winwidth' applies to the current window. Use 'winminwidth' to set
9555 the minimal width for other windows.
9556
9557 *'wrap'* *'nowrap'*
9558'wrap' boolean (default on)
9559 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00009560 This option changes how text is displayed. It doesn't change the text
9561 in the buffer, see 'textwidth' for that.
9562 When on, lines longer than the width of the window will wrap and
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00009563 displaying continues on the next line. When off lines will not wrap
9564 and only part of long lines will be displayed. When the cursor is
Bram Moolenaar071d4272004-06-13 20:20:40 +00009565 moved to a part that is not shown, the screen will scroll
9566 horizontally.
9567 The line will be broken in the middle of a word if necessary. See
9568 'linebreak' to get the break at a word boundary.
9569 To make scrolling horizontally a bit more useful, try this: >
9570 :set sidescroll=5
9571 :set listchars+=precedes:<,extends:>
9572< See 'sidescroll', 'listchars' and |wrap-off|.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01009573 This option can't be set from a |modeline| when the 'diff' option is
9574 on.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009575
9576 *'wrapmargin'* *'wm'*
9577'wrapmargin' 'wm' number (default 0)
9578 local to buffer
9579 Number of characters from the right window border where wrapping
9580 starts. When typing text beyond this limit, an <EOL> will be inserted
9581 and inserting continues on the next line.
9582 Options that add a margin, such as 'number' and 'foldcolumn', cause
9583 the text width to be further reduced. This is Vi compatible.
9584 When 'textwidth' is non-zero, this option is not used.
Bram Moolenaarca635012015-09-25 20:34:21 +02009585 This option is set to 0 when 'paste' is set and restored when 'paste'
9586 is reset.
Bram Moolenaara6c27c42019-05-09 19:16:22 +02009587 See also 'formatoptions' and |ins-textwidth|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009588
9589 *'wrapscan'* *'ws'* *'nowrapscan'* *'nows'*
9590'wrapscan' 'ws' boolean (default on) *E384* *E385*
9591 global
Bram Moolenaarac6e65f2005-08-29 22:25:38 +00009592 Searches wrap around the end of the file. Also applies to |]s| and
9593 |[s|, searching for spelling mistakes.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009594
9595 *'write'* *'nowrite'*
9596'write' boolean (default on)
9597 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00009598 Allows writing files. When not set, writing a file is not allowed.
9599 Can be used for a view-only mode, where modifications to the text are
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00009600 still allowed. Can be reset with the |-m| or |-M| command line
Bram Moolenaar071d4272004-06-13 20:20:40 +00009601 argument. Filtering text is still possible, even though this requires
9602 writing a temporary file.
9603
9604 *'writeany'* *'wa'* *'nowriteany'* *'nowa'*
9605'writeany' 'wa' boolean (default off)
9606 global
9607 Allows writing to any file with no need for "!" override.
9608
9609 *'writebackup'* *'wb'* *'nowritebackup'* *'nowb'*
9610'writebackup' 'wb' boolean (default on with |+writebackup| feature, off
9611 otherwise)
9612 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00009613 Make a backup before overwriting a file. The backup is removed after
9614 the file was successfully written, unless the 'backup' option is
Bram Moolenaar1aeaf8c2012-05-18 13:46:39 +02009615 also on.
9616 WARNING: Switching this option off means that when Vim fails to write
9617 your buffer correctly and then, for whatever reason, Vim exits, you
9618 lose both the original file and what you were writing. Only reset
9619 this option if your file system is almost full and it makes the write
9620 fail (and make sure not to exit Vim until the write was successful).
9621 See |backup-table| for another explanation.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009622 When the 'backupskip' pattern matches, a backup is not made anyway.
Bram Moolenaar0c0734d2019-11-26 21:44:46 +01009623 Depending on 'backupcopy' the backup is a new file or the original
9624 file renamed (and a new file is written).
Bram Moolenaar071d4272004-06-13 20:20:40 +00009625 NOTE: This option is set to the default value when 'compatible' is
9626 set.
9627
9628 *'writedelay'* *'wd'*
9629'writedelay' 'wd' number (default 0)
9630 global
Bram Moolenaar802a0d92016-06-26 16:17:58 +02009631 The number of milliseconds to wait for each character sent to the
Bram Moolenaar071d4272004-06-13 20:20:40 +00009632 screen. When non-zero, characters are sent to the terminal one by
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01009633 one. For debugging purposes.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009634
Bram Moolenaar6f79e612021-12-21 09:12:23 +00009635 *'xtermcodes'* *'noxtermcodes'*
9636'xtermcodes' boolean (default on)
9637 global
9638 When detecting xterm patchlevel 141 or higher with the termresponse
Bram Moolenaarfa3b7232021-12-24 13:18:38 +00009639 mechanism and this option is set, Vim will request the actual terminal
Bram Moolenaar6f79e612021-12-21 09:12:23 +00009640 key codes and number of colors from the terminal. This takes care of
9641 various configuration options of the terminal that cannot be obtained
9642 from the termlib/terminfo entry, see |xterm-codes|.
9643 A side effect may be that t_Co changes and Vim will redraw the
9644 display.
9645
9646
Bram Moolenaar91f84f62018-07-29 15:07:52 +02009647 vim:tw=78:ts=8:noet:ft=help:norl: