mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2026-07-09 10:59:38 +00:00
Code Issues Packages Projects Releases Wiki Activity

refactor: cleanup, docs #40480

Browse Source
This commit is contained in:
Justin M. Keyes
2026-06-29 13:10:31 -04:00
committed by GitHub
parent 845b66dd4a
commit d2073d2eec
25 changed files with 211 additions and 186 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
runtime/doc/api.txt
View File

@@ -2606,7 +2606,8 @@ nvim_buf_get_mark({buf}, {name}) *nvim_buf_get_mark()*
• |nvim_buf_del_mark()|
nvim_buf_get_name({buf}) *nvim_buf_get_name()*
Gets the full file name for the buffer
Gets the full/absolute filepath of the buffer, or the buffer name for
non-file buffers.
Attributes: ~
Since: 0.1.0

15
runtime/doc/dev.txt
View File

@@ -358,7 +358,7 @@ preference):
4. `on_error` callback
- For async and "visitors" traversing a graph, where many errors may be
collected while work continues.
5. `vim.notify` (sometimes with optional `opts.silent` (async, visitors))
5. `nvim_echo` (consider `opts.silent` for async/visitors)
- High-level / application-level messages. End-user invokes these directly.
@@ -409,9 +409,16 @@ API PATTERNS *dev-api-patterns*
filter(…, opts, fn)
-- ❌ NO:
filter(…, fn, opts)
- Expose a `config(opts)` function if the module accepts user configuration.
If `opts` is omitted (or `nil`) it returns the current configuration.
- Example: See |vim.diagnostic.config()|.
- If the module or topic wants to support configuration:
- Prefer a new 'option' (or family of related options, or "xxoptions" style
such as 'jumpoptions'). Options get these benefits "for free":
- Completion: `:set a<tab>`, `:lua vim.o.a<tab>`
- |OptionSet| event
- Scopes: global/buf/win/tab (can start as global, then "graduate" later)
- UI: `:verbose set`, `:options`, etc.
- Alternatively if the editor |options| system absolutey doesn't fit: Expose
a `config(opts)` interface (example: |vim.diagnostic.config()|). If `opts`
is omitted (or `nil`) it returns the current configuration.
- "Enable" ("toggle") interface and behavior:
- `enable(…, nil)` and `enable(…, {buf=nil})` are synonyms and control
the "global" enablement of a feature.

50
runtime/doc/editing.txt
View File

@@ -260,34 +260,33 @@ CTRL-^ Edit the alternate file. Mostly the alternate file is
See |CTRL-^| above for further details.
*gf* *E446* *E447*
[count]gf Edit the file whose name is under or after the cursor.
[count]gf Edit the filename at (or after) cursor.
Mnemonic: "goto file".
Uses the 'isfname' option to find out which characters
are supposed to be in a file name. Trailing
punctuation characters ".,:;!" are ignored. Escaped
spaces "\ " are reduced to a single space.
Uses the 'path' option as a list of directory names to
look for the file. See the 'path' option for details
about relative directories and wildcards.
Uses the 'suffixesadd' option to check for file names
with a suffix added.
If the file can't be found, 'includeexpr' is used to
modify the name and another attempt is done.
If a [count] is given, the count'th file that is found
in the 'path' is edited.
- The 'isfname' option decides what a filename is.
Trailing punctuation characters ".,:;!" are ignored.
Escaped spaces "\ " are reduced to a single space.
- The 'path' option decides where to look for the
file, including relative directories and wildcards.
- The 'suffixesadd' option controls which suffixes
(file extensions) are tried when building potential
filepaths.
- If the search fails, it is retried after applying
'includeexpr' to the filename.
- If a [count] is given, the count'th file that is
found in the 'path' is edited.
- If the name is a URL ("type://machine/path"), you
need the |netrw| plugin.
- Environment variables are expanded. |expand-env|.
- On unix: "~" is expanded.
This command fails if Vim refuses to |abandon| the
current file.
If you want to edit the file in a new window use
|CTRL-W_CTRL-F|.
See |CTRL-W_CTRL-F| to edit the file in a new window.
If you do want to edit a new file, use: >
:e <cfile>
< To make gf always work like that: >
:map gf :e <cfile><CR>
< If the name is a hypertext link, that looks like
"type://machine/path", you need the |netrw| plugin.
For Unix the '~' character is expanded, like in
"~user/file". Environment variables are expanded too
|expand-env|.
<
*v_gf*
{Visual}[count]gf Same as "gf", but the highlighted text is used as the
@@ -603,9 +602,8 @@ argument is subject to |cmdline-special| expansion, |wildcard| expansion, etc.
Instead, to open a filepath literally, use `bufadd(vim.fs.normalize(…))`: >lua
local buf = vim.fn.bufadd(vim.fs.normalize(path))
vim.fn.bufload(buf) -- Trigger BufReadPre/BufReadPost/FileType.
vim.bo[buf].buflisted = true -- Show in ":ls".
vim.api.nvim_win_set_buf(0, buf) -- Show in current window.
-- Set 'buflisted'; trigger BufReadPre/BufReadPost/FileType.
vim.api.nvim_buf_call(buf, vim.cmd.edit)
Alternatively, |nvim_cmd()| and |vim.cmd()| accept a structured form whose
`args` are tokenized verbatim. But the argument still goes through |:edit|'s

23
runtime/doc/gui.txt
View File

@@ -77,29 +77,30 @@ Restart Nvim
*:restart* *:restart!*
:restart[!] [+cmd] [command]
Restarts Nvim. Sets |v:exitreason|. See also |ZR|.
When [!] is included, the session is not restored.
Restarts Nvim. Saves and restores the current session, unless
[!] is given. Sets |v:exitreason|. See also |ZR|.
1. Stops Nvim using `:qall` (or |+cmd|, if given).
2. Starts a new Nvim server using the same |v:argv| (except
`-- [file…]` files). Sets |v:startreason| to "restart" on the
new server.
3. Attaches all UIs to the new Nvim server and runs `[command]`
1. Saves the current session (unless [!] was given).
2. Stops Nvim using `:qall` (or |+cmd|, if given).
3. Starts a new Nvim server using the same |v:argv| (except
`-- [file…]` files), and sets |v:startreason|.
4. Restores the saved session (unless [!] was given).
5. Attaches all UIs to the new Nvim server and runs `[command]`
on it.
Example: discard changes and stop with `:qall!`, then restart: >
:restart +qall!
< Example: restart and restore the current session: >
< Example: restart and (manually) restore the session: >
:mksession! Session.vim | restart! source Session.vim
< Example: restart and update plugins: >
:restart packupdate
<
Note:
• Only works if the UI and server are on the same system.
• Windows limitation: when +cmd is executed, |v:servername|
• Windows limitation: during +cmd execution, |v:servername|
refers to a temporary address.
• If no UI handles the "restart" event, this command will lead
to a dangling server process.
• If no UI handles the "restart" event, this leaves a dangling
process.
------------------------------------------------------------------------------
Connect UI to a different server

2
runtime/doc/index.txt
View File

@@ -12,7 +12,7 @@ to look for deleting something, use: "/delete".
For an overview of options see |option-list|.
For an overview of built-in functions see |functions|.
For a list of Vim variables see |vim-variable|.
For a list of Vim variables see |vvars|.
Type |gO| to see the table of contents.

2
runtime/doc/lua.txt
View File

@@ -2749,7 +2749,7 @@ vim.fs.normalize({path}, {opts}) *vim.fs.normalize()*
On Windows, backslash (\) characters are converted to forward slashes (/).
Examples: >lua
Examples: >
[[C:\Users\jdoe]] => "C:/Users/jdoe"
"~/src/neovim" => "/home/jdoe/src/neovim"
"$XDG_CONFIG_HOME/nvim/init.vim" => "/Users/jdoe/.config/nvim/init.vim"

7
runtime/doc/news.txt
View File

@@ -89,6 +89,7 @@ EDITOR
• Only supports one "cmdline level", not "infinite recursion".
• Expr-register (|i_CTRL-R_=|, |c_CTRL-R_=|) no longer supports opening
cmdwin via |c_CTRL-F|.
• Behavior of |:restart| changed. Use "!" (|:restart!|) to get the old behavior.
EVENTS
@@ -195,7 +196,8 @@ EDITOR
• The |cmdwin-char| is shown via 'statuscolumn'.
• |gf| and |<cfile>| support `file://…` URIs.
• |:log| opens log files.
• |:restart| now restores the current session while |:restart!| does not.
• |:restart| saves/restores the current session (window layout, buffers, …).
• |:restart!| (with a bang "!") does not save/restore the session.
• |ZR| restarts Nvim (|:restart!|).
• |:uptime| displays uptime.
• |:packupdate| and |:packdel| for managing |vim.pack|.
@@ -295,6 +297,7 @@ PERFORMANCE
• Internal LSP data is cleared using `table.clear`, which reduces GC and
memory reallocation during each data reset.
• RPC client avoids string allocations when parsing Content-Length messages.
• LSP: "overscan" semantic_token range requests to avoid flicker.
PLUGINS
@@ -335,7 +338,7 @@ UI
VIMSCRIPT
• |v:exitreason| is set before |QuitPre|.
• |v:startreason| differentiates between restart and normal start.
• |v:startreason| indicates whether Nvim started normally or by |:restart|.
• |v:starttime| is the process start time (nanoseconds since UNIX epoch).
• |v:useractive| indicates user activity.
• |serverlist()| with `info=true` returns details for each server (own + peers).

29
runtime/doc/options.txt
View File

@@ -810,11 +810,13 @@ A jump table for the options with a short description can be found at |Q_op|.
'autoread' 'ar' boolean (default on)
global or local to buffer |global-local|
When a file was changed outside of Nvim, automatically read it again.
Skipped if the file was deleted, so you have the text from before it
was deleted. If the file appears again then it is read. |timestamp|
Skipped if the file was deleted (so you still have the last-available
text). If the file appears again, then it is read; you can |undo| to
see the previous contents. |timestamp|
This is partially driven by OS filewatcher events |uv_fs_event_t|, so
even the current buffer may be updated.
This is driven (partially) by OS filewatcher events |uv_fs_event_t|,
so buffers are updated immediately (instead of only on focus-change or
shell-commands).
If this option has a local value, use this command to switch back to
using the global value: >vim
@@ -855,13 +857,13 @@ A jump table for the options with a short description can be found at |Q_op|.
that background type. The |TUI| or other UI sets this on startup
if it can detect the background color, and re-detects it whenever a UI
attaches later, unless 'background' was set explicitly. When multiple
terminal UIs are attached they share one value, taken from whichever
terminal reports its background last (which may not be the most
recently attached one, since it depends on response speed).
UIs are attached they share one value, decided by "last wins" (may
not be the most recently-attached UI, since it depends on response
speed).
This option does NOT change the background color, it tells Nvim what
the "inherited" (terminal/GUI) background looks like.
See |:hi-normal| if you want to set the background color explicitly.
the "inherited" (terminal/GUI) background looks like. See |:hi-normal|
to set the background color explicitly.
*g:colors_name*
When a color scheme is loaded (the "g:colors_name" variable is set)
changing 'background' will cause the color scheme to be reloaded. If
@@ -869,14 +871,13 @@ A jump table for the options with a short description can be found at |Q_op|.
However, if the color scheme sets 'background' itself the effect may
be undone. First delete the "g:colors_name" variable when needed.
Normally this option would be set in the vimrc file. Possibly
depending on the terminal name. Example: >vim
Historically, this option was set in the vimrc file. Example: >vim
if $TERM ==# "xterm"
set background=dark
endif
< When this option is changed, the default settings for the highlight groups
will change. To use other settings, place ":highlight" commands AFTER
the setting of the 'background' option.
< When this option is changed, the defaults for highlight groups
will change. To override those defaults, place ":highlight" commands
AFTER setting the 'background' option.
*'backspace'* *'bs'*
'backspace' 'bs' string (default "indent,eol,start")

4
runtime/doc/plugins.txt
View File

@@ -19,7 +19,7 @@ Standard plugins *standard-plugin-list*
Help-link Loaded Short description ~
|dir| Yes Directory listing for |:edit|
|difftool| No Compares two directories or files side-by-side
|difftool| No Compares directories (and files) side-by-side
|editorconfig| Yes Detect and interpret editorconfig
|ft-shada| Yes Allows editing binary |shada| files
|man.lua| Yes View manpages in Nvim
@@ -69,7 +69,7 @@ Directory buffers follow the global 'hidden' option by default. To delete them
after use: >vim
autocmd FileType directory setlocal bufhidden=delete
<
Use "wipe" to discard all buffer state; see |'bufhidden'|.
Use "wipe" to discard all buffer state; see 'bufhidden'.
*g:loaded_nvim_dir_plugin*
To disable this plugin, set this in your config before startup: >lua

6
runtime/doc/terminal.txt
View File

@@ -265,6 +265,12 @@ Example: >vim
Use |jobwait()| to check if the terminal job has finished: >vim
let running = jobwait([&channel], 0)[0] == -1
<
==============================================================================
Concepts *terminal-concepts*
TODO
==============================================================================
:Termdebug plugin *terminal-debug* *terminal-debugger*
*package-termdebug* *termdebug*

7
runtime/doc/vim_diff.txt
View File

@@ -425,9 +425,10 @@ Options:
- 'inccommand' shows interactive results for |:substitute|-like commands
and |:command-preview| commands
- 'jumpoptions'
- "view" tries to restore |mark-view| when moving through the jumplist.
- "view" tries to restore |mark-view| when moving through the |jumplist|,
|changelist|, |alternate-file|, and |mark-motions|.
- "clean" removes unloaded buffers from the jumplist.
- the |jumplist|, |changelist|, |alternate-file| or using |mark-motions|.
- 'langmap' supports multibyte chars.
- 'laststatus' global statusline support
- 'mousemodel' cannot be set to empty.
- 'mousescroll' amount to scroll by when scrolling with a mouse
@@ -712,7 +713,6 @@ Missing features *nvim-missing*
These legacy Vim features are not yet implemented:
- *:gui*
- *:gvim*
- *'browsedir'* *'bsdir'*
- *'completepopup'*
- *'guioptions'* *'go'*
@@ -743,6 +743,7 @@ Aliases:
Commands:
- :behave
- :fixdel
- *:gvim*
- *hardcopy* `:hardcopy` was removed. Instead, use `:TOhtml` and print the
resulting HTML using a web browser or other HTML viewer.
- :helpfind

2
runtime/doc/vimeval.txt
View File

@@ -1803,7 +1803,7 @@ Note that this means that filetype plugins don't get a different set of script
variables for each buffer. Use local buffer variables instead |b:var|.
PREDEFINED VIM VARIABLES *vim-variable* *v:var* *v:*
PREDEFINED VIM VARIABLES *vim-variable*
*E963*
The alphabetic list of all builtin variables and details are in a separate

38
runtime/doc/vimfn.txt
View File

@@ -593,7 +593,7 @@ browsedir({title}, {initdir}) *browsedir()*
(`0|1`)
bufadd({name}) *bufadd()*
Adds buffer {name} to the buffer list literally: no special
Adds buffer {name} to the |buffer-list| literally: no special
chars or expansion are applied (including "~"). Returns the
new (or existing matching) buffer number, or 0 on error.
@@ -601,9 +601,9 @@ bufadd({name}) *bufadd()*
{name} is an empty string, a new buffer is always created.
Example (Lua): >lua
local b = vim.fn.bufadd(vim.fs.normalize('someName'))
vim.bo[b].buflisted = true
vim.fn.bufload(b)
local buf = vim.fn.bufadd(vim.fs.normalize('someName'))
-- Set 'buflisted'; trigger BufReadPre/BufReadPost/FileType.
vim.api.nvim_buf_call(buf, vim.cmd.edit)
<
Parameters: ~
@@ -5800,7 +5800,11 @@ jobstart({cmd} [, {opts}]) *jobstart()*
pty: (boolean) Connect the job to a new pseudo
terminal, and its streams to the master file
descriptor. `on_stdout` receives all output,
`on_stderr` is ignored. |terminal-start|
`on_stderr` is ignored. Note: if the child writes
a query (DA1, OSC, …), it may hang or timeout waiting
for a response! To avoid that, `on_stdout` should
reply via |nvim_chan_send()| on the child's stdin.
See |terminal-start| |terminal-concepts|
rpc: (boolean) Use |msgpack-rpc| to communicate with
the job over stdio. Then `on_stdout` is ignored,
but `on_stderr` can still be used.
@@ -5811,11 +5815,12 @@ jobstart({cmd} [, {opts}]) *jobstart()*
stdin: (string) Either "pipe" (default) to connect the
job's stdin to a channel or "null" to disconnect
stdin.
term: (boolean) Spawns {cmd} in a new pseudo-terminal session
connected to the current (unmodified) buffer. Implies "pty".
Default "height" and "width" are set to the current window
dimensions. |jobstart()|. Defaults $TERM to "xterm-256color".
width: (number) Width of the `pty` terminal.
term: (boolean) Spawns {cmd} in a new pseudo-terminal
session connected to the current (unmodified) buffer.
Implies "pty". Defaults "height" and "width" to the
current window dimensions. Defaults $TERM to
"xterm-256color".
width: (number) Width of the `pty` pseudo-terminal.
{opts} is passed as |self| dictionary to the callback; the
caller may set other keys to pass application-specific data.
@@ -9274,14 +9279,13 @@ setbufvar({buf}, {varname}, {val}) *setbufvar()*
Lua: Prefer |nvim_buf_set_var()| or |vim.b| after resolving
{buf} to a bufnr; option names use |nvim_set_option_value()|.
Set option or local variable {varname} in buffer {buf} to
{val}.
This also works for a global or local window option, but it
doesn't work for a global or local window variable.
For a local window option the global value is unchanged.
Set option or local variable {varname} (string, without "b:")
in buffer {buf} to {val}. Also works for a global or
window-local option (not variable). When targeting
a window-local option, the global option is unchanged.
For the use of {buf}, see |bufname()| above.
The {varname} argument is a string.
Note that the variable name without "b:" must be used.
Examples: >vim
call setbufvar(1, "&mod", 1)
call setbufvar("todo", "myvar", "foobar")

10
runtime/doc/vvars.txt
View File

@@ -4,7 +4,7 @@
NVIM REFERENCE MANUAL
Predefined variables *vvars*
Predefined variables *vvars* *v:var* *v:*
Most variables are read-only, when a variable can be set by the user, it will
be mentioned at the variable description below. The type cannot be changed.
@@ -636,9 +636,9 @@ v:stacktrace
*v:startreason* *startreason-variable*
v:startreason
The reason Nvim started. Possible values:
- "normal" normal startup.
- "restart" started by |:restart|.
- "restart!" started by |:restart!| or |ZR|.
- "normal" Normal startup, yearning for life, etc.
- "restart" Started by |:restart|.
- "restart!" Started by |:restart!| or |ZR|.
Read-only.
@@ -763,7 +763,7 @@ v:true
operator) and to one when used as a Number (e.g. in |expr5| or
|expr7| when used with numeric operators). Read-only.
*v:useractive* *useractive-variable*
*v:useractive* *useractive-variable* *user-idle*
v:useractive
Timestamp (nanoseconds since UNIX epoch) indicating the most
recent user activity, i.e. when a key is received from a UI

40
runtime/lua/vim/_core/server.lua
View File

@@ -1,6 +1,4 @@
local fs = vim.fs
local uv = vim.uv
-- For "--listen" and related functionality.
-- For "--listen", ":restart", and related remote/server functionality.
local M = {}
@@ -156,34 +154,32 @@ function M.rebind_after_restart(canonical_addr, expected_uis)
end)
end
-- Called by ex_restart(). Saves the current session and calls back to
-- ex_restart() with the necessary arguments to restore the session.
-- Called by ex_restart(). Saves the current session and calls ex_restart() (again) with the
-- updated arguments.
--
-- TODO: https://github.com/neovim/neovim/issues/34204
--
--- @param eap vim._core.ExCmdArgs
--- @param extra { quit_cmd: string }
function M.ex_session_restart(eap, extra)
-- Commands to run after restart
local after_cmd = eap.args
local after_cmd = eap.args -- User-provided [command].
assert(not after_cmd:find(']==]'))
-- Use custom quit command if provided
local quit_cmd = 'qall'
if extra.quit_cmd ~= '' then
quit_cmd = extra.quit_cmd
end
-- Use custom +cmd if given.
local quit_cmd = extra.quit_cmd == '' and 'qall' or extra.quit_cmd
-- Preserve the value of v:this_session
-- Preserve v:this_session in the restarted Nvim.
local this_session = vim.v.this_session
assert(not this_session:find(']==]'))
-- Get temp file to write session to
local temp_dir = fs.abspath(fs.dirname(fs.dirname(vim.fn.tempname())))
assert(not temp_dir:find(']==]'))
local fd, session = uv.fs_mkstemp(fs.joinpath(temp_dir, 'restart_session_XXXXXX'))
-- Nvim temp "root dir": "/tmp/…/nvim.<user>/"
local tmproot = vim.fs.abspath(vim.fs.dirname(vim.fs.dirname(vim.fn.tempname())))
assert(not tmproot:find(']==]'))
local fd, session = vim.uv.fs_mkstemp(vim.fs.joinpath(tmproot, 'restart_session_XXXXXX'))
if not fd then
error('Failed to get temporary filename for restart session')
end
uv.fs_close(fd)
vim.uv.fs_close(fd)
-- Write session
local session_arg = vim.fn.fnameescape(session)
@@ -195,22 +191,20 @@ function M.ex_session_restart(eap, extra)
table.insert(after_list, ('vim.cmd("source %s")'):format(session_arg))
table.insert(after_list, ('pcall(vim.fs.rm, [==[%s]==])'):format(session))
table.insert(after_list, ('vim.v.this_session = [==[%s]==]'):format(this_session))
-- User provided command
if after_cmd ~= '' then
table.insert(after_list, ('vim.cmd([==[%s]==])'):format(after_cmd))
end
-- Concatenate everything together
local after = 'lua ' .. table.concat(after_list, ';')
-- Restart Neovim and run our Lua commands
local success, msg = pcall(function()
-- "+:::" special argument tells the C handler that this is actually a non-bang restart
-- That way, v:startreason can be set correctly
-- "+:::" dummy prefix tells the C handler that this is actually a non-bang restart.
-- Then v:startreason (if any) can be preserved.
vim.cmd.restart { '+:::', quit_cmd, after, bang = true }
end)
if not success then
fs.rm(session, { force = true })
vim.fs.rm(session, { force = true })
error(msg)
end
end

2
runtime/lua/vim/_meta/api.gen.lua generated
View File

@@ -509,7 +509,7 @@ function vim.api.nvim_buf_get_lines(buf, start, end_, strict_indexing) end
--- uppercase/file mark set in another buffer.
function vim.api.nvim_buf_get_mark(buf, name) end
--- Gets the full file name for the buffer
--- Gets the full/absolute filepath of the buffer, or the buffer name for non-file buffers.
---
--- @param buf integer Buffer id, or 0 for current buffer
--- @return string # Buffer name

29
runtime/lua/vim/_meta/options.gen.lua generated
View File

@@ -169,11 +169,13 @@ vim.bo.autoindent = vim.o.autoindent
vim.bo.ai = vim.bo.autoindent
--- When a file was changed outside of Nvim, automatically read it again.
--- Skipped if the file was deleted, so you have the text from before it
--- was deleted. If the file appears again then it is read. `timestamp`
--- Skipped if the file was deleted (so you still have the last-available
--- text). If the file appears again, then it is read; you can `undo` to
--- see the previous contents. `timestamp`
---
--- This is partially driven by OS filewatcher events `uv_fs_event_t`, so
--- even the current buffer may be updated.
--- This is driven (partially) by OS filewatcher events `uv_fs_event_t`,
--- so buffers are updated immediately (instead of only on focus-change or
--- shell-commands).
---
--- If this option has a local value, use this command to switch back to
--- using the global value:
@@ -228,13 +230,13 @@ vim.go.awa = vim.go.autowriteall
--- that background type. The `TUI` or other UI sets this on startup
--- if it can detect the background color, and re-detects it whenever a UI
--- attaches later, unless 'background' was set explicitly. When multiple
--- terminal UIs are attached they share one value, taken from whichever
--- terminal reports its background last (which may not be the most
--- recently attached one, since it depends on response speed).
--- UIs are attached they share one value, decided by "last wins" (may
--- not be the most recently-attached UI, since it depends on response
--- speed).
---
--- This option does NOT change the background color, it tells Nvim what
--- the "inherited" (terminal/GUI) background looks like.
--- See `:hi-normal` if you want to set the background color explicitly.
--- the "inherited" (terminal/GUI) background looks like. See `:hi-normal`
--- to set the background color explicitly.
--- *g:colors_name*
--- When a color scheme is loaded (the "g:colors_name" variable is set)
--- changing 'background' will cause the color scheme to be reloaded. If
@@ -242,17 +244,16 @@ vim.go.awa = vim.go.autowriteall
--- However, if the color scheme sets 'background' itself the effect may
--- be undone. First delete the "g:colors_name" variable when needed.
---
--- Normally this option would be set in the vimrc file. Possibly
--- depending on the terminal name. Example:
--- Historically, this option was set in the vimrc file. Example:
---
--- ```vim
--- if $TERM ==# "xterm"
--- set background=dark
--- endif
--- ```
--- When this option is changed, the default settings for the highlight groups
--- will change. To use other settings, place ":highlight" commands AFTER
--- the setting of the 'background' option.
--- When this option is changed, the defaults for highlight groups
--- will change. To override those defaults, place ":highlight" commands
--- AFTER setting the 'background' option.
---
--- @type 'light'|'dark'
vim.o.background = "dark"

38
runtime/lua/vim/_meta/vimfn.gen.lua generated
View File

@@ -496,7 +496,7 @@ function vim.fn.browse(save, title, initdir, default) end
--- @return 0|1
function vim.fn.browsedir(title, initdir) end
--- Adds buffer {name} to the buffer list literally: no special
--- Adds buffer {name} to the |buffer-list| literally: no special
--- chars or expansion are applied (including "~"). Returns the
--- new (or existing matching) buffer number, or 0 on error.
---
@@ -504,9 +504,9 @@ function vim.fn.browsedir(title, initdir) end
--- {name} is an empty string, a new buffer is always created.
---
--- Example (Lua): >lua
--- local b = vim.fn.bufadd(vim.fs.normalize('someName'))
--- vim.bo[b].buflisted = true
--- vim.fn.bufload(b)
--- local buf = vim.fn.bufadd(vim.fs.normalize('someName'))
--- -- Set 'buflisted'; trigger BufReadPre/BufReadPost/FileType.
--- vim.api.nvim_buf_call(buf, vim.cmd.edit)
--- <
---
--- @param name string
@@ -5247,7 +5247,11 @@ function vim.fn.jobsend(...) end
--- pty: (boolean) Connect the job to a new pseudo
--- terminal, and its streams to the master file
--- descriptor. `on_stdout` receives all output,
--- `on_stderr` is ignored. |terminal-start|
--- `on_stderr` is ignored. Note: if the child writes
--- a query (DA1, OSC, …), it may hang or timeout waiting
--- for a response! To avoid that, `on_stdout` should
--- reply via |nvim_chan_send()| on the child's stdin.
--- See |terminal-start| |terminal-concepts|
--- rpc: (boolean) Use |msgpack-rpc| to communicate with
--- the job over stdio. Then `on_stdout` is ignored,
--- but `on_stderr` can still be used.
@@ -5258,11 +5262,12 @@ function vim.fn.jobsend(...) end
--- stdin: (string) Either "pipe" (default) to connect the
--- job's stdin to a channel or "null" to disconnect
--- stdin.
--- term: (boolean) Spawns {cmd} in a new pseudo-terminal session
--- connected to the current (unmodified) buffer. Implies "pty".
--- Default "height" and "width" are set to the current window
--- dimensions. |jobstart()|. Defaults $TERM to "xterm-256color".
--- width: (number) Width of the `pty` terminal.
--- term: (boolean) Spawns {cmd} in a new pseudo-terminal
--- session connected to the current (unmodified) buffer.
--- Implies "pty". Defaults "height" and "width" to the
--- current window dimensions. Defaults $TERM to
--- "xterm-256color".
--- width: (number) Width of the `pty` pseudo-terminal.
---
--- {opts} is passed as |self| dictionary to the callback; the
--- caller may set other keys to pass application-specific data.
@@ -8412,14 +8417,13 @@ function vim.fn.setbufline(buf, lnum, text) end
--- Lua: Prefer |nvim_buf_set_var()| or |vim.b| after resolving {buf} to a bufnr; option names use |nvim_set_option_value()|.
---
--- Set option or local variable {varname} in buffer {buf} to
--- {val}.
--- This also works for a global or local window option, but it
--- doesn't work for a global or local window variable.
--- For a local window option the global value is unchanged.
--- Set option or local variable {varname} (string, without "b:")
--- in buffer {buf} to {val}. Also works for a global or
--- window-local option (not variable). When targeting
--- a window-local option, the global option is unchanged.
---
--- For the use of {buf}, see |bufname()| above.
--- The {varname} argument is a string.
--- Note that the variable name without "b:" must be used.
---
--- Examples: >vim
--- call setbufvar(1, "&mod", 1)
--- call setbufvar("todo", "myvar", "foobar")

6
runtime/lua/vim/_meta/vvars.gen.lua generated
View File

@@ -668,9 +668,9 @@ vim.v.shell_error = ...
vim.v.stacktrace = ...
--- The reason Nvim started. Possible values:
--- - "normal" normal startup.
--- - "restart" started by `:restart`.
--- - "restart!" started by `:restart!` or `ZR`.
--- - "normal" Normal startup, yearning for life, etc.
--- - "restart" Started by `:restart`.
--- - "restart!" Started by `:restart!` or `ZR`.
---
--- Read-only.
--- @type string

2
runtime/lua/vim/fs.lua
View File

@@ -640,7 +640,7 @@ end
--- On Windows, backslash (\) characters are converted to forward slashes (/).
---
--- Examples:
--- ```lua
--- ```
--- [[C:\Users\jdoe]] => "C:/Users/jdoe"
--- "~/src/neovim" => "/home/jdoe/src/neovim"
--- "$XDG_CONFIG_HOME/nvim/init.vim" => "/Users/jdoe/.config/nvim/init.vim"

2
src/nvim/api/buffer.c
View File

@@ -938,7 +938,7 @@ void nvim_buf_del_var(Buffer buf, String name, Error *err)
dict_set_var(b->b_vars, name, NIL, true, false, NULL, err);
}
/// Gets the full file name for the buffer
/// Gets the full/absolute filepath of the buffer, or the buffer name for non-file buffers.
///
/// @param buf Buffer id, or 0 for current buffer
/// @param[out] err Error details, if any

38
src/nvim/eval.lua
View File

@@ -671,7 +671,7 @@ M.funcs = {
args = 1,
base = 1,
desc = [=[
Adds buffer {name} to the buffer list literally: no special
Adds buffer {name} to the |buffer-list| literally: no special
chars or expansion are applied (including "~"). Returns the
new (or existing matching) buffer number, or 0 on error.
@@ -679,9 +679,9 @@ M.funcs = {
{name} is an empty string, a new buffer is always created.
Example (Lua): >lua
local b = vim.fn.bufadd(vim.fs.normalize('someName'))
vim.bo[b].buflisted = true
vim.fn.bufload(b)
local buf = vim.fn.bufadd(vim.fs.normalize('someName'))
-- Set 'buflisted'; trigger BufReadPre/BufReadPost/FileType.
vim.api.nvim_buf_call(buf, vim.cmd.edit)
<
]=],
name = 'bufadd',
@@ -6378,7 +6378,11 @@ M.funcs = {
pty: (boolean) Connect the job to a new pseudo
terminal, and its streams to the master file
descriptor. `on_stdout` receives all output,
`on_stderr` is ignored. |terminal-start|
`on_stderr` is ignored. Note: if the child writes
a query (DA1, OSC, …), it may hang or timeout waiting
for a response! To avoid that, `on_stdout` should
reply via |nvim_chan_send()| on the child's stdin.
See |terminal-start| |terminal-concepts|
rpc: (boolean) Use |msgpack-rpc| to communicate with
the job over stdio. Then `on_stdout` is ignored,
but `on_stderr` can still be used.
@@ -6389,11 +6393,12 @@ M.funcs = {
stdin: (string) Either "pipe" (default) to connect the
job's stdin to a channel or "null" to disconnect
stdin.
term: (boolean) Spawns {cmd} in a new pseudo-terminal session
connected to the current (unmodified) buffer. Implies "pty".
Default "height" and "width" are set to the current window
dimensions. |jobstart()|. Defaults $TERM to "xterm-256color".
width: (number) Width of the `pty` terminal.
term: (boolean) Spawns {cmd} in a new pseudo-terminal
session connected to the current (unmodified) buffer.
Implies "pty". Defaults "height" and "width" to the
current window dimensions. Defaults $TERM to
"xterm-256color".
width: (number) Width of the `pty` pseudo-terminal.
{opts} is passed as |self| dictionary to the callback; the
caller may set other keys to pass application-specific data.
@@ -10106,14 +10111,13 @@ M.funcs = {
args = 3,
base = 3,
desc = [=[
Set option or local variable {varname} in buffer {buf} to
{val}.
This also works for a global or local window option, but it
doesn't work for a global or local window variable.
For a local window option the global value is unchanged.
Set option or local variable {varname} (string, without "b:")
in buffer {buf} to {val}. Also works for a global or
window-local option (not variable). When targeting
a window-local option, the global option is unchanged.
For the use of {buf}, see |bufname()| above.
The {varname} argument is a string.
Note that the variable name without "b:" must be used.
Examples: >vim
call setbufvar(1, "&mod", 1)
call setbufvar("todo", "myvar", "foobar")

6
src/nvim/ex_docmd.c
View File

@@ -4970,8 +4970,7 @@ static void ex_quitall(exarg_T *eap)
static void ex_restart(exarg_T *eap)
{
if (!eap->forceit) {
// Pass +cmd via the `extra` slot of nlua_call_excmd
dict_T *extra_d = tv_dict_alloc();
dict_T *extra_d = tv_dict_alloc(); // Pass +cmd in the `extra` param of nlua_call_excmd.
tv_dict_add_str(extra_d, S_LEN("quit_cmd"), eap->do_ecmd_cmd ? eap->do_ecmd_cmd : "");
typval_T extra_tv = { .v_type = VAR_DICT, .vval.v_dict = extra_d };
nlua_call_excmd("vim._core.server", "ex_session_restart", eap, &cmdmod, &extra_tv);
@@ -4983,10 +4982,9 @@ static void ex_restart(exarg_T *eap)
char *quit_cmd = (eap->do_ecmd_cmd) ? eap->do_ecmd_cmd : "qall";
char *after_cmd = eap->arg;
// "+:::" is how ex_session_restart() signals that it (recursively) called into :restart.
// XXX: "+:::" is how ex_session_restart() signals that it (recursively) called :restart.
if (strequal(quit_cmd, ":::")) {
startreason = "restart";
// Set quit_cmd and after_cmd from args
if (eap->argc > 1) {
eap->args[1][eap->arglens[1]] = NUL;
quit_cmd = eap->args[1];

29
src/nvim/options.lua
View File

@@ -302,11 +302,13 @@ local options = {
defaults = true,
desc = [=[
When a file was changed outside of Nvim, automatically read it again.
Skipped if the file was deleted, so you have the text from before it
was deleted. If the file appears again then it is read. |timestamp|
Skipped if the file was deleted (so you still have the last-available
text). If the file appears again, then it is read; you can |undo| to
see the previous contents. |timestamp|
This is partially driven by OS filewatcher events |uv_fs_event_t|, so
even the current buffer may be updated.
This is driven (partially) by OS filewatcher events |uv_fs_event_t|,
so buffers are updated immediately (instead of only on focus-change or
shell-commands).
If this option has a local value, use this command to switch back to
using the global value: >vim
@@ -370,13 +372,13 @@ local options = {
that background type. The |TUI| or other UI sets this on startup
if it can detect the background color, and re-detects it whenever a UI
attaches later, unless 'background' was set explicitly. When multiple
terminal UIs are attached they share one value, taken from whichever
terminal reports its background last (which may not be the most
recently attached one, since it depends on response speed).
UIs are attached they share one value, decided by "last wins" (may
not be the most recently-attached UI, since it depends on response
speed).
This option does NOT change the background color, it tells Nvim what
the "inherited" (terminal/GUI) background looks like.
See |:hi-normal| if you want to set the background color explicitly.
the "inherited" (terminal/GUI) background looks like. See |:hi-normal|
to set the background color explicitly.
*g:colors_name*
When a color scheme is loaded (the "g:colors_name" variable is set)
changing 'background' will cause the color scheme to be reloaded. If
@@ -384,14 +386,13 @@ local options = {
However, if the color scheme sets 'background' itself the effect may
be undone. First delete the "g:colors_name" variable when needed.
Normally this option would be set in the vimrc file. Possibly
depending on the terminal name. Example: >vim
Historically, this option was set in the vimrc file. Example: >vim
if $TERM ==# "xterm"
set background=dark
endif
< When this option is changed, the default settings for the highlight groups
will change. To use other settings, place ":highlight" commands AFTER
the setting of the 'background' option.
< When this option is changed, the defaults for highlight groups
will change. To override those defaults, place ":highlight" commands
AFTER setting the 'background' option.
]=],
full_name = 'background',
scope = { 'global' },

7
src/nvim/vvars.lua
View File

@@ -449,6 +449,7 @@ M.vars = {
},
useractive = {
type = 'integer',
tags = { 'user-idle' },
desc = [=[
Timestamp (nanoseconds since UNIX epoch) indicating the most
recent user activity, i.e. when a key is received from a UI
@@ -780,9 +781,9 @@ M.vars = {
type = 'string',
desc = [=[
The reason Nvim started. Possible values:
- "normal" normal startup.
- "restart" started by |:restart|.
- "restart!" started by |:restart!| or |ZR|.
- "normal" Normal startup, yearning for life, etc.
- "restart" Started by |:restart|.
- "restart!" Started by |:restart!| or |ZR|.
Read-only.
]=],