dev_vimpatch.txt (18204B)
1 *dev_vimpatch.txt* Nvim 2 3 NVIM REFERENCE MANUAL 4 5 Merging patches from Vim *dev-vimpatch* 6 7 8 Nvim was forked from Vim 7.4.160; it is kept up-to-date with relevant Vim 9 patches in order to avoid duplicate work. Run `vim-patch.sh` 10 https://github.com/neovim/neovim/blob/master/scripts/vim-patch.sh to see the 11 status of Vim patches: 12 >bash 13 ./scripts/vim-patch.sh -l 14 < 15 Everyone is welcome to |dev-vimpatch-pull-requests| for relevant Vim 16 patches, but some types of patches are |dev-vimpatch-not-applicable|. 17 See |dev-vimpatch-quickstart| to get started immediately. 18 19 20 Type |gO| to see the table of contents. 21 22 ============================================================================== 23 QUICKSTART *dev-vimpatch-quickstart* 24 25 1. Pull the Nvim source: >bash 26 git clone https://github.com/neovim/neovim.git 27 2. Run `./scripts/vim-patch.sh -l` to see the list of missing Vim patches. 28 3. Choose a patch from the list (usually the oldest one), e.g. `8.0.0123`. 29 - Check for open vim-patch PRs 30 https://github.com/neovim/neovim/pulls?q=is%3Apr+is%3Aopen+label%3Avim-patch. 31 4. Run `./scripts/vim-patch.sh -p 8.0.0123` 32 5. Follow the instructions given by the script. 33 34 NOTES ~ 35 36 - It's strongly recommended to work on the oldest missing patch, because 37 later patches might depend on the changes. 38 - Use `git log --grep` or `git log -G` to search the Nvim/Vim source history 39 (even deleted code). E.g. to find `reset_option_was_set`: >bash 40 41 git log -p -G reset_option_was_set 42 < 43 - Pass `git log` options like `--grep` and `-G` to `./scripts/vim-patch.sh -L` 44 to filter unmerged Vim patches E.g. to find `+quickfix` patches: >bash 45 46 ./scripts/vim-patch.sh -L --grep quickfix -- src 47 < 48 ============================================================================== 49 PULL REQUESTS *dev-vimpatch-pull-requests* 50 51 Note: vim-patch.sh automates these steps for you. Use it! 52 53 - Install `gh` (https://cli.github.com/) if you want to use `vim-patch.sh` to 54 create PRs automatically 55 - The pull request title should include `vim-patch:8.x.xxxx` (no whitespace) 56 - The commit message 57 https://github.com/neovim/neovim/commit/4ccf1125ff569eccfc34abc4ad794044c5ab7455 58 should include: 59 - A token indicating the Vim patch number, formatted as follows: 60 `vim-patch:8.0.0123` (no whitespace) 61 - A URL pointing to the Vim commit: 62 https://github.com/vim/vim/commit/c8020ee825b9d9196b1329c0e097424576fc9b3a 63 - The original Vim commit message, including author 64 65 Reviewers: hint for reviewing `runtime/` patches 66 https://github.com/neovim/neovim/pull/1744#issuecomment-68202876 67 68 ============================================================================== 69 NA (NOT APPLICABLE) PATCHES *dev-vimpatch-not-applicable* 70 71 Many Vim patches are not applicable to Nvim. If you find NA patches, visit an 72 open "version.c: update" pull request 73 https://github.com/neovim/neovim/pulls?q=is%3Apr+author%3Aapp%2Fgithub-actions+version.c+is%3Aopen 74 and mention the NA patches in a comment (please edit/update one comment, 75 rather than adding a new comment for each patch). 76 77 If there are no open `version.c: update` pull requests, include NA patches in 78 a commit message in the following format: 79 > 80 vim-patch:<version-or-commit> 81 vim-patch:<version-or-commit> 82 ... 83 < 84 where `<version-or-commit>` is a valid Vim version (like `8.0.0123`) or 85 commit-id (SHA). Each patch is on a separate line. 86 87 It is preferred to include NA patches by squashing it in applicable Vim 88 patches, especially if the Vim patches are related. First line of the commit 89 message should be from the applicable Vim patch. 90 > 91 ./scripts/vim-patch -p <na-patch> 92 ./scripts/vim-patch -p <na-patch> 93 ... 94 ./scripts/vim-patch -P <patch> 95 git rebase -i master 96 < 97 Example: 98 https://github.com/neovim/neovim/commit/00f60c2ce78fc1280e93d5a36bc7b2267d5f4ac6 99 100 TYPES OF "NOT APPLICABLE" VIM PATCHES ~ 101 102 - Vim9script features, and anything related to `:scriptversion`. (Nvim 103 supports Vimscript version 1 only.) Be aware that patches labelled `Vim9:` 104 may still contain applicable fixes to other parts of the codebase, so these 105 patch need to be checked individually. 106 - Updates to `testdir/Makefile` are usually NA because the Makefile implicitly 107 finds 108 https://github.com/neovim/neovim/commit/8a677f8a4bff6005fa39f090c14e970c3dfdbe6e#diff-b3c6ad6680a25a1b42095879e3a87104R52 109 all `test_*.vim` files. 110 - Compiler warning fixes: Nvim strives to have no warnings at all, and has a 111 very different build system from Vim. 112 - Note: Coverity fixes in Vim are relevant to Nvim. 113 - `*.proto` changes: Nvim autogenerates function prototypes 114 - `#ifdef` tweaking: For example, Vim decided to enable `FEAT_VISUAL` for all 115 platforms - but Nvim already does that. Adding new `FEAT_` guards also isn't 116 relevant to Nvim. 117 - Legacy system support: Fixes for legacy systems such as Amiga, OS/2 Xenix, 118 Mac OS 9, Windows older than XP SP2, are not needed because they are not 119 supported by Nvim. 120 - NA files: `src/Make_*`, `src/testdir/Make__*` 121 - `if_*.c` changes: `if_python.c` et. al. were removed. 122 - Most `term.c` changes: the Nvim TUI uses `libtermkey` to read terminal sequences; 123 Note: `replace_termcodes()` is applicable and moved to `src/nvim/keycodes.c`. 124 - `job` patches: incompatible API and implementation 125 - NA files: `src/channel_*`, `src/job_*`, `src/testdir/test_channel_*`, 126 `src/testdir/test_job_*` 127 - `:terminal` patches that modify NA files: incompatible API and 128 implementation 129 - NA files: `src/terminal_*`, `src/testdir/test_terminal_*` 130 - `defaults.vim` patches 131 - Most GUI-related changes: Nvim GUIs are implemented external to the core C 132 codebase. 133 - NA files: `src/gui_*`, `src/gvim_*`, `src/GvimExt/*`, `src/testdir/test_gui*` 134 - `balloon` changes: Nvim does not support balloon feature 135 - NA files: `src/beval_*`, `src/testdir/test_balloon_*` 136 - Screendump tests from `test_popupwin.vim`, `test_popupwin_textprop.vim`: 137 https://github.com/neovim/neovim/pull/12741#issuecomment-704677141 138 - json changes: incompatible API https://github.com/neovim/neovim/pull/4131 139 - NA files: `src/json*`, `src/testdir/test_json.vim` 140 - `test_restricted.vim` restricted mode is removed in 141 https://github.com/neovim/neovim/pull/11996 142 - Many tests in `test_prompt_buffer.vim` require incompatible Vim features 143 such as `channel`; they should still be included, but skipped 144 - Non-runtime documentation: Moved to `BUILD.md`, `INSTALL.md`. 145 - NA files: `Filelist`, `README`, `INSTALL`, 146 - Anything else might be relevant; err on the side of caution, and post an 147 issue if you aren't sure. 148 149 ============================================================================== 150 VERSION.C *dev-vimpatch-version.c* 151 152 The list of Vim patches in `src/nvim/version.c` is automatically updated 153 https://github.com/neovim/neovim/pull/7780 based on the presence of 154 `vim-patch:xxx` tokens in the Nvim git log. 155 156 - Don't update `src/nvim/version.c` yourself. 157 - `scripts/vim-patch.sh -p` intentionally omits `version.c` to avoid merge 158 conflicts and save time when porting a patch. 159 - The automation script (`scripts/vimpatch.lua`) only recognizes tokens like 160 `vim-patch:8.0.1206`, not `vim-patch:<hash>`. 161 162 ============================================================================== 163 CODE DIFFERENCES *dev-vimpatch-code-differences* 164 165 The following functions have been removed or deprecated in favor of newer 166 alternatives. See `memory.c` 167 https://github.com/neovim/neovim/blob/master/src/nvim/memory.c for more 168 information. 169 > 170 ----------------------------------------------------------------------- 171 Deprecated or removed Replacement 172 ----------------------------------------------------------------------- 173 vim_free xfree 174 VIM_CLEAR(&foo) XFREE_CLEAR(foo) 175 malloc alloc lalloc lalloc_id ALLOC_ONE xmalloc 176 calloc lalloc_clear xcalloc 177 realloc vim_realloc xrealloc 178 mch_memmove memmove 179 vim_memset copy_chars copy_spaces memset 180 vim_strbyte strchr 181 vim_strncpy strncpy xstrlcpy/xmemcpyz 182 vim_strcat strncat xstrlcat 183 VIM_ISWHITE ascii_iswhite 184 IS_WHITE_OR_NUL ascii_iswhite_or_nul 185 IS_WHITE_NL_OR_NUL ascii_iswhite_nl_or_nul 186 vim_isalpha mb_isalpha 187 vim_isNormalIDc ascii_isident 188 vim_islower vim_isupper mb_islower mb_isupper 189 vim_tolower vim_toupper mb_tolower mb_toupper 190 mb_ptr2len utfc_ptr2len 191 mb_ptr2len_len utfc_ptr2len_len 192 mb_char2len utf_char2len 193 mb_char2bytes utf_char2bytes 194 mb_ptr2cells utf_ptr2cells 195 mb_ptr2cells_len utf_ptr2cells_len 196 mb_char2cells utf_char2cells 197 mb_off2cells utf_off2cells 198 mb_ptr2char utf_ptr2char 199 mb_head_off utf_head_off 200 mb_tail_off utf_cp_bounds 201 mb_strnicmp2 utf_strnicmp 202 MB_STRNICMP2 utf_strnicmp 203 mb_lefthalve grid_lefthalve 204 mb_fix_col grid_fix_col 205 utf_off2cells grid_off2cells 206 ml_get_curline get_cursor_line_ptr 207 ml_get_cursor get_cursor_pos_ptr 208 ml_get_curline_len get_cursor_line_len 209 ml_get_cursor_len get_cursor_pos_len 210 screen_char ui_line 211 screen_line grid_put_linebuf 212 screen_* (most functions) grid_* 213 update_prepare, update_finish #9484 removed; use update_screen only 214 ARRAY_LENGTH ARRAY_SIZE 215 vim_strsave_escape_csi vim_strsave_escape_ks 216 vim_unescape_csi vim_unescape_ks 217 gettail path_tail 218 mch_isFullName path_is_absolute 219 script_do_profile profile_init 220 221 ----------------------------------------------------------------------- 222 < 223 Make sure to note the difference between `utf_` and `utfc_` when replacing 224 `mb_` functions. Also indirect call syntax `(*mb_ptr2len)(...)` should be 225 replaced with an ordinary function call `utfc_ptr2len(...)`. 226 > 227 ----------------------------------------------------------------------- 228 Data type Format (Vim source) Portable format (Nvim source) 229 ------------ ----------------------- ---------------------------------- 230 long long "%lld" "%" PRId64 231 size_t "%ld" "%zu" 232 linenr_T "%ld" "%" PRIdLINENR 233 ----------------------------------------------------------------------- 234 < 235 - See also: https://github.com/neovim/neovim/pull/1729#discussion_r22423779 236 - Vim's `ga_init2` was renamed to `ga_init` and the original `ga_init` is 237 gone. 238 - "Old style" Vim tests (`src/testdir/*.in`) should be converted to Lua tests 239 (see #1286 https://github.com/neovim/neovim/issues/1286 and #1328 240 https://github.com/neovim/neovim/pull/1328). See Checklist for migrating 241 legacy tests 242 https://github.com/neovim/neovim/blob/master/test/README.md#checklist-for-migrating-legacy-tests. 243 - However, please do not convert "new style" Vim tests 244 (`src/testdir/*.vim`) to Lua. The "new style" Vim tests are faster than 245 the old ones, and converting them takes time and effort better spent 246 elsewhere. Just copy them to `test/old/testdir/*.vim`. 247 - Conditions that check `enc_utf8` or `has_mbyte` are obsolete (only the 248 "true" case is applicable). 249 - `enc_utf8` and `has_mbyte` macros were removed in 250 https://github.com/neovim/neovim/pull/13293 251 - Check for `CSI` in typeahead buffer is only necessary in Vim with 252 `FEAT_GUI`. `CSI` does not have a special meaning in typeahead buffer in 253 Nvim. (also see https://github.com/neovim/neovim/pull/16936) 254 255 ============================================================================== 256 LIST MANAGEMENT *dev-vimpatch-list-management* 257 258 Management of lists (types `list_T` and `listitem_T` from vim) was changed in 259 https://github.com/neovim/neovim/pull/7708/. There is a lint against the "old" 260 usage, but here are the most important changes. 261 262 Declarations for the table 263 264 - `list_T list`: a list 265 - `listitem_T li`: an item of `list` 266 - `int val` a value for `lv_copyID` 267 268 > 269 -------------------------------------------------------------------------------------- 270 Old New Comment 271 ------------------------------- ------------------------------------------------------ 272 list->lv_first tv_list_first(list) 273 list->lv_last tv_list_last(list) 274 li->li_next TV_LIST_ITEM_NEXT(list, li) To be avoided if possible, must use list which li belongs to. 275 li->li_prev TV_LIST_ITEM_PREV(list, li) To be avoided if possible, must use list which li belongs to. 276 Suggestion by @ZyX-l: Use TV_LIST_ITER or indexing instead of the previous two calls. 277 list->lv_len tv_list_len(list) 278 list->lv_lock tv_list_locked(list) 279 &li->li_tv TV_LIST_ITEM_TV(li) 280 list->lv_refcount++ tv_list_ref(list) 281 val = list->lv_copyID val = tv_list_copyid(list) 282 list->lv_copyID = val tv_list_set_copyid(list, val) 283 284 for (li = list->lv_first; TV_LIST_ITER_CONST(list, li, Use TV_LIST_ITER(...) if you need to 285 li != NULL && another_cond; { if (another_cond) {break;} code}) modify list items (note: assigning copyID is also modification and this happens 286 li = li->li_next) code always when recursively traversing a list). 287 288 -------------------------------------------------------------------------------------- 289 < 290 For more details and some more advanced usage, see `typval.h` and `typval.c`. 291 292 ============================================================================== 293 DOCUMENTATION DIFFERENCES *dev-vimpatch-documentation* 294 295 The following should be removed from all imported documentation, and not be 296 used in new documentation: 297 298 - `{Only when compiled with ...}`: the vast majority of features have been 299 made non-optional (see https://github.com/neovim/neovim/wiki/Introduction) 300 301 ============================================================================== 302 FILETYPE DETECTION *dev-vimpatch-filetype* 303 304 Nvim's filetype detection behavior matches Vim, but is implemented as part of 305 |vim.filetype| (see `$VIMRUNTIME/lua/vim/filetype.lua`). The logic is encoded in 306 three tables, listed in order of precedence (the first match is returned): 307 1. `filename` for literal full path or basename lookup; 308 2. `pattern` for matching filenames or paths against |lua-pattern|s, optimized 309 for fast lookup; 310 3. `extension` for literal extension lookup. 311 312 Logic that requires checking file contents or buffer variables is implemented 313 in `$VIMRUNTIME/lua/vim/filetype/detect.lua`. 314 315 When porting filetype patches from Vim, keep the following in mind: 316 317 Prefer explicit filenames or extensions over patterns, especially for case 318 insensitive matches (see https://github.com/neovim/neovim/pull/29800): > 319 "*[mM]akefile" regex -> "makefile", "Makefile" filenames 320 "*.js\c" regex -> "js", "jS", "Js", "jS" extensions 321 322 Pattern matching has several differences: 323 - It is done using explicit Lua patterns without implicit anchoring instead 324 of Vim regexes: > 325 "*/debian/changelog" -> "/debian/changelog$" 326 "*/bind/db.*" -> "/bind/db%." 327 < 328 - Filetype patterns are grouped by their parent pattern to improve matching 329 performance: If the parent pattern does not match, skip testing all child 330 patterns. Note that unlike leaf patterns, parent patterns do not have 331 special matching behaviour if they contain a `/`. 332 333 When adding a new filetype with pattern matching, consider the following: 334 - If there is already a group with appropriate parent pattern, use it. 335 - If there can be a fast and specific enough pattern to group at least 3 336 filetype patterns, add it as a separate grouped entry. 337 338 New parent patterns should be 339 - fast: rule of thumb is that it should be a short explicit string 340 (i.e. no quantifiers or character sets); 341 - specific: rules of thumb, in order: 342 - full directory name (e.g., `"/etc/"`, `"/log/"`); 343 - part of a rare enough directory name (e.g., `"/conf"`, `"git/"`); 344 - string rarely used in real full paths (e.g., `"nginx"`). 345 346 Example: 347 - Filetype pattern: `".*/etc/a2ps/.*%.cfg"` 348 - Good parents: `"/etc/"` or `"%.cfg$"` 349 - Bad parents: `"%."` (fast but not specific) or `"/a2ps/.*%."` (specific 350 but slow) 351 352 When modifying an existing regular pattern, make sure that it still fits its 353 group. 354 355 vim:tw=78:ts=8:noet:ft=help:norl: