blob: d11cb1f1851c02868c9949d3fcb8783fc9e5b2fb [file] [log] [blame]
zeertzjq476b65e2025-06-19 19:40:51 +02001*autocmd.txt* For Vim version 9.1. Last change: 2025 Jun 19
Bram Moolenaar071d4272004-06-13 20:20:40 +00002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
Bram Moolenaar675e8d62018-06-24 20:42:01 +02007Automatic commands *autocommand* *autocommands*
Bram Moolenaar071d4272004-06-13 20:20:40 +00008
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|
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +0000177. Buffer-local autocommands |autocmd-buflocal|
188. Groups |autocmd-groups|
199. Executing autocommands |autocmd-execute|
2010. Using autocommands |autocmd-use|
Bram Moolenaarb3480382005-12-11 21:33:32 +00002111. Disabling autocommands |autocmd-disable|
Bram Moolenaar071d4272004-06-13 20:20:40 +000022
Bram Moolenaar071d4272004-06-13 20:20:40 +000023
24==============================================================================
251. Introduction *autocmd-intro*
26
Bram Moolenaard4755bb2004-09-02 19:12:26 +000027You 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
Bram Moolenaar071d4272004-06-13 20:20:40 +000031features, such as editing compressed files (see |gzip-example|). The usual
32place to put autocommands is in your .vimrc or .exrc file.
33
Bram Moolenaar72540672018-02-09 22:00:53 +010034 *E203* *E204* *E143* *E855* *E937* *E952*
Bram Moolenaar071d4272004-06-13 20:20:40 +000035WARNING: 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
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +010050Recommended use:
51- Always use a group, so that it's easy to delete the autocommand.
52- Keep the command itself short, call a function to do more work.
Bram Moolenaarcfa8f9a2022-06-03 21:59:47 +010053- Make it so that the script it is defined in can be sourced several times
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +010054 without the autocommand being repeated.
55
56Example in Vim9 script: >
Boyang Du72985652024-07-09 18:46:12 +020057 autocmd_add([{replace: true,
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +010058 group: 'DemoGroup',
59 event: 'BufEnter',
60 pattern: '*.txt',
61 cmd: 'call DemoBufEnter()'
Boyang Du72985652024-07-09 18:46:12 +020062 }])
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +010063
64In legacy script: >
Boyang Du72985652024-07-09 18:46:12 +020065 call autocmd_add([#{replace: v:true,
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +010066 \ group: 'DemoGroup',
Bram Moolenaar938ae282023-02-20 20:44:55 +000067 \ event: 'BufEnter',
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +010068 \ pattern: '*.txt',
69 \ cmd: 'call DemoBufEnter()'
Boyang Du72985652024-07-09 18:46:12 +020070 \ }])
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +010071
Bram Moolenaar071d4272004-06-13 20:20:40 +000072==============================================================================
732. Defining autocommands *autocmd-define*
74
Bram Moolenaar071d4272004-06-13 20:20:40 +000075 *:au* *:autocmd*
Bram Moolenaarfd31be22022-01-16 14:46:06 +000076:au[tocmd] [group] {event} {aupat} [++once] [++nested] {cmd}
Bram Moolenaar071d4272004-06-13 20:20:40 +000077 Add {cmd} to the list of commands that Vim will
78 execute automatically on {event} for a file matching
Bram Moolenaarfd31be22022-01-16 14:46:06 +000079 {aupat} |autocmd-patterns|.
Bram Moolenaar85388672021-01-31 17:03:52 +010080 Here {event} cannot be "*". *E1155*
Bram Moolenaar98ef2332018-03-18 14:44:37 +010081 Note: A quote character is seen as argument to the
82 :autocmd and won't start a comment.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010083 Vim always adds the {cmd} after existing autocommands,
84 so that the autocommands execute in the order in which
Bram Moolenaareb93f3f2019-04-04 15:04:56 +020085 they were given.
86 See |autocmd-nested| for [++nested]. "nested"
87 (without the ++) can also be used, for backwards
Bram Moolenaar1588bc82022-03-08 21:35:07 +000088 compatibility, but not in |Vim9| script. *E1078*
Bram Moolenaareb93f3f2019-04-04 15:04:56 +020089 *autocmd-once*
90 If [++once] is supplied the command is executed once,
91 then removed ("one shot").
Bram Moolenaar071d4272004-06-13 20:20:40 +000092
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +000093The special pattern <buffer> or <buffer=N> defines a buffer-local autocommand.
94See |autocmd-buflocal|.
95
Bram Moolenaar1b884a02020-12-10 21:11:27 +010096If the `:autocmd` is in Vim9 script (a script that starts with `:vim9script`
97and in a `:def` function) then {cmd} will be executed as in Vim9
Bram Moolenaar4466ad62020-11-21 13:16:30 +010098script. Thus this depends on where the autocmd is defined, not where it is
99triggered.
Bram Moolenaarf1dcd142022-12-31 15:30:45 +0000100 *:autocmd-block*
Bram Moolenaar6aa57292021-08-14 21:25:52 +0200101{cmd} can be a block, like with `:command`, see |:command-repl|. Example: >
Bram Moolenaar73b8b0a2021-08-01 14:52:32 +0200102 au BufReadPost *.xml {
103 setlocal matchpairs+=<:>
104 /<start
105 }
106
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +0100107The |autocmd_add()| function can be used to add a list of autocmds and autocmd
Yegappan Lakshmanan971f6822022-05-24 11:40:11 +0100108groups from a Vim script. It is preferred if you have anything that would
109require using `:execute` with `:autocmd`.
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +0100110
Bram Moolenaare99e8442016-07-26 20:43:40 +0200111Note: The ":autocmd" command can only be followed by another command when the
Bram Moolenaar88a42052021-11-21 21:13:36 +0000112'|' appears where the pattern is expected. This works: >
Bram Moolenaare99e8442016-07-26 20:43:40 +0200113 :augroup mine | au! BufRead | augroup END
114But this sees "augroup" as part of the defined command: >
Bram Moolenaarb0d45e72017-11-05 18:19:24 +0100115 :augroup mine | au! BufRead * | augroup END
Bram Moolenaare99e8442016-07-26 20:43:40 +0200116 :augroup mine | au BufRead * set tw=70 | augroup END
Bram Moolenaarb0d45e72017-11-05 18:19:24 +0100117Instead you can put the group name into the command: >
118 :au! mine BufRead *
119 :au mine BufRead * set tw=70
120Or use `:execute`: >
121 :augroup mine | exe "au! BufRead *" | augroup END
122 :augroup mine | exe "au BufRead * set tw=70" | augroup END
Bram Moolenaare99e8442016-07-26 20:43:40 +0200123
Bram Moolenaar75ab5902022-04-18 15:36:40 +0100124< *autocmd-expand*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000125Note that special characters (e.g., "%", "<cword>") in the ":autocmd"
126arguments are not expanded when the autocommand is defined. These will be
127expanded when the Event is recognized, and the {cmd} is executed. The only
128exception is that "<sfile>" is expanded when the autocmd is defined. Example:
129>
130 :au BufNewFile,BufRead *.html so <sfile>:h/html.vim
131
132Here Vim expands <sfile> to the name of the file containing this line.
zeertzjq476b65e2025-06-19 19:40:51 +0200133However, <sfile> works differently in a function, in which case it's better to
134use `:execute` with <script> to achieve the same purpose:
135>
136 :exe $'au BufNewFile,BufRead *.html so {expand("<script>:h")}/html.vim'
Bram Moolenaar071d4272004-06-13 20:20:40 +0000137
Bram Moolenaar2ec618c2016-10-01 14:47:05 +0200138`:autocmd` adds to the list of autocommands regardless of whether they are
139already present. When your .vimrc file is sourced twice, the autocommands
140will appear twice. To avoid this, define your autocommands in a group, so
141that you can easily clear them: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000142
Bram Moolenaar2ec618c2016-10-01 14:47:05 +0200143 augroup vimrc
Bram Moolenaar98ef2332018-03-18 14:44:37 +0100144 " Remove all vimrc autocommands
145 autocmd!
Bram Moolenaar2ec618c2016-10-01 14:47:05 +0200146 au BufNewFile,BufRead *.html so <sfile>:h/html.vim
147 augroup END
Bram Moolenaar071d4272004-06-13 20:20:40 +0000148
149If you don't want to remove all autocommands, you can instead use a variable
150to ensure that Vim includes the autocommands only once: >
151
152 :if !exists("autocommands_loaded")
153 : let autocommands_loaded = 1
154 : au ...
155 :endif
156
157When the [group] argument is not given, Vim uses the current group (as defined
158with ":augroup"); otherwise, Vim uses the group defined with [group]. Note
159that [group] must have been defined before. You cannot define a new group
160with ":au group ..."; use ":augroup" for that.
161
162While testing autocommands, you might find the 'verbose' option to be useful: >
163 :set verbose=9
164This setting makes Vim echo the autocommands as it executes them.
165
166When defining an autocommand in a script, it will be able to call functions
167local to the script and use mappings local to the script. When the event is
168triggered and the command executed, it will run in the context of the script
169it was defined in. This matters if |<SID>| is used in a command.
170
Bram Moolenaar446cb832008-06-24 21:56:24 +0000171When executing the commands, the message from one command overwrites a
Bram Moolenaar071d4272004-06-13 20:20:40 +0000172previous message. This is different from when executing the commands
173manually. Mostly the screen will not scroll up, thus there is no hit-enter
174prompt. When one command outputs two messages this can happen anyway.
175
176==============================================================================
1773. Removing autocommands *autocmd-remove*
178
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +0100179In addition to the below described commands, the |autocmd_delete()| function can
180be used to remove a list of autocmds and autocmd groups from a Vim script.
181
Bram Moolenaarfd31be22022-01-16 14:46:06 +0000182:au[tocmd]! [group] {event} {aupat} [++once] [++nested] {cmd}
Bram Moolenaar071d4272004-06-13 20:20:40 +0000183 Remove all autocommands associated with {event} and
Bram Moolenaarfd31be22022-01-16 14:46:06 +0000184 {aupat}, and add the command {cmd}.
Bram Moolenaareb93f3f2019-04-04 15:04:56 +0200185 See |autocmd-once| for [++once].
186 See |autocmd-nested| for [++nested].
Bram Moolenaar071d4272004-06-13 20:20:40 +0000187
Bram Moolenaarfd31be22022-01-16 14:46:06 +0000188:au[tocmd]! [group] {event} {aupat}
Bram Moolenaar071d4272004-06-13 20:20:40 +0000189 Remove all autocommands associated with {event} and
Bram Moolenaarfd31be22022-01-16 14:46:06 +0000190 {aupat}.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000191
Bram Moolenaarfd31be22022-01-16 14:46:06 +0000192:au[tocmd]! [group] * {aupat}
193 Remove all autocommands associated with {aupat} for
194 all events.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000195
196:au[tocmd]! [group] {event}
197 Remove ALL autocommands for {event}.
Bram Moolenaar2ec618c2016-10-01 14:47:05 +0200198 Warning: You should not do this without a group for
199 |BufRead| and other common events, it can break
200 plugins, syntax highlighting, etc.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000201
202:au[tocmd]! [group] Remove ALL autocommands.
Bram Moolenaar98ef2332018-03-18 14:44:37 +0100203 Note: a quote will be seen as argument to the :autocmd
204 and won't start a comment.
Bram Moolenaar2ec618c2016-10-01 14:47:05 +0200205 Warning: You should normally not do this without a
206 group, it breaks plugins, syntax highlighting, etc.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000207
208When the [group] argument is not given, Vim uses the current group (as defined
209with ":augroup"); otherwise, Vim uses the group defined with [group].
210
211==============================================================================
2124. Listing autocommands *autocmd-list*
213
Bram Moolenaarfd31be22022-01-16 14:46:06 +0000214:au[tocmd] [group] {event} {aupat}
Bram Moolenaar071d4272004-06-13 20:20:40 +0000215 Show the autocommands associated with {event} and
Bram Moolenaarfd31be22022-01-16 14:46:06 +0000216 {aupat}.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000217
Bram Moolenaarfd31be22022-01-16 14:46:06 +0000218:au[tocmd] [group] * {aupat}
219 Show the autocommands associated with {aupat} for all
Bram Moolenaar071d4272004-06-13 20:20:40 +0000220 events.
221
222:au[tocmd] [group] {event}
223 Show all autocommands for {event}.
224
225:au[tocmd] [group] Show all autocommands.
226
227If you provide the [group] argument, Vim lists only the autocommands for
228[group]; otherwise, Vim lists the autocommands for ALL groups. Note that this
229argument behavior differs from that for defining and removing autocommands.
230
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +0000231In order to list buffer-local autocommands, use a pattern in the form <buffer>
232or <buffer=N>. See |autocmd-buflocal|.
233
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +0100234The |autocmd_get()| function can be used from a Vim script to get a list of
235autocmds.
236
Bram Moolenaarac6e65f2005-08-29 22:25:38 +0000237 *:autocmd-verbose*
238When 'verbose' is non-zero, listing an autocommand will also display where it
239was last defined. Example: >
240
241 :verbose autocmd BufEnter
242 FileExplorer BufEnter
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000243 * call s:LocalBrowse(expand("<amatch>"))
Bram Moolenaarac6e65f2005-08-29 22:25:38 +0000244 Last set from /usr/share/vim/vim-7.0/plugin/NetrwPlugin.vim
245<
246See |:verbose-cmd| for more information.
247
Bram Moolenaar071d4272004-06-13 20:20:40 +0000248==============================================================================
2495. Events *autocmd-events* *E215* *E216*
250
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000251You can specify a comma-separated list of event names. No white space can be
252used in this list. The command applies to all the events in the list.
253
254For READING FILES there are four kinds of events possible:
255 BufNewFile starting to edit a non-existent file
256 BufReadPre BufReadPost starting to edit an existing file
257 FilterReadPre FilterReadPost read the temp file with filter output
258 FileReadPre FileReadPost any other file read
259Vim uses only one of these four kinds when reading a file. The "Pre" and
260"Post" events are both triggered, before and after reading the file.
261
262Note that the autocommands for the *ReadPre events and all the Filter events
263are not allowed to change the current buffer (you will get an error message if
264this happens). This is to prevent the file to be read into the wrong buffer.
265
266Note that the 'modified' flag is reset AFTER executing the BufReadPost
267and BufNewFile autocommands. But when the 'modified' option was set by the
268autocommands, this doesn't happen.
269
270You can use the 'eventignore' option to ignore a number of events or all
271events.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000272 *autocommand-events* *{event}*
273Vim recognizes the following events. Vim ignores the case of event names
274(e.g., you can use "BUFread" or "bufread" instead of "BufRead").
275
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000276First an overview by function with a short explanation. Then the list
Bram Moolenaar551dbcc2006-04-25 22:13:59 +0000277alphabetically with full explanations |autocmd-events-abc|.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000278
279Name triggered by ~
280
281 Reading
282|BufNewFile| starting to edit a file that doesn't exist
283|BufReadPre| starting to edit a new buffer, before reading the file
284|BufRead| starting to edit a new buffer, after reading the file
285|BufReadPost| starting to edit a new buffer, after reading the file
286|BufReadCmd| before starting to edit a new buffer |Cmd-event|
287
288|FileReadPre| before reading a file with a ":read" command
289|FileReadPost| after reading a file with a ":read" command
Bram Moolenaar551dbcc2006-04-25 22:13:59 +0000290|FileReadCmd| before reading a file with a ":read" command |Cmd-event|
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000291
292|FilterReadPre| before reading a file from a filter command
293|FilterReadPost| after reading a file from a filter command
294
295|StdinReadPre| before reading from stdin into the buffer
296|StdinReadPost| After reading from the stdin into the buffer
297
298 Writing
299|BufWrite| starting to write the whole buffer to a file
300|BufWritePre| starting to write the whole buffer to a file
301|BufWritePost| after writing the whole buffer to a file
302|BufWriteCmd| before writing the whole buffer to a file |Cmd-event|
303
304|FileWritePre| starting to write part of a buffer to a file
305|FileWritePost| after writing part of a buffer to a file
306|FileWriteCmd| before writing part of a buffer to a file |Cmd-event|
307
308|FileAppendPre| starting to append to a file
309|FileAppendPost| after appending to a file
310|FileAppendCmd| before appending to a file |Cmd-event|
311
312|FilterWritePre| starting to write a file for a filter command or diff
313|FilterWritePost| after writing a file for a filter command or diff
314
315 Buffers
316|BufAdd| just after adding a buffer to the buffer list
317|BufCreate| just after adding a buffer to the buffer list
318|BufDelete| before deleting a buffer from the buffer list
319|BufWipeout| before completely deleting a buffer
320
321|BufFilePre| before changing the name of the current buffer
322|BufFilePost| after changing the name of the current buffer
323
324|BufEnter| after entering a buffer
325|BufLeave| before leaving to another buffer
326|BufWinEnter| after a buffer is displayed in a window
327|BufWinLeave| before a buffer is removed from a window
328
329|BufUnload| before unloading a buffer
Bram Moolenaarcb80aa22020-10-26 21:12:46 +0100330|BufHidden| just before a buffer becomes hidden
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000331|BufNew| just after creating a new buffer
332
333|SwapExists| detected an existing swap file
334
335 Options
336|FileType| when the 'filetype' option has been set
337|Syntax| when the 'syntax' option has been set
338|EncodingChanged| after the 'encoding' option has been changed
339|TermChanged| after the value of 'term' has changed
Bram Moolenaar53744302015-07-17 17:38:22 +0200340|OptionSet| after setting any option
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000341
342 Startup and exit
343|VimEnter| after doing all the startup stuff
344|GUIEnter| after starting the GUI successfully
Bram Moolenaard09acef2012-09-21 14:54:30 +0200345|GUIFailed| after starting the GUI failed
Bram Moolenaard7afed32007-05-06 13:26:41 +0000346|TermResponse| after the terminal response to |t_RV| is received
Danek Duvalld7d56032024-01-14 20:19:59 +0100347|TermResponseAll| after the terminal response to |t_RV| and others is received
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000348
Bram Moolenaar12a96de2018-03-11 14:44:18 +0100349|QuitPre| when using `:quit`, before deciding whether to exit
350|ExitPre| when using a command that may make Vim exit
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000351|VimLeavePre| before exiting Vim, before writing the viminfo file
352|VimLeave| before exiting Vim, after writing the viminfo file
353
Bram Moolenaar100118c2020-12-11 19:30:34 +0100354|VimSuspend| when suspending Vim
355|VimResume| when Vim is resumed after being suspended
356
Bram Moolenaar28ed4df2019-10-26 16:21:40 +0200357 Terminal
358|TerminalOpen| after a terminal buffer was created
359|TerminalWinOpen| after a terminal buffer was created in a new window
360
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000361 Various
362|FileChangedShell| Vim notices that a file changed since editing started
Bram Moolenaar7d47b6e2006-03-15 22:59:18 +0000363|FileChangedShellPost| After handling a file changed since editing started
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000364|FileChangedRO| before making the first change to a read-only file
365
Bram Moolenaar2c64ca12018-10-19 16:22:31 +0200366|DiffUpdated| after diffs have been updated
Bram Moolenaar28e8f732022-02-09 12:58:20 +0000367|DirChangedPre| before the working directory will change
Bram Moolenaarb7407d32018-02-03 17:36:27 +0100368|DirChanged| after the working directory has changed
369
Bram Moolenaara94bc432006-03-10 21:42:59 +0000370|ShellCmdPost| after executing a shell command
371|ShellFilterPost| after filtering with a shell command
372
Bram Moolenaard5005162014-08-22 23:05:54 +0200373|CmdUndefined| a user command is used but it isn't defined
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000374|FuncUndefined| a user function is used but it isn't defined
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +0000375|SpellFileMissing| a spell file is used but it can't be found
Bram Moolenaar1f35bf92006-03-07 22:38:47 +0000376|SourcePre| before sourcing a Vim script
Bram Moolenaar2a953fc2019-01-26 17:41:47 +0100377|SourcePost| after sourcing a Vim script
Bram Moolenaar8dd1aa52007-01-16 20:33:19 +0000378|SourceCmd| before sourcing a Vim script |Cmd-event|
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000379
Bram Moolenaar7d47b6e2006-03-15 22:59:18 +0000380|VimResized| after the Vim window size changed
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000381|FocusGained| Vim got input focus
382|FocusLost| Vim lost input focus
383|CursorHold| the user doesn't press a key for a while
Bram Moolenaar754b5602006-02-09 23:53:20 +0000384|CursorHoldI| the user doesn't press a key for a while in Insert mode
385|CursorMoved| the cursor was moved in Normal mode
Shougo Matsushitad0952142024-06-20 22:05:16 +0200386|CursorMovedC| the cursor was moved in the |Command-line|
Bram Moolenaar754b5602006-02-09 23:53:20 +0000387|CursorMovedI| the cursor was moved in Insert mode
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000388
Sergey Vlasov1f47db72024-01-25 23:07:00 +0100389|WinNewPre| before creating a new window
Bram Moolenaarc917da42016-07-19 22:31:36 +0200390|WinNew| after creating a new window
Bram Moolenaar12c11d52016-07-19 23:13:03 +0200391|TabNew| after creating a new tab page
naohiro ono23beefe2021-11-13 12:38:49 +0000392|WinClosed| after closing a window
Bram Moolenaar12c11d52016-07-19 23:13:03 +0200393|TabClosed| after closing a tab page
Jim Zhou5606ca52025-03-13 21:58:25 +0100394|TabClosedPre| before closing a tab page
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000395|WinEnter| after entering another window
396|WinLeave| before leaving a window
Bram Moolenaarfaa959a2006-02-20 21:37:40 +0000397|TabEnter| after entering another tab page
398|TabLeave| before leaving a tab page
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000399|CmdwinEnter| after entering the command-line window
400|CmdwinLeave| before leaving the command-line window
401
Bram Moolenaarb5b75622018-03-09 22:22:21 +0100402|CmdlineChanged| after a change was made to the command-line text
403|CmdlineEnter| after the cursor moves to the command line
404|CmdlineLeave| before the cursor leaves the command line
Girish Palya92f68e22025-04-21 11:12:41 +0200405|CmdlineLeavePre| before preparing to leave the command line
Bram Moolenaarb5b75622018-03-09 22:22:21 +0100406
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000407|InsertEnter| starting Insert mode
408|InsertChange| when typing <Insert> while in Insert or Replace mode
409|InsertLeave| when leaving Insert mode
Bram Moolenaar938ae282023-02-20 20:44:55 +0000410|InsertLeavePre| just before leaving Insert mode
Bram Moolenaare659c952011-05-19 17:25:41 +0200411|InsertCharPre| when a character was typed in Insert mode, before
412 inserting it
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000413
=?UTF-8?q?Magnus=20Gro=C3=9F?=f1e88762021-09-12 13:39:55 +0200414|ModeChanged| after changing the mode
415
Bram Moolenaardfb18412013-12-11 18:53:29 +0100416|TextChanged| after a change was made to the text in Normal mode
417|TextChangedI| after a change was made to the text in Insert mode
Bram Moolenaar5a093432018-02-10 18:15:19 +0100418 when popup menu is not visible
419|TextChangedP| after a change was made to the text in Insert mode
420 when popup menu visible
Shougo Matsushita4ccaedf2022-10-15 11:48:00 +0100421|TextChangedT| after a change was made to the text in Terminal mode
Bram Moolenaarb477af22018-07-15 20:20:18 +0200422|TextYankPost| after text has been yanked or deleted
Bram Moolenaardfb18412013-12-11 18:53:29 +0100423
Bram Moolenaar8aeec402019-09-15 23:02:04 +0200424|SafeState| nothing pending, going to wait for the user to type a
425 character
Bram Moolenaar69198cb2019-09-16 21:58:13 +0200426|SafeStateAgain| repeated SafeState
Bram Moolenaar8aeec402019-09-15 23:02:04 +0200427
Bram Moolenaar15142e22018-04-30 22:19:58 +0200428|ColorSchemePre| before loading a color scheme
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000429|ColorScheme| after loading a color scheme
430
431|RemoteReply| a reply from a server Vim was received
432
433|QuickFixCmdPre| before a quickfix command is run
434|QuickFixCmdPost| after a quickfix command is run
435
436|SessionLoadPost| after loading a session file
437
h-east53753f62024-05-05 18:42:31 +0200438|SessionWritePost| after writing the session file using
439 the |:mksession| command
Colin Kennedye5f22802024-03-26 18:20:16 +0100440
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000441|MenuPopup| just before showing the popup menu
Bram Moolenaard7f246c2019-04-08 18:15:41 +0200442|CompleteChanged| after Insert mode completion menu changed
Bram Moolenaar3f169ce2020-01-26 22:43:31 +0100443|CompleteDonePre| after Insert mode completion is done, before clearing
444 info
445|CompleteDone| after Insert mode completion is done, after clearing
446 info
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000447
Shougo Matsushita83678842024-07-11 22:05:12 +0200448|KeyInputPre| just before a key is processed
449
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000450|User| to be used in combination with ":doautocmd"
Bram Moolenaarbe5ee862020-06-10 20:56:58 +0200451|SigUSR1| after the SIGUSR1 signal has been detected
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000452
LemonBoy09371822022-04-08 15:18:45 +0100453|WinScrolled| after scrolling or resizing a window
454
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000455
456The alphabetical list of autocommand events: *autocmd-events-abc*
457
458 *BufCreate* *BufAdd*
459BufAdd or BufCreate Just after creating a new buffer which is
460 added to the buffer list, or adding a buffer
461 to the buffer list.
462 Also used just after a buffer in the buffer
463 list has been renamed.
Bram Moolenaar469bdbd2019-12-11 23:05:48 +0100464 Not triggered for the initial buffers created
465 during startup.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000466 The BufCreate event is for historic reasons.
467 NOTE: When this autocommand is executed, the
468 current buffer "%" may be different from the
469 buffer being created "<afile>".
470 *BufDelete*
471BufDelete Before deleting a buffer from the buffer list.
472 The BufUnload may be called first (if the
473 buffer was loaded).
474 Also used just before a buffer in the buffer
475 list is renamed.
476 NOTE: When this autocommand is executed, the
477 current buffer "%" may be different from the
Bram Moolenaar446cb832008-06-24 21:56:24 +0000478 buffer being deleted "<afile>" and "<abuf>".
Bram Moolenaarb849e712009-06-24 15:51:37 +0000479 Don't change to another buffer, it will cause
480 problems.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000481 *BufEnter*
482BufEnter After entering a buffer. Useful for setting
483 options for a file type. Also executed when
484 starting to edit a buffer, after the
485 BufReadPost autocommands.
486 *BufFilePost*
487BufFilePost After changing the name of the current buffer
488 with the ":file" or ":saveas" command.
Bram Moolenaar4770d092006-01-12 23:22:24 +0000489 *BufFilePre*
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000490BufFilePre Before changing the name of the current buffer
491 with the ":file" or ":saveas" command.
492 *BufHidden*
Bram Moolenaar790c18b2019-07-04 17:22:06 +0200493BufHidden Just before a buffer becomes hidden. That is,
494 when there are no longer windows that show
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000495 the buffer, but the buffer is not unloaded or
496 deleted. Not used for ":qa" or ":q" when
497 exiting Vim.
498 NOTE: When this autocommand is executed, the
499 current buffer "%" may be different from the
500 buffer being unloaded "<afile>".
501 *BufLeave*
502BufLeave Before leaving to another buffer. Also when
503 leaving or closing the current window and the
504 new current window is not for the same buffer.
505 Not used for ":qa" or ":q" when exiting Vim.
506 *BufNew*
507BufNew Just after creating a new buffer. Also used
508 just after a buffer has been renamed. When
509 the buffer is added to the buffer list BufAdd
510 will be triggered too.
511 NOTE: When this autocommand is executed, the
512 current buffer "%" may be different from the
513 buffer being created "<afile>".
Bram Moolenaar071d4272004-06-13 20:20:40 +0000514 *BufNewFile*
515BufNewFile When starting to edit a file that doesn't
516 exist. Can be used to read in a skeleton
517 file.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000518 *BufRead* *BufReadPost*
519BufRead or BufReadPost When starting to edit a new buffer, after
520 reading the file into the buffer, before
521 executing the modelines. See |BufWinEnter|
522 for when you need to do something after
523 processing the modelines.
Bram Moolenaar75ab5902022-04-18 15:36:40 +0100524 Also triggered:
525 - when writing an unnamed buffer in a way that
526 the buffer gets a name
527 - after successfully recovering a file
528 - for the filetypedetect group when executing
529 ":filetype detect"
530 Not triggered:
531 - for the `:read file` command
532 - when the file doesn't exist
Bram Moolenaar4770d092006-01-12 23:22:24 +0000533 *BufReadCmd*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000534BufReadCmd Before starting to edit a new buffer. Should
535 read the file into the buffer. |Cmd-event|
Bram Moolenaar4770d092006-01-12 23:22:24 +0000536 *BufReadPre* *E200* *E201*
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000537BufReadPre When starting to edit a new buffer, before
538 reading the file into the buffer. Not used
539 if the file doesn't exist.
540 *BufUnload*
541BufUnload Before unloading a buffer. This is when the
542 text in the buffer is going to be freed. This
543 may be after a BufWritePost and before a
544 BufDelete. Also used for all buffers that are
545 loaded when Vim is going to exit.
546 NOTE: When this autocommand is executed, the
547 current buffer "%" may be different from the
548 buffer being unloaded "<afile>".
Bram Moolenaar64d8e252016-09-06 22:12:34 +0200549 Don't change to another buffer or window, it
550 will cause problems!
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +0200551 When exiting and v:dying is 2 or more this
552 event is not triggered.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000553 *BufWinEnter*
554BufWinEnter After a buffer is displayed in a window. This
555 can be when the buffer is loaded (after
Bram Moolenaar446cb832008-06-24 21:56:24 +0000556 processing the modelines) or when a hidden
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000557 buffer is displayed in a window (and is no
Bram Moolenaar446cb832008-06-24 21:56:24 +0000558 longer hidden).
559 Does not happen for |:split| without
560 arguments, since you keep editing the same
561 buffer, or ":split" with a file that's already
Bram Moolenaarc236c162008-07-13 17:41:49 +0000562 open in a window, because it re-uses an
563 existing buffer. But it does happen for a
564 ":split" with the name of the current buffer,
565 since it reloads that buffer.
Bram Moolenaar606cb8b2018-05-03 20:40:20 +0200566 Does not happen for a terminal window, because
567 it starts in Terminal-Job mode and Normal mode
568 commands won't work. Use |TerminalOpen| instead.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000569 *BufWinLeave*
570BufWinLeave Before a buffer is removed from a window.
571 Not when it's still visible in another window.
572 Also triggered when exiting. It's triggered
573 before BufUnload or BufHidden.
574 NOTE: When this autocommand is executed, the
575 current buffer "%" may be different from the
576 buffer being unloaded "<afile>".
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +0200577 When exiting and v:dying is 2 or more this
578 event is not triggered.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000579 *BufWipeout*
580BufWipeout Before completely deleting a buffer. The
581 BufUnload and BufDelete events may be called
582 first (if the buffer was loaded and was in the
583 buffer list). Also used just before a buffer
584 is renamed (also when it's not in the buffer
585 list).
586 NOTE: When this autocommand is executed, the
587 current buffer "%" may be different from the
588 buffer being deleted "<afile>".
Bram Moolenaarb849e712009-06-24 15:51:37 +0000589 Don't change to another buffer, it will cause
590 problems.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000591 *BufWrite* *BufWritePre*
592BufWrite or BufWritePre Before writing the whole buffer to a file.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000593 *BufWriteCmd*
594BufWriteCmd Before writing the whole buffer to a file.
595 Should do the writing of the file and reset
Bram Moolenaar1cd871b2004-12-19 22:46:22 +0000596 'modified' if successful, unless '+' is in
597 'cpo' and writing to another file |cpo-+|.
598 The buffer contents should not be changed.
Bram Moolenaar5302d9e2011-09-14 17:55:08 +0200599 When the command resets 'modified' the undo
600 information is adjusted to mark older undo
Christian Brabandtdf684192025-04-03 12:33:02 +0200601 states as 'modified', like |:write| does. Use
602 the |'[| and |']| marks for the range of lines.
Bram Moolenaar1cd871b2004-12-19 22:46:22 +0000603 |Cmd-event|
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000604 *BufWritePost*
605BufWritePost After writing the whole buffer to a file
606 (should undo the commands for BufWritePre).
Bram Moolenaard5005162014-08-22 23:05:54 +0200607 *CmdUndefined*
608CmdUndefined When a user command is used but it isn't
609 defined. Useful for defining a command only
610 when it's used. The pattern is matched
611 against the command name. Both <amatch> and
612 <afile> are set to the name of the command.
zeertzjqaf056942025-03-08 16:45:20 +0100613 This is triggered even when inside an
614 autocommand defined without |autocmd-nested|.
Bram Moolenaard5005162014-08-22 23:05:54 +0200615 NOTE: Autocompletion won't work until the
616 command is defined. An alternative is to
617 always define the user command and have it
618 invoke an autoloaded function. See |autoload|.
Bram Moolenaar153b7042018-01-31 15:48:32 +0100619 *CmdlineChanged*
Bram Moolenaarb5b75622018-03-09 22:22:21 +0100620CmdlineChanged After a change was made to the text in the
621 command line. Be careful not to mess up
622 the command line, it may cause Vim to lock up.
Bram Moolenaar153b7042018-01-31 15:48:32 +0100623 <afile> is set to a single character,
624 indicating the type of command-line.
625 |cmdwin-char|
Bram Moolenaarfafcf0d2017-10-19 18:35:51 +0200626 *CmdlineEnter*
627CmdlineEnter After moving the cursor to the command line,
628 where the user can type a command or search
Bram Moolenaar957cf672020-11-12 14:21:06 +0100629 string; including non-interactive use of ":"
630 in a mapping, but not when using |<Cmd>|.
Bram Moolenaar938ae282023-02-20 20:44:55 +0000631 The pattern is matched against the character
632 representing the type of command-line.
633 |cmdwin-char|
Bram Moolenaarfafcf0d2017-10-19 18:35:51 +0200634 <afile> is set to a single character,
635 indicating the type of command-line.
Bram Moolenaarfafcf0d2017-10-19 18:35:51 +0200636 *CmdlineLeave*
Bram Moolenaar957cf672020-11-12 14:21:06 +0100637CmdlineLeave Before leaving the command line; including
638 non-interactive use of ":" in a mapping, but
639 not when using |<Cmd>|.
Bram Moolenaar01164a62017-11-02 22:58:42 +0100640 Also when abandoning the command line, after
641 typing CTRL-C or <Esc>.
642 When the commands result in an error the
643 command line is still executed.
Bram Moolenaarfafcf0d2017-10-19 18:35:51 +0200644 <afile> is set to a single character,
645 indicating the type of command-line.
646 |cmdwin-char|
Girish Palya92f68e22025-04-21 11:12:41 +0200647 *CmdlineLeavePre*
648CmdlineLeavePre Just before leaving the command line, and
649 before |CmdlineLeave|. Useful for capturing
650 completion info with |cmdcomplete_info()|, as
651 this information is cleared before
652 |CmdlineLeave| is triggered. Triggered for
653 non-interactive use of ":" in a mapping, but
654 not when using |<Cmd>|. Also triggered when
655 abandoning the command line by typing CTRL-C
656 or <Esc>. <afile> is set to a single
657 character indicating the command-line type.
658 See |cmdwin-char| for details.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000659 *CmdwinEnter*
660CmdwinEnter After entering the command-line window.
661 Useful for setting options specifically for
Bram Moolenaar96e38a82019-09-09 18:35:33 +0200662 this special type of window.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000663 <afile> is set to a single character,
664 indicating the type of command-line.
665 |cmdwin-char|
666 *CmdwinLeave*
667CmdwinLeave Before leaving the command-line window.
668 Useful to clean up any global setting done
Bram Moolenaar96e38a82019-09-09 18:35:33 +0200669 with CmdwinEnter.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000670 <afile> is set to a single character,
671 indicating the type of command-line.
672 |cmdwin-char|
673 *ColorScheme*
674ColorScheme After loading a color scheme. |:colorscheme|
Bram Moolenaar0daafaa2022-09-04 17:45:43 +0100675 Not triggered if the color scheme is not
676 found.
Bram Moolenaarb95186f2013-11-28 18:53:52 +0100677 The pattern is matched against the
678 colorscheme name. <afile> can be used for the
679 name of the actual file where this option was
680 set, and <amatch> for the new colorscheme
681 name.
682
Bram Moolenaar15142e22018-04-30 22:19:58 +0200683 *ColorSchemePre*
684ColorSchemePre Before loading a color scheme. |:colorscheme|
685 Useful to setup removing things added by a
686 color scheme, before another one is loaded.
Bram Moolenaar589edb32019-09-20 14:38:13 +0200687CompleteChanged *CompleteChanged*
Bram Moolenaard7f246c2019-04-08 18:15:41 +0200688 After each time the Insert mode completion
689 menu changed. Not fired on popup menu hide,
Bram Moolenaar3f169ce2020-01-26 22:43:31 +0100690 use |CompleteDonePre| or |CompleteDone| for
691 that. Never triggered recursively.
Bram Moolenaar754b5602006-02-09 23:53:20 +0000692
Bram Moolenaard7f246c2019-04-08 18:15:41 +0200693 Sets these |v:event| keys:
Bram Moolenaar911ead12019-04-21 00:03:35 +0200694 completed_item See |complete-items|.
Bram Moolenaard7f246c2019-04-08 18:15:41 +0200695 height nr of items visible
696 width screen cells
697 row top screen row
698 col leftmost screen column
699 size total nr of items
700 scrollbar TRUE if visible
701
702 It is not allowed to change the text |textlock|.
Bram Moolenaare9bd5722019-08-17 19:36:06 +0200703
704 The size and position of the popup are also
705 available by calling |pum_getpos()|.
706
Bram Moolenaar3f169ce2020-01-26 22:43:31 +0100707 *CompleteDonePre*
708CompleteDonePre After Insert mode completion is done. Either
709 when something was completed or abandoning
710 completion. |ins-completion|
711 |complete_info()| can be used, the info is
712 cleared after triggering CompleteDonePre.
713 The |v:completed_item| variable contains
714 information about the completed item.
715
Bram Moolenaar30b65812012-07-12 22:01:11 +0200716 *CompleteDone*
717CompleteDone After Insert mode completion is done. Either
718 when something was completed or abandoning
719 completion. |ins-completion|
Bram Moolenaar3f169ce2020-01-26 22:43:31 +0100720 |complete_info()| cannot be used, the info is
721 cleared before triggering CompleteDone. Use
722 CompleteDonePre if you need it.
Bram Moolenaar42a45122015-07-10 17:56:23 +0200723 The |v:completed_item| variable contains
724 information about the completed item.
Bram Moolenaar30b65812012-07-12 22:01:11 +0200725
glepnir1c5a1202024-12-04 20:27:34 +0100726 Sets these |v:event| keys:
727 complete_word The word that was
728 selected, empty if
729 abandoned complete.
730 complete_type |complete_info_mode|
731
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000732 *CursorHold*
733CursorHold When the user doesn't press a key for the time
Bram Moolenaard58a3bf2020-09-28 21:48:16 +0200734 specified with 'updatetime'. Not triggered
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000735 until the user has pressed a key (i.e. doesn't
736 fire every 'updatetime' ms if you leave Vim to
737 make some coffee. :) See |CursorHold-example|
738 for previewing tags.
739 This event is only triggered in Normal mode.
Bram Moolenaard7afed32007-05-06 13:26:41 +0000740 It is not triggered when waiting for a command
741 argument to be typed, or a movement after an
742 operator.
Bram Moolenaare3226be2005-12-18 22:10:00 +0000743 While recording the CursorHold event is not
744 triggered. |q|
Bram Moolenaar3a991dd2014-10-02 01:41:41 +0200745 *<CursorHold>*
746 Internally the autocommand is triggered by the
747 <CursorHold> key. In an expression mapping
748 |getchar()| may see this character.
749
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000750 Note: Interactive commands cannot be used for
751 this event. There is no hit-enter prompt,
752 the screen is updated directly (when needed).
753 Note: In the future there will probably be
754 another option to set the time.
755 Hint: to force an update of the status lines
756 use: >
757 :let &ro = &ro
Bram Moolenaar5666fcd2019-12-26 14:35:26 +0100758< {only on Amiga, Unix, Win32 and all GUI
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000759 versions}
Bram Moolenaar754b5602006-02-09 23:53:20 +0000760 *CursorHoldI*
761CursorHoldI Just like CursorHold, but in Insert mode.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +0200762 Not triggered when waiting for another key,
763 e.g. after CTRL-V, and not when in CTRL-X mode
764 |insert_expand|.
Bram Moolenaar754b5602006-02-09 23:53:20 +0000765
766 *CursorMoved*
Bram Moolenaar52b91d82013-06-15 21:39:51 +0200767CursorMoved After the cursor was moved in Normal or Visual
768 mode. Also when the text of the cursor line
769 has been changed, e.g., with "x", "rx" or "p".
Bram Moolenaar46eea442022-03-30 10:51:39 +0100770 Not always triggered when there is typeahead,
771 while executing commands in a script file,
772 when an operator is pending or when moving to
Bram Moolenaar90df4b92021-07-07 20:26:08 +0200773 another window while remaining at the same
774 cursor position.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +0000775 For an example see |match-parens|.
Bram Moolenaar26967612019-03-17 17:13:16 +0100776 Note: This can not be skipped with
777 `:noautocmd`.
Bram Moolenaarbf884932013-04-05 22:26:15 +0200778 Careful: This is triggered very often, don't
779 do anything that the user does not expect or
780 that is slow.
Shougo Matsushitad0952142024-06-20 22:05:16 +0200781 *CursorMovedC*
782CursorMovedC After the cursor was moved in the command
zeertzjq81456202024-07-07 20:48:25 +0200783 line. Be careful not to mess up the command
784 line, it may cause Vim to lock up.
Shougo Matsushitad0952142024-06-20 22:05:16 +0200785 <afile> is set to a single character,
786 indicating the type of command-line.
787 |cmdwin-char|
Bram Moolenaar754b5602006-02-09 23:53:20 +0000788 *CursorMovedI*
789CursorMovedI After the cursor was moved in Insert mode.
Bram Moolenaar5302d9e2011-09-14 17:55:08 +0200790 Not triggered when the popup menu is visible.
Bram Moolenaar754b5602006-02-09 23:53:20 +0000791 Otherwise the same as CursorMoved.
Bram Moolenaar75ab5902022-04-18 15:36:40 +0100792 *DiffUpdated*
793DiffUpdated After diffs have been updated. Depending on
794 what kind of diff is being used (internal or
795 external) this can be triggered on every
796 change or when doing |:diffupdate|.
797 *DirChangedPre*
798DirChangedPre The working directory is going to be changed,
799 as with |DirChanged|. The pattern is like
800 with |DirChanged|. The new directory can be
801 found in v:event.directory.
802 *DirChanged*
803DirChanged The working directory has changed in response
804 to the |:cd| or |:tcd| or |:lcd| commands, or
805 as a result of the 'autochdir' option.
806 The pattern can be:
807 "window" to trigger on `:lcd`
808 "tabpage" to trigger on `:tcd`
809 "global" to trigger on `:cd`
810 "auto" to trigger on 'autochdir'.
811 "drop" to trigger on editing a file
812 <afile> is set to the new directory name.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000813 *EncodingChanged*
814EncodingChanged Fires off after the 'encoding' option has been
815 changed. Useful to set up fonts, for example.
Bram Moolenaar75ab5902022-04-18 15:36:40 +0100816 *ExitPre*
817ExitPre When using `:quit`, `:wq` in a way it makes
818 Vim exit, or using `:qall`, just after
819 |QuitPre|. Can be used to close any
820 non-essential window. Exiting may still be
821 cancelled if there is a modified buffer that
822 isn't automatically saved, use |VimLeavePre|
823 for really exiting.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000824 *FileAppendCmd*
825FileAppendCmd Before appending to a file. Should do the
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000826 appending to the file. Use the '[ and ']
Bram Moolenaar22863042021-10-16 15:23:36 +0100827 marks for the range of lines. |Cmd-event|
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000828 *FileAppendPost*
829FileAppendPost After appending to a file.
830 *FileAppendPre*
831FileAppendPre Before appending to a file. Use the '[ and ']
832 marks for the range of lines.
833 *FileChangedRO*
834FileChangedRO Before making the first change to a read-only
835 file. Can be used to check-out the file from
836 a source control system. Not triggered when
837 the change was caused by an autocommand.
838 This event is triggered when making the first
839 change in a buffer or the first change after
Bram Moolenaar61660ea2006-04-07 21:40:07 +0000840 'readonly' was set, just before the change is
841 applied to the text.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000842 WARNING: If the autocommand moves the cursor
843 the effect of the change is undefined.
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000844 *E788*
845 It is not allowed to change to another buffer
846 here. You can reload the buffer but not edit
847 another one.
Bram Moolenaar92dff182014-02-11 19:15:50 +0100848 *E881*
849 If the number of lines changes saving for undo
850 may fail and the change will be aborted.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000851 *FileChangedShell*
852FileChangedShell When Vim notices that the modification time of
853 a file has changed since editing started.
854 Also when the file attributes of the file
Bram Moolenaare968e362014-05-13 20:23:24 +0200855 change or when the size of the file changes.
856 |timestamp|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000857 Mostly triggered after executing a shell
858 command, but also with a |:checktime| command
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +0200859 or when gvim regains input focus.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000860 This autocommand is triggered for each changed
861 file. It is not used when 'autoread' is set
862 and the buffer was not changed. If a
863 FileChangedShell autocommand is present the
864 warning message and prompt is not given.
Bram Moolenaar19a09a12005-03-04 23:39:37 +0000865 The |v:fcs_reason| variable is set to indicate
866 what happened and |v:fcs_choice| can be used
867 to tell Vim what to do next.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000868 NOTE: When this autocommand is executed, the
869 current buffer "%" may be different from the
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +0200870 buffer that was changed, which is in "<afile>".
Bram Moolenaar071d4272004-06-13 20:20:40 +0000871 NOTE: The commands must not change the current
872 buffer, jump to another buffer or delete a
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100873 buffer. *E246* *E811*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000874 NOTE: This event never nests, to avoid an
875 endless loop. This means that while executing
876 commands for the FileChangedShell event no
877 other FileChangedShell event will be
878 triggered.
Bram Moolenaar7d47b6e2006-03-15 22:59:18 +0000879 *FileChangedShellPost*
880FileChangedShellPost After handling a file that was changed outside
881 of Vim. Can be used to update the statusline.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000882 *FileEncoding*
883FileEncoding Obsolete. It still works and is equivalent
884 to |EncodingChanged|.
885 *FileReadCmd*
886FileReadCmd Before reading a file with a ":read" command.
887 Should do the reading of the file. |Cmd-event|
888 *FileReadPost*
889FileReadPost After reading a file with a ":read" command.
890 Note that Vim sets the '[ and '] marks to the
891 first and last line of the read. This can be
892 used to operate on the lines just read.
893 *FileReadPre*
894FileReadPre Before reading a file with a ":read" command.
895 *FileType*
Bram Moolenaard7afed32007-05-06 13:26:41 +0000896FileType When the 'filetype' option has been set. The
897 pattern is matched against the filetype.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000898 <afile> can be used for the name of the file
899 where this option was set, and <amatch> for
Bram Moolenaar74675a62017-07-15 13:53:23 +0200900 the new value of 'filetype'. Navigating to
901 another window or buffer is not allowed.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000902 See |filetypes|.
903 *FileWriteCmd*
904FileWriteCmd Before writing to a file, when not writing the
905 whole buffer. Should do the writing to the
906 file. Should not change the buffer. Use the
Christian Brabandtdf684192025-04-03 12:33:02 +0200907 |'[| and |']| marks for the range of lines.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000908 |Cmd-event|
909 *FileWritePost*
910FileWritePost After writing to a file, when not writing the
911 whole buffer.
912 *FileWritePre*
913FileWritePre Before writing to a file, when not writing the
Christian Brabandtdf684192025-04-03 12:33:02 +0200914 whole buffer. Use the |'[| and |']| marks for the
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000915 range of lines.
916 *FilterReadPost*
917FilterReadPost After reading a file from a filter command.
918 Vim checks the pattern against the name of
919 the current buffer as with FilterReadPre.
920 Not triggered when 'shelltemp' is off.
921 *FilterReadPre* *E135*
922FilterReadPre Before reading a file from a filter command.
923 Vim checks the pattern against the name of
924 the current buffer, not the name of the
925 temporary file that is the output of the
926 filter command.
927 Not triggered when 'shelltemp' is off.
928 *FilterWritePost*
929FilterWritePost After writing a file for a filter command or
Bram Moolenaar4c05fa02019-01-01 15:32:17 +0100930 making a diff with an external diff (see
Bram Moolenaar22863042021-10-16 15:23:36 +0100931 |DiffUpdated| for internal diff).
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000932 Vim checks the pattern against the name of
933 the current buffer as with FilterWritePre.
934 Not triggered when 'shelltemp' is off.
935 *FilterWritePre*
936FilterWritePre Before writing a file for a filter command or
Bram Moolenaar4c05fa02019-01-01 15:32:17 +0100937 making a diff with an external diff.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000938 Vim checks the pattern against the name of
939 the current buffer, not the name of the
940 temporary file that is the output of the
941 filter command.
942 Not triggered when 'shelltemp' is off.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000943 *FocusGained*
944FocusGained When Vim got input focus. Only for the GUI
945 version and a few console versions where this
Christian Brabandt49ddeef2024-07-07 20:29:43 +0200946 can be detected. |xterm-focus-event|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000947 *FocusLost*
948FocusLost When Vim lost input focus. Only for the GUI
949 version and a few console versions where this
Christian Brabandt49ddeef2024-07-07 20:29:43 +0200950 can be detected. |xterm-focus-event|
951 May also happen when a dialog pops up.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000952 *FuncUndefined*
953FuncUndefined When a user function is used but it isn't
954 defined. Useful for defining a function only
Bram Moolenaard7afed32007-05-06 13:26:41 +0000955 when it's used. The pattern is matched
956 against the function name. Both <amatch> and
957 <afile> are set to the name of the function.
zeertzjqaf056942025-03-08 16:45:20 +0100958 This is triggered even when inside an
959 autocommand defined without |autocmd-nested|,
960 but not triggered when compiling a |Vim9|
Bram Moolenaar4072ba52020-12-23 13:56:35 +0100961 function.
Bram Moolenaard5005162014-08-22 23:05:54 +0200962 NOTE: When writing Vim scripts a better
963 alternative is to use an autoloaded function.
Bram Moolenaar7c626922005-02-07 22:01:03 +0000964 See |autoload-functions|.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000965 *GUIEnter*
966GUIEnter After starting the GUI successfully, and after
967 opening the window. It is triggered before
968 VimEnter when using gvim. Can be used to
969 position the window from a .gvimrc file: >
970 :autocmd GUIEnter * winpos 100 50
Bram Moolenaard7afed32007-05-06 13:26:41 +0000971< *GUIFailed*
972GUIFailed After starting the GUI failed. Vim may
973 continue to run in the terminal, if possible
974 (only on Unix and alikes, when connecting the
975 X server fails). You may want to quit Vim: >
976 :autocmd GUIFailed * qall
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000977< *InsertChange*
978InsertChange When typing <Insert> while in Insert or
979 Replace mode. The |v:insertmode| variable
980 indicates the new mode.
981 Be careful not to move the cursor or do
982 anything else that the user does not expect.
Bram Moolenaare659c952011-05-19 17:25:41 +0200983 *InsertCharPre*
984InsertCharPre When a character is typed in Insert mode,
985 before inserting the char.
986 The |v:char| variable indicates the char typed
987 and can be changed during the event to insert
988 a different character. When |v:char| is set
989 to more than one character this text is
990 inserted literally.
991 It is not allowed to change the text |textlock|.
992 The event is not triggered when 'paste' is
Bram Moolenaarb5b75622018-03-09 22:22:21 +0100993 set. {only with the +eval feature}
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000994 *InsertEnter*
Bram Moolenaard7afed32007-05-06 13:26:41 +0000995InsertEnter Just before starting Insert mode. Also for
996 Replace mode and Virtual Replace mode. The
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000997 |v:insertmode| variable indicates the mode.
Bram Moolenaar097c9922013-05-19 21:15:15 +0200998 Be careful not to do anything else that the
999 user does not expect.
1000 The cursor is restored afterwards. If you do
1001 not want that set |v:char| to a non-empty
1002 string.
Bram Moolenaarb53e13a2020-10-21 12:19:53 +02001003 *InsertLeavePre*
1004InsertLeavePre Just before leaving Insert mode. Also when
Bram Moolenaarcb80aa22020-10-26 21:12:46 +01001005 using CTRL-O |i_CTRL-O|. Be careful not to
Bram Moolenaarb53e13a2020-10-21 12:19:53 +02001006 change mode or use `:normal`, it will likely
1007 cause trouble.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001008 *InsertLeave*
Bram Moolenaarb53e13a2020-10-21 12:19:53 +02001009InsertLeave Just after leaving Insert mode. Also when
1010 using CTRL-O |i_CTRL-O|. But not for |i_CTRL-C|.
Shougo Matsushita83678842024-07-11 22:05:12 +02001011 *KeyInputPre*
Shougo Matsushitafcc1b572024-07-17 20:25:22 +02001012KeyInputPre Just before a key is processed after mappings
1013 have been applied. The pattern is matched
1014 against a string that indicates the current
1015 mode, which is the same as what is returned by
1016 `mode(1)`.
Shougo Matsushita83678842024-07-11 22:05:12 +02001017 The |v:char| variable indicates the key typed
1018 and can be changed during the event to process
1019 a different key. When |v:char| is not a
1020 single character or a special key, the first
1021 character is used.
1022 The following values of |v:event| are set:
1023 typed The key is typed or not.
Shougo Matsushita890f97c2024-08-18 16:57:04 +02001024 typedchar The (actual) typed key since
1025 the last |KeyInputPre| call.
1026 Note: "typedchar" may be empty if successive
1027 |KeyInputPre| autocmds are processed.
Shougo Matsushita83678842024-07-11 22:05:12 +02001028 It is not allowed to change the text
1029 |textlock| or the current mode.
1030 {only with the +eval feature}
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001031 *MenuPopup*
1032MenuPopup Just before showing the popup menu (under the
1033 right mouse button). Useful for adjusting the
1034 menu for what is under the cursor or mouse
1035 pointer.
Bram Moolenaar4c5d8152018-10-19 22:36:53 +02001036 The pattern is matched against one or two
1037 characters representing the mode:
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001038 n Normal
1039 v Visual
1040 o Operator-pending
1041 i Insert
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00001042 c Command line
Bram Moolenaar4c5d8152018-10-19 22:36:53 +02001043 tl Terminal
=?UTF-8?q?Magnus=20Gro=C3=9F?=f1e88762021-09-12 13:39:55 +02001044 *ModeChanged*
1045ModeChanged After changing the mode. The pattern is
1046 matched against `'old_mode:new_mode'`, for
=?UTF-8?q?Magnus=20Gro=C3=9F?=25def2c2021-10-22 18:56:39 +01001047 example match against `*:c*` to simulate
1048 |CmdlineEnter|.
=?UTF-8?q?Magnus=20Gro=C3=9F?=f1e88762021-09-12 13:39:55 +02001049 The following values of |v:event| are set:
1050 old_mode The mode before it changed.
1051 new_mode The new mode as also returned
=?UTF-8?q?Magnus=20Gro=C3=9F?=25def2c2021-10-22 18:56:39 +01001052 by |mode()| called with a
1053 non-zero argument.
=?UTF-8?q?Magnus=20Gro=C3=9F?=f1e88762021-09-12 13:39:55 +02001054 When ModeChanged is triggered, old_mode will
1055 have the value of new_mode when the event was
1056 last triggered.
=?UTF-8?q?Magnus=20Gro=C3=9F?=25def2c2021-10-22 18:56:39 +01001057 This will be triggered on every minor mode
1058 change.
=?UTF-8?q?Magnus=20Gro=C3=9F?=f1e88762021-09-12 13:39:55 +02001059 Usage example to use relative line numbers
Bram Moolenaar6e649222021-10-04 21:32:54 +01001060 when entering Visual mode: >
=?UTF-8?q?Magnus=20Gro=C3=9F?=25def2c2021-10-22 18:56:39 +01001061 :au ModeChanged [vV\x16]*:* let &l:rnu = mode() =~# '^[vV\x16]'
1062 :au ModeChanged *:[vV\x16]* let &l:rnu = mode() =~# '^[vV\x16]'
1063 :au WinEnter,WinLeave * let &l:rnu = mode() =~# '^[vV\x16]'
=?UTF-8?q?Magnus=20Gro=C3=9F?=f1e88762021-09-12 13:39:55 +02001064< *OptionSet*
Bram Moolenaar53744302015-07-17 17:38:22 +02001065OptionSet After setting an option. The pattern is
1066 matched against the long option name.
Bram Moolenaard7c96872019-06-15 17:12:48 +02001067 |<amatch>| indicates what option has been set.
Bram Moolenaar53744302015-07-17 17:38:22 +02001068
Bram Moolenaard7c96872019-06-15 17:12:48 +02001069 |v:option_type| indicates whether it's global
Bram Moolenaar6c1e1572019-06-22 02:13:00 +02001070 or local scoped.
Bram Moolenaard7c96872019-06-15 17:12:48 +02001071 |v:option_command| indicates what type of
1072 set/let command was used (follow the tag to
1073 see the table).
1074 |v:option_new| indicates the newly set value.
Bram Moolenaar6c1e1572019-06-22 02:13:00 +02001075 |v:option_oldlocal| has the old local value.
1076 |v:option_oldglobal| has the old global value.
Bram Moolenaard7c96872019-06-15 17:12:48 +02001077 |v:option_old| indicates the old option value.
1078
1079 |v:option_oldlocal| is only set when |:set|
1080 or |:setlocal| or a |modeline| was used to set
1081 the option. Similarly |v:option_oldglobal| is
1082 only set when |:set| or |:setglobal| was used.
1083
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01001084 This does not set |<abuf>|, you could use
1085 |bufnr()|.
1086
Bram Moolenaard7c96872019-06-15 17:12:48 +02001087 Note that when setting a |global-local| string
1088 option with |:set|, then |v:option_old| is the
1089 old global value. However, for all other kinds
1090 of options (local string options, global-local
1091 number options, ...) it is the old local
1092 value.
1093
1094 OptionSet is not triggered on startup and for
1095 the 'key' option for obvious reasons.
Bram Moolenaar53744302015-07-17 17:38:22 +02001096
Bram Moolenaarf9132812015-07-21 19:19:13 +02001097 Usage example: Check for the existence of the
1098 directory in the 'backupdir' and 'undodir'
1099 options, create the directory if it doesn't
1100 exist yet.
1101
1102 Note: It's a bad idea to reset an option
1103 during this autocommand, this may break a
1104 plugin. You can always use `:noa` to prevent
1105 triggering this autocommand.
Bram Moolenaar53744302015-07-17 17:38:22 +02001106
Bram Moolenaar95bafa22018-10-02 13:26:25 +02001107 When using |:set| in the autocommand the event
1108 is not triggered again.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001109 *QuickFixCmdPre*
1110QuickFixCmdPre Before a quickfix command is run (|:make|,
Bram Moolenaara6557602006-02-04 22:43:20 +00001111 |:lmake|, |:grep|, |:lgrep|, |:grepadd|,
1112 |:lgrepadd|, |:vimgrep|, |:lvimgrep|,
Bram Moolenaar6be7f872012-01-20 21:08:56 +01001113 |:vimgrepadd|, |:lvimgrepadd|, |:cscope|,
Bram Moolenaar84f72352012-03-11 15:57:40 +01001114 |:cfile|, |:cgetfile|, |:caddfile|, |:lfile|,
1115 |:lgetfile|, |:laddfile|, |:helpgrep|,
Bram Moolenaar64d8e252016-09-06 22:12:34 +02001116 |:lhelpgrep|, |:cexpr|, |:cgetexpr|,
1117 |:caddexpr|, |:cbuffer|, |:cgetbuffer|,
1118 |:caddbuffer|).
Bram Moolenaarf1eeae92010-05-14 23:14:42 +02001119 The pattern is matched against the command
1120 being run. When |:grep| is used but 'grepprg'
1121 is set to "internal" it still matches "grep".
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001122 This command cannot be used to set the
1123 'makeprg' and 'grepprg' variables.
1124 If this command causes an error, the quickfix
1125 command is not executed.
1126 *QuickFixCmdPost*
1127QuickFixCmdPost Like QuickFixCmdPre, but after a quickfix
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00001128 command is run, before jumping to the first
Bram Moolenaar8ec1f852012-03-07 20:13:49 +01001129 location. For |:cfile| and |:lfile| commands
Bram Moolenaarb59ae592022-11-23 23:46:31 +00001130 it is run after the error file is read and
1131 before moving to the first error.
Bram Moolenaar8ec1f852012-03-07 20:13:49 +01001132 See |QuickFixCmdPost-example|.
Bram Moolenaar30b65812012-07-12 22:01:11 +02001133 *QuitPre*
Bram Moolenaarac7bd632013-03-19 11:35:58 +01001134QuitPre When using `:quit`, `:wq` or `:qall`, before
1135 deciding whether it closes the current window
Bram Moolenaard2ea7cf2021-05-30 20:54:13 +02001136 or quits Vim. For `:wq` the buffer is written
1137 before QuitPre is triggered. Can be used to
1138 close any non-essential window if the current
1139 window is the last ordinary window.
Bram Moolenaar12a96de2018-03-11 14:44:18 +01001140 Also see |ExitPre|.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001141 *RemoteReply*
1142RemoteReply When a reply from a Vim that functions as
Bram Moolenaard7afed32007-05-06 13:26:41 +00001143 server was received |server2client()|. The
1144 pattern is matched against the {serverid}.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001145 <amatch> is equal to the {serverid} from which
1146 the reply was sent, and <afile> is the actual
1147 reply string.
1148 Note that even if an autocommand is defined,
1149 the reply should be read with |remote_read()|
1150 to consume it.
Bram Moolenaar8aeec402019-09-15 23:02:04 +02001151 *SafeState*
1152SafeState When nothing is pending, going to wait for the
1153 user to type a character.
1154 This will not be triggered when:
1155 - an operator is pending
1156 - a register was entered with "r
1157 - halfway executing a command
1158 - executing a mapping
1159 - there is typeahead
1160 - Insert mode completion is active
1161 - Command line completion is active
1162 You can use `mode()` to find out what state
1163 Vim is in. That may be:
zeertzjqe13b6652024-01-24 03:39:04 +08001164 - Visual mode
Bram Moolenaar8aeec402019-09-15 23:02:04 +02001165 - Normal mode
1166 - Insert mode
1167 - Command-line mode
1168 Depending on what you want to do, you may also
1169 check more with `state()`, e.g. whether the
1170 screen was scrolled for messages.
Bram Moolenaar69198cb2019-09-16 21:58:13 +02001171 *SafeStateAgain*
1172SafeStateAgain Like SafeState but after processing any
1173 messages and invoking callbacks. This may be
1174 triggered often, don't do something that takes
1175 time.
Bram Moolenaar8aeec402019-09-15 23:02:04 +02001176
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001177 *SessionLoadPost*
1178SessionLoadPost After loading the session file created using
1179 the |:mksession| command.
Colin Kennedye5f22802024-03-26 18:20:16 +01001180 *SessionWritePost*
1181SessionWritePost After writing a session file by calling
1182 the |:mksession| command.
Bram Moolenaara94bc432006-03-10 21:42:59 +00001183 *ShellCmdPost*
1184ShellCmdPost After executing a shell command with |:!cmd|,
1185 |:shell|, |:make| and |:grep|. Can be used to
1186 check for any changed files.
1187 *ShellFilterPost*
1188ShellFilterPost After executing a shell command with
1189 ":{range}!cmd", ":w !cmd" or ":r !cmd".
1190 Can be used to check for any changed files.
Bram Moolenaar1f35bf92006-03-07 22:38:47 +00001191 *SourcePre*
1192SourcePre Before sourcing a Vim script. |:source|
Bram Moolenaar8dd1aa52007-01-16 20:33:19 +00001193 <afile> is the name of the file being sourced.
Bram Moolenaar2b618522019-01-12 13:26:03 +01001194 *SourcePost*
1195SourcePost After sourcing a Vim script. |:source|
1196 <afile> is the name of the file being sourced.
1197 Not triggered when sourcing was interrupted.
1198 Also triggered after a SourceCmd autocommand
1199 was triggered.
Bram Moolenaar8dd1aa52007-01-16 20:33:19 +00001200 *SourceCmd*
1201SourceCmd When sourcing a Vim script. |:source|
1202 <afile> is the name of the file being sourced.
1203 The autocommand must source this file.
1204 |Cmd-event|
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +00001205 *SpellFileMissing*
1206SpellFileMissing When trying to load a spell checking file and
Bram Moolenaar8dd1aa52007-01-16 20:33:19 +00001207 it can't be found. The pattern is matched
1208 against the language. <amatch> is the
1209 language, 'encoding' also matters. See
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +00001210 |spell-SpellFileMissing|.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001211 *StdinReadPost*
1212StdinReadPost After reading from the stdin into the buffer,
1213 before executing the modelines. Only used
1214 when the "-" argument was used when Vim was
1215 started |--|.
1216 *StdinReadPre*
1217StdinReadPre Before reading from stdin into the buffer.
1218 Only used when the "-" argument was used when
1219 Vim was started |--|.
1220 *SwapExists*
1221SwapExists Detected an existing swap file when starting
1222 to edit a file. Only when it is possible to
1223 select a way to handle the situation, when Vim
1224 would ask the user what to do.
1225 The |v:swapname| variable holds the name of
Bram Moolenaarb3480382005-12-11 21:33:32 +00001226 the swap file found, <afile> the file being
1227 edited. |v:swapcommand| may contain a command
1228 to be executed in the opened file.
1229 The commands should set the |v:swapchoice|
1230 variable to a string with one character to
1231 tell Vim what should be done next:
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001232 'o' open read-only
1233 'e' edit the file anyway
1234 'r' recover
1235 'd' delete the swap file
1236 'q' quit, don't edit the file
1237 'a' abort, like hitting CTRL-C
1238 When set to an empty string the user will be
1239 asked, as if there was no SwapExists autocmd.
Bram Moolenaarb849e712009-06-24 15:51:37 +00001240 *E812*
1241 It is not allowed to change to another buffer,
1242 change a buffer name or change directory
1243 here.
Bram Moolenaarb5b75622018-03-09 22:22:21 +01001244 {only available with the +eval feature}
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001245 *Syntax*
Bram Moolenaard7afed32007-05-06 13:26:41 +00001246Syntax When the 'syntax' option has been set. The
1247 pattern is matched against the syntax name.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001248 <afile> can be used for the name of the file
1249 where this option was set, and <amatch> for
1250 the new value of 'syntax'.
1251 See |:syn-on|.
Bram Moolenaar12c11d52016-07-19 23:13:03 +02001252 *TabClosed*
1253TabClosed After closing a tab page.
Jim Zhou5606ca52025-03-13 21:58:25 +01001254 *TabClosedPre*
1255TabClosedPre Before closing a tab page. The window layout
1256 is locked, thus opening and closing of windows
1257 is prohibited.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00001258 *TabEnter*
1259TabEnter Just after entering a tab page. |tab-page|
Bram Moolenaar56a907a2006-05-06 21:44:30 +00001260 After triggering the WinEnter and before
1261 triggering the BufEnter event.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00001262 *TabLeave*
1263TabLeave Just before leaving a tab page. |tab-page|
1264 A WinLeave event will have been triggered
1265 first.
Bram Moolenaarc917da42016-07-19 22:31:36 +02001266 *TabNew*
1267TabNew When a tab page was created. |tab-page|
1268 A WinEnter event will have been triggered
1269 first, TabEnter follows.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001270 *TermChanged*
1271TermChanged After the value of 'term' has changed. Useful
1272 for re-loading the syntax file to update the
1273 colors, fonts and other terminal-dependent
1274 settings. Executed for all loaded buffers.
Bram Moolenaarb852c3e2018-03-11 16:55:36 +01001275 *TerminalOpen*
1276TerminalOpen Just after a terminal buffer was created, with
1277 `:terminal` or |term_start()|. This event is
1278 triggered even if the buffer is created
1279 without a window, with the ++hidden option.
Bram Moolenaar28ed4df2019-10-26 16:21:40 +02001280 *TerminalWinOpen*
1281TerminalWinOpen Just after a terminal buffer was created, with
1282 `:terminal` or |term_start()|. This event is
1283 triggered only if the buffer is created
1284 with a window. Can be used to set window
1285 local options for the terminal window.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001286 *TermResponse*
1287TermResponse After the response to |t_RV| is received from
1288 the terminal. The value of |v:termresponse|
1289 can be used to do things depending on the
Christian Brabandt2abec432024-10-27 21:33:09 +01001290 terminal version.
1291 This is used in |defaults.vim| to detect
1292 putty terminal and set a dark background: >
1293
1294 au TermResponse *
1295 \ if v:termresponse == "\e[>0;136;0c"
1296 \ set bg=dark
1297 \ endif
1298<
1299 Note: that this event may be triggered halfway
1300 executing another event, especially if file
1301 I/O, a shell command or anything else that
1302 takes time is involved.
Danek Duvalld7d56032024-01-14 20:19:59 +01001303 *TermResponseAll*
1304TermResponseAll After the response to |t_RV|, |t_RC|, |t_RS|,
1305 |t_RB|, |t_RF|, or |t_u7| are received from
1306 the terminal. The value of |v:termresponse|,
1307 |v:termblinkresp|, |v:termstyleresp|,
1308 |v:termrbgresp|, |v:termrfgresp|, and
1309 |v:termu7resp|, correspondingly, can be used.
1310 <amatch> will be set to any of:
1311 "version",
1312 "cursorblink",
1313 "cursorshape",
1314 "background",
1315 "foreground",
1316 "ambiguouswidth"
1317 Note that this event may be triggered halfway
1318 executing another event, especially if file I/O,
1319 a shell command or anything else that takes time
1320 is involved.
Bram Moolenaarbf884932013-04-05 22:26:15 +02001321 *TextChanged*
1322TextChanged After a change was made to the text in the
Bram Moolenaard09091d2019-01-17 16:07:22 +01001323 current buffer in Normal mode. That is after
1324 |b:changedtick| has changed (also when that
1325 happened before the TextChanged autocommand
1326 was defined).
Bram Moolenaarbf884932013-04-05 22:26:15 +02001327 Not triggered when there is typeahead or when
1328 an operator is pending.
Bram Moolenaar26967612019-03-17 17:13:16 +01001329 Note: This can not be skipped with
1330 `:noautocmd`.
Bram Moolenaarbf884932013-04-05 22:26:15 +02001331 Careful: This is triggered very often, don't
1332 do anything that the user does not expect or
1333 that is slow.
1334 *TextChangedI*
1335TextChangedI After a change was made to the text in the
1336 current buffer in Insert mode.
1337 Not triggered when the popup menu is visible.
1338 Otherwise the same as TextChanged.
Bram Moolenaar5a093432018-02-10 18:15:19 +01001339 *TextChangedP*
1340TextChangedP After a change was made to the text in the
1341 current buffer in Insert mode, only when the
1342 popup menu is visible. Otherwise the same as
1343 TextChanged.
Shougo Matsushita4ccaedf2022-10-15 11:48:00 +01001344 *TextChangedT*
1345TextChangedT After a change was made to the text in the
1346 current buffer in Terminal mode.
1347 Otherwise the same as TextChanged.
Bram Moolenaarf0b03c42017-12-17 17:17:07 +01001348 *TextYankPost*
Bram Moolenaar7e1652c2017-12-16 18:27:02 +01001349TextYankPost After text has been yanked or deleted in the
1350 current buffer. The following values of
1351 |v:event| can be used to determine the operation
1352 that triggered this autocmd:
Bram Moolenaara016eeb2022-04-09 11:37:38 +01001353 inclusive TRUE if the motion is
1354 |inclusive| else the motion is
1355 |exclusive|.
Bram Moolenaar589edb32019-09-20 14:38:13 +02001356 operator The operation performed.
1357 regcontents Text that was stored in the
Bram Moolenaar7e1652c2017-12-16 18:27:02 +01001358 register, as a list of lines,
1359 like with: >
1360 getreg(r, 1, 1)
Bram Moolenaar22863042021-10-16 15:23:36 +01001361< regname Name of the register or empty
1362 string for the unnamed
1363 register, see |registers|.
Bram Moolenaar7e1652c2017-12-16 18:27:02 +01001364 regtype Type of the register, see
1365 |getregtype()|.
Bram Moolenaar37d16732020-06-12 22:09:01 +02001366 visual True if the operation is
1367 performed on a |Visual| area.
Bram Moolenaar7e1652c2017-12-16 18:27:02 +01001368 Not triggered when |quote_| is used nor when
1369 called recursively.
1370 It is not allowed to change the buffer text,
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00001371 see |textlock|. *E1064*
Jim Zhou7db96132025-03-12 20:57:24 +01001372 Also triggered indirectly when Vim tries to
1373 become owner of the Visual selection because
1374 of setting "autoselect" for 'guioptions' or
1375 'clipboard'.
Bram Moolenaarb5b75622018-03-09 22:22:21 +01001376 {only when compiled with the +eval feature}
Bram Moolenaarbe5ee862020-06-10 20:56:58 +02001377
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001378 *User*
1379User Never executed automatically. To be used for
1380 autocommands that are only executed with
1381 ":doautocmd".
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02001382 Note that when `:doautocmd User MyEvent` is
1383 used while there are no matching autocommands,
1384 you will get an error. If you don't want
LemonBoy09371822022-04-08 15:18:45 +01001385 that, either check whether an autocommand is
1386 defined using `exists('#User#MyEvent')` or
1387 define a dummy autocommand yourself.
1388 Example: >
1389 if exists('#User#MyEvent')
1390 doautocmd User MyEvent
1391 endif
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01001392<
Bram Moolenaarbe5ee862020-06-10 20:56:58 +02001393 *SigUSR1*
1394SigUSR1 After the SIGUSR1 signal has been detected.
1395 Could be used if other ways of notifying Vim
1396 are not feasible. E.g. to check for the
1397 result of a build that takes a long time, or
1398 when a motion sensor is triggered.
1399 {only on Unix}
1400
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001401 *UserGettingBored*
Bram Moolenaarbf884932013-04-05 22:26:15 +02001402UserGettingBored When the user presses the same key 42 times.
1403 Just kidding! :-)
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001404 *VimEnter*
1405VimEnter After doing all the startup stuff, including
1406 loading .vimrc files, executing the "-c cmd"
1407 arguments, creating all windows and loading
1408 the buffers in them.
Bram Moolenaar14735512016-03-26 21:00:08 +01001409 Just before this event is triggered the
1410 |v:vim_did_enter| variable is set, so that you
1411 can do: >
1412 if v:vim_did_enter
1413 call s:init()
1414 else
Bram Moolenaar589edb32019-09-20 14:38:13 +02001415 au VimEnter * call s:init()
Bram Moolenaar14735512016-03-26 21:00:08 +01001416 endif
1417< *VimLeave*
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001418VimLeave Before exiting Vim, just after writing the
1419 .viminfo file. Executed only once, like
1420 VimLeavePre.
1421 To detect an abnormal exit use |v:dying|.
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +02001422 When v:dying is 2 or more this event is not
1423 triggered.
Bram Moolenaarf0068c52020-11-30 17:42:10 +01001424 To get the exit code use |v:exiting|.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001425 *VimLeavePre*
1426VimLeavePre Before exiting Vim, just before writing the
1427 .viminfo file. This is executed only once,
1428 if there is a match with the name of what
1429 happens to be the current buffer when exiting.
1430 Mostly useful with a "*" pattern. >
1431 :autocmd VimLeavePre * call CleanupStuff()
1432< To detect an abnormal exit use |v:dying|.
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +02001433 When v:dying is 2 or more this event is not
1434 triggered.
Bram Moolenaarf0068c52020-11-30 17:42:10 +01001435 To get the exit code use |v:exiting|.
Bram Moolenaar7d47b6e2006-03-15 22:59:18 +00001436 *VimResized*
1437VimResized After the Vim window was resized, thus 'lines'
1438 and/or 'columns' changed. Not when starting
1439 up though.
Bram Moolenaar100118c2020-12-11 19:30:34 +01001440 *VimResume*
1441VimResume When the Vim instance is resumed after being
1442 suspended and |VimSuspend| was triggered.
1443 Useful for triggering |:checktime| and ensure
1444 the buffers content did not change while Vim
1445 was suspended: >
1446 :autocmd VimResume * checktime
1447< *VimSuspend*
1448VimSuspend When the Vim instance is suspended. Only when
dbivolaruab16ad32021-12-29 19:41:47 +00001449 CTRL-Z was typed inside Vim, or when the SIGTSTP
1450 signal was sent to Vim, but not for SIGSTOP.
naohiro ono23beefe2021-11-13 12:38:49 +00001451 *WinClosed*
Bram Moolenaarb59ae592022-11-23 23:46:31 +00001452WinClosed When closing a window, just before it is
1453 removed from the window layout. The pattern
1454 is matched against the |window-ID|. Both
naohiro ono23beefe2021-11-13 12:38:49 +00001455 <amatch> and <afile> are set to the
1456 |window-ID|. Non-recursive (event cannot
1457 trigger itself).
Bram Moolenaar071d4272004-06-13 20:20:40 +00001458 *WinEnter*
1459WinEnter After entering another window. Not done for
1460 the first window, when Vim has just started.
1461 Useful for setting the window height.
1462 If the window is for another buffer, Vim
1463 executes the BufEnter autocommands after the
1464 WinEnter autocommands.
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02001465 Note: For split and tabpage commands the
1466 WinEnter event is triggered after the split
1467 or tab command but before the file is loaded.
1468
Bram Moolenaar071d4272004-06-13 20:20:40 +00001469 *WinLeave*
1470WinLeave Before leaving a window. If the window to be
1471 entered next is for a different buffer, Vim
1472 executes the BufLeave autocommands before the
1473 WinLeave autocommands (but not for ":new").
1474 Not used for ":qa" or ":q" when exiting Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001475
Sergey Vlasov1f47db72024-01-25 23:07:00 +01001476 *WinNewPre*
1477WinNewPre Before creating a new window. Triggered
1478 before commands that modify window layout by
Christian Brabandtfb3f9692024-08-11 20:09:17 +02001479 creating a split.
h-east90e1fe42024-08-12 18:26:08 +02001480 Not done when creating tab pages and for the
1481 first window, as the window structure is not
Christian Brabandtfb3f9692024-08-11 20:09:17 +02001482 initialized yet and so is generally not safe.
Sergey Vlasov1f47db72024-01-25 23:07:00 +01001483 It is not allowed to modify window layout
1484 while executing commands for the WinNewPre
1485 event.
1486 Most useful to store current window layout
1487 and compare it with the new layout after the
1488 Window has been created.
1489
Bram Moolenaar12c11d52016-07-19 23:13:03 +02001490 *WinNew*
1491WinNew When a new window was created. Not done for
Bram Moolenaar50ba5262016-09-22 22:33:02 +02001492 the first window, when Vim has just started.
Bram Moolenaar12c11d52016-07-19 23:13:03 +02001493 Before a WinEnter event.
1494
LemonBoy09371822022-04-08 15:18:45 +01001495 *WinScrolled*
Bram Moolenaar35fc61c2022-11-22 12:40:50 +00001496WinScrolled After any window in the current tab page
1497 scrolled the text (horizontally or vertically)
1498 or changed width or height. See
1499 |win-scrolled-resized|.
Bram Moolenaar0a60f792022-11-19 21:18:11 +00001500
Christian Brabandtb8d5c852025-04-04 19:11:13 +02001501 Note: This can not be skipped with
1502 `:noautocmd`, because it triggers after
1503 processing normal commands when Vim is back in
1504 the main loop. If you want to disable this,
1505 consider setting the 'eventignore' option
1506 instead.
1507
Bram Moolenaar0a60f792022-11-19 21:18:11 +00001508 The pattern is matched against the |window-ID|
1509 of the first window that scrolled or resized.
1510 Both <amatch> and <afile> are set to the
1511 |window-ID|.
1512
Bram Moolenaar35fc61c2022-11-22 12:40:50 +00001513 |v:event| is set with information about size
1514 and scroll changes. |WinScrolled-event|
1515
Bram Moolenaar0a60f792022-11-19 21:18:11 +00001516 Only starts triggering after startup finished
1517 and the first screen redraw was done.
Bram Moolenaar35fc61c2022-11-22 12:40:50 +00001518 Does not trigger when defining the first
1519 WinScrolled or WinResized event, but may
1520 trigger when adding more.
Bram Moolenaar0a60f792022-11-19 21:18:11 +00001521
1522 Non-recursive: the event will not trigger
1523 while executing commands for the WinScrolled
1524 event. However, if the command causes a
1525 window to scroll or change size, then another
LemonBoy09371822022-04-08 15:18:45 +01001526 WinScrolled event will be triggered later.
Bram Moolenaar0a60f792022-11-19 21:18:11 +00001527
Bram Moolenaar35fc61c2022-11-22 12:40:50 +00001528
1529 *WinResized*
1530WinResized After a window in the current tab page changed
1531 width or height.
1532 See |win-scrolled-resized|.
1533
1534 |v:event| is set with information about size
1535 changes. |WinResized-event|
1536
1537 Same behavior as |WinScrolled| for the
1538 pattern, triggering and recursiveness.
LemonBoy09371822022-04-08 15:18:45 +01001539
Bram Moolenaar071d4272004-06-13 20:20:40 +00001540==============================================================================
Bram Moolenaarfd31be22022-01-16 14:46:06 +000015416. Patterns *autocmd-patterns* *{aupat}*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001542
LemonBoy09371822022-04-08 15:18:45 +01001543The {aupat} argument of `:autocmd` can be a comma-separated list. This works as
Bram Moolenaarfd31be22022-01-16 14:46:06 +00001544if the command was given with each pattern separately. Thus this command: >
Bram Moolenaar5a5f4592015-04-13 12:43:06 +02001545 :autocmd BufRead *.txt,*.info set et
1546Is equivalent to: >
1547 :autocmd BufRead *.txt set et
1548 :autocmd BufRead *.info set et
1549
Bram Moolenaarfd31be22022-01-16 14:46:06 +00001550The file pattern {aupat} is tested for a match against the file name in one of
Bram Moolenaar071d4272004-06-13 20:20:40 +00001551two ways:
15521. When there is no '/' in the pattern, Vim checks for a match against only
1553 the tail part of the file name (without its leading directory path).
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010015542. When there is a '/' in the pattern, Vim checks for a match against both the
1555 short file name (as you typed it) and the full file name (after expanding
1556 it to a full path and resolving symbolic links).
Bram Moolenaar071d4272004-06-13 20:20:40 +00001557
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00001558The special pattern <buffer> or <buffer=N> is used for buffer-local
1559autocommands |autocmd-buflocal|. This pattern is not matched against the name
1560of a buffer.
1561
Bram Moolenaar071d4272004-06-13 20:20:40 +00001562Examples: >
1563 :autocmd BufRead *.txt set et
1564Set the 'et' option for all text files. >
1565
1566 :autocmd BufRead /vim/src/*.c set cindent
1567Set the 'cindent' option for C files in the /vim/src directory. >
1568
1569 :autocmd BufRead /tmp/*.c set ts=5
1570If you have a link from "/tmp/test.c" to "/home/nobody/vim/src/test.c", and
1571you start editing "/tmp/test.c", this autocommand will match.
1572
1573Note: To match part of a path, but not from the root directory, use a '*' as
1574the first character. Example: >
1575 :autocmd BufRead */doc/*.txt set tw=78
1576This autocommand will for example be executed for "/tmp/doc/xx.txt" and
1577"/usr/home/piet/doc/yy.txt". The number of directories does not matter here.
1578
1579
1580The file name that the pattern is matched against is after expanding
Bram Moolenaar446cb832008-06-24 21:56:24 +00001581wildcards. Thus if you issue this command: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001582 :e $ROOTDIR/main.$EXT
1583The argument is first expanded to: >
1584 /usr/root/main.py
1585Before it's matched with the pattern of the autocommand. Careful with this
1586when using events like FileReadCmd, the value of <amatch> may not be what you
1587expect.
1588
1589
1590Environment variables can be used in a pattern: >
1591 :autocmd BufRead $VIMRUNTIME/doc/*.txt set expandtab
1592And ~ can be used for the home directory (if $HOME is defined): >
1593 :autocmd BufWritePost ~/.vimrc so ~/.vimrc
1594 :autocmd BufRead ~archive/* set readonly
1595The environment variable is expanded when the autocommand is defined, not when
1596the autocommand is executed. This is different from the command!
1597
1598 *file-pattern*
1599The pattern is interpreted like mostly used in file names:
Bram Moolenaar3b1db362013-08-10 15:00:24 +02001600 * matches any sequence of characters; Unusual: includes path
Bram Moolenaar9d98fe92013-08-03 18:35:36 +02001601 separators
Bram Moolenaar071d4272004-06-13 20:20:40 +00001602 ? matches any single character
1603 \? matches a '?'
1604 . matches a '.'
1605 ~ matches a '~'
1606 , separates patterns
1607 \, matches a ','
1608 { } like \( \) in a |pattern|
1609 , inside { }: like \| in a |pattern|
Bram Moolenaara946afe2013-08-02 15:22:39 +02001610 \} literal }
1611 \{ literal {
1612 \\\{n,m\} like \{n,m} in a |pattern|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001613 \ special meaning like in a |pattern|
1614 [ch] matches 'c' or 'h'
1615 [^ch] match any character but 'c' and 'h'
1616
1617Note that for all systems the '/' character is used for path separator (even
Bram Moolenaar6f345a12019-12-17 21:27:18 +01001618for MS-Windows). This was done because the backslash is difficult to use in a
1619pattern and to make the autocommands portable across different systems.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001620
Bram Moolenaar64d8e252016-09-06 22:12:34 +02001621It is possible to use |pattern| items, but they may not work as expected,
1622because of the translation done for the above.
1623
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00001624 *autocmd-changes*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001625Matching with the pattern is done when an event is triggered. Changing the
1626buffer name in one of the autocommands, or even deleting the buffer, does not
1627change which autocommands will be executed. Example: >
1628
1629 au BufEnter *.foo bdel
1630 au BufEnter *.foo set modified
1631
1632This will delete the current buffer and then set 'modified' in what has become
1633the current buffer instead. Vim doesn't take into account that "*.foo"
1634doesn't match with that buffer name. It matches "*.foo" with the name of the
1635buffer at the moment the event was triggered.
1636
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00001637However, buffer-local autocommands will not be executed for a buffer that has
1638been wiped out with |:bwipe|. After deleting the buffer with |:bdel| the
1639buffer actually still exists (it becomes unlisted), thus the autocommands are
1640still executed.
1641
Bram Moolenaar071d4272004-06-13 20:20:40 +00001642==============================================================================
Bram Moolenaarc9b4b052006-04-30 18:54:39 +000016437. Buffer-local autocommands *autocmd-buflocal* *autocmd-buffer-local*
1644 *<buffer=N>* *<buffer=abuf>* *E680*
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00001645
1646Buffer-local autocommands are attached to a specific buffer. They are useful
1647if the buffer does not have a name and when the name does not match a specific
1648pattern. But it also means they must be explicitly added to each buffer.
1649
1650Instead of a pattern buffer-local autocommands use one of these forms:
1651 <buffer> current buffer
1652 <buffer=99> buffer number 99
1653 <buffer=abuf> using <abuf> (only when executing autocommands)
1654 |<abuf>|
1655
1656Examples: >
1657 :au CursorHold <buffer> echo 'hold'
1658 :au CursorHold <buffer=33> echo 'hold'
Bram Moolenaar88774fd2015-08-25 19:52:04 +02001659 :au BufNewFile * au CursorHold <buffer=abuf> echo 'hold'
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00001660
1661All the commands for autocommands also work with buffer-local autocommands,
1662simply use the special string instead of the pattern. Examples: >
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001663 :au! * <buffer> " remove buffer-local autocommands for
1664 " current buffer
1665 :au! * <buffer=33> " remove buffer-local autocommands for
1666 " buffer #33
Bram Moolenaar446cb832008-06-24 21:56:24 +00001667 :bufdo :au! CursorHold <buffer> " remove autocmd for given event for all
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001668 " buffers
1669 :au * <buffer> " list buffer-local autocommands for
1670 " current buffer
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00001671
1672Note that when an autocommand is defined for the current buffer, it is stored
1673with the buffer number. Thus it uses the form "<buffer=12>", where 12 is the
1674number of the current buffer. You will see this when listing autocommands,
1675for example.
1676
1677To test for presence of buffer-local autocommands use the |exists()| function
1678as follows: >
1679 :if exists("#CursorHold#<buffer=12>") | ... | endif
1680 :if exists("#CursorHold#<buffer>") | ... | endif " for current buffer
1681
1682When a buffer is wiped out its buffer-local autocommands are also gone, of
1683course. Note that when deleting a buffer, e.g., with ":bdel", it is only
1684unlisted, the autocommands are still present. In order to see the removal of
1685buffer-local autocommands: >
1686 :set verbose=6
1687
1688It is not possible to define buffer-local autocommands for a non-existent
1689buffer.
1690
1691==============================================================================
16928. Groups *autocmd-groups*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001693
1694Autocommands can be put together in a group. This is useful for removing or
1695executing a group of autocommands. For example, all the autocommands for
1696syntax highlighting are put in the "highlight" group, to be able to execute
1697":doautoall highlight BufRead" when the GUI starts.
1698
1699When no specific group is selected, Vim uses the default group. The default
1700group does not have a name. You cannot execute the autocommands from the
1701default group separately; you can execute them only by executing autocommands
1702for all groups.
1703
1704Normally, when executing autocommands automatically, Vim uses the autocommands
1705for all groups. The group only matters when executing autocommands with
1706":doautocmd" or ":doautoall", or when defining or deleting autocommands.
1707
1708The group name can contain any characters except white space. The group name
1709"end" is reserved (also in uppercase).
1710
1711The group name is case sensitive. Note that this is different from the event
1712name!
1713
1714 *:aug* *:augroup*
1715:aug[roup] {name} Define the autocmd group name for the
1716 following ":autocmd" commands. The name "end"
1717 or "END" selects the default group.
Bram Moolenaar256972a2015-12-29 19:10:25 +01001718 To avoid confusion, the name should be
1719 different from existing {event} names, as this
1720 most likely will not do what you intended.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001721
Bram Moolenaar64d8e252016-09-06 22:12:34 +02001722 *:augroup-delete* *E367* *W19* *E936*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001723:aug[roup]! {name} Delete the autocmd group {name}. Don't use
1724 this if there is still an autocommand using
Bram Moolenaarbc8801c2016-08-02 21:04:33 +02001725 this group! You will get a warning if doing
Bram Moolenaare7b1ea02020-08-07 19:54:59 +02001726 it anyway. When the group is the current
1727 group you will get error E936.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001728
1729To enter autocommands for a specific group, use this method:
17301. Select the group with ":augroup {name}".
17312. Delete any old autocommands with ":au!".
17323. Define the autocommands.
17334. Go back to the default group with "augroup END".
1734
1735Example: >
1736 :augroup uncompress
1737 : au!
1738 : au BufEnter *.gz %!gunzip
1739 :augroup END
1740
1741This prevents having the autocommands defined twice (e.g., after sourcing the
1742.vimrc file again).
1743
Bram Moolenaar6e649222021-10-04 21:32:54 +01001744 *FileExplorer*
1745There is one group that is recognized by Vim: FileExplorer. If this group
1746exists Vim assumes that editing a directory is possible and will trigger a
1747plugin that lists the files in that directory. This is used by the |netrw|
1748plugin. This allows you to do: >
1749 browse edit
1750
Bram Moolenaar071d4272004-06-13 20:20:40 +00001751==============================================================================
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +000017529. Executing autocommands *autocmd-execute*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001753
1754Vim can also execute Autocommands non-automatically. This is useful if you
1755have changed autocommands, or when Vim has executed the wrong autocommands
1756(e.g., the file pattern match was wrong).
1757
1758Note that the 'eventignore' option applies here too. Events listed in this
1759option will not cause any commands to be executed.
1760
Bram Moolenaar61da1bf2019-06-06 12:14:49 +02001761 *:do* *:doau* *:doaut* *:doautocmd* *E217*
Bram Moolenaar5dc62522012-02-13 00:05:22 +01001762:do[autocmd] [<nomodeline>] [group] {event} [fname]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001763 Apply the autocommands matching [fname] (default:
1764 current file name) for {event} to the current buffer.
1765 You can use this when the current file name does not
1766 match the right pattern, after changing settings, or
1767 to execute autocommands for a certain event.
1768 It's possible to use this inside an autocommand too,
1769 so you can base the autocommands for one extension on
1770 another extension. Example: >
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01001771 :au BufEnter *.cpp so ~/.vimrc_cpp
1772 :au BufEnter *.cpp doau BufEnter x.c
Bram Moolenaar071d4272004-06-13 20:20:40 +00001773< Be careful to avoid endless loops. See
1774 |autocmd-nested|.
1775
1776 When the [group] argument is not given, Vim executes
1777 the autocommands for all groups. When the [group]
1778 argument is included, Vim executes only the matching
1779 autocommands for that group. Note: if you use an
1780 undefined group name, Vim gives you an error message.
Bram Moolenaar60542ac2012-02-12 20:14:01 +01001781 *<nomodeline>*
1782 After applying the autocommands the modelines are
1783 processed, so that their settings overrule the
1784 settings from autocommands, like what happens when
1785 editing a file. This is skipped when the <nomodeline>
1786 argument is present. You probably want to use
1787 <nomodeline> for events that are not used when loading
1788 a buffer, such as |User|.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001789 Processing modelines is also skipped when no
1790 matching autocommands were executed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001791
1792 *:doautoa* *:doautoall*
Bram Moolenaara61d5fb2012-02-12 00:18:58 +01001793:doautoa[ll] [<nomodeline>] [group] {event} [fname]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001794 Like ":doautocmd", but apply the autocommands to each
Bram Moolenaardad44732021-03-31 20:07:33 +02001795 loaded buffer. The current buffer is done last.
1796
1797 Note that [fname] is used to select the autocommands,
Bram Moolenaar4c295022021-05-02 17:19:11 +02001798 not the buffers to which they are applied. Example: >
1799 augroup mine
1800 autocmd!
1801 autocmd FileType * echo expand('<amatch>')
1802 augroup END
1803 doautoall mine FileType Loaded-Buffer
1804< Sourcing this script, you'll see as many
1805 "Loaded-Buffer" echoed as there are loaded buffers.
Bram Moolenaardad44732021-03-31 20:07:33 +02001806
Bram Moolenaar071d4272004-06-13 20:20:40 +00001807 Careful: Don't use this for autocommands that delete a
1808 buffer, change to another buffer or change the
1809 contents of a buffer; the result is unpredictable.
1810 This command is intended for autocommands that set
1811 options, change highlighting, and things like that.
1812
1813==============================================================================
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +0000181410. Using autocommands *autocmd-use*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001815
1816For WRITING FILES there are four possible sets of events. Vim uses only one
1817of these sets for a write command:
1818
1819BufWriteCmd BufWritePre BufWritePost writing the whole buffer
1820 FilterWritePre FilterWritePost writing to filter temp file
1821FileAppendCmd FileAppendPre FileAppendPost appending to a file
1822FileWriteCmd FileWritePre FileWritePost any other file write
1823
1824When there is a matching "*Cmd" autocommand, it is assumed it will do the
1825writing. No further writing is done and the other events are not triggered.
1826|Cmd-event|
1827
1828Note that the *WritePost commands should undo any changes to the buffer that
1829were caused by the *WritePre commands; otherwise, writing the file will have
1830the side effect of changing the buffer.
1831
1832Before executing the autocommands, the buffer from which the lines are to be
1833written temporarily becomes the current buffer. Unless the autocommands
1834change the current buffer or delete the previously current buffer, the
1835previously current buffer is made the current buffer again.
1836
1837The *WritePre and *AppendPre autocommands must not delete the buffer from
1838which the lines are to be written.
1839
1840The '[ and '] marks have a special position:
1841- Before the *ReadPre event the '[ mark is set to the line just above where
1842 the new lines will be inserted.
1843- Before the *ReadPost event the '[ mark is set to the first line that was
1844 just read, the '] mark to the last line.
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001845- Before executing the *WriteCmd, *WritePre and *AppendPre autocommands the '[
1846 mark is set to the first line that will be written, the '] mark to the last
1847 line.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001848Careful: '[ and '] change when using commands that change the buffer.
1849
1850In commands which expect a file name, you can use "<afile>" for the file name
1851that is being read |:<afile>| (you can also use "%" for the current file
1852name). "<abuf>" can be used for the buffer number of the currently effective
Bram Moolenaard2f3a8b2018-06-19 14:35:59 +02001853buffer. This also works for buffers that don't have a name. But it doesn't
Bram Moolenaar071d4272004-06-13 20:20:40 +00001854work for files without a buffer (e.g., with ":r file").
1855
1856 *gzip-example*
1857Examples for reading and writing compressed files: >
1858 :augroup gzip
1859 : autocmd!
1860 : autocmd BufReadPre,FileReadPre *.gz set bin
1861 : autocmd BufReadPost,FileReadPost *.gz '[,']!gunzip
1862 : autocmd BufReadPost,FileReadPost *.gz set nobin
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001863 : autocmd BufReadPost,FileReadPost *.gz execute ":doautocmd BufReadPost " .. expand("%:r")
Bram Moolenaar071d4272004-06-13 20:20:40 +00001864 : autocmd BufWritePost,FileWritePost *.gz !mv <afile> <afile>:r
1865 : autocmd BufWritePost,FileWritePost *.gz !gzip <afile>:r
1866
1867 : autocmd FileAppendPre *.gz !gunzip <afile>
1868 : autocmd FileAppendPre *.gz !mv <afile>:r <afile>
1869 : autocmd FileAppendPost *.gz !mv <afile> <afile>:r
1870 : autocmd FileAppendPost *.gz !gzip <afile>:r
1871 :augroup END
1872
1873The "gzip" group is used to be able to delete any existing autocommands with
1874":autocmd!", for when the file is sourced twice.
1875
1876("<afile>:r" is the file name without the extension, see |:_%:|)
1877
1878The commands executed for the BufNewFile, BufRead/BufReadPost, BufWritePost,
1879FileAppendPost and VimLeave events do not set or reset the changed flag of the
1880buffer. When you decompress the buffer with the BufReadPost autocommands, you
1881can still exit with ":q". When you use ":undo" in BufWritePost to undo the
1882changes made by BufWritePre commands, you can still do ":q" (this also makes
1883"ZZ" work). If you do want the buffer to be marked as modified, set the
1884'modified' option.
1885
1886To execute Normal mode commands from an autocommand, use the ":normal"
1887command. Use with care! If the Normal mode command is not finished, the user
1888needs to type characters (e.g., after ":normal m" you need to type a mark
1889name).
1890
1891If you want the buffer to be unmodified after changing it, reset the
1892'modified' option. This makes it possible to exit the buffer with ":q"
1893instead of ":q!".
1894
1895 *autocmd-nested* *E218*
Bram Moolenaar26967612019-03-17 17:13:16 +01001896By default, autocommands do not nest. For example, if you use ":e" or ":w" in
1897an autocommand, Vim does not execute the BufRead and BufWrite autocommands for
Bram Moolenaar071d4272004-06-13 20:20:40 +00001898those commands. If you do want this, use the "nested" flag for those commands
1899in which you want nesting. For example: >
Bram Moolenaareb93f3f2019-04-04 15:04:56 +02001900 :autocmd FileChangedShell *.c ++nested e!
Bram Moolenaar071d4272004-06-13 20:20:40 +00001901The nesting is limited to 10 levels to get out of recursive loops.
1902
1903It's possible to use the ":au" command in an autocommand. This can be a
1904self-modifying command! This can be useful for an autocommand that should
1905execute only once.
1906
Bram Moolenaarb3480382005-12-11 21:33:32 +00001907If you want to skip autocommands for one command, use the |:noautocmd| command
1908modifier or the 'eventignore' option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001909
1910Note: When reading a file (with ":read file" or with a filter command) and the
1911last line in the file does not have an <EOL>, Vim remembers this. At the next
1912write (with ":write file" or with a filter command), if the same line is
1913written again as the last line in a file AND 'binary' is set, Vim does not
1914supply an <EOL>. This makes a filter command on the just read lines write the
1915same file as was read, and makes a write command on just filtered lines write
1916the same file as was read from the filter. For example, another way to write
1917a compressed file: >
1918
1919 :autocmd FileWritePre *.gz set bin|'[,']!gzip
1920 :autocmd FileWritePost *.gz undo|set nobin
1921<
1922 *autocommand-pattern*
1923You can specify multiple patterns, separated by commas. Here are some
1924examples: >
1925
1926 :autocmd BufRead * set tw=79 nocin ic infercase fo=2croq
1927 :autocmd BufRead .letter set tw=72 fo=2tcrq
1928 :autocmd BufEnter .letter set dict=/usr/lib/dict/words
1929 :autocmd BufLeave .letter set dict=
1930 :autocmd BufRead,BufNewFile *.c,*.h set tw=0 cin noic
1931 :autocmd BufEnter *.c,*.h abbr FOR for (i = 0; i < 3; ++i)<CR>{<CR>}<Esc>O
1932 :autocmd BufLeave *.c,*.h unabbr FOR
1933
1934For makefiles (makefile, Makefile, imakefile, makefile.unix, etc.): >
1935
1936 :autocmd BufEnter ?akefile* set include=^s\=include
1937 :autocmd BufLeave ?akefile* set include&
1938
1939To always start editing C files at the first function: >
1940
1941 :autocmd BufRead *.c,*.h 1;/^{
1942
1943Without the "1;" above, the search would start from wherever the file was
1944entered, rather than from the start of the file.
1945
1946 *skeleton* *template*
1947To read a skeleton (template) file when opening a new file: >
1948
1949 :autocmd BufNewFile *.c 0r ~/vim/skeleton.c
1950 :autocmd BufNewFile *.h 0r ~/vim/skeleton.h
1951 :autocmd BufNewFile *.java 0r ~/vim/skeleton.java
1952
1953To insert the current date and time in a *.html file when writing it: >
1954
1955 :autocmd BufWritePre,FileWritePre *.html ks|call LastMod()|'s
1956 :fun LastMod()
1957 : if line("$") > 20
1958 : let l = 20
1959 : else
1960 : let l = line("$")
1961 : endif
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001962 : exe "1," .. l .. "g/Last modified: /s/Last modified: .*/Last modified: " ..
Bram Moolenaar071d4272004-06-13 20:20:40 +00001963 : \ strftime("%Y %b %d")
1964 :endfun
1965
1966You need to have a line "Last modified: <date time>" in the first 20 lines
1967of the file for this to work. Vim replaces <date time> (and anything in the
1968same line after it) with the current date and time. Explanation:
1969 ks mark current position with mark 's'
1970 call LastMod() call the LastMod() function to do the work
1971 's return the cursor to the old position
1972The LastMod() function checks if the file is shorter than 20 lines, and then
1973uses the ":g" command to find lines that contain "Last modified: ". For those
1974lines the ":s" command is executed to replace the existing date with the
1975current one. The ":execute" command is used to be able to use an expression
1976for the ":g" and ":s" commands. The date is obtained with the strftime()
1977function. You can change its argument to get another date string.
1978
1979When entering :autocmd on the command-line, completion of events and command
1980names may be done (with <Tab>, CTRL-D, etc.) where appropriate.
1981
1982Vim executes all matching autocommands in the order that you specify them.
1983It is recommended that your first autocommand be used for all files by using
1984"*" as the file pattern. This means that you can define defaults you like
1985here for any settings, and if there is another matching autocommand it will
1986override these. But if there is no other matching autocommand, then at least
1987your default settings are recovered (if entering this file from another for
1988which autocommands did match). Note that "*" will also match files starting
1989with ".", unlike Unix shells.
1990
1991 *autocmd-searchpat*
1992Autocommands do not change the current search patterns. Vim saves the current
1993search patterns before executing autocommands then restores them after the
1994autocommands finish. This means that autocommands do not affect the strings
1995highlighted with the 'hlsearch' option. Within autocommands, you can still
1996use search patterns normally, e.g., with the "n" command.
1997If you want an autocommand to set the search pattern, such that it is used
1998after the autocommand finishes, use the ":let @/ =" command.
1999The search-highlighting cannot be switched off with ":nohlsearch" in an
2000autocommand. Use the 'h' flag in the 'viminfo' option to disable search-
2001highlighting when starting Vim.
2002
2003 *Cmd-event*
2004When using one of the "*Cmd" events, the matching autocommands are expected to
Bram Moolenaar8dd1aa52007-01-16 20:33:19 +00002005do the file reading, writing or sourcing. This can be used when working with
2006a special kind of file, for example on a remote system.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002007CAREFUL: If you use these events in a wrong way, it may have the effect of
2008making it impossible to read or write the matching files! Make sure you test
2009your autocommands properly. Best is to use a pattern that will never match a
2010normal file name, for example "ftp://*".
2011
2012When defining a BufReadCmd it will be difficult for Vim to recover a crashed
2013editing session. When recovering from the original file, Vim reads only those
2014parts of a file that are not found in the swap file. Since that is not
2015possible with a BufReadCmd, use the |:preserve| command to make sure the
2016original file isn't needed for recovery. You might want to do this only when
2017you expect the file to be modified.
2018
Bram Moolenaar8dd1aa52007-01-16 20:33:19 +00002019For file read and write commands the |v:cmdarg| variable holds the "++enc="
2020and "++ff=" argument that are effective. These should be used for the command
2021that reads/writes the file. The |v:cmdbang| variable is one when "!" was
2022used, zero otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002023
Bram Moolenaarc88ebf72010-07-22 22:30:23 +02002024See the $VIMRUNTIME/plugin/netrwPlugin.vim for examples.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002025
Bram Moolenaarb3480382005-12-11 21:33:32 +00002026==============================================================================
202711. Disabling autocommands *autocmd-disable*
2028
2029To disable autocommands for some time use the 'eventignore' option. Note that
2030this may cause unexpected behavior, make sure you restore 'eventignore'
2031afterwards, using a |:try| block with |:finally|.
2032
Luuk van Baalb7147f82025-02-08 18:52:39 +01002033To disable autocmds indefinitely in a specific window use the 'eventignorewin'
2034option. This can only be used to ignore window and buffer related events.
2035
Bram Moolenaarb3480382005-12-11 21:33:32 +00002036 *:noautocmd* *:noa*
2037To disable autocommands for just one command use the ":noautocmd" command
2038modifier. This will set 'eventignore' to "all" for the duration of the
2039following command. Example: >
2040
2041 :noautocmd w fname.gz
2042
2043This will write the file without triggering the autocommands defined by the
2044gzip plugin.
2045
Bram Moolenaar26967612019-03-17 17:13:16 +01002046Note that some autocommands are not triggered right away, but only later.
2047This specifically applies to |CursorMoved| and |TextChanged|.
2048
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00002049
Bram Moolenaar91f84f62018-07-29 15:07:52 +02002050 vim:tw=78:ts=8:noet:ft=help:norl: