codekingpro/portable-devtools
114k
1*autocmd.txt* For Vim version 9.2. Last change: 2026 Feb 252 3 4 VIM REFERENCE MANUAL by Bram Moolenaar5 6 7Automatic commands *autocommand* *autocommands*8 9For a basic explanation, see section |40.3| in the user manual.10 111. Introduction |autocmd-intro|122. Defining autocommands |autocmd-define|133. Removing autocommands |autocmd-remove|144. Listing autocommands |autocmd-list|155. Events |autocmd-events|166. Patterns |autocmd-patterns|177. Buffer-local autocommands |autocmd-buflocal|188. Groups |autocmd-groups|199. Executing autocommands |autocmd-execute|2010. Using autocommands |autocmd-use|2111. Disabling autocommands |autocmd-disable|22 23 24==============================================================================251. Introduction *autocmd-intro*26 27You can specify commands to be executed automatically when reading or writing28a file, when entering or leaving a buffer or window, and when exiting Vim.29For example, you can create an autocommand to set the 'cindent' option for30files matching *.c. You can also use autocommands to implement advanced31features, such as editing compressed files (see |gzip-example|). The usual32place to put autocommands is in your .vimrc or .exrc file.33 34 *E203* *E204* *E143* *E855* *E937* *E952*35WARNING: Using autocommands is very powerful, and may lead to unexpected side36effects. Be careful not to destroy your text.37- It's a good idea to do some testing on an expendable copy of a file first.38 For example: If you use autocommands to decompress a file when starting to39 edit it, make sure that the autocommands for compressing when writing work40 correctly.41- Be prepared for an error halfway through (e.g., disk full). Vim will mostly42 be able to undo the changes to the buffer, but you may have to clean up the43 changes to other files by hand (e.g., compress a file that has been44 decompressed).45- If the BufRead* events allow you to edit a compressed file, the FileRead*46 events should do the same (this makes recovery possible in some rare cases).47 It's a good idea to use the same autocommands for the File* and Buf* events48 when possible.49 50Recommended use:51- Always use a group, so that it's easy to delete the autocommand.52- Keep the command itself short, call a function to do more work.53- Make it so that the script it is defined in can be sourced several times54 without the autocommand being repeated.55 56Example in Vim9 script: >57 autocmd_add([{replace: true,58 group: 'DemoGroup',59 event: 'BufEnter',60 pattern: '*.txt',61 cmd: 'call DemoBufEnter()'62 }])63 64In legacy script: >65 call autocmd_add([#{replace: v:true,66 \ group: 'DemoGroup',67 \ event: 'BufEnter',68 \ pattern: '*.txt',69 \ cmd: 'call DemoBufEnter()'70 \ }])71 72==============================================================================732. Defining autocommands *autocmd-define*74 75 *:au* *:autocmd*76:au[tocmd] [group] {event} {aupat} [++once] [++nested] {cmd}77 Add {cmd} to the list of commands that Vim will78 execute automatically on {event} for a file matching79 {aupat} |autocmd-patterns|.80 Here {event} cannot be "*". *E1155*81 Note: A quote character is seen as argument to the82 :autocmd and won't start a comment.83 Vim always adds the {cmd} after existing autocommands,84 so that the autocommands execute in the order in which85 they were given.86 See |autocmd-nested| for [++nested]. "nested"87 (without the ++) can also be used, for backwards88 compatibility, but not in |Vim9| script. *E1078*89 *autocmd-once*90 If [++once] is supplied the command is executed once,91 then removed ("one shot").92 93The special pattern <buffer> or <buffer=N> defines a buffer-local autocommand.94See |autocmd-buflocal|.95 96If the `:autocmd` is in Vim9 script (a script that starts with `:vim9script`97and in a `:def` function) then {cmd} will be executed as in Vim998script. Thus this depends on where the autocmd is defined, not where it is99triggered.100 *:autocmd-block*101{cmd} can be a block, like with `:command`, see |:command-repl|. Example: >102 au BufReadPost *.xml {103 setlocal matchpairs+=<:>104 /<start105 }106 107The |autocmd_add()| function can be used to add a list of autocmds and autocmd108groups from a Vim script. It is preferred if you have anything that would109require using `:execute` with `:autocmd`.110 111Note: The ":autocmd" command can only be followed by another command when the112'|' appears where the pattern is expected. This works: >113 :augroup mine | au! BufRead | augroup END114But this sees "augroup" as part of the defined command: >115 :augroup mine | au! BufRead * | augroup END116 :augroup mine | au BufRead * set tw=70 | augroup END117Instead you can put the group name into the command: >118 :au! mine BufRead *119 :au mine BufRead * set tw=70120Or use `:execute`: >121 :augroup mine | exe "au! BufRead *" | augroup END122 :augroup mine | exe "au BufRead * set tw=70" | augroup END123 124< *autocmd-expand*125Note that special characters (e.g., "%", "<cword>") in the ":autocmd"126arguments are not expanded when the autocommand is defined. These will be127expanded when the Event is recognized, and the {cmd} is executed. The only128exception is that "<sfile>" is expanded when the autocmd is defined. Example:129>130 :au BufNewFile,BufRead *.html so <sfile>:h/html.vim131 132Here Vim expands <sfile> to the name of the file containing this line.133However, <sfile> works differently in a function, in which case it's better to134use `:execute` with <script> to achieve the same purpose:135>136 :exe $'au BufNewFile,BufRead *.html so {expand("<script>:h")}/html.vim'137 138`:autocmd` adds to the list of autocommands regardless of whether they are139already present. When your .vimrc file is sourced twice, the autocommands140will appear twice. To avoid this, define your autocommands in a group, so141that you can easily clear them: >142 143 augroup vimrc144 " Remove all vimrc autocommands145 autocmd!146 au BufNewFile,BufRead *.html so <sfile>:h/html.vim147 augroup END148 149If you don't want to remove all autocommands, you can instead use a variable150to ensure that Vim includes the autocommands only once: >151 152 :if !exists("autocommands_loaded")153 : let autocommands_loaded = 1154 : au ...155 :endif156 157When the [group] argument is not given, Vim uses the current group (as defined158with ":augroup"); otherwise, Vim uses the group defined with [group]. Note159that [group] must have been defined before. You cannot define a new group160with ":au group ..."; use ":augroup" for that.161 162While testing autocommands, you might find the 'verbose' option to be useful: >163 :set verbose=9164This setting makes Vim echo the autocommands as it executes them.165 166When defining an autocommand in a script, it will be able to call functions167local to the script and use mappings local to the script. When the event is168triggered and the command executed, it will run in the context of the script169it was defined in. This matters if |<SID>| is used in a command.170 171When executing the commands, the message from one command overwrites a172previous message. This is different from when executing the commands173manually. Mostly the screen will not scroll up, thus there is no hit-enter174prompt. When one command outputs two messages this can happen anyway.175 176==============================================================================1773. Removing autocommands *autocmd-remove*178 179In addition to the below described commands, the |autocmd_delete()| function can180be used to remove a list of autocmds and autocmd groups from a Vim script.181 182:au[tocmd]! [group] {event} {aupat} [++once] [++nested] {cmd}183 Remove all autocommands associated with {event} and184 {aupat}, and add the command {cmd}.185 See |autocmd-once| for [++once].186 See |autocmd-nested| for [++nested].187 188:au[tocmd]! [group] {event} {aupat}189 Remove all autocommands associated with {event} and190 {aupat}.191 192:au[tocmd]! [group] * {aupat}193 Remove all autocommands associated with {aupat} for194 all events.195 196:au[tocmd]! [group] {event}197 Remove ALL autocommands for {event}.198 Warning: You should not do this without a group for199 |BufRead| and other common events, it can break200 plugins, syntax highlighting, etc.201 202:au[tocmd]! [group] Remove ALL autocommands.203 Note: a quote will be seen as argument to the :autocmd204 and won't start a comment.205 Warning: You should normally not do this without a206 group, it breaks plugins, syntax highlighting, etc.207 208When the [group] argument is not given, Vim uses the current group (as defined209with ":augroup"); otherwise, Vim uses the group defined with [group].210 211==============================================================================2124. Listing autocommands *autocmd-list*213 214:au[tocmd] [group] {event} {aupat}215 Show the autocommands associated with {event} and216 {aupat}.217 218:au[tocmd] [group] * {aupat}219 Show the autocommands associated with {aupat} for all220 events.221 222:au[tocmd] [group] {event}223 Show all autocommands for {event}.224 225:au[tocmd] [group] Show all autocommands.226 227If you provide the [group] argument, Vim lists only the autocommands for228[group]; otherwise, Vim lists the autocommands for ALL groups. Note that this229argument behavior differs from that for defining and removing autocommands.230 231In order to list buffer-local autocommands, use a pattern in the form <buffer>232or <buffer=N>. See |autocmd-buflocal|.233 234The |autocmd_get()| function can be used from a Vim script to get a list of235autocmds.236 237 *:autocmd-verbose*238When 'verbose' is non-zero, listing an autocommand will also display where it239was last defined. Example: >240 241 :verbose autocmd BufEnter242 FileExplorer BufEnter243 * call s:LocalBrowse(expand("<amatch>"))244 Last set from /usr/share/vim/vim-7.0/plugin/NetrwPlugin.vim245<246See |:verbose-cmd| for more information.247 248==============================================================================2495. Events *autocmd-events* *E215* *E216*250 251You can specify a comma-separated list of event names. No white space can be252used in this list. The command applies to all the events in the list.253 254For READING FILES there are four kinds of events possible:255 BufNewFile starting to edit a non-existent file256 BufReadPre BufReadPost starting to edit an existing file257 FilterReadPre FilterReadPost read the temp file with filter output258 FileReadPre FileReadPost any other file read259Vim uses only one of these four kinds when reading a file. The "Pre" and260"Post" events are both triggered, before and after reading the file.261 262Note that the autocommands for the *ReadPre events and all the Filter events263are not allowed to change the current buffer (you will get an error message if264this happens). This is to prevent the file to be read into the wrong buffer.265 266Note that the 'modified' flag is reset AFTER executing the BufReadPost267and BufNewFile autocommands. But when the 'modified' option was set by the268autocommands, this doesn't happen.269 270You can use the 'eventignore' option to ignore a number of events or all271events.272 *autocommand-events* *{event}*273Vim recognizes the following events. Vim ignores the case of event names274(e.g., you can use "BUFread" or "bufread" instead of "BufRead").275 276First an overview by function with a short explanation. Then the list277alphabetically with full explanations |autocmd-events-abc|.278 279Name triggered by ~280 281 Reading282|BufNewFile| starting to edit a file that doesn't exist283|BufReadPre| starting to edit a new buffer, before reading the file284|BufRead| starting to edit a new buffer, after reading the file285|BufReadPost| starting to edit a new buffer, after reading the file286|BufReadCmd| before starting to edit a new buffer |Cmd-event|287 288|FileReadPre| before reading a file with a ":read" command289|FileReadPost| after reading a file with a ":read" command290|FileReadCmd| before reading a file with a ":read" command |Cmd-event|291 292|FilterReadPre| before reading a file from a filter command293|FilterReadPost| after reading a file from a filter command294 295|StdinReadPre| before reading from stdin into the buffer296|StdinReadPost| After reading from the stdin into the buffer297 298 Writing299|BufWrite| starting to write the whole buffer to a file300|BufWritePre| starting to write the whole buffer to a file301|BufWritePost| after writing the whole buffer to a file302|BufWriteCmd| before writing the whole buffer to a file |Cmd-event|303 304|FileWritePre| starting to write part of a buffer to a file305|FileWritePost| after writing part of a buffer to a file306|FileWriteCmd| before writing part of a buffer to a file |Cmd-event|307 308|FileAppendPre| starting to append to a file309|FileAppendPost| after appending to a file310|FileAppendCmd| before appending to a file |Cmd-event|311 312|FilterWritePre| starting to write a file for a filter command or diff313|FilterWritePost| after writing a file for a filter command or diff314 315 Buffers316|BufAdd| just after adding a buffer to the buffer list317|BufCreate| just after adding a buffer to the buffer list318|BufDelete| before deleting a buffer from the buffer list319|BufWipeout| before completely deleting a buffer320 321|BufFilePre| before changing the name of the current buffer322|BufFilePost| after changing the name of the current buffer323 324|BufEnter| after entering a buffer325|BufLeave| before leaving to another buffer326|BufWinEnter| after a buffer is displayed in a window327|BufWinLeave| before a buffer is removed from a window328 329|BufUnload| before unloading a buffer330|BufHidden| just before a buffer becomes hidden331|BufNew| just after creating a new buffer332 333|SwapExists| detected an existing swap file334 335 Options336|FileType| when the 'filetype' option has been set337|Syntax| when the 'syntax' option has been set338|EncodingChanged| after the 'encoding' option has been changed339|TermChanged| after the value of 'term' has changed340|OptionSet| after setting any option341 342 Startup and exit343|VimEnter| after doing all the startup stuff344|GUIEnter| after starting the GUI successfully345|GUIFailed| after starting the GUI failed346|TermResponse| after the terminal response to |t_RV| is received347|TermResponseAll| after the terminal response to |t_RV| and others is348 received349 350|QuitPre| when using `:quit`, before deciding whether to exit351|ExitPre| when using a command that may make Vim exit352|VimLeavePre| before exiting Vim, before writing the viminfo file353|VimLeave| before exiting Vim, after writing the viminfo file354 355|VimSuspend| when suspending Vim356|VimResume| when Vim is resumed after being suspended357 358 Terminal359|TerminalOpen| after a terminal buffer was created360|TerminalWinOpen| after a terminal buffer was created in a new window361 362 Various363|FileChangedShell| Vim notices that a file changed since editing started364|FileChangedShellPost| After handling a file changed since editing started365|FileChangedRO| before making the first change to a read-only file366 367|DiffUpdated| after diffs have been updated368|DirChangedPre| before the working directory will change369|DirChanged| after the working directory has changed370 371|ShellCmdPost| after executing a shell command372|ShellFilterPost| after filtering with a shell command373 374|CmdUndefined| a user command is used but it isn't defined375|FuncUndefined| a user function is used but it isn't defined376|SpellFileMissing| a spell file is used but it can't be found377|SourcePre| before sourcing a Vim script378|SourcePost| after sourcing a Vim script379|SourceCmd| before sourcing a Vim script |Cmd-event|380 381|VimResized| after the Vim window size changed382|FocusGained| Vim got input focus383|FocusLost| Vim lost input focus384|CursorHold| the user doesn't press a key for a while385|CursorHoldI| the user doesn't press a key for a while in Insert386 mode387|CursorMoved| the cursor was moved in Normal mode388|CursorMovedC| the cursor was moved in the |Command-line|389|CursorMovedI| the cursor was moved in Insert mode390 391|WinNewPre| before creating a new window392|WinNew| after creating a new window393|TabNew| after creating a new tab page394|WinClosed| after closing a window395|TabClosed| after closing a tab page396|TabClosedPre| before closing a tab page397|WinEnter| after entering another window398|WinLeave| before leaving a window399|TabEnter| after entering another tab page400|TabLeave| before leaving a tab page401|CmdwinEnter| after entering the command-line window402|CmdwinLeave| before leaving the command-line window403 404|CmdlineChanged| after a change was made to the command-line text405|CmdlineEnter| after the cursor moves to the command line406|CmdlineLeave| before the cursor leaves the command line407|CmdlineLeavePre| before preparing to leave the command line408 409|InsertEnter| starting Insert mode410|InsertChange| when typing <Insert> while in Insert or Replace mode411|InsertLeave| when leaving Insert mode412|InsertLeavePre| just before leaving Insert mode413|InsertCharPre| when a character was typed in Insert mode, before414 inserting it415 416|ModeChanged| after changing the mode417 418|TextChanged| after a change was made to the text in Normal mode419|TextChangedI| after a change was made to the text in Insert mode420 when popup menu is not visible421|TextChangedP| after a change was made to the text in Insert mode422 when popup menu visible423|TextChangedT| after a change was made to the text in Terminal mode424|TextYankPost| after text has been yanked or deleted425 426|SafeState| nothing pending, going to wait for the user to type a427 character428|SafeStateAgain| repeated SafeState429 430|ColorSchemePre| before loading a color scheme431|ColorScheme| after loading a color scheme432 433|RemoteReply| a reply from a server Vim was received434 435|QuickFixCmdPre| before a quickfix command is run436|QuickFixCmdPost| after a quickfix command is run437 438|SessionLoadPre| before loading a session file439|SessionLoadPost| after loading a session file440 441|SessionWritePost| after writing the session file using442 the |:mksession| command443 444|MenuPopup| just before showing the popup menu445|CompleteChanged| after Insert mode completion menu changed446|CompleteDonePre| after Insert mode completion is done, before clearing447 info448|CompleteDone| after Insert mode completion is done, after clearing449 info450 451|KeyInputPre| just before a key is processed452 453|User| to be used in combination with ":doautocmd"454|SigUSR1| after the SIGUSR1 signal has been detected455 456|WinScrolled| after scrolling or resizing a window457 458 459The alphabetical list of autocommand events: *autocmd-events-abc*460 461 *BufCreate* *BufAdd*462BufAdd or BufCreate Just after creating a new buffer which is463 added to the buffer list, or adding a buffer464 to the buffer list.465 Also used just after a buffer in the buffer466 list has been renamed.467 Not triggered for the initial buffers created468 during startup.469 The BufCreate event is for historic reasons.470 NOTE: When this autocommand is executed, the471 current buffer "%" may be different from the472 buffer being created "<afile>".473 *BufDelete*474BufDelete Before deleting a buffer from the buffer list.475 The BufUnload may be called first (if the476 buffer was loaded).477 Also used just before a buffer in the buffer478 list is renamed.479 NOTE: When this autocommand is executed, the480 current buffer "%" may be different from the481 buffer being deleted "<afile>" and "<abuf>".482 Don't change to another buffer, it will cause483 problems.484 *BufEnter*485BufEnter After entering a buffer. Useful for setting486 options for a file type. Also executed when487 starting to edit a buffer, after the488 BufReadPost autocommands.489 *BufFilePost*490BufFilePost After changing the name of the current buffer491 with the ":file" or ":saveas" command.492 *BufFilePre*493BufFilePre Before changing the name of the current buffer494 with the ":file" or ":saveas" command.495 *BufHidden*496BufHidden Just before a buffer becomes hidden. That is,497 when there are no longer windows that show498 the buffer, but the buffer is not unloaded or499 deleted. Not used for ":qa" or ":q" when500 exiting Vim.501 NOTE: When this autocommand is executed, the502 current buffer "%" may be different from the503 buffer being unloaded "<afile>".504 *BufLeave*505BufLeave Before leaving to another buffer. Also when506 leaving or closing the current window and the507 new current window is not for the same buffer.508 Not used for ":qa" or ":q" when exiting Vim.509 *BufNew*510BufNew Just after creating a new buffer. Also used511 just after a buffer has been renamed. When512 the buffer is added to the buffer list BufAdd513 will be triggered too.514 NOTE: When this autocommand is executed, the515 current buffer "%" may be different from the516 buffer being created "<afile>".517 *BufNewFile*518BufNewFile When starting to edit a file that doesn't519 exist. Can be used to read in a skeleton520 file.521 *BufRead* *BufReadPost*522BufRead or BufReadPost When starting to edit a new buffer, after523 reading the file into the buffer, before524 executing the modelines. See |BufWinEnter|525 for when you need to do something after526 processing the modelines.527 Also triggered:528 - when writing an unnamed buffer in a way that529 the buffer gets a name530 - after successfully recovering a file531 - for the filetypedetect group when executing532 ":filetype detect"533 Not triggered:534 - for the `:read file` command535 - when the file doesn't exist536 *BufReadCmd*537BufReadCmd Before starting to edit a new buffer. Should538 read the file into the buffer. |Cmd-event|539 *BufReadPre* *E200* *E201*540BufReadPre When starting to edit a new buffer, before541 reading the file into the buffer. Not used542 if the file doesn't exist.543 *BufUnload*544BufUnload Before unloading a buffer. This is when the545 text in the buffer is going to be freed. This546 may be after a BufWritePost and before a547 BufDelete. Also used for all buffers that are548 loaded when Vim is going to exit.549 NOTE: When this autocommand is executed, the550 current buffer "%" may be different from the551 buffer being unloaded "<afile>".552 *E1546*553 Don't change to another buffer or window, it554 will cause problems!555 When exiting and v:dying is 2 or more this556 event is not triggered.557 *BufWinEnter*558BufWinEnter After a buffer is displayed in a window. This559 can be when the buffer is loaded (after560 processing the modelines) or when a hidden561 buffer is displayed in a window (and is no562 longer hidden).563 Does not happen for |:split| without564 arguments, since you keep editing the same565 buffer, or ":split" with a file that's already566 open in a window, because it re-uses an567 existing buffer. But it does happen for a568 ":split" with the name of the current buffer,569 since it reloads that buffer.570 Does not happen for a terminal window, because571 it starts in Terminal-Job mode and Normal mode572 commands won't work. Use |TerminalOpen|573 instead.574 *BufWinLeave*575BufWinLeave Before a buffer is removed from a window.576 Not when it's still visible in another window.577 Also triggered when exiting. It's triggered578 before BufUnload or BufHidden.579 NOTE: When this autocommand is executed, the580 current buffer "%" may be different from the581 buffer being unloaded "<afile>".582 When exiting and v:dying is 2 or more this583 event is not triggered.584 *BufWipeout*585BufWipeout Before completely deleting a buffer. The586 BufUnload and BufDelete events may be called587 first (if the buffer was loaded and was in the588 buffer list). Also used just before a buffer589 is renamed (also when it's not in the buffer590 list).591 NOTE: When this autocommand is executed, the592 current buffer "%" may be different from the593 buffer being deleted "<afile>".594 Don't change to another buffer, it will cause595 problems.596 *BufWrite* *BufWritePre*597BufWrite or BufWritePre Before writing the whole buffer to a file.598 *BufWriteCmd*599BufWriteCmd Before writing the whole buffer to a file.600 Should do the writing of the file and reset601 'modified' if successful, unless '+' is in602 'cpo' and writing to another file |cpo-+|.603 The buffer contents should not be changed.604 When the command resets 'modified' the undo605 information is adjusted to mark older undo606 states as 'modified', like |:write| does. Use607 the |'[| and |']| marks for the range of lines.608 |Cmd-event|609 *BufWritePost*610BufWritePost After writing the whole buffer to a file611 (should undo the commands for BufWritePre).612 *CmdUndefined*613CmdUndefined When a user command is used but it isn't614 defined. Useful for defining a command only615 when it's used. The pattern is matched616 against the command name. Both <amatch> and617 <afile> are set to the name of the command.618 This is triggered even when inside an619 autocommand defined without |autocmd-nested|.620 NOTE: Autocompletion won't work until the621 command is defined. An alternative is to622 always define the user command and have it623 invoke an autoloaded function. See |autoload|.624 *CmdlineChanged*625CmdlineChanged After a change was made to the text in the626 command line. Be careful not to mess up627 the command line, it may cause Vim to lock up.628 <afile> is set to a single character,629 indicating the type of command-line.630 |cmdwin-char|631 *CmdlineEnter*632CmdlineEnter After moving the cursor to the command line,633 where the user can type a command or search634 string; including non-interactive use of ":"635 in a mapping, but not when using |<Cmd>|.636 The pattern is matched against the character637 representing the type of command-line.638 |cmdwin-char|639 <afile> is set to a single character,640 indicating the type of command-line.641 *CmdlineLeave*642CmdlineLeave Before leaving the command line; including643 non-interactive use of ":" in a mapping, but644 not when using |<Cmd>|.645 Also when abandoning the command line, after646 typing CTRL-C or <Esc>.647 When the commands result in an error the648 command line is still executed.649 <afile> is set to a single character,650 indicating the type of command-line.651 |cmdwin-char|652 Sets the |v:char| to the key that exited the653 command-line (e.g. <CR>, <CTRL-C>, <Esc>).654 *CmdlineLeavePre*655CmdlineLeavePre Just before leaving the command line, and656 before |CmdlineLeave|. Useful for capturing657 completion info with |cmdcomplete_info()|, as658 this information is cleared before659 |CmdlineLeave| is triggered. Triggered for660 non-interactive use of ":" in a mapping, but661 not when using |<Cmd>|. Also triggered when662 abandoning the command line by typing CTRL-C663 or <Esc>. <afile> is set to a single664 character indicating the command-line type.665 See |cmdwin-char| for details.666 Sets |v:char| as with |CmdlineLeave|.667 *CmdwinEnter*668CmdwinEnter After entering the command-line window.669 Useful for setting options specifically for670 this special type of window.671 <afile> is set to a single character,672 indicating the type of command-line.673 |cmdwin-char|674 *CmdwinLeave*675CmdwinLeave Before leaving the command-line window.676 Useful to clean up any global setting done677 with CmdwinEnter.678 <afile> is set to a single character,679 indicating the type of command-line.680 |cmdwin-char|681 *ColorScheme*682ColorScheme After loading a color scheme. |:colorscheme|683 Not triggered if the color scheme is not684 found.685 The pattern is matched against the686 colorscheme name. <afile> can be used for the687 name of the actual file where this option was688 set, and <amatch> for the new colorscheme689 name.690 691 *ColorSchemePre*692ColorSchemePre Before loading a color scheme. |:colorscheme|693 Useful to setup removing things added by a694 color scheme, before another one is loaded.695CompleteChanged *CompleteChanged*696 After each time the Insert mode completion697 menu changed. Not fired on popup menu hide,698 use |CompleteDonePre| or |CompleteDone| for699 that. Never triggered recursively.700 701 Sets these |v:event| keys:702 completed_item See |complete-items|.703 height nr of items visible704 width screen cells705 row top screen row706 col leftmost screen column707 size total nr of items708 scrollbar TRUE if visible709 710 It is not allowed to change the text |textlock|.711 712 The size and position of the popup are also713 available by calling |pum_getpos()|.714 715 *CompleteDonePre*716CompleteDonePre After Insert mode completion is done. Either717 when something was completed or abandoning718 completion. |ins-completion|719 |complete_info()| can be used, the info is720 cleared after triggering CompleteDonePre.721 The |v:completed_item| variable contains722 information about the completed item.723 724 *CompleteDone*725CompleteDone After Insert mode completion is done. Either726 when something was completed or abandoning727 completion. |ins-completion|728 |complete_info()| cannot be used, the info is729 cleared before triggering CompleteDone. Use730 CompleteDonePre if you need it.731 The |v:completed_item| variable contains732 information about the completed item.733 734 Sets these |v:event| keys:735 complete_word The word that was736 selected, empty if737 abandoned complete.738 complete_type |complete_info_mode|739 740 *CursorHold*741CursorHold When the user doesn't press a key for the time742 specified with 'updatetime'. Not triggered743 until the user has pressed a key (i.e. doesn't744 fire every 'updatetime' ms if you leave Vim to745 make some coffee. :) See |CursorHold-example|746 for previewing tags.747 This event is only triggered in Normal mode.748 It is not triggered when waiting for a command749 argument to be typed, or a movement after an750 operator.751 While recording the CursorHold event is not752 triggered. |q|753 *<CursorHold>*754 Internally the autocommand is triggered by the755 <CursorHold> key. In an expression mapping756 |getchar()| may see this character.757 758 Note: Interactive commands cannot be used for759 this event. There is no hit-enter prompt,760 the screen is updated directly (when needed).761 Note: In the future there will probably be762 another option to set the time.763 Hint: to force an update of the status lines764 use: >765 :let &ro = &ro766< {only on Amiga, Unix, Win32 and all GUI767 versions}768 *CursorHoldI*769CursorHoldI Just like CursorHold, but in Insert mode.770 Not triggered when waiting for another key,771 e.g. after CTRL-V, and not when in CTRL-X mode772 |insert_expand|.773 774 *CursorMoved*775CursorMoved After the cursor was moved in Normal or Visual776 mode. Also when the text of the cursor line777 has been changed, e.g., with "x", "rx" or "p".778 Not always triggered when there is typeahead,779 while executing commands in a script file,780 when an operator is pending or when moving to781 another window while remaining at the same782 cursor position.783 For an example see |match-parens|.784 Note: This can not be skipped with785 `:noautocmd`.786 Careful: This is triggered very often, don't787 do anything that the user does not expect or788 that is slow.789 *CursorMovedC*790CursorMovedC After the cursor was moved in the command791 line. Be careful not to mess up the command792 line, it may cause Vim to lock up.793 <afile> is set to a single character,794 indicating the type of command-line.795 |cmdwin-char|796 *CursorMovedI*797CursorMovedI After the cursor was moved in Insert mode.798 Not triggered when the popup menu is visible.799 Otherwise the same as CursorMoved.800 *DiffUpdated*801DiffUpdated After diffs have been updated. Depending on802 what kind of diff is being used (internal or803 external) this can be triggered on every804 change or when doing |:diffupdate|.805 *DirChangedPre*806DirChangedPre The working directory is going to be changed,807 as with |DirChanged|. The pattern is like808 with |DirChanged|. The new directory can be809 found in v:event.directory.810 *DirChanged*811DirChanged The working directory has changed in response812 to the |:cd| or |:tcd| or |:lcd| commands, or813 as a result of the 'autochdir' option.814 The pattern can be:815 "window" to trigger on `:lcd`816 "tabpage" to trigger on `:tcd`817 "global" to trigger on `:cd`818 "auto" to trigger on 'autochdir'.819 "drop" to trigger on editing a file820 <afile> is set to the new directory name.821 *EncodingChanged*822EncodingChanged Fires off after the 'encoding' option has been823 changed. Useful to set up fonts, for example.824 *ExitPre*825ExitPre When using `:quit`, `:wq` in a way it makes826 Vim exit, or using `:qall`, just after827 |QuitPre|. Can be used to close any828 non-essential window. Exiting may still be829 cancelled if there is a modified buffer that830 isn't automatically saved, use |VimLeavePre|831 for really exiting.832 *FileAppendCmd*833FileAppendCmd Before appending to a file. Should do the834 appending to the file. Use the '[ and ']835 marks for the range of lines. |Cmd-event|836 *FileAppendPost*837FileAppendPost After appending to a file.838 *FileAppendPre*839FileAppendPre Before appending to a file. Use the '[ and ']840 marks for the range of lines.841 *FileChangedRO*842FileChangedRO Before making the first change to a read-only843 file. Can be used to check-out the file from844 a source control system. Not triggered when845 the change was caused by an autocommand.846 This event is triggered when making the first847 change in a buffer or the first change after848 'readonly' was set, just before the change is849 applied to the text.850 WARNING: If the autocommand moves the cursor851 the effect of the change is undefined.852 *E788*853 It is not allowed to change to another buffer854 here. You can reload the buffer but not edit855 another one.856 *E881*857 If the number of lines changes saving for undo858 may fail and the change will be aborted.859 *FileChangedShell*860FileChangedShell When Vim notices that the modification time of861 a file has changed since editing started.862 Also when the file attributes of the file863 change or when the size of the file changes.864 |timestamp|865 Mostly triggered after executing a shell866 command, but also with a |:checktime| command867 or when gvim regains input focus.868 This autocommand is triggered for each changed869 file. It is not used when 'autoread' is set870 and the buffer was not changed. If a871 FileChangedShell autocommand is present the872 warning message and prompt is not given.873 The |v:fcs_reason| variable is set to indicate874 what happened and |v:fcs_choice| can be used875 to tell Vim what to do next.876 NOTE: When this autocommand is executed, the877 current buffer "%" may be different from the878 buffer that was changed, which is in879 "<afile>".880 NOTE: The commands must not change the current881 buffer, jump to another buffer or delete a882 buffer. *E246* *E811*883 NOTE: This event never nests, to avoid an884 endless loop. This means that while executing885 commands for the FileChangedShell event no886 other FileChangedShell event will be887 triggered.888 *FileChangedShellPost*889FileChangedShellPost After handling a file that was changed outside890 of Vim. Can be used to update the statusline.891 *FileEncoding*892FileEncoding Obsolete. It still works and is equivalent893 to |EncodingChanged|.894 *FileReadCmd*895FileReadCmd Before reading a file with a ":read" command.896 Should do the reading of the file. |Cmd-event|897 *FileReadPost*898FileReadPost After reading a file with a ":read" command.899 Note that Vim sets the '[ and '] marks to the900 first and last line of the read. This can be901 used to operate on the lines just read.902 *FileReadPre*903FileReadPre Before reading a file with a ":read" command.904 *FileType*905FileType When the 'filetype' option has been set. The906 pattern is matched against the filetype.907 <afile> can be used for the name of the file908 where this option was set, and <amatch> for909 the new value of 'filetype'. Navigating to910 another window or buffer is not allowed.911 See |filetypes|.912 *FileWriteCmd*913FileWriteCmd Before writing to a file, when not writing the914 whole buffer. Should do the writing to the915 file. Should not change the buffer. Use the916 |'[| and |']| marks for the range of lines.917 |Cmd-event|918 *FileWritePost*919FileWritePost After writing to a file, when not writing the920 whole buffer.921 *FileWritePre*922FileWritePre Before writing to a file, when not writing the923 whole buffer. Use the |'[| and |']| marks for the924 range of lines.925 *FilterReadPost*926FilterReadPost After reading a file from a filter command.927 Vim checks the pattern against the name of928 the current buffer as with FilterReadPre.929 Not triggered when 'shelltemp' is off.930 *FilterReadPre* *E135*931FilterReadPre Before reading a file from a filter command.932 Vim checks the pattern against the name of933 the current buffer, not the name of the934 temporary file that is the output of the935 filter command.936 Not triggered when 'shelltemp' is off.937 *FilterWritePost*938FilterWritePost After writing a file for a filter command or939 making a diff with an external diff (see940 |DiffUpdated| for internal diff).941 Vim checks the pattern against the name of942 the current buffer as with FilterWritePre.943 Not triggered when 'shelltemp' is off.944 *FilterWritePre*945FilterWritePre Before writing a file for a filter command or946 making a diff with an external diff.947 Vim checks the pattern against the name of948 the current buffer, not the name of the949 temporary file that is the output of the950 filter command.951 Not triggered when 'shelltemp' is off.952 *FocusGained*953FocusGained When Vim got input focus. Only for the GUI954 version and a few console versions where this955 can be detected. |xterm-focus-event|956 *FocusLost*957FocusLost When Vim lost input focus. Only for the GUI958 version and a few console versions where this959 can be detected. |xterm-focus-event|960 May also happen when a dialog pops up.961 *FuncUndefined*962FuncUndefined When a user function is used but it isn't963 defined. Useful for defining a function only964 when it's used. The pattern is matched965 against the function name. Both <amatch> and966 <afile> are set to the name of the function.967 This is triggered even when inside an968 autocommand defined without |autocmd-nested|,969 but not triggered when compiling a |Vim9|970 function.971 NOTE: When writing Vim scripts a better972 alternative is to use an autoloaded function.973 See |autoload-functions|.974 *GUIEnter*975GUIEnter After starting the GUI successfully, and after976 opening the window. It is triggered before977 VimEnter when using gvim. Can be used to978 position the window from a .gvimrc file: >979 :autocmd GUIEnter * winpos 100 50980< *GUIFailed*981GUIFailed After starting the GUI failed. Vim may982 continue to run in the terminal, if possible983 (only on Unix and alikes, when connecting the984 X server fails). You may want to quit Vim: >985 :autocmd GUIFailed * qall986< *InsertChange*987InsertChange When typing <Insert> while in Insert or988 Replace mode. The |v:insertmode| variable989 indicates the new mode.990 Be careful not to move the cursor or do991 anything else that the user does not expect.992 *InsertCharPre*993InsertCharPre When a character is typed in Insert mode,994 before inserting the char.995 The |v:char| variable indicates the char typed996 and can be changed during the event to insert997 a different character. When |v:char| is set998 to more than one character this text is999 inserted literally.1000 It is not allowed to change the text |textlock|.1001 The event is not triggered when 'paste' is1002 set. {only with the +eval feature}1003 *InsertEnter*1004InsertEnter Just before starting Insert mode. Also for1005 Replace mode and Virtual Replace mode. The1006 |v:insertmode| variable indicates the mode.1007 Be careful not to do anything else that the1008 user does not expect.1009 The cursor is restored afterwards. If you do1010 not want that set |v:char| to a non-empty1011 string.1012 *InsertLeavePre*1013InsertLeavePre Just before leaving Insert mode. Also when1014 using CTRL-O |i_CTRL-O|. Be careful not to1015 change mode or use `:normal`, it will likely1016 cause trouble.1017 *InsertLeave*1018InsertLeave Just after leaving Insert mode. Also when1019 using CTRL-O |i_CTRL-O|. But not for |i_CTRL-C|.1020 *KeyInputPre*1021KeyInputPre Just before a key is processed after mappings1022 have been applied. The pattern is matched1023 against a string that indicates the current1024 mode, which is the same as what is returned by1025 `mode(1)`.1026 The |v:char| variable indicates the key typed1027 and can be changed during the event to process1028 a different key. When |v:char| is not a1029 single character or a special key, the first1030 character is used.1031 The following values of |v:event| are set:1032 typed The key is typed or not.1033 typedchar The (actual) typed key since1034 the last |KeyInputPre| call.1035 Note: "typedchar" may be empty if successive1036 |KeyInputPre| autocmds are processed.1037 It is not allowed to change the text1038 |textlock| or the current mode.1039 {only with the +eval feature}1040 *MenuPopup*1041MenuPopup Just before showing the popup menu (under the1042 right mouse button). Useful for adjusting the1043 menu for what is under the cursor or mouse1044 pointer.1045 The pattern is matched against one or two1046 characters representing the mode:1047 n Normal1048 v Visual1049 o Operator-pending1050 i Insert1051 c Command line1052 tl Terminal1053 *ModeChanged*1054ModeChanged After changing the mode. The pattern is1055 matched against `'old_mode:new_mode'`, for1056 example match against `*:c*` to simulate1057 |CmdlineEnter|.1058 The following values of |v:event| are set:1059 old_mode The mode before it changed.1060 new_mode The new mode as also returned1061 by |mode()| called with a1062 non-zero argument.1063 When ModeChanged is triggered, old_mode will1064 have the value of new_mode when the event was1065 last triggered.1066 This will be triggered on every minor mode1067 change.1068 Usage example to use relative line numbers1069 when entering Visual mode: >1070 :au ModeChanged [vV\x16]*:* let &l:rnu = mode() =~# '^[vV\x16]'1071 :au ModeChanged *:[vV\x16]* let &l:rnu = mode() =~# '^[vV\x16]'1072 :au WinEnter,WinLeave * let &l:rnu = mode() =~# '^[vV\x16]'1073< *OptionSet*1074OptionSet After setting an option. The pattern is1075 matched against the long option name.1076 |<amatch>| indicates what option has been set.1077 1078 |v:option_type| indicates whether it's global1079 or local scoped.1080 |v:option_command| indicates what type of1081 set/let command was used (follow the tag to1082 see the table).1083 |v:option_new| indicates the newly set value.1084 |v:option_oldlocal| has the old local value.1085 |v:option_oldglobal| has the old global value.1086 |v:option_old| indicates the old option value.1087 1088 |v:option_oldlocal| is only set when |:set|1089 or |:setlocal| or a |modeline| was used to set1090 the option. Similarly |v:option_oldglobal| is1091 only set when |:set| or |:setglobal| was used.1092 1093 This does not set |<abuf>|, you could use1094 |bufnr()|.1095 1096 Note that when setting a |global-local| string1097 option with |:set|, then |v:option_old| is the1098 old global value. However, for all other1099 kinds of options (local string options,1100 global-local number options, ...) it is the1101 old local value.1102 1103 OptionSet is not triggered on startup and for1104 the 'key' option for obvious reasons.1105 1106 Usage example: Check for the existence of the1107 directory in the 'backupdir' and 'undodir'1108 options, create the directory if it doesn't1109 exist yet.1110 1111 Note: It's a bad idea to reset an option1112 during this autocommand, this may break a1113 plugin. You can always use `:noa` to prevent1114 triggering this autocommand.1115 1116 When using |:set| in the autocommand the event1117 is not triggered again.1118 *QuickFixCmdPre*1119QuickFixCmdPre Before a quickfix command is run (|:make|,1120 |:lmake|, |:grep|, |:lgrep|, |:grepadd|,1121 |:lgrepadd|, |:vimgrep|, |:lvimgrep|,1122 |:vimgrepadd|, |:lvimgrepadd|, |:cscope|,1123 |:cfile|, |:cgetfile|, |:caddfile|, |:lfile|,1124 |:lgetfile|, |:laddfile|, |:helpgrep|,1125 |:lhelpgrep|, |:cexpr|, |:cgetexpr|,1126 |:caddexpr|, |:cbuffer|, |:cgetbuffer|,1127 |:caddbuffer|).1128 The pattern is matched against the command1129 being run. When |:grep| is used but 'grepprg'1130 is set to "internal" it still matches "grep".1131 This command cannot be used to set the1132 'makeprg' and 'grepprg' variables.1133 If this command causes an error, the quickfix1134 command is not executed.1135 *QuickFixCmdPost*1136QuickFixCmdPost Like QuickFixCmdPre, but after a quickfix1137 command is run, before jumping to the first1138 location. For |:cfile| and |:lfile| commands1139 it is run after the error file is read and1140 before moving to the first error.1141 See |QuickFixCmdPost-example|.1142 *QuitPre*1143QuitPre When using `:quit`, `:wq` or `:qall`, before1144 deciding whether it closes the current window1145 or quits Vim. For `:wq` the buffer is written1146 before QuitPre is triggered. Can be used to1147 close any non-essential window if the current1148 window is the last ordinary window.1149 Also see |ExitPre|.1150 *RemoteReply*1151RemoteReply When a reply from a Vim that functions as1152 server was received |server2client()|. The1153 pattern is matched against the {serverid}.1154 <amatch> is equal to the {serverid} from which1155 the reply was sent, and <afile> is the actual1156 reply string.1157 Note that even if an autocommand is defined,1158 the reply should be read with |remote_read()|1159 to consume it.1160 *SafeState*1161SafeState When nothing is pending, going to wait for the1162 user to type a character.1163 This will not be triggered when:1164 - an operator is pending1165 - a register was entered with "r1166 - halfway executing a command1167 - executing a mapping1168 - there is typeahead1169 - Insert mode completion is active1170 - Command line completion is active1171 You can use `mode()` to find out what state1172 Vim is in. That may be:1173 - Visual mode1174 - Normal mode1175 - Insert mode1176 - Command-line mode1177 Depending on what you want to do, you may also1178 check more with `state()`, e.g. whether the1179 screen was scrolled for messages.1180 *SafeStateAgain*1181SafeStateAgain Like SafeState but after processing any1182 messages and invoking callbacks. This may be1183 triggered often, don't do something that takes1184 time.1185 1186 *SessionLoadPre*1187SessionLoadPre Before loading the session file created using1188 the |:mksession| command.1189 *SessionLoadPost*1190SessionLoadPost After loading the session file created using1191 the |:mksession| command.1192 *SessionWritePost*1193SessionWritePost After writing a session file by calling1194 the |:mksession| command.1195 *ShellCmdPost*1196ShellCmdPost After executing a shell command with |:!cmd|,1197 |:shell|, |:make| and |:grep|. Can be used to1198 check for any changed files.1199 *ShellFilterPost*1200ShellFilterPost After executing a shell command with