diff options
| -rw-r--r-- | runtime/doc/autocmd.txt | 190 |
1 files changed, 91 insertions, 99 deletions
diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index 608f8bbf3d..8006a45899 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -397,17 +397,18 @@ BufFilePost After changing the name of the current buffer BufFilePre Before changing the name of the current buffer with the ":file" or ":saveas" command. *BufHidden* -BufHidden Just before a buffer becomes hidden. That is, - when there are no longer windows that show - the buffer, but the buffer is not unloaded or - deleted. Not used for ":qa" or ":q" when - exiting Vim. +BufHidden Before a buffer becomes hidden: when there are + no longer windows that show the buffer, but + the buffer is not unloaded or deleted. + + Not used for ":qa" or ":q" when exiting Vim. NOTE: current buffer "%" may be different from the buffer being unloaded "<afile>". *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. *BufNew* BufNew Just after creating a new buffer. Also used @@ -423,16 +424,17 @@ BufNewFile When starting to edit a file that doesn't *BufRead* *BufReadPost* BufRead or BufReadPost When starting to edit a new buffer, after reading the file into the buffer, before - executing the modelines. See |BufWinEnter| - for when you need to do something after - processing the modelines. - This does NOT work for ":r file". Not used - when the file doesn't exist. Also used after - successfully recovering a file. - Also triggered for the filetypedetect group - when executing ":filetype detect" and when - writing an unnamed buffer in a way that the - buffer gets a name. + processing modelines. See |BufWinEnter| to do + something after processing modelines. + Also triggered: + - when writing an unnamed buffer such that the + buffer gets a name + - after successfully recovering a file + - for the "filetypedetect" group when + executing ":filetype detect" + Not triggered: + - for ":r file" + - if the file doesn't exist *BufReadCmd* BufReadCmd Before starting to edit a new buffer. Should read the file into the buffer. |Cmd-event| @@ -441,34 +443,33 @@ 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. This is when the - text in the buffer is going to be freed. This - may be after a BufWritePost and before a - BufDelete. Also used for all buffers that are - loaded when Vim is going to exit. +BufUnload Before unloading a buffer, when the text in + the buffer is going to be freed. + After BufWritePost. + Before BufDelete. + Triggers for all loaded buffers when Vim is + going to exit. NOTE: Current buffer "%" may be different from the buffer being unloaded "<afile>". - Do not change to another buffer or window! + 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 - can be when the buffer is loaded (after - processing the modelines) or when a hidden - buffer is displayed in a window (and is no - longer hidden). - Does not happen for |:split| without - arguments, since you keep editing the same - buffer, or ":split" with a file that's already - open in a window, because it re-uses an - existing buffer. But it does happen for a - ":split" with the name of the current buffer, - since it reloads that buffer. + may be when the buffer is loaded (after + processing modelines) or when a hidden buffer + is displayed (and is no longer hidden). + + Not triggered for |:split| without arguments, + since the buffer does not change, or :split + 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. - Also triggered when exiting. It's triggered - before BufUnload or BufHidden. + Also triggered when exiting. + Before BufUnload, BufHidden. NOTE: Current buffer "%" may be different from the buffer being unloaded "<afile>". Not triggered when exiting and v:dying is 2 or @@ -516,7 +517,7 @@ 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 <amatch> and - <afile> are set to the name of the command. + <afile> expand to the command name. NOTE: Autocompletion won't work until the command is defined. An alternative is to always define the user command and have it @@ -525,12 +526,12 @@ CmdUndefined When a user command is used but it isn't CmdlineChanged After a change was made to the text inside command line. Be careful not to mess up the command line, it may cause Vim to lock up. - <afile> is set to the |cmdline-char|. + <afile> expands to the |cmdline-char|. *CmdlineEnter* CmdlineEnter After entering the command-line (including non-interactive use of ":" in a mapping: use |<Cmd>| instead to avoid this). - <afile> is set to the |cmdline-char|. + <afile> expands to the |cmdline-char|. Sets these |v:event| keys: cmdlevel cmdtype @@ -538,26 +539,26 @@ CmdlineEnter After entering the command-line (including CmdlineLeave Before leaving the command-line (including non-interactive use of ":" in a mapping: use |<Cmd>| instead to avoid this). - <afile> is set to the |cmdline-char|. + <afile> expands to the |cmdline-char|. Sets these |v:event| keys: abort (mutable) cmdlevel cmdtype Note: `abort` can only be changed from false - to true. An autocmd cannot execute an already - aborted cmdline by changing it to false. + to true: cannot execute an already aborted + cmdline by changing it to false. *CmdwinEnter* CmdwinEnter After entering the command-line window. Useful for setting options specifically for this special type of window. - <afile> is set to a single character, + <afile> 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 with CmdwinEnter. - <afile> is set to a single character, + <afile> expands to a single character, indicating the type of command-line. |cmdwin-char| *ColorScheme* @@ -599,8 +600,7 @@ CompleteDone After Insert mode completion is done. Either completion. |ins-completion| |complete_info()| can be used, the info is cleared after triggering CompleteDone. - The |v:completed_item| variable contains the - completed item. + |v:completed_item| gives the completed item. *CursorHold* CursorHold When the user doesn't press a key for the time @@ -630,9 +630,9 @@ CursorHold When the user doesn't press a key for the time :let &ro = &ro *CursorHoldI* -CursorHoldI Just like CursorHold, but in Insert mode. - Not triggered when waiting for another key, - e.g. after CTRL-V, and not when in CTRL-X mode +CursorHoldI Like CursorHold, but in Insert mode. Not + triggered when waiting for another key, e.g. + after CTRL-V, and not in CTRL-X mode |insert_expand|. *CursorMoved* @@ -643,7 +643,7 @@ CursorMoved After the cursor was moved in Normal or Visual Not triggered when there is typeahead or when an operator is pending. For an example see |match-parens|. - Note: Cannot be skipped with `:noautocmd`. + Note: Cannot be skipped with |:noautocmd|. Careful: This is triggered very often, don't do anything that the user does not expect or that is slow. @@ -665,7 +665,7 @@ DirChanged After the |current-directory| was changed. *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| + marks for the range of lines. |Cmd-event| *FileAppendPost* FileAppendPost After appending to a file. *FileAppendPre* @@ -673,19 +673,18 @@ 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 check-out the file from + file. Can be used to checkout the file from a source control system. Not triggered when the change was caused by an autocommand. - This event is triggered when making the first - change in a buffer or the first change after - 'readonly' was set, just before the change is - applied to the text. + Triggered when making the first change in + a buffer or the first change after 'readonly' + was set, just before the change is applied to + the text. WARNING: If the autocommand moves the cursor the effect of the change is undefined. *E788* - It is not allowed to change to another buffer - here. You can reload the buffer but not edit - another one. + Cannot switch buffers. You can reload the + buffer but not edit another one. *E881* If the number of lines changes saving for undo may fail and the change will be aborted. @@ -704,28 +703,21 @@ FileChangedShell When Vim notices that the modification time of Also when the file attributes of the file change or when the size of the file changes. |timestamp| - Mostly triggered after executing a shell - command, but also with a |:checktime| command - or when gvim regains input focus. - This autocommand is triggered for each changed - file. It is not used when 'autoread' is set - and the buffer was not changed. If a - FileChangedShell autocommand is present the - warning message and prompt is not given. - The |v:fcs_reason| variable is set to indicate - what happened and |v:fcs_choice| can be used - to tell Vim what to do next. - NOTE: When this autocommand is executed, the - current buffer "%" may be different from the - buffer that was changed, which is in "<afile>". - NOTE: The commands must not change the current - buffer, jump to another buffer or delete a - buffer. *E246* *E811* - NOTE: This event never nests, to avoid an - endless loop. This means that while executing - commands for the FileChangedShell event no - other FileChangedShell event will be - triggered. + Triggered for each changed file, after: + - executing a shell command + - |:checktime| + - |FocusGained| + Not used when 'autoread' is set and the buffer + was not changed. If a FileChangedShell + autocommand exists the warning message and + prompt is not given. + |v:fcs_reason| indicates what happened. Set + |v:fcs_choice| to control what happens next. + NOTE: Current buffer "%" may be different from + the buffer that was changed "<afile>". + *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. @@ -742,10 +734,10 @@ 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. - <afile> can be used for the name of the file - where this option was set, and <amatch> for - the new value of 'filetype'. Navigating to - another window or buffer is not allowed. + <afile> is the name of the file where this + option was set. <amatch> is the new value of + 'filetype'. + Cannot switch windows or buffers. See |filetypes|. *FileWriteCmd* FileWriteCmd Before writing to a file, when not writing the @@ -1018,27 +1010,26 @@ SwapExists Detected an existing swap file when starting When set to an empty string the user will be asked, as if there was no SwapExists autocmd. *E812* - It is not allowed to change to another buffer, - change a buffer name or change directory - here. + 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. - <afile> can be used for the name of the file - where this option was set, and <amatch> for - the new value of 'syntax'. + <afile> expands to the name of the file where + this option was set. <amatch> expands to the + new value of 'syntax'. See |:syn-on|. *TabEnter* TabEnter Just after entering a tab page. |tab-page| - After triggering the WinEnter and before - triggering the BufEnter event. + After WinEnter. + Before BufEnter. *TabLeave* TabLeave Just before leaving a tab page. |tab-page| - A WinLeave event will have been triggered - first. + After WinLeave. *TabNew* TabNew When creating a new tab page. |tab-page| - After WinEnter and before TabEnter. + After WinEnter. + Before TabEnter. *TabNewEntered* TabNewEntered After entering a new tab page. |tab-page| After BufEnter. @@ -1060,10 +1051,9 @@ TermClose When a |terminal| job ends. TermResponse After the response to t_RV is received from the terminal. The value of |v:termresponse| can be used to do things depending on the - terminal version. Note that this event may be - triggered halfway through another event - (especially if file I/O, a shell command, or - anything else that takes time is involved). + terminal version. May be triggered halfway + through another event (file I/O, a shell + command, or anything else that takes time). *TextChanged* TextChanged After a change was made to the text in the current buffer in Normal mode. That is after @@ -1136,6 +1126,7 @@ VimSuspend Before Nvim enters |suspend| state. *WinClosed* WinClosed After closing a window. <afile> expands to the |window-ID|. + After WinLeave. Non-recursive (event cannot trigger itself). See also |ExitPre|, |QuitPre|. *WinEnter* @@ -1155,10 +1146,11 @@ WinLeave Before leaving a window. If the window to be executes the BufLeave autocommands before the WinLeave autocommands (but not for ":new"). Not used for ":qa" or ":q" when exiting Vim. + After WinClosed. *WinNew* WinNew When a new window was created. Not done for the first window, when Vim has just started. - Before a WinEnter event. + Before WinEnter. ============================================================================== 6. Patterns *autocmd-pattern* *{pat}* |