Home Explore Blog CI



neovim

7th chunk of `runtime/doc/options.txt`
4de8b3358ceee50e151b2d940c88453a81b7bff6dc19bcb60000000100000fa2
 *: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).

								*$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.

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

Besides changing options with the ":set" command, you can set options
automatically in various ways:

1. With a |config| file or a |startup| argument. You can create an
   initialization file with |:mkvimrc|, |:mkview| and |:mksession|.
2. |autocommand|s executed when you edit a file.
3. ".nvim.lua" files in the current directory, if 'exrc' is enabled.
4. |editorconfig| in the current buffer's directory or ancestors.
5. 'modeline' settings found at the beginning or end of the file. See below.

					*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

Title: Expanding Options, Auto-Setting Options, and Modelines in Vim
Summary
This section explains how Vim handles environment variables like $HOME on different operating systems and details the limitations on expanded option lengths. It then discusses various methods for automatically setting options, including config files, autocommands, `.nvim.lua` files, EditorConfig, and modelines. The section specifically covers the two forms of modelines and their syntax, which allow setting options directly within a file.