1*autocmd.txt* For Vim version 7.3. Last change: 2010 Jul 22 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7Automatic commands *autocommand* 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{Vi does not have any of these commands} 24{only when the |+autocmd| feature has not been disabled at compile time} 25 26============================================================================== 271. Introduction *autocmd-intro* 28 29You can specify commands to be executed automatically when reading or writing 30a file, when entering or leaving a buffer or window, and when exiting Vim. 31For example, you can create an autocommand to set the 'cindent' option for 32files matching *.c. You can also use autocommands to implement advanced 33features, such as editing compressed files (see |gzip-example|). The usual 34place to put autocommands is in your .vimrc or .exrc file. 35 36 *E203* *E204* *E143* 37WARNING: Using autocommands is very powerful, and may lead to unexpected side 38effects. Be careful not to destroy your text. 39- It's a good idea to do some testing on an expendable copy of a file first. 40 For example: If you use autocommands to decompress a file when starting to 41 edit it, make sure that the autocommands for compressing when writing work 42 correctly. 43- Be prepared for an error halfway through (e.g., disk full). Vim will mostly 44 be able to undo the changes to the buffer, but you may have to clean up the 45 changes to other files by hand (e.g., compress a file that has been 46 decompressed). 47- If the BufRead* events allow you to edit a compressed file, the FileRead* 48 events should do the same (this makes recovery possible in some rare cases). 49 It's a good idea to use the same autocommands for the File* and Buf* events 50 when possible. 51 52============================================================================== 532. Defining autocommands *autocmd-define* 54 55Note: The ":autocmd" command cannot be followed by another command, since any 56'|' is considered part of the command. 57 58 *:au* *:autocmd* 59:au[tocmd] [group] {event} {pat} [nested] {cmd} 60 Add {cmd} to the list of commands that Vim will 61 execute automatically on {event} for a file matching 62 {pat} |autocmd-patterns|. 63 Vim always adds the {cmd} after existing autocommands, 64 so that the autocommands execute in the order in which 65 they were given. See |autocmd-nested| for [nested]. 66 67The special pattern <buffer> or <buffer=N> defines a buffer-local autocommand. 68See |autocmd-buflocal|. 69 70Note that special characters (e.g., "%", "<cword>") in the ":autocmd" 71arguments are not expanded when the autocommand is defined. These will be 72expanded when the Event is recognized, and the {cmd} is executed. The only 73exception is that "<sfile>" is expanded when the autocmd is defined. Example: 74> 75 :au BufNewFile,BufRead *.html so <sfile>:h/html.vim 76 77Here Vim expands <sfile> to the name of the file containing this line. 78 79When your .vimrc file is sourced twice, the autocommands will appear twice. 80To avoid this, put this command in your .vimrc file, before defining 81autocommands: > 82 83 :autocmd! " Remove ALL autocommands for the current group. 84 85If you don't want to remove all autocommands, you can instead use a variable 86to ensure that Vim includes the autocommands only once: > 87 88 :if !exists("autocommands_loaded") 89 : let autocommands_loaded = 1 90 : au ... 91 :endif 92 93When the [group] argument is not given, Vim uses the current group (as defined 94with ":augroup"); otherwise, Vim uses the group defined with [group]. Note 95that [group] must have been defined before. You cannot define a new group 96with ":au group ..."; use ":augroup" for that. 97 98While testing autocommands, you might find the 'verbose' option to be useful: > 99 :set verbose=9 100This setting makes Vim echo the autocommands as it executes them. 101 102When defining an autocommand in a script, it will be able to call functions 103local to the script and use mappings local to the script. When the event is 104triggered and the command executed, it will run in the context of the script 105it was defined in. This matters if |<SID>| is used in a command. 106 107When executing the commands, the message from one command overwrites a 108previous message. This is different from when executing the commands 109manually. Mostly the screen will not scroll up, thus there is no hit-enter 110prompt. When one command outputs two messages this can happen anyway. 111 112============================================================================== 1133. Removing autocommands *autocmd-remove* 114 115:au[tocmd]! [group] {event} {pat} [nested] {cmd} 116 Remove all autocommands associated with {event} and 117 {pat}, and add the command {cmd}. See 118 |autocmd-nested| for [nested]. 119 120:au[tocmd]! [group] {event} {pat} 121 Remove all autocommands associated with {event} and 122 {pat}. 123 124:au[tocmd]! [group] * {pat} 125 Remove all autocommands associated with {pat} for all 126 events. 127 128:au[tocmd]! [group] {event} 129 Remove ALL autocommands for {event}. 130 131:au[tocmd]! [group] Remove ALL autocommands. 132 133When the [group] argument is not given, Vim uses the current group (as defined 134with ":augroup"); otherwise, Vim uses the group defined with [group]. 135 136============================================================================== 1374. Listing autocommands *autocmd-list* 138 139:au[tocmd] [group] {event} {pat} 140 Show the autocommands associated with {event} and 141 {pat}. 142 143:au[tocmd] [group] * {pat} 144 Show the autocommands associated with {pat} for all 145 events. 146 147:au[tocmd] [group] {event} 148 Show all autocommands for {event}. 149 150:au[tocmd] [group] Show all autocommands. 151 152If you provide the [group] argument, Vim lists only the autocommands for 153[group]; otherwise, Vim lists the autocommands for ALL groups. Note that this 154argument behavior differs from that for defining and removing autocommands. 155 156In order to list buffer-local autocommands, use a pattern in the form <buffer> 157or <buffer=N>. See |autocmd-buflocal|. 158 159 *:autocmd-verbose* 160When 'verbose' is non-zero, listing an autocommand will also display where it 161was last defined. Example: > 162 163 :verbose autocmd BufEnter 164 FileExplorer BufEnter 165 * call s:LocalBrowse(expand("<amatch>")) 166 Last set from /usr/share/vim/vim-7.0/plugin/NetrwPlugin.vim 167< 168See |:verbose-cmd| for more information. 169 170============================================================================== 1715. Events *autocmd-events* *E215* *E216* 172 173You can specify a comma-separated list of event names. No white space can be 174used in this list. The command applies to all the events in the list. 175 176For READING FILES there are four kinds of events possible: 177 BufNewFile starting to edit a non-existent file 178 BufReadPre BufReadPost starting to edit an existing file 179 FilterReadPre FilterReadPost read the temp file with filter output 180 FileReadPre FileReadPost any other file read 181Vim uses only one of these four kinds when reading a file. The "Pre" and 182"Post" events are both triggered, before and after reading the file. 183 184Note that the autocommands for the *ReadPre events and all the Filter events 185are not allowed to change the current buffer (you will get an error message if 186this happens). This is to prevent the file to be read into the wrong buffer. 187 188Note that the 'modified' flag is reset AFTER executing the BufReadPost 189and BufNewFile autocommands. But when the 'modified' option was set by the 190autocommands, this doesn't happen. 191 192You can use the 'eventignore' option to ignore a number of events or all 193events. 194 *autocommand-events* *{event}* 195Vim recognizes the following events. Vim ignores the case of event names 196(e.g., you can use "BUFread" or "bufread" instead of "BufRead"). 197 198First an overview by function with a short explanation. Then the list 199alphabetically with full explanations |autocmd-events-abc|. 200 201Name triggered by ~ 202 203 Reading 204|BufNewFile| starting to edit a file that doesn't exist 205|BufReadPre| starting to edit a new buffer, before reading the file 206|BufRead| starting to edit a new buffer, after reading the file 207|BufReadPost| starting to edit a new buffer, after reading the file 208|BufReadCmd| before starting to edit a new buffer |Cmd-event| 209 210|FileReadPre| before reading a file with a ":read" command 211|FileReadPost| after reading a file with a ":read" command 212|FileReadCmd| before reading a file with a ":read" command |Cmd-event| 213 214|FilterReadPre| before reading a file from a filter command 215|FilterReadPost| after reading a file from a filter command 216 217|StdinReadPre| before reading from stdin into the buffer 218|StdinReadPost| After reading from the stdin into the buffer 219 220 Writing 221|BufWrite| starting to write the whole buffer to a file 222|BufWritePre| starting to write the whole buffer to a file 223|BufWritePost| after writing the whole buffer to a file 224|BufWriteCmd| before writing the whole buffer to a file |Cmd-event| 225 226|FileWritePre| starting to write part of a buffer to a file 227|FileWritePost| after writing part of a buffer to a file 228|FileWriteCmd| before writing part of a buffer to a file |Cmd-event| 229 230|FileAppendPre| starting to append to a file 231|FileAppendPost| after appending to a file 232|FileAppendCmd| before appending to a file |Cmd-event| 233 234|FilterWritePre| starting to write a file for a filter command or diff 235|FilterWritePost| after writing a file for a filter command or diff 236 237 Buffers 238|BufAdd| just after adding a buffer to the buffer list 239|BufCreate| just after adding a buffer to the buffer list 240|BufDelete| before deleting a buffer from the buffer list 241|BufWipeout| before completely deleting a buffer 242 243|BufFilePre| before changing the name of the current buffer 244|BufFilePost| after changing the name of the current buffer 245 246|BufEnter| after entering a buffer 247|BufLeave| before leaving to another buffer 248|BufWinEnter| after a buffer is displayed in a window 249|BufWinLeave| before a buffer is removed from a window 250 251|BufUnload| before unloading a buffer 252|BufHidden| just after a buffer has become hidden 253|BufNew| just after creating a new buffer 254 255|SwapExists| detected an existing swap file 256 257 Options 258|FileType| when the 'filetype' option has been set 259|Syntax| when the 'syntax' option has been set 260|EncodingChanged| after the 'encoding' option has been changed 261|TermChanged| after the value of 'term' has changed 262 263 Startup and exit 264|VimEnter| after doing all the startup stuff 265|GUIEnter| after starting the GUI successfully 266|TermResponse| after the terminal response to |t_RV| is received 267 268|VimLeavePre| before exiting Vim, before writing the viminfo file 269|VimLeave| before exiting Vim, after writing the viminfo file 270 271 Various 272|FileChangedShell| Vim notices that a file changed since editing started 273|FileChangedShellPost| After handling a file changed since editing started 274|FileChangedRO| before making the first change to a read-only file 275 276|ShellCmdPost| after executing a shell command 277|ShellFilterPost| after filtering with a shell command 278 279|FuncUndefined| a user function is used but it isn't defined 280|SpellFileMissing| a spell file is used but it can't be found 281|SourcePre| before sourcing a Vim script 282|SourceCmd| before sourcing a Vim script |Cmd-event| 283 284|VimResized| after the Vim window size changed 285|FocusGained| Vim got input focus 286|FocusLost| Vim lost input focus 287|CursorHold| the user doesn't press a key for a while 288|CursorHoldI| the user doesn't press a key for a while in Insert mode 289|CursorMoved| the cursor was moved in Normal mode 290|CursorMovedI| the cursor was moved in Insert mode 291 292|WinEnter| after entering another window 293|WinLeave| before leaving a window 294|TabEnter| after entering another tab page 295|TabLeave| before leaving a tab page 296|CmdwinEnter| after entering the command-line window 297|CmdwinLeave| before leaving the command-line window 298 299|InsertEnter| starting Insert mode 300|InsertChange| when typing <Insert> while in Insert or Replace mode 301|InsertLeave| when leaving Insert mode 302 303|ColorScheme| after loading a color scheme 304 305|RemoteReply| a reply from a server Vim was received 306 307|QuickFixCmdPre| before a quickfix command is run 308|QuickFixCmdPost| after a quickfix command is run 309 310|SessionLoadPost| after loading a session file 311 312|MenuPopup| just before showing the popup menu 313 314|User| to be used in combination with ":doautocmd" 315 316 317The alphabetical list of autocommand events: *autocmd-events-abc* 318 319 *BufCreate* *BufAdd* 320BufAdd or BufCreate Just after creating a new buffer which is 321 added to the buffer list, or adding a buffer 322 to the buffer list. 323 Also used just after a buffer in the buffer 324 list has been renamed. 325 The BufCreate event is for historic reasons. 326 NOTE: When this autocommand is executed, the 327 current buffer "%" may be different from the 328 buffer being created "<afile>". 329 *BufDelete* 330BufDelete Before deleting a buffer from the buffer list. 331 The BufUnload may be called first (if the 332 buffer was loaded). 333 Also used just before a buffer in the buffer 334 list is renamed. 335 NOTE: When this autocommand is executed, the 336 current buffer "%" may be different from the 337 buffer being deleted "<afile>" and "<abuf>". 338 Don't change to another buffer, it will cause 339 problems. 340 *BufEnter* 341BufEnter After entering a buffer. Useful for setting 342 options for a file type. Also executed when 343 starting to edit a buffer, after the 344 BufReadPost autocommands. 345 *BufFilePost* 346BufFilePost After changing the name of the current buffer 347 with the ":file" or ":saveas" command. 348 *BufFilePre* 349BufFilePre Before changing the name of the current buffer 350 with the ":file" or ":saveas" command. 351 *BufHidden* 352BufHidden Just after a buffer has become hidden. That 353 is, when there are no longer windows that show 354 the buffer, but the buffer is not unloaded or 355 deleted. Not used for ":qa" or ":q" when 356 exiting Vim. 357 NOTE: When this autocommand is executed, the 358 current buffer "%" may be different from the 359 buffer being unloaded "<afile>". 360 *BufLeave* 361BufLeave Before leaving to another buffer. Also when 362 leaving or closing the current window and the 363 new current window is not for the same buffer. 364 Not used for ":qa" or ":q" when exiting Vim. 365 *BufNew* 366BufNew Just after creating a new buffer. Also used 367 just after a buffer has been renamed. When 368 the buffer is added to the buffer list BufAdd 369 will be triggered too. 370 NOTE: When this autocommand is executed, the 371 current buffer "%" may be different from the 372 buffer being created "<afile>". 373 *BufNewFile* 374BufNewFile When starting to edit a file that doesn't 375 exist. Can be used to read in a skeleton 376 file. 377 *BufRead* *BufReadPost* 378BufRead or BufReadPost When starting to edit a new buffer, after 379 reading the file into the buffer, before 380 executing the modelines. See |BufWinEnter| 381 for when you need to do something after 382 processing the modelines. 383 This does NOT work for ":r file". Not used 384 when the file doesn't exist. Also used after 385 successfully recovering a file. 386 *BufReadCmd* 387BufReadCmd Before starting to edit a new buffer. Should 388 read the file into the buffer. |Cmd-event| 389 *BufReadPre* *E200* *E201* 390BufReadPre When starting to edit a new buffer, before 391 reading the file into the buffer. Not used 392 if the file doesn't exist. 393 *BufUnload* 394BufUnload Before unloading a buffer. This is when the 395 text in the buffer is going to be freed. This 396 may be after a BufWritePost and before a 397 BufDelete. Also used for all buffers that are 398 loaded when Vim is going to exit. 399 NOTE: When this autocommand is executed, the 400 current buffer "%" may be different from the 401 buffer being unloaded "<afile>". 402 Don't change to another buffer, it will cause 403 problems. 404 When exiting and v:dying is 2 or more this 405 event is not triggered. 406 *BufWinEnter* 407BufWinEnter After a buffer is displayed in a window. This 408 can be when the buffer is loaded (after 409 processing the modelines) or when a hidden 410 buffer is displayed in a window (and is no 411 longer hidden). 412 Does not happen for |:split| without 413 arguments, since you keep editing the same 414 buffer, or ":split" with a file that's already 415 open in a window, because it re-uses an 416 existing buffer. But it does happen for a 417 ":split" with the name of the current buffer, 418 since it reloads that buffer. 419 *BufWinLeave* 420BufWinLeave Before a buffer is removed from a window. 421 Not when it's still visible in another window. 422 Also triggered when exiting. It's triggered 423 before BufUnload or BufHidden. 424 NOTE: When this autocommand is executed, the 425 current buffer "%" may be different from the 426 buffer being unloaded "<afile>". 427 When exiting and v:dying is 2 or more this 428 event is not triggered. 429 *BufWipeout* 430BufWipeout Before completely deleting a buffer. The 431 BufUnload and BufDelete events may be called 432 first (if the buffer was loaded and was in the 433 buffer list). Also used just before a buffer 434 is renamed (also when it's not in the buffer 435 list). 436 NOTE: When this autocommand is executed, the 437 current buffer "%" may be different from the 438 buffer being deleted "<afile>". 439 Don't change to another buffer, it will cause 440 problems. 441 *BufWrite* *BufWritePre* 442BufWrite or BufWritePre Before writing the whole buffer to a file. 443 *BufWriteCmd* 444BufWriteCmd Before writing the whole buffer to a file. 445 Should do the writing of the file and reset 446 'modified' if successful, unless '+' is in 447 'cpo' and writing to another file |cpo-+|. 448 The buffer contents should not be changed. 449 |Cmd-event| 450 *BufWritePost* 451BufWritePost After writing the whole buffer to a file 452 (should undo the commands for BufWritePre). 453 *CmdwinEnter* 454CmdwinEnter After entering the command-line window. 455 Useful for setting options specifically for 456 this special type of window. This is 457 triggered _instead_ of BufEnter and WinEnter. 458 <afile> is set to a single character, 459 indicating the type of command-line. 460 |cmdwin-char| 461 *CmdwinLeave* 462CmdwinLeave Before leaving the command-line window. 463 Useful to clean up any global setting done 464 with CmdwinEnter. This is triggered _instead_ 465 of BufLeave and WinLeave. 466 <afile> is set to a single character, 467 indicating the type of command-line. 468 |cmdwin-char| 469 *ColorScheme* 470ColorScheme After loading a color scheme. |:colorscheme| 471 472 *CursorHold* 473CursorHold When the user doesn't press a key for the time 474 specified with 'updatetime'. Not re-triggered 475 until the user has pressed a key (i.e. doesn't 476 fire every 'updatetime' ms if you leave Vim to 477 make some coffee. :) See |CursorHold-example| 478 for previewing tags. 479 This event is only triggered in Normal mode. 480 It is not triggered when waiting for a command 481 argument to be typed, or a movement after an 482 operator. 483 While recording the CursorHold event is not 484 triggered. |q| 485 Note: Interactive commands cannot be used for 486 this event. There is no hit-enter prompt, 487 the screen is updated directly (when needed). 488 Note: In the future there will probably be 489 another option to set the time. 490 Hint: to force an update of the status lines 491 use: > 492 :let &ro = &ro 493< {only on Amiga, Unix, Win32, MSDOS and all GUI 494 versions} 495 *CursorHoldI* 496CursorHoldI Just like CursorHold, but in Insert mode. 497 498 *CursorMoved* 499CursorMoved After the cursor was moved in Normal mode. 500 Also when the text of the cursor line has been 501 changed, e.g., with "x", "rx" or "p". 502 Not triggered when there is typeahead or when 503 an operator is pending. 504 For an example see |match-parens|. 505 Careful: Don't do anything that the user does 506 not expect or that is slow. 507 *CursorMovedI* 508CursorMovedI After the cursor was moved in Insert mode. 509 Otherwise the same as CursorMoved. 510 *EncodingChanged* 511EncodingChanged Fires off after the 'encoding' option has been 512 changed. Useful to set up fonts, for example. 513 *FileAppendCmd* 514FileAppendCmd Before appending to a file. Should do the 515 appending to the file. Use the '[ and '] 516 marks for the range of lines.|Cmd-event| 517 *FileAppendPost* 518FileAppendPost After appending to a file. 519 *FileAppendPre* 520FileAppendPre Before appending to a file. Use the '[ and '] 521 marks for the range of lines. 522 *FileChangedRO* 523FileChangedRO Before making the first change to a read-only 524 file. Can be used to check-out the file from 525 a source control system. Not triggered when 526 the change was caused by an autocommand. 527 This event is triggered when making the first 528 change in a buffer or the first change after 529 'readonly' was set, just before the change is 530 applied to the text. 531 WARNING: If the autocommand moves the cursor 532 the effect of the change is undefined. 533 *E788* 534 It is not allowed to change to another buffer 535 here. You can reload the buffer but not edit 536 another one. 537 *FileChangedShell* 538FileChangedShell When Vim notices that the modification time of 539 a file has changed since editing started. 540 Also when the file attributes of the file 541 change. |timestamp| 542 Mostly triggered after executing a shell 543 command, but also with a |:checktime| command 544 or when Gvim regains input focus. 545 This autocommand is triggered for each changed 546 file. It is not used when 'autoread' is set 547 and the buffer was not changed. If a 548 FileChangedShell autocommand is present the 549 warning message and prompt is not given. 550 The |v:fcs_reason| variable is set to indicate 551 what happened and |v:fcs_choice| can be used 552 to tell Vim what to do next. 553 NOTE: When this autocommand is executed, the 554 current buffer "%" may be different from the 555 buffer that was changed "<afile>". 556 NOTE: The commands must not change the current 557 buffer, jump to another buffer or delete a 558 buffer. *E246* *E811* 559 NOTE: This event never nests, to avoid an 560 endless loop. This means that while executing 561 commands for the FileChangedShell event no 562 other FileChangedShell event will be 563 triggered. 564 *FileChangedShellPost* 565FileChangedShellPost After handling a file that was changed outside 566 of Vim. Can be used to update the statusline. 567 *FileEncoding* 568FileEncoding Obsolete. It still works and is equivalent 569 to |EncodingChanged|. 570 *FileReadCmd* 571FileReadCmd Before reading a file with a ":read" command. 572 Should do the reading of the file. |Cmd-event| 573 *FileReadPost* 574FileReadPost After reading a file with a ":read" command. 575 Note that Vim sets the '[ and '] marks to the 576 first and last line of the read. This can be 577 used to operate on the lines just read. 578 *FileReadPre* 579FileReadPre Before reading a file with a ":read" command. 580 *FileType* 581FileType When the 'filetype' option has been set. The 582 pattern is matched against the filetype. 583 <afile> can be used for the name of the file 584 where this option was set, and <amatch> for 585 the new value of 'filetype'. 586 See |filetypes|. 587 *FileWriteCmd* 588FileWriteCmd Before writing to a file, when not writing the 589 whole buffer. Should do the writing to the 590 file. Should not change the buffer. Use the 591 '[ and '] marks for the range of lines. 592 |Cmd-event| 593 *FileWritePost* 594FileWritePost After writing to a file, when not writing the 595 whole buffer. 596 *FileWritePre* 597FileWritePre Before writing to a file, when not writing the 598 whole buffer. Use the '[ and '] marks for the 599 range of lines. 600 *FilterReadPost* 601FilterReadPost After reading a file from a filter command. 602 Vim checks the pattern against the name of 603 the current buffer as with FilterReadPre. 604 Not triggered when 'shelltemp' is off. 605 *FilterReadPre* *E135* 606FilterReadPre Before reading a file from a filter command. 607 Vim checks the pattern against the name of 608 the current buffer, not the name of the 609 temporary file that is the output of the 610 filter command. 611 Not triggered when 'shelltemp' is off. 612 *FilterWritePost* 613FilterWritePost After writing a file for a filter command or 614 making a diff. 615 Vim checks the pattern against the name of 616 the current buffer as with FilterWritePre. 617 Not triggered when 'shelltemp' is off. 618 *FilterWritePre* 619FilterWritePre Before writing a file for a filter command or 620 making a diff. 621 Vim checks the pattern against the name of 622 the current buffer, not the name of the 623 temporary file that is the output of the 624 filter command. 625 Not triggered when 'shelltemp' is off. 626 *FocusGained* 627FocusGained When Vim got input focus. Only for the GUI 628 version and a few console versions where this 629 can be detected. 630 *FocusLost* 631FocusLost When Vim lost input focus. Only for the GUI 632 version and a few console versions where this 633 can be detected. May also happen when a 634 dialog pops up. 635 *FuncUndefined* 636FuncUndefined When a user function is used but it isn't 637 defined. Useful for defining a function only 638 when it's used. The pattern is matched 639 against the function name. Both <amatch> and 640 <afile> are set to the name of the function. 641 See |autoload-functions|. 642 *GUIEnter* 643GUIEnter After starting the GUI successfully, and after 644 opening the window. It is triggered before 645 VimEnter when using gvim. Can be used to 646 position the window from a .gvimrc file: > 647 :autocmd GUIEnter * winpos 100 50 648< *GUIFailed* 649GUIFailed After starting the GUI failed. Vim may 650 continue to run in the terminal, if possible 651 (only on Unix and alikes, when connecting the 652 X server fails). You may want to quit Vim: > 653 :autocmd GUIFailed * qall 654< *InsertChange* 655InsertChange When typing <Insert> while in Insert or 656 Replace mode. The |v:insertmode| variable 657 indicates the new mode. 658 Be careful not to move the cursor or do 659 anything else that the user does not expect. 660 *InsertEnter* 661InsertEnter Just before starting Insert mode. Also for 662 Replace mode and Virtual Replace mode. The 663 |v:insertmode| variable indicates the mode. 664 Be careful not to move the cursor or do 665 anything else that the user does not expect. 666 *InsertLeave* 667InsertLeave When leaving Insert mode. Also when using 668 CTRL-O |i_CTRL-O|. But not for |i_CTRL-C|. 669 *MenuPopup* 670MenuPopup Just before showing the popup menu (under the 671 right mouse button). Useful for adjusting the 672 menu for what is under the cursor or mouse 673 pointer. 674 The pattern is matched against a single 675 character representing the mode: 676 n Normal 677 v Visual 678 o Operator-pending 679 i Insert 680 c Command line 681 *QuickFixCmdPre* 682QuickFixCmdPre Before a quickfix command is run (|:make|, 683 |:lmake|, |:grep|, |:lgrep|, |:grepadd|, 684 |:lgrepadd|, |:vimgrep|, |:lvimgrep|, 685 |:vimgrepadd|, |:lvimgrepadd|, |:cscope|). 686 The pattern is matched against the command 687 being run. When |:grep| is used but 'grepprg' 688 is set to "internal" it still matches "grep". 689 This command cannot be used to set the 690 'makeprg' and 'grepprg' variables. 691 If this command causes an error, the quickfix 692 command is not executed. 693 *QuickFixCmdPost* 694QuickFixCmdPost Like QuickFixCmdPre, but after a quickfix 695 command is run, before jumping to the first 696 location. See |QuickFixCmdPost-example|. 697 *RemoteReply* 698RemoteReply When a reply from a Vim that functions as 699 server was received |server2client()|. The 700 pattern is matched against the {serverid}. 701 <amatch> is equal to the {serverid} from which 702 the reply was sent, and <afile> is the actual 703 reply string. 704 Note that even if an autocommand is defined, 705 the reply should be read with |remote_read()| 706 to consume it. 707 *SessionLoadPost* 708SessionLoadPost After loading the session file created using 709 the |:mksession| command. 710 *ShellCmdPost* 711ShellCmdPost After executing a shell command with |:!cmd|, 712 |:shell|, |:make| and |:grep|. Can be used to 713 check for any changed files. 714 *ShellFilterPost* 715ShellFilterPost After executing a shell command with 716 ":{range}!cmd", ":w !cmd" or ":r !cmd". 717 Can be used to check for any changed files. 718 *SourcePre* 719SourcePre Before sourcing a Vim script. |:source| 720 <afile> is the name of the file being sourced. 721 *SourceCmd* 722SourceCmd When sourcing a Vim script. |:source| 723 <afile> is the name of the file being sourced. 724 The autocommand must source this file. 725 |Cmd-event| 726 *SpellFileMissing* 727SpellFileMissing When trying to load a spell checking file and 728 it can't be found. The pattern is matched 729 against the language. <amatch> is the 730 language, 'encoding' also matters. See 731 |spell-SpellFileMissing|. 732 *StdinReadPost* 733StdinReadPost After reading from the stdin into the buffer, 734 before executing the modelines. Only used 735 when the "-" argument was used when Vim was 736 started |--|. 737 *StdinReadPre* 738StdinReadPre Before reading from stdin into the buffer. 739 Only used when the "-" argument was used when 740 Vim was started |--|. 741 *SwapExists* 742SwapExists Detected an existing swap file when starting 743 to edit a file. Only when it is possible to 744 select a way to handle the situation, when Vim 745 would ask the user what to do. 746 The |v:swapname| variable holds the name of 747 the swap file found, <afile> the file being 748 edited. |v:swapcommand| may contain a command 749 to be executed in the opened file. 750 The commands should set the |v:swapchoice| 751 variable to a string with one character to 752 tell Vim what should be done next: 753 'o' open read-only 754 'e' edit the file anyway 755 'r' recover 756 'd' delete the swap file 757 'q' quit, don't edit the file 758 'a' abort, like hitting CTRL-C 759 When set to an empty string the user will be 760 asked, as if there was no SwapExists autocmd. 761 *E812* 762 It is not allowed to change to another buffer, 763 change a buffer name or change directory 764 here. 765 *Syntax* 766Syntax When the 'syntax' option has been set. The 767 pattern is matched against the syntax name. 768 <afile> can be used for the name of the file 769 where this option was set, and <amatch> for 770 the new value of 'syntax'. 771 See |:syn-on|. 772 *TabEnter* 773TabEnter Just after entering a tab page. |tab-page| 774 After triggering the WinEnter and before 775 triggering the BufEnter event. 776 *TabLeave* 777TabLeave Just before leaving a tab page. |tab-page| 778 A WinLeave event will have been triggered 779 first. 780 *TermChanged* 781TermChanged After the value of 'term' has changed. Useful 782 for re-loading the syntax file to update the 783 colors, fonts and other terminal-dependent 784 settings. Executed for all loaded buffers. 785 *TermResponse* 786TermResponse After the response to |t_RV| is received from 787 the terminal. The value of |v:termresponse| 788 can be used to do things depending on the 789 terminal version. 790 *User* 791User Never executed automatically. To be used for 792 autocommands that are only executed with 793 ":doautocmd". 794 *UserGettingBored* 795UserGettingBored When the user hits CTRL-C. Just kidding! :-) 796 *VimEnter* 797VimEnter After doing all the startup stuff, including 798 loading .vimrc files, executing the "-c cmd" 799 arguments, creating all windows and loading 800 the buffers in them. 801 *VimLeave* 802VimLeave Before exiting Vim, just after writing the 803 .viminfo file. Executed only once, like 804 VimLeavePre. 805 To detect an abnormal exit use |v:dying|. 806 When v:dying is 2 or more this event is not 807 triggered. 808 *VimLeavePre* 809VimLeavePre Before exiting Vim, just before writing the 810 .viminfo file. This is executed only once, 811 if there is a match with the name of what 812 happens to be the current buffer when exiting. 813 Mostly useful with a "*" pattern. > 814 :autocmd VimLeavePre * call CleanupStuff() 815< To detect an abnormal exit use |v:dying|. 816 When v:dying is 2 or more this event is not 817 triggered. 818 *VimResized* 819VimResized After the Vim window was resized, thus 'lines' 820 and/or 'columns' changed. Not when starting 821 up though. 822 *WinEnter* 823WinEnter After entering another window. Not done for 824 the first window, when Vim has just started. 825 Useful for setting the window height. 826 If the window is for another buffer, Vim 827 executes the BufEnter autocommands after the 828 WinEnter autocommands. 829 Note: When using ":split fname" the WinEnter 830 event is triggered after the split but before 831 the file "fname" is loaded. 832 *WinLeave* 833WinLeave Before leaving a window. If the window to be 834 entered next is for a different buffer, Vim 835 executes the BufLeave autocommands before the 836 WinLeave autocommands (but not for ":new"). 837 Not used for ":qa" or ":q" when exiting Vim. 838 839============================================================================== 8406. Patterns *autocmd-patterns* *{pat}* 841 842The file pattern {pat} is tested for a match against the file name in one of 843two ways: 8441. When there is no '/' in the pattern, Vim checks for a match against only 845 the tail part of the file name (without its leading directory path). 8462. When there is a '/' in the pattern, Vim checks for a match against both the 847 short file name (as you typed it) and the full file name (after expanding 848 it to a full path and resolving symbolic links). 849 850The special pattern <buffer> or <buffer=N> is used for buffer-local 851autocommands |autocmd-buflocal|. This pattern is not matched against the name 852of a buffer. 853 854Examples: > 855 :autocmd BufRead *.txt set et 856Set the 'et' option for all text files. > 857 858 :autocmd BufRead /vim/src/*.c set cindent 859Set the 'cindent' option for C files in the /vim/src directory. > 860 861 :autocmd BufRead /tmp/*.c set ts=5 862If you have a link from "/tmp/test.c" to "/home/nobody/vim/src/test.c", and 863you start editing "/tmp/test.c", this autocommand will match. 864 865Note: To match part of a path, but not from the root directory, use a '*' as 866the first character. Example: > 867 :autocmd BufRead */doc/*.txt set tw=78 868This autocommand will for example be executed for "/tmp/doc/xx.txt" and 869"/usr/home/piet/doc/yy.txt". The number of directories does not matter here. 870 871 872The file name that the pattern is matched against is after expanding 873wildcards. Thus if you issue this command: > 874 :e $ROOTDIR/main.$EXT 875The argument is first expanded to: > 876 /usr/root/main.py 877Before it's matched with the pattern of the autocommand. Careful with this 878when using events like FileReadCmd, the value of <amatch> may not be what you 879expect. 880 881 882Environment variables can be used in a pattern: > 883 :autocmd BufRead $VIMRUNTIME/doc/*.txt set expandtab 884And ~ can be used for the home directory (if $HOME is defined): > 885 :autocmd BufWritePost ~/.vimrc so ~/.vimrc 886 :autocmd BufRead ~archive/* set readonly 887The environment variable is expanded when the autocommand is defined, not when 888the autocommand is executed. This is different from the command! 889 890 *file-pattern* 891The pattern is interpreted like mostly used in file names: 892 * matches any sequence of characters 893 ? matches any single character 894 \? matches a '?' 895 . matches a '.' 896 ~ matches a '~' 897 , separates patterns 898 \, matches a ',' 899 { } like \( \) in a |pattern| 900 , inside { }: like \| in a |pattern| 901 \ special meaning like in a |pattern| 902 [ch] matches 'c' or 'h' 903 [^ch] match any character but 'c' and 'h' 904 905Note that for all systems the '/' character is used for path separator (even 906MS-DOS and OS/2). This was done because the backslash is difficult to use 907in a pattern and to make the autocommands portable across different systems. 908 909 *autocmd-changes* 910Matching with the pattern is done when an event is triggered. Changing the 911buffer name in one of the autocommands, or even deleting the buffer, does not 912change which autocommands will be executed. Example: > 913 914 au BufEnter *.foo bdel 915 au BufEnter *.foo set modified 916 917This will delete the current buffer and then set 'modified' in what has become 918the current buffer instead. Vim doesn't take into account that "*.foo" 919doesn't match with that buffer name. It matches "*.foo" with the name of the 920buffer at the moment the event was triggered. 921 922However, buffer-local autocommands will not be executed for a buffer that has 923been wiped out with |:bwipe|. After deleting the buffer with |:bdel| the 924buffer actually still exists (it becomes unlisted), thus the autocommands are 925still executed. 926 927============================================================================== 9287. Buffer-local autocommands *autocmd-buflocal* *autocmd-buffer-local* 929 *<buffer=N>* *<buffer=abuf>* *E680* 930 931Buffer-local autocommands are attached to a specific buffer. They are useful 932if the buffer does not have a name and when the name does not match a specific 933pattern. But it also means they must be explicitly added to each buffer. 934 935Instead of a pattern buffer-local autocommands use one of these forms: 936 <buffer> current buffer 937 <buffer=99> buffer number 99 938 <buffer=abuf> using <abuf> (only when executing autocommands) 939 |<abuf>| 940 941Examples: > 942 :au CursorHold <buffer> echo 'hold' 943 :au CursorHold <buffer=33> echo 'hold' 944 :au CursorHold <buffer=abuf> echo 'hold' 945 946All the commands for autocommands also work with buffer-local autocommands, 947simply use the special string instead of the pattern. Examples: > 948 :au! * <buffer> " remove buffer-local autocommands for 949 " current buffer 950 :au! * <buffer=33> " remove buffer-local autocommands for 951 " buffer #33 952 :bufdo :au! CursorHold <buffer> " remove autocmd for given event for all 953 " buffers 954 :au * <buffer> " list buffer-local autocommands for 955 " current buffer 956 957Note that when an autocommand is defined for the current buffer, it is stored 958with the buffer number. Thus it uses the form "<buffer=12>", where 12 is the 959number of the current buffer. You will see this when listing autocommands, 960for example. 961 962To test for presence of buffer-local autocommands use the |exists()| function 963as follows: > 964 :if exists("#CursorHold#<buffer=12>") | ... | endif 965 :if exists("#CursorHold#<buffer>") | ... | endif " for current buffer 966 967When a buffer is wiped out its buffer-local autocommands are also gone, of 968course. Note that when deleting a buffer, e.g., with ":bdel", it is only 969unlisted, the autocommands are still present. In order to see the removal of 970buffer-local autocommands: > 971 :set verbose=6 972 973It is not possible to define buffer-local autocommands for a non-existent 974buffer. 975 976============================================================================== 9778. Groups *autocmd-groups* 978 979Autocommands can be put together in a group. This is useful for removing or 980executing a group of autocommands. For example, all the autocommands for 981syntax highlighting are put in the "highlight" group, to be able to execute 982":doautoall highlight BufRead" when the GUI starts. 983 984When no specific group is selected, Vim uses the default group. The default 985group does not have a name. You cannot execute the autocommands from the 986default group separately; you can execute them only by executing autocommands 987for all groups. 988 989Normally, when executing autocommands automatically, Vim uses the autocommands 990for all groups. The group only matters when executing autocommands with 991":doautocmd" or ":doautoall", or when defining or deleting autocommands. 992 993The group name can contain any characters except white space. The group name 994"end" is reserved (also in uppercase). 995 996The group name is case sensitive. Note that this is different from the event 997name! 998 999 *:aug* *:augroup* 1000:aug[roup] {name} Define the autocmd group name for the 1001 following ":autocmd" commands. The name "end" 1002 or "END" selects the default group. 1003 1004 *:augroup-delete* *E367* 1005:aug[roup]! {name} Delete the autocmd group {name}. Don't use 1006 this if there is still an autocommand using 1007 this group! This is not checked. 1008 1009To enter autocommands for a specific group, use this method: 10101. Select the group with ":augroup {name}". 10112. Delete any old autocommands with ":au!". 10123. Define the autocommands. 10134. Go back to the default group with "augroup END". 1014 1015Example: > 1016 :augroup uncompress 1017 : au! 1018 : au BufEnter *.gz %!gunzip 1019 :augroup END 1020 1021This prevents having the autocommands defined twice (e.g., after sourcing the 1022.vimrc file again). 1023 1024============================================================================== 10259. Executing autocommands *autocmd-execute* 1026 1027Vim can also execute Autocommands non-automatically. This is useful if you 1028have changed autocommands, or when Vim has executed the wrong autocommands 1029(e.g., the file pattern match was wrong). 1030 1031Note that the 'eventignore' option applies here too. Events listed in this 1032option will not cause any commands to be executed. 1033 1034 *:do* *:doau* *:doautocmd* *E217* 1035:do[autocmd] [group] {event} [fname] 1036 Apply the autocommands matching [fname] (default: 1037 current file name) for {event} to the current buffer. 1038 You can use this when the current file name does not 1039 match the right pattern, after changing settings, or 1040 to execute autocommands for a certain event. 1041 It's possible to use this inside an autocommand too, 1042 so you can base the autocommands for one extension on 1043 another extension. Example: > 1044 :au Bufenter *.cpp so ~/.vimrc_cpp 1045 :au Bufenter *.cpp doau BufEnter x.c 1046< Be careful to avoid endless loops. See 1047 |autocmd-nested|. 1048 1049 When the [group] argument is not given, Vim executes 1050 the autocommands for all groups. When the [group] 1051 argument is included, Vim executes only the matching 1052 autocommands for that group. Note: if you use an 1053 undefined group name, Vim gives you an error message. 1054 1055 After applying the autocommands the modelines are 1056 processed, so that their settings overrule the 1057 settings from autocommands, like what happens when 1058 editing a file. 1059 1060 *:doautoa* *:doautoall* 1061:doautoa[ll] [group] {event} [fname] 1062 Like ":doautocmd", but apply the autocommands to each 1063 loaded buffer. Note that [fname] is used to select 1064 the autocommands, not the buffers to which they are 1065 applied. 1066 Careful: Don't use this for autocommands that delete a 1067 buffer, change to another buffer or change the 1068 contents of a buffer; the result is unpredictable. 1069 This command is intended for autocommands that set 1070 options, change highlighting, and things like that. 1071 1072============================================================================== 107310. Using autocommands *autocmd-use* 1074 1075For WRITING FILES there are four possible sets of events. Vim uses only one 1076of these sets for a write command: 1077 1078BufWriteCmd BufWritePre BufWritePost writing the whole buffer 1079 FilterWritePre FilterWritePost writing to filter temp file 1080FileAppendCmd FileAppendPre FileAppendPost appending to a file 1081FileWriteCmd FileWritePre FileWritePost any other file write 1082 1083When there is a matching "*Cmd" autocommand, it is assumed it will do the 1084writing. No further writing is done and the other events are not triggered. 1085|Cmd-event| 1086 1087Note that the *WritePost commands should undo any changes to the buffer that 1088were caused by the *WritePre commands; otherwise, writing the file will have 1089the side effect of changing the buffer. 1090 1091Before executing the autocommands, the buffer from which the lines are to be 1092written temporarily becomes the current buffer. Unless the autocommands 1093change the current buffer or delete the previously current buffer, the 1094previously current buffer is made the current buffer again. 1095 1096The *WritePre and *AppendPre autocommands must not delete the buffer from 1097which the lines are to be written. 1098 1099The '[ and '] marks have a special position: 1100- Before the *ReadPre event the '[ mark is set to the line just above where 1101 the new lines will be inserted. 1102- Before the *ReadPost event the '[ mark is set to the first line that was 1103 just read, the '] mark to the last line. 1104- Before executing the *WriteCmd, *WritePre and *AppendPre autocommands the '[ 1105 mark is set to the first line that will be written, the '] mark to the last 1106 line. 1107Careful: '[ and '] change when using commands that change the buffer. 1108 1109In commands which expect a file name, you can use "<afile>" for the file name 1110that is being read |:<afile>| (you can also use "%" for the current file 1111name). "<abuf>" can be used for the buffer number of the currently effective 1112buffer. This also works for buffers that doesn't have a name. But it doesn't 1113work for files without a buffer (e.g., with ":r file"). 1114 1115 *gzip-example* 1116Examples for reading and writing compressed files: > 1117 :augroup gzip 1118 : autocmd! 1119 : autocmd BufReadPre,FileReadPre *.gz set bin 1120 : autocmd BufReadPost,FileReadPost *.gz '[,']!gunzip 1121 : autocmd BufReadPost,FileReadPost *.gz set nobin 1122 : autocmd BufReadPost,FileReadPost *.gz execute ":doautocmd BufReadPost " . expand("%:r") 1123 : autocmd BufWritePost,FileWritePost *.gz !mv <afile> <afile>:r 1124 : autocmd BufWritePost,FileWritePost *.gz !gzip <afile>:r 1125 1126 : autocmd FileAppendPre *.gz !gunzip <afile> 1127 : autocmd FileAppendPre *.gz !mv <afile>:r <afile> 1128 : autocmd FileAppendPost *.gz !mv <afile> <afile>:r 1129 : autocmd FileAppendPost *.gz !gzip <afile>:r 1130 :augroup END 1131 1132The "gzip" group is used to be able to delete any existing autocommands with 1133":autocmd!", for when the file is sourced twice. 1134 1135("<afile>:r" is the file name without the extension, see |:_%:|) 1136 1137The commands executed for the BufNewFile, BufRead/BufReadPost, BufWritePost, 1138FileAppendPost and VimLeave events do not set or reset the changed flag of the 1139buffer. When you decompress the buffer with the BufReadPost autocommands, you 1140can still exit with ":q". When you use ":undo" in BufWritePost to undo the 1141changes made by BufWritePre commands, you can still do ":q" (this also makes 1142"ZZ" work). If you do want the buffer to be marked as modified, set the 1143'modified' option. 1144 1145To execute Normal mode commands from an autocommand, use the ":normal" 1146command. Use with care! If the Normal mode command is not finished, the user 1147needs to type characters (e.g., after ":normal m" you need to type a mark 1148name). 1149 1150If you want the buffer to be unmodified after changing it, reset the 1151'modified' option. This makes it possible to exit the buffer with ":q" 1152instead of ":q!". 1153 1154 *autocmd-nested* *E218* 1155By default, autocommands do not nest. If you use ":e" or ":w" in an 1156autocommand, Vim does not execute the BufRead and BufWrite autocommands for 1157those commands. If you do want this, use the "nested" flag for those commands 1158in which you want nesting. For example: > 1159 :autocmd FileChangedShell *.c nested e! 1160The nesting is limited to 10 levels to get out of recursive loops. 1161 1162It's possible to use the ":au" command in an autocommand. This can be a 1163self-modifying command! This can be useful for an autocommand that should 1164execute only once. 1165 1166If you want to skip autocommands for one command, use the |:noautocmd| command 1167modifier or the 'eventignore' option. 1168 1169Note: When reading a file (with ":read file" or with a filter command) and the 1170last line in the file does not have an <EOL>, Vim remembers this. At the next 1171write (with ":write file" or with a filter command), if the same line is 1172written again as the last line in a file AND 'binary' is set, Vim does not 1173supply an <EOL>. This makes a filter command on the just read lines write the 1174same file as was read, and makes a write command on just filtered lines write 1175the same file as was read from the filter. For example, another way to write 1176a compressed file: > 1177 1178 :autocmd FileWritePre *.gz set bin|'[,']!gzip 1179 :autocmd FileWritePost *.gz undo|set nobin 1180< 1181 *autocommand-pattern* 1182You can specify multiple patterns, separated by commas. Here are some 1183examples: > 1184 1185 :autocmd BufRead * set tw=79 nocin ic infercase fo=2croq 1186 :autocmd BufRead .letter set tw=72 fo=2tcrq 1187 :autocmd BufEnter .letter set dict=/usr/lib/dict/words 1188 :autocmd BufLeave .letter set dict= 1189 :autocmd BufRead,BufNewFile *.c,*.h set tw=0 cin noic 1190 :autocmd BufEnter *.c,*.h abbr FOR for (i = 0; i < 3; ++i)<CR>{<CR>}<Esc>O 1191 :autocmd BufLeave *.c,*.h unabbr FOR 1192 1193For makefiles (makefile, Makefile, imakefile, makefile.unix, etc.): > 1194 1195 :autocmd BufEnter ?akefile* set include=^s\=include 1196 :autocmd BufLeave ?akefile* set include& 1197 1198To always start editing C files at the first function: > 1199 1200 :autocmd BufRead *.c,*.h 1;/^{ 1201 1202Without the "1;" above, the search would start from wherever the file was 1203entered, rather than from the start of the file. 1204 1205 *skeleton* *template* 1206To read a skeleton (template) file when opening a new file: > 1207 1208 :autocmd BufNewFile *.c 0r ~/vim/skeleton.c 1209 :autocmd BufNewFile *.h 0r ~/vim/skeleton.h 1210 :autocmd BufNewFile *.java 0r ~/vim/skeleton.java 1211 1212To insert the current date and time in a *.html file when writing it: > 1213 1214 :autocmd BufWritePre,FileWritePre *.html ks|call LastMod()|'s 1215 :fun LastMod() 1216 : if line("$") > 20 1217 : let l = 20 1218 : else 1219 : let l = line("$") 1220 : endif 1221 : exe "1," . l . "g/Last modified: /s/Last modified: .*/Last modified: " . 1222 : \ strftime("%Y %b %d") 1223 :endfun 1224 1225You need to have a line "Last modified: <date time>" in the first 20 lines 1226of the file for this to work. Vim replaces <date time> (and anything in the 1227same line after it) with the current date and time. Explanation: 1228 ks mark current position with mark 's' 1229 call LastMod() call the LastMod() function to do the work 1230 's return the cursor to the old position 1231The LastMod() function checks if the file is shorter than 20 lines, and then 1232uses the ":g" command to find lines that contain "Last modified: ". For those 1233lines the ":s" command is executed to replace the existing date with the 1234current one. The ":execute" command is used to be able to use an expression 1235for the ":g" and ":s" commands. The date is obtained with the strftime() 1236function. You can change its argument to get another date string. 1237 1238When entering :autocmd on the command-line, completion of events and command 1239names may be done (with <Tab>, CTRL-D, etc.) where appropriate. 1240 1241Vim executes all matching autocommands in the order that you specify them. 1242It is recommended that your first autocommand be used for all files by using 1243"*" as the file pattern. This means that you can define defaults you like 1244here for any settings, and if there is another matching autocommand it will 1245override these. But if there is no other matching autocommand, then at least 1246your default settings are recovered (if entering this file from another for 1247which autocommands did match). Note that "*" will also match files starting 1248with ".", unlike Unix shells. 1249 1250 *autocmd-searchpat* 1251Autocommands do not change the current search patterns. Vim saves the current 1252search patterns before executing autocommands then restores them after the 1253autocommands finish. This means that autocommands do not affect the strings 1254highlighted with the 'hlsearch' option. Within autocommands, you can still 1255use search patterns normally, e.g., with the "n" command. 1256If you want an autocommand to set the search pattern, such that it is used 1257after the autocommand finishes, use the ":let @/ =" command. 1258The search-highlighting cannot be switched off with ":nohlsearch" in an 1259autocommand. Use the 'h' flag in the 'viminfo' option to disable search- 1260highlighting when starting Vim. 1261 1262 *Cmd-event* 1263When using one of the "*Cmd" events, the matching autocommands are expected to 1264do the file reading, writing or sourcing. This can be used when working with 1265a special kind of file, for example on a remote system. 1266CAREFUL: If you use these events in a wrong way, it may have the effect of 1267making it impossible to read or write the matching files! Make sure you test 1268your autocommands properly. Best is to use a pattern that will never match a 1269normal file name, for example "ftp://*". 1270 1271When defining a BufReadCmd it will be difficult for Vim to recover a crashed 1272editing session. When recovering from the original file, Vim reads only those 1273parts of a file that are not found in the swap file. Since that is not 1274possible with a BufReadCmd, use the |:preserve| command to make sure the 1275original file isn't needed for recovery. You might want to do this only when 1276you expect the file to be modified. 1277 1278For file read and write commands the |v:cmdarg| variable holds the "++enc=" 1279and "++ff=" argument that are effective. These should be used for the command 1280that reads/writes the file. The |v:cmdbang| variable is one when "!" was 1281used, zero otherwise. 1282 1283See the $VIMRUNTIME/plugin/netrwPlugin.vim for examples. 1284 1285============================================================================== 128611. Disabling autocommands *autocmd-disable* 1287 1288To disable autocommands for some time use the 'eventignore' option. Note that 1289this may cause unexpected behavior, make sure you restore 'eventignore' 1290afterwards, using a |:try| block with |:finally|. 1291 1292 *:noautocmd* *:noa* 1293To disable autocommands for just one command use the ":noautocmd" command 1294modifier. This will set 'eventignore' to "all" for the duration of the 1295following command. Example: > 1296 1297 :noautocmd w fname.gz 1298 1299This will write the file without triggering the autocommands defined by the 1300gzip plugin. 1301 1302 1303 vim:tw=78:ts=8:ft=help:norl: 1304