News
Nvim :help pages, generated
from source
using the tree-sitter-vimdoc parser.
Notable changes since Nvim 0.10
For changes in the previous release, see
news-0.10.
====== Remove this section before release. ======
The following changes to UNRELEASED features were made during the development
cycle (Nvim HEAD, the "master" branch).
EXPERIMENTS
Removed vim.loader.disable(). Use vim.loader.enable(false) instead.
LSP
vim.lsp.buf.document_symbol() uses the
location-list by default. Use
vim.lsp.buf.document_symbol({ loclist = false }) to use the
quickfix
list.
OPTIONS
The
msghistory option has been removed in favor of
'messagesopt'.
TREESITTER
These changes may require adaptations in your config or plugins.
API
vim.rpcnotify(0) and rpcnotify(0) broadcast to ALL channels. Previously
they would "multicast" only to subscribed channels (controlled by
nvim_subscribe()). Plugins and clients that want "multicast" behavior must
now maintain their own list of channels.
In the future,
vim.rpcnotify() may accept a list of channels, if there
is demand for this use-case.
"Dictionary" was renamed to "Dict" internally and in the RPC
api-metadata.
This is not expected to break clients because there are no known clients
that actually use the
return_type field or the parameter type names
reported by
--api-info or
nvim_get_api_info().
Renamed nvim__id_dictionary (unsupported/experimental API) to
nvim__id_dict.
BUILD
On Windows, only building with the UCRT runtime is supported.
Translations are turned off by default. Enable by building Nvim with the
CMake flag ENABLE_TRANSLATIONS=ON.
DIAGNOSTICS
The "underline" diagnostics handler sorts diagnostics by severity when using
the "severity_sort" option.
Diagnostics are filtered by severity before being passed to a diagnostic
handler
diagnostic-handlers.
The "virtual_text" handler is disabled by default. Enable with
vim.diagnostic.config({ virtual_text = true })
EDITOR
The order in which signs are placed was changed. Higher priority signs will
now appear left of lower priority signs.
hl-CurSearch now behaves the same as Vim and no longer updates on every
cursor movement.
Moving in the buffer list using
:bnext and similar commands behaves as
documented and skips help buffers if run from a non-help buffer, otherwise
it moves to another help buffer.
Bells from a
terminal buffer are now silent by default, unless
'belloff'
option doesn't contain "term" or "all".
EVENTS
New/enhanced arguments in these existing UI events:
cmdline_hide: abort argument indicating if the cmdline was aborted.
cmdline_show:
Prompts that were previously emitted as msg_show events, are now routed
through cmdline_show.
hl_id argument to highlight the prompt text.
msg_show:
history argument indicating if the message was added to the history.
new message kinds: "bufwrite", "completion", "list_cmd", "lua_print",
"search_cmd", "shell_out/err/ret", "undo", "verbose", wildlist".
HIGHLIGHTS
TermCursorNC is removed and no longer supported. Unfocused terminals no
longer have a cursor.
LSP
LUA
OPTIONS
:setlocal {option}< copies the global value to the local value for number
and boolean
global-local options instead of removing the local value.
PLUGINS
TREESITTER
Query:iter_matches() correctly returns all matching nodes in a match
instead of only the last node. This means that the returned table maps
capture IDs to a list of nodes that need to be iterated over. For
backwards compatibility, an option
all=false (only return the last
matching node) is provided that will be removed in a future release.
TUI
VIMSCRIPT
v:msgpack_types has the type "binary" removed.
msgpackparse() no longer
treats BIN, STR and FIXSTR as separate types. Any of these is returned as a
string if possible, or a
blob if the value contained embedded NUL:s.
The following new features were added.
API
Improved API "meta" docstrings and :help documentation.
nvim_echo() err field to print error messages and
chunks accepts
highlight group IDs.
nvim_open_win() supports a
mouse field that allows configuring mouse
interaction with the window separately from
focusable field.
conceal_lines field to conceal an entire line.
hl_group field can be an array of layered groups.
virt_text_pos field accepts value eol_right_align to allow for right
aligned text that truncates before covering up buffer text.
virt_lines_overflow field accepts value
scroll to enable horizontal
scrolling for virtual lines with
'nowrap'.
vim.hl.range() now has a optional
timeout field which allows for a timed highlight
DEFAULTS
Highlighting:
Improved styling of :checkhealth and :help buffers.
Mappings:
Mouse
popup-menu includes an "Open in web browser" item when you right-click
on a URL.
Mouse
popup-menu includes a "Go to definition" item when LSP is active
in the buffer.
Mouse
popup-menu includes "Show Diagnostics", "Show All Diagnostics" and
"Configure Diagnostics" items when there are diagnostics in the buffer.
[D-default and
]D-default jump to the first and last diagnostic in the
current buffer, respectively.
Mappings inspired by Tim Pope's vim-unimpaired:
[[ and
]] in Normal mode jump between shell prompts for shells which emit
OSC 133 sequences ("shell integration" or "semantic prompts").
Snippet:
<Tab> in Insert and Select mode maps to vim.snippet.jump({ direction = 1 })
when a snippet is active and jumpable forwards.
<S-Tab> in Insert and Select mode maps to vim.snippet.jump({ direction = -1 })
when a snippet is active and jumpable backwards.
DIAGNOSTICS
A "virtual_lines" diagnostic handler was added to render diagnostics using
virtual lines below the respective code.
The "virtual_text" diagnostic handler accepts a current_line option to
only show virtual text at the cursor's line.
EDITOR
Use
g== in :help docs to execute Lua and Vimscript code examples.
Redoing a large paste is significantly faster and ignores
'autoindent'.
Replaying a macro with
@ also replays pasted text.
On Windows, filename arguments on the command-line prefixed with "~\" or
"~/" are now expanded to the user's profile directory, not a relative path
to a literal "~" directory.
gO now works in
help,
checkhealth, and
markdown buffers.
Jump between sections in help and checkhealth buffers with [[ and
]].
EVENTS
CompleteDone now sets the
reason key in
v:event which specifies the reason
for completion being done.
vim.on_key() callbacks can consume the key by returning an empty string.
LSP
:checkhealth vim.lsp displays the server version (if available).
Completion side effects (including snippet expansion, execution of commands
and application of additional text edits) is now built-in.
vim.lsp.buf.format() now supports passing a list of ranges
via the
range parameter (this requires support for the
textDocument/rangesFormatting request).
The client now supports 'utf-8' and 'utf-32' position encodings.
vim.lsp.config() has been added to define default configurations for
servers. In addition, configurations can be specified in
lsp/<name>.lua.
The textDocument/completion request now includes the completion context in
its parameters.
LUA
Command-line completions for: vim.g, vim.t, vim.w, vim.b, vim.v,
vim.o, vim.wo, vim.bo, vim.opt, vim.opt_local, vim.opt_global,
and vim.fn.
vim.validate() now has a new signature which uses less tables,
is more performant and easier to read.
OPTIONS
'tabclose' controls which tab page to focus when closing a tab page.
Significantly reduced redraw time for long lines with treesitter
highlighting.
LSP diagnostics and inlay hints are de-duplicated (new requests cancel
inflight requests). This greatly improves performance with slow LSP servers.
Treesitter highlighting is now asynchronous. To force synchronous parsing,
use vim.g._ts_force_sync_parsing = true.
Treesitter folding is now calculated asynchronously.
Treesitter injection query iteration is now asynchronous, making edits in
large buffers with combined injections much quicker.
10x reduction in blocking time when attaching an LSP to a large buffer.
PLUGINS
EditorConfig
spelling_language property is now supported.
Commenting
'commentstring' values can now be specified in a Treesitter capture's
bo.commentstring metadata field, providing finer grained support for
languages like
JSX.
STARTUP
-es ("script mode") disables shada by default.
TERMINAL
The
terminal now understands the OSC 52 escape sequence to write to the
system clipboard (copy). Querying with OSC 52 (paste) is not supported.
The terminal buffer now supports reflow (wrapped lines adapt when the buffer
is resized horizontally).
Note: Lines that are not visible and kept in
'scrollback' are not reflown.
The
terminal now supports OSC 8 escape sequences and will display
hyperlinks in supporting host terminals.
The
terminal now uses the actual cursor, rather than a "virtual" cursor.
This means that escape codes sent by applications running in a terminal
buffer can change the cursor shape and visibility. However, it also
means that the
TermCursorNC highlight group is no longer supported: an
unfocused terminal window will have no cursor at all (so there is nothing to
highlight).
The
terminal will send theme update notifications when
'background' is
changed and DEC mode 2031 is enabled.
The
terminal has experimental support for the Kitty keyboard protocol
(sometimes called "CSI u" key encoding). Only the "Disambiguate escape
codes" mode is currently supported.
The
terminal emits a
TermRequest autocommand event when the child process
emits an APC control sequence.
TermRequest has a "cursor" field in its
event-data indicating the
cursor position when the sequence was received.
TREESITTER
vim.treesitter.get_node() now takes an option
include_anonymous, default
false, which allows it to return anonymous nodes as well as named nodes.
LanguageTree:parse() optionally supports asynchronous invocation, which is
activated by passing the
on_parse callback parameter.
Bundled markdown highlight queries use conceal_lines metadata to conceal
code block fence lines vertically.
TUI
The builtin UI declares info
nvim_set_client_info() on its channel. See
startup-tui. To see the current UI info, try this:
:lua =vim.api.nvim_get_chan_info(vim.api.nvim_list_uis()[1].chan)
log messages written by the builtin UI client (TUI,
--remote-ui) are
now prefixed with "ui" instead of "?".
The TUI will re-query the terminal's background color when a theme update
notification is received and Nvim will update
'background' accordingly.
UI
:detach the current UI, let the Nvim server continue running as a background
process. Works with the builtin TUI, and all GUIs.
vim.ui.open() (by default bound to
gx) accepts an
opt.cmd parameter
which controls the tool used to open the given path or URL. If you want to
globally set this, you can override vim.ui.open using the same approach
described at
vim.paste().
ui-messages content chunks now also contain the highlight group ID.
VIMSCRIPT
getchar() and
getcharstr() have optional
{opts} Dict argument to control:
cursor behavior, return type, and whether to simplify the returned key.
These existing features changed their behavior.
'scrollbind' now works properly with buffers that contain virtual lines.
Scrollbind works by aligning to a target top line of each window in a tab
page. Previously this was done by calculating the difference between the old
top line and the target top line, and scrolling by that amount. Now the
top lines are calculated using screen line numbers which take virtual lines
into account.
The implementation of grapheme clusters (or combining chars
mbyte-combining)
was upgraded to closely follow extended grapheme clusters as defined by UAX#29
in the unicode standard. Noteworthily, this enables proper display of many
more emoji characters than before, including those encoded with multiple
emoji codepoints combined with ZWJ (zero width joiner) codepoints.
This also applies to :terminal output, where width of cells will be calculated
using the upgraded implementation.
vim.on_key() callbacks won't be invoked recursively when a callback itself
consumes input.
"q" in man pages now uses
CTRL-W_q instead of
CTRL-W_c to close the
current window, and it no longer throws
E444 when there is only one window
on the screen. Global variable
vim.g.pager is removed.
Default
'titlestring' is now implemented with
'statusline' "%" format items.
This means the default, empty value is essentially an alias to:
%t%(\ %M%)%(\ \(%{expand(\"%:~:h\")}\)%)%a\ -\ Nvim. This is only an
implementation simplification, not a behavior change.
These deprecated features were removed.