blob: b9b76ffced903b4e6481143d345bcfc111987a85 [file] [log] [blame]
Christian Brabandtb8d5c852025-04-04 19:11:13 +02001*autocmd.txt* For Vim version 9.1. Last change: 2025 Apr 04
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.
133
Bram Moolenaar2ec618c2016-10-01 14:47:05 +0200134`:autocmd` adds to the list of autocommands regardless of whether they are
135already present. When your .vimrc file is sourced twice, the autocommands
136will appear twice. To avoid this, define your autocommands in a group, so
137that you can easily clear them: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000138
Bram Moolenaar2ec618c2016-10-01 14:47:05 +0200139 augroup vimrc
Bram Moolenaar98ef2332018-03-18 14:44:37 +0100140 " Remove all vimrc autocommands
141 autocmd!
Bram Moolenaar2ec618c2016-10-01 14:47:05 +0200142 au BufNewFile,BufRead *.html so <sfile>:h/html.vim
143 augroup END
Bram Moolenaar071d4272004-06-13 20:20:40 +0000144
145If you don't want to remove all autocommands, you can instead use a variable
146to ensure that Vim includes the autocommands only once: >
147
148 :if !exists("autocommands_loaded")
149 : let autocommands_loaded = 1
150 : au ...
151 :endif
152
153When the [group] argument is not given, Vim uses the current group (as defined
154with ":augroup"); otherwise, Vim uses the group defined with [group]. Note
155that [group] must have been defined before. You cannot define a new group
156with ":au group ..."; use ":augroup" for that.
157
158While testing autocommands, you might find the 'verbose' option to be useful: >
159 :set verbose=9
160This setting makes Vim echo the autocommands as it executes them.
161
162When defining an autocommand in a script, it will be able to call functions
163local to the script and use mappings local to the script. When the event is
164triggered and the command executed, it will run in the context of the script
165it was defined in. This matters if |<SID>| is used in a command.
166
Bram Moolenaar446cb832008-06-24 21:56:24 +0000167When executing the commands, the message from one command overwrites a
Bram Moolenaar071d4272004-06-13 20:20:40 +0000168previous message. This is different from when executing the commands
169manually. Mostly the screen will not scroll up, thus there is no hit-enter
170prompt. When one command outputs two messages this can happen anyway.
171
172==============================================================================
1733. Removing autocommands *autocmd-remove*
174
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +0100175In addition to the below described commands, the |autocmd_delete()| function can
176be used to remove a list of autocmds and autocmd groups from a Vim script.
177
Bram Moolenaarfd31be22022-01-16 14:46:06 +0000178:au[tocmd]! [group] {event} {aupat} [++once] [++nested] {cmd}
Bram Moolenaar071d4272004-06-13 20:20:40 +0000179 Remove all autocommands associated with {event} and
Bram Moolenaarfd31be22022-01-16 14:46:06 +0000180 {aupat}, and add the command {cmd}.
Bram Moolenaareb93f3f2019-04-04 15:04:56 +0200181 See |autocmd-once| for [++once].
182 See |autocmd-nested| for [++nested].
Bram Moolenaar071d4272004-06-13 20:20:40 +0000183
Bram Moolenaarfd31be22022-01-16 14:46:06 +0000184:au[tocmd]! [group] {event} {aupat}
Bram Moolenaar071d4272004-06-13 20:20:40 +0000185 Remove all autocommands associated with {event} and
Bram Moolenaarfd31be22022-01-16 14:46:06 +0000186 {aupat}.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000187
Bram Moolenaarfd31be22022-01-16 14:46:06 +0000188:au[tocmd]! [group] * {aupat}
189 Remove all autocommands associated with {aupat} for
190 all events.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000191
192:au[tocmd]! [group] {event}
193 Remove ALL autocommands for {event}.
Bram Moolenaar2ec618c2016-10-01 14:47:05 +0200194 Warning: You should not do this without a group for
195 |BufRead| and other common events, it can break
196 plugins, syntax highlighting, etc.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000197
198:au[tocmd]! [group] Remove ALL autocommands.
Bram Moolenaar98ef2332018-03-18 14:44:37 +0100199 Note: a quote will be seen as argument to the :autocmd
200 and won't start a comment.
Bram Moolenaar2ec618c2016-10-01 14:47:05 +0200201 Warning: You should normally not do this without a
202 group, it breaks plugins, syntax highlighting, etc.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000203
204When the [group] argument is not given, Vim uses the current group (as defined
205with ":augroup"); otherwise, Vim uses the group defined with [group].
206
207==============================================================================
2084. Listing autocommands *autocmd-list*
209
Bram Moolenaarfd31be22022-01-16 14:46:06 +0000210:au[tocmd] [group] {event} {aupat}
Bram Moolenaar071d4272004-06-13 20:20:40 +0000211 Show the autocommands associated with {event} and
Bram Moolenaarfd31be22022-01-16 14:46:06 +0000212 {aupat}.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000213
Bram Moolenaarfd31be22022-01-16 14:46:06 +0000214:au[tocmd] [group] * {aupat}
215 Show the autocommands associated with {aupat} for all
Bram Moolenaar071d4272004-06-13 20:20:40 +0000216 events.
217
218:au[tocmd] [group] {event}
219 Show all autocommands for {event}.
220
221:au[tocmd] [group] Show all autocommands.
222
223If you provide the [group] argument, Vim lists only the autocommands for
224[group]; otherwise, Vim lists the autocommands for ALL groups. Note that this
225argument behavior differs from that for defining and removing autocommands.
226
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +0000227In order to list buffer-local autocommands, use a pattern in the form <buffer>
228or <buffer=N>. See |autocmd-buflocal|.
229
Yegappan Lakshmanan1755a912022-05-19 10:31:47 +0100230The |autocmd_get()| function can be used from a Vim script to get a list of
231autocmds.
232
Bram Moolenaarac6e65f2005-08-29 22:25:38 +0000233 *:autocmd-verbose*
234When 'verbose' is non-zero, listing an autocommand will also display where it
235was last defined. Example: >
236
237 :verbose autocmd BufEnter
238 FileExplorer BufEnter
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000239 * call s:LocalBrowse(expand("<amatch>"))
Bram Moolenaarac6e65f2005-08-29 22:25:38 +0000240 Last set from /usr/share/vim/vim-7.0/plugin/NetrwPlugin.vim
241<
242See |:verbose-cmd| for more information.
243
Bram Moolenaar071d4272004-06-13 20:20:40 +0000244==============================================================================
2455. Events *autocmd-events* *E215* *E216*
246
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000247You can specify a comma-separated list of event names. No white space can be
248used in this list. The command applies to all the events in the list.
249
250For READING FILES there are four kinds of events possible:
251 BufNewFile starting to edit a non-existent file
252 BufReadPre BufReadPost starting to edit an existing file
253 FilterReadPre FilterReadPost read the temp file with filter output
254 FileReadPre FileReadPost any other file read
255Vim uses only one of these four kinds when reading a file. The "Pre" and
256"Post" events are both triggered, before and after reading the file.
257
258Note that the autocommands for the *ReadPre events and all the Filter events
259are not allowed to change the current buffer (you will get an error message if
260this happens). This is to prevent the file to be read into the wrong buffer.
261
262Note that the 'modified' flag is reset AFTER executing the BufReadPost
263and BufNewFile autocommands. But when the 'modified' option was set by the
264autocommands, this doesn't happen.
265
266You can use the 'eventignore' option to ignore a number of events or all
267events.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000268 *autocommand-events* *{event}*
269Vim recognizes the following events. Vim ignores the case of event names
270(e.g., you can use "BUFread" or "bufread" instead of "BufRead").
271
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000272First an overview by function with a short explanation. Then the list
Bram Moolenaar551dbcc2006-04-25 22:13:59 +0000273alphabetically with full explanations |autocmd-events-abc|.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000274
275Name triggered by ~
276
277 Reading
278|BufNewFile| starting to edit a file that doesn't exist
279|BufReadPre| starting to edit a new buffer, before reading the file
280|BufRead| starting to edit a new buffer, after reading the file
281|BufReadPost| starting to edit a new buffer, after reading the file
282|BufReadCmd| before starting to edit a new buffer |Cmd-event|
283
284|FileReadPre| before reading a file with a ":read" command
285|FileReadPost| after reading a file with a ":read" command
Bram Moolenaar551dbcc2006-04-25 22:13:59 +0000286|FileReadCmd| before reading a file with a ":read" command |Cmd-event|
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000287
288|FilterReadPre| before reading a file from a filter command
289|FilterReadPost| after reading a file from a filter command
290
291|StdinReadPre| before reading from stdin into the buffer
292|StdinReadPost| After reading from the stdin into the buffer
293
294 Writing
295|BufWrite| starting to write the whole buffer to a file
296|BufWritePre| starting to write the whole buffer to a file
297|BufWritePost| after writing the whole buffer to a file
298|BufWriteCmd| before writing the whole buffer to a file |Cmd-event|
299
300|FileWritePre| starting to write part of a buffer to a file
301|FileWritePost| after writing part of a buffer to a file
302|FileWriteCmd| before writing part of a buffer to a file |Cmd-event|
303
304|FileAppendPre| starting to append to a file
305|FileAppendPost| after appending to a file
306|FileAppendCmd| before appending to a file |Cmd-event|
307
308|FilterWritePre| starting to write a file for a filter command or diff
309|FilterWritePost| after writing a file for a filter command or diff
310
311 Buffers
312|BufAdd| just after adding a buffer to the buffer list
313|BufCreate| just after adding a buffer to the buffer list
314|BufDelete| before deleting a buffer from the buffer list
315|BufWipeout| before completely deleting a buffer
316
317|BufFilePre| before changing the name of the current buffer
318|BufFilePost| after changing the name of the current buffer
319
320|BufEnter| after entering a buffer
321|BufLeave| before leaving to another buffer
322|BufWinEnter| after a buffer is displayed in a window
323|BufWinLeave| before a buffer is removed from a window
324
325|BufUnload| before unloading a buffer
Bram Moolenaarcb80aa22020-10-26 21:12:46 +0100326|BufHidden| just before a buffer becomes hidden
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000327|BufNew| just after creating a new buffer
328
329|SwapExists| detected an existing swap file
330
331 Options
332|FileType| when the 'filetype' option has been set
333|Syntax| when the 'syntax' option has been set
334|EncodingChanged| after the 'encoding' option has been changed
335|TermChanged| after the value of 'term' has changed
Bram Moolenaar53744302015-07-17 17:38:22 +0200336|OptionSet| after setting any option
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000337
338 Startup and exit
339|VimEnter| after doing all the startup stuff
340|GUIEnter| after starting the GUI successfully
Bram Moolenaard09acef2012-09-21 14:54:30 +0200341|GUIFailed| after starting the GUI failed
Bram Moolenaard7afed32007-05-06 13:26:41 +0000342|TermResponse| after the terminal response to |t_RV| is received
Danek Duvalld7d56032024-01-14 20:19:59 +0100343|TermResponseAll| after the terminal response to |t_RV| and others is received
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000344
Bram Moolenaar12a96de2018-03-11 14:44:18 +0100345|QuitPre| when using `:quit`, before deciding whether to exit
346|ExitPre| when using a command that may make Vim exit
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000347|VimLeavePre| before exiting Vim, before writing the viminfo file
348|VimLeave| before exiting Vim, after writing the viminfo file
349
Bram Moolenaar100118c2020-12-11 19:30:34 +0100350|VimSuspend| when suspending Vim
351|VimResume| when Vim is resumed after being suspended
352
Bram Moolenaar28ed4df2019-10-26 16:21:40 +0200353 Terminal
354|TerminalOpen| after a terminal buffer was created
355|TerminalWinOpen| after a terminal buffer was created in a new window
356
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000357 Various
358|FileChangedShell| Vim notices that a file changed since editing started
Bram Moolenaar7d47b6e2006-03-15 22:59:18 +0000359|FileChangedShellPost| After handling a file changed since editing started
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000360|FileChangedRO| before making the first change to a read-only file
361
Bram Moolenaar2c64ca12018-10-19 16:22:31 +0200362|DiffUpdated| after diffs have been updated
Bram Moolenaar28e8f732022-02-09 12:58:20 +0000363|DirChangedPre| before the working directory will change
Bram Moolenaarb7407d32018-02-03 17:36:27 +0100364|DirChanged| after the working directory has changed
365
Bram Moolenaara94bc432006-03-10 21:42:59 +0000366|ShellCmdPost| after executing a shell command
367|ShellFilterPost| after filtering with a shell command
368
Bram Moolenaard5005162014-08-22 23:05:54 +0200369|CmdUndefined| a user command is used but it isn't defined
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000370|FuncUndefined| a user function is used but it isn't defined
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +0000371|SpellFileMissing| a spell file is used but it can't be found
Bram Moolenaar1f35bf92006-03-07 22:38:47 +0000372|SourcePre| before sourcing a Vim script
Bram Moolenaar2a953fc2019-01-26 17:41:47 +0100373|SourcePost| after sourcing a Vim script
Bram Moolenaar8dd1aa52007-01-16 20:33:19 +0000374|SourceCmd| before sourcing a Vim script |Cmd-event|
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000375
Bram Moolenaar7d47b6e2006-03-15 22:59:18 +0000376|VimResized| after the Vim window size changed
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000377|FocusGained| Vim got input focus
378|FocusLost| Vim lost input focus
379|CursorHold| the user doesn't press a key for a while
Bram Moolenaar754b5602006-02-09 23:53:20 +0000380|CursorHoldI| the user doesn't press a key for a while in Insert mode
381|CursorMoved| the cursor was moved in Normal mode
Shougo Matsushitad0952142024-06-20 22:05:16 +0200382|CursorMovedC| the cursor was moved in the |Command-line|
Bram Moolenaar754b5602006-02-09 23:53:20 +0000383|CursorMovedI| the cursor was moved in Insert mode
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000384
Sergey Vlasov1f47db72024-01-25 23:07:00 +0100385|WinNewPre| before creating a new window
Bram Moolenaarc917da42016-07-19 22:31:36 +0200386|WinNew| after creating a new window
Bram Moolenaar12c11d52016-07-19 23:13:03 +0200387|TabNew| after creating a new tab page
naohiro ono23beefe2021-11-13 12:38:49 +0000388|WinClosed| after closing a window
Bram Moolenaar12c11d52016-07-19 23:13:03 +0200389|TabClosed| after closing a tab page
Jim Zhou5606ca52025-03-13 21:58:25 +0100390|TabClosedPre| before closing a tab page
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000391|WinEnter| after entering another window
392|WinLeave| before leaving a window
Bram Moolenaarfaa959a2006-02-20 21:37:40 +0000393|TabEnter| after entering another tab page
394|TabLeave| before leaving a tab page
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000395|CmdwinEnter| after entering the command-line window
396|CmdwinLeave| before leaving the command-line window
397
Bram Moolenaarb5b75622018-03-09 22:22:21 +0100398|CmdlineChanged| after a change was made to the command-line text
399|CmdlineEnter| after the cursor moves to the command line
400|CmdlineLeave| before the cursor leaves the command line
401
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000402|InsertEnter| starting Insert mode
403|InsertChange| when typing <Insert> while in Insert or Replace mode
404|InsertLeave| when leaving Insert mode
Bram Moolenaar938ae282023-02-20 20:44:55 +0000405|InsertLeavePre| just before leaving Insert mode
Bram Moolenaare659c952011-05-19 17:25:41 +0200406|InsertCharPre| when a character was typed in Insert mode, before
407 inserting it
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000408
=?UTF-8?q?Magnus=20Gro=C3=9F?=f1e88762021-09-12 13:39:55 +0200409|ModeChanged| after changing the mode
410
Bram Moolenaardfb18412013-12-11 18:53:29 +0100411|TextChanged| after a change was made to the text in Normal mode
412|TextChangedI| after a change was made to the text in Insert mode
Bram Moolenaar5a093432018-02-10 18:15:19 +0100413 when popup menu is not visible
414|TextChangedP| after a change was made to the text in Insert mode
415 when popup menu visible
Shougo Matsushita4ccaedf2022-10-15 11:48:00 +0100416|TextChangedT| after a change was made to the text in Terminal mode
Bram Moolenaarb477af22018-07-15 20:20:18 +0200417|TextYankPost| after text has been yanked or deleted
Bram Moolenaardfb18412013-12-11 18:53:29 +0100418
Bram Moolenaar8aeec402019-09-15 23:02:04 +0200419|SafeState| nothing pending, going to wait for the user to type a
420 character
Bram Moolenaar69198cb2019-09-16 21:58:13 +0200421|SafeStateAgain| repeated SafeState
Bram Moolenaar8aeec402019-09-15 23:02:04 +0200422
Bram Moolenaar15142e22018-04-30 22:19:58 +0200423|ColorSchemePre| before loading a color scheme
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000424|ColorScheme| after loading a color scheme
425
426|RemoteReply| a reply from a server Vim was received
427
428|QuickFixCmdPre| before a quickfix command is run
429|QuickFixCmdPost| after a quickfix command is run
430
431|SessionLoadPost| after loading a session file
432
h-east53753f62024-05-05 18:42:31 +0200433|SessionWritePost| after writing the session file using
434 the |:mksession| command
Colin Kennedye5f22802024-03-26 18:20:16 +0100435
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000436|MenuPopup| just before showing the popup menu
Bram Moolenaard7f246c2019-04-08 18:15:41 +0200437|CompleteChanged| after Insert mode completion menu changed
Bram Moolenaar3f169ce2020-01-26 22:43:31 +0100438|CompleteDonePre| after Insert mode completion is done, before clearing
439 info
440|CompleteDone| after Insert mode completion is done, after clearing
441 info
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000442
Shougo Matsushita83678842024-07-11 22:05:12 +0200443|KeyInputPre| just before a key is processed
444
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000445|User| to be used in combination with ":doautocmd"
Bram Moolenaarbe5ee862020-06-10 20:56:58 +0200446|SigUSR1| after the SIGUSR1 signal has been detected
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000447
LemonBoy09371822022-04-08 15:18:45 +0100448|WinScrolled| after scrolling or resizing a window
449
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000450
451The alphabetical list of autocommand events: *autocmd-events-abc*
452
453 *BufCreate* *BufAdd*
454BufAdd or BufCreate Just after creating a new buffer which is
455 added to the buffer list, or adding a buffer
456 to the buffer list.
457 Also used just after a buffer in the buffer
458 list has been renamed.
Bram Moolenaar469bdbd2019-12-11 23:05:48 +0100459 Not triggered for the initial buffers created
460 during startup.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000461 The BufCreate event is for historic reasons.
462 NOTE: When this autocommand is executed, the
463 current buffer "%" may be different from the
464 buffer being created "<afile>".
465 *BufDelete*
466BufDelete Before deleting a buffer from the buffer list.
467 The BufUnload may be called first (if the
468 buffer was loaded).
469 Also used just before a buffer in the buffer
470 list is renamed.
471 NOTE: When this autocommand is executed, the
472 current buffer "%" may be different from the
Bram Moolenaar446cb832008-06-24 21:56:24 +0000473 buffer being deleted "<afile>" and "<abuf>".
Bram Moolenaarb849e712009-06-24 15:51:37 +0000474 Don't change to another buffer, it will cause
475 problems.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000476 *BufEnter*
477BufEnter After entering a buffer. Useful for setting
478 options for a file type. Also executed when
479 starting to edit a buffer, after the
480 BufReadPost autocommands.
481 *BufFilePost*
482BufFilePost After changing the name of the current buffer
483 with the ":file" or ":saveas" command.
Bram Moolenaar4770d092006-01-12 23:22:24 +0000484 *BufFilePre*
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000485BufFilePre Before changing the name of the current buffer
486 with the ":file" or ":saveas" command.
487 *BufHidden*
Bram Moolenaar790c18b2019-07-04 17:22:06 +0200488BufHidden Just before a buffer becomes hidden. That is,
489 when there are no longer windows that show
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000490 the buffer, but the buffer is not unloaded or
491 deleted. Not used for ":qa" or ":q" when
492 exiting Vim.
493 NOTE: When this autocommand is executed, the
494 current buffer "%" may be different from the
495 buffer being unloaded "<afile>".
496 *BufLeave*
497BufLeave Before leaving to another buffer. Also when
498 leaving or closing the current window and the
499 new current window is not for the same buffer.
500 Not used for ":qa" or ":q" when exiting Vim.
501 *BufNew*
502BufNew Just after creating a new buffer. Also used
503 just after a buffer has been renamed. When
504 the buffer is added to the buffer list BufAdd
505 will be triggered too.
506 NOTE: When this autocommand is executed, the
507 current buffer "%" may be different from the
508 buffer being created "<afile>".
Bram Moolenaar071d4272004-06-13 20:20:40 +0000509 *BufNewFile*
510BufNewFile When starting to edit a file that doesn't
511 exist. Can be used to read in a skeleton
512 file.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000513 *BufRead* *BufReadPost*
514BufRead or BufReadPost When starting to edit a new buffer, after
515 reading the file into the buffer, before
516 executing the modelines. See |BufWinEnter|
517 for when you need to do something after
518 processing the modelines.
Bram Moolenaar75ab5902022-04-18 15:36:40 +0100519 Also triggered:
520 - when writing an unnamed buffer in a way that
521 the buffer gets a name
522 - after successfully recovering a file
523 - for the filetypedetect group when executing
524 ":filetype detect"
525 Not triggered:
526 - for the `:read file` command
527 - when the file doesn't exist
Bram Moolenaar4770d092006-01-12 23:22:24 +0000528 *BufReadCmd*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000529BufReadCmd Before starting to edit a new buffer. Should
530 read the file into the buffer. |Cmd-event|
Bram Moolenaar4770d092006-01-12 23:22:24 +0000531 *BufReadPre* *E200* *E201*
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000532BufReadPre When starting to edit a new buffer, before
533 reading the file into the buffer. Not used
534 if the file doesn't exist.
535 *BufUnload*
536BufUnload Before unloading a buffer. This is when the
537 text in the buffer is going to be freed. This
538 may be after a BufWritePost and before a
539 BufDelete. Also used for all buffers that are
540 loaded when Vim is going to exit.
541 NOTE: When this autocommand is executed, the
542 current buffer "%" may be different from the
543 buffer being unloaded "<afile>".
Bram Moolenaar64d8e252016-09-06 22:12:34 +0200544 Don't change to another buffer or window, it
545 will cause problems!
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +0200546 When exiting and v:dying is 2 or more this
547 event is not triggered.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000548 *BufWinEnter*
549BufWinEnter After a buffer is displayed in a window. This
550 can be when the buffer is loaded (after
Bram Moolenaar446cb832008-06-24 21:56:24 +0000551 processing the modelines) or when a hidden
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000552 buffer is displayed in a window (and is no
Bram Moolenaar446cb832008-06-24 21:56:24 +0000553 longer hidden).
554 Does not happen for |:split| without
555 arguments, since you keep editing the same
556 buffer, or ":split" with a file that's already
Bram Moolenaarc236c162008-07-13 17:41:49 +0000557 open in a window, because it re-uses an
558 existing buffer. But it does happen for a
559 ":split" with the name of the current buffer,
560 since it reloads that buffer.
Bram Moolenaar606cb8b2018-05-03 20:40:20 +0200561 Does not happen for a terminal window, because
562 it starts in Terminal-Job mode and Normal mode
563 commands won't work. Use |TerminalOpen| instead.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000564 *BufWinLeave*
565BufWinLeave Before a buffer is removed from a window.
566 Not when it's still visible in another window.
567 Also triggered when exiting. It's triggered
568 before BufUnload or BufHidden.
569 NOTE: When this autocommand is executed, the
570 current buffer "%" may be different from the
571 buffer being unloaded "<afile>".
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +0200572 When exiting and v:dying is 2 or more this
573 event is not triggered.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000574 *BufWipeout*
575BufWipeout Before completely deleting a buffer. The
576 BufUnload and BufDelete events may be called
577 first (if the buffer was loaded and was in the
578 buffer list). Also used just before a buffer
579 is renamed (also when it's not in the buffer
580 list).
581 NOTE: When this autocommand is executed, the
582 current buffer "%" may be different from the
583 buffer being deleted "<afile>".
Bram Moolenaarb849e712009-06-24 15:51:37 +0000584 Don't change to another buffer, it will cause
585 problems.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000586 *BufWrite* *BufWritePre*
587BufWrite or BufWritePre Before writing the whole buffer to a file.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000588 *BufWriteCmd*
589BufWriteCmd Before writing the whole buffer to a file.
590 Should do the writing of the file and reset
Bram Moolenaar1cd871b2004-12-19 22:46:22 +0000591 'modified' if successful, unless '+' is in
592 'cpo' and writing to another file |cpo-+|.
593 The buffer contents should not be changed.
Bram Moolenaar5302d9e2011-09-14 17:55:08 +0200594 When the command resets 'modified' the undo
595 information is adjusted to mark older undo
Christian Brabandtdf684192025-04-03 12:33:02 +0200596 states as 'modified', like |:write| does. Use
597 the |'[| and |']| marks for the range of lines.
Bram Moolenaar1cd871b2004-12-19 22:46:22 +0000598 |Cmd-event|
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000599 *BufWritePost*
600BufWritePost After writing the whole buffer to a file
601 (should undo the commands for BufWritePre).
Bram Moolenaard5005162014-08-22 23:05:54 +0200602 *CmdUndefined*
603CmdUndefined When a user command is used but it isn't
604 defined. Useful for defining a command only
605 when it's used. The pattern is matched
606 against the command name. Both <amatch> and
607 <afile> are set to the name of the command.
zeertzjqaf056942025-03-08 16:45:20 +0100608 This is triggered even when inside an
609 autocommand defined without |autocmd-nested|.
Bram Moolenaard5005162014-08-22 23:05:54 +0200610 NOTE: Autocompletion won't work until the
611 command is defined. An alternative is to
612 always define the user command and have it
613 invoke an autoloaded function. See |autoload|.
Bram Moolenaar153b7042018-01-31 15:48:32 +0100614 *CmdlineChanged*
Bram Moolenaarb5b75622018-03-09 22:22:21 +0100615CmdlineChanged After a change was made to the text in the
616 command line. Be careful not to mess up
617 the command line, it may cause Vim to lock up.
Bram Moolenaar153b7042018-01-31 15:48:32 +0100618 <afile> is set to a single character,
619 indicating the type of command-line.
620 |cmdwin-char|
Bram Moolenaarfafcf0d2017-10-19 18:35:51 +0200621 *CmdlineEnter*
622CmdlineEnter After moving the cursor to the command line,
623 where the user can type a command or search
Bram Moolenaar957cf672020-11-12 14:21:06 +0100624 string; including non-interactive use of ":"
625 in a mapping, but not when using |<Cmd>|.
Bram Moolenaar938ae282023-02-20 20:44:55 +0000626 The pattern is matched against the character
627 representing the type of command-line.
628 |cmdwin-char|
Bram Moolenaarfafcf0d2017-10-19 18:35:51 +0200629 <afile> is set to a single character,
630 indicating the type of command-line.
Bram Moolenaarfafcf0d2017-10-19 18:35:51 +0200631 *CmdlineLeave*
Bram Moolenaar957cf672020-11-12 14:21:06 +0100632CmdlineLeave Before leaving the command line; including
633 non-interactive use of ":" in a mapping, but
634 not when using |<Cmd>|.
Bram Moolenaar01164a62017-11-02 22:58:42 +0100635 Also when abandoning the command line, after
636 typing CTRL-C or <Esc>.
637 When the commands result in an error the
638 command line is still executed.
Bram Moolenaarfafcf0d2017-10-19 18:35:51 +0200639 <afile> is set to a single character,
640 indicating the type of command-line.
641 |cmdwin-char|
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000642 *CmdwinEnter*
643CmdwinEnter After entering the command-line window.
644 Useful for setting options specifically for
Bram Moolenaar96e38a82019-09-09 18:35:33 +0200645 this special type of window.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000646 <afile> is set to a single character,
647 indicating the type of command-line.
648 |cmdwin-char|
649 *CmdwinLeave*
650CmdwinLeave Before leaving the command-line window.
651 Useful to clean up any global setting done
Bram Moolenaar96e38a82019-09-09 18:35:33 +0200652 with CmdwinEnter.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000653 <afile> is set to a single character,
654 indicating the type of command-line.
655 |cmdwin-char|
656 *ColorScheme*
657ColorScheme After loading a color scheme. |:colorscheme|
Bram Moolenaar0daafaa2022-09-04 17:45:43 +0100658 Not triggered if the color scheme is not
659 found.
Bram Moolenaarb95186f2013-11-28 18:53:52 +0100660 The pattern is matched against the
661 colorscheme name. <afile> can be used for the
662 name of the actual file where this option was
663 set, and <amatch> for the new colorscheme
664 name.
665
Bram Moolenaar15142e22018-04-30 22:19:58 +0200666 *ColorSchemePre*
667ColorSchemePre Before loading a color scheme. |:colorscheme|
668 Useful to setup removing things added by a
669 color scheme, before another one is loaded.
Bram Moolenaar589edb32019-09-20 14:38:13 +0200670CompleteChanged *CompleteChanged*
Bram Moolenaard7f246c2019-04-08 18:15:41 +0200671 After each time the Insert mode completion
672 menu changed. Not fired on popup menu hide,
Bram Moolenaar3f169ce2020-01-26 22:43:31 +0100673 use |CompleteDonePre| or |CompleteDone| for
674 that. Never triggered recursively.
Bram Moolenaar754b5602006-02-09 23:53:20 +0000675
Bram Moolenaard7f246c2019-04-08 18:15:41 +0200676 Sets these |v:event| keys:
Bram Moolenaar911ead12019-04-21 00:03:35 +0200677 completed_item See |complete-items|.
Bram Moolenaard7f246c2019-04-08 18:15:41 +0200678 height nr of items visible
679 width screen cells
680 row top screen row
681 col leftmost screen column
682 size total nr of items
683 scrollbar TRUE if visible
684
685 It is not allowed to change the text |textlock|.
Bram Moolenaare9bd5722019-08-17 19:36:06 +0200686
687 The size and position of the popup are also
688 available by calling |pum_getpos()|.
689
Bram Moolenaar3f169ce2020-01-26 22:43:31 +0100690 *CompleteDonePre*
691CompleteDonePre After Insert mode completion is done. Either
692 when something was completed or abandoning
693 completion. |ins-completion|
694 |complete_info()| can be used, the info is
695 cleared after triggering CompleteDonePre.
696 The |v:completed_item| variable contains
697 information about the completed item.
698
Bram Moolenaar30b65812012-07-12 22:01:11 +0200699 *CompleteDone*
700CompleteDone After Insert mode completion is done. Either
701 when something was completed or abandoning
702 completion. |ins-completion|
Bram Moolenaar3f169ce2020-01-26 22:43:31 +0100703 |complete_info()| cannot be used, the info is
704 cleared before triggering CompleteDone. Use
705 CompleteDonePre if you need it.
Bram Moolenaar42a45122015-07-10 17:56:23 +0200706 The |v:completed_item| variable contains
707 information about the completed item.
Bram Moolenaar30b65812012-07-12 22:01:11 +0200708
glepnir1c5a1202024-12-04 20:27:34 +0100709 Sets these |v:event| keys:
710 complete_word The word that was
711 selected, empty if
712 abandoned complete.
713 complete_type |complete_info_mode|
714
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000715 *CursorHold*
716CursorHold When the user doesn't press a key for the time
Bram Moolenaard58a3bf2020-09-28 21:48:16 +0200717 specified with 'updatetime'. Not triggered
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000718 until the user has pressed a key (i.e. doesn't
719 fire every 'updatetime' ms if you leave Vim to
720 make some coffee. :) See |CursorHold-example|
721 for previewing tags.
722 This event is only triggered in Normal mode.
Bram Moolenaard7afed32007-05-06 13:26:41 +0000723 It is not triggered when waiting for a command
724 argument to be typed, or a movement after an
725 operator.
Bram Moolenaare3226be2005-12-18 22:10:00 +0000726 While recording the CursorHold event is not
727 triggered. |q|
Bram Moolenaar3a991dd2014-10-02 01:41:41 +0200728 *<CursorHold>*
729 Internally the autocommand is triggered by the
730 <CursorHold> key. In an expression mapping
731 |getchar()| may see this character.
732
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000733 Note: Interactive commands cannot be used for
734 this event. There is no hit-enter prompt,
735 the screen is updated directly (when needed).
736 Note: In the future there will probably be
737 another option to set the time.
738 Hint: to force an update of the status lines
739 use: >
740 :let &ro = &ro
Bram Moolenaar5666fcd2019-12-26 14:35:26 +0100741< {only on Amiga, Unix, Win32 and all GUI
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000742 versions}
Bram Moolenaar754b5602006-02-09 23:53:20 +0000743 *CursorHoldI*
744CursorHoldI Just like CursorHold, but in Insert mode.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +0200745 Not triggered when waiting for another key,
746 e.g. after CTRL-V, and not when in CTRL-X mode
747 |insert_expand|.
Bram Moolenaar754b5602006-02-09 23:53:20 +0000748
749 *CursorMoved*
Bram Moolenaar52b91d82013-06-15 21:39:51 +0200750CursorMoved After the cursor was moved in Normal or Visual
751 mode. Also when the text of the cursor line
752 has been changed, e.g., with "x", "rx" or "p".
Bram Moolenaar46eea442022-03-30 10:51:39 +0100753 Not always triggered when there is typeahead,
754 while executing commands in a script file,
755 when an operator is pending or when moving to
Bram Moolenaar90df4b92021-07-07 20:26:08 +0200756 another window while remaining at the same
757 cursor position.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +0000758 For an example see |match-parens|.
Bram Moolenaar26967612019-03-17 17:13:16 +0100759 Note: This can not be skipped with
760 `:noautocmd`.
Bram Moolenaarbf884932013-04-05 22:26:15 +0200761 Careful: This is triggered very often, don't
762 do anything that the user does not expect or
763 that is slow.
Shougo Matsushitad0952142024-06-20 22:05:16 +0200764 *CursorMovedC*
765CursorMovedC After the cursor was moved in the command
zeertzjq81456202024-07-07 20:48:25 +0200766 line. Be careful not to mess up the command
767 line, it may cause Vim to lock up.
Shougo Matsushitad0952142024-06-20 22:05:16 +0200768 <afile> is set to a single character,
769 indicating the type of command-line.
770 |cmdwin-char|
Bram Moolenaar754b5602006-02-09 23:53:20 +0000771 *CursorMovedI*
772CursorMovedI After the cursor was moved in Insert mode.
Bram Moolenaar5302d9e2011-09-14 17:55:08 +0200773 Not triggered when the popup menu is visible.
Bram Moolenaar754b5602006-02-09 23:53:20 +0000774 Otherwise the same as CursorMoved.
Bram Moolenaar75ab5902022-04-18 15:36:40 +0100775 *DiffUpdated*
776DiffUpdated After diffs have been updated. Depending on
777 what kind of diff is being used (internal or
778 external) this can be triggered on every
779 change or when doing |:diffupdate|.
780 *DirChangedPre*
781DirChangedPre The working directory is going to be changed,
782 as with |DirChanged|. The pattern is like
783 with |DirChanged|. The new directory can be
784 found in v:event.directory.
785 *DirChanged*
786DirChanged The working directory has changed in response
787 to the |:cd| or |:tcd| or |:lcd| commands, or
788 as a result of the 'autochdir' option.
789 The pattern can be:
790 "window" to trigger on `:lcd`
791 "tabpage" to trigger on `:tcd`
792 "global" to trigger on `:cd`
793 "auto" to trigger on 'autochdir'.
794 "drop" to trigger on editing a file
795 <afile> is set to the new directory name.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000796 *EncodingChanged*
797EncodingChanged Fires off after the 'encoding' option has been
798 changed. Useful to set up fonts, for example.
Bram Moolenaar75ab5902022-04-18 15:36:40 +0100799 *ExitPre*
800ExitPre When using `:quit`, `:wq` in a way it makes
801 Vim exit, or using `:qall`, just after
802 |QuitPre|. Can be used to close any
803 non-essential window. Exiting may still be
804 cancelled if there is a modified buffer that
805 isn't automatically saved, use |VimLeavePre|
806 for really exiting.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000807 *FileAppendCmd*
808FileAppendCmd Before appending to a file. Should do the
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000809 appending to the file. Use the '[ and ']
Bram Moolenaar22863042021-10-16 15:23:36 +0100810 marks for the range of lines. |Cmd-event|
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000811 *FileAppendPost*
812FileAppendPost After appending to a file.
813 *FileAppendPre*
814FileAppendPre Before appending to a file. Use the '[ and ']
815 marks for the range of lines.
816 *FileChangedRO*
817FileChangedRO Before making the first change to a read-only
818 file. Can be used to check-out the file from
819 a source control system. Not triggered when
820 the change was caused by an autocommand.
821 This event is triggered when making the first
822 change in a buffer or the first change after
Bram Moolenaar61660ea2006-04-07 21:40:07 +0000823 'readonly' was set, just before the change is
824 applied to the text.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000825 WARNING: If the autocommand moves the cursor
826 the effect of the change is undefined.
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000827 *E788*
828 It is not allowed to change to another buffer
829 here. You can reload the buffer but not edit
830 another one.
Bram Moolenaar92dff182014-02-11 19:15:50 +0100831 *E881*
832 If the number of lines changes saving for undo
833 may fail and the change will be aborted.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000834 *FileChangedShell*
835FileChangedShell When Vim notices that the modification time of
836 a file has changed since editing started.
837 Also when the file attributes of the file
Bram Moolenaare968e362014-05-13 20:23:24 +0200838 change or when the size of the file changes.
839 |timestamp|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000840 Mostly triggered after executing a shell
841 command, but also with a |:checktime| command
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +0200842 or when gvim regains input focus.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000843 This autocommand is triggered for each changed
844 file. It is not used when 'autoread' is set
845 and the buffer was not changed. If a
846 FileChangedShell autocommand is present the
847 warning message and prompt is not given.
Bram Moolenaar19a09a12005-03-04 23:39:37 +0000848 The |v:fcs_reason| variable is set to indicate
849 what happened and |v:fcs_choice| can be used
850 to tell Vim what to do next.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000851 NOTE: When this autocommand is executed, the
852 current buffer "%" may be different from the
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +0200853 buffer that was changed, which is in "<afile>".
Bram Moolenaar071d4272004-06-13 20:20:40 +0000854 NOTE: The commands must not change the current
855 buffer, jump to another buffer or delete a
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100856 buffer. *E246* *E811*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000857 NOTE: This event never nests, to avoid an
858 endless loop. This means that while executing
859 commands for the FileChangedShell event no
860 other FileChangedShell event will be
861 triggered.
Bram Moolenaar7d47b6e2006-03-15 22:59:18 +0000862 *FileChangedShellPost*
863FileChangedShellPost After handling a file that was changed outside
864 of Vim. Can be used to update the statusline.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000865 *FileEncoding*
866FileEncoding Obsolete. It still works and is equivalent
867 to |EncodingChanged|.
868 *FileReadCmd*
869FileReadCmd Before reading a file with a ":read" command.
870 Should do the reading of the file. |Cmd-event|
871 *FileReadPost*
872FileReadPost After reading a file with a ":read" command.
873 Note that Vim sets the '[ and '] marks to the
874 first and last line of the read. This can be
875 used to operate on the lines just read.
876 *FileReadPre*
877FileReadPre Before reading a file with a ":read" command.
878 *FileType*
Bram Moolenaard7afed32007-05-06 13:26:41 +0000879FileType When the 'filetype' option has been set. The
880 pattern is matched against the filetype.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000881 <afile> can be used for the name of the file
882 where this option was set, and <amatch> for
Bram Moolenaar74675a62017-07-15 13:53:23 +0200883 the new value of 'filetype'. Navigating to
884 another window or buffer is not allowed.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000885 See |filetypes|.
886 *FileWriteCmd*
887FileWriteCmd Before writing to a file, when not writing the
888 whole buffer. Should do the writing to the
889 file. Should not change the buffer. Use the
Christian Brabandtdf684192025-04-03 12:33:02 +0200890 |'[| and |']| marks for the range of lines.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000891 |Cmd-event|
892 *FileWritePost*
893FileWritePost After writing to a file, when not writing the
894 whole buffer.
895 *FileWritePre*
896FileWritePre Before writing to a file, when not writing the
Christian Brabandtdf684192025-04-03 12:33:02 +0200897 whole buffer. Use the |'[| and |']| marks for the
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000898 range of lines.
899 *FilterReadPost*
900FilterReadPost After reading a file from a filter command.
901 Vim checks the pattern against the name of
902 the current buffer as with FilterReadPre.
903 Not triggered when 'shelltemp' is off.
904 *FilterReadPre* *E135*
905FilterReadPre Before reading a file from a filter command.
906 Vim checks the pattern against the name of
907 the current buffer, not the name of the
908 temporary file that is the output of the
909 filter command.
910 Not triggered when 'shelltemp' is off.
911 *FilterWritePost*
912FilterWritePost After writing a file for a filter command or
Bram Moolenaar4c05fa02019-01-01 15:32:17 +0100913 making a diff with an external diff (see
Bram Moolenaar22863042021-10-16 15:23:36 +0100914 |DiffUpdated| for internal diff).
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000915 Vim checks the pattern against the name of
916 the current buffer as with FilterWritePre.
917 Not triggered when 'shelltemp' is off.
918 *FilterWritePre*
919FilterWritePre Before writing a file for a filter command or
Bram Moolenaar4c05fa02019-01-01 15:32:17 +0100920 making a diff with an external diff.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000921 Vim checks the pattern against the name of
922 the current buffer, not the name of the
923 temporary file that is the output of the
924 filter command.
925 Not triggered when 'shelltemp' is off.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000926 *FocusGained*
927FocusGained When Vim got input focus. Only for the GUI
928 version and a few console versions where this
Christian Brabandt49ddeef2024-07-07 20:29:43 +0200929 can be detected. |xterm-focus-event|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000930 *FocusLost*
931FocusLost When Vim lost input focus. Only for the GUI
932 version and a few console versions where this
Christian Brabandt49ddeef2024-07-07 20:29:43 +0200933 can be detected. |xterm-focus-event|
934 May also happen when a dialog pops up.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000935 *FuncUndefined*
936FuncUndefined When a user function is used but it isn't
937 defined. Useful for defining a function only
Bram Moolenaard7afed32007-05-06 13:26:41 +0000938 when it's used. The pattern is matched
939 against the function name. Both <amatch> and
940 <afile> are set to the name of the function.
zeertzjqaf056942025-03-08 16:45:20 +0100941 This is triggered even when inside an
942 autocommand defined without |autocmd-nested|,
943 but not triggered when compiling a |Vim9|
Bram Moolenaar4072ba52020-12-23 13:56:35 +0100944 function.
Bram Moolenaard5005162014-08-22 23:05:54 +0200945 NOTE: When writing Vim scripts a better
946 alternative is to use an autoloaded function.
Bram Moolenaar7c626922005-02-07 22:01:03 +0000947 See |autoload-functions|.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000948 *GUIEnter*
949GUIEnter After starting the GUI successfully, and after
950 opening the window. It is triggered before
951 VimEnter when using gvim. Can be used to
952 position the window from a .gvimrc file: >
953 :autocmd GUIEnter * winpos 100 50
Bram Moolenaard7afed32007-05-06 13:26:41 +0000954< *GUIFailed*
955GUIFailed After starting the GUI failed. Vim may
956 continue to run in the terminal, if possible
957 (only on Unix and alikes, when connecting the
958 X server fails). You may want to quit Vim: >
959 :autocmd GUIFailed * qall
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000960< *InsertChange*
961InsertChange When typing <Insert> while in Insert or
962 Replace mode. The |v:insertmode| variable
963 indicates the new mode.
964 Be careful not to move the cursor or do
965 anything else that the user does not expect.
Bram Moolenaare659c952011-05-19 17:25:41 +0200966 *InsertCharPre*
967InsertCharPre When a character is typed in Insert mode,
968 before inserting the char.
969 The |v:char| variable indicates the char typed
970 and can be changed during the event to insert
971 a different character. When |v:char| is set
972 to more than one character this text is
973 inserted literally.
974 It is not allowed to change the text |textlock|.
975 The event is not triggered when 'paste' is
Bram Moolenaarb5b75622018-03-09 22:22:21 +0100976 set. {only with the +eval feature}
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000977 *InsertEnter*
Bram Moolenaard7afed32007-05-06 13:26:41 +0000978InsertEnter Just before starting Insert mode. Also for
979 Replace mode and Virtual Replace mode. The
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000980 |v:insertmode| variable indicates the mode.
Bram Moolenaar097c9922013-05-19 21:15:15 +0200981 Be careful not to do anything else that the
982 user does not expect.
983 The cursor is restored afterwards. If you do
984 not want that set |v:char| to a non-empty
985 string.
Bram Moolenaarb53e13a2020-10-21 12:19:53 +0200986 *InsertLeavePre*
987InsertLeavePre Just before leaving Insert mode. Also when
Bram Moolenaarcb80aa22020-10-26 21:12:46 +0100988 using CTRL-O |i_CTRL-O|. Be careful not to
Bram Moolenaarb53e13a2020-10-21 12:19:53 +0200989 change mode or use `:normal`, it will likely
990 cause trouble.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000991 *InsertLeave*
Bram Moolenaarb53e13a2020-10-21 12:19:53 +0200992InsertLeave Just after leaving Insert mode. Also when
993 using CTRL-O |i_CTRL-O|. But not for |i_CTRL-C|.
Shougo Matsushita83678842024-07-11 22:05:12 +0200994 *KeyInputPre*
Shougo Matsushitafcc1b572024-07-17 20:25:22 +0200995KeyInputPre Just before a key is processed after mappings
996 have been applied. The pattern is matched
997 against a string that indicates the current
998 mode, which is the same as what is returned by
999 `mode(1)`.
Shougo Matsushita83678842024-07-11 22:05:12 +02001000 The |v:char| variable indicates the key typed
1001 and can be changed during the event to process
1002 a different key. When |v:char| is not a
1003 single character or a special key, the first
1004 character is used.
1005 The following values of |v:event| are set:
1006 typed The key is typed or not.
Shougo Matsushita890f97c2024-08-18 16:57:04 +02001007 typedchar The (actual) typed key since
1008 the last |KeyInputPre| call.
1009 Note: "typedchar" may be empty if successive
1010 |KeyInputPre| autocmds are processed.
Shougo Matsushita83678842024-07-11 22:05:12 +02001011 It is not allowed to change the text
1012 |textlock| or the current mode.
1013 {only with the +eval feature}
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001014 *MenuPopup*
1015MenuPopup Just before showing the popup menu (under the
1016 right mouse button). Useful for adjusting the
1017 menu for what is under the cursor or mouse
1018 pointer.
Bram Moolenaar4c5d8152018-10-19 22:36:53 +02001019 The pattern is matched against one or two
1020 characters representing the mode:
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001021 n Normal
1022 v Visual
1023 o Operator-pending
1024 i Insert
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00001025 c Command line
Bram Moolenaar4c5d8152018-10-19 22:36:53 +02001026 tl Terminal
=?UTF-8?q?Magnus=20Gro=C3=9F?=f1e88762021-09-12 13:39:55 +02001027 *ModeChanged*
1028ModeChanged After changing the mode. The pattern is
1029 matched against `'old_mode:new_mode'`, for
=?UTF-8?q?Magnus=20Gro=C3=9F?=25def2c2021-10-22 18:56:39 +01001030 example match against `*:c*` to simulate
1031 |CmdlineEnter|.
=?UTF-8?q?Magnus=20Gro=C3=9F?=f1e88762021-09-12 13:39:55 +02001032 The following values of |v:event| are set:
1033 old_mode The mode before it changed.
1034 new_mode The new mode as also returned
=?UTF-8?q?Magnus=20Gro=C3=9F?=25def2c2021-10-22 18:56:39 +01001035 by |mode()| called with a
1036 non-zero argument.
=?UTF-8?q?Magnus=20Gro=C3=9F?=f1e88762021-09-12 13:39:55 +02001037 When ModeChanged is triggered, old_mode will
1038 have the value of new_mode when the event was
1039 last triggered.
=?UTF-8?q?Magnus=20Gro=C3=9F?=25def2c2021-10-22 18:56:39 +01001040 This will be triggered on every minor mode
1041 change.
=?UTF-8?q?Magnus=20Gro=C3=9F?=f1e88762021-09-12 13:39:55 +02001042 Usage example to use relative line numbers
Bram Moolenaar6e649222021-10-04 21:32:54 +01001043 when entering Visual mode: >
=?UTF-8?q?Magnus=20Gro=C3=9F?=25def2c2021-10-22 18:56:39 +01001044 :au ModeChanged [vV\x16]*:* let &l:rnu = mode() =~# '^[vV\x16]'
1045 :au ModeChanged *:[vV\x16]* let &l:rnu = mode() =~# '^[vV\x16]'
1046 :au WinEnter,WinLeave * let &l:rnu = mode() =~# '^[vV\x16]'
=?UTF-8?q?Magnus=20Gro=C3=9F?=f1e88762021-09-12 13:39:55 +02001047< *OptionSet*
Bram Moolenaar53744302015-07-17 17:38:22 +02001048OptionSet After setting an option. The pattern is
1049 matched against the long option name.
Bram Moolenaard7c96872019-06-15 17:12:48 +02001050 |<amatch>| indicates what option has been set.
Bram Moolenaar53744302015-07-17 17:38:22 +02001051
Bram Moolenaard7c96872019-06-15 17:12:48 +02001052 |v:option_type| indicates whether it's global
Bram Moolenaar6c1e1572019-06-22 02:13:00 +02001053 or local scoped.
Bram Moolenaard7c96872019-06-15 17:12:48 +02001054 |v:option_command| indicates what type of
1055 set/let command was used (follow the tag to
1056 see the table).
1057 |v:option_new| indicates the newly set value.
Bram Moolenaar6c1e1572019-06-22 02:13:00 +02001058 |v:option_oldlocal| has the old local value.
1059 |v:option_oldglobal| has the old global value.
Bram Moolenaard7c96872019-06-15 17:12:48 +02001060 |v:option_old| indicates the old option value.
1061
1062 |v:option_oldlocal| is only set when |:set|
1063 or |:setlocal| or a |modeline| was used to set
1064 the option. Similarly |v:option_oldglobal| is
1065 only set when |:set| or |:setglobal| was used.
1066
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01001067 This does not set |<abuf>|, you could use
1068 |bufnr()|.
1069
Bram Moolenaard7c96872019-06-15 17:12:48 +02001070 Note that when setting a |global-local| string
1071 option with |:set|, then |v:option_old| is the
1072 old global value. However, for all other kinds
1073 of options (local string options, global-local
1074 number options, ...) it is the old local
1075 value.
1076
1077 OptionSet is not triggered on startup and for
1078 the 'key' option for obvious reasons.
Bram Moolenaar53744302015-07-17 17:38:22 +02001079
Bram Moolenaarf9132812015-07-21 19:19:13 +02001080 Usage example: Check for the existence of the
1081 directory in the 'backupdir' and 'undodir'
1082 options, create the directory if it doesn't
1083 exist yet.
1084
1085 Note: It's a bad idea to reset an option
1086 during this autocommand, this may break a
1087 plugin. You can always use `:noa` to prevent
1088 triggering this autocommand.
Bram Moolenaar53744302015-07-17 17:38:22 +02001089
Bram Moolenaar95bafa22018-10-02 13:26:25 +02001090 When using |:set| in the autocommand the event
1091 is not triggered again.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001092 *QuickFixCmdPre*
1093QuickFixCmdPre Before a quickfix command is run (|:make|,
Bram Moolenaara6557602006-02-04 22:43:20 +00001094 |:lmake|, |:grep|, |:lgrep|, |:grepadd|,
1095 |:lgrepadd|, |:vimgrep|, |:lvimgrep|,
Bram Moolenaar6be7f872012-01-20 21:08:56 +01001096 |:vimgrepadd|, |:lvimgrepadd|, |:cscope|,
Bram Moolenaar84f72352012-03-11 15:57:40 +01001097 |:cfile|, |:cgetfile|, |:caddfile|, |:lfile|,
1098 |:lgetfile|, |:laddfile|, |:helpgrep|,
Bram Moolenaar64d8e252016-09-06 22:12:34 +02001099 |:lhelpgrep|, |:cexpr|, |:cgetexpr|,
1100 |:caddexpr|, |:cbuffer|, |:cgetbuffer|,
1101 |:caddbuffer|).
Bram Moolenaarf1eeae92010-05-14 23:14:42 +02001102 The pattern is matched against the command
1103 being run. When |:grep| is used but 'grepprg'
1104 is set to "internal" it still matches "grep".
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001105 This command cannot be used to set the
1106 'makeprg' and 'grepprg' variables.
1107 If this command causes an error, the quickfix
1108 command is not executed.
1109 *QuickFixCmdPost*
1110QuickFixCmdPost Like QuickFixCmdPre, but after a quickfix
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00001111 command is run, before jumping to the first
Bram Moolenaar8ec1f852012-03-07 20:13:49 +01001112 location. For |:cfile| and |:lfile| commands
Bram Moolenaarb59ae592022-11-23 23:46:31 +00001113 it is run after the error file is read and
1114 before moving to the first error.
Bram Moolenaar8ec1f852012-03-07 20:13:49 +01001115 See |QuickFixCmdPost-example|.
Bram Moolenaar30b65812012-07-12 22:01:11 +02001116 *QuitPre*
Bram Moolenaarac7bd632013-03-19 11:35:58 +01001117QuitPre When using `:quit`, `:wq` or `:qall`, before
1118 deciding whether it closes the current window
Bram Moolenaard2ea7cf2021-05-30 20:54:13 +02001119 or quits Vim. For `:wq` the buffer is written
1120 before QuitPre is triggered. Can be used to
1121 close any non-essential window if the current
1122 window is the last ordinary window.
Bram Moolenaar12a96de2018-03-11 14:44:18 +01001123 Also see |ExitPre|.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001124 *RemoteReply*
1125RemoteReply When a reply from a Vim that functions as
Bram Moolenaard7afed32007-05-06 13:26:41 +00001126 server was received |server2client()|. The
1127 pattern is matched against the {serverid}.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001128 <amatch> is equal to the {serverid} from which
1129 the reply was sent, and <afile> is the actual
1130 reply string.
1131 Note that even if an autocommand is defined,
1132 the reply should be read with |remote_read()|
1133 to consume it.
Bram Moolenaar8aeec402019-09-15 23:02:04 +02001134 *SafeState*
1135SafeState When nothing is pending, going to wait for the
1136 user to type a character.
1137 This will not be triggered when:
1138 - an operator is pending
1139 - a register was entered with "r
1140 - halfway executing a command
1141 - executing a mapping
1142 - there is typeahead
1143 - Insert mode completion is active
1144 - Command line completion is active
1145 You can use `mode()` to find out what state
1146 Vim is in. That may be:
zeertzjqe13b6652024-01-24 03:39:04 +08001147 - Visual mode
Bram Moolenaar8aeec402019-09-15 23:02:04 +02001148 - Normal mode
1149 - Insert mode
1150 - Command-line mode
1151 Depending on what you want to do, you may also
1152 check more with `state()`, e.g. whether the
1153 screen was scrolled for messages.
Bram Moolenaar69198cb2019-09-16 21:58:13 +02001154 *SafeStateAgain*
1155SafeStateAgain Like SafeState but after processing any
1156 messages and invoking callbacks. This may be
1157 triggered often, don't do something that takes
1158 time.
Bram Moolenaar8aeec402019-09-15 23:02:04 +02001159
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001160 *SessionLoadPost*
1161SessionLoadPost After loading the session file created using
1162 the |:mksession| command.
Colin Kennedye5f22802024-03-26 18:20:16 +01001163 *SessionWritePost*
1164SessionWritePost After writing a session file by calling
1165 the |:mksession| command.
Bram Moolenaara94bc432006-03-10 21:42:59 +00001166 *ShellCmdPost*
1167ShellCmdPost After executing a shell command with |:!cmd|,
1168 |:shell|, |:make| and |:grep|. Can be used to
1169 check for any changed files.
1170 *ShellFilterPost*
1171ShellFilterPost After executing a shell command with
1172 ":{range}!cmd", ":w !cmd" or ":r !cmd".
1173 Can be used to check for any changed files.
Bram Moolenaar1f35bf92006-03-07 22:38:47 +00001174 *SourcePre*
1175SourcePre Before sourcing a Vim script. |:source|
Bram Moolenaar8dd1aa52007-01-16 20:33:19 +00001176 <afile> is the name of the file being sourced.
Bram Moolenaar2b618522019-01-12 13:26:03 +01001177 *SourcePost*
1178SourcePost After sourcing a Vim script. |:source|
1179 <afile> is the name of the file being sourced.
1180 Not triggered when sourcing was interrupted.
1181 Also triggered after a SourceCmd autocommand
1182 was triggered.
Bram Moolenaar8dd1aa52007-01-16 20:33:19 +00001183 *SourceCmd*
1184SourceCmd When sourcing a Vim script. |:source|
1185 <afile> is the name of the file being sourced.
1186 The autocommand must source this file.
1187 |Cmd-event|
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +00001188 *SpellFileMissing*
1189SpellFileMissing When trying to load a spell checking file and
Bram Moolenaar8dd1aa52007-01-16 20:33:19 +00001190 it can't be found. The pattern is matched
1191 against the language. <amatch> is the
1192 language, 'encoding' also matters. See
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +00001193 |spell-SpellFileMissing|.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001194 *StdinReadPost*
1195StdinReadPost After reading from the stdin into the buffer,
1196 before executing the modelines. Only used
1197 when the "-" argument was used when Vim was
1198 started |--|.
1199 *StdinReadPre*
1200StdinReadPre Before reading from stdin into the buffer.
1201 Only used when the "-" argument was used when
1202 Vim was started |--|.
1203 *SwapExists*
1204SwapExists Detected an existing swap file when starting
1205 to edit a file. Only when it is possible to
1206 select a way to handle the situation, when Vim
1207 would ask the user what to do.
1208 The |v:swapname| variable holds the name of
Bram Moolenaarb3480382005-12-11 21:33:32 +00001209 the swap file found, <afile> the file being
1210 edited. |v:swapcommand| may contain a command
1211 to be executed in the opened file.
1212 The commands should set the |v:swapchoice|
1213 variable to a string with one character to
1214 tell Vim what should be done next:
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001215 'o' open read-only
1216 'e' edit the file anyway
1217 'r' recover
1218 'd' delete the swap file
1219 'q' quit, don't edit the file
1220 'a' abort, like hitting CTRL-C
1221 When set to an empty string the user will be
1222 asked, as if there was no SwapExists autocmd.
Bram Moolenaarb849e712009-06-24 15:51:37 +00001223 *E812*
1224 It is not allowed to change to another buffer,
1225 change a buffer name or change directory
1226 here.
Bram Moolenaarb5b75622018-03-09 22:22:21 +01001227 {only available with the +eval feature}
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001228 *Syntax*
Bram Moolenaard7afed32007-05-06 13:26:41 +00001229Syntax When the 'syntax' option has been set. The
1230 pattern is matched against the syntax name.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001231 <afile> can be used for the name of the file
1232 where this option was set, and <amatch> for
1233 the new value of 'syntax'.
1234 See |:syn-on|.
Bram Moolenaar12c11d52016-07-19 23:13:03 +02001235 *TabClosed*
1236TabClosed After closing a tab page.
Jim Zhou5606ca52025-03-13 21:58:25 +01001237 *TabClosedPre*
1238TabClosedPre Before closing a tab page. The window layout
1239 is locked, thus opening and closing of windows
1240 is prohibited.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00001241 *TabEnter*
1242TabEnter Just after entering a tab page. |tab-page|
Bram Moolenaar56a907a2006-05-06 21:44:30 +00001243 After triggering the WinEnter and before
1244 triggering the BufEnter event.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00001245 *TabLeave*
1246TabLeave Just before leaving a tab page. |tab-page|
1247 A WinLeave event will have been triggered
1248 first.
Bram Moolenaarc917da42016-07-19 22:31:36 +02001249 *TabNew*
1250TabNew When a tab page was created. |tab-page|
1251 A WinEnter event will have been triggered
1252 first, TabEnter follows.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001253 *TermChanged*
1254TermChanged After the value of 'term' has changed. Useful
1255 for re-loading the syntax file to update the
1256 colors, fonts and other terminal-dependent
1257 settings. Executed for all loaded buffers.
Bram Moolenaarb852c3e2018-03-11 16:55:36 +01001258 *TerminalOpen*
1259TerminalOpen Just after a terminal buffer was created, with
1260 `:terminal` or |term_start()|. This event is
1261 triggered even if the buffer is created
1262 without a window, with the ++hidden option.
Bram Moolenaar28ed4df2019-10-26 16:21:40 +02001263 *TerminalWinOpen*
1264TerminalWinOpen Just after a terminal buffer was created, with
1265 `:terminal` or |term_start()|. This event is
1266 triggered only if the buffer is created
1267 with a window. Can be used to set window
1268 local options for the terminal window.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001269 *TermResponse*
1270TermResponse After the response to |t_RV| is received from
1271 the terminal. The value of |v:termresponse|
1272 can be used to do things depending on the
Christian Brabandt2abec432024-10-27 21:33:09 +01001273 terminal version.
1274 This is used in |defaults.vim| to detect
1275 putty terminal and set a dark background: >
1276
1277 au TermResponse *
1278 \ if v:termresponse == "\e[>0;136;0c"
1279 \ set bg=dark
1280 \ endif
1281<
1282 Note: that this event may be triggered halfway
1283 executing another event, especially if file
1284 I/O, a shell command or anything else that
1285 takes time is involved.
Danek Duvalld7d56032024-01-14 20:19:59 +01001286 *TermResponseAll*
1287TermResponseAll After the response to |t_RV|, |t_RC|, |t_RS|,
1288 |t_RB|, |t_RF|, or |t_u7| are received from
1289 the terminal. The value of |v:termresponse|,
1290 |v:termblinkresp|, |v:termstyleresp|,
1291 |v:termrbgresp|, |v:termrfgresp|, and
1292 |v:termu7resp|, correspondingly, can be used.
1293 <amatch> will be set to any of:
1294 "version",
1295 "cursorblink",
1296 "cursorshape",
1297 "background",
1298 "foreground",
1299 "ambiguouswidth"
1300 Note that this event may be triggered halfway
1301 executing another event, especially if file I/O,
1302 a shell command or anything else that takes time
1303 is involved.
Bram Moolenaarbf884932013-04-05 22:26:15 +02001304 *TextChanged*
1305TextChanged After a change was made to the text in the
Bram Moolenaard09091d2019-01-17 16:07:22 +01001306 current buffer in Normal mode. That is after
1307 |b:changedtick| has changed (also when that
1308 happened before the TextChanged autocommand
1309 was defined).
Bram Moolenaarbf884932013-04-05 22:26:15 +02001310 Not triggered when there is typeahead or when
1311 an operator is pending.
Bram Moolenaar26967612019-03-17 17:13:16 +01001312 Note: This can not be skipped with
1313 `:noautocmd`.
Bram Moolenaarbf884932013-04-05 22:26:15 +02001314 Careful: This is triggered very often, don't
1315 do anything that the user does not expect or
1316 that is slow.
1317 *TextChangedI*
1318TextChangedI After a change was made to the text in the
1319 current buffer in Insert mode.
1320 Not triggered when the popup menu is visible.
1321 Otherwise the same as TextChanged.
Bram Moolenaar5a093432018-02-10 18:15:19 +01001322 *TextChangedP*
1323TextChangedP After a change was made to the text in the
1324 current buffer in Insert mode, only when the
1325 popup menu is visible. Otherwise the same as
1326 TextChanged.
Shougo Matsushita4ccaedf2022-10-15 11:48:00 +01001327 *TextChangedT*
1328TextChangedT After a change was made to the text in the
1329 current buffer in Terminal mode.
1330 Otherwise the same as TextChanged.
Bram Moolenaarf0b03c42017-12-17 17:17:07 +01001331 *TextYankPost*
Bram Moolenaar7e1652c2017-12-16 18:27:02 +01001332TextYankPost After text has been yanked or deleted in the
1333 current buffer. The following values of
1334 |v:event| can be used to determine the operation
1335 that triggered this autocmd:
Bram Moolenaara016eeb2022-04-09 11:37:38 +01001336 inclusive TRUE if the motion is
1337 |inclusive| else the motion is
1338 |exclusive|.
Bram Moolenaar589edb32019-09-20 14:38:13 +02001339 operator The operation performed.
1340 regcontents Text that was stored in the
Bram Moolenaar7e1652c2017-12-16 18:27:02 +01001341 register, as a list of lines,
1342 like with: >
1343 getreg(r, 1, 1)
Bram Moolenaar22863042021-10-16 15:23:36 +01001344< regname Name of the register or empty
1345 string for the unnamed
1346 register, see |registers|.
Bram Moolenaar7e1652c2017-12-16 18:27:02 +01001347 regtype Type of the register, see
1348 |getregtype()|.
Bram Moolenaar37d16732020-06-12 22:09:01 +02001349 visual True if the operation is
1350 performed on a |Visual| area.
Bram Moolenaar7e1652c2017-12-16 18:27:02 +01001351 Not triggered when |quote_| is used nor when
1352 called recursively.
1353 It is not allowed to change the buffer text,
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00001354 see |textlock|. *E1064*
Jim Zhou7db96132025-03-12 20:57:24 +01001355 Also triggered indirectly when Vim tries to
1356 become owner of the Visual selection because
1357 of setting "autoselect" for 'guioptions' or
1358 'clipboard'.
Bram Moolenaarb5b75622018-03-09 22:22:21 +01001359 {only when compiled with the +eval feature}
Bram Moolenaarbe5ee862020-06-10 20:56:58 +02001360
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001361 *User*
1362User Never executed automatically. To be used for
1363 autocommands that are only executed with
1364 ":doautocmd".
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02001365 Note that when `:doautocmd User MyEvent` is
1366 used while there are no matching autocommands,
1367 you will get an error. If you don't want
LemonBoy09371822022-04-08 15:18:45 +01001368 that, either check whether an autocommand is
1369 defined using `exists('#User#MyEvent')` or
1370 define a dummy autocommand yourself.
1371 Example: >
1372 if exists('#User#MyEvent')
1373 doautocmd User MyEvent
1374 endif
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01001375<
Bram Moolenaarbe5ee862020-06-10 20:56:58 +02001376 *SigUSR1*
1377SigUSR1 After the SIGUSR1 signal has been detected.
1378 Could be used if other ways of notifying Vim
1379 are not feasible. E.g. to check for the
1380 result of a build that takes a long time, or
1381 when a motion sensor is triggered.
1382 {only on Unix}
1383
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001384 *UserGettingBored*
Bram Moolenaarbf884932013-04-05 22:26:15 +02001385UserGettingBored When the user presses the same key 42 times.
1386 Just kidding! :-)
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001387 *VimEnter*
1388VimEnter After doing all the startup stuff, including
1389 loading .vimrc files, executing the "-c cmd"
1390 arguments, creating all windows and loading
1391 the buffers in them.
Bram Moolenaar14735512016-03-26 21:00:08 +01001392 Just before this event is triggered the
1393 |v:vim_did_enter| variable is set, so that you
1394 can do: >
1395 if v:vim_did_enter
1396 call s:init()
1397 else
Bram Moolenaar589edb32019-09-20 14:38:13 +02001398 au VimEnter * call s:init()
Bram Moolenaar14735512016-03-26 21:00:08 +01001399 endif
1400< *VimLeave*
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001401VimLeave Before exiting Vim, just after writing the
1402 .viminfo file. Executed only once, like
1403 VimLeavePre.
1404 To detect an abnormal exit use |v:dying|.
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +02001405 When v:dying is 2 or more this event is not
1406 triggered.
Bram Moolenaarf0068c52020-11-30 17:42:10 +01001407 To get the exit code use |v:exiting|.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001408 *VimLeavePre*
1409VimLeavePre Before exiting Vim, just before writing the
1410 .viminfo file. This is executed only once,
1411 if there is a match with the name of what
1412 happens to be the current buffer when exiting.
1413 Mostly useful with a "*" pattern. >
1414 :autocmd VimLeavePre * call CleanupStuff()
1415< To detect an abnormal exit use |v:dying|.
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +02001416 When v:dying is 2 or more this event is not
1417 triggered.
Bram Moolenaarf0068c52020-11-30 17:42:10 +01001418 To get the exit code use |v:exiting|.
Bram Moolenaar7d47b6e2006-03-15 22:59:18 +00001419 *VimResized*
1420VimResized After the Vim window was resized, thus 'lines'
1421 and/or 'columns' changed. Not when starting
1422 up though.
Bram Moolenaar100118c2020-12-11 19:30:34 +01001423 *VimResume*
1424VimResume When the Vim instance is resumed after being
1425 suspended and |VimSuspend| was triggered.
1426 Useful for triggering |:checktime| and ensure
1427 the buffers content did not change while Vim
1428 was suspended: >
1429 :autocmd VimResume * checktime
1430< *VimSuspend*
1431VimSuspend When the Vim instance is suspended. Only when
dbivolaruab16ad32021-12-29 19:41:47 +00001432 CTRL-Z was typed inside Vim, or when the SIGTSTP
1433 signal was sent to Vim, but not for SIGSTOP.
naohiro ono23beefe2021-11-13 12:38:49 +00001434 *WinClosed*
Bram Moolenaarb59ae592022-11-23 23:46:31 +00001435WinClosed When closing a window, just before it is
1436 removed from the window layout. The pattern
1437 is matched against the |window-ID|. Both
naohiro ono23beefe2021-11-13 12:38:49 +00001438 <amatch> and <afile> are set to the
1439 |window-ID|. Non-recursive (event cannot
1440 trigger itself).
Bram Moolenaar071d4272004-06-13 20:20:40 +00001441 *WinEnter*
1442WinEnter After entering another window. Not done for
1443 the first window, when Vim has just started.
1444 Useful for setting the window height.
1445 If the window is for another buffer, Vim
1446 executes the BufEnter autocommands after the
1447 WinEnter autocommands.
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02001448 Note: For split and tabpage commands the
1449 WinEnter event is triggered after the split
1450 or tab command but before the file is loaded.
1451
Bram Moolenaar071d4272004-06-13 20:20:40 +00001452 *WinLeave*
1453WinLeave Before leaving a window. If the window to be
1454 entered next is for a different buffer, Vim
1455 executes the BufLeave autocommands before the
1456 WinLeave autocommands (but not for ":new").
1457 Not used for ":qa" or ":q" when exiting Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001458
Sergey Vlasov1f47db72024-01-25 23:07:00 +01001459 *WinNewPre*
1460WinNewPre Before creating a new window. Triggered
1461 before commands that modify window layout by
Christian Brabandtfb3f9692024-08-11 20:09:17 +02001462 creating a split.
h-east90e1fe42024-08-12 18:26:08 +02001463 Not done when creating tab pages and for the
1464 first window, as the window structure is not
Christian Brabandtfb3f9692024-08-11 20:09:17 +02001465 initialized yet and so is generally not safe.
Sergey Vlasov1f47db72024-01-25 23:07:00 +01001466 It is not allowed to modify window layout
1467 while executing commands for the WinNewPre
1468 event.
1469 Most useful to store current window layout
1470 and compare it with the new layout after the
1471 Window has been created.
1472
Bram Moolenaar12c11d52016-07-19 23:13:03 +02001473 *WinNew*
1474WinNew When a new window was created. Not done for
Bram Moolenaar50ba5262016-09-22 22:33:02 +02001475 the first window, when Vim has just started.
Bram Moolenaar12c11d52016-07-19 23:13:03 +02001476 Before a WinEnter event.
1477
LemonBoy09371822022-04-08 15:18:45 +01001478 *WinScrolled*
Bram Moolenaar35fc61c2022-11-22 12:40:50 +00001479WinScrolled After any window in the current tab page
1480 scrolled the text (horizontally or vertically)
1481 or changed width or height. See
1482 |win-scrolled-resized|.
Bram Moolenaar0a60f792022-11-19 21:18:11 +00001483
Christian Brabandtb8d5c852025-04-04 19:11:13 +02001484 Note: This can not be skipped with
1485 `:noautocmd`, because it triggers after
1486 processing normal commands when Vim is back in
1487 the main loop. If you want to disable this,
1488 consider setting the 'eventignore' option
1489 instead.
1490
Bram Moolenaar0a60f792022-11-19 21:18:11 +00001491 The pattern is matched against the |window-ID|
1492 of the first window that scrolled or resized.
1493 Both <amatch> and <afile> are set to the
1494 |window-ID|.
1495
Bram Moolenaar35fc61c2022-11-22 12:40:50 +00001496 |v:event| is set with information about size
1497 and scroll changes. |WinScrolled-event|
1498
Bram Moolenaar0a60f792022-11-19 21:18:11 +00001499 Only starts triggering after startup finished
1500 and the first screen redraw was done.
Bram Moolenaar35fc61c2022-11-22 12:40:50 +00001501 Does not trigger when defining the first
1502 WinScrolled or WinResized event, but may
1503 trigger when adding more.
Bram Moolenaar0a60f792022-11-19 21:18:11 +00001504
1505 Non-recursive: the event will not trigger
1506 while executing commands for the WinScrolled
1507 event. However, if the command causes a
1508 window to scroll or change size, then another
LemonBoy09371822022-04-08 15:18:45 +01001509 WinScrolled event will be triggered later.
Bram Moolenaar0a60f792022-11-19 21:18:11 +00001510
Bram Moolenaar35fc61c2022-11-22 12:40:50 +00001511
1512 *WinResized*
1513WinResized After a window in the current tab page changed
1514 width or height.
1515 See |win-scrolled-resized|.
1516
1517 |v:event| is set with information about size
1518 changes. |WinResized-event|
1519
1520 Same behavior as |WinScrolled| for the
1521 pattern, triggering and recursiveness.
LemonBoy09371822022-04-08 15:18:45 +01001522
Bram Moolenaar071d4272004-06-13 20:20:40 +00001523==============================================================================
Bram Moolenaarfd31be22022-01-16 14:46:06 +000015246. Patterns *autocmd-patterns* *{aupat}*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001525
LemonBoy09371822022-04-08 15:18:45 +01001526The {aupat} argument of `:autocmd` can be a comma-separated list. This works as
Bram Moolenaarfd31be22022-01-16 14:46:06 +00001527if the command was given with each pattern separately. Thus this command: >
Bram Moolenaar5a5f4592015-04-13 12:43:06 +02001528 :autocmd BufRead *.txt,*.info set et
1529Is equivalent to: >
1530 :autocmd BufRead *.txt set et
1531 :autocmd BufRead *.info set et
1532
Bram Moolenaarfd31be22022-01-16 14:46:06 +00001533The file pattern {aupat} is tested for a match against the file name in one of
Bram Moolenaar071d4272004-06-13 20:20:40 +00001534two ways:
15351. When there is no '/' in the pattern, Vim checks for a match against only
1536 the tail part of the file name (without its leading directory path).
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010015372. When there is a '/' in the pattern, Vim checks for a match against both the
1538 short file name (as you typed it) and the full file name (after expanding
1539 it to a full path and resolving symbolic links).
Bram Moolenaar071d4272004-06-13 20:20:40 +00001540
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00001541The special pattern <buffer> or <buffer=N> is used for buffer-local
1542autocommands |autocmd-buflocal|. This pattern is not matched against the name
1543of a buffer.
1544
Bram Moolenaar071d4272004-06-13 20:20:40 +00001545Examples: >
1546 :autocmd BufRead *.txt set et
1547Set the 'et' option for all text files. >
1548
1549 :autocmd BufRead /vim/src/*.c set cindent
1550Set the 'cindent' option for C files in the /vim/src directory. >
1551
1552 :autocmd BufRead /tmp/*.c set ts=5
1553If you have a link from "/tmp/test.c" to "/home/nobody/vim/src/test.c", and
1554you start editing "/tmp/test.c", this autocommand will match.
1555
1556Note: To match part of a path, but not from the root directory, use a '*' as
1557the first character. Example: >
1558 :autocmd BufRead */doc/*.txt set tw=78
1559This autocommand will for example be executed for "/tmp/doc/xx.txt" and
1560"/usr/home/piet/doc/yy.txt". The number of directories does not matter here.
1561
1562
1563The file name that the pattern is matched against is after expanding
Bram Moolenaar446cb832008-06-24 21:56:24 +00001564wildcards. Thus if you issue this command: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001565 :e $ROOTDIR/main.$EXT
1566The argument is first expanded to: >
1567 /usr/root/main.py
1568Before it's matched with the pattern of the autocommand. Careful with this
1569when using events like FileReadCmd, the value of <amatch> may not be what you
1570expect.
1571
1572
1573Environment variables can be used in a pattern: >
1574 :autocmd BufRead $VIMRUNTIME/doc/*.txt set expandtab
1575And ~ can be used for the home directory (if $HOME is defined): >
1576 :autocmd BufWritePost ~/.vimrc so ~/.vimrc
1577 :autocmd BufRead ~archive/* set readonly
1578The environment variable is expanded when the autocommand is defined, not when
1579the autocommand is executed. This is different from the command!
1580
1581 *file-pattern*
1582The pattern is interpreted like mostly used in file names:
Bram Moolenaar3b1db362013-08-10 15:00:24 +02001583 * matches any sequence of characters; Unusual: includes path
Bram Moolenaar9d98fe92013-08-03 18:35:36 +02001584 separators
Bram Moolenaar071d4272004-06-13 20:20:40 +00001585 ? matches any single character
1586 \? matches a '?'
1587 . matches a '.'
1588 ~ matches a '~'
1589 , separates patterns
1590 \, matches a ','
1591 { } like \( \) in a |pattern|
1592 , inside { }: like \| in a |pattern|
Bram Moolenaara946afe2013-08-02 15:22:39 +02001593 \} literal }
1594 \{ literal {
1595 \\\{n,m\} like \{n,m} in a |pattern|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001596 \ special meaning like in a |pattern|
1597 [ch] matches 'c' or 'h'
1598 [^ch] match any character but 'c' and 'h'
1599
1600Note that for all systems the '/' character is used for path separator (even
Bram Moolenaar6f345a12019-12-17 21:27:18 +01001601for MS-Windows). This was done because the backslash is difficult to use in a
1602pattern and to make the autocommands portable across different systems.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001603
Bram Moolenaar64d8e252016-09-06 22:12:34 +02001604It is possible to use |pattern| items, but they may not work as expected,
1605because of the translation done for the above.
1606
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00001607 *autocmd-changes*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001608Matching with the pattern is done when an event is triggered. Changing the
1609buffer name in one of the autocommands, or even deleting the buffer, does not
1610change which autocommands will be executed. Example: >
1611
1612 au BufEnter *.foo bdel
1613 au BufEnter *.foo set modified
1614
1615This will delete the current buffer and then set 'modified' in what has become
1616the current buffer instead. Vim doesn't take into account that "*.foo"
1617doesn't match with that buffer name. It matches "*.foo" with the name of the
1618buffer at the moment the event was triggered.
1619
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00001620However, buffer-local autocommands will not be executed for a buffer that has
1621been wiped out with |:bwipe|. After deleting the buffer with |:bdel| the
1622buffer actually still exists (it becomes unlisted), thus the autocommands are
1623still executed.
1624
Bram Moolenaar071d4272004-06-13 20:20:40 +00001625==============================================================================
Bram Moolenaarc9b4b052006-04-30 18:54:39 +000016267. Buffer-local autocommands *autocmd-buflocal* *autocmd-buffer-local*
1627 *<buffer=N>* *<buffer=abuf>* *E680*
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00001628
1629Buffer-local autocommands are attached to a specific buffer. They are useful
1630if the buffer does not have a name and when the name does not match a specific
1631pattern. But it also means they must be explicitly added to each buffer.
1632
1633Instead of a pattern buffer-local autocommands use one of these forms:
1634 <buffer> current buffer
1635 <buffer=99> buffer number 99
1636 <buffer=abuf> using <abuf> (only when executing autocommands)
1637 |<abuf>|
1638
1639Examples: >
1640 :au CursorHold <buffer> echo 'hold'
1641 :au CursorHold <buffer=33> echo 'hold'
Bram Moolenaar88774fd2015-08-25 19:52:04 +02001642 :au BufNewFile * au CursorHold <buffer=abuf> echo 'hold'
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00001643
1644All the commands for autocommands also work with buffer-local autocommands,
1645simply use the special string instead of the pattern. Examples: >
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001646 :au! * <buffer> " remove buffer-local autocommands for
1647 " current buffer
1648 :au! * <buffer=33> " remove buffer-local autocommands for
1649 " buffer #33
Bram Moolenaar446cb832008-06-24 21:56:24 +00001650 :bufdo :au! CursorHold <buffer> " remove autocmd for given event for all
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001651 " buffers
1652 :au * <buffer> " list buffer-local autocommands for
1653 " current buffer
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00001654
1655Note that when an autocommand is defined for the current buffer, it is stored
1656with the buffer number. Thus it uses the form "<buffer=12>", where 12 is the
1657number of the current buffer. You will see this when listing autocommands,
1658for example.
1659
1660To test for presence of buffer-local autocommands use the |exists()| function
1661as follows: >
1662 :if exists("#CursorHold#<buffer=12>") | ... | endif
1663 :if exists("#CursorHold#<buffer>") | ... | endif " for current buffer
1664
1665When a buffer is wiped out its buffer-local autocommands are also gone, of
1666course. Note that when deleting a buffer, e.g., with ":bdel", it is only
1667unlisted, the autocommands are still present. In order to see the removal of
1668buffer-local autocommands: >
1669 :set verbose=6
1670
1671It is not possible to define buffer-local autocommands for a non-existent
1672buffer.
1673
1674==============================================================================
16758. Groups *autocmd-groups*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001676
1677Autocommands can be put together in a group. This is useful for removing or
1678executing a group of autocommands. For example, all the autocommands for
1679syntax highlighting are put in the "highlight" group, to be able to execute
1680":doautoall highlight BufRead" when the GUI starts.
1681
1682When no specific group is selected, Vim uses the default group. The default
1683group does not have a name. You cannot execute the autocommands from the
1684default group separately; you can execute them only by executing autocommands
1685for all groups.
1686
1687Normally, when executing autocommands automatically, Vim uses the autocommands
1688for all groups. The group only matters when executing autocommands with
1689":doautocmd" or ":doautoall", or when defining or deleting autocommands.
1690
1691The group name can contain any characters except white space. The group name
1692"end" is reserved (also in uppercase).
1693
1694The group name is case sensitive. Note that this is different from the event
1695name!
1696
1697 *:aug* *:augroup*
1698:aug[roup] {name} Define the autocmd group name for the
1699 following ":autocmd" commands. The name "end"
1700 or "END" selects the default group.
Bram Moolenaar256972a2015-12-29 19:10:25 +01001701 To avoid confusion, the name should be
1702 different from existing {event} names, as this
1703 most likely will not do what you intended.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001704
Bram Moolenaar64d8e252016-09-06 22:12:34 +02001705 *:augroup-delete* *E367* *W19* *E936*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001706:aug[roup]! {name} Delete the autocmd group {name}. Don't use
1707 this if there is still an autocommand using
Bram Moolenaarbc8801c2016-08-02 21:04:33 +02001708 this group! You will get a warning if doing
Bram Moolenaare7b1ea02020-08-07 19:54:59 +02001709 it anyway. When the group is the current
1710 group you will get error E936.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001711
1712To enter autocommands for a specific group, use this method:
17131. Select the group with ":augroup {name}".
17142. Delete any old autocommands with ":au!".
17153. Define the autocommands.
17164. Go back to the default group with "augroup END".
1717
1718Example: >
1719 :augroup uncompress
1720 : au!
1721 : au BufEnter *.gz %!gunzip
1722 :augroup END
1723
1724This prevents having the autocommands defined twice (e.g., after sourcing the
1725.vimrc file again).
1726
Bram Moolenaar6e649222021-10-04 21:32:54 +01001727 *FileExplorer*
1728There is one group that is recognized by Vim: FileExplorer. If this group
1729exists Vim assumes that editing a directory is possible and will trigger a
1730plugin that lists the files in that directory. This is used by the |netrw|
1731plugin. This allows you to do: >
1732 browse edit
1733
Bram Moolenaar071d4272004-06-13 20:20:40 +00001734==============================================================================
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +000017359. Executing autocommands *autocmd-execute*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001736
1737Vim can also execute Autocommands non-automatically. This is useful if you
1738have changed autocommands, or when Vim has executed the wrong autocommands
1739(e.g., the file pattern match was wrong).
1740
1741Note that the 'eventignore' option applies here too. Events listed in this
1742option will not cause any commands to be executed.
1743
Bram Moolenaar61da1bf2019-06-06 12:14:49 +02001744 *:do* *:doau* *:doaut* *:doautocmd* *E217*
Bram Moolenaar5dc62522012-02-13 00:05:22 +01001745:do[autocmd] [<nomodeline>] [group] {event} [fname]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001746 Apply the autocommands matching [fname] (default:
1747 current file name) for {event} to the current buffer.
1748 You can use this when the current file name does not
1749 match the right pattern, after changing settings, or
1750 to execute autocommands for a certain event.
1751 It's possible to use this inside an autocommand too,
1752 so you can base the autocommands for one extension on
1753 another extension. Example: >
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01001754 :au BufEnter *.cpp so ~/.vimrc_cpp
1755 :au BufEnter *.cpp doau BufEnter x.c
Bram Moolenaar071d4272004-06-13 20:20:40 +00001756< Be careful to avoid endless loops. See
1757 |autocmd-nested|.
1758
1759 When the [group] argument is not given, Vim executes
1760 the autocommands for all groups. When the [group]
1761 argument is included, Vim executes only the matching
1762 autocommands for that group. Note: if you use an
1763 undefined group name, Vim gives you an error message.
Bram Moolenaar60542ac2012-02-12 20:14:01 +01001764 *<nomodeline>*
1765 After applying the autocommands the modelines are
1766 processed, so that their settings overrule the
1767 settings from autocommands, like what happens when
1768 editing a file. This is skipped when the <nomodeline>
1769 argument is present. You probably want to use
1770 <nomodeline> for events that are not used when loading
1771 a buffer, such as |User|.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001772 Processing modelines is also skipped when no
1773 matching autocommands were executed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001774
1775 *:doautoa* *:doautoall*
Bram Moolenaara61d5fb2012-02-12 00:18:58 +01001776:doautoa[ll] [<nomodeline>] [group] {event} [fname]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001777 Like ":doautocmd", but apply the autocommands to each
Bram Moolenaardad44732021-03-31 20:07:33 +02001778 loaded buffer. The current buffer is done last.
1779
1780 Note that [fname] is used to select the autocommands,
Bram Moolenaar4c295022021-05-02 17:19:11 +02001781 not the buffers to which they are applied. Example: >
1782 augroup mine
1783 autocmd!
1784 autocmd FileType * echo expand('<amatch>')
1785 augroup END
1786 doautoall mine FileType Loaded-Buffer
1787< Sourcing this script, you'll see as many
1788 "Loaded-Buffer" echoed as there are loaded buffers.
Bram Moolenaardad44732021-03-31 20:07:33 +02001789
Bram Moolenaar071d4272004-06-13 20:20:40 +00001790 Careful: Don't use this for autocommands that delete a
1791 buffer, change to another buffer or change the
1792 contents of a buffer; the result is unpredictable.
1793 This command is intended for autocommands that set
1794 options, change highlighting, and things like that.
1795
1796==============================================================================
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +0000179710. Using autocommands *autocmd-use*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001798
1799For WRITING FILES there are four possible sets of events. Vim uses only one
1800of these sets for a write command:
1801
1802BufWriteCmd BufWritePre BufWritePost writing the whole buffer
1803 FilterWritePre FilterWritePost writing to filter temp file
1804FileAppendCmd FileAppendPre FileAppendPost appending to a file
1805FileWriteCmd FileWritePre FileWritePost any other file write
1806
1807When there is a matching "*Cmd" autocommand, it is assumed it will do the
1808writing. No further writing is done and the other events are not triggered.
1809|Cmd-event|
1810
1811Note that the *WritePost commands should undo any changes to the buffer that
1812were caused by the *WritePre commands; otherwise, writing the file will have
1813the side effect of changing the buffer.
1814
1815Before executing the autocommands, the buffer from which the lines are to be
1816written temporarily becomes the current buffer. Unless the autocommands
1817change the current buffer or delete the previously current buffer, the
1818previously current buffer is made the current buffer again.
1819
1820The *WritePre and *AppendPre autocommands must not delete the buffer from
1821which the lines are to be written.
1822
1823The '[ and '] marks have a special position:
1824- Before the *ReadPre event the '[ mark is set to the line just above where
1825 the new lines will be inserted.
1826- Before the *ReadPost event the '[ mark is set to the first line that was
1827 just read, the '] mark to the last line.
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001828- Before executing the *WriteCmd, *WritePre and *AppendPre autocommands the '[
1829 mark is set to the first line that will be written, the '] mark to the last
1830 line.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001831Careful: '[ and '] change when using commands that change the buffer.
1832
1833In commands which expect a file name, you can use "<afile>" for the file name
1834that is being read |:<afile>| (you can also use "%" for the current file
1835name). "<abuf>" can be used for the buffer number of the currently effective
Bram Moolenaard2f3a8b2018-06-19 14:35:59 +02001836buffer. This also works for buffers that don't have a name. But it doesn't
Bram Moolenaar071d4272004-06-13 20:20:40 +00001837work for files without a buffer (e.g., with ":r file").
1838
1839 *gzip-example*
1840Examples for reading and writing compressed files: >
1841 :augroup gzip
1842 : autocmd!
1843 : autocmd BufReadPre,FileReadPre *.gz set bin
1844 : autocmd BufReadPost,FileReadPost *.gz '[,']!gunzip
1845 : autocmd BufReadPost,FileReadPost *.gz set nobin
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001846 : autocmd BufReadPost,FileReadPost *.gz execute ":doautocmd BufReadPost " .. expand("%:r")
Bram Moolenaar071d4272004-06-13 20:20:40 +00001847 : autocmd BufWritePost,FileWritePost *.gz !mv <afile> <afile>:r
1848 : autocmd BufWritePost,FileWritePost *.gz !gzip <afile>:r
1849
1850 : autocmd FileAppendPre *.gz !gunzip <afile>
1851 : autocmd FileAppendPre *.gz !mv <afile>:r <afile>
1852 : autocmd FileAppendPost *.gz !mv <afile> <afile>:r
1853 : autocmd FileAppendPost *.gz !gzip <afile>:r
1854 :augroup END
1855
1856The "gzip" group is used to be able to delete any existing autocommands with
1857":autocmd!", for when the file is sourced twice.
1858
1859("<afile>:r" is the file name without the extension, see |:_%:|)
1860
1861The commands executed for the BufNewFile, BufRead/BufReadPost, BufWritePost,
1862FileAppendPost and VimLeave events do not set or reset the changed flag of the
1863buffer. When you decompress the buffer with the BufReadPost autocommands, you
1864can still exit with ":q". When you use ":undo" in BufWritePost to undo the
1865changes made by BufWritePre commands, you can still do ":q" (this also makes
1866"ZZ" work). If you do want the buffer to be marked as modified, set the
1867'modified' option.
1868
1869To execute Normal mode commands from an autocommand, use the ":normal"
1870command. Use with care! If the Normal mode command is not finished, the user
1871needs to type characters (e.g., after ":normal m" you need to type a mark
1872name).
1873
1874If you want the buffer to be unmodified after changing it, reset the
1875'modified' option. This makes it possible to exit the buffer with ":q"
1876instead of ":q!".
1877
1878 *autocmd-nested* *E218*
Bram Moolenaar26967612019-03-17 17:13:16 +01001879By default, autocommands do not nest. For example, if you use ":e" or ":w" in
1880an autocommand, Vim does not execute the BufRead and BufWrite autocommands for
Bram Moolenaar071d4272004-06-13 20:20:40 +00001881those commands. If you do want this, use the "nested" flag for those commands
1882in which you want nesting. For example: >
Bram Moolenaareb93f3f2019-04-04 15:04:56 +02001883 :autocmd FileChangedShell *.c ++nested e!
Bram Moolenaar071d4272004-06-13 20:20:40 +00001884The nesting is limited to 10 levels to get out of recursive loops.
1885
1886It's possible to use the ":au" command in an autocommand. This can be a
1887self-modifying command! This can be useful for an autocommand that should
1888execute only once.
1889
Bram Moolenaarb3480382005-12-11 21:33:32 +00001890If you want to skip autocommands for one command, use the |:noautocmd| command
1891modifier or the 'eventignore' option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001892
1893Note: When reading a file (with ":read file" or with a filter command) and the
1894last line in the file does not have an <EOL>, Vim remembers this. At the next
1895write (with ":write file" or with a filter command), if the same line is
1896written again as the last line in a file AND 'binary' is set, Vim does not
1897supply an <EOL>. This makes a filter command on the just read lines write the
1898same file as was read, and makes a write command on just filtered lines write
1899the same file as was read from the filter. For example, another way to write
1900a compressed file: >
1901
1902 :autocmd FileWritePre *.gz set bin|'[,']!gzip
1903 :autocmd FileWritePost *.gz undo|set nobin
1904<
1905 *autocommand-pattern*
1906You can specify multiple patterns, separated by commas. Here are some
1907examples: >
1908
1909 :autocmd BufRead * set tw=79 nocin ic infercase fo=2croq
1910 :autocmd BufRead .letter set tw=72 fo=2tcrq
1911 :autocmd BufEnter .letter set dict=/usr/lib/dict/words
1912 :autocmd BufLeave .letter set dict=
1913 :autocmd BufRead,BufNewFile *.c,*.h set tw=0 cin noic
1914 :autocmd BufEnter *.c,*.h abbr FOR for (i = 0; i < 3; ++i)<CR>{<CR>}<Esc>O
1915 :autocmd BufLeave *.c,*.h unabbr FOR
1916
1917For makefiles (makefile, Makefile, imakefile, makefile.unix, etc.): >
1918
1919 :autocmd BufEnter ?akefile* set include=^s\=include
1920 :autocmd BufLeave ?akefile* set include&
1921
1922To always start editing C files at the first function: >
1923
1924 :autocmd BufRead *.c,*.h 1;/^{
1925
1926Without the "1;" above, the search would start from wherever the file was
1927entered, rather than from the start of the file.
1928
1929 *skeleton* *template*
1930To read a skeleton (template) file when opening a new file: >
1931
1932 :autocmd BufNewFile *.c 0r ~/vim/skeleton.c
1933 :autocmd BufNewFile *.h 0r ~/vim/skeleton.h
1934 :autocmd BufNewFile *.java 0r ~/vim/skeleton.java
1935
1936To insert the current date and time in a *.html file when writing it: >
1937
1938 :autocmd BufWritePre,FileWritePre *.html ks|call LastMod()|'s
1939 :fun LastMod()
1940 : if line("$") > 20
1941 : let l = 20
1942 : else
1943 : let l = line("$")
1944 : endif
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001945 : exe "1," .. l .. "g/Last modified: /s/Last modified: .*/Last modified: " ..
Bram Moolenaar071d4272004-06-13 20:20:40 +00001946 : \ strftime("%Y %b %d")
1947 :endfun
1948
1949You need to have a line "Last modified: <date time>" in the first 20 lines
1950of the file for this to work. Vim replaces <date time> (and anything in the
1951same line after it) with the current date and time. Explanation:
1952 ks mark current position with mark 's'
1953 call LastMod() call the LastMod() function to do the work
1954 's return the cursor to the old position
1955The LastMod() function checks if the file is shorter than 20 lines, and then
1956uses the ":g" command to find lines that contain "Last modified: ". For those
1957lines the ":s" command is executed to replace the existing date with the
1958current one. The ":execute" command is used to be able to use an expression
1959for the ":g" and ":s" commands. The date is obtained with the strftime()
1960function. You can change its argument to get another date string.
1961
1962When entering :autocmd on the command-line, completion of events and command
1963names may be done (with <Tab>, CTRL-D, etc.) where appropriate.
1964
1965Vim executes all matching autocommands in the order that you specify them.
1966It is recommended that your first autocommand be used for all files by using
1967"*" as the file pattern. This means that you can define defaults you like
1968here for any settings, and if there is another matching autocommand it will
1969override these. But if there is no other matching autocommand, then at least
1970your default settings are recovered (if entering this file from another for
1971which autocommands did match). Note that "*" will also match files starting
1972with ".", unlike Unix shells.
1973
1974 *autocmd-searchpat*
1975Autocommands do not change the current search patterns. Vim saves the current
1976search patterns before executing autocommands then restores them after the
1977autocommands finish. This means that autocommands do not affect the strings
1978highlighted with the 'hlsearch' option. Within autocommands, you can still
1979use search patterns normally, e.g., with the "n" command.
1980If you want an autocommand to set the search pattern, such that it is used
1981after the autocommand finishes, use the ":let @/ =" command.
1982The search-highlighting cannot be switched off with ":nohlsearch" in an
1983autocommand. Use the 'h' flag in the 'viminfo' option to disable search-
1984highlighting when starting Vim.
1985
1986 *Cmd-event*
1987When using one of the "*Cmd" events, the matching autocommands are expected to
Bram Moolenaar8dd1aa52007-01-16 20:33:19 +00001988do the file reading, writing or sourcing. This can be used when working with
1989a special kind of file, for example on a remote system.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001990CAREFUL: If you use these events in a wrong way, it may have the effect of
1991making it impossible to read or write the matching files! Make sure you test
1992your autocommands properly. Best is to use a pattern that will never match a
1993normal file name, for example "ftp://*".
1994
1995When defining a BufReadCmd it will be difficult for Vim to recover a crashed
1996editing session. When recovering from the original file, Vim reads only those
1997parts of a file that are not found in the swap file. Since that is not
1998possible with a BufReadCmd, use the |:preserve| command to make sure the
1999original file isn't needed for recovery. You might want to do this only when
2000you expect the file to be modified.
2001
Bram Moolenaar8dd1aa52007-01-16 20:33:19 +00002002For file read and write commands the |v:cmdarg| variable holds the "++enc="
2003and "++ff=" argument that are effective. These should be used for the command
2004that reads/writes the file. The |v:cmdbang| variable is one when "!" was
2005used, zero otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002006
Bram Moolenaarc88ebf72010-07-22 22:30:23 +02002007See the $VIMRUNTIME/plugin/netrwPlugin.vim for examples.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002008
Bram Moolenaarb3480382005-12-11 21:33:32 +00002009==============================================================================
201011. Disabling autocommands *autocmd-disable*
2011
2012To disable autocommands for some time use the 'eventignore' option. Note that
2013this may cause unexpected behavior, make sure you restore 'eventignore'
2014afterwards, using a |:try| block with |:finally|.
2015
Luuk van Baalb7147f82025-02-08 18:52:39 +01002016To disable autocmds indefinitely in a specific window use the 'eventignorewin'
2017option. This can only be used to ignore window and buffer related events.
2018
Bram Moolenaarb3480382005-12-11 21:33:32 +00002019 *:noautocmd* *:noa*
2020To disable autocommands for just one command use the ":noautocmd" command
2021modifier. This will set 'eventignore' to "all" for the duration of the
2022following command. Example: >
2023
2024 :noautocmd w fname.gz
2025
2026This will write the file without triggering the autocommands defined by the
2027gzip plugin.
2028
Bram Moolenaar26967612019-03-17 17:13:16 +01002029Note that some autocommands are not triggered right away, but only later.
2030This specifically applies to |CursorMoved| and |TextChanged|.
2031
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00002032
Bram Moolenaar91f84f62018-07-29 15:07:52 +02002033 vim:tw=78:ts=8:noet:ft=help:norl: