blob: f200a30e5025bdd58daf000e92eb6ab967c824b1 [file] [log] [blame]
Shougo Matsushita890f97c2024-08-18 16:57:04 +02001*autocmd.txt* For Vim version 9.1. Last change: 2024 Aug 18
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
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000390|WinEnter| after entering another window
391|WinLeave| before leaving a window
Bram Moolenaarfaa959a2006-02-20 21:37:40 +0000392|TabEnter| after entering another tab page
393|TabLeave| before leaving a tab page
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000394|CmdwinEnter| after entering the command-line window
395|CmdwinLeave| before leaving the command-line window
396
Bram Moolenaarb5b75622018-03-09 22:22:21 +0100397|CmdlineChanged| after a change was made to the command-line text
398|CmdlineEnter| after the cursor moves to the command line
399|CmdlineLeave| before the cursor leaves the command line
400
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000401|InsertEnter| starting Insert mode
402|InsertChange| when typing <Insert> while in Insert or Replace mode
403|InsertLeave| when leaving Insert mode
Bram Moolenaar938ae282023-02-20 20:44:55 +0000404|InsertLeavePre| just before leaving Insert mode
Bram Moolenaare659c952011-05-19 17:25:41 +0200405|InsertCharPre| when a character was typed in Insert mode, before
406 inserting it
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000407
=?UTF-8?q?Magnus=20Gro=C3=9F?=f1e88762021-09-12 13:39:55 +0200408|ModeChanged| after changing the mode
409
Bram Moolenaardfb18412013-12-11 18:53:29 +0100410|TextChanged| after a change was made to the text in Normal mode
411|TextChangedI| after a change was made to the text in Insert mode
Bram Moolenaar5a093432018-02-10 18:15:19 +0100412 when popup menu is not visible
413|TextChangedP| after a change was made to the text in Insert mode
414 when popup menu visible
Shougo Matsushita4ccaedf2022-10-15 11:48:00 +0100415|TextChangedT| after a change was made to the text in Terminal mode
Bram Moolenaarb477af22018-07-15 20:20:18 +0200416|TextYankPost| after text has been yanked or deleted
Bram Moolenaardfb18412013-12-11 18:53:29 +0100417
Bram Moolenaar8aeec402019-09-15 23:02:04 +0200418|SafeState| nothing pending, going to wait for the user to type a
419 character
Bram Moolenaar69198cb2019-09-16 21:58:13 +0200420|SafeStateAgain| repeated SafeState
Bram Moolenaar8aeec402019-09-15 23:02:04 +0200421
Bram Moolenaar15142e22018-04-30 22:19:58 +0200422|ColorSchemePre| before loading a color scheme
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000423|ColorScheme| after loading a color scheme
424
425|RemoteReply| a reply from a server Vim was received
426
427|QuickFixCmdPre| before a quickfix command is run
428|QuickFixCmdPost| after a quickfix command is run
429
430|SessionLoadPost| after loading a session file
431
h-east53753f62024-05-05 18:42:31 +0200432|SessionWritePost| after writing the session file using
433 the |:mksession| command
Colin Kennedye5f22802024-03-26 18:20:16 +0100434
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000435|MenuPopup| just before showing the popup menu
Bram Moolenaard7f246c2019-04-08 18:15:41 +0200436|CompleteChanged| after Insert mode completion menu changed
Bram Moolenaar3f169ce2020-01-26 22:43:31 +0100437|CompleteDonePre| after Insert mode completion is done, before clearing
438 info
439|CompleteDone| after Insert mode completion is done, after clearing
440 info
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000441
Shougo Matsushita83678842024-07-11 22:05:12 +0200442|KeyInputPre| just before a key is processed
443
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000444|User| to be used in combination with ":doautocmd"
Bram Moolenaarbe5ee862020-06-10 20:56:58 +0200445|SigUSR1| after the SIGUSR1 signal has been detected
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000446
LemonBoy09371822022-04-08 15:18:45 +0100447|WinScrolled| after scrolling or resizing a window
448
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000449
450The alphabetical list of autocommand events: *autocmd-events-abc*
451
452 *BufCreate* *BufAdd*
453BufAdd or BufCreate Just after creating a new buffer which is
454 added to the buffer list, or adding a buffer
455 to the buffer list.
456 Also used just after a buffer in the buffer
457 list has been renamed.
Bram Moolenaar469bdbd2019-12-11 23:05:48 +0100458 Not triggered for the initial buffers created
459 during startup.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000460 The BufCreate event is for historic reasons.
461 NOTE: When this autocommand is executed, the
462 current buffer "%" may be different from the
463 buffer being created "<afile>".
464 *BufDelete*
465BufDelete Before deleting a buffer from the buffer list.
466 The BufUnload may be called first (if the
467 buffer was loaded).
468 Also used just before a buffer in the buffer
469 list is renamed.
470 NOTE: When this autocommand is executed, the
471 current buffer "%" may be different from the
Bram Moolenaar446cb832008-06-24 21:56:24 +0000472 buffer being deleted "<afile>" and "<abuf>".
Bram Moolenaarb849e712009-06-24 15:51:37 +0000473 Don't change to another buffer, it will cause
474 problems.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000475 *BufEnter*
476BufEnter After entering a buffer. Useful for setting
477 options for a file type. Also executed when
478 starting to edit a buffer, after the
479 BufReadPost autocommands.
480 *BufFilePost*
481BufFilePost After changing the name of the current buffer
482 with the ":file" or ":saveas" command.
Bram Moolenaar4770d092006-01-12 23:22:24 +0000483 *BufFilePre*
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000484BufFilePre Before changing the name of the current buffer
485 with the ":file" or ":saveas" command.
486 *BufHidden*
Bram Moolenaar790c18b2019-07-04 17:22:06 +0200487BufHidden Just before a buffer becomes hidden. That is,
488 when there are no longer windows that show
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000489 the buffer, but the buffer is not unloaded or
490 deleted. Not used for ":qa" or ":q" when
491 exiting Vim.
492 NOTE: When this autocommand is executed, the
493 current buffer "%" may be different from the
494 buffer being unloaded "<afile>".
495 *BufLeave*
496BufLeave Before leaving to another buffer. Also when
497 leaving or closing the current window and the
498 new current window is not for the same buffer.
499 Not used for ":qa" or ":q" when exiting Vim.
500 *BufNew*
501BufNew Just after creating a new buffer. Also used
502 just after a buffer has been renamed. When
503 the buffer is added to the buffer list BufAdd
504 will be triggered too.
505 NOTE: When this autocommand is executed, the
506 current buffer "%" may be different from the
507 buffer being created "<afile>".
Bram Moolenaar071d4272004-06-13 20:20:40 +0000508 *BufNewFile*
509BufNewFile When starting to edit a file that doesn't
510 exist. Can be used to read in a skeleton
511 file.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000512 *BufRead* *BufReadPost*
513BufRead or BufReadPost When starting to edit a new buffer, after
514 reading the file into the buffer, before
515 executing the modelines. See |BufWinEnter|
516 for when you need to do something after
517 processing the modelines.
Bram Moolenaar75ab5902022-04-18 15:36:40 +0100518 Also triggered:
519 - when writing an unnamed buffer in a way that
520 the buffer gets a name
521 - after successfully recovering a file
522 - for the filetypedetect group when executing
523 ":filetype detect"
524 Not triggered:
525 - for the `:read file` command
526 - when the file doesn't exist
Bram Moolenaar4770d092006-01-12 23:22:24 +0000527 *BufReadCmd*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000528BufReadCmd Before starting to edit a new buffer. Should
529 read the file into the buffer. |Cmd-event|
Bram Moolenaar4770d092006-01-12 23:22:24 +0000530 *BufReadPre* *E200* *E201*
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000531BufReadPre When starting to edit a new buffer, before
532 reading the file into the buffer. Not used
533 if the file doesn't exist.
534 *BufUnload*
535BufUnload Before unloading a buffer. This is when the
536 text in the buffer is going to be freed. This
537 may be after a BufWritePost and before a
538 BufDelete. Also used for all buffers that are
539 loaded when Vim is going to exit.
540 NOTE: When this autocommand is executed, the
541 current buffer "%" may be different from the
542 buffer being unloaded "<afile>".
Bram Moolenaar64d8e252016-09-06 22:12:34 +0200543 Don't change to another buffer or window, it
544 will cause problems!
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +0200545 When exiting and v:dying is 2 or more this
546 event is not triggered.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000547 *BufWinEnter*
548BufWinEnter After a buffer is displayed in a window. This
549 can be when the buffer is loaded (after
Bram Moolenaar446cb832008-06-24 21:56:24 +0000550 processing the modelines) or when a hidden
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000551 buffer is displayed in a window (and is no
Bram Moolenaar446cb832008-06-24 21:56:24 +0000552 longer hidden).
553 Does not happen for |:split| without
554 arguments, since you keep editing the same
555 buffer, or ":split" with a file that's already
Bram Moolenaarc236c162008-07-13 17:41:49 +0000556 open in a window, because it re-uses an
557 existing buffer. But it does happen for a
558 ":split" with the name of the current buffer,
559 since it reloads that buffer.
Bram Moolenaar606cb8b2018-05-03 20:40:20 +0200560 Does not happen for a terminal window, because
561 it starts in Terminal-Job mode and Normal mode
562 commands won't work. Use |TerminalOpen| instead.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000563 *BufWinLeave*
564BufWinLeave Before a buffer is removed from a window.
565 Not when it's still visible in another window.
566 Also triggered when exiting. It's triggered
567 before BufUnload or BufHidden.
568 NOTE: When this autocommand is executed, the
569 current buffer "%" may be different from the
570 buffer being unloaded "<afile>".
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +0200571 When exiting and v:dying is 2 or more this
572 event is not triggered.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000573 *BufWipeout*
574BufWipeout Before completely deleting a buffer. The
575 BufUnload and BufDelete events may be called
576 first (if the buffer was loaded and was in the
577 buffer list). Also used just before a buffer
578 is renamed (also when it's not in the buffer
579 list).
580 NOTE: When this autocommand is executed, the
581 current buffer "%" may be different from the
582 buffer being deleted "<afile>".
Bram Moolenaarb849e712009-06-24 15:51:37 +0000583 Don't change to another buffer, it will cause
584 problems.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000585 *BufWrite* *BufWritePre*
586BufWrite or BufWritePre Before writing the whole buffer to a file.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000587 *BufWriteCmd*
588BufWriteCmd Before writing the whole buffer to a file.
589 Should do the writing of the file and reset
Bram Moolenaar1cd871b2004-12-19 22:46:22 +0000590 'modified' if successful, unless '+' is in
591 'cpo' and writing to another file |cpo-+|.
592 The buffer contents should not be changed.
Bram Moolenaar5302d9e2011-09-14 17:55:08 +0200593 When the command resets 'modified' the undo
594 information is adjusted to mark older undo
595 states as 'modified', like |:write| does.
Bram Moolenaar1cd871b2004-12-19 22:46:22 +0000596 |Cmd-event|
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000597 *BufWritePost*
598BufWritePost After writing the whole buffer to a file
599 (should undo the commands for BufWritePre).
Bram Moolenaard5005162014-08-22 23:05:54 +0200600 *CmdUndefined*
601CmdUndefined When a user command is used but it isn't
602 defined. Useful for defining a command only
603 when it's used. The pattern is matched
604 against the command name. Both <amatch> and
605 <afile> are set to the name of the command.
606 NOTE: Autocompletion won't work until the
607 command is defined. An alternative is to
608 always define the user command and have it
609 invoke an autoloaded function. See |autoload|.
Bram Moolenaar153b7042018-01-31 15:48:32 +0100610 *CmdlineChanged*
Bram Moolenaarb5b75622018-03-09 22:22:21 +0100611CmdlineChanged After a change was made to the text in the
612 command line. Be careful not to mess up
613 the command line, it may cause Vim to lock up.
Bram Moolenaar153b7042018-01-31 15:48:32 +0100614 <afile> is set to a single character,
615 indicating the type of command-line.
616 |cmdwin-char|
Bram Moolenaarfafcf0d2017-10-19 18:35:51 +0200617 *CmdlineEnter*
618CmdlineEnter After moving the cursor to the command line,
619 where the user can type a command or search
Bram Moolenaar957cf672020-11-12 14:21:06 +0100620 string; including non-interactive use of ":"
621 in a mapping, but not when using |<Cmd>|.
Bram Moolenaar938ae282023-02-20 20:44:55 +0000622 The pattern is matched against the character
623 representing the type of command-line.
624 |cmdwin-char|
Bram Moolenaarfafcf0d2017-10-19 18:35:51 +0200625 <afile> is set to a single character,
626 indicating the type of command-line.
Bram Moolenaarfafcf0d2017-10-19 18:35:51 +0200627 *CmdlineLeave*
Bram Moolenaar957cf672020-11-12 14:21:06 +0100628CmdlineLeave Before leaving the command line; including
629 non-interactive use of ":" in a mapping, but
630 not when using |<Cmd>|.
Bram Moolenaar01164a62017-11-02 22:58:42 +0100631 Also when abandoning the command line, after
632 typing CTRL-C or <Esc>.
633 When the commands result in an error the
634 command line is still executed.
Bram Moolenaarfafcf0d2017-10-19 18:35:51 +0200635 <afile> is set to a single character,
636 indicating the type of command-line.
637 |cmdwin-char|
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000638 *CmdwinEnter*
639CmdwinEnter After entering the command-line window.
640 Useful for setting options specifically for
Bram Moolenaar96e38a82019-09-09 18:35:33 +0200641 this special type of window.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000642 <afile> is set to a single character,
643 indicating the type of command-line.
644 |cmdwin-char|
645 *CmdwinLeave*
646CmdwinLeave Before leaving the command-line window.
647 Useful to clean up any global setting done
Bram Moolenaar96e38a82019-09-09 18:35:33 +0200648 with CmdwinEnter.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000649 <afile> is set to a single character,
650 indicating the type of command-line.
651 |cmdwin-char|
652 *ColorScheme*
653ColorScheme After loading a color scheme. |:colorscheme|
Bram Moolenaar0daafaa2022-09-04 17:45:43 +0100654 Not triggered if the color scheme is not
655 found.
Bram Moolenaarb95186f2013-11-28 18:53:52 +0100656 The pattern is matched against the
657 colorscheme name. <afile> can be used for the
658 name of the actual file where this option was
659 set, and <amatch> for the new colorscheme
660 name.
661
Bram Moolenaar15142e22018-04-30 22:19:58 +0200662 *ColorSchemePre*
663ColorSchemePre Before loading a color scheme. |:colorscheme|
664 Useful to setup removing things added by a
665 color scheme, before another one is loaded.
Bram Moolenaar589edb32019-09-20 14:38:13 +0200666CompleteChanged *CompleteChanged*
Bram Moolenaard7f246c2019-04-08 18:15:41 +0200667 After each time the Insert mode completion
668 menu changed. Not fired on popup menu hide,
Bram Moolenaar3f169ce2020-01-26 22:43:31 +0100669 use |CompleteDonePre| or |CompleteDone| for
670 that. Never triggered recursively.
Bram Moolenaar754b5602006-02-09 23:53:20 +0000671
Bram Moolenaard7f246c2019-04-08 18:15:41 +0200672 Sets these |v:event| keys:
Bram Moolenaar911ead12019-04-21 00:03:35 +0200673 completed_item See |complete-items|.
Bram Moolenaard7f246c2019-04-08 18:15:41 +0200674 height nr of items visible
675 width screen cells
676 row top screen row
677 col leftmost screen column
678 size total nr of items
679 scrollbar TRUE if visible
680
681 It is not allowed to change the text |textlock|.
Bram Moolenaare9bd5722019-08-17 19:36:06 +0200682
683 The size and position of the popup are also
684 available by calling |pum_getpos()|.
685
Bram Moolenaar3f169ce2020-01-26 22:43:31 +0100686 *CompleteDonePre*
687CompleteDonePre After Insert mode completion is done. Either
688 when something was completed or abandoning
689 completion. |ins-completion|
690 |complete_info()| can be used, the info is
691 cleared after triggering CompleteDonePre.
692 The |v:completed_item| variable contains
693 information about the completed item.
694
Bram Moolenaar30b65812012-07-12 22:01:11 +0200695 *CompleteDone*
696CompleteDone After Insert mode completion is done. Either
697 when something was completed or abandoning
698 completion. |ins-completion|
Bram Moolenaar3f169ce2020-01-26 22:43:31 +0100699 |complete_info()| cannot be used, the info is
700 cleared before triggering CompleteDone. Use
701 CompleteDonePre if you need it.
Bram Moolenaar42a45122015-07-10 17:56:23 +0200702 The |v:completed_item| variable contains
703 information about the completed item.
Bram Moolenaar30b65812012-07-12 22:01:11 +0200704
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000705 *CursorHold*
706CursorHold When the user doesn't press a key for the time
Bram Moolenaard58a3bf2020-09-28 21:48:16 +0200707 specified with 'updatetime'. Not triggered
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000708 until the user has pressed a key (i.e. doesn't
709 fire every 'updatetime' ms if you leave Vim to
710 make some coffee. :) See |CursorHold-example|
711 for previewing tags.
712 This event is only triggered in Normal mode.
Bram Moolenaard7afed32007-05-06 13:26:41 +0000713 It is not triggered when waiting for a command
714 argument to be typed, or a movement after an
715 operator.
Bram Moolenaare3226be2005-12-18 22:10:00 +0000716 While recording the CursorHold event is not
717 triggered. |q|
Bram Moolenaar3a991dd2014-10-02 01:41:41 +0200718 *<CursorHold>*
719 Internally the autocommand is triggered by the
720 <CursorHold> key. In an expression mapping
721 |getchar()| may see this character.
722
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000723 Note: Interactive commands cannot be used for
724 this event. There is no hit-enter prompt,
725 the screen is updated directly (when needed).
726 Note: In the future there will probably be
727 another option to set the time.
728 Hint: to force an update of the status lines
729 use: >
730 :let &ro = &ro
Bram Moolenaar5666fcd2019-12-26 14:35:26 +0100731< {only on Amiga, Unix, Win32 and all GUI
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000732 versions}
Bram Moolenaar754b5602006-02-09 23:53:20 +0000733 *CursorHoldI*
734CursorHoldI Just like CursorHold, but in Insert mode.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +0200735 Not triggered when waiting for another key,
736 e.g. after CTRL-V, and not when in CTRL-X mode
737 |insert_expand|.
Bram Moolenaar754b5602006-02-09 23:53:20 +0000738
739 *CursorMoved*
Bram Moolenaar52b91d82013-06-15 21:39:51 +0200740CursorMoved After the cursor was moved in Normal or Visual
741 mode. Also when the text of the cursor line
742 has been changed, e.g., with "x", "rx" or "p".
Bram Moolenaar46eea442022-03-30 10:51:39 +0100743 Not always triggered when there is typeahead,
744 while executing commands in a script file,
745 when an operator is pending or when moving to
Bram Moolenaar90df4b92021-07-07 20:26:08 +0200746 another window while remaining at the same
747 cursor position.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +0000748 For an example see |match-parens|.
Bram Moolenaar26967612019-03-17 17:13:16 +0100749 Note: This can not be skipped with
750 `:noautocmd`.
Bram Moolenaarbf884932013-04-05 22:26:15 +0200751 Careful: This is triggered very often, don't
752 do anything that the user does not expect or
753 that is slow.
Shougo Matsushitad0952142024-06-20 22:05:16 +0200754 *CursorMovedC*
755CursorMovedC After the cursor was moved in the command
zeertzjq81456202024-07-07 20:48:25 +0200756 line. Be careful not to mess up the command
757 line, it may cause Vim to lock up.
Shougo Matsushitad0952142024-06-20 22:05:16 +0200758 <afile> is set to a single character,
759 indicating the type of command-line.
760 |cmdwin-char|
Bram Moolenaar754b5602006-02-09 23:53:20 +0000761 *CursorMovedI*
762CursorMovedI After the cursor was moved in Insert mode.
Bram Moolenaar5302d9e2011-09-14 17:55:08 +0200763 Not triggered when the popup menu is visible.
Bram Moolenaar754b5602006-02-09 23:53:20 +0000764 Otherwise the same as CursorMoved.
Bram Moolenaar75ab5902022-04-18 15:36:40 +0100765 *DiffUpdated*
766DiffUpdated After diffs have been updated. Depending on
767 what kind of diff is being used (internal or
768 external) this can be triggered on every
769 change or when doing |:diffupdate|.
770 *DirChangedPre*
771DirChangedPre The working directory is going to be changed,
772 as with |DirChanged|. The pattern is like
773 with |DirChanged|. The new directory can be
774 found in v:event.directory.
775 *DirChanged*
776DirChanged The working directory has changed in response
777 to the |:cd| or |:tcd| or |:lcd| commands, or
778 as a result of the 'autochdir' option.
779 The pattern can be:
780 "window" to trigger on `:lcd`
781 "tabpage" to trigger on `:tcd`
782 "global" to trigger on `:cd`
783 "auto" to trigger on 'autochdir'.
784 "drop" to trigger on editing a file
785 <afile> is set to the new directory name.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000786 *EncodingChanged*
787EncodingChanged Fires off after the 'encoding' option has been
788 changed. Useful to set up fonts, for example.
Bram Moolenaar75ab5902022-04-18 15:36:40 +0100789 *ExitPre*
790ExitPre When using `:quit`, `:wq` in a way it makes
791 Vim exit, or using `:qall`, just after
792 |QuitPre|. Can be used to close any
793 non-essential window. Exiting may still be
794 cancelled if there is a modified buffer that
795 isn't automatically saved, use |VimLeavePre|
796 for really exiting.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000797 *FileAppendCmd*
798FileAppendCmd Before appending to a file. Should do the
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000799 appending to the file. Use the '[ and ']
Bram Moolenaar22863042021-10-16 15:23:36 +0100800 marks for the range of lines. |Cmd-event|
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000801 *FileAppendPost*
802FileAppendPost After appending to a file.
803 *FileAppendPre*
804FileAppendPre Before appending to a file. Use the '[ and ']
805 marks for the range of lines.
806 *FileChangedRO*
807FileChangedRO Before making the first change to a read-only
808 file. Can be used to check-out the file from
809 a source control system. Not triggered when
810 the change was caused by an autocommand.
811 This event is triggered when making the first
812 change in a buffer or the first change after
Bram Moolenaar61660ea2006-04-07 21:40:07 +0000813 'readonly' was set, just before the change is
814 applied to the text.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000815 WARNING: If the autocommand moves the cursor
816 the effect of the change is undefined.
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000817 *E788*
818 It is not allowed to change to another buffer
819 here. You can reload the buffer but not edit
820 another one.
Bram Moolenaar92dff182014-02-11 19:15:50 +0100821 *E881*
822 If the number of lines changes saving for undo
823 may fail and the change will be aborted.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000824 *FileChangedShell*
825FileChangedShell When Vim notices that the modification time of
826 a file has changed since editing started.
827 Also when the file attributes of the file
Bram Moolenaare968e362014-05-13 20:23:24 +0200828 change or when the size of the file changes.
829 |timestamp|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000830 Mostly triggered after executing a shell
831 command, but also with a |:checktime| command
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +0200832 or when gvim regains input focus.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000833 This autocommand is triggered for each changed
834 file. It is not used when 'autoread' is set
835 and the buffer was not changed. If a
836 FileChangedShell autocommand is present the
837 warning message and prompt is not given.
Bram Moolenaar19a09a12005-03-04 23:39:37 +0000838 The |v:fcs_reason| variable is set to indicate
839 what happened and |v:fcs_choice| can be used
840 to tell Vim what to do next.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000841 NOTE: When this autocommand is executed, the
842 current buffer "%" may be different from the
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +0200843 buffer that was changed, which is in "<afile>".
Bram Moolenaar071d4272004-06-13 20:20:40 +0000844 NOTE: The commands must not change the current
845 buffer, jump to another buffer or delete a
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100846 buffer. *E246* *E811*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000847 NOTE: This event never nests, to avoid an
848 endless loop. This means that while executing
849 commands for the FileChangedShell event no
850 other FileChangedShell event will be
851 triggered.
Bram Moolenaar7d47b6e2006-03-15 22:59:18 +0000852 *FileChangedShellPost*
853FileChangedShellPost After handling a file that was changed outside
854 of Vim. Can be used to update the statusline.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000855 *FileEncoding*
856FileEncoding Obsolete. It still works and is equivalent
857 to |EncodingChanged|.
858 *FileReadCmd*
859FileReadCmd Before reading a file with a ":read" command.
860 Should do the reading of the file. |Cmd-event|
861 *FileReadPost*
862FileReadPost After reading a file with a ":read" command.
863 Note that Vim sets the '[ and '] marks to the
864 first and last line of the read. This can be
865 used to operate on the lines just read.
866 *FileReadPre*
867FileReadPre Before reading a file with a ":read" command.
868 *FileType*
Bram Moolenaard7afed32007-05-06 13:26:41 +0000869FileType When the 'filetype' option has been set. The
870 pattern is matched against the filetype.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000871 <afile> can be used for the name of the file
872 where this option was set, and <amatch> for
Bram Moolenaar74675a62017-07-15 13:53:23 +0200873 the new value of 'filetype'. Navigating to
874 another window or buffer is not allowed.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000875 See |filetypes|.
876 *FileWriteCmd*
877FileWriteCmd Before writing to a file, when not writing the
878 whole buffer. Should do the writing to the
879 file. Should not change the buffer. Use the
880 '[ and '] marks for the range of lines.
881 |Cmd-event|
882 *FileWritePost*
883FileWritePost After writing to a file, when not writing the
884 whole buffer.
885 *FileWritePre*
886FileWritePre Before writing to a file, when not writing the
887 whole buffer. Use the '[ and '] marks for the
888 range of lines.
889 *FilterReadPost*
890FilterReadPost After reading a file from a filter command.
891 Vim checks the pattern against the name of
892 the current buffer as with FilterReadPre.
893 Not triggered when 'shelltemp' is off.
894 *FilterReadPre* *E135*
895FilterReadPre Before reading a file from a filter command.
896 Vim checks the pattern against the name of
897 the current buffer, not the name of the
898 temporary file that is the output of the
899 filter command.
900 Not triggered when 'shelltemp' is off.
901 *FilterWritePost*
902FilterWritePost After writing a file for a filter command or
Bram Moolenaar4c05fa02019-01-01 15:32:17 +0100903 making a diff with an external diff (see
Bram Moolenaar22863042021-10-16 15:23:36 +0100904 |DiffUpdated| for internal diff).
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000905 Vim checks the pattern against the name of
906 the current buffer as with FilterWritePre.
907 Not triggered when 'shelltemp' is off.
908 *FilterWritePre*
909FilterWritePre Before writing a file for a filter command or
Bram Moolenaar4c05fa02019-01-01 15:32:17 +0100910 making a diff with an external diff.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000911 Vim checks the pattern against the name of
912 the current buffer, not the name of the
913 temporary file that is the output of the
914 filter command.
915 Not triggered when 'shelltemp' is off.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000916 *FocusGained*
917FocusGained When Vim got input focus. Only for the GUI
918 version and a few console versions where this
Christian Brabandt49ddeef2024-07-07 20:29:43 +0200919 can be detected. |xterm-focus-event|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000920 *FocusLost*
921FocusLost When Vim lost input focus. Only for the GUI
922 version and a few console versions where this
Christian Brabandt49ddeef2024-07-07 20:29:43 +0200923 can be detected. |xterm-focus-event|
924 May also happen when a dialog pops up.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000925 *FuncUndefined*
926FuncUndefined When a user function is used but it isn't
927 defined. Useful for defining a function only
Bram Moolenaard7afed32007-05-06 13:26:41 +0000928 when it's used. The pattern is matched
929 against the function name. Both <amatch> and
930 <afile> are set to the name of the function.
Bram Moolenaar4072ba52020-12-23 13:56:35 +0100931 Not triggered when compiling a |Vim9|
932 function.
Bram Moolenaard5005162014-08-22 23:05:54 +0200933 NOTE: When writing Vim scripts a better
934 alternative is to use an autoloaded function.
Bram Moolenaar7c626922005-02-07 22:01:03 +0000935 See |autoload-functions|.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000936 *GUIEnter*
937GUIEnter After starting the GUI successfully, and after
938 opening the window. It is triggered before
939 VimEnter when using gvim. Can be used to
940 position the window from a .gvimrc file: >
941 :autocmd GUIEnter * winpos 100 50
Bram Moolenaard7afed32007-05-06 13:26:41 +0000942< *GUIFailed*
943GUIFailed After starting the GUI failed. Vim may
944 continue to run in the terminal, if possible
945 (only on Unix and alikes, when connecting the
946 X server fails). You may want to quit Vim: >
947 :autocmd GUIFailed * qall
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000948< *InsertChange*
949InsertChange When typing <Insert> while in Insert or
950 Replace mode. The |v:insertmode| variable
951 indicates the new mode.
952 Be careful not to move the cursor or do
953 anything else that the user does not expect.
Bram Moolenaare659c952011-05-19 17:25:41 +0200954 *InsertCharPre*
955InsertCharPre When a character is typed in Insert mode,
956 before inserting the char.
957 The |v:char| variable indicates the char typed
958 and can be changed during the event to insert
959 a different character. When |v:char| is set
960 to more than one character this text is
961 inserted literally.
962 It is not allowed to change the text |textlock|.
963 The event is not triggered when 'paste' is
Bram Moolenaarb5b75622018-03-09 22:22:21 +0100964 set. {only with the +eval feature}
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000965 *InsertEnter*
Bram Moolenaard7afed32007-05-06 13:26:41 +0000966InsertEnter Just before starting Insert mode. Also for
967 Replace mode and Virtual Replace mode. The
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000968 |v:insertmode| variable indicates the mode.
Bram Moolenaar097c9922013-05-19 21:15:15 +0200969 Be careful not to do anything else that the
970 user does not expect.
971 The cursor is restored afterwards. If you do
972 not want that set |v:char| to a non-empty
973 string.
Bram Moolenaarb53e13a2020-10-21 12:19:53 +0200974 *InsertLeavePre*
975InsertLeavePre Just before leaving Insert mode. Also when
Bram Moolenaarcb80aa22020-10-26 21:12:46 +0100976 using CTRL-O |i_CTRL-O|. Be careful not to
Bram Moolenaarb53e13a2020-10-21 12:19:53 +0200977 change mode or use `:normal`, it will likely
978 cause trouble.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000979 *InsertLeave*
Bram Moolenaarb53e13a2020-10-21 12:19:53 +0200980InsertLeave Just after leaving Insert mode. Also when
981 using CTRL-O |i_CTRL-O|. But not for |i_CTRL-C|.
Shougo Matsushita83678842024-07-11 22:05:12 +0200982 *KeyInputPre*
Shougo Matsushitafcc1b572024-07-17 20:25:22 +0200983KeyInputPre Just before a key is processed after mappings
984 have been applied. The pattern is matched
985 against a string that indicates the current
986 mode, which is the same as what is returned by
987 `mode(1)`.
Shougo Matsushita83678842024-07-11 22:05:12 +0200988 The |v:char| variable indicates the key typed
989 and can be changed during the event to process
990 a different key. When |v:char| is not a
991 single character or a special key, the first
992 character is used.
993 The following values of |v:event| are set:
994 typed The key is typed or not.
Shougo Matsushita890f97c2024-08-18 16:57:04 +0200995 typedchar The (actual) typed key since
996 the last |KeyInputPre| call.
997 Note: "typedchar" may be empty if successive
998 |KeyInputPre| autocmds are processed.
Shougo Matsushita83678842024-07-11 22:05:12 +0200999 It is not allowed to change the text
1000 |textlock| or the current mode.
1001 {only with the +eval feature}
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001002 *MenuPopup*
1003MenuPopup Just before showing the popup menu (under the
1004 right mouse button). Useful for adjusting the
1005 menu for what is under the cursor or mouse
1006 pointer.
Bram Moolenaar4c5d8152018-10-19 22:36:53 +02001007 The pattern is matched against one or two
1008 characters representing the mode:
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001009 n Normal
1010 v Visual
1011 o Operator-pending
1012 i Insert
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00001013 c Command line
Bram Moolenaar4c5d8152018-10-19 22:36:53 +02001014 tl Terminal
=?UTF-8?q?Magnus=20Gro=C3=9F?=f1e88762021-09-12 13:39:55 +02001015 *ModeChanged*
1016ModeChanged After changing the mode. The pattern is
1017 matched against `'old_mode:new_mode'`, for
=?UTF-8?q?Magnus=20Gro=C3=9F?=25def2c2021-10-22 18:56:39 +01001018 example match against `*:c*` to simulate
1019 |CmdlineEnter|.
=?UTF-8?q?Magnus=20Gro=C3=9F?=f1e88762021-09-12 13:39:55 +02001020 The following values of |v:event| are set:
1021 old_mode The mode before it changed.
1022 new_mode The new mode as also returned
=?UTF-8?q?Magnus=20Gro=C3=9F?=25def2c2021-10-22 18:56:39 +01001023 by |mode()| called with a
1024 non-zero argument.
=?UTF-8?q?Magnus=20Gro=C3=9F?=f1e88762021-09-12 13:39:55 +02001025 When ModeChanged is triggered, old_mode will
1026 have the value of new_mode when the event was
1027 last triggered.
=?UTF-8?q?Magnus=20Gro=C3=9F?=25def2c2021-10-22 18:56:39 +01001028 This will be triggered on every minor mode
1029 change.
=?UTF-8?q?Magnus=20Gro=C3=9F?=f1e88762021-09-12 13:39:55 +02001030 Usage example to use relative line numbers
Bram Moolenaar6e649222021-10-04 21:32:54 +01001031 when entering Visual mode: >
=?UTF-8?q?Magnus=20Gro=C3=9F?=25def2c2021-10-22 18:56:39 +01001032 :au ModeChanged [vV\x16]*:* let &l:rnu = mode() =~# '^[vV\x16]'
1033 :au ModeChanged *:[vV\x16]* let &l:rnu = mode() =~# '^[vV\x16]'
1034 :au WinEnter,WinLeave * let &l:rnu = mode() =~# '^[vV\x16]'
=?UTF-8?q?Magnus=20Gro=C3=9F?=f1e88762021-09-12 13:39:55 +02001035< *OptionSet*
Bram Moolenaar53744302015-07-17 17:38:22 +02001036OptionSet After setting an option. The pattern is
1037 matched against the long option name.
Bram Moolenaard7c96872019-06-15 17:12:48 +02001038 |<amatch>| indicates what option has been set.
Bram Moolenaar53744302015-07-17 17:38:22 +02001039
Bram Moolenaard7c96872019-06-15 17:12:48 +02001040 |v:option_type| indicates whether it's global
Bram Moolenaar6c1e1572019-06-22 02:13:00 +02001041 or local scoped.
Bram Moolenaard7c96872019-06-15 17:12:48 +02001042 |v:option_command| indicates what type of
1043 set/let command was used (follow the tag to
1044 see the table).
1045 |v:option_new| indicates the newly set value.
Bram Moolenaar6c1e1572019-06-22 02:13:00 +02001046 |v:option_oldlocal| has the old local value.
1047 |v:option_oldglobal| has the old global value.
Bram Moolenaard7c96872019-06-15 17:12:48 +02001048 |v:option_old| indicates the old option value.
1049
1050 |v:option_oldlocal| is only set when |:set|
1051 or |:setlocal| or a |modeline| was used to set
1052 the option. Similarly |v:option_oldglobal| is
1053 only set when |:set| or |:setglobal| was used.
1054
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01001055 This does not set |<abuf>|, you could use
1056 |bufnr()|.
1057
Bram Moolenaard7c96872019-06-15 17:12:48 +02001058 Note that when setting a |global-local| string
1059 option with |:set|, then |v:option_old| is the
1060 old global value. However, for all other kinds
1061 of options (local string options, global-local
1062 number options, ...) it is the old local
1063 value.
1064
1065 OptionSet is not triggered on startup and for
1066 the 'key' option for obvious reasons.
Bram Moolenaar53744302015-07-17 17:38:22 +02001067
Bram Moolenaarf9132812015-07-21 19:19:13 +02001068 Usage example: Check for the existence of the
1069 directory in the 'backupdir' and 'undodir'
1070 options, create the directory if it doesn't
1071 exist yet.
1072
1073 Note: It's a bad idea to reset an option
1074 during this autocommand, this may break a
1075 plugin. You can always use `:noa` to prevent
1076 triggering this autocommand.
Bram Moolenaar53744302015-07-17 17:38:22 +02001077
Bram Moolenaar95bafa22018-10-02 13:26:25 +02001078 When using |:set| in the autocommand the event
1079 is not triggered again.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001080 *QuickFixCmdPre*
1081QuickFixCmdPre Before a quickfix command is run (|:make|,
Bram Moolenaara6557602006-02-04 22:43:20 +00001082 |:lmake|, |:grep|, |:lgrep|, |:grepadd|,
1083 |:lgrepadd|, |:vimgrep|, |:lvimgrep|,
Bram Moolenaar6be7f872012-01-20 21:08:56 +01001084 |:vimgrepadd|, |:lvimgrepadd|, |:cscope|,
Bram Moolenaar84f72352012-03-11 15:57:40 +01001085 |:cfile|, |:cgetfile|, |:caddfile|, |:lfile|,
1086 |:lgetfile|, |:laddfile|, |:helpgrep|,
Bram Moolenaar64d8e252016-09-06 22:12:34 +02001087 |:lhelpgrep|, |:cexpr|, |:cgetexpr|,
1088 |:caddexpr|, |:cbuffer|, |:cgetbuffer|,
1089 |:caddbuffer|).
Bram Moolenaarf1eeae92010-05-14 23:14:42 +02001090 The pattern is matched against the command
1091 being run. When |:grep| is used but 'grepprg'
1092 is set to "internal" it still matches "grep".
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001093 This command cannot be used to set the
1094 'makeprg' and 'grepprg' variables.
1095 If this command causes an error, the quickfix
1096 command is not executed.
1097 *QuickFixCmdPost*
1098QuickFixCmdPost Like QuickFixCmdPre, but after a quickfix
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00001099 command is run, before jumping to the first
Bram Moolenaar8ec1f852012-03-07 20:13:49 +01001100 location. For |:cfile| and |:lfile| commands
Bram Moolenaarb59ae592022-11-23 23:46:31 +00001101 it is run after the error file is read and
1102 before moving to the first error.
Bram Moolenaar8ec1f852012-03-07 20:13:49 +01001103 See |QuickFixCmdPost-example|.
Bram Moolenaar30b65812012-07-12 22:01:11 +02001104 *QuitPre*
Bram Moolenaarac7bd632013-03-19 11:35:58 +01001105QuitPre When using `:quit`, `:wq` or `:qall`, before
1106 deciding whether it closes the current window
Bram Moolenaard2ea7cf2021-05-30 20:54:13 +02001107 or quits Vim. For `:wq` the buffer is written
1108 before QuitPre is triggered. Can be used to
1109 close any non-essential window if the current
1110 window is the last ordinary window.
Bram Moolenaar12a96de2018-03-11 14:44:18 +01001111 Also see |ExitPre|.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001112 *RemoteReply*
1113RemoteReply When a reply from a Vim that functions as
Bram Moolenaard7afed32007-05-06 13:26:41 +00001114 server was received |server2client()|. The
1115 pattern is matched against the {serverid}.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001116 <amatch> is equal to the {serverid} from which
1117 the reply was sent, and <afile> is the actual
1118 reply string.
1119 Note that even if an autocommand is defined,
1120 the reply should be read with |remote_read()|
1121 to consume it.
Bram Moolenaar8aeec402019-09-15 23:02:04 +02001122 *SafeState*
1123SafeState When nothing is pending, going to wait for the
1124 user to type a character.
1125 This will not be triggered when:
1126 - an operator is pending
1127 - a register was entered with "r
1128 - halfway executing a command
1129 - executing a mapping
1130 - there is typeahead
1131 - Insert mode completion is active
1132 - Command line completion is active
1133 You can use `mode()` to find out what state
1134 Vim is in. That may be:
zeertzjqe13b6652024-01-24 03:39:04 +08001135 - Visual mode
Bram Moolenaar8aeec402019-09-15 23:02:04 +02001136 - Normal mode
1137 - Insert mode
1138 - Command-line mode
1139 Depending on what you want to do, you may also
1140 check more with `state()`, e.g. whether the
1141 screen was scrolled for messages.
Bram Moolenaar69198cb2019-09-16 21:58:13 +02001142 *SafeStateAgain*
1143SafeStateAgain Like SafeState but after processing any
1144 messages and invoking callbacks. This may be
1145 triggered often, don't do something that takes
1146 time.
Bram Moolenaar8aeec402019-09-15 23:02:04 +02001147
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001148 *SessionLoadPost*
1149SessionLoadPost After loading the session file created using
1150 the |:mksession| command.
Colin Kennedye5f22802024-03-26 18:20:16 +01001151 *SessionWritePost*
1152SessionWritePost After writing a session file by calling
1153 the |:mksession| command.
Bram Moolenaara94bc432006-03-10 21:42:59 +00001154 *ShellCmdPost*
1155ShellCmdPost After executing a shell command with |:!cmd|,
1156 |:shell|, |:make| and |:grep|. Can be used to
1157 check for any changed files.
1158 *ShellFilterPost*
1159ShellFilterPost After executing a shell command with
1160 ":{range}!cmd", ":w !cmd" or ":r !cmd".
1161 Can be used to check for any changed files.
Bram Moolenaar1f35bf92006-03-07 22:38:47 +00001162 *SourcePre*
1163SourcePre Before sourcing a Vim script. |:source|
Bram Moolenaar8dd1aa52007-01-16 20:33:19 +00001164 <afile> is the name of the file being sourced.
Bram Moolenaar2b618522019-01-12 13:26:03 +01001165 *SourcePost*
1166SourcePost After sourcing a Vim script. |:source|
1167 <afile> is the name of the file being sourced.
1168 Not triggered when sourcing was interrupted.
1169 Also triggered after a SourceCmd autocommand
1170 was triggered.
Bram Moolenaar8dd1aa52007-01-16 20:33:19 +00001171 *SourceCmd*
1172SourceCmd When sourcing a Vim script. |:source|
1173 <afile> is the name of the file being sourced.
1174 The autocommand must source this file.
1175 |Cmd-event|
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +00001176 *SpellFileMissing*
1177SpellFileMissing When trying to load a spell checking file and
Bram Moolenaar8dd1aa52007-01-16 20:33:19 +00001178 it can't be found. The pattern is matched
1179 against the language. <amatch> is the
1180 language, 'encoding' also matters. See
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +00001181 |spell-SpellFileMissing|.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001182 *StdinReadPost*
1183StdinReadPost After reading from the stdin into the buffer,
1184 before executing the modelines. Only used
1185 when the "-" argument was used when Vim was
1186 started |--|.
1187 *StdinReadPre*
1188StdinReadPre Before reading from stdin into the buffer.
1189 Only used when the "-" argument was used when
1190 Vim was started |--|.
1191 *SwapExists*
1192SwapExists Detected an existing swap file when starting
1193 to edit a file. Only when it is possible to
1194 select a way to handle the situation, when Vim
1195 would ask the user what to do.
1196 The |v:swapname| variable holds the name of
Bram Moolenaarb3480382005-12-11 21:33:32 +00001197 the swap file found, <afile> the file being
1198 edited. |v:swapcommand| may contain a command
1199 to be executed in the opened file.
1200 The commands should set the |v:swapchoice|
1201 variable to a string with one character to
1202 tell Vim what should be done next:
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001203 'o' open read-only
1204 'e' edit the file anyway
1205 'r' recover
1206 'd' delete the swap file
1207 'q' quit, don't edit the file
1208 'a' abort, like hitting CTRL-C
1209 When set to an empty string the user will be
1210 asked, as if there was no SwapExists autocmd.
Bram Moolenaarb849e712009-06-24 15:51:37 +00001211 *E812*
1212 It is not allowed to change to another buffer,
1213 change a buffer name or change directory
1214 here.
Bram Moolenaarb5b75622018-03-09 22:22:21 +01001215 {only available with the +eval feature}
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001216 *Syntax*
Bram Moolenaard7afed32007-05-06 13:26:41 +00001217Syntax When the 'syntax' option has been set. The
1218 pattern is matched against the syntax name.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001219 <afile> can be used for the name of the file
1220 where this option was set, and <amatch> for
1221 the new value of 'syntax'.
1222 See |:syn-on|.
Bram Moolenaar12c11d52016-07-19 23:13:03 +02001223 *TabClosed*
1224TabClosed After closing a tab page.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00001225 *TabEnter*
1226TabEnter Just after entering a tab page. |tab-page|
Bram Moolenaar56a907a2006-05-06 21:44:30 +00001227 After triggering the WinEnter and before
1228 triggering the BufEnter event.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00001229 *TabLeave*
1230TabLeave Just before leaving a tab page. |tab-page|
1231 A WinLeave event will have been triggered
1232 first.
Bram Moolenaarc917da42016-07-19 22:31:36 +02001233 *TabNew*
1234TabNew When a tab page was created. |tab-page|
1235 A WinEnter event will have been triggered
1236 first, TabEnter follows.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001237 *TermChanged*
1238TermChanged After the value of 'term' has changed. Useful
1239 for re-loading the syntax file to update the
1240 colors, fonts and other terminal-dependent
1241 settings. Executed for all loaded buffers.
Bram Moolenaarb852c3e2018-03-11 16:55:36 +01001242 *TerminalOpen*
1243TerminalOpen Just after a terminal buffer was created, with
1244 `:terminal` or |term_start()|. This event is
1245 triggered even if the buffer is created
1246 without a window, with the ++hidden option.
Bram Moolenaar28ed4df2019-10-26 16:21:40 +02001247 *TerminalWinOpen*
1248TerminalWinOpen Just after a terminal buffer was created, with
1249 `:terminal` or |term_start()|. This event is
1250 triggered only if the buffer is created
1251 with a window. Can be used to set window
1252 local options for the terminal window.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001253 *TermResponse*
1254TermResponse After the response to |t_RV| is received from
1255 the terminal. The value of |v:termresponse|
1256 can be used to do things depending on the
Bram Moolenaar8e5af3e2011-04-28 19:02:44 +02001257 terminal version. Note that this event may be
1258 triggered halfway executing another event,
1259 especially if file I/O, a shell command or
1260 anything else that takes time is involved.
Danek Duvalld7d56032024-01-14 20:19:59 +01001261 *TermResponseAll*
1262TermResponseAll After the response to |t_RV|, |t_RC|, |t_RS|,
1263 |t_RB|, |t_RF|, or |t_u7| are received from
1264 the terminal. The value of |v:termresponse|,
1265 |v:termblinkresp|, |v:termstyleresp|,
1266 |v:termrbgresp|, |v:termrfgresp|, and
1267 |v:termu7resp|, correspondingly, can be used.
1268 <amatch> will be set to any of:
1269 "version",
1270 "cursorblink",
1271 "cursorshape",
1272 "background",
1273 "foreground",
1274 "ambiguouswidth"
1275 Note that this event may be triggered halfway
1276 executing another event, especially if file I/O,
1277 a shell command or anything else that takes time
1278 is involved.
Bram Moolenaarbf884932013-04-05 22:26:15 +02001279 *TextChanged*
1280TextChanged After a change was made to the text in the
Bram Moolenaard09091d2019-01-17 16:07:22 +01001281 current buffer in Normal mode. That is after
1282 |b:changedtick| has changed (also when that
1283 happened before the TextChanged autocommand
1284 was defined).
Bram Moolenaarbf884932013-04-05 22:26:15 +02001285 Not triggered when there is typeahead or when
1286 an operator is pending.
Bram Moolenaar26967612019-03-17 17:13:16 +01001287 Note: This can not be skipped with
1288 `:noautocmd`.
Bram Moolenaarbf884932013-04-05 22:26:15 +02001289 Careful: This is triggered very often, don't
1290 do anything that the user does not expect or
1291 that is slow.
1292 *TextChangedI*
1293TextChangedI After a change was made to the text in the
1294 current buffer in Insert mode.
1295 Not triggered when the popup menu is visible.
1296 Otherwise the same as TextChanged.
Bram Moolenaar5a093432018-02-10 18:15:19 +01001297 *TextChangedP*
1298TextChangedP After a change was made to the text in the
1299 current buffer in Insert mode, only when the
1300 popup menu is visible. Otherwise the same as
1301 TextChanged.
Shougo Matsushita4ccaedf2022-10-15 11:48:00 +01001302 *TextChangedT*
1303TextChangedT After a change was made to the text in the
1304 current buffer in Terminal mode.
1305 Otherwise the same as TextChanged.
Bram Moolenaarf0b03c42017-12-17 17:17:07 +01001306 *TextYankPost*
Bram Moolenaar7e1652c2017-12-16 18:27:02 +01001307TextYankPost After text has been yanked or deleted in the
1308 current buffer. The following values of
1309 |v:event| can be used to determine the operation
1310 that triggered this autocmd:
Bram Moolenaara016eeb2022-04-09 11:37:38 +01001311 inclusive TRUE if the motion is
1312 |inclusive| else the motion is
1313 |exclusive|.
Bram Moolenaar589edb32019-09-20 14:38:13 +02001314 operator The operation performed.
1315 regcontents Text that was stored in the
Bram Moolenaar7e1652c2017-12-16 18:27:02 +01001316 register, as a list of lines,
1317 like with: >
1318 getreg(r, 1, 1)
Bram Moolenaar22863042021-10-16 15:23:36 +01001319< regname Name of the register or empty
1320 string for the unnamed
1321 register, see |registers|.
Bram Moolenaar7e1652c2017-12-16 18:27:02 +01001322 regtype Type of the register, see
1323 |getregtype()|.
Bram Moolenaar37d16732020-06-12 22:09:01 +02001324 visual True if the operation is
1325 performed on a |Visual| area.
Bram Moolenaar7e1652c2017-12-16 18:27:02 +01001326 Not triggered when |quote_| is used nor when
1327 called recursively.
1328 It is not allowed to change the buffer text,
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00001329 see |textlock|. *E1064*
Bram Moolenaarb5b75622018-03-09 22:22:21 +01001330 {only when compiled with the +eval feature}
Bram Moolenaarbe5ee862020-06-10 20:56:58 +02001331
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001332 *User*
1333User Never executed automatically. To be used for
1334 autocommands that are only executed with
1335 ":doautocmd".
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02001336 Note that when `:doautocmd User MyEvent` is
1337 used while there are no matching autocommands,
1338 you will get an error. If you don't want
LemonBoy09371822022-04-08 15:18:45 +01001339 that, either check whether an autocommand is
1340 defined using `exists('#User#MyEvent')` or
1341 define a dummy autocommand yourself.
1342 Example: >
1343 if exists('#User#MyEvent')
1344 doautocmd User MyEvent
1345 endif
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01001346<
Bram Moolenaarbe5ee862020-06-10 20:56:58 +02001347 *SigUSR1*
1348SigUSR1 After the SIGUSR1 signal has been detected.
1349 Could be used if other ways of notifying Vim
1350 are not feasible. E.g. to check for the
1351 result of a build that takes a long time, or
1352 when a motion sensor is triggered.
1353 {only on Unix}
1354
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001355 *UserGettingBored*
Bram Moolenaarbf884932013-04-05 22:26:15 +02001356UserGettingBored When the user presses the same key 42 times.
1357 Just kidding! :-)
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001358 *VimEnter*
1359VimEnter After doing all the startup stuff, including
1360 loading .vimrc files, executing the "-c cmd"
1361 arguments, creating all windows and loading
1362 the buffers in them.
Bram Moolenaar14735512016-03-26 21:00:08 +01001363 Just before this event is triggered the
1364 |v:vim_did_enter| variable is set, so that you
1365 can do: >
1366 if v:vim_did_enter
1367 call s:init()
1368 else
Bram Moolenaar589edb32019-09-20 14:38:13 +02001369 au VimEnter * call s:init()
Bram Moolenaar14735512016-03-26 21:00:08 +01001370 endif
1371< *VimLeave*
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001372VimLeave Before exiting Vim, just after writing the
1373 .viminfo file. Executed only once, like
1374 VimLeavePre.
1375 To detect an abnormal exit use |v:dying|.
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +02001376 When v:dying is 2 or more this event is not
1377 triggered.
Bram Moolenaarf0068c52020-11-30 17:42:10 +01001378 To get the exit code use |v:exiting|.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001379 *VimLeavePre*
1380VimLeavePre Before exiting Vim, just before writing the
1381 .viminfo file. This is executed only once,
1382 if there is a match with the name of what
1383 happens to be the current buffer when exiting.
1384 Mostly useful with a "*" pattern. >
1385 :autocmd VimLeavePre * call CleanupStuff()
1386< To detect an abnormal exit use |v:dying|.
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +02001387 When v:dying is 2 or more this event is not
1388 triggered.
Bram Moolenaarf0068c52020-11-30 17:42:10 +01001389 To get the exit code use |v:exiting|.
Bram Moolenaar7d47b6e2006-03-15 22:59:18 +00001390 *VimResized*
1391VimResized After the Vim window was resized, thus 'lines'
1392 and/or 'columns' changed. Not when starting
1393 up though.
Bram Moolenaar100118c2020-12-11 19:30:34 +01001394 *VimResume*
1395VimResume When the Vim instance is resumed after being
1396 suspended and |VimSuspend| was triggered.
1397 Useful for triggering |:checktime| and ensure
1398 the buffers content did not change while Vim
1399 was suspended: >
1400 :autocmd VimResume * checktime
1401< *VimSuspend*
1402VimSuspend When the Vim instance is suspended. Only when
dbivolaruab16ad32021-12-29 19:41:47 +00001403 CTRL-Z was typed inside Vim, or when the SIGTSTP
1404 signal was sent to Vim, but not for SIGSTOP.
naohiro ono23beefe2021-11-13 12:38:49 +00001405 *WinClosed*
Bram Moolenaarb59ae592022-11-23 23:46:31 +00001406WinClosed When closing a window, just before it is
1407 removed from the window layout. The pattern
1408 is matched against the |window-ID|. Both
naohiro ono23beefe2021-11-13 12:38:49 +00001409 <amatch> and <afile> are set to the
1410 |window-ID|. Non-recursive (event cannot
1411 trigger itself).
Bram Moolenaar071d4272004-06-13 20:20:40 +00001412 *WinEnter*
1413WinEnter After entering another window. Not done for
1414 the first window, when Vim has just started.
1415 Useful for setting the window height.
1416 If the window is for another buffer, Vim
1417 executes the BufEnter autocommands after the
1418 WinEnter autocommands.
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02001419 Note: For split and tabpage commands the
1420 WinEnter event is triggered after the split
1421 or tab command but before the file is loaded.
1422
Bram Moolenaar071d4272004-06-13 20:20:40 +00001423 *WinLeave*
1424WinLeave Before leaving a window. If the window to be
1425 entered next is for a different buffer, Vim
1426 executes the BufLeave autocommands before the
1427 WinLeave autocommands (but not for ":new").
1428 Not used for ":qa" or ":q" when exiting Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001429
Sergey Vlasov1f47db72024-01-25 23:07:00 +01001430 *WinNewPre*
1431WinNewPre Before creating a new window. Triggered
1432 before commands that modify window layout by
Christian Brabandtfb3f9692024-08-11 20:09:17 +02001433 creating a split.
h-east90e1fe42024-08-12 18:26:08 +02001434 Not done when creating tab pages and for the
1435 first window, as the window structure is not
Christian Brabandtfb3f9692024-08-11 20:09:17 +02001436 initialized yet and so is generally not safe.
Sergey Vlasov1f47db72024-01-25 23:07:00 +01001437 It is not allowed to modify window layout
1438 while executing commands for the WinNewPre
1439 event.
1440 Most useful to store current window layout
1441 and compare it with the new layout after the
1442 Window has been created.
1443
Bram Moolenaar12c11d52016-07-19 23:13:03 +02001444 *WinNew*
1445WinNew When a new window was created. Not done for
Bram Moolenaar50ba5262016-09-22 22:33:02 +02001446 the first window, when Vim has just started.
Bram Moolenaar12c11d52016-07-19 23:13:03 +02001447 Before a WinEnter event.
1448
LemonBoy09371822022-04-08 15:18:45 +01001449 *WinScrolled*
Bram Moolenaar35fc61c2022-11-22 12:40:50 +00001450WinScrolled After any window in the current tab page
1451 scrolled the text (horizontally or vertically)
1452 or changed width or height. See
1453 |win-scrolled-resized|.
Bram Moolenaar0a60f792022-11-19 21:18:11 +00001454
1455 The pattern is matched against the |window-ID|
1456 of the first window that scrolled or resized.
1457 Both <amatch> and <afile> are set to the
1458 |window-ID|.
1459
Bram Moolenaar35fc61c2022-11-22 12:40:50 +00001460 |v:event| is set with information about size
1461 and scroll changes. |WinScrolled-event|
1462
Bram Moolenaar0a60f792022-11-19 21:18:11 +00001463 Only starts triggering after startup finished
1464 and the first screen redraw was done.
Bram Moolenaar35fc61c2022-11-22 12:40:50 +00001465 Does not trigger when defining the first
1466 WinScrolled or WinResized event, but may
1467 trigger when adding more.
Bram Moolenaar0a60f792022-11-19 21:18:11 +00001468
1469 Non-recursive: the event will not trigger
1470 while executing commands for the WinScrolled
1471 event. However, if the command causes a
1472 window to scroll or change size, then another
LemonBoy09371822022-04-08 15:18:45 +01001473 WinScrolled event will be triggered later.
Bram Moolenaar0a60f792022-11-19 21:18:11 +00001474
Bram Moolenaar35fc61c2022-11-22 12:40:50 +00001475
1476 *WinResized*
1477WinResized After a window in the current tab page changed
1478 width or height.
1479 See |win-scrolled-resized|.
1480
1481 |v:event| is set with information about size
1482 changes. |WinResized-event|
1483
1484 Same behavior as |WinScrolled| for the
1485 pattern, triggering and recursiveness.
LemonBoy09371822022-04-08 15:18:45 +01001486
Bram Moolenaar071d4272004-06-13 20:20:40 +00001487==============================================================================
Bram Moolenaarfd31be22022-01-16 14:46:06 +000014886. Patterns *autocmd-patterns* *{aupat}*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001489
LemonBoy09371822022-04-08 15:18:45 +01001490The {aupat} argument of `:autocmd` can be a comma-separated list. This works as
Bram Moolenaarfd31be22022-01-16 14:46:06 +00001491if the command was given with each pattern separately. Thus this command: >
Bram Moolenaar5a5f4592015-04-13 12:43:06 +02001492 :autocmd BufRead *.txt,*.info set et
1493Is equivalent to: >
1494 :autocmd BufRead *.txt set et
1495 :autocmd BufRead *.info set et
1496
Bram Moolenaarfd31be22022-01-16 14:46:06 +00001497The file pattern {aupat} is tested for a match against the file name in one of
Bram Moolenaar071d4272004-06-13 20:20:40 +00001498two ways:
14991. When there is no '/' in the pattern, Vim checks for a match against only
1500 the tail part of the file name (without its leading directory path).
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010015012. When there is a '/' in the pattern, Vim checks for a match against both the
1502 short file name (as you typed it) and the full file name (after expanding
1503 it to a full path and resolving symbolic links).
Bram Moolenaar071d4272004-06-13 20:20:40 +00001504
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00001505The special pattern <buffer> or <buffer=N> is used for buffer-local
1506autocommands |autocmd-buflocal|. This pattern is not matched against the name
1507of a buffer.
1508
Bram Moolenaar071d4272004-06-13 20:20:40 +00001509Examples: >
1510 :autocmd BufRead *.txt set et
1511Set the 'et' option for all text files. >
1512
1513 :autocmd BufRead /vim/src/*.c set cindent
1514Set the 'cindent' option for C files in the /vim/src directory. >
1515
1516 :autocmd BufRead /tmp/*.c set ts=5
1517If you have a link from "/tmp/test.c" to "/home/nobody/vim/src/test.c", and
1518you start editing "/tmp/test.c", this autocommand will match.
1519
1520Note: To match part of a path, but not from the root directory, use a '*' as
1521the first character. Example: >
1522 :autocmd BufRead */doc/*.txt set tw=78
1523This autocommand will for example be executed for "/tmp/doc/xx.txt" and
1524"/usr/home/piet/doc/yy.txt". The number of directories does not matter here.
1525
1526
1527The file name that the pattern is matched against is after expanding
Bram Moolenaar446cb832008-06-24 21:56:24 +00001528wildcards. Thus if you issue this command: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001529 :e $ROOTDIR/main.$EXT
1530The argument is first expanded to: >
1531 /usr/root/main.py
1532Before it's matched with the pattern of the autocommand. Careful with this
1533when using events like FileReadCmd, the value of <amatch> may not be what you
1534expect.
1535
1536
1537Environment variables can be used in a pattern: >
1538 :autocmd BufRead $VIMRUNTIME/doc/*.txt set expandtab
1539And ~ can be used for the home directory (if $HOME is defined): >
1540 :autocmd BufWritePost ~/.vimrc so ~/.vimrc
1541 :autocmd BufRead ~archive/* set readonly
1542The environment variable is expanded when the autocommand is defined, not when
1543the autocommand is executed. This is different from the command!
1544
1545 *file-pattern*
1546The pattern is interpreted like mostly used in file names:
Bram Moolenaar3b1db362013-08-10 15:00:24 +02001547 * matches any sequence of characters; Unusual: includes path
Bram Moolenaar9d98fe92013-08-03 18:35:36 +02001548 separators
Bram Moolenaar071d4272004-06-13 20:20:40 +00001549 ? matches any single character
1550 \? matches a '?'
1551 . matches a '.'
1552 ~ matches a '~'
1553 , separates patterns
1554 \, matches a ','
1555 { } like \( \) in a |pattern|
1556 , inside { }: like \| in a |pattern|
Bram Moolenaara946afe2013-08-02 15:22:39 +02001557 \} literal }
1558 \{ literal {
1559 \\\{n,m\} like \{n,m} in a |pattern|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001560 \ special meaning like in a |pattern|
1561 [ch] matches 'c' or 'h'
1562 [^ch] match any character but 'c' and 'h'
1563
1564Note that for all systems the '/' character is used for path separator (even
Bram Moolenaar6f345a12019-12-17 21:27:18 +01001565for MS-Windows). This was done because the backslash is difficult to use in a
1566pattern and to make the autocommands portable across different systems.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001567
Bram Moolenaar64d8e252016-09-06 22:12:34 +02001568It is possible to use |pattern| items, but they may not work as expected,
1569because of the translation done for the above.
1570
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00001571 *autocmd-changes*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001572Matching with the pattern is done when an event is triggered. Changing the
1573buffer name in one of the autocommands, or even deleting the buffer, does not
1574change which autocommands will be executed. Example: >
1575
1576 au BufEnter *.foo bdel
1577 au BufEnter *.foo set modified
1578
1579This will delete the current buffer and then set 'modified' in what has become
1580the current buffer instead. Vim doesn't take into account that "*.foo"
1581doesn't match with that buffer name. It matches "*.foo" with the name of the
1582buffer at the moment the event was triggered.
1583
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00001584However, buffer-local autocommands will not be executed for a buffer that has
1585been wiped out with |:bwipe|. After deleting the buffer with |:bdel| the
1586buffer actually still exists (it becomes unlisted), thus the autocommands are
1587still executed.
1588
Bram Moolenaar071d4272004-06-13 20:20:40 +00001589==============================================================================
Bram Moolenaarc9b4b052006-04-30 18:54:39 +000015907. Buffer-local autocommands *autocmd-buflocal* *autocmd-buffer-local*
1591 *<buffer=N>* *<buffer=abuf>* *E680*
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00001592
1593Buffer-local autocommands are attached to a specific buffer. They are useful
1594if the buffer does not have a name and when the name does not match a specific
1595pattern. But it also means they must be explicitly added to each buffer.
1596
1597Instead of a pattern buffer-local autocommands use one of these forms:
1598 <buffer> current buffer
1599 <buffer=99> buffer number 99
1600 <buffer=abuf> using <abuf> (only when executing autocommands)
1601 |<abuf>|
1602
1603Examples: >
1604 :au CursorHold <buffer> echo 'hold'
1605 :au CursorHold <buffer=33> echo 'hold'
Bram Moolenaar88774fd2015-08-25 19:52:04 +02001606 :au BufNewFile * au CursorHold <buffer=abuf> echo 'hold'
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00001607
1608All the commands for autocommands also work with buffer-local autocommands,
1609simply use the special string instead of the pattern. Examples: >
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001610 :au! * <buffer> " remove buffer-local autocommands for
1611 " current buffer
1612 :au! * <buffer=33> " remove buffer-local autocommands for
1613 " buffer #33
Bram Moolenaar446cb832008-06-24 21:56:24 +00001614 :bufdo :au! CursorHold <buffer> " remove autocmd for given event for all
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001615 " buffers
1616 :au * <buffer> " list buffer-local autocommands for
1617 " current buffer
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00001618
1619Note that when an autocommand is defined for the current buffer, it is stored
1620with the buffer number. Thus it uses the form "<buffer=12>", where 12 is the
1621number of the current buffer. You will see this when listing autocommands,
1622for example.
1623
1624To test for presence of buffer-local autocommands use the |exists()| function
1625as follows: >
1626 :if exists("#CursorHold#<buffer=12>") | ... | endif
1627 :if exists("#CursorHold#<buffer>") | ... | endif " for current buffer
1628
1629When a buffer is wiped out its buffer-local autocommands are also gone, of
1630course. Note that when deleting a buffer, e.g., with ":bdel", it is only
1631unlisted, the autocommands are still present. In order to see the removal of
1632buffer-local autocommands: >
1633 :set verbose=6
1634
1635It is not possible to define buffer-local autocommands for a non-existent
1636buffer.
1637
1638==============================================================================
16398. Groups *autocmd-groups*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001640
1641Autocommands can be put together in a group. This is useful for removing or
1642executing a group of autocommands. For example, all the autocommands for
1643syntax highlighting are put in the "highlight" group, to be able to execute
1644":doautoall highlight BufRead" when the GUI starts.
1645
1646When no specific group is selected, Vim uses the default group. The default
1647group does not have a name. You cannot execute the autocommands from the
1648default group separately; you can execute them only by executing autocommands
1649for all groups.
1650
1651Normally, when executing autocommands automatically, Vim uses the autocommands
1652for all groups. The group only matters when executing autocommands with
1653":doautocmd" or ":doautoall", or when defining or deleting autocommands.
1654
1655The group name can contain any characters except white space. The group name
1656"end" is reserved (also in uppercase).
1657
1658The group name is case sensitive. Note that this is different from the event
1659name!
1660
1661 *:aug* *:augroup*
1662:aug[roup] {name} Define the autocmd group name for the
1663 following ":autocmd" commands. The name "end"
1664 or "END" selects the default group.
Bram Moolenaar256972a2015-12-29 19:10:25 +01001665 To avoid confusion, the name should be
1666 different from existing {event} names, as this
1667 most likely will not do what you intended.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001668
Bram Moolenaar64d8e252016-09-06 22:12:34 +02001669 *:augroup-delete* *E367* *W19* *E936*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001670:aug[roup]! {name} Delete the autocmd group {name}. Don't use
1671 this if there is still an autocommand using
Bram Moolenaarbc8801c2016-08-02 21:04:33 +02001672 this group! You will get a warning if doing
Bram Moolenaare7b1ea02020-08-07 19:54:59 +02001673 it anyway. When the group is the current
1674 group you will get error E936.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001675
1676To enter autocommands for a specific group, use this method:
16771. Select the group with ":augroup {name}".
16782. Delete any old autocommands with ":au!".
16793. Define the autocommands.
16804. Go back to the default group with "augroup END".
1681
1682Example: >
1683 :augroup uncompress
1684 : au!
1685 : au BufEnter *.gz %!gunzip
1686 :augroup END
1687
1688This prevents having the autocommands defined twice (e.g., after sourcing the
1689.vimrc file again).
1690
Bram Moolenaar6e649222021-10-04 21:32:54 +01001691 *FileExplorer*
1692There is one group that is recognized by Vim: FileExplorer. If this group
1693exists Vim assumes that editing a directory is possible and will trigger a
1694plugin that lists the files in that directory. This is used by the |netrw|
1695plugin. This allows you to do: >
1696 browse edit
1697
Bram Moolenaar071d4272004-06-13 20:20:40 +00001698==============================================================================
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +000016999. Executing autocommands *autocmd-execute*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001700
1701Vim can also execute Autocommands non-automatically. This is useful if you
1702have changed autocommands, or when Vim has executed the wrong autocommands
1703(e.g., the file pattern match was wrong).
1704
1705Note that the 'eventignore' option applies here too. Events listed in this
1706option will not cause any commands to be executed.
1707
Bram Moolenaar61da1bf2019-06-06 12:14:49 +02001708 *:do* *:doau* *:doaut* *:doautocmd* *E217*
Bram Moolenaar5dc62522012-02-13 00:05:22 +01001709:do[autocmd] [<nomodeline>] [group] {event} [fname]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001710 Apply the autocommands matching [fname] (default:
1711 current file name) for {event} to the current buffer.
1712 You can use this when the current file name does not
1713 match the right pattern, after changing settings, or
1714 to execute autocommands for a certain event.
1715 It's possible to use this inside an autocommand too,
1716 so you can base the autocommands for one extension on
1717 another extension. Example: >
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01001718 :au BufEnter *.cpp so ~/.vimrc_cpp
1719 :au BufEnter *.cpp doau BufEnter x.c
Bram Moolenaar071d4272004-06-13 20:20:40 +00001720< Be careful to avoid endless loops. See
1721 |autocmd-nested|.
1722
1723 When the [group] argument is not given, Vim executes
1724 the autocommands for all groups. When the [group]
1725 argument is included, Vim executes only the matching
1726 autocommands for that group. Note: if you use an
1727 undefined group name, Vim gives you an error message.
Bram Moolenaar60542ac2012-02-12 20:14:01 +01001728 *<nomodeline>*
1729 After applying the autocommands the modelines are
1730 processed, so that their settings overrule the
1731 settings from autocommands, like what happens when
1732 editing a file. This is skipped when the <nomodeline>
1733 argument is present. You probably want to use
1734 <nomodeline> for events that are not used when loading
1735 a buffer, such as |User|.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001736 Processing modelines is also skipped when no
1737 matching autocommands were executed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001738
1739 *:doautoa* *:doautoall*
Bram Moolenaara61d5fb2012-02-12 00:18:58 +01001740:doautoa[ll] [<nomodeline>] [group] {event} [fname]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001741 Like ":doautocmd", but apply the autocommands to each
Bram Moolenaardad44732021-03-31 20:07:33 +02001742 loaded buffer. The current buffer is done last.
1743
1744 Note that [fname] is used to select the autocommands,
Bram Moolenaar4c295022021-05-02 17:19:11 +02001745 not the buffers to which they are applied. Example: >
1746 augroup mine
1747 autocmd!
1748 autocmd FileType * echo expand('<amatch>')
1749 augroup END
1750 doautoall mine FileType Loaded-Buffer
1751< Sourcing this script, you'll see as many
1752 "Loaded-Buffer" echoed as there are loaded buffers.
Bram Moolenaardad44732021-03-31 20:07:33 +02001753
Bram Moolenaar071d4272004-06-13 20:20:40 +00001754 Careful: Don't use this for autocommands that delete a
1755 buffer, change to another buffer or change the
1756 contents of a buffer; the result is unpredictable.
1757 This command is intended for autocommands that set
1758 options, change highlighting, and things like that.
1759
1760==============================================================================
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +0000176110. Using autocommands *autocmd-use*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001762
1763For WRITING FILES there are four possible sets of events. Vim uses only one
1764of these sets for a write command:
1765
1766BufWriteCmd BufWritePre BufWritePost writing the whole buffer
1767 FilterWritePre FilterWritePost writing to filter temp file
1768FileAppendCmd FileAppendPre FileAppendPost appending to a file
1769FileWriteCmd FileWritePre FileWritePost any other file write
1770
1771When there is a matching "*Cmd" autocommand, it is assumed it will do the
1772writing. No further writing is done and the other events are not triggered.
1773|Cmd-event|
1774
1775Note that the *WritePost commands should undo any changes to the buffer that
1776were caused by the *WritePre commands; otherwise, writing the file will have
1777the side effect of changing the buffer.
1778
1779Before executing the autocommands, the buffer from which the lines are to be
1780written temporarily becomes the current buffer. Unless the autocommands
1781change the current buffer or delete the previously current buffer, the
1782previously current buffer is made the current buffer again.
1783
1784The *WritePre and *AppendPre autocommands must not delete the buffer from
1785which the lines are to be written.
1786
1787The '[ and '] marks have a special position:
1788- Before the *ReadPre event the '[ mark is set to the line just above where
1789 the new lines will be inserted.
1790- Before the *ReadPost event the '[ mark is set to the first line that was
1791 just read, the '] mark to the last line.
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001792- Before executing the *WriteCmd, *WritePre and *AppendPre autocommands the '[
1793 mark is set to the first line that will be written, the '] mark to the last
1794 line.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001795Careful: '[ and '] change when using commands that change the buffer.
1796
1797In commands which expect a file name, you can use "<afile>" for the file name
1798that is being read |:<afile>| (you can also use "%" for the current file
1799name). "<abuf>" can be used for the buffer number of the currently effective
Bram Moolenaard2f3a8b2018-06-19 14:35:59 +02001800buffer. This also works for buffers that don't have a name. But it doesn't
Bram Moolenaar071d4272004-06-13 20:20:40 +00001801work for files without a buffer (e.g., with ":r file").
1802
1803 *gzip-example*
1804Examples for reading and writing compressed files: >
1805 :augroup gzip
1806 : autocmd!
1807 : autocmd BufReadPre,FileReadPre *.gz set bin
1808 : autocmd BufReadPost,FileReadPost *.gz '[,']!gunzip
1809 : autocmd BufReadPost,FileReadPost *.gz set nobin
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001810 : autocmd BufReadPost,FileReadPost *.gz execute ":doautocmd BufReadPost " .. expand("%:r")
Bram Moolenaar071d4272004-06-13 20:20:40 +00001811 : autocmd BufWritePost,FileWritePost *.gz !mv <afile> <afile>:r
1812 : autocmd BufWritePost,FileWritePost *.gz !gzip <afile>:r
1813
1814 : autocmd FileAppendPre *.gz !gunzip <afile>
1815 : autocmd FileAppendPre *.gz !mv <afile>:r <afile>
1816 : autocmd FileAppendPost *.gz !mv <afile> <afile>:r
1817 : autocmd FileAppendPost *.gz !gzip <afile>:r
1818 :augroup END
1819
1820The "gzip" group is used to be able to delete any existing autocommands with
1821":autocmd!", for when the file is sourced twice.
1822
1823("<afile>:r" is the file name without the extension, see |:_%:|)
1824
1825The commands executed for the BufNewFile, BufRead/BufReadPost, BufWritePost,
1826FileAppendPost and VimLeave events do not set or reset the changed flag of the
1827buffer. When you decompress the buffer with the BufReadPost autocommands, you
1828can still exit with ":q". When you use ":undo" in BufWritePost to undo the
1829changes made by BufWritePre commands, you can still do ":q" (this also makes
1830"ZZ" work). If you do want the buffer to be marked as modified, set the
1831'modified' option.
1832
1833To execute Normal mode commands from an autocommand, use the ":normal"
1834command. Use with care! If the Normal mode command is not finished, the user
1835needs to type characters (e.g., after ":normal m" you need to type a mark
1836name).
1837
1838If you want the buffer to be unmodified after changing it, reset the
1839'modified' option. This makes it possible to exit the buffer with ":q"
1840instead of ":q!".
1841
1842 *autocmd-nested* *E218*
Bram Moolenaar26967612019-03-17 17:13:16 +01001843By default, autocommands do not nest. For example, if you use ":e" or ":w" in
1844an autocommand, Vim does not execute the BufRead and BufWrite autocommands for
Bram Moolenaar071d4272004-06-13 20:20:40 +00001845those commands. If you do want this, use the "nested" flag for those commands
1846in which you want nesting. For example: >
Bram Moolenaareb93f3f2019-04-04 15:04:56 +02001847 :autocmd FileChangedShell *.c ++nested e!
Bram Moolenaar071d4272004-06-13 20:20:40 +00001848The nesting is limited to 10 levels to get out of recursive loops.
1849
1850It's possible to use the ":au" command in an autocommand. This can be a
1851self-modifying command! This can be useful for an autocommand that should
1852execute only once.
1853
Bram Moolenaarb3480382005-12-11 21:33:32 +00001854If you want to skip autocommands for one command, use the |:noautocmd| command
1855modifier or the 'eventignore' option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001856
1857Note: When reading a file (with ":read file" or with a filter command) and the
1858last line in the file does not have an <EOL>, Vim remembers this. At the next
1859write (with ":write file" or with a filter command), if the same line is
1860written again as the last line in a file AND 'binary' is set, Vim does not
1861supply an <EOL>. This makes a filter command on the just read lines write the
1862same file as was read, and makes a write command on just filtered lines write
1863the same file as was read from the filter. For example, another way to write
1864a compressed file: >
1865
1866 :autocmd FileWritePre *.gz set bin|'[,']!gzip
1867 :autocmd FileWritePost *.gz undo|set nobin
1868<
1869 *autocommand-pattern*
1870You can specify multiple patterns, separated by commas. Here are some
1871examples: >
1872
1873 :autocmd BufRead * set tw=79 nocin ic infercase fo=2croq
1874 :autocmd BufRead .letter set tw=72 fo=2tcrq
1875 :autocmd BufEnter .letter set dict=/usr/lib/dict/words
1876 :autocmd BufLeave .letter set dict=
1877 :autocmd BufRead,BufNewFile *.c,*.h set tw=0 cin noic
1878 :autocmd BufEnter *.c,*.h abbr FOR for (i = 0; i < 3; ++i)<CR>{<CR>}<Esc>O
1879 :autocmd BufLeave *.c,*.h unabbr FOR
1880
1881For makefiles (makefile, Makefile, imakefile, makefile.unix, etc.): >
1882
1883 :autocmd BufEnter ?akefile* set include=^s\=include
1884 :autocmd BufLeave ?akefile* set include&
1885
1886To always start editing C files at the first function: >
1887
1888 :autocmd BufRead *.c,*.h 1;/^{
1889
1890Without the "1;" above, the search would start from wherever the file was
1891entered, rather than from the start of the file.
1892
1893 *skeleton* *template*
1894To read a skeleton (template) file when opening a new file: >
1895
1896 :autocmd BufNewFile *.c 0r ~/vim/skeleton.c
1897 :autocmd BufNewFile *.h 0r ~/vim/skeleton.h
1898 :autocmd BufNewFile *.java 0r ~/vim/skeleton.java
1899
1900To insert the current date and time in a *.html file when writing it: >
1901
1902 :autocmd BufWritePre,FileWritePre *.html ks|call LastMod()|'s
1903 :fun LastMod()
1904 : if line("$") > 20
1905 : let l = 20
1906 : else
1907 : let l = line("$")
1908 : endif
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001909 : exe "1," .. l .. "g/Last modified: /s/Last modified: .*/Last modified: " ..
Bram Moolenaar071d4272004-06-13 20:20:40 +00001910 : \ strftime("%Y %b %d")
1911 :endfun
1912
1913You need to have a line "Last modified: <date time>" in the first 20 lines
1914of the file for this to work. Vim replaces <date time> (and anything in the
1915same line after it) with the current date and time. Explanation:
1916 ks mark current position with mark 's'
1917 call LastMod() call the LastMod() function to do the work
1918 's return the cursor to the old position
1919The LastMod() function checks if the file is shorter than 20 lines, and then
1920uses the ":g" command to find lines that contain "Last modified: ". For those
1921lines the ":s" command is executed to replace the existing date with the
1922current one. The ":execute" command is used to be able to use an expression
1923for the ":g" and ":s" commands. The date is obtained with the strftime()
1924function. You can change its argument to get another date string.
1925
1926When entering :autocmd on the command-line, completion of events and command
1927names may be done (with <Tab>, CTRL-D, etc.) where appropriate.
1928
1929Vim executes all matching autocommands in the order that you specify them.
1930It is recommended that your first autocommand be used for all files by using
1931"*" as the file pattern. This means that you can define defaults you like
1932here for any settings, and if there is another matching autocommand it will
1933override these. But if there is no other matching autocommand, then at least
1934your default settings are recovered (if entering this file from another for
1935which autocommands did match). Note that "*" will also match files starting
1936with ".", unlike Unix shells.
1937
1938 *autocmd-searchpat*
1939Autocommands do not change the current search patterns. Vim saves the current
1940search patterns before executing autocommands then restores them after the
1941autocommands finish. This means that autocommands do not affect the strings
1942highlighted with the 'hlsearch' option. Within autocommands, you can still
1943use search patterns normally, e.g., with the "n" command.
1944If you want an autocommand to set the search pattern, such that it is used
1945after the autocommand finishes, use the ":let @/ =" command.
1946The search-highlighting cannot be switched off with ":nohlsearch" in an
1947autocommand. Use the 'h' flag in the 'viminfo' option to disable search-
1948highlighting when starting Vim.
1949
1950 *Cmd-event*
1951When using one of the "*Cmd" events, the matching autocommands are expected to
Bram Moolenaar8dd1aa52007-01-16 20:33:19 +00001952do the file reading, writing or sourcing. This can be used when working with
1953a special kind of file, for example on a remote system.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001954CAREFUL: If you use these events in a wrong way, it may have the effect of
1955making it impossible to read or write the matching files! Make sure you test
1956your autocommands properly. Best is to use a pattern that will never match a
1957normal file name, for example "ftp://*".
1958
1959When defining a BufReadCmd it will be difficult for Vim to recover a crashed
1960editing session. When recovering from the original file, Vim reads only those
1961parts of a file that are not found in the swap file. Since that is not
1962possible with a BufReadCmd, use the |:preserve| command to make sure the
1963original file isn't needed for recovery. You might want to do this only when
1964you expect the file to be modified.
1965
Bram Moolenaar8dd1aa52007-01-16 20:33:19 +00001966For file read and write commands the |v:cmdarg| variable holds the "++enc="
1967and "++ff=" argument that are effective. These should be used for the command
1968that reads/writes the file. The |v:cmdbang| variable is one when "!" was
1969used, zero otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001970
Bram Moolenaarc88ebf72010-07-22 22:30:23 +02001971See the $VIMRUNTIME/plugin/netrwPlugin.vim for examples.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001972
Bram Moolenaarb3480382005-12-11 21:33:32 +00001973==============================================================================
197411. Disabling autocommands *autocmd-disable*
1975
1976To disable autocommands for some time use the 'eventignore' option. Note that
1977this may cause unexpected behavior, make sure you restore 'eventignore'
1978afterwards, using a |:try| block with |:finally|.
1979
1980 *:noautocmd* *:noa*
1981To disable autocommands for just one command use the ":noautocmd" command
1982modifier. This will set 'eventignore' to "all" for the duration of the
1983following command. Example: >
1984
1985 :noautocmd w fname.gz
1986
1987This will write the file without triggering the autocommands defined by the
1988gzip plugin.
1989
Bram Moolenaar26967612019-03-17 17:13:16 +01001990Note that some autocommands are not triggered right away, but only later.
1991This specifically applies to |CursorMoved| and |TextChanged|.
1992
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00001993
Bram Moolenaar91f84f62018-07-29 15:07:52 +02001994 vim:tw=78:ts=8:noet:ft=help:norl: