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.

BREAKING CHANGES IN HEAD OR EXPERIMENTAL news-breaking-dev

====== 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.

OPTIONS

'jumpoptions' flag "unload" has been renamed to "clean".
The msghistory option has been removed in favor of 'messagesopt'.

BREAKING CHANGES news-breaking

These changes may require adaptations in your config or plugins.

API

Improved API "meta" docstrings and :help documentation.
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().
nvim_open_win() supports a mouse field that allows configuring mouse interaction with the window separately from focusable field.
Renamed nvim__id_dictionary (unsupported/experimental API) to nvim__id_dict.

BUILD

On Windows, only building with the UCRT runtime is supported.

DEFAULTS

]d-default and [d-default accept a count.
[D-default and ]D-default jump to the first and last diagnostic in the current buffer, respectively.
'number', 'relativenumber', 'signcolumn', and 'foldcolumn' are disabled in terminal buffers. See terminal-config for an example of changing these defaults.
vim.json.encode() no longer escapes the forward slash symbol by default

DIAGNOSTICS

vim.diagnostic.config() accepts a "jump" table to specify defaults for vim.diagnostic.jump().
The "underline" diagnostics handler sorts diagnostics by severity when using the "severity_sort" option.

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

vim.ui_attach() callbacks for ui-messages msg_show events are executed in api-fast context.

LSP

Improved rendering of LSP hover docs. K-lsp-default
vim.lsp.completion.enable() gained the convert callback which enables customizing the transformation of an LSP CompletionItem to complete-items.
vim.lsp.diagnostic.from() can be used to convert a list of vim.Diagnostic objects into their LSP diagnostic representation.
vim.lsp.buf.references(), vim.lsp.buf.declaration(), vim.lsp.buf.definition(), vim.lsp.buf.type_definition(), vim.lsp.buf.implementation() and vim.lsp.buf.hover() now support merging the results of multiple clients but no longer trigger the global handlers from vim.lsp.handlers
vim.lsp.buf.typehierarchy() now passes the correct params for each client request.
vim.lsp.diagnostic.on_publish_diagnostics() and vim.lsp.diagnostic.on_diagnostic() no longer accept a config parameter and can no longer be configured with vim.lsp.with(). Instead use:
vim.diagnostic.config(config, vim.lsp.diagnostic.get_namespace(client_id))

LUA

API functions now consistently return an empty dictionary as vim.empty_dict(). Earlier, a lua-special-tbl was sometimes used.
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.

OPTIONS

The 'statuscolumn' %l item can now be used as a number column segment that changes according to related options. It takes care of alignment, 'number', 'relativenumber' and 'signcolumn' set to "number". The now redundant %r item is no longer treated specially for 'statuscolumn'.
:set {option}< removes the local value for all global-local options instead of just string global-local options.
:setlocal {option}< copies the global value to the local value for number and boolean global-local options instead of removing the local value.
Setting hidden-options now gives an error. In particular, setting 'noshellslash' is now only allowed on Windows.

PLUGINS

TODO

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.
vim.treesitter.language.get_filetypes() always includes the {language} argument in addition to explicitly registered filetypes.
vim.treesitter.language.get_lang() falls back to the {filetype} argument if no languages are explicitly registered.
vim.treesitter.language.add() returns true if a parser was loaded successfully and nil,errmsg otherwise instead of throwing an error.
New TSNode:child_with_descendant(), which is nearly identical to TSNode:child_containing_descendant() except that it can return the descendant itself.

TUI

TODO

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.

NEW FEATURES news-features

The following new features were added.

API

nvim__ns_set() can set properties for a namespace
vim.json.encode() has an option to enable forward slash escaping

DEFAULTS

Highlighting:
Improved styling of :checkhealth and :help buffers.
Mappings:
grn in Normal mode maps to vim.lsp.buf.rename()
grr in Normal mode maps to vim.lsp.buf.references()
gri in Normal mode maps to vim.lsp.buf.implementation()
gO in Normal mode maps to vim.lsp.buf.document_symbol()
gra in Normal and Visual mode maps to vim.lsp.buf.code_action()
CTRL-S in Insert and Select mode maps to vim.lsp.buf.signature_help()
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.
Mappings inspired by Tim Pope's vim-unimpaired:
[q, ]q, [Q, ]Q, [CTRL-Q, ]CTRL-Q navigate through the quickfix list
[l, ]l, [L, ]L, [CTRL-L, ]CTRL-L navigate through the location-list
[t, ]t, [T, ]T, [CTRL-T, ]CTRL-T navigate through the tag-matchlist
[a, ]a, [A, ]A navigate through the argument-list
[b, ]b, [B, ]B navigate through the buffer-list
[<Space>, ]<Space> add an empty line above and below the cursor
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.

EDITOR

Improved paste handling for redo (dot-repeat) and macros (recording):
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.
hl-PmenuMatch and hl-PmenuMatchSel show matched text in completion popup.

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

Completion side effects (including snippet expansion, execution of commands and application of additional text edits) is now built-in.
vim.lsp.util.locations_to_items() sets end_col and end_lnum fields.
vim.lsp.buf.format() now supports passing a list of ranges via the range parameter (this requires support for the textDocument/rangesFormatting request).
vim.lsp.buf.code_action() actions show client name when there are multiple clients.
vim.lsp.buf.signature_help() can now cycle through different signatures using <C-s> and also support multiple clients.
The client now supports 'utf-8' and 'utf-32' position encodings.
vim.lsp.buf.hover() now highlights hover ranges using the hl-LspReferenceTarget highlight group.
Functions in vim.lsp.Client can now be called as methods.
vim.lsp.config() has been added to define default configurations for servers. In addition, configurations can be specified in lsp/<name>.lua.
vim.lsp.enable() has been added to enable servers.

LUA

vim.fs.rm() can delete files and directories.
vim.validate() now has a new signature which uses less tables, is more performant and easier to read.
vim.str_byteindex() and vim.str_utfindex() gained overload signatures supporting two new parameters, encoding and strict_indexing.

OPTIONS

'completeopt' flag "fuzzy" enables fuzzy-matching during ins-completion.
'messagesopt' configures :messages and hit-enter prompt.
'tabclose' controls which tab page to focus when closing a tab page.

PERFORMANCE

Significantly reduced redraw time for long lines with treesitter highlighting.

PLUGINS

EditorConfig
spelling_language property is now supported.

STARTUP

Nvim will fail if the --listen or $NVIM_LISTEN_ADDRESS address is invalid, instead of silently skipping an invalid address.

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.
hl-StatusLineTerm and hl-StatusLineTermNC define highlights for the status line in terminal windows.
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.

TREESITTER

LanguageTree:node_for_range() gets anonymous and named nodes for a range
vim.treesitter.get_node() now takes an option include_anonymous, default false, which allows it to return anonymous nodes as well as named nodes.
treesitter-directive-trim! can trim all whitespace (not just empty lines) from both sides of a node.
vim.treesitter.get_captures_at_pos() now returns the id of each capture

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

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().
vim.ui.open() now supports [lemonade](https://github.com/lemonade-command/lemonade) as an option for opening urls/files. This is handy if you are in an ssh connection and use lemonade.
The ins-completion-menu now supports cascading highlight styles. hl-PmenuSel and hl-PmenuMatch both inherit from hl-Pmenu, and hl-PmenuMatchSel inherits highlights from both hl-PmenuSel and hl-PmenuMatch.
vim.diagnostic.setqflist() updates an existing quickfix list with the given title if found
ui-messages content chunks now also contain the highlight group ID.

CHANGED FEATURES news-changed

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.
Text in the 'statusline', 'tabline', and 'winbar' now inherits highlights from the respective hl-StatusLine, hl-TabLine, and hl-WinBar highlight groups.
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.

REMOVED FEATURES news-removed

These deprecated features were removed.
N/A

DEPRECATIONS news-deprecations

Main
Commands index
Quick reference