532 lines
19 KiB
Plaintext
532 lines
19 KiB
Plaintext
*vim_diff.txt* Nvim
|
||
|
||
|
||
NVIM REFERENCE MANUAL
|
||
|
||
|
||
Differences between Nvim and Vim *vim-differences*
|
||
|
||
Nvim differs from Vim in many ways, although editor and VimL features are
|
||
mostly identical. This document is a complete and centralized reference of
|
||
the differences.
|
||
|
||
Type |gO| to see the table of contents.
|
||
|
||
==============================================================================
|
||
1. Configuration *nvim-configuration*
|
||
|
||
- Use `$XDG_CONFIG_HOME/nvim/init.vim` instead of `.vimrc` for configuration.
|
||
- Use `$XDG_CONFIG_HOME/nvim` instead of `.vim` to store configuration files.
|
||
- Use `$XDG_DATA_HOME/nvim/shada/main.shada` instead of `.viminfo` for persistent
|
||
session information. |shada|
|
||
|
||
==============================================================================
|
||
2. Defaults *nvim-defaults*
|
||
|
||
- Syntax highlighting is enabled by default
|
||
- ":filetype plugin indent on" is enabled by default
|
||
|
||
- 'autoindent' is enabled
|
||
- 'autoread' is enabled
|
||
- 'background' defaults to "dark" (unless set automatically by the terminal/UI)
|
||
- 'backspace' defaults to "indent,eol,start"
|
||
- 'backupdir' defaults to .,~/.local/share/nvim/backup (|xdg|)
|
||
- 'belloff' defaults to "all"
|
||
- 'compatible' is always disabled
|
||
- 'complete' excludes "i"
|
||
- 'cscopeverbose' is enabled
|
||
- 'directory' defaults to ~/.local/share/nvim/swap// (|xdg|), auto-created
|
||
- 'display' defaults to "lastline,msgsep"
|
||
- 'encoding' is UTF-8 (cf. 'fileencoding' for file-content encoding)
|
||
- 'fillchars' defaults (in effect) to "vert:│,fold:·"
|
||
- 'formatoptions' defaults to "tcqj"
|
||
- 'fsync' is disabled
|
||
- 'history' defaults to 10000 (the maximum)
|
||
- 'hlsearch' is enabled
|
||
- 'incsearch' is enabled
|
||
- 'langnoremap' is enabled
|
||
- 'langremap' is disabled
|
||
- 'laststatus' defaults to 2 (statusline is always shown)
|
||
- 'listchars' defaults to "tab:> ,trail:-,nbsp:+"
|
||
- 'nrformats' defaults to "bin,hex"
|
||
- 'ruler' is enabled
|
||
- 'sessionoptions' excludes "options"
|
||
- 'shortmess' includes "F", excludes "S"
|
||
- 'showcmd' is enabled
|
||
- 'sidescroll' defaults to 1
|
||
- 'smarttab' is enabled
|
||
- 'startofline' is disabled
|
||
- 'tabpagemax' defaults to 50
|
||
- 'tags' defaults to "./tags;,tags"
|
||
- 'ttimeoutlen' defaults to 50
|
||
- 'ttyfast' is always set
|
||
- 'undodir' defaults to ~/.local/share/nvim/undo (|xdg|), auto-created
|
||
- 'viminfo' includes "!"
|
||
- 'wildmenu' is enabled
|
||
- 'wildoptions' defaults to "pum,tagfile"
|
||
|
||
- The |man.vim| plugin is enabled, to provide the |:Man| command.
|
||
- The |matchit| plugin is enabled. To disable it in your config: >
|
||
:let loaded_matchit = 1
|
||
|
||
==============================================================================
|
||
3. New Features *nvim-features*
|
||
|
||
MAJOR COMPONENTS ~
|
||
|
||
API |API|
|
||
Lua scripting |lua|
|
||
Job control |job-control|
|
||
Remote plugins |remote-plugin|
|
||
Providers
|
||
Clipboard |provider-clipboard|
|
||
Node.js plugins |provider-nodejs|
|
||
Python plugins |provider-python|
|
||
Ruby plugins |provider-ruby|
|
||
Shared data |shada|
|
||
Embedded terminal |terminal|
|
||
VimL parser |nvim_parse_expression()|
|
||
XDG base directories |xdg|
|
||
|
||
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 with
|
||
various combinations of 100+ optional features). 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:
|
||
http://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 any
|
||
backwards-compatibility cost. Some examples:
|
||
|
||
- |K| in help documents can be used like |CTRL-]|.
|
||
- Directories for 'directory' and 'undodir' are auto-created.
|
||
- Terminal features such as 'guicursor' are enabled where possible.
|
||
|
||
ARCHITECTURE ~
|
||
|
||
External plugins run in separate processes. |remote-plugin| This improves
|
||
stability 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.
|
||
|
||
Platform and I/O facilities are built upon libuv. Nvim benefits from libuv
|
||
features and bug fixes, and other projects benefit from improvements to libuv
|
||
by Nvim developers.
|
||
|
||
FEATURES ~
|
||
|
||
Command-line highlighting:
|
||
The expression prompt (|@=|, |c_CTRL-R_=|, |i_CTRL-R_=|) is highlighted
|
||
using a built-in VimL expression parser. |expr-highlight|
|
||
*E5408* *E5409*
|
||
|input()|, |inputdialog()| support custom highlighting. |input()-highlight|
|
||
*g:Nvim_color_cmdline*
|
||
(Experimental) 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:
|
||
|:autocmd| accepts the `++once` flag
|
||
|:checkhealth|
|
||
|:cquit| can use [count] to set the exit code
|
||
|:drop| is always available
|
||
|:Man| is available by default, with many improvements such as completion
|
||
|:sign-define| accepts a `numhl` argument, to highlight the line number
|
||
|:tchdir| tab-local |current-directory|
|
||
|
||
Events:
|
||
|DirChanged|
|
||
|Signal|
|
||
|TabNewEntered|
|
||
|TermClose|
|
||
|TermOpen|
|
||
|TextYankPost|
|
||
|UIEnter|
|
||
|UILeave|
|
||
|VimResume|
|
||
|VimSuspend|
|
||
|
||
Functions:
|
||
|dictwatcheradd()| notifies a callback whenever a |Dict| is modified
|
||
|dictwatcherdel()|
|
||
|menu_get()|
|
||
|msgpackdump()|, |msgpackparse()| provide msgpack de/serialization
|
||
|stdpath()|
|
||
|system()|, |systemlist()| can run {cmd} directly (without 'shell')
|
||
|
||
Highlight groups:
|
||
|highlight-blend| controls blend level for a highlight group
|
||
|expr-highlight| highlight groups (prefixed with "Nvim")
|
||
|hl-NormalFloat| highlights floating window
|
||
|hl-NormalNC| highlights non-current windows
|
||
|hl-MsgArea| highlights messages/cmdline area
|
||
|hl-MsgSeparator| highlights separator for scrolled messages
|
||
|hl-QuickFixLine|
|
||
|hl-Substitute|
|
||
|hl-TermCursor|
|
||
|hl-TermCursorNC|
|
||
|hl-Whitespace| highlights 'listchars' whitespace
|
||
|
||
Input:
|
||
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.
|
||
|
||
ALT in insert-mode behaves like <Esc> if not mapped. |i_ALT|
|
||
|
||
Mappings:
|
||
|<Cmd>| pseudokey
|
||
|
||
Normal commands:
|
||
"Outline": Type |gO| in |:Man| and |:help| pages to see a document outline.
|
||
|
||
Options:
|
||
'cpoptions' flags: |cpo-_|
|
||
'display' flags: "msgsep" minimizes scrolling when showing messages
|
||
'guicursor' works in the terminal
|
||
'fillchars' flags: "msgsep" (see 'display'), "eob" for |hl-EndOfBuffer|
|
||
marker, "foldopen", "foldsep", "foldclose"
|
||
'inccommand' shows interactive results for |:substitute|-like commands
|
||
'listchars' local to window
|
||
'pumblend' pseudo-transparent popupmenu
|
||
'scrollback'
|
||
'signcolumn' supports up to 9 dynamic/fixed columns
|
||
'statusline' supports unlimited alignment sections
|
||
'tabline' %@Func@foo%X can call any function on mouse-click
|
||
'wildoptions' "pum" flag to use popupmenu for wildmode completion
|
||
'winblend' pseudo-transparency in floating windows |api-floatwin|
|
||
'winhighlight' window-local highlights
|
||
|
||
Signs:
|
||
Signs are removed if the associated line is deleted.
|
||
|
||
Variables:
|
||
|v:event|
|
||
|v:exiting|
|
||
|v:progpath| is always absolute ("full")
|
||
|v:windowid| is always available (for use by external UIs)
|
||
|
||
==============================================================================
|
||
4. Changed features *nvim-features-changed*
|
||
|
||
Nvim always builds with all features, in contrast to Vim which may have
|
||
certain features removed/added at compile-time. |feature-compile|
|
||
|
||
If a Python interpreter is available on your `$PATH`, |:python| and |:python3|
|
||
are always available and may be used simultaneously. See |provider-python|.
|
||
|
||
|:redir| nested in |execute()| works.
|
||
|
||
|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.
|
||
2. When |:echo| encounters duplicate containers like >
|
||
|
||
let l = []
|
||
echo [l, l]
|
||
<
|
||
it does not use "[...]" (was: "[[], [...]]", now: "[[], []]"). "..." is
|
||
only used for recursive containers.
|
||
3. |: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.
|
||
4. Stringifyed infinite and NaN values now use |str2float()| and can be evaled
|
||
back.
|
||
5. (internal) Trying to print or stringify VAR_UNKNOWN in Vim results in
|
||
nothing, E908, in Nvim it is internal error.
|
||
|
||
|json_decode()| behaviour changed:
|
||
1. It may output |msgpack-special-dict|.
|
||
2. |msgpack-special-dict| is emitted also in case of duplicate keys, while in
|
||
Vim it errors out.
|
||
3. It accepts only valid JSON. Trailing commas are not accepted.
|
||
|
||
|json_encode()| behaviour slightly changed: now |msgpack-special-dict| values
|
||
are accepted, but |v:none| is not.
|
||
|
||
*v:none* variable is absent. In Vim it represents “no value” in “js” strings
|
||
like "[,]" parsed as "[v:none]" by |js_decode()|.
|
||
|
||
*js_encode()* and *js_decode()* functions are also absent.
|
||
|
||
Viminfo text files were replaced with binary (messagepack) ShaDa files.
|
||
Additional differences:
|
||
|
||
- |shada-c| has no effect.
|
||
- |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.
|
||
- |:wviminfo| was renamed to |:wshada|, |:rviminfo| to |:rshada|. Old
|
||
commands are still kept.
|
||
- 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-handling|
|
||
- ShaDa file keeps search direction (|v:searchforward|), viminfo does not.
|
||
|
||
|printf()| returns something meaningful when used with `%p` argument: in Vim
|
||
it used to return useless address of the string (strings are copied to the
|
||
newly allocated memory all over the place) and fail on types which cannot be
|
||
coerced to strings. See |id()| for more details, currently it uses
|
||
`printf("%p", {expr})` internally.
|
||
|
||
|c_CTRL-R| pasting a non-special register into |cmdline| omits the last <CR>.
|
||
|
||
Lua interface (|lua.txt|):
|
||
|
||
- `:lua print("a\0b")` will print `a^@b`, like with `:echomsg "a\nb"` . In Vim
|
||
that prints `a` and `b` on separate lines, exactly like
|
||
`:lua print("a\nb")` .
|
||
- `:lua error('TEST')` emits the error “E5105: Error while calling lua chunk:
|
||
[string "<VimL compiled string>"]:1: TEST”, whereas Vim emits only “TEST”.
|
||
- Lua has direct access to Nvim |API| via `vim.api`.
|
||
- Lua package.path and package.cpath are automatically updated according to
|
||
'runtimepath': |lua-require|.
|
||
|
||
Commands:
|
||
|:doautocmd| does not warn about "No matching autocommands".
|
||
|
||
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).
|
||
|input()| and |inputdialog()| support user-defined cmdline highlighting.
|
||
|
||
Highlight groups:
|
||
|hl-ColorColumn|, |hl-CursorColumn| are lower priority than most other
|
||
groups
|
||
|hl-CursorLine| is low-priority unless foreground color is set
|
||
|
||
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'.
|
||
|
||
Motion:
|
||
The |jumplist| avoids useless/phantom jumps.
|
||
|
||
Normal commands:
|
||
|Q| is the same as |gQ|
|
||
|
||
Options:
|
||
'ttimeout', 'ttimeoutlen' behavior was simplified
|
||
|jumpoptions| "stack" behavior
|
||
|
||
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|
|
||
|
||
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.
|
||
|-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
|
||
|
||
TUI:
|
||
*:set-termcap*
|
||
Start Nvim with 'verbose' level 3 to show terminal capabilities: >
|
||
nvim -V3
|
||
<
|
||
*'term'* *E529* *E530* *E531*
|
||
'term' reflects the terminal type derived from |$TERM| and other environment
|
||
checks. For debugging only; not reliable during startup. >
|
||
:echo &term
|
||
< "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.
|
||
|
||
UI/Display:
|
||
|Visual| selection highlights the character at cursor. |visual-use|
|
||
|
||
VimL (Vim script) compatibility:
|
||
`count` does not alias to |v:count|
|
||
`errmsg` does not alias to |v:errmsg|
|
||
`shell_error` does not alias to |v:shell_error|
|
||
`this_session` does not alias to |v:this_session|
|
||
|
||
==============================================================================
|
||
5. Missing legacy features *nvim-features-missing*
|
||
|
||
Some legacy Vim features are not implemented:
|
||
|
||
- |if_lua|: Nvim Lua API is not compatible with Vim's "if_lua"
|
||
- *if_mzscheme*
|
||
- *if_perl*
|
||
- |if_py|: *python-bindeval* *python-Function* are not supported
|
||
- *if_tcl*
|
||
|
||
==============================================================================
|
||
6. Removed features *nvim-features-removed*
|
||
|
||
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 (alias for "nvim -RZ")
|
||
rvim (alias for "nvim -Z")
|
||
view (alias for "nvim -R")
|
||
vimdiff (alias for "nvim -d" |diff-mode|)
|
||
|
||
Commands:
|
||
:fixdel
|
||
:helpfind
|
||
:mode (no longer accepts an argument)
|
||
:open
|
||
:Print
|
||
:shell
|
||
:smile
|
||
:tearoff
|
||
|
||
Compile-time features:
|
||
EBCDIC
|
||
Emacs tags support
|
||
X11 integration (see |x11-selection|)
|
||
|
||
Highlight groups:
|
||
*hl-StatusLineTerm* *hl-StatusLineTermNC* are unnecessary because Nvim
|
||
supports 'winhighlight' window-local highlights.
|
||
For example, to mimic Vim's StatusLineTerm: >
|
||
hi StatusLineTerm ctermfg=black ctermbg=green
|
||
hi StatusLineTermNC ctermfg=green
|
||
autocmd TermOpen,WinEnter * if &buftype=='terminal'
|
||
\|setlocal winhighlight=StatusLine:StatusLineTerm,StatusLineNC:StatusLineTermNC
|
||
\|else|setlocal winhighlight=|endif
|
||
<
|
||
|
||
Options:
|
||
'antialias'
|
||
'bioskey' (MS-DOS)
|
||
'conskey' (MS-DOS)
|
||
*'cp'* *'nocompatible'* *'nocp'* *'compatible'* (Nvim is always "nocompatible".)
|
||
'cpoptions' (gjkHw<*- and all POSIX flags were removed)
|
||
*'cryptmethod'* *'cm'* *'key'* (Vim encryption implementation)
|
||
*'ed'* *'edcompatible'* *'noed'* *'noedcompatible'*
|
||
'encoding' ("utf-8" is always used)
|
||
'esckeys'
|
||
'guioptions' "t" flag was removed
|
||
*'guipty'* (Nvim uses pipes and PTYs consistently on all platforms.)
|
||
'highlight' (Names of builtin |highlight-groups| cannot be changed.)
|
||
*'imactivatefunc'* *'imaf'*
|
||
*'imactivatekey'* *'imak'*
|
||
*'imstatusfunc'* *'imsf'*
|
||
*'macatsui'*
|
||
'maxmem' Nvim delegates memory-management to the OS.
|
||
'maxmemtot' Nvim delegates memory-management to the OS.
|
||
'maxcombine' (6 is always used)
|
||
*'restorescreen'* *'rs'* *'norestorescreen'* *'nors'*
|
||
'shelltype'
|
||
*'shortname'* *'sn'* *'noshortname'* *'nosn'*
|
||
*'swapsync'* *'sws'*
|
||
*'termencoding'* *'tenc'* (Vim 7.4.852 also removed this for Windows)
|
||
'textauto'
|
||
'textmode'
|
||
*'toolbar'* *'tb'*
|
||
*'toolbariconsize'* *'tbis'*
|
||
*'ttybuiltin'* *'tbi'* *'nottybuiltin'* *'notbi'*
|
||
*'ttymouse'* *'ttym'*
|
||
*'ttyscroll'* *'tsl'*
|
||
*'ttytype'* *'tty'*
|
||
'ttyfast'
|
||
'weirdinvert'
|
||
|
||
Startup:
|
||
--literal (file args are always literal; to expand wildcards on Windows, use
|
||
|:n| e.g. `nvim +"n *"`)
|
||
Easy mode: eview, evim, nvim -y
|
||
Vi mode: nvim -v
|
||
|
||
Test functions:
|
||
test_alloc_fail()
|
||
test_autochdir()
|
||
test_disable_char_avail()
|
||
test_garbagecollect_now()
|
||
test_null_channel()
|
||
test_null_dict()
|
||
test_null_job()
|
||
test_null_list()
|
||
test_null_partial()
|
||
test_null_string()
|
||
test_override()
|
||
test_settime()
|
||
|
||
TUI:
|
||
*t_xx* *termcap-options* *t_AB* *t_Sb* *t_vb* *t_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.
|
||
|
||
*termcap*
|
||
Nvim never uses the termcap database, only |terminfo| and |builtin-terms|.
|
||
|
||
*xterm-8bit* *xterm-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.
|
||
|
||
==============================================================================
|
||
vim:tw=78:ts=8:sw=2:et:ft=help:norl:
|