*autocmd.txt* For Vim version 5.0j. Last modification: 1997 May 31 VIM REFERENCE MANUAL by Bram Moolenaar Automatic commands *autocommand* 1. Introduction |autocmd-intro| 2. Defining autocommands |autocmd-define| 3. Events |autocmd-events| 4. Patterns |autocmd-patterns| 5. Using autocommands |autocmd-use| ============================================================================== 1. Introduction *autocmd-intro* You can specify commands to be executed automatically for when reading or writing a file, when entering or leaving a buffer or window, and when exiting Vim. For example, 'cindent' can be set for files matching *.c, and unset otherwise. Autocommands can be used to edit compressed files. These commands are normally put in your .vimrc or .exrc file. {All this is not in Vi} WARNING: Using autocommands is very powerful, but may lead to unexpected side effects. Be careful not to destroy your text. - It's a good idea to first do some testing on an expendable copy of a file first. For example: If you use autocommands to decompress a file when starting to edit it, make sure that the autocommands for compressing when writing work correctly. - Be prepared for an error halfway through (e.g., disk full). Vim will mostly be able to undo the changes to the buffer, but you may have to clean up the changes to other files by hand (e.g., compress a file that has been decompressed). - If the BufRead* events allow you to edit a compressed file, the FileRead* events should do the same (to be able to do recovery in some rare cases). It's a good idea to use the same autocommands for the File* and Buf* events when possible. The autocommand feature is only included if Vim has been compiled with AUTOCMD defined. If the output of ":version" contains "+autocmd" it is included (this is the default), if it contains "-autocmd" then the autocommand feature doesn't work. ============================================================================== 2. Defining autocommands *autocmd-define* Note: This command cannot be followed by another command, since any '|' is considered part of the command. *:au* *:autocmd* :au[tocmd] {event} {pat} [nested] {cmd} Add {cmd} to the list of commands that will be automatically executed on {event} for a file matching {pat}. The {cmd} is always added after existing autocommands, so that the autocommands are executed in the order in which they were given. See |autocmd-nest| for [nested]. :au[tocmd] {event} {pat} Show the auto-commands associated with {event} and {pat}. :au[tocmd] * {pat} Show the auto-commands associated with {pat} for all events. :au[tocmd] {event} Show all auto-commands for {event}. :au[tocmd] Show all auto-commands. :au[tocmd]! {event} {pat} [nested] {cmd} Remove all auto-commands associated with {event} and {pat}, and add the command {cmd}. See |autocmd-nest| for [nested]. :au[tocmd]! {event} {pat} Remove all auto-commands associated with {event} and {pat}. :au[tocmd]! * {pat} Remove all auto-commands associated with {pat} for all events. :au[tocmd]! {event} Remove ALL auto-commands for {event}. :au[tocmd]! Remove ALL auto-commands. *:do* *:doautocmd* :do[autocmd] {event} [fname] Apply the autocommands matching [fname] (default: current file name) for {event} to the current buffer. This can be used when the current file name does not match the right pattern, after changing settings, or to execute autocommands for a certain event. It's possible to use this inside an autocommand too, so you can base the autocommands for one extension on another extension. Example: :au Bufenter *.cpp so ~/.vimrc_cpp :au Bufenter *.cpp doau BufEnter x.c Be careful for endless loops. See |autocmd-nest|. *:doautoa* *:doautoall* :doautoa[ll] {event} [fname] Like ":doautocmd", but execute it for each loaded buffer. Careful: Don't use this for autocommands that delete a buffer, change to another buffer or change the contents of a buffer, the result will be unpredictable. It is only meant to perform autocommands that set options, change highlighting, and things like that. Note that special characters (e.g., "%", "") in the ":autocmd" arguments are not expanded when the autocommand is defined. These will be expanded when the Event is recognized, and the {cmd} is executed. The only exception is that "" is expanded when the autocmd is defined. Example: :au BufEnter *.html so :h/html.vim Here is expanded to the file that contains this line. When your .vimrc file is sourced twice, the autocommands will appear twice. To avoid this, put this command in your .vimrc file, before defining autocommands: :autocmd! " Remove ALL auto-commands. ============================================================================== 3. Events *autocmd-events* *autocommand-events* *{event}* These events are recognized. Case is ignored, for example "BUFread" and "bufread" can be used instead of "BufRead". *BufNewFile* BufNewFile When starting to edit a file that doesn't exist. Can be used to read in a skeleton file. *BufReadPre* BufReadPre When starting to edit a new buffer, before reading the file into the buffer. Not used when the file doesn't exist. *BufRead* *BufReadPost* BufRead or BufReadPost When starting to edit a new buffer, after reading the file into the buffer, before executing the modelines. This does NOT work for ":r file". Not used when the file doesn't exist. *FileReadPre* FileReadPre Before reading a file with a ":read" command. *FileReadPost* FileReadPost After reading a file with a ":read" command. Note that the '[ and '] marks are set to the first and last line of the read, this can be used to operate on the just read lines. *FilterReadPre* FilterReadPre Before reading a file from a filter command. The file name of the current buffer is used to match with the pattern, not the name of the temporary file that is the output of the filter command. *FilterReadPost* FilterReadPost After reading a file from a filter command. Like FilterReadPre, the file name of the current buffer is used. *StdinReadPre* StdinReadPre Before reading from stdin into the buffer. Only used when the "-" argument was used when Vim was started |--|. *StdinReadPost* StdinReadPost After reading from the stdin into the buffer, before executing the modelines. Only used when the "-" argument was used when Vim was started |--|. *BufWrite* *BufWritePre* BufWrite or BufWritePre Before writing the whole buffer to a file. *BufWritePost* BufWritePost After writing the whole buffer to a file (should undo the commands for BufWritePre). *FileWritePre* FileWritePre Before writing to a file, when not writing the whole buffer. *FileWritePost* FileWritePost After writing to a file, when not writing the whole buffer. *FileAppendPre* FileAppendPre Before appending to a file. *FileAppendPost* FileAppendPost After appending to a file. *FilterWritePre* FilterWritePre Before writing a file for a filter command. The file name of the current buffer is used to match with the pattern, not the name of the temporary file that is the input for the filter command. *FilterWritePost* FilterWritePost After writing a file for a filter command. Like FilterWritePre, the file name of the current buffer is used. *FileChangedShell* FileChangedShell After a shell command is run, and vim notices that the modification time of the current file has changed since editing started. Run in place of the 'has been changed' message. See |timestamp|. Useful for reloading related buffers which are affected by a single command. *BufEnter* BufEnter After entering a buffer. Useful for setting options for a file type. Also executed when starting to edit a buffer, after the BufReadPost autocommands. *BufLeave* BufLeave Before leaving to another buffer. Also when leaving or closing the current window and the new current window is not for the same buffer. *WinEnter* WinEnter After entering another window. Not done for the first window, when Vim is just started. Useful for setting the window height. If the window is for another buffer, the BufEnter autocommands are executed after the WinEnter autocommands. *TermChanged* TermChanged After the value of 'term' was changed. Useful for re-loading the syntax file to update the colors, fonts and other terminal-dependent settings. Executed for all loaded buffers. *WinLeave* WinLeave Before leaving to another window. If the window to be entered is for a different buffer, the BufLeave autocommands are executed before the WinLeave autocommands. *VimLeave* VimLeave Before exiting Vim, just before writing the .viminfo file. There is no VimEnter event, because you can use the .vimrc for that. For READING FILES there are three possible pairs of events, only one pair is used at a time: BufNewFile starting to edit a non-existant file BufReadPre BufReadPost starting to edit an existing file FilterReadPre FilterReadPost read the temp file with filter output FileReadPre FileReadPost any other file read Note that the autocommands for the *ReadPre events and all the Filter events are not allowed to change the current buffer. You will get an error message if this happens anyway. This is to prevent the file to be read into the wrong buffer. ============================================================================== 4. Patterns *autocmd-patterns* Normally the file pattern is tested for a match against just the tail part of the file name (without its leading directory path), but if the path separator character '/' appears in the pattern, then it will be tested against the full file name. For example: :autocmd BufRead */vim/src/*.c set wrap Note that for all systems the '/' character is used for path separator, also on MS-DOS and OS/2. This was done because the backslash is difficult to use in a pattern, and to make the autocommands portable accross different systems. Note that using ~ in a file name (for home directory) doesn't work. Use a pattern that matches the full path name, for example "*home/user/.cshrc". ============================================================================== 5. Using autocommands *autocmd-use* Before the *ReadPre event the '[ mark is set to the line just above where the new lines will be inserted. Before the *ReadPost event the '[ mark is set to the first line that was just read, the '] mark to the last line. Careful: '[ and '] will change when using commands that change the buffer. "" can be used for the file name that is being read, in commands where a file name is expected (where you can also use "%" for the current file name) |:|. Examples for reading compressed files: :autocmd! BufReadPre,FileReadPre *.gz set bin :autocmd BufReadPost,FileReadPost *.gz '[,']!gunzip :autocmd BufReadPost,FileReadPost *.gz set nobin NOTE: When using the examples given, any existing autocommands for the same event/pattern combination will be removed, because of the '!'. For WRITING FILES there are four possible pairs of events, only one pair is used at a time: BufWritePre BufWritePost writing the whole buffer FilterWritePre FilterWritePost writing to the temp file with filter input FileAppendPre FileAppendPost appending to a file FileWritePre FileWritePost any other file write Note that the *WritePost commands should undo any changes to the buffer that were caused by the *WritePre commands, otherwise writing the file will have the side effect of changing the buffer. Before executing the autocommands, the buffer from where the lines are to be written is temporarily made the current buffer. Unless the autocommands change the current buffer, or delete the previously current buffer, the previously current buffer is made the current buffer again. The *WritePre and *AppendPre autocommands must not delete the buffer from where the lines are to be written. Before executing the *WritePre and *AppendPre autocommands the '[ mark is set to the first line that will be written, the '] mark to the last line. Careful: '[ and '] will change when using commands that change the buffer. "" can be used for the file name that is being written, in commands where a file name is expected (where you can also use "%" for the current file name) |:|. *gzip-example* Examples for writing compressed files: :autocmd! BufWritePost,FileWritePost *.gz !mv :r :autocmd BufWritePost,FileWritePost *.gz !gzip :r :autocmd! FileAppendPre *.gz !gunzip :autocmd FileAppendPre *.gz !mv :r :autocmd! FileAppendPost *.gz !mv :r :autocmd FileAppendPost *.gz !gzip :r (":r" is the file name without the extension, see |:_%:|) The commands executed for the BufNewFile, BufRead/BufReadPost, BufWritePost, FileAppendPost and VimLeave events do not set or reset the changed flag of the buffer. When you decompress the buffer with the BufReadPost autocommands, you can still exit with ":q". When you use ":undo" in BufWritePost to undo the changes made by BufWritePre commands, you can still do ":q" (this also makes "ZZ" work). To execute Normal mode commands from an autocommand, use the ":normal" command. Use with care! If the Normal mode command is not finished, the user needs to type characters (e.g., after ":normal m" you need to type a mark name). If you want the buffer not to be modified after changing it, reset the 'modified' option. This makes it possible to exit the buffer with ":q" instead of ":q!". *autocmd-nest* By default, autocommands do not nest. If you use ":e" or ":w" in an autocommand, the BufRead and BufWrite autocommands are not executed for those commands. If you do want this, the "nested" flag must be given for those commands where nesting is desired. For example: :autocmd FileChangedShell *.c nested e! The nesting is limited to 10 levels, to get out of recursive loops. It's not possible to use the ":au" command in an autocommand (that could be a self-modifying command!). There is currently no way to disable the autocommands. If you want to write a file without executing the autocommands for that type of file, write it under another name and rename it with a shell command. Note: When reading a file (with ":read file" or with a filter command) and the last line in the file does not have an end-of-line character, this is remembered. At the next write (with ":write file" or with a filter command), if the same line is written again as the last line in a file AND 'binary' is set, no end-of-line character is written. This makes a filter command on the just read lines write the same file as was read, and makes a write command on just filtered lines write the same file as was read from the filter. For example, another way to write a compressed file: :autocmd FileWritePre *.gz set bin|'[,']!gzip :autocmd FileWritePost *.gz undo|set nobin *autocommand-pattern* Multiple patterns may be given separated by commas. Here are some examples: :autocmd BufRead * set tw=79 nocin ic infercase fo=2croq :autocmd BufRead .letter set tw=72 fo=2tcrq :autocmd BufEnter .letter set dict=/usr/lib/dict/words :autocmd BufLeave .letter set dict= :autocmd BufRead,BufNewFile *.c,*.h set tw=0 cin noic :autocmd BufEnter *.c,*.h abbr FOR for(i = 0; i < 3; i++)^M{^M}^[O :autocmd BufLeave *.c,*.h unabbr FOR For makefiles (makefile, Makefile, imakefile, makefile.unix, etc.): :autocmd BufEnter ?akefile* set include=^s\=include :autocmd BufLeave ?akefile* set include& To always start editing C files at the first function: :autocmd BufRead *.c,*.h 1;/^{ Without the "1;" above, the search would start from wherever the file was entered, rather than from the start of the file. To read a skeleton file for new C files: :autocmd BufNewFile *.c 0r ~/.skeleton.c :autocmd BufNewFile *.h 0r ~/.skeleton.h To insert the current date and time in a *.html file when writing it: :autocmd BufWritePre,FileWritePre *.html ks|1,20g/Last modification: /normal f:lD:read !date^MkJ's (to insert the ^M type CTRL-V CTRL-M) You need to have a line "Last modification: " in the first 20 lines of the file for this to work. The (and anything in the same line after it) will be replaced with the current date and time. Explanation: ks mark current position with mark 's' 1,20g/pattern/ find lines that contain the pattern normal f: find the ':' lD delete the old date and time !date^M read the current date and time into the next line kJ Join the date and time with the previous line 's return the cursor to the old position When entering :autocmd on the command line, completion of events and command names may be done (with , CTRL-D, etc.) where appropriate. All matching auto-commands will be executed in the order that they were specified. It is recommended that your first auto-command be used for all files by using "*" as the file pattern. This means that you can define defaults you like here for any settings, and if there is another matching auto-command it will override these. But if there is no other matching auto-command, then at least your default settings are recovered (if entering this file from another for which auto-commands did match). Note that "*" will also match files starting with ".", unlike Unix shells. vim:tw=78:ts=8:sw=8: