commit 858576777eb3d5227c6450c327ea87e40a59fda1
parent fd69b7111912ae5ccb01327b130f582be23e44dc
Author: Justin M. Keyes <justinkz@gmail.com>
Date: Thu, 25 Dec 2025 04:02:12 -0500
docs: lsp, options, promptbuf
Close #37630
Close #37682
Close #37762
Close #37785
Co-authored-by: Daniel Schmitt <d.schmitt@lansoftware.de>
Co-authored-by: Duane Hilton <duane9@gmail.com>
Co-authored-by: NeOzay <colpaert.benoit@gmail.com>
Co-authored-by: Yi Ming <ofseed@foxmail.com>
Co-authored-by: "Justin M. Keyes" <justinkz@gmail.com>
Diffstat:
19 files changed, 75 insertions(+), 49 deletions(-)
diff --git a/BUILD.md b/BUILD.md
@@ -70,6 +70,18 @@ make distclean
make deps
```
+### PUC Lua
+
+To build with "PUC Lua" instead of LuaJit:
+
+ make CMAKE_EXTRA_FLAGS="-DPREFER_LUA=ON" DEPS_CMAKE_FLAGS="-DUSE_BUNDLED_LUAJIT=OFF -DUSE_BUNDLED_LUA=ON"
+
+### Build options
+
+View the full list of CMake options defined in this project:
+
+ cmake -B build -LH
+
## Building on Windows
### Windows / MSVC
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -235,7 +235,7 @@ See [#549][549] for more details.
The Lua [`runtime/lua/vim/_core/`](./runtime/lua/vim/_core/) modules are
precompiled to bytecode, so changes won't be usable unless you (1) rebuild Nvim
or (2) start Nvim with `--luamod-dev` and `$VIMRUNTIME`. For example try adding
-a function to `runtime/lua/vim/editor.lua`, then:
+a function to `runtime/lua/vim/_core/editor.lua`, then:
```bash
VIMRUNTIME=./runtime ./build/bin/nvim --luamod-dev
diff --git a/MAINTAIN.md b/MAINTAIN.md
@@ -116,12 +116,7 @@ should be stated explicitly and publicly.
Third-party dependencies
------------------------
-For some dependencies we maintain temporary "forks", which are simply private
-branches with a few extra patches, while we wait for the upstream project to
-merge the patches. This is done instead of maintaining the patches as (fragile)
-CMake `PATCH_COMMAND` steps.
-
-These "bundled" dependencies can be updated by bumping their versions in `cmake.deps/deps.txt`.
+"Bundled" dependencies can be updated by bumping their versions in `cmake.deps/deps.txt`.
Some can be auto-bumped by `scripts/bump_deps.lua`.
* [LuaJIT](https://github.com/LuaJIT/LuaJIT)
@@ -136,9 +131,10 @@ Some can be auto-bumped by `scripts/bump_deps.lua`.
* [libiconv](https://ftp.gnu.org/pub/gnu/libiconv)
* [lua-compat](https://github.com/keplerproject/lua-compat-5.3)
* [tree-sitter](https://github.com/tree-sitter/tree-sitter)
-* [unibilium](https://github.com/neovim/unibilium)
- * The original project [was abandoned](https://github.com/neovim/neovim/issues/10302), so the [neovim/unibilium](https://github.com/neovim/unibilium) fork is considered "upstream" and is maintained on the `master` branch.
* [treesitter parsers](https://github.com/neovim/neovim/blob/7e97c773e3ba78fcddbb2a0b9b0d572c8210c83e/cmake.deps/deps.txt#L47-L62)
+* (Deprecated) [unibilium](https://github.com/neovim/unibilium)
+ * The original project [was abandoned](https://github.com/neovim/neovim/issues/10302), so the [neovim/unibilium](https://github.com/neovim/unibilium) fork is considered "upstream" and is maintained on the `master` branch.
+ * **Note:** unibilium is NOT required. See [BUILD.md](./BUILD.md#build-without-unibilium) to build Nvim without unibilium.
### Vendored dependencies
diff --git a/runtime/doc/channel.txt b/runtime/doc/channel.txt
@@ -189,7 +189,7 @@ normally only do that in a newly created buffer: >vim
The user can edit and input text at the end of the buffer. Pressing Enter in
the input section invokes the |prompt_setcallback()| callback, which is
typically expected to process the prompt and show results by appending to the
-buffer. To input multiline text, use Shift-<Enter> to add a new line without
+buffer. To input multiline text, use *Shift-<Enter>* to add a new line without
submitting the prompt, or just |put| or |paste| multiline text.
Only the section starting with the mark |':| of the buffer (after the prompt)
diff --git a/runtime/doc/dev.txt b/runtime/doc/dev.txt
@@ -365,7 +365,7 @@ Where possible, these patterns apply to _both_ Lua and the API:
If `opts` is omitted (or `nil`) it returns the current configuration.
- Example: See |vim.diagnostic.config()|.
- "Enable" ("toggle") interface and behavior:
- - `enable(…, nil)` and `enable(…, {buf=nil})` are synonyms and control the
+ - `enable(…, nil)` and `enable(…, {buf=nil})` are synonyms and control
the "global" enablement of a feature.
- `is_enabled(nil)` and `is_enabled({buf=nil})`, likewise, query the
global state of the feature.
diff --git a/runtime/doc/dev_arch.txt b/runtime/doc/dev_arch.txt
@@ -154,8 +154,8 @@ API
*dev-api-fast*
API functions and Vimscript "eval" functions may be marked as |api-fast| which
-means they are safe to call in Lua callbacks and other scenarios. A functions
-CANNOT be marked as "fast" if could trigger `os_breakcheck()`, which may
+means they are safe to call in Lua callbacks and other scenarios. A function
+CANNOT be marked as "fast" if it could trigger `os_breakcheck()`, which may
"yield" the current execution and start a new execution of code not expecting
this:
- accidentally recursing into a function not expecting this.
diff --git a/runtime/doc/dev_style.txt b/runtime/doc/dev_style.txt
@@ -6,7 +6,7 @@
Nvim style guide *dev-style*
-Style guidelines for developers working Nvim's source code.
+Style guidelines for developers working on Nvim's source code.
License: CC-By 3.0 https://creativecommons.org/licenses/by/3.0/
diff --git a/runtime/doc/dev_test.txt b/runtime/doc/dev_test.txt
@@ -349,17 +349,26 @@ GUIDELINES
files.
- `#define` constants must be rewritten `const` or `enum` so they can be
"visible" to the tests.
-- Use `pending()` to skip tests
- ([example](https://github.com/neovim/neovim/commit/5c1dc0fbe7388528875aff9d7b5055ad718014de#diff-bf80b24c724b0004e8418102f68b0679R18)).
- Do not silently skip the test with `if-else`. If a functional test depends on
- some external factor (e.g. the existence of `md5sum` on `$PATH`), _and_ you
- can't mock or fake the dependency, then skip the test via `pending()` if the
- external factor is missing. This ensures that the _total_ test-count
- (success + fail + error + pending) is the same in all environments.
+- Use `pending()` or `t.skip()` to skip tests.
+ - Example: https://github.com/neovim/neovim/commit/5c1dc0fbe7388528875aff9d7b5055ad718014de#diff-bf80b24c724b0004e8418102f68b0679R18
+ - Note: If a test is skipped because of a non-actionable reason, we don't
+ want it to appear in the "pending" list. Include "N/A" in the skip
+ description, then it won't be added to the "pending" list. For example, if
+ a test is skipped because it's running on a non-LuaJit system, including
+ it in the "pending" list is just noise. Thus, its pending reason should
+ say "N/A": >
+ pending('N/A: missing LuaJIT FFI')
+<
+ - Do not silently skip the test with `if-else`. If a functional test depends
+ on some external factor (e.g. the existence of `md5sum` on `$PATH`), _and_
+ you can't mock or fake the dependency, then skip the test via `pending()`
+ if the external factor is missing. This ensures that the _total_
+ test-count (success + fail + error + pending) is the same in all
+ environments.
- Note: `pending()` is ignored if it is missing an argument, unless it is
[contained in an `it()` block](https://github.com/neovim/neovim/blob/d21690a66e7eb5ebef18046c7a79ef898966d786/test/functional/ex_cmds/grep_spec.lua#L11).
Provide empty function argument if the `pending()` call is outside `it()`
- ([example](https://github.com/neovim/neovim/commit/5c1dc0fbe7388528875aff9d7b5055ad718014de#diff-bf80b24c724b0004e8418102f68b0679R18)).
+ Example: https://github.com/neovim/neovim/commit/5c1dc0fbe7388528875aff9d7b5055ad718014de#diff-bf80b24c724b0004e8418102f68b0679R18
WHERE TESTS GO
@@ -502,7 +511,7 @@ Number; !must be defined to function properly):
- `NVIM_TEST_TRACE_LEVEL` (U) (N): specifies unit tests tracing level:
- `0` disables tracing (the fastest, but you get no data if tests crash and
- there no core dump was generated),
+ no core dump was generated),
- `1` leaves only C function calls and returns in the trace (faster than
recording everything),
- `2` records all function calls, returns and executed Lua source lines.
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
@@ -56,7 +56,14 @@ Follow these steps to get LSP features:
a |lsp-root_markers| file so the workspace can be recognized.
5. Check that LSP is active ("attached") for the buffer: >vim
:checkhealth vim.lsp
-6. (Optional) Configure keymaps and autocommands to use LSP features.
+6. Please note that certain LSP features are disabled by default,
+ you may choose to enable them manually. See:
+ - |lsp-codelens|
+ - |lsp-document_color|
+ - |lsp-linked_editing_range|
+ - |lsp-inlay_hint|
+ - |lsp-inline_completion|
+7. (Optional) Configure keymaps and autocommands to use LSP features.
|lsp-attach|
==============================================================================
@@ -657,18 +664,16 @@ LspProgress *LspProgress*
Redraw the statusline whenever an LSP progress message arrives: >vim
autocmd LspProgress * redrawstatus
<
- Tell the parent terminal to indicate progress using a native progress
- indicator (requires a supporting terminal): >lua
- vim.api.nvim_create_autocmd('LspProgress', {
- callback = function(ev)
+ Emit a |progress-message| on LSP progress events: >lua
+ vim.api.nvim_create_autocmd('LspProgress', { buffer = buf, callback = function(ev)
local value = ev.data.params.value
- if value.kind == 'begin' then
- vim.api.nvim_ui_send('\027]9;4;1;0\027\\')
- elseif value.kind == 'end' then
- vim.api.nvim_ui_send('\027]9;4;0\027\\')
- elseif value.kind == 'report' then
- vim.api.nvim_ui_send(string.format('\027]9;4;1;%d\027\\', value.percentage or 0))
- end
+ vim.api.nvim_echo({ { value.message or 'done' } }, false, {
+ id = 'lsp',
+ kind = 'progress',
+ title = value.title,
+ status = value.kind ~= 'end' and 'running' or 'success',
+ percent = value.percentage,
+ })
end,
})
<
diff --git a/runtime/doc/lua-plugin.txt b/runtime/doc/lua-plugin.txt
@@ -142,7 +142,8 @@ initialization may be useful in specific cases:
Keep in mind that this approach requires users to call `setup` in order to
use your plugin, even if the default configuration is enough for them.
Consider carefully whether your plugin benefits from combined `setup()` pattern
-before adopting it.
+before adopting it. This article chronicles the history and tradeoffs of
+`setup()`: https://mrcjkb.dev/posts/2023-08-22-setup.html
NOTE: A well designed plugin has minimal impact on startup time. See also
|lua-plugin-lazy|.
diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt
@@ -1581,7 +1581,7 @@ supports incremental command preview:
preview_ns,
'Substitute',
{line1 + i - 2, start_idx - 1},
- {line1 + i - 2, end_idx},
+ {line1 + i - 2, end_idx}
)
-- Add lines and set highlights in the preview buffer
@@ -1601,7 +1601,7 @@ supports incremental command preview:
preview_ns,
'Substitute',
{preview_buf_line, #prefix + start_idx - 1},
- {preview_buf_line, #prefix + end_idx},
+ {preview_buf_line, #prefix + end_idx}
)
preview_buf_line = preview_buf_line + 1
end
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
@@ -41,7 +41,7 @@ TREESITTER
UI
-• `progress` attribute removed form |ui-messages| msg_show event
+• `progress` attribute removed from |ui-messages| msg_show event
VIMSCRIPT
@@ -255,7 +255,7 @@ LSP
https://microsoft.github.io/language-server-protocol/specification/#textDocument_colorPresentation
• The `textDocument/diagnostic` request now includes the previous id in its
parameters.
-• |vim.lsp.enable()| start/stops clients as necessary. And detaches
+• |vim.lsp.enable()| start/stops clients as necessary and detaches
non-applicable LSP clients.
• |vim.lsp.is_enabled()| checks if a LSP config is enabled (without
"resolving" it).
@@ -314,7 +314,7 @@ LUA
• |vim.hl.range()| now allows multiple timed highlights.
• |vim.tbl_extend()| and |vim.tbl_deep_extend()| now accept a function behavior argument.
• |vim.fs.root()| can define "equal priority" via nested lists.
-• |vim.version.range()| output can be converted to human-readable string with |tostring()|.
+• |vim.version.range()| output can be converted to a human-readable string with |tostring()|.
• |vim.version.intersect()| computes intersection of two version ranges.
• |Iter:take()| and |Iter:skip()| now optionally accept predicates.
• Built-in plugin manager |vim.pack|
@@ -359,17 +359,17 @@ PERFORMANCE
additional constraints for improved correctness and resistance to
backtracking edge cases.
• |i_CTRL-R| inserts named/clipboard registers literally, 10x speedup.
+• LSP `textDocument/semanticTokens/range` is supported, which requests tokens
+ for the viewport (visible screen) only.
PLUGINS
• Customize :checkhealth by handling a `FileType checkhealth` event.
|health-usage|
-
• Simplify Python provider setup to a single step: `uv tool install pynvim`
Nvim will detect the plugin's location without user configuration, even if
unrelated Python virtual environments are activated.
|provider-python|
-
• |:checkhealth| now checks for an available |vim.ui.open()| handler.
STARTUP
@@ -407,6 +407,7 @@ UI
• "Error detected while processing:" changed to "Error in:".
• "Error executing Lua:" changed to "Lua:".
• 'busy' status is shown in default statusline with symbol ◐
+• Cursor shape indicates when it is behind an unfocused floating window.
• Improved LSP signature help rendering.
• Multigrid UIs can call nvim_input_mouse with grid 0 to let Nvim decide the grid.
diff --git a/runtime/lua/vim/health/health.lua b/runtime/lua/vim/health/health.lua
@@ -621,6 +621,8 @@ local function check_sysinfo()
[[
## Problem
+ Describe the problem (concisely).
+
## Steps to reproduce
```
diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua
@@ -198,7 +198,7 @@ end
--- provide the root dir, or LSP will not be activated for the buffer. Thus a `root_dir()` function
--- can dynamically decide per-buffer whether to activate (or skip) LSP.
--- See example at |vim.lsp.enable()|.
---- @field root_dir? string|fun(bufnr: integer, on_dir:fun(root_dir?:string))
+--- @field root_dir? string|fun(bufnr: integer, on_dir:fun(root_dir?:string)) #
---
--- [lsp-root_markers]()
--- Filename(s) (".git/", "package.json", …) used to decide the workspace root. Unused if `root_dir`
diff --git a/runtime/scripts/optwin.lua b/runtime/scripts/optwin.lua
@@ -29,7 +29,6 @@ local options_list = {
{ 'autochdir', N_ 'change to directory of file in buffer' },
{ 'wrapscan', N_ 'search commands wrap around the end of the buffer' },
{ 'incsearch', N_ 'show match for partly typed search command' },
- { 'magic', N_ 'change the way backslashes are used in search patterns' },
{ 'regexpengine', N_ 'select the default regexp engine used' },
{ 'ignorecase', N_ 'ignore case when using a search pattern' },
{ 'smartcase', N_ "override 'ignorecase' when pattern has upper case characters" },
@@ -438,7 +437,6 @@ local options_list = {
{ 'eventignorewin', N_ 'list of autocommand events which are to be ignored in a window' },
{ 'loadplugins', N_ 'load plugin scripts when starting up' },
{ 'exrc', N_ 'enable reading .vimrc/.exrc/.gvimrc in the current directory' },
- { 'gdefault', N_ 'use the \'g\' flag for ":substitute"' },
{ 'maxfuncdepth', N_ 'maximum depth of function calls' },
{ 'sessionoptions', N_ 'list of words that specifies what to put in a session file' },
{ 'viewoptions', N_ 'list of words that specifies what to save for :mkview' },
diff --git a/src/nvim/message.h b/src/nvim/message.h
@@ -37,7 +37,7 @@ EXTERN bool msg_ext_skip_flush INIT( = false);
EXTERN bool msg_ext_append INIT( = false);
/// Set to true when previous message should be overwritten.
EXTERN bool msg_ext_overwrite INIT( = false);
-/// Set to true to avoid setting "verbose" kind for last set messages.
+/// Set to true to avoid setting "verbose" kind for "last set" messages.
EXTERN bool msg_ext_skip_verbose INIT( = false);
/// allocated grid for messages. Used unless ext_messages is active.
diff --git a/test/functional/lua/fs_spec.lua b/test/functional/lua/fs_spec.lua
@@ -731,7 +731,7 @@ describe('vim.fs', function()
vim.uv.fs_rmdir('Xtest_fs-rm')
end)
- it('works with symlink', function()
+ it('symlink', function()
-- File
vim.uv.fs_symlink('Xtest_fs-rm/file-to-link', 'Xtest_fs-rm/file-as-link')
vim.fs.rm('Xtest_fs-rm/file-as-link')
diff --git a/test/functional/lua/ui_spec.lua b/test/functional/lua/ui_spec.lua
@@ -109,7 +109,7 @@ describe('vim.ui', function()
eq(true, exec_lua('return (nil == result)'))
end)
- it('can return opts.cacelreturn when aborted with ESC with cancelreturn opt #18144', function()
+ it('can return opts.cancelreturn when aborted with ESC with cancelreturn opt #18144', function()
feed(':lua result = "on_confirm not called"<cr>')
feed(':lua vim.ui.input({ cancelreturn = "CANCEL" }, function(input) result = input end)<cr>')
feed('Inputted Text<esc>')
diff --git a/test/functional/plugin/optwin_spec.lua b/test/functional/plugin/optwin_spec.lua
@@ -68,10 +68,12 @@ describe('optwin.lua', function()
'secure',
'prompt',
'edcompatible',
+ 'gdefault',
'guioptions',
'guitablabel',
'guitabtooltip',
'insertmode',
+ 'magic',
'mouseshape',
'imcmdline',
'imdisable',
