1*autocmd.txt* For Vim version 8.2. Last change: 2021 Oct 04 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 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 writing 28a 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 for 30files matching *.c. You can also use autocommands to implement advanced 31features, such as editing compressed files (see |gzip-example|). The usual 32place 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 side 36effects. 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 to 39 edit it, make sure that the autocommands for compressing when writing work 40 correctly. 41- Be prepared for an error halfway through (e.g., disk full). Vim will mostly 42 be able to undo the changes to the buffer, but you may have to clean up the 43 changes to other files by hand (e.g., compress a file that has been 44 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* events 48 when possible. 49 50============================================================================== 512. Defining autocommands *autocmd-define* 52 53 *:au* *:autocmd* 54:au[tocmd] [group] {event} {pat} [++once] [++nested] {cmd} 55 Add {cmd} to the list of commands that Vim will 56 execute automatically on {event} for a file matching 57 {pat} |autocmd-patterns|. 58 Here {event} cannot be "*". *E1155* 59 Note: A quote character is seen as argument to the 60 :autocmd and won't start a comment. 61 Vim always adds the {cmd} after existing autocommands, 62 so that the autocommands execute in the order in which 63 they were given. 64 See |autocmd-nested| for [++nested]. "nested" 65 (without the ++) can also be used, for backwards 66 compatibility. 67 *autocmd-once* 68 If [++once] is supplied the command is executed once, 69 then removed ("one shot"). 70 71The special pattern <buffer> or <buffer=N> defines a buffer-local autocommand. 72See |autocmd-buflocal|. 73 74If the `:autocmd` is in Vim9 script (a script that starts with `:vim9script` 75and in a `:def` function) then {cmd} will be executed as in Vim9 76script. Thus this depends on where the autocmd is defined, not where it is 77triggered. 78 79{cmd} can be a block, like with `:command`, see |:command-repl|. Example: > 80 au BufReadPost *.xml { 81 setlocal matchpairs+=<:> 82 /<start 83 } 84 85Note: The ":autocmd" command can only be followed by another command when the 86'|' appears before {cmd}. This works: > 87 :augroup mine | au! BufRead | augroup END 88But this sees "augroup" as part of the defined command: > 89 :augroup mine | au! BufRead * | augroup END 90 :augroup mine | au BufRead * set tw=70 | augroup END 91Instead you can put the group name into the command: > 92 :au! mine BufRead * 93 :au mine BufRead * set tw=70 94Or use `:execute`: > 95 :augroup mine | exe "au! BufRead *" | augroup END 96 :augroup mine | exe "au BufRead * set tw=70" | augroup END 97 98Note that special characters (e.g., "%", "<cword>") in the ":autocmd" 99arguments are not expanded when the autocommand is defined. These will be 100expanded when the Event is recognized, and the {cmd} is executed. The only 101exception is that "<sfile>" is expanded when the autocmd is defined. Example: 102> 103 :au BufNewFile,BufRead *.html so <sfile>:h/html.vim 104 105Here Vim expands <sfile> to the name of the file containing this line. 106 107`:autocmd` adds to the list of autocommands regardless of whether they are 108already present. When your .vimrc file is sourced twice, the autocommands 109will appear twice. To avoid this, define your autocommands in a group, so 110that you can easily clear them: > 111 112 augroup vimrc 113 " Remove all vimrc autocommands 114 autocmd! 115 au BufNewFile,BufRead *.html so <sfile>:h/html.vim 116 augroup END 117 118If you don't want to remove all autocommands, you can instead use a variable 119to ensure that Vim includes the autocommands only once: > 120 121 :if !exists("autocommands_loaded") 122 : let autocommands_loaded = 1 123 : au ... 124 :endif 125 126When the [group] argument is not given, Vim uses the current group (as defined 127with ":augroup"); otherwise, Vim uses the group defined with [group]. Note 128that [group] must have been defined before. You cannot define a new group 129with ":au group ..."; use ":augroup" for that. 130 131While testing autocommands, you might find the 'verbose' option to be useful: > 132 :set verbose=9 133This setting makes Vim echo the autocommands as it executes them. 134 135When defining an autocommand in a script, it will be able to call functions 136local to the script and use mappings local to the script. When the event is 137triggered and the command executed, it will run in the context of the script 138it was defined in. This matters if |<SID>| is used in a command. 139 140When executing the commands, the message from one command overwrites a 141previous message. This is different from when executing the commands 142manually. Mostly the screen will not scroll up, thus there is no hit-enter 143prompt. When one command outputs two messages this can happen anyway. 144 145============================================================================== 1463. Removing autocommands *autocmd-remove* 147 148:au[tocmd]! [group] {event} {pat} [++once] [++nested] {cmd} 149 Remove all autocommands associated with {event} and 150 {pat}, and add the command {cmd}. 151 See |autocmd-once| for [++once]. 152 See |autocmd-nested| for [++nested]. 153 154:au[tocmd]! [group] {event} {pat} 155 Remove all autocommands associated with {event} and 156 {pat}. 157 158:au[tocmd]! [group] * {pat} 159 Remove all autocommands associated with {pat} for all 160 events. 161 162:au[tocmd]! [group] {event} 163 Remove ALL autocommands for {event}. 164 Warning: You should not do this without a group for 165 |BufRead| and other common events, it can break 166 plugins, syntax highlighting, etc. 167 168:au[tocmd]! [group] Remove ALL autocommands. 169 Note: a quote will be seen as argument to the :autocmd 170 and won't start a comment. 171 Warning: You should normally not do this without a 172 group, it breaks plugins, syntax highlighting, etc. 173 174When the [group] argument is not given, Vim uses the current group (as defined 175with ":augroup"); otherwise, Vim uses the group defined with [group]. 176 177============================================================================== 1784. Listing autocommands *autocmd-list* 179 180:au[tocmd] [group] {event} {pat} 181 Show the autocommands associated with {event} and 182 {pat}. 183 184:au[tocmd] [group] * {pat} 185 Show the autocommands associated with {pat} for all 186 events. 187 188:au[tocmd] [group] {event} 189 Show all autocommands for {event}. 190 191:au[tocmd] [group] Show all autocommands. 192 193If you provide the [group] argument, Vim lists only the autocommands for 194[group]; otherwise, Vim lists the autocommands for ALL groups. Note that this 195argument behavior differs from that for defining and removing autocommands. 196 197In order to list buffer-local autocommands, use a pattern in the form <buffer> 198or <buffer=N>. See |autocmd-buflocal|. 199 200 *:autocmd-verbose* 201When 'verbose' is non-zero, listing an autocommand will also display where it 202was last defined. Example: > 203 204 :verbose autocmd BufEnter 205 FileExplorer BufEnter 206 * call s:LocalBrowse(expand("<amatch>")) 207 Last set from /usr/share/vim/vim-7.0/plugin/NetrwPlugin.vim 208< 209See |:verbose-cmd| for more information. 210 211============================================================================== 2125. Events *autocmd-events* *E215* *E216* 213 214You can specify a comma-separated list of event names. No white space can be 215used in this list. The command applies to all the events in the list. 216 217For READING FILES there are four kinds of events possible: 218 BufNewFile starting to edit a non-existent file 219 BufReadPre BufReadPost starting to edit an existing file 220 FilterReadPre FilterReadPost read the temp file with filter output 221 FileReadPre FileReadPost any other file read 222Vim uses only one of these four kinds when reading a file. The "Pre" and 223"Post" events are both triggered, before and after reading the file. 224 225Note that the autocommands for the *ReadPre events and all the Filter events 226are not allowed to change the current buffer (you will get an error message if 227this happens). This is to prevent the file to be read into the wrong buffer. 228 229Note that the 'modified' flag is reset AFTER executing the BufReadPost 230and BufNewFile autocommands. But when the 'modified' option was set by the 231autocommands, this doesn't happen. 232 233You can use the 'eventignore' option to ignore a number of events or all 234events. 235 *autocommand-events* *{event}* 236Vim recognizes the following events. Vim ignores the case of event names 237(e.g., you can use "BUFread" or "bufread" instead of "BufRead"). 238 239First an overview by function with a short explanation. Then the list 240alphabetically with full explanations |autocmd-events-abc|. 241 242Name triggered by ~ 243 244 Reading 245|BufNewFile| starting to edit a file that doesn't exist 246|BufReadPre| starting to edit a new buffer, before reading the file 247|BufRead| starting to edit a new buffer, after reading the file 248|BufReadPost| starting to edit a new buffer, after reading the file 249|BufReadCmd| before starting to edit a new buffer |Cmd-event| 250 251|FileReadPre| before reading a file with a ":read" command 252|FileReadPost| after reading a file with a ":read" command 253|FileReadCmd| before reading a file with a ":read" command |Cmd-event| 254 255|FilterReadPre| before reading a file from a filter command 256|FilterReadPost| after reading a file from a filter command 257 258|StdinReadPre| before reading from stdin into the buffer 259|StdinReadPost| After reading from the stdin into the buffer 260 261 Writing 262|BufWrite| starting to write the whole buffer to a file 263|BufWritePre| starting to write the whole buffer to a file 264|BufWritePost| after writing the whole buffer to a file 265|BufWriteCmd| before writing the whole buffer to a file |Cmd-event| 266 267|FileWritePre| starting to write part of a buffer to a file 268|FileWritePost| after writing part of a buffer to a file 269|FileWriteCmd| before writing part of a buffer to a file |Cmd-event| 270 271|FileAppendPre| starting to append to a file 272|FileAppendPost| after appending to a file 273|FileAppendCmd| before appending to a file |Cmd-event| 274 275|FilterWritePre| starting to write a file for a filter command or diff 276|FilterWritePost| after writing a file for a filter command or diff 277 278 Buffers 279|BufAdd| just after adding a buffer to the buffer list 280|BufCreate| just after adding a buffer to the buffer list 281|BufDelete| before deleting a buffer from the buffer list 282|BufWipeout| before completely deleting a buffer 283 284|BufFilePre| before changing the name of the current buffer 285|BufFilePost| after changing the name of the current buffer 286 287|BufEnter| after entering a buffer 288|BufLeave| before leaving to another buffer 289|BufWinEnter| after a buffer is displayed in a window 290|BufWinLeave| before a buffer is removed from a window 291 292|BufUnload| before unloading a buffer 293|BufHidden| just before a buffer becomes hidden 294|BufNew| just after creating a new buffer 295 296|SwapExists| detected an existing swap file 297 298 Options 299|FileType| when the 'filetype' option has been set 300|Syntax| when the 'syntax' option has been set 301|EncodingChanged| after the 'encoding' option has been changed 302|TermChanged| after the value of 'term' has changed 303|OptionSet| after setting any option 304 305 Startup and exit 306|VimEnter| after doing all the startup stuff 307|GUIEnter| after starting the GUI successfully 308|GUIFailed| after starting the GUI failed 309|TermResponse| after the terminal response to |t_RV| is received 310 311|QuitPre| when using `:quit`, before deciding whether to exit 312|ExitPre| when using a command that may make Vim exit 313|VimLeavePre| before exiting Vim, before writing the viminfo file 314|VimLeave| before exiting Vim, after writing the viminfo file 315 316|VimSuspend| when suspending Vim 317|VimResume| when Vim is resumed after being suspended 318 319 Terminal 320|TerminalOpen| after a terminal buffer was created 321|TerminalWinOpen| after a terminal buffer was created in a new window 322 323 Various 324|FileChangedShell| Vim notices that a file changed since editing started 325|FileChangedShellPost| After handling a file changed since editing started 326|FileChangedRO| before making the first change to a read-only file 327 328|DiffUpdated| after diffs have been updated 329|DirChanged| after the working directory has changed 330 331|ShellCmdPost| after executing a shell command 332|ShellFilterPost| after filtering with a shell command 333 334|CmdUndefined| a user command is used but it isn't defined 335|FuncUndefined| a user function is used but it isn't defined 336|SpellFileMissing| a spell file is used but it can't be found 337|SourcePre| before sourcing a Vim script 338|SourcePost| after sourcing a Vim script 339|SourceCmd| before sourcing a Vim script |Cmd-event| 340 341|VimResized| after the Vim window size changed 342|FocusGained| Vim got input focus 343|FocusLost| Vim lost input focus 344|CursorHold| the user doesn't press a key for a while 345|CursorHoldI| the user doesn't press a key for a while in Insert mode 346|CursorMoved| the cursor was moved in Normal mode 347|CursorMovedI| the cursor was moved in Insert mode 348 349|WinNew| after creating a new window 350|TabNew| after creating a new tab page 351|WinClosed| after closing a window 352|TabClosed| after closing a tab page 353|WinEnter| after entering another window 354|WinLeave| before leaving a window 355|TabEnter| after entering another tab page 356|TabLeave| before leaving a tab page 357|CmdwinEnter| after entering the command-line window 358|CmdwinLeave| before leaving the command-line window 359 360|CmdlineChanged| after a change was made to the command-line text 361|CmdlineEnter| after the cursor moves to the command line 362|CmdlineLeave| before the cursor leaves the command line 363 364|InsertEnter| starting Insert mode 365|InsertChange| when typing <Insert> while in Insert or Replace mode 366|InsertLeave| when leaving Insert mode 367|InsertCharPre| when a character was typed in Insert mode, before 368 inserting it 369 370|ModeChanged| after changing the mode 371 372|TextChanged| after a change was made to the text in Normal mode 373|TextChangedI| after a change was made to the text in Insert mode 374 when popup menu is not visible 375|TextChangedP| after a change was made to the text in Insert mode 376 when popup menu visible 377|TextYankPost| after text has been yanked or deleted 378 379|SafeState| nothing pending, going to wait for the user to type a 380 character 381|SafeStateAgain| repeated SafeState 382 383|ColorSchemePre| before loading a color scheme 384|ColorScheme| after loading a color scheme 385 386|RemoteReply| a reply from a server Vim was received 387 388|QuickFixCmdPre| before a quickfix command is run 389|QuickFixCmdPost| after a quickfix command is run 390 391|SessionLoadPost| after loading a session file 392 393|MenuPopup| just before showing the popup menu 394|CompleteChanged| after Insert mode completion menu changed 395|CompleteDonePre| after Insert mode completion is done, before clearing 396 info 397|CompleteDone| after Insert mode completion is done, after clearing 398 info 399 400|User| to be used in combination with ":doautocmd" 401|SigUSR1| after the SIGUSR1 signal has been detected 402 403 404The alphabetical list of autocommand events: *autocmd-events-abc* 405 406 *BufCreate* *BufAdd* 407BufAdd or BufCreate Just after creating a new buffer which is 408 added to the buffer list, or adding a buffer 409 to the buffer list. 410 Also used just after a buffer in the buffer 411 list has been renamed. 412 Not triggered for the initial buffers created 413 during startup. 414 The BufCreate event is for historic reasons. 415 NOTE: When this autocommand is executed, the 416 current buffer "%" may be different from the 417 buffer being created "<afile>". 418 *BufDelete* 419BufDelete Before deleting a buffer from the buffer list. 420 The BufUnload may be called first (if the 421 buffer was loaded). 422 Also used just before a buffer in the buffer 423 list is renamed. 424 NOTE: When this autocommand is executed, the 425 current buffer "%" may be different from the 426 buffer being deleted "<afile>" and "<abuf>". 427 Don't change to another buffer, it will cause 428 problems. 429 *BufEnter* 430BufEnter After entering a buffer. Useful for setting 431 options for a file type. Also executed when 432 starting to edit a buffer, after the 433 BufReadPost autocommands. 434 *BufFilePost* 435BufFilePost After changing the name of the current buffer 436 with the ":file" or ":saveas" command. 437 *BufFilePre* 438BufFilePre Before changing the name of the current buffer 439 with the ":file" or ":saveas" command. 440 *BufHidden* 441BufHidden Just before a buffer becomes hidden. That is, 442 when there are no longer windows that show 443 the buffer, but the buffer is not unloaded or 444 deleted. Not used for ":qa" or ":q" when 445 exiting Vim. 446 NOTE: When this autocommand is executed, the 447 current buffer "%" may be different from the 448 buffer being unloaded "<afile>". 449 *BufLeave* 450BufLeave Before leaving to another buffer. Also when 451 leaving or closing the current window and the 452 new current window is not for the same buffer. 453 Not used for ":qa" or ":q" when exiting Vim. 454 *BufNew* 455BufNew Just after creating a new buffer. Also used 456 just after a buffer has been renamed. When 457 the buffer is added to the buffer list BufAdd 458 will be triggered too. 459 NOTE: When this autocommand is executed, the 460 current buffer "%" may be different from the 461 buffer being created "<afile>". 462 *BufNewFile* 463BufNewFile When starting to edit a file that doesn't 464 exist. Can be used to read in a skeleton 465 file. 466 *BufRead* *BufReadPost* 467BufRead or BufReadPost When starting to edit a new buffer, after 468 reading the file into the buffer, before 469 executing the modelines. See |BufWinEnter| 470 for when you need to do something after 471 processing the modelines. 472 This does NOT work for ":r file". Not used 473 when the file doesn't exist. Also used after 474 successfully recovering a file. 475 Also triggered for the filetypedetect group 476 when executing ":filetype detect" and when 477 writing an unnamed buffer in a way that the 478 buffer gets a name. 479 *BufReadCmd* 480BufReadCmd Before starting to edit a new buffer. Should 481 read the file into the buffer. |Cmd-event| 482 *BufReadPre* *E200* *E201* 483BufReadPre When starting to edit a new buffer, before 484 reading the file into the buffer. Not used 485 if the file doesn't exist. 486 *BufUnload* 487BufUnload Before unloading a buffer. This is when the 488 text in the buffer is going to be freed. This 489 may be after a BufWritePost and before a 490 BufDelete. Also used for all buffers that are 491 loaded when Vim is going to exit. 492 NOTE: When this autocommand is executed, the 493 current buffer "%" may be different from the 494 buffer being unloaded "<afile>". 495 Don't change to another buffer or window, it 496 will cause problems! 497 When exiting and v:dying is 2 or more this 498 event is not triggered. 499 *BufWinEnter* 500BufWinEnter After a buffer is displayed in a window. This 501 can be when the buffer is loaded (after 502 processing the modelines) or when a hidden 503 buffer is displayed in a window (and is no 504 longer hidden). 505 Does not happen for |:split| without 506 arguments, since you keep editing the same 507 buffer, or ":split" with a file that's already 508 open in a window, because it re-uses an 509 existing buffer. But it does happen for a 510 ":split" with the name of the current buffer, 511 since it reloads that buffer. 512 Does not happen for a terminal window, because 513 it starts in Terminal-Job mode and Normal mode 514 commands won't work. Use |TerminalOpen| instead. 515 *BufWinLeave* 516BufWinLeave Before a buffer is removed from a window. 517 Not when it's still visible in another window. 518 Also triggered when exiting. It's triggered 519 before BufUnload or BufHidden. 520 NOTE: When this autocommand is executed, the 521 current buffer "%" may be different from the 522 buffer being unloaded "<afile>". 523 When exiting and v:dying is 2 or more this 524 event is not triggered. 525 *BufWipeout* 526BufWipeout Before completely deleting a buffer. The 527 BufUnload and BufDelete events may be called 528 first (if the buffer was loaded and was in the 529 buffer list). Also used just before a buffer 530 is renamed (also when it's not in the buffer 531 list). 532 NOTE: When this autocommand is executed, the 533 current buffer "%" may be different from the 534 buffer being deleted "<afile>". 535 Don't change to another buffer, it will cause 536 problems. 537 *BufWrite* *BufWritePre* 538BufWrite or BufWritePre Before writing the whole buffer to a file. 539 *BufWriteCmd* 540BufWriteCmd Before writing the whole buffer to a file. 541 Should do the writing of the file and reset 542 'modified' if successful, unless '+' is in 543 'cpo' and writing to another file |cpo-+|. 544 The buffer contents should not be changed. 545 When the command resets 'modified' the undo 546 information is adjusted to mark older undo 547 states as 'modified', like |:write| does. 548 |Cmd-event| 549 *BufWritePost* 550BufWritePost After writing the whole buffer to a file 551 (should undo the commands for BufWritePre). 552 *CmdUndefined* 553CmdUndefined When a user command is used but it isn't 554 defined. Useful for defining a command only 555 when it's used. The pattern is matched 556 against the command name. Both <amatch> and 557 <afile> are set to the name of the command. 558 NOTE: Autocompletion won't work until the 559 command is defined. An alternative is to 560 always define the user command and have it 561 invoke an autoloaded function. See |autoload|. 562 *CmdlineChanged* 563CmdlineChanged After a change was made to the text in the 564 command line. Be careful not to mess up 565 the command line, it may cause Vim to lock up. 566 <afile> is set to a single character, 567 indicating the type of command-line. 568 |cmdwin-char| 569 *CmdlineEnter* 570CmdlineEnter After moving the cursor to the command line, 571 where the user can type a command or search 572 string; including non-interactive use of ":" 573 in a mapping, but not when using |<Cmd>|. 574 <afile> is set to a single character, 575 indicating the type of command-line. 576 |cmdwin-char| 577 *CmdlineLeave* 578CmdlineLeave Before leaving the command line; including 579 non-interactive use of ":" in a mapping, but 580 not when using |<Cmd>|. 581 Also when abandoning the command line, after 582 typing CTRL-C or <Esc>. 583 When the commands result in an error the 584 command line is still executed. 585 <afile> is set to a single character, 586 indicating the type of command-line. 587 |cmdwin-char| 588 *CmdwinEnter* 589CmdwinEnter After entering the command-line window. 590 Useful for setting options specifically for 591 this special type of window. 592 <afile> is set to a single character, 593 indicating the type of command-line. 594 |cmdwin-char| 595 *CmdwinLeave* 596CmdwinLeave Before leaving the command-line window. 597 Useful to clean up any global setting done 598 with CmdwinEnter. 599 <afile> is set to a single character, 600 indicating the type of command-line. 601 |cmdwin-char| 602 *ColorScheme* 603ColorScheme After loading a color scheme. |:colorscheme| 604 The pattern is matched against the 605 colorscheme name. <afile> can be used for the 606 name of the actual file where this option was 607 set, and <amatch> for the new colorscheme 608 name. 609 610 *ColorSchemePre* 611ColorSchemePre Before loading a color scheme. |:colorscheme| 612 Useful to setup removing things added by a 613 color scheme, before another one is loaded. 614CompleteChanged *CompleteChanged* 615 After each time the Insert mode completion 616 menu changed. Not fired on popup menu hide, 617 use |CompleteDonePre| or |CompleteDone| for 618 that. Never triggered recursively. 619 620 Sets these |v:event| keys: 621 completed_item See |complete-items|. 622 height nr of items visible 623 width screen cells 624 row top screen row 625 col leftmost screen column 626 size total nr of items 627 scrollbar TRUE if visible 628 629 It is not allowed to change the text |textlock|. 630 631 The size and position of the popup are also 632 available by calling |pum_getpos()|. 633 634 *CompleteDonePre* 635CompleteDonePre After Insert mode completion is done. Either 636 when something was completed or abandoning 637 completion. |ins-completion| 638 |complete_info()| can be used, the info is 639 cleared after triggering CompleteDonePre. 640 The |v:completed_item| variable contains 641 information about the completed item. 642 643 *CompleteDone* 644CompleteDone After Insert mode completion is done. Either 645 when something was completed or abandoning 646 completion. |ins-completion| 647 |complete_info()| cannot be used, the info is 648 cleared before triggering CompleteDone. Use 649 CompleteDonePre if you need it. 650 The |v:completed_item| variable contains 651 information about the completed item. 652 653 *CursorHold* 654CursorHold When the user doesn't press a key for the time 655 specified with 'updatetime'. Not triggered 656 until the user has pressed a key (i.e. doesn't 657 fire every 'updatetime' ms if you leave Vim to 658 make some coffee. :) See |CursorHold-example| 659 for previewing tags. 660 This event is only triggered in Normal mode. 661 It is not triggered when waiting for a command 662 argument to be typed, or a movement after an 663 operator. 664 While recording the CursorHold event is not 665 triggered. |q| 666 *<CursorHold>* 667 Internally the autocommand is triggered by the 668 <CursorHold> key. In an expression mapping 669 |getchar()| may see this character. 670 671 Note: Interactive commands cannot be used for 672 this event. There is no hit-enter prompt, 673 the screen is updated directly (when needed). 674 Note: In the future there will probably be 675 another option to set the time. 676 Hint: to force an update of the status lines 677 use: > 678 :let &ro = &ro 679< {only on Amiga, Unix, Win32 and all GUI 680 versions} 681 *CursorHoldI* 682CursorHoldI Just like CursorHold, but in Insert mode. 683 Not triggered when waiting for another key, 684 e.g. after CTRL-V, and not when in CTRL-X mode 685 |insert_expand|. 686 687 *CursorMoved* 688CursorMoved After the cursor was moved in Normal or Visual 689 mode. Also when the text of the cursor line 690 has been changed, e.g., with "x", "rx" or "p". 691 Not triggered when there is typeahead, while 692 executing commands in a script file, when 693 an operator is pending or when moving to 694 another window while remaining at the same 695 cursor position. 696 For an example see |match-parens|. 697 Note: This can not be skipped with 698 `:noautocmd`. 699 Careful: This is triggered very often, don't 700 do anything that the user does not expect or 701 that is slow. 702 *CursorMovedI* 703CursorMovedI After the cursor was moved in Insert mode. 704 Not triggered when the popup menu is visible. 705 Otherwise the same as CursorMoved. 706 *EncodingChanged* 707EncodingChanged Fires off after the 'encoding' option has been 708 changed. Useful to set up fonts, for example. 709 *FileAppendCmd* 710FileAppendCmd Before appending to a file. Should do the 711 appending to the file. Use the '[ and '] 712 marks for the range of lines. |Cmd-event| 713 *FileAppendPost* 714FileAppendPost After appending to a file. 715 *FileAppendPre* 716FileAppendPre Before appending to a file. Use the '[ and '] 717 marks for the range of lines. 718 *FileChangedRO* 719FileChangedRO Before making the first change to a read-only 720 file. Can be used to check-out the file from 721 a source control system. Not triggered when 722 the change was caused by an autocommand. 723 This event is triggered when making the first 724 change in a buffer or the first change after 725 'readonly' was set, just before the change is 726 applied to the text. 727 WARNING: If the autocommand moves the cursor 728 the effect of the change is undefined. 729 *E788* 730 It is not allowed to change to another buffer 731 here. You can reload the buffer but not edit 732 another one. 733 *E881* 734 If the number of lines changes saving for undo 735 may fail and the change will be aborted. 736 *DiffUpdated* 737DiffUpdated After diffs have been updated. Depending on 738 what kind of diff is being used (internal or 739 external) this can be triggered on every 740 change or when doing |:diffupdate|. 741 *DirChanged* 742DirChanged The working directory has changed in response 743 to the |:cd| or |:tcd| or |:lcd| commands, or 744 as a result of the 'autochdir' option. 745 The pattern can be: 746 "window" to trigger on `:lcd` 747 "tabpage" to trigger on `:tcd` 748 "global" to trigger on `:cd` 749 "auto" to trigger on 'autochdir'. 750 "drop" to trigger on editing a file 751 <afile> is set to the new directory name. 752 *ExitPre* 753ExitPre When using `:quit`, `:wq` in a way it makes 754 Vim exit, or using `:qall`, just after 755 |QuitPre|. Can be used to close any 756 non-essential window. Exiting may still be 757 cancelled if there is a modified buffer that 758 isn't automatically saved, use |VimLeavePre| 759 for really exiting. 760 *FileChangedShell* 761FileChangedShell When Vim notices that the modification time of 762 a file has changed since editing started. 763 Also when the file attributes of the file 764 change or when the size of the file changes. 765 |timestamp| 766 Mostly triggered after executing a shell 767 command, but also with a |:checktime| command 768 or when gvim regains input focus. 769 This autocommand is triggered for each changed 770 file. It is not used when 'autoread' is set 771 and the buffer was not changed. If a 772 FileChangedShell autocommand is present the 773 warning message and prompt is not given. 774 The |v:fcs_reason| variable is set to indicate 775 what happened and |v:fcs_choice| can be used 776 to tell Vim what to do next. 777 NOTE: When this autocommand is executed, the 778 current buffer "%" may be different from the 779 buffer that was changed, which is in "<afile>". 780 NOTE: The commands must not change the current 781 buffer, jump to another buffer or delete a 782 buffer. *E246* *E811* 783 NOTE: This event never nests, to avoid an 784 endless loop. This means that while executing 785 commands for the FileChangedShell event no 786 other FileChangedShell event will be 787 triggered. 788 *FileChangedShellPost* 789FileChangedShellPost After handling a file that was changed outside 790 of Vim. Can be used to update the statusline. 791 *FileEncoding* 792FileEncoding Obsolete. It still works and is equivalent 793 to |EncodingChanged|. 794 *FileReadCmd* 795FileReadCmd Before reading a file with a ":read" command. 796 Should do the reading of the file. |Cmd-event| 797 *FileReadPost* 798FileReadPost After reading a file with a ":read" command. 799 Note that Vim sets the '[ and '] marks to the 800 first and last line of the read. This can be 801 used to operate on the lines just read. 802 *FileReadPre* 803FileReadPre Before reading a file with a ":read" command. 804 *FileType* 805FileType When the 'filetype' option has been set. The 806 pattern is matched against the filetype. 807 <afile> can be used for the name of the file 808 where this option was set, and <amatch> for 809 the new value of 'filetype'. Navigating to 810 another window or buffer is not allowed. 811 See |filetypes|. 812 *FileWriteCmd* 813FileWriteCmd Before writing to a file, when not writing the 814 whole buffer. Should do the writing to the 815 file. Should not change the buffer. Use the 816 '[ and '] marks for the range of lines. 817 |Cmd-event| 818 *FileWritePost* 819FileWritePost After writing to a file, when not writing the 820 whole buffer. 821 *FileWritePre* 822FileWritePre Before writing to a file, when not writing the 823 whole buffer. Use the '[ and '] marks for the 824 range of lines. 825 *FilterReadPost* 826FilterReadPost After reading a file from a filter command. 827 Vim checks the pattern against the name of 828 the current buffer as with FilterReadPre. 829 Not triggered when 'shelltemp' is off. 830 *FilterReadPre* *E135* 831FilterReadPre Before reading a file from a filter command. 832 Vim checks the pattern against the name of 833 the current buffer, not the name of the 834 temporary file that is the output of the 835 filter command. 836 Not triggered when 'shelltemp' is off. 837 *FilterWritePost* 838FilterWritePost After writing a file for a filter command or 839 making a diff with an external diff (see 840 |DiffUpdated| for internal diff). 841 Vim checks the pattern against the name of 842 the current buffer as with FilterWritePre. 843 Not triggered when 'shelltemp' is off. 844 *FilterWritePre* 845FilterWritePre Before writing a file for a filter command or 846 making a diff with an external diff. 847 Vim checks the pattern against the name of 848 the current buffer, not the name of the 849 temporary file that is the output of the 850 filter command. 851 Not triggered when 'shelltemp' is off. 852 *FocusGained* 853FocusGained When Vim got input focus. Only for the GUI 854 version and a few console versions where this 855 can be detected. 856 *FocusLost* 857FocusLost When Vim lost input focus. Only for the GUI 858 version and a few console versions where this 859 can be detected. May also happen when a 860 dialog pops up. 861 *FuncUndefined* 862FuncUndefined When a user function is used but it isn't 863 defined. Useful for defining a function only 864 when it's used. The pattern is matched 865 against the function name. Both <amatch> and 866 <afile> are set to the name of the function. 867 Not triggered when compiling a |Vim9| 868 function. 869 NOTE: When writing Vim scripts a better 870 alternative is to use an autoloaded function. 871 See |autoload-functions|. 872 *GUIEnter* 873GUIEnter After starting the GUI successfully, and after 874 opening the window. It is triggered before 875 VimEnter when using gvim. Can be used to 876 position the window from a .gvimrc file: > 877 :autocmd GUIEnter * winpos 100 50 878< *GUIFailed* 879GUIFailed After starting the GUI failed. Vim may 880 continue to run in the terminal, if possible 881 (only on Unix and alikes, when connecting the 882 X server fails). You may want to quit Vim: > 883 :autocmd GUIFailed * qall 884< *InsertChange* 885InsertChange When typing <Insert> while in Insert or 886 Replace mode. The |v:insertmode| variable 887 indicates the new mode. 888 Be careful not to move the cursor or do 889 anything else that the user does not expect. 890 *InsertCharPre* 891InsertCharPre When a character is typed in Insert mode, 892 before inserting the char. 893 The |v:char| variable indicates the char typed 894 and can be changed during the event to insert 895 a different character. When |v:char| is set 896 to more than one character this text is 897 inserted literally. 898 It is not allowed to change the text |textlock|. 899 The event is not triggered when 'paste' is 900 set. {only with the +eval feature} 901 *InsertEnter* 902InsertEnter Just before starting Insert mode. Also for 903 Replace mode and Virtual Replace mode. The 904 |v:insertmode| variable indicates the mode. 905 Be careful not to do anything else that the 906 user does not expect. 907 The cursor is restored afterwards. If you do 908 not want that set |v:char| to a non-empty 909 string. 910 *InsertLeavePre* 911InsertLeavePre Just before leaving Insert mode. Also when 912 using CTRL-O |i_CTRL-O|. Be careful not to 913 change mode or use `:normal`, it will likely 914 cause trouble. 915 *InsertLeave* 916InsertLeave Just after leaving Insert mode. Also when 917 using CTRL-O |i_CTRL-O|. But not for |i_CTRL-C|. 918 *MenuPopup* 919MenuPopup Just before showing the popup menu (under the 920 right mouse button). Useful for adjusting the 921 menu for what is under the cursor or mouse 922 pointer. 923 The pattern is matched against one or two 924 characters representing the mode: 925 n Normal 926 v Visual 927 o Operator-pending 928 i Insert 929 c Command line 930 tl Terminal 931 *ModeChanged* 932ModeChanged After changing the mode. The pattern is 933 matched against `'old_mode:new_mode'`, for 934 example match against `*:c*` to simulate 935 |CmdlineEnter|. 936 The following values of |v:event| are set: 937 old_mode The mode before it changed. 938 new_mode The new mode as also returned 939 by |mode()| called with a 940 non-zero argument. 941 When ModeChanged is triggered, old_mode will 942 have the value of new_mode when the event was 943 last triggered. 944 This will be triggered on every minor mode 945 change. 946 Usage example to use relative line numbers 947 when entering Visual mode: > 948 :au ModeChanged [vV\x16]*:* let &l:rnu = mode() =~# '^[vV\x16]' 949 :au ModeChanged *:[vV\x16]* let &l:rnu = mode() =~# '^[vV\x16]' 950 :au WinEnter,WinLeave * let &l:rnu = mode() =~# '^[vV\x16]' 951< *OptionSet* 952OptionSet After setting an option. The pattern is 953 matched against the long option name. 954 |<amatch>| indicates what option has been set. 955 956 |v:option_type| indicates whether it's global 957 or local scoped. 958 |v:option_command| indicates what type of 959 set/let command was used (follow the tag to 960 see the table). 961 |v:option_new| indicates the newly set value. 962 |v:option_oldlocal| has the old local value. 963 |v:option_oldglobal| has the old global value. 964 |v:option_old| indicates the old option value. 965 966 |v:option_oldlocal| is only set when |:set| 967 or |:setlocal| or a |modeline| was used to set 968 the option. Similarly |v:option_oldglobal| is 969 only set when |:set| or |:setglobal| was used. 970 971 Note that when setting a |global-local| string 972 option with |:set|, then |v:option_old| is the 973 old global value. However, for all other kinds 974 of options (local string options, global-local 975 number options, ...) it is the old local 976 value. 977 978 OptionSet is not triggered on startup and for 979 the 'key' option for obvious reasons. 980 981 Usage example: Check for the existence of the 982 directory in the 'backupdir' and 'undodir' 983 options, create the directory if it doesn't 984 exist yet. 985 986 Note: It's a bad idea to reset an option 987 during this autocommand, this may break a 988 plugin. You can always use `:noa` to prevent 989 triggering this autocommand. 990 991 When using |:set| in the autocommand the event 992 is not triggered again. 993 *QuickFixCmdPre* 994QuickFixCmdPre Before a quickfix command is run (|:make|, 995 |:lmake|, |:grep|, |:lgrep|, |:grepadd|, 996 |:lgrepadd|, |:vimgrep|, |:lvimgrep|, 997 |:vimgrepadd|, |:lvimgrepadd|, |:cscope|, 998 |:cfile|, |:cgetfile|, |:caddfile|, |:lfile|, 999 |:lgetfile|, |:laddfile|, |:helpgrep|, 1000 |:lhelpgrep|, |:cexpr|, |:cgetexpr|, 1001 |:caddexpr|, |:cbuffer|, |:cgetbuffer|, 1002 |:caddbuffer|). 1003 The pattern is matched against the command 1004 being run. When |:grep| is used but 'grepprg' 1005 is set to "internal" it still matches "grep". 1006 This command cannot be used to set the 1007 'makeprg' and 'grepprg' variables. 1008 If this command causes an error, the quickfix 1009 command is not executed. 1010 *QuickFixCmdPost* 1011QuickFixCmdPost Like QuickFixCmdPre, but after a quickfix 1012 command is run, before jumping to the first 1013 location. For |:cfile| and |:lfile| commands 1014 it is run after error file is read and before 1015 moving to the first error. 1016 See |QuickFixCmdPost-example|. 1017 *QuitPre* 1018QuitPre When using `:quit`, `:wq` or `:qall`, before 1019 deciding whether it closes the current window 1020 or quits Vim. For `:wq` the buffer is written 1021 before QuitPre is triggered. Can be used to 1022 close any non-essential window if the current 1023 window is the last ordinary window. 1024 Also see |ExitPre|. 1025 *RemoteReply* 1026RemoteReply When a reply from a Vim that functions as 1027 server was received |server2client()|. The 1028 pattern is matched against the {serverid}. 1029 <amatch> is equal to the {serverid} from which 1030 the reply was sent, and <afile> is the actual 1031 reply string. 1032 Note that even if an autocommand is defined, 1033 the reply should be read with |remote_read()| 1034 to consume it. 1035 *SafeState* 1036SafeState When nothing is pending, going to wait for the 1037 user to type a character. 1038 This will not be triggered when: 1039 - an operator is pending 1040 - a register was entered with "r 1041 - halfway executing a command 1042 - executing a mapping 1043 - there is typeahead 1044 - Insert mode completion is active 1045 - Command line completion is active 1046 You can use `mode()` to find out what state 1047 Vim is in. That may be: 1048 - VIsual mode 1049 - Normal mode 1050 - Insert mode 1051 - Command-line mode 1052 Depending on what you want to do, you may also 1053 check more with `state()`, e.g. whether the 1054 screen was scrolled for messages. 1055 *SafeStateAgain* 1056SafeStateAgain Like SafeState but after processing any 1057 messages and invoking callbacks. This may be 1058 triggered often, don't do something that takes 1059 time. 1060 1061 *SessionLoadPost* 1062SessionLoadPost After loading the session file created using 1063 the |:mksession| command. 1064 *ShellCmdPost* 1065ShellCmdPost After executing a shell command with |:!cmd|, 1066 |:shell|, |:make| and |:grep|. Can be used to 1067 check for any changed files. 1068 *ShellFilterPost* 1069ShellFilterPost After executing a shell command with 1070 ":{range}!cmd", ":w !cmd" or ":r !cmd". 1071 Can be used to check for any changed files. 1072 *SourcePre* 1073SourcePre Before sourcing a Vim script. |:source| 1074 <afile> is the name of the file being sourced. 1075 *SourcePost* 1076SourcePost After sourcing a Vim script. |:source| 1077 <afile> is the name of the file being sourced. 1078 Not triggered when sourcing was interrupted. 1079 Also triggered after a SourceCmd autocommand 1080 was triggered. 1081 *SourceCmd* 1082SourceCmd When sourcing a Vim script. |:source| 1083 <afile> is the name of the file being sourced. 1084 The autocommand must source this file. 1085 |Cmd-event| 1086 *SpellFileMissing* 1087SpellFileMissing When trying to load a spell checking file and 1088 it can't be found. The pattern is matched 1089 against the language. <amatch> is the 1090 language, 'encoding' also matters. See 1091 |spell-SpellFileMissing|. 1092 *StdinReadPost* 1093StdinReadPost After reading from the stdin into the buffer, 1094 before executing the modelines. Only used 1095 when the "-" argument was used when Vim was 1096 started |--|. 1097 *StdinReadPre* 1098StdinReadPre Before reading from stdin into the buffer. 1099 Only used when the "-" argument was used when 1100 Vim was started |--|. 1101 *SwapExists* 1102SwapExists Detected an existing swap file when starting 1103 to edit a file. Only when it is possible to 1104 select a way to handle the situation, when Vim 1105 would ask the user what to do. 1106 The |v:swapname| variable holds the name of 1107 the swap file found, <afile> the file being 1108 edited. |v:swapcommand| may contain a command 1109 to be executed in the opened file. 1110 The commands should set the |v:swapchoice| 1111 variable to a string with one character to 1112 tell Vim what should be done next: 1113 'o' open read-only 1114 'e' edit the file anyway 1115 'r' recover 1116 'd' delete the swap file 1117 'q' quit, don't edit the file 1118 'a' abort, like hitting CTRL-C 1119 When set to an empty string the user will be 1120 asked, as if there was no SwapExists autocmd. 1121 *E812* 1122 It is not allowed to change to another buffer, 1123 change a buffer name or change directory 1124 here. 1125 {only available with the +eval feature} 1126 *Syntax* 1127Syntax When the 'syntax' option has been set. The 1128 pattern is matched against the syntax name. 1129 <afile> can be used for the name of the file 1130 where this option was set, and <amatch> for 1131 the new value of 'syntax'. 1132 See |:syn-on|. 1133 *TabClosed* 1134TabClosed After closing a tab page. 1135 *TabEnter* 1136TabEnter Just after entering a tab page. |tab-page| 1137 After triggering the WinEnter and before 1138 triggering the BufEnter event. 1139 *TabLeave* 1140TabLeave Just before leaving a tab page. |tab-page| 1141 A WinLeave event will have been triggered 1142 first. 1143 *TabNew* 1144TabNew When a tab page was created. |tab-page| 1145 A WinEnter event will have been triggered 1146 first, TabEnter follows. 1147 *TermChanged* 1148TermChanged After the value of 'term' has changed. Useful 1149 for re-loading the syntax file to update the 1150 colors, fonts and other terminal-dependent 1151 settings. Executed for all loaded buffers. 1152 *TerminalOpen* 1153TerminalOpen Just after a terminal buffer was created, with 1154 `:terminal` or |term_start()|. This event is 1155 triggered even if the buffer is created 1156 without a window, with the ++hidden option. 1157 *TerminalWinOpen* 1158TerminalWinOpen Just after a terminal buffer was created, with 1159 `:terminal` or |term_start()|. This event is 1160 triggered only if the buffer is created 1161 with a window. Can be used to set window 1162 local options for the terminal window. 1163 *TermResponse* 1164TermResponse After the response to |t_RV| is received from 1165 the terminal. The value of |v:termresponse| 1166 can be used to do things depending on the 1167 terminal version. Note that this event may be 1168 triggered halfway executing another event, 1169 especially if file I/O, a shell command or 1170 anything else that takes time is involved. 1171 *TextChanged* 1172TextChanged After a change was made to the text in the 1173 current buffer in Normal mode. That is after 1174 |b:changedtick| has changed (also when that 1175 happened before the TextChanged autocommand 1176 was defined). 1177 Not triggered when there is typeahead or when 1178 an operator is pending. 1179 Note: This can not be skipped with 1180 `:noautocmd`. 1181 Careful: This is triggered very often, don't 1182 do anything that the user does not expect or 1183 that is slow. 1184 *TextChangedI* 1185TextChangedI After a change was made to the text in the 1186 current buffer in Insert mode. 1187 Not triggered when the popup menu is visible. 1188 Otherwise the same as TextChanged. 1189 *TextChangedP* 1190TextChangedP After a change was made to the text in the 1191 current buffer in Insert mode, only when the 1192 popup menu is visible. Otherwise the same as 1193 TextChanged. 1194 *TextYankPost* 1195TextYankPost After text has been yanked or deleted in the 1196 current buffer. The following values of 1197 |v:event| can be used to determine the operation 1198 that triggered this autocmd: 1199 operator The operation performed. 1200 regcontents Text that was stored in the 1201 register, as a list of lines, 1202 like with: > 1203 getreg(r, 1, 1) 1204< regname Name of the register or empty 1205 string for the unnamed 1206 register, see |registers|. 1207 regtype Type of the register, see 1208 |getregtype()|. 1209 visual True if the operation is 1210 performed on a |Visual| area. 1211 Not triggered when |quote_| is used nor when 1212 called recursively. 1213 It is not allowed to change the buffer text, 1214 see |textlock|. 1215 {only when compiled with the +eval feature} 1216 1217 *User* 1218User Never executed automatically. To be used for 1219 autocommands that are only executed with 1220 ":doautocmd". 1221 Note that when `:doautocmd User MyEvent` is 1222 used while there are no matching autocommands, 1223 you will get an error. If you don't want 1224 that, define a dummy autocommand yourself. 1225 1226 *SigUSR1* 1227SigUSR1 After the SIGUSR1 signal has been detected. 1228 Could be used if other ways of notifying Vim 1229 are not feasible. E.g. to check for the 1230 result of a build that takes a long time, or 1231 when a motion sensor is triggered. 1232 {only on Unix} 1233 1234 *UserGettingBored* 1235UserGettingBored When the user presses the same key 42 times. 1236 Just kidding! :-) 1237 *VimEnter* 1238VimEnter After doing all the startup stuff, including 1239 loading .vimrc files, executing the "-c cmd" 1240 arguments, creating all windows and loading 1241 the buffers in them. 1242 Just before this event is triggered the 1243 |v:vim_did_enter| variable is set, so that you 1244 can do: > 1245 if v:vim_did_enter 1246 call s:init() 1247 else 1248 au VimEnter * call s:init() 1249 endif 1250< *VimLeave* 1251VimLeave Before exiting Vim, just after writing the 1252 .viminfo file. Executed only once, like 1253 VimLeavePre. 1254 To detect an abnormal exit use |v:dying|. 1255 When v:dying is 2 or more this event is not 1256 triggered. 1257 To get the exit code use |v:exiting|. 1258 *VimLeavePre* 1259VimLeavePre Before exiting Vim, just before writing the 1260 .viminfo file. This is executed only once, 1261 if there is a match with the name of what 1262 happens to be the current buffer when exiting. 1263 Mostly useful with a "*" pattern. > 1264 :autocmd VimLeavePre * call CleanupStuff() 1265< To detect an abnormal exit use |v:dying|. 1266 When v:dying is 2 or more this event is not 1267 triggered. 1268 To get the exit code use |v:exiting|. 1269 *VimResized* 1270VimResized After the Vim window was resized, thus 'lines' 1271 and/or 'columns' changed. Not when starting 1272 up though. 1273 *VimResume* 1274VimResume When the Vim instance is resumed after being 1275 suspended and |VimSuspend| was triggered. 1276 Useful for triggering |:checktime| and ensure 1277 the buffers content did not change while Vim 1278 was suspended: > 1279 :autocmd VimResume * checktime 1280< *VimSuspend* 1281VimSuspend When the Vim instance is suspended. Only when 1282 CTRL-Z was typed inside Vim, not when the 1283 SIGSTOP or SIGTSTP signal was sent to Vim. 1284 *WinClosed* 1285WinClosed After closing a window. The pattern is 1286 matched against the |window-ID|. Both 1287 <amatch> and <afile> are set to the 1288 |window-ID|. Non-recursive (event cannot 1289 trigger itself). 1290 *WinEnter* 1291WinEnter After entering another window. Not done for 1292 the first window, when Vim has just started. 1293 Useful for setting the window height. 1294 If the window is for another buffer, Vim 1295 executes the BufEnter autocommands after the 1296 WinEnter autocommands. 1297 Note: For split and tabpage commands the 1298 WinEnter event is triggered after the split 1299 or tab command but before the file is loaded. 1300 1301 *WinLeave* 1302WinLeave Before leaving a window. If the window to be 1303 entered next is for a different buffer, Vim 1304 executes the BufLeave autocommands before the 1305 WinLeave autocommands (but not for ":new"). 1306 Not used for ":qa" or ":q" when exiting Vim. 1307 1308 *WinNew* 1309WinNew When a new window was created. Not done for 1310 the first window, when Vim has just started. 1311 Before a WinEnter event. 1312 1313============================================================================== 13146. Patterns *autocmd-patterns* *{pat}* 1315 1316The {pat} argument can be a comma separated list. This works as if the 1317command was given with each pattern separately. Thus this command: > 1318 :autocmd BufRead *.txt,*.info set et 1319Is equivalent to: > 1320 :autocmd BufRead *.txt set et 1321 :autocmd BufRead *.info set et 1322 1323The file pattern {pat} is tested for a match against the file name in one of 1324two ways: 13251. When there is no '/' in the pattern, Vim checks for a match against only 1326 the tail part of the file name (without its leading directory path). 13272. When there is a '/' in the pattern, Vim checks for a match against both the 1328 short file name (as you typed it) and the full file name (after expanding 1329 it to a full path and resolving symbolic links). 1330 1331The special pattern <buffer> or <buffer=N> is used for buffer-local 1332autocommands |autocmd-buflocal|. This pattern is not matched against the name 1333of a buffer. 1334 1335Examples: > 1336 :autocmd BufRead *.txt set et 1337Set the 'et' option for all text files. > 1338 1339 :autocmd BufRead /vim/src/*.c set cindent 1340Set the 'cindent' option for C files in the /vim/src directory. > 1341 1342 :autocmd BufRead /tmp/*.c set ts=5 1343If you have a link from "/tmp/test.c" to "/home/nobody/vim/src/test.c", and 1344you start editing "/tmp/test.c", this autocommand will match. 1345 1346Note: To match part of a path, but not from the root directory, use a '*' as 1347the first character. Example: > 1348 :autocmd BufRead */doc/*.txt set tw=78 1349This autocommand will for example be executed for "/tmp/doc/xx.txt" and 1350"/usr/home/piet/doc/yy.txt". The number of directories does not matter here. 1351 1352 1353The file name that the pattern is matched against is after expanding 1354wildcards. Thus if you issue this command: > 1355 :e $ROOTDIR/main.$EXT 1356The argument is first expanded to: > 1357 /usr/root/main.py 1358Before it's matched with the pattern of the autocommand. Careful with this 1359when using events like FileReadCmd, the value of <amatch> may not be what you 1360expect. 1361 1362 1363Environment variables can be used in a pattern: > 1364 :autocmd BufRead $VIMRUNTIME/doc/*.txt set expandtab 1365And ~ can be used for the home directory (if $HOME is defined): > 1366 :autocmd BufWritePost ~/.vimrc so ~/.vimrc 1367 :autocmd BufRead ~archive/* set readonly 1368The environment variable is expanded when the autocommand is defined, not when 1369the autocommand is executed. This is different from the command! 1370 1371 *file-pattern* 1372The pattern is interpreted like mostly used in file names: 1373 * matches any sequence of characters; Unusual: includes path 1374 separators 1375 ? matches any single character 1376 \? matches a '?' 1377 . matches a '.' 1378 ~ matches a '~' 1379 , separates patterns 1380 \, matches a ',' 1381 { } like \( \) in a |pattern| 1382 , inside { }: like \| in a |pattern| 1383 \} literal } 1384 \{ literal { 1385 \\\{n,m\} like \{n,m} in a |pattern| 1386 \ special meaning like in a |pattern| 1387 [ch] matches 'c' or 'h' 1388 [^ch] match any character but 'c' and 'h' 1389 1390Note that for all systems the '/' character is used for path separator (even 1391for MS-Windows). This was done because the backslash is difficult to use in a 1392pattern and to make the autocommands portable across different systems. 1393 1394It is possible to use |pattern| items, but they may not work as expected, 1395because of the translation done for the above. 1396 1397 *autocmd-changes* 1398Matching with the pattern is done when an event is triggered. Changing the 1399buffer name in one of the autocommands, or even deleting the buffer, does not 1400change which autocommands will be executed. Example: > 1401 1402 au BufEnter *.foo bdel 1403 au BufEnter *.foo set modified 1404 1405This will delete the current buffer and then set 'modified' in what has become 1406the current buffer instead. Vim doesn't take into account that "*.foo" 1407doesn't match with that buffer name. It matches "*.foo" with the name of the 1408buffer at the moment the event was triggered. 1409 1410However, buffer-local autocommands will not be executed for a buffer that has 1411been wiped out with |:bwipe|. After deleting the buffer with |:bdel| the 1412buffer actually still exists (it becomes unlisted), thus the autocommands are 1413still executed. 1414 1415============================================================================== 14167. Buffer-local autocommands *autocmd-buflocal* *autocmd-buffer-local* 1417 *<buffer=N>* *<buffer=abuf>* *E680* 1418 1419Buffer-local autocommands are attached to a specific buffer. They are useful 1420if the buffer does not have a name and when the name does not match a specific 1421pattern. But it also means they must be explicitly added to each buffer. 1422 1423Instead of a pattern buffer-local autocommands use one of these forms: 1424 <buffer> current buffer 1425 <buffer=99> buffer number 99 1426 <buffer=abuf> using <abuf> (only when executing autocommands) 1427 |<abuf>| 1428 1429Examples: > 1430 :au CursorHold <buffer> echo 'hold' 1431 :au CursorHold <buffer=33> echo 'hold' 1432 :au BufNewFile * au CursorHold <buffer=abuf> echo 'hold' 1433 1434All the commands for autocommands also work with buffer-local autocommands, 1435simply use the special string instead of the pattern. Examples: > 1436 :au! * <buffer> " remove buffer-local autocommands for 1437 " current buffer 1438 :au! * <buffer=33> " remove buffer-local autocommands for 1439 " buffer #33 1440 :bufdo :au! CursorHold <buffer> " remove autocmd for given event for all 1441 " buffers 1442 :au * <buffer> " list buffer-local autocommands for 1443 " current buffer 1444 1445Note that when an autocommand is defined for the current buffer, it is stored 1446with the buffer number. Thus it uses the form "<buffer=12>", where 12 is the 1447number of the current buffer. You will see this when listing autocommands, 1448for example. 1449 1450To test for presence of buffer-local autocommands use the |exists()| function 1451as follows: > 1452 :if exists("#CursorHold#<buffer=12>") | ... | endif 1453 :if exists("#CursorHold#<buffer>") | ... | endif " for current buffer 1454 1455When a buffer is wiped out its buffer-local autocommands are also gone, of 1456course. Note that when deleting a buffer, e.g., with ":bdel", it is only 1457unlisted, the autocommands are still present. In order to see the removal of 1458buffer-local autocommands: > 1459 :set verbose=6 1460 1461It is not possible to define buffer-local autocommands for a non-existent 1462buffer. 1463 1464============================================================================== 14658. Groups *autocmd-groups* 1466 1467Autocommands can be put together in a group. This is useful for removing or 1468executing a group of autocommands. For example, all the autocommands for 1469syntax highlighting are put in the "highlight" group, to be able to execute 1470":doautoall highlight BufRead" when the GUI starts. 1471 1472When no specific group is selected, Vim uses the default group. The default 1473group does not have a name. You cannot execute the autocommands from the 1474default group separately; you can execute them only by executing autocommands 1475for all groups. 1476 1477Normally, when executing autocommands automatically, Vim uses the autocommands 1478for all groups. The group only matters when executing autocommands with 1479":doautocmd" or ":doautoall", or when defining or deleting autocommands. 1480 1481The group name can contain any characters except white space. The group name 1482"end" is reserved (also in uppercase). 1483 1484The group name is case sensitive. Note that this is different from the event 1485name! 1486 1487 *:aug* *:augroup* 1488:aug[roup] {name} Define the autocmd group name for the 1489 following ":autocmd" commands. The name "end" 1490 or "END" selects the default group. 1491 To avoid confusion, the name should be 1492 different from existing {event} names, as this 1493 most likely will not do what you intended. 1494 1495 *:augroup-delete* *E367* *W19* *E936* 1496:aug[roup]! {name} Delete the autocmd group {name}. Don't use 1497 this if there is still an autocommand using 1498 this group! You will get a warning if doing 1499 it anyway. When the group is the current 1500 group you will get error E936. 1501 1502To enter autocommands for a specific group, use this method: 15031. Select the group with ":augroup {name}". 15042. Delete any old autocommands with ":au!". 15053. Define the autocommands. 15064. Go back to the default group with "augroup END". 1507 1508Example: > 1509 :augroup uncompress 1510 : au! 1511 : au BufEnter *.gz %!gunzip 1512 :augroup END 1513 1514This prevents having the autocommands defined twice (e.g., after sourcing the 1515.vimrc file again). 1516 1517 *FileExplorer* 1518There is one group that is recognized by Vim: FileExplorer. If this group 1519exists Vim assumes that editing a directory is possible and will trigger a 1520plugin that lists the files in that directory. This is used by the |netrw| 1521plugin. This allows you to do: > 1522 browse edit 1523 1524============================================================================== 15259. Executing autocommands *autocmd-execute* 1526 1527Vim can also execute Autocommands non-automatically. This is useful if you 1528have changed autocommands, or when Vim has executed the wrong autocommands 1529(e.g., the file pattern match was wrong). 1530 1531Note that the 'eventignore' option applies here too. Events listed in this 1532option will not cause any commands to be executed. 1533 1534 *:do* *:doau* *:doaut* *:doautocmd* *E217* 1535:do[autocmd] [<nomodeline>] [group] {event} [fname] 1536 Apply the autocommands matching [fname] (default: 1537 current file name) for {event} to the current buffer. 1538 You can use this when the current file name does not 1539 match the right pattern, after changing settings, or 1540 to execute autocommands for a certain event. 1541 It's possible to use this inside an autocommand too, 1542 so you can base the autocommands for one extension on 1543 another extension. Example: > 1544 :au BufEnter *.cpp so ~/.vimrc_cpp 1545 :au BufEnter *.cpp doau BufEnter x.c 1546< Be careful to avoid endless loops. See 1547 |autocmd-nested|. 1548 1549 When the [group] argument is not given, Vim executes 1550 the autocommands for all groups. When the [group] 1551 argument is included, Vim executes only the matching 1552 autocommands for that group. Note: if you use an 1553 undefined group name, Vim gives you an error message. 1554 *<nomodeline>* 1555 After applying the autocommands the modelines are 1556 processed, so that their settings overrule the 1557 settings from autocommands, like what happens when 1558 editing a file. This is skipped when the <nomodeline> 1559 argument is present. You probably want to use 1560 <nomodeline> for events that are not used when loading 1561 a buffer, such as |User|. 1562 Processing modelines is also skipped when no 1563 matching autocommands were executed. 1564 1565 *:doautoa* *:doautoall* 1566:doautoa[ll] [<nomodeline>] [group] {event} [fname] 1567 Like ":doautocmd", but apply the autocommands to each 1568 loaded buffer. The current buffer is done last. 1569 1570 Note that [fname] is used to select the autocommands, 1571 not the buffers to which they are applied. Example: > 1572 augroup mine 1573 autocmd! 1574 autocmd FileType * echo expand('<amatch>') 1575 augroup END 1576 doautoall mine FileType Loaded-Buffer 1577< Sourcing this script, you'll see as many 1578 "Loaded-Buffer" echoed as there are loaded buffers. 1579 1580 Careful: Don't use this for autocommands that delete a 1581 buffer, change to another buffer or change the 1582 contents of a buffer; the result is unpredictable. 1583 This command is intended for autocommands that set 1584 options, change highlighting, and things like that. 1585 1586============================================================================== 158710. Using autocommands *autocmd-use* 1588 1589For WRITING FILES there are four possible sets of events. Vim uses only one 1590of these sets for a write command: 1591 1592BufWriteCmd BufWritePre BufWritePost writing the whole buffer 1593 FilterWritePre FilterWritePost writing to filter temp file 1594FileAppendCmd FileAppendPre FileAppendPost appending to a file 1595FileWriteCmd FileWritePre FileWritePost any other file write 1596 1597When there is a matching "*Cmd" autocommand, it is assumed it will do the 1598writing. No further writing is done and the other events are not triggered. 1599|Cmd-event| 1600 1601Note that the *WritePost commands should undo any changes to the buffer that 1602were caused by the *WritePre commands; otherwise, writing the file will have 1603the side effect of changing the buffer. 1604 1605Before executing the autocommands, the buffer from which the lines are to be 1606written temporarily becomes the current buffer. Unless the autocommands 1607change the current buffer or delete the previously current buffer, the 1608previously current buffer is made the current buffer again. 1609 1610The *WritePre and *AppendPre autocommands must not delete the buffer from 1611which the lines are to be written. 1612 1613The '[ and '] marks have a special position: 1614- Before the *ReadPre event the '[ mark is set to the line just above where 1615 the new lines will be inserted. 1616- Before the *ReadPost event the '[ mark is set to the first line that was 1617 just read, the '] mark to the last line. 1618- Before executing the *WriteCmd, *WritePre and *AppendPre autocommands the '[ 1619 mark is set to the first line that will be written, the '] mark to the last 1620 line. 1621Careful: '[ and '] change when using commands that change the buffer. 1622 1623In commands which expect a file name, you can use "<afile>" for the file name 1624that is being read |:<afile>| (you can also use "%" for the current file 1625name). "<abuf>" can be used for the buffer number of the currently effective 1626buffer. This also works for buffers that don't have a name. But it doesn't 1627work for files without a buffer (e.g., with ":r file"). 1628 1629 *gzip-example* 1630Examples for reading and writing compressed files: > 1631 :augroup gzip 1632 : autocmd! 1633 : autocmd BufReadPre,FileReadPre *.gz set bin 1634 : autocmd BufReadPost,FileReadPost *.gz '[,']!gunzip 1635 : autocmd BufReadPost,FileReadPost *.gz set nobin 1636 : autocmd BufReadPost,FileReadPost *.gz execute ":doautocmd BufReadPost " . expand("%:r") 1637 : autocmd BufWritePost,FileWritePost *.gz !mv <afile> <afile>:r 1638 : autocmd BufWritePost,FileWritePost *.gz !gzip <afile>:r 1639 1640 : autocmd FileAppendPre *.gz !gunzip <afile> 1641 : autocmd FileAppendPre *.gz !mv <afile>:r <afile> 1642 : autocmd FileAppendPost *.gz !mv <afile> <afile>:r 1643 : autocmd FileAppendPost *.gz !gzip <afile>:r 1644 :augroup END 1645 1646The "gzip" group is used to be able to delete any existing autocommands with 1647":autocmd!", for when the file is sourced twice. 1648 1649("<afile>:r" is the file name without the extension, see |:_%:|) 1650 1651The commands executed for the BufNewFile, BufRead/BufReadPost, BufWritePost, 1652FileAppendPost and VimLeave events do not set or reset the changed flag of the 1653buffer. When you decompress the buffer with the BufReadPost autocommands, you 1654can still exit with ":q". When you use ":undo" in BufWritePost to undo the 1655changes made by BufWritePre commands, you can still do ":q" (this also makes 1656"ZZ" work). If you do want the buffer to be marked as modified, set the 1657'modified' option. 1658 1659To execute Normal mode commands from an autocommand, use the ":normal" 1660command. Use with care! If the Normal mode command is not finished, the user 1661needs to type characters (e.g., after ":normal m" you need to type a mark 1662name). 1663 1664If you want the buffer to be unmodified after changing it, reset the 1665'modified' option. This makes it possible to exit the buffer with ":q" 1666instead of ":q!". 1667 1668 *autocmd-nested* *E218* 1669By default, autocommands do not nest. For example, if you use ":e" or ":w" in 1670an autocommand, Vim does not execute the BufRead and BufWrite autocommands for 1671those commands. If you do want this, use the "nested" flag for those commands 1672in which you want nesting. For example: > 1673 :autocmd FileChangedShell *.c ++nested e! 1674The nesting is limited to 10 levels to get out of recursive loops. 1675 1676It's possible to use the ":au" command in an autocommand. This can be a 1677self-modifying command! This can be useful for an autocommand that should 1678execute only once. 1679 1680If you want to skip autocommands for one command, use the |:noautocmd| command 1681modifier or the 'eventignore' option. 1682 1683Note: When reading a file (with ":read file" or with a filter command) and the 1684last line in the file does not have an <EOL>, Vim remembers this. At the next 1685write (with ":write file" or with a filter command), if the same line is 1686written again as the last line in a file AND 'binary' is set, Vim does not 1687supply an <EOL>. This makes a filter command on the just read lines write the 1688same file as was read, and makes a write command on just filtered lines write 1689the same file as was read from the filter. For example, another way to write 1690a compressed file: > 1691 1692 :autocmd FileWritePre *.gz set bin|'[,']!gzip 1693 :autocmd FileWritePost *.gz undo|set nobin 1694< 1695 *autocommand-pattern* 1696You can specify multiple patterns, separated by commas. Here are some 1697examples: > 1698 1699 :autocmd BufRead * set tw=79 nocin ic infercase fo=2croq 1700 :autocmd BufRead .letter set tw=72 fo=2tcrq 1701 :autocmd BufEnter .letter set dict=/usr/lib/dict/words 1702 :autocmd BufLeave .letter set dict= 1703 :autocmd BufRead,BufNewFile *.c,*.h set tw=0 cin noic 1704 :autocmd BufEnter *.c,*.h abbr FOR for (i = 0; i < 3; ++i)<CR>{<CR>}<Esc>O 1705 :autocmd BufLeave *.c,*.h unabbr FOR 1706 1707For makefiles (makefile, Makefile, imakefile, makefile.unix, etc.): > 1708 1709 :autocmd BufEnter ?akefile* set include=^s\=include 1710 :autocmd BufLeave ?akefile* set include& 1711 1712To always start editing C files at the first function: > 1713 1714 :autocmd BufRead *.c,*.h 1;/^{ 1715 1716Without the "1;" above, the search would start from wherever the file was 1717entered, rather than from the start of the file. 1718 1719 *skeleton* *template* 1720To read a skeleton (template) file when opening a new file: > 1721 1722 :autocmd BufNewFile *.c 0r ~/vim/skeleton.c 1723 :autocmd BufNewFile *.h 0r ~/vim/skeleton.h 1724 :autocmd BufNewFile *.java 0r ~/vim/skeleton.java 1725 1726To insert the current date and time in a *.html file when writing it: > 1727 1728 :autocmd BufWritePre,FileWritePre *.html ks|call LastMod()|'s 1729 :fun LastMod() 1730 : if line("$") > 20 1731 : let l = 20 1732 : else 1733 : let l = line("$") 1734 : endif 1735 : exe "1," . l . "g/Last modified: /s/Last modified: .*/Last modified: " . 1736 : \ strftime("%Y %b %d") 1737 :endfun 1738 1739You need to have a line "Last modified: <date time>" in the first 20 lines 1740of the file for this to work. Vim replaces <date time> (and anything in the 1741same line after it) with the current date and time. Explanation: 1742 ks mark current position with mark 's' 1743 call LastMod() call the LastMod() function to do the work 1744 's return the cursor to the old position 1745The LastMod() function checks if the file is shorter than 20 lines, and then 1746uses the ":g" command to find lines that contain "Last modified: ". For those 1747lines the ":s" command is executed to replace the existing date with the 1748current one. The ":execute" command is used to be able to use an expression 1749for the ":g" and ":s" commands. The date is obtained with the strftime() 1750function. You can change its argument to get another date string. 1751 1752When entering :autocmd on the command-line, completion of events and command 1753names may be done (with <Tab>, CTRL-D, etc.) where appropriate. 1754 1755Vim executes all matching autocommands in the order that you specify them. 1756It is recommended that your first autocommand be used for all files by using 1757"*" as the file pattern. This means that you can define defaults you like 1758here for any settings, and if there is another matching autocommand it will 1759override these. But if there is no other matching autocommand, then at least 1760your default settings are recovered (if entering this file from another for 1761which autocommands did match). Note that "*" will also match files starting 1762with ".", unlike Unix shells. 1763 1764 *autocmd-searchpat* 1765Autocommands do not change the current search patterns. Vim saves the current 1766search patterns before executing autocommands then restores them after the 1767autocommands finish. This means that autocommands do not affect the strings 1768highlighted with the 'hlsearch' option. Within autocommands, you can still 1769use search patterns normally, e.g., with the "n" command. 1770If you want an autocommand to set the search pattern, such that it is used 1771after the autocommand finishes, use the ":let @/ =" command. 1772The search-highlighting cannot be switched off with ":nohlsearch" in an 1773autocommand. Use the 'h' flag in the 'viminfo' option to disable search- 1774highlighting when starting Vim. 1775 1776 *Cmd-event* 1777When using one of the "*Cmd" events, the matching autocommands are expected to 1778do the file reading, writing or sourcing. This can be used when working with 1779a special kind of file, for example on a remote system. 1780CAREFUL: If you use these events in a wrong way, it may have the effect of 1781making it impossible to read or write the matching files! Make sure you test 1782your autocommands properly. Best is to use a pattern that will never match a 1783normal file name, for example "ftp://*". 1784 1785When defining a BufReadCmd it will be difficult for Vim to recover a crashed 1786editing session. When recovering from the original file, Vim reads only those 1787parts of a file that are not found in the swap file. Since that is not 1788possible with a BufReadCmd, use the |:preserve| command to make sure the 1789original file isn't needed for recovery. You might want to do this only when 1790you expect the file to be modified. 1791 1792For file read and write commands the |v:cmdarg| variable holds the "++enc=" 1793and "++ff=" argument that are effective. These should be used for the command 1794that reads/writes the file. The |v:cmdbang| variable is one when "!" was 1795used, zero otherwise. 1796 1797See the $VIMRUNTIME/plugin/netrwPlugin.vim for examples. 1798 1799============================================================================== 180011. Disabling autocommands *autocmd-disable* 1801 1802To disable autocommands for some time use the 'eventignore' option. Note that 1803this may cause unexpected behavior, make sure you restore 'eventignore' 1804afterwards, using a |:try| block with |:finally|. 1805 1806 *:noautocmd* *:noa* 1807To disable autocommands for just one command use the ":noautocmd" command 1808modifier. This will set 'eventignore' to "all" for the duration of the 1809following command. Example: > 1810 1811 :noautocmd w fname.gz 1812 1813This will write the file without triggering the autocommands defined by the 1814gzip plugin. 1815 1816Note that some autocommands are not triggered right away, but only later. 1817This specifically applies to |CursorMoved| and |TextChanged|. 1818 1819 1820 vim:tw=78:ts=8:noet:ft=help:norl: 1821