path: root/runtime/doc/vim_diff.txt

*vim_diff.txt*    Nvim


			    NVIM REFERENCE MANUAL


Differences between Nvim and Vim			       *vim-differences*

Nvim differs from Vim in many ways, big and small.  This document is
a complete and centralized reference of those differences.

				      Type |gO| to see the table of contents.

==============================================================================
1. Configuration					    *nvim-configuration*

- Use `$XDG_CONFIG_HOME/nvim/init.vim` instead of `.vimrc` for storing
  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.

==============================================================================
2. Defaults					            *nvim-defaults*

- Syntax highlighting is enabled by default
- ":filetype plugin indent on" is enabled by default

- 'autoindent' is set by default
- 'autoread' is set by default
- 'backspace' defaults to "indent,eol,start"
- 'backupdir' defaults to .,~/.local/share/nvim/backup (|xdg|)
- 'belloff' defaults to "all"
- 'complete' doesn't include "i"
- 'cscopeverbose' is enabled
- 'directory' defaults to ~/.local/share/nvim/swap// (|xdg|), auto-created
- 'display' defaults to "lastline"
- 'formatoptions' defaults to "tcqj"
- 'history' defaults to 10000 (the maximum)
- 'hlsearch' is set by default
- 'incsearch' is set by default
- 'langnoremap' is enabled by default
- 'langremap' is disabled by default
- 'laststatus' defaults to 2 (statusline is always shown)
- 'listchars' defaults to "tab:> ,trail:-,nbsp:+"
- 'nocompatible' is always set
- 'nrformats' defaults to "bin,hex"
- 'ruler' is set by default
- 'sessionoptions' doesn't include "options"
- 'showcmd' is set by default
- 'sidescroll' defaults to 1
- 'smarttab' is set by default
- 'tabpagemax' defaults to 50
- 'tags' defaults to "./tags;,tags"
- 'ttyfast' is always set
- 'undodir' defaults to ~/.local/share/nvim/undo (|xdg|), auto-created
- 'viminfo' includes "!"
- 'wildmenu' is set by default

==============================================================================
3. New Features						       *nvim-features*

MAJOR COMPONENTS ~

API				|API|
Lua scripting			|lua|
Job control			|job-control|
Remote plugins			|remote-plugin|
Providers
  Clipboard			|provider-clipboard|
  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_py| and
|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 ~

"Outline": Type |gO| in |:Man| and |:help| pages to see a document outline.

|META| (ALT) chords are recognized, even in the terminal. Any |<M-| mapping
will work. Some examples: <M-1>, <M-2>, <M-BS>, <M-Del>, <M-Ins>, <M-/>,
<M-\>, <M-Space>, <M-Enter>, <M-=>, <M-->, <M-?>, <M-$>, ...
META chords are case-sensitive: <M-a> and <M-A> are two different keycodes.

Some `CTRL-SHIFT-...` key chords are distinguished from `CTRL-...` variants
(even in the terminal). Specifically, the following are known to work:
  <C-Tab>, <C-S-Tab>, <C-BS>, <C-S-BS>, <C-Enter>, <C-S-Enter>

Options:
  'cpoptions' flags: |cpo-_|
  'guicursor' works in the terminal
  'inccommand' shows interactive results for |:substitute|-like commands
  'scrollback'
  'statusline' supports unlimited alignment sections
  'tabline' %@Func@foo%X can call any function on mouse-click
  'winhighlight' window-local highlights

Variables:
  |v:event|
  |v:exiting|
  |v:progpath| is always absolute ("full")
  |v:windowid| is always available (for use by external UIs)

Commands:
  |:checkhealth|
  |:drop| is available on all platforms
  |:Man| is available by default, with many improvements such as completion
  |:tchdir| tab-local |current-directory|

Functions:
  |dictwatcheradd()| notifies a callback whenever a |Dict| is modified
  |dictwatcherdel()|
  |menu_get()|
  |msgpackdump()|, |msgpackparse()| provide msgpack de/serialization

Events:
  |DirChanged|
  |TabNewEntered|
  |TermClose|
  |TermOpen|
  |TextYankPost|

Highlight groups:
  |hl-NormalNC| highlights non-current windows
  |hl-QuickFixLine|
  |hl-Substitute|
  |hl-TermCursor|
  |hl-TermCursorNC|
  |hl-Whitespace| highlights 'listchars' whitespace
  |expr-highlight| highlight groups (prefixed with "Nvim")

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

==============================================================================
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.  This is like if Vim's "HUGE"
build was the only Vim release type (except Nvim is smaller than Vim's "HUGE"
build).

If a Python interpreter is available on your `$PATH`, |:python| and |:python3|
are always available and may be used simultaneously in separate plugins.  The
`neovim` pip package must be installed to use Python plugins in Nvim (see
|provider-python|).

Because of general |256-color| usage whereever possible, Nvim will even 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 termcap,
and has a |ttybuiltin| setting to control how that combination works.  Nvim
uses either one or the other of an external |terminfo| entry or the built-in
one.  It does not attempt to mix data from the two.

|:!| does not support "interactive" commands. Use |:terminal| instead.
(GUI Vim has a similar limitation, see ":help gui-pty" in Vim.)

|system()| does not support writing/reading "backgrounded" commands. |E5677|

|:redir| nested in |execute()| works.

Nvim may throttle (skip) messages from shell commands (|:!|, |:grep|, |:make|)
if there is too much output. No data is lost, this only affects display and
makes things faster. |:terminal| output is never throttled.

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

'encoding' is always "utf-8".

|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 Neovim 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 (|if_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')` will print “TEST” as the error in Vim and “E5105: Error 
  while calling lua chunk: [string "<VimL compiled string>"]:1: TEST” in 
  Neovim.
- Lua has direct access to Nvim |API| via `vim.api`.
- Lua package.path and package.cpath are automatically updated according to
  'runtimepath': |lua-require|.

|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

VimL (Vim script) compatibility:
  `count` does not alias to |v:count|

==============================================================================
5. Missing legacy features				 *nvim-features-missing*

Some legacy Vim features are not implemented:

- |if_py|: vim.bindeval() and vim.Function() are not supported
- |if_lua|: the `vim` object is missing most legacy methods
- *if_perl*
- *if_mzscheme*
- *if_tcl*

==============================================================================
6. Removed features					 *nvim-features-removed*

These Vim features were intentionally removed from Nvim.

			*'cp'* *'nocompatible'* *'nocp'* *'compatible'*
Nvim is always "non-compatible" with Vi.
  ":set nocompatible" is ignored
  ":set compatible" is an error

			*'ed'* *'edcompatible'* *'noed'* *'noedcompatible'*
Ed-compatible mode:
  ":set noedcompatible" is ignored
  ":set edcompatible" is an error

			*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. For
example, 'guicursor' sets the terminal cursor style if possible.

			*:set-termcap*
Start Nvim with 'verbose' level 3 to see the 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.

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

'ttyfast':
  ":set ttyfast" is ignored
  ":set nottyfast" is an error

Encryption support:
  *'cryptmethod'* *'cm'*
  *'key'*

MS-DOS support:
  'bioskey'
  'conskey'

Test functions:
  test_alloc_fail()
  test_autochdir()
  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()

Other options:
  'antialias'
  'cpoptions' (g j k H w < * - and all POSIX flags were removed)
  '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'*
  *'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'*
  'weirdinvert'

Other commands:
  :Print
  :fixdel
  :helpfind
  :mode (no longer accepts an argument)
  :open
  :shell
  :smile
  :tearoff

Other compile-time features:
  EBCDIC
  Emacs tags support
  X11 integration (see |x11-selection|)

Nvim does not have a built-in GUI and hence the following aliases have been
removed: gvim, gex, gview, rgvim, rgview

"Easy mode" (eview, evim, nvim -y)
"(g)vimdiff" (alias for "(g)nvim -d" |diff-mode|)
"Vi mode" (nvim -v)

The ability to start nvim via the following aliases has been removed in favor
of just using their command line arguments:

  ex        nvim -e
  exim      nvim -E
  view      nvim -R
  rvim      nvim -Z
  rview     nvim -RZ

==============================================================================
 vim:tw=78:ts=8:noet:ft=help:norl: