*autocmd.txt* For Vim version 9.1. Last change: 2025 Jun 19 VIM REFERENCE MANUAL by Bram Moolenaar Automatic commands *autocommand* *autocommands* For a basic explanation, see section |40.3| in the user manual. 1. Introduction |autocmd-intro| 2. Defining autocommands |autocmd-define| 3. Removing autocommands |autocmd-remove| 4. Listing autocommands |autocmd-list| 5. Events |autocmd-events| 6. Patterns |autocmd-patterns| 7. Buffer-local autocommands |autocmd-buflocal| 8. Groups |autocmd-groups| 9. Executing autocommands |autocmd-execute| 10. Using autocommands |autocmd-use| 11. Disabling autocommands |autocmd-disable| ============================================================================== 1. Introduction *autocmd-intro* You can specify commands to be executed automatically when reading or writing a file, when entering or leaving a buffer or window, and when exiting Vim. For example, you can create an autocommand to set the 'cindent' option for files matching *.c. You can also use autocommands to implement advanced features, such as editing compressed files (see |gzip-example|). The usual place to put autocommands is in your .vimrc or .exrc file. *E203* *E204* *E143* *E855* *E937* *E952* WARNING: Using autocommands is very powerful, and may lead to unexpected side effects. Be careful not to destroy your text. - It's a good idea to 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 (this makes recovery possible in some rare cases). It's a good idea to use the same autocommands for the File* and Buf* events when possible. Recommended use: - Always use a group, so that it's easy to delete the autocommand. - Keep the command itself short, call a function to do more work. - Make it so that the script it is defined in can be sourced several times without the autocommand being repeated. Example in Vim9 script: > autocmd_add([{replace: true, group: 'DemoGroup', event: 'BufEnter', pattern: '*.txt', cmd: 'call DemoBufEnter()' }]) In legacy script: > call autocmd_add([#{replace: v:true, \ group: 'DemoGroup', \ event: 'BufEnter', \ pattern: '*.txt', \ cmd: 'call DemoBufEnter()' \ }]) ============================================================================== 2. Defining autocommands *autocmd-define* *:au* *:autocmd* :au[tocmd] [group] {event} {aupat} [++once] [++nested] {cmd} Add {cmd} to the list of commands that Vim will execute automatically on {event} for a file matching {aupat} |autocmd-patterns|. Here {event} cannot be "*". *E1155* Note: A quote character is seen as argument to the :autocmd and won't start a comment. Vim always adds the {cmd} after existing autocommands, so that the autocommands execute in the order in which they were given. See |autocmd-nested| for [++nested]. "nested" (without the ++) can also be used, for backwards compatibility, but not in |Vim9| script. *E1078* *autocmd-once* If [++once] is supplied the command is executed once, then removed ("one shot"). The special pattern or defines a buffer-local autocommand. See |autocmd-buflocal|. If the `:autocmd` is in Vim9 script (a script that starts with `:vim9script` and in a `:def` function) then {cmd} will be executed as in Vim9 script. Thus this depends on where the autocmd is defined, not where it is triggered. *:autocmd-block* {cmd} can be a block, like with `:command`, see |:command-repl|. Example: > au BufReadPost *.xml { setlocal matchpairs+=<:> / :augroup mine | au! BufRead | augroup END But this sees "augroup" as part of the defined command: > :augroup mine | au! BufRead * | augroup END :augroup mine | au BufRead * set tw=70 | augroup END Instead you can put the group name into the command: > :au! mine BufRead * :au mine BufRead * set tw=70 Or use `:execute`: > :augroup mine | exe "au! BufRead *" | augroup END :augroup mine | exe "au BufRead * set tw=70" | augroup END < *autocmd-expand* 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 BufNewFile,BufRead *.html so :h/html.vim Here Vim expands to the name of the file containing this line. However, works differently in a function, in which case it's better to use `:execute` with