tea-test-dao/Git/usr/share/vim/vim91/doc/options.txt

Hello Tea

*options.txt*	For Vim version 9.1.  Last change: 2023 Dec 20


		  VIM REFERENCE MANUAL	  by Bram Moolenaar


Options							*options*

1. Setting options			|set-option|
2. Automatically setting options	|auto-setting|
3. Options summary			|option-summary|

For an overview of options see quickref.txt |option-list|.

Vim has a number of internal variables and switches which can be set to
achieve special effects.  These options come in three forms:
	boolean		can only be on or off		*boolean* *toggle*
	number		has a numeric value
	string		has a string value

==============================================================================
1. Setting options					*set-option* *E764*

							*:se* *:set*
:se[t][!]		Show all options that differ from their default value.
			When [!] is present every option is on a separate
			line.

:se[t][!] all		Show all but terminal options.
			When [!] is present every option is on a separate
			line.

:se[t] termcap		Show all terminal options.  Note that in the GUI the
			key codes are not shown, because they are generated
			internally and can't be changed.  Changing the terminal
			codes in the GUI is not useful either...
			The options have the form t_AB, see
			|terminal-options|.

:se[t]! termcap		Idem, but don't use multiple columns.

								*E518* *E519*
:se[t] {option}?	Show value of {option}.

:se[t] {option}		Toggle option: set, switch it on.
			Number option: show value.
			String option: show value.

:se[t] no{option}	Toggle option: Reset, switch it off.

							   *:set-!* *:set-inv*
:se[t] {option}!   or
:se[t] inv{option}	Toggle option: Invert value.

				*:set-default* *:set-&* *:set-&vi* *:set-&vim*
:se[t] {option}&	Reset option to its default value.  May depend on the
			current value of 'compatible'.
:se[t] {option}&vi	Reset option to its Vi default value.
:se[t] {option}&vim	Reset option to its Vim default value.

:se[t] all&		Set all options to their default value.  The values of
			these options are not changed:
			  all terminal options, starting with t_
			  'columns'
			  'cryptmethod'
			  'encoding'
			  'key'
			  'lines'
			  'term'
			  'ttymouse'
			  'ttytype'
			Warning: This may have a lot of side effects.

					    *:set-args* *:set=* *E487* *E521*
:se[t] {option}={value}		or
:se[t] {option}:{value}
			Set string or number option to {value}.
			For numeric options the value can be given in decimal,
			hex (preceded with 0x) or octal (preceded with '0').
			The old value can be inserted by typing 'wildchar' (by
			default this is a <Tab> or CTRL-E if 'compatible' is
			set). Many string options with fixed syntax and names
			also support completing known values.  See
			|cmdline-completion| and |complete-set-option|.
			White space between {option} and '=' is allowed and
			will be ignored.  White space between '=' and {value}
			is not allowed.
			See |option-backslash| for using white space and
			backslashes in {value}.

:se[t] {option}+={value}				*:set+=*
			Add the {value} to a number option, or append the
			{value} to a string option.  When the option is a
			comma-separated list, a comma is added, unless the
			value was empty.
			If the option is a list of flags, superfluous flags
			are removed.  When adding a flag that was already
			present the option value doesn't change.
			Also see |:set-args| above.

:se[t] {option}^={value}				*:set^=*
			Multiply the {value} to a number option, or prepend
			the {value} to a string option.  When the option is a
			comma-separated list, a comma is added, unless the
			value was empty.
			Also see |:set-args| above.

:se[t] {option}-={value}				*:set-=*
			Subtract the {value} from a number option, or remove
			the {value} from a string option, if it is there.
			If the {value} is not found in a string option, there
			is no error or warning.  When the option is a comma
			separated list, a comma is deleted, unless the option
			becomes empty.
			When the option is a list of flags, {value} must be
			exactly as they appear in the option.  Remove flags
			one by one to avoid problems.
			The individual values from a comma separated list or
			list of flags can be inserted by typing 'wildchar'.
			See |complete-set-option|.
			Also see |:set-args| above.

The {option} arguments to ":set" may be repeated.  For example: >
	:set ai nosi sw=3 ts=3
If you make an error in one of the arguments, an error message will be given
and the following arguments will be ignored.

							*:set-verbose*
When 'verbose' is non-zero, displaying an option value will also tell where it
was last set.  Example: >
	:verbose set shiftwidth cindent?
<  shiftwidth=4 ~
	  Last set from modeline line 1 ~
  cindent ~
	  Last set from /usr/local/share/vim/vim60/ftplugin/c.vim line 30 ~
This is only done when specific option values are requested, not for ":verbose
set all" or ":verbose set" without an argument.
When the option was set by hand there is no "Last set" message.
When the option was set while executing a function, user command or
autocommand, the script in which it was defined is reported.
Note that an option may also have been set as a side effect of setting
'compatible'.
A few special texts:
	Last set from modeline line 1 ~
		Option was set in a |modeline|.
	Last set from --cmd argument ~
		Option was set with command line argument |--cmd| or +.
	Last set from -c argument ~
		Option was set with command line argument |-c|, +, |-S| or
		|-q|.
	Last set from environment variable ~
		Option was set from an environment variable, $VIMINIT,
		$GVIMINIT or $EXINIT.
	Last set from error handler ~
		Option was cleared when evaluating it resulted in an error.

{not available when compiled without the |+eval| feature}

							*:set-termcap* *E522*
For {option} the form "t_xx" may be used to set a terminal option.  This will
override the value from the termcap.  You can then use it in a mapping.  If
the "xx" part contains special characters, use the <t_xx> form: >
	:set <t_#4>=^[Ot
This can also be used to translate a special code for a normal key.  For
example, if Alt-b produces <Esc>b, use this: >
	:set <M-b>=^[b
(the ^[ is a real <Esc> here, use CTRL-V <Esc> to enter it)
The advantage over a mapping is that it works in all situations.

You can define any key codes, e.g.: >
	:set t_xy=^[foo;
There is no warning for using a name that isn't recognized.  You can map these
codes as you like: >
	:map <t_xy> something
<								*E846*
When a key code is not set, it's like it does not exist.  Trying to get its
value will result in an error: >
	:set t_kb=
	:set t_kb
<	E846: Key code not set: t_kb ~

The t_xx options cannot be set from a |modeline| or in the |sandbox|, for
security reasons.

The listing from ":set" looks different from Vi.  Long string options are put
at the end of the list.  The number of options is quite large.  The output of
"set all" probably does not fit on the screen, causing Vim to give the
|more-prompt|.

							*option-backslash*
To include white space in a string option value it has to be preceded with a
backslash.  To include a backslash you have to use two.  Effectively this
means that the number of backslashes in an option value is halved (rounded
down).
In options 'path', 'cdpath', and 'tags', spaces have to be preceded with three
backslashes instead for compatibility with version 3.0 where the options can
be separated by either commas or spaces.
Comma-separated options like 'backupdir' and 'tags' will also require commas
to be escaped with two backslashes, whereas this is not needed for
non-comma-separated ones like 'makeprg'.
When setting options using |:let| and |literal-string|, you need to use one
fewer layer of backslash.
A few examples: >
   :set makeprg=make\ file	    results in "make file"
   :let &makeprg='make file'	    (same as above)
   :set makeprg=make\\\ file	    results in "make\ file"
   :set tags=tags\ /usr/tags	    results in "tags" and "/usr/tags"
   :set tags=tags\\\ file	    results in "tags file"
   :let &tags='tags\ file'	    (same as above)

   :set makeprg=make,file	    results in "make,file"
   :set makeprg=make\\,file	    results in "make\,file"
   :set tags=tags,file		    results in "tags" and "file"
   :set tags=tags\\,file	    results in "tags,file"
   :let &tags='tags\,file'	    (same as above)

The "|" character separates a ":set" command from a following command.  To
include the "|" in the option value, use "\|" instead.  This example sets the
'titlestring' option to "hi|there": >
   :set titlestring=hi\|there
This sets the 'titlestring' option to "hi" and 'iconstring' to "there": >
   :set titlestring=hi|set iconstring=there

Similarly, in legacy script the double quote character starts a comment.  To
include the '"' in the option value, use '\"' instead.  This example sets the
'titlestring' option to 'hi "there"': >
   :set titlestring=hi\ \"there\"

In |Vim9| script it's simpler, comments start with a '#' character, and only
when preceded by white space.  A backslash is needed less often: >
   vim9script
   set titlestring=hi\ "there"
   set titlestring=hi#there#
   set titlestring=hi\ \#there#

For Win32 backslashes in file names are mostly not removed.  More precise: For
options that expect a file name (those where environment variables are
expanded) a backslash before a normal file name character is not removed.  But
a backslash before a special character (space, backslash, comma, etc.) is used
like explained above.
There is one special situation, when the value starts with "\\": >
   :set dir=\\machine\path	    results in "\\machine\path"
   :set dir=\\\\machine\\path	    results in "\\machine\path"
   :set dir=\\path\\file	    results in "\\path\file" (wrong!)
For the first one the start is kept, but for the second one the backslashes
are halved.  This makes sure it works both when you expect backslashes to be
halved and when you expect the backslashes to be kept.  The third gives a
result which is probably not what you want.  Avoid it.

				*add-option-flags* *remove-option-flags*
				*E539* *E550* *E551* *E552*
Some options are a list of flags.  When you want to add a flag to such an
option, without changing the existing ones, you can do it like this: >
   :set guioptions+=a
Remove a flag from an option like this: >
   :set guioptions-=a
This removes the 'a' flag from 'guioptions'.
Note that you should add or remove one flag at a time.  If 'guioptions' has
the value "ab", using "set guioptions-=ba" won't work, because the string "ba"
doesn't appear.

			   *:set_env* *expand-env* *expand-environment-var*
Environment variables in specific string options will be expanded.  If the
environment variable exists the '$' and the following environment variable
name is replaced with its value.  If it does not exist the '$' and the name
are not modified.  Any non-id character (not a letter, digit or '_') may
follow the environment variable name.  That character and what follows is
appended to the value of the environment variable.  Examples: >
   :set term=$TERM.new
   :set path=/usr/$INCLUDE,$HOME/include,.
When adding or removing a string from an option with ":set opt-=val" or ":set
opt+=val" the expansion is done before the adding or removing.


Handling of local options			*local-options*

Note: The following also applies to |global-local| options.

Some of the options only apply to a window or buffer.  Each window or buffer
has its own copy of this option, thus each can have its own value.  This
allows you to set 'list' in one window but not in another.  And set
'shiftwidth' to 3 in one buffer and 4 in another.

The following explains what happens to these local options in specific
situations.  You don't really need to know all of this, since Vim mostly uses
the option values you would expect.  Unfortunately, doing what the user
expects is a bit complicated...

When splitting a window, the local options are copied to the new window.  Thus
right after the split the contents of the two windows look the same.

When editing a new buffer, its local option values must be initialized.  Since
the local options of the current buffer might be specifically for that buffer,
these are not used.  Instead, for each buffer-local option there also is a
global value, which is used for new buffers.  With ":set" both the local and
global value is changed.  With "setlocal" only the local value is changed,
thus this value is not used when editing a new buffer.

When editing a buffer that has been edited before, the options from the window
that was last closed are used again.  If this buffer has been edited in this
window, the values from back then are used.  Otherwise the values from the
last closed window where the buffer was edited last are used.

It's possible to set a local window option specifically for a type of buffer.
When you edit another buffer in the same window, you don't want to keep
using these local window options.  Therefore Vim keeps a global value of the
local window options, which is used when editing another buffer.  Each window
has its own copy of these values.  Thus these are local to the window, but
global to all buffers in the window.  With this you can do: >
	:e one
	:set list
	:e two
Now the 'list' option will also be set in "two", since with the ":set list"
command you have also set the global value. >
	:set nolist
	:e one
	:setlocal list
	:e two
Now the 'list' option is not set, because ":set nolist" resets the global
value, ":setlocal list" only changes the local value and ":e two" gets the
global value.  Note that if you do this next: >
	:e one
You will get back the 'list' value as it was the last time you edited "one".
The options local to a window are remembered for each buffer.  This also
happens when the buffer is not loaded, but they are lost when the buffer is
wiped out |:bwipe|.

Special local window options			*local-noglobal*

The following local window options won't be copied over when new windows are
created, thus they behave slightly differently:

	Option		Reason	~
	'previewwindow'	there can only be a single one
	'scroll'	specific to existing window
	'winfixheight'	specific to existing window
	'winfixwidth'	specific to existing window

Special local buffer options

The following local buffer options won't be copied over when new buffers are
created, thus they behave slightly differently:

	Option		Reason	~
	'filetype'	explicitly set by autocommands
	'syntax'	explicitly set by autocommands
	'bufhidden'	denote |special-buffers|
	'buftype'	denote |special-buffers|
	'readonly'	will be detected automatically
	'modified'	will be detected automatically

							*:setl* *:setlocal*
:setl[ocal][!] ...	Like ":set" but set only the value local to the
			current buffer or window.  Not all options have a
			local value.  If the option does not have a local
			value the global value is set.
			With the "all" argument: display local values for all
			local options.
			Without argument: Display local values for all local
			options which are different from the default.
			When displaying a specific local option, show the
			local value.  For a global/local boolean option, when
			the global value is being used, "--" is displayed
			before the option name.
			For a global option the global value is
			shown (but that might change in the future).

:setl[ocal] {option}<	Set the local value of {option} to its global value by
			copying the value.

:se[t] {option}<	For |global-local| options: Remove the local value of
			{option}, so that the global value will be used.

							*:setg* *:setglobal*
:setg[lobal][!] ...	Like ":set" but set only the global value for a local
			option without changing the local value.
			When displaying an option, the global value is shown.
			With the "all" argument: display global values for all
			local options.
			Without argument: display global values for all local
			options which are different from the default.

For buffer-local and window-local options:
	Command		 global value	    local value ~
      :set option=value	     set		set
 :setlocal option=value	      -			set
:setglobal option=value	     set		 -
      :set option?	      -		       display
 :setlocal option?	      -		       display
:setglobal option?	    display		 -


Global options with a local value			*global-local*

Options are global when you mostly use one value for all buffers and windows.
For some global options it's useful to sometimes have a different local value.
You can set the local value with ":setlocal".  That buffer or window will then
use the local value, while other buffers and windows continue using the global
value.

For example, you have two windows, both on C source code.  They use the global
'makeprg' option.  If you do this in one of the two windows: >
	:set makeprg=gmake
then the other window will switch to the same value.  There is no need to set
the 'makeprg' option in the other C source window too.
However, if you start editing a Perl file in a new window, you want to use
another 'makeprg' for it, without changing the value used for the C source
files.  You use this command: >
	:setlocal makeprg=perlmake
You can switch back to using the global value by making the local value empty: >
	:setlocal makeprg=
This only works for a string option.  For a number or boolean option you need
to use the "<" flag, like this: >
	:setlocal autoread<
Note that for non-boolean and non-number options using "<" copies the global
value to the local value, it doesn't switch back to using the global value
(that matters when the global value changes later).  You can also use: >
	:set path<
This will make the local value of 'path' empty, so that the global value is
used.  Thus it does the same as: >
	:setlocal path=
Note: In the future more global options can be made |global-local|.  Using
":setlocal" on a global option might work differently then.

						*option-value-function*
Some options ('completefunc', 'imactivatefunc', 'imstatusfunc', 'omnifunc',
'operatorfunc', 'quickfixtextfunc', 'tagfunc' and 'thesaurusfunc') are set to
a function name or a function reference or a lambda function.  When using a
lambda it will be converted to the name, e.g. "<lambda>123".  Examples:
>
	set opfunc=MyOpFunc
	set opfunc=function('MyOpFunc')
	set opfunc=funcref('MyOpFunc')
	set opfunc={a\ ->\ MyOpFunc(a)}

Set to a script-local function: >
	set opfunc=s:MyLocalFunc
	set opfunc=<SID>MyLocalFunc
In |Vim9| script the "s:" and "<SID>" can be omitted if the function exists in
the script: >
	set opfunc=MyLocalFunc

Set using a funcref variable: >
	let Fn = function('MyTagFunc')
	let &tagfunc = Fn

Set using a lambda expression: >
	let &tagfunc = {t -> MyTagFunc(t)}

Set using a variable with lambda expression: >
	let L = {a, b, c -> MyTagFunc(a, b , c)}
	let &tagfunc = L

In Vim9 script, in a compiled function, you can use a lambda, but a
closure does not work, because the function will be called without the
context of where it was defined.


Setting the filetype

:setf[iletype] [FALLBACK] {filetype}			*:setf* *:setfiletype*
			Set the 'filetype' option to {filetype}, but only if
			not done yet in a sequence of (nested) autocommands.
			This is short for: >
				:if !did_filetype()
				:  setlocal filetype={filetype}
				:endif
<			This command is used in a filetype.vim file to avoid
			setting the 'filetype' option twice, causing different
			settings and syntax files to be loaded.

			When the optional FALLBACK argument is present, a
			later :setfiletype command will override the
			'filetype'.  This is to be used for filetype
			detections that are just a guess.  |did_filetype()|
			will return false after this command.

				*option-window* *optwin*
:bro[wse] se[t]			*:set-browse* *:browse-set* *:opt* *:options*
:opt[ions]		Open a window for viewing and setting all options.
			Options are grouped by function.
			Offers short help for each option.  Hit <CR> on the
			short help to open a help window with more help for
			the option.
			Modify the value of the option and hit <CR> on the
			"set" line to set the new value.  For window and
			buffer specific options, the last accessed window is
			used to set the option value in, unless this is a help
			window, in which case the window below help window is
			used (skipping the option-window).
			{not available when compiled without the |+eval|
			feature}

								*$HOME*
Using "~" is like using "$HOME", but it is only recognized at the start of an
option and after a space or comma.

On Unix systems "~user" can be used too.  It is replaced by the home directory
of user "user".  Example: >
    :set path=~mool/include,/usr/include,.

On Unix systems the form "${HOME}" can be used too.  The name between {} can
contain non-id characters then.  Note that if you want to use this for the
"gf" command, you need to add the '{' and '}' characters to 'isfname'.

NOTE: expanding environment variables and "~/" is only done with the ":set"
command, not when assigning a value to an option with ":let".

							*$HOME-windows*
On MS-Windows, if $HOME is not defined as an environment variable, then
at runtime Vim will set it to the expansion of $HOMEDRIVE$HOMEPATH.
If $HOMEDRIVE is not set then $USERPROFILE is used.

This expanded value is not exported to the environment, this matters when
running an external command: >
	:echo system('set | findstr ^HOME=')
and >
	:echo luaeval('os.getenv("HOME")')
should echo nothing (an empty string) despite exists('$HOME') being true.
When setting $HOME to a non-empty string it will be exported to the
subprocesses.


Note the maximum length of an expanded option is limited.  How much depends on
the system, mostly it is something like 256 or 1024 characters.

							*:fix* *:fixdel*
:fix[del]		Set the value of 't_kD':
				't_kb' is     't_kD' becomes	~
				  CTRL-?	CTRL-H
				not CTRL-?	CTRL-?

			(CTRL-? is 0o177 octal, 0x7f hex)

			If your delete key terminal code is wrong, but the
			code for backspace is alright, you can put this in
			your .vimrc: >
				:fixdel
<			This works no matter what the actual code for
			backspace is.

			If the backspace key terminal code is wrong you can
			use this: >
				:if &term == "termname"
				:  set t_kb=^V<BS>
				:  fixdel
				:endif
<			Where "^V" is CTRL-V and "<BS>" is the backspace key
			(don't type four characters!).  Replace "termname"
			with your terminal name.

			If your <Delete> key sends a strange key sequence (not
			CTRL-? or CTRL-H) you cannot use ":fixdel".  Then use: >
				:if &term == "termname"
				:  set t_kD=^V<Delete>
				:endif
<			Where "^V" is CTRL-V and "<Delete>" is the delete key
			(don't type eight characters!).  Replace "termname"
			with your terminal name.

							*Linux-backspace*
			Note about Linux: By default the backspace key
			produces CTRL-?, which is wrong.  You can fix it by
			putting this line in your rc.local: >
				echo "keycode 14 = BackSpace" | loadkeys
<
							*NetBSD-backspace*
			Note about NetBSD: If your backspace doesn't produce
			the right code, try this: >
				xmodmap -e "keycode 22 = BackSpace"
<			If this works, add this in your .Xmodmap file: >
				keysym 22 = BackSpace
<			You need to restart for this to take effect.

==============================================================================
2. Automatically setting options			*auto-setting*

Besides changing options with the ":set" command, there are three alternatives
to set options automatically for one or more files:

1. When starting Vim initializations are read from various places.  See
   |initialization|.  Most of them are performed for all editing sessions,
   and some of them depend on the directory where Vim is started.
   You can create an initialization file with |:mkvimrc|, |:mkview| and
   |:mksession|.
2. If you start editing a new file, the automatic commands are executed.
   This can be used to set options for files matching a particular pattern and
   many other things.  See |autocommand|.
3. If you start editing a new file, and the 'modeline' option is on, a
   number of lines at the beginning and end of the file are checked for
   modelines.  This is explained here.

					*modeline* *vim:* *vi:* *ex:* *E520*
There are two forms of modelines.  The first form:
	[text{white}]{vi:|vim:|ex:}[white]{options}

[text{white}]		empty or any text followed by at least one blank
			character (<Space> or <Tab>); "ex:" always requires at
			least one blank character
{vi:|vim:|ex:}		the string "vi:", "vim:" or "ex:"
[white]			optional white space
{options}		a list of option settings, separated with white space
			or ':', where each part between ':' is the argument
			for a ":set" command (can be empty)

Examples:
   vi:noai:sw=3 ts=6 ~
   vim: tw=77 ~

The second form (this is compatible with some versions of Vi):

	[text{white}]{vi:|vim:|Vim:|ex:}[white]se[t] {options}:[text]

[text{white}]		empty or any text followed by at least one blank
			character (<Space> or <Tab>); "ex:" always requires at
			least one blank character
{vi:|vim:|Vim:|ex:}	the string "vi:", "vim:", "Vim:" or "ex:"
[white]			optional white space
se[t]			the string "set " or "se " (note the space); When
			"Vim" is used it must be "set".
{options}		a list of options, separated with white space, which
			is the argument for a ":set" command
:			a colon
[text]			any text or empty

Examples:
   /* vim: set ai tw=75: */ ~
   /* Vim: set ai tw=75: */ ~

The white space before {vi:|vim:|Vim:|ex:} is required.  This minimizes the
chance that a normal word like "lex:" is caught.  There is one exception:
"vi:" and "vim:" can also be at the start of the line (for compatibility with
version 3.0).  Using "ex:" at the start of the line will be ignored (this
could be short for "example:").

If the modeline is disabled within a modeline, subsequent modelines will be
ignored.  This is to allow turning off modeline on a per-file basis.  This is
useful when a line looks like a modeline but isn't.  For example, it would be
good to start a YAML file containing strings like "vim:" with
    # vim: nomodeline ~
so as to avoid modeline misdetection.  Following options on the same line
after modeline deactivation, if any, are still evaluated (but you would
normally not have any).

							*modeline-local*
The options are set like with ":setlocal": The new value only applies to the
buffer and window that contain the file.  Although it's possible to set global
options from a modeline, this is unusual.  If you have two windows open and
the files in it set the same global option to a different value, the result
depends on which one was opened last.

When editing a file that was already loaded, only the window-local options
from the modeline are used.  Thus if you manually changed a buffer-local
option after opening the file, it won't be changed if you edit the same buffer
in another window.  But window-local options will be set.

							*modeline-version*
If the modeline is only to be used for some versions of Vim, the version
number can be specified where "vim:" or "Vim:" is used:
	vim{vers}:	version {vers} or later
	vim<{vers}:	version before {vers}
	vim={vers}:	version {vers}
	vim>{vers}:	version after {vers}
{vers} is 700 for Vim 7.0 (hundred times the major version plus minor).
For example, to use a modeline only for Vim 7.0:
	/* vim700: set foldmethod=marker */ ~
To use a modeline for Vim after version 7.2:
	/* vim>702: set cole=2: */ ~
There can be no blanks between "vim" and the ":".


The number of lines that are checked can be set with the 'modelines' option.
If 'modeline' is off or 'modelines' is 0 no lines are checked.

Note that for the first form all of the rest of the line is used, thus a line
like:
   /* vi:ts=4: */ ~
will give an error message for the trailing "*/".  This line is OK:
   /* vi:set ts=4: */ ~

If an error is detected the rest of the line is skipped.

If you want to include a ':' in a set command precede it with a '\'.  The
backslash in front of the ':' will be removed.  Example:
   /* vi:set fillchars=stl\:^,vert\:\|: */ ~
This sets the 'fillchars' option to "stl:^,vert:\|".  Only a single backslash
before the ':' is removed.  Thus to include "\:" you have to specify "\\:".
							*E992*
No other commands than "set" are supported, for security reasons (somebody
might create a Trojan horse text file with modelines).  And not all options
can be set.  For some options a flag is set, so that when the value is used
the |sandbox| is effective.  Some options can only be set from the modeline
when 'modelineexpr' is set (the default is off).

Still, there is always a small risk that a modeline causes trouble.  E.g.,
when some joker sets 'textwidth' to 5 all your lines are wrapped unexpectedly.
So disable modelines before editing untrusted text.  The mail ftplugin does
this, for example.

Hint: If you would like to do something else than setting an option, you could
define an autocommand that checks the file for a specific string.  For
example: >
	au BufReadPost * if getline(1) =~ "VAR" | call SetVar() | endif
And define a function SetVar() that does something with the line containing
"VAR".

==============================================================================
3. Options summary					*option-summary*

In the list below all the options are mentioned with their full name and with
an abbreviation if there is one.  Both forms may be used.

In this document when a boolean option is "set" that means that ":set option"
is entered.  When an option is "reset", ":set nooption" is used.

For some options there are two default values: The "Vim default", which is
used when 'compatible' is not set, and the "Vi default", which is used when
'compatible' is set.

Most options are the same in all windows and buffers.  There are a few that
are specific to how the text is presented in a window.  These can be set to a
different value in each window.  For example the 'list' option can be set in
one window and reset in another for the same text, giving both types of view
at the same time.  There are a few options that are specific to a certain
file.  These can have a different value for each file or buffer.  For example
the 'textwidth' option can be 78 for a normal text file and 0 for a C
program.

	global			one option for all buffers and windows
	local to window		each window has its own copy of this option
	local to buffer		each buffer has its own copy of this option

When creating a new window the option values from the currently active window
are used as a default value for the window-specific options.  For the
buffer-specific options this depends on the 's' and 'S' flags in the
'cpoptions' option.  If 's' is included (which is the default) the values for
buffer options are copied from the currently active buffer when a buffer is
first entered.  If 'S' is present the options are copied each time the buffer
is entered, this is almost like having global options.  If 's' and 'S' are not
present, the options are copied from the currently active buffer when the
buffer is created.

Hidden options						*hidden-options*

Not all options are supported in all versions.  This depends on the supported
features and sometimes on the system.  A remark about this is in curly braces
below.  When an option is not supported it may still be set without getting an
error, this is called a hidden option.  You can't get the value of a hidden
option though, it is not stored.

To test if option "foo" can be used with ":set" use something like this: >
	if exists('&foo')
This also returns true for a hidden option.  To test if option "foo" is really
supported use something like this: >
	if exists('+foo')
<
							*E355*
A jump table for the options with a short description can be found at |Q_op|.

					*'aleph'* *'al'* *aleph* *Aleph*
'aleph' 'al'		number	(default 128 for MS-Windows, 224 otherwise)
			global
			{only available when compiled with the |+rightleft|
			feature}
	The ASCII code for the first letter of the Hebrew alphabet.  The
	routine that maps the keyboard in Hebrew mode, both in Insert mode
	(when hkmap is set) and on the command-line (when hitting CTRL-_)
	outputs the Hebrew characters in the range [aleph..aleph+26].
	aleph=128 applies to PC code, and aleph=224 applies to ISO 8859-8.
	See |rileft.txt|.

			*'allowrevins'* *'ari'* *'noallowrevins'* *'noari'*
'allowrevins' 'ari'	boolean	(default off)
			global
			{only available when compiled with the |+rightleft|
			feature}
	Allow CTRL-_ in Insert and Command-line mode.  This is default off, to
	avoid that users that accidentally type CTRL-_ instead of SHIFT-_ get
	into reverse Insert mode, and don't know how to get out.  See
	'revins'.
	NOTE: This option is reset when 'compatible' is set.

			 *'altkeymap'* *'akm'* *'noaltkeymap'* *'noakm'*
'altkeymap' 'akm'	boolean (default off)
			global
			{only available when compiled with the |+farsi|
			feature}
	This option was for using Farsi, which has been removed.  See
	|farsi.txt|.

						*'ambiwidth'* *'ambw'*
'ambiwidth' 'ambw'	string (default: "single")
			global
	Only effective when 'encoding' is "utf-8" or another Unicode encoding.
	Tells Vim what to do with characters with East Asian Width Class
	Ambiguous (such as Euro, Registered Sign, Copyright Sign, Greek
	letters, Cyrillic letters).

	There are currently two possible values:
	"single":	Use the same width as characters in US-ASCII.  This is
			expected by most users.
	"double":	Use twice the width of ASCII characters.
							*E834* *E835*
	The value "double" cannot be used if 'listchars' or 'fillchars'
	contains a character that would be double width.  These errors may
	also be given when calling setcellwidths().

	The values are overruled for characters specified with
	|setcellwidths()|.

	There are a number of CJK fonts for which the width of glyphs for
	those characters are solely based on how many octets they take in
	legacy/traditional CJK encodings.  In those encodings, Euro,
	Registered sign, Greek/Cyrillic letters are represented by two octets,
	therefore those fonts have "wide" glyphs for them.  This is also
	true of some line drawing characters used to make tables in text
	file.  Therefore, when a CJK font is used for GUI Vim or
	Vim is running inside a terminal (emulators) that uses a CJK font
	(or Vim is run inside an xterm invoked with "-cjkwidth" option.),
	this option should be set to "double" to match the width perceived
	by Vim with the width of glyphs in the font.  Perhaps it also has
	to be set to "double" under CJK MS-Windows when the system locale is
	set to one of CJK locales.  See Unicode Standard Annex #11
	(http://www.unicode.org/reports/tr11).

	Vim may set this option automatically at startup time when Vim is
	compiled with the |+termresponse| feature and if |t_u7| is set to the
	escape sequence to request cursor position report.  The response can
	be found in |v:termu7resp|.

			*'antialias'* *'anti'* *'noantialias'* *'noanti'*
'antialias' 'anti'	boolean (default: off)
			global
			{only available when compiled with GUI enabled
			on macOS}
	This option only has an effect in the GUI version of Vim on macOS
	v10.2 or later.  When on, Vim will use smooth ("antialiased") fonts,
	which can be easier to read at certain sizes on certain displays.
	Setting this option can sometimes cause problems if 'guifont' is set
	to its default (empty string).
	NOTE: This option is reset when 'compatible' is set.

				*'arabic'* *'arab'* *'noarabic'* *'noarab'*
'arabic' 'arab'		boolean (default off)
			local to window
			{only available when compiled with the |+arabic|
			feature}
	This option can be set to start editing Arabic text.
	Setting this option will:
	- Set the 'rightleft' option, unless 'termbidi' is set.
	- Set the 'arabicshape' option, unless 'termbidi' is set.
	- Set the 'keymap' option to "arabic"; in Insert mode CTRL-^ toggles
	  between typing English and Arabic key mapping.
	- Set the 'delcombine' option
	Note that 'encoding' must be "utf-8" for working with Arabic text.

	Resetting this option will:
	- Reset the 'rightleft' option.
	- Disable the use of 'keymap' (without changing its value).
	Note that 'arabicshape' and 'delcombine' are not reset (it is a global
	option).
	NOTE: This option is reset when 'compatible' is set.
	Also see |arabic.txt|.

					*'arabicshape'* *'arshape'*
					*'noarabicshape'* *'noarshape'*
'arabicshape' 'arshape'	boolean (default on)
			global
			{only available when compiled with the |+arabic|
			feature}
	When on and 'termbidi' is off, the required visual character
	corrections that need to take place for displaying the Arabic language
	take effect.  Shaping, in essence, gets enabled; the term is a broad
	one which encompasses:
	  a) the changing/morphing of characters based on their location
	     within a word (initial, medial, final and stand-alone).
	  b) the enabling of the ability to compose characters
	  c) the enabling of the required combining of some characters
	When disabled the display shows each character's true stand-alone
	form.
	Arabic is a complex language which requires other settings, for
	further details see |arabic.txt|.
	NOTE: This option is set when 'compatible' is set.

			*'autochdir'* *'acd'* *'noautochdir'* *'noacd'*
'autochdir' 'acd'	boolean (default off)
			global
			{only available when compiled with it, use
			exists("+autochdir") to check}
	When on, Vim will change the current working directory whenever you
	open a file, switch buffers, delete a buffer or open/close a window.
	It will change to the directory containing the file which was opened
	or selected.  When a buffer has no name it also has no directory, thus
	the current directory won't change when navigating to it.
	Note: When this option is on some plugins may not work.

			*'autoindent'* *'ai'* *'noautoindent'* *'noai'*
'autoindent' 'ai'	boolean	(default off)
			local to buffer
	Copy indent from current line when starting a new line (typing <CR>
	in Insert mode or when using the "o" or "O" command).  If you do not
	type anything on the new line except <BS> or CTRL-D and then type
	<Esc>, CTRL-O or <CR>, the indent is deleted again.  Moving the cursor
	to another line has the same effect, unless the 'I' flag is included
	in 'cpoptions'.
	When autoindent is on, formatting (with the "gq" command or when you
	reach 'textwidth' in Insert mode) uses the indentation of the first
	line.
	When 'smartindent' or 'cindent' is on the indent is changed in
	a different way.
	The 'autoindent' option is reset when the 'paste' option is set and
	restored when 'paste' is reset.

				 *'autoread'* *'ar'* *'noautoread'* *'noar'*
'autoread' 'ar'		boolean	(default off)
			global or local to buffer |global-local|
	When a file has been detected to have been changed outside of Vim and
	it has not been changed inside of Vim, automatically read it again.
	When the file has been deleted this is not done, so you have the text
	from before it was deleted.  When it appears again then it is read.
	|timestamp|
	If this option has a local value, use this command to switch back to
	using the global value: >
		:set autoread<
<

			*'autoshelldir'* *'asd'* *'noautoshelldir'* *'noasd'*
'autoshelldir' 'asd'	boolean (default off)
			global
	When on, Vim will change the current working directory whenever you
	change the directory of the shell running in a terminal window. You
	need proper setting-up, so whenever the shell's pwd changes an OSC 7
	escape sequence will be emitted.  For example, on Linux, you can
	source /etc/profile.d/vte.sh in your shell profile if you use bash or
	zsh.  For bash this should work (put it in a bash init file): >
		if [[ -n "$VIM_TERMINAL" ]]; then
		    PROMPT_COMMAND='_vim_sync_PWD'
		    function _vim_sync_PWD() {
			printf '\033]7;file://%s\033\\' "$PWD"
		    }
		fi
<
	Or, in a zsh init file: >
		if [[ -n "$VIM_TERMINAL" ]]; then
		    autoload -Uz add-zsh-hook
		    add-zsh-hook -Uz chpwd _vim_sync_PWD
		    function _vim_sync_PWD() {
			printf '\033]7;file://%s\033\\' "$PWD"
		    }
		fi
<
	In a fish init file: >
		if test -n "$VIM_TERMINAL"
		    function _vim_sync_PWD --on-variable=PWD
			printf '\033]7;file://%s\033\\' "$PWD"
		    end
		end
<
	You can find an alternative method at |terminal-autoshelldir|.
	When the parsing of the OSC sequence fails you get *E1179* .

				 *'autowrite'* *'aw'* *'noautowrite'* *'noaw'*
'autowrite' 'aw'	boolean	(default off)
			global
	Write the contents of the file, if it has been modified, on each
	`:next`, `:rewind`, `:last`, `:first`, `:previous`, `:stop`,
	`:suspend`, `:tag`, `:!`, `:make`, CTRL-] and CTRL-^ command; and when
	a `:buffer`, CTRL-O, CTRL-I, '{A-Z0-9}, or `{A-Z0-9} command takes one
	to another file.
	A buffer is not written if it becomes hidden, e.g. when 'bufhidden' is
	set to "hide" and `:next` is used.
	Note that for some commands the 'autowrite' option is not used, see
	'autowriteall' for that.
	Some buffers will not be written, specifically when 'buftype' is
	"nowrite", "nofile", "terminal" or "prompt".
	USE WITH CARE: If you make temporary changes to a buffer that you
	don't want to be saved this option may cause it to be saved anyway.
	Renaming the buffer with ":file {name}" may help avoid this.

			 *'autowriteall'* *'awa'* *'noautowriteall'* *'noawa'*
'autowriteall' 'awa'	boolean	(default off)
			global
	Like 'autowrite', but also used for commands ":edit", ":enew", ":quit",
	":qall", ":exit", ":xit", ":recover" and closing the Vim window.
	Setting this option also implies that Vim behaves like 'autowrite' has
	been set.

							*'background'* *'bg'*
'background' 'bg'	string	(default "dark" or "light", see below)
			global
	When set to "dark", Vim will try to use colors that look good on a
	dark background.  When set to "light", Vim will try to use colors that
	look good on a light background.  Any other value is illegal.
	Vim tries to set the default value according to the terminal used.
	This will not always be correct.
	Setting this option does not change the background color, it tells Vim
	what the background color looks like.  For changing the background
	color, see |:hi-normal|.

	When 'background' is set Vim will adjust the default color groups for
	the new value.  But the colors used for syntax highlighting will not
	change.					*g:colors_name*
	When a color scheme is loaded (the "g:colors_name" variable is set)
	setting 'background' will cause the color scheme to be reloaded.  If
	the color scheme adjusts to the value of 'background' this will work.
	However, if the color scheme sets 'background' itself the effect may
	be undone.  First delete the "g:colors_name" variable when needed.

	When setting 'background' to the default value with: >
		:set background&
<	Vim will guess the value.  In the GUI this should work correctly,
	in other cases Vim might not be able to guess the right value.
	If the GUI supports a dark theme, you can use the "d" flag in
	'guioptions', see 'go-d'.

	When the |t_RB| option is set, Vim will use it to request the background
	color from the terminal.  If the returned RGB value is dark/light and
	'background' is not dark/light, 'background' will be set and the
	screen is redrawn.  This may have side effects, make t_BG empty in
	your .vimrc if you suspect this problem.  The response to |t_RB| can
	be found in |v:termrbgresp|.

	When starting the GUI, the default value for 'background' will be
	"light".  When the value is not set in the .gvimrc, and Vim detects
	that the background is actually quite dark, 'background' is set to
	"dark".  But this happens only AFTER the .gvimrc file has been read
	(because the window needs to be opened to find the actual background
	color).  To get around this, force the GUI window to be opened by
	putting a ":gui" command in the .gvimrc file, before where the value
	of 'background' is used (e.g., before ":syntax on").

	For MS-Windows the default is "dark".
	For other systems "dark" is used when 'term' is "linux",
	"screen.linux", "cygwin" or "putty", or $COLORFGBG suggests a dark
	background.  Otherwise the default is "light".

	The |:terminal| command and the |term_start()| function use the
	'background' value to decide whether the terminal window will start
	with a white or black background.

	Normally this option would be set in the .vimrc file.  Possibly
	depending on the terminal name.  Example: >
		:if &term == "pcterm"
		:  set background=dark
		:endif
<	When this option is set, the default settings for the highlight groups
	will change.  To use other settings, place ":highlight" commands AFTER
	the setting of the 'background' option.
	This option is also used in the "$VIMRUNTIME/syntax/syntax.vim" file
	to select the colors for syntax highlighting.  After changing this
	option, you must load syntax.vim again to see the result.  This can be
	done with ":syntax on".

							*'backspace'* *'bs'*
'backspace' 'bs'	string	(default "", set to "indent,eol,start"
							    in |defaults.vim|)
			global
	Influences the working of <BS>, <Del>, CTRL-W and CTRL-U in Insert
	mode.  This is a list of items, separated by commas.  Each item allows
	a way to backspace over something:
	value	effect	~
	indent	allow backspacing over autoindent
	eol	allow backspacing over line breaks (join lines)
	start	allow backspacing over the start of insert; CTRL-W and CTRL-U
		stop once at the start of insert.
	nostop	like start, except CTRL-W and CTRL-U do not stop at the start of
		insert.

	When the value is empty, Vi compatible backspacing is used, none of
	the ways mentioned for the items above are possible.

	For backwards compatibility with version 5.4 and earlier:
	value	effect	~
	  0	same as ":set backspace=" (Vi compatible)
	  1	same as ":set backspace=indent,eol"
	  2	same as ":set backspace=indent,eol,start"
	  3	same as ":set backspace=indent,eol,nostop"

	See |:fixdel| if your <BS> or <Del> key does not do what you want.
	NOTE: This option is set to "" when 'compatible' is set.

				*'backup'* *'bk'* *'nobackup'* *'nobk'*
'backup' 'bk'		boolean	(default off)
			global
	Make a backup before overwriting a file.  Leave it around after the
	file has been successfully written.  If you do not want to keep the
	backup file, but you do want a backup while the file is being
	written, reset this option and set the 'writebackup' option (this is
	the default).  If you do not want a backup file at all reset both
	options (use this if your file system is almost full).  See the
	|backup-table| for more explanations.
	When the 'backupskip' pattern matches, a backup is not made anyway.
	When 'patchmode' is set, the backup may be renamed to become the
	oldest version of a file.
	NOTE: This option is reset when 'compatible' is set.

						*'backupcopy'* *'bkc'*
'backupcopy' 'bkc'	string	(Vi default for Unix: "yes", otherwise: "auto")
			global or local to buffer |global-local|
	When writing a file and a backup is made, this option tells how it's
	done.  This is a comma-separated list of words.

	The main values are:
	"yes"	make a copy of the file and overwrite the original one
	"no"	rename the file and write a new one
	"auto"	one of the previous, what works best

	Extra values that can be combined with the ones above are:
	"breaksymlink"	always break symlinks when writing
	"breakhardlink"	always break hardlinks when writing

	Making a copy and overwriting the original file:
	- Takes extra time to copy the file.
	+ When the file has special attributes, is a (hard/symbolic) link or
	  has a resource fork, all this is preserved.
	- When the file is a link the backup will have the name of the link,
	  not of the real file.

	Renaming the file and writing a new one:
	+ It's fast.
	- Sometimes not all attributes of the file can be copied to the new
	  file.
	- When the file is a link the new file will not be a link.

	The "auto" value is the middle way: When Vim sees that renaming the
	file is possible without side effects (the attributes can be passed on
	and the file is not a link) that is used.  When problems are expected,
	a copy will be made.

	The "breaksymlink" and "breakhardlink" values can be used in
	combination with any of "yes", "no" and "auto".  When included, they
	force Vim to always break either symbolic or hard links by doing
	exactly what the "no" option does, renaming the original file to
	become the backup and writing a new file in its place.  This can be
	useful for example in source trees where all the files are symbolic or
	hard links and any changes should stay in the local source tree, not
	be propagated back to the original source.
							*crontab*
	One situation where "no" and "auto" will cause problems: A program
	that opens a file, invokes Vim to edit that file, and then tests if
	the open file was changed (through the file descriptor) will check the
	backup file instead of the newly created file.  "crontab -e" is an
	example.

	When a copy is made, the original file is truncated and then filled
	with the new text.  This means that protection bits, owner and
	symbolic links of the original file are unmodified.  The backup file,
	however, is a new file, owned by the user who edited the file.  The
	group of the backup is set to the group of the original file.  If this
	fails, the protection bits for the group are made the same as for
	others.

	When the file is renamed, this is the other way around: The backup has
	the same attributes of the original file, and the newly written file
	is owned by the current user.  When the file was a (hard/symbolic)
	link, the new file will not!  That's why the "auto" value doesn't
	rename when the file is a link.  The owner and group of the newly
	written file will be set to the same ones as the original file, but
	the system may refuse to do this.  In that case the "auto" value will
	again not rename the file.

	NOTE: This option is set to the Vi default value when 'compatible' is
	set and to the Vim default value when 'compatible' is reset.

						*'backupdir'* *'bdir'*
'backupdir' 'bdir'	string	(default for Amiga: ".,t:",
				 for Win32: ".,$TEMP,c:/tmp,c:/temp"
				 for Unix: ".,~/tmp