Vim_diff
Nvim:help pages,generated fromsource using thetree-sitter-vimdoc parser.
Differences between Nvim and Vim
Nvim differs from Vim in many ways, although editor and Vimscript (notVim9script) features are mostly identical. This document is a complete andcentralized reference of the differences.
Use
$XDG_CONFIG_HOME/nvim/init.vim instead of
.vimrc for your
config.
Use$XDG_CONFIG_HOME/nvim instead of.vim to store configuration files.
Use
$XDG_STATE_HOME/nvim/shada/main.shada instead of
.viminfo for persistent session information.
shada Filetype detection is enabled by default. This can be disabled by adding ":filetype off" to
init.vim.
Syntax highlighting is enabled by default. This can be disabled by adding ":syntax off" to
init.vim.
Default color scheme has been updated. This can result in color schemes looking differently due to them relying on how highlight groups are defined by default. Add ":colorscheme vim" to
init.vim or ":source $VIMRUNTIME/colors/vim.lua" to your color scheme file to restore the old default links and colors. See
:highlight for a list of highlight groups colorschemes should set.
'autoread' is enabled (works in all UIs, including terminal)
'background' defaults to "dark" (unless set automatically by the terminal/UI)
'backupdir' defaults to .,~/.local/state/nvim/backup// (
xdg), auto-created
'define' defaults to "". The C ftplugin sets it to "^\\s*#\\s*define"
'directory' defaults to ~/.local/state/nvim/swap// (
xdg), auto-created
'fillchars' defaults (in effect) to "vert:│,fold:·,foldsep:│"
'grepprg' uses the -H and -I flags for regular grep, and defaults to using ripgrep if available
'include' defaults to "". The C ftplugin sets it to "^\\s*#\\s*include"
'isfname' does not include ":" (on Windows). Drive letters are handled correctly without it. (Use
gF for filepaths suffixed with ":line:col").
'path' defaults to ".,,". The C ftplugin adds "/usr/include" if it exists.
'tags' defaults to "./tags;,tags"
'termguicolors' is enabled by default if Nvim can detect support from the host terminal
'undodir' defaults to ~/.local/state/nvim/undo// (
xdg), auto-created
editorconfig plugin is enabled, .editorconfig settings are applied.
man.lua plugin is enabled, so
:Man is available by default.
|matchit| plugin is enabled. To disable it in your config:
:let loaded_matchit = 1
Mouse is NOT enabled in
Cmdline-mode or the
more-prompt, so you cantemporarily disable it just by typing ":". Or if you want to partially orfully disable the mouse or popup-menu, do any of the following:
Disable mouse completely by unsetting the
'mouse' option:
set mouse=
Change the
'mousemodel', so
<RightMouse> extends selection instead of showing the popup-menu:
set mousemodel=extend
Map
<A-LeftMouse> so that it temporarily disables mouse until the cursor moves:
nnoremap <A-LeftMouse> <Cmd> \ set mouse=<Bar> \ echo 'mouse OFF until next cursor-move'<Bar> \ autocmd CursorMoved * ++once set mouse&<Bar> \ echo 'mouse ON'<CR>
To remove the default popup-menu without disabling mouse:
aunmenu PopUpautocmd! nvim.popupmenu
To remove only the "How-to disable mouse" menu item (and its separator):
aunmenu PopUp.How-to\ disable\ mouseaunmenu PopUp.-2-
DEFAULT MAPPINGS
default-mappingsNvim creates the following default mappings at
startup. You can disable anyof these in your config by simply removing the mapping, e.g. ":unmap Y". Ifyou never want any default mappings, call
:mapclear early in your config.
DEFAULT AUTOCOMMANDS
default-autocmdsDefault autocommands exist in the following groups. Use ":autocmd!
{group}" toremove them and ":autocmd
{group}" to see how they're defined.
nvim.terminal:
TermClose: A
terminal buffer started with no arguments (which thus uses
'shell') and which exits with no error is closed automatically.
TermRequest: The terminal emulator responds to OSC background and foreground requests, indicating (1) a black background and white foreground when Nvim option
'background' is "dark" or (2) a white background and black foreground when
'background' is "light". While this may not reflect the actual foreground/background color, it permits
'background' to be retained for a nested Nvim instance running in the terminal emulator.
TermRequest: Nvim will create extmarks for shells which annotate their prompts with OSC 133 escape sequences, enabling users to quickly navigate between prompts using
[[ and
]].
TermOpen: Sets default options and mappings for
terminal buffers:
[[ and
]] to navigate between shell prompts
nvim.swapfile:
SwapExists: Skips the swapfile prompt (sets
v:swapchoice to "e") when the swapfile is owned by a running Nvim process. Shows
W325 "Ignoring swapfile…" message.
nvim.exrc:
VimEnter: Extend
'exrc' to also search for project-local configuration files in all parent directories.
nvim.progress:
Progress: Display native progress bars in the TUI using the OSC 9;4 escape sequence.
MAJOR COMPONENTS
USER EXPERIENCE
Working intuitively and consistently is a major goal of Nvim.
feature-compile Nvim always includes ALL features, in contrast to Vim (which ships various combinations of 100+ optional features).
feature-compile Think of it as a leaner version of Vim's "HUGE" build. This reduces surface area for bugs, and removes a common source of confusion and friction for users.
Nvim avoids features that cannot be provided on all platforms; instead that is delegated to external plugins/extensions. E.g. the
-X platform-specific option is "sometimes" available in Vim (with potential surprises:
https://stackoverflow.com/q/14635295).
Vim's internal test functions (test_autochdir(), test_settime(), etc.) are not exposed (nor implemented); instead Nvim has a robust API.
Behaviors, options, documentation are removed if they cost users more time than they save.
Usability details have been improved where the benefit outweighs anybackwards-compatibility cost. Some examples:
Terminal features such as
'guicursor' are enabled where possible.
Some features are built in that otherwise required external plugins:
Highlighting the yanked region, see
vim.hl.
ARCHITECTURE
The Nvim UI is "decoupled" from the core editor: all UIs, including thebuiltin
TUI are just plugins that connect to a Nvim server (via
--serveror
--embed). Multiple Nvim UI clients can connect to the same Nvim editorserver.
External plugins run in separate processes.
remote-plugin This improvesstability and allows those plugins to work without blocking the editor. Even"legacy" Python and Ruby plugins which use the old Vim interfaces (
if_pyth,
if_ruby) run out-of-process, so they cannot crash Nvim.
Platform and I/O facilities are built upon libuv. Nvim benefits from libuvfeatures and bug fixes, and other projects benefit from improvements to libuvby Nvim developers.
FEATURES
Command-line:
(Experimental)
g:Nvim_color_cmdline Command-line (
:) is colored by callback defined in
g:Nvim_color_cmdline (this callback is for testing only, and will be removed in the future).
Commands:
:drop is always available
:Man is available by default, with many improvements such as completion
:match can be invoked before highlight group is defined
:write with "++p" flag creates parent directories.
:update command writes new file buffers even when unmodified.
Editor:
prompt-buffer supports multiline input/paste, undo/redo, and o/O normal commands.
i_CTRL-R inserts named/clipboard registers (A-Z,a-z,0-9+) literally, like pasting instead of like user input. Improves performance, avoids broken formatting. To get the old behavior you can use
<C-R>=@x.
Events (autocommands):
Fixed inconsistent behavior in execution of nested autocommands #23368
TermResponse is fired for DCS, OSC, and APC sequences received from the terminal, in addition to the Primary Device Attributes response.
v:termresponse Functions:
matchadd() can be called before highlight group is defined
Input/Mappings:
ALT (
META) chords always work (even in the
TUI). Map
<M- with any key:
<M-1>,
<M-BS>,
<M-Del>,
<M-Ins>,
<M-/>,
<M-\>,
<M-Space>,
<M-Enter>, etc.
Case-sensitive:<M-a> and<M-A> are two different keycodes.
Normal commands:
gO shows a filetype-defined "outline" of the current buffer.
Q replays the last recorded macro instead of switching to Ex mode (
gQ).
Options:
:set {option}< removes local value for all
global-local options.
:setlocal {option}< copies global value to local value for all options.
'autoread' works in the terminal (if it supports "focus" events)
'exrc' searches for ".nvim.lua", ".nvimrc", or ".exrc" files. The user is prompted whether to trust the file.
'fillchars' flags: "msgsep", "horiz", "horizup", "horizdown", "vertleft", "vertright", "verthoriz"
"view" tries to restore
mark-view when moving through the jumplist.
"clean" removes unloaded buffers from the jumplist.
"F" flag does not affect output from autocommands.
"q" flag fully hides macro recording message.
'signcolumn' can show multiple signs (dynamic or fixed columns)
'tabline' middle-click on tabpage label closes tabpage, and %@Func@foo%X can call any function on mouse-click
'busy' busy status for buffers
Performance:
Signs are implemented using Nvim's internal "marktree" (btree) structure.
Folds are not updated during insert-mode.
Shell:
Shell output (
:!,
:make, …) is always routed through the UI, so it cannot "mess up" the screen. (You can still use "chansend(v:stderr,…)" if you want to mess up the screen :)
Nvim throttles (skips) messages from shell commands (
:!,
:grep,
:make) if there is too much output. No data is lost, this only affects display and improves performance.
:terminal output is never throttled.
:! does not support "interactive" commands. Use
:terminal instead. (GUI Vim has a similar limitation, see ":help gui-pty" in Vim.)
:!start is not special-cased on Windows.
system() does not support writing/reading "backgrounded" commands.
E5677 Signs:
Signs are removed if the associated line is deleted.
Signs placed twice with the same identifier in the same group are moved.
Startup:
-e and
-es invoke the same "improved Ex mode" as -E and -Es.
-E and
-Es read stdin as text (into buffer 1).
-es and
-Es have improved behavior:
Quits automatically, don't need "-c qa!".
Skips swap-file dialog.
Optimized for non-interactive scripts: disables swapfile, shada.
-l Executes Lua scripts non-interactively.
-s reads Normal commands from stdin if the script name is "-".
Reading text (instead of commands) from stdin
--:
works by default: "-" file is optional
works in more cases:
-Es, file args
'term'E529E530E531'term' reflects the terminal type derived from
$TERM and other environment checks. Use
:echo &term to get its value. For debugging only; not reliable during startup.
Note: If you want to detect when Nvim is running in a terminal, use
has('gui_running')has() or see
nvim_list_uis() for an example of how to inspect the UI channel.
"builtin_x" means one of the
builtin-terms was chosen, because the expected terminfo file was not found on the system.
Nvim will use 256-colour capability on Linux virtual terminals. Vim uses only 8 colours plus bright foreground on Linux VTs.
Vim combines what is in its
builtin-terms with what it reads from terminfo, and has a
'ttybuiltin' setting to control how that combination works. Nvim uses one or the other, it does not attempt to merge the two.
Variables:
v:windowid is always available (for use by external UIs)
These Nvim features were later integrated into Vim.
'wildoptions' flags: "pum" enables popupmenu for wildmode completion
:source works with anonymous (no file) scripts
Lua: vim.g, vim.w, vim.b, vim.t, vim.v, vim.fn, vim.call()
This section documents various low-level behavior changes.
mkdir() behaviour changed:
1. Assuming /tmp/foo does not exist and /tmp can be written to mkdir('/tmp/foo/bar', 'p', 0700) will create both /tmp/foo and /tmp/foo/bar with 0700 permissions. Vim mkdir will create /tmp/foo with 0755.
2. If you try to create an existing directory with'p' (e.g. mkdir('/', 'p')) mkdir() will silently exit. In Vim this was an error.
3. mkdir() error messages now include strerror() text when mkdir fails.
string() and
:echo behaviour changed:
1. No maximum recursion depth limit is applied to nested container structures.
2.
string() fails immediately on nested containers, not when recursion limit was exceeded.
3. When
:echo encounters duplicate containers like
let l = []echo [l, l]
it does not use "[...]" (was: "[[], [...]]", now: "[[], []]"). "..." is only used for recursive containers.
4.
:echo printing nested containers adds "@level" after "..." designating the level at which recursive container was printed:
:echo-self-refer. Same thing applies to
string() (though it uses construct like "{E724@level}"), but this is not reliable because
string() continues to error out.
5. Stringifyed infinite and NaN values now use
str2float() and can be evaled back.
6. (internal) Trying to print or stringify VAR_UNKNOWN in Vim results in nothing, E908, in Nvim it is internal error.
json_decode() behaviour changed:
3. It accepts only valid JSON. Trailing commas are not accepted.
Viminfo text files were replaced with binary (messagepack)
shada files.Additional differences:
shada-s now limits size of every item and not just registers.
'viminfo' option got renamed to
'shada'. Old option is kept as an alias for compatibility reasons.
ShaDa file format was designed with forward and backward compatibility in mind.
shada-compatibility Some errors make ShaDa code keep temporary file in-place for user to decide what to do with it. Vim deletes temporary file in these cases.
shada-error-handlingprintf() returns something meaningful when used with
%p argument: in Vimit used to return useless address of the string (strings are copied to thenewly allocated memory all over the place) and fail on types which cannot becoerced to strings. See
id() for more details, currently it uses
printf("%p", {expr}) internally.
Lua interface (
lua.txt):
:lua print("a\0b") will printa^@b, like with:echomsg "a\nb" . In Vim that printsa andb on separate lines, exactly like:lua print("a\nb") .
:lua error('TEST') emits the error:
E5108: Lua: [string "<Vimscript compiled string>"]:1: TEST
whereas Vim emits only "TEST".
Lua has direct access to Nvim
API via
vim.api.
Commands:
:doautocmd does not warn about "No matching autocommands".
:write! does not show a prompt if the file was updated externally.
Command-line:
The meanings of arrow keys do not change depending on
'wildoptions'.
Functions:
input() and
inputdialog() support for each other’s features (return on cancel and completion respectively) via dictionary argument (replaces all other arguments if used), and "cancelreturn" can have any type if passed in a dictionary.
Highlight groups:
Highlight groups names are allowed to contain@ characters.
It is an error to define a highlight group with a name that doesn't match the regexp
[a-zA-Z0-9_.@-]* (see
group-name).
Macro (
recording) behavior:
Replay of a macro recorded during :lmap produces the same actions as when it was recorded. In Vim if a macro is recorded while using :lmap'ped keys then the behaviour during record and replay differs.
'keymap' is implemented via :lmap instead of :lnoremap so that you can use macros and
'keymap' at the same time. This also means you can use
:imap on the results of keys from
'keymap'.
Mappings:
Creating a mapping for a simplifiable key (e.g.<C-I>) doesn't replace an existing mapping for its simplified form (e.g.<Tab>).
"#" followed by a digit doesn't stand for a function key at the start of the lhs of a mapping.
Motion:
The
jumplist avoids useless/phantom jumps.
Syntax highlighting:
syncolor.vim has been removed. Nvim now sets up default highlighting groups automatically for both light and dark backgrounds, regardless of whether or not syntax highlighting is enabled. This means that
:syntax-on and
:syntax-enable are now identical. Users who previously used an after/syntax/syncolor.vim file should transition that file into a colorscheme.
:colorschemeWorking directory (Vim implemented some of these after Nvim):
haslocaldir() checks for tab-local directory if and only if -1 is passed as window number, and its only possible returns values are 0 and 1.
getcwd(-1) is equivalent togetcwd(-1, 0) instead of returning the global working directory. Usegetcwd(-1, -1) to get the global working directory.
Options:
'titlestring' uses printf-style '%' items (see:
'statusline') to implement the default behaviour. The implementation is equivalent to setting
'titlestring' to
%t%(\ %M%)%(\ \(%{expand(\"%:~:h\")}\)%)%a\ -\ Nvim.
These legacy Vim features are not yet implemented:
These Vim features were intentionally removed from Nvim.
Aliases:
ex (alias for "nvim -e")
exim (alias for "nvim -E")
gex (GUI)
gview (GUI)
gvim (GUI)
gvimdiff (GUI)
rgview (GUI)
rgvim (GUI)
rview
rvim
view (alias for "nvim -R")
Commands:
:behave
:fixdel
hardcopy:hardcopy was removed. Instead, use
:TOhtml and print the resulting HTML using a web browser or other HTML viewer.
:helpfind
:mode (no longer accepts an argument)
:open
:Print
:promptfind
:promptrepl
:scriptversion (always version 1)
:shell
:smile
:tearoff
:cstag
:cscope
:lcscope
:scscope
:Vimuntar
:TOhtml was replaced by a Lua version (with various differences)
Compile-time features:
Emacs tags support
Eval:
Vim9script (the Vim 9+ flavor of Vimscript) is not supported.
v:none (used by Vim to represent JavaScript "undefined"); use
v:null instead.
Options:
antialias
forbackspace=0 setbackspace= (empty)
forbackspace=1 setbackspace=indent,eol
forbackspace=2 setbackspace=indent,eol,start (default behavior in Nvim)
forbackspace=3 setbackspace=indent,eol,nostop
bioskey (MS-DOS)
conskey (MS-DOS)
'cpoptions' (gjpkHw<*- and all POSIX flags were removed)
cscopepathcomp
cscopeprg
cscopequickfix
cscoperelative
cscopetag
cscopetagorder
cscopeverbose
esckeys
'guipty' (Nvim uses pipes and PTYs consistently on all platforms.)
keyprotocol
'pastetoggle''pt' Just Paste It.™
paste is handled automatically when you paste text using your terminal's or GUI's paste feature (
CTRL-SHIFT-v, CMD-v (macOS), middle-click, …).
'insertmode''im' Use the following script to emulate
'insertmode':
autocmd BufWinEnter * startinsertinoremap <Esc> <C-X><C-Z><C-]>inoremap <C-C> <C-X><C-Z>inoremap <C-L> <C-X><C-Z><C-]><Esc>inoremap <C-Z> <C-X><C-Z><Cmd>suspend<CR>noremap <C-C> <Esc>snoremap <C-C> <Esc>noremap <C-\><C-G> <C-\><C-N><Cmd>startinsert<CR>cnoremap <C-\><C-G> <C-\><C-N><Cmd>startinsert<CR>inoremap <C-\><C-G> <C-X><C-Z>autocmd CmdwinEnter * noremap <buffer> <C-C> <C-C>autocmd CmdwinEnter * inoremap <buffer> <C-C> <C-C>lua << EOF vim.on_key(function(c) if c == '\27' then local mode = vim.api.nvim_get_mode().mode if mode:find('^[nvV\22sS\19]') and vim.fn.getcmdtype() == '' then vim.schedule(function() vim.cmd('startinsert') end) end end end)EOF
'maxcombine''mco' : Nvim counts maximum character sizes in bytes, not codepoints. This is guaranteed to be big enough to always fit all chars properly displayed in vim with
'maxcombine' set to 6.
You can still edit text with larger characters than fits in the screen buffer, you just can't see them. Use
g8 or
ga. See
mbyte-combining.
NOTE: the rexexp engine still has a hard-coded limit of considering 6 composing chars only.
'maxmem' Nvim delegates memory-management to the OS.
'maxmemtot' Nvim delegates memory-management to the OS.
printoptions
'secure' : Everything is allowed in
'exrc' files, because they must be explicitly marked as "trusted".
textauto
textmode
weirdinvert
Plugins:
logiPat
rrhelper
shellmenu
macmap.vim
tools/check_colors.vim
macros/{justify,matchit,swapmous}.vim: usepackadd! justify etc. directly
Providers:
if_lua : Nvim
Lua API is not compatible with Vim's "if_lua".
Startup:
--literal: File args are always literal; to expand wildcards on Windows, use
:n e.g.
nvim +"n *" Easy mode: eview, evim, nvim -y
Restricted mode: rview, rvim, nvim -Z
Vi mode: nvim -v
Test functions:
test_alloc_fail()
test_autochdir()
test_feedinput()
test_garbagecollect_soon()
test_getvalue()
test_ignore_error()
test_null_blob()
test_null_channel()
test_null_dict()
test_null_function()
test_null_job()
test_null_list()
test_null_partial()
test_null_string()
test_option_not_set()
test_override()
test_refcount()
test_scrollbar()
test_setmouse()
test_settime()
test_srand_seed()
test_unknown()
test_void()
TUI:
t_xxtermcap-optionst_ABt_Sbt_vbt_SI Nvim does not have special
t_XX options nor
<t_XX> keycodes to configure terminal capabilities. Instead Nvim treats the terminal as any other UI, e.g.
'guicursor' sets the terminal cursor style if possible.
xterm-8bitxterm-8-bit Xterm can be run in a mode where it uses true 8-bit CSI. Supporting this requires autodetection of whether the terminal is in UTF-8 mode or non-UTF-8 mode, as the 8-bit CSI character has to be written differently in each case. Vim issues a "request version" sequence to the terminal at startup and looks at how the terminal is sending CSI. Nvim does not issue such a sequence and always uses 7-bit control sequences.