News

Nvim :help pages, generated from source using the tree-sitter-vimdoc parser.

Notable changes since Nvim 0.12

For changes in the previous release, see news-0.12.

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

EVENTS

todo

EXPERIMENTS

todo

LSP

todo

LUA

vim.pos, vim.range always require the buf parameter.

range.cursor() and range.to_cursor() are removed. Use range.mark() and range.to_mark() instead.

pos.to_cursor() returns a (row, col) tuple instead of returning them as separate values.

DIAGNOSTICS

todo

OPTIONS

todo

TREESITTER

todo

UI

todo

VIMSCRIPT

todo

BREAKING CHANGES news-breaking

These changes may require adaptations in your config or plugins.

API

nvim_create_autocmd(), nvim_exec_autocmds() and nvim_clear_autocmds() no longer treat an empty non-nil pattern as nil.

nvim_clear_autocmds() no longer treats an empty array event as nil.

vim.o, vim.opt, and nvim_set_option_value() expand ~ and environment variables (expand-env).

DIAGNOSTICS

vim.diagnostic.Opts.Status.format no longer accepts the table mapping from severity to text. Use vim.diagnostic.Opts.Signs.text instead.

current_line property of vim.diagnostic.Opts.VirtualLines and vim.diagnostic.Opts.VirtualText is now applied on CursorHold event. Make sure your 'updatetime' is reasonable.

EDITOR

On Windows, the trust db now stores paths with "/" slashes. This means the trust store will be reset (one time).

stdpath("log") moved to stdpath("state")/logs.

cmdwin (q:, q/, q?, c_CTRL-F):

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.

EVENTS

BufModifiedSet has been removed. Use the OptionSet event with pattern "modified" instead.

ui-messages msg_show.bufwrite and msg_show.completion messages are now msg_show.progress events.

LSP

vim.lsp.ClientConfig.cmd given as a string array now uses vim.lsp.ClientConfig.root_dir as its default process working directory.

client.attached_buffers[buf] now stores languageId string (was boolean).

LUA

"standalone" Lua interpreter mode nvim -ll was removed. Use -l script mode instead.

vim.opt no longer supports chaining multiple infix operators (e.g. vim.opt.wildignore + '*.o' + '*.obj'). Instead, use tables: vim.opt.wildignore + {'*.o', '*.obj'}

OPTIONS

The 'statusline' %= item is no longer ignored in item groups. It applies to the containing item group and its minwid. An %< item inside an item group now only applies to the containing group and its maxwid. Therefore, multiple %< can now be effective. The default truncation of item groups is now at the first contained item. To restore the previous truncation from the left, add a %< to the start. The same applies to 'rulerformat', 'statuscolumn', 'tabline', 'winbar', 'titlestring', and 'iconstring'.

PLUGINS

todo

TREESITTER

todo

NEW FEATURES news-features

The following new features were added.

API

nvim_buf_call() and nvim_win_call() now preserve multiple return values.

nvim_set_hl() supports "font" key.

nvim_open_win() zindex controls whether the UI will use a dimmed cursor shape when an unfocused float is on top of the cursor.

nvim_echo() distinguishes zero percent from omitted percent for Progress events.

nvim_create_user_command() accepts desc for Vimscript commands.

Support for tabpage-local options ('cmdheight'):

gettabvar()

gettabwinvar()

nvim_get_option_info2()

nvim_get_option_value()

nvim_set_option_value()

nvim_buf_set_extmark() virt_lines_overflow accepts "wrap" to enable wrapping onto extra rows and "auto" which enables horizontal scrolling when 'nowrap' is set and wrapping when 'wrap' is set.

nvim_set_option_value() accepts a new operation field to modify the existing option value.

nvim_set_option_value() returns the new option value.

BUILD

Building using "zig build" requires zig 0.16.x.

zig build: "-Dcross" option was removed. Often cross-compilation is now detected, so e.g. from a linux host:

zig build -Dtarget=aarch64-macos

will automatically compile a host Lua for use during build.

zig build: The new "-Dhost={target_string}" option can be used to override the used host. Use "-Dhost=native" to force cross-compiling or "-Dhost=" (empty string) to assume that target binaries can run on the host during the build process (e.g. if target is x86 on a x86_64 system, or if emulation set up with binfmt or similar).

DEFAULTS

todo

DIAGNOSTICS

vim.diagnostic.status() uses the severity names defined by the signs field of vim.diagnostic.config(), if any.

virtual_lines.overflow in vim.diagnostic.config() controls how virtual lines wider than the window are displayed.

EDITOR

:command-completion-customlist can return a list of dictionaries with kind/menu/info/abbr for the popup menu.

cmdwin (q:, q/, q?, c_CTRL-F) is implemented as a "normal" buffer+window instead of a nested-state modal loop:

'inccommand' works in cmdwin!

API calls (e.g. nvim_buf_delete()) that previously failed with "E11: Invalid in command-line window" while cmdwin was open, now work normally. Async plugins no longer need special CmdwinLeave workarounds.

Removed most cmdwin-specific E11 guards, except for window navigation.

The cmdwin-char is shown via 'statuscolumn'.

gf and <cfile> support file://… URIs.

:log opens log files.

ZR restarts Nvim (:restart).

:uptime displays uptime.

:packupdate and :packdel for managing vim.pack.

'scrollback' is now also valid in prompt-buffer buffers to limit the number of history lines kept above the prompt.

v_al and v_il text objects select the whole buffer and the current line without leading or trailing white space.

'autoread' uses file system watchers to detect external changes in real-time, instead of only on FocusGained/|:checktime|.

During complete()-triggered completion, CTRL-N and CTRL-P are now subject to insert-mode mappings.

Multi-byte characters, translated by 'langmap', now invoke correct mappings. Example:

set langmap=õ]

Typing õõ in Normal-mode now invokes a mapping bound to ]].

EVENTS

:delmarks now triggers the MarkSet autocommand with line==col==0, same as nvim_buf_del_mark()

SessionWritePre event emits just before :mksession.

TextPutPre and TextPutPost are triggered before/after putting text.

TabMoved is triggered when tabs are reordered.

HIGHLIGHTS

Dimmed for text that should be de-emphasized.

vim.hl.hl_op() highlights text regions for TextYankPost and TextPutPost events. It replaces the now deprecated vim.hl.on_yank().

LSP

LSP capabilities:

Completion supports CompletionItem.preselect if 'completeopt' has "preselect". https://microsoft.github.io/language-server-protocol/specification/#completionClientCapabilities

textDocument/foldingRange vim.lsp.foldtext() highlights collapsed text. https://microsoft.github.io/language-server-protocol/specification/#textDocument_foldingRange

:checkhealth vim.lsp highlights the "current buffer".

vim.lsp.buf.declaration(), vim.lsp.buf.definition(), vim.lsp.buf.type_definition(), and vim.lsp.buf.implementation() now follows 'switchbuf'.

vim.lsp.buf.declaration(), vim.lsp.buf.definition(), vim.lsp.buf.type_definition(), and vim.lsp.buf.implementation() now supports passing arbitrary positions.

Support for nested snippets.

LUA

vim.ui.img can display images. Use :checkhealth img to confirm your terminal supports it.

vim.net.request() can specify custom headers by passing opts.headers.

vim.net.request() can now accept method param overload for multiple HTTP methods.

writefile() treats Lua strings as "blob", so it can be used to write binary data.

vim.filetype.inspect() returns a copy of the internal tables used for filetype detection.

Added __eq metamethod to vim.VersionRange. 2 distinct but representing the same range instances now compare equal.

Documentation for vim.fn now points to preferred Lua alternatives when available.

vim.list.unique() and vim.list.bisect() now support passing a string as a shorthand of a key

vim.isnil() tests if a value is nil or vim.NIL.

vim.nonnil() returns the first argument which is not nil.

vim.npcall() calls the function fn in protected-mode like pcall(), but returns nil on error.

vim.pos can now convert between positions and buffer offsets.

vim.pos and vim.range can now convert between mark positions.

vim.ui.input() now allows setting input scope.

vim.log provides a logging interface.

vim.pack.get() output includes revision of a pending update.

vim.pack.get() can fetch new updates before computing the output.

vim.o now accepts table style values for assignment.

OPTIONS

'ttyfast' can be disabled during startup by setting $NVIM_NOTTYFAST.

'scrolloffpad' allows vertically centering cursor at the end of file.

'shortmess' flag shm-u silences undo/redo messages.

'statusline' supports stl-%0{ to insert the expression result verbatim. The %= item is supported within item groups to separate alignment sections within the containing group until its minwid is reached. The truncation of an item group to its maxwid can be controlled with the %< item. The same applies to 'rulerformat', 'statuscolumn', 'tabline', 'winbar', 'titlestring', and 'iconstring'.

'winpinned' prevents window from closing unless specifically targeted.

PERFORMANCE

treesitter-highlight performance on large injection-heavy files improves by 50% to 100% by reusing edited child-tree ranges.

Nvim architecture allows pure-Lua implementations of some vim.fn functions, which skips the Vimscript <=> Lua "bridge" (no data conversion/marshalling) entirely, if the vim.fn function is called from Lua.

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.

PLUGINS

provider: add bun support for Node.js plugins

STARTUP

todo

TERMINAL

todo

TREESITTER

v_]N v_[N expand selection to sibling treesitter node.

treesitter-highlight-conceal can be removed by adding a @noconceal capture.

vim.treesitter.select() starts or adjusts a visual selection at cursor, based on tree nodes.

TUI

The TUI will re-query the terminal's background color when resuming from a suspended state, and Nvim will update 'background' accordingly.

User can override the builtin "terminfo" via $NVIM_TERMDEFS. This is similar to Vim's t_xx options.

UI

:checkhealth shows filewatcher info in the Performance section.

These builtin "picker" menus delegate to vim.ui.select():

:browse oldfiles

:recover

:tselect

z= (spell suggest)

VIMSCRIPT

v:exitreason is set before QuitPre.

v:startreason differentiates between restart and normal start.

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

CHANGED FEATURES news-changed

These existing features changed their behavior.

nvim_exec_autocmds({buf=…}) runs in the context of the target buffer.

OptionSet is no longer triggered during startup by automatic 'background' detection.

Editing a local directory now shows its contents in a filetype=directory buffer. See dir.

:Open with no arguments uses the current file.

The "buffer" key was renamed to "buf" in these functions (but the old name "buffer" is still accepted, for backwards compatibility):

nvim_clear_autocmds()

nvim_create_autocmd()

nvim_exec_autocmds()

nvim_get_autocmds()

vim.keymap.set() and vim.keymap.del() accept a list of strings for lhs.

'statuscolumn' click function labels can be different across rows. v:virtnum and v:lnum are available during the click function callback.

REMOVED FEATURES news-removed

These deprecated features were removed.

vim.lsp.buf.declaration(), vim.lsp.buf.definition(), vim.lsp.buf.type_definition(), and vim.lsp.buf.implementation() no longer accept the reuse_win option.

DEPRECATIONS news-deprecations

See deprecated-0.13.