From 43398547ec72c99ab0b90837c02de4a0add77b04 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 19 Apr 2026 08:36:19 -0400 Subject: [PATCH] backport docs: misc (#39206) docs: misc (cherry picked from commit 54398c587473c0f1d96b601a281477e184865401) --- .github/ISSUE_TEMPLATE/bug_report.yml | 15 +- .github/workflows/notes.md | 2 +- INSTALL.md | 46 ++- runtime/doc/autocmd.txt | 348 +++++++++++++------- runtime/doc/dev.txt | 7 +- runtime/doc/filetype.txt | 15 + runtime/doc/help.txt | 15 +- runtime/doc/insert.txt | 2 +- runtime/doc/lsp.txt | 33 +- runtime/doc/lua.txt | 50 +-- runtime/doc/pack.txt | 2 +- runtime/lua/vim/_core/options.lua | 30 +- runtime/lua/vim/_meta/api_keysets_extra.lua | 5 +- runtime/lua/vim/_meta/events.lua | 3 + runtime/lua/vim/fs.lua | 35 +- runtime/lua/vim/pack.lua | 2 +- runtime/lua/vim/ui.lua | 13 +- test/functional/plugin/lsp/util_spec.lua | 10 +- 18 files changed, 387 insertions(+), 246 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 8a9c621916..8ec8ba9049 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -7,16 +7,15 @@ body: attributes: value: | *Before reporting:* - - Confirm the problem is reproducible on [**master**](https://github.com/neovim/neovim/releases/nightly) or [**latest stable**](https://github.com/neovim/neovim/releases/stable) release - - Run `make distclean` when encountering build issues + - Confirm the problem is reproducible in the [latest **nightly** release](https://github.com/neovim/neovim/releases/nightly). + - Run `make distclean` when encountering build issues. - Search [existing issues](https://github.com/neovim/neovim/issues?q=is%3Aissue%20is%3Aopen%20type%3ABug) (including [closed](https://github.com/neovim/neovim/issues?q=is%3Aissue%20is%3Aclosed%20type%3ABug)) - - Read the [FAQ](https://neovim.io/doc/user/faq.html) and ["Reporting Problems" in CONTRIBUTING.md](https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md#reporting-problems). - - Usage or "How to" questions belong on [stackoverflow](https://vi.stackexchange.com/) and will be closed. + - Read the [FAQ](https://neovim.io/doc/user/faq/) and ["Reporting Problems" in CONTRIBUTING.md](https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md#reporting-problems). + - Usage or "How to" questions will be closed, use [Discussions](https://github.com/neovim/neovim/discussions) or [stackoverflow](https://vi.stackexchange.com/) instead. - type: textarea attributes: label: "Problem" - description: "Describe the current behavior. May include logs, images, or videos." + description: "Describe the problem concisely. May include logs, images, or videos." validations: required: true - type: textarea @@ -24,10 +23,10 @@ body: label: "Steps to reproduce" description: | - For build failures: list the exact steps including CMake flags (if any). - - If the bug pertains to crashing (or segfault), please include a [stacktrace](https://neovim.io/doc/user/dev_tools.html#dev-tools-backtrace). + - If the bug is a crash/segfault, please include a [stacktrace](https://neovim.io/doc/user/dev_tools/#dev-tools-backtrace). - For startup or shell-related problems: try `env -i TERM=ansi-256color "$(which nvim)"`. - Use the provided [minimal reproduction template](https://github.com/neovim/neovim/blob/master/contrib/minimal.lua) to create a minimal configuration. After you fill it out with necessary information, run with `nvim --clean -u minimal.lua`. - - Please do **not** include a package manager in the reproduction steps. + - Do **not** include a package manager in the reproduction steps. placeholder: | nvim --clean :edit foo diff --git a/.github/workflows/notes.md b/.github/workflows/notes.md index b6958a6686..bf7b1dc095 100644 --- a/.github/workflows/notes.md +++ b/.github/workflows/notes.md @@ -23,7 +23,7 @@ ${NVIM_VERSION} 2. Run the MSI 3. Run `nvim.exe` in your terminal -Note: On Windows "Server" you may need to [install vcruntime140.dll](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist?view=msvc-170). +Note: On Windows "Server" you may need to [install `vcruntime*.dll`](https://neovim.io/doc/install/#windows). ### macOS (x86_64) diff --git a/INSTALL.md b/INSTALL.md index e213e98978..934128507c 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -36,38 +36,54 @@ Windows 8+ is required. Windows 7 or older is not supported. ### [Winget](https://docs.microsoft.com/en-us/windows/package-manager/winget/) - **Release:** `winget install Neovim.Neovim` +- **Nightly:** [Not supported by winget](https://github.com/neovim/neovim/issues/38585) ### [Chocolatey](https://chocolatey.org) -- **Latest Release:** `choco install neovim` (use -y for automatically skipping confirmation messages) -- **Development (pre-release):** `choco install neovim --pre` +- **Release:** `choco install neovim` (use -y for automatically skipping confirmation messages) +- **Nightly:** `choco install neovim --pre` ### [Scoop](https://scoop.sh/) + ```bash scoop bucket add main scoop install neovim ``` -- **Release:** `scoop install neovim` Several Neovim GUIs are available from scoop (extras): [scoop.sh/#/apps?q=neovim](https://scoop.sh/#/apps?q=neovim) -### Pre-built archives +### MSI + +> [!TIP] +> If you are missing `VCRUNTIME170.dll`, install the [Visual Studio C++ redistributable](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist) (choose x86_64 or x86 depending on your system). +> If you have scoop, try: `scoop install vcredist`. + +You can use this powershell script to install the MSI from the [releases page](https://github.com/neovim/neovim/releases): + +- For x86_64: + ```pwsh + iwr -Uri "https://github.com/neovim/neovim/releases/download/nightly/nvim-win64.msi" -OutFile nvim-win64.msi + msiexec /i nvim-win64.msi /passive + rm nvim-win64.msi + ``` +- For arm64: + ```pwsh + iwr -Uri "https://github.com/neovim/neovim/releases/download/nightly/nvim-win-arm64.msi" -OutFile nvim-win-arm64.msi + msiexec /i nvim-win-arm64.msi /passive + rm nvim-win-arm64.msi + ``` + +### Zip -0. If you are missing `VCRUNTIME170.dll`, install the [Visual Studio C++ redistributable](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist) (choose x86_64 or x86 depending on your system). - - Hint: if you have scoop, try: `scoop install vcredist` 1. Choose a package (**nvim-winXX.zip**) from the [releases page](https://github.com/neovim/neovim/releases). 2. Unzip the package. Any location is fine, administrator privileges are _not_ required. - `$VIMRUNTIME` will be set to that location automatically. 3. Run `nvim.exe` from a terminal. +4. (Optional) Add the `bin` folder (e.g. `C:/Program Files/nvim/bin`) to your PATH. + This makes it easy to run `nvim` from any directory. -**Optional** steps: +### Optional steps -- Add the `bin` folder (e.g. `C:\Program Files\nvim\bin`) to your PATH. - - This makes it easy to run `nvim` from anywhere. -- If `:set spell` does not work, create the `%LOCALAPPDATA%/nvim-data/site/spell` folder. - You can then copy your spell files over (for English, located - [here](https://github.com/vim/vim/blob/master/runtime/spell/en.utf-8.spl) and - [here](https://github.com/vim/vim/blob/master/runtime/spell/en.utf-8.sug)); - For Python plugins you need the `pynvim` module. Installation via uv (https://docs.astral.sh/uv/) is recommended; the `--upgrade` switch ensures installation of the latest version: @@ -75,7 +91,7 @@ Several Neovim GUIs are available from scoop (extras): [scoop.sh/#/apps?q=neovim uv tool install --upgrade pynvim ``` - Run `:checkhealth` and read `:help provider-python` for more details. -- **init.vim ("vimrc"):** If you already have Vim installed you can copy `%userprofile%\_vimrc` to `%userprofile%\AppData\Local\nvim\init.vim` to use your Vim config with Neovim. +- **init.vim ("vimrc"):** If you already have Vim installed you can copy `%userprofile%/_vimrc` to `%userprofile%/AppData/Local/nvim/init.vim` to use your Vim config with Neovim. ## macOS / OS X @@ -454,7 +470,7 @@ make CMAKE_BUILD_TYPE=Release sudo make install ``` -For Unix-like systems this installs Neovim to `/usr/local`, while for Windows to `C:\Program Files`. Note, however, that this can complicate uninstallation. The following example avoids this by isolating an installation under `$HOME/neovim`: +For Unix-like systems this installs Neovim to `/usr/local`, while for Windows to `C:/Program Files`. Note, however, that this can complicate uninstallation. The following example avoids this by isolating an installation under `$HOME/neovim`: ```bash rm -r build/ # clear the CMake cache make CMAKE_EXTRA_FLAGS="-DCMAKE_INSTALL_PREFIX=$HOME/neovim" diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index 5b09cc15f6..3d435d8a5f 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -226,16 +226,17 @@ autocommands, this doesn't happen. You can use the 'eventignore' option to ignore a number of events or all events. -Events that provide |event-data| have a matching `vim.event..data` type -defined in `runtime/lua/vim/_meta/events.lua`. You can use @cast to narrow -`ev.data` for type-checking and completion: >lua + *event-data-types* +Events that provide |event-data| have a corresponding `vim.event..data` +type defined in `runtime/lua/vim/_meta/events.lua`. If you have Lua LSP +enabled, you can annotate your handler to get type-checking and completion: >lua - vim.api.nvim_create_autocmd('LspAttach', { - callback = function(ev) - ---@cast ev {data: vim.event.lspattach.data} - local client = vim.lsp.get_client_by_id(ev.data.client_id) - end, - }) + vim.api.nvim_create_autocmd('LspAttach', { + ---@param ev {data: vim.event.lspattach.data} + callback = function(ev) + local client = vim.lsp.get_client_by_id(ev.data.client_id) + end, + }) < *events* *{event}* Nvim recognizes the following events. Names are case-insensitive. @@ -248,6 +249,7 @@ BufAdd After adding a new buffer or existing unlisted Before |BufEnter|. NOTE: Current buffer "%" is not the target buffer "", "". || + *BufDelete* BufDelete Before deleting a buffer from the buffer list. The BufUnload may be called first (if the @@ -257,6 +259,7 @@ BufDelete Before deleting a buffer from the buffer list. NOTE: Current buffer "%" is not the target buffer "", "". || Do not change to another buffer. + *BufEnter* BufEnter After entering (visiting, switching-to) a new or existing buffer. Useful for setting @@ -264,12 +267,15 @@ BufEnter After entering (visiting, switching-to) a new does not trigger for existing buffers. After |BufAdd|. After |BufReadPost|. + *BufFilePost* BufFilePost After changing the name of the current buffer with the ":file" or ":saveas" command. + *BufFilePre* BufFilePre Before changing the name of the current buffer with the ":file" or ":saveas" command. + *BufHidden* BufHidden Before a buffer becomes hidden: when there are no longer windows that show the buffer, but @@ -278,15 +284,18 @@ BufHidden Before a buffer becomes hidden: when there are Not used for ":qa" or ":q" when exiting Vim. NOTE: Current buffer "%" is not the target buffer "", "". || + *BufLeave* BufLeave Before leaving to another buffer. Also when leaving or closing the current window and the new current window is not for the same buffer. Not used for ":qa" or ":q" when exiting Vim. + *BufModifiedSet* BufModifiedSet After the `'modified'` value of a buffer has been changed. Special-case of |OptionSet|. + *BufNew* BufNew After creating a new buffer (except during startup, see |VimEnter|) or renaming an @@ -296,10 +305,12 @@ BufNew After creating a new buffer (except during NOTE: Current buffer "%" is not the target buffer "", "". || See also |BufAdd|, |BufNewFile|. + *BufNewFile* BufNewFile When starting to edit a file that doesn't exist. Can be used to read in a skeleton file. + *BufRead* *BufReadPost* BufRead or BufReadPost When starting to edit a new buffer, after reading the file into the buffer, before @@ -314,13 +325,16 @@ BufRead or BufReadPost When starting to edit a new buffer, after Not triggered: - for the `:read file` command - when the file doesn't exist + *BufReadCmd* BufReadCmd Before starting to edit a new buffer. Should read the file into the buffer. |Cmd-event| + *BufReadPre* *E200* *E201* BufReadPre When starting to edit a new buffer, before reading the file into the buffer. Not used if the file doesn't exist. + *BufUnload* BufUnload Before unloading a buffer, when the text in the buffer is going to be freed. @@ -334,6 +348,7 @@ BufUnload Before unloading a buffer, when the text in Do not switch buffers or windows! Not triggered when exiting and v:dying is 2 or more. + *BufWinEnter* BufWinEnter After a buffer is displayed in a window. This may be when the buffer is loaded (after @@ -345,6 +360,7 @@ BufWinEnter After a buffer is displayed in a window. This with a file already open in a window. Triggered for ":split" with the name of the current buffer, since it reloads that buffer. + *BufWinLeave* BufWinLeave Before a buffer is removed from a window. Not when it's still visible in another window. @@ -354,6 +370,7 @@ BufWinLeave Before a buffer is removed from a window. buffer "", "". || Not triggered when exiting and v:dying is 2 or more. + *BufWipeout* BufWipeout Before completely deleting a buffer. The BufUnload and BufDelete events may be called @@ -364,8 +381,10 @@ BufWipeout Before completely deleting a buffer. The NOTE: Current buffer "%" is not the target buffer "", "". || Do not change to another buffer. + *BufWrite* *BufWritePre* BufWrite or BufWritePre Before writing the whole buffer to a file. + *BufWriteCmd* BufWriteCmd Before writing the whole buffer to a file. Should do the writing of the file and reset @@ -377,9 +396,11 @@ BufWriteCmd Before writing the whole buffer to a file. states as 'modified', like |:write| does. Use the |'[| and |']| marks for the range of lines. |Cmd-event| + *BufWritePost* BufWritePost After writing the whole buffer to a file (should undo the commands for BufWritePre). + *ChanInfo* ChanInfo State of channel changed, for instance the client of a RPC channel described itself. @@ -387,30 +408,21 @@ ChanInfo State of channel changed, for instance the autocommand defined without |autocmd-nested|. Sets these |v:event| keys: info as from |nvim_get_chan_info()| + *ChanOpen* ChanOpen Just after a channel was opened. This is triggered even when inside an autocommand defined without |autocmd-nested|. Sets these |v:event| keys: info as from |nvim_get_chan_info()| - *CmdUndefined* -CmdUndefined When a user command is used but it isn't - defined. Useful for defining a command only - when it's used. The pattern is matched - against the command name. Both and - expand to the command name. - This is triggered even when inside an - autocommand defined without |autocmd-nested|. - NOTE: Autocompletion won't work until the - command is defined. An alternative is to - always define the user command and have it - invoke an autoloaded function. See |autoload|. + *CmdlineChanged* CmdlineChanged After EVERY change inside command line. Also triggered during mappings! Use || instead of ":" in mappings, to avoid that. expands to the |cmdline-char|. + *CmdlineEnter* CmdlineEnter After entering the command-line (including non-interactive use of ":" in a mapping: use @@ -420,6 +432,7 @@ CmdlineEnter After entering the command-line (including Sets these |v:event| keys: cmdlevel cmdtype + *CmdlineLeave* CmdlineLeave Before leaving the command-line (including non-interactive use of ":" in a mapping: use @@ -434,6 +447,7 @@ CmdlineLeave Before leaving the command-line (including Note: `abort` can only be changed from false to true: cannot execute an already aborted cmdline by changing it to false. + *CmdlineLeavePre* CmdlineLeavePre Just before leaving the command line, and before |CmdlineLeave|. Useful for capturing @@ -445,6 +459,20 @@ CmdlineLeavePre Just before leaving the command line, and abandoning the command line by typing CTRL-C or . is set to |cmdline-char|. Sets |v:char| as with |CmdlineLeave|. + + *CmdUndefined* +CmdUndefined When a user command is used but it isn't + defined. Useful for defining a command only + when it's used. The pattern is matched + against the command name. Both and + expand to the command name. + This is triggered even when inside an + autocommand defined without |autocmd-nested|. + NOTE: Autocompletion won't work until the + command is defined. An alternative is to + always define the user command and have it + invoke an autoloaded function. See |autoload|. + *CmdwinEnter* CmdwinEnter After entering the command-line window. Useful for setting options specifically for @@ -452,6 +480,7 @@ CmdwinEnter After entering the command-line window. expands to a single character, indicating the type of command-line. |cmdwin-char| + *CmdwinLeave* CmdwinLeave Before leaving the command-line window. Useful to clean up any global setting done @@ -459,6 +488,7 @@ CmdwinLeave Before leaving the command-line window. expands to a single character, indicating the type of command-line. |cmdwin-char| + *ColorScheme* ColorScheme After loading a color scheme. |:colorscheme| Not triggered if the color scheme is not @@ -495,13 +525,6 @@ CompleteChanged *CompleteChanged* The size and position of the popup are also available by calling |pum_getpos()|. - *CompleteDonePre* -CompleteDonePre After Insert mode completion is done. Either - when something was completed or discarded. - |ins-completion| - |complete_info()| is valid during this event. - |v:completed_item| gives the completed item. - *CompleteDone* CompleteDone After Insert mode completion is done. Either when something was completed or discarded. @@ -526,6 +549,13 @@ CompleteDone After Insert mode completion is done. Either - "discard": completion was abandoned for other reason. + *CompleteDonePre* +CompleteDonePre After Insert mode completion is done. Either + when something was completed or discarded. + |ins-completion| + |complete_info()| is valid during this event. + |v:completed_item| gives the completed item. + *CursorHold* CursorHold When there is no user input for 'updatetime' duration, in Normal-mode. Not triggered while @@ -561,20 +591,24 @@ CursorMoved After the cursor was moved in Normal or Visual Careful: This is triggered very often, don't do anything that the user does not expect or that is slow. + *CursorMovedC* CursorMovedC After the cursor was moved in the command line. Be careful not to mess up the command line, it may cause Vim to lock up. expands to the |cmdline-char|. + *CursorMovedI* CursorMovedI After the cursor was moved in Insert mode. Not triggered when the popup menu is visible. Otherwise the same as CursorMoved. + *DiffUpdated* DiffUpdated After diffs have been updated. Depending on what kind of diff is being used (internal or external) this can be triggered on every change or when doing |:diffupdate|. + *DirChanged* DirChanged After the |current-directory| was changed. The pattern can be: @@ -589,6 +623,7 @@ DirChanged After the |current-directory| was changed. switching window (or tab) is set to the new directory name. Non-recursive (event cannot trigger itself). + *DirChangedPre* DirChangedPre When the |current-directory| is going to be changed, as with |DirChanged|. @@ -600,6 +635,7 @@ DirChangedPre When the |current-directory| is going to be switching window (or tab) is set to the new directory name. Non-recursive (event cannot trigger itself). + *ExitPre* ExitPre When using `:quit`, `:wq` in a way it makes Vim exit, or using `:qall`, just after @@ -609,15 +645,19 @@ ExitPre When using `:quit`, `:wq` in a way it makes isn't automatically saved, use |VimLeavePre| for really exiting. See also |QuitPre|, |WinClosed|. + *FileAppendCmd* FileAppendCmd Before appending to a file. Should do the appending to the file. Use the '[ and '] marks for the range of lines. |Cmd-event| + *FileAppendPost* FileAppendPost After appending to a file. + *FileAppendPre* FileAppendPre Before appending to a file. Use the '[ and '] marks for the range of lines. + *FileChangedRO* FileChangedRO Before making the first change to a read-only file. Can be used to checkout the file from @@ -635,6 +675,7 @@ FileChangedRO Before making the first change to a read-only *E881* If the number of lines changes saving for undo may fail and the change will be aborted. + *FileChangedShell* FileChangedShell When Vim notices that the modification time of a file has changed since editing started. @@ -657,19 +698,24 @@ FileChangedShell When Vim notices that the modification time of *E246* *E811* Cannot switch, jump to or delete buffers. Non-recursive (event cannot trigger itself). + *FileChangedShellPost* FileChangedShellPost After handling a file that was changed outside of Vim. Can be used to update the statusline. + *FileReadCmd* FileReadCmd Before reading a file with a ":read" command. Should do the reading of the file. |Cmd-event| + *FileReadPost* FileReadPost After reading a file with a ":read" command. Note that Vim sets the '[ and '] marks to the first and last line of the read. This can be used to operate on the lines just read. + *FileReadPre* FileReadPre Before reading a file with a ":read" command. + *FileType* FileType When the 'filetype' option has been set. The pattern is matched against the filetype. @@ -678,24 +724,29 @@ FileType When the 'filetype' option has been set. The 'filetype'. Cannot switch windows or buffers. See |filetypes|. + *FileWriteCmd* FileWriteCmd Before writing to a file, when not writing the whole buffer. Should do the writing to the file. Should not change the buffer. Use the |'[| and |']| marks for the range of lines. |Cmd-event| + *FileWritePost* FileWritePost After writing to a file, when not writing the whole buffer. + *FileWritePre* FileWritePre Before writing to a file, when not writing the whole buffer. Use the |'[| and |']| marks for the range of lines. + *FilterReadPost* FilterReadPost After reading a file from a filter command. Vim checks the pattern against the name of the current buffer as with FilterReadPre. Not triggered when 'shelltemp' is off. + *FilterReadPre* *E135* FilterReadPre Before reading a file from a filter command. Vim checks the pattern against the name of @@ -703,6 +754,7 @@ FilterReadPre Before reading a file from a filter command. temporary file that is the output of the filter command. Not triggered when 'shelltemp' is off. + *FilterWritePost* FilterWritePost After writing a file for a filter command or making a diff with an external diff (see @@ -710,6 +762,7 @@ FilterWritePost After writing a file for a filter command or Vim checks the pattern against the name of the current buffer as with FilterWritePre. Not triggered when 'shelltemp' is off. + *FilterWritePre* FilterWritePre Before writing a file for a filter command or making a diff with an external diff. @@ -718,11 +771,14 @@ FilterWritePre Before writing a file for a filter command or temporary file that is the output of the filter command. Not triggered when 'shelltemp' is off. + *FocusGained* FocusGained Nvim got focus. + *FocusLost* FocusLost Nvim lost focus. Also (potentially) when a GUI dialog pops up. + *FuncUndefined* FuncUndefined When a user function is used but it isn't defined. Useful for defining a function only @@ -734,22 +790,14 @@ FuncUndefined When a user function is used but it isn't NOTE: When writing Vim scripts a better alternative is to use an autoloaded function. See |autoload-functions|. - *UIEnter* -UIEnter After a UI connects via |nvim_ui_attach()|, or - after builtin TUI is started, after |VimEnter|. - Sets these |v:event| keys: - chan: |channel-id| of the UI - *UILeave* -UILeave After a UI disconnects from Nvim, or after - builtin TUI is stopped, after |VimLeave|. - Sets these |v:event| keys: - chan: |channel-id| of the UI + *InsertChange* InsertChange When typing while in Insert or Replace mode. The |v:insertmode| variable indicates the new mode. Be careful not to move the cursor or do anything else that the user does not expect. + *InsertCharPre* InsertCharPre When a character is typed in Insert mode, before inserting the char. @@ -760,6 +808,7 @@ InsertCharPre When a character is typed in Insert mode, inserted literally. Cannot change the text. |textlock| + *InsertEnter* InsertEnter Just before starting Insert mode. Also for Replace mode and Virtual Replace mode. The @@ -769,20 +818,24 @@ InsertEnter Just before starting Insert mode. Also for The cursor is restored afterwards. If you do not want that set |v:char| to a non-empty string. + *InsertLeavePre* InsertLeavePre Just before leaving Insert mode. Also when using CTRL-O |i_CTRL-O|. Be careful not to change mode or use `:normal`, it will likely cause trouble. + *InsertLeave* InsertLeave Just after leaving Insert mode. Also when using CTRL-O |i_CTRL-O|. But not for |i_CTRL-C|. + LspAttach See |LspAttach| LspDetach See |LspDetach| LspNotify See |LspNotify| LspProgress See |LspProgress| LspRequest See |LspRequest| LspTokenUpdate See |LspTokenUpdate| + *MarkSet* MarkSet After a |mark| is set by |m|, |:mark|, and |nvim_buf_set_mark()|, or deleted by |:delmarks| @@ -812,6 +865,7 @@ MenuPopup Just before showing the popup menu (under the i Insert c Command line tl Terminal + *ModeChanged* ModeChanged After changing the mode. The pattern is matched against `'old_mode:new_mode'`, for @@ -828,37 +882,12 @@ ModeChanged After changing the mode. The pattern is This will be triggered on every minor mode change. Usage example to use relative line numbers - when entering visual mode: > + when entering visual mode: >vim :au ModeChanged [vV\x16]*:* let &l:rnu = mode() =~# '^[vV\x16]' :au ModeChanged *:[vV\x16]* let &l:rnu = mode() =~# '^[vV\x16]' :au WinEnter,WinLeave * let &l:rnu = mode() =~# '^[vV\x16]' -Progress *Progress* - After a |progress-message| is created or updated via - `nvim_echo`. The pattern is matched against - `source` of the message. The |event-data| contains: - id: id of the message - text: text of the message - title: title of the progress message - source: source of the progress message - status: status of the progress message - percent: how much progress has been - made for this progress item - data: arbitaray data sent with - progress message - See `vim.event.progress.data`. - Usage example: ->lua - vim.api.nvim_create_autocmd('Progress', { - pattern={'term'}, - callback = function(ev) - print(string.format('event fired: %s', vim.inspect(ev))) - end - }) - local id = vim.api.nvim_echo({{'searching...'}}, true, {kind='progress', status='running', percent=10, title='term', source='search'}) - vim.api.nvim_echo({{'searching'}}, true, {id = id, kind='progress', status='running', percent=50, title='term', source='search'}) - vim.api.nvim_echo({{'done'}}, true, {id = id, kind='progress', status='success', percent=100, title='term', source='search'}) - -< *OptionSet* +< + *OptionSet* OptionSet After setting an option (except during |startup|). The |autocmd-pattern| is matched against the long option name. || @@ -907,6 +936,36 @@ OptionSet After setting an option (except during Not triggered on startup. +PackChangedPre See |PackChangedPre| +PackChanged See |PackChanged| + +Progress *Progress* + After a |progress-message| is created or updated via + `nvim_echo`. The pattern is matched against + `source` of the message. + + The |event-data| has these keys (type: `vim.event.progress.data`): + - id: id of the message + - text: text of the message + - title: title of the progress message + - source: source of the progress message + - status: status of the progress message + - percent: how much progress has been made + - data: arbitrary data sent with the message + + Usage example: +>lua + vim.api.nvim_create_autocmd('Progress', { + pattern={'term'}, + callback = function(ev) + print(string.format('event fired: %s', vim.inspect(ev))) + end + }) + local id = vim.api.nvim_echo({{'searching...'}}, true, {kind='progress', status='running', percent=10, title='term', source='search'}) + vim.api.nvim_echo({{'searching'}}, true, {id = id, kind='progress', status='running', percent=50, title='term', source='search'}) + vim.api.nvim_echo({{'done'}}, true, {id = id, kind='progress', status='success', percent=100, title='term', source='search'}) + +< *QuickFixCmdPre* QuickFixCmdPre Before a quickfix command is run (|:make|, |:lmake|, |:grep|, |:lgrep|, |:grepadd|, @@ -924,6 +983,7 @@ QuickFixCmdPre Before a quickfix command is run (|:make|, 'makeprg' and 'grepprg' variables. If this command causes an error, the quickfix command is not executed. + *QuickFixCmdPost* QuickFixCmdPost Like QuickFixCmdPre, but after a quickfix command is run, before jumping to the first @@ -931,6 +991,7 @@ QuickFixCmdPost Like QuickFixCmdPre, but after a quickfix it is run after the error file is read and before moving to the first error. See |QuickFixCmdPost-example|. + *QuitPre* QuitPre When using `:quit`, `:wq` or `:qall`, before deciding whether it closes the current window @@ -939,25 +1000,13 @@ QuitPre When using `:quit`, `:wq` or `:qall`, before close any non-essential window if the current window is the last ordinary window. See also |ExitPre|, |WinClosed|. - *RemoteReply* -RemoteReply When a reply from a Vim that functions as - server was received server2client(). The - pattern is matched against the {serverid}. - is equal to the {serverid} from which - the reply was sent, and is the actual - reply string. - Note that even if an autocommand is defined, - the reply should be read with remote_read() - to consume it. - *SearchWrapped* -SearchWrapped After making a search with |n| or |N| if the - search wraps around the document back to - the start/finish respectively. + *RecordingEnter* RecordingEnter When a macro starts recording. The pattern is the current file name, and |reg_recording()| is the current register that is used. + *RecordingLeave* RecordingLeave When a macro stops recording. The pattern is the current file name, and @@ -968,6 +1017,18 @@ RecordingLeave When a macro stops recording. Sets these |v:event| keys: regcontents regname + + *RemoteReply* +RemoteReply When a reply from a Vim that functions as + server was received server2client(). The + pattern is matched against the {serverid}. + is equal to the {serverid} from which + the reply was sent, and is the actual + reply string. + Note that even if an autocommand is defined, + the reply should be read with remote_read() + to consume it. + *SafeState* SafeState When nothing is pending, going to wait for the user to type a character. @@ -989,21 +1050,35 @@ SafeState When nothing is pending, going to wait for the check more with `state()`, e.g. whether the screen was scrolled for messages. + *SearchWrapped* +SearchWrapped After making a search with |n| or |N| if the + search wraps around the document back to + the start/finish respectively. + *SessionLoadPre* SessionLoadPre Before loading the session file created using the |:mksession| command. + *SessionLoadPost* SessionLoadPost After loading the session file created using the |:mksession| command. + *SessionWritePost* SessionWritePost After writing a session file by calling the |:mksession| command. + *ShellCmdPost* ShellCmdPost After executing a shell command with |:!cmd|, |:make| and |:grep|. Can be used to check for any changed files. For non-blocking shell commands, see |job-control|. + + *ShellFilterPost* +ShellFilterPost After executing a shell command with + ":{range}!cmd", ":w !cmd" or ":r !cmd". + Can be used to check for any changed files. + *Signal* Signal After Nvim receives a signal. The pattern is matched against the signal name. Only @@ -1012,36 +1087,39 @@ Signal After Nvim receives a signal. The pattern is autocommand defined without |autocmd-nested|. Example: >vim autocmd Signal SIGUSR1 call some#func() -< *ShellFilterPost* -ShellFilterPost After executing a shell command with - ":{range}!cmd", ":w !cmd" or ":r !cmd". - Can be used to check for any changed files. + +< *SourceCmd* +SourceCmd When sourcing a Vimscript/Lua file. |:source| + is the name of the file being sourced. + The autocommand must source that file. + |Cmd-event| + *SourcePre* SourcePre Before sourcing a Vimscript/Lua file. |:source| is the name of the file being sourced. + *SourcePost* SourcePost After sourcing a Vimscript/Lua file. |:source| is the name of the file being sourced. Not triggered when sourcing was interrupted. Also triggered after a SourceCmd autocommand was triggered. - *SourceCmd* -SourceCmd When sourcing a Vimscript/Lua file. |:source| - is the name of the file being sourced. - The autocommand must source that file. - |Cmd-event| + *SpellFileMissing* SpellFileMissing When trying to load a spell checking file and it can't be found. The pattern is matched against the language. is the language, 'encoding' also matters. See |spell-SpellFileMissing|. + *StdinReadPost* StdinReadPost During startup, after reading from stdin into the buffer, before executing modelines. |--| + *StdinReadPre* StdinReadPre During startup, before reading from stdin into the buffer. |--| + *SwapExists* SwapExists Detected an existing swap file when starting to edit a file. Only when it is possible to @@ -1065,6 +1143,7 @@ SwapExists Detected an existing swap file when starting *E812* Cannot change to another buffer, change the buffer name or change directory. + *Syntax* Syntax When the 'syntax' option has been set. The pattern is matched against the syntax name. @@ -1072,50 +1151,59 @@ Syntax When the 'syntax' option has been set. The this option was set. expands to the new value of 'syntax'. See |:syn-on|. + *TabClosed* TabClosed After closing a tab page. expands to the tab page number. + *TabClosedPre* TabClosedPre Before closing a tab page. The window layout is locked, thus opening and closing of windows is prohibited. + *TabEnter* TabEnter Just after entering a tab page. |tab-page| After WinEnter. Before BufEnter. + *TabLeave* TabLeave Just before leaving a tab page. |tab-page| After WinLeave. + *TabNew* TabNew When creating a new tab page. |tab-page| After WinEnter. Before TabEnter. + *TabNewEntered* TabNewEntered After entering a new tab page. |tab-page| After BufEnter. + + *TermClose* +TermClose When a |terminal| job ends. + Sets these |v:event| keys: + status job exit status, or -1 if the + terminal buffer is deleted + + *TermEnter* +TermEnter After entering |Terminal-mode|. + After TermOpen. + + *TermLeave* +TermLeave After leaving |Terminal-mode|. + After TermClose. + *TermOpen* TermOpen When a |terminal| job is starting. Can be used to configure the terminal buffer. To get the terminal process details: >lua vim.print(vim.api.nvim_get_chan_info(vim.bo.channel)) < - *TermEnter* -TermEnter After entering |Terminal-mode|. - After TermOpen. - *TermLeave* -TermLeave After leaving |Terminal-mode|. - After TermClose. - *TermClose* -TermClose When a |terminal| job ends. - Sets these |v:event| keys: - status job exit status, or -1 if the - terminal buffer is deleted *TermRequest* TermRequest When a |:terminal| child process emits an OSC, - DCS, or APC sequence. Sets |v:termrequest|. The - |event-data| is a table with the following - fields: + DCS, or APC sequence. Sets |v:termrequest|. + The |event-data| has these keys (type: `vim.event.termrequest.data`): - sequence: the received sequence - terminator: the received sequence terminator (i.e. BEL or ST) - cursor: (1,0)-indexed, buffer-relative @@ -1129,9 +1217,9 @@ TermRequest When a |:terminal| child process emits an OSC, *TermResponse* TermResponse When Nvim receives a DA1, OSC, DCS, or APC response from - the host terminal. Sets |v:termresponse|. The - |event-data| is a table with the following fields: + the host terminal. Sets |v:termresponse|. + The |event-data| has these keys (type: `vim.event.termresponse.data`): - sequence: the received sequence See `vim.event.termresponse.data`. @@ -1167,20 +1255,24 @@ TextChanged After a change was made to the text in the Careful: This is triggered very often, don't do anything that the user does not expect or that is slow. + *TextChangedI* TextChangedI After a change was made to the text in the current buffer in Insert mode. Not triggered when the popup menu is visible. Otherwise the same as TextChanged. + *TextChangedP* TextChangedP After a change was made to the text in the current buffer in Insert mode, only when the popup menu is visible. Otherwise the same as TextChanged. + *TextChangedT* TextChangedT After a change was made to the text in the current buffer in |Terminal-mode|. Otherwise the same as TextChanged. + *TextYankPost* TextYankPost Just after a |yank| or |deleting| command, but not if the black hole register |quote_| is used nor @@ -1198,15 +1290,30 @@ TextYankPost Just after a |yank| or |deleting| command, but not Non-recursive (event cannot trigger itself). Cannot change the text. |textlock| + + *UIEnter* +UIEnter After a UI connects via |nvim_ui_attach()|, or + after builtin TUI is started, after |VimEnter|. + Sets these |v:event| keys: + chan: |channel-id| of the UI + + *UILeave* +UILeave After a UI disconnects from Nvim, or after + builtin TUI is stopped, after |VimLeave|. + Sets these |v:event| keys: + chan: |channel-id| of the UI + *User* User Not executed automatically. Use |:doautocmd| to trigger this, typically for "custom events" in a plugin. Example: > :autocmd User MyPlugin echom 'got MyPlugin event' :doautocmd User MyPlugin + < *UserGettingBored* UserGettingBored When the user presses the same key 42 times. Just kidding! :-) + *VimEnter* VimEnter After doing all the startup stuff, including loading vimrc files, executing the "-c cmd" @@ -1220,6 +1327,7 @@ VimEnter After doing all the startup stuff, including else au VimEnter * call s:init() endif + < *VimLeave* VimLeave Before exiting Vim, just after writing the .shada file. Executed only once, like @@ -1227,6 +1335,7 @@ VimLeave Before exiting Vim, just after writing the Use |v:dying| to detect an abnormal exit. Use |v:exiting| to get the exit code. Not triggered if |v:dying| is 2 or more. + *VimLeavePre* VimLeavePre Before exiting Vim, just before writing the |shada| file. Executed only once, if the @@ -1236,14 +1345,18 @@ VimLeavePre Before exiting Vim, just before writing the < Use |v:dying| to detect an abnormal exit. Use |v:exiting| to get the exit code. Not triggered if |v:dying| is 2 or more. + *VimResized* VimResized After the Vim window was resized, thus 'lines' and/or 'columns' changed. Not when starting up though. + *VimResume* VimResume After Nvim resumes from |suspend| state. + *VimSuspend* VimSuspend Before Nvim enters |suspend| state. + *WinClosed* WinClosed When closing a window, just before it is removed from the window layout. The pattern @@ -1252,6 +1365,7 @@ WinClosed When closing a window, just before it is After WinLeave. Non-recursive (event cannot trigger itself). See also |ExitPre|, |QuitPre|. + *WinEnter* WinEnter After entering another window. Not done for the first window, when Vim has just started. @@ -1270,6 +1384,7 @@ WinLeave Before leaving a window. If the window to be WinLeave autocommands (but not for ":new"). Not used for ":qa" or ":q" when exiting Vim. Before WinClosed. + *WinNewPre* WinNewPre Before creating a new window. Triggered before commands that modify window layout by @@ -1289,6 +1404,17 @@ WinNew When a new window was created. Not done for the first window, when Vim has just started. Before WinEnter. + *WinResized* +WinResized After a window in the current tab page changed + width or height. + See |win-scrolled-resized|. + + |v:event| is set with information about size + changes. |WinResized-event| + + Same behavior as |WinScrolled| for the + pattern, triggering and recursiveness. + *WinScrolled* WinScrolled After any window in the current tab page scrolled the text (horizontally or vertically) @@ -1322,18 +1448,6 @@ WinScrolled After any window in the current tab page window to scroll or change size, then another WinScrolled event will be triggered later. - - *WinResized* -WinResized After a window in the current tab page changed - width or height. - See |win-scrolled-resized|. - - |v:event| is set with information about size - changes. |WinResized-event| - - Same behavior as |WinScrolled| for the - pattern, triggering and recursiveness. - ============================================================================== 6. Patterns *autocmd-pattern* *{aupat}* diff --git a/runtime/doc/dev.txt b/runtime/doc/dev.txt index 6a96b3d8f7..19162f2587 100644 --- a/runtime/doc/dev.txt +++ b/runtime/doc/dev.txt @@ -306,10 +306,13 @@ To choose a new "EXX" error code (e.g. |E5555|), just print a message with a new EXX number: > emsg(_("E996: Invalid thing")); < -You can confirm that the new error code isn't used by running: > +To see existing error codes: > + :new | put =filter(getcompletion('h E', 'cmdline'), 'v:val =~# ''E\d\d''') + +The `linterrcodes` build target checks that all "EXX" codes are unique and +have help tags. It runs in CI, but you can also run it locally: > make linterrcodes < -The `linterrcodes.lua` check requires the new error code to have a help tag. ------------------------------------------------------------------------------ Stdlib design *dev-lua* diff --git a/runtime/doc/filetype.txt b/runtime/doc/filetype.txt index 7f5fec5b16..9f87e6d335 100644 --- a/runtime/doc/filetype.txt +++ b/runtime/doc/filetype.txt @@ -409,6 +409,11 @@ If both, the global `plugin_exec` and the `_exec` specific variable are set, the filetype specific variable should have precedent. +ADA + +Documentation for this plugin is here: |ft_ada.txt|. + + ASCIIDOC *ft-asciidoc-plugin* To enable |folding| use this: > @@ -899,6 +904,11 @@ To disable this behavior, set the following variable in your vimrc: > let g:python_recommended_style = 0 +POWERSHELL + +Documentation for this plugin is here: |ft_ps1.txt|. + + QUERY *ft-query-plugin* @@ -961,6 +971,11 @@ and for LaTeX code. If you prefer that 'formatexpr' is not set, add to your let rnw_dynamic_comments = 0 +RAKU + +Documentation for this plugin is here: |ft_raku.txt|. + + RPM SPEC *ft-spec-plugin* Since the text for this plugin is rather long it has been put in a separate diff --git a/runtime/doc/help.txt b/runtime/doc/help.txt index ccbe79e974..d022ecf556 100644 --- a/runtime/doc/help.txt +++ b/runtime/doc/help.txt @@ -80,19 +80,14 @@ API (extensibility/scripting/plugins) ------------------------------------------------------------------------------ Programming language support -- |lsp| Language Server Protocol (LSP) - |diagnostic-api| Diagnostic framework -- |treesitter| Incremental syntax parsing -- |indent.txt| automatic indenting for C and other languages -- |syntax| syntax highlighting - |filetype| Settings for specific types of files +- |indent.txt| automatic indenting for C and other languages +- |lsp| Language Server Protocol (LSP) - |quickfix| Commands for a quick edit-compile-fix cycle -- |ft_ada.txt| Ada filetype plugin -- |ft_hare.txt| Filetype plugin for Hare -- |ft_ps1.txt| PowerShell filetype plugin -- |ft_raku.txt| Raku filetype plugin -- |ft_rust.txt| Rust filetype plugin -- |ft_sql.txt| SQL filetype plugin +- |syntax| syntax highlighting +- |treesitter| Incremental syntax parsing +- |vim.pack| Plugin manager ------------------------------------------------------------------------------ UI diff --git a/runtime/doc/insert.txt b/runtime/doc/insert.txt index d52bc6e644..015e971434 100644 --- a/runtime/doc/insert.txt +++ b/runtime/doc/insert.txt @@ -1332,7 +1332,7 @@ The same, but now pretending searching for matches is slow: > INSERT COMPLETION POPUP MENU *ins-completion-menu* *popupmenu-completion* -Vim can display the matches in a simplistic popup menu. +Vim can display the matches in a popup menu. The menu is used when: - The 'completeopt' option contains "menu" or "menuone". diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index 86631da4ce..8a57554586 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -688,8 +688,8 @@ EVENTS *lsp-events* LspAttach *LspAttach* After an LSP client performs "initialize" and attaches to a buffer. The - |autocmd-pattern| is the buffer name. The client ID is passed in the - Lua handler |event-data| argument. See `vim.event.lspattach.data`. + |autocmd-pattern| is the buffer name. The |event-data| (type: + `vim.event.lspattach.data`) has the client ID. Example: >lua vim.api.nvim_create_autocmd('LspAttach', { @@ -721,8 +721,8 @@ LspAttach *LspAttach* LspDetach *LspDetach* Just before an LSP client detaches from a buffer. The |autocmd-pattern| is - the buffer name. The client ID is passed in the Lua handler |event-data| - argument. See `vim.event.lspdetach.data`. + the buffer name. The |event-data| (type: `vim.event.lspdetach.data`) has + the client ID. Example: >lua vim.api.nvim_create_autocmd('LspDetach', { @@ -745,8 +745,8 @@ LspNotify *LspNotify* This event is triggered after each successful notification sent to an LSP server. - The client_id, LSP method, and parameters are sent in the Lua handler - |event-data| table argument. See `vim.event.lspnotify.data`. + The |event-data| (type: `vim.event.lspnotify.data`) has the client_id, LSP + method, and parameters. Example: >lua vim.api.nvim_create_autocmd('LspNotify', { @@ -772,9 +772,9 @@ LspProgress *LspProgress* If the server sends a "work done progress", the `pattern` is set to `kind` (one of `begin`, `report` or `end`). - The Lua handler |event-data| argument has `client_id` and `params` - properties, where `params` is the request params sent by the server (see - `lsp.ProgressParams`). See `vim.event.lspprogress.data`. + The |event-data| (type: `vim.event.lspprogress.data`) has `client_id` and + `params` properties, where `params` is the request params sent by the + server (see `lsp.ProgressParams`). Examples: @@ -809,11 +809,10 @@ LspRequest *LspRequest* is requested using `client.cancel_request(request_id)`, then this event will trigger with {type} == `cancel`. - The Lua handler |event-data| argument has the client ID, request ID, and - request (described at |vim.lsp.Client|, {requests} field). If the request - type is `complete`, the request will be deleted from the client's pending - requests table after processing the event handlers. - See `vim.event.lsprequest.data`. + The |event-data| (type: `vim.event.lsprequest.data`) has the client ID, + request ID, and request (described at |vim.lsp.Client|, {requests} field). + If the request type is `complete`, the request will be deleted from the + client's pending requests table after processing the event handlers. Example: >lua vim.api.nvim_create_autocmd('LspRequest', { @@ -840,9 +839,9 @@ LspRequest *LspRequest* LspTokenUpdate *LspTokenUpdate* When a visible semantic token is sent or updated by the LSP server, or when an existing token becomes visible for the first time. The - |autocmd-pattern| is the buffer name. The Lua handler |event-data| - argument has the client ID and token (see - |vim.lsp.semantic_tokens.get_at_pos()|). See `vim.event.lsptokenupdate.data`. + |autocmd-pattern| is the buffer name. The |event-data| (type: + `vim.event.lsptokenupdate.data`) has the client ID and token (see + |vim.lsp.semantic_tokens.get_at_pos()|). Example: >lua vim.api.nvim_create_autocmd('LspTokenUpdate', { diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 08968c05ce..d1e514a853 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -1164,9 +1164,9 @@ Option:remove({value}) *vim.opt:remove()* • {value} (`string`) Value to remove vim.bo[{bufnr}] *vim.bo* - Get or set buffer-scoped |options| for the buffer with number {bufnr}. - Like `:setlocal`. If {bufnr} is omitted then the current buffer is used. - Invalid {bufnr} or key is an error. + Gets or sets buffer-scoped |options| on buffer {bufnr} (or "current + buffer" if 0 or omitted). Like `:setlocal`. Invalid {bufnr} or key is an + error. Example: >lua local bufnr = vim.api.nvim_get_current_buf() @@ -1176,9 +1176,9 @@ vim.bo[{bufnr}] *vim.bo* < vim.env *vim.env* - Environment variables defined in the editor session. See |expand-env| and - |:let-environment| for the Vimscript behavior. Invalid or unset key - returns `nil`. + Gets or sets environment variables in the current editor process. See + |expand-env| and |:let-environment| for the Vimscript behavior. Invalid or + unset key returns `nil`. Example: >lua vim.env.FOO = 'bar' @@ -1186,11 +1186,10 @@ vim.env *vim.env* < vim.go *vim.go* - Get or set global |options|. Like `:setglobal`. Invalid key is an error. + Gets or sets global |options|. Like `:setglobal`. Invalid key is an error. - Note: this is different from |vim.o| because this accesses the global - option value and thus is mostly useful for use with |global-local| - options. + Note: unlike |vim.o|, this accesses the global option value and thus is + mostly useful with |global-local| options. Example: >lua vim.go.cmdheight = 4 @@ -1199,7 +1198,7 @@ vim.go *vim.go* < vim.o *vim.o* - Get or set |options|. Works like `:set`, so buffer/window-scoped options + Gets or sets |options|. Works like `:set`, so buffer/window-scoped options target the current buffer/window. Invalid key is an error. Example: >lua @@ -1209,14 +1208,12 @@ vim.o *vim.o* < vim.wo[{winid}][{bufnr}] *vim.wo* - Get or set window-scoped |options| for the window with handle {winid} and - buffer with number {bufnr}. Like `:setlocal` if setting a |global-local| - option or if {bufnr} is provided, like `:set` otherwise. If {winid} is - omitted then the current window is used. Invalid {winid}, {bufnr} or key - is an error. + Gets or sets window-scoped |options| on window {winid} (or "current + window" if 0 or omitted) and buffer {bufnr} (0 for current buffer). Like + `:setlocal` if setting a |global-local| option or if {bufnr} is specified, + like `:set` otherwise. Invalid {winid}, {bufnr}, or key is an error. - Note: only {bufnr} with value `0` (the current buffer in the window) is - supported. + Note: only bufnr=0 (current window-buffer) is supported, currently. Example: >lua local winid = vim.api.nvim_get_current_win() @@ -2484,28 +2481,31 @@ vim.filetype.match({args}) *vim.filetype.match()* ============================================================================== Lua module: vim.fs *vim.fs* - *vim.fs.copy()* + Use |filecopy()| or |uv.fs_copyfile()| to performantly copy an existing file. Example: >lua - vim.fn.filecopy('foo.txt', 'bar.txt') + vim.fn.filecopy('foo.txt', 'bar.txt') < *vim.fs.exists()* + Use |uv.fs_stat()| to check a file's type, and whether it exists. Example: >lua - if vim.uv.fs_stat(file) then - vim.print('file exists') - end + if vim.uv.fs_stat(file) then + vim.print('file exists') + end < *vim.fs.read()* -You can use |readblob()| to get a file's contents without explicitly opening/closing it. + +You can use |readblob()| to get a file's contents without explicitly +opening/closing it. Or use |io.lines()| to iterate lines in a text file. Example: >lua - vim.print(vim.fn.readblob('.git/config')) + vim.print(vim.fn.readblob('.git/config')) < diff --git a/runtime/doc/pack.txt b/runtime/doc/pack.txt index dce61f8a93..5819e39a7d 100644 --- a/runtime/doc/pack.txt +++ b/runtime/doc/pack.txt @@ -361,7 +361,7 @@ Performing actions via `vim.pack` functions can trigger these events: • *PackChangedPre* - before trying to change plugin's state. • *PackChanged* - after plugin's state has changed. -Each event populates the following |event-data| fields: +The |event-data| has these keys (type: `vim.event.packchanged.data`): • `active` - whether plugin was added via |vim.pack.add()| to current session. • `kind` - one of "install" (install on disk; before loading), "update" (update already installed plugin; might be not loaded), "delete" (delete diff --git a/runtime/lua/vim/_core/options.lua b/runtime/lua/vim/_core/options.lua index 12c4f86232..50e0c1ef18 100644 --- a/runtime/lua/vim/_core/options.lua +++ b/runtime/lua/vim/_core/options.lua @@ -134,9 +134,8 @@ local function get_options_info(name) return info end ---- Environment variables defined in the editor session. ---- See |expand-env| and |:let-environment| for the Vimscript behavior. ---- Invalid or unset key returns `nil`. +--- Gets or sets environment variables in the current editor process. See |expand-env| and +--- |:let-environment| for the Vimscript behavior. Invalid or unset key returns `nil`. --- --- Example: --- @@ -229,7 +228,7 @@ end --- global value of a |global-local| option, see |:setglobal|. --- ---- Get or set |options|. Works like `:set`, so buffer/window-scoped options target the current +--- Gets or sets |options|. Works like `:set`, so buffer/window-scoped options target the current --- buffer/window. Invalid key is an error. --- --- Example: @@ -248,12 +247,10 @@ vim.o = setmetatable({}, { end, }) ---- Get or set global |options|. Like `:setglobal`. Invalid key is ---- an error. +--- Gets or sets global |options|. Like `:setglobal`. Invalid key is an error. --- ---- Note: this is different from |vim.o| because this accesses the global ---- option value and thus is mostly useful for use with |global-local| ---- options. +--- Note: unlike |vim.o|, this accesses the global option value and thus is mostly useful +--- with |global-local| options. --- --- Example: --- @@ -271,9 +268,8 @@ vim.go = setmetatable({}, { end, }) ---- Get or set buffer-scoped |options| for the buffer with number {bufnr}. ---- Like `:setlocal`. If {bufnr} is omitted then the current buffer is used. ---- Invalid {bufnr} or key is an error. +--- Gets or sets buffer-scoped |options| on buffer {bufnr} (or "current buffer" if 0 or omitted). Like +--- `:setlocal`. Invalid {bufnr} or key is an error. --- --- Example: --- @@ -285,13 +281,11 @@ vim.go = setmetatable({}, { --- ``` vim.bo = new_buf_opt_accessor() ---- Get or set window-scoped |options| for the window with handle {winid} and ---- buffer with number {bufnr}. Like `:setlocal` if setting a |global-local| option ---- or if {bufnr} is provided, like `:set` otherwise. If {winid} is omitted then ---- the current window is used. Invalid {winid}, {bufnr} or key is an error. +--- Gets or sets window-scoped |options| on window {winid} (or "current window" if 0 or omitted) and +--- buffer {bufnr} (0 for current buffer). Like `:setlocal` if setting a |global-local| option or if +--- {bufnr} is specified, like `:set` otherwise. Invalid {winid}, {bufnr}, or key is an error. --- ---- Note: only {bufnr} with value `0` (the current buffer in the window) is ---- supported. +--- Note: only bufnr=0 (current window-buffer) is supported, currently. --- --- Example: --- diff --git a/runtime/lua/vim/_meta/api_keysets_extra.lua b/runtime/lua/vim/_meta/api_keysets_extra.lua index 3b8461892b..0ac48e80da 100644 --- a/runtime/lua/vim/_meta/api_keysets_extra.lua +++ b/runtime/lua/vim/_meta/api_keysets_extra.lua @@ -1,8 +1,9 @@ --- @meta _ -- This file is NOT generated, edit it directly. See also _meta/api_keysets.gen.lua. + error('Cannot require a meta file') ---- Extra types we can't generate keysets for +--- Extra types we don't define keysets for. --- @class vim.api.keyset.extmark_details --- @field ns_id integer @@ -75,7 +76,7 @@ error('Cannot require a meta file') --- @field match string expanded value of --- @field buf integer expanded value of --- @field file string expanded value of ---- @field data? any arbitrary data passed from |nvim_exec_autocmds()| *event-data* +--- @field data? any arbitrary data passed from |nvim_exec_autocmds()| --- @class vim.api.keyset.create_user_command.command_args --- @field name string Command name diff --git a/runtime/lua/vim/_meta/events.lua b/runtime/lua/vim/_meta/events.lua index 6f70794cf9..c7def2e7c3 100644 --- a/runtime/lua/vim/_meta/events.lua +++ b/runtime/lua/vim/_meta/events.lua @@ -1,4 +1,7 @@ --- @meta +-- This file is NOT generated, edit it directly. +-- +-- See also `vim.api.keyset.events` in `api_keysets.gen.lua`. error('Cannot require a meta file') --- @class vim.event.lspattach.data diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua index d50ce39eac..13162d5b19 100644 --- a/runtime/lua/vim/fs.lua +++ b/runtime/lua/vim/fs.lua @@ -1,32 +1,35 @@ ---- @brief 
help
---- *vim.fs.copy()*
+--- @brief
+--- [vim.fs.copy()]()
+---
 --- Use |filecopy()| or |uv.fs_copyfile()| to performantly copy an existing file.
 ---
 --- Example:
 ---
---- >lua
----   vim.fn.filecopy('foo.txt', 'bar.txt')
---- <
+--- ```lua
+--- vim.fn.filecopy('foo.txt', 'bar.txt')
+--- ```
+---
+--- [vim.fs.exists()]()
 ---
---- *vim.fs.exists()*
 --- Use |uv.fs_stat()| to check a file's type, and whether it exists.
 ---
 --- Example:
 ---
---- >lua
----   if vim.uv.fs_stat(file) then
----     vim.print('file exists')
----   end
---- <
+--- ```lua
+--- if vim.uv.fs_stat(file) then
+---   vim.print('file exists')
+--- end
+--- ```
+---
+--- [vim.fs.read()]()
 ---
---- *vim.fs.read()*
 --- You can use |readblob()| to get a file's contents without explicitly opening/closing it.
+--- Or use |io.lines()| to iterate lines in a text file.
 ---
 --- Example:
----
---- >lua
----   vim.print(vim.fn.readblob('.git/config'))
---- <
+--- ```lua
+--- vim.print(vim.fn.readblob('.git/config'))
+--- ```
 
 local uv = vim.uv
 
diff --git a/runtime/lua/vim/pack.lua b/runtime/lua/vim/pack.lua
index ad48d6ce7d..8a597e20cd 100644
--- a/runtime/lua/vim/pack.lua
+++ b/runtime/lua/vim/pack.lua
@@ -167,7 +167,7 @@
 ---- [PackChangedPre]() - before trying to change plugin's state.
 ---- [PackChanged]() - after plugin's state has changed.
 ---
----Each event populates the following |event-data| fields:
+---The |event-data| has these keys (type: `vim.event.packchanged.data`):
 ---- `active` - whether plugin was added via |vim.pack.add()| to current session.
 ---- `kind` - one of "install" (install on disk; before loading),
 ---  "update" (update already installed plugin; might be not loaded),
diff --git a/runtime/lua/vim/ui.lua b/runtime/lua/vim/ui.lua
index fc0083251b..fe670893e5 100644
--- a/runtime/lua/vim/ui.lua
+++ b/runtime/lua/vim/ui.lua
@@ -304,16 +304,9 @@ function M._get_urls()
 end
 
 do
-  ---@class ProgressMessage
-  ---@field id? number|string  ID of the progress message
-  ---@field title? string   Title of the progress message
-  ---@field status string  Status: "running" | "success" | "failed" | "cancel"
-  ---@field percent? integer Percent complete (0–100)
-  ---@private
-
   --- Cache of active progress messages, keyed by msg_id
   --- TODO(justinmk): visibility of "stale" (never-finished) Progress. https://github.com/neovim/neovim/pull/35428#discussion_r2942696157
-  ---@type table
+  ---@type table
   local progress = {}
 
   -- store progress events
@@ -325,7 +318,7 @@ do
     progress_autocmd = vim.api.nvim_create_autocmd('Progress', {
       group = progress_group,
       desc = 'Tracks progress messages for vim.ui.progress_status()',
-      ---@param ev {data: {id: integer, title: string, status: string, percent: integer}}
+      ---@param ev {data: vim.event.progress.data}
       callback = function(ev)
         if not ev.data or not ev.data.id then
           return
@@ -349,7 +342,7 @@ do
   --- Gets a status description summarizing currently running progress messages.
   --- - If none: returns empty string
   --- - If N item running: "AVG%(N)"
-  ---@param running ProgressMessage[]
+  ---@param running vim.event.progress.data[]
   ---@return string
   local function progress_status_fmt(running)
     local count = #running
diff --git a/test/functional/plugin/lsp/util_spec.lua b/test/functional/plugin/lsp/util_spec.lua
index 66af0ffd1e..bf573f68ee 100644
--- a/test/functional/plugin/lsp/util_spec.lua
+++ b/test/functional/plugin/lsp/util_spec.lua
@@ -1238,6 +1238,9 @@ describe('vim.lsp.util', function()
         ' @see `nvim_buf_detach()`',
         ' @see `api-buffer-updates-lua`',
         '',
+        -- For each @param/@return: #30695
+        --  - Separate each by one empty line.
+        --  - Remove all other blank lines.
         '@*param* `buffer` — Buffer handle, or 0 for current buffer',
         '',
         '@*param* `send_buffer` — True if whole buffer.',
@@ -1300,7 +1303,7 @@ describe('vim.lsp.util', function()
 
       before_each(function()
         local _ = Screen.new(80, 80)
-        feed('79i')
+        feed('79i') -- fill screen with empty lines
       end)
 
       describe('when on the first line it places window below', function()
@@ -1479,6 +1482,7 @@ describe('vim.lsp.util', function()
       {1:~                                                    }|*9
                                                            |
     ]])
+      -- Entering window keeps lines concealed and doesn't end up below inner window size.
       feed('wG')
       screen:expect([[
                                                            |
@@ -1488,8 +1492,9 @@ describe('vim.lsp.util', function()
       {1:~                                                    }|*9
                                                            |
     ]])
+      -- Correct height when float inherits 'conceallevel' >= 2 #32639
       command('close | set conceallevel=2')
-      feed('')
+      feed('') -- Prevent CursorMoved closing the next float immediately
       exec_lua([[
       vim.lsp.util.open_floating_preview({ '```lua', 'local foo', '```' }, 'markdown', {
         border = 'single',
@@ -1504,6 +1509,7 @@ describe('vim.lsp.util', function()
       {1:~                                                    }|*9
                                                            |
     ]])
+      -- This tests the valid winline code path (why doesn't the above?).
       exec_lua([[
       vim.cmd.only()
       vim.lsp.util.open_floating_preview({ 'foo', '```lua', 'local bar', '```' }, 'markdown', {