commit dbd7f4587371901f927152037c8f38fb63b1f59d
parent 71ce3030eb589b813d3c719b21271787622f7828
Author: zeertzjq <zeertzjq@outlook.com>
Date: Mon, 24 Nov 2025 10:29:39 +0800
vim-patch:2190036: runtime(doc): Add environment variable expansion note to options (#36675)
Add "Environment variables are expanded |:set_env|" documentation to
options that have the P_EXPAND flag but were missing this note.
Updated options:
- 'cdpath'
- 'dictionary'
- 'mkspellmem'
- 'packpath'
- 'runtimepath'
- 'spellfile'
- 'spellsuggest'
- 'thesaurus'
- 'ttytype'
- 'undodir'
- 'verbosefile'
- 'viewdir'
- 'viminfofile'
These options support environment variable expansion in their values
(e.g., $HOME, $USER) but the documentation didn't explicitly mention
this capability. This brings their documentation in line with other
options like backupdir, directory, and makeprg that already include
this note.
closes: vim/vim#18791
https://github.com/vim/vim/commit/2190036c8cfb1e94625756b8ffbb3aa65f04687e
Co-authored-by: Alex Plate <AlexPl292@gmail.com>
Diffstat:
3 files changed, 50 insertions(+), 14 deletions(-)
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
@@ -1288,7 +1288,8 @@ A jump table for the options with a short description can be found at |Q_op|.
a modified version of the following command in your vimrc file to
override it: >vim
let &cdpath = ',' .. substitute(substitute($CDPATH, '[, ]', '\\\0', 'g'), ':', ',', 'g')
-< This option cannot be set from a |modeline| or in the |sandbox|, for
+< Environment variables are expanded |:set_env|.
+ This option cannot be set from a |modeline| or in the |sandbox|, for
security reasons.
(parts of 'cdpath' can be passed to the shell to expand file names).
@@ -2146,6 +2147,7 @@ A jump table for the options with a short description can be found at |Q_op|.
To include a comma in a file name precede it with a backslash. Spaces
after a comma are ignored, otherwise spaces are included in the file
name. See |option-backslash| about using backslashes.
+ Environment variables are expanded |:set_env|.
This has nothing to do with the |Dictionary| variable type.
Where to find a list of words?
- BSD/macOS include the "/usr/share/dict/words" file.
@@ -4452,7 +4454,7 @@ A jump table for the options with a short description can be found at |Q_op|.
set mkspellmem=900000,3000,800
< If you have less than 512 Mbyte |:mkspell| may fail for some
languages, no matter what you set 'mkspellmem' to.
-
+ Environment variables are expanded |:set_env|.
This option cannot be set from a |modeline| or in the |sandbox|, for
security reasons.
@@ -4775,6 +4777,7 @@ A jump table for the options with a short description can be found at |Q_op|.
global
Directories used to find packages.
See |packages| and |packages-runtimepath|.
+ Environment variables are expanded |:set_env|.
This option cannot be set from a |modeline| or in the |sandbox|, for
security reasons.
@@ -5231,6 +5234,9 @@ A jump table for the options with a short description can be found at |Q_op|.
to find files which add to distributed runtime files.
With |--clean| the home directory entries are not included.
+ Environment variables are expanded |:set_env|.
+ This option cannot be set from a |modeline| or in the |sandbox|, for
+ security reasons.
*'scroll'* *'scr'*
'scroll' 'scr' number (default half the window height)
@@ -5532,6 +5538,7 @@ A jump table for the options with a short description can be found at |Q_op|.
When equal to "NONE" no shada file will be read or written.
This option can be set with the |-i| command line flag. The |--clean|
command line flag sets it to "NONE".
+ Environment variables are expanded |:set_env|.
This option cannot be set from a |modeline| or in the |sandbox|, for
security reasons.
@@ -6073,6 +6080,7 @@ A jump table for the options with a short description can be found at |Q_op|.
name if you want to. However, it will then only be used when
'spellfile' is set to it, for entries in 'spelllang' only files
without region name will be found.
+ Environment variables are expanded |:set_env|.
This option cannot be set from a |modeline| or in the |sandbox|, for
security reasons.
@@ -6194,7 +6202,7 @@ A jump table for the options with a short description can be found at |Q_op|.
Only one of "best", "double" or "fast" may be used. The others may
appear several times in any order. Example: >vim
set sps=file:~/.config/nvim/sugg,best,expr:MySuggest()
-<
+< Environment variables are expanded |:set_env|.
This option cannot be set from a |modeline| or in the |sandbox|, for
security reasons.
@@ -6873,8 +6881,9 @@ A jump table for the options with a short description can be found at |Q_op|.
name. See |option-backslash| about using backslashes. The use of
|:set+=| and |:set-=| is preferred when adding or removing directories
from the list. This avoids problems when a future version uses
- another default. Backticks cannot be used in this option for security
- reasons.
+ another default.
+ Environment variables are expanded |:set_env|.
+ Backticks cannot be used in this option for security reasons.
*'thesaurusfunc'* *'tsrfu'*
'thesaurusfunc' 'tsrfu' string (default "")
@@ -7009,6 +7018,7 @@ A jump table for the options with a short description can be found at |Q_op|.
undo file that exists is used. When it cannot be read an error is
given, no further entry is used.
See |undo-persistence|.
+ Environment variables are expanded |:set_env|.
This option cannot be set from a |modeline| or in the |sandbox|, for
security reasons.
@@ -7162,6 +7172,7 @@ A jump table for the options with a short description can be found at |Q_op|.
Setting 'verbosefile' to a new value is like making it empty first.
The difference with |:redir| is that verbose messages are not
displayed when 'verbosefile' is set.
+ Environment variables are expanded |:set_env|.
This option cannot be set from a |modeline| or in the |sandbox|, for
security reasons.
@@ -7169,6 +7180,7 @@ A jump table for the options with a short description can be found at |Q_op|.
'viewdir' 'vdir' string (default "$XDG_STATE_HOME/nvim/view//")
global
Name of the directory where to store files for |:mkview|.
+ Environment variables are expanded |:set_env|.
This option cannot be set from a |modeline| or in the |sandbox|, for
security reasons.
diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua
@@ -753,6 +753,7 @@ vim.go.cdh = vim.go.cdhome
--- ```vim
--- let &cdpath = ',' .. substitute(substitute($CDPATH, '[, ]', '\\\0', 'g'), ':', ',', 'g')
--- ```
+--- Environment variables are expanded `:set_env`.
--- This option cannot be set from a `modeline` or in the `sandbox`, for
--- security reasons.
--- (parts of 'cdpath' can be passed to the shell to expand file names).
@@ -1752,6 +1753,7 @@ vim.go.deco = vim.go.delcombine
--- To include a comma in a file name precede it with a backslash. Spaces
--- after a comma are ignored, otherwise spaces are included in the file
--- name. See `option-backslash` about using backslashes.
+--- Environment variables are expanded `:set_env`.
--- This has nothing to do with the `Dictionary` variable type.
--- Where to find a list of words?
--- - BSD/macOS include the "/usr/share/dict/words" file.
@@ -4547,7 +4549,7 @@ vim.go.mopt = vim.go.messagesopt
--- ```
--- If you have less than 512 Mbyte `:mkspell` may fail for some
--- languages, no matter what you set 'mkspellmem' to.
----
+--- Environment variables are expanded `:set_env`.
--- This option cannot be set from a `modeline` or in the `sandbox`, for
--- security reasons.
---
@@ -4931,6 +4933,7 @@ vim.go.opfunc = vim.go.operatorfunc
--- Directories used to find packages.
--- See `packages` and `packages-runtimepath`.
+--- Environment variables are expanded `:set_env`.
--- This option cannot be set from a `modeline` or in the `sandbox`, for
--- security reasons.
---
@@ -5489,6 +5492,9 @@ vim.go.ruf = vim.go.rulerformat
--- to find files which add to distributed runtime files.
---
--- With `--clean` the home directory entries are not included.
+--- Environment variables are expanded `:set_env`.
+--- This option cannot be set from a `modeline` or in the `sandbox`, for
+--- security reasons.
---
--- @type string
vim.o.runtimepath = "..."
@@ -5832,6 +5838,7 @@ vim.go.sd = vim.go.shada
--- When equal to "NONE" no shada file will be read or written.
--- This option can be set with the `-i` command line flag. The `--clean`
--- command line flag sets it to "NONE".
+--- Environment variables are expanded `:set_env`.
--- This option cannot be set from a `modeline` or in the `sandbox`, for
--- security reasons.
---
@@ -6487,6 +6494,7 @@ vim.bo.spc = vim.bo.spellcapcheck
--- name if you want to. However, it will then only be used when
--- 'spellfile' is set to it, for entries in 'spelllang' only files
--- without region name will be found.
+--- Environment variables are expanded `:set_env`.
--- This option cannot be set from a `modeline` or in the `sandbox`, for
--- security reasons.
---
@@ -6623,7 +6631,7 @@ vim.bo.spo = vim.bo.spelloptions
--- ```vim
--- set sps=file:~/.config/nvim/sugg,best,expr:MySuggest()
--- ```
----
+--- Environment variables are expanded `:set_env`.
--- This option cannot be set from a `modeline` or in the `sandbox`, for
--- security reasons.
---
@@ -7438,8 +7446,9 @@ vim.bo.tw = vim.bo.textwidth
--- name. See `option-backslash` about using backslashes. The use of
--- `:set+=` and `:set-=` is preferred when adding or removing directories
--- from the list. This avoids problems when a future version uses
---- another default. Backticks cannot be used in this option for security
---- reasons.
+--- another default.
+--- Environment variables are expanded `:set_env`.
+--- Backticks cannot be used in this option for security reasons.
---
--- @type string
vim.o.thesaurus = ""
@@ -7610,6 +7619,7 @@ vim.go.ttm = vim.go.ttimeoutlen
--- undo file that exists is used. When it cannot be read an error is
--- given, no further entry is used.
--- See `undo-persistence`.
+--- Environment variables are expanded `:set_env`.
--- This option cannot be set from a `modeline` or in the `sandbox`, for
--- security reasons.
---
@@ -7803,6 +7813,7 @@ vim.go.vbs = vim.go.verbose
--- Setting 'verbosefile' to a new value is like making it empty first.
--- The difference with `:redir` is that verbose messages are not
--- displayed when 'verbosefile' is set.
+--- Environment variables are expanded `:set_env`.
--- This option cannot be set from a `modeline` or in the `sandbox`, for
--- security reasons.
---
@@ -7813,6 +7824,7 @@ vim.go.verbosefile = vim.o.verbosefile
vim.go.vfile = vim.go.verbosefile
--- Name of the directory where to store files for `:mkview`.
+--- Environment variables are expanded `:set_env`.
--- This option cannot be set from a `modeline` or in the `sandbox`, for
--- security reasons.
---
diff --git a/src/nvim/options.lua b/src/nvim/options.lua
@@ -1080,7 +1080,8 @@ local options = {
a modified version of the following command in your vimrc file to
override it: >vim
let &cdpath = ',' .. substitute(substitute($CDPATH, '[, ]', '\\\0', 'g'), ':', ',', 'g')
- < This option cannot be set from a |modeline| or in the |sandbox|, for
+ < Environment variables are expanded |:set_env|.
+ This option cannot be set from a |modeline| or in the |sandbox|, for
security reasons.
(parts of 'cdpath' can be passed to the shell to expand file names).
]=],
@@ -2300,6 +2301,7 @@ local options = {
To include a comma in a file name precede it with a backslash. Spaces
after a comma are ignored, otherwise spaces are included in the file
name. See |option-backslash| about using backslashes.
+ Environment variables are expanded |:set_env|.
This has nothing to do with the |Dictionary| variable type.
Where to find a list of words?
- BSD/macOS include the "/usr/share/dict/words" file.
@@ -5892,7 +5894,7 @@ local options = {
set mkspellmem=900000,3000,800
< If you have less than 512 Mbyte |:mkspell| may fail for some
languages, no matter what you set 'mkspellmem' to.
-
+ Environment variables are expanded |:set_env|.
This option cannot be set from a |modeline| or in the |sandbox|, for
security reasons.
]=],
@@ -6480,6 +6482,7 @@ local options = {
desc = [=[
Directories used to find packages.
See |packages| and |packages-runtimepath|.
+ Environment variables are expanded |:set_env|.
This option cannot be set from a |modeline| or in the |sandbox|, for
security reasons.
]=],
@@ -7209,6 +7212,9 @@ local options = {
to find files which add to distributed runtime files.
With |--clean| the home directory entries are not included.
+ Environment variables are expanded |:set_env|.
+ This option cannot be set from a |modeline| or in the |sandbox|, for
+ security reasons.
]=],
expand = 'nodefault',
full_name = 'runtimepath',
@@ -7660,6 +7666,7 @@ local options = {
When equal to "NONE" no shada file will be read or written.
This option can be set with the |-i| command line flag. The |--clean|
command line flag sets it to "NONE".
+ Environment variables are expanded |:set_env|.
This option cannot be set from a |modeline| or in the |sandbox|, for
security reasons.
]=],
@@ -8501,6 +8508,7 @@ local options = {
name if you want to. However, it will then only be used when
'spellfile' is set to it, for entries in 'spelllang' only files
without region name will be found.
+ Environment variables are expanded |:set_env|.
This option cannot be set from a |modeline| or in the |sandbox|, for
security reasons.
]=],
@@ -8661,7 +8669,7 @@ local options = {
Only one of "best", "double" or "fast" may be used. The others may
appear several times in any order. Example: >vim
set sps=file:~/.config/nvim/sugg,best,expr:MySuggest()
- <
+ < Environment variables are expanded |:set_env|.
This option cannot be set from a |modeline| or in the |sandbox|, for
security reasons.
]=],
@@ -9627,8 +9635,9 @@ local options = {
name. See |option-backslash| about using backslashes. The use of
|:set+=| and |:set-=| is preferred when adding or removing directories
from the list. This avoids problems when a future version uses
- another default. Backticks cannot be used in this option for security
- reasons.
+ another default.
+ Environment variables are expanded |:set_env|.
+ Backticks cannot be used in this option for security reasons.
]=],
expand = true,
full_name = 'thesaurus',
@@ -9860,6 +9869,7 @@ local options = {
undo file that exists is used. When it cannot be read an error is
given, no further entry is used.
See |undo-persistence|.
+ Environment variables are expanded |:set_env|.
This option cannot be set from a |modeline| or in the |sandbox|, for
security reasons.
@@ -10090,6 +10100,7 @@ local options = {
Setting 'verbosefile' to a new value is like making it empty first.
The difference with |:redir| is that verbose messages are not
displayed when 'verbosefile' is set.
+ Environment variables are expanded |:set_env|.
This option cannot be set from a |modeline| or in the |sandbox|, for
security reasons.
]=],
@@ -10106,6 +10117,7 @@ local options = {
defaults = '',
desc = [=[
Name of the directory where to store files for |:mkview|.
+ Environment variables are expanded |:set_env|.
This option cannot be set from a |modeline| or in the |sandbox|, for
security reasons.
]=],
