blob: 3c0ba4c6844bf3a4a762534c568db3328f95ee15 [file] [log] [blame]
h_east596a9f22023-11-21 21:24:23 +09001*options.txt* For Vim version 9.0. Last change: 2023 Nov 20
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
njohnstonaabca252023-11-19 23:18:57 +00001427 appear halfway through 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.
dkearns8ebdbc92023-10-29 06:26:19 +11001607 This option cannot be set from a |modeline| or in the |sandbox|, for
1608 security reasons.
Bram Moolenaar7b1463b2021-12-11 17:24:39 +00001609 NOTE: This option is reset when 'compatible' is set.
1610
Bram Moolenaar071d4272004-06-13 20:20:40 +00001611 *'cdpath'* *'cd'* *E344* *E346*
1612'cdpath' 'cd' string (default: equivalent to $CDPATH or ",,")
1613 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001614 This is a list of directories which will be searched when using the
Bram Moolenaar00aa0692019-04-27 20:37:57 +02001615 |:cd|, |:tcd| and |:lcd| commands, provided that the directory being
1616 searched for has a relative path, not an absolute part starting with
1617 "/", "./" or "../", the 'cdpath' option is not used then.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001618 The 'cdpath' option's value has the same form and semantics as
1619 |'path'|. Also see |file-searching|.
1620 The default value is taken from $CDPATH, with a "," prepended to look
1621 in the current directory first.
1622 If the default value taken from $CDPATH is not what you want, include
1623 a modified version of the following command in your vimrc file to
1624 override it: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001625 :let &cdpath = ',' .. substitute(substitute($CDPATH, '[, ]', '\\\0', 'g'), ':', ',', 'g')
Bram Moolenaar071d4272004-06-13 20:20:40 +00001626< This option cannot be set from a |modeline| or in the |sandbox|, for
1627 security reasons.
1628 (parts of 'cdpath' can be passed to the shell to expand file names).
1629
1630 *'cedit'*
1631'cedit' string (Vi default: "", Vim default: CTRL-F)
1632 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001633 The key used in Command-line Mode to open the command-line window.
1634 The default is CTRL-F when 'compatible' is off.
1635 Only non-printable keys are allowed.
1636 The key can be specified as a single character, but it is difficult to
1637 type. The preferred way is to use the <> notation. Examples: >
Bram Moolenaare18dbe82016-07-02 21:42:23 +02001638 :exe "set cedit=\<C-Y>"
1639 :exe "set cedit=\<Esc>"
Bram Moolenaar071d4272004-06-13 20:20:40 +00001640< |Nvi| also has this option, but it only uses the first character.
1641 See |cmdwin|.
Bram Moolenaar036986f2017-03-16 17:41:02 +01001642 NOTE: This option is set to the Vim default value when 'compatible'
1643 is reset.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001644
1645 *'charconvert'* *'ccv'* *E202* *E214* *E513*
1646'charconvert' 'ccv' string (default "")
1647 global
Bram Moolenaar4c92e752019-02-17 21:18:32 +01001648 {only available when compiled with the |+eval| feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001649 An expression that is used for character encoding conversion. It is
1650 evaluated when a file that is to be read or has been written has a
1651 different encoding from what is desired.
1652 'charconvert' is not used when the internal iconv() function is
1653 supported and is able to do the conversion. Using iconv() is
1654 preferred, because it is much faster.
1655 'charconvert' is not used when reading stdin |--|, because there is no
1656 file to convert from. You will have to save the text in a file first.
Bram Moolenaarf10911e2022-01-29 22:20:48 +00001657 The expression must return zero, false or an empty string for success,
1658 non-zero or true for failure.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001659 The possible encoding names encountered are in 'encoding'.
1660 Additionally, names given in 'fileencodings' and 'fileencoding' are
1661 used.
1662 Conversion between "latin1", "unicode", "ucs-2", "ucs-4" and "utf-8"
1663 is done internally by Vim, 'charconvert' is not used for this.
1664 'charconvert' is also used to convert the viminfo file, if the 'c'
1665 flag is present in 'viminfo'. Also used for Unicode conversion.
1666 Example: >
1667 set charconvert=CharConvert()
1668 fun CharConvert()
1669 system("recode "
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001670 \ .. v:charconvert_from .. ".." .. v:charconvert_to
1671 \ .. " <" .. v:fname_in .. " >" .. v:fname_out)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001672 return v:shell_error
1673 endfun
1674< The related Vim variables are:
1675 v:charconvert_from name of the current encoding
1676 v:charconvert_to name of the desired encoding
1677 v:fname_in name of the input file
1678 v:fname_out name of the output file
1679 Note that v:fname_in and v:fname_out will never be the same.
1680 Note that v:charconvert_from and v:charconvert_to may be different
1681 from 'encoding'. Vim internally uses UTF-8 instead of UCS-2 or UCS-4.
Bram Moolenaarf10911e2022-01-29 22:20:48 +00001682
Bram Moolenaara4e0b972022-10-01 19:43:52 +01001683 The advantage of using a function call without arguments is that it is
1684 faster, see |expr-option-function|.
1685
Bram Moolenaar071d4272004-06-13 20:20:40 +00001686 Encryption is not done by Vim when using 'charconvert'. If you want
1687 to encrypt the file after conversion, 'charconvert' should take care
1688 of this.
Bram Moolenaarf10911e2022-01-29 22:20:48 +00001689
1690 If the 'charconvert' expression starts with s: or |<SID>|, then it is
1691 replaced with the script ID (|local-function|). Example: >
1692 set charconvert=s:MyConvert()
1693 set charconvert=<SID>SomeConvert()
1694< Otherwise the expression is evaluated in the context of the script
1695 where the option was set, thus script-local items are available.
1696
Bram Moolenaar071d4272004-06-13 20:20:40 +00001697 This option cannot be set from a |modeline| or in the |sandbox|, for
1698 security reasons.
1699
1700 *'cindent'* *'cin'* *'nocindent'* *'nocin'*
1701'cindent' 'cin' boolean (default off)
1702 local to buffer
Bram Moolenaar446cb832008-06-24 21:56:24 +00001703 Enables automatic C program indenting. See 'cinkeys' to set the keys
Bram Moolenaar071d4272004-06-13 20:20:40 +00001704 that trigger reindenting in insert mode and 'cinoptions' to set your
1705 preferred indent style.
1706 If 'indentexpr' is not empty, it overrules 'cindent'.
1707 If 'lisp' is not on and both 'indentexpr' and 'equalprg' are empty,
1708 the "=" operator indents using this algorithm rather than calling an
1709 external program.
1710 See |C-indenting|.
1711 When you don't like the way 'cindent' works, try the 'smartindent'
1712 option or 'indentexpr'.
1713 This option is not used when 'paste' is set.
1714 NOTE: This option is reset when 'compatible' is set.
1715
1716 *'cinkeys'* *'cink'*
Bram Moolenaarce655742019-01-31 14:12:57 +01001717'cinkeys' 'cink' string (default "0{,0},0),0],:,0#,!^F,o,O,e")
Bram Moolenaar071d4272004-06-13 20:20:40 +00001718 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001719 A list of keys that, when typed in Insert mode, cause reindenting of
1720 the current line. Only used if 'cindent' is on and 'indentexpr' is
1721 empty.
1722 For the format of this option see |cinkeys-format|.
1723 See |C-indenting|.
1724
1725 *'cinoptions'* *'cino'*
1726'cinoptions' 'cino' string (default "")
1727 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001728 The 'cinoptions' affect the way 'cindent' reindents lines in a C
1729 program. See |cinoptions-values| for the values of this option, and
1730 |C-indenting| for info on C indenting in general.
1731
1732
1733 *'cinwords'* *'cinw'*
1734'cinwords' 'cinw' string (default "if,else,while,do,for,switch")
1735 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001736 These keywords start an extra indent in the next line when
1737 'smartindent' or 'cindent' is set. For 'cindent' this is only done at
1738 an appropriate place (inside {}).
1739 Note that 'ignorecase' isn't used for 'cinwords'. If case doesn't
1740 matter, include the keyword both the uppercase and lowercase:
1741 "if,If,IF".
1742
Tom Praschan3506cf32022-04-07 12:39:08 +01001743 *'cinscopedecls'* *'cinsd'*
1744'cinscopedecls' 'cinsd' string (default "public,protected,private")
1745 local to buffer
Tom Praschan3506cf32022-04-07 12:39:08 +01001746 Keywords that are interpreted as a C++ scope declaration by |cino-g|.
1747 Useful e.g. for working with the Qt framework that defines additional
1748 scope declarations "signals", "public slots" and "private slots": >
1749 set cinscopedecls+=signals,public\ slots,private\ slots
1750
1751< *'clipboard'* *'cb'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001752'clipboard' 'cb' string (default "autoselect,exclude:cons\|linux"
1753 for X-windows, "" otherwise)
1754 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001755 {only in GUI versions or when the |+xterm_clipboard|
1756 feature is included}
Tom Praschan3506cf32022-04-07 12:39:08 +01001757 This option is a list of comma-separated names.
Bram Moolenaar942db232021-02-13 18:14:48 +01001758 Note: if one of the items is "exclude:", then you can't add an item
Bram Moolenaar5ed11532022-07-06 13:18:11 +01001759 after that. Therefore do not append an item with += but use ^= to
Bram Moolenaar942db232021-02-13 18:14:48 +01001760 prepend, e.g.: >
1761 set clipboard^=unnamed
Bram Moolenaar9fbdbb82022-09-27 17:30:34 +01001762< When using the GUI see |'go-A'|.
1763 These names are recognized:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001764
Bram Moolenaarc0885aa2012-07-10 16:49:23 +02001765 *clipboard-unnamed*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001766 unnamed When included, Vim will use the clipboard register '*'
1767 for all yank, delete, change and put operations which
1768 would normally go to the unnamed register. When a
1769 register is explicitly specified, it will always be
1770 used regardless of whether "unnamed" is in 'clipboard'
1771 or not. The clipboard register can always be
1772 explicitly accessed using the "* notation. Also see
1773 |gui-clipboard|.
1774
Bram Moolenaar30b65812012-07-12 22:01:11 +02001775 *clipboard-unnamedplus*
Bram Moolenaar00154502013-02-13 16:15:55 +01001776 unnamedplus A variant of the "unnamed" flag which uses the
1777 clipboard register '+' (|quoteplus|) instead of
1778 register '*' for all yank, delete, change and put
1779 operations which would normally go to the unnamed
1780 register. When "unnamed" is also included to the
1781 option, yank operations (but not delete, change or
1782 put) will additionally copy the text into register
1783 '*'.
Bram Moolenaar81af9252010-12-10 20:35:50 +01001784 Only available with the |+X11| feature.
Bram Moolenaarbf9680e2010-12-02 21:43:16 +01001785 Availability can be checked with: >
1786 if has('unnamedplus')
1787<
Bram Moolenaar30b65812012-07-12 22:01:11 +02001788 *clipboard-autoselect*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001789 autoselect Works like the 'a' flag in 'guioptions': If present,
1790 then whenever Visual mode is started, or the Visual
1791 area extended, Vim tries to become the owner of the
1792 windowing system's global selection or put the
1793 selected text on the clipboard used by the selection
Bram Moolenaarba3ff532018-11-04 14:45:49 +01001794 register "*. See |'go-a'| and |quotestar| for details.
1795 When the GUI is active, the 'a' flag in 'guioptions'
1796 is used, when the GUI is not active, this "autoselect"
1797 flag is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001798 Also applies to the modeless selection.
1799
Bram Moolenaarc0885aa2012-07-10 16:49:23 +02001800 *clipboard-autoselectplus*
1801 autoselectplus Like "autoselect" but using the + register instead of
1802 the * register. Compare to the 'P' flag in
1803 'guioptions'.
1804
1805 *clipboard-autoselectml*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001806 autoselectml Like "autoselect", but for the modeless selection
1807 only. Compare to the 'A' flag in 'guioptions'.
1808
Bram Moolenaarc0885aa2012-07-10 16:49:23 +02001809 *clipboard-html*
Bram Moolenaar3a6eaa52009-06-16 13:23:06 +00001810 html When the clipboard contains HTML, use this when
1811 pasting. When putting text on the clipboard, mark it
1812 as HTML. This works to copy rendered HTML from
1813 Firefox, paste it as raw HTML in Vim, select the HTML
1814 in Vim and paste it in a rich edit box in Firefox.
Bram Moolenaar20a825a2010-05-31 21:27:30 +02001815 You probably want to add this only temporarily,
1816 possibly use BufEnter autocommands.
Bram Moolenaar3a6eaa52009-06-16 13:23:06 +00001817 Only supported for GTK version 2 and later.
Bram Moolenaar3a6eaa52009-06-16 13:23:06 +00001818
Bram Moolenaarc0885aa2012-07-10 16:49:23 +02001819 *clipboard-exclude*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001820 exclude:{pattern}
1821 Defines a pattern that is matched against the name of
1822 the terminal 'term'. If there is a match, no
1823 connection will be made to the X server. This is
1824 useful in this situation:
1825 - Running Vim in a console.
1826 - $DISPLAY is set to start applications on another
1827 display.
1828 - You do not want to connect to the X server in the
1829 console, but do want this in a terminal emulator.
1830 To never connect to the X server use: >
1831 exclude:.*
1832< This has the same effect as using the |-X| argument.
1833 Note that when there is no connection to the X server
1834 the window title won't be restored and the clipboard
1835 cannot be accessed.
1836 The value of 'magic' is ignored, {pattern} is
1837 interpreted as if 'magic' was on.
1838 The rest of the option value will be used for
1839 {pattern}, this must be the last entry.
1840
1841 *'cmdheight'* *'ch'*
1842'cmdheight' 'ch' number (default 1)
Shougo Matsushitaf39cfb72022-07-30 16:54:05 +01001843 global or local to tab page
Bram Moolenaara2a89732022-08-31 14:46:18 +01001844 Number of screen lines to use for the command-line. A larger value
1845 helps avoiding |hit-enter| prompts.
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00001846 The value of this option is stored with the tab page, so that each tab
1847 page can have a different value.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001848
1849 *'cmdwinheight'* *'cwh'*
1850'cmdwinheight' 'cwh' number (default 7)
1851 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001852 Number of screen lines to use for the command-line window. |cmdwin|
1853
Bram Moolenaar483c5d82010-10-20 18:45:33 +02001854 *'colorcolumn'* *'cc'*
1855'colorcolumn' 'cc' string (default "")
1856 local to window
Bram Moolenaar483c5d82010-10-20 18:45:33 +02001857 {not available when compiled without the |+syntax|
1858 feature}
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01001859 'colorcolumn' is a comma-separated list of screen columns that are
Bram Moolenaar483c5d82010-10-20 18:45:33 +02001860 highlighted with ColorColumn |hl-ColorColumn|. Useful to align
1861 text. Will make screen redrawing slower.
1862 The screen column can be an absolute number, or a number preceded with
1863 '+' or '-', which is added to or subtracted from 'textwidth'. >
1864
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01001865 :set cc=+1 " highlight column after 'textwidth'
Bram Moolenaar483c5d82010-10-20 18:45:33 +02001866 :set cc=+1,+2,+3 " highlight three columns after 'textwidth'
1867 :hi ColorColumn ctermbg=lightgrey guibg=lightgrey
1868<
1869 When 'textwidth' is zero then the items with '-' and '+' are not used.
1870 A maximum of 256 columns are highlighted.
1871
Bram Moolenaar071d4272004-06-13 20:20:40 +00001872 *'columns'* *'co'* *E594*
1873'columns' 'co' number (default 80 or terminal width)
1874 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001875 Number of columns of the screen. Normally this is set by the terminal
Bram Moolenaar7c626922005-02-07 22:01:03 +00001876 initialization and does not have to be set by hand. Also see
1877 |posix-screen-size|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001878 When Vim is running in the GUI or in a resizable window, setting this
1879 option will cause the window size to be changed. When you only want
1880 to use the size for the GUI, put the command in your |gvimrc| file.
1881 When you set this option and Vim is unable to change the physical
Bram Moolenaar02467872007-05-06 13:22:01 +00001882 number of columns of the display, the display may be messed up. For
1883 the GUI it is always possible and Vim limits the number of columns to
1884 what fits on the screen. You can use this command to get the widest
1885 window possible: >
1886 :set columns=9999
1887< Minimum value is 12, maximum value is 10000.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001888
1889 *'comments'* *'com'* *E524* *E525*
1890'comments' 'com' string (default
1891 "s1:/*,mb:*,ex:*/,://,b:#,:%,:XCOMM,n:>,fb:-")
1892 local to buffer
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01001893 A comma-separated list of strings that can start a comment line. See
Bram Moolenaar071d4272004-06-13 20:20:40 +00001894 |format-comments|. See |option-backslash| about using backslashes to
1895 insert a space.
1896
1897 *'commentstring'* *'cms'* *E537*
1898'commentstring' 'cms' string (default "/*%s*/")
1899 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00001900 {not available when compiled without the |+folding|
1901 feature}
1902 A template for a comment. The "%s" in the value is replaced with the
1903 comment text. Currently only used to add markers for folding, see
1904 |fold-marker|.
1905
1906 *'compatible'* *'cp'* *'nocompatible'* *'nocp'*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001907'compatible' 'cp' boolean (default on, off when a |vimrc| or |gvimrc|
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +02001908 file is found, reset in |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001909 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00001910 This option has the effect of making Vim either more Vi-compatible, or
1911 make Vim behave in a more useful way.
Bram Moolenaar214641f2017-03-05 17:04:09 +01001912
Bram Moolenaar071d4272004-06-13 20:20:40 +00001913 This is a special kind of option, because when it's set or reset,
Bram Moolenaar214641f2017-03-05 17:04:09 +01001914 other options are also changed as a side effect.
1915 NOTE: Setting or resetting this option can have a lot of unexpected
1916 effects: Mappings are interpreted in another way, undo behaves
1917 differently, etc. If you set this option in your vimrc file, you
1918 should probably put it at the very start.
1919
Bram Moolenaar071d4272004-06-13 20:20:40 +00001920 By default this option is on and the Vi defaults are used for the
1921 options. This default was chosen for those people who want to use Vim
1922 just like Vi, and don't even (want to) know about the 'compatible'
1923 option.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001924 When a |vimrc| or |gvimrc| file is found while Vim is starting up,
Bram Moolenaard042c562005-06-30 22:04:15 +00001925 this option is switched off, and all options that have not been
1926 modified will be set to the Vim defaults. Effectively, this means
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001927 that when a |vimrc| or |gvimrc| file exists, Vim will use the Vim
Bram Moolenaard042c562005-06-30 22:04:15 +00001928 defaults, otherwise it will use the Vi defaults. (Note: This doesn't
Bram Moolenaar02467872007-05-06 13:22:01 +00001929 happen for the system-wide vimrc or gvimrc file, nor for a file given
1930 with the |-u| argument). Also see |compatible-default| and
1931 |posix-compliance|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001932 You can also set this option with the "-C" argument, and reset it with
1933 "-N". See |-C| and |-N|.
Bram Moolenaar214641f2017-03-05 17:04:09 +01001934 See 'cpoptions' for more fine tuning of Vi compatibility.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001935
Bram Moolenaar214641f2017-03-05 17:04:09 +01001936 When this option is set, numerous other options are set to make Vim as
1937 Vi-compatible as possible. When this option is unset, various options
1938 are set to make Vim more useful. The table below lists all the
1939 options affected.
1940 The {?} column indicates when the options are affected:
1941 + Means that the option is set to the value given in {set value} when
1942 'compatible' is set.
1943 & Means that the option is set to the value given in {set value} when
1944 'compatible' is set AND is set to its Vim default value when
1945 'compatible' is unset.
1946 - Means the option is NOT changed when setting 'compatible' but IS
1947 set to its Vim default when 'compatible' is unset.
1948 The {effect} column summarises the change when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001949
Bram Moolenaar036986f2017-03-16 17:41:02 +01001950 option ? set value effect ~
Bram Moolenaar214641f2017-03-05 17:04:09 +01001951
1952 'allowrevins' + off no CTRL-_ command
1953 'antialias' + off don't use antialiased fonts
Bram Moolenaarbe4e0162023-02-02 13:59:48 +00001954 'arabic' + off reset arabic-related options
Bram Moolenaar214641f2017-03-05 17:04:09 +01001955 'arabicshape' + on correct character shapes
1956 'backspace' + "" normal backspace
1957 'backup' + off no backup file
1958 'backupcopy' & Unix: "yes" backup file is a copy
1959 else: "auto" copy or rename backup file
1960 'balloonexpr' + "" text to show in evaluation balloon
1961 'breakindent' + off don't indent when wrapping lines
1962 'cedit' - {unchanged} {set vim default only on resetting 'cp'}
Bram Moolenaar7b1463b2021-12-11 17:24:39 +00001963 'cdhome' + off ":cd" don't chdir to home on non-Unix
Bram Moolenaar214641f2017-03-05 17:04:09 +01001964 'cindent' + off no C code indentation
1965 'compatible' - {unchanged} {set vim default only on resetting 'cp'}
1966 'copyindent' + off don't copy indent structure
1967 'cpoptions' & (all flags) Vi-compatible flags
1968 'cscopepathcomp'+ 0 don't show directories in tags list
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01001969 'cscoperelative'+ off don't use basename of path as prefix
Bram Moolenaar214641f2017-03-05 17:04:09 +01001970 'cscopetag' + off don't use cscope for ":tag"
Bram Moolenaar036986f2017-03-16 17:41:02 +01001971 'cscopetagorder'+ 0 see |cscopetagorder|
Bram Moolenaar214641f2017-03-05 17:04:09 +01001972 'cscopeverbose' + off see |cscopeverbose|
1973 'delcombine' + off unicode: delete whole char combination
1974 'digraph' + off no digraphs
1975 'esckeys' & off no <Esc>-keys in Insert mode
Christian Brabandt5f5131d2023-10-25 21:44:26 +02001976 this also disables |modifyOtherKeys|
1977 and |xterm-bracketed-paste|
Bram Moolenaar214641f2017-03-05 17:04:09 +01001978 'expandtab' + off tabs not expanded to spaces
1979 'fileformats' & "" no automatic file format detection,
Bram Moolenaar6f345a12019-12-17 21:27:18 +01001980 "dos,unix" except for MS-Windows
Bram Moolenaar214641f2017-03-05 17:04:09 +01001981 'formatexpr' + "" use 'formatprg' for auto-formatting
1982 'formatoptions' & "vt" Vi compatible formatting
1983 'gdefault' + off no default 'g' flag for ":s"
1984 'history' & 0 no commandline history
1985 'hkmap' + off no Hebrew keyboard mapping
1986 'hkmapp' + off no phonetic Hebrew keyboard mapping
1987 'hlsearch' + off no highlighting of search matches
1988 'incsearch' + off no incremental searching
1989 'indentexpr' + "" no indenting by expression
1990 'insertmode' + off do not start in Insert mode
1991 'iskeyword' & "@,48-57,_" keywords contain alphanumeric
Bram Moolenaar071d4272004-06-13 20:20:40 +00001992 characters and '_'
Bram Moolenaar214641f2017-03-05 17:04:09 +01001993 'joinspaces' + on insert 2 spaces after period
1994 'modeline' & off no modelines
1995 'more' & off no pauses in listings
1996 'mzquantum' - {unchanged} {set vim default only on resetting 'cp'}
1997 'numberwidth' & 8 min number of columns for line number
1998 'preserveindent'+ off don't preserve current indent structure
1999 when changing it
2000 'revins' + off no reverse insert
2001 'ruler' + off no ruler
2002 'scrolljump' + 1 no jump scroll
2003 'scrolloff' + 0 no scroll offset
2004 'shelltemp' - {unchanged} {set vim default only on resetting 'cp'}
2005 'shiftround' + off indent not rounded to shiftwidth
Bram Moolenaar9dfa3132019-05-04 21:08:40 +02002006 'shortmess' & "S" no shortening of messages
Bram Moolenaar214641f2017-03-05 17:04:09 +01002007 'showcmd' & off command characters not shown
2008 'showmode' & off current mode not shown
2009 'sidescrolloff' + 0 cursor moves to edge of screen in scroll
2010 'smartcase' + off no automatic ignore case switch
2011 'smartindent' + off no smart indentation
2012 'smarttab' + off no smart tab size
2013 'softtabstop' + 0 tabs are always 'tabstop' positions
2014 'startofline' + on goto startofline with some commands
2015 'tagcase' & "followic" 'ignorecase' when searching tags file
2016 'tagrelative' & off tag file names are not relative
2017 'termguicolors' + off don't use highlight-(guifg|guibg)
2018 'textauto' & off no automatic textmode detection
2019 'textwidth' + 0 no automatic line wrap
2020 'tildeop' + off tilde is not an operator
2021 'ttimeout' + off no terminal timeout
2022 'undofile' + off don't use an undo file
Bram Moolenaar036986f2017-03-16 17:41:02 +01002023 'viminfo' - {unchanged} {set Vim default only on resetting 'cp'}
Bram Moolenaar214641f2017-03-05 17:04:09 +01002024 'virtualedit' + "" cursor can only be placed on characters
2025 'whichwrap' & "" left-right movements don't wrap
2026 'wildchar' & CTRL-E only when the current value is <Tab>
Bram Moolenaar071d4272004-06-13 20:20:40 +00002027 use CTRL-E for cmdline completion
Bram Moolenaar214641f2017-03-05 17:04:09 +01002028 'writebackup' + on or off depends on the |+writebackup| feature
Bram Moolenaar071d4272004-06-13 20:20:40 +00002029
2030 *'complete'* *'cpt'* *E535*
2031'complete' 'cpt' string (default: ".,w,b,u,t,i")
2032 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00002033 This option specifies how keyword completion |ins-completion| works
2034 when CTRL-P or CTRL-N are used. It is also used for whole-line
2035 completion |i_CTRL-X_CTRL-L|. It indicates the type of completion
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01002036 and the places to scan. It is a comma-separated list of flags:
Bram Moolenaar3848e002016-03-19 18:42:29 +01002037 . scan the current buffer ('wrapscan' is ignored)
Bram Moolenaar071d4272004-06-13 20:20:40 +00002038 w scan buffers from other windows
2039 b scan other loaded buffers that are in the buffer list
2040 u scan the unloaded buffers that are in the buffer list
2041 U scan the buffers that are not in the buffer list
2042 k scan the files given with the 'dictionary' option
Bram Moolenaar0b238792006-03-02 22:49:12 +00002043 kspell use the currently active spell checking |spell|
Bram Moolenaar071d4272004-06-13 20:20:40 +00002044 k{dict} scan the file {dict}. Several "k" flags can be given,
2045 patterns are valid too. For example: >
2046 :set cpt=k/usr/dict/*,k~/spanish
2047< s scan the files given with the 'thesaurus' option
2048 s{tsr} scan the file {tsr}. Several "s" flags can be given, patterns
2049 are valid too.
2050 i scan current and included files
2051 d scan current and included files for defined name or macro
2052 |i_CTRL-X_CTRL-D|
2053 ] tag completion
2054 t same as "]"
2055
2056 Unloaded buffers are not loaded, thus their autocmds |:autocmd| are
2057 not executed, this may lead to unexpected completions from some files
2058 (gzipped files for example). Unloaded buffers are not scanned for
2059 whole-line completion.
2060
2061 The default is ".,w,b,u,t,i", which means to scan:
2062 1. the current buffer
2063 2. buffers in other windows
2064 3. other loaded buffers
2065 4. unloaded buffers
2066 5. tags
2067 6. included files
2068
2069 As you can see, CTRL-N and CTRL-P can be used to do any 'iskeyword'-
Bram Moolenaar582fd852005-03-28 20:58:01 +00002070 based expansion (e.g., dictionary |i_CTRL-X_CTRL-K|, included patterns
2071 |i_CTRL-X_CTRL-I|, tags |i_CTRL-X_CTRL-]| and normal expansions).
Bram Moolenaar071d4272004-06-13 20:20:40 +00002072
Bram Moolenaarcfbc5ee2004-07-02 15:38:35 +00002073 *'completefunc'* *'cfu'*
2074'completefunc' 'cfu' string (default: empty)
2075 local to buffer
Bram Moolenaardb84e452010-08-15 13:50:43 +02002076 {not available when compiled without the |+eval|
Bram Moolenaare2c453d2019-08-21 14:37:09 +02002077 feature}
Bram Moolenaarc7486e02005-12-29 22:48:26 +00002078 This option specifies a function to be used for Insert mode completion
2079 with CTRL-X CTRL-U. |i_CTRL-X_CTRL-U|
Bram Moolenaar280f1262006-01-30 00:14:18 +00002080 See |complete-functions| for an explanation of how the function is
Yegappan Lakshmanan8658c752021-12-03 11:09:29 +00002081 invoked and what it should return. The value can be the name of a
2082 function, a |lambda| or a |Funcref|. See |option-value-function| for
2083 more information.
Bram Moolenaar166af9b2010-11-16 20:34:40 +01002084 This option cannot be set from a |modeline| or in the |sandbox|, for
2085 security reasons.
Bram Moolenaar325b7a22004-07-05 15:58:32 +00002086
Bram Moolenaarac3150d2019-07-28 16:36:39 +02002087 *'completeslash'* *'csl'*
2088'completeslash' 'csl' string (default: "")
2089 local to buffer
Bram Moolenaar2e693a82019-10-16 22:35:02 +02002090 {only for MS-Windows}
Bram Moolenaarac3150d2019-07-28 16:36:39 +02002091 When this option is set it overrules 'shellslash' for completion:
2092 - When this option is set to "slash", a forward slash is used for path
2093 completion in insert mode. This is useful when editing HTML tag, or
Bram Moolenaar6f345a12019-12-17 21:27:18 +01002094 Makefile with 'noshellslash' on MS-Windows.
Bram Moolenaarac3150d2019-07-28 16:36:39 +02002095 - When this option is set to "backslash", backslash is used. This is
Bram Moolenaar6f345a12019-12-17 21:27:18 +01002096 useful when editing a batch file with 'shellslash' set on MS-Windows.
Bram Moolenaarac3150d2019-07-28 16:36:39 +02002097 - When this option is empty, same character is used as for
2098 'shellslash'.
2099 For Insert mode completion the buffer-local value is used. For
2100 command line completion the global value is used.
2101
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00002102 *'completeopt'* *'cot'*
Bram Moolenaar96d2c5b2006-03-11 21:27:59 +00002103'completeopt' 'cot' string (default: "menu,preview")
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00002104 global
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01002105 A comma-separated list of options for Insert mode completion
Bram Moolenaarc7453f52006-02-10 23:20:28 +00002106 |ins-completion|. The supported values are:
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00002107
2108 menu Use a popup menu to show the possible completions. The
2109 menu is only shown when there is more than one match and
2110 sufficient colors are available. |ins-completion-menu|
2111
Bram Moolenaar65c923a2006-03-03 22:56:30 +00002112 menuone Use the popup menu also when there is only one match.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00002113 Useful when there is additional information about the
Bram Moolenaar65c923a2006-03-03 22:56:30 +00002114 match, e.g., what file it comes from.
2115
Bram Moolenaarc1e37902006-04-18 21:55:01 +00002116 longest Only insert the longest common text of the matches. If
2117 the menu is displayed you can use CTRL-L to add more
2118 characters. Whether case is ignored depends on the kind
2119 of completion. For buffer text the 'ignorecase' option is
2120 used.
Bram Moolenaarc7453f52006-02-10 23:20:28 +00002121
Bram Moolenaar96d2c5b2006-03-11 21:27:59 +00002122 preview Show extra information about the currently selected
Bram Moolenaar02467872007-05-06 13:22:01 +00002123 completion in the preview window. Only works in
2124 combination with "menu" or "menuone".
2125
Bram Moolenaar576a4a62019-08-18 15:25:17 +02002126 popup Show extra information about the currently selected
2127 completion in a popup window. Only works in combination
2128 with "menu" or "menuone". Overrides "preview".
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02002129 See |'completepopup'| for specifying properties.
Bram Moolenaar2e693a82019-10-16 22:35:02 +02002130 {only works when compiled with the |+textprop| feature}
Bram Moolenaar576a4a62019-08-18 15:25:17 +02002131
Bram Moolenaardca7abe2019-10-20 18:17:57 +02002132 popuphidden
Bram Moolenaar0c0734d2019-11-26 21:44:46 +01002133 Just like "popup" but initially hide the popup. Use a
Bram Moolenaardca7abe2019-10-20 18:17:57 +02002134 |CompleteChanged| autocommand to fetch the info and call
2135 |popup_show()| once the popup has been filled.
2136 See the example at |complete-popuphidden|.
2137 {only works when compiled with the |+textprop| feature}
2138
Bram Moolenaarb6be1e22015-07-10 18:18:40 +02002139 noinsert Do not insert any text for a match until the user selects
2140 a match from the menu. Only works in combination with
2141 "menu" or "menuone". No effect if "longest" is present.
2142
2143 noselect Do not select a match in the menu, force the user to
2144 select one from the menu. Only works in combination with
2145 "menu" or "menuone".
2146
Bram Moolenaar96d2c5b2006-03-11 21:27:59 +00002147
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02002148 *'completepopup'* *'cpp'*
2149'completepopup' 'cpp' string (default empty)
2150 global
2151 {not available when compiled without the |+textprop|
2152 or |+quickfix| feature}
2153 When 'completeopt' contains "popup" then this option is used for the
Bram Moolenaar447bfba2020-07-18 16:07:16 +02002154 properties of the info popup when it is created. If an info popup
2155 window already exists it is closed, so that the option value is
2156 applied when it is created again.
2157 You can also use |popup_findinfo()| and then set properties for an
2158 existing info popup with |popup_setoptions()|. See |complete-popup|.
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02002159
2160
Bram Moolenaarf5963f72010-07-23 22:10:27 +02002161 *'concealcursor'* *'cocu'*
2162'concealcursor' 'cocu' string (default: "")
2163 local to window
Bram Moolenaarf5963f72010-07-23 22:10:27 +02002164 {not available when compiled without the |+conceal|
2165 feature}
2166 Sets the modes in which text in the cursor line can also be concealed.
2167 When the current mode is listed then concealing happens just like in
2168 other lines.
2169 n Normal mode
2170 v Visual mode
2171 i Insert mode
Bram Moolenaarca8c9862010-07-24 15:00:38 +02002172 c Command line editing, for 'incsearch'
Bram Moolenaarf5963f72010-07-23 22:10:27 +02002173
Bram Moolenaare6dc5732010-07-24 23:52:26 +02002174 'v' applies to all lines in the Visual area, not only the cursor.
Bram Moolenaarca8c9862010-07-24 15:00:38 +02002175 A useful value is "nc". This is used in help files. So long as you
Bram Moolenaarf5963f72010-07-23 22:10:27 +02002176 are moving around text is concealed, but when starting to insert text
2177 or selecting a Visual area the concealed text is displayed, so that
2178 you can see what you are doing.
Bram Moolenaarf70e3d62010-07-24 13:15:07 +02002179 Keep in mind that the cursor position is not always where it's
2180 displayed. E.g., when moving vertically it may change column.
Bram Moolenaarf5963f72010-07-23 22:10:27 +02002181
2182
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002183 *'conceallevel'* *'cole'*
2184'conceallevel' 'cole' number (default 0)
Bram Moolenaar860cae12010-06-05 23:22:07 +02002185 local to window
Bram Moolenaar860cae12010-06-05 23:22:07 +02002186 {not available when compiled without the |+conceal|
2187 feature}
Bram Moolenaar6df6f472010-07-18 18:04:50 +02002188 Determine how text with the "conceal" syntax attribute |:syn-conceal|
2189 is shown:
Bram Moolenaar860cae12010-06-05 23:22:07 +02002190
Bram Moolenaar6df6f472010-07-18 18:04:50 +02002191 Value Effect ~
Bram Moolenaar860cae12010-06-05 23:22:07 +02002192 0 Text is shown normally
Bram Moolenaar477db062010-07-28 18:17:41 +02002193 1 Each block of concealed text is replaced with one
2194 character. If the syntax item does not have a custom
2195 replacement character defined (see |:syn-cchar|) the
2196 character defined in 'listchars' is used (default is a
2197 space).
2198 It is highlighted with the "Conceal" highlight group.
Bram Moolenaar860cae12010-06-05 23:22:07 +02002199 2 Concealed text is completely hidden unless it has a
2200 custom replacement character defined (see
Bram Moolenaar477db062010-07-28 18:17:41 +02002201 |:syn-cchar|).
Bram Moolenaara7781e02010-07-19 20:13:22 +02002202 3 Concealed text is completely hidden.
Bram Moolenaar860cae12010-06-05 23:22:07 +02002203
Bram Moolenaara7781e02010-07-19 20:13:22 +02002204 Note: in the cursor line concealed text is not hidden, so that you can
Bram Moolenaarf5963f72010-07-23 22:10:27 +02002205 edit and copy the text. This can be changed with the 'concealcursor'
2206 option.
Bram Moolenaar860cae12010-06-05 23:22:07 +02002207
Bram Moolenaar071d4272004-06-13 20:20:40 +00002208 *'confirm'* *'cf'* *'noconfirm'* *'nocf'*
2209'confirm' 'cf' boolean (default off)
2210 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00002211 When 'confirm' is on, certain operations that would normally
2212 fail because of unsaved changes to a buffer, e.g. ":q" and ":e",
2213 instead raise a |dialog| asking if you wish to save the current
2214 file(s). You can still use a ! to unconditionally |abandon| a buffer.
2215 If 'confirm' is off you can still activate confirmation for one
2216 command only (this is most useful in mappings) with the |:confirm|
2217 command.
2218 Also see the |confirm()| function and the 'v' flag in 'guioptions'.
2219
2220 *'conskey'* *'consk'* *'noconskey'* *'noconsk'*
2221'conskey' 'consk' boolean (default off)
2222 global
Bram Moolenaarf3913272016-02-25 00:00:01 +01002223 This was for MS-DOS and is no longer supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002224
2225 *'copyindent'* *'ci'* *'nocopyindent'* *'noci'*
2226'copyindent' 'ci' boolean (default off)
2227 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00002228 Copy the structure of the existing lines indent when autoindenting a
2229 new line. Normally the new indent is reconstructed by a series of
2230 tabs followed by spaces as required (unless |'expandtab'| is enabled,
2231 in which case only spaces are used). Enabling this option makes the
2232 new line copy whatever characters were used for indenting on the
Bram Moolenaar446cb832008-06-24 21:56:24 +00002233 existing line. 'expandtab' has no effect on these characters, a Tab
2234 remains a Tab. If the new indent is greater than on the existing
Bram Moolenaar071d4272004-06-13 20:20:40 +00002235 line, the remaining space is filled in the normal manner.
Bram Moolenaar036986f2017-03-16 17:41:02 +01002236 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002237 Also see 'preserveindent'.
2238
Bram Moolenaare0fa3742016-02-20 15:47:01 +01002239 *'cpoptions'* *'cpo'* *cpo*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002240'cpoptions' 'cpo' string (Vim default: "aABceFs",
2241 Vi default: all flags)
2242 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00002243 A sequence of single character flags. When a character is present
Bram Moolenaar7cba6c02013-09-05 22:13:31 +02002244 this indicates Vi-compatible behavior. This is used for things where
2245 not being Vi-compatible is mostly or sometimes preferred.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002246 'cpoptions' stands for "compatible-options".
2247 Commas can be added for readability.
2248 To avoid problems with flags that are added in the future, use the
2249 "+=" and "-=" feature of ":set" |add-option-flags|.
Bram Moolenaar71eb3ad2021-12-26 12:07:30 +00002250
Bram Moolenaar071d4272004-06-13 20:20:40 +00002251 NOTE: This option is set to the Vi default value when 'compatible' is
2252 set and to the Vim default value when 'compatible' is reset.
Bram Moolenaar71eb3ad2021-12-26 12:07:30 +00002253
2254 NOTE: In a |Vim9| script, when `vim9script` is encountered, the value
2255 is saved, 'cpoptions' is set to the Vim default, and the saved value
2256 is restored at the end of the script. Changes to the value of
2257 'cpoptions' will be applied to the saved value, but keep in mind that
2258 removing a flag that is not present when 'cpoptions' is changed has no
2259 effect. In the |.vimrc| file the value is not restored, thus using
2260 `vim9script` in the |.vimrc| file results in using the Vim default.
2261
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002262 NOTE: This option is set to the POSIX default value at startup when
2263 the Vi default value would be used and the $VIM_POSIX environment
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002264 variable exists |posix|. This means Vim tries to behave like the
2265 POSIX specification.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002266
2267 contains behavior ~
2268 *cpo-a*
2269 a When included, a ":read" command with a file name
2270 argument will set the alternate file name for the
2271 current window.
2272 *cpo-A*
2273 A When included, a ":write" command with a file name
2274 argument will set the alternate file name for the
2275 current window.
2276 *cpo-b*
2277 b "\|" in a ":map" command is recognized as the end of
2278 the map command. The '\' is included in the mapping,
2279 the text after the '|' is interpreted as the next
2280 command. Use a CTRL-V instead of a backslash to
2281 include the '|' in the mapping. Applies to all
2282 mapping, abbreviation, menu and autocmd commands.
2283 See also |map_bar|.
2284 *cpo-B*
2285 B A backslash has no special meaning in mappings,
Bram Moolenaara9604e62018-07-21 05:56:22 +02002286 abbreviations, user commands and the "to" part of the
2287 menu commands. Remove this flag to be able to use a
2288 backslash like a CTRL-V. For example, the command
2289 ":map X \<Esc>" results in X being mapped to:
Bram Moolenaar071d4272004-06-13 20:20:40 +00002290 'B' included: "\^[" (^[ is a real <Esc>)
2291 'B' excluded: "<Esc>" (5 characters)
2292 ('<' excluded in both cases)
2293 *cpo-c*
2294 c Searching continues at the end of any match at the
2295 cursor position, but not further than the start of the
2296 next line. When not present searching continues
2297 one character from the cursor position. With 'c'
2298 "abababababab" only gets three matches when repeating
2299 "/abab", without 'c' there are five matches.
2300 *cpo-C*
2301 C Do not concatenate sourced lines that start with a
2302 backslash. See |line-continuation|.
2303 *cpo-d*
2304 d Using "./" in the 'tags' option doesn't mean to use
2305 the tags file relative to the current file, but the
2306 tags file in the current directory.
2307 *cpo-D*
2308 D Can't use CTRL-K to enter a digraph after Normal mode
2309 commands with a character argument, like |r|, |f| and
2310 |t|.
2311 *cpo-e*
2312 e When executing a register with ":@r", always add a
2313 <CR> to the last line, also when the register is not
2314 linewise. If this flag is not present, the register
2315 is not linewise and the last line does not end in a
2316 <CR>, then the last line is put on the command-line
2317 and can be edited before hitting <CR>.
2318 *cpo-E*
2319 E It is an error when using "y", "d", "c", "g~", "gu" or
2320 "gU" on an Empty region. The operators only work when
Bram Moolenaar15142e22018-04-30 22:19:58 +02002321 at least one character is to be operated on. Example:
Bram Moolenaar071d4272004-06-13 20:20:40 +00002322 This makes "y0" fail in the first column.
2323 *cpo-f*
2324 f When included, a ":read" command with a file name
2325 argument will set the file name for the current buffer,
2326 if the current buffer doesn't have a file name yet.
2327 *cpo-F*
2328 F When included, a ":write" command with a file name
2329 argument will set the file name for the current
2330 buffer, if the current buffer doesn't have a file name
Bram Moolenaarb3480382005-12-11 21:33:32 +00002331 yet. Also see |cpo-P|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002332 *cpo-g*
2333 g Goto line 1 when using ":edit" without argument.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002334 *cpo-H*
2335 H When using "I" on a line with only blanks, insert
2336 before the last blank. Without this flag insert after
2337 the last blank.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002338 *cpo-i*
2339 i When included, interrupting the reading of a file will
2340 leave it modified.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002341 *cpo-I*
2342 I When moving the cursor up or down just after inserting
2343 indent for 'autoindent', do not delete the indent.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002344 *cpo-j*
2345 j When joining lines, only add two spaces after a '.',
2346 not after '!' or '?'. Also see 'joinspaces'.
2347 *cpo-J*
2348 J A |sentence| has to be followed by two spaces after
Bram Moolenaar582fd852005-03-28 20:58:01 +00002349 the '.', '!' or '?'. A <Tab> is not recognized as
Bram Moolenaar071d4272004-06-13 20:20:40 +00002350 white space.
2351 *cpo-k*
2352 k Disable the recognition of raw key codes in
2353 mappings, abbreviations, and the "to" part of menu
2354 commands. For example, if <Key> sends ^[OA (where ^[
2355 is <Esc>), the command ":map X ^[OA" results in X
2356 being mapped to:
2357 'k' included: "^[OA" (3 characters)
2358 'k' excluded: "<Key>" (one key code)
2359 Also see the '<' flag below.
2360 *cpo-K*
2361 K Don't wait for a key code to complete when it is
2362 halfway a mapping. This breaks mapping <F1><F1> when
2363 only part of the second <F1> has been read. It
2364 enables cancelling the mapping by typing <F1><Esc>.
2365 *cpo-l*
2366 l Backslash in a [] range in a search pattern is taken
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002367 literally, only "\]", "\^", "\-" and "\\" are special.
2368 See |/[]|
Bram Moolenaar071d4272004-06-13 20:20:40 +00002369 'l' included: "/[ \t]" finds <Space>, '\' and 't'
2370 'l' excluded: "/[ \t]" finds <Space> and <Tab>
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002371 Also see |cpo-\|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002372 *cpo-L*
2373 L When the 'list' option is set, 'wrapmargin',
2374 'textwidth', 'softtabstop' and Virtual Replace mode
2375 (see |gR|) count a <Tab> as two characters, instead of
2376 the normal behavior of a <Tab>.
2377 *cpo-m*
2378 m When included, a showmatch will always wait half a
2379 second. When not included, a showmatch will wait half
2380 a second or until a character is typed. |'showmatch'|
2381 *cpo-M*
2382 M When excluded, "%" matching will take backslashes into
2383 account. Thus in "( \( )" and "\( ( \)" the outer
2384 parenthesis match. When included "%" ignores
2385 backslashes, which is Vi compatible.
2386 *cpo-n*
Bram Moolenaar64486672010-05-16 15:46:46 +02002387 n When included, the column used for 'number' and
2388 'relativenumber' will also be used for text of wrapped
2389 lines.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002390 *cpo-o*
2391 o Line offset to search command is not remembered for
2392 next search.
2393 *cpo-O*
2394 O Don't complain if a file is being overwritten, even
2395 when it didn't exist when editing it. This is a
2396 protection against a file unexpectedly created by
2397 someone else. Vi didn't complain about this.
2398 *cpo-p*
2399 p Vi compatible Lisp indenting. When not present, a
2400 slightly better algorithm is used.
Bram Moolenaarb3480382005-12-11 21:33:32 +00002401 *cpo-P*
2402 P When included, a ":write" command that appends to a
2403 file will set the file name for the current buffer, if
2404 the current buffer doesn't have a file name yet and
2405 the 'F' flag is also included |cpo-F|.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002406 *cpo-q*
2407 q When joining multiple lines leave the cursor at the
2408 position where it would be when joining two lines.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002409 *cpo-r*
2410 r Redo ("." command) uses "/" to repeat a search
2411 command, instead of the actually used search string.
2412 *cpo-R*
2413 R Remove marks from filtered lines. Without this flag
2414 marks are kept like |:keepmarks| was used.
2415 *cpo-s*
2416 s Set buffer options when entering the buffer for the
2417 first time. This is like it is in Vim version 3.0.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002418 And it is the default. If not present the options are
Bram Moolenaar071d4272004-06-13 20:20:40 +00002419 set when the buffer is created.
2420 *cpo-S*
2421 S Set buffer options always when entering a buffer
2422 (except 'readonly', 'fileformat', 'filetype' and
2423 'syntax'). This is the (most) Vi compatible setting.
2424 The options are set to the values in the current
2425 buffer. When you change an option and go to another
2426 buffer, the value is copied. Effectively makes the
2427 buffer options global to all buffers.
2428
2429 's' 'S' copy buffer options
2430 no no when buffer created
2431 yes no when buffer first entered (default)
2432 X yes each time when buffer entered (vi comp.)
2433 *cpo-t*
2434 t Search pattern for the tag command is remembered for
2435 "n" command. Otherwise Vim only puts the pattern in
2436 the history for search pattern, but doesn't change the
2437 last used search pattern.
2438 *cpo-u*
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002439 u Undo is Vi compatible. See |undo-two-ways|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002440 *cpo-v*
2441 v Backspaced characters remain visible on the screen in
2442 Insert mode. Without this flag the characters are
2443 erased from the screen right away. With this flag the
2444 screen newly typed text overwrites backspaced
2445 characters.
2446 *cpo-w*
2447 w When using "cw" on a blank character, only change one
2448 character and not all blanks until the start of the
2449 next word.
2450 *cpo-W*
2451 W Don't overwrite a readonly file. When omitted, ":w!"
2452 overwrites a readonly file, if possible.
2453 *cpo-x*
2454 x <Esc> on the command-line executes the command-line.
2455 The default in Vim is to abandon the command-line,
2456 because <Esc> normally aborts a command. |c_<Esc>|
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002457 *cpo-X*
2458 X When using a count with "R" the replaced text is
2459 deleted only once. Also when repeating "R" with "."
2460 and a count.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002461 *cpo-y*
Bram Moolenaard09091d2019-01-17 16:07:22 +01002462 y A yank command can be redone with ".". Think twice if
2463 you really want to use this, it may break some
2464 plugins, since most people expect "." to only repeat a
2465 change.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002466 *cpo-Z*
2467 Z When using "w!" while the 'readonly' option is set,
2468 don't reset 'readonly'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002469 *cpo-!*
2470 ! When redoing a filter command, use the last used
2471 external command, whatever it was. Otherwise the last
2472 used -filter- command is used.
2473 *cpo-$*
2474 $ When making a change to one line, don't redisplay the
2475 line, but put a '$' at the end of the changed text.
2476 The changed text will be overwritten when you type the
2477 new text. The line is redisplayed if you type any
2478 command that moves the cursor from the insertion
2479 point.
2480 *cpo-%*
2481 % Vi-compatible matching is done for the "%" command.
2482 Does not recognize "#if", "#endif", etc.
2483 Does not recognize "/*" and "*/".
2484 Parens inside single and double quotes are also
2485 counted, causing a string that contains a paren to
2486 disturb the matching. For example, in a line like
2487 "if (strcmp("foo(", s))" the first paren does not
2488 match the last one. When this flag is not included,
2489 parens inside single and double quotes are treated
2490 specially. When matching a paren outside of quotes,
2491 everything inside quotes is ignored. When matching a
2492 paren inside quotes, it will find the matching one (if
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002493 there is one). This works very well for C programs.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00002494 This flag is also used for other features, such as
2495 C-indenting.
Bram Moolenaar7c626922005-02-07 22:01:03 +00002496 *cpo--*
2497 - When included, a vertical movement command fails when
Bram Moolenaar8ada17c2006-01-19 22:16:24 +00002498 it would go above the first line or below the last
2499 line. Without it the cursor moves to the first or
2500 last line, unless it already was in that line.
Bram Moolenaar7c626922005-02-07 22:01:03 +00002501 Applies to the commands "-", "k", CTRL-P, "+", "j",
Bram Moolenaar8ada17c2006-01-19 22:16:24 +00002502 CTRL-N, CTRL-J and ":1234".
Bram Moolenaar1cd871b2004-12-19 22:46:22 +00002503 *cpo-+*
2504 + When included, a ":write file" command will reset the
2505 'modified' flag of the buffer, even though the buffer
2506 itself may still be different from its file.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00002507 *cpo-star*
Bram Moolenaar071d4272004-06-13 20:20:40 +00002508 * Use ":*" in the same way as ":@". When not included,
2509 ":*" is an alias for ":'<,'>", select the Visual area.
2510 *cpo-<*
2511 < Disable the recognition of special key codes in |<>|
2512 form in mappings, abbreviations, and the "to" part of
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002513 menu commands. For example, the command
Bram Moolenaar071d4272004-06-13 20:20:40 +00002514 ":map X <Tab>" results in X being mapped to:
2515 '<' included: "<Tab>" (5 characters)
2516 '<' excluded: "^I" (^I is a real <Tab>)
2517 Also see the 'k' flag above.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002518 *cpo->*
2519 > When appending to a register, put a line break before
2520 the appended text.
Bram Moolenaar8b3e0332011-06-26 05:36:34 +02002521 *cpo-;*
2522 ; When using |,| or |;| to repeat the last |t| search
2523 and the cursor is right in front of the searched
2524 character, the cursor won't move. When not included,
2525 the cursor would skip over it and jump to the
Bram Moolenaarc8734422012-06-01 22:38:45 +02002526 following occurrence.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002527
2528 POSIX flags. These are not included in the Vi default value, except
2529 when $VIM_POSIX was set on startup. |posix|
2530
2531 contains behavior ~
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00002532 *cpo-#*
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002533 # A count before "D", "o" and "O" has no effect.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002534 *cpo-&*
2535 & When ":preserve" was used keep the swap file when
2536 exiting normally while this buffer is still loaded.
2537 This flag is tested when exiting.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002538 *cpo-\*
2539 \ Backslash in a [] range in a search pattern is taken
2540 literally, only "\]" is special See |/[]|
Bram Moolenaar90915b52005-08-21 22:17:52 +00002541 '\' included: "/[ \-]" finds <Space>, '\' and '-'
2542 '\' excluded: "/[ \-]" finds <Space> and '-'
2543 Also see |cpo-l|.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002544 *cpo-/*
2545 / When "%" is used as the replacement string in a |:s|
2546 command, use the previous replacement string. |:s%|
2547 *cpo-{*
2548 { The |{| and |}| commands also stop at a "{" character
2549 at the start of a line.
2550 *cpo-.*
2551 . The ":chdir" and ":cd" commands fail if the current
2552 buffer is modified, unless ! is used. Vim doesn't
2553 need this, since it remembers the full path of an
2554 opened file.
2555 *cpo-bar*
2556 | The value of the $LINES and $COLUMNS environment
2557 variables overrule the terminal size values obtained
2558 with system specific functions.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002559
Bram Moolenaar071d4272004-06-13 20:20:40 +00002560
Bram Moolenaar40e6a712010-05-16 22:32:54 +02002561 *'cryptmethod'* *'cm'*
Bram Moolenaara86187b2018-12-16 18:20:00 +01002562'cryptmethod' 'cm' string (default "blowfish2")
Bram Moolenaar49771f42010-07-20 17:32:38 +02002563 global or local to buffer |global-local|
Bram Moolenaar40e6a712010-05-16 22:32:54 +02002564 Method used for encryption when the buffer is written to a file:
Bram Moolenaar0bbabe82010-05-17 20:32:55 +02002565 *pkzip*
Bram Moolenaar49771f42010-07-20 17:32:38 +02002566 zip PkZip compatible method. A weak kind of encryption.
Bram Moolenaarf50a2532010-05-21 15:36:08 +02002567 Backwards compatible with Vim 7.2 and older.
Christian Brabandtaae58342023-04-23 17:50:22 +01002568 Only use if you need to be backwards compatible.
Bram Moolenaar0bbabe82010-05-17 20:32:55 +02002569 *blowfish*
Bram Moolenaar8f4ac012014-08-10 13:38:34 +02002570 blowfish Blowfish method. Medium strong encryption but it has
2571 an implementation flaw. Requires Vim 7.3 or later,
2572 files can NOT be read by Vim 7.2 and older. This adds
2573 a "seed" to the file, every time you write the file
2574 the encrypted bytes will be different.
Christian Brabandtaae58342023-04-23 17:50:22 +01002575 Obsolete, please do no longer use.
Bram Moolenaar8f4ac012014-08-10 13:38:34 +02002576 *blowfish2*
2577 blowfish2 Blowfish method. Medium strong encryption. Requires
Bram Moolenaar5e9b2fa2016-02-01 22:37:05 +01002578 Vim 7.4.401 or later, files can NOT be read by Vim 7.3
Bram Moolenaar8f4ac012014-08-10 13:38:34 +02002579 and older. This adds a "seed" to the file, every time
2580 you write the file the encrypted bytes will be
2581 different. The whole undo file is encrypted, not just
2582 the pieces of text.
Bram Moolenaara2baa732022-02-04 16:09:54 +00002583 *E1193* *E1194* *E1195* *E1196* *E1230*
Christian Brabandtf573c6e2021-06-20 14:02:16 +02002584 *E1197* *E1198* *E1199* *E1200* *E1201*
2585 xchacha20 XChaCha20 Cipher with Poly1305 Message Authentication
2586 Code. Medium strong till strong encryption.
2587 Encryption is provided by the libsodium library, it
Bram Moolenaar22863042021-10-16 15:23:36 +01002588 requires Vim to be built with |+sodium|.
Christian Brabandtf573c6e2021-06-20 14:02:16 +02002589 It adds a seed and a message authentication code (MAC)
2590 to the file. This needs at least a Vim 8.2.3022 to
2591 read the encrypted file.
2592 Encryption of swap files is not supported, therefore
2593 no swap file will be used when xchacha20 encryption is
2594 enabled.
2595 Encryption of undo files is not yet supported,
2596 therefore no undo file will currently be written.
Christian Brabandtaae58342023-04-23 17:50:22 +01002597 CAREFUL: Files written with this method might have to
2598 be read back with the same version of Vim if the
2599 binary format changes later.
2600 Obsolete, please do no longer use.
2601 xchacha20v2 Same algorithm as with "xchacha20" that correctly
2602 stores the key derivation parameters together with the
2603 encrypted file. Should work better in case the
2604 parameters in the libsodium library ever change.
2605 STILL EXPERIMENTAL: Files written with this method
Christian Brabandtf573c6e2021-06-20 14:02:16 +02002606 might have to be read back with the same version of
2607 Vim if the binary format changes later.
Bram Moolenaarf50a2532010-05-21 15:36:08 +02002608
Christian Brabandtaae58342023-04-23 17:50:22 +01002609 You should use "blowfish2", also to re-encrypt older files. The
2610 "xchacha20" method provides better encryption, but it does not work
2611 with all versions of Vim.
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01002612
Bram Moolenaar40e6a712010-05-16 22:32:54 +02002613 When reading an encrypted file 'cryptmethod' will be set automatically
Bram Moolenaarf50a2532010-05-21 15:36:08 +02002614 to the detected method of the file being read. Thus if you write it
2615 without changing 'cryptmethod' the same method will be used.
2616 Changing 'cryptmethod' does not mark the file as modified, you have to
Bram Moolenaar49771f42010-07-20 17:32:38 +02002617 explicitly write it, you don't get a warning unless there are other
2618 modifications. Also see |:X|.
2619
2620 When setting the global value to an empty string, it will end up with
Bram Moolenaara86187b2018-12-16 18:20:00 +01002621 the value "blowfish2". When setting the local value to an empty
2622 string the buffer will use the global value.
Bram Moolenaar49771f42010-07-20 17:32:38 +02002623
Bram Moolenaarf50a2532010-05-21 15:36:08 +02002624 When a new encryption method is added in a later version of Vim, and
2625 the current version does not recognize it, you will get *E821* .
Bram Moolenaar49771f42010-07-20 17:32:38 +02002626 You need to edit this file with the later version of Vim.
Bram Moolenaar40e6a712010-05-16 22:32:54 +02002627
2628
Bram Moolenaar071d4272004-06-13 20:20:40 +00002629 *'cscopepathcomp'* *'cspc'*
2630'cscopepathcomp' 'cspc' number (default 0)
2631 global
2632 {not available when compiled without the |+cscope|
2633 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002634 Determines how many components of the path to show in a list of tags.
2635 See |cscopepathcomp|.
Bram Moolenaar036986f2017-03-16 17:41:02 +01002636 NOTE: This option is set to 0 when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002637
2638 *'cscopeprg'* *'csprg'*
2639'cscopeprg' 'csprg' string (default "cscope")
2640 global
2641 {not available when compiled without the |+cscope|
2642 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002643 Specifies the command to execute cscope. See |cscopeprg|.
2644 This option cannot be set from a |modeline| or in the |sandbox|, for
2645 security reasons.
2646
2647 *'cscopequickfix'* *'csqf'*
2648'cscopequickfix' 'csqf' string (default "")
2649 global
2650 {not available when compiled without the |+cscope|
2651 or |+quickfix| features}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002652 Specifies whether to use quickfix window to show cscope results.
2653 See |cscopequickfix|.
2654
Bram Moolenaarec7944a2013-06-12 21:29:15 +02002655 *'cscoperelative'* *'csre'* *'nocscoperelative'* *'nocsre'*
Bram Moolenaar2f982e42011-06-12 20:42:22 +02002656'cscoperelative' 'csre' boolean (default off)
2657 global
2658 {not available when compiled without the |+cscope|
2659 feature}
Bram Moolenaar2f982e42011-06-12 20:42:22 +02002660 In the absence of a prefix (-P) for cscope. setting this option enables
2661 to use the basename of cscope.out path as the prefix.
2662 See |cscoperelative|.
Bram Moolenaar036986f2017-03-16 17:41:02 +01002663 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaar2f982e42011-06-12 20:42:22 +02002664
Bram Moolenaar071d4272004-06-13 20:20:40 +00002665 *'cscopetag'* *'cst'* *'nocscopetag'* *'nocst'*
2666'cscopetag' 'cst' boolean (default off)
2667 global
2668 {not available when compiled without the |+cscope|
2669 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002670 Use cscope for tag commands. See |cscope-options|.
2671 NOTE: This option is reset when 'compatible' is set.
2672
2673 *'cscopetagorder'* *'csto'*
2674'cscopetagorder' 'csto' number (default 0)
2675 global
2676 {not available when compiled without the |+cscope|
2677 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002678 Determines the order in which ":cstag" performs a search. See
2679 |cscopetagorder|.
2680 NOTE: This option is set to 0 when 'compatible' is set.
2681
2682 *'cscopeverbose'* *'csverb'*
2683 *'nocscopeverbose'* *'nocsverb'*
2684'cscopeverbose' 'csverb' boolean (default off)
2685 global
2686 {not available when compiled without the |+cscope|
2687 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00002688 Give messages when adding a cscope database. See |cscopeverbose|.
2689 NOTE: This option is reset when 'compatible' is set.
2690
Bram Moolenaar860cae12010-06-05 23:22:07 +02002691 *'cursorbind'* *'crb'* *'nocursorbind'* *'nocrb'*
2692'cursorbind' 'crb' boolean (default off)
2693 local to window
Bram Moolenaar860cae12010-06-05 23:22:07 +02002694 When this option is set, as the cursor in the current
2695 window moves other cursorbound windows (windows that also have
2696 this option set) move their cursors to the corresponding line and
2697 column. This option is useful for viewing the
2698 differences between two versions of a file (see 'diff'); in diff mode,
2699 inserted and deleted lines (though not characters within a line) are
Bram Moolenaar1a384422010-07-14 19:53:30 +02002700 taken into account.
Bram Moolenaar860cae12010-06-05 23:22:07 +02002701
Bram Moolenaar600dddc2006-03-12 22:05:10 +00002702
2703 *'cursorcolumn'* *'cuc'* *'nocursorcolumn'* *'nocuc'*
2704'cursorcolumn' 'cuc' boolean (default off)
2705 local to window
Bram Moolenaardb84e452010-08-15 13:50:43 +02002706 {not available when compiled without the |+syntax|
Bram Moolenaar600dddc2006-03-12 22:05:10 +00002707 feature}
2708 Highlight the screen column of the cursor with CursorColumn
2709 |hl-CursorColumn|. Useful to align text. Will make screen redrawing
2710 slower.
Bram Moolenaar4c3f5362006-04-11 21:38:50 +00002711 If you only want the highlighting in the current window you can use
2712 these autocommands: >
2713 au WinLeave * set nocursorline nocursorcolumn
2714 au WinEnter * set cursorline cursorcolumn
2715<
Bram Moolenaar600dddc2006-03-12 22:05:10 +00002716
2717 *'cursorline'* *'cul'* *'nocursorline'* *'nocul'*
2718'cursorline' 'cul' boolean (default off)
2719 local to window
Bram Moolenaardb84e452010-08-15 13:50:43 +02002720 {not available when compiled without the |+syntax|
Bram Moolenaar600dddc2006-03-12 22:05:10 +00002721 feature}
Bram Moolenaar410e98a2019-09-09 22:05:49 +02002722 Highlight the text line of the cursor with CursorLine |hl-CursorLine|.
2723 Useful to easily spot the cursor. Will make screen redrawing slower.
Bram Moolenaare2f98b92006-03-29 21:18:24 +00002724 When Visual mode is active the highlighting isn't used to make it
Bram Moolenaar779b74b2006-04-10 14:55:34 +00002725 easier to see the selected text.
Bram Moolenaar600dddc2006-03-12 22:05:10 +00002726
2727
Bram Moolenaar410e98a2019-09-09 22:05:49 +02002728 *'cursorlineopt'* *'culopt'*
Bram Moolenaar017ba072019-09-14 21:01:23 +02002729'cursorlineopt' 'culopt' string (default: "number,line")
Bram Moolenaar410e98a2019-09-09 22:05:49 +02002730 local to window
Bram Moolenaar410e98a2019-09-09 22:05:49 +02002731 {not available when compiled without the |+syntax|
2732 feature}
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01002733 Comma-separated list of settings for how 'cursorline' is displayed.
Bram Moolenaar017ba072019-09-14 21:01:23 +02002734 Valid values:
2735 "line" Highlight the text line of the cursor with
Bram Moolenaar410e98a2019-09-09 22:05:49 +02002736 CursorLine |hl-CursorLine|.
Bram Moolenaar017ba072019-09-14 21:01:23 +02002737 "screenline" Highlight only the screen line of the cursor with
2738 CursorLine |hl-CursorLine|.
2739 "number" Highlight the line number of the cursor with
Bram Moolenaar410e98a2019-09-09 22:05:49 +02002740 CursorLineNr |hl-CursorLineNr|.
Bram Moolenaar017ba072019-09-14 21:01:23 +02002741
2742 Special value:
2743 "both" Alias for the values "line,number".
2744
2745 "line" and "screenline" cannot be used together.
Bram Moolenaar410e98a2019-09-09 22:05:49 +02002746
2747
Bram Moolenaar071d4272004-06-13 20:20:40 +00002748 *'debug'*
2749'debug' string (default "")
2750 global
Bram Moolenaar57657d82006-04-21 22:12:41 +00002751 These values can be used:
2752 msg Error messages that would otherwise be omitted will be given
2753 anyway.
2754 throw Error messages that would otherwise be omitted will be given
2755 anyway and also throw an exception and set |v:errmsg|.
2756 beep A message will be given when otherwise only a beep would be
2757 produced.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00002758 The values can be combined, separated by a comma.
Bram Moolenaar57657d82006-04-21 22:12:41 +00002759 "msg" and "throw" are useful for debugging 'foldexpr', 'formatexpr' or
2760 'indentexpr'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002761
2762 *'define'* *'def'*
2763'define' 'def' string (default "^\s*#\s*define")
2764 global or local to buffer |global-local|
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002765 Pattern to be used to find a macro definition. It is a search
Bram Moolenaar071d4272004-06-13 20:20:40 +00002766 pattern, just like for the "/" command. This option is used for the
2767 commands like "[i" and "[d" |include-search|. The 'isident' option is
2768 used to recognize the defined name after the match:
2769 {match with 'define'}{non-ID chars}{defined name}{non-ID char}
2770 See |option-backslash| about inserting backslashes to include a space
2771 or backslash.
2772 The default value is for C programs. For C++ this value would be
2773 useful, to include const type declarations: >
2774 ^\(#\s*define\|[a-z]*\s*const\s*[a-z]*\)
Bram Moolenaar63b74a82019-03-24 15:09:13 +01002775< You can also use "\ze" just before the name and continue the pattern
2776 to check what is following. E.g. for Javascript, if a function is
2777 defined with "func_name = function(args)": >
2778 ^\s*\ze\i\+\s*=\s*function(
2779< If the function is defined with "func_name : function() {...": >
2780 ^\s*\ze\i\+\s*[:]\s*(*function\s*(
Bram Moolenaar071d4272004-06-13 20:20:40 +00002781< When using the ":set" command, you need to double the backslashes!
Bram Moolenaar63b74a82019-03-24 15:09:13 +01002782 To avoid that use `:let` with a single quote string: >
2783 let &l:define = '^\s*\ze\k\+\s*=\s*function('
Bram Moolenaar911ead12019-04-21 00:03:35 +02002784<
Bram Moolenaar071d4272004-06-13 20:20:40 +00002785
2786 *'delcombine'* *'deco'* *'nodelcombine'* *'nodeco'*
2787'delcombine' 'deco' boolean (default off)
2788 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00002789 If editing Unicode and this option is set, backspace and Normal mode
2790 "x" delete each combining character on its own. When it is off (the
2791 default) the character along with its combining characters are
2792 deleted.
Bram Moolenaar4f4d51a2020-10-11 13:57:40 +02002793 Note: When 'delcombine' is set "xx" may work differently from "2x"!
Bram Moolenaar071d4272004-06-13 20:20:40 +00002794
2795 This is useful for Arabic, Hebrew and many other languages where one
2796 may have combining characters overtop of base characters, and want
2797 to remove only the combining ones.
Bram Moolenaar036986f2017-03-16 17:41:02 +01002798 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002799
2800 *'dictionary'* *'dict'*
2801'dictionary' 'dict' string (default "")
2802 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00002803 List of file names, separated by commas, that are used to lookup words
2804 for keyword completion commands |i_CTRL-X_CTRL-K|. Each file should
2805 contain a list of words. This can be one word per line, or several
2806 words per line, separated by non-keyword characters (white space is
2807 preferred). Maximum line length is 510 bytes.
Bram Moolenaar259f26a2018-05-15 22:25:40 +02002808
2809 When this option is empty or an entry "spell" is present, and spell
2810 checking is enabled, words in the word lists for the currently active
2811 'spelllang' are used. See |spell|.
2812
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002813 To include a comma in a file name precede it with a backslash. Spaces
Bram Moolenaar071d4272004-06-13 20:20:40 +00002814 after a comma are ignored, otherwise spaces are included in the file
2815 name. See |option-backslash| about using backslashes.
Bram Moolenaard8b02732005-01-14 21:48:43 +00002816 This has nothing to do with the |Dictionary| variable type.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002817 Where to find a list of words?
2818 - On FreeBSD, there is the file "/usr/share/dict/words".
2819 - In the Simtel archive, look in the "msdos/linguist" directory.
2820 - In "miscfiles" of the GNU collection.
2821 The use of |:set+=| and |:set-=| is preferred when adding or removing
2822 directories from the list. This avoids problems when a future version
2823 uses another default.
2824 Backticks cannot be used in this option for security reasons.
2825
2826 *'diff'* *'nodiff'*
2827'diff' boolean (default off)
2828 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00002829 {not available when compiled without the |+diff|
2830 feature}
2831 Join the current window in the group of windows that shows differences
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002832 between files. See |vimdiff|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002833
2834 *'dex'* *'diffexpr'*
2835'diffexpr' 'dex' string (default "")
2836 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00002837 {not available when compiled without the |+diff|
2838 feature}
Bram Moolenaare828b762018-09-10 17:51:58 +02002839 Expression which is evaluated to obtain a diff file (either ed-style
2840 or unified-style) from two versions of a file. See |diff-diffexpr|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002841 This option cannot be set from a |modeline| or in the |sandbox|, for
2842 security reasons.
2843
2844 *'dip'* *'diffopt'*
Bram Moolenaarc8234772019-11-10 21:00:27 +01002845'diffopt' 'dip' string (default "internal,filler,closeoff")
Bram Moolenaar071d4272004-06-13 20:20:40 +00002846 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00002847 {not available when compiled without the |+diff|
2848 feature}
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00002849 Option settings for diff mode. It can consist of the following items.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002850 All are optional. Items must be separated by a comma.
2851
2852 filler Show filler lines, to keep the text
2853 synchronized with a window that has inserted
2854 lines at the same position. Mostly useful
2855 when windows are side-by-side and 'scrollbind'
2856 is set.
2857
2858 context:{n} Use a context of {n} lines between a change
2859 and a fold that contains unchanged lines.
2860 When omitted a context of six lines is used.
Bram Moolenaarf6b40102019-02-22 15:24:03 +01002861 When using zero the context is actually one,
2862 since folds require a line in between, also
dundargoc20f48d52023-10-02 21:49:23 +02002863 for a deleted line. Set it to a very large
2864 value (999999) to disable folding completely.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002865 See |fold-diff|.
2866
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002867 iblank Ignore changes where lines are all blank. Adds
2868 the "-B" flag to the "diff" command if
2869 'diffexpr' is empty. Check the documentation
2870 of the "diff" command for what this does
2871 exactly.
2872 NOTE: the diff windows will get out of sync,
2873 because no differences between blank lines are
2874 taken into account.
2875
Bram Moolenaar071d4272004-06-13 20:20:40 +00002876 icase Ignore changes in case of text. "a" and "A"
2877 are considered the same. Adds the "-i" flag
2878 to the "diff" command if 'diffexpr' is empty.
2879
2880 iwhite Ignore changes in amount of white space. Adds
2881 the "-b" flag to the "diff" command if
2882 'diffexpr' is empty. Check the documentation
2883 of the "diff" command for what this does
2884 exactly. It should ignore adding trailing
2885 white space, but not leading white space.
2886
Bram Moolenaar95bafa22018-10-02 13:26:25 +02002887 iwhiteall Ignore all white space changes. Adds
2888 the "-w" flag to the "diff" command if
2889 'diffexpr' is empty. Check the documentation
2890 of the "diff" command for what this does
2891 exactly.
2892
2893 iwhiteeol Ignore white space changes at end of line.
2894 Adds the "-Z" flag to the "diff" command if
2895 'diffexpr' is empty. Check the documentation
2896 of the "diff" command for what this does
2897 exactly.
2898
Bram Moolenaar7d47b6e2006-03-15 22:59:18 +00002899 horizontal Start diff mode with horizontal splits (unless
2900 explicitly specified otherwise).
2901
2902 vertical Start diff mode with vertical splits (unless
2903 explicitly specified otherwise).
2904
Bram Moolenaarc8234772019-11-10 21:00:27 +01002905 closeoff When a window is closed where 'diff' is set
2906 and there is only one window remaining in the
2907 same tab page with 'diff' set, execute
2908 `:diffoff` in that window. This undoes a
2909 `:diffsplit` command.
2910
Bram Moolenaar97ce4192017-12-01 20:35:58 +01002911 hiddenoff Do not use diff mode for a buffer when it
2912 becomes hidden.
2913
Bram Moolenaar7d47b6e2006-03-15 22:59:18 +00002914 foldcolumn:{n} Set the 'foldcolumn' option to {n} when
2915 starting diff mode. Without this 2 is used.
2916
Bram Moolenaar4223d432021-02-10 13:18:17 +01002917 followwrap Follow the 'wrap' option and leave as it is.
2918
Bram Moolenaare828b762018-09-10 17:51:58 +02002919 internal Use the internal diff library. This is
2920 ignored when 'diffexpr' is set. *E960*
2921 When running out of memory when writing a
2922 buffer this item will be ignored for diffs
2923 involving that buffer. Set the 'verbose'
2924 option to see when this happens.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002925
Bram Moolenaare828b762018-09-10 17:51:58 +02002926 indent-heuristic
Bram Moolenaarf0d58ef2018-11-16 16:13:44 +01002927 Use the indent heuristic for the internal
2928 diff library.
Bram Moolenaare828b762018-09-10 17:51:58 +02002929
2930 algorithm:{text} Use the specified diff algorithm with the
Bram Moolenaarf0d58ef2018-11-16 16:13:44 +01002931 internal diff engine. Currently supported
Bram Moolenaare828b762018-09-10 17:51:58 +02002932 algorithms are:
2933 myers the default algorithm
2934 minimal spend extra time to generate the
2935 smallest possible diff
2936 patience patience diff algorithm
2937 histogram histogram diff algorithm
2938
2939 Examples: >
2940 :set diffopt=internal,filler,context:4
Bram Moolenaar071d4272004-06-13 20:20:40 +00002941 :set diffopt=
Bram Moolenaare828b762018-09-10 17:51:58 +02002942 :set diffopt=internal,filler,foldcolumn:3
2943 :set diffopt-=internal " do NOT use the internal diff parser
Bram Moolenaar071d4272004-06-13 20:20:40 +00002944<
2945 *'digraph'* *'dg'* *'nodigraph'* *'nodg'*
2946'digraph' 'dg' boolean (default off)
2947 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00002948 {not available when compiled without the |+digraphs|
2949 feature}
2950 Enable the entering of digraphs in Insert mode with {char1} <BS>
2951 {char2}. See |digraphs|.
2952 NOTE: This option is reset when 'compatible' is set.
2953
2954 *'directory'* *'dir'*
2955'directory' 'dir' string (default for Amiga: ".,t:",
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01002956 for Win32: ".,$TEMP,c:\tmp,c:\temp"
Bram Moolenaar071d4272004-06-13 20:20:40 +00002957 for Unix: ".,~/tmp,/var/tmp,/tmp")
2958 global
2959 List of directory names for the swap file, separated with commas.
Bram Moolenaare7b1ea02020-08-07 19:54:59 +02002960 Recommended value: ".,~/vimswap//" - this will put the swap file next
2961 to the edited file if possible, and in your personal swap directory
2962 otherwise. Make sure "~/vimswap//" is only readable for you.
2963
2964 Possible items:
Bram Moolenaar071d4272004-06-13 20:20:40 +00002965 - The swap file will be created in the first directory where this is
2966 possible.
2967 - Empty means that no swap file will be used (recovery is
Bram Moolenaar00e192b2019-10-19 17:01:28 +02002968 impossible!) and no |E303| error will be given.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002969 - A directory "." means to put the swap file in the same directory as
2970 the edited file. On Unix, a dot is prepended to the file name, so
2971 it doesn't show in a directory listing. On MS-Windows the "hidden"
2972 attribute is set and a dot prepended if possible.
Bram Moolenaar8024f932020-01-14 19:29:13 +01002973 - A directory starting with "./" (or ".\" for MS-Windows) means to put
2974 the swap file relative to where the edited file is. The leading "."
2975 is replaced with the path name of the edited file.
Bram Moolenaarb782ba42018-08-07 21:39:28 +02002976 - For Unix and Win32, if a directory ends in two path separators "//",
2977 the swap file name will be built from the complete path to the file
Bram Moolenaar207f0092020-08-30 17:20:20 +02002978 with all path separators replaced by percent '%' signs (including
2979 the colon following the drive letter on Win32). This will ensure
2980 file name uniqueness in the preserve directory.
Bram Moolenaarb782ba42018-08-07 21:39:28 +02002981 On Win32, it is also possible to end with "\\". However, When a
2982 separating comma is following, you must use "//", since "\\" will
2983 include the comma in the file name. Therefore it is recommended to
2984 use '//', instead of '\\'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002985 - Spaces after the comma are ignored, other spaces are considered part
2986 of the directory name. To have a space at the start of a directory
2987 name, precede it with a backslash.
2988 - To include a comma in a directory name precede it with a backslash.
2989 - A directory name may end in an ':' or '/'.
2990 - Environment variables are expanded |:set_env|.
2991 - Careful with '\' characters, type one before a space, type two to
2992 get one in the option (see |option-backslash|), for example: >
2993 :set dir=c:\\tmp,\ dir\\,with\\,commas,\\\ dir\ with\ spaces
2994< - For backwards compatibility with Vim version 3.0 a '>' at the start
2995 of the option is removed.
2996 Using "." first in the list is recommended. This means that editing
2997 the same file twice will result in a warning. Using "/tmp" on Unix is
2998 discouraged: When the system crashes you lose the swap file.
2999 "/var/tmp" is often not cleared when rebooting, thus is a better
Bram Moolenaare7b1ea02020-08-07 19:54:59 +02003000 choice than "/tmp". But others on the computer may be able to see the
3001 files, and it can contain a lot of files, your swap files get lost in
3002 the crowd. That is why a "tmp" directory in your home directory is
3003 tried first.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003004 The use of |:set+=| and |:set-=| is preferred when adding or removing
3005 directories from the list. This avoids problems when a future version
3006 uses another default.
3007 This option cannot be set from a |modeline| or in the |sandbox|, for
3008 security reasons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003009
3010 *'display'* *'dy'*
Bram Moolenaarbc8801c2016-08-02 21:04:33 +02003011'display' 'dy' string (default "", set to "truncate" in
3012 |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00003013 global
Bram Moolenaarf269eab2022-10-03 18:04:35 +01003014 Change the way text is displayed. This is a comma-separated list of
Bram Moolenaar071d4272004-06-13 20:20:40 +00003015 flags:
3016 lastline When included, as much as possible of the last line
Bram Moolenaarad9c2a02016-07-27 23:26:04 +02003017 in a window will be displayed. "@@@" is put in the
3018 last columns of the last screen line to indicate the
3019 rest of the line is not displayed.
3020 truncate Like "lastline", but "@@@" is displayed in the first
3021 column of the last screen line. Overrules "lastline".
Bram Moolenaar071d4272004-06-13 20:20:40 +00003022 uhex Show unprintable characters hexadecimal as <xx>
3023 instead of using ^C and ~C.
3024
Bram Moolenaard0796902016-09-16 20:02:31 +02003025 When neither "lastline" nor "truncate" is included, a last line that
Bram Moolenaarad9c2a02016-07-27 23:26:04 +02003026 doesn't fit is replaced with "@" lines.
3027
Bram Moolenaar4ba5f1d2022-10-04 14:36:29 +01003028 The "@" character can be changed by setting the "lastline" item in
3029 'fillchars'. The character is highlighted with |hl-NonText|.
3030
Bram Moolenaar071d4272004-06-13 20:20:40 +00003031 *'eadirection'* *'ead'*
3032'eadirection' 'ead' string (default "both")
3033 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003034 Tells when the 'equalalways' option applies:
3035 ver vertically, width of windows is not affected
3036 hor horizontally, height of windows is not affected
3037 both width and height of windows is affected
3038
3039 *'ed'* *'edcompatible'* *'noed'* *'noedcompatible'*
3040'edcompatible' 'ed' boolean (default off)
3041 global
3042 Makes the 'g' and 'c' flags of the ":substitute" command to be
3043 toggled each time the flag is given. See |complex-change|. See
3044 also 'gdefault' option.
Bram Moolenaarb4d6c3e2017-05-27 16:45:17 +02003045 Switching this option on may break plugins!
Bram Moolenaar4072ba52020-12-23 13:56:35 +01003046 This option is not used in |Vim9| script.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003047
Bram Moolenaar03413f42016-04-12 21:07:15 +02003048 *'emoji'* *'emo'* *'noemoji'* *'noemo'*
Bram Moolenaar3848e002016-03-19 18:42:29 +01003049'emoji' 'emo' boolean (default: on)
3050 global
Bram Moolenaar3848e002016-03-19 18:42:29 +01003051 When on all Unicode emoji characters are considered to be full width.
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02003052 This excludes "text emoji" characters, which are normally displayed as
3053 single width. Unfortunately there is no good specification for this
3054 and it has been determined on trial-and-error basis. Use the
3055 |setcellwidths()| function to change the behavior.
Bram Moolenaar3848e002016-03-19 18:42:29 +01003056
Bram Moolenaar071d4272004-06-13 20:20:40 +00003057 *'encoding'* *'enc'* *E543*
K.Takataf883d902021-05-30 18:04:19 +02003058'encoding' 'enc' string (default for MS-Windows: "utf-8",
3059 otherwise: value from $LANG or "latin1")
Bram Moolenaar071d4272004-06-13 20:20:40 +00003060 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003061 Sets the character encoding used inside Vim. It applies to text in
3062 the buffers, registers, Strings in expressions, text stored in the
3063 viminfo file, etc. It sets the kind of characters which Vim can work
3064 with. See |encoding-names| for the possible values.
3065
3066 NOTE: Changing this option will not change the encoding of the
Bram Moolenaar1cd871b2004-12-19 22:46:22 +00003067 existing text in Vim. It may cause non-ASCII text to become invalid.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003068 It should normally be kept at its default value, or set when Vim
Bram Moolenaar02467872007-05-06 13:22:01 +00003069 starts up. See |multibyte|. To reload the menus see |:menutrans|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003070
Bram Moolenaar865242e2010-07-14 21:12:05 +02003071 This option cannot be set from a |modeline|. It would most likely
3072 corrupt the text.
3073
Bram Moolenaar3df01732017-02-17 22:47:16 +01003074 NOTE: For GTK+ 2 or later, it is highly recommended to set 'encoding'
3075 to "utf-8". Although care has been taken to allow different values of
Bram Moolenaar071d4272004-06-13 20:20:40 +00003076 'encoding', "utf-8" is the natural choice for the environment and
3077 avoids unnecessary conversion overhead. "utf-8" has not been made
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003078 the default to prevent different behavior of the GUI and terminal
Bram Moolenaar071d4272004-06-13 20:20:40 +00003079 versions, and to avoid changing the encoding of newly created files
3080 without your knowledge (in case 'fileencodings' is empty).
3081
3082 The character encoding of files can be different from 'encoding'.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003083 This is specified with 'fileencoding'. The conversion is done with
Bram Moolenaar071d4272004-06-13 20:20:40 +00003084 iconv() or as specified with 'charconvert'.
3085
Bram Moolenaar207f0092020-08-30 17:20:20 +02003086 If you need to know whether 'encoding' is a multibyte encoding, you
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003087 can use: >
3088 if has("multi_byte_encoding")
3089<
Bram Moolenaar071d4272004-06-13 20:20:40 +00003090 Normally 'encoding' will be equal to your current locale. This will
3091 be the default if Vim recognizes your environment settings. If
3092 'encoding' is not set to the current locale, 'termencoding' must be
3093 set to convert typed and displayed text. See |encoding-table|.
3094
3095 When you set this option, it fires the |EncodingChanged| autocommand
3096 event so that you can set up fonts if necessary.
3097
3098 When the option is set, the value is converted to lowercase. Thus
3099 you can set it with uppercase values too. Underscores are translated
3100 to '-' signs.
3101 When the encoding is recognized, it is changed to the standard name.
3102 For example "Latin-1" becomes "latin1", "ISO_88592" becomes
3103 "iso-8859-2" and "utf8" becomes "utf-8".
3104
3105 Note: "latin1" is also used when the encoding could not be detected.
3106 This only works when editing files in the same encoding! When the
3107 actual character set is not latin1, make sure 'fileencoding' and
3108 'fileencodings' are empty. When conversion is needed, switch to using
3109 utf-8.
3110
3111 When "unicode", "ucs-2" or "ucs-4" is used, Vim internally uses utf-8.
3112 You don't notice this while editing, but it does matter for the
3113 |viminfo-file|. And Vim expects the terminal to use utf-8 too. Thus
3114 setting 'encoding' to one of these values instead of utf-8 only has
3115 effect for encoding used for files when 'fileencoding' is empty.
3116
Bram Moolenaar661b1822005-07-28 22:36:45 +00003117 When 'encoding' is set to a Unicode encoding, and 'fileencodings' was
3118 not set yet, the default for 'fileencodings' is changed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003119
Bram Moolenaar6ebe4f92022-10-28 20:47:54 +01003120 *'endoffile'* *'eof'* *'noendoffile'* *'noeof'*
Bram Moolenaar0aad88f2022-11-12 11:54:26 +00003121'endoffile' 'eof' boolean (default off)
Bram Moolenaar071d4272004-06-13 20:20:40 +00003122 local to buffer
Bram Moolenaar6ebe4f92022-10-28 20:47:54 +01003123 Indicates that a CTRL-Z character was found at the end of the file
3124 when reading it. Normally only happens when 'fileformat' is "dos".
Bram Moolenaar071d4272004-06-13 20:20:40 +00003125 When writing a file and this option is off and the 'binary' option
Bram Moolenaar6ebe4f92022-10-28 20:47:54 +01003126 is on, or 'fixeol' option is off, no CTRL-Z will be written at the
Bram Moolenaarfb0cf232022-10-22 11:25:19 +01003127 end of the file.
K.Takata3af98212022-11-01 20:36:19 +00003128 See |eol-and-eof| for example settings.
Bram Moolenaarfb0cf232022-10-22 11:25:19 +01003129
3130 *'endofline'* *'eol'* *'noendofline'* *'noeol'*
3131'endofline' 'eol' boolean (default on)
3132 local to buffer
3133 When writing a file and this option is off and the 'binary' option
Bram Moolenaar34d72d42015-07-17 14:18:08 +02003134 is on, or 'fixeol' option is off, no <EOL> will be written for the
3135 last line in the file. This option is automatically set or reset when
3136 starting to edit a new file, depending on whether file has an <EOL>
3137 for the last line in the file. Normally you don't have to set or
3138 reset this option.
3139 When 'binary' is off and 'fixeol' is on the value is not used when
3140 writing the file. When 'binary' is on or 'fixeol' is off it is used
3141 to remember the presence of a <EOL> for the last line in the file, so
3142 that when you write the file the situation from the original file can
3143 be kept. But you can change it if you want to.
K.Takata3af98212022-11-01 20:36:19 +00003144 See |eol-and-eof| for example settings.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003145
3146 *'equalalways'* *'ea'* *'noequalalways'* *'noea'*
3147'equalalways' 'ea' boolean (default on)
3148 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003149 When on, all the windows are automatically made the same size after
Bram Moolenaar009b2592004-10-24 19:18:58 +00003150 splitting or closing a window. This also happens the moment the
3151 option is switched on. When off, splitting a window will reduce the
3152 size of the current window and leave the other windows the same. When
3153 closing a window the extra lines are given to the window next to it
3154 (depending on 'splitbelow' and 'splitright').
Bram Moolenaar071d4272004-06-13 20:20:40 +00003155 When mixing vertically and horizontally split windows, a minimal size
3156 is computed and some windows may be larger if there is room. The
3157 'eadirection' option tells in which direction the size is affected.
Bram Moolenaar67f71312007-08-12 14:55:56 +00003158 Changing the height and width of a window can be avoided by setting
3159 'winfixheight' and 'winfixwidth', respectively.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003160 If a window size is specified when creating a new window sizes are
3161 currently not equalized (it's complicated, but may be implemented in
3162 the future).
Bram Moolenaar071d4272004-06-13 20:20:40 +00003163
3164 *'equalprg'* *'ep'*
3165'equalprg' 'ep' string (default "")
3166 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00003167 External program to use for "=" command. When this option is empty
Bram Moolenaar446cb832008-06-24 21:56:24 +00003168 the internal formatting functions are used; either 'lisp', 'cindent'
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003169 or 'indentexpr'. When Vim was compiled without internal formatting,
3170 the "indent" program is used.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003171 Environment variables are expanded |:set_env|. See |option-backslash|
Bram Moolenaar071d4272004-06-13 20:20:40 +00003172 about including spaces and backslashes.
3173 This option cannot be set from a |modeline| or in the |sandbox|, for
3174 security reasons.
3175
3176 *'errorbells'* *'eb'* *'noerrorbells'* *'noeb'*
3177'errorbells' 'eb' boolean (default off)
3178 global
3179 Ring the bell (beep or screen flash) for error messages. This only
3180 makes a difference for error messages, the bell will be used always
3181 for a lot of errors without a message (e.g., hitting <Esc> in Normal
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003182 mode). See 'visualbell' on how to make the bell behave like a beep,
Bram Moolenaar165bc692015-07-21 17:53:25 +02003183 screen flash or do nothing. See 'belloff' to finetune when to ring the
3184 bell.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003185
3186 *'errorfile'* *'ef'*
3187'errorfile' 'ef' string (Amiga default: "AztecC.Err",
3188 others: "errors.err")
3189 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003190 {not available when compiled without the |+quickfix|
3191 feature}
3192 Name of the errorfile for the QuickFix mode (see |:cf|).
3193 When the "-q" command-line argument is used, 'errorfile' is set to the
3194 following argument. See |-q|.
3195 NOT used for the ":make" command. See 'makeef' for that.
3196 Environment variables are expanded |:set_env|.
3197 See |option-backslash| about including spaces and backslashes.
3198 This option cannot be set from a |modeline| or in the |sandbox|, for
3199 security reasons.
3200
3201 *'errorformat'* *'efm'*
3202'errorformat' 'efm' string (default is very long)
3203 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00003204 {not available when compiled without the |+quickfix|
3205 feature}
3206 Scanf-like description of the format for the lines in the error file
3207 (see |errorformat|).
3208
3209 *'esckeys'* *'ek'* *'noesckeys'* *'noek'*
3210'esckeys' 'ek' boolean (Vim default: on, Vi default: off)
3211 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003212 Function keys that start with an <Esc> are recognized in Insert
3213 mode. When this option is off, the cursor and function keys cannot be
3214 used in Insert mode if they start with an <Esc>. The advantage of
3215 this is that the single <Esc> is recognized immediately, instead of
3216 after one second. Instead of resetting this option, you might want to
3217 try changing the values for 'timeoutlen' and 'ttimeoutlen'. Note that
3218 when 'esckeys' is off, you can still map anything, but the cursor keys
3219 won't work by default.
3220 NOTE: This option is set to the Vi default value when 'compatible' is
3221 set and to the Vim default value when 'compatible' is reset.
Christian Brabandt5f5131d2023-10-25 21:44:26 +02003222 NOTE: when this option is off then the |modifyOtherKeys| and
3223 |xterm-bracketed-paste| functionality is disabled while in Insert mode
3224 to avoid ending Insert mode with any key that has a modifier.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003225
3226 *'eventignore'* *'ei'*
3227'eventignore' 'ei' string (default "")
3228 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003229 A list of autocommand event names, which are to be ignored.
Bram Moolenaarf193fff2006-04-27 00:02:13 +00003230 When set to "all" or when "all" is one of the items, all autocommand
3231 events are ignored, autocommands will not be executed.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01003232 Otherwise this is a comma-separated list of event names. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00003233 :set ei=WinEnter,WinLeave
3234<
3235 *'expandtab'* *'et'* *'noexpandtab'* *'noet'*
3236'expandtab' 'et' boolean (default off)
3237 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00003238 In Insert mode: Use the appropriate number of spaces to insert a
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003239 <Tab>. Spaces are used in indents with the '>' and '<' commands and
Bram Moolenaar071d4272004-06-13 20:20:40 +00003240 when 'autoindent' is on. To insert a real tab when 'expandtab' is
3241 on, use CTRL-V<Tab>. See also |:retab| and |ins-expandtab|.
Bram Moolenaarca635012015-09-25 20:34:21 +02003242 This option is reset when the 'paste' option is set and restored when
3243 the 'paste' option is reset.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003244 NOTE: This option is reset when 'compatible' is set.
3245
3246 *'exrc'* *'ex'* *'noexrc'* *'noex'*
3247'exrc' 'ex' boolean (default off)
3248 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003249 Enables the reading of .vimrc, .exrc and .gvimrc in the current
Bram Moolenaar36f44c22016-08-28 18:17:20 +02003250 directory.
3251
3252 Setting this option is a potential security leak. E.g., consider
3253 unpacking a package or fetching files from github, a .vimrc in there
3254 might be a trojan horse. BETTER NOT SET THIS OPTION!
3255 Instead, define an autocommand in your .vimrc to set options for a
3256 matching directory.
3257
3258 If you do switch this option on you should also consider setting the
3259 'secure' option (see |initialization|).
3260 Also see |.vimrc| and |gui-init|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003261 This option cannot be set from a |modeline| or in the |sandbox|, for
3262 security reasons.
3263
3264 *'fileencoding'* *'fenc'* *E213*
3265'fileencoding' 'fenc' string (default: "")
3266 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00003267 Sets the character encoding for the file of this buffer.
Bram Moolenaar865242e2010-07-14 21:12:05 +02003268
Bram Moolenaar071d4272004-06-13 20:20:40 +00003269 When 'fileencoding' is different from 'encoding', conversion will be
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003270 done when writing the file. For reading see below.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003271 When 'fileencoding' is empty, the same value as 'encoding' will be
3272 used (no conversion when reading or writing a file).
Bram Moolenaar214641f2017-03-05 17:04:09 +01003273 No error will be given when the value is set, only when it is used,
3274 only when writing a file.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003275 Conversion will also be done when 'encoding' and 'fileencoding' are
3276 both a Unicode encoding and 'fileencoding' is not utf-8. That's
3277 because internally Unicode is always stored as utf-8.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003278 WARNING: Conversion can cause loss of information! When
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003279 'encoding' is "utf-8" or another Unicode encoding, conversion
3280 is most likely done in a way that the reverse conversion
3281 results in the same text. When 'encoding' is not "utf-8" some
3282 characters may be lost!
Bram Moolenaar865242e2010-07-14 21:12:05 +02003283
Bram Moolenaar071d4272004-06-13 20:20:40 +00003284 See 'encoding' for the possible values. Additionally, values may be
3285 specified that can be handled by the converter, see
3286 |mbyte-conversion|.
Bram Moolenaar865242e2010-07-14 21:12:05 +02003287
Bram Moolenaar071d4272004-06-13 20:20:40 +00003288 When reading a file 'fileencoding' will be set from 'fileencodings'.
3289 To read a file in a certain encoding it won't work by setting
Bram Moolenaar02467872007-05-06 13:22:01 +00003290 'fileencoding', use the |++enc| argument. One exception: when
3291 'fileencodings' is empty the value of 'fileencoding' is used.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003292 For a new file the global value of 'fileencoding' is used.
Bram Moolenaar865242e2010-07-14 21:12:05 +02003293
Bram Moolenaar071d4272004-06-13 20:20:40 +00003294 Prepending "8bit-" and "2byte-" has no meaning here, they are ignored.
3295 When the option is set, the value is converted to lowercase. Thus
3296 you can set it with uppercase values too. '_' characters are
3297 replaced with '-'. If a name is recognized from the list for
3298 'encoding', it is replaced by the standard name. For example
3299 "ISO8859-2" becomes "iso-8859-2".
Bram Moolenaar865242e2010-07-14 21:12:05 +02003300
Bram Moolenaar071d4272004-06-13 20:20:40 +00003301 When this option is set, after starting to edit a file, the 'modified'
3302 option is set, because the file would be different when written.
Bram Moolenaar865242e2010-07-14 21:12:05 +02003303
3304 Keep in mind that changing 'fenc' from a modeline happens
3305 AFTER the text has been read, thus it applies to when the file will be
3306 written. If you do set 'fenc' in a modeline, you might want to set
3307 'nomodified' to avoid not being able to ":q".
3308
Bram Moolenaar071d4272004-06-13 20:20:40 +00003309 This option can not be changed when 'modifiable' is off.
3310
3311 *'fe'*
3312 NOTE: Before version 6.0 this option specified the encoding for the
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003313 whole of Vim, this was a mistake. Now use 'encoding' instead. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00003314 old short name was 'fe', which is no longer used.
3315
3316 *'fileencodings'* *'fencs'*
Bram Moolenaar1cd871b2004-12-19 22:46:22 +00003317'fileencodings' 'fencs' string (default: "ucs-bom",
3318 "ucs-bom,utf-8,default,latin1" when
3319 'encoding' is set to a Unicode value)
Bram Moolenaar071d4272004-06-13 20:20:40 +00003320 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003321 This is a list of character encodings considered when starting to edit
3322 an existing file. When a file is read, Vim tries to use the first
3323 mentioned character encoding. If an error is detected, the next one
3324 in the list is tried. When an encoding is found that works,
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003325 'fileencoding' is set to it. If all fail, 'fileencoding' is set to
Bram Moolenaar071d4272004-06-13 20:20:40 +00003326 an empty string, which means the value of 'encoding' is used.
3327 WARNING: Conversion can cause loss of information! When
3328 'encoding' is "utf-8" (or one of the other Unicode variants)
3329 conversion is most likely done in a way that the reverse
3330 conversion results in the same text. When 'encoding' is not
Bram Moolenaarc6d8db72005-12-13 20:04:55 +00003331 "utf-8" some non-ASCII characters may be lost! You can use
3332 the |++bad| argument to specify what is done with characters
3333 that can't be converted.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003334 For an empty file or a file with only ASCII characters most encodings
3335 will work and the first entry of 'fileencodings' will be used (except
3336 "ucs-bom", which requires the BOM to be present). If you prefer
3337 another encoding use an BufReadPost autocommand event to test if your
3338 preferred encoding is to be used. Example: >
3339 au BufReadPost * if search('\S', 'w') == 0 |
3340 \ set fenc=iso-2022-jp | endif
3341< This sets 'fileencoding' to "iso-2022-jp" if the file does not contain
3342 non-blank characters.
Bram Moolenaarc6d8db72005-12-13 20:04:55 +00003343 When the |++enc| argument is used then the value of 'fileencodings' is
3344 not used.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00003345 Note that 'fileencodings' is not used for a new file, the global value
3346 of 'fileencoding' is used instead. You can set it with: >
3347 :setglobal fenc=iso-8859-2
3348< This means that a non-existing file may get a different encoding than
3349 an empty file.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003350 The special value "ucs-bom" can be used to check for a Unicode BOM
3351 (Byte Order Mark) at the start of the file. It must not be preceded
3352 by "utf-8" or another Unicode encoding for this to work properly.
3353 An entry for an 8-bit encoding (e.g., "latin1") should be the last,
3354 because Vim cannot detect an error, thus the encoding is always
3355 accepted.
Bram Moolenaar1cd871b2004-12-19 22:46:22 +00003356 The special value "default" can be used for the encoding from the
K.Takataef8706f2021-05-31 18:40:49 +02003357 environment. On MS-Windows this is the system encoding. Otherwise
3358 this is the default value for 'encoding'. It is useful when
3359 'encoding' is set to "utf-8" and your environment uses a non-latin1
3360 encoding, such as Russian.
Bram Moolenaarca003e12006-03-17 23:19:38 +00003361 When 'encoding' is "utf-8" and a file contains an illegal byte
3362 sequence it won't be recognized as UTF-8. You can use the |8g8|
3363 command to find the illegal byte sequence.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003364 WRONG VALUES: WHAT'S WRONG:
3365 latin1,utf-8 "latin1" will always be used
3366 utf-8,ucs-bom,latin1 BOM won't be recognized in an utf-8
3367 file
3368 cp1250,latin1 "cp1250" will always be used
3369 If 'fileencodings' is empty, 'fileencoding' is not modified.
3370 See 'fileencoding' for the possible values.
3371 Setting this option does not have an effect until the next time a file
3372 is read.
3373
3374 *'fileformat'* *'ff'*
Bram Moolenaar00590742019-02-15 21:06:09 +01003375'fileformat' 'ff' string (MS-Windows default: "dos",
3376 Unix, macOS default: "unix")
Bram Moolenaar071d4272004-06-13 20:20:40 +00003377 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00003378 This gives the <EOL> of the current buffer, which is used for
3379 reading/writing the buffer from/to a file:
Bram Moolenaar4072ba52020-12-23 13:56:35 +01003380 dos <CR><NL>
Bram Moolenaar071d4272004-06-13 20:20:40 +00003381 unix <NL>
3382 mac <CR>
3383 When "dos" is used, CTRL-Z at the end of a file is ignored.
3384 See |file-formats| and |file-read|.
3385 For the character encoding of the file see 'fileencoding'.
3386 When 'binary' is set, the value of 'fileformat' is ignored, file I/O
Bram Moolenaarbf884932013-04-05 22:26:15 +02003387 works like it was set to "unix".
Bram Moolenaar071d4272004-06-13 20:20:40 +00003388 This option is set automatically when starting to edit a file and
3389 'fileformats' is not empty and 'binary' is off.
3390 When this option is set, after starting to edit a file, the 'modified'
3391 option is set, because the file would be different when written.
3392 This option can not be changed when 'modifiable' is off.
3393 For backwards compatibility: When this option is set to "dos",
3394 'textmode' is set, otherwise 'textmode' is reset.
3395
3396 *'fileformats'* *'ffs'*
3397'fileformats' 'ffs' string (default:
Bram Moolenaar00590742019-02-15 21:06:09 +01003398 Vim+Vi MS-Windows: "dos,unix",
3399 Vim Unix, macOS: "unix,dos",
Bram Moolenaar071d4272004-06-13 20:20:40 +00003400 Vi Cygwin: "unix,dos",
3401 Vi others: "")
3402 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003403 This gives the end-of-line (<EOL>) formats that will be tried when
3404 starting to edit a new buffer and when reading a file into an existing
3405 buffer:
3406 - When empty, the format defined with 'fileformat' will be used
3407 always. It is not set automatically.
3408 - When set to one name, that format will be used whenever a new buffer
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003409 is opened. 'fileformat' is set accordingly for that buffer. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00003410 'fileformats' name will be used when a file is read into an existing
3411 buffer, no matter what 'fileformat' for that buffer is set to.
3412 - When more than one name is present, separated by commas, automatic
3413 <EOL> detection will be done when reading a file. When starting to
3414 edit a file, a check is done for the <EOL>:
3415 1. If all lines end in <CR><NL>, and 'fileformats' includes "dos",
3416 'fileformat' is set to "dos".
3417 2. If a <NL> is found and 'fileformats' includes "unix", 'fileformat'
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003418 is set to "unix". Note that when a <NL> is found without a
Bram Moolenaar071d4272004-06-13 20:20:40 +00003419 preceding <CR>, "unix" is preferred over "dos".
Bram Moolenaar2b8388b2015-02-28 13:11:45 +01003420 3. If 'fileformat' has not yet been set, and if a <CR> is found, and
3421 if 'fileformats' includes "mac", 'fileformat' is set to "mac".
Bram Moolenaar00659062010-09-21 22:34:02 +02003422 This means that "mac" is only chosen when:
3423 "unix" is not present or no <NL> is found in the file, and
3424 "dos" is not present or no <CR><NL> is found in the file.
3425 Except: if "unix" was chosen, but there is a <CR> before
3426 the first <NL>, and there appear to be more <CR>s than <NL>s in
Bram Moolenaar166af9b2010-11-16 20:34:40 +01003427 the first few lines, "mac" is used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003428 4. If 'fileformat' is still not set, the first name from
3429 'fileformats' is used.
3430 When reading a file into an existing buffer, the same is done, but
3431 this happens like 'fileformat' has been set appropriately for that
3432 file only, the option is not changed.
3433 When 'binary' is set, the value of 'fileformats' is not used.
3434
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01003435 When Vim starts up with an empty buffer the first item is used. You
3436 can overrule this by setting 'fileformat' in your .vimrc.
Bram Moolenaar81af9252010-12-10 20:35:50 +01003437
Bram Moolenaar071d4272004-06-13 20:20:40 +00003438 For systems with a Dos-like <EOL> (<CR><NL>), when reading files that
3439 are ":source"ed and for vimrc files, automatic <EOL> detection may be
3440 done:
3441 - When 'fileformats' is empty, there is no automatic detection. Dos
3442 format will be used.
3443 - When 'fileformats' is set to one or more names, automatic detection
3444 is done. This is based on the first <NL> in the file: If there is a
3445 <CR> in front of it, Dos format is used, otherwise Unix format is
3446 used.
3447 Also see |file-formats|.
3448 For backwards compatibility: When this option is set to an empty
3449 string or one format (no comma is included), 'textauto' is reset,
3450 otherwise 'textauto' is set.
3451 NOTE: This option is set to the Vi default value when 'compatible' is
3452 set and to the Vim default value when 'compatible' is reset.
3453
Bram Moolenaarbf884932013-04-05 22:26:15 +02003454 *'fileignorecase'* *'fic'* *'nofileignorecase'* *'nofic'*
3455'fileignorecase' 'fic' boolean (default on for systems where case in file
3456 names is normally ignored)
Bram Moolenaar71afbfe2013-03-19 16:49:16 +01003457 global
Bram Moolenaar71afbfe2013-03-19 16:49:16 +01003458 When set case is ignored when using file names and directories.
3459 See 'wildignorecase' for only ignoring case when doing completion.
3460
Bram Moolenaar071d4272004-06-13 20:20:40 +00003461 *'filetype'* *'ft'*
3462'filetype' 'ft' string (default: "")
Christian Brabandt596ad662023-08-16 00:11:09 +02003463 local to buffer |local-noglobal|
Bram Moolenaar071d4272004-06-13 20:20:40 +00003464 When this option is set, the FileType autocommand event is triggered.
3465 All autocommands that match with the value of this option will be
3466 executed. Thus the value of 'filetype' is used in place of the file
3467 name.
3468 Otherwise this option does not always reflect the current file type.
3469 This option is normally set when the file type is detected. To enable
3470 this use the ":filetype on" command. |:filetype|
3471 Setting this option to a different value is most useful in a modeline,
3472 for a file for which the file type is not automatically recognized.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00003473 Example, for in an IDL file:
3474 /* vim: set filetype=idl : */ ~
3475 |FileType| |filetypes|
3476 When a dot appears in the value then this separates two filetype
3477 names. Example:
3478 /* vim: set filetype=c.doxygen : */ ~
3479 This will use the "c" filetype first, then the "doxygen" filetype.
3480 This works both for filetype plugins and for syntax files. More than
3481 one dot may appear.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003482 This option is not copied to another buffer, independent of the 's' or
3483 'S' flag in 'cpoptions'.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00003484 Only normal file name characters can be used, "/\*?[|<>" are illegal.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003485
3486 *'fillchars'* *'fcs'*
Bram Moolenaara98f8a22021-02-13 18:24:23 +01003487'fillchars' 'fcs' string (default "vert:|,fold:-,eob:~")
Bram Moolenaar96ba25a2022-07-04 17:34:33 +01003488 global or local to window |global-local|
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02003489 {not available when compiled without the |+folding|
3490 feature}
Bram Moolenaar96ba25a2022-07-04 17:34:33 +01003491 Characters to fill the statuslines, vertical separators and special
3492 lines in the window.
3493 It is a comma-separated list of items. Each item has a name, a colon
3494 and the value of that item:
Bram Moolenaar071d4272004-06-13 20:20:40 +00003495
Bram Moolenaar96ba25a2022-07-04 17:34:33 +01003496 item name default Used for ~
Christian Brabandt6a650bf2023-11-08 21:23:29 +01003497 stl ' ' statusline of the current window
3498 stlnc ' ' statusline of the non-current windows
Bram Moolenaar96ba25a2022-07-04 17:34:33 +01003499 vert '|' vertical separators |:vsplit|
3500 fold '-' filling 'foldtext'
3501 foldopen '-' mark the beginning of a fold
3502 foldclose '+' show a closed fold
3503 foldsep '|' open fold middle character
3504 diff '-' deleted lines of the 'diff' option
3505 eob '~' empty lines below the end of a buffer
Bram Moolenaar4ba5f1d2022-10-04 14:36:29 +01003506 lastline '@' 'display' contains lastline/truncate
Bram Moolenaar071d4272004-06-13 20:20:40 +00003507
Christian Brabandt6a650bf2023-11-08 21:23:29 +01003508 Any one that is omitted will fall back to the default.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003509
3510 Example: >
Christian Brabandt6a650bf2023-11-08 21:23:29 +01003511 :set fillchars=stl:\ ,stlnc:\ ,vert:\|,fold:-,diff:-
3512<
Bram Moolenaar8cc5b552022-06-23 13:04:20 +01003513 For the "stl", "stlnc", "foldopen", "foldclose" and "foldsep" items
3514 single-byte and multibyte characters are supported. But double-width
3515 characters are not supported.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003516
Bram Moolenaar071d4272004-06-13 20:20:40 +00003517 The highlighting used for these items:
Bram Moolenaar96ba25a2022-07-04 17:34:33 +01003518 item name highlight group ~
3519 stl StatusLine |hl-StatusLine|
3520 stlnc StatusLineNC |hl-StatusLineNC|
3521 vert VertSplit |hl-VertSplit|
3522 fold Folded |hl-Folded|
3523 diff DiffDelete |hl-DiffDelete|
3524 eob EndOfBuffer |hl-EndOfBuffer|
Bram Moolenaar4ba5f1d2022-10-04 14:36:29 +01003525 lastline NonText |hl-NonText|
Bram Moolenaar071d4272004-06-13 20:20:40 +00003526
Bram Moolenaar34d72d42015-07-17 14:18:08 +02003527 *'fixendofline'* *'fixeol'* *'nofixendofline'* *'nofixeol'*
3528'fixendofline' 'fixeol' boolean (default on)
3529 local to buffer
Bram Moolenaar34d72d42015-07-17 14:18:08 +02003530 When writing a file and this option is on, <EOL> at the end of file
Bram Moolenaarfb0cf232022-10-22 11:25:19 +01003531 will be restored if missing. Turn this option off if you want to
Bram Moolenaar34d72d42015-07-17 14:18:08 +02003532 preserve the situation from the original file.
3533 When the 'binary' option is set the value of this option doesn't
3534 matter.
3535 See the 'endofline' option.
K.Takata3af98212022-11-01 20:36:19 +00003536 See |eol-and-eof| for example settings.
Bram Moolenaar34d72d42015-07-17 14:18:08 +02003537
Bram Moolenaar071d4272004-06-13 20:20:40 +00003538 *'fkmap'* *'fk'* *'nofkmap'* *'nofk'*
Bram Moolenaar98a29d02021-01-18 19:55:44 +01003539'fkmap' 'fk' boolean (default off)
Bram Moolenaar071d4272004-06-13 20:20:40 +00003540 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003541 {only available when compiled with the |+rightleft|
3542 feature}
Bram Moolenaar14184a32019-02-16 15:10:30 +01003543 This option was for using Farsi, which has been removed. See
3544 |farsi.txt|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003545
3546 *'foldclose'* *'fcl'*
3547'foldclose' 'fcl' string (default "")
3548 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003549 {not available when compiled without the |+folding|
3550 feature}
3551 When set to "all", a fold is closed when the cursor isn't in it and
3552 its level is higher than 'foldlevel'. Useful if you want folds to
3553 automatically close when moving out of them.
3554
3555 *'foldcolumn'* *'fdc'*
3556'foldcolumn' 'fdc' number (default 0)
3557 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003558 {not available when compiled without the |+folding|
3559 feature}
3560 When non-zero, a column with the specified width is shown at the side
3561 of the window which indicates open and closed folds. The maximum
3562 value is 12.
3563 See |folding|.
3564
3565 *'foldenable'* *'fen'* *'nofoldenable'* *'nofen'*
3566'foldenable' 'fen' boolean (default on)
3567 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003568 {not available when compiled without the |+folding|
3569 feature}
3570 When off, all folds are open. This option can be used to quickly
3571 switch between showing all text unfolded and viewing the text with
3572 folds (including manually opened or closed folds). It can be toggled
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003573 with the |zi| command. The 'foldcolumn' will remain blank when
Bram Moolenaar071d4272004-06-13 20:20:40 +00003574 'foldenable' is off.
3575 This option is set by commands that create a new fold or close a fold.
3576 See |folding|.
3577
3578 *'foldexpr'* *'fde'*
3579'foldexpr' 'fde' string (default: "0")
3580 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003581 {not available when compiled without the |+folding|
Bram Moolenaardb84e452010-08-15 13:50:43 +02003582 or |+eval| features}
Bram Moolenaar071d4272004-06-13 20:20:40 +00003583 The expression used for when 'foldmethod' is "expr". It is evaluated
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00003584 for each line to obtain its fold level. The context is set to the
3585 script where 'foldexpr' was set, script-local items can be accessed.
3586 See |fold-expr| for the usage.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00003587
Bram Moolenaar30b65812012-07-12 22:01:11 +02003588 The expression will be evaluated in the |sandbox| if set from a
3589 modeline, see |sandbox-option|.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01003590 This option can't be set from a |modeline| when the 'diff' option is
Bram Moolenaar110289e2019-05-23 15:38:06 +02003591 on or the 'modelineexpr' option is off.
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00003592
3593 It is not allowed to change text or jump to another window while
3594 evaluating 'foldexpr' |textlock|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003595
3596 *'foldignore'* *'fdi'*
3597'foldignore' 'fdi' string (default: "#")
3598 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003599 {not available when compiled without the |+folding|
3600 feature}
3601 Used only when 'foldmethod' is "indent". Lines starting with
3602 characters in 'foldignore' will get their fold level from surrounding
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003603 lines. White space is skipped before checking for this character.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003604 The default "#" works well for C programs. See |fold-indent|.
3605
3606 *'foldlevel'* *'fdl'*
3607'foldlevel' 'fdl' number (default: 0)
3608 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003609 {not available when compiled without the |+folding|
3610 feature}
3611 Sets the fold level: Folds with a higher level will be closed.
3612 Setting this option to zero will close all folds. Higher numbers will
3613 close fewer folds.
3614 This option is set by commands like |zm|, |zM| and |zR|.
3615 See |fold-foldlevel|.
3616
3617 *'foldlevelstart'* *'fdls'*
3618'foldlevelstart' 'fdls' number (default: -1)
3619 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003620 {not available when compiled without the |+folding|
3621 feature}
3622 Sets 'foldlevel' when starting to edit another buffer in a window.
3623 Useful to always start editing with all folds closed (value zero),
3624 some folds closed (one) or no folds closed (99).
3625 This is done before reading any modeline, thus a setting in a modeline
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00003626 overrules this option. Starting to edit a file for |diff-mode| also
Bram Moolenaar071d4272004-06-13 20:20:40 +00003627 ignores this option and closes all folds.
3628 It is also done before BufReadPre autocommands, to allow an autocmd to
3629 overrule the 'foldlevel' value for specific files.
3630 When the value is negative, it is not used.
3631
3632 *'foldmarker'* *'fmr'* *E536*
3633'foldmarker' 'fmr' string (default: "{{{,}}}")
3634 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003635 {not available when compiled without the |+folding|
3636 feature}
3637 The start and end marker used when 'foldmethod' is "marker". There
3638 must be one comma, which separates the start and end marker. The
3639 marker is a literal string (a regular expression would be too slow).
3640 See |fold-marker|.
3641
3642 *'foldmethod'* *'fdm'*
3643'foldmethod' 'fdm' string (default: "manual")
3644 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003645 {not available when compiled without the |+folding|
3646 feature}
3647 The kind of folding used for the current window. Possible values:
3648 |fold-manual| manual Folds are created manually.
3649 |fold-indent| indent Lines with equal indent form a fold.
3650 |fold-expr| expr 'foldexpr' gives the fold level of a line.
3651 |fold-marker| marker Markers are used to specify folds.
3652 |fold-syntax| syntax Syntax highlighting items specify folds.
3653 |fold-diff| diff Fold text that is not changed.
3654
3655 *'foldminlines'* *'fml'*
3656'foldminlines' 'fml' number (default: 1)
3657 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003658 {not available when compiled without the |+folding|
3659 feature}
Bram Moolenaar00654022011-02-25 14:42:19 +01003660 Sets the number of screen lines above which a fold can be displayed
3661 closed. Also for manually closed folds. With the default value of
3662 one a fold can only be closed if it takes up two or more screen lines.
3663 Set to zero to be able to close folds of just one screen line.
Bram Moolenaar446beb42011-05-10 17:18:44 +02003664 Note that this only has an effect on what is displayed. After using
Bram Moolenaar071d4272004-06-13 20:20:40 +00003665 "zc" to close a fold, which is displayed open because it's smaller
3666 than 'foldminlines', a following "zc" may close a containing fold.
3667
3668 *'foldnestmax'* *'fdn'*
3669'foldnestmax' 'fdn' number (default: 20)
3670 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003671 {not available when compiled without the |+folding|
3672 feature}
3673 Sets the maximum nesting of folds for the "indent" and "syntax"
3674 methods. This avoids that too many folds will be created. Using more
3675 than 20 doesn't work, because the internal limit is 20.
3676
3677 *'foldopen'* *'fdo'*
3678'foldopen' 'fdo' string (default: "block,hor,mark,percent,quickfix,
3679 search,tag,undo")
3680 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003681 {not available when compiled without the |+folding|
3682 feature}
3683 Specifies for which type of commands folds will be opened, if the
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01003684 command moves the cursor into a closed fold. It is a comma-separated
Bram Moolenaar071d4272004-06-13 20:20:40 +00003685 list of items.
Bram Moolenaar05365702010-10-27 18:34:44 +02003686 NOTE: When the command is part of a mapping this option is not used.
3687 Add the |zv| command to the mapping to get the same effect.
3688 (rationale: the mapping may want to control opening folds itself)
3689
Bram Moolenaar071d4272004-06-13 20:20:40 +00003690 item commands ~
3691 all any
3692 block "(", "{", "[[", "[{", etc.
3693 hor horizontal movements: "l", "w", "fx", etc.
3694 insert any command in Insert mode
3695 jump far jumps: "G", "gg", etc.
3696 mark jumping to a mark: "'m", CTRL-O, etc.
3697 percent "%"
3698 quickfix ":cn", ":crew", ":make", etc.
3699 search search for a pattern: "/", "n", "*", "gd", etc.
3700 (not for a search pattern in a ":" command)
Bram Moolenaar910f66f2006-04-05 20:41:53 +00003701 Also for |[s| and |]s|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003702 tag jumping to a tag: ":ta", CTRL-T, etc.
3703 undo undo or redo: "u" and CTRL-R
Bram Moolenaar071d4272004-06-13 20:20:40 +00003704 When a movement command is used for an operator (e.g., "dl" or "y%")
3705 this option is not used. This means the operator will include the
3706 whole closed fold.
3707 Note that vertical movements are not here, because it would make it
3708 very difficult to move onto a closed fold.
3709 In insert mode the folds containing the cursor will always be open
3710 when text is inserted.
3711 To close folds you can re-apply 'foldlevel' with the |zx| command or
3712 set the 'foldclose' option to "all".
3713
3714 *'foldtext'* *'fdt'*
3715'foldtext' 'fdt' string (default: "foldtext()")
3716 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00003717 {not available when compiled without the |+folding|
3718 feature}
3719 An expression which is used to specify the text displayed for a closed
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00003720 fold. The context is set to the script where 'foldexpr' was set,
3721 script-local items can be accessed. See |fold-foldtext| for the
3722 usage.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003723
Bram Moolenaar30b65812012-07-12 22:01:11 +02003724 The expression will be evaluated in the |sandbox| if set from a
3725 modeline, see |sandbox-option|.
Bram Moolenaar110289e2019-05-23 15:38:06 +02003726 This option cannot be set in a modeline when 'modelineexpr' is off.
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00003727
3728 It is not allowed to change text or jump to another window while
3729 evaluating 'foldtext' |textlock|.
3730
Bram Moolenaarc95a3022016-06-12 23:01:46 +02003731 *'formatexpr'* *'fex'*
3732'formatexpr' 'fex' string (default "")
3733 local to buffer
Bram Moolenaarc95a3022016-06-12 23:01:46 +02003734 {not available when compiled without the |+eval|
3735 feature}
3736 Expression which is evaluated to format a range of lines for the |gq|
3737 operator or automatic formatting (see 'formatoptions'). When this
3738 option is empty 'formatprg' is used.
3739
3740 The |v:lnum| variable holds the first line to be formatted.
3741 The |v:count| variable holds the number of lines to be formatted.
3742 The |v:char| variable holds the character that is going to be
3743 inserted if the expression is being evaluated due to
3744 automatic formatting. This can be empty. Don't insert
3745 it yet!
3746
3747 Example: >
3748 :set formatexpr=mylang#Format()
3749< This will invoke the mylang#Format() function in the
3750 autoload/mylang.vim file in 'runtimepath'. |autoload|
3751
Bram Moolenaara4e0b972022-10-01 19:43:52 +01003752 The advantage of using a function call without arguments is that it is
3753 faster, see |expr-option-function|.
3754
Bram Moolenaarc95a3022016-06-12 23:01:46 +02003755 The expression is also evaluated when 'textwidth' is set and adding
3756 text beyond that limit. This happens under the same conditions as
3757 when internal formatting is used. Make sure the cursor is kept in the
3758 same spot relative to the text then! The |mode()| function will
3759 return "i" or "R" in this situation.
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01003760
Bram Moolenaarc95a3022016-06-12 23:01:46 +02003761 When the expression evaluates to non-zero Vim will fall back to using
3762 the internal format mechanism.
3763
Yegappan Lakshmanan8bb65f22021-12-26 10:51:39 +00003764 If the expression starts with s: or |<SID>|, then it is replaced with
3765 the script ID (|local-function|). Example: >
3766 set formatexpr=s:MyFormatExpr()
3767 set formatexpr=<SID>SomeFormatExpr()
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00003768< Otherwise, the expression is evaluated in the context of the script
3769 where the option was set, thus script-local items are available.
3770
Bram Moolenaarc95a3022016-06-12 23:01:46 +02003771 The expression will be evaluated in the |sandbox| when set from a
3772 modeline, see |sandbox-option|. That stops the option from working,
3773 since changing the buffer text is not allowed.
Bram Moolenaar110289e2019-05-23 15:38:06 +02003774 This option cannot be set in a modeline when 'modelineexpr' is off.
Bram Moolenaar036986f2017-03-16 17:41:02 +01003775 NOTE: This option is set to "" when 'compatible' is set.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02003776
Bram Moolenaar86b68352004-12-27 21:59:20 +00003777 *'formatlistpat'* *'flp'*
3778'formatlistpat' 'flp' string (default: "^\s*\d\+[\]:.)}\t ]\s*")
3779 local to buffer
Bram Moolenaar86b68352004-12-27 21:59:20 +00003780 A pattern that is used to recognize a list header. This is used for
3781 the "n" flag in 'formatoptions'.
3782 The pattern must match exactly the text that will be the indent for
Bram Moolenaar677ee682005-01-27 14:41:15 +00003783 the line below it. You can use |/\ze| to mark the end of the match
Bram Moolenaar86b68352004-12-27 21:59:20 +00003784 while still checking more characters. There must be a character
3785 following the pattern, when it matches the whole line it is handled
3786 like there is no match.
3787 The default recognizes a number, followed by an optional punctuation
3788 character and white space.
3789
Bram Moolenaar6c60f472019-04-28 16:00:35 +02003790 *'formatoptions'* *'fo'*
3791'formatoptions' 'fo' string (Vim default: "tcq", Vi default: "vt")
3792 local to buffer
3793 This is a sequence of letters which describes how automatic
Christian Brabandt1b08d2c2023-11-11 15:50:13 +01003794 formatting is to be done.
3795 See |fo-table| for possible values and |gq| for how to format text.
3796 When the 'paste' option is on, no formatting is done (like
3797 'formatoptions' is empty). Commas can be inserted for readability.
Bram Moolenaar6c60f472019-04-28 16:00:35 +02003798 To avoid problems with flags that are added in the future, use the
3799 "+=" and "-=" feature of ":set" |add-option-flags|.
3800 NOTE: This option is set to the Vi default value when 'compatible' is
3801 set and to the Vim default value when 'compatible' is reset.
3802
Bram Moolenaar071d4272004-06-13 20:20:40 +00003803 *'formatprg'* *'fp'*
3804'formatprg' 'fp' string (default "")
Bram Moolenaar9be7c042017-01-14 14:28:30 +01003805 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00003806 The name of an external program that will be used to format the lines
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00003807 selected with the |gq| operator. The program must take the input on
Bram Moolenaar071d4272004-06-13 20:20:40 +00003808 stdin and produce the output on stdout. The Unix program "fmt" is
Bram Moolenaara5792f52005-11-23 21:25:05 +00003809 such a program.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00003810 If the 'formatexpr' option is not empty it will be used instead.
3811 Otherwise, if 'formatprg' option is an empty string, the internal
3812 format function will be used |C-indenting|.
Bram Moolenaara5792f52005-11-23 21:25:05 +00003813 Environment variables are expanded |:set_env|. See |option-backslash|
3814 about including spaces and backslashes.
Bram Moolenaar30b65812012-07-12 22:01:11 +02003815 This option cannot be set from a |modeline| or in the |sandbox|, for
3816 security reasons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003817
Bram Moolenaard94464e2015-11-02 15:28:18 +01003818 *'fsync'* *'fs'* *'nofsync'* *'nofs'*
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00003819'fsync' 'fs' boolean (default on)
3820 global
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00003821 When on, the library function fsync() will be called after writing a
3822 file. This will flush a file to disk, ensuring that it is safely
3823 written even on filesystems which do metadata-only journaling. This
3824 will force the harddrive to spin up on Linux systems running in laptop
3825 mode, so it may be undesirable in some situations. Be warned that
3826 turning this off increases the chances of data loss after a crash. On
3827 systems without an fsync() implementation, this variable is always
3828 off.
3829 Also see 'swapsync' for controlling fsync() on swap files.
Bram Moolenaar340dd0f2021-10-14 17:52:23 +01003830 'fsync' also applies to |writefile()| (unless a flag is used to
3831 overrule it) and when writing undo files (see |undo-persistence|).
Bram Moolenaar110289e2019-05-23 15:38:06 +02003832 This option cannot be set from a |modeline| or in the |sandbox|, for
3833 security reasons.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00003834
Bram Moolenaar071d4272004-06-13 20:20:40 +00003835 *'gdefault'* *'gd'* *'nogdefault'* *'nogd'*
3836'gdefault' 'gd' boolean (default off)
3837 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003838 When on, the ":substitute" flag 'g' is default on. This means that
3839 all matches in a line are substituted instead of one. When a 'g' flag
3840 is given to a ":substitute" command, this will toggle the substitution
3841 of all or one match. See |complex-change|.
3842
3843 command 'gdefault' on 'gdefault' off ~
3844 :s/// subst. all subst. one
3845 :s///g subst. one subst. all
3846 :s///gg subst. all subst. one
3847
3848 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaar21020352017-06-13 17:21:04 +02003849 DEPRECATED: Setting this option may break plugins that are not aware
3850 of this option. Also, many users get confused that adding the /g flag
3851 has the opposite effect of that it normally does.
Bram Moolenaar4072ba52020-12-23 13:56:35 +01003852 This option is not used in |Vim9| script.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003853
3854 *'grepformat'* *'gfm'*
Bram Moolenaar6e932462014-09-09 18:48:09 +02003855'grepformat' 'gfm' string (default "%f:%l:%m,%f:%l%m,%f %l%m")
Bram Moolenaar071d4272004-06-13 20:20:40 +00003856 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003857 Format to recognize for the ":grep" command output.
3858 This is a scanf-like string that uses the same format as the
3859 'errorformat' option: see |errorformat|.
3860
3861 *'grepprg'* *'gp'*
3862'grepprg' 'gp' string (default "grep -n ",
3863 Unix: "grep -n $* /dev/null",
3864 Win32: "findstr /n" or "grep -n",
3865 VMS: "SEARCH/NUMBERS ")
3866 global or local to buffer |global-local|
Bram Moolenaar582fd852005-03-28 20:58:01 +00003867 Program to use for the |:grep| command. This option may contain '%'
Bram Moolenaar071d4272004-06-13 20:20:40 +00003868 and '#' characters, which are expanded like when used in a command-
3869 line. The placeholder "$*" is allowed to specify where the arguments
3870 will be included. Environment variables are expanded |:set_env|. See
3871 |option-backslash| about including spaces and backslashes.
3872 When your "grep" accepts the "-H" argument, use this to make ":grep"
3873 also work well with a single file: >
3874 :set grepprg=grep\ -nH
Bram Moolenaar7c626922005-02-07 22:01:03 +00003875< Special value: When 'grepprg' is set to "internal" the |:grep| command
Bram Moolenaara6557602006-02-04 22:43:20 +00003876 works like |:vimgrep|, |:lgrep| like |:lvimgrep|, |:grepadd| like
3877 |:vimgrepadd| and |:lgrepadd| like |:lvimgrepadd|.
Bram Moolenaar86b68352004-12-27 21:59:20 +00003878 See also the section |:make_makeprg|, since most of the comments there
Bram Moolenaar071d4272004-06-13 20:20:40 +00003879 apply equally to 'grepprg'.
3880 For Win32, the default is "findstr /n" if "findstr.exe" can be found,
3881 otherwise it's "grep -n".
3882 This option cannot be set from a |modeline| or in the |sandbox|, for
3883 security reasons.
3884
3885 *'guicursor'* *'gcr'* *E545* *E546* *E548* *E549*
3886'guicursor' 'gcr' string (default "n-v-c:block-Cursor/lCursor,
3887 ve:ver35-Cursor,
3888 o:hor50-Cursor,
3889 i-ci:ver25-Cursor/lCursor,
3890 r-cr:hor20-Cursor/lCursor,
3891 sm:block-Cursor
3892 -blinkwait175-blinkoff150-blinkon175",
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01003893 for Win32 console:
Bram Moolenaar071d4272004-06-13 20:20:40 +00003894 "n-v-c:block,o:hor50,i-ci:hor15,
3895 r-cr:hor30,sm:block")
3896 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003897 {only available when compiled with GUI enabled, and
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01003898 for Win32 console}
Bram Moolenaar071d4272004-06-13 20:20:40 +00003899 This option tells Vim what the cursor should look like in different
Bram Moolenaar8024f932020-01-14 19:29:13 +01003900 modes. It fully works in the GUI. In a Win32 console, only the
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01003901 height of the cursor can be changed. This can be done by specifying a
3902 block cursor, or a percentage for a vertical or horizontal cursor.
Bram Moolenaar1e7813a2015-03-31 18:31:03 +02003903 For a console the 't_SI', 't_SR', and 't_EI' escape sequences are
3904 used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003905
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01003906 The option is a comma-separated list of parts. Each part consist of a
Bram Moolenaar071d4272004-06-13 20:20:40 +00003907 mode-list and an argument-list:
3908 mode-list:argument-list,mode-list:argument-list,..
3909 The mode-list is a dash separated list of these modes:
3910 n Normal mode
3911 v Visual mode
3912 ve Visual mode with 'selection' "exclusive" (same as 'v',
3913 if not specified)
3914 o Operator-pending mode
3915 i Insert mode
3916 r Replace mode
3917 c Command-line Normal (append) mode
3918 ci Command-line Insert mode
3919 cr Command-line Replace mode
3920 sm showmatch in Insert mode
3921 a all modes
3922 The argument-list is a dash separated list of these arguments:
3923 hor{N} horizontal bar, {N} percent of the character height
3924 ver{N} vertical bar, {N} percent of the character width
3925 block block cursor, fills the whole character
3926 [only one of the above three should be present]
3927 blinkwait{N} *cursor-blinking*
3928 blinkon{N}
3929 blinkoff{N}
3930 blink times for cursor: blinkwait is the delay before
3931 the cursor starts blinking, blinkon is the time that
3932 the cursor is shown and blinkoff is the time that the
3933 cursor is not shown. The times are in msec. When one
3934 of the numbers is zero, there is no blinking. The
3935 default is: "blinkwait700-blinkon400-blinkoff250".
3936 These numbers are used for a missing entry. This
3937 means that blinking is enabled by default. To switch
3938 blinking off you can use "blinkon0". The cursor only
3939 blinks when Vim is waiting for input, not while
3940 executing a command.
3941 To make the cursor blink in an xterm, see
3942 |xterm-blink|.
3943 {group-name}
3944 a highlight group name, that sets the color and font
3945 for the cursor
3946 {group-name}/{group-name}
3947 Two highlight group names, the first is used when
3948 no language mappings are used, the other when they
3949 are. |language-mapping|
3950
3951 Examples of parts:
3952 n-c-v:block-nCursor in Normal, Command-line and Visual mode, use a
3953 block cursor with colors from the "nCursor"
3954 highlight group
3955 i-ci:ver30-iCursor-blinkwait300-blinkon200-blinkoff150
3956 In Insert and Command-line Insert mode, use a
3957 30% vertical bar cursor with colors from the
3958 "iCursor" highlight group. Blink a bit
3959 faster.
3960
3961 The 'a' mode is different. It will set the given argument-list for
3962 all modes. It does not reset anything to defaults. This can be used
3963 to do a common setting for all modes. For example, to switch off
3964 blinking: "a:blinkon0"
3965
3966 Examples of cursor highlighting: >
3967 :highlight Cursor gui=reverse guifg=NONE guibg=NONE
3968 :highlight Cursor gui=NONE guifg=bg guibg=fg
3969<
3970 *'guifont'* *'gfn'*
Bram Moolenaar251e1912011-06-19 05:09:16 +02003971 *E235* *E596*
Bram Moolenaar071d4272004-06-13 20:20:40 +00003972'guifont' 'gfn' string (default "")
3973 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003974 {only available when compiled with GUI enabled}
3975 This is a list of fonts which will be used for the GUI version of Vim.
Bram Moolenaarf720d0a2019-04-28 14:02:47 +02003976 In its simplest form the value is just one font name.
3977 See |gui-font| for the details.
Bram Moolenaar071d4272004-06-13 20:20:40 +00003978
3979 *'guifontset'* *'gfs'*
3980 *E250* *E252* *E234* *E597* *E598*
3981'guifontset' 'gfs' string (default "")
3982 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003983 {only available when compiled with GUI enabled and
3984 with the |+xfontset| feature}
Bram Moolenaar3df01732017-02-17 22:47:16 +01003985 {not available in the GTK+ GUI}
Bram Moolenaar071d4272004-06-13 20:20:40 +00003986 When not empty, specifies two (or more) fonts to be used. The first
3987 one for normal English, the second one for your special language. See
3988 |xfontset|.
Bram Moolenaarf720d0a2019-04-28 14:02:47 +02003989
Bram Moolenaar071d4272004-06-13 20:20:40 +00003990 *'guifontwide'* *'gfw'* *E231* *E533* *E534*
3991'guifontwide' 'gfw' string (default "")
3992 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00003993 {only available when compiled with GUI enabled}
3994 When not empty, specifies a comma-separated list of fonts to be used
3995 for double-width characters. The first font that can be loaded is
Bram Moolenaarf720d0a2019-04-28 14:02:47 +02003996 used. See |gui-fontwide|.
Bram Moolenaar0f272122013-01-23 18:37:40 +01003997
Bram Moolenaar071d4272004-06-13 20:20:40 +00003998 *'guiheadroom'* *'ghr'*
3999'guiheadroom' 'ghr' number (default 50)
4000 global
Bram Moolenaar110289e2019-05-23 15:38:06 +02004001 {only for GTK and X11 GUI}
Bram Moolenaar071d4272004-06-13 20:20:40 +00004002 The number of pixels subtracted from the screen height when fitting
4003 the GUI window on the screen. Set this before the GUI is started,
4004 e.g., in your |gvimrc| file. When zero, the whole screen height will
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004005 be used by the window. When positive, the specified number of pixel
Bram Moolenaar071d4272004-06-13 20:20:40 +00004006 lines will be left for window decorations and other items on the
4007 screen. Set it to a negative value to allow windows taller than the
4008 screen.
4009
Dusan Popovic4eeedc02021-10-16 20:52:05 +01004010 *'guiligatures'* *'gli'* *E1243*
4011'guiligatures' 'gli' string (default "")
4012 global
4013 {only for GTK GUI}
4014 List of ASCII characters that, when combined together, can create more
4015 complex shapes. Each character must be a printable ASCII character
4016 with a value in the 32-127 range.
4017 Example: >
4018 :set guiligatures=!\"#$%&()*+-./:<=>?@[]^_{\|~
4019< Changing this option updates screen output immediately. Set it to an
4020 empty string to disable ligatures.
4021
Bram Moolenaar071d4272004-06-13 20:20:40 +00004022 *'guioptions'* *'go'*
Bram Moolenaar2c64ca12018-10-19 16:22:31 +02004023'guioptions' 'go' string (default "egmrLtT" (MS-Windows,
4024 "t" is removed in |defaults.vim|),
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01004025 "aegimrLtT" (GTK and Motif),
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +02004026 )
Bram Moolenaar071d4272004-06-13 20:20:40 +00004027 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004028 {only available when compiled with GUI enabled}
Bram Moolenaared203462004-06-16 11:19:22 +00004029 This option only has an effect in the GUI version of Vim. It is a
Bram Moolenaar071d4272004-06-13 20:20:40 +00004030 sequence of letters which describes what components and options of the
4031 GUI should be used.
4032 To avoid problems with flags that are added in the future, use the
4033 "+=" and "-=" feature of ":set" |add-option-flags|.
4034
Bram Moolenaar13568252018-03-16 20:46:58 +01004035 Valid characters are as follows:
4036 *'go-!'*
4037 '!' External commands are executed in a terminal window. Without
4038 this flag the MS-Windows GUI will open a console window to
4039 execute the command. The Unix GUI will simulate a dumb
4040 terminal to list the command output.
4041 The terminal window will be positioned at the bottom, and grow
4042 upwards as needed.
Bram Moolenaarba3ff532018-11-04 14:45:49 +01004043 *'go-a'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004044 'a' Autoselect: If present, then whenever VISUAL mode is started,
4045 or the Visual area extended, Vim tries to become the owner of
4046 the windowing system's global selection. This means that the
4047 Visually highlighted text is available for pasting into other
4048 applications as well as into Vim itself. When the Visual mode
4049 ends, possibly due to an operation on the text, or when an
4050 application wants to paste the selection, the highlighted text
4051 is automatically yanked into the "* selection register.
4052 Thus the selection is still available for pasting into other
4053 applications after the VISUAL mode has ended.
4054 If not present, then Vim won't become the owner of the
4055 windowing system's global selection unless explicitly told to
4056 by a yank or delete operation for the "* register.
4057 The same applies to the modeless selection.
Bram Moolenaarc0885aa2012-07-10 16:49:23 +02004058 *'go-P'*
4059 'P' Like autoselect but using the "+ register instead of the "*
Bram Moolenaar3848e002016-03-19 18:42:29 +01004060 register.
Bram Moolenaar02467872007-05-06 13:22:01 +00004061 *'go-A'*
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004062 'A' Autoselect for the modeless selection. Like 'a', but only
Bram Moolenaar071d4272004-06-13 20:20:40 +00004063 applies to the modeless selection.
4064
4065 'guioptions' autoselect Visual autoselect modeless ~
4066 "" - -
4067 "a" yes yes
4068 "A" - yes
4069 "aA" yes yes
4070
Bram Moolenaar9fbdbb82022-09-27 17:30:34 +01004071 When using a terminal see the 'clipboard' option.
4072
Bram Moolenaar02467872007-05-06 13:22:01 +00004073 *'go-c'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004074 'c' Use console dialogs instead of popup dialogs for simple
4075 choices.
Bram Moolenaar50bf7ce2019-09-15 13:17:00 +02004076 *'go-d'*
4077 'd' Use dark theme variant if available. Currently only works for
4078 GTK+ GUI.
Bram Moolenaar02467872007-05-06 13:22:01 +00004079 *'go-e'*
Bram Moolenaare224ffa2006-03-01 00:01:28 +00004080 'e' Add tab pages when indicated with 'showtabline'.
Bram Moolenaar5c8837f2006-02-25 21:52:33 +00004081 'guitablabel' can be used to change the text in the labels.
4082 When 'e' is missing a non-GUI tab pages line may be used.
Bram Moolenaard68071d2006-05-02 22:08:30 +00004083 The GUI tabs are only supported on some systems, currently
Bram Moolenaarb3f74062020-02-26 16:16:53 +01004084 GTK, Motif, Mac OS/X, Haiku, and MS-Windows.
Bram Moolenaar02467872007-05-06 13:22:01 +00004085 *'go-f'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004086 'f' Foreground: Don't use fork() to detach the GUI from the shell
4087 where it was started. Use this for programs that wait for the
4088 editor to finish (e.g., an e-mail program). Alternatively you
4089 can use "gvim -f" or ":gui -f" to start the GUI in the
4090 foreground. |gui-fork|
4091 Note: Set this option in the vimrc file. The forking may have
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004092 happened already when the |gvimrc| file is read.
Bram Moolenaar02467872007-05-06 13:22:01 +00004093 *'go-i'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004094 'i' Use a Vim icon. For GTK with KDE it is used in the left-upper
4095 corner of the window. It's black&white on non-GTK, because of
4096 limitations of X11. For a color icon, see |X11-icon|.
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02004097 *'go-m'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004098 'm' Menu bar is present.
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02004099 *'go-M'*
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004100 'M' The system menu "$VIMRUNTIME/menu.vim" is not sourced. Note
Bram Moolenaar071d4272004-06-13 20:20:40 +00004101 that this flag must be added in the .vimrc file, before
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004102 switching on syntax or filetype recognition (when the |gvimrc|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004103 file is sourced the system menu has already been loaded; the
Bram Moolenaar01164a62017-11-02 22:58:42 +01004104 `:syntax on` and `:filetype on` commands load the menu too).
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02004105 *'go-g'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004106 'g' Grey menu items: Make menu items that are not active grey. If
4107 'g' is not included inactive menu items are not shown at all.
Bram Moolenaar02467872007-05-06 13:22:01 +00004108 *'go-t'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004109 't' Include tearoff menu items. Currently only works for Win32,
4110 GTK+, and Motif 1.2 GUI.
Bram Moolenaar02467872007-05-06 13:22:01 +00004111 *'go-T'*
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01004112 'T' Include Toolbar. Currently only in Win32, GTK+, Motif and
4113 Photon GUIs.
Bram Moolenaar02467872007-05-06 13:22:01 +00004114 *'go-r'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004115 'r' Right-hand scrollbar is always present.
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02004116 *'go-R'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004117 'R' Right-hand scrollbar is present when there is a vertically
4118 split window.
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02004119 *'go-l'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004120 'l' Left-hand scrollbar is always present.
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02004121 *'go-L'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004122 'L' Left-hand scrollbar is present when there is a vertically
4123 split window.
Bram Moolenaar02467872007-05-06 13:22:01 +00004124 *'go-b'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004125 'b' Bottom (horizontal) scrollbar is present. Its size depends on
4126 the longest visible line, or on the cursor line if the 'h'
4127 flag is included. |gui-horiz-scroll|
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02004128 *'go-h'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004129 'h' Limit horizontal scrollbar size to the length of the cursor
4130 line. Reduces computations. |gui-horiz-scroll|
4131
4132 And yes, you may even have scrollbars on the left AND the right if
4133 you really want to :-). See |gui-scrollbars| for more information.
4134
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02004135 *'go-v'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004136 'v' Use a vertical button layout for dialogs. When not included,
4137 a horizontal layout is preferred, but when it doesn't fit a
Bram Moolenaardad44732021-03-31 20:07:33 +02004138 vertical layout is used anyway. Not supported in GTK 3.
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02004139 *'go-p'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004140 'p' Use Pointer callbacks for X11 GUI. This is required for some
4141 window managers. If the cursor is not blinking or hollow at
4142 the right moment, try adding this flag. This must be done
Bram Moolenaar910f66f2006-04-05 20:41:53 +00004143 before starting the GUI. Set it in your |gvimrc|. Adding or
Bram Moolenaar071d4272004-06-13 20:20:40 +00004144 removing it after the GUI has started has no effect.
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02004145 *'go-F'*
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004146 'F' Add a footer. Only for Motif. See |gui-footer|.
Bram Moolenaar8ac44152017-11-09 18:33:29 +01004147 *'go-k'*
4148 'k' Keep the GUI window size when adding/removing a scrollbar, or
4149 toolbar, tabline, etc. Instead, the behavior is similar to
4150 when the window is maximized and will adjust 'lines' and
4151 'columns' to fit to the window. Without the 'k' flag Vim will
Bram Moolenaar51b0f372017-11-18 18:52:04 +01004152 try to keep 'lines' and 'columns' the same when adding and
Bram Moolenaar8ac44152017-11-09 18:33:29 +01004153 removing GUI components.
Bram Moolenaar02467872007-05-06 13:22:01 +00004154
Bram Moolenaar071d4272004-06-13 20:20:40 +00004155 *'guipty'* *'noguipty'*
4156'guipty' boolean (default on)
4157 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004158 {only available when compiled with GUI enabled}
4159 Only in the GUI: If on, an attempt is made to open a pseudo-tty for
4160 I/O to/from shell commands. See |gui-pty|.
4161
Bram Moolenaar5c8837f2006-02-25 21:52:33 +00004162 *'guitablabel'* *'gtl'*
4163'guitablabel' 'gtl' string (default empty)
4164 global
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02004165 {only available when compiled with GUI enabled}
Bram Moolenaar944697a2022-02-20 19:48:20 +00004166 When non-empty describes the text to use in a label of the GUI tab
Bram Moolenaard68071d2006-05-02 22:08:30 +00004167 pages line. When empty and when the result is empty Vim will use a
4168 default label. See |setting-guitablabel| for more info.
Bram Moolenaar5c8837f2006-02-25 21:52:33 +00004169
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004170 The format of this option is like that of 'statusline'.
Bram Moolenaar57657d82006-04-21 22:12:41 +00004171 'guitabtooltip' is used for the tooltip, see below.
Bram Moolenaar51628222016-12-01 23:03:28 +01004172 The expression will be evaluated in the |sandbox| when set from a
4173 modeline, see |sandbox-option|.
Bram Moolenaar110289e2019-05-23 15:38:06 +02004174 This option cannot be set in a modeline when 'modelineexpr' is off.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00004175
Bram Moolenaar5c8837f2006-02-25 21:52:33 +00004176 Only used when the GUI tab pages line is displayed. 'e' must be
4177 present in 'guioptions'. For the non-GUI tab pages line 'tabline' is
4178 used.
4179
Bram Moolenaar57657d82006-04-21 22:12:41 +00004180 *'guitabtooltip'* *'gtt'*
4181'guitabtooltip' 'gtt' string (default empty)
4182 global
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02004183 {only available when compiled with GUI enabled}
Bram Moolenaar944697a2022-02-20 19:48:20 +00004184 When non-empty describes the text to use in a tooltip for the GUI tab
Bram Moolenaar57657d82006-04-21 22:12:41 +00004185 pages line. When empty Vim will use a default tooltip.
4186 This option is otherwise just like 'guitablabel' above.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004187 You can include a line break. Simplest method is to use |:let|: >
4188 :let &guitabtooltip = "line one\nline two"
4189<
Bram Moolenaar57657d82006-04-21 22:12:41 +00004190
Bram Moolenaar071d4272004-06-13 20:20:40 +00004191 *'helpfile'* *'hf'*
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01004192'helpfile' 'hf' string (default (MS-Windows) "$VIMRUNTIME\doc\help.txt"
Bram Moolenaar071d4272004-06-13 20:20:40 +00004193 (others) "$VIMRUNTIME/doc/help.txt")
4194 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004195 Name of the main help file. All distributed help files should be
4196 placed together in one directory. Additionally, all "doc" directories
4197 in 'runtimepath' will be used.
4198 Environment variables are expanded |:set_env|. For example:
4199 "$VIMRUNTIME/doc/help.txt". If $VIMRUNTIME is not set, $VIM is also
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004200 tried. Also see |$VIMRUNTIME| and |option-backslash| about including
Bram Moolenaar071d4272004-06-13 20:20:40 +00004201 spaces and backslashes.
4202 This option cannot be set from a |modeline| or in the |sandbox|, for
4203 security reasons.
4204
4205 *'helpheight'* *'hh'*
4206'helpheight' 'hh' number (default 20)
4207 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004208 Minimal initial height of the help window when it is opened with the
4209 ":help" command. The initial height of the help window is half of the
4210 current window, or (when the 'ea' option is on) the same as other
4211 windows. When the height is less than 'helpheight', the height is
4212 set to 'helpheight'. Set to zero to disable.
4213
4214 *'helplang'* *'hlg'*
4215'helplang' 'hlg' string (default: messages language or empty)
4216 global
4217 {only available when compiled with the |+multi_lang|
4218 feature}
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01004219 Comma-separated list of languages. Vim will use the first language
Bram Moolenaar071d4272004-06-13 20:20:40 +00004220 for which the desired help can be found. The English help will always
4221 be used as a last resort. You can add "en" to prefer English over
4222 another language, but that will only find tags that exist in that
4223 language and not in the English help.
4224 Example: >
4225 :set helplang=de,it
4226< This will first search German, then Italian and finally English help
4227 files.
4228 When using |CTRL-]| and ":help!" in a non-English help file Vim will
4229 try to find the tag in the current language before using this option.
4230 See |help-translated|.
4231
4232 *'hidden'* *'hid'* *'nohidden'* *'nohid'*
4233'hidden' 'hid' boolean (default off)
4234 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004235 When off a buffer is unloaded when it is |abandon|ed. When on a
4236 buffer becomes hidden when it is |abandon|ed. If the buffer is still
4237 displayed in another window, it does not become hidden, of course.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01004238
Bram Moolenaar071d4272004-06-13 20:20:40 +00004239 The commands that move through the buffer list sometimes make a buffer
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01004240 hidden even if the 'hidden' option is off when these three are true:
4241 - the buffer is modified
4242 - 'autowrite' is off or writing is not possible
4243 - the '!' flag was used
4244 Also see |windows.txt|.
4245
Bram Moolenaarcfbc5ee2004-07-02 15:38:35 +00004246 To only make one buffer hidden use the 'bufhidden' option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004247 This option is set for one command with ":hide {command}" |:hide|.
4248 WARNING: It's easy to forget that you have changes in hidden buffers.
4249 Think twice when using ":q!" or ":qa!".
4250
4251 *'highlight'* *'hl'*
4252'highlight' 'hl' string (default (as a single string):
Bram Moolenaar58b85342016-08-14 19:54:54 +02004253 "8:SpecialKey,~:EndOfBuffer,@:NonText,
4254 d:Directory,e:ErrorMsg,i:IncSearch,
4255 l:Search,m:MoreMsg,M:ModeMsg,n:LineNr,
Bram Moolenaarefae76a2019-10-27 22:54:58 +01004256 a:LineNrAbove,b:LineNrBelow,
Bram Moolenaar58b85342016-08-14 19:54:54 +02004257 N:CursorLineNr,r:Question,s:StatusLine,
4258 S:StatusLineNC,c:VertSplit,t:Title,
Bram Moolenaar9d87a372018-12-18 21:41:50 +01004259 v:Visual,V:VisualNOS,w:WarningMsg,
4260 W:WildMenu,f:Folded,F:FoldColumn,
4261 A:DiffAdd,C:DiffChange,D:DiffDelete,
4262 T:DiffText,>:SignColumn,-:Conceal,
Bram Moolenaarc8c88492018-12-27 23:59:26 +01004263 B:SpellBad,P:SpellCap,R:SpellRare,
Bram Moolenaar9d87a372018-12-18 21:41:50 +01004264 L:SpellLocal,+:Pmenu,=:PmenuSel,
Gianmaria Bajo6a7c7742023-03-10 16:35:53 +00004265 [:PmenuKind,]:PmenuKindSel,
4266 {:PmenuExtra,}:PmenuExtraSel,
Bram Moolenaar21020352017-06-13 17:21:04 +02004267 x:PmenuSbar,X:PmenuThumb,*:TabLine,
4268 #:TabLineSel,_:TabLineFill,!:CursorColumn,
Bram Moolenaarf55e4c82017-08-01 20:44:53 +02004269 .:CursorLine,o:ColorColumn,q:QuickFixLine,
Bram Moolenaarc572da52017-08-27 16:52:01 +02004270 z:StatusLineTerm,Z:StatusLineTermNC")
Bram Moolenaar071d4272004-06-13 20:20:40 +00004271 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004272 This option can be used to set highlighting mode for various
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01004273 occasions. It is a comma-separated list of character pairs. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00004274 first character in a pair gives the occasion, the second the mode to
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004275 use for that occasion. The occasions are:
Bram Moolenaar071d4272004-06-13 20:20:40 +00004276 |hl-SpecialKey| 8 Meta and special keys listed with ":map"
Bram Moolenaar58b85342016-08-14 19:54:54 +02004277 |hl-EndOfBuffer| ~ lines after the last line in the buffer
4278 |hl-NonText| @ '@' at the end of the window and
Bram Moolenaar071d4272004-06-13 20:20:40 +00004279 characters from 'showbreak'
4280 |hl-Directory| d directories in CTRL-D listing and other special
4281 things in listings
4282 |hl-ErrorMsg| e error messages
4283 h (obsolete, ignored)
4284 |hl-IncSearch| i 'incsearch' highlighting
LemonBoya4399382022-04-09 21:04:08 +01004285 |hl-CurSearch| y current instance of last search pattern
Bram Moolenaar071d4272004-06-13 20:20:40 +00004286 |hl-Search| l last search pattern highlighting (see 'hlsearch')
4287 |hl-MoreMsg| m |more-prompt|
4288 |hl-ModeMsg| M Mode (e.g., "-- INSERT --")
Bram Moolenaar64486672010-05-16 15:46:46 +02004289 |hl-LineNr| n line number for ":number" and ":#" commands, and
4290 when 'number' or 'relativenumber' option is set.
Bram Moolenaarefae76a2019-10-27 22:54:58 +01004291 |hl-LineNrAbove| a line number above the cursor for when the
4292 'relativenumber' option is set.
4293 |hl-LineNrBelow| b line number below the cursor for when the
4294 'relativenumber' option is set.
Bram Moolenaara3e6bc92013-01-30 14:18:00 +01004295 |hl-CursorLineNr| N like n for when 'cursorline' or 'relativenumber' is
4296 set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004297 |hl-Question| r |hit-enter| prompt and yes/no questions
4298 |hl-StatusLine| s status line of current window |status-line|
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01004299 |hl-StatusLineNC| S status lines of not-current windows
Bram Moolenaar071d4272004-06-13 20:20:40 +00004300 |hl-Title| t Titles for output from ":set all", ":autocmd" etc.
4301 |hl-VertSplit| c column used to separate vertically split windows
4302 |hl-Visual| v Visual mode
4303 |hl-VisualNOS| V Visual mode when Vim does is "Not Owning the
4304 Selection" Only X11 Gui's |gui-x11| and
4305 |xterm-clipboard|.
4306 |hl-WarningMsg| w warning messages
4307 |hl-WildMenu| W wildcard matches displayed for 'wildmenu'
4308 |hl-Folded| f line used for closed folds
4309 |hl-FoldColumn| F 'foldcolumn'
Bram Moolenaar0d9c26d2005-07-02 23:19:16 +00004310 |hl-DiffAdd| A added line in diff mode
4311 |hl-DiffChange| C changed line in diff mode
4312 |hl-DiffDelete| D deleted line in diff mode
4313 |hl-DiffText| T inserted text in diff mode
Bram Moolenaar071d4272004-06-13 20:20:40 +00004314 |hl-SignColumn| > column used for |signs|
Bram Moolenaar9d87a372018-12-18 21:41:50 +01004315 |hl-Conceal| - the placeholders used for concealed characters
4316 (see 'conceallevel')
Bram Moolenaar217ad922005-03-20 22:37:15 +00004317 |hl-SpellBad| B misspelled word |spell|
Bram Moolenaar9855d6b2010-07-18 14:34:51 +02004318 |hl-SpellCap| P word that should start with capital |spell|
Bram Moolenaar217ad922005-03-20 22:37:15 +00004319 |hl-SpellRare| R rare word |spell|
4320 |hl-SpellLocal| L word from other region |spell|
Bram Moolenaar9d87a372018-12-18 21:41:50 +01004321 |hl-Pmenu| + popup menu normal line
4322 |hl-PmenuSel| = popup menu selected line
Gianmaria Bajo6a7c7742023-03-10 16:35:53 +00004323 |hl-PmenuKind| [ popup menu "kind" normal line
4324 |hl-PmenuKindSel| ] popup menu "kind" selected line
h_east59858792023-10-25 22:47:05 +09004325 |hl-PmenuExtra| { popup menu "extra" normal line
4326 |hl-PmenuExtraSel| } popup menu "extra" selected line
Bram Moolenaar9d87a372018-12-18 21:41:50 +01004327 |hl-PmenuSbar| x popup menu scrollbar
4328 |hl-PmenuThumb| X popup menu scrollbar thumb
Bram Moolenaar071d4272004-06-13 20:20:40 +00004329
4330 The display modes are:
4331 r reverse (termcap entry "mr" and "me")
4332 i italic (termcap entry "ZH" and "ZR")
4333 b bold (termcap entry "md" and "me")
4334 s standout (termcap entry "so" and "se")
4335 u underline (termcap entry "us" and "ue")
Bram Moolenaar84f54632022-06-29 18:39:11 +01004336 c undercurl (termcap entry "Us" and "Ce")
4337 2 double underline (termcap entry "Ds" and "Ce")
4338 d dotted underline (termcap entry "ds" and "Ce")
4339 = dashed underline (termcap entry "Ds" and "Ce")
Bram Moolenaarcf4b00c2017-09-02 18:33:56 +02004340 t strikethrough (termcap entry "Ts" and "Te")
Bram Moolenaar071d4272004-06-13 20:20:40 +00004341 n no highlighting
4342 - no highlighting
4343 : use a highlight group
4344 The default is used for occasions that are not included.
4345 If you want to change what the display modes do, see |dos-colors|
4346 for an example.
4347 When using the ':' display mode, this must be followed by the name of
4348 a highlight group. A highlight group can be used to define any type
4349 of highlighting, including using color. See |:highlight| on how to
4350 define one. The default uses a different group for each occasion.
4351 See |highlight-default| for the default highlight groups.
4352
Bram Moolenaar071d4272004-06-13 20:20:40 +00004353 *'history'* *'hi'*
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +02004354'history' 'hi' number (Vim default: 50, Vi default: 0,
4355 set to 200 in |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004356 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004357 A history of ":" commands, and a history of previous search patterns
Bram Moolenaar78159bb2014-06-25 11:48:54 +02004358 is remembered. This option decides how many entries may be stored in
Bram Moolenaar071d4272004-06-13 20:20:40 +00004359 each of these histories (see |cmdline-editing|).
Bram Moolenaar78159bb2014-06-25 11:48:54 +02004360 The maximum value is 10000.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004361 NOTE: This option is set to the Vi default value when 'compatible' is
4362 set and to the Vim default value when 'compatible' is reset.
4363
4364 *'hkmap'* *'hk'* *'nohkmap'* *'nohk'*
4365'hkmap' 'hk' boolean (default off)
4366 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004367 {only available when compiled with the |+rightleft|
4368 feature}
4369 When on, the keyboard is mapped for the Hebrew character set.
4370 Normally you would set 'allowrevins' and use CTRL-_ in insert mode to
4371 toggle this option. See |rileft.txt|.
4372 NOTE: This option is reset when 'compatible' is set.
4373
4374 *'hkmapp'* *'hkp'* *'nohkmapp'* *'nohkp'*
4375'hkmapp' 'hkp' boolean (default off)
4376 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004377 {only available when compiled with the |+rightleft|
4378 feature}
4379 When on, phonetic keyboard mapping is used. 'hkmap' must also be on.
4380 This is useful if you have a non-Hebrew keyboard.
4381 See |rileft.txt|.
4382 NOTE: This option is reset when 'compatible' is set.
4383
Bram Moolenaar036986f2017-03-16 17:41:02 +01004384 *'hlsearch'* *'hls'* *'nohlsearch'* *'nohls'*
4385'hlsearch' 'hls' boolean (default off)
4386 global
Bram Moolenaar036986f2017-03-16 17:41:02 +01004387 {not available when compiled without the
4388 |+extra_search| feature}
4389 When there is a previous search pattern, highlight all its matches.
4390 The type of highlighting used can be set with the 'l' occasion in the
4391 'highlight' option. This uses the "Search" highlight group by
4392 default. Note that only the matching text is highlighted, any offsets
Bram Moolenaarcfa8f9a2022-06-03 21:59:47 +01004393 are not applied. If the "CurSearch" highlight group is set then the
4394 current match is highlighted with that.
Bram Moolenaar036986f2017-03-16 17:41:02 +01004395 See also: 'incsearch' and |:match|.
4396 When you get bored looking at the highlighted matches, you can turn it
4397 off with |:nohlsearch|. This does not change the option value, as
4398 soon as you use a search command, the highlighting comes back.
4399 'redrawtime' specifies the maximum time spent on finding matches.
4400 When the search pattern can match an end-of-line, Vim will try to
4401 highlight all of the matched text. However, this depends on where the
4402 search starts. This will be the first line in the window or the first
4403 line below a closed fold. A match in a previous line which is not
4404 drawn may not continue in a newly drawn line.
4405 You can specify whether the highlight status is restored on startup
4406 with the 'h' flag in 'viminfo' |viminfo-h|.
4407 NOTE: This option is reset when 'compatible' is set.
4408
Bram Moolenaar071d4272004-06-13 20:20:40 +00004409 *'icon'* *'noicon'*
4410'icon' boolean (default off, on when title can be restored)
4411 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004412 When on, the icon text of the window will be set to the value of
4413 'iconstring' (if it is not empty), or to the name of the file
4414 currently being edited. Only the last part of the name is used.
4415 Overridden by the 'iconstring' option.
4416 Only works if the terminal supports setting window icons (currently
4417 only X11 GUI and terminals with a non-empty 't_IS' option - these are
4418 Unix xterm and iris-ansi by default, where 't_IS' is taken from the
4419 builtin termcap).
4420 When Vim was compiled with HAVE_X11 defined, the original icon will be
Bram Moolenaar582fd852005-03-28 20:58:01 +00004421 restored if possible |X11|. See |X11-icon| for changing the icon on
Bram Moolenaar071d4272004-06-13 20:20:40 +00004422 X11.
Bram Moolenaar3a991dd2014-10-02 01:41:41 +02004423 For MS-Windows the icon can be changed, see |windows-icon|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004424
4425 *'iconstring'*
4426'iconstring' string (default "")
4427 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004428 When this option is not empty, it will be used for the icon text of
4429 the window. This happens only when the 'icon' option is on.
4430 Only works if the terminal supports setting window icon text
4431 (currently only X11 GUI and terminals with a non-empty 't_IS' option).
Bram Moolenaar130cbfc2021-04-07 21:07:20 +02004432 Does not work for MS-Windows.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004433 When Vim was compiled with HAVE_X11 defined, the original icon will be
4434 restored if possible |X11|.
4435 When this option contains printf-style '%' items, they will be
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004436 expanded according to the rules used for 'statusline'. See
Bram Moolenaar071d4272004-06-13 20:20:40 +00004437 'titlestring' for example settings.
Bram Moolenaar110289e2019-05-23 15:38:06 +02004438 This option cannot be set in a modeline when 'modelineexpr' is off.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004439 {not available when compiled without the |+statusline| feature}
4440
4441 *'ignorecase'* *'ic'* *'noignorecase'* *'noic'*
4442'ignorecase' 'ic' boolean (default off)
4443 global
Yee Cheng Chin2bbd0d32023-10-14 02:23:45 -07004444 Ignore case in search patterns, |cmdline-completion|, when
4445 searching in the tags file, and non-|Vim9| |expr-==|.
Bram Moolenaar0f6562e2015-11-24 18:48:14 +01004446 Also see 'smartcase' and 'tagcase'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004447 Can be overruled by using "\c" or "\C" in the pattern, see
4448 |/ignorecase|.
4449
Bram Moolenaarabab85a2013-06-26 19:18:05 +02004450 *'imactivatefunc'* *'imaf'*
4451'imactivatefunc' 'imaf' string (default "")
4452 global
Bram Moolenaarabab85a2013-06-26 19:18:05 +02004453 This option specifies a function that will be called to
Yegappan Lakshmanan7645da52021-12-04 14:02:30 +00004454 activate or deactivate the Input Method. The value can be the name of
4455 a function, a |lambda| or a |Funcref|. See |option-value-function| for
4456 more information.
Bram Moolenaaref8c6172020-07-01 15:12:44 +02004457 It is not used in the MS-Windows GUI version.
Bram Moolenaar110289e2019-05-23 15:38:06 +02004458 The expression will be evaluated in the |sandbox| when set from a
4459 modeline, see |sandbox-option|.
Bram Moolenaarabab85a2013-06-26 19:18:05 +02004460
4461 Example: >
4462 function ImActivateFunc(active)
4463 if a:active
4464 ... do something
4465 else
4466 ... do something
4467 endif
4468 " return value is not used
4469 endfunction
4470 set imactivatefunc=ImActivateFunc
4471<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004472 *'imactivatekey'* *'imak'*
4473'imactivatekey' 'imak' string (default "")
4474 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004475 {only available when compiled with |+xim| and
Bram Moolenaar67c53842010-05-22 18:28:27 +02004476 |+GUI_GTK|} *E599*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004477 Specifies the key that your Input Method in X-Windows uses for
4478 activation. When this is specified correctly, vim can fully control
4479 IM with 'imcmdline', 'iminsert' and 'imsearch'.
4480 You can't use this option to change the activation key, the option
4481 tells Vim what the key is.
4482 Format:
4483 [MODIFIER_FLAG-]KEY_STRING
4484
4485 These characters can be used for MODIFIER_FLAG (case is ignored):
4486 S Shift key
4487 L Lock key
4488 C Control key
4489 1 Mod1 key
4490 2 Mod2 key
4491 3 Mod3 key
4492 4 Mod4 key
4493 5 Mod5 key
4494 Combinations are allowed, for example "S-C-space" or "SC-space" are
4495 both shift+ctrl+space.
4496 See <X11/keysymdef.h> and XStringToKeysym for KEY_STRING.
4497
4498 Example: >
4499 :set imactivatekey=S-space
4500< "S-space" means shift+space. This is the activation key for kinput2 +
4501 canna (Japanese), and ami (Korean).
4502
4503 *'imcmdline'* *'imc'* *'noimcmdline'* *'noimc'*
4504'imcmdline' 'imc' boolean (default off)
4505 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004506 When set the Input Method is always on when starting to edit a command
4507 line, unless entering a search pattern (see 'imsearch' for that).
4508 Setting this option is useful when your input method allows entering
4509 English characters directly, e.g., when it's used to type accented
4510 characters with dead keys.
4511
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004512 *'imdisable'* *'imd'* *'noimdisable'* *'noimd'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00004513'imdisable' 'imd' boolean (default off, on for some systems (SGI))
4514 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004515 When set the Input Method is never used. This is useful to disable
4516 the IM when it doesn't work properly.
4517 Currently this option is on by default for SGI/IRIX machines. This
4518 may change in later releases.
4519
4520 *'iminsert'* *'imi'*
Bram Moolenaar4cf56bb2017-09-16 15:50:32 +02004521'iminsert' 'imi' number (default 0)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004522 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00004523 Specifies whether :lmap or an Input Method (IM) is to be used in
4524 Insert mode. Valid values:
4525 0 :lmap is off and IM is off
4526 1 :lmap is ON and IM is off
4527 2 :lmap is off and IM is ON
Bram Moolenaar071d4272004-06-13 20:20:40 +00004528 To always reset the option to zero when leaving Insert mode with <Esc>
4529 this can be used: >
4530 :inoremap <ESC> <ESC>:set iminsert=0<CR>
4531< This makes :lmap and IM turn off automatically when leaving Insert
4532 mode.
4533 Note that this option changes when using CTRL-^ in Insert mode
4534 |i_CTRL-^|.
4535 The value is set to 1 when setting 'keymap' to a valid keymap name.
4536 It is also used for the argument of commands like "r" and "f".
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01004537 The value 0 may not work correctly with Motif with some XIM
Bram Moolenaar071d4272004-06-13 20:20:40 +00004538 methods. Use 'imdisable' to disable XIM then.
4539
Bram Moolenaar6315a9a2017-11-25 15:20:02 +01004540 You can set 'imactivatefunc' and 'imstatusfunc' to handle IME/XIM
Bram Moolenaard473c8c2018-08-11 18:00:22 +02004541 via external command if Vim is not compiled with the |+xim|,
Bram Moolenaar6315a9a2017-11-25 15:20:02 +01004542 |+multi_byte_ime| or |global-ime|.
4543
Bram Moolenaar071d4272004-06-13 20:20:40 +00004544 *'imsearch'* *'ims'*
Bram Moolenaar4cf56bb2017-09-16 15:50:32 +02004545'imsearch' 'ims' number (default -1)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004546 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00004547 Specifies whether :lmap or an Input Method (IM) is to be used when
4548 entering a search pattern. Valid values:
4549 -1 the value of 'iminsert' is used, makes it look like
4550 'iminsert' is also used when typing a search pattern
4551 0 :lmap is off and IM is off
4552 1 :lmap is ON and IM is off
4553 2 :lmap is off and IM is ON
4554 Note that this option changes when using CTRL-^ in Command-line mode
4555 |c_CTRL-^|.
4556 The value is set to 1 when it is not -1 and setting the 'keymap'
4557 option to a valid keymap name.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01004558 The value 0 may not work correctly with Motif with some XIM
Bram Moolenaar071d4272004-06-13 20:20:40 +00004559 methods. Use 'imdisable' to disable XIM then.
4560
Bram Moolenaarabab85a2013-06-26 19:18:05 +02004561 *'imstatusfunc'* *'imsf'*
4562'imstatusfunc' 'imsf' string (default "")
4563 global
Bram Moolenaarabab85a2013-06-26 19:18:05 +02004564 This option specifies a function that is called to obtain the status
4565 of Input Method. It must return a positive number when IME is active.
Yegappan Lakshmanan7645da52021-12-04 14:02:30 +00004566 The value can be the name of a function, a |lambda| or a |Funcref|.
4567 See |option-value-function| for more information.
Bram Moolenaaref8c6172020-07-01 15:12:44 +02004568 It is not used in the MS-Windows GUI version.
Bram Moolenaarabab85a2013-06-26 19:18:05 +02004569
4570 Example: >
4571 function ImStatusFunc()
4572 let is_active = ...do something
4573 return is_active ? 1 : 0
4574 endfunction
4575 set imstatusfunc=ImStatusFunc
4576<
4577 NOTE: This function is invoked very often. Keep it fast.
Bram Moolenaar110289e2019-05-23 15:38:06 +02004578 The expression will be evaluated in the |sandbox| when set from a
4579 modeline, see |sandbox-option|.
Bram Moolenaarabab85a2013-06-26 19:18:05 +02004580
Bram Moolenaar5c6dbcb2017-08-30 22:00:20 +02004581 *'imstyle'* *'imst'*
4582'imstyle' 'imst' number (default 1)
4583 global
Bram Moolenaar5c6dbcb2017-08-30 22:00:20 +02004584 {only available when compiled with |+xim| and
4585 |+GUI_GTK|}
Bram Moolenaar37c64c72017-09-19 22:06:03 +02004586 This option specifies the input style of Input Method:
4587 0 use on-the-spot style
4588 1 over-the-spot style
Bram Moolenaar5c6dbcb2017-08-30 22:00:20 +02004589 See: |xim-input-style|
4590
Bram Moolenaar24a98a02017-09-27 22:23:55 +02004591 For a long time on-the-spot style had been used in the GTK version of
4592 vim, however, it is known that it causes troubles when using mappings,
Bram Moolenaar5c6dbcb2017-08-30 22:00:20 +02004593 |single-repeat|, etc. Therefore over-the-spot style becomes the
4594 default now. This should work fine for most people, however if you
4595 have any problem with it, try using on-the-spot style.
Bram Moolenaar110289e2019-05-23 15:38:06 +02004596 The expression will be evaluated in the |sandbox| when set from a
4597 modeline, see |sandbox-option|.
Bram Moolenaar5c6dbcb2017-08-30 22:00:20 +02004598
Bram Moolenaar071d4272004-06-13 20:20:40 +00004599 *'include'* *'inc'*
4600'include' 'inc' string (default "^\s*#\s*include")
4601 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004602 {not available when compiled without the
4603 |+find_in_path| feature}
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004604 Pattern to be used to find an include command. It is a search
Bram Moolenaar071d4272004-06-13 20:20:40 +00004605 pattern, just like for the "/" command (See |pattern|). The default
4606 value is for C programs. This option is used for the commands "[i",
Bram Moolenaar1e015462005-09-25 22:16:38 +00004607 "]I", "[d", etc.
4608 Normally the 'isfname' option is used to recognize the file name that
Bram Moolenaar482aaeb2005-09-29 18:26:07 +00004609 comes after the matched pattern. But if "\zs" appears in the pattern
4610 then the text matched from "\zs" to the end, or until "\ze" if it
4611 appears, is used as the file name. Use this to include characters
4612 that are not in 'isfname', such as a space. You can then use
4613 'includeexpr' to process the matched text.
Bram Moolenaar1e015462005-09-25 22:16:38 +00004614 See |option-backslash| about including spaces and backslashes.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004615
4616 *'includeexpr'* *'inex'*
4617'includeexpr' 'inex' string (default "")
4618 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00004619 {not available when compiled without the
Bram Moolenaardb84e452010-08-15 13:50:43 +02004620 |+find_in_path| or |+eval| features}
Bram Moolenaar071d4272004-06-13 20:20:40 +00004621 Expression to be used to transform the string found with the 'include'
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004622 option to a file name. Mostly useful to change "." to "/" for Java: >
Bram Moolenaarb59ae592022-11-23 23:46:31 +00004623 :setlocal includeexpr=substitute(v:fname,'\\.','/','g')
Bram Moolenaar071d4272004-06-13 20:20:40 +00004624< The "v:fname" variable will be set to the file name that was detected.
Bram Moolenaarb59ae592022-11-23 23:46:31 +00004625 Note the double backslash: the `:set` command first halves them, then
4626 one remains it the value, where "\." matches a dot literally. For
4627 simple character replacements `tr()` avoids the need for escaping: >
4628 :setlocal includeexpr=tr(v:fname,'.','/')
4629<
Bram Moolenaar071d4272004-06-13 20:20:40 +00004630 Also used for the |gf| command if an unmodified file name can't be
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004631 found. Allows doing "gf" on the name after an 'include' statement.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004632 Also used for |<cfile>|.
4633
Yegappan Lakshmanan8bb65f22021-12-26 10:51:39 +00004634 If the expression starts with s: or |<SID>|, then it is replaced with
4635 the script ID (|local-function|). Example: >
Bram Moolenaarb59ae592022-11-23 23:46:31 +00004636 setlocal includeexpr=s:MyIncludeExpr()
4637 setlocal includeexpr=<SID>SomeIncludeExpr()
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00004638< Otherwise, the expression is evaluated in the context of the script
4639 where the option was set, thus script-local items are available.
4640
Bram Moolenaara4e0b972022-10-01 19:43:52 +01004641 It is more efficient if the value is just a function call without
4642 arguments, see |expr-option-function|.
4643
Bram Moolenaar30b65812012-07-12 22:01:11 +02004644 The expression will be evaluated in the |sandbox| when set from a
4645 modeline, see |sandbox-option|.
Bram Moolenaar110289e2019-05-23 15:38:06 +02004646 This option cannot be set in a modeline when 'modelineexpr' is off.
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00004647
4648 It is not allowed to change text or jump to another window while
4649 evaluating 'includeexpr' |textlock|.
4650
Bram Moolenaar071d4272004-06-13 20:20:40 +00004651 *'incsearch'* *'is'* *'noincsearch'* *'nois'*
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +02004652'incsearch' 'is' boolean (default off, set in |defaults.vim| if the
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01004653 |+reltime| feature is supported)
Bram Moolenaar071d4272004-06-13 20:20:40 +00004654 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004655 {not available when compiled without the
Bram Moolenaardb84e452010-08-15 13:50:43 +02004656 |+extra_search| features}
Bram Moolenaar21cf8232004-07-16 20:18:37 +00004657 While typing a search command, show where the pattern, as it was typed
4658 so far, matches. The matched string is highlighted. If the pattern
4659 is invalid or not found, nothing is shown. The screen will be updated
4660 often, this is only useful on fast terminals.
Bram Moolenaarfc65cab2018-08-28 22:58:02 +02004661 Also applies to the pattern in commands: >
4662 :global
4663 :lvimgrep
4664 :lvimgrepadd
4665 :smagic
4666 :snomagic
4667 :sort
4668 :substitute
4669 :vglobal
4670 :vimgrep
4671 :vimgrepadd
4672< Note that the match will be shown, but the cursor will return to its
Bram Moolenaar21cf8232004-07-16 20:18:37 +00004673 original position when no match is found and when pressing <Esc>. You
4674 still need to finish the search command with <Enter> to move the
4675 cursor to the match.
Bram Moolenaardc083282016-10-11 08:57:33 +02004676 You can use the CTRL-G and CTRL-T keys to move to the next and
4677 previous match. |c_CTRL-G| |c_CTRL-T|
Bram Moolenaar91a4e822008-01-19 14:59:58 +00004678 When compiled with the |+reltime| feature Vim only searches for about
4679 half a second. With a complicated pattern and/or a lot of text the
4680 match may not be found. This is to avoid that Vim hangs while you
4681 are typing the pattern.
Bram Moolenaar21cf8232004-07-16 20:18:37 +00004682 The highlighting can be set with the 'i' flag in 'highlight'.
Bram Moolenaar2f058492017-11-30 20:27:52 +01004683 When 'hlsearch' is on, all matched strings are highlighted too while
4684 typing a search command. See also: 'hlsearch'.
Bram Moolenaard473c8c2018-08-11 18:00:22 +02004685 If you don't want to turn 'hlsearch' on, but want to highlight all
4686 matches while searching, you can turn on and off 'hlsearch' with
4687 autocmd. Example: >
Bram Moolenaar2e51d9a2017-10-29 16:40:30 +01004688 augroup vimrc-incsearch-highlight
4689 autocmd!
Bram Moolenaarf8f8b2e2017-11-02 19:08:48 +01004690 autocmd CmdlineEnter /,\? :set hlsearch
4691 autocmd CmdlineLeave /,\? :set nohlsearch
Bram Moolenaar2e51d9a2017-10-29 16:40:30 +01004692 augroup END
4693<
Bram Moolenaarefd2bf12006-03-16 21:41:35 +00004694 CTRL-L can be used to add one character from after the current match
Bram Moolenaara9dc3752010-07-11 20:46:53 +02004695 to the command line. If 'ignorecase' and 'smartcase' are set and the
4696 command line has no uppercase characters, the added character is
4697 converted to lowercase.
Bram Moolenaarefd2bf12006-03-16 21:41:35 +00004698 CTRL-R CTRL-W can be used to add the word at the end of the current
4699 match, excluding the characters that were already typed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004700 NOTE: This option is reset when 'compatible' is set.
4701
4702 *'indentexpr'* *'inde'*
4703'indentexpr' 'inde' string (default "")
4704 local to buffer
Bram Moolenaar8e145b82022-05-21 20:17:31 +01004705 {not available when compiled without the |+eval|
4706 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00004707 Expression which is evaluated to obtain the proper indent for a line.
4708 It is used when a new line is created, for the |=| operator and
4709 in Insert mode as specified with the 'indentkeys' option.
4710 When this option is not empty, it overrules the 'cindent' and
Bram Moolenaar20f90cf2011-05-19 12:22:51 +02004711 'smartindent' indenting. When 'lisp' is set, this option is
Bram Moolenaar49846fb2022-10-15 16:05:33 +01004712 is only used when 'lispoptions' contains "expr:1".
Bram Moolenaar071d4272004-06-13 20:20:40 +00004713 When 'paste' is set this option is not used for indenting.
4714 The expression is evaluated with |v:lnum| set to the line number for
Bram Moolenaar482aaeb2005-09-29 18:26:07 +00004715 which the indent is to be computed. The cursor is also in this line
Bram Moolenaar071d4272004-06-13 20:20:40 +00004716 when the expression is evaluated (but it may be moved around).
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00004717
Yegappan Lakshmanan8bb65f22021-12-26 10:51:39 +00004718 If the expression starts with s: or |<SID>|, then it is replaced with
4719 the script ID (|local-function|). Example: >
4720 set indentexpr=s:MyIndentExpr()
4721 set indentexpr=<SID>SomeIndentExpr()
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00004722< Otherwise, the expression is evaluated in the context of the script
4723 where the option was set, thus script-local items are available.
4724
Bram Moolenaara4e0b972022-10-01 19:43:52 +01004725 The advantage of using a function call without arguments is that it is
4726 faster, see |expr-option-function|.
4727
Bram Moolenaar071d4272004-06-13 20:20:40 +00004728 The expression must return the number of spaces worth of indent. It
4729 can return "-1" to keep the current indent (this means 'autoindent' is
4730 used for the indent).
4731 Functions useful for computing the indent are |indent()|, |cindent()|
4732 and |lispindent()|.
4733 The evaluation of the expression must not have side effects! It must
4734 not change the text, jump to another window, etc. Afterwards the
4735 cursor position is always restored, thus the cursor may be moved.
4736 Normally this option would be set to call a function: >
4737 :set indentexpr=GetMyIndent()
4738< Error messages will be suppressed, unless the 'debug' option contains
4739 "msg".
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00004740 See |indent-expression|.
Bram Moolenaar036986f2017-03-16 17:41:02 +01004741 NOTE: This option is set to "" when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004742
Bram Moolenaar30b65812012-07-12 22:01:11 +02004743 The expression will be evaluated in the |sandbox| when set from a
4744 modeline, see |sandbox-option|.
Bram Moolenaar110289e2019-05-23 15:38:06 +02004745 This option cannot be set in a modeline when 'modelineexpr' is off.
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00004746
4747 It is not allowed to change text or jump to another window while
4748 evaluating 'indentexpr' |textlock|.
4749
4750
Bram Moolenaar071d4272004-06-13 20:20:40 +00004751 *'indentkeys'* *'indk'*
Bram Moolenaarce655742019-01-31 14:12:57 +01004752'indentkeys' 'indk' string (default "0{,0},0),0],:,0#,!^F,o,O,e")
Bram Moolenaar071d4272004-06-13 20:20:40 +00004753 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00004754 A list of keys that, when typed in Insert mode, cause reindenting of
4755 the current line. Only happens if 'indentexpr' isn't empty.
4756 The format is identical to 'cinkeys', see |indentkeys-format|.
4757 See |C-indenting| and |indent-expression|.
4758
4759 *'infercase'* *'inf'* *'noinfercase'* *'noinf'*
4760'infercase' 'inf' boolean (default off)
4761 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00004762 When doing keyword completion in insert mode |ins-completion|, and
Bram Moolenaar446cb832008-06-24 21:56:24 +00004763 'ignorecase' is also on, the case of the match is adjusted depending
4764 on the typed text. If the typed text contains a lowercase letter
4765 where the match has an upper case letter, the completed part is made
4766 lowercase. If the typed text has no lowercase letters and the match
4767 has a lowercase letter where the typed text has an uppercase letter,
4768 and there is a letter before it, the completed part is made uppercase.
4769 With 'noinfercase' the match is used as-is.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004770
4771 *'insertmode'* *'im'* *'noinsertmode'* *'noim'*
4772'insertmode' 'im' boolean (default off)
4773 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004774 Makes Vim work in a way that Insert mode is the default mode. Useful
4775 if you want to use Vim as a modeless editor. Used for |evim|.
4776 These Insert mode commands will be useful:
4777 - Use the cursor keys to move around.
Bram Moolenaardc1f1642016-08-16 18:33:43 +02004778 - Use CTRL-O to execute one Normal mode command |i_CTRL-O|. When
Bram Moolenaar071d4272004-06-13 20:20:40 +00004779 this is a mapping, it is executed as if 'insertmode' was off.
4780 Normal mode remains active until the mapping is finished.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004781 - Use CTRL-L to execute a number of Normal mode commands, then use
Bram Moolenaar488c6512005-08-11 20:09:58 +00004782 <Esc> to get back to Insert mode. Note that CTRL-L moves the cursor
4783 left, like <Esc> does when 'insertmode' isn't set. |i_CTRL-L|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004784
4785 These items change when 'insertmode' is set:
4786 - when starting to edit of a file, Vim goes to Insert mode.
4787 - <Esc> in Insert mode is a no-op and beeps.
4788 - <Esc> in Normal mode makes Vim go to Insert mode.
4789 - CTRL-L in Insert mode is a command, it is not inserted.
4790 - CTRL-Z in Insert mode suspends Vim, see |CTRL-Z|. *i_CTRL-Z*
4791 However, when <Esc> is used inside a mapping, it behaves like
4792 'insertmode' was not set. This was done to be able to use the same
4793 mappings with 'insertmode' set or not set.
4794 When executing commands with |:normal| 'insertmode' is not used.
4795
4796 NOTE: This option is reset when 'compatible' is set.
4797
4798 *'isfname'* *'isf'*
Bram Moolenaar6f345a12019-12-17 21:27:18 +01004799'isfname' 'isf' string (default for Win32:
Bram Moolenaar071d4272004-06-13 20:20:40 +00004800 "@,48-57,/,\,.,-,_,+,,,#,$,%,{,},[,],:,@-@,!,~,="
4801 for AMIGA: "@,48-57,/,.,-,_,+,,,$,:"
4802 for VMS: "@,48-57,/,.,-,_,+,,,#,$,%,<,>,[,],:,;,~"
4803 for OS/390: "@,240-249,/,.,-,_,+,,,#,$,%,~,="
4804 otherwise: "@,48-57,/,.,-,_,+,,,#,$,%,~,=")
4805 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004806 The characters specified by this option are included in file names and
4807 path names. Filenames are used for commands like "gf", "[i" and in
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004808 the tags file. It is also used for "\f" in a |pattern|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004809 Multi-byte characters 256 and above are always included, only the
4810 characters up to 255 are specified with this option.
4811 For UTF-8 the characters 0xa0 to 0xff are included as well.
Bram Moolenaar446cb832008-06-24 21:56:24 +00004812 Think twice before adding white space to this option. Although a
4813 space may appear inside a file name, the effect will be that Vim
4814 doesn't know where a file name starts or ends when doing completion.
4815 It most likely works better without a space in 'isfname'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004816
4817 Note that on systems using a backslash as path separator, Vim tries to
4818 do its best to make it work as you would expect. That is a bit
4819 tricky, since Vi originally used the backslash to escape special
4820 characters. Vim will not remove a backslash in front of a normal file
4821 name character on these systems, but it will on Unix and alikes. The
4822 '&' and '^' are not included by default, because these are special for
4823 cmd.exe.
4824
4825 The format of this option is a list of parts, separated with commas.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004826 Each part can be a single character number or a range. A range is two
4827 character numbers with '-' in between. A character number can be a
Bram Moolenaar071d4272004-06-13 20:20:40 +00004828 decimal number between 0 and 255 or the ASCII character itself (does
4829 not work for digits). Example:
4830 "_,-,128-140,#-43" (include '_' and '-' and the range
4831 128 to 140 and '#' to 43)
4832 If a part starts with '^', the following character number or range
4833 will be excluded from the option. The option is interpreted from left
4834 to right. Put the excluded character after the range where it is
4835 included. To include '^' itself use it as the last character of the
4836 option or the end of a range. Example:
4837 "^a-z,#,^" (exclude 'a' to 'z', include '#' and '^')
4838 If the character is '@', all characters where isalpha() returns TRUE
4839 are included. Normally these are the characters a to z and A to Z,
4840 plus accented characters. To include '@' itself use "@-@". Examples:
4841 "@,^a-z" All alphabetic characters, excluding lower
Bram Moolenaar446cb832008-06-24 21:56:24 +00004842 case ASCII letters.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004843 "a-z,A-Z,@-@" All letters plus the '@' character.
4844 A comma can be included by using it where a character number is
4845 expected. Example:
4846 "48-57,,,_" Digits, comma and underscore.
4847 A comma can be excluded by prepending a '^'. Example:
4848 " -~,^,,9" All characters from space to '~', excluding
4849 comma, plus <Tab>.
4850 See |option-backslash| about including spaces and backslashes.
4851
4852 *'isident'* *'isi'*
Bram Moolenaar6f345a12019-12-17 21:27:18 +01004853'isident' 'isi' string (default for Win32:
Bram Moolenaar071d4272004-06-13 20:20:40 +00004854 "@,48-57,_,128-167,224-235"
4855 otherwise: "@,48-57,_,192-255")
4856 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004857 The characters given by this option are included in identifiers.
4858 Identifiers are used in recognizing environment variables and after a
4859 match of the 'define' option. It is also used for "\i" in a
Bram Moolenaar582fd852005-03-28 20:58:01 +00004860 |pattern|. See 'isfname' for a description of the format of this
Bram Moolenaar95bafa22018-10-02 13:26:25 +02004861 option. For '@' only characters up to 255 are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004862 Careful: If you change this option, it might break expanding
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004863 environment variables. E.g., when '/' is included and Vim tries to
Bram Moolenaar071d4272004-06-13 20:20:40 +00004864 expand "$HOME/.viminfo". Maybe you should change 'iskeyword' instead.
4865
4866 *'iskeyword'* *'isk'*
Bram Moolenaar6f345a12019-12-17 21:27:18 +01004867'iskeyword' 'isk' string (Vim default for Win32:
Bram Moolenaar071d4272004-06-13 20:20:40 +00004868 "@,48-57,_,128-167,224-235"
4869 otherwise: "@,48-57,_,192-255"
4870 Vi default: "@,48-57,_")
4871 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00004872 Keywords are used in searching and recognizing with many commands:
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00004873 "w", "*", "[i", etc. It is also used for "\k" in a |pattern|. See
Bram Moolenaar95bafa22018-10-02 13:26:25 +02004874 'isfname' for a description of the format of this option. For '@'
Bram Moolenaar4c295022021-05-02 17:19:11 +02004875 characters above 255 check the "word" character class (any character
4876 that is not white space or punctuation).
Bram Moolenaar95bafa22018-10-02 13:26:25 +02004877 For C programs you could use "a-z,A-Z,48-57,_,.,-,>".
Bram Moolenaar071d4272004-06-13 20:20:40 +00004878 For a help file it is set to all non-blank printable characters except
4879 '*', '"' and '|' (so that CTRL-] on a command finds the help for that
4880 command).
4881 When the 'lisp' option is on the '-' character is always included.
Bram Moolenaarb8060fe2016-01-19 22:29:28 +01004882 This option also influences syntax highlighting, unless the syntax
4883 uses |:syn-iskeyword|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004884 NOTE: This option is set to the Vi default value when 'compatible' is
4885 set and to the Vim default value when 'compatible' is reset.
4886
4887 *'isprint'* *'isp'*
Bram Moolenaar3d1cde82020-08-15 18:55:18 +02004888'isprint' 'isp' string (default for Win32 and macOS:
Bram Moolenaar071d4272004-06-13 20:20:40 +00004889 "@,~-255"; otherwise: "@,161-255")
4890 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004891 The characters given by this option are displayed directly on the
4892 screen. It is also used for "\p" in a |pattern|. The characters from
4893 space (ASCII 32) to '~' (ASCII 126) are always displayed directly,
4894 even when they are not included in 'isprint' or excluded. See
4895 'isfname' for a description of the format of this option.
4896
4897 Non-printable characters are displayed with two characters:
4898 0 - 31 "^@" - "^_"
4899 32 - 126 always single characters
4900 127 "^?"
4901 128 - 159 "~@" - "~_"
4902 160 - 254 "| " - "|~"
4903 255 "~?"
4904 When 'encoding' is a Unicode one, illegal bytes from 128 to 255 are
4905 displayed as <xx>, with the hexadecimal value of the byte.
4906 When 'display' contains "uhex" all unprintable characters are
4907 displayed as <xx>.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01004908 The SpecialKey highlighting will be used for unprintable characters.
4909 |hl-SpecialKey|
Bram Moolenaar071d4272004-06-13 20:20:40 +00004910
4911 Multi-byte characters 256 and above are always included, only the
4912 characters up to 255 are specified with this option. When a character
4913 is printable but it is not available in the current font, a
4914 replacement character will be shown.
4915 Unprintable and zero-width Unicode characters are displayed as <xxxx>.
4916 There is no option to specify these characters.
4917
4918 *'joinspaces'* *'js'* *'nojoinspaces'* *'nojs'*
4919'joinspaces' 'js' boolean (default on)
4920 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00004921 Insert two spaces after a '.', '?' and '!' with a join command.
4922 When 'cpoptions' includes the 'j' flag, only do this after a '.'.
4923 Otherwise only one space is inserted.
4924 NOTE: This option is set when 'compatible' is set.
4925
Yegappan Lakshmanan87018252023-09-20 20:20:04 +02004926 *'jumpoptions'* *'jop'*
4927'jumpoptions' 'jop' string (default "")
4928 global
4929 List of words that change the behavior of the |jumplist|.
4930 stack Make the jumplist behave like the tagstack.
4931 Relative location of entries in the jumplist is
4932 preserved at the cost of discarding subsequent entries
4933 when navigating backwards in the jumplist and then
4934 jumping to a location. |jumplist-stack|
4935
Bram Moolenaar071d4272004-06-13 20:20:40 +00004936 *'key'*
4937'key' string (default "")
4938 local to buffer
Bram Moolenaar996343d2010-07-04 22:20:21 +02004939 {only available when compiled with the |+cryptv|
4940 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00004941 The key that is used for encrypting and decrypting the current buffer.
Bram Moolenaar40e6a712010-05-16 22:32:54 +02004942 See |encryption| and 'cryptmethod'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004943 Careful: Do not set the key value by hand, someone might see the typed
4944 key. Use the |:X| command. But you can make 'key' empty: >
4945 :set key=
4946< It is not possible to get the value of this option with ":set key" or
4947 "echo &key". This is to avoid showing it to someone who shouldn't
4948 know. It also means you cannot see it yourself once you have set it,
4949 be careful not to make a typing error!
Yee Cheng Chin6ee7b522023-10-01 09:13:22 +02004950 You also cannot use |:set-=|, |:set+=|, |:set^=| on this option to
4951 prevent an attacker from guessing substrings in your key.
Bram Moolenaard58e9292011-02-09 17:07:58 +01004952 You can use "&key" in an expression to detect whether encryption is
4953 enabled. When 'key' is set it returns "*****" (five stars).
Bram Moolenaar071d4272004-06-13 20:20:40 +00004954
4955 *'keymap'* *'kmp'* *E544*
4956'keymap' 'kmp' string (default "")
4957 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00004958 {only available when compiled with the |+keymap|
4959 feature}
4960 Name of a keyboard mapping. See |mbyte-keymap|.
4961 Setting this option to a valid keymap name has the side effect of
4962 setting 'iminsert' to one, so that the keymap becomes effective.
4963 'imsearch' is also set to one, unless it was -1
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00004964 Only normal file name characters can be used, "/\*?[|<>" are illegal.
Bram Moolenaar071d4272004-06-13 20:20:40 +00004965
4966 *'keymodel'* *'km'*
4967'keymodel' 'km' string (default "")
4968 global
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01004969 List of comma-separated words, which enable special things that keys
Bram Moolenaar071d4272004-06-13 20:20:40 +00004970 can do. These values can be used:
4971 startsel Using a shifted special key starts selection (either
4972 Select mode or Visual mode, depending on "key" being
4973 present in 'selectmode').
4974 stopsel Using a not-shifted special key stops selection.
4975 Special keys in this context are the cursor keys, <End>, <Home>,
4976 <PageUp> and <PageDown>.
4977 The 'keymodel' option is set by the |:behave| command.
4978
Bram Moolenaar63a2e362022-11-23 20:20:18 +00004979 *'keyprotocol'* *'kpc'*
4980'keyprotocol' 'kpc' string (default: see below)
4981 global
4982 Specifies what keyboard protocol to use depending on the value of
4983 'term'. The supported keyboard protocols names are:
4984 none whatever the terminal uses
4985 mok2 modifyOtherKeys level 2, as supported by xterm
4986 kitty Kitty keyboard protocol, as supported by Kitty
4987
Bram Moolenaara87749e2022-11-30 10:23:17 +00004988 The option value is a list of comma separated items. Each item has
Bram Moolenaar63a2e362022-11-23 20:20:18 +00004989 a pattern that is matched against the 'term' option, a colon and the
4990 protocol name to be used. To illustrate this, the default value would
4991 be set with: >
4992 set keyprotocol=kitty:kitty,foot:kitty,wezterm:kitty,xterm:mok2
4993
4994< This means that when 'term' contains "kitty, "foot" or "wezterm"
4995 somewhere then the "kitty" protocol is used. When 'term' contains
Bram Moolenaar938ae282023-02-20 20:44:55 +00004996 "xterm" somewhere, then the "mok2" protocol is used.
Bram Moolenaar63a2e362022-11-23 20:20:18 +00004997
4998 The first match is used, thus if you want to have "kitty" use the
4999 kitty protocol, but "badkitty" not, then you should match "badkitty"
5000 first and use the "none" value: >
5001 set keyprotocol=badkitty:none,kitty:kitty
5002<
5003 The option is used after 'term' has been changed. First the termcap
5004 entries are set, possibly using the builtin list, see |builtin-terms|.
5005 Then this option is inspected and if there is a match and a protocol
5006 is specified the following happens:
5007 none Nothing, the regular t_TE and t_TI values remain
5008
5009 mok2 The t_TE value is changed to:
5010 CSI >4;m disables modifyOtherKeys
5011 The t_TI value is changed to:
5012 CSI >4;2m enables modifyOtherKeys
Bram Moolenaara87749e2022-11-30 10:23:17 +00005013 CSI ?4m request the modifyOtherKeys state
Bram Moolenaar63a2e362022-11-23 20:20:18 +00005014
5015 kitty The t_TE value is changed to:
5016 CSI >4;m disables modifyOtherKeys
Bram Moolenaara87749e2022-11-30 10:23:17 +00005017 CSI =0;1u disables the kitty keyboard protocol
Bram Moolenaar63a2e362022-11-23 20:20:18 +00005018 The t_TI value is changed to:
Bram Moolenaara87749e2022-11-30 10:23:17 +00005019 CSI =1;1u enables the kitty keyboard protocol
Bram Moolenaar63a2e362022-11-23 20:20:18 +00005020 CSI ?u request kitty keyboard protocol state
5021 CSI >c request the termresponse
5022
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00005023 If you notice problems, such as characters being displayed that
5024 disappear after `CTRL-L`, you might want to try making this option
5025 empty. Then set the 'term' option to have it take effect: >
5026 set keyprotocol=
5027 let &term = &term
Bram Moolenaarbe4e0162023-02-02 13:59:48 +00005028<
Bram Moolenaar63a2e362022-11-23 20:20:18 +00005029
Bram Moolenaar071d4272004-06-13 20:20:40 +00005030 *'keywordprg'* *'kp'*
5031'keywordprg' 'kp' string (default "man" or "man -s", DOS: ":help",
Bram Moolenaar2ff8b642016-05-24 10:46:45 +02005032 VMS: "help")
Bram Moolenaar071d4272004-06-13 20:20:40 +00005033 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00005034 Program to use for the |K| command. Environment variables are
5035 expanded |:set_env|. ":help" may be used to access the Vim internal
5036 help. (Note that previously setting the global option to the empty
5037 value did this, which is now deprecated.)
Bram Moolenaar2ff8b642016-05-24 10:46:45 +02005038 When the first character is ":", the command is invoked as a Vim
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01005039 Ex command with [count] added as an argument if it is not zero.
Bram Moolenaar2ff8b642016-05-24 10:46:45 +02005040 When "man", "man -s" or an Ex command is used, Vim will automatically
5041 translate a count for the "K" command and pass it as the first
5042 argument. For "man -s" the "-s" is removed when there is no count.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005043 See |option-backslash| about including spaces and backslashes.
5044 Example: >
5045 :set keywordprg=man\ -s
5046< This option cannot be set from a |modeline| or in the |sandbox|, for
5047 security reasons.
5048
5049 *'langmap'* *'lmap'* *E357* *E358*
5050'langmap' 'lmap' string (default "")
5051 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005052 {only available when compiled with the |+langmap|
5053 feature}
5054 This option allows switching your keyboard into a special language
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00005055 mode. When you are typing text in Insert mode the characters are
Bram Moolenaarfa735342016-01-03 22:14:44 +01005056 inserted directly. When in Normal mode the 'langmap' option takes
Bram Moolenaar071d4272004-06-13 20:20:40 +00005057 care of translating these special characters to the original meaning
5058 of the key. This means you don't have to change the keyboard mode to
5059 be able to execute Normal mode commands.
5060 This is the opposite of the 'keymap' option, where characters are
5061 mapped in Insert mode.
Bram Moolenaarb17893a2020-03-14 08:19:51 +01005062 Also consider setting 'langremap' to off, to prevent 'langmap' from
5063 applying to characters resulting from a mapping.
Bram Moolenaare968e362014-05-13 20:23:24 +02005064 This option cannot be set from a |modeline| or in the |sandbox|, for
5065 security reasons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005066
Bram Moolenaarfd2ac762006-03-01 22:09:21 +00005067 Example (for Greek, in UTF-8): *greek* >
5068 :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 +00005069< Example (exchanges meaning of z and y for commands): >
5070 :set langmap=zy,yz,ZY,YZ
5071<
5072 The 'langmap' option is a list of parts, separated with commas. Each
5073 part can be in one of two forms:
5074 1. A list of pairs. Each pair is a "from" character immediately
5075 followed by the "to" character. Examples: "aA", "aAbBcC".
5076 2. A list of "from" characters, a semi-colon and a list of "to"
5077 characters. Example: "abc;ABC"
5078 Example: "aA,fgh;FGH,cCdDeE"
5079 Special characters need to be preceded with a backslash. These are
Bram Moolenaar4f4d51a2020-10-11 13:57:40 +02005080 ";", ',', '"', '|' and backslash itself.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005081
5082 This will allow you to activate vim actions without having to switch
5083 back and forth between the languages. Your language characters will
5084 be understood as normal vim English characters (according to the
5085 langmap mappings) in the following cases:
5086 o Normal/Visual mode (commands, buffer/register names, user mappings)
5087 o Insert/Replace Mode: Register names after CTRL-R
5088 o Insert/Replace Mode: Mappings
5089 Characters entered in Command-line mode will NOT be affected by
5090 this option. Note that this option can be changed at any time
5091 allowing to switch between mappings for different languages/encodings.
5092 Use a mapping to avoid having to type it each time!
5093
5094 *'langmenu'* *'lm'*
5095'langmenu' 'lm' string (default "")
5096 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005097 {only available when compiled with the |+menu| and
5098 |+multi_lang| features}
5099 Language to use for menu translation. Tells which file is loaded
5100 from the "lang" directory in 'runtimepath': >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00005101 "lang/menu_" .. &langmenu .. ".vim"
Bram Moolenaar071d4272004-06-13 20:20:40 +00005102< (without the spaces). For example, to always use the Dutch menus, no
5103 matter what $LANG is set to: >
5104 :set langmenu=nl_NL.ISO_8859-1
5105< When 'langmenu' is empty, |v:lang| is used.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00005106 Only normal file name characters can be used, "/\*?[|<>" are illegal.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005107 If your $LANG is set to a non-English language but you do want to use
5108 the English menus: >
5109 :set langmenu=none
5110< This option must be set before loading menus, switching on filetype
5111 detection or syntax highlighting. Once the menus are defined setting
5112 this option has no effect. But you could do this: >
5113 :source $VIMRUNTIME/delmenu.vim
5114 :set langmenu=de_DE.ISO_8859-1
5115 :source $VIMRUNTIME/menu.vim
5116< Warning: This deletes all menus that you defined yourself!
5117
Bram Moolenaard94464e2015-11-02 15:28:18 +01005118 *'langnoremap'* *'lnr'* *'nolangnoremap'* *'nolnr'*
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +02005119'langnoremap' 'lnr' boolean (default off, set in |defaults.vim|)
Bram Moolenaar4391cf92014-11-05 17:44:52 +01005120 global
Bram Moolenaar4391cf92014-11-05 17:44:52 +01005121 {only available when compiled with the |+langmap|
5122 feature}
Bram Moolenaare4a3bcf2016-08-26 19:52:37 +02005123 This is just like 'langremap' but with the value inverted. It only
5124 exists for backwards compatibility. When setting 'langremap' then
5125 'langnoremap' is set to the inverted value, and the other way around.
5126
5127 *'langremap'* *'lrm'* *'nolangremap'* *'nolrm'*
Bram Moolenaarb17893a2020-03-14 08:19:51 +01005128'langremap' 'lrm' boolean (default on, set to off in |defaults.vim|)
Bram Moolenaare4a3bcf2016-08-26 19:52:37 +02005129 global
Bram Moolenaare4a3bcf2016-08-26 19:52:37 +02005130 {only available when compiled with the |+langmap|
5131 feature}
5132 When off, setting 'langmap' does not apply to characters resulting from
Bram Moolenaar4391cf92014-11-05 17:44:52 +01005133 a mapping. This basically means, if you noticed that setting
Bram Moolenaare4a3bcf2016-08-26 19:52:37 +02005134 'langmap' disables some of your mappings, try resetting this option.
5135 This option defaults to on for backwards compatibility. Set it off if
Bram Moolenaar4391cf92014-11-05 17:44:52 +01005136 that works for you to avoid mappings to break.
5137
Bram Moolenaar071d4272004-06-13 20:20:40 +00005138 *'laststatus'* *'ls'*
5139'laststatus' 'ls' number (default 1)
5140 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005141 The value of this option influences when the last window will have a
5142 status line:
5143 0: never
5144 1: only if there are at least two windows
5145 2: always
5146 The screen looks nicer with a status line if you have several
5147 windows, but it takes another screen line. |status-line|
5148
5149 *'lazyredraw'* *'lz'* *'nolazyredraw'* *'nolz'*
5150'lazyredraw' 'lz' boolean (default off)
5151 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005152 When this option is set, the screen will not be redrawn while
5153 executing macros, registers and other commands that have not been
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00005154 typed. Also, updating the window title is postponed. To force an
Bram Moolenaar071d4272004-06-13 20:20:40 +00005155 update use |:redraw|.
Bram Moolenaara57b5532022-06-24 11:48:03 +01005156 This may occasionally cause display errors. It is only meant to be set
5157 temporarily when performing an operation where redrawing may cause
Bram Moolenaar8cc5b552022-06-23 13:04:20 +01005158 flickering or cause a slow down.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005159
5160 *'linebreak'* *'lbr'* *'nolinebreak'* *'nolbr'*
5161'linebreak' 'lbr' boolean (default off)
5162 local to window
Bram Moolenaardb84e452010-08-15 13:50:43 +02005163 {not available when compiled without the |+linebreak|
Bram Moolenaar071d4272004-06-13 20:20:40 +00005164 feature}
Bram Moolenaar946e27a2014-06-25 18:50:27 +02005165 If on, Vim will wrap long lines at a character in 'breakat' rather
Bram Moolenaar071d4272004-06-13 20:20:40 +00005166 than at the last character that fits on the screen. Unlike
5167 'wrapmargin' and 'textwidth', this does not insert <EOL>s in the file,
Bram Moolenaar946e27a2014-06-25 18:50:27 +02005168 it only affects the way the file is displayed, not its contents.
5169 If 'breakindent' is set, line is visually indented. Then, the value
5170 of 'showbreak' is used to put in front of wrapped lines. This option
Bram Moolenaar86b17e92014-07-02 20:00:47 +02005171 is not used when the 'wrap' option is off.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005172 Note that <Tab> characters after an <EOL> are mostly not displayed
5173 with the right amount of white space.
5174
5175 *'lines'* *E593*
5176'lines' number (default 24 or terminal height)
5177 global
5178 Number of lines of the Vim window.
5179 Normally you don't need to set this. It is done automatically by the
Bram Moolenaar7c626922005-02-07 22:01:03 +00005180 terminal initialization code. Also see |posix-screen-size|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005181 When Vim is running in the GUI or in a resizable window, setting this
5182 option will cause the window size to be changed. When you only want
5183 to use the size for the GUI, put the command in your |gvimrc| file.
5184 Vim limits the number of lines to what fits on the screen. You can
5185 use this command to get the tallest window possible: >
5186 :set lines=999
Bram Moolenaarf4d11452005-12-02 00:46:37 +00005187< Minimum value is 2, maximum value is 1000.
Bram Moolenaardc1f1642016-08-16 18:33:43 +02005188 If you get fewer lines than expected, check the 'guiheadroom' option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005189 When you set this option and Vim is unable to change the physical
5190 number of lines of the display, the display may be messed up.
5191
5192 *'linespace'* *'lsp'*
5193'linespace' 'lsp' number (default 0, 1 for Win32 GUI)
5194 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005195 {only in the GUI}
5196 Number of pixel lines inserted between characters. Useful if the font
5197 uses the full character cell height, making lines touch each other.
5198 When non-zero there is room for underlining.
Bram Moolenaarbc7aa852005-03-06 23:38:09 +00005199 With some fonts there can be too much room between lines (to have
5200 space for ascents and descents). Then it makes sense to set
5201 'linespace' to a negative value. This may cause display problems
5202 though!
Bram Moolenaar071d4272004-06-13 20:20:40 +00005203
5204 *'lisp'* *'nolisp'*
5205'lisp' boolean (default off)
5206 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00005207 Lisp mode: When <Enter> is typed in insert mode set the indent for
5208 the next line to Lisp standards (well, sort of). Also happens with
5209 "cc" or "S". 'autoindent' must also be on for this to work. The 'p'
5210 flag in 'cpoptions' changes the method of indenting: Vi compatible or
5211 better. Also see 'lispwords'.
5212 The '-' character is included in keyword characters. Redefines the
5213 "=" operator to use this same indentation algorithm rather than
5214 calling an external program if 'equalprg' is empty.
5215 This option is not used when 'paste' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005216
Bram Moolenaar49846fb2022-10-15 16:05:33 +01005217 *'lispoptions'* *'lop'*
5218'lispoptions' 'lop' string (default "")
5219 local to buffer
5220 Comma-separated list of items that influence the Lisp indenting when
5221 enabled with the |'lisp'| option. Currently only one item is
5222 supported:
5223 expr:1 use 'indentexpr' for Lisp indenting when it is set
5224 expr:0 do not use 'indentexpr' for Lisp indenting (default)
5225 Note that when using 'indentexpr' the `=` operator indents all the
5226 lines, otherwise the first line is not indented (Vi-compatible).
5227
Bram Moolenaar071d4272004-06-13 20:20:40 +00005228 *'lispwords'* *'lw'*
5229'lispwords' 'lw' string (default is very long)
Bram Moolenaaraf6c1312014-03-12 18:55:58 +01005230 global or local to buffer |global-local|
Bram Moolenaar48c3f4e2022-08-08 15:42:38 +01005231 Comma-separated list of words that influence the Lisp indenting when
5232 enabled with the |'lisp'| option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005233
5234 *'list'* *'nolist'*
5235'list' boolean (default off)
5236 local to window
Bram Moolenaar113cb512021-11-07 20:27:04 +00005237 List mode: By default show tabs as CTRL-I is displayed, display $
5238 after end of line. Useful to see the difference between tabs and
5239 spaces and for trailing blanks. Further changed by the 'listchars'
5240 option.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005241
5242 The cursor is displayed at the start of the space a Tab character
5243 occupies, not at the end as usual in Normal mode. To get this cursor
5244 position while displaying Tabs with spaces, use: >
Bram Moolenaardd007ed2013-07-09 15:44:17 +02005245 :set list lcs=tab:\ \
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005246<
5247 Note that list mode will also affect formatting (set with 'textwidth'
5248 or 'wrapmargin') when 'cpoptions' includes 'L'. See 'listchars' for
Bram Moolenaar071d4272004-06-13 20:20:40 +00005249 changing the way tabs are displayed.
5250
5251 *'listchars'* *'lcs'*
5252'listchars' 'lcs' string (default "eol:$")
Bram Moolenaareed9d462021-02-15 20:38:25 +01005253 global or local to window |global-local|
Bram Moolenaarf9d5ca12010-08-01 16:13:51 +02005254 Strings to use in 'list' mode and for the |:list| command. It is a
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01005255 comma-separated list of string settings.
Bram Moolenaar79278362015-04-21 18:33:48 +02005256 *lcs-eol*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005257 eol:c Character to show at the end of each line. When
5258 omitted, there is no extra character at the end of the
5259 line.
Bram Moolenaar79278362015-04-21 18:33:48 +02005260 *lcs-tab*
Bram Moolenaar83a52172019-01-16 22:41:54 +01005261 tab:xy[z] Two or three characters to be used to show a tab.
5262 The third character is optional.
5263
5264 tab:xy The 'x' is always used, then 'y' as many times as will
5265 fit. Thus "tab:>-" displays:
5266 >
5267 >-
5268 >--
5269 etc.
5270
5271 tab:xyz The 'z' is always used, then 'x' is prepended, and
5272 then 'y' is used as many times as will fit. Thus
5273 "tab:<->" displays:
5274 >
5275 <>
5276 <->
5277 <-->
5278 etc.
5279
5280 When "tab:" is omitted, a tab is shown as ^I.
Bram Moolenaar79278362015-04-21 18:33:48 +02005281 *lcs-space*
5282 space:c Character to show for a space. When omitted, spaces
5283 are left blank.
zeertzjqf14b8ba2021-09-10 16:58:30 +02005284 *lcs-multispace*
5285 multispace:c...
Bram Moolenaarbe4e0162023-02-02 13:59:48 +00005286 One or more characters to use cyclically to show for
5287 multiple consecutive spaces. Overrides the "space"
zeertzjqf14b8ba2021-09-10 16:58:30 +02005288 setting, except for single spaces. When omitted, the
5289 "space" setting is used. For example,
5290 `:set listchars=multispace:---+` shows ten consecutive
5291 spaces as:
Bram Moolenaaraca12fd2022-06-07 10:16:15 +01005292 ---+---+-- ~
Bram Moolenaar91478ae2021-02-03 15:58:13 +01005293 *lcs-lead*
5294 lead:c Character to show for leading spaces. When omitted,
zeertzjqf14b8ba2021-09-10 16:58:30 +02005295 leading spaces are blank. Overrides the "space" and
5296 "multispace" settings for leading spaces. You can
5297 combine it with "tab:", for example: >
Bram Moolenaar942db232021-02-13 18:14:48 +01005298 :set listchars+=tab:>-,lead:.
Bram Moolenaaraca12fd2022-06-07 10:16:15 +01005299< *lcs-leadmultispace*
5300 leadmultispace:c...
Bram Moolenaar069a7d52022-06-27 22:16:08 +01005301 Like the |lcs-multispace| value, but for leading
5302 spaces only. Also overrides |lcs-lead| for leading
5303 multiple spaces.
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01005304 `:set listchars=leadmultispace:---+` shows ten
5305 consecutive leading spaces as:
Bram Moolenaaraca12fd2022-06-07 10:16:15 +01005306 ---+---+--XXX ~
5307 Where "XXX" denotes the first non-blank characters in
5308 the line.
5309 *lcs-trail*
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00005310 trail:c Character to show for trailing spaces. When omitted,
zeertzjqf14b8ba2021-09-10 16:58:30 +02005311 trailing spaces are blank. Overrides the "space" and
5312 "multispace" settings for trailing spaces.
Bram Moolenaar79278362015-04-21 18:33:48 +02005313 *lcs-extends*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005314 extends:c Character to show in the last column, when 'wrap' is
5315 off and the line continues beyond the right of the
5316 screen.
Bram Moolenaar79278362015-04-21 18:33:48 +02005317 *lcs-precedes*
Bram Moolenaarbffba7f2019-09-20 17:00:17 +02005318 precedes:c Character to show in the first visible column of the
5319 physical line, when there is text preceding the
5320 character visible in the first column.
Bram Moolenaar79278362015-04-21 18:33:48 +02005321 *lcs-conceal*
Bram Moolenaar860cae12010-06-05 23:22:07 +02005322 conceal:c Character to show in place of concealed text, when
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02005323 'conceallevel' is set to 1.
Bram Moolenaar79278362015-04-21 18:33:48 +02005324 *lcs-nbsp*
Bram Moolenaar73284b92015-05-04 17:28:22 +02005325 nbsp:c Character to show for a non-breakable space character
5326 (0xA0 (160 decimal) and U+202F). Left blank when
5327 omitted.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005328
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00005329 The characters ':' and ',' should not be used. UTF-8 characters can
Bram Moolenaar071d4272004-06-13 20:20:40 +00005330 be used when 'encoding' is "utf-8", otherwise only printable
Bram Moolenaar910f66f2006-04-05 20:41:53 +00005331 characters are allowed. All characters must be single width.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005332
Bram Moolenaar93ff6722021-10-16 17:51:40 +01005333 Each character can be specified as hex: >
5334 set listchars=eol:\\x24
5335 set listchars=eol:\\u21b5
5336 set listchars=eol:\\U000021b5
5337< Note that a double backslash is used. The number of hex characters
5338 must be exactly 2 for \\x, 4 for \\u and 8 for \\U.
5339
Bram Moolenaar071d4272004-06-13 20:20:40 +00005340 Examples: >
5341 :set lcs=tab:>-,trail:-
Bram Moolenaarcfbc5ee2004-07-02 15:38:35 +00005342 :set lcs=tab:>-,eol:<,nbsp:%
Bram Moolenaar071d4272004-06-13 20:20:40 +00005343 :set lcs=extends:>,precedes:<
5344< The "NonText" highlighting will be used for "eol", "extends" and
Bram Moolenaar34cc7d82021-09-21 20:09:51 +02005345 "precedes". "SpecialKey" will be used for "tab", "nbsp", "space",
5346 "multispace", "lead" and "trail".
Bram Moolenaar02467872007-05-06 13:22:01 +00005347 |hl-NonText| |hl-SpecialKey|
Bram Moolenaar071d4272004-06-13 20:20:40 +00005348
5349 *'lpl'* *'nolpl'* *'loadplugins'* *'noloadplugins'*
5350'loadplugins' 'lpl' boolean (default on)
5351 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005352 When on the plugin scripts are loaded when starting up |load-plugins|.
5353 This option can be reset in your |vimrc| file to disable the loading
5354 of plugins.
Bram Moolenaarc4da1132017-07-15 19:39:43 +02005355 Note that using the "-u NONE", "-u DEFAULTS" and "--noplugin" command
5356 line arguments reset this option. See |-u| and |--noplugin|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005357
Bram Moolenaard94464e2015-11-02 15:28:18 +01005358 *'luadll'*
Bram Moolenaar3848e002016-03-19 18:42:29 +01005359'luadll' string (default depends on the build)
Bram Moolenaard94464e2015-11-02 15:28:18 +01005360 global
Bram Moolenaard94464e2015-11-02 15:28:18 +01005361 {only available when compiled with the |+lua/dyn|
5362 feature}
Bram Moolenaar25e4fcd2016-01-09 14:57:47 +01005363 Specifies the name of the Lua shared library. The default is
5364 DYNAMIC_LUA_DLL, which was specified at compile time.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02005365 Environment variables are expanded |:set_env|.
Bram Moolenaard94464e2015-11-02 15:28:18 +01005366 This option cannot be set from a |modeline| or in the |sandbox|, for
5367 security reasons.
5368
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00005369 *'macatsui'* *'nomacatsui'*
5370'macatsui' boolean (default on)
5371 global
Bram Moolenaar3d1cde82020-08-15 18:55:18 +02005372 {not supported}
5373 No longer supported, as the Mac OS X GUI code was removed.
Bram Moolenaar02467872007-05-06 13:22:01 +00005374
Bram Moolenaar071d4272004-06-13 20:20:40 +00005375 *'magic'* *'nomagic'*
5376'magic' boolean (default on)
5377 global
5378 Changes the special characters that can be used in search patterns.
5379 See |pattern|.
Bram Moolenaar64d8e252016-09-06 22:12:34 +02005380 WARNING: Switching this option off most likely breaks plugins! That
5381 is because many patterns assume it's on and will fail when it's off.
5382 Only switch it off when working with old Vi scripts. In any other
5383 situation write patterns that work when 'magic' is on. Include "\M"
5384 when you want to |/\M|.
Bram Moolenaar4072ba52020-12-23 13:56:35 +01005385 In |Vim9| script the value of 'magic' is ignored, patterns behave like
5386 it is always set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005387
5388 *'makeef'* *'mef'*
5389'makeef' 'mef' string (default: "")
5390 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005391 {not available when compiled without the |+quickfix|
5392 feature}
5393 Name of the errorfile for the |:make| command (see |:make_makeprg|)
5394 and the |:grep| command.
5395 When it is empty, an internally generated temp file will be used.
5396 When "##" is included, it is replaced by a number to make the name
5397 unique. This makes sure that the ":make" command doesn't overwrite an
5398 existing file.
5399 NOT used for the ":cf" command. See 'errorfile' for that.
5400 Environment variables are expanded |:set_env|.
5401 See |option-backslash| about including spaces and backslashes.
5402 This option cannot be set from a |modeline| or in the |sandbox|, for
5403 security reasons.
5404
Bram Moolenaar2c7292d2017-03-05 17:43:31 +01005405 *'makeencoding'* *'menc'*
5406'makeencoding' 'menc' string (default "")
5407 global or local to buffer |global-local|
Bram Moolenaar2c7292d2017-03-05 17:43:31 +01005408 Encoding used for reading the output of external commands. When empty,
5409 encoding is not converted.
5410 This is used for `:make`, `:lmake`, `:grep`, `:lgrep`, `:grepadd`,
5411 `:lgrepadd`, `:cfile`, `:cgetfile`, `:caddfile`, `:lfile`, `:lgetfile`,
5412 and `:laddfile`.
5413
5414 This would be mostly useful when you use MS-Windows and set 'encoding'
5415 to "utf-8". If |+iconv| is enabled and GNU libiconv is used, setting
5416 'makeencoding' to "char" has the same effect as setting to the system
5417 locale encoding. Example: >
5418 :set encoding=utf-8
5419 :set makeencoding=char " system locale is used
5420<
Bram Moolenaar071d4272004-06-13 20:20:40 +00005421 *'makeprg'* *'mp'*
5422'makeprg' 'mp' string (default "make", VMS: "MMS")
5423 global or local to buffer |global-local|
Bram Moolenaar02467872007-05-06 13:22:01 +00005424 Program to use for the ":make" command. See |:make_makeprg|.
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01005425 This option may contain '%' and '#' characters (see |:_%| and |:_#|),
5426 which are expanded to the current and alternate file name. Use |::S|
Bram Moolenaar26df0922014-02-23 23:39:13 +01005427 to escape file names in case they contain special characters.
Bram Moolenaar02467872007-05-06 13:22:01 +00005428 Environment variables are expanded |:set_env|. See |option-backslash|
5429 about including spaces and backslashes.
5430 Note that a '|' must be escaped twice: once for ":set" and once for
5431 the interpretation of a command. When you use a filter called
5432 "myfilter" do it like this: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005433 :set makeprg=gmake\ \\\|\ myfilter
5434< The placeholder "$*" can be given (even multiple times) to specify
5435 where the arguments will be included, for example: >
5436 :set makeprg=latex\ \\\\nonstopmode\ \\\\input\\{$*}
5437< This option cannot be set from a |modeline| or in the |sandbox|, for
5438 security reasons.
5439
5440 *'matchpairs'* *'mps'*
5441'matchpairs' 'mps' string (default "(:),{:},[:]")
5442 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00005443 Characters that form pairs. The |%| command jumps from one to the
Bram Moolenaara3e6bc92013-01-30 14:18:00 +01005444 other.
5445 Only character pairs are allowed that are different, thus you cannot
5446 jump between two double quotes.
5447 The characters must be separated by a colon.
Bram Moolenaar02467872007-05-06 13:22:01 +00005448 The pairs must be separated by a comma. Example for including '<' and
Bram Moolenaar130cbfc2021-04-07 21:07:20 +02005449 '>' (for HTML): >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005450 :set mps+=<:>
5451
5452< A more exotic example, to jump between the '=' and ';' in an
5453 assignment, useful for languages like C and Java: >
5454 :au FileType c,cpp,java set mps+==:;
5455
5456< For a more advanced way of using "%", see the matchit.vim plugin in
Bram Moolenaar01164a62017-11-02 22:58:42 +01005457 the $VIMRUNTIME/pack/dist/opt/matchit directory. |add-local-help|
Bram Moolenaar071d4272004-06-13 20:20:40 +00005458
5459 *'matchtime'* *'mat'*
5460'matchtime' 'mat' number (default 5)
5461 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005462 Tenths of a second to show the matching paren, when 'showmatch' is
5463 set. Note that this is not in milliseconds, like other options that
5464 set a time. This is to be compatible with Nvi.
5465
Bram Moolenaar362e1a32006-03-06 23:29:24 +00005466 *'maxcombine'* *'mco'*
5467'maxcombine' 'mco' number (default 2)
5468 global
Bram Moolenaar362e1a32006-03-06 23:29:24 +00005469 The maximum number of combining characters supported for displaying.
5470 Only used when 'encoding' is "utf-8".
5471 The default is OK for most languages. Hebrew may require 4.
5472 Maximum value is 6.
5473 Even when this option is set to 2 you can still edit text with more
5474 combining characters, you just can't see them. Use |g8| or |ga|.
5475 See |mbyte-combining|.
5476
Bram Moolenaar071d4272004-06-13 20:20:40 +00005477 *'maxfuncdepth'* *'mfd'*
5478'maxfuncdepth' 'mfd' number (default 100)
5479 global
Bram Moolenaardb84e452010-08-15 13:50:43 +02005480 {not available when compiled without the |+eval|
Bram Moolenaar02467872007-05-06 13:22:01 +00005481 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00005482 Maximum depth of function calls for user functions. This normally
5483 catches endless recursion. When using a recursive function with
5484 more depth, set 'maxfuncdepth' to a bigger number. But this will use
5485 more memory, there is the danger of failing when memory is exhausted.
Bram Moolenaarbc2eada2017-01-02 21:27:47 +01005486 Increasing this limit above 200 also changes the maximum for Ex
Bram Moolenaar0b0f0992018-05-22 21:41:30 +02005487 command recursion, see |E169|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005488 See also |:function|.
5489
5490 *'maxmapdepth'* *'mmd'* *E223*
5491'maxmapdepth' 'mmd' number (default 1000)
5492 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005493 Maximum number of times a mapping is done without resulting in a
5494 character to be used. This normally catches endless mappings, like
5495 ":map x y" with ":map y x". It still does not catch ":map g wg",
5496 because the 'w' is used before the next mapping is done. See also
5497 |key-mapping|.
5498
5499 *'maxmem'* *'mm'*
5500'maxmem' 'mm' number (default between 256 to 5120 (system
5501 dependent) or half the amount of memory
5502 available)
5503 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005504 Maximum amount of memory (in Kbyte) to use for one buffer. When this
5505 limit is reached allocating extra memory for a buffer will cause
Bram Moolenaarcafafb32018-02-22 21:07:09 +01005506 other memory to be freed.
5507 The maximum usable value is about 2000000. Use this to work without a
5508 limit.
5509 The value is ignored when 'swapfile' is off.
5510 Also see 'maxmemtot'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005511
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00005512 *'maxmempattern'* *'mmp'*
5513'maxmempattern' 'mmp' number (default 1000)
5514 global
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00005515 Maximum amount of memory (in Kbyte) to use for pattern matching.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005516 The maximum value is about 2000000. Use this to work without a limit.
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00005517 *E363*
Bram Moolenaar02467872007-05-06 13:22:01 +00005518 When Vim runs into the limit it gives an error message and mostly
5519 behaves like CTRL-C was typed.
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00005520 Running into the limit often means that the pattern is very
5521 inefficient or too complex. This may already happen with the pattern
5522 "\(.\)*" on a very long line. ".*" works much better.
Bram Moolenaarfd358112018-07-07 23:21:31 +02005523 Might also happen on redraw, when syntax rules try to match a complex
5524 text structure.
5525 Vim may run out of memory before hitting the 'maxmempattern' limit, in
5526 which case you get an "Out of memory" error instead.
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00005527
Bram Moolenaar071d4272004-06-13 20:20:40 +00005528 *'maxmemtot'* *'mmt'*
5529'maxmemtot' 'mmt' number (default between 2048 and 10240 (system
5530 dependent) or half the amount of memory
5531 available)
5532 global
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005533 Maximum amount of memory in Kbyte to use for all buffers together.
5534 The maximum usable value is about 2000000 (2 Gbyte). Use this to work
Bram Moolenaarfa735342016-01-03 22:14:44 +01005535 without a limit.
5536 On 64 bit machines higher values might work. But hey, do you really
5537 need more than 2 Gbyte for text editing? Keep in mind that text is
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02005538 stored in the swap file, one can edit files > 2 Gbyte anyway. We do
Bram Moolenaarfa735342016-01-03 22:14:44 +01005539 need the memory to store undo info.
Bram Moolenaarcafafb32018-02-22 21:07:09 +01005540 Buffers with 'swapfile' off still count to the total amount of memory
5541 used.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01005542 Also see 'maxmem'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005543
5544 *'menuitems'* *'mis'*
5545'menuitems' 'mis' number (default 25)
5546 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005547 {not available when compiled without the |+menu|
5548 feature}
5549 Maximum number of items to use in a menu. Used for menus that are
5550 generated from a list of items, e.g., the Buffers menu. Changing this
5551 option has no direct effect, the menu must be refreshed first.
5552
Bram Moolenaar8aff23a2005-08-19 20:40:30 +00005553 *'mkspellmem'* *'msm'*
5554'mkspellmem' 'msm' string (default "460000,2000,500")
5555 global
Bram Moolenaar8aff23a2005-08-19 20:40:30 +00005556 {not available when compiled without the |+syntax|
5557 feature}
5558 Parameters for |:mkspell|. This tunes when to start compressing the
5559 word tree. Compression can be slow when there are many words, but
5560 it's needed to avoid running out of memory. The amount of memory used
5561 per word depends very much on how similar the words are, that's why
5562 this tuning is complicated.
5563
5564 There are three numbers, separated by commas:
5565 {start},{inc},{added}
5566
5567 For most languages the uncompressed word tree fits in memory. {start}
5568 gives the amount of memory in Kbyte that can be used before any
5569 compression is done. It should be a bit smaller than the amount of
5570 memory that is available to Vim.
5571
5572 When going over the {start} limit the {inc} number specifies the
5573 amount of memory in Kbyte that can be allocated before another
5574 compression is done. A low number means compression is done after
5575 less words are added, which is slow. A high number means more memory
5576 will be allocated.
5577
5578 After doing compression, {added} times 1024 words can be added before
5579 the {inc} limit is ignored and compression is done when any extra
5580 amount of memory is needed. A low number means there is a smaller
5581 chance of hitting the {inc} limit, less memory is used but it's
5582 slower.
5583
5584 The languages for which these numbers are important are Italian and
5585 Hungarian. The default works for when you have about 512 Mbyte. If
5586 you have 1 Gbyte you could use: >
5587 :set mkspellmem=900000,3000,800
5588< If you have less than 512 Mbyte |:mkspell| may fail for some
5589 languages, no matter what you set 'mkspellmem' to.
5590
dkearns8ebdbc92023-10-29 06:26:19 +11005591 This option cannot be set from a |modeline| or in the |sandbox|, for
5592 security reasons.
Bram Moolenaar07607392019-05-26 19:20:43 +02005593
Bram Moolenaar071d4272004-06-13 20:20:40 +00005594 *'modeline'* *'ml'* *'nomodeline'* *'noml'*
Bram Moolenaar8243a792007-05-01 17:05:03 +00005595'modeline' 'ml' boolean (Vim default: on (off for root),
5596 Vi default: off)
Bram Moolenaar071d4272004-06-13 20:20:40 +00005597 local to buffer
Bram Moolenaar110289e2019-05-23 15:38:06 +02005598 If 'modeline' is on 'modelines' gives the number of lines that is
5599 checked for set commands. If 'modeline' is off or 'modelines' is zero
5600 no lines are checked. See |modeline|.
5601
5602 *'modelineexpr'* *'mle'* *'nomodelineexpr'* *'nomle'*
5603'modelineexpr' 'mle' boolean (default: off)
5604 global
5605 When on allow some options that are an expression to be set in the
5606 modeline. Check the option for whether it is affected by
5607 'modelineexpr'. Also see |modeline|.
Bram Moolenaar1c6fd1e2019-05-23 22:11:59 +02005608 This option cannot be set from a |modeline| or in the |sandbox|, for
5609 security reasons.
Bram Moolenaar110289e2019-05-23 15:38:06 +02005610
Bram Moolenaar071d4272004-06-13 20:20:40 +00005611 *'modelines'* *'mls'*
5612'modelines' 'mls' number (default 5)
5613 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005614 If 'modeline' is on 'modelines' gives the number of lines that is
5615 checked for set commands. If 'modeline' is off or 'modelines' is zero
5616 no lines are checked. See |modeline|.
5617 NOTE: 'modeline' is set to the Vi default value when 'compatible' is
5618 set and to the Vim default value when 'compatible' is reset.
5619
5620 *'modifiable'* *'ma'* *'nomodifiable'* *'noma'*
Bram Moolenaar110289e2019-05-23 15:38:06 +02005621 *E21*
Bram Moolenaar071d4272004-06-13 20:20:40 +00005622'modifiable' 'ma' boolean (default on)
5623 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00005624 When off the buffer contents cannot be changed. The 'fileformat' and
5625 'fileencoding' options also can't be changed.
Bram Moolenaar369b6f52017-01-17 12:22:32 +01005626 Can be reset on startup with the |-M| command line argument.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005627
5628 *'modified'* *'mod'* *'nomodified'* *'nomod'*
5629'modified' 'mod' boolean (default off)
Christian Brabandt596ad662023-08-16 00:11:09 +02005630 local to buffer |local-noglobal|
Bram Moolenaar071d4272004-06-13 20:20:40 +00005631 When on, the buffer is considered to be modified. This option is set
5632 when:
5633 1. A change was made to the text since it was last written. Using the
5634 |undo| command to go back to the original text will reset the
5635 option. But undoing changes that were made before writing the
5636 buffer will set the option again, since the text is different from
5637 when it was written.
5638 2. 'fileformat' or 'fileencoding' is different from its original
5639 value. The original value is set when the buffer is read or
5640 written. A ":set nomodified" command also resets the original
5641 values to the current values and the 'modified' option will be
5642 reset.
Bram Moolenaar4f3f6682016-03-26 23:01:59 +01005643 Similarly for 'eol' and 'bomb'.
Bram Moolenaar5302d9e2011-09-14 17:55:08 +02005644 This option is not set when a change is made to the buffer as the
5645 result of a BufNewFile, BufRead/BufReadPost, BufWritePost,
5646 FileAppendPost or VimLeave autocommand event. See |gzip-example| for
5647 an explanation.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005648 When 'buftype' is "nowrite" or "nofile" this option may be set, but
5649 will be ignored.
Bram Moolenaarb5b75622018-03-09 22:22:21 +01005650 Note that the text may actually be the same, e.g. 'modified' is set
5651 when using "rA" on an "A".
Bram Moolenaar071d4272004-06-13 20:20:40 +00005652
5653 *'more'* *'nomore'*
5654'more' boolean (Vim default: on, Vi default: off)
5655 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005656 When on, listings pause when the whole screen is filled. You will get
5657 the |more-prompt|. When this option is off there are no pauses, the
5658 listing continues until finished.
5659 NOTE: This option is set to the Vi default value when 'compatible' is
5660 set and to the Vim default value when 'compatible' is reset.
5661
Bram Moolenaar98a29d02021-01-18 19:55:44 +01005662 *'mouse'*
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01005663'mouse' string (default "", "a" for GUI and Win32,
Bram Moolenaar5b418992019-10-27 18:50:25 +01005664 set to "a" or "nvi" in |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00005665 global
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01005666 Enable the use of the mouse. Works for most terminals (xterm, Win32
5667 |win32-mouse|, QNX pterm, *BSD console with sysmouse and Linux console
5668 with gpm). For using the mouse in the GUI, see |gui-mouse|. The
5669 mouse can be enabled for different modes:
Bram Moolenaar7f2e9d72017-11-11 20:58:53 +01005670 n Normal mode and Terminal modes
Bram Moolenaar071d4272004-06-13 20:20:40 +00005671 v Visual mode
5672 i Insert mode
5673 c Command-line mode
5674 h all previous modes when editing a help file
5675 a all previous modes
5676 r for |hit-enter| and |more-prompt| prompt
Bram Moolenaar95bafa22018-10-02 13:26:25 +02005677 Normally you would enable the mouse in all five modes with: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00005678 :set mouse=a
Bram Moolenaar5b418992019-10-27 18:50:25 +01005679< If your terminal can't overrule the mouse events going to the
5680 application, use: >
5681 :set mouse=nvi
Bram Moolenaar65e0d772020-06-14 17:29:55 +02005682< Then you can press ":", select text for the system, and press Esc to go
Bram Moolenaar5b418992019-10-27 18:50:25 +01005683 back to Vim using the mouse events.
5684 In |defaults.vim| "nvi" is used if the 'term' option is not matching
5685 "xterm".
5686
5687 When the mouse is not enabled, the GUI will still use the mouse for
Bram Moolenaar071d4272004-06-13 20:20:40 +00005688 modeless selection. This doesn't move the text cursor.
5689
5690 See |mouse-using|. Also see |'clipboard'|.
5691
5692 Note: When enabling the mouse in a terminal, copy/paste will use the
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00005693 "* register if there is access to an X-server. The xterm handling of
Bram Moolenaar071d4272004-06-13 20:20:40 +00005694 the mouse buttons can still be used by keeping the shift key pressed.
5695 Also see the 'clipboard' option.
5696
5697 *'mousefocus'* *'mousef'* *'nomousefocus'* *'nomousef'*
5698'mousefocus' 'mousef' boolean (default off)
5699 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005700 {only works in the GUI}
5701 The window that the mouse pointer is on is automatically activated.
5702 When changing the window layout or window focus in another way, the
5703 mouse pointer is moved to the window with keyboard focus. Off is the
5704 default because it makes using the pull down menus a little goofy, as
5705 a pointer transit may activate a window unintentionally.
Bram Moolenaar5ef1c6a2019-11-10 22:09:11 +01005706 MS-Windows: Also see 'scrollfocus' for what window is scrolled when
Bram Moolenaar1d9215b2020-01-25 13:27:42 +01005707 using the mouse scroll wheel.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005708
5709 *'mousehide'* *'mh'* *'nomousehide'* *'nomh'*
5710'mousehide' 'mh' boolean (default on)
5711 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005712 {only works in the GUI}
5713 When on, the mouse pointer is hidden when characters are typed.
5714 The mouse pointer is restored when the mouse is moved.
5715
5716 *'mousemodel'* *'mousem'*
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01005717'mousemodel' 'mousem' string (default "extend", "popup" for Win32)
Bram Moolenaar071d4272004-06-13 20:20:40 +00005718 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005719 Sets the model to use for the mouse. The name mostly specifies what
5720 the right mouse button is used for:
5721 extend Right mouse button extends a selection. This works
5722 like in an xterm.
5723 popup Right mouse button pops up a menu. The shifted left
5724 mouse button extends a selection. This works like
Bram Moolenaar582fd852005-03-28 20:58:01 +00005725 with Microsoft Windows.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005726 popup_setpos Like "popup", but the cursor will be moved to the
5727 position where the mouse was clicked, and thus the
5728 selected operation will act upon the clicked object.
5729 If clicking inside a selection, that selection will
Bram Moolenaar582fd852005-03-28 20:58:01 +00005730 be acted upon, i.e. no cursor move. This implies of
Bram Moolenaar071d4272004-06-13 20:20:40 +00005731 course, that right clicking outside a selection will
5732 end Visual mode.
5733 Overview of what button does what for each model:
5734 mouse extend popup(_setpos) ~
5735 left click place cursor place cursor
5736 left drag start selection start selection
5737 shift-left search word extend selection
5738 right click extend selection popup menu (place cursor)
5739 right drag extend selection -
5740 middle click paste paste
5741
5742 In the "popup" model the right mouse button produces a pop-up menu.
5743 You need to define this first, see |popup-menu|.
5744
5745 Note that you can further refine the meaning of buttons with mappings.
5746 See |gui-mouse-mapping|. But mappings are NOT used for modeless
5747 selection (because that's handled in the GUI code directly).
5748
5749 The 'mousemodel' option is set by the |:behave| command.
5750
h_east59858792023-10-25 22:47:05 +09005751 *'mousemoveevent'* *'mousemev'* *'nomousemoveevent'* *'nomousemev'*
Ernie Raelc4cb5442022-04-03 15:47:28 +01005752'mousemoveevent' 'mousemev' boolean (default off)
5753 global
5754 {only works in the GUI}
5755 When on, mouse move events are delivered to the input queue and are
5756 available for mapping. The default, off, avoids the mouse movement
5757 overhead except when needed. See |gui-mouse-mapping|.
5758 Warning: Setting this option can make pending mappings to be aborted
5759 when the mouse is moved.
5760 Currently only works in the GUI, may be made to work in a terminal
5761 later.
5762
Bram Moolenaar071d4272004-06-13 20:20:40 +00005763 *'mouseshape'* *'mouses'* *E547*
Bram Moolenaarf6b40102019-02-22 15:24:03 +01005764'mouseshape' 'mouses' string (default "i-r:beam,s:updown,sd:udsizing,
5765 vs:leftright,vd:lrsizing,m:no,
5766 ml:up-arrow,v:rightup-arrow")
Bram Moolenaar071d4272004-06-13 20:20:40 +00005767 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00005768 {only available when compiled with the |+mouseshape|
5769 feature}
5770 This option tells Vim what the mouse pointer should look like in
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01005771 different modes. The option is a comma-separated list of parts, much
Bram Moolenaar071d4272004-06-13 20:20:40 +00005772 like used for 'guicursor'. Each part consist of a mode/location-list
5773 and an argument-list:
5774 mode-list:shape,mode-list:shape,..
5775 The mode-list is a dash separated list of these modes/locations:
5776 In a normal window: ~
5777 n Normal mode
5778 v Visual mode
5779 ve Visual mode with 'selection' "exclusive" (same as 'v',
5780 if not specified)
5781 o Operator-pending mode
5782 i Insert mode
5783 r Replace mode
5784
5785 Others: ~
5786 c appending to the command-line
5787 ci inserting in the command-line
5788 cr replacing in the command-line
5789 m at the 'Hit ENTER' or 'More' prompts
5790 ml idem, but cursor in the last line
5791 e any mode, pointer below last window
5792 s any mode, pointer on a status line
5793 sd any mode, while dragging a status line
5794 vs any mode, pointer on a vertical separator line
5795 vd any mode, while dragging a vertical separator line
5796 a everywhere
5797
5798 The shape is one of the following:
5799 avail name looks like ~
5800 w x arrow Normal mouse pointer
5801 w x blank no pointer at all (use with care!)
5802 w x beam I-beam
5803 w x updown up-down sizing arrows
5804 w x leftright left-right sizing arrows
5805 w x busy The system's usual busy pointer
5806 w x no The system's usual 'no input' pointer
5807 x udsizing indicates up-down resizing
5808 x lrsizing indicates left-right resizing
5809 x crosshair like a big thin +
5810 x hand1 black hand
5811 x hand2 white hand
5812 x pencil what you write with
5813 x question big ?
5814 x rightup-arrow arrow pointing right-up
5815 w x up-arrow arrow pointing up
5816 x <number> any X11 pointer number (see X11/cursorfont.h)
5817
5818 The "avail" column contains a 'w' if the shape is available for Win32,
5819 x for X11.
5820 Any modes not specified or shapes not available use the normal mouse
5821 pointer.
5822
5823 Example: >
5824 :set mouseshape=s:udsizing,m:no
5825< will make the mouse turn to a sizing arrow over the status lines and
5826 indicate no input when the hit-enter prompt is displayed (since
5827 clicking the mouse has no effect in this state.)
5828
5829 *'mousetime'* *'mouset'*
5830'mousetime' 'mouset' number (default 500)
5831 global
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01005832 Only for GUI, Win32 and Unix with xterm. Defines the maximum
Bram Moolenaar071d4272004-06-13 20:20:40 +00005833 time in msec between two mouse clicks for the second click to be
5834 recognized as a multi click.
5835
Bram Moolenaar0ab35b22017-10-08 17:41:37 +02005836 *'mzschemedll'*
5837'mzschemedll' string (default depends on the build)
5838 global
Bram Moolenaar0ab35b22017-10-08 17:41:37 +02005839 {only available when compiled with the |+mzscheme/dyn|
5840 feature}
5841 Specifies the name of the MzScheme shared library. The default is
5842 DYNAMIC_MZSCH_DLL which was specified at compile time.
5843 Environment variables are expanded |:set_env|.
Bram Moolenaarb0d45e72017-11-05 18:19:24 +01005844 The value must be set in the |vimrc| script or earlier. In the
Bram Moolenaar01164a62017-11-02 22:58:42 +01005845 startup, before the |load-plugins| step.
Bram Moolenaar0ab35b22017-10-08 17:41:37 +02005846 This option cannot be set from a |modeline| or in the |sandbox|, for
5847 security reasons.
5848
5849 *'mzschemegcdll'*
5850'mzschemegcdll' string (default depends on the build)
5851 global
Bram Moolenaar0ab35b22017-10-08 17:41:37 +02005852 {only available when compiled with the |+mzscheme/dyn|
5853 feature}
5854 Specifies the name of the MzScheme GC shared library. The default is
5855 DYNAMIC_MZGC_DLL which was specified at compile time.
5856 The value can be equal to 'mzschemedll' if it includes the GC code.
5857 Environment variables are expanded |:set_env|.
5858 This option cannot be set from a |modeline| or in the |sandbox|, for
5859 security reasons.
5860
Bram Moolenaar325b7a22004-07-05 15:58:32 +00005861 *'mzquantum'* *'mzq'*
5862'mzquantum' 'mzq' number (default 100)
5863 global
Bram Moolenaar325b7a22004-07-05 15:58:32 +00005864 {not available when compiled without the |+mzscheme|
5865 feature}
5866 The number of milliseconds between polls for MzScheme threads.
5867 Negative or zero value means no thread scheduling.
Bram Moolenaar036986f2017-03-16 17:41:02 +01005868 NOTE: This option is set to the Vim default value when 'compatible'
5869 is reset.
Bram Moolenaar325b7a22004-07-05 15:58:32 +00005870
Bram Moolenaar071d4272004-06-13 20:20:40 +00005871 *'nrformats'* *'nf'*
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +02005872'nrformats' 'nf' string (default "bin,octal,hex",
5873 set to "bin,hex" in |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00005874 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00005875 This defines what bases Vim will consider for numbers when using the
5876 CTRL-A and CTRL-X commands for adding to and subtracting from a number
5877 respectively; see |CTRL-A| for more info on these commands.
Bram Moolenaar4770d092006-01-12 23:22:24 +00005878 alpha If included, single alphabetical characters will be
Bram Moolenaar071d4272004-06-13 20:20:40 +00005879 incremented or decremented. This is useful for a list with a
Bram Moolenaar3848e002016-03-19 18:42:29 +01005880 letter index a), b), etc. *octal-nrformats*
Bram Moolenaar4770d092006-01-12 23:22:24 +00005881 octal If included, numbers that start with a zero will be considered
Bram Moolenaar071d4272004-06-13 20:20:40 +00005882 to be octal. Example: Using CTRL-A on "007" results in "010".
Bram Moolenaar4770d092006-01-12 23:22:24 +00005883 hex If included, numbers starting with "0x" or "0X" will be
Bram Moolenaar071d4272004-06-13 20:20:40 +00005884 considered to be hexadecimal. Example: Using CTRL-X on
5885 "0x100" results in "0x0ff".
Bram Moolenaar25e4fcd2016-01-09 14:57:47 +01005886 bin If included, numbers starting with "0b" or "0B" will be
5887 considered to be binary. Example: Using CTRL-X on
5888 "0b1000" subtracts one, resulting in "0b0111".
Bram Moolenaaraaad9952020-05-31 15:08:59 +02005889 unsigned If included, numbers are recognized as unsigned. Thus a
5890 leading dash or negative sign won't be considered as part of
5891 the number. Examples:
5892 Using CTRL-X on "2020" in "9-2020" results in "9-2019"
5893 (without "unsigned" it would become "9-2021").
5894 Using CTRL-A on "2020" in "9-2020" results in "9-2021"
5895 (without "unsigned" it would become "9-2019").
Bram Moolenaaracc22402020-06-07 21:07:18 +02005896 Using CTRL-X on "0" or CTRL-A on "18446744073709551615"
5897 (2^64 - 1) has no effect, overflow is prevented.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005898 Numbers which simply begin with a digit in the range 1-9 are always
5899 considered decimal. This also happens for numbers that are not
5900 recognized as octal or hex.
5901
5902 *'number'* *'nu'* *'nonumber'* *'nonu'*
5903'number' 'nu' boolean (default off)
5904 local to window
5905 Print the line number in front of each line. When the 'n' option is
5906 excluded from 'cpoptions' a wrapped line will not use the column of
5907 line numbers (this is the default when 'compatible' isn't set).
Bram Moolenaar592e0a22004-07-03 16:05:59 +00005908 The 'numberwidth' option can be used to set the room used for the line
5909 number.
Bram Moolenaar071d4272004-06-13 20:20:40 +00005910 When a long, wrapped line doesn't start with the first character, '-'
5911 characters are put before the number.
James McCoya80aad72021-12-22 19:45:28 +00005912 For highlighting see |hl-LineNr|, and |hl-CursorLineNr|, and the
5913 |:sign-define| "numhl" argument.
Bram Moolenaar203d04d2013-06-06 21:36:40 +02005914 *number_relativenumber*
5915 The 'relativenumber' option changes the displayed number to be
5916 relative to the cursor. Together with 'number' there are these
5917 four combinations (cursor in line 3):
5918
Bram Moolenaar3848e002016-03-19 18:42:29 +01005919 'nonu' 'nu' 'nonu' 'nu'
Bram Moolenaar203d04d2013-06-06 21:36:40 +02005920 'nornu' 'nornu' 'rnu' 'rnu'
5921
5922 |apple | 1 apple | 2 apple | 2 apple
5923 |pear | 2 pear | 1 pear | 1 pear
5924 |nobody | 3 nobody | 0 nobody |3 nobody
5925 |there | 4 there | 1 there | 1 there
Bram Moolenaar071d4272004-06-13 20:20:40 +00005926
Bram Moolenaar592e0a22004-07-03 16:05:59 +00005927 *'numberwidth'* *'nuw'*
5928'numberwidth' 'nuw' number (Vim default: 4 Vi default: 8)
5929 local to window
Bram Moolenaar325b7a22004-07-05 15:58:32 +00005930 {only available when compiled with the |+linebreak|
5931 feature}
Bram Moolenaar592e0a22004-07-03 16:05:59 +00005932 Minimal number of columns to use for the line number. Only relevant
Bram Moolenaar64486672010-05-16 15:46:46 +02005933 when the 'number' or 'relativenumber' option is set or printing lines
5934 with a line number. Since one space is always between the number and
5935 the text, there is one less character for the number itself.
Bram Moolenaar592e0a22004-07-03 16:05:59 +00005936 The value is the minimum width. A bigger width is used when needed to
Bram Moolenaar64486672010-05-16 15:46:46 +02005937 fit the highest line number in the buffer respectively the number of
5938 rows in the window, depending on whether 'number' or 'relativenumber'
5939 is set. Thus with the Vim default of 4 there is room for a line number
5940 up to 999. When the buffer has 1000 lines five columns will be used.
Bram Moolenaarf8a07122019-07-01 22:06:07 +02005941 The minimum value is 1, the maximum value is 20.
Bram Moolenaar036986f2017-03-16 17:41:02 +01005942 NOTE: This option is set to the Vi default value when 'compatible' is
5943 set and to the Vim default value when 'compatible' is reset.
Bram Moolenaar592e0a22004-07-03 16:05:59 +00005944
Bram Moolenaarf75a9632005-09-13 21:20:47 +00005945 *'omnifunc'* *'ofu'*
5946'omnifunc' 'ofu' string (default: empty)
Bram Moolenaare344bea2005-09-01 20:46:49 +00005947 local to buffer
Bram Moolenaardb84e452010-08-15 13:50:43 +02005948 {not available when compiled without the |+eval|
Bram Moolenaare2c453d2019-08-21 14:37:09 +02005949 feature}
Bram Moolenaarc7486e02005-12-29 22:48:26 +00005950 This option specifies a function to be used for Insert mode omni
5951 completion with CTRL-X CTRL-O. |i_CTRL-X_CTRL-O|
Bram Moolenaar280f1262006-01-30 00:14:18 +00005952 See |complete-functions| for an explanation of how the function is
Yegappan Lakshmanan8658c752021-12-03 11:09:29 +00005953 invoked and what it should return. The value can be the name of a
5954 function, a |lambda| or a |Funcref|. See |option-value-function| for
5955 more information.
Bram Moolenaar043545e2006-10-10 16:44:07 +00005956 This option is usually set by a filetype plugin:
Bram Moolenaar9c102382006-05-03 21:26:49 +00005957 |:filetype-plugin-on|
Bram Moolenaar30b65812012-07-12 22:01:11 +02005958 This option cannot be set from a |modeline| or in the |sandbox|, for
5959 security reasons.
Bram Moolenaare344bea2005-09-01 20:46:49 +00005960
5961
Bram Moolenaar02467872007-05-06 13:22:01 +00005962 *'opendevice'* *'odev'* *'noopendevice'* *'noodev'*
Bram Moolenaar043545e2006-10-10 16:44:07 +00005963'opendevice' 'odev' boolean (default off)
5964 global
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00005965 {only for MS-Windows} *E796*
Bram Moolenaar043545e2006-10-10 16:44:07 +00005966 Enable reading and writing from devices. This may get Vim stuck on a
5967 device that can be opened but doesn't actually do the I/O. Therefore
5968 it is off by default.
5969 Note that on MS-Windows editing "aux.h", "lpt1.txt" and the like also
5970 result in editing a device.
5971
5972
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00005973 *'operatorfunc'* *'opfunc'*
5974'operatorfunc' 'opfunc' string (default: empty)
5975 global
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00005976 This option specifies a function to be called by the |g@| operator.
Yegappan Lakshmanan777175b2021-11-18 22:08:57 +00005977 See |:map-operator| for more info and an example. The value can be
5978 the name of a function, a |lambda| or a |Funcref|. See
5979 |option-value-function| for more information.
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00005980
5981 This option cannot be set from a |modeline| or in the |sandbox|, for
5982 security reasons.
5983
5984
Bram Moolenaar251e1912011-06-19 05:09:16 +02005985 *'osfiletype'* *'oft'*
5986'osfiletype' 'oft' string (default: "")
Bram Moolenaar071d4272004-06-13 20:20:40 +00005987 local to buffer
Bram Moolenaar251e1912011-06-19 05:09:16 +02005988 This option was supported on RISC OS, which has been removed.
5989
Bram Moolenaar071d4272004-06-13 20:20:40 +00005990
Bram Moolenaarf6fee0e2016-02-21 23:02:49 +01005991 *'packpath'* *'pp'*
5992'packpath' 'pp' string (default: see 'runtimepath')
Bram Moolenaarf6fee0e2016-02-21 23:02:49 +01005993 Directories used to find packages. See |packages|.
dkearns8ebdbc92023-10-29 06:26:19 +11005994 This option cannot be set from a |modeline| or in the |sandbox|, for
5995 security reasons.
Bram Moolenaarf6fee0e2016-02-21 23:02:49 +01005996
5997
Bram Moolenaar071d4272004-06-13 20:20:40 +00005998 *'paragraphs'* *'para'*
Bram Moolenaar57e48462008-03-12 16:38:55 +00005999'paragraphs' 'para' string (default "IPLPPPQPP TPHPLIPpLpItpplpipbp")
Bram Moolenaar071d4272004-06-13 20:20:40 +00006000 global
6001 Specifies the nroff macros that separate paragraphs. These are pairs
6002 of two letters (see |object-motions|).
6003
6004 *'paste'* *'nopaste'*
6005'paste' boolean (default off)
6006 global
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006007 Put Vim in Paste mode. This is useful if you want to cut or copy
6008 some text from one window and paste it in Vim. This will avoid
Bram Moolenaar071d4272004-06-13 20:20:40 +00006009 unexpected effects.
6010 Setting this option is useful when using Vim in a terminal, where Vim
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006011 cannot distinguish between typed text and pasted text. In the GUI, Vim
Bram Moolenaar071d4272004-06-13 20:20:40 +00006012 knows about pasting and will mostly do the right thing without 'paste'
6013 being set. The same is true for a terminal where Vim handles the
6014 mouse clicks itself.
Bram Moolenaar2ce06f62005-01-31 19:19:04 +00006015 This option is reset when starting the GUI. Thus if you set it in
6016 your .vimrc it will work in a terminal, but not in the GUI. Setting
6017 'paste' in the GUI has side effects: e.g., the Paste toolbar button
6018 will no longer work in Insert mode, because it uses a mapping.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006019 When the 'paste' option is switched on (also when it was already on):
6020 - mapping in Insert mode and Command-line mode is disabled
6021 - abbreviations are disabled
Bram Moolenaar071d4272004-06-13 20:20:40 +00006022 - 'autoindent' is reset
Bram Moolenaarca635012015-09-25 20:34:21 +02006023 - 'expandtab' is reset
Bram Moolenaar4d8f4762021-06-27 15:18:56 +02006024 - 'hkmap' is reset
Bram Moolenaar071d4272004-06-13 20:20:40 +00006025 - 'revins' is reset
6026 - 'ruler' is reset
6027 - 'showmatch' is reset
Bram Moolenaarca635012015-09-25 20:34:21 +02006028 - 'smarttab' is reset
6029 - 'softtabstop' is set to 0
6030 - 'textwidth' is set to 0
6031 - 'wrapmargin' is set to 0
Bram Moolenaar4d8f4762021-06-27 15:18:56 +02006032 - 'varsofttabstop' is made empty
Bram Moolenaar071d4272004-06-13 20:20:40 +00006033 These options keep their value, but their effect is disabled:
Bram Moolenaar071d4272004-06-13 20:20:40 +00006034 - 'cindent'
Bram Moolenaar4d8f4762021-06-27 15:18:56 +02006035 - 'formatoptions' is used like it is empty
Bram Moolenaarca635012015-09-25 20:34:21 +02006036 - 'indentexpr'
6037 - 'lisp'
Bram Moolenaar4d8f4762021-06-27 15:18:56 +02006038 - 'smartindent'
Bram Moolenaar071d4272004-06-13 20:20:40 +00006039 NOTE: When you start editing another file while the 'paste' option is
6040 on, settings from the modelines or autocommands may change the
6041 settings again, causing trouble when pasting text. You might want to
6042 set the 'paste' option again.
6043 When the 'paste' option is reset the mentioned options are restored to
6044 the value before the moment 'paste' was switched from off to on.
6045 Resetting 'paste' before ever setting it does not have any effect.
6046 Since mapping doesn't work while 'paste' is active, you need to use
6047 the 'pastetoggle' option to toggle the 'paste' option with some key.
6048
6049 *'pastetoggle'* *'pt'*
6050'pastetoggle' 'pt' string (default "")
6051 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006052 When non-empty, specifies the key sequence that toggles the 'paste'
6053 option. This is like specifying a mapping: >
6054 :map {keys} :set invpaste<CR>
6055< Where {keys} is the value of 'pastetoggle'.
6056 The difference is that it will work even when 'paste' is set.
6057 'pastetoggle' works in Insert mode and Normal mode, but not in
6058 Command-line mode.
6059 Mappings are checked first, thus overrule 'pastetoggle'. However,
6060 when 'paste' is on mappings are ignored in Insert mode, thus you can do
6061 this: >
6062 :map <F10> :set paste<CR>
6063 :map <F11> :set nopaste<CR>
6064 :imap <F10> <C-O>:set paste<CR>
6065 :imap <F11> <nop>
6066 :set pastetoggle=<F11>
6067< This will make <F10> start paste mode and <F11> stop paste mode.
6068 Note that typing <F10> in paste mode inserts "<F10>", since in paste
6069 mode everything is inserted literally, except the 'pastetoggle' key
6070 sequence.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006071 When the value has several bytes 'ttimeoutlen' applies.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006072
6073 *'pex'* *'patchexpr'*
6074'patchexpr' 'pex' string (default "")
6075 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006076 {not available when compiled without the |+diff|
6077 feature}
6078 Expression which is evaluated to apply a patch to a file and generate
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006079 the resulting new version of the file. See |diff-patchexpr|.
dkearns8ebdbc92023-10-29 06:26:19 +11006080 This option cannot be set from a |modeline| or in the |sandbox|, for
6081 security reasons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006082
Bram Moolenaardbc28022014-07-26 13:40:44 +02006083 *'patchmode'* *'pm'* *E205* *E206*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006084'patchmode' 'pm' string (default "")
6085 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006086 When non-empty the oldest version of a file is kept. This can be used
6087 to keep the original version of a file if you are changing files in a
6088 source distribution. Only the first time that a file is written a
6089 copy of the original file will be kept. The name of the copy is the
6090 name of the original file with the string in the 'patchmode' option
6091 appended. This option should start with a dot. Use a string like
Bram Moolenaardf980db2017-12-24 13:22:00 +01006092 ".orig" or ".org". 'backupdir' must not be empty for this to work
6093 (Detail: The backup file is renamed to the patchmode file after the
6094 new file has been successfully written, that's why it must be possible
6095 to write a backup file). If there was no file to be backed up, an
6096 empty file is created.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006097 When the 'backupskip' pattern matches, a patchmode file is not made.
6098 Using 'patchmode' for compressed files appends the extension at the
6099 end (e.g., "file.gz.orig"), thus the resulting name isn't always
6100 recognized as a compressed file.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00006101 Only normal file name characters can be used, "/\*?[|<>" are illegal.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006102
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01006103 *'path'* *'pa'* *E343* *E345* *E347* *E854*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006104'path' 'pa' string (default on Unix: ".,/usr/include,,"
Bram Moolenaar071d4272004-06-13 20:20:40 +00006105 other systems: ".,,")
6106 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006107 This is a list of directories which will be searched when using the
Bram Moolenaarc236c162008-07-13 17:41:49 +00006108 |gf|, [f, ]f, ^Wf, |:find|, |:sfind|, |:tabfind| and other commands,
6109 provided that the file being searched for has a relative path (not
6110 starting with "/", "./" or "../"). The directories in the 'path'
6111 option may be relative or absolute.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006112 - Use commas to separate directory names: >
6113 :set path=.,/usr/local/include,/usr/include
6114< - Spaces can also be used to separate directory names (for backwards
6115 compatibility with version 3.0). To have a space in a directory
6116 name, precede it with an extra backslash, and escape the space: >
6117 :set path=.,/dir/with\\\ space
6118< - To include a comma in a directory name precede it with an extra
6119 backslash: >
6120 :set path=.,/dir/with\\,comma
6121< - To search relative to the directory of the current file, use: >
6122 :set path=.
6123< - To search in the current directory use an empty string between two
6124 commas: >
6125 :set path=,,
6126< - A directory name may end in a ':' or '/'.
6127 - Environment variables are expanded |:set_env|.
6128 - When using |netrw.vim| URLs can be used. For example, adding
6129 "http://www.vim.org" will make ":find index.html" work.
Bram Moolenaarc236c162008-07-13 17:41:49 +00006130 - Search upwards and downwards in a directory tree using "*", "**" and
6131 ";". See |file-searching| for info and syntax.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006132 - Careful with '\' characters, type two to get one in the option: >
6133 :set path=.,c:\\include
6134< Or just use '/' instead: >
6135 :set path=.,c:/include
6136< Don't forget "." or files won't even be found in the same directory as
6137 the file!
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006138 The maximum length is limited. How much depends on the system, mostly
Bram Moolenaar071d4272004-06-13 20:20:40 +00006139 it is something like 256 or 1024 characters.
6140 You can check if all the include files are found, using the value of
6141 'path', see |:checkpath|.
6142 The use of |:set+=| and |:set-=| is preferred when adding or removing
6143 directories from the list. This avoids problems when a future version
6144 uses another default. To remove the current directory use: >
6145 :set path-=
6146< To add the current directory use: >
6147 :set path+=
6148< To use an environment variable, you probably need to replace the
6149 separator. Here is an example to append $INCL, in which directory
6150 names are separated with a semi-colon: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00006151 :let &path = &path .. "," .. substitute($INCL, ';', ',', 'g')
Bram Moolenaar071d4272004-06-13 20:20:40 +00006152< Replace the ';' with a ':' or whatever separator is used. Note that
6153 this doesn't work when $INCL contains a comma or white space.
6154
Bram Moolenaar37c64c72017-09-19 22:06:03 +02006155 *'perldll'*
6156'perldll' string (default depends on the build)
6157 global
Bram Moolenaar37c64c72017-09-19 22:06:03 +02006158 {only available when compiled with the |+perl/dyn|
6159 feature}
6160 Specifies the name of the Perl shared library. The default is
6161 DYNAMIC_PERL_DLL, which was specified at compile time.
6162 Environment variables are expanded |:set_env|.
6163 This option cannot be set from a |modeline| or in the |sandbox|, for
6164 security reasons.
6165
Bram Moolenaar071d4272004-06-13 20:20:40 +00006166 *'preserveindent'* *'pi'* *'nopreserveindent'* *'nopi'*
6167'preserveindent' 'pi' boolean (default off)
6168 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00006169 When changing the indent of the current line, preserve as much of the
6170 indent structure as possible. Normally the indent is replaced by a
6171 series of tabs followed by spaces as required (unless |'expandtab'| is
6172 enabled, in which case only spaces are used). Enabling this option
6173 means the indent will preserve as many existing characters as possible
6174 for indenting, and only add additional tabs or spaces as required.
Bram Moolenaar446cb832008-06-24 21:56:24 +00006175 'expandtab' does not apply to the preserved white space, a Tab remains
6176 a Tab.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006177 NOTE: When using ">>" multiple times the resulting indent is a mix of
6178 tabs and spaces. You might not like this.
Bram Moolenaar036986f2017-03-16 17:41:02 +01006179 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006180 Also see 'copyindent'.
6181 Use |:retab| to clean up white space.
6182
6183 *'previewheight'* *'pvh'*
6184'previewheight' 'pvh' number (default 12)
6185 global
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02006186 {not available when compiled without the |+quickfix|
6187 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00006188 Default height for a preview window. Used for |:ptag| and associated
Bram Moolenaar79648732019-07-18 21:43:07 +02006189 commands. Used for |CTRL-W_}| when no count is given. Not used when
6190 'previewpopup' is set.
6191
6192 *'previewpopup'* *'pvp'*
6193'previewpopup' 'pvp' string (default empty)
6194 global
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02006195 {not available when compiled without the |+textprop|
6196 or |+quickfix| feature}
Bram Moolenaar79648732019-07-18 21:43:07 +02006197 When not empty a popup window is used for commands that would open a
6198 preview window. See |preview-popup|.
Bram Moolenaar576a4a62019-08-18 15:25:17 +02006199 Not used for the insert completion info, add "popup" to
6200 'completeopt' for that.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006201
6202 *'previewwindow'* *'nopreviewwindow'*
6203 *'pvw'* *'nopvw'* *E590*
6204'previewwindow' 'pvw' boolean (default off)
Christian Brabandt596ad662023-08-16 00:11:09 +02006205 local to window |local-noglobal|
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02006206 {not available when compiled without the |+quickfix|
6207 feature}
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006208 Identifies the preview window. Only one window can have this option
Bram Moolenaar071d4272004-06-13 20:20:40 +00006209 set. It's normally not set directly, but by using one of the commands
6210 |:ptag|, |:pedit|, etc.
6211
6212 *'printdevice'* *'pdev'*
6213'printdevice' 'pdev' string (default empty)
6214 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006215 {only available when compiled with the |+printer|
6216 feature}
Bram Moolenaar8299df92004-07-10 09:47:34 +00006217 The name of the printer to be used for |:hardcopy|.
6218 See |pdev-option|.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00006219 This option cannot be set from a |modeline| or in the |sandbox|, for
6220 security reasons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006221
Bram Moolenaar8299df92004-07-10 09:47:34 +00006222 *'printencoding'* *'penc'*
Bram Moolenaar95bafa22018-10-02 13:26:25 +02006223'printencoding' 'penc' string (default empty, except for some systems)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006224 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006225 {only available when compiled with the |+printer|
6226 and |+postscript| features}
Bram Moolenaar8299df92004-07-10 09:47:34 +00006227 Sets the character encoding used when printing.
6228 See |penc-option|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006229
6230 *'printexpr'* *'pexpr'*
Bram Moolenaar95bafa22018-10-02 13:26:25 +02006231'printexpr' 'pexpr' string (default: see below)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006232 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006233 {only available when compiled with the |+printer|
6234 and |+postscript| features}
Bram Moolenaar8299df92004-07-10 09:47:34 +00006235 Expression used to print the PostScript produced with |:hardcopy|.
6236 See |pexpr-option|.
Bram Moolenaar51628222016-12-01 23:03:28 +01006237 This option cannot be set from a |modeline| or in the |sandbox|, for
6238 security reasons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006239
Bram Moolenaar8299df92004-07-10 09:47:34 +00006240 *'printfont'* *'pfn'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006241'printfont' 'pfn' string (default "courier")
6242 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006243 {only available when compiled with the |+printer|
6244 feature}
Bram Moolenaar8299df92004-07-10 09:47:34 +00006245 The name of the font that will be used for |:hardcopy|.
6246 See |pfn-option|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006247
6248 *'printheader'* *'pheader'*
6249'printheader' 'pheader' string (default "%<%f%h%m%=Page %N")
6250 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006251 {only available when compiled with the |+printer|
6252 feature}
Bram Moolenaar8299df92004-07-10 09:47:34 +00006253 The format of the header produced in |:hardcopy| output.
6254 See |pheader-option|.
6255
6256 *'printmbcharset'* *'pmbcs'*
6257'printmbcharset' 'pmbcs' string (default "")
6258 global
Bram Moolenaar4c92e752019-02-17 21:18:32 +01006259 {only available when compiled with the |+printer|
6260 and |+postscript| features}
Bram Moolenaar8299df92004-07-10 09:47:34 +00006261 The CJK character set to be used for CJK output from |:hardcopy|.
6262 See |pmbcs-option|.
6263
6264 *'printmbfont'* *'pmbfn'*
6265'printmbfont' 'pmbfn' string (default "")
6266 global
Bram Moolenaar4c92e752019-02-17 21:18:32 +01006267 {only available when compiled with the |+printer|
6268 and |+postscript| features}
Bram Moolenaar8299df92004-07-10 09:47:34 +00006269 List of font names to be used for CJK output from |:hardcopy|.
6270 See |pmbfn-option|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006271
6272 *'printoptions'* *'popt'*
6273'printoptions' 'popt' string (default "")
6274 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006275 {only available when compiled with |+printer| feature}
Bram Moolenaar8299df92004-07-10 09:47:34 +00006276 List of items that control the format of the output of |:hardcopy|.
6277 See |popt-option|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006278
Bram Moolenaar26a60b42005-02-22 08:49:11 +00006279 *'prompt'* *'noprompt'*
6280'prompt' boolean (default on)
6281 global
6282 When on a ":" prompt is used in Ex mode.
6283
Bram Moolenaar7d47b6e2006-03-15 22:59:18 +00006284 *'pumheight'* *'ph'*
6285'pumheight' 'ph' number (default 0)
6286 global
Bram Moolenaar06a89a52006-04-29 22:01:03 +00006287 Determines the maximum number of items to show in the popup menu for
6288 Insert mode completion. When zero as much space as available is used.
Bram Moolenaar7d47b6e2006-03-15 22:59:18 +00006289 |ins-completion-menu|.
6290
Bram Moolenaara8f04aa2018-02-10 15:36:55 +01006291 *'pumwidth'* *'pw'*
Bram Moolenaarcafafb32018-02-22 21:07:09 +01006292'pumwidth' 'pw' number (default 15)
Bram Moolenaara8f04aa2018-02-10 15:36:55 +01006293 global
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01006294 Determines the minimum width to use for the popup menu for Insert mode
Bram Moolenaarcafafb32018-02-22 21:07:09 +01006295 completion. |ins-completion-menu|.
Bram Moolenaara8f04aa2018-02-10 15:36:55 +01006296
Bram Moolenaard94464e2015-11-02 15:28:18 +01006297 *'pythondll'*
Bram Moolenaar3848e002016-03-19 18:42:29 +01006298'pythondll' string (default depends on the build)
Bram Moolenaard94464e2015-11-02 15:28:18 +01006299 global
Bram Moolenaard94464e2015-11-02 15:28:18 +01006300 {only available when compiled with the |+python/dyn|
6301 feature}
Bram Moolenaar25e4fcd2016-01-09 14:57:47 +01006302 Specifies the name of the Python 2.x shared library. The default is
6303 DYNAMIC_PYTHON_DLL, which was specified at compile time.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02006304 Environment variables are expanded |:set_env|.
Bram Moolenaard94464e2015-11-02 15:28:18 +01006305 This option cannot be set from a |modeline| or in the |sandbox|, for
6306 security reasons.
Bram Moolenaar7d47b6e2006-03-15 22:59:18 +00006307
Bram Moolenaar94073162018-01-31 21:49:05 +01006308 *'pythonhome'*
6309'pythonhome' string (default "")
6310 global
Bram Moolenaar94073162018-01-31 21:49:05 +01006311 {only available when compiled with the |+python/dyn|
6312 feature}
6313 Specifies the name of the Python 2.x home directory. When 'pythonhome'
6314 and the PYTHONHOME environment variable are not set, PYTHON_HOME,
6315 which was specified at compile time, will be used for the Python 2.x
6316 home directory.
6317 Environment variables are expanded |:set_env|.
6318 This option cannot be set from a |modeline| or in the |sandbox|, for
6319 security reasons.
6320
Bram Moolenaarb4ff5182015-11-10 21:15:48 +01006321 *'pythonthreedll'*
Bram Moolenaar25e4fcd2016-01-09 14:57:47 +01006322'pythonthreedll' string (default depends on the build)
Bram Moolenaarb4ff5182015-11-10 21:15:48 +01006323 global
Bram Moolenaarb4ff5182015-11-10 21:15:48 +01006324 {only available when compiled with the |+python3/dyn|
6325 feature}
Bram Moolenaar25e4fcd2016-01-09 14:57:47 +01006326 Specifies the name of the Python 3 shared library. The default is
6327 DYNAMIC_PYTHON3_DLL, which was specified at compile time.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02006328 Environment variables are expanded |:set_env|.
Bram Moolenaarb4ff5182015-11-10 21:15:48 +01006329 This option cannot be set from a |modeline| or in the |sandbox|, for
6330 security reasons.
6331
Bram Moolenaar94073162018-01-31 21:49:05 +01006332 *'pythonthreehome'*
6333'pythonthreehome' string (default "")
6334 global
Bram Moolenaar94073162018-01-31 21:49:05 +01006335 {only available when compiled with the |+python3/dyn|
6336 feature}
6337 Specifies the name of the Python 3 home directory. When
6338 'pythonthreehome' and the PYTHONHOME environment variable are not set,
6339 PYTHON3_HOME, which was specified at compile time, will be used for
6340 the Python 3 home directory.
6341 Environment variables are expanded |:set_env|.
6342 This option cannot be set from a |modeline| or in the |sandbox|, for
6343 security reasons.
6344
Bram Moolenaarf42dd3c2017-01-28 16:06:38 +01006345 *'pyxversion'* *'pyx'*
6346'pyxversion' 'pyx' number (default depends on the build)
6347 global
Bram Moolenaarf42dd3c2017-01-28 16:06:38 +01006348 {only available when compiled with the |+python| or
6349 the |+python3| feature}
6350 Specifies the python version used for pyx* functions and commands
6351 |python_x|. The default value is as follows:
6352
6353 Compiled with Default ~
6354 |+python| and |+python3| 0
6355 only |+python| 2
6356 only |+python3| 3
6357
6358 Available values are 0, 2 and 3.
6359 If 'pyxversion' is 0, it is set to 2 or 3 after the first execution of
6360 any python2/3 commands or functions. E.g. `:py` sets to 2, and `:py3`
6361 sets to 3. `:pyx` sets it to 3 if Python 3 is available, otherwise sets
6362 to 2 if Python 2 is available.
6363 See also: |has-pythonx|
6364
6365 If Vim is compiled with only |+python| or |+python3| setting
6366 'pyxversion' has no effect. The pyx* functions and commands are
6367 always the same as the compiled version.
6368
6369 This option cannot be set from a |modeline| or in the |sandbox|, for
6370 security reasons.
6371
Bram Moolenaar858ba062020-05-31 23:11:59 +02006372 *'quickfixtextfunc'* *'qftf'*
6373'quickfixtextfunc' 'qftf' string (default "")
6374 global
6375 {only available when compiled with the |+quickfix|
6376 feature}
6377 This option specifies a function to be used to get the text to display
6378 in the quickfix and location list windows. This can be used to
6379 customize the information displayed in the quickfix or location window
6380 for each entry in the corresponding quickfix or location list. See
6381 |quickfix-window-function| for an explanation of how to write the
Yegappan Lakshmanan777175b2021-11-18 22:08:57 +00006382 function and an example. The value can be the name of a function, a
6383 |lambda| or a |Funcref|. See |option-value-function| for more
6384 information.
Bram Moolenaar858ba062020-05-31 23:11:59 +02006385
6386 This option cannot be set from a |modeline| or in the |sandbox|, for
6387 security reasons.
6388
Bram Moolenaar677ee682005-01-27 14:41:15 +00006389 *'quoteescape'* *'qe'*
Bram Moolenaarcfbc5ee2004-07-02 15:38:35 +00006390'quoteescape' 'qe' string (default "\")
6391 local to buffer
Bram Moolenaarcfbc5ee2004-07-02 15:38:35 +00006392 The characters that are used to escape quotes in a string. Used for
6393 objects like a', a" and a` |a'|.
6394 When one of the characters in this option is found inside a string,
6395 the following character will be skipped. The default value makes the
6396 text "foo\"bar\\" considered to be one string.
6397
Bram Moolenaar071d4272004-06-13 20:20:40 +00006398 *'readonly'* *'ro'* *'noreadonly'* *'noro'*
6399'readonly' 'ro' boolean (default off)
Christian Brabandt596ad662023-08-16 00:11:09 +02006400 local to buffer |local-noglobal|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006401 If on, writes fail unless you use a '!'. Protects you from
6402 accidentally overwriting a file. Default on when Vim is started
6403 in read-only mode ("vim -R") or when the executable is called "view".
Bram Moolenaar4399ef42005-02-12 14:29:27 +00006404 When using ":w!" the 'readonly' option is reset for the current
6405 buffer, unless the 'Z' flag is in 'cpoptions'.
Bram Moolenaar6c60f472019-04-28 16:00:35 +02006406 When using the ":view" command the 'readonly' option is set for the
6407 newly edited buffer.
Bram Moolenaar369b6f52017-01-17 12:22:32 +01006408 See 'modifiable' for disallowing changes to the buffer.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006409
Bram Moolenaar91a4e822008-01-19 14:59:58 +00006410 *'redrawtime'* *'rdt'*
6411'redrawtime' 'rdt' number (default 2000)
6412 global
Bram Moolenaar91a4e822008-01-19 14:59:58 +00006413 {only available when compiled with the |+reltime|
6414 feature}
6415 The time in milliseconds for redrawing the display. This applies to
Bram Moolenaar15142e22018-04-30 22:19:58 +02006416 searching for patterns for 'hlsearch', |:match| highlighting and syntax
Bram Moolenaar06f1ed22017-06-18 22:41:03 +02006417 highlighting.
Bram Moolenaar91a4e822008-01-19 14:59:58 +00006418 When redrawing takes more than this many milliseconds no further
Bram Moolenaar06f1ed22017-06-18 22:41:03 +02006419 matches will be highlighted.
6420 For syntax highlighting the time applies per window. When over the
6421 limit syntax highlighting is disabled until |CTRL-L| is used.
6422 This is used to avoid that Vim hangs when using a very complicated
6423 pattern.
Bram Moolenaar91a4e822008-01-19 14:59:58 +00006424
Bram Moolenaar543b7ef2013-06-01 14:50:56 +02006425 *'regexpengine'* *'re'*
Bram Moolenaare6ae6222013-05-21 21:01:10 +02006426'regexpengine' 're' number (default 0)
6427 global
Bram Moolenaare6ae6222013-05-21 21:01:10 +02006428 This selects the default regexp engine. |two-engines|
6429 The possible values are:
6430 0 automatic selection
6431 1 old engine
6432 2 NFA engine
6433 Note that when using the NFA engine and the pattern contains something
6434 that is not supported the pattern will not match. This is only useful
6435 for debugging the regexp engine.
Bram Moolenaarfda37292014-11-05 14:27:36 +01006436 Using automatic selection enables Vim to switch the engine, if the
6437 default engine becomes too costly. E.g., when the NFA engine uses too
6438 many states. This should prevent Vim from hanging on a combination of
6439 a complex pattern with long text.
Bram Moolenaare6ae6222013-05-21 21:01:10 +02006440
Bram Moolenaar64486672010-05-16 15:46:46 +02006441 *'relativenumber'* *'rnu'* *'norelativenumber'* *'nornu'*
6442'relativenumber' 'rnu' boolean (default off)
6443 local to window
Bram Moolenaar64486672010-05-16 15:46:46 +02006444 Show the line number relative to the line with the cursor in front of
Bram Moolenaar06b5d512010-05-22 15:37:44 +02006445 each line. Relative line numbers help you use the |count| you can
Bram Moolenaar64486672010-05-16 15:46:46 +02006446 precede some vertical motion commands (e.g. j k + -) with, without
6447 having to calculate it yourself. Especially useful in combination with
6448 other commands (e.g. y d c < > gq gw =).
6449 When the 'n' option is excluded from 'cpoptions' a wrapped
6450 line will not use the column of line numbers (this is the default when
6451 'compatible' isn't set).
6452 The 'numberwidth' option can be used to set the room used for the line
6453 number.
6454 When a long, wrapped line doesn't start with the first character, '-'
6455 characters are put before the number.
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02006456 See |hl-LineNr| and |hl-CursorLineNr| for the highlighting used for
6457 the number.
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01006458
Bram Moolenaar203d04d2013-06-06 21:36:40 +02006459 The number in front of the cursor line also depends on the value of
6460 'number', see |number_relativenumber| for all combinations of the two
6461 options.
Bram Moolenaar64486672010-05-16 15:46:46 +02006462
Bram Moolenaar071d4272004-06-13 20:20:40 +00006463 *'remap'* *'noremap'*
6464'remap' boolean (default on)
6465 global
6466 Allows for mappings to work recursively. If you do not want this for
6467 a single entry, use the :noremap[!] command.
Bram Moolenaara3227e22006-03-08 21:32:40 +00006468 NOTE: To avoid portability problems with Vim scripts, always keep
6469 this option at the default "on". Only switch it off when working with
6470 old Vi scripts.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006471
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02006472 *'renderoptions'* *'rop'*
6473'renderoptions' 'rop' string (default: empty)
6474 global
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02006475 {only available when compiled with GUI and DIRECTX on
6476 MS-Windows}
6477 Select a text renderer and set its options. The options depend on the
6478 renderer.
6479
6480 Syntax: >
6481 set rop=type:{renderer}(,{name}:{value})*
6482<
6483 Currently, only one optional renderer is available.
6484
6485 render behavior ~
6486 directx Vim will draw text using DirectX (DirectWrite). It makes
6487 drawn glyphs more beautiful than default GDI.
6488 It requires 'encoding' is "utf-8", and only works on
6489 MS-Windows Vista or newer version.
6490
6491 Options:
6492 name meaning type value ~
6493 gamma gamma float 1.0 - 2.2 (maybe)
6494 contrast enhancedContrast float (unknown)
6495 level clearTypeLevel float (unknown)
6496 geom pixelGeometry int 0 - 2 (see below)
6497 renmode renderingMode int 0 - 6 (see below)
6498 taamode textAntialiasMode int 0 - 3 (see below)
Bram Moolenaara338adc2018-01-31 20:51:47 +01006499 scrlines Scroll Lines int (deprecated)
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02006500
Bram Moolenaar92467d32017-12-05 13:22:16 +01006501 See this URL for detail (except for scrlines):
6502 https://msdn.microsoft.com/en-us/library/dd368190.aspx
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02006503
6504 For geom: structure of a device pixel.
6505 0 - DWRITE_PIXEL_GEOMETRY_FLAT
6506 1 - DWRITE_PIXEL_GEOMETRY_RGB
6507 2 - DWRITE_PIXEL_GEOMETRY_BGR
6508
6509 See this URL for detail:
Bram Moolenaar92467d32017-12-05 13:22:16 +01006510 https://msdn.microsoft.com/en-us/library/dd368114.aspx
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02006511
6512 For renmode: method of rendering glyphs.
6513 0 - DWRITE_RENDERING_MODE_DEFAULT
6514 1 - DWRITE_RENDERING_MODE_ALIASED
6515 2 - DWRITE_RENDERING_MODE_GDI_CLASSIC
6516 3 - DWRITE_RENDERING_MODE_GDI_NATURAL
6517 4 - DWRITE_RENDERING_MODE_NATURAL
6518 5 - DWRITE_RENDERING_MODE_NATURAL_SYMMETRIC
6519 6 - DWRITE_RENDERING_MODE_OUTLINE
6520
6521 See this URL for detail:
Bram Moolenaar92467d32017-12-05 13:22:16 +01006522 https://msdn.microsoft.com/en-us/library/dd368118.aspx
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02006523
6524 For taamode: antialiasing mode used for drawing text.
6525 0 - D2D1_TEXT_ANTIALIAS_MODE_DEFAULT
6526 1 - D2D1_TEXT_ANTIALIAS_MODE_CLEARTYPE
6527 2 - D2D1_TEXT_ANTIALIAS_MODE_GRAYSCALE
6528 3 - D2D1_TEXT_ANTIALIAS_MODE_ALIASED
6529
6530 See this URL for detail:
Bram Moolenaar92467d32017-12-05 13:22:16 +01006531 https://msdn.microsoft.com/en-us/library/dd368170.aspx
6532
Bram Moolenaara338adc2018-01-31 20:51:47 +01006533 For scrlines:
6534 This was used for optimizing scrolling behavior, however this
6535 is now deprecated. If specified, it is simply ignored.
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02006536
6537 Example: >
6538 set encoding=utf-8
Bram Moolenaard7ccc4d2017-11-26 14:29:32 +01006539 set gfn=Ricty_Diminished:h12
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02006540 set rop=type:directx
6541<
Bram Moolenaard7ccc4d2017-11-26 14:29:32 +01006542 If select a raster font (Courier, Terminal or FixedSys which
6543 have ".fon" extension in file name) to 'guifont', it will be
Bram Moolenaar92467d32017-12-05 13:22:16 +01006544 drawn by GDI as a fallback.
Bram Moolenaard7ccc4d2017-11-26 14:29:32 +01006545
6546 NOTE: It is known that some fonts and options combination
6547 causes trouble on drawing glyphs.
6548
Bram Moolenaar92467d32017-12-05 13:22:16 +01006549 - 'renmode:5' and 'renmode:6' will not work with some
Bram Moolenaard7ccc4d2017-11-26 14:29:32 +01006550 special made fonts (True-Type fonts which includes only
6551 bitmap glyphs).
6552 - 'taamode:3' will not work with some vector fonts.
6553
6554 NOTE: With this option, you can display colored emoji
6555 (emoticon) in Windows 8.1 or later. To display colored emoji,
6556 there are some conditions which you should notice.
6557
6558 - If your font includes non-colored emoji already, it will
6559 be used.
6560 - If your font doesn't have emoji, the system chooses an
6561 alternative symbol font. On Windows 10, "Segoe UI Emoji"
6562 will be used.
6563 - When this alternative font didn't have fixed width glyph,
6564 emoji might be rendered beyond the bounding box of drawing
6565 cell.
Bram Moolenaarb5a7a8b2014-08-06 14:52:30 +02006566
6567 Other render types are currently not supported.
6568
Bram Moolenaar071d4272004-06-13 20:20:40 +00006569 *'report'*
6570'report' number (default 2)
6571 global
6572 Threshold for reporting number of lines changed. When the number of
6573 changed lines is more than 'report' a message will be given for most
6574 ":" commands. If you want it always, set 'report' to 0.
6575 For the ":substitute" command the number of substitutions is used
6576 instead of the number of lines.
6577
6578 *'restorescreen'* *'rs'* *'norestorescreen'* *'nors'*
6579'restorescreen' 'rs' boolean (default on)
6580 global
Bram Moolenaar8024f932020-01-14 19:29:13 +01006581 {only in MS-Windows console version}
Bram Moolenaar071d4272004-06-13 20:20:40 +00006582 When set, the screen contents is restored when exiting Vim. This also
6583 happens when executing external commands.
6584
6585 For non-Windows Vim: You can set or reset the 't_ti' and 't_te'
6586 options in your .vimrc. To disable restoring:
6587 set t_ti= t_te=
6588 To enable restoring (for an xterm):
6589 set t_ti=^[7^[[r^[[?47h t_te=^[[?47l^[8
6590 (Where ^[ is an <Esc>, type CTRL-V <Esc> to insert it)
6591
6592 *'revins'* *'ri'* *'norevins'* *'nori'*
6593'revins' 'ri' boolean (default off)
6594 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006595 {only available when compiled with the |+rightleft|
6596 feature}
6597 Inserting characters in Insert mode will work backwards. See "typing
6598 backwards" |ins-reverse|. This option can be toggled with the CTRL-_
6599 command in Insert mode, when 'allowrevins' is set.
Bram Moolenaarca635012015-09-25 20:34:21 +02006600 NOTE: This option is reset when 'compatible' is set.
6601 This option is reset when 'paste' is set and restored when 'paste' is
6602 reset.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006603
6604 *'rightleft'* *'rl'* *'norightleft'* *'norl'*
6605'rightleft' 'rl' boolean (default off)
6606 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00006607 {only available when compiled with the |+rightleft|
6608 feature}
6609 When on, display orientation becomes right-to-left, i.e., characters
6610 that are stored in the file appear from the right to the left.
6611 Using this option, it is possible to edit files for languages that
6612 are written from the right to the left such as Hebrew and Arabic.
6613 This option is per window, so it is possible to edit mixed files
6614 simultaneously, or to view the same file in both ways (this is
6615 useful whenever you have a mixed text file with both right-to-left
6616 and left-to-right strings so that both sets are displayed properly
6617 in different windows). Also see |rileft.txt|.
6618
Bram Moolenaar607cc1e2010-07-18 18:47:44 +02006619 *'rightleftcmd'* *'rlc'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00006620'rightleftcmd' 'rlc' string (default "search")
6621 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00006622 {only available when compiled with the |+rightleft|
6623 feature}
6624 Each word in this option enables the command line editing to work in
6625 right-to-left mode for a group of commands:
6626
6627 search "/" and "?" commands
6628
6629 This is useful for languages such as Hebrew, Arabic and Farsi.
6630 The 'rightleft' option must be set for 'rightleftcmd' to take effect.
6631
Bram Moolenaard94464e2015-11-02 15:28:18 +01006632 *'rubydll'*
Bram Moolenaar3848e002016-03-19 18:42:29 +01006633'rubydll' string (default: depends on the build)
Bram Moolenaard94464e2015-11-02 15:28:18 +01006634 global
Bram Moolenaard94464e2015-11-02 15:28:18 +01006635 {only available when compiled with the |+ruby/dyn|
6636 feature}
Bram Moolenaar25e4fcd2016-01-09 14:57:47 +01006637 Specifies the name of the Ruby shared library. The default is
6638 DYNAMIC_RUBY_DLL, which was specified at compile time.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02006639 Environment variables are expanded |:set_env|.
Bram Moolenaard94464e2015-11-02 15:28:18 +01006640 This option cannot be set from a |modeline| or in the |sandbox|, for
6641 security reasons.
6642
Bram Moolenaar071d4272004-06-13 20:20:40 +00006643 *'ruler'* *'ru'* *'noruler'* *'noru'*
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +02006644'ruler' 'ru' boolean (default off, set in |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00006645 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006646 Show the line and column number of the cursor position, separated by a
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006647 comma. When there is room, the relative position of the displayed
Bram Moolenaar071d4272004-06-13 20:20:40 +00006648 text in the file is shown on the far right:
6649 Top first line is visible
6650 Bot last line is visible
6651 All first and last line are visible
6652 45% relative position in the file
6653 If 'rulerformat' is set, it will determine the contents of the ruler.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006654 Each window has its own ruler. If a window has a status line, the
Bram Moolenaara2a89732022-08-31 14:46:18 +01006655 ruler is shown there. Otherwise it is shown in the last line of the
6656 screen. If the statusline is given by 'statusline' (i.e. not empty),
6657 this option takes precedence over 'ruler' and 'rulerformat'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006658 If the number of characters displayed is different from the number of
Bram Moolenaar207f0092020-08-30 17:20:20 +02006659 bytes in the text (e.g., for a TAB or a multibyte character), both
Bram Moolenaar071d4272004-06-13 20:20:40 +00006660 the text column (byte number) and the screen column are shown,
6661 separated with a dash.
6662 For an empty line "0-1" is shown.
6663 For an empty buffer the line number will also be zero: "0,0-1".
Bram Moolenaarca635012015-09-25 20:34:21 +02006664 This option is reset when 'paste' is set and restored when 'paste' is
6665 reset.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006666 If you don't want to see the ruler all the time but want to know where
6667 you are, use "g CTRL-G" |g_CTRL-G|.
6668 NOTE: This option is reset when 'compatible' is set.
6669
6670 *'rulerformat'* *'ruf'*
6671'rulerformat' 'ruf' string (default empty)
6672 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006673 {not available when compiled without the |+statusline|
6674 feature}
6675 When this option is not empty, it determines the content of the ruler
6676 string, as displayed for the 'ruler' option.
Bram Moolenaara23ccb82006-02-27 00:08:02 +00006677 The format of this option is like that of 'statusline'.
Bram Moolenaar110289e2019-05-23 15:38:06 +02006678 This option cannot be set in a modeline when 'modelineexpr' is off.
6679
Bram Moolenaar071d4272004-06-13 20:20:40 +00006680 The default ruler width is 17 characters. To make the ruler 15
6681 characters wide, put "%15(" at the start and "%)" at the end.
6682 Example: >
6683 :set rulerformat=%15(%c%V\ %p%%%)
6684<
6685 *'runtimepath'* *'rtp'* *vimfiles*
6686'runtimepath' 'rtp' string (default:
Bram Moolenaar942db232021-02-13 18:14:48 +01006687 Unix: "$HOME/.vim,
Bram Moolenaar071d4272004-06-13 20:20:40 +00006688 $VIM/vimfiles,
6689 $VIMRUNTIME,
6690 $VIM/vimfiles/after,
6691 $HOME/.vim/after"
6692 Amiga: "home:vimfiles,
6693 $VIM/vimfiles,
6694 $VIMRUNTIME,
6695 $VIM/vimfiles/after,
6696 home:vimfiles/after"
Bram Moolenaar942db232021-02-13 18:14:48 +01006697 MS-Windows: "$HOME/vimfiles,
Bram Moolenaar071d4272004-06-13 20:20:40 +00006698 $VIM/vimfiles,
6699 $VIMRUNTIME,
6700 $VIM/vimfiles/after,
6701 $HOME/vimfiles/after"
Bram Moolenaar3d1cde82020-08-15 18:55:18 +02006702 macOS: "$VIM:vimfiles,
Bram Moolenaar071d4272004-06-13 20:20:40 +00006703 $VIMRUNTIME,
6704 $VIM:vimfiles:after"
Bram Moolenaarb3f74062020-02-26 16:16:53 +01006705 Haiku: "$BE_USER_SETTINGS/vim,
6706 $VIM/vimfiles,
6707 $VIMRUNTIME,
6708 $VIM/vimfiles/after,
Bram Moolenaar942db232021-02-13 18:14:48 +01006709 $BE_USER_SETTINGS/vim/after"
6710 VMS: "sys$login:vimfiles,
Bram Moolenaar071d4272004-06-13 20:20:40 +00006711 $VIM/vimfiles,
6712 $VIMRUNTIME,
6713 $VIM/vimfiles/after,
Bram Moolenaar582fd852005-03-28 20:58:01 +00006714 sys$login:vimfiles/after")
Bram Moolenaar071d4272004-06-13 20:20:40 +00006715 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006716 This is a list of directories which will be searched for runtime
6717 files:
6718 filetype.vim filetypes by file name |new-filetype|
6719 scripts.vim filetypes by file contents |new-filetype-scripts|
Bram Moolenaar4399ef42005-02-12 14:29:27 +00006720 autoload/ automatically loaded scripts |autoload-functions|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006721 colors/ color scheme files |:colorscheme|
6722 compiler/ compiler files |:compiler|
6723 doc/ documentation |write-local-help|
6724 ftplugin/ filetype plugins |write-filetype-plugin|
Bram Moolenaar8a7d6542020-01-26 15:56:19 +01006725 import/ files that are found by `:import`
Bram Moolenaar071d4272004-06-13 20:20:40 +00006726 indent/ indent scripts |indent-expression|
6727 keymap/ key mapping files |mbyte-keymap|
6728 lang/ menu translations |:menutrans|
6729 menu.vim GUI menus |menu.vim|
Bram Moolenaar26852122016-05-24 20:02:38 +02006730 pack/ packages |:packadd|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006731 plugin/ plugin scripts |write-plugin|
6732 print/ files for printing |postscript-print-encoding|
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +00006733 spell/ spell checking files |spell|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006734 syntax/ syntax files |mysyntaxfile|
6735 tutor/ files for vimtutor |tutor|
6736
6737 And any other file searched for with the |:runtime| command.
6738
6739 The defaults for most systems are setup to search five locations:
6740 1. In your home directory, for your personal preferences.
6741 2. In a system-wide Vim directory, for preferences from the system
6742 administrator.
6743 3. In $VIMRUNTIME, for files distributed with Vim.
6744 *after-directory*
6745 4. In the "after" directory in the system-wide Vim directory. This is
6746 for the system administrator to overrule or add to the distributed
6747 defaults (rarely needed)
6748 5. In the "after" directory in your home directory. This is for
6749 personal preferences to overrule or add to the distributed defaults
6750 or system-wide settings (rarely needed).
6751
Bram Moolenaard0796902016-09-16 20:02:31 +02006752 More entries are added when using |packages|. If it gets very long
6753 then `:set rtp` will be truncated, use `:echo &rtp` to see the full
6754 string.
Bram Moolenaar26852122016-05-24 20:02:38 +02006755
Bram Moolenaar071d4272004-06-13 20:20:40 +00006756 Note that, unlike 'path', no wildcards like "**" are allowed. Normal
6757 wildcards are allowed, but can significantly slow down searching for
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006758 runtime files. For speed, use as few items as possible and avoid
Bram Moolenaar071d4272004-06-13 20:20:40 +00006759 wildcards.
6760 See |:runtime|.
6761 Example: >
6762 :set runtimepath=~/vimruntime,/mygroup/vim,$VIMRUNTIME
6763< This will use the directory "~/vimruntime" first (containing your
6764 personal Vim runtime files), then "/mygroup/vim" (shared between a
6765 group of people) and finally "$VIMRUNTIME" (the distributed runtime
6766 files).
6767 You probably should always include $VIMRUNTIME somewhere, to use the
6768 distributed runtime files. You can put a directory before $VIMRUNTIME
6769 to find files which replace a distributed runtime files. You can put
6770 a directory after $VIMRUNTIME to find files which add to distributed
6771 runtime files.
Bram Moolenaarb5b75622018-03-09 22:22:21 +01006772 When Vim is started with |--clean| the home directory entries are not
6773 included.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006774 This option cannot be set from a |modeline| or in the |sandbox|, for
6775 security reasons.
6776
6777 *'scroll'* *'scr'*
6778'scroll' 'scr' number (default: half the window height)
Christian Brabandt596ad662023-08-16 00:11:09 +02006779 local to window |local-noglobal|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006780 Number of lines to scroll with CTRL-U and CTRL-D commands. Will be
6781 set to half the number of lines in the window when the window size
Bram Moolenaar74667062020-12-28 15:41:41 +01006782 changes. This may happen when enabling the |status-line| or
6783 'tabline' option after setting the 'scroll' option.
6784 If you give a count to the CTRL-U or CTRL-D command it will
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006785 be used as the new value for 'scroll'. Reset to half the window
Bram Moolenaar25c9c682019-05-05 18:13:34 +02006786 height with ":set scroll=0".
Bram Moolenaar071d4272004-06-13 20:20:40 +00006787
6788 *'scrollbind'* *'scb'* *'noscrollbind'* *'noscb'*
6789'scrollbind' 'scb' boolean (default off)
6790 local to window
zeertzjq5277cfa2023-09-28 01:00:12 +08006791 See also |scroll-binding|. When this option is set, scrolling the
6792 current window also scrolls other scrollbind windows (windows that
6793 also have this option set). This option is useful for viewing the
Bram Moolenaar071d4272004-06-13 20:20:40 +00006794 differences between two versions of a file, see 'diff'.
6795 See |'scrollopt'| for options that determine how this option should be
6796 interpreted.
6797 This option is mostly reset when splitting a window to edit another
6798 file. This means that ":split | edit file" results in two windows
6799 with scroll-binding, but ":split file" does not.
6800
Bram Moolenaarae20f342019-11-05 21:09:23 +01006801 *'scrollfocus'* *'scf'* *'noscrollfocus'* *'noscf'*
6802'scrollfocus' 'scf' boolean (default off)
6803 global
6804 {only for MS-Windows GUI}
6805 When using the scroll wheel and this option is set, the window under
6806 the mouse pointer is scrolled. With this option off the current
6807 window is scrolled.
Bram Moolenaar5ef1c6a2019-11-10 22:09:11 +01006808 Systems other than MS-Windows always behave like this option is on.
Bram Moolenaarae20f342019-11-05 21:09:23 +01006809
Bram Moolenaar071d4272004-06-13 20:20:40 +00006810 *'scrolljump'* *'sj'*
6811'scrolljump' 'sj' number (default 1)
6812 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006813 Minimal number of lines to scroll when the cursor gets off the
6814 screen (e.g., with "j"). Not used for scroll commands (e.g., CTRL-E,
6815 CTRL-D). Useful if your terminal scrolls very slowly.
Bram Moolenaar1e015462005-09-25 22:16:38 +00006816 When set to a negative number from -1 to -100 this is used as the
6817 percentage of the window height. Thus -50 scrolls half the window
6818 height.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006819 NOTE: This option is set to 1 when 'compatible' is set.
6820
6821 *'scrolloff'* *'so'*
Bram Moolenaar50ba5262016-09-22 22:33:02 +02006822'scrolloff' 'so' number (default 0, set to 5 in |defaults.vim|)
Bram Moolenaar375e3392019-01-31 18:26:10 +01006823 global or local to window |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006824 Minimal number of screen lines to keep above and below the cursor.
6825 This will make some context visible around where you are working. If
6826 you set it to a very large value (999) the cursor line will always be
6827 in the middle of the window (except at the start or end of the file or
6828 when long lines wrap).
Bram Moolenaar375e3392019-01-31 18:26:10 +01006829 After using the local value, go back the global value with one of
6830 these two: >
6831 setlocal scrolloff<
6832 setlocal scrolloff=-1
6833< For scrolling horizontally see 'sidescrolloff'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006834 NOTE: This option is set to 0 when 'compatible' is set.
6835
6836 *'scrollopt'* *'sbo'*
6837'scrollopt' 'sbo' string (default "ver,jump")
6838 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006839 This is a comma-separated list of words that specifies how
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00006840 'scrollbind' windows should behave. 'sbo' stands for ScrollBind
6841 Options.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006842 The following words are available:
6843 ver Bind vertical scrolling for 'scrollbind' windows
6844 hor Bind horizontal scrolling for 'scrollbind' windows
6845 jump Applies to the offset between two windows for vertical
6846 scrolling. This offset is the difference in the first
6847 displayed line of the bound windows. When moving
6848 around in a window, another 'scrollbind' window may
6849 reach a position before the start or after the end of
6850 the buffer. The offset is not changed though, when
6851 moving back the 'scrollbind' window will try to scroll
6852 to the desired position when possible.
6853 When now making that window the current one, two
6854 things can be done with the relative offset:
6855 1. When "jump" is not included, the relative offset is
6856 adjusted for the scroll position in the new current
6857 window. When going back to the other window, the
Bram Moolenaar02467872007-05-06 13:22:01 +00006858 new relative offset will be used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006859 2. When "jump" is included, the other windows are
6860 scrolled to keep the same relative offset. When
6861 going back to the other window, it still uses the
6862 same relative offset.
6863 Also see |scroll-binding|.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00006864 When 'diff' mode is active there always is vertical scroll binding,
6865 even when "ver" isn't there.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006866
6867 *'sections'* *'sect'*
6868'sections' 'sect' string (default "SHNHH HUnhsh")
6869 global
6870 Specifies the nroff macros that separate sections. These are pairs of
6871 two letters (See |object-motions|). The default makes a section start
6872 at the nroff macros ".SH", ".NH", ".H", ".HU", ".nh" and ".sh".
6873
6874 *'secure'* *'nosecure'* *E523*
6875'secure' boolean (default off)
6876 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006877 When on, ":autocmd", shell and write commands are not allowed in
6878 ".vimrc" and ".exrc" in the current directory and map commands are
6879 displayed. Switch it off only if you know that you will not run into
6880 problems, or when the 'exrc' option is off. On Unix this option is
6881 only used if the ".vimrc" or ".exrc" is not owned by you. This can be
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006882 dangerous if the systems allows users to do a "chown". You better set
Bram Moolenaar071d4272004-06-13 20:20:40 +00006883 'secure' at the end of your ~/.vimrc then.
6884 This option cannot be set from a |modeline| or in the |sandbox|, for
6885 security reasons.
6886
6887 *'selection'* *'sel'*
6888'selection' 'sel' string (default "inclusive")
6889 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00006890 This option defines the behavior of the selection. It is only used
6891 in Visual and Select mode.
6892 Possible values:
6893 value past line inclusive ~
6894 old no yes
6895 inclusive yes yes
6896 exclusive yes no
6897 "past line" means that the cursor is allowed to be positioned one
6898 character past the line.
6899 "inclusive" means that the last character of the selection is included
6900 in an operation. For example, when "x" is used to delete the
6901 selection.
Bram Moolenaare4a3bcf2016-08-26 19:52:37 +02006902 When "old" is used and 'virtualedit' allows the cursor to move past
6903 the end of line the line break still isn't included.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006904 Note that when "exclusive" is used and selecting from the end
6905 backwards, you cannot include the last character of a line, when
6906 starting in Normal mode and 'virtualedit' empty.
6907
6908 The 'selection' option is set by the |:behave| command.
6909
6910 *'selectmode'* *'slm'*
6911'selectmode' 'slm' string (default "")
6912 global
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01006913 This is a comma-separated list of words, which specifies when to start
Bram Moolenaar071d4272004-06-13 20:20:40 +00006914 Select mode instead of Visual mode, when a selection is started.
6915 Possible values:
6916 mouse when using the mouse
6917 key when using shifted special keys
6918 cmd when using "v", "V" or CTRL-V
6919 See |Select-mode|.
6920 The 'selectmode' option is set by the |:behave| command.
6921
6922 *'sessionoptions'* *'ssop'*
6923'sessionoptions' 'ssop' string (default: "blank,buffers,curdir,folds,
Bram Moolenaarb5b75622018-03-09 22:22:21 +01006924 help,options,tabpages,winsize,terminal")
Bram Moolenaar071d4272004-06-13 20:20:40 +00006925 global
Bram Moolenaardb84e452010-08-15 13:50:43 +02006926 {not available when compiled without the |+mksession|
Bram Moolenaar071d4272004-06-13 20:20:40 +00006927 feature}
6928 Changes the effect of the |:mksession| command. It is a comma
6929 separated list of words. Each word enables saving and restoring
6930 something:
6931 word save and restore ~
6932 blank empty windows
6933 buffers hidden and unloaded buffers, not just those in windows
6934 curdir the current directory
6935 folds manually created folds, opened/closed folds and local
6936 fold options
6937 globals global variables that start with an uppercase letter
Bram Moolenaar12805862005-01-05 22:16:17 +00006938 and contain at least one lowercase letter. Only
6939 String and Number types are stored.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006940 help the help window
6941 localoptions options and mappings local to a window or buffer (not
6942 global values for local options)
6943 options all options and mappings (also global values for local
6944 options)
Bram Moolenaard23b7142021-04-17 21:04:34 +02006945 skiprtp exclude 'runtimepath' and 'packpath' from the options
Bram Moolenaar071d4272004-06-13 20:20:40 +00006946 resize size of the Vim window: 'lines' and 'columns'
6947 sesdir the directory in which the session file is located
6948 will become the current directory (useful with
6949 projects accessed over a network from different
6950 systems)
6951 slash backslashes in file names replaced with forward
6952 slashes
Bram Moolenaar18144c82006-04-12 21:52:12 +00006953 tabpages all tab pages; without this only the current tab page
6954 is restored, so that you can make a session for each
6955 tab page separately
Bram Moolenaard473c8c2018-08-11 18:00:22 +02006956 terminal include terminal windows where the command can be
6957 restored
Bram Moolenaar071d4272004-06-13 20:20:40 +00006958 unix with Unix end-of-line format (single <NL>), even when
6959 on Windows or DOS
6960 winpos position of the whole Vim window
6961 winsize window sizes
6962
6963 Don't include both "curdir" and "sesdir".
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01006964 When neither "curdir" nor "sesdir" is included, file names are stored
6965 with absolute paths.
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00006966 If you leave out "options" many things won't work well after restoring
6967 the session.
Bram Moolenaar071d4272004-06-13 20:20:40 +00006968 "slash" and "unix" are useful on Windows when sharing session files
6969 with Unix. The Unix version of Vim cannot source dos format scripts,
6970 but the Windows version of Vim can source unix format scripts.
6971
6972 *'shell'* *'sh'* *E91*
Bram Moolenaar95a9dd12019-12-19 22:12:03 +01006973'shell' 'sh' string (default $SHELL or "sh", Win32: "cmd.exe")
Bram Moolenaar071d4272004-06-13 20:20:40 +00006974 global
6975 Name of the shell to use for ! and :! commands. When changing the
6976 value also check these options: 'shelltype', 'shellpipe', 'shellslash'
6977 'shellredir', 'shellquote', 'shellxquote' and 'shellcmdflag'.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006978 It is allowed to give an argument to the command, e.g. "csh -f".
Bram Moolenaar071d4272004-06-13 20:20:40 +00006979 See |option-backslash| about including spaces and backslashes.
6980 Environment variables are expanded |:set_env|.
Bram Moolenaar4bfa8af2018-02-03 15:14:46 +01006981
Bram Moolenaara2baa732022-02-04 16:09:54 +00006982 In |restricted-mode| shell commands will not be possible. This mode
6983 is used if the value of $SHELL ends in "false" or "nologin".
6984
Bram Moolenaar1ff14ba2019-11-02 14:09:23 +01006985 If the name of the shell contains a space, you need to enclose it in
Bram Moolenaar5ef1c6a2019-11-10 22:09:11 +01006986 quotes and escape the space. Example with quotes: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00006987 :set shell=\"c:\program\ files\unix\sh.exe\"\ -f
6988< Note the backslash before each quote (to avoid starting a comment) and
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00006989 each space (to avoid ending the option value). Also note that the
Bram Moolenaar071d4272004-06-13 20:20:40 +00006990 "-f" is not inside the quotes, because it is not part of the command
Bram Moolenaar4bfa8af2018-02-03 15:14:46 +01006991 name. Vim automagically recognizes the backslashes that are path
Bram Moolenaar071d4272004-06-13 20:20:40 +00006992 separators.
Bram Moolenaar4bfa8af2018-02-03 15:14:46 +01006993 Example with escaped space (Vim will do this when initializing the
6994 option from $SHELL): >
6995 :set shell=/bin/with\\\ space/sh
Bram Moolenaard473c8c2018-08-11 18:00:22 +02006996< The resulting value of 'shell' is "/bin/with\ space/sh", two
Bram Moolenaar4bfa8af2018-02-03 15:14:46 +01006997 backslashes are consumed by `:set`.
6998
Bram Moolenaar071d4272004-06-13 20:20:40 +00006999 Under MS-Windows, when the executable ends in ".com" it must be
7000 included. Thus setting the shell to "command.com" or "4dos.com"
7001 works, but "command" and "4dos" do not work for all commands (e.g.,
7002 filtering).
7003 For unknown reasons, when using "4dos.com" the current directory is
7004 changed to "C:\". To avoid this set 'shell' like this: >
7005 :set shell=command.com\ /c\ 4dos
7006< This option cannot be set from a |modeline| or in the |sandbox|, for
7007 security reasons.
7008
7009 *'shellcmdflag'* *'shcf'*
Bram Moolenaar5dc62522012-02-13 00:05:22 +01007010'shellcmdflag' 'shcf' string (default: "-c";
Mike Williams12795022021-06-28 20:53:58 +02007011 Win32, when 'shell' contains "powershell":
7012 "-Command", or when it does not contain "sh"
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01007013 somewhere: "/c")
Bram Moolenaar071d4272004-06-13 20:20:40 +00007014 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007015 Flag passed to the shell to execute "!" and ":!" commands; e.g.,
Mike Williams12795022021-06-28 20:53:58 +02007016 "bash.exe -c ls", "powershell.exe -Command dir", or "cmd.exe /c dir".
7017 For MS-Windows, the default is set according to the value of 'shell',
7018 to reduce the need to set this option by the user.
Bram Moolenaar5302d9e2011-09-14 17:55:08 +02007019 On Unix it can have more than one flag. Each white space separated
7020 part is passed as an argument to the shell command.
7021 See |option-backslash| about including spaces and backslashes.
Mike Williams12795022021-06-28 20:53:58 +02007022 Also see |dos-shell| and |dos-powershell| for MS-Windows.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007023 This option cannot be set from a |modeline| or in the |sandbox|, for
7024 security reasons.
7025
7026 *'shellpipe'* *'sp'*
Mike Williams12795022021-06-28 20:53:58 +02007027'shellpipe' 'sp' string (default ">", ">%s 2>&1", "| tee", "|& tee"
7028 "2>&1| tee", or
7029 "2>&1 | Out-File -Encoding default")
Bram Moolenaar071d4272004-06-13 20:20:40 +00007030 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007031 {not available when compiled without the |+quickfix|
7032 feature}
7033 String to be used to put the output of the ":make" command in the
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007034 error file. See also |:make_makeprg|. See |option-backslash| about
Bram Moolenaar071d4272004-06-13 20:20:40 +00007035 including spaces and backslashes.
7036 The name of the temporary file can be represented by "%s" if necessary
7037 (the file name is appended automatically if no %s appears in the value
7038 of this option).
Mike Williams12795022021-06-28 20:53:58 +02007039 For the Amiga the default is ">". For MS-Windows using powershell the
7040 default is "2>&1 | Out-File -Encoding default", otherwise the default
7041 is ">%s 2>&1". The output is directly saved in a file and not echoed
7042 to the screen.
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02007043 For Unix the default is "| tee". The stdout of the compiler is saved
Bram Moolenaar071d4272004-06-13 20:20:40 +00007044 in a file and echoed to the screen. If the 'shell' option is "csh" or
7045 "tcsh" after initializations, the default becomes "|& tee". If the
Bram Moolenaar96f45c02019-10-26 19:53:45 +02007046 'shell' option is "sh", "ksh", "mksh", "pdksh", "zsh", "zsh-beta",
Natanael Copa56318362021-05-06 18:46:35 +02007047 "bash", "fish", "ash" or "dash" the default becomes "2>&1| tee". This
7048 means that stderr is also included. Before using the 'shell' option a
7049 path is removed, thus "/bin/sh" uses "sh".
Mike Williamsa3d1b292021-06-30 20:56:00 +02007050 For Unix and MS-Windows, when the 'shell' option is "pwsh" the default
7051 becomes ">%s 2>&1" and the output is not echoed to the screen.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007052 The initialization of this option is done after reading the ".vimrc"
7053 and the other initializations, so that when the 'shell' option is set
7054 there, the 'shellpipe' option changes automatically, unless it was
7055 explicitly set before.
7056 When 'shellpipe' is set to an empty string, no redirection of the
7057 ":make" output will be done. This is useful if you use a 'makeprg'
7058 that writes to 'makeef' by itself. If you want no piping, but do
7059 want to include the 'makeef', set 'shellpipe' to a single space.
7060 Don't forget to precede the space with a backslash: ":set sp=\ ".
7061 In the future pipes may be used for filtering and this option will
7062 become obsolete (at least for Unix).
7063 This option cannot be set from a |modeline| or in the |sandbox|, for
7064 security reasons.
7065
7066 *'shellquote'* *'shq'*
Mike Williamsa3d1b292021-06-30 20:56:00 +02007067'shellquote' 'shq' string (default: "")
Bram Moolenaar071d4272004-06-13 20:20:40 +00007068 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007069 Quoting character(s), put around the command passed to the shell, for
7070 the "!" and ":!" commands. The redirection is kept outside of the
7071 quoting. See 'shellxquote' to include the redirection. It's
7072 probably not useful to set both options.
7073 This is an empty string by default. Only known to be useful for
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01007074 third-party shells on MS-Windows-like systems, such as the MKS Korn
Mike Williamsa3d1b292021-06-30 20:56:00 +02007075 Shell or bash, where it should be "\"". See |dos-shell|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007076 This option cannot be set from a |modeline| or in the |sandbox|, for
7077 security reasons.
7078
7079 *'shellredir'* *'srr'*
Mike Williams12795022021-06-28 20:53:58 +02007080'shellredir' 'srr' string (default ">", ">&", ">%s 2>&1", or
7081 "2>&1 | Out-File -Encoding default")
Bram Moolenaar071d4272004-06-13 20:20:40 +00007082 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007083 String to be used to put the output of a filter command in a temporary
7084 file. See also |:!|. See |option-backslash| about including spaces
7085 and backslashes.
7086 The name of the temporary file can be represented by "%s" if necessary
7087 (the file name is appended automatically if no %s appears in the value
7088 of this option).
Bram Moolenaar96f45c02019-10-26 19:53:45 +02007089 The default is ">". For Unix, if the 'shell' option is "csh" or
7090 "tcsh" during initializations, the default becomes ">&". If the
Bram Moolenaar0c0734d2019-11-26 21:44:46 +01007091 'shell' option is "sh", "ksh", "mksh", "pdksh", "zsh", "zsh-beta",
Mike Williamsa3d1b292021-06-30 20:56:00 +02007092 "bash", "fish", or "pwsh", the default becomes ">%s 2>&1". This means
7093 that stderr is also included. For Win32, the Unix checks are done and
Mike Williams12795022021-06-28 20:53:58 +02007094 additionally "cmd" is checked for, which makes the default ">%s 2>&1",
7095 and "powershell" is checked for which makes the default
Mike Williamsa3d1b292021-06-30 20:56:00 +02007096 "2>&1 | Out-File -Encoding default" (see |dos-powershell|). Also, the
7097 same names with ".exe" appended are checked for.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007098 The initialization of this option is done after reading the ".vimrc"
7099 and the other initializations, so that when the 'shell' option is set
7100 there, the 'shellredir' option changes automatically unless it was
7101 explicitly set before.
7102 In the future pipes may be used for filtering and this option will
7103 become obsolete (at least for Unix).
7104 This option cannot be set from a |modeline| or in the |sandbox|, for
7105 security reasons.
7106
7107 *'shellslash'* *'ssl'* *'noshellslash'* *'nossl'*
7108'shellslash' 'ssl' boolean (default off)
7109 global
Bram Moolenaar6f345a12019-12-17 21:27:18 +01007110 {only for MS-Windows}
Bram Moolenaar071d4272004-06-13 20:20:40 +00007111 When set, a forward slash is used when expanding file names. This is
Mike Williamsa3d1b292021-06-30 20:56:00 +02007112 useful when a Unix-like shell is used instead of cmd.exe, pwsh.exe, or
Mike Williams12795022021-06-28 20:53:58 +02007113 powershell.exe. Backward slashes can still be typed, but they are
7114 changed to forward slashes by Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007115 Note that setting or resetting this option has no effect for some
7116 existing file names, thus this option needs to be set before opening
7117 any file for best results. This might change in the future.
7118 'shellslash' only works when a backslash can be used as a path
7119 separator. To test if this is so use: >
7120 if exists('+shellslash')
Bram Moolenaarac3150d2019-07-28 16:36:39 +02007121< Also see 'completeslash'.
7122
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007123 *'shelltemp'* *'stmp'* *'noshelltemp'* *'nostmp'*
7124'shelltemp' 'stmp' boolean (Vi default off, Vim default on)
7125 global
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007126 When on, use temp files for shell commands. When off use a pipe.
7127 When using a pipe is not possible temp files are used anyway.
Bram Moolenaar97293012011-07-18 19:40:27 +02007128 Currently a pipe is only supported on Unix and MS-Windows 2K and
7129 later. You can check it with: >
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007130 :if has("filterpipe")
7131< The advantage of using a pipe is that nobody can read the temp file
7132 and the 'shell' command does not need to support redirection.
7133 The advantage of using a temp file is that the file type and encoding
7134 can be detected.
7135 The |FilterReadPre|, |FilterReadPost| and |FilterWritePre|,
7136 |FilterWritePost| autocommands event are not triggered when
7137 'shelltemp' is off.
Bram Moolenaar269f5952016-07-15 22:54:41 +02007138 The `system()` function does not respect this option and always uses
7139 temp files.
Bram Moolenaar036986f2017-03-16 17:41:02 +01007140 NOTE: This option is set to the Vim default value when 'compatible'
7141 is reset.
Bram Moolenaar26a60b42005-02-22 08:49:11 +00007142
Bram Moolenaar071d4272004-06-13 20:20:40 +00007143 *'shelltype'* *'st'*
7144'shelltype' 'st' number (default 0)
7145 global
Bram Moolenaar6c60f472019-04-28 16:00:35 +02007146 {only for the Amiga}
Bram Moolenaar071d4272004-06-13 20:20:40 +00007147 On the Amiga this option influences the way how the commands work
7148 which use a shell.
7149 0 and 1: always use the shell
7150 2 and 3: use the shell only to filter lines
7151 4 and 5: use shell only for ':sh' command
7152 When not using the shell, the command is executed directly.
7153
7154 0 and 2: use "shell 'shellcmdflag' cmd" to start external commands
7155 1 and 3: use "shell cmd" to start external commands
7156
Bram Moolenaardb7207e2012-02-22 17:30:19 +01007157 *'shellxescape'* *'sxe'*
7158'shellxescape' 'sxe' string (default: "";
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01007159 for MS-Windows: "\"&|<>()@^")
Bram Moolenaardb7207e2012-02-22 17:30:19 +01007160 global
Bram Moolenaardb7207e2012-02-22 17:30:19 +01007161 When 'shellxquote' is set to "(" then the characters listed in this
7162 option will be escaped with a '^' character. This makes it possible
7163 to execute most external commands with cmd.exe.
dkearns8ebdbc92023-10-29 06:26:19 +11007164 This option cannot be set from a |modeline| or in the |sandbox|, for
7165 security reasons.
Bram Moolenaardb7207e2012-02-22 17:30:19 +01007166
Bram Moolenaar071d4272004-06-13 20:20:40 +00007167 *'shellxquote'* *'sxq'*
7168'shellxquote' 'sxq' string (default: "";
Bram Moolenaarf66b3fc2012-02-20 22:18:30 +01007169 for Win32, when 'shell' is cmd.exe: "("
Mike Williams12795022021-06-28 20:53:58 +02007170 for Win32, when 'shell' is
7171 powershell.exe: "\""
Bram Moolenaarf66b3fc2012-02-20 22:18:30 +01007172 for Win32, when 'shell' contains "sh"
7173 somewhere: "\""
Bram Moolenaar071d4272004-06-13 20:20:40 +00007174 for Unix, when using system(): "\"")
7175 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007176 Quoting character(s), put around the command passed to the shell, for
7177 the "!" and ":!" commands. Includes the redirection. See
7178 'shellquote' to exclude the redirection. It's probably not useful
7179 to set both options.
Bram Moolenaarf66b3fc2012-02-20 22:18:30 +01007180 When the value is '(' then ')' is appended. When the value is '"('
7181 then ')"' is appended.
7182 When the value is '(' then also see 'shellxescape'.
Bram Moolenaara64ba222012-02-12 23:23:31 +01007183 This is an empty string by default on most systems, but is known to be
Mike Williamsa3d1b292021-06-30 20:56:00 +02007184 useful for on Win32 version, either for cmd.exe, powershell.exe, or
7185 pwsh.exe which automatically strips off the first and last quote on a
7186 command, or 3rd-party shells such as the MKS Korn Shell or bash, where
7187 it should be "\"". The default is adjusted according the value of
Mike Williams12795022021-06-28 20:53:58 +02007188 'shell', to reduce the need to set this option by the user. See
7189 |dos-shell|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007190 This option cannot be set from a |modeline| or in the |sandbox|, for
7191 security reasons.
7192
7193 *'shiftround'* *'sr'* *'noshiftround'* *'nosr'*
7194'shiftround' 'sr' boolean (default off)
7195 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007196 Round indent to multiple of 'shiftwidth'. Applies to > and <
7197 commands. CTRL-T and CTRL-D in Insert mode always round the indent to
7198 a multiple of 'shiftwidth' (this is Vi compatible).
7199 NOTE: This option is reset when 'compatible' is set.
7200
7201 *'shiftwidth'* *'sw'*
7202'shiftwidth' 'sw' number (default 8)
7203 local to buffer
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007204 Number of spaces to use for each step of (auto)indent. Used for
Bram Moolenaar071d4272004-06-13 20:20:40 +00007205 |'cindent'|, |>>|, |<<|, etc.
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01007206 When zero the 'tabstop' value will be used. Use the |shiftwidth()|
Bram Moolenaar3a0d8092012-10-21 03:02:54 +02007207 function to get the effective shiftwidth value.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007208
7209 *'shortmess'* *'shm'*
Bram Moolenaar9dfa3132019-05-04 21:08:40 +02007210'shortmess' 'shm' string (Vim default "filnxtToOS", Vi default: "S",
7211 POSIX default: "AS")
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00007212 global *E1336*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007213 This option helps to avoid all the |hit-enter| prompts caused by file
7214 messages, for example with CTRL-G, and to avoid some other messages.
7215 It is a list of flags:
7216 flag meaning when present ~
Bram Moolenaar7db29e42022-12-11 15:53:04 +00007217 f use "(3 of 5)" instead of "(file 3 of 5)" *shm-f*
7218 i use "[noeol]" instead of "[Incomplete last line]" *shm-i*
7219 l use "999L, 888B" instead of "999 lines, 888 bytes" *shm-l*
7220 m use "[+]" instead of "[Modified]" *shm-m*
7221 n use "[New]" instead of "[New File]" *shm-n*
7222 r use "[RO]" instead of "[readonly]" *shm-r*
7223 w use "[w]" instead of "written" for file write message *shm-w*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007224 and "[a]" instead of "appended" for ':w >> file' command
Bram Moolenaar7db29e42022-12-11 15:53:04 +00007225 x use "[dos]" instead of "[dos format]", "[unix]" *shm-x*
7226 instead of "[unix format]" and "[mac]" instead of "[mac
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00007227 format]"
Bram Moolenaar7db29e42022-12-11 15:53:04 +00007228 a all of the above abbreviations *shm-a*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007229
Bram Moolenaar7db29e42022-12-11 15:53:04 +00007230 o overwrite message for writing a file with subsequent *shm-o*
7231 message for reading a file (useful for ":wn" or when
7232 'autowrite' on)
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00007233 O message for reading a file overwrites any previous *shm-O*
7234 message; also for quickfix message (e.g., ":cn")
Bram Moolenaar7db29e42022-12-11 15:53:04 +00007235 s don't give "search hit BOTTOM, continuing at TOP" or *shm-s*
7236 "search hit TOP, continuing at BOTTOM" messages; when using
7237 the search count do not show "W" after the count message (see
7238 S below)
7239 t truncate file message at the start if it is too long *shm-t*
7240 to fit on the command-line, "<" will appear in the left most
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00007241 column; ignored in Ex mode
Bram Moolenaar7db29e42022-12-11 15:53:04 +00007242 T truncate other messages in the middle if they are too *shm-T*
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00007243 long to fit on the command line; "..." will appear in the
7244 middle; ignored in Ex mode
Bram Moolenaar7db29e42022-12-11 15:53:04 +00007245 W don't give "written" or "[w]" when writing a file *shm-W*
7246 A don't give the "ATTENTION" message when an existing *shm-A*
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00007247 swap file is found
Bram Moolenaar7db29e42022-12-11 15:53:04 +00007248 I don't give the intro message when starting Vim, *shm-I*
Bram Moolenaar938ae282023-02-20 20:44:55 +00007249 see |:intro|
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00007250 c don't give |ins-completion-menu| messages; for *shm-c*
Bram Moolenaar7db29e42022-12-11 15:53:04 +00007251 example, "-- XXX completion (YYY)", "match 1 of 2", "The only
7252 match", "Pattern not found", "Back at original", etc.
7253 C don't give messages while scanning for ins-completion *shm-C*
7254 items, for instance "scanning tags"
7255 q use "recording" instead of "recording @a" *shm-q*
7256 F don't give the file info when editing a file, like *shm-F*
7257 `:silent` was used for the command; note that this also
7258 affects messages from autocommands
Bram Moolenaar938ae282023-02-20 20:44:55 +00007259 S do not show search count message when searching, e.g. *shm-S*
7260 "[1/5]"
Bram Moolenaar071d4272004-06-13 20:20:40 +00007261
7262 This gives you the opportunity to avoid that a change between buffers
7263 requires you to hit <Enter>, but still gives as useful a message as
7264 possible for the space available. To get the whole message that you
7265 would have got with 'shm' empty, use ":file!"
7266 Useful values:
7267 shm= No abbreviation of message.
7268 shm=a Abbreviation, but no loss of information.
7269 shm=at Abbreviation, and truncate message when necessary.
7270
7271 NOTE: This option is set to the Vi default value when 'compatible' is
7272 set and to the Vim default value when 'compatible' is reset.
7273
7274 *'shortname'* *'sn'* *'noshortname'* *'nosn'*
7275'shortname' 'sn' boolean (default off)
7276 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00007277 Filenames are assumed to be 8 characters plus one extension of 3
7278 characters. Multiple dots in file names are not allowed. When this
7279 option is on, dots in file names are replaced with underscores when
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01007280 adding an extension (".~" or ".swp"). This option is useful
Bram Moolenaar071d4272004-06-13 20:20:40 +00007281 when editing files on an MS-DOS compatible filesystem, e.g., messydos
Bram Moolenaarade0d392020-01-21 22:33:58 +01007282 or crossdos.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007283
7284 *'showbreak'* *'sbr'* *E595*
7285'showbreak' 'sbr' string (default "")
Bram Moolenaaree857022019-11-09 23:26:40 +01007286 global or local to window |global-local|
Bram Moolenaardb84e452010-08-15 13:50:43 +02007287 {not available when compiled without the |+linebreak|
Bram Moolenaar071d4272004-06-13 20:20:40 +00007288 feature}
7289 String to put at the start of lines that have been wrapped. Useful
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007290 values are "> " or "+++ ": >
7291 :set showbreak=>\
7292< Note the backslash to escape the trailing space. It's easier like
7293 this: >
Bram Moolenaar1a384422010-07-14 19:53:30 +02007294 :let &showbreak = '+++ '
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007295< Only printable single-cell characters are allowed, excluding <Tab> and
Bram Moolenaar071d4272004-06-13 20:20:40 +00007296 comma (in a future version the comma might be used to separate the
7297 part that is shown at the end and at the start of a line).
7298 The characters are highlighted according to the '@' flag in
7299 'highlight'.
7300 Note that tabs after the showbreak will be displayed differently.
7301 If you want the 'showbreak' to appear in between line numbers, add the
7302 "n" flag to 'cpoptions'.
Bram Moolenaaree857022019-11-09 23:26:40 +01007303 A window-local value overrules a global value. If the global value is
7304 set and you want no value in the current window use NONE: >
7305 :setlocal showbreak=NONE
7306<
Bram Moolenaar071d4272004-06-13 20:20:40 +00007307 *'showcmd'* *'sc'* *'noshowcmd'* *'nosc'*
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +02007308'showcmd' 'sc' boolean (Vim default: on, off for Unix,
7309 Vi default: off, set in |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00007310 global
Bram Moolenaar02467872007-05-06 13:22:01 +00007311 Show (partial) command in the last line of the screen. Set this
7312 option off if your terminal is slow.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007313 In Visual mode the size of the selected area is shown:
7314 - When selecting characters within a line, the number of characters.
Bram Moolenaarf91787c2010-07-17 12:47:16 +02007315 If the number of bytes is different it is also displayed: "2-6"
7316 means two characters and six bytes.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007317 - When selecting more than one line, the number of lines.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01007318 - When selecting a block, the size in screen characters:
7319 {lines}x{columns}.
Luuk van Baalba936f62022-12-15 13:15:39 +00007320 This information can be displayed in an alternative location using the
7321 'showcmdloc' option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007322 NOTE: This option is set to the Vi default value when 'compatible' is
7323 set and to the Vim default value when 'compatible' is reset.
7324
Luuk van Baalba936f62022-12-15 13:15:39 +00007325 *'showcmdloc'* *'sloc'*
7326'showcmdloc' 'sloc' string (default "last")
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00007327 global
Luuk van Baalba936f62022-12-15 13:15:39 +00007328 This option can be used to display the (partially) entered command in
7329 another location. Possible values are:
7330 last Last line of the screen (default).
7331 statusline Status line of the current window.
Bram Moolenaarf1dcd142022-12-31 15:30:45 +00007332 tabline First line of the screen if 'showtabline' is enabled.
Luuk van Baalba936f62022-12-15 13:15:39 +00007333 Setting this option to "statusline" or "tabline" means that these will
7334 be redrawn whenever the command changes, which can be on every key
7335 pressed.
7336 The %S 'statusline' item can be used in 'statusline' or 'tabline' to
7337 place the text. Without a custom 'statusline' or 'tabline' it will be
7338 displayed in a convenient location.
7339
Bram Moolenaar071d4272004-06-13 20:20:40 +00007340 *'showfulltag'* *'sft'* *'noshowfulltag'* *'nosft'*
7341'showfulltag' 'sft' boolean (default off)
7342 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007343 When completing a word in insert mode (see |ins-completion|) from the
7344 tags file, show both the tag name and a tidied-up form of the search
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007345 pattern (if there is one) as possible matches. Thus, if you have
Bram Moolenaar071d4272004-06-13 20:20:40 +00007346 matched a C function, you can see a template for what arguments are
7347 required (coding style permitting).
Bram Moolenaar446cb832008-06-24 21:56:24 +00007348 Note that this doesn't work well together with having "longest" in
7349 'completeopt', because the completion from the search pattern may not
7350 match the typed text.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007351
7352 *'showmatch'* *'sm'* *'noshowmatch'* *'nosm'*
7353'showmatch' 'sm' boolean (default off)
7354 global
7355 When a bracket is inserted, briefly jump to the matching one. The
7356 jump is only done if the match can be seen on the screen. The time to
7357 show the match can be set with 'matchtime'.
7358 A Beep is given if there is no match (no matter if the match can be
Bram Moolenaarca635012015-09-25 20:34:21 +02007359 seen or not).
7360 This option is reset when 'paste' is set and restored when 'paste' is
7361 reset.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007362 When the 'm' flag is not included in 'cpoptions', typing a character
7363 will immediately move the cursor back to where it belongs.
7364 See the "sm" field in 'guicursor' for setting the cursor shape and
7365 blinking when showing the match.
7366 The 'matchpairs' option can be used to specify the characters to show
7367 matches for. 'rightleft' and 'revins' are used to look for opposite
7368 matches.
Bram Moolenaarfd2ac762006-03-01 22:09:21 +00007369 Also see the matchparen plugin for highlighting the match when moving
7370 around |pi_paren.txt|.
7371 Note: Use of the short form is rated PG.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007372
7373 *'showmode'* *'smd'* *'noshowmode'* *'nosmd'*
7374'showmode' 'smd' boolean (Vim default: on, Vi default: off)
7375 global
7376 If in Insert, Replace or Visual mode put a message on the last line.
7377 Use the 'M' flag in 'highlight' to set the type of highlighting for
7378 this message.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007379 When |XIM| may be used the message will include "XIM". But this
Bram Moolenaar071d4272004-06-13 20:20:40 +00007380 doesn't mean XIM is really active, especially when 'imactivatekey' is
7381 not set.
7382 NOTE: This option is set to the Vi default value when 'compatible' is
7383 set and to the Vim default value when 'compatible' is reset.
7384
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00007385 *'showtabline'* *'stal'*
7386'showtabline' 'stal' number (default 1)
7387 global
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00007388 The value of this option specifies when the line with tab page labels
7389 will be displayed:
7390 0: never
7391 1: only if there are at least two tab pages
7392 2: always
7393 This is both for the GUI and non-GUI implementation of the tab pages
7394 line.
7395 See |tab-page| for more information about tab pages.
7396
Bram Moolenaar071d4272004-06-13 20:20:40 +00007397 *'sidescroll'* *'ss'*
7398'sidescroll' 'ss' number (default 0)
7399 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007400 The minimal number of columns to scroll horizontally. Used only when
7401 the 'wrap' option is off and the cursor is moved off of the screen.
7402 When it is zero the cursor will be put in the middle of the screen.
7403 When using a slow terminal set it to a large number or 0. When using
7404 a fast terminal use a small number or 1. Not used for "zh" and "zl"
7405 commands.
7406
7407 *'sidescrolloff'* *'siso'*
7408'sidescrolloff' 'siso' number (default 0)
Bram Moolenaar375e3392019-01-31 18:26:10 +01007409 global or local to window |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00007410 The minimal number of screen columns to keep to the left and to the
Bram Moolenaar482aaeb2005-09-29 18:26:07 +00007411 right of the cursor if 'nowrap' is set. Setting this option to a
7412 value greater than 0 while having |'sidescroll'| also at a non-zero
7413 value makes some context visible in the line you are scrolling in
7414 horizontally (except at beginning of the line). Setting this option
7415 to a large value (like 999) has the effect of keeping the cursor
7416 horizontally centered in the window, as long as one does not come too
7417 close to the beginning of the line.
Bram Moolenaar375e3392019-01-31 18:26:10 +01007418 After using the local value, go back the global value with one of
7419 these two: >
7420 setlocal sidescrolloff<
7421 setlocal sidescrolloff=-1
7422< NOTE: This option is set to 0 when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007423
7424 Example: Try this together with 'sidescroll' and 'listchars' as
7425 in the following example to never allow the cursor to move
Bram Moolenaar95ec9d62016-08-12 18:29:59 +02007426 onto the "extends" character: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00007427
7428 :set nowrap sidescroll=1 listchars=extends:>,precedes:<
7429 :set sidescrolloff=1
Bram Moolenaar95ec9d62016-08-12 18:29:59 +02007430<
7431 *'signcolumn'* *'scl'*
7432'signcolumn' 'scl' string (default "auto")
7433 local to window
Bram Moolenaar95ec9d62016-08-12 18:29:59 +02007434 {not available when compiled without the |+signs|
7435 feature}
Bram Moolenaar09521312016-08-12 22:54:35 +02007436 Whether or not to draw the signcolumn. Valid values are:
Bram Moolenaar938ae282023-02-20 20:44:55 +00007437 "auto" only when there is a sign to display
7438 "no" never
7439 "yes" always
Bram Moolenaar394c5d82019-06-17 21:48:05 +02007440 "number" display signs in the 'number' column. If the number
Bram Moolenaar6c1e1572019-06-22 02:13:00 +02007441 column is not present, then behaves like "auto".
Bram Moolenaar071d4272004-06-13 20:20:40 +00007442
7443
7444 *'smartcase'* *'scs'* *'nosmartcase'* *'noscs'*
7445'smartcase' 'scs' boolean (default off)
7446 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007447 Override the 'ignorecase' option if the search pattern contains upper
7448 case characters. Only used when the search pattern is typed and
7449 'ignorecase' option is on. Used for the commands "/", "?", "n", "N",
Bram Moolenaarc8734422012-06-01 22:38:45 +02007450 ":g" and ":s". Not used for "*", "#", "gd", tag search, etc. After
Bram Moolenaar071d4272004-06-13 20:20:40 +00007451 "*" and "#" you can make 'smartcase' used by doing a "/" command,
7452 recalling the search pattern from history and hitting <Enter>.
7453 NOTE: This option is reset when 'compatible' is set.
7454
7455 *'smartindent'* *'si'* *'nosmartindent'* *'nosi'*
7456'smartindent' 'si' boolean (default off)
7457 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00007458 Do smart autoindenting when starting a new line. Works for C-like
7459 programs, but can also be used for other languages. 'cindent' does
7460 something like this, works better in most cases, but is more strict,
Bram Moolenaar81af9252010-12-10 20:35:50 +01007461 see |C-indenting|. When 'cindent' is on or 'indentexpr' is set,
Bram Moolenaar166af9b2010-11-16 20:34:40 +01007462 setting 'si' has no effect. 'indentexpr' is a more advanced
7463 alternative.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007464 Normally 'autoindent' should also be on when using 'smartindent'.
7465 An indent is automatically inserted:
7466 - After a line ending in '{'.
7467 - After a line starting with a keyword from 'cinwords'.
7468 - Before a line starting with '}' (only with the "O" command).
7469 When typing '}' as the first character in a new line, that line is
7470 given the same indent as the matching '{'.
7471 When typing '#' as the first character in a new line, the indent for
7472 that line is removed, the '#' is put in the first column. The indent
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007473 is restored for the next line. If you don't want this, use this
Bram Moolenaar071d4272004-06-13 20:20:40 +00007474 mapping: ":inoremap # X^H#", where ^H is entered with CTRL-V CTRL-H.
7475 When using the ">>" command, lines starting with '#' are not shifted
7476 right.
Bram Moolenaar036986f2017-03-16 17:41:02 +01007477 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaarca635012015-09-25 20:34:21 +02007478 This option is reset when 'paste' is set and restored when 'paste' is
7479 reset.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007480
7481 *'smarttab'* *'sta'* *'nosmarttab'* *'nosta'*
7482'smarttab' 'sta' boolean (default off)
7483 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007484 When on, a <Tab> in front of a line inserts blanks according to
Bram Moolenaar280f1262006-01-30 00:14:18 +00007485 'shiftwidth'. 'tabstop' or 'softtabstop' is used in other places. A
7486 <BS> will delete a 'shiftwidth' worth of space at the start of the
7487 line.
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +00007488 When off, a <Tab> always inserts blanks according to 'tabstop' or
Bram Moolenaar280f1262006-01-30 00:14:18 +00007489 'softtabstop'. 'shiftwidth' is only used for shifting text left or
7490 right |shift-left-right|.
Bram Moolenaarebcbd022007-05-12 14:28:25 +00007491 What gets inserted (a <Tab> or spaces) depends on the 'expandtab'
Bram Moolenaar071d4272004-06-13 20:20:40 +00007492 option. Also see |ins-expandtab|. When 'expandtab' is not set, the
Bram Moolenaar843ee412004-06-30 16:16:41 +00007493 number of spaces is minimized by using <Tab>s.
Bram Moolenaarca635012015-09-25 20:34:21 +02007494 This option is reset when 'paste' is set and restored when 'paste' is
7495 reset.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007496 NOTE: This option is reset when 'compatible' is set.
7497
Bram Moolenaarf6196f42022-10-02 21:29:55 +01007498 *'smoothscroll'* *'sms'* *'nosmoothscroll'* *'nosms'*
7499'smoothscroll' 'sms' boolean (default off)
7500 local to window
7501 Scrolling works with screen lines. When 'wrap' is set and the first
7502 line in the window wraps part of it may not be visible, as if it is
Bram Moolenaarf269eab2022-10-03 18:04:35 +01007503 above the window. "<<<" is displayed at the start of the first line,
7504 highlighted with |hl-NonText|.
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01007505 You may also want to add "lastline" to the 'display' option to show as
7506 much of the last line as possible.
Bram Moolenaarf269eab2022-10-03 18:04:35 +01007507 NOTE: only partly implemented, currently works with CTRL-E, CTRL-Y
7508 and scrolling with the mouse.
Bram Moolenaarf6196f42022-10-02 21:29:55 +01007509
Bram Moolenaar071d4272004-06-13 20:20:40 +00007510 *'softtabstop'* *'sts'*
7511'softtabstop' 'sts' number (default 0)
7512 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00007513 Number of spaces that a <Tab> counts for while performing editing
7514 operations, like inserting a <Tab> or using <BS>. It "feels" like
7515 <Tab>s are being inserted, while in fact a mix of spaces and <Tab>s is
7516 used. This is useful to keep the 'ts' setting at its standard value
7517 of 8, while being able to edit like it is set to 'sts'. However,
7518 commands like "x" still work on the actual characters.
7519 When 'sts' is zero, this feature is off.
Bram Moolenaar3a0d8092012-10-21 03:02:54 +02007520 When 'sts' is negative, the value of 'shiftwidth' is used.
Bram Moolenaarca635012015-09-25 20:34:21 +02007521 'softtabstop' is set to 0 when the 'paste' option is set and restored
7522 when 'paste' is reset.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007523 See also |ins-expandtab|. When 'expandtab' is not set, the number of
7524 spaces is minimized by using <Tab>s.
7525 The 'L' flag in 'cpoptions' changes how tabs are used when 'list' is
7526 set.
7527 NOTE: This option is set to 0 when 'compatible' is set.
7528
Bram Moolenaar04958cb2018-06-23 19:23:02 +02007529 If Vim is compiled with the |+vartabs| feature then the value of
7530 'softtabstop' will be ignored if |'varsofttabstop'| is set to
7531 anything other than an empty string.
7532
Bram Moolenaar217ad922005-03-20 22:37:15 +00007533 *'spell'* *'nospell'*
7534'spell' boolean (default off)
7535 local to window
Bram Moolenaar217ad922005-03-20 22:37:15 +00007536 {not available when compiled without the |+syntax|
7537 feature}
7538 When on spell checking will be done. See |spell|.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00007539 The languages are specified with 'spelllang'.
Bram Moolenaar217ad922005-03-20 22:37:15 +00007540
Bram Moolenaar0d9c26d2005-07-02 23:19:16 +00007541 *'spellcapcheck'* *'spc'*
Bram Moolenaar0dc065e2005-07-04 22:49:24 +00007542'spellcapcheck' 'spc' string (default "[.?!]\_[\])'" \t]\+")
Bram Moolenaar0d9c26d2005-07-02 23:19:16 +00007543 local to buffer
Bram Moolenaar0d9c26d2005-07-02 23:19:16 +00007544 {not available when compiled without the |+syntax|
7545 feature}
7546 Pattern to locate the end of a sentence. The following word will be
7547 checked to start with a capital letter. If not then it is highlighted
Bram Moolenaar8aff23a2005-08-19 20:40:30 +00007548 with SpellCap |hl-SpellCap| (unless the word is also badly spelled).
Bram Moolenaar0d9c26d2005-07-02 23:19:16 +00007549 When this check is not wanted make this option empty.
7550 Only used when 'spell' is set.
Bram Moolenaar0dc065e2005-07-04 22:49:24 +00007551 Be careful with special characters, see |option-backslash| about
7552 including spaces and backslashes.
Bram Moolenaar90cfdbe2005-08-12 19:59:19 +00007553 To set this option automatically depending on the language, see
7554 |set-spc-auto|.
Bram Moolenaar0d9c26d2005-07-02 23:19:16 +00007555
Bram Moolenaar82cf9b62005-06-07 21:09:25 +00007556 *'spellfile'* *'spf'*
7557'spellfile' 'spf' string (default empty)
7558 local to buffer
Bram Moolenaar82cf9b62005-06-07 21:09:25 +00007559 {not available when compiled without the |+syntax|
7560 feature}
7561 Name of the word list file where words are added for the |zg| and |zw|
Bram Moolenaar045e82d2005-07-08 22:25:33 +00007562 commands. It must end in ".{encoding}.add". You need to include the
7563 path, otherwise the file is placed in the current directory.
Bram Moolenaar48c3f4e2022-08-08 15:42:38 +01007564 The path may include characters from 'isfname', space, comma and '@'.
Bram Moolenaar0d9c26d2005-07-02 23:19:16 +00007565 *E765*
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01007566 It may also be a comma-separated list of names. A count before the
Bram Moolenaar0d9c26d2005-07-02 23:19:16 +00007567 |zg| and |zw| commands can be used to access each. This allows using
7568 a personal word list file and a project word list file.
Bram Moolenaar82cf9b62005-06-07 21:09:25 +00007569 When a word is added while this option is empty Vim will set it for
Bram Moolenaar910f66f2006-04-05 20:41:53 +00007570 you: Using the first directory in 'runtimepath' that is writable. If
7571 there is no "spell" directory yet it will be created. For the file
7572 name the first language name that appears in 'spelllang' is used,
Bram Moolenaar3b506942005-06-23 22:36:45 +00007573 ignoring the region.
7574 The resulting ".spl" file will be used for spell checking, it does not
7575 have to appear in 'spelllang'.
7576 Normally one file is used for all regions, but you can add the region
7577 name if you want to. However, it will then only be used when
7578 'spellfile' is set to it, for entries in 'spelllang' only files
7579 without region name will be found.
Bram Moolenaare7566042005-06-17 22:00:15 +00007580 This option cannot be set from a |modeline| or in the |sandbox|, for
7581 security reasons.
Bram Moolenaar82cf9b62005-06-07 21:09:25 +00007582
Bram Moolenaar217ad922005-03-20 22:37:15 +00007583 *'spelllang'* *'spl'*
Bram Moolenaar82cf9b62005-06-07 21:09:25 +00007584'spelllang' 'spl' string (default "en")
Bram Moolenaar217ad922005-03-20 22:37:15 +00007585 local to buffer
Bram Moolenaar217ad922005-03-20 22:37:15 +00007586 {not available when compiled without the |+syntax|
7587 feature}
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01007588 A comma-separated list of word list names. When the 'spell' option is
Bram Moolenaar3b506942005-06-23 22:36:45 +00007589 on spellchecking will be done for these languages. Example: >
7590 set spelllang=en_us,nl,medical
7591< This means US English, Dutch and medical words are recognized. Words
7592 that are not recognized will be highlighted.
Bram Moolenaar911ead12019-04-21 00:03:35 +02007593 The word list name must consist of alphanumeric characters, a dash or
7594 an underscore. It should not include a comma or dot. Using a dash is
Bram Moolenaar3b506942005-06-23 22:36:45 +00007595 recommended to separate the two letter language name from a
7596 specification. Thus "en-rare" is used for rare English words.
7597 A region name must come last and have the form "_xx", where "xx" is
7598 the two-letter, lower case region name. You can use more than one
7599 region by listing them: "en_us,en_ca" supports both US and Canadian
7600 English, but not words specific for Australia, New Zealand or Great
Bram Moolenaarfa735342016-01-03 22:14:44 +01007601 Britain. (Note: currently en_au and en_nz dictionaries are older than
7602 en_ca, en_gb and en_us).
Bram Moolenaarcc63c642013-11-12 04:44:01 +01007603 If the name "cjk" is included East Asian characters are excluded from
7604 spell checking. This is useful when editing text that also has Asian
7605 words.
Bram Moolenaar6c391a72021-09-09 21:55:11 +02007606 Note that the "medical" dictionary does not exist, it is just an
7607 example of a longer name.
Bram Moolenaar8aff23a2005-08-19 20:40:30 +00007608 *E757*
Bram Moolenaarce0842a2005-07-18 21:58:11 +00007609 As a special case the name of a .spl file can be given as-is. The
7610 first "_xx" in the name is removed and used as the region name
7611 (_xx is an underscore, two letters and followed by a non-letter).
7612 This is mainly for testing purposes. You must make sure the correct
7613 encoding is used, Vim doesn't check it.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00007614 When 'encoding' is set the word lists are reloaded. Thus it's a good
Bram Moolenaarce0842a2005-07-18 21:58:11 +00007615 idea to set 'spelllang' after setting 'encoding' to avoid loading the
7616 files twice.
Bram Moolenaar3b506942005-06-23 22:36:45 +00007617 How the related spell files are found is explained here: |spell-load|.
Bram Moolenaar217ad922005-03-20 22:37:15 +00007618
Bram Moolenaar98692072006-02-04 00:57:42 +00007619 If the |spellfile.vim| plugin is active and you use a language name
7620 for which Vim cannot find the .spl file in 'runtimepath' the plugin
7621 will ask you if you want to download the file.
7622
Bram Moolenaar90cfdbe2005-08-12 19:59:19 +00007623 After this option has been set successfully, Vim will source the files
7624 "spell/LANG.vim" in 'runtimepath'. "LANG" is the value of 'spelllang'
Bram Moolenaarb730f0c2018-11-25 03:56:26 +01007625 up to the first character that is not an ASCII letter or number and
7626 not a dash. Also see |set-spc-auto|.
Bram Moolenaar90cfdbe2005-08-12 19:59:19 +00007627
Bram Moolenaar362b44b2020-06-10 21:47:00 +02007628 *'spelloptions'* *'spo'*
7629'spelloptions' 'spo' string (default "")
7630 local to buffer
7631 {not available when compiled without the |+syntax|
7632 feature}
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01007633 A comma-separated list of options for spell checking:
Bram Moolenaar362b44b2020-06-10 21:47:00 +02007634 camel When a word is CamelCased, assume "Cased" is a
7635 separate word: every upper-case character in a word
7636 that comes after a lower case character indicates the
7637 start of a new word.
Bram Moolenaar90cfdbe2005-08-12 19:59:19 +00007638
Bram Moolenaard857f0e2005-06-21 22:37:39 +00007639 *'spellsuggest'* *'sps'*
7640'spellsuggest' 'sps' string (default "best")
7641 global
Bram Moolenaard857f0e2005-06-21 22:37:39 +00007642 {not available when compiled without the |+syntax|
7643 feature}
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00007644 Methods used for spelling suggestions. Both for the |z=| command and
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00007645 the |spellsuggest()| function. This is a comma-separated list of
7646 items:
Bram Moolenaard857f0e2005-06-21 22:37:39 +00007647
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00007648 best Internal method that works best for English. Finds
7649 changes like "fast" and uses a bit of sound-a-like
7650 scoring to improve the ordering.
7651
7652 double Internal method that uses two methods and mixes the
7653 results. The first method is "fast", the other method
Bram Moolenaard857f0e2005-06-21 22:37:39 +00007654 computes how much the suggestion sounds like the bad
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00007655 word. That only works when the language specifies
7656 sound folding. Can be slow and doesn't always give
7657 better results.
7658
7659 fast Internal method that only checks for simple changes:
7660 character inserts/deletes/swaps. Works well for
7661 simple typing mistakes.
7662
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00007663 {number} The maximum number of suggestions listed for |z=|.
Bram Moolenaar8aff23a2005-08-19 20:40:30 +00007664 Not used for |spellsuggest()|. The number of
7665 suggestions is never more than the value of 'lines'
7666 minus two.
7667
Bram Moolenaar585ee072022-01-29 11:22:17 +00007668 timeout:{millisec} Limit the time searching for suggestions to
7669 {millisec} milli seconds. Applies to the following
7670 methods. When omitted the limit is 5000. When
7671 negative there is no limit. {only works when built
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01007672 with the |+reltime| feature}
Bram Moolenaar585ee072022-01-29 11:22:17 +00007673
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00007674 file:{filename} Read file {filename}, which must have two columns,
7675 separated by a slash. The first column contains the
7676 bad word, the second column the suggested good word.
7677 Example:
7678 theribal/terrible ~
7679 Use this for common mistakes that do not appear at the
7680 top of the suggestion list with the internal methods.
7681 Lines without a slash are ignored, use this for
7682 comments.
Bram Moolenaarbcb98982014-05-01 14:08:19 +02007683 The word in the second column must be correct,
7684 otherwise it will not be used. Add the word to an
7685 ".add" file if it is currently flagged as a spelling
7686 mistake.
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00007687 The file is used for all languages.
7688
7689 expr:{expr} Evaluate expression {expr}. Use a function to avoid
Bram Moolenaara4e0b972022-10-01 19:43:52 +01007690 trouble with spaces. Best is to call a function
7691 without arguments, see |expr-option-function|.
7692 |v:val| holds the badly spelled word. The expression
7693 must evaluate to a List of Lists, each with a
7694 suggestion and a score.
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00007695 Example:
Bram Moolenaar214641f2017-03-05 17:04:09 +01007696 [['the', 33], ['that', 44]] ~
Bram Moolenaar2c7a29c2005-12-12 22:02:31 +00007697 Set 'verbose' and use |z=| to see the scores that the
Bram Moolenaar24bbcfe2005-06-28 23:32:02 +00007698 internal methods use. A lower score is better.
7699 This may invoke |spellsuggest()| if you temporarily
7700 set 'spellsuggest' to exclude the "expr:" part.
7701 Errors are silently ignored, unless you set the
7702 'verbose' option to a non-zero value.
7703
7704 Only one of "best", "double" or "fast" may be used. The others may
7705 appear several times in any order. Example: >
7706 :set sps=file:~/.vim/sugg,best,expr:MySuggest()
7707<
7708 This option cannot be set from a |modeline| or in the |sandbox|, for
7709 security reasons.
Bram Moolenaard857f0e2005-06-21 22:37:39 +00007710
7711
Bram Moolenaar071d4272004-06-13 20:20:40 +00007712 *'splitbelow'* *'sb'* *'nosplitbelow'* *'nosb'*
7713'splitbelow' 'sb' boolean (default off)
7714 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007715 When on, splitting a window will put the new window below the current
7716 one. |:split|
7717
Bram Moolenaar3c053a12022-10-16 13:11:12 +01007718 *'splitkeep'* *'spk'*
Luuk van Baal13ece2a2022-10-03 15:28:08 +01007719'splitkeep' 'spk' string (default "cursor")
7720 global
7721 The value of this option determines the scroll behavior when opening,
7722 closing or resizing horizontal splits.
7723
7724 Possible values are:
7725 cursor Keep the same relative cursor position.
7726 screen Keep the text on the same screen line.
7727 topline Keep the topline the same.
7728
7729 For the "screen" and "topline" values, the cursor position will be
7730 changed when necessary. In this case, the jumplist will be populated
7731 with the previous cursor position. For "screen", the text cannot always
Bram Moolenaar3c053a12022-10-16 13:11:12 +01007732 be kept on the same screen line when 'wrap' is enabled.
Luuk van Baal13ece2a2022-10-03 15:28:08 +01007733
Bram Moolenaar071d4272004-06-13 20:20:40 +00007734 *'splitright'* *'spr'* *'nosplitright'* *'nospr'*
7735'splitright' 'spr' boolean (default off)
7736 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007737 When on, splitting a window will put the new window right of the
7738 current one. |:vsplit|
7739
7740 *'startofline'* *'sol'* *'nostartofline'* *'nosol'*
7741'startofline' 'sol' boolean (default on)
7742 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007743 When "on" the commands listed below move the cursor to the first
Bram Moolenaar843ee412004-06-30 16:16:41 +00007744 non-blank of the line. When off the cursor is kept in the same column
Bram Moolenaar71badf92023-04-22 22:40:14 +01007745 (if possible). This applies to the commands:
7746 - CTRL-D, CTRL-U, CTRL-B, CTRL-F, "G", "H", "M", "L", "gg"
7747 - "d", "<<" and ">>" with a linewise operator
7748 - "%" with a count
7749 - buffer changing commands (CTRL-^, :bnext, :bNext, etc.)
7750 - Ex commands that only has a line number, e.g., ":25" or ":+".
Bram Moolenaar071d4272004-06-13 20:20:40 +00007751 In case of buffer changing commands the cursor is placed at the column
7752 where it was the last time the buffer was edited.
7753 NOTE: This option is set when 'compatible' is set.
7754
Bram Moolenaar00654022011-02-25 14:42:19 +01007755 *'statusline'* *'stl'* *E540* *E542*
Bram Moolenaar071d4272004-06-13 20:20:40 +00007756'statusline' 'stl' string (default empty)
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00007757 global or local to window |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00007758 {not available when compiled without the |+statusline|
7759 feature}
Bram Moolenaar944697a2022-02-20 19:48:20 +00007760 When non-empty, this option determines the content of the status line.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007761 Also see |status-line|.
7762
7763 The option consists of printf style '%' items interspersed with
7764 normal text. Each status line item is of the form:
7765 %-0{minwid}.{maxwid}{item}
Bram Moolenaar5e9b2fa2016-02-01 22:37:05 +01007766 All fields except the {item} are optional. A single percent sign can
Bram Moolenaar8133cc62020-10-26 21:05:27 +01007767 be given as "%%".
Bram Moolenaar071d4272004-06-13 20:20:40 +00007768
Bram Moolenaar238a5642006-02-21 22:12:05 +00007769 When the option starts with "%!" then it is used as an expression,
7770 evaluated and the result is used as the option value. Example: >
7771 :set statusline=%!MyStatusLine()
Bram Moolenaar1c6fd1e2019-05-23 22:11:59 +02007772< The *g:statusline_winid* variable will be set to the |window-ID| of the
7773 window that the status line belongs to.
7774 The result can contain %{} items that will be evaluated too.
Bram Moolenaar61d35bd2012-03-28 20:51:51 +02007775 Note that the "%!" expression is evaluated in the context of the
7776 current window and buffer, while %{} items are evaluated in the
7777 context of the window that the statusline belongs to.
Bram Moolenaar238a5642006-02-21 22:12:05 +00007778
7779 When there is error while evaluating the option then it will be made
7780 empty to avoid further errors. Otherwise screen updating would loop.
Bram Moolenaar1b5f03e2023-01-09 20:12:45 +00007781 When the result contains unprintable characters the result is
7782 unpredictable.
Bram Moolenaar238a5642006-02-21 22:12:05 +00007783
Bram Moolenaar071d4272004-06-13 20:20:40 +00007784 Note that the only effect of 'ruler' when this option is set (and
7785 'laststatus' is 2) is controlling the output of |CTRL-G|.
7786
7787 field meaning ~
Bram Moolenaar582fd852005-03-28 20:58:01 +00007788 - Left justify the item. The default is right justified
Bram Moolenaar071d4272004-06-13 20:20:40 +00007789 when minwid is larger than the length of the item.
Bram Moolenaar582fd852005-03-28 20:58:01 +00007790 0 Leading zeroes in numeric items. Overridden by '-'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007791 minwid Minimum width of the item, padding as set by '-' & '0'.
7792 Value must be 50 or less.
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007793 maxwid Maximum width of the item. Truncation occurs with a '<'
Bram Moolenaar071d4272004-06-13 20:20:40 +00007794 on the left for text items. Numeric items will be
7795 shifted down to maxwid-2 digits followed by '>'number
7796 where number is the amount of missing digits, much like
7797 an exponential notation.
7798 item A one letter code as described below.
7799
7800 Following is a description of the possible statusline items. The
7801 second character in "item" is the type:
7802 N for number
7803 S for string
7804 F for flags as described below
7805 - not applicable
7806
7807 item meaning ~
Bram Moolenaar02467872007-05-06 13:22:01 +00007808 f S Path to the file in the buffer, as typed or relative to current
7809 directory.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007810 F S Full path to the file in the buffer.
7811 t S File name (tail) of file in the buffer.
Bram Moolenaare37d50a2008-08-06 17:06:04 +00007812 m F Modified flag, text is "[+]"; "[-]" if 'modifiable' is off.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007813 M F Modified flag, text is ",+" or ",-".
Bram Moolenaare37d50a2008-08-06 17:06:04 +00007814 r F Readonly flag, text is "[RO]".
Bram Moolenaar071d4272004-06-13 20:20:40 +00007815 R F Readonly flag, text is ",RO".
Bram Moolenaare37d50a2008-08-06 17:06:04 +00007816 h F Help buffer flag, text is "[help]".
Bram Moolenaar071d4272004-06-13 20:20:40 +00007817 H F Help buffer flag, text is ",HLP".
Bram Moolenaare37d50a2008-08-06 17:06:04 +00007818 w F Preview window flag, text is "[Preview]".
Bram Moolenaar071d4272004-06-13 20:20:40 +00007819 W F Preview window flag, text is ",PRV".
Bram Moolenaare37d50a2008-08-06 17:06:04 +00007820 y F Type of file in the buffer, e.g., "[vim]". See 'filetype'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007821 Y F Type of file in the buffer, e.g., ",VIM". See 'filetype'.
Bram Moolenaar7fd73202010-07-25 16:58:46 +02007822 q S "[Quickfix List]", "[Location List]" or empty.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007823 k S Value of "b:keymap_name" or 'keymap' when |:lmap| mappings are
7824 being used: "<keymap>"
7825 n N Buffer number.
Bram Moolenaar00654022011-02-25 14:42:19 +01007826 b N Value of character under cursor.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007827 B N As above, in hexadecimal.
7828 o N Byte number in file of byte under cursor, first byte is 1.
7829 Mnemonic: Offset from start of file (with one added)
7830 {not available when compiled without |+byte_offset| feature}
7831 O N As above, in hexadecimal.
Bram Moolenaar582fd852005-03-28 20:58:01 +00007832 N N Printer page number. (Only works in the 'printheader' option.)
Bram Moolenaar071d4272004-06-13 20:20:40 +00007833 l N Line number.
7834 L N Number of lines in buffer.
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02007835 c N Column number (byte index).
7836 v N Virtual column number (screen column).
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007837 V N Virtual column number as -{num}. Not displayed if equal to 'c'.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007838 p N Percentage through file in lines as in |CTRL-G|.
7839 P S Percentage through file of displayed window. This is like the
Bram Moolenaar14b69452013-06-29 23:05:20 +02007840 percentage described for 'ruler'. Always 3 in length, unless
7841 translated.
Luuk van Baalba936f62022-12-15 13:15:39 +00007842 S S 'showcmd' content, see 'showcmdloc'.
Bram Moolenaar582fd852005-03-28 20:58:01 +00007843 a S Argument list status as in default title. ({current} of {max})
Bram Moolenaar071d4272004-06-13 20:20:40 +00007844 Empty if the argument file count is zero or one.
Bram Moolenaar238a5642006-02-21 22:12:05 +00007845 { NF Evaluate expression between '%{' and '}' and substitute result.
Bram Moolenaar6d150f72018-04-21 20:03:20 +02007846 Note that there is no '%' before the closing '}'. The
7847 expression cannot contain a '}' character, call a function to
Bram Moolenaar0c0734d2019-11-26 21:44:46 +01007848 work around that. See |stl-%{| below.
shadmansaleh30e3de22021-05-15 17:23:28 +02007849 {% - This is almost same as { except the result of the expression is
7850 re-evaluated as a statusline format string. Thus if the
7851 return value of expr contains % items they will get expanded.
7852 The expression can contain the } character, the end of
7853 expression is denoted by %}.
Bram Moolenaar22863042021-10-16 15:23:36 +01007854 For example: >
shadmansaleh30e3de22021-05-15 17:23:28 +02007855 func! Stl_filename() abort
7856 return "%t"
7857 endfunc
7858< `stl=%{Stl_filename()}` results in `"%t"`
7859 `stl=%{%Stl_filename()%}` results in `"Name of current file"`
Bram Moolenaar22863042021-10-16 15:23:36 +01007860 %} - End of `{%` expression
Bram Moolenaar071d4272004-06-13 20:20:40 +00007861 ( - Start of item group. Can be used for setting the width and
7862 alignment of a section. Must be followed by %) somewhere.
7863 ) - End of item group. No width fields allowed.
Bram Moolenaard1f56e62006-02-22 21:25:37 +00007864 T N For 'tabline': start of tab page N label. Use %T after the last
7865 label. This information is used for mouse clicks.
7866 X N For 'tabline': start of close tab N label. Use %X after the
7867 label, e.g.: %3Xclose%X. Use %999X for a "close current tab"
7868 mark. This information is used for mouse clicks.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007869 < - Where to truncate line if too long. Default is at the start.
7870 No width fields allowed.
Yegappan Lakshmanan3ec78f92023-02-11 11:15:25 +00007871 = - Separation point between alignment sections. Each section will
7872 be separated by an equal number of spaces. With one %= what
7873 comes after it will be right-aligned. With two %= there is a
7874 middle part, with white space left and right of it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007875 No width fields allowed.
Bram Moolenaar238a5642006-02-21 22:12:05 +00007876 # - Set highlight group. The name must follow and then a # again.
7877 Thus use %#HLname# for highlight group HLname. The same
7878 highlighting is used, also for the statusline of non-current
7879 windows.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007880 * - Set highlight group to User{N}, where {N} is taken from the
Bram Moolenaar582fd852005-03-28 20:58:01 +00007881 minwid field, e.g. %1*. Restore normal highlight with %* or %0*.
Bram Moolenaarbe4e0162023-02-02 13:59:48 +00007882 The difference between User{N} and StatusLine will be applied to
7883 StatusLineNC for the statusline of non-current windows.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007884 The number N must be between 1 and 9. See |hl-User1..9|
7885
Bram Moolenaare37d50a2008-08-06 17:06:04 +00007886 When displaying a flag, Vim removes the leading comma, if any, when
7887 that flag comes right after plaintext. This will make a nice display
7888 when flags are used like in the examples below.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007889
Bram Moolenaar582fd852005-03-28 20:58:01 +00007890 When all items in a group becomes an empty string (i.e. flags that are
Bram Moolenaar071d4272004-06-13 20:20:40 +00007891 not set) and a minwid is not set for the group, the whole group will
7892 become empty. This will make a group like the following disappear
7893 completely from the statusline when none of the flags are set. >
7894 :set statusline=...%(\ [%M%R%H]%)...
Bram Moolenaar1c6fd1e2019-05-23 22:11:59 +02007895< Beware that an expression is evaluated each and every time the status
7896 line is displayed.
Bram Moolenaar0c0734d2019-11-26 21:44:46 +01007897 *stl-%{* *g:actual_curbuf* *g:actual_curwin*
Bram Moolenaarade0d392020-01-21 22:33:58 +01007898 While evaluating %{} the current buffer and current window will be set
7899 temporarily to that of the window (and buffer) whose statusline is
Bram Moolenaar0c0734d2019-11-26 21:44:46 +01007900 currently being drawn. The expression will evaluate in this context.
7901 The variable "g:actual_curbuf" is set to the `bufnr()` number of the
7902 real current buffer and "g:actual_curwin" to the |window-ID| of the
7903 real current window. These values are strings.
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00007904
Bram Moolenaar30b65812012-07-12 22:01:11 +02007905 The 'statusline' option will be evaluated in the |sandbox| if set from
7906 a modeline, see |sandbox-option|.
Bram Moolenaar110289e2019-05-23 15:38:06 +02007907 This option cannot be set in a modeline when 'modelineexpr' is off.
Bram Moolenaarb71eaae2006-01-20 23:10:18 +00007908
7909 It is not allowed to change text or jump to another window while
7910 evaluating 'statusline' |textlock|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007911
7912 If the statusline is not updated when you want it (e.g., after setting
7913 a variable that's used in an expression), you can force an update by
Bram Moolenaarcfa8f9a2022-06-03 21:59:47 +01007914 using `:redrawstatus`.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007915
Bram Moolenaarcfa8f9a2022-06-03 21:59:47 +01007916 A result of all digits is regarded a number for display purposes.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007917 Otherwise the result is taken as flag text and applied to the rules
7918 described above.
7919
Bram Moolenaarcd71fa32005-03-11 22:46:48 +00007920 Watch out for errors in expressions. They may render Vim unusable!
Bram Moolenaar071d4272004-06-13 20:20:40 +00007921 If you are stuck, hold down ':' or 'Q' to get a prompt, then quit and
Bram Moolenaarc4da1132017-07-15 19:39:43 +02007922 edit your .vimrc or whatever with "vim --clean" to get it right.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007923
7924 Examples:
7925 Emulate standard status line with 'ruler' set >
7926 :set statusline=%<%f\ %h%m%r%=%-14.(%l,%c%V%)\ %P
7927< Similar, but add ASCII value of char under the cursor (like "ga") >
7928 :set statusline=%<%f%h%m%r%=%b\ 0x%B\ \ %l,%c%V\ %P
7929< Display byte count and byte value, modified flag in red. >
7930 :set statusline=%<%f%=\ [%1*%M%*%n%R%H]\ %-19(%3l,%02c%03V%)%O'%02b'
7931 :hi User1 term=inverse,bold cterm=inverse,bold ctermfg=red
7932< Display a ,GZ flag if a compressed file is loaded >
7933 :set statusline=...%r%{VarExists('b:gzflag','\ [GZ]')}%h...
7934< In the |:autocmd|'s: >
7935 :let b:gzflag = 1
7936< And: >
7937 :unlet b:gzflag
7938< And define this function: >
7939 :function VarExists(var, val)
7940 : if exists(a:var) | return a:val | else | return '' | endif
7941 :endfunction
7942<
7943 *'suffixes'* *'su'*
7944'suffixes' 'su' string (default ".bak,~,.o,.h,.info,.swp,.obj")
7945 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007946 Files with these suffixes get a lower priority when multiple files
7947 match a wildcard. See |suffixes|. Commas can be used to separate the
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007948 suffixes. Spaces after the comma are ignored. A dot is also seen as
7949 the start of a suffix. To avoid a dot or comma being recognized as a
Bram Moolenaar071d4272004-06-13 20:20:40 +00007950 separator, precede it with a backslash (see |option-backslash| about
7951 including spaces and backslashes).
7952 See 'wildignore' for completely ignoring files.
7953 The use of |:set+=| and |:set-=| is preferred when adding or removing
7954 suffixes from the list. This avoids problems when a future version
7955 uses another default.
7956
7957 *'suffixesadd'* *'sua'*
7958'suffixesadd' 'sua' string (default "")
7959 local to buffer
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01007960 Comma-separated list of suffixes, which are used when searching for a
Bram Moolenaar071d4272004-06-13 20:20:40 +00007961 file for the "gf", "[I", etc. commands. Example: >
7962 :set suffixesadd=.java
7963<
7964 *'swapfile'* *'swf'* *'noswapfile'* *'noswf'*
7965'swapfile' 'swf' boolean (default on)
7966 local to buffer
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007967 Use a swapfile for the buffer. This option can be reset when a
Bram Moolenaar071d4272004-06-13 20:20:40 +00007968 swapfile is not wanted for a specific buffer. For example, with
7969 confidential information that even root must not be able to access.
7970 Careful: All text will be in memory:
7971 - Don't use this for big files.
7972 - Recovery will be impossible!
7973 A swapfile will only be present when |'updatecount'| is non-zero and
7974 'swapfile' is set.
7975 When 'swapfile' is reset, the swap file for the current buffer is
7976 immediately deleted. When 'swapfile' is set, and 'updatecount' is
7977 non-zero, a swap file is immediately created.
7978 Also see |swap-file| and |'swapsync'|.
Bram Moolenaar76f3b1a2014-03-27 22:30:07 +01007979 If you want to open a new buffer without creating a swap file for it,
7980 use the |:noswapfile| modifier.
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01007981 See 'directory' for where the swap file is created.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007982
7983 This option is used together with 'bufhidden' and 'buftype' to
7984 specify special kinds of buffers. See |special-buffers|.
7985
7986 *'swapsync'* *'sws'*
7987'swapsync' 'sws' string (default "fsync")
7988 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00007989 When this option is not empty a swap file is synced to disk after
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00007990 writing to it. This takes some time, especially on busy unix systems.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007991 When this option is empty parts of the swap file may be in memory and
7992 not written to disk. When the system crashes you may lose more work.
7993 On Unix the system does a sync now and then without Vim asking for it,
7994 so the disadvantage of setting this option off is small. On some
7995 systems the swap file will not be written at all. For a unix system
7996 setting it to "sync" will use the sync() call instead of the default
7997 fsync(), which may work better on some systems.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00007998 The 'fsync' option is used for the actual file.
Bram Moolenaar071d4272004-06-13 20:20:40 +00007999
8000 *'switchbuf'* *'swb'*
8001'switchbuf' 'swb' string (default "")
8002 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008003 This option controls the behavior when switching between buffers.
Yegappan Lakshmanan54be5fb2023-05-12 17:49:13 +01008004 This option is checked, when
8005 - jumping to errors with the |quickfix| commands (|:cc|, |:cn|, |:cp|,
h_east59858792023-10-25 22:47:05 +09008006 etc.).
Yegappan Lakshmanan54be5fb2023-05-12 17:49:13 +01008007 - jumping to a tag using the |:stag| command.
8008 - opening a file using the |CTRL-W_f| or |CTRL-W_F| command.
8009 - jumping to a buffer using a buffer split command (e.g. |:sbuffer|,
8010 |:sbnext|, or |:sbrewind|).
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01008011 Possible values (comma-separated list):
Yegappan Lakshmanan54be5fb2023-05-12 17:49:13 +01008012 useopen If included, jump to the first open window in the
8013 current tab page that contains the specified buffer
8014 (if there is one). Otherwise: Do not examine other
8015 windows.
Bram Moolenaar779b74b2006-04-10 14:55:34 +00008016 usetab Like "useopen", but also consider windows in other tab
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00008017 pages.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008018 split If included, split the current window before loading
Bram Moolenaar15146672011-10-20 22:22:38 +02008019 a buffer for a |quickfix| command that display errors.
Bram Moolenaar63b74a82019-03-24 15:09:13 +01008020 Otherwise: do not split, use current window (when used
8021 in the quickfix window: the previously used window or
8022 split if there is no other window).
Bram Moolenaara594d772015-06-19 14:41:49 +02008023 vsplit Just like "split" but split vertically.
Bram Moolenaar446cb832008-06-24 21:56:24 +00008024 newtab Like "split", but open a new tab page. Overrules
Bram Moolenaar0bc380a2010-07-10 13:52:13 +02008025 "split" when both are present.
Bram Moolenaar539aa6b2019-11-17 18:09:38 +01008026 uselast If included, jump to the previously used window when
8027 jumping to errors with |quickfix| commands.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008028
Bram Moolenaar3b56eb32005-07-11 22:40:32 +00008029 *'synmaxcol'* *'smc'*
8030'synmaxcol' 'smc' number (default 3000)
8031 local to buffer
Bram Moolenaar3b56eb32005-07-11 22:40:32 +00008032 {not available when compiled without the |+syntax|
8033 feature}
Bram Moolenaarce0842a2005-07-18 21:58:11 +00008034 Maximum column in which to search for syntax items. In long lines the
8035 text after this column is not highlighted and following lines may not
8036 be highlighted correctly, because the syntax state is cleared.
Bram Moolenaar3b56eb32005-07-11 22:40:32 +00008037 This helps to avoid very slow redrawing for an XML file that is one
8038 long line.
8039 Set to zero to remove the limit.
8040
Bram Moolenaar071d4272004-06-13 20:20:40 +00008041 *'syntax'* *'syn'*
8042'syntax' 'syn' string (default empty)
Christian Brabandt596ad662023-08-16 00:11:09 +02008043 local to buffer |local-noglobal|
Bram Moolenaar071d4272004-06-13 20:20:40 +00008044 {not available when compiled without the |+syntax|
8045 feature}
8046 When this option is set, the syntax with this name is loaded, unless
8047 syntax highlighting has been switched off with ":syntax off".
8048 Otherwise this option does not always reflect the current syntax (the
8049 b:current_syntax variable does).
8050 This option is most useful in a modeline, for a file which syntax is
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00008051 not automatically recognized. Example, in an IDL file:
8052 /* vim: set syntax=idl : */ ~
8053 When a dot appears in the value then this separates two filetype
8054 names. Example:
8055 /* vim: set syntax=c.doxygen : */ ~
8056 This will use the "c" syntax first, then the "doxygen" syntax.
8057 Note that the second one must be prepared to be loaded as an addition,
8058 otherwise it will be skipped. More than one dot may appear.
8059 To switch off syntax highlighting for the current file, use: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00008060 :set syntax=OFF
8061< To switch syntax highlighting on according to the current value of the
8062 'filetype' option: >
8063 :set syntax=ON
8064< What actually happens when setting the 'syntax' option is that the
8065 Syntax autocommand event is triggered with the value as argument.
8066 This option is not copied to another buffer, independent of the 's' or
8067 'S' flag in 'cpoptions'.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00008068 Only normal file name characters can be used, "/\*?[|<>" are illegal.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008069
Bram Moolenaarfd2ac762006-03-01 22:09:21 +00008070 *'tabline'* *'tal'*
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00008071'tabline' 'tal' string (default empty)
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00008072 global
Bram Moolenaar944697a2022-02-20 19:48:20 +00008073 When non-empty, this option determines the content of the tab pages
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00008074 line at the top of the Vim window. When empty Vim will use a default
Bram Moolenaard1f56e62006-02-22 21:25:37 +00008075 tab pages line. See |setting-tabline| for more info.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00008076
8077 The tab pages line only appears as specified with the 'showtabline'
Bram Moolenaar5c8837f2006-02-25 21:52:33 +00008078 option and only when there is no GUI tab line. When 'e' is in
8079 'guioptions' and the GUI supports a tab line 'guitablabel' is used
Bram Moolenaar7f036442010-08-15 15:24:20 +02008080 instead. Note that the two tab pages lines are very different.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00008081
8082 The value is evaluated like with 'statusline'. You can use
8083 |tabpagenr()|, |tabpagewinnr()| and |tabpagebuflist()| to figure out
Bram Moolenaard1f56e62006-02-22 21:25:37 +00008084 the text to be displayed. Use "%1T" for the first label, "%2T" for
8085 the second one, etc. Use "%X" items for closing labels.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00008086
Bram Moolenaare12bab32019-01-08 22:02:56 +01008087 When changing something that is used in 'tabline' that does not
8088 trigger it to be updated, use |:redrawtabline|.
Bram Moolenaar110289e2019-05-23 15:38:06 +02008089 This option cannot be set in a modeline when 'modelineexpr' is off.
Bram Moolenaare12bab32019-01-08 22:02:56 +01008090
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00008091 Keep in mind that only one of the tab pages is the current one, others
8092 are invisible and you can't jump to their windows.
8093
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00008094
Bram Moolenaarfd2ac762006-03-01 22:09:21 +00008095 *'tabpagemax'* *'tpm'*
8096'tabpagemax' 'tpm' number (default 10)
8097 global
Bram Moolenaarfd2ac762006-03-01 22:09:21 +00008098 Maximum number of tab pages to be opened by the |-p| command line
8099 argument or the ":tab all" command. |tabpage|
8100
8101
8102 *'tabstop'* *'ts'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008103'tabstop' 'ts' number (default 8)
8104 local to buffer
8105 Number of spaces that a <Tab> in the file counts for. Also see
Bram Moolenaarf10911e2022-01-29 22:20:48 +00008106 the |:retab| command, and the 'softtabstop' option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008107
8108 Note: Setting 'tabstop' to any other value than 8 can make your file
Bram Moolenaarf10911e2022-01-29 22:20:48 +00008109 appear wrong in many places, e.g., when printing it.
8110 The value must be more than 0 and less than 10000.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008111
8112 There are four main ways to use tabs in Vim:
8113 1. Always keep 'tabstop' at 8, set 'softtabstop' and 'shiftwidth' to 4
8114 (or 3 or whatever you prefer) and use 'noexpandtab'. Then Vim
Bram Moolenaarebcbd022007-05-12 14:28:25 +00008115 will use a mix of tabs and spaces, but typing <Tab> and <BS> will
Bram Moolenaar071d4272004-06-13 20:20:40 +00008116 behave like a tab appears every 4 (or 3) characters.
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01008117 This is the recommended way, the file will look the same with other
8118 tools and when listing it in a terminal.
8119 2. Set 'softtabstop' and 'shiftwidth' to whatever you prefer and use
8120 'expandtab'. This way you will always insert spaces. The
8121 formatting will never be messed up when 'tabstop' is changed (leave
8122 it at 8 just in case). The file will be a bit larger.
8123 You do need to check if no Tabs exist in the file. You can get rid
8124 of them by first setting 'expandtab' and using `%retab!`, making
8125 sure the value of 'tabstop' is set correctly.
8126 3. Set 'tabstop' and 'shiftwidth' to whatever you prefer and use
Bram Moolenaar071d4272004-06-13 20:20:40 +00008127 'expandtab'. This way you will always insert spaces. The
8128 formatting will never be messed up when 'tabstop' is changed.
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01008129 You do need to check if no Tabs exist in the file, just like in the
8130 item just above.
8131 4. Set 'tabstop' and 'shiftwidth' to whatever you prefer and use a
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00008132 |modeline| to set these values when editing the file again. Only
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01008133 works when using Vim to edit the file, other tools assume a tabstop
8134 is worth 8 spaces.
8135 5. Always set 'tabstop' and 'shiftwidth' to the same value, and
Bram Moolenaar071d4272004-06-13 20:20:40 +00008136 'noexpandtab'. This should then work (for initial indents only)
8137 for any tabstop setting that people use. It might be nice to have
8138 tabs after the first non-blank inserted as spaces if you do this
8139 though. Otherwise aligned comments will be wrong when 'tabstop' is
8140 changed.
8141
Bram Moolenaar04958cb2018-06-23 19:23:02 +02008142 If Vim is compiled with the |+vartabs| feature then the value of
8143 'tabstop' will be ignored if |'vartabstop'| is set to anything other
8144 than an empty string.
8145
Bram Moolenaar071d4272004-06-13 20:20:40 +00008146 *'tagbsearch'* *'tbs'* *'notagbsearch'* *'notbs'*
8147'tagbsearch' 'tbs' boolean (default on)
8148 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008149 When searching for a tag (e.g., for the |:ta| command), Vim can either
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00008150 use a binary search or a linear search in a tags file. Binary
Bram Moolenaar071d4272004-06-13 20:20:40 +00008151 searching makes searching for a tag a LOT faster, but a linear search
8152 will find more tags if the tags file wasn't properly sorted.
8153 Vim normally assumes that your tags files are sorted, or indicate that
8154 they are not sorted. Only when this is not the case does the
8155 'tagbsearch' option need to be switched off.
8156
8157 When 'tagbsearch' is on, binary searching is first used in the tags
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00008158 files. In certain situations, Vim will do a linear search instead for
Bram Moolenaar071d4272004-06-13 20:20:40 +00008159 certain files, or retry all files with a linear search. When
8160 'tagbsearch' is off, only a linear search is done.
8161
8162 Linear searching is done anyway, for one file, when Vim finds a line
8163 at the start of the file indicating that it's not sorted: >
Bram Moolenaar446cb832008-06-24 21:56:24 +00008164 !_TAG_FILE_SORTED 0 /some comment/
Bram Moolenaar071d4272004-06-13 20:20:40 +00008165< [The whitespace before and after the '0' must be a single <Tab>]
8166
8167 When a binary search was done and no match was found in any of the
Bram Moolenaar0f6562e2015-11-24 18:48:14 +01008168 files listed in 'tags', and case is ignored or a pattern is used
Bram Moolenaar071d4272004-06-13 20:20:40 +00008169 instead of a normal tag name, a retry is done with a linear search.
8170 Tags in unsorted tags files, and matches with different case will only
8171 be found in the retry.
8172
Bram Moolenaard4755bb2004-09-02 19:12:26 +00008173 If a tag file indicates that it is case-fold sorted, the second,
Bram Moolenaar0f6562e2015-11-24 18:48:14 +01008174 linear search can be avoided when case is ignored. Use a value of '2'
8175 in the "!_TAG_FILE_SORTED" line for this. A tag file can be case-fold
8176 sorted with the -f switch to "sort" in most unices, as in the command:
Bram Moolenaar47c532e2022-03-19 15:18:53 +00008177 "sort -f -o tags tags". For Universal ctags and Exuberant ctags
8178 version 5.x or higher (at least 5.5) the --sort=foldcase switch can be
8179 used for this as well. Note that case must be folded to uppercase for
8180 this to work.
Bram Moolenaar0f6562e2015-11-24 18:48:14 +01008181
8182 By default, tag searches are case-sensitive. Case is ignored when
8183 'ignorecase' is set and 'tagcase' is "followic", or when 'tagcase' is
8184 "ignore".
Bram Moolenaar66e29d72016-08-20 16:57:02 +02008185 Also when 'tagcase' is "followscs" and 'smartcase' is set, or
8186 'tagcase' is "smart", and the pattern contains only lowercase
8187 characters.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008188
8189 When 'tagbsearch' is off, tags searching is slower when a full match
8190 exists, but faster when no full match exists. Tags in unsorted tags
8191 files may only be found with 'tagbsearch' off.
8192 When the tags file is not sorted, or sorted in a wrong way (not on
8193 ASCII byte value), 'tagbsearch' should be off, or the line given above
8194 must be included in the tags file.
8195 This option doesn't affect commands that find all matching tags (e.g.,
8196 command-line completion and ":help").
Bram Moolenaar071d4272004-06-13 20:20:40 +00008197
Bram Moolenaar0f6562e2015-11-24 18:48:14 +01008198 *'tagcase'* *'tc'*
8199'tagcase' 'tc' string (default "followic")
8200 global or local to buffer |global-local|
Bram Moolenaar0f6562e2015-11-24 18:48:14 +01008201 This option specifies how case is handled when searching the tags
8202 file:
8203 followic Follow the 'ignorecase' option
Bram Moolenaar66e29d72016-08-20 16:57:02 +02008204 followscs Follow the 'smartcase' and 'ignorecase' options
Bram Moolenaar0f6562e2015-11-24 18:48:14 +01008205 ignore Ignore case
8206 match Match case
Bram Moolenaar66e29d72016-08-20 16:57:02 +02008207 smart Ignore case unless an upper case letter is used
Bram Moolenaar036986f2017-03-16 17:41:02 +01008208 NOTE: This option is set to the Vi default value when 'compatible' is
8209 set and to the Vim default value when 'compatible' is reset.
Bram Moolenaar0f6562e2015-11-24 18:48:14 +01008210
Bram Moolenaar45e18cb2019-04-28 18:05:35 +02008211 *'tagfunc'* *'tfu'*
8212'tagfunc' 'tfu' string (default: empty)
8213 local to buffer
8214 {not available when compiled without the |+eval|
8215 feature}
8216 This option specifies a function to be used to perform tag searches.
8217 The function gets the tag pattern and should return a List of matching
8218 tags. See |tag-function| for an explanation of how to write the
Yegappan Lakshmanan19916a82021-11-24 16:32:55 +00008219 function and an example. The value can be the name of a function, a
8220 |lambda| or a |Funcref|. See |option-value-function| for more
8221 information.
dkearns8ebdbc92023-10-29 06:26:19 +11008222 This option cannot be set from a |modeline| or in the |sandbox|, for
8223 security reasons.
Bram Moolenaar45e18cb2019-04-28 18:05:35 +02008224
Bram Moolenaar071d4272004-06-13 20:20:40 +00008225 *'taglength'* *'tl'*
8226'taglength' 'tl' number (default 0)
8227 global
8228 If non-zero, tags are significant up to this number of characters.
8229
8230 *'tagrelative'* *'tr'* *'notagrelative'* *'notr'*
8231'tagrelative' 'tr' boolean (Vim default: on, Vi default: off)
8232 global
Bram Moolenaarc6fe9192006-04-09 21:54:49 +00008233 If on and using a tags file in another directory, file names in that
8234 tags file are relative to the directory where the tags file is.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008235 NOTE: This option is set to the Vi default value when 'compatible' is
8236 set and to the Vim default value when 'compatible' is reset.
8237
8238 *'tags'* *'tag'* *E433*
8239'tags' 'tag' string (default "./tags,tags", when compiled with
8240 |+emacs_tags|: "./tags,./TAGS,tags,TAGS")
8241 global or local to buffer |global-local|
8242 Filenames for the tag command, separated by spaces or commas. To
Yee Cheng Chin54844852023-10-09 18:12:31 +02008243 include a space or comma in a file name, precede it with backslashes
8244 (see |option-backslash| about including spaces/commas and backslashes).
Bram Moolenaar071d4272004-06-13 20:20:40 +00008245 When a file name starts with "./", the '.' is replaced with the path
8246 of the current file. But only when the 'd' flag is not included in
8247 'cpoptions'. Environment variables are expanded |:set_env|. Also see
8248 |tags-option|.
8249 "*", "**" and other wildcards can be used to search for tags files in
Bram Moolenaare2b590e2010-08-08 18:29:48 +02008250 a directory tree. See |file-searching|. E.g., "/lib/**/tags" will
8251 find all files named "tags" below "/lib". The filename itself cannot
8252 contain wildcards, it is used as-is. E.g., "/lib/**/tags?" will find
Bram Moolenaar2bd9dbc2022-08-25 18:12:06 +01008253 files called "tags?".
Bram Moolenaare7eb9df2005-09-09 19:49:30 +00008254 The |tagfiles()| function can be used to get a list of the file names
8255 actually used.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008256 If Vim was compiled with the |+emacs_tags| feature, Emacs-style tag
8257 files are also supported. They are automatically recognized. The
8258 default value becomes "./tags,./TAGS,tags,TAGS", unless case
8259 differences are ignored (MS-Windows). |emacs-tags|
8260 The use of |:set+=| and |:set-=| is preferred when adding or removing
8261 file names from the list. This avoids problems when a future version
8262 uses another default.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008263
8264 *'tagstack'* *'tgst'* *'notagstack'* *'notgst'*
8265'tagstack' 'tgst' boolean (default on)
8266 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008267 When on, the |tagstack| is used normally. When off, a ":tag" or
8268 ":tselect" command with an argument will not push the tag onto the
8269 tagstack. A following ":tag" without an argument, a ":pop" command or
8270 any other command that uses the tagstack will use the unmodified
8271 tagstack, but does change the pointer to the active entry.
8272 Resetting this option is useful when using a ":tag" command in a
8273 mapping which should not change the tagstack.
8274
Bram Moolenaar8a5115c2016-01-09 19:41:11 +01008275 *'tcldll'*
Bram Moolenaar3848e002016-03-19 18:42:29 +01008276'tcldll' string (default depends on the build)
Bram Moolenaar8a5115c2016-01-09 19:41:11 +01008277 global
Bram Moolenaar8a5115c2016-01-09 19:41:11 +01008278 {only available when compiled with the |+tcl/dyn|
8279 feature}
8280 Specifies the name of the Tcl shared library. The default is
8281 DYNAMIC_TCL_DLL, which was specified at compile time.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02008282 Environment variables are expanded |:set_env|.
Bram Moolenaar8a5115c2016-01-09 19:41:11 +01008283 This option cannot be set from a |modeline| or in the |sandbox|, for
8284 security reasons.
8285
Bram Moolenaar071d4272004-06-13 20:20:40 +00008286 *'term'* *E529* *E530* *E531*
8287'term' string (default is $TERM, if that fails:
8288 in the GUI: "builtin_gui"
8289 on Amiga: "amiga"
Bram Moolenaarb3f74062020-02-26 16:16:53 +01008290 on Haiku: "xterm"
Bram Moolenaar071d4272004-06-13 20:20:40 +00008291 on Mac: "mac-ansi"
Bram Moolenaar071d4272004-06-13 20:20:40 +00008292 on Unix: "ansi"
8293 on VMS: "ansi"
8294 on Win 32: "win32")
8295 global
8296 Name of the terminal. Used for choosing the terminal control
8297 characters. Environment variables are expanded |:set_env|.
8298 For example: >
8299 :set term=$TERM
8300< See |termcap|.
8301
8302 *'termbidi'* *'tbidi'*
8303 *'notermbidi'* *'notbidi'*
8304'termbidi' 'tbidi' boolean (default off, on for "mlterm")
8305 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008306 {only available when compiled with the |+arabic|
8307 feature}
8308 The terminal is in charge of Bi-directionality of text (as specified
8309 by Unicode). The terminal is also expected to do the required shaping
8310 that some languages (such as Arabic) require.
8311 Setting this option implies that 'rightleft' will not be set when
8312 'arabic' is set and the value of 'arabicshape' will be ignored.
8313 Note that setting 'termbidi' has the immediate effect that
8314 'arabicshape' is ignored, but 'rightleft' isn't changed automatically.
8315 This option is reset when the GUI is started.
8316 For further details see |arabic.txt|.
8317
8318 *'termencoding'* *'tenc'*
Bram Moolenaar3d1cde82020-08-15 18:55:18 +02008319'termencoding' 'tenc' string (default ""; with GTK+ GUI: "utf-8")
Bram Moolenaar071d4272004-06-13 20:20:40 +00008320 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008321 Encoding used for the terminal. This specifies what character
8322 encoding the keyboard produces and the display will understand. For
Bram Moolenaar3848e002016-03-19 18:42:29 +01008323 the GUI it only applies to the keyboard ('encoding' is used for the
Bram Moolenaar3d1cde82020-08-15 18:55:18 +02008324 display).
Bram Moolenaar4b7cdca2020-01-01 16:18:38 +01008325 *E617* *E950*
Bram Moolenaar3df01732017-02-17 22:47:16 +01008326 Note: This does not apply to the GTK+ GUI. After the GUI has been
Bram Moolenaar071d4272004-06-13 20:20:40 +00008327 successfully initialized, 'termencoding' is forcibly set to "utf-8".
8328 Any attempts to set a different value will be rejected, and an error
8329 message is shown.
Bram Moolenaarac360bf2015-09-01 20:31:20 +02008330 For the Win32 GUI and console versions 'termencoding' is not used,
Bram Moolenaar071d4272004-06-13 20:20:40 +00008331 because the Win32 system always passes Unicode characters.
8332 When empty, the same encoding is used as for the 'encoding' option.
8333 This is the normal value.
8334 Not all combinations for 'termencoding' and 'encoding' are valid. See
8335 |encoding-table|.
8336 The value for this option must be supported by internal conversions or
8337 iconv(). When this is not possible no conversion will be done and you
8338 will probably experience problems with non-ASCII characters.
8339 Example: You are working with the locale set to euc-jp (Japanese) and
8340 want to edit a UTF-8 file: >
8341 :let &termencoding = &encoding
8342 :set encoding=utf-8
8343< You need to do this when your system has no locale support for UTF-8.
8344
Bram Moolenaar938ae282023-02-20 20:44:55 +00008345 *'termguicolors'* *'tgc'* *'notermguicolors'* *'notgc'* *E954*
Bram Moolenaar61be73b2016-04-29 22:59:22 +02008346'termguicolors' 'tgc' boolean (default off)
8347 global
Bram Moolenaar61be73b2016-04-29 22:59:22 +02008348 {not available when compiled without the
8349 |+termguicolors| feature}
8350 When on, uses |highlight-guifg| and |highlight-guibg| attributes in
Bram Moolenaarcafafb32018-02-22 21:07:09 +01008351 the terminal (thus using 24-bit color).
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01008352
Bram Moolenaarcafafb32018-02-22 21:07:09 +01008353 Requires a ISO-8613-3 compatible terminal. If setting this option
8354 does not work (produces a colorless UI) reading |xterm-true-color|
8355 might help.
8356
8357 For Win32 console, Windows 10 version 1703 (Creators Update) or later
8358 is required. Use this check to find out: >
8359 if has('vcon')
Bram Moolenaar22f1d0e2018-02-27 14:53:30 +01008360< This requires Vim to be built with the |+vtp| feature.
8361
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +02008362 Note that the "cterm" attributes are still used, not the "gui" ones.
Yasuhiro Matsumotoaa04e1b2022-05-07 14:09:19 +01008363
8364 When using Vim with Windows Terminal, the background of Windows
8365 Terminal is normally filled with the Vim background color. Setting
8366 'termguicolors' and the guibg of the Normal highlight group to NONE
8367 will make the background transparent: >
8368 :hi Normal guibg=NONE
8369<
Bram Moolenaar036986f2017-03-16 17:41:02 +01008370 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaar61be73b2016-04-29 22:59:22 +02008371
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02008372 *'termwinkey'* *'twk'*
8373'termwinkey' 'twk' string (default "")
Bram Moolenaar74675a62017-07-15 13:53:23 +02008374 local to window
Bram Moolenaarf55e4c82017-08-01 20:44:53 +02008375 The key that starts a CTRL-W command in a terminal window. Other keys
Bram Moolenaar74675a62017-07-15 13:53:23 +02008376 are sent to the job running in the window.
Bram Moolenaarf55e4c82017-08-01 20:44:53 +02008377 The <> notation can be used, e.g.: >
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02008378 :set termwinkey=<C-L>
Bram Moolenaarf55e4c82017-08-01 20:44:53 +02008379< The string must be one key stroke but can be multiple bytes.
8380 When not set CTRL-W is used, so that CTRL-W : gets you to the command
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02008381 line. If 'termwinkey' is set to CTRL-L then CTRL-L : gets you to the
Bram Moolenaarf55e4c82017-08-01 20:44:53 +02008382 command line.
Bram Moolenaar74675a62017-07-15 13:53:23 +02008383
Bram Moolenaar6c60f472019-04-28 16:00:35 +02008384 *'termwinscroll'* *'twsl'*
8385'termwinscroll' 'twsl' number (default 10000)
8386 local to buffer
8387 {not available when compiled without the
8388 |+terminal| feature}
8389 Number of scrollback lines to keep. When going over this limit the
8390 first 10% of the scrollback lines are deleted. This is just to reduce
8391 the memory usage. See |Terminal-Normal|.
Bram Moolenaar36968af2021-11-15 17:13:11 +00008392 Also used as a limit for text sent to the terminal in one write,
8393 multiplied by the number of columns times 3 (average number of bytes
8394 per cell).
Bram Moolenaar6c60f472019-04-28 16:00:35 +02008395
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02008396 *'termwinsize'* *'tws'*
8397'termwinsize' 'tws' string (default "")
Bram Moolenaar74675a62017-07-15 13:53:23 +02008398 local to window
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02008399 Size used when opening the |terminal| window. Format:
8400 {rows}x{columns} or {rows}*{columns}.
Bram Moolenaar74675a62017-07-15 13:53:23 +02008401 - When empty the terminal gets the size from the window.
Bram Moolenaar498c2562018-04-15 23:45:15 +02008402 - When set with a "x" (e.g., "24x80") the terminal size is not
8403 adjusted to the window size. If the window is smaller only the
8404 top-left part is displayed.
8405 - When set with a "*" (e.g., "10*50") the terminal size follows the
8406 window size, but will not be smaller than the specified rows and/or
8407 columns.
8408 - When rows is zero then use the height of the window.
8409 - When columns is zero then use the width of the window.
8410 - Using "0x0" or "0*0" is the same as empty.
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02008411 - Can be overruled in the |term_start()| options with "term_rows" and
8412 "term_cols".
Bram Moolenaar498c2562018-04-15 23:45:15 +02008413
8414 Examples:
8415 "30x0" uses 30 rows and the current window width.
8416 "20*0" uses at least 20 rows and the current window width.
8417 "0*40" uses the current window height and at least 40 columns.
Bram Moolenaar1f2903c2017-07-23 19:51:01 +02008418 Note that the command running in the terminal window may still change
8419 the size of the terminal. In that case the Vim window will be
8420 adjusted to that size, if possible.
Bram Moolenaar74675a62017-07-15 13:53:23 +02008421
Bram Moolenaarc6ddce32019-02-08 12:47:03 +01008422 *'termwintype'* *'twt'*
8423'termwintype' 'twt' string (default "")
8424 global
Bram Moolenaarc6ddce32019-02-08 12:47:03 +01008425 {only available when compiled with the |terminal|
8426 feature on MS-Windows}
8427 Specify the virtual console (pty) used when opening the terminal
8428 window.
8429
8430 Possible values are:
Bram Moolenaard9ef1b82019-02-13 19:23:10 +01008431 "" use ConPTY if it is stable, winpty otherwise
Bram Moolenaarc6ddce32019-02-08 12:47:03 +01008432 "winpty" use winpty, fail if not supported
8433 "conpty" use |ConPTY|, fail if not supported
8434
Bram Moolenaard9ef1b82019-02-13 19:23:10 +01008435 |ConPTY| support depends on the platform. Windows 10 October 2018
8436 Update is the first version that supports ConPTY, however it is still
8437 considered unstable. ConPTY might become stable in the next release
8438 of Windows 10. winpty support needs to be installed. If neither is
Bram Moolenaarc6ddce32019-02-08 12:47:03 +01008439 supported then you cannot open a terminal window.
8440
Bram Moolenaar071d4272004-06-13 20:20:40 +00008441 *'terse'* *'noterse'*
8442'terse' boolean (default off)
8443 global
8444 When set: Add 's' flag to 'shortmess' option (this makes the message
8445 for a search that hits the start or end of the file not being
8446 displayed). When reset: Remove 's' flag from 'shortmess' option. {Vi
8447 shortens a lot of messages}
8448
8449 *'textauto'* *'ta'* *'notextauto'* *'nota'*
8450'textauto' 'ta' boolean (Vim default: on, Vi default: off)
8451 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008452 This option is obsolete. Use 'fileformats'.
8453 For backwards compatibility, when 'textauto' is set, 'fileformats' is
8454 set to the default value for the current system. When 'textauto' is
8455 reset, 'fileformats' is made empty.
8456 NOTE: This option is set to the Vi default value when 'compatible' is
8457 set and to the Vim default value when 'compatible' is reset.
8458
8459 *'textmode'* *'tx'* *'notextmode'* *'notx'*
Bram Moolenaar6f345a12019-12-17 21:27:18 +01008460'textmode' 'tx' boolean (Win32: default on,
Bram Moolenaar071d4272004-06-13 20:20:40 +00008461 others: default off)
8462 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00008463 This option is obsolete. Use 'fileformat'.
8464 For backwards compatibility, when 'textmode' is set, 'fileformat' is
8465 set to "dos". When 'textmode' is reset, 'fileformat' is set to
8466 "unix".
8467
8468 *'textwidth'* *'tw'*
8469'textwidth' 'tw' number (default 0)
8470 local to buffer
Bram Moolenaar071d4272004-06-13 20:20:40 +00008471 Maximum width of text that is being inserted. A longer line will be
8472 broken after white space to get this width. A zero value disables
Bram Moolenaarca635012015-09-25 20:34:21 +02008473 this.
8474 'textwidth' is set to 0 when the 'paste' option is set and restored
8475 when 'paste' is reset.
8476 When 'textwidth' is zero, 'wrapmargin' may be used. See also
Bram Moolenaar071d4272004-06-13 20:20:40 +00008477 'formatoptions' and |ins-textwidth|.
Bram Moolenaarfc1421e2006-04-20 22:17:20 +00008478 When 'formatexpr' is set it will be used to break the line.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008479 NOTE: This option is set to 0 when 'compatible' is set.
8480
8481 *'thesaurus'* *'tsr'*
8482'thesaurus' 'tsr' string (default "")
8483 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00008484 List of file names, separated by commas, that are used to lookup words
Bram Moolenaarf4d8b762021-10-17 14:13:09 +01008485 for thesaurus completion commands |i_CTRL-X_CTRL-T|. See
8486 |compl-thesaurus|.
Bram Moolenaarf0d58ef2018-11-16 16:13:44 +01008487
Bram Moolenaarf4d8b762021-10-17 14:13:09 +01008488 This option is not used if 'thesaurusfunc' is set, either for the
8489 buffer or globally.
Bram Moolenaarf0d58ef2018-11-16 16:13:44 +01008490
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00008491 To include a comma in a file name precede it with a backslash. Spaces
Bram Moolenaar071d4272004-06-13 20:20:40 +00008492 after a comma are ignored, otherwise spaces are included in the file
Bram Moolenaarf4d8b762021-10-17 14:13:09 +01008493 name. See |option-backslash| about using backslashes. The use of
8494 |:set+=| and |:set-=| is preferred when adding or removing directories
8495 from the list. This avoids problems when a future version uses
8496 another default. Backticks cannot be used in this option for security
8497 reasons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008498
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00008499 *'thesaurusfunc'* *'tsrfu'*
Yegappan Lakshmanan160e9942021-10-16 15:41:29 +01008500'thesaurusfunc' 'tsrfu' string (default: empty)
Bram Moolenaarf4d8b762021-10-17 14:13:09 +01008501 global or local to buffer |global-local|
Yegappan Lakshmanan160e9942021-10-16 15:41:29 +01008502 {not available when compiled without the |+eval|
8503 feature}
8504 This option specifies a function to be used for thesaurus completion
Bram Moolenaarf4d8b762021-10-17 14:13:09 +01008505 with CTRL-X CTRL-T. |i_CTRL-X_CTRL-T| See |compl-thesaurusfunc|.
Yegappan Lakshmanan8658c752021-12-03 11:09:29 +00008506 The value can be the name of a function, a |lambda| or a |Funcref|.
8507 See |option-value-function| for more information.
Bram Moolenaarf4d8b762021-10-17 14:13:09 +01008508
Yegappan Lakshmanan160e9942021-10-16 15:41:29 +01008509 This option cannot be set from a |modeline| or in the |sandbox|, for
8510 security reasons.
8511
Bram Moolenaar071d4272004-06-13 20:20:40 +00008512 *'tildeop'* *'top'* *'notildeop'* *'notop'*
8513'tildeop' 'top' boolean (default off)
8514 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008515 When on: The tilde command "~" behaves like an operator.
8516 NOTE: This option is reset when 'compatible' is set.
8517
8518 *'timeout'* *'to'* *'notimeout'* *'noto'*
8519'timeout' 'to' boolean (default on)
8520 global
8521 *'ttimeout'* *'nottimeout'*
Bram Moolenaar94237492017-04-23 18:40:21 +02008522'ttimeout' boolean (default off, set in |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008523 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008524 These two options together determine the behavior when part of a
8525 mapped key sequence or keyboard code has been received:
8526
8527 'timeout' 'ttimeout' action ~
8528 off off do not time out
8529 on on or off time out on :mappings and key codes
8530 off on time out on key codes
8531
8532 If both options are off, Vim will wait until either the complete
8533 mapping or key sequence has been received, or it is clear that there
8534 is no mapping or key sequence for the received characters. For
8535 example: if you have mapped "vl" and Vim has received 'v', the next
8536 character is needed to see if the 'v' is followed by an 'l'.
8537 When one of the options is on, Vim will wait for about 1 second for
8538 the next character to arrive. After that the already received
8539 characters are interpreted as single characters. The waiting time can
8540 be changed with the 'timeoutlen' option.
8541 On slow terminals or very busy systems timing out may cause
8542 malfunctioning cursor keys. If both options are off, Vim waits
8543 forever after an entered <Esc> if there are key codes that start
8544 with <Esc>. You will have to type <Esc> twice. If you do not have
8545 problems with key codes, but would like to have :mapped key
8546 sequences not timing out in 1 second, set the 'ttimeout' option and
8547 reset the 'timeout' option.
8548
8549 NOTE: 'ttimeout' is reset when 'compatible' is set.
8550
8551 *'timeoutlen'* *'tm'*
8552'timeoutlen' 'tm' number (default 1000)
8553 global
Bram Moolenaar25c9c682019-05-05 18:13:34 +02008554
Bram Moolenaar071d4272004-06-13 20:20:40 +00008555 *'ttimeoutlen'* *'ttm'*
Bram Moolenaar94237492017-04-23 18:40:21 +02008556'ttimeoutlen' 'ttm' number (default -1, set to 100 in |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008557 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008558 The time in milliseconds that is waited for a key code or mapped key
8559 sequence to complete. Also used for CTRL-\ CTRL-N and CTRL-\ CTRL-G
8560 when part of a command has been typed.
8561 Normally only 'timeoutlen' is used and 'ttimeoutlen' is -1. When a
8562 different timeout value for key codes is desired set 'ttimeoutlen' to
8563 a non-negative number.
8564
8565 ttimeoutlen mapping delay key code delay ~
8566 < 0 'timeoutlen' 'timeoutlen'
8567 >= 0 'timeoutlen' 'ttimeoutlen'
8568
8569 The timeout only happens when the 'timeout' and 'ttimeout' options
8570 tell so. A useful setting would be >
8571 :set timeout timeoutlen=3000 ttimeoutlen=100
8572< (time out on mapping after three seconds, time out on key codes after
8573 a tenth of a second).
8574
8575 *'title'* *'notitle'*
8576'title' boolean (default off, on when title can be restored)
8577 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008578 When on, the title of the window will be set to the value of
8579 'titlestring' (if it is not empty), or to:
8580 filename [+=-] (path) - VIM
8581 Where:
8582 filename the name of the file being edited
8583 - indicates the file cannot be modified, 'ma' off
8584 + indicates the file was modified
8585 = indicates the file is read-only
8586 =+ indicates the file is read-only and modified
8587 (path) is the path of the file being edited
8588 - VIM the server name |v:servername| or "VIM"
8589 Only works if the terminal supports setting window titles
8590 (currently Amiga console, Win32 console, all GUI versions and
Bram Moolenaard1caa942020-04-10 22:10:56 +02008591 terminals with a non-empty 't_ts' option - these are Unix xterm and
Bram Moolenaar071d4272004-06-13 20:20:40 +00008592 iris-ansi by default, where 't_ts' is taken from the builtin termcap).
8593 *X11*
8594 When Vim was compiled with HAVE_X11 defined, the original title will
8595 be restored if possible. The output of ":version" will include "+X11"
8596 when HAVE_X11 was defined, otherwise it will be "-X11". This also
8597 works for the icon name |'icon'|.
8598 But: When Vim was started with the |-X| argument, restoring the title
8599 will not work (except in the GUI).
8600 If the title cannot be restored, it is set to the value of 'titleold'.
8601 You might want to restore the title outside of Vim then.
8602 When using an xterm from a remote machine you can use this command:
8603 rsh machine_name xterm -display $DISPLAY &
8604 then the WINDOWID environment variable should be inherited and the
8605 title of the window should change back to what it should be after
8606 exiting Vim.
8607
8608 *'titlelen'*
8609'titlelen' number (default 85)
8610 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008611 Gives the percentage of 'columns' to use for the length of the window
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00008612 title. When the title is longer, only the end of the path name is
8613 shown. A '<' character before the path name is used to indicate this.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008614 Using a percentage makes this adapt to the width of the window. But
8615 it won't work perfectly, because the actual number of characters
8616 available also depends on the font used and other things in the title
8617 bar. When 'titlelen' is zero the full path is used. Otherwise,
8618 values from 1 to 30000 percent can be used.
8619 'titlelen' is also used for the 'titlestring' option.
8620
8621 *'titleold'*
8622'titleold' string (default "Thanks for flying Vim")
8623 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008624 This option will be used for the window title when exiting Vim if the
8625 original title cannot be restored. Only happens if 'title' is on or
8626 'titlestring' is not empty.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00008627 This option cannot be set from a |modeline| or in the |sandbox|, for
8628 security reasons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008629 *'titlestring'*
8630'titlestring' string (default "")
8631 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008632 When this option is not empty, it will be used for the title of the
8633 window. This happens only when the 'title' option is on.
8634 Only works if the terminal supports setting window titles (currently
8635 Amiga console, Win32 console, all GUI versions and terminals with a
8636 non-empty 't_ts' option).
8637 When Vim was compiled with HAVE_X11 defined, the original title will
Bram Moolenaar51628222016-12-01 23:03:28 +01008638 be restored if possible, see |X11|.
Bram Moolenaar110289e2019-05-23 15:38:06 +02008639
Bram Moolenaar071d4272004-06-13 20:20:40 +00008640 When this option contains printf-style '%' items, they will be
8641 expanded according to the rules used for 'statusline'.
Bram Moolenaar110289e2019-05-23 15:38:06 +02008642 This option cannot be set in a modeline when 'modelineexpr' is off.
8643
Bram Moolenaar071d4272004-06-13 20:20:40 +00008644 Example: >
Bram Moolenaarc51cf032022-02-26 12:25:45 +00008645 :auto BufEnter * let &titlestring = hostname() .. "/" .. expand("%:p")
Bram Moolenaar071d4272004-06-13 20:20:40 +00008646 :set title titlestring=%<%F%=%l/%L-%P titlelen=70
8647< The value of 'titlelen' is used to align items in the middle or right
8648 of the available space.
8649 Some people prefer to have the file name first: >
8650 :set titlestring=%t%(\ %M%)%(\ (%{expand(\"%:~:.:h\")})%)%(\ %a%)
8651< Note the use of "%{ }" and an expression to get the path of the file,
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00008652 without the file name. The "%( %)" constructs are used to add a
Bram Moolenaar071d4272004-06-13 20:20:40 +00008653 separating space only when needed.
8654 NOTE: Use of special characters in 'titlestring' may cause the display
8655 to be garbled (e.g., when it contains a CR or NL character).
8656 {not available when compiled without the |+statusline| feature}
8657
8658 *'toolbar'* *'tb'*
8659'toolbar' 'tb' string (default "icons,tooltips")
8660 global
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01008661 {only for |+GUI_GTK|, |+GUI_Motif| and |+GUI_Photon|}
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00008662 The contents of this option controls various toolbar settings. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00008663 possible values are:
8664 icons Toolbar buttons are shown with icons.
8665 text Toolbar buttons shown with text.
8666 horiz Icon and text of a toolbar button are
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00008667 horizontally arranged. {only in GTK+ 2 GUI}
Bram Moolenaar071d4272004-06-13 20:20:40 +00008668 tooltips Tooltips are active for toolbar buttons.
8669 Tooltips refer to the popup help text which appears after the mouse
8670 cursor is placed over a toolbar button for a brief moment.
8671
8672 If you want the toolbar to be shown with icons as well as text, do the
8673 following: >
8674 :set tb=icons,text
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01008675< Motif cannot display icons and text at the same time. They
Bram Moolenaar071d4272004-06-13 20:20:40 +00008676 will show icons if both are requested.
8677
8678 If none of the strings specified in 'toolbar' are valid or if
8679 'toolbar' is empty, this option is ignored. If you want to disable
8680 the toolbar, you need to set the 'guioptions' option. For example: >
8681 :set guioptions-=T
8682< Also see |gui-toolbar|.
8683
8684 *'toolbariconsize'* *'tbis'*
8685'toolbariconsize' 'tbis' string (default "small")
8686 global
Bram Moolenaar3df01732017-02-17 22:47:16 +01008687 {only in the GTK+ GUI}
Bram Moolenaar071d4272004-06-13 20:20:40 +00008688 Controls the size of toolbar icons. The possible values are:
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01008689 tiny Use tiny icons.
8690 small Use small icons (default).
8691 medium Use medium-sized icons.
8692 large Use large icons.
8693 huge Use even larger icons.
8694 giant Use very big icons.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008695 The exact dimensions in pixels of the various icon sizes depend on
Bram Moolenaar77cdfd12016-03-12 12:57:59 +01008696 the current theme. Common dimensions are giant=48x48, huge=32x32,
8697 large=24x24, medium=24x24, small=20x20 and tiny=16x16.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008698
8699 If 'toolbariconsize' is empty, the global default size as determined
8700 by user preferences or the current theme is used.
8701
8702 *'ttybuiltin'* *'tbi'* *'nottybuiltin'* *'notbi'*
8703'ttybuiltin' 'tbi' boolean (default on)
8704 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008705 When on, the builtin termcaps are searched before the external ones.
8706 When off the builtin termcaps are searched after the external ones.
8707 When this option is changed, you should set the 'term' option next for
8708 the change to take effect, for example: >
8709 :set notbi term=$TERM
8710< See also |termcap|.
8711 Rationale: The default for this option is "on", because the builtin
8712 termcap entries are generally better (many systems contain faulty
8713 xterm entries...).
8714
8715 *'ttyfast'* *'tf'* *'nottyfast'* *'notf'*
Bram Moolenaarc1cf4c92022-11-25 15:09:35 +00008716'ttyfast' 'tf' boolean (default on)
Bram Moolenaar071d4272004-06-13 20:20:40 +00008717 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008718 Indicates a fast terminal connection. More characters will be sent to
8719 the screen for redrawing, instead of using insert/delete line
8720 commands. Improves smoothness of redrawing when there are multiple
8721 windows and the terminal does not support a scrolling region.
8722 Also enables the extra writing of characters at the end of each screen
8723 line for lines that wrap. This helps when using copy/paste with the
8724 mouse in an xterm and other terminals.
8725
Bram Moolenaarc1cf4c92022-11-25 15:09:35 +00008726 The default used to be set only for some terminal names, but these
8727 days nearly all terminals are fast, therefore the default is now "on".
8728 If you have a slow connection you may want to set this option off,
8729 e.g. depending on the host name: >
8730 if hostname() =~ 'faraway'
8731 set nottyfast
8732 endif
8733<
Bram Moolenaar071d4272004-06-13 20:20:40 +00008734 *'ttymouse'* *'ttym'*
8735'ttymouse' 'ttym' string (default depends on 'term')
8736 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008737 {only in Unix and VMS, doesn't work in the GUI; not
8738 available when compiled without |+mouse|}
8739 Name of the terminal type for which mouse codes are to be recognized.
Bram Moolenaar2c7a7632007-05-10 18:19:11 +00008740 Currently these strings are valid:
Bram Moolenaar071d4272004-06-13 20:20:40 +00008741 *xterm-mouse*
8742 xterm xterm-like mouse handling. The mouse generates
8743 "<Esc>[Mscr", where "scr" is three bytes:
8744 "s" = button state
8745 "c" = column plus 33
8746 "r" = row plus 33
Bram Moolenaare968e362014-05-13 20:23:24 +02008747 This only works up to 223 columns! See "dec",
8748 "urxvt", and "sgr" for solutions.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008749 xterm2 Works like "xterm", but with the xterm reporting the
8750 mouse position while the mouse is dragged. This works
8751 much faster and more precise. Your xterm must at
Bram Moolenaarbc7aa852005-03-06 23:38:09 +00008752 least at patchlevel 88 / XFree 3.3.3 for this to
Bram Moolenaar071d4272004-06-13 20:20:40 +00008753 work. See below for how Vim detects this
8754 automatically.
8755 *netterm-mouse*
Bram Moolenaar25c9c682019-05-05 18:13:34 +02008756 netterm NetTerm mouse handling. A left mouse click generates
Bram Moolenaar071d4272004-06-13 20:20:40 +00008757 "<Esc>}r,c<CR>", where "r,c" are two decimal numbers
Bram Moolenaar25c9c682019-05-05 18:13:34 +02008758 for the row and column. No other mouse events are
8759 supported.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008760 *dec-mouse*
8761 dec DEC terminal mouse handling. The mouse generates a
8762 rather complex sequence, starting with "<Esc>[".
Bram Moolenaare4efc3b2005-03-07 23:16:51 +00008763 This is also available for an Xterm, if it was
8764 configured with "--enable-dec-locator".
Bram Moolenaar071d4272004-06-13 20:20:40 +00008765 *jsbterm-mouse*
8766 jsbterm JSB term mouse handling.
8767 *pterm-mouse*
8768 pterm QNX pterm mouse handling.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01008769 *urxvt-mouse*
8770 urxvt Mouse handling for the urxvt (rxvt-unicode) terminal.
Bram Moolenaare968e362014-05-13 20:23:24 +02008771 The mouse works only if the terminal supports this
8772 encoding style, but it does not have 223 columns limit
8773 unlike "xterm" or "xterm2".
Bram Moolenaar9b451252012-08-15 17:43:31 +02008774 *sgr-mouse*
8775 sgr Mouse handling for the terminal that emits SGR-styled
Bram Moolenaare968e362014-05-13 20:23:24 +02008776 mouse reporting. The mouse works even in columns
8777 beyond 223. This option is backward compatible with
8778 "xterm2" because it can also decode "xterm2" style
8779 mouse codes.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008780
8781 The mouse handling must be enabled at compile time |+mouse_xterm|
Bram Moolenaare968e362014-05-13 20:23:24 +02008782 |+mouse_dec| |+mouse_netterm| |+mouse_jsbterm| |+mouse_urxvt|
8783 |+mouse_sgr|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008784 Only "xterm"(2) is really recognized. NetTerm mouse codes are always
8785 recognized, if enabled at compile time. DEC terminal mouse codes
8786 are recognized if enabled at compile time, and 'ttymouse' is not
Bram Moolenaare968e362014-05-13 20:23:24 +02008787 "xterm", "xterm2", "urxvt" or "sgr" (because dec mouse codes conflict
8788 with them).
Bram Moolenaar071d4272004-06-13 20:20:40 +00008789 This option is automatically set to "xterm", when the 'term' option is
Bram Moolenaar45758762016-10-12 23:08:06 +02008790 set to a name that starts with "xterm", "mlterm", "screen", "tmux",
8791 "st" (full match only), "st-" or "stterm", and 'ttymouse' is not set
8792 already.
Bram Moolenaar06cd14d2023-01-10 12:37:38 +00008793 If the terminfo/termcap entry "XM" exists and the first number is
8794 "1006" then 'ttymouse' will be set to "sgr". This works for many
8795 modern terminals.
Bram Moolenaare968e362014-05-13 20:23:24 +02008796 Additionally, if vim is compiled with the |+termresponse| feature and
8797 |t_RV| is set to the escape sequence to request the xterm version
Bram Moolenaarf8a07122019-07-01 22:06:07 +02008798 number, more intelligent detection is done.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008799 The "xterm2" value will be set if the xterm version is reported to be
Bram Moolenaard47d5222018-12-09 20:43:55 +01008800 from 95 to 276. The "sgr" value will be set if Vim detects Mac
8801 Terminal.app, iTerm2 or mintty, and when the xterm version is 277 or
8802 higher.
Bram Moolenaare968e362014-05-13 20:23:24 +02008803 If you do not want 'ttymouse' to be set to "xterm2" or "sgr"
8804 automatically, set t_RV to an empty string: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00008805 :set t_RV=
8806<
8807 *'ttyscroll'* *'tsl'*
8808'ttyscroll' 'tsl' number (default 999)
8809 global
8810 Maximum number of lines to scroll the screen. If there are more lines
8811 to scroll the window is redrawn. For terminals where scrolling is
8812 very slow and redrawing is not slow this can be set to a small number,
8813 e.g., 3, to speed up displaying.
8814
8815 *'ttytype'* *'tty'*
8816'ttytype' 'tty' string (default from $TERM)
8817 global
8818 Alias for 'term', see above.
8819
Bram Moolenaar55debbe2010-05-23 23:34:36 +02008820 *'undodir'* *'udir'*
8821'undodir' 'udir' string (default ".")
8822 global
Bram Moolenaardb84e452010-08-15 13:50:43 +02008823 {only when compiled with the |+persistent_undo| feature}
Bram Moolenaar55debbe2010-05-23 23:34:36 +02008824 List of directory names for undo files, separated with commas.
Bram Moolenaarb230bd52010-05-25 21:02:00 +02008825 See |'backupdir'| for details of the format.
Bram Moolenaar6a244fe2010-05-24 22:02:24 +02008826 "." means using the directory of the file. The undo file name for
8827 "file.txt" is ".file.txt.un~".
8828 For other directories the file name is the full path of the edited
8829 file, with path separators replaced with "%".
Bram Moolenaar55debbe2010-05-23 23:34:36 +02008830 When writing: The first directory that exists is used. "." always
8831 works, no directories after "." will be used for writing.
8832 When reading all entries are tried to find an undo file. The first
8833 undo file that exists is used. When it cannot be read an error is
8834 given, no further entry is used.
8835 See |undo-persistence|.
Bram Moolenaar110289e2019-05-23 15:38:06 +02008836 This option cannot be set from a |modeline| or in the |sandbox|, for
8837 security reasons.
Bram Moolenaar55debbe2010-05-23 23:34:36 +02008838
Bram Moolenaar543b7ef2013-06-01 14:50:56 +02008839 *'undofile'* *'noundofile'* *'udf'* *'noudf'*
Bram Moolenaar55debbe2010-05-23 23:34:36 +02008840'undofile' 'udf' boolean (default off)
8841 local to buffer
Bram Moolenaardb84e452010-08-15 13:50:43 +02008842 {only when compiled with the |+persistent_undo| feature}
Bram Moolenaar55debbe2010-05-23 23:34:36 +02008843 When on, Vim automatically saves undo history to an undo file when
8844 writing a buffer to a file, and restores undo history from the same
8845 file on buffer read.
Bram Moolenaarb230bd52010-05-25 21:02:00 +02008846 The directory where the undo file is stored is specified by 'undodir'.
8847 For more information about this feature see |undo-persistence|.
Bram Moolenaar59f931e2010-07-24 20:27:03 +02008848 The undo file is not read when 'undoreload' causes the buffer from
8849 before a reload to be saved for undo.
Bram Moolenaar97d62492012-11-15 21:28:22 +01008850 When 'undofile' is turned off the undo file is NOT deleted.
Bram Moolenaar036986f2017-03-16 17:41:02 +01008851 NOTE: This option is reset when 'compatible' is set.
Bram Moolenaar55debbe2010-05-23 23:34:36 +02008852
Bram Moolenaar071d4272004-06-13 20:20:40 +00008853 *'undolevels'* *'ul'*
Bram Moolenaar8024f932020-01-14 19:29:13 +01008854'undolevels' 'ul' number (default 100, 1000 for Unix, VMS and Win32)
Bram Moolenaarf5a2fd82013-11-06 05:26:15 +01008855 global or local to buffer |global-local|
Bram Moolenaar071d4272004-06-13 20:20:40 +00008856 Maximum number of changes that can be undone. Since undo information
Bram Moolenaar5be4cee2019-09-27 19:34:08 +02008857 is kept in memory, higher numbers will cause more memory to be used.
8858 Nevertheless, a single change can already use a large amount of memory.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008859 Set to 0 for Vi compatibility: One level of undo and "u" undoes
8860 itself: >
8861 set ul=0
8862< But you can also get Vi compatibility by including the 'u' flag in
8863 'cpoptions', and still be able to use CTRL-R to repeat undo.
Bram Moolenaar945e2db2010-06-05 17:43:32 +02008864 Also see |undo-two-ways|.
Bram Moolenaarf5a2fd82013-11-06 05:26:15 +01008865 Set to -1 for no undo at all. You might want to do this only for the
8866 current buffer: >
8867 setlocal ul=-1
Bram Moolenaar071d4272004-06-13 20:20:40 +00008868< This helps when you run out of memory for a single change.
Bram Moolenaar32efaf62014-11-05 17:02:17 +01008869
8870 The local value is set to -123456 when the global value is to be used.
8871
Bram Moolenaar945e2db2010-06-05 17:43:32 +02008872 Also see |clear-undo|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008873
Bram Moolenaar59f931e2010-07-24 20:27:03 +02008874 *'undoreload'* *'ur'*
8875'undoreload' 'ur' number (default 10000)
8876 global
Bram Moolenaar59f931e2010-07-24 20:27:03 +02008877 Save the whole buffer for undo when reloading it. This applies to the
8878 ":e!" command and reloading for when the buffer changed outside of
8879 Vim. |FileChangedShell|
Bram Moolenaar24a98a02017-09-27 22:23:55 +02008880 The save only happens when this option is negative or when the number
Bram Moolenaar59f931e2010-07-24 20:27:03 +02008881 of lines is smaller than the value of this option.
8882 Set this option to zero to disable undo for a reload.
8883
8884 When saving undo for a reload, any undo file is not read.
8885
8886 Note that this causes the whole buffer to be stored in memory. Set
8887 this option to a lower value if you run out of memory.
8888
Bram Moolenaar071d4272004-06-13 20:20:40 +00008889 *'updatecount'* *'uc'*
8890'updatecount' 'uc' number (default: 200)
8891 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008892 After typing this many characters the swap file will be written to
8893 disk. When zero, no swap file will be created at all (see chapter on
8894 recovery |crash-recovery|). 'updatecount' is set to zero by starting
8895 Vim with the "-n" option, see |startup|. When editing in readonly
8896 mode this option will be initialized to 10000.
8897 The swapfile can be disabled per buffer with |'swapfile'|.
8898 When 'updatecount' is set from zero to non-zero, swap files are
8899 created for all buffers that have 'swapfile' set. When 'updatecount'
8900 is set to zero, existing swap files are not deleted.
8901 Also see |'swapsync'|.
8902 This option has no meaning in buffers where |'buftype'| is "nofile"
8903 or "nowrite".
8904
8905 *'updatetime'* *'ut'*
8906'updatetime' 'ut' number (default 4000)
8907 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008908 If this many milliseconds nothing is typed the swap file will be
8909 written to disk (see |crash-recovery|). Also used for the
8910 |CursorHold| autocommand event.
8911
Bram Moolenaar04958cb2018-06-23 19:23:02 +02008912 *'varsofttabstop'* *'vsts'*
8913'varsofttabstop' 'vsts' string (default "")
8914 local to buffer
8915 {only available when compiled with the |+vartabs|
8916 feature}
Bram Moolenaar04958cb2018-06-23 19:23:02 +02008917 A list of the number of spaces that a <Tab> counts for while editing,
8918 such as inserting a <Tab> or using <BS>. It "feels" like variable-
8919 width <Tab>s are being inserted, while in fact a mixture of spaces
8920 and <Tab>s is used. Tab widths are separated with commas, with the
8921 final value applying to all subsequent tabs.
8922
8923 For example, when editing assembly language files where statements
Bram Moolenaar6dc819b2018-07-03 16:42:19 +02008924 start in the 9th column and comments in the 41st, it may be useful
Bram Moolenaar04958cb2018-06-23 19:23:02 +02008925 to use the following: >
8926 :set varsofttabstop=8,32,8
Bram Moolenaar6dc819b2018-07-03 16:42:19 +02008927< This will set soft tabstops with 8 and 8 + 32 spaces, and 8 more
8928 for every column thereafter.
Bram Moolenaar04958cb2018-06-23 19:23:02 +02008929
8930 Note that the value of |'softtabstop'| will be ignored while
8931 'varsofttabstop' is set.
8932
8933 *'vartabstop'* *'vts'*
8934'vartabstop' 'vts' string (default "")
8935 local to buffer
8936 {only available when compiled with the |+vartabs|
8937 feature}
Bram Moolenaar04958cb2018-06-23 19:23:02 +02008938 A list of the number of spaces that a <Tab> in the file counts for,
8939 separated by commas. Each value corresponds to one tab, with the
8940 final value applying to all subsequent tabs. For example: >
8941 :set vartabstop=4,20,10,8
8942< This will make the first tab 4 spaces wide, the second 20 spaces,
8943 the third 10 spaces, and all following tabs 8 spaces.
8944
8945 Note that the value of |'tabstop'| will be ignored while 'vartabstop'
8946 is set.
8947
Bram Moolenaar071d4272004-06-13 20:20:40 +00008948 *'verbose'* *'vbs'*
8949'verbose' 'vbs' number (default 0)
8950 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00008951 When bigger than zero, Vim will give messages about what it is doing.
8952 Currently, these messages are given:
8953 >= 1 When the viminfo file is read or written.
8954 >= 2 When a file is ":source"'ed.
Bram Moolenaar647a5302020-05-03 17:01:24 +02008955 >= 4 Shell commands.
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00008956 >= 5 Every searched tags file and include file.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008957 >= 8 Files for which a group of autocommands is executed.
8958 >= 9 Every executed autocommand.
Bram Moolenaar647a5302020-05-03 17:01:24 +02008959 >= 11 Finding items in a path
Bram Moolenaar071d4272004-06-13 20:20:40 +00008960 >= 12 Every executed function.
8961 >= 13 When an exception is thrown, caught, finished, or discarded.
8962 >= 14 Anything pending in a ":finally" clause.
Bram Moolenaar823654b2020-05-29 23:03:09 +02008963 >= 15 Every executed Ex command from a script (truncated at 200
8964 characters).
Bram Moolenaare7b1ea02020-08-07 19:54:59 +02008965 >= 16 Every executed Ex command.
Bram Moolenaar071d4272004-06-13 20:20:40 +00008966
8967 This option can also be set with the "-V" argument. See |-V|.
8968 This option is also set by the |:verbose| command.
8969
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +00008970 When the 'verbosefile' option is set then the verbose messages are not
8971 displayed.
8972
8973 *'verbosefile'* *'vfile'*
8974'verbosefile' 'vfile' string (default empty)
8975 global
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +00008976 When not empty all messages are written in a file with this name.
8977 When the file exists messages are appended.
8978 Writing to the file ends when Vim exits or when 'verbosefile' is made
Bram Moolenaar80794b12010-06-13 05:20:42 +02008979 empty. Writes are buffered, thus may not show up for some time.
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +00008980 Setting 'verbosefile' to a new value is like making it empty first.
8981 The difference with |:redir| is that verbose messages are not
8982 displayed when 'verbosefile' is set.
dkearns8ebdbc92023-10-29 06:26:19 +11008983 This option cannot be set from a |modeline| or in the |sandbox|, for
8984 security reasons.
Bram Moolenaar5c06f8b2005-05-31 22:14:58 +00008985
Bram Moolenaar071d4272004-06-13 20:20:40 +00008986 *'viewdir'* *'vdir'*
h_east59858792023-10-25 22:47:05 +09008987'viewdir' 'vdir' string (default for Amiga: "home:vimfiles/view",
Bram Moolenaar801961d2023-06-23 16:15:13 +01008988 for Win32: "$HOME/vimfiles/view",
Christian Brabandtb8b1c8e2023-06-23 22:23:01 +01008989 for Unix: "$HOME/.vim/view",
h_east59858792023-10-25 22:47:05 +09008990 for macOS: "$VIM/vimfiles/view",
Bram Moolenaar801961d2023-06-23 16:15:13 +01008991 for VMS: "sys$login:vimfiles/view")
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}
8995 Name of the directory where to store files for |:mkview|.
8996 This option cannot be set from a |modeline| or in the |sandbox|, for
8997 security reasons.
8998
8999 *'viewoptions'* *'vop'*
Bram Moolenaar13e90412017-11-11 18:16:48 +01009000'viewoptions' 'vop' string (default: "folds,options,cursor,curdir")
Bram Moolenaar071d4272004-06-13 20:20:40 +00009001 global
Bram Moolenaardb84e452010-08-15 13:50:43 +02009002 {not available when compiled without the |+mksession|
Bram Moolenaar071d4272004-06-13 20:20:40 +00009003 feature}
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01009004 Changes the effect of the |:mkview| command. It is a comma-separated
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00009005 list of words. Each word enables saving and restoring something:
Bram Moolenaar071d4272004-06-13 20:20:40 +00009006 word save and restore ~
9007 cursor cursor position in file and in window
9008 folds manually created folds, opened/closed folds and local
9009 fold options
9010 options options and mappings local to a window or buffer (not
9011 global values for local options)
Bram Moolenaar6e932462014-09-09 18:48:09 +02009012 localoptions same as "options"
Bram Moolenaar071d4272004-06-13 20:20:40 +00009013 slash backslashes in file names replaced with forward
9014 slashes
9015 unix with Unix end-of-line format (single <NL>), even when
Bram Moolenaar6f345a12019-12-17 21:27:18 +01009016 on MS-Windows
Bram Moolenaar13e90412017-11-11 18:16:48 +01009017 curdir the window-local directory, if set with `:lcd`
Bram Moolenaar071d4272004-06-13 20:20:40 +00009018
Bram Moolenaar6f345a12019-12-17 21:27:18 +01009019 "slash" and "unix" are useful on MS-Windows when sharing view files
Bram Moolenaar071d4272004-06-13 20:20:40 +00009020 with Unix. The Unix version of Vim cannot source dos format scripts,
Bram Moolenaar6f345a12019-12-17 21:27:18 +01009021 but the MS-Windows version of Vim can source unix format scripts.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009022
9023 *'viminfo'* *'vi'* *E526* *E527* *E528*
Bram Moolenaar6f345a12019-12-17 21:27:18 +01009024'viminfo' 'vi' string (Vi default: "", Vim default for
9025 MS-Windows: '100,<50,s10,h,rA:,rB:,
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01009026 for Amiga: '100,<50,s10,h,rdf0:,rdf1:,rdf2:
9027 for others: '100,<50,s10,h)
Bram Moolenaar071d4272004-06-13 20:20:40 +00009028 global
Bram Moolenaardb84e452010-08-15 13:50:43 +02009029 {not available when compiled without the |+viminfo|
Bram Moolenaar071d4272004-06-13 20:20:40 +00009030 feature}
9031 When non-empty, the viminfo file is read upon startup and written
Bram Moolenaarc4da1132017-07-15 19:39:43 +02009032 when exiting Vim (see |viminfo-file|). Except when 'viminfofile' is
9033 "NONE".
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01009034 The string should be a comma-separated list of parameters, each
Bram Moolenaarc4da1132017-07-15 19:39:43 +02009035 consisting of a single character identifying the particular parameter,
9036 followed by a number or string which specifies the value of that
9037 parameter. If a particular character is left out, then the default
9038 value is used for that parameter. The following is a list of the
9039 identifying characters and the effect of their value.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009040 CHAR VALUE ~
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01009041 *viminfo-!*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009042 ! When included, save and restore global variables that start
9043 with an uppercase letter, and don't contain a lowercase
9044 letter. Thus "KEEPTHIS and "K_L_M" are stored, but "KeepThis"
Bram Moolenaar680eeca2010-10-20 17:44:42 +02009045 and "_K_L_M" are not. Nested List and Dict items may not be
Bram Moolenaar166af9b2010-11-16 20:34:40 +01009046 read back correctly, you end up with an empty item.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01009047 *viminfo-quote*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009048 " Maximum number of lines saved for each register. Old name of
9049 the '<' item, with the disadvantage that you need to put a
9050 backslash before the ", otherwise it will be recognized as the
9051 start of a comment!
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01009052 *viminfo-%*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009053 % When included, save and restore the buffer list. If Vim is
9054 started with a file name argument, the buffer list is not
9055 restored. If Vim is started without a file name argument, the
Bram Moolenaard042dc82015-11-24 19:18:36 +01009056 buffer list is restored from the viminfo file. Quickfix
9057 ('buftype'), unlisted ('buflisted'), unnamed and buffers on
9058 removable media (|viminfo-r|) are not saved.
Bram Moolenaar15d0a8c2004-09-06 17:44:46 +00009059 When followed by a number, the number specifies the maximum
9060 number of buffers that are stored. Without a number all
9061 buffers are stored.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01009062 *viminfo-'*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009063 ' Maximum number of previously edited files for which the marks
9064 are remembered. This parameter must always be included when
9065 'viminfo' is non-empty.
9066 Including this item also means that the |jumplist| and the
9067 |changelist| are stored in the viminfo file.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01009068 *viminfo-/*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009069 / Maximum number of items in the search pattern history to be
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00009070 saved. If non-zero, then the previous search and substitute
Bram Moolenaar071d4272004-06-13 20:20:40 +00009071 patterns are also saved. When not included, the value of
9072 'history' is used.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01009073 *viminfo-:*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009074 : Maximum number of items in the command-line history to be
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00009075 saved. When not included, the value of 'history' is used.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01009076 *viminfo-<*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009077 < Maximum number of lines saved for each register. If zero then
9078 registers are not saved. When not included, all lines are
9079 saved. '"' is the old name for this item.
9080 Also see the 's' item below: limit specified in Kbyte.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01009081 *viminfo-@*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009082 @ Maximum number of items in the input-line history to be
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00009083 saved. When not included, the value of 'history' is used.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01009084 *viminfo-c*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009085 c When included, convert the text in the viminfo file from the
9086 'encoding' used when writing the file to the current
Bram Moolenaar582fd852005-03-28 20:58:01 +00009087 'encoding'. See |viminfo-encoding|.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01009088 *viminfo-f*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009089 f Whether file marks need to be stored. If zero, file marks ('0
9090 to '9, 'A to 'Z) are not stored. When not present or when
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00009091 non-zero, they are all stored. '0 is used for the current
Bram Moolenaar071d4272004-06-13 20:20:40 +00009092 cursor position (when exiting or when doing ":wviminfo").
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01009093 *viminfo-h*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009094 h Disable the effect of 'hlsearch' when loading the viminfo
9095 file. When not included, it depends on whether ":nohlsearch"
9096 has been used since the last search command.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01009097 *viminfo-n*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009098 n Name of the viminfo file. The name must immediately follow
Bram Moolenaarc4da1132017-07-15 19:39:43 +02009099 the 'n'. Must be at the end of the option! If the
9100 'viminfofile' option is set, that file name overrides the one
9101 given here with 'viminfo'. Environment variables are
Bram Moolenaar063b9d12016-07-09 20:21:48 +02009102 expanded when opening the file, not when setting the option.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01009103 *viminfo-r*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009104 r Removable media. The argument is a string (up to the next
9105 ','). This parameter can be given several times. Each
9106 specifies the start of a path for which no marks will be
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01009107 stored. This is to avoid removable media. For MS-Windows you
Bram Moolenaar071d4272004-06-13 20:20:40 +00009108 could use "ra:,rb:", for Amiga "rdf0:,rdf1:,rdf2:". You can
9109 also use it for temp files, e.g., for Unix: "r/tmp". Case is
9110 ignored. Maximum length of each 'r' argument is 50
9111 characters.
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01009112 *viminfo-s*
Bram Moolenaar071d4272004-06-13 20:20:40 +00009113 s Maximum size of an item in Kbyte. If zero then registers are
9114 not saved. Currently only applies to registers. The default
9115 "s10" will exclude registers with more than 10 Kbyte of text.
9116 Also see the '<' item above: line count limit.
9117
9118 Example: >
9119 :set viminfo='50,<1000,s100,:0,n~/vim/viminfo
9120<
9121 '50 Marks will be remembered for the last 50 files you
9122 edited.
9123 <1000 Contents of registers (up to 1000 lines each) will be
9124 remembered.
9125 s100 Registers with more than 100 Kbyte text are skipped.
9126 :0 Command-line history will not be saved.
9127 n~/vim/viminfo The name of the file to use is "~/vim/viminfo".
9128 no / Since '/' is not specified, the default will be used,
9129 that is, save all of the search history, and also the
9130 previous search and substitute patterns.
9131 no % The buffer list will not be saved nor read back.
9132 no h 'hlsearch' highlighting will be restored.
9133
9134 When setting 'viminfo' from an empty value you can use |:rviminfo| to
9135 load the contents of the file, this is not done automatically.
9136
9137 This option cannot be set from a |modeline| or in the |sandbox|, for
9138 security reasons.
Bram Moolenaar036986f2017-03-16 17:41:02 +01009139 NOTE: This option is set to the Vim default value when 'compatible'
9140 is reset.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009141
Bram Moolenaarc4da1132017-07-15 19:39:43 +02009142 *'viminfofile'* *'vif'*
9143'viminfofile' 'vif' string (default: "")
9144 global
Bram Moolenaarc4da1132017-07-15 19:39:43 +02009145 {not available when compiled without the |+viminfo|
9146 feature}
9147 When non-empty, overrides the file name used for viminfo.
9148 When equal to "NONE" no viminfo file will be read or written.
9149 This option can be set with the |-i| command line flag. The |--clean|
9150 command line flag sets it to "NONE".
Bram Moolenaar110289e2019-05-23 15:38:06 +02009151 This option cannot be set from a |modeline| or in the |sandbox|, for
9152 security reasons.
Bram Moolenaarc4da1132017-07-15 19:39:43 +02009153
Bram Moolenaar071d4272004-06-13 20:20:40 +00009154 *'virtualedit'* *'ve'*
9155'virtualedit' 've' string (default "")
Gary Johnson51ad8502021-08-03 18:33:08 +02009156 global or local to window |global-local|
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01009157 A comma-separated list of these words:
Bram Moolenaar071d4272004-06-13 20:20:40 +00009158 block Allow virtual editing in Visual block mode.
9159 insert Allow virtual editing in Insert mode.
9160 all Allow virtual editing in all modes.
Bram Moolenaarefd2bf12006-03-16 21:41:35 +00009161 onemore Allow the cursor to move just past the end of the line
Gary Johnson53ba05b2021-07-26 22:19:10 +02009162 none When used as the local value, do not allow virtual
9163 editing even when the global value is set. When used
9164 as the global value, "none" is the same as "".
9165 NONE Alternative spelling of "none".
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00009166
Bram Moolenaar071d4272004-06-13 20:20:40 +00009167 Virtual editing means that the cursor can be positioned where there is
Bram Moolenaarebcbd022007-05-12 14:28:25 +00009168 no actual character. This can be halfway into a tab or beyond the end
Bram Moolenaar071d4272004-06-13 20:20:40 +00009169 of the line. Useful for selecting a rectangle in Visual mode and
9170 editing a table.
Bram Moolenaarefd2bf12006-03-16 21:41:35 +00009171 "onemore" is not the same, it will only allow moving the cursor just
9172 after the last character of the line. This makes some commands more
9173 consistent. Previously the cursor was always past the end of the line
9174 if the line was empty. But it is far from Vi compatible. It may also
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00009175 break some plugins or Vim scripts. For example because |l| can move
9176 the cursor after the last character. Use with care!
Bram Moolenaar9ba7e172013-07-17 22:37:26 +02009177 Using the `$` command will move to the last character in the line, not
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00009178 past it. This may actually move the cursor to the left!
Bram Moolenaar9ba7e172013-07-17 22:37:26 +02009179 The `g$` command will move to the end of the screen line.
Bram Moolenaarefd2bf12006-03-16 21:41:35 +00009180 It doesn't make sense to combine "all" with "onemore", but you will
9181 not get a warning for it.
Bram Moolenaar53f7fcc2021-07-28 20:10:16 +02009182 When combined with other words, "none" is ignored.
Bram Moolenaar036986f2017-03-16 17:41:02 +01009183 NOTE: This option is set to "" when 'compatible' is set.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009184
9185 *'visualbell'* *'vb'* *'novisualbell'* *'novb'* *beep*
9186'visualbell' 'vb' boolean (default off)
9187 global
Bram Moolenaar74675a62017-07-15 13:53:23 +02009188 Use a visual bell instead of beeping. The terminal code to display the
Bram Moolenaar071d4272004-06-13 20:20:40 +00009189 visual bell is given with 't_vb'. When no beep or flash is wanted,
Bram Moolenaar74675a62017-07-15 13:53:23 +02009190 use: >
9191 :set vb t_vb=
9192< If you want a short flash, you can use this on many terminals: >
9193 :set vb t_vb=[?5h$<100>[?5l
9194< Here $<100> specifies the time, you can use a smaller or bigger value
9195 to get a shorter or longer flash.
9196
9197 Note: Vim will limit the bell to once per half a second. This avoids
9198 having to wait for the flashing to finish when there are lots of
9199 bells, e.g. on key repeat. This also happens without 'visualbell'
9200 set.
9201
Bram Moolenaar071d4272004-06-13 20:20:40 +00009202 In the GUI, 't_vb' defaults to "<Esc>|f", which inverts the display
9203 for 20 msec. If you want to use a different time, use "<Esc>|40f",
9204 where 40 is the time in msec.
Bram Moolenaar74675a62017-07-15 13:53:23 +02009205
9206 Note: When the GUI starts, 't_vb' is reset to its default value. You
9207 might want to set it again in your |gvimrc|.
9208
Bram Moolenaar071d4272004-06-13 20:20:40 +00009209 Does not work on the Amiga, you always get a screen flash.
9210 Also see 'errorbells'.
9211
9212 *'warn'* *'nowarn'*
9213'warn' boolean (default on)
9214 global
9215 Give a warning message when a shell command is used while the buffer
9216 has been changed.
9217
9218 *'weirdinvert'* *'wiv'* *'noweirdinvert'* *'nowiv'*
9219'weirdinvert' 'wiv' boolean (default off)
9220 global
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00009221 This option has the same effect as the 't_xs' terminal option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009222 It is provided for backwards compatibility with version 4.x.
9223 Setting 'weirdinvert' has the effect of making 't_xs' non-empty, and
9224 vice versa. Has no effect when the GUI is running.
9225
9226 *'whichwrap'* *'ww'*
9227'whichwrap' 'ww' string (Vim default: "b,s", Vi default: "")
9228 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00009229 Allow specified keys that move the cursor left/right to move to the
9230 previous/next line when the cursor is on the first/last character in
9231 the line. Concatenate characters to allow this for these keys:
9232 char key mode ~
9233 b <BS> Normal and Visual
9234 s <Space> Normal and Visual
Bram Moolenaar87b5ca52006-03-04 21:55:31 +00009235 h "h" Normal and Visual (not recommended)
9236 l "l" Normal and Visual (not recommended)
Bram Moolenaar071d4272004-06-13 20:20:40 +00009237 < <Left> Normal and Visual
9238 > <Right> Normal and Visual
9239 ~ "~" Normal
9240 [ <Left> Insert and Replace
9241 ] <Right> Insert and Replace
9242 For example: >
9243 :set ww=<,>,[,]
9244< allows wrap only when cursor keys are used.
9245 When the movement keys are used in combination with a delete or change
9246 operator, the <EOL> also counts for a character. This makes "3h"
9247 different from "3dh" when the cursor crosses the end of a line. This
9248 is also true for "x" and "X", because they do the same as "dl" and
9249 "dh". If you use this, you may also want to use the mapping
9250 ":map <BS> X" to make backspace delete the character in front of the
9251 cursor.
Bram Moolenaar362e1a32006-03-06 23:29:24 +00009252 When 'l' is included and it is used after an operator at the end of a
Bram Moolenaar589edb32019-09-20 14:38:13 +02009253 line (not an empty line) then it will not move to the next line. This
9254 makes "dl", "cl", "yl" etc. work normally.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009255 NOTE: This option is set to the Vi default value when 'compatible' is
9256 set and to the Vim default value when 'compatible' is reset.
9257
9258 *'wildchar'* *'wc'*
9259'wildchar' 'wc' number (Vim default: <Tab>, Vi default: CTRL-E)
9260 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00009261 Character you have to type to start wildcard expansion in the
9262 command-line, as specified with 'wildmode'.
Bram Moolenaar446cb832008-06-24 21:56:24 +00009263 More info here: |cmdline-completion|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009264 The character is not recognized when used inside a macro. See
9265 'wildcharm' for that.
Bram Moolenaar34cc7d82021-09-21 20:09:51 +02009266 Some keys will not work, such as CTRL-C, <CR> and Enter.
Yee Cheng Chin8f4fb002023-10-17 10:06:56 +02009267 <Esc> can be used, but hitting it twice in a row will still exit
9268 command-line as a failsafe measure.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009269 Although 'wc' is a number option, you can set it to a special key: >
Bram Moolenaar34cc7d82021-09-21 20:09:51 +02009270 :set wc=<Tab>
Bram Moolenaar071d4272004-06-13 20:20:40 +00009271< NOTE: This option is set to the Vi default value when 'compatible' is
9272 set and to the Vim default value when 'compatible' is reset.
9273
9274 *'wildcharm'* *'wcm'*
9275'wildcharm' 'wcm' number (default: none (0))
9276 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00009277 'wildcharm' works exactly like 'wildchar', except that it is
Bram Moolenaar582fd852005-03-28 20:58:01 +00009278 recognized when used inside a macro. You can find "spare" command-line
9279 keys suitable for this option by looking at |ex-edit-index|. Normally
Bram Moolenaar071d4272004-06-13 20:20:40 +00009280 you'll never actually type 'wildcharm', just use it in mappings that
9281 automatically invoke completion mode, e.g.: >
9282 :set wcm=<C-Z>
Bram Moolenaar446cb832008-06-24 21:56:24 +00009283 :cnoremap ss so $vim/sessions/*.vim<C-Z>
Bram Moolenaar071d4272004-06-13 20:20:40 +00009284< Then after typing :ss you can use CTRL-P & CTRL-N.
9285
9286 *'wildignore'* *'wig'*
9287'wildignore' 'wig' string (default "")
9288 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00009289 A list of file patterns. A file that matches with one of these
Bram Moolenaar30b65812012-07-12 22:01:11 +02009290 patterns is ignored when expanding |wildcards|, completing file or
9291 directory names, and influences the result of |expand()|, |glob()| and
9292 |globpath()| unless a flag is passed to disable this.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009293 The pattern is used like with |:autocmd|, see |autocmd-patterns|.
9294 Also see 'suffixes'.
9295 Example: >
9296 :set wildignore=*.o,*.obj
9297< The use of |:set+=| and |:set-=| is preferred when adding or removing
9298 a pattern from the list. This avoids problems when a future version
9299 uses another default.
9300
Bram Moolenaar94950a92010-12-02 16:01:29 +01009301
h_east596a9f22023-11-21 21:24:23 +09009302 *'wildignorecase'* *'wic'* *'nowildignorecase'* *'nowic'*
Bram Moolenaar94950a92010-12-02 16:01:29 +01009303'wildignorecase' 'wic' boolean (default off)
9304 global
Bram Moolenaar94950a92010-12-02 16:01:29 +01009305 When set case is ignored when completing file names and directories.
Bram Moolenaar71afbfe2013-03-19 16:49:16 +01009306 Has no effect when 'fileignorecase' is set.
Bram Moolenaar94950a92010-12-02 16:01:29 +01009307 Does not apply when the shell is used to expand wildcards, which
9308 happens when there are special characters.
9309
9310
Bram Moolenaar071d4272004-06-13 20:20:40 +00009311 *'wildmenu'* *'wmnu'* *'nowildmenu'* *'nowmnu'*
Bram Moolenaar8c08b5b2016-07-28 22:24:15 +02009312'wildmenu' 'wmnu' boolean (default off, set in |defaults.vim|)
Bram Moolenaar071d4272004-06-13 20:20:40 +00009313 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00009314 When 'wildmenu' is on, command-line completion operates in an enhanced
9315 mode. On pressing 'wildchar' (usually <Tab>) to invoke completion,
Bram Moolenaar54162322022-08-26 16:58:51 +01009316 the possible matches are shown.
9317 When 'wildoptions' contains "pum", then the completion matches are
9318 shown in a popup menu. Otherwise they are displayed just above the
9319 command line, with the first match highlighted (overwriting the status
9320 line, if there is one).
Yegappan Lakshmanan3908ef52022-02-08 12:08:07 +00009321 Keys that show the previous/next match, such as <Tab> or
Bram Moolenaar071d4272004-06-13 20:20:40 +00009322 CTRL-P/CTRL-N, cause the highlight to move to the appropriate match.
9323 When 'wildmode' is used, "wildmenu" mode is used where "full" is
9324 specified. "longest" and "list" do not start "wildmenu" mode.
Bram Moolenaar26402cb2013-02-20 21:26:00 +01009325 You can check the current mode with |wildmenumode()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009326 If there are more matches than can fit in the line, a ">" is shown on
9327 the right and/or a "<" is shown on the left. The status line scrolls
9328 as needed.
9329 The "wildmenu" mode is abandoned when a key is hit that is not used
9330 for selecting a completion.
Yee Cheng Chin2bbd0d32023-10-14 02:23:45 -07009331 While the "wildmenu" is active, the following keys have special
9332 meanings:
9333 CTRL-P - go to the previous entry
9334 CTRL-N - go to the next entry
Bram Moolenaar071d4272004-06-13 20:20:40 +00009335 <CR> - in menu completion, when the cursor is just after a
9336 dot: move into a submenu.
Yee Cheng Chin209ec902023-10-17 10:56:25 +02009337 CTRL-E - end completion, go back to what was there before
9338 selecting a match.
9339 CTRL-Y - accept the currently selected match and stop
9340 completion.
Yee Cheng Chin2bbd0d32023-10-14 02:23:45 -07009341
9342 When not using the popup menu for command line completion, the
9343 following keys have special meanings:
9344 <Left> <Right> - select previous/next match (like CTRL-P/CTRL-N)
Bram Moolenaar071d4272004-06-13 20:20:40 +00009345 <Up> - in filename/menu name completion: move up into
9346 parent directory or parent menu.
Yee Cheng Chin2bbd0d32023-10-14 02:23:45 -07009347 <Down> - in filename/menu name completion: move into a
9348 subdirectory or submenu.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009349
Yegappan Lakshmanan3908ef52022-02-08 12:08:07 +00009350 When using the popup menu for command line completion, the following
9351 keys have special meanings:
Yee Cheng Chin2bbd0d32023-10-14 02:23:45 -07009352 <Up> <Down> - select previous/next match (like CTRL-P/CTRL-N)
zeertzjq3c81f472023-10-15 16:02:08 +08009353 <PageUp> - select a match several entries back
9354 <PageDown> - select a match several entries further
Yegappan Lakshmanan3908ef52022-02-08 12:08:07 +00009355 <Left> - in filename/menu name completion: move up into
9356 parent directory or parent menu.
9357 <Right> - in filename/menu name completion: move into a
9358 subdirectory or submenu.
Yegappan Lakshmanan3908ef52022-02-08 12:08:07 +00009359
Bram Moolenaar071d4272004-06-13 20:20:40 +00009360 This makes the menus accessible from the console |console-menus|.
9361
9362 If you prefer the <Left> and <Right> keys to move the cursor instead
9363 of selecting a different match, use this: >
9364 :cnoremap <Left> <Space><BS><Left>
9365 :cnoremap <Right> <Space><BS><Right>
9366<
9367 The "WildMenu" highlighting is used for displaying the current match
9368 |hl-WildMenu|.
9369
9370 *'wildmode'* *'wim'*
9371'wildmode' 'wim' string (Vim default: "full")
9372 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00009373 Completion mode that is used for the character specified with
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01009374 'wildchar'. It is a comma-separated list of up to four parts. Each
Bram Moolenaar02467872007-05-06 13:22:01 +00009375 part specifies what to do for each consecutive use of 'wildchar'. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00009376 first part specifies the behavior for the first use of 'wildchar',
9377 The second part for the second use, etc.
Bram Moolenaar130cbfc2021-04-07 21:07:20 +02009378
9379 Each part consists of a colon separated list consisting of the
9380 following possible values:
Bram Moolenaar071d4272004-06-13 20:20:40 +00009381 "" Complete only the first match.
9382 "full" Complete the next full match. After the last match,
9383 the original string is used and then the first match
Bram Moolenaar130cbfc2021-04-07 21:07:20 +02009384 again. Will also start 'wildmenu' if it is enabled.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009385 "longest" Complete till longest common string. If this doesn't
9386 result in a longer string, use the next part.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009387 "list" When more than one match, list all matches.
Bram Moolenaar130cbfc2021-04-07 21:07:20 +02009388 "lastused" When completing buffer names and more than one buffer
9389 matches, sort buffers by time last used (other than
9390 the current buffer).
9391 When there is only a single match, it is fully completed in all cases.
9392
9393 Examples of useful colon-separated values:
9394 "longest:full" Like "longest", but also start 'wildmenu' if it is
9395 enabled. Will not complete to the next full match.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009396 "list:full" When more than one match, list all matches and
9397 complete first match.
9398 "list:longest" When more than one match, list all matches and
9399 complete till longest common string.
Bram Moolenaar130cbfc2021-04-07 21:07:20 +02009400 "list:lastused" When more than one buffer matches, list all matches
9401 and sort buffers by time last used (other than the
9402 current buffer).
Bram Moolenaar071d4272004-06-13 20:20:40 +00009403
9404 Examples: >
9405 :set wildmode=full
Bram Moolenaar582fd852005-03-28 20:58:01 +00009406< Complete first full match, next match, etc. (the default) >
Bram Moolenaar071d4272004-06-13 20:20:40 +00009407 :set wildmode=longest,full
9408< Complete longest common string, then each full match >
9409 :set wildmode=list:full
9410< List all matches and complete each full match >
9411 :set wildmode=list,full
9412< List all matches without completing, then each full match >
9413 :set wildmode=longest,list
9414< Complete longest common string, then list alternatives.
Bram Moolenaar446cb832008-06-24 21:56:24 +00009415 More info here: |cmdline-completion|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009416
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00009417 *'wildoptions'* *'wop'*
9418'wildoptions' 'wop' string (default "")
9419 global
Yegappan Lakshmanan3908ef52022-02-08 12:08:07 +00009420 A list of words that change how |cmdline-completion| is done.
9421 The following values are supported:
Bram Moolenaar1588bc82022-03-08 21:35:07 +00009422 fuzzy Use |fuzzy-matching| to find completion matches. When
Yegappan Lakshmanan38b85cb2022-02-24 13:28:41 +00009423 this value is specified, wildcard expansion will not
9424 be used for completion. The matches will be sorted by
9425 the "best match" rather than alphabetically sorted.
9426 This will find more matches than the wildcard
9427 expansion. Currently fuzzy matching based completion
9428 is not supported for file and directory names and
9429 instead wildcard expansion is used.
Bram Moolenaar8a3b8052022-06-26 12:21:15 +01009430 pum Display the completion matches using the popup menu
Yegappan Lakshmanan3908ef52022-02-08 12:08:07 +00009431 in the same style as the |ins-completion-menu|.
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00009432 tagfile When using CTRL-D to list matching tags, the kind of
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00009433 tag and the file of the tag is listed. Only one match
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00009434 is displayed per line. Often used tag kinds are:
9435 d #define
9436 f function
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00009437
Bram Moolenaar071d4272004-06-13 20:20:40 +00009438 *'winaltkeys'* *'wak'*
9439'winaltkeys' 'wak' string (default "menu")
9440 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00009441 {only used in Win32, Motif, GTK and Photon GUI}
9442 Some GUI versions allow the access to menu entries by using the ALT
9443 key in combination with a character that appears underlined in the
9444 menu. This conflicts with the use of the ALT key for mappings and
9445 entering special characters. This option tells what to do:
9446 no Don't use ALT keys for menus. ALT key combinations can be
9447 mapped, but there is no automatic handling. This can then be
9448 done with the |:simalt| command.
9449 yes ALT key handling is done by the windowing system. ALT key
9450 combinations cannot be mapped.
9451 menu Using ALT in combination with a character that is a menu
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00009452 shortcut key, will be handled by the windowing system. Other
Bram Moolenaar071d4272004-06-13 20:20:40 +00009453 keys can be mapped.
9454 If the menu is disabled by excluding 'm' from 'guioptions', the ALT
9455 key is never used for the menu.
Bram Moolenaar293ee4d2004-12-09 21:34:53 +00009456 This option is not used for <F10>; on Win32 and with GTK <F10> will
9457 select the menu, unless it has been mapped.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009458
Bram Moolenaar4d784b22019-05-25 19:51:39 +02009459 *'wincolor'* *'wcr'*
9460'wincolor' 'wcr' string (default empty)
9461 local to window
9462 Highlight group name to use for this window instead of the Normal
9463 color |hl-Normal|.
9464
Bram Moolenaar4399ef42005-02-12 14:29:27 +00009465 *'window'* *'wi'*
9466'window' 'wi' number (default screen height - 1)
9467 global
Bram Moolenaardad44732021-03-31 20:07:33 +02009468 Window height used for |CTRL-F| and |CTRL-B| when there is only one
9469 window and the value is smaller than 'lines' minus one. The screen
9470 will scroll 'window' minus two lines, with a minimum of one.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00009471 When 'window' is equal to 'lines' minus one CTRL-F and CTRL-B scroll
9472 in a much smarter way, taking care of wrapping lines.
9473 When resizing the Vim window, the value is smaller than 1 or more than
9474 or equal to 'lines' it will be set to 'lines' minus 1.
Bram Moolenaardad44732021-03-31 20:07:33 +02009475 Note: Do not confuse this with the height of the Vim window, use
9476 'lines' for that.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00009477
Bram Moolenaar071d4272004-06-13 20:20:40 +00009478 *'winheight'* *'wh'* *E591*
9479'winheight' 'wh' number (default 1)
9480 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00009481 Minimal number of lines for the current window. This is not a hard
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00009482 minimum, Vim will use fewer lines if there is not enough room. If the
Bram Moolenaar446cb832008-06-24 21:56:24 +00009483 focus goes to a window that is smaller, its size is increased, at the
9484 cost of the height of other windows.
9485 Set 'winheight' to a small number for normal editing.
9486 Set it to 999 to make the current window fill most of the screen.
9487 Other windows will be only 'winminheight' high. This has the drawback
9488 that ":all" will create only two windows. To avoid "vim -o 1 2 3 4"
9489 to create only two windows, set the option after startup is done,
9490 using the |VimEnter| event: >
9491 au VimEnter * set winheight=999
9492< Minimum value is 1.
9493 The height is not adjusted after one of the commands that change the
Bram Moolenaar071d4272004-06-13 20:20:40 +00009494 height of the current window.
9495 'winheight' applies to the current window. Use 'winminheight' to set
9496 the minimal height for other windows.
9497
9498 *'winfixheight'* *'wfh'* *'nowinfixheight'* *'nowfh'*
9499'winfixheight' 'wfh' boolean (default off)
Christian Brabandt596ad662023-08-16 00:11:09 +02009500 local to window |local-noglobal|
Bram Moolenaar071d4272004-06-13 20:20:40 +00009501 Keep the window height when windows are opened or closed and
Bram Moolenaar02467872007-05-06 13:22:01 +00009502 'equalalways' is set. Also for |CTRL-W_=|. Set by default for the
9503 |preview-window| and |quickfix-window|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009504 The height may be changed anyway when running out of room.
9505
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00009506 *'winfixwidth'* *'wfw'* *'nowinfixwidth'* *'nowfw'*
9507'winfixwidth' 'wfw' boolean (default off)
Christian Brabandt596ad662023-08-16 00:11:09 +02009508 local to window |local-noglobal|
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00009509 Keep the window width when windows are opened or closed and
Bram Moolenaar02467872007-05-06 13:22:01 +00009510 'equalalways' is set. Also for |CTRL-W_=|.
Bram Moolenaar97b2ad32006-03-18 21:40:56 +00009511 The width may be changed anyway when running out of room.
9512
Bram Moolenaar071d4272004-06-13 20:20:40 +00009513 *'winminheight'* *'wmh'*
9514'winminheight' 'wmh' number (default 1)
9515 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00009516 The minimal height of a window, when it's not the current window.
9517 This is a hard minimum, windows will never become smaller.
9518 When set to zero, windows may be "squashed" to zero lines (i.e. just a
9519 status bar) if necessary. They will return to at least one line when
9520 they become active (since the cursor has to have somewhere to go.)
9521 Use 'winheight' to set the minimal height of the current window.
9522 This option is only checked when making a window smaller. Don't use a
9523 large number, it will cause errors when opening more than a few
9524 windows. A value of 0 to 3 is reasonable.
9525
9526 *'winminwidth'* *'wmw'*
9527'winminwidth' 'wmw' number (default 1)
9528 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00009529 The minimal width of a window, when it's not the current window.
9530 This is a hard minimum, windows will never become smaller.
9531 When set to zero, windows may be "squashed" to zero columns (i.e. just
9532 a vertical separator) if necessary. They will return to at least one
9533 line when they become active (since the cursor has to have somewhere
9534 to go.)
9535 Use 'winwidth' to set the minimal width of the current window.
9536 This option is only checked when making a window smaller. Don't use a
9537 large number, it will cause errors when opening more than a few
9538 windows. A value of 0 to 12 is reasonable.
9539
Bram Moolenaar9e13aa72017-08-16 23:14:08 +02009540 *'winptydll'*
9541'winptydll' string (default "winpty32.dll" or "winpty64.dll")
9542 global
Bram Moolenaar9e13aa72017-08-16 23:14:08 +02009543 {only available when compiled with the |terminal|
9544 feature on MS-Windows}
9545 Specifies the name of the winpty shared library, used for the
Bram Moolenaare7b1ea02020-08-07 19:54:59 +02009546 |:terminal| command. The default depends on whether Vim was built as a
Bram Moolenaarc572da52017-08-27 16:52:01 +02009547 32-bit or 64-bit executable. If not found, "winpty.dll" is tried as
Bram Moolenaar9e13aa72017-08-16 23:14:08 +02009548 a fallback.
9549 Environment variables are expanded |:set_env|.
9550 This option cannot be set from a |modeline| or in the |sandbox|, for
9551 security reasons.
9552
Bram Moolenaar071d4272004-06-13 20:20:40 +00009553 *'winwidth'* *'wiw'* *E592*
9554'winwidth' 'wiw' number (default 20)
9555 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00009556 Minimal number of columns for the current window. This is not a hard
9557 minimum, Vim will use fewer columns if there is not enough room. If
9558 the current window is smaller, its size is increased, at the cost of
9559 the width of other windows. Set it to 999 to make the current window
9560 always fill the screen. Set it to a small number for normal editing.
9561 The width is not adjusted after one of the commands to change the
9562 width of the current window.
9563 'winwidth' applies to the current window. Use 'winminwidth' to set
9564 the minimal width for other windows.
9565
9566 *'wrap'* *'nowrap'*
9567'wrap' boolean (default on)
9568 local to window
Bram Moolenaar071d4272004-06-13 20:20:40 +00009569 This option changes how text is displayed. It doesn't change the text
9570 in the buffer, see 'textwidth' for that.
9571 When on, lines longer than the width of the window will wrap and
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00009572 displaying continues on the next line. When off lines will not wrap
9573 and only part of long lines will be displayed. When the cursor is
Bram Moolenaar071d4272004-06-13 20:20:40 +00009574 moved to a part that is not shown, the screen will scroll
9575 horizontally.
9576 The line will be broken in the middle of a word if necessary. See
9577 'linebreak' to get the break at a word boundary.
9578 To make scrolling horizontally a bit more useful, try this: >
9579 :set sidescroll=5
9580 :set listchars+=precedes:<,extends:>
9581< See 'sidescroll', 'listchars' and |wrap-off|.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01009582 This option can't be set from a |modeline| when the 'diff' option is
9583 on.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009584
9585 *'wrapmargin'* *'wm'*
9586'wrapmargin' 'wm' number (default 0)
9587 local to buffer
9588 Number of characters from the right window border where wrapping
9589 starts. When typing text beyond this limit, an <EOL> will be inserted
9590 and inserting continues on the next line.
9591 Options that add a margin, such as 'number' and 'foldcolumn', cause
9592 the text width to be further reduced. This is Vi compatible.
9593 When 'textwidth' is non-zero, this option is not used.
Bram Moolenaarca635012015-09-25 20:34:21 +02009594 This option is set to 0 when 'paste' is set and restored when 'paste'
9595 is reset.
Bram Moolenaara6c27c42019-05-09 19:16:22 +02009596 See also 'formatoptions' and |ins-textwidth|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009597
9598 *'wrapscan'* *'ws'* *'nowrapscan'* *'nows'*
9599'wrapscan' 'ws' boolean (default on) *E384* *E385*
9600 global
Bram Moolenaarac6e65f2005-08-29 22:25:38 +00009601 Searches wrap around the end of the file. Also applies to |]s| and
9602 |[s|, searching for spelling mistakes.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009603
9604 *'write'* *'nowrite'*
9605'write' boolean (default on)
9606 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00009607 Allows writing files. When not set, writing a file is not allowed.
9608 Can be used for a view-only mode, where modifications to the text are
Bram Moolenaarf4b8e572004-06-24 15:53:16 +00009609 still allowed. Can be reset with the |-m| or |-M| command line
Bram Moolenaar071d4272004-06-13 20:20:40 +00009610 argument. Filtering text is still possible, even though this requires
9611 writing a temporary file.
9612
9613 *'writeany'* *'wa'* *'nowriteany'* *'nowa'*
9614'writeany' 'wa' boolean (default off)
9615 global
9616 Allows writing to any file with no need for "!" override.
9617
9618 *'writebackup'* *'wb'* *'nowritebackup'* *'nowb'*
9619'writebackup' 'wb' boolean (default on with |+writebackup| feature, off
9620 otherwise)
9621 global
Bram Moolenaar071d4272004-06-13 20:20:40 +00009622 Make a backup before overwriting a file. The backup is removed after
9623 the file was successfully written, unless the 'backup' option is
Bram Moolenaar1aeaf8c2012-05-18 13:46:39 +02009624 also on.
9625 WARNING: Switching this option off means that when Vim fails to write
9626 your buffer correctly and then, for whatever reason, Vim exits, you
9627 lose both the original file and what you were writing. Only reset
9628 this option if your file system is almost full and it makes the write
9629 fail (and make sure not to exit Vim until the write was successful).
9630 See |backup-table| for another explanation.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009631 When the 'backupskip' pattern matches, a backup is not made anyway.
Bram Moolenaar0c0734d2019-11-26 21:44:46 +01009632 Depending on 'backupcopy' the backup is a new file or the original
9633 file renamed (and a new file is written).
Bram Moolenaar071d4272004-06-13 20:20:40 +00009634 NOTE: This option is set to the default value when 'compatible' is
9635 set.
9636
9637 *'writedelay'* *'wd'*
9638'writedelay' 'wd' number (default 0)
9639 global
Bram Moolenaar802a0d92016-06-26 16:17:58 +02009640 The number of milliseconds to wait for each character sent to the
Bram Moolenaar071d4272004-06-13 20:20:40 +00009641 screen. When non-zero, characters are sent to the terminal one by
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01009642 one. For debugging purposes.
Bram Moolenaar071d4272004-06-13 20:20:40 +00009643
Bram Moolenaar6f79e612021-12-21 09:12:23 +00009644 *'xtermcodes'* *'noxtermcodes'*
9645'xtermcodes' boolean (default on)
9646 global
9647 When detecting xterm patchlevel 141 or higher with the termresponse
Bram Moolenaarfa3b7232021-12-24 13:18:38 +00009648 mechanism and this option is set, Vim will request the actual terminal
Bram Moolenaar6f79e612021-12-21 09:12:23 +00009649 key codes and number of colors from the terminal. This takes care of
9650 various configuration options of the terminal that cannot be obtained
9651 from the termlib/terminfo entry, see |xterm-codes|.
9652 A side effect may be that t_Co changes and Vim will redraw the
9653 display.
9654
9655
Bram Moolenaar91f84f62018-07-29 15:07:52 +02009656 vim:tw=78:ts=8:noet:ft=help:norl: