Quick links: help overview · quick reference · user manual toc · reference manual toc
Go to keyword (shortcut: k)
Site search (shortcut: s)
dev_vimpatch.txt          Nvim

                            NVIM REFERENCE MANUAL

Merging patches from Vim                                    dev-vimpatch


Nvim was forked from Vim 7.4.160; it is kept up-to-date with relevant Vim
patches in order to avoid duplicate work. Run vim-patch.sh
https://github.com/neovim/neovim/blob/master/scripts/vim-patch.sh to see the
status of Vim patches:
>bash
    ./scripts/vim-patch.sh -l
<
Everyone is welcome to dev-vimpatch-pull-requests for relevant Vim
patches, but some types of patches are dev-vimpatch-not-applicable.
See dev-vimpatch-quickstart to get started immediately.


                                         Type gO to see the table of contents.

==============================================================================
QUICKSTART                                        dev-vimpatch-quickstart

1. Pull the Nvim source:
>bash
    git clone https://github.com/neovim/neovim.git
<
2. Run `./scripts/vim-patch.sh -l` to see the list of missing Vim patches.

3. Choose a patch from the list (usually the oldest one), e.g. 8.0.0123.

   - Check for open vim-patch PRs
     https://github.com/neovim/neovim/pulls?q=is%3Apr+is%3Aopen+label%3Avim-patch.

4. Run `./scripts/vim-patch.sh -p 8.0.0123`

5. Follow the instructions given by the script.

NOTES 

- It's strongly recommended to work on the oldest missing patch, because
  later patches might depend on the changes.
- Use `git log --grep` or `git log -G` to search the Nvim/Vim source history
  (even deleted code). E.g. to find reset_option_was_set: >bash

    git log -p -G reset_option_was_set
<
- Pass `git log` options like --grep and -G to `./scripts/vim-patch.sh -L`
  to filter unmerged Vim patches E.g. to find +quickfix patches: >bash

    ./scripts/vim-patch.sh -L --grep quickfix -- src
<
==============================================================================
PULL REQUESTS                                  dev-vimpatch-pull-requests

Note: vim-patch.sh automates these steps for you. Use it!

- Install gh (https://cli.github.com/) if you want to use vim-patch.sh to
  create PRs automatically
- The pull request title should include vim-patch:8.x.xxxx (no whitespace)
- The commit message
  https://github.com/neovim/neovim/commit/4ccf1125ff569eccfc34abc4ad794044c5ab7455
  should include:
    - A token indicating the Vim patch number, formatted as follows:
      vim-patch:8.0.0123 (no whitespace)
    - A URL pointing to the Vim commit:
      https://github.com/vim/vim/commit/c8020ee825b9d9196b1329c0e097424576fc9b3a
    - The original Vim commit message, including author

Reviewers: hint for reviewing runtime/ patches
https://github.com/neovim/neovim/pull/1744#issuecomment-68202876

==============================================================================
NA (NOT APPLICABLE) PATCHES                    dev-vimpatch-not-applicable

Many Vim patches are not applicable to Nvim. If you find NA patches, visit an
open "version.c: update" pull request
https://github.com/neovim/neovim/pulls?q=is%3Apr+author%3Aapp%2Fgithub-actions+version.c+is%3Aopen
and mention the NA patches in a comment (please edit/update one comment,
rather than adding a new comment for each patch).

If there are no open `version.c: update` pull requests, include NA patches in
a commit message in the following format:

    vim-patch:<version-or-commit>
    vim-patch:<version-or-commit>
    ...

where <version-or-commit> is a valid Vim version (like 8.0.0123) or
commit-id (SHA). Each patch is on a separate line.

It is preferred to include NA patches by squashing it in applicable Vim
patches, especially if the Vim patches are related. First line of the commit
message should be from the applicable Vim patch.

    ./scripts/vim-patch -p <na-patch>
    ./scripts/vim-patch -p <na-patch>
    ...
    ./scripts/vim-patch -P <patch>
    git rebase -i master

Example:
https://github.com/neovim/neovim/commit/00f60c2ce78fc1280e93d5a36bc7b2267d5f4ac6

TYPES OF "NOT APPLICABLE" VIM PATCHES 

- Vim9script features, and anything related to :scriptversion. (Nvim
  supports Vimscript version 1 only.) Be aware that patches labelled Vim9:
  may still contain applicable fixes to other parts of the codebase, so these
  patch need to be checked individually.
- Updates to testdir/Makefile are usually NA because the Makefile implicitly
  finds
  https://github.com/neovim/neovim/commit/8a677f8a4bff6005fa39f090c14e970c3dfdbe6e#diff-b3c6ad6680a25a1b42095879e3a87104R52
  all test_*.vim files.
- Compiler warning fixes: Nvim strives to have no warnings at all, and has a
  very different build system from Vim.
    - Note: Coverity fixes in Vim are relevant to Nvim.
- *.proto changes: Nvim autogenerates function prototypes
- #ifdef tweaking: For example, Vim decided to enable FEAT_VISUAL for all
  platforms - but Nvim already does that. Adding new FEAT_ guards also isn't
  relevant to Nvim.
- Legacy system support: Fixes for legacy systems such as Amiga, OS/2 Xenix,
  Mac OS 9, Windows older than XP SP2, are not needed because they are not
  supported by Nvim.
    - NA files: src/Make_*, src/testdir/Make__*
- if_*.c changes: if_python.c et. al. were removed.
- term.c changes: the Nvim TUI uses libtermkey to read terminal sequences;
  Vim's term.c was removed.
- job patches: incompatible API and implementation
    - NA files: src/channel_*, src/job_*, src/testdir/test_channel_*,
      src/testdir/test_job_*
- :terminal patches that modify NA files: incompatible API and
  implementation
    - NA files: src/terminal_*, src/testdir/test_terminal_*
- defaults.vim patches
- Most GUI-related changes: Nvim GUIs are implemented external to the core C
  codebase.
    - NA files: src/gui_*, src/gvim_*, src/GvimExt/*, src/testdir/test_gui*
- balloon changes: Nvim does not support balloon feature
    - NA files: src/beval_*, src/testdir/test_balloon_*
- libvterm changes: Nvim does not vendor libvterm in src/.
- Screendump tests from test_popupwin.vim, test_popupwin_textprop.vim:
  https://github.com/neovim/neovim/pull/12741#issuecomment-704677141
- json changes: incompatible API https://github.com/neovim/neovim/pull/4131
    - NA files: src/json*, src/testdir/test_json.vim
- test_restricted.vim restricted mode is removed in
  https://github.com/neovim/neovim/pull/11996
- Many tests in test_prompt_buffer.vim require incompatible Vim features
  such as channel; they should still be included, but skipped
- non-runtime documentation: Moved to https://neovim.io/doc/,
    - NA files: Filelist, README, INSTALL,
- Anything else might be relevant; err on the side of caution, and post an
  issue if you aren't sure.

==============================================================================
VERSION.C                                          dev-vimpatch-version.c

The list of Vim patches in src/nvim/version.c is automatically updated
https://github.com/neovim/neovim/pull/7780 based on the presence of
vim-patch:xxx tokens in the Nvim git log.

- Don't update src/nvim/version.c yourself.
    - `scripts/vim-patch.sh -p` intentionally omits version.c to avoid merge
      conflicts and save time when porting a patch.
- The automation script (`scripts/vimpatch.lua`) only recognizes tokens like
  vim-patch:8.0.1206, not vim-patch:<hash>.

==============================================================================
CODE DIFFERENCES                            dev-vimpatch-code-differences

The following functions have been removed or deprecated in favor of newer
alternatives. See memory.c
https://github.com/neovim/neovim/blob/master/src/nvim/memory.c for more
information.

  -----------------------------------------------------------------------
  Deprecated or removed                                 Replacement
  -----------------------------------------------------------------------
  vim_free                                                 xfree
  VIM_CLEAR(&foo)                                    XFREE_CLEAR(foo)
  malloc alloc lalloc lalloc_id ALLOC_ONE                 xmalloc
  calloc lalloc_clear                                     xcalloc
  realloc vim_realloc                                    xrealloc
  mch_memmove                                             memmove
  vim_memset copy_chars copy_spaces                       memset
  vim_strbyte                                             strchr
  vim_strncpy strncpy                               xstrlcpy/xmemcpyz
  vim_strcat strncat                                     xstrlcat
  VIM_ISWHITE                                          ascii_iswhite
  IS_WHITE_OR_NUL                                  ascii_iswhite_or_nul
  vim_isalpha                                           mb_isalpha
  vim_isNormalIDc                                      ascii_isident
  vim_islower vim_isupper                          mb_islower mb_isupper
  vim_tolower vim_toupper                          mb_tolower mb_toupper
  mb_ptr2len                                           utfc_ptr2len
  mb_ptr2len_len                                     utfc_ptr2len_len
  mb_char2len                                          utf_char2len
  mb_char2bytes                                       utf_char2bytes
  mb_ptr2cells                                         utf_ptr2cells
  mb_ptr2cells_len                                   utf_ptr2cells_len
  mb_char2cells                                       utf_char2cells
  mb_off2cells                                         utf_off2cells
  mb_ptr2char                                          utf_ptr2char
  mb_head_off                                          utf_head_off
  mb_tail_off                                          utf_cp_bounds
  mb_lefthalve                                        grid_lefthalve
  mb_fix_col                                           grid_fix_col
  utf_off2cells                                       grid_off2cells
  ml_get_curline                                    get_cursor_line_ptr
  ml_get_cursor                                     get_cursor_pos_ptr
  ml_get_curline_len                                get_cursor_line_len
  ml_get_cursor_len                                 get_cursor_pos_len
  screen_char                                             ui_line
  screen_line                                        grid_put_linebuf
  screen_* (most functions)                               grid_*
  update_prepare, update_finish #9484                  removed; use update_screen only
  ARRAY_LENGTH                                          ARRAY_SIZE
  vim_strsave_escape_csi                           vim_strsave_escape_ks
  vim_unescape_csi                                    vim_unescape_ks
  gettail                                                path_tail
  mch_isFullName                                     path_is_absolute
  script_do_profile                                    profile_init

  -----------------------------------------------------------------------

Make sure to note the difference between utf_ and utfc_ when replacing
mb_ functions. Also indirect call syntax (*mb_ptr2len)(...) should be
replaced with an ordinary function call utfc_ptr2len(...).

  -----------------------------------------------------------------------
  Data type    Format (Vim source)     Portable format (Nvim source)
  ------------ ----------------------- ----------------------------------
  long long    "%lld"                  "%" PRId64
  size_t       "%ld"                   "%zu"
  linenr_T     "%ld"                   "%" PRIdLINENR
  -----------------------------------------------------------------------

- See also: https://github.com/neovim/neovim/pull/1729#discussion_r22423779
- Vim's ga_init2 was renamed to ga_init and the original ga_init is
  gone.
- "Old style" Vim tests (`src/testdir/*.in`) should be converted to Lua tests
  (see #1286 https://github.com/neovim/neovim/issues/1286 and #1328
  https://github.com/neovim/neovim/pull/1328). See Checklist for migrating
  legacy tests
  https://github.com/neovim/neovim/blob/master/test/README.md#checklist-for-migrating-legacy-tests.
    - However, please do not convert "new style" Vim tests
      (`src/testdir/*.vim`) to Lua. The "new style" Vim tests are faster than
      the old ones, and converting them takes time and effort better spent
      elsewhere. Just copy them to test/old/testdir/*.vim.
- Conditions that check enc_utf8 or has_mbyte are obsolete (only the
  "true" case is applicable).
    - enc_utf8 and has_mbyte macros were removed in
      https://github.com/neovim/neovim/pull/13293
- Check for CSI in typeahead buffer is only necessary in Vim with
  FEAT_GUI. CSI does not have a special meaning in typeahead buffer in
  Nvim. (also see https://github.com/neovim/neovim/pull/16936)

==============================================================================
LIST MANAGEMENT                              dev-vimpatch-list-management

Management of lists (types list_T and listitem_T from vim) was changed in
https://github.com/neovim/neovim/pull/7708/. There is a lint against the "old"
usage, but here are the most important changes.

Declarations for the table

- `list_T list`: a list
- `listitem_T li`: an item of list
- `int val` a value for lv_copyID


  --------------------------------------------------------------------------------------
  Old                             New                                  Comment
  ------------------------------- ------------------------------------------------------
  list->lv_first                  tv_list_first(list)
  list->lv_last                   tv_list_last(list)
  li->li_next                     TV_LIST_ITEM_NEXT(list, li)          To be avoided if possible, must use list which li belongs to.
  li->li_prev                     TV_LIST_ITEM_PREV(list, li)          To be avoided if possible, must use list which li belongs to.
                                  Suggestion by @ZyX-l:                Use TV_LIST_ITER or indexing instead of the previous two calls.
  list->lv_len                    tv_list_len(list)
  list->lv_lock                   tv_list_locked(list)
  &li->li_tv                      TV_LIST_ITEM_TV(li)
  list->lv_refcount++             tv_list_ref(list)
  val = list->lv_copyID           val = tv_list_copyid(list)
  list->lv_copyID = val           tv_list_set_copyid(list, val)

  for (li = list->lv_first;       TV_LIST_ITER_CONST(list, li,         Use TV_LIST_ITER(...) if you need to
  li != NULL && another_cond;     { if (another_cond) {break;} code})  modify list items (note: assigning copyID is also modification and this happens
  li = li->li_next) code                                               always when recursively traversing a list).

  --------------------------------------------------------------------------------------

For more details and some more advanced usage, see typval.h and typval.c.

==============================================================================
DOCUMENTATION DIFFERENCES          dev-vimpatch-documentation

The following should be removed from all imported documentation, and not be
used in new documentation:

- `{Only when compiled with ...}`: the vast majority of features have been
  made non-optional (see https://github.com/neovim/neovim/wiki/Introduction)

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


Quick links: help overview · quick reference · user manual toc · reference manual toc