blob: 2ac0247bb0c51ec05581f9f812d521c053fe9d10 [file] [log] [blame]
Christian Brabandtb4ddc6c2024-01-02 16:51:11 +01001*autocmd.txt* For Vim version 9.1. Last change: 2023 May 20
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: >
57 autocmd_add({replace: true,
58 group: 'DemoGroup',
59 event: 'BufEnter',
60 pattern: '*.txt',
61 cmd: 'call DemoBufEnter()'
62 })
63
64In legacy script: >
65 call autocmd_add(#{replace: v:true,
66 \ 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()'
70 \ })
71
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
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000343
Bram Moolenaar12a96de2018-03-11 14:44:18 +0100344|QuitPre| when using `:quit`, before deciding whether to exit
345|ExitPre| when using a command that may make Vim exit
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000346|VimLeavePre| before exiting Vim, before writing the viminfo file
347|VimLeave| before exiting Vim, after writing the viminfo file
348
Bram Moolenaar100118c2020-12-11 19:30:34 +0100349|VimSuspend| when suspending Vim
350|VimResume| when Vim is resumed after being suspended
351
Bram Moolenaar28ed4df2019-10-26 16:21:40 +0200352 Terminal
353|TerminalOpen| after a terminal buffer was created
354|TerminalWinOpen| after a terminal buffer was created in a new window
355
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000356 Various
357|FileChangedShell| Vim notices that a file changed since editing started
Bram Moolenaar7d47b6e2006-03-15 22:59:18 +0000358|FileChangedShellPost| After handling a file changed since editing started
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000359|FileChangedRO| before making the first change to a read-only file
360
Bram Moolenaar2c64ca12018-10-19 16:22:31 +0200361|DiffUpdated| after diffs have been updated
Bram Moolenaar28e8f732022-02-09 12:58:20 +0000362|DirChangedPre| before the working directory will change
Bram Moolenaarb7407d32018-02-03 17:36:27 +0100363|DirChanged| after the working directory has changed
364
Bram Moolenaara94bc432006-03-10 21:42:59 +0000365|ShellCmdPost| after executing a shell command
366|ShellFilterPost| after filtering with a shell command
367
Bram Moolenaard5005162014-08-22 23:05:54 +0200368|CmdUndefined| a user command is used but it isn't defined
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000369|FuncUndefined| a user function is used but it isn't defined
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +0000370|SpellFileMissing| a spell file is used but it can't be found
Bram Moolenaar1f35bf92006-03-07 22:38:47 +0000371|SourcePre| before sourcing a Vim script
Bram Moolenaar2a953fc2019-01-26 17:41:47 +0100372|SourcePost| after sourcing a Vim script
Bram Moolenaar8dd1aa52007-01-16 20:33:19 +0000373|SourceCmd| before sourcing a Vim script |Cmd-event|
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000374
Bram Moolenaar7d47b6e2006-03-15 22:59:18 +0000375|VimResized| after the Vim window size changed
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000376|FocusGained| Vim got input focus
377|FocusLost| Vim lost input focus
378|CursorHold| the user doesn't press a key for a while
Bram Moolenaar754b5602006-02-09 23:53:20 +0000379|CursorHoldI| the user doesn't press a key for a while in Insert mode
380|CursorMoved| the cursor was moved in Normal mode
381|CursorMovedI| the cursor was moved in Insert mode
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000382
Bram Moolenaarc917da42016-07-19 22:31:36 +0200383|WinNew| after creating a new window
Bram Moolenaar12c11d52016-07-19 23:13:03 +0200384|TabNew| after creating a new tab page
naohiro ono23beefe2021-11-13 12:38:49 +0000385|WinClosed| after closing a window
Bram Moolenaar12c11d52016-07-19 23:13:03 +0200386|TabClosed| after closing a tab page
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000387|WinEnter| after entering another window
388|WinLeave| before leaving a window
Bram Moolenaarfaa959a2006-02-20 21:37:40 +0000389|TabEnter| after entering another tab page
390|TabLeave| before leaving a tab page
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000391|CmdwinEnter| after entering the command-line window
392|CmdwinLeave| before leaving the command-line window
393
Bram Moolenaarb5b75622018-03-09 22:22:21 +0100394|CmdlineChanged| after a change was made to the command-line text
395|CmdlineEnter| after the cursor moves to the command line
396|CmdlineLeave| before the cursor leaves the command line
397
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000398|InsertEnter| starting Insert mode
399|InsertChange| when typing <Insert> while in Insert or Replace mode
400|InsertLeave| when leaving Insert mode
Bram Moolenaar938ae282023-02-20 20:44:55 +0000401|InsertLeavePre| just before leaving Insert mode
Bram Moolenaare659c952011-05-19 17:25:41 +0200402|InsertCharPre| when a character was typed in Insert mode, before
403 inserting it
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000404
=?UTF-8?q?Magnus=20Gro=C3=9F?=f1e88762021-09-12 13:39:55 +0200405|ModeChanged| after changing the mode
406
Bram Moolenaardfb18412013-12-11 18:53:29 +0100407|TextChanged| after a change was made to the text in Normal mode
408|TextChangedI| after a change was made to the text in Insert mode
Bram Moolenaar5a093432018-02-10 18:15:19 +0100409 when popup menu is not visible
410|TextChangedP| after a change was made to the text in Insert mode
411 when popup menu visible
Shougo Matsushita4ccaedf2022-10-15 11:48:00 +0100412|TextChangedT| after a change was made to the text in Terminal mode
Bram Moolenaarb477af22018-07-15 20:20:18 +0200413|TextYankPost| after text has been yanked or deleted
Bram Moolenaardfb18412013-12-11 18:53:29 +0100414
Bram Moolenaar8aeec402019-09-15 23:02:04 +0200415|SafeState| nothing pending, going to wait for the user to type a
416 character
Bram Moolenaar69198cb2019-09-16 21:58:13 +0200417|SafeStateAgain| repeated SafeState
Bram Moolenaar8aeec402019-09-15 23:02:04 +0200418
Bram Moolenaar15142e22018-04-30 22:19:58 +0200419|ColorSchemePre| before loading a color scheme
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000420|ColorScheme| after loading a color scheme
421
422|RemoteReply| a reply from a server Vim was received
423
424|QuickFixCmdPre| before a quickfix command is run
425|QuickFixCmdPost| after a quickfix command is run
426
427|SessionLoadPost| after loading a session file
428
429|MenuPopup| just before showing the popup menu
Bram Moolenaard7f246c2019-04-08 18:15:41 +0200430|CompleteChanged| after Insert mode completion menu changed
Bram Moolenaar3f169ce2020-01-26 22:43:31 +0100431|CompleteDonePre| after Insert mode completion is done, before clearing
432 info
433|CompleteDone| after Insert mode completion is done, after clearing
434 info
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000435
436|User| to be used in combination with ":doautocmd"
Bram Moolenaarbe5ee862020-06-10 20:56:58 +0200437|SigUSR1| after the SIGUSR1 signal has been detected
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000438
LemonBoy09371822022-04-08 15:18:45 +0100439|WinScrolled| after scrolling or resizing a window
440
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000441
442The alphabetical list of autocommand events: *autocmd-events-abc*
443
444 *BufCreate* *BufAdd*
445BufAdd or BufCreate Just after creating a new buffer which is
446 added to the buffer list, or adding a buffer
447 to the buffer list.
448 Also used just after a buffer in the buffer
449 list has been renamed.
Bram Moolenaar469bdbd2019-12-11 23:05:48 +0100450 Not triggered for the initial buffers created
451 during startup.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000452 The BufCreate event is for historic reasons.
453 NOTE: When this autocommand is executed, the
454 current buffer "%" may be different from the
455 buffer being created "<afile>".
456 *BufDelete*
457BufDelete Before deleting a buffer from the buffer list.
458 The BufUnload may be called first (if the
459 buffer was loaded).
460 Also used just before a buffer in the buffer
461 list is renamed.
462 NOTE: When this autocommand is executed, the
463 current buffer "%" may be different from the
Bram Moolenaar446cb832008-06-24 21:56:24 +0000464 buffer being deleted "<afile>" and "<abuf>".
Bram Moolenaarb849e712009-06-24 15:51:37 +0000465 Don't change to another buffer, it will cause
466 problems.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000467 *BufEnter*
468BufEnter After entering a buffer. Useful for setting
469 options for a file type. Also executed when
470 starting to edit a buffer, after the
471 BufReadPost autocommands.
472 *BufFilePost*
473BufFilePost After changing the name of the current buffer
474 with the ":file" or ":saveas" command.
Bram Moolenaar4770d092006-01-12 23:22:24 +0000475 *BufFilePre*
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000476BufFilePre Before changing the name of the current buffer
477 with the ":file" or ":saveas" command.
478 *BufHidden*
Bram Moolenaar790c18b2019-07-04 17:22:06 +0200479BufHidden Just before a buffer becomes hidden. That is,
480 when there are no longer windows that show
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000481 the buffer, but the buffer is not unloaded or
482 deleted. Not used for ":qa" or ":q" when
483 exiting Vim.
484 NOTE: When this autocommand is executed, the
485 current buffer "%" may be different from the
486 buffer being unloaded "<afile>".
487 *BufLeave*
488BufLeave Before leaving to another buffer. Also when
489 leaving or closing the current window and the
490 new current window is not for the same buffer.
491 Not used for ":qa" or ":q" when exiting Vim.
492 *BufNew*
493BufNew Just after creating a new buffer. Also used
494 just after a buffer has been renamed. When
495 the buffer is added to the buffer list BufAdd
496 will be triggered too.
497 NOTE: When this autocommand is executed, the
498 current buffer "%" may be different from the
499 buffer being created "<afile>".
Bram Moolenaar071d4272004-06-13 20:20:40 +0000500 *BufNewFile*
501BufNewFile When starting to edit a file that doesn't
502 exist. Can be used to read in a skeleton
503 file.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000504 *BufRead* *BufReadPost*
505BufRead or BufReadPost When starting to edit a new buffer, after
506 reading the file into the buffer, before
507 executing the modelines. See |BufWinEnter|
508 for when you need to do something after
509 processing the modelines.
Bram Moolenaar75ab5902022-04-18 15:36:40 +0100510 Also triggered:
511 - when writing an unnamed buffer in a way that
512 the buffer gets a name
513 - after successfully recovering a file
514 - for the filetypedetect group when executing
515 ":filetype detect"
516 Not triggered:
517 - for the `:read file` command
518 - when the file doesn't exist
Bram Moolenaar4770d092006-01-12 23:22:24 +0000519 *BufReadCmd*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000520BufReadCmd Before starting to edit a new buffer. Should
521 read the file into the buffer. |Cmd-event|
Bram Moolenaar4770d092006-01-12 23:22:24 +0000522 *BufReadPre* *E200* *E201*
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000523BufReadPre When starting to edit a new buffer, before
524 reading the file into the buffer. Not used
525 if the file doesn't exist.
526 *BufUnload*
527BufUnload Before unloading a buffer. This is when the
528 text in the buffer is going to be freed. This
529 may be after a BufWritePost and before a
530 BufDelete. Also used for all buffers that are
531 loaded when Vim is going to exit.
532 NOTE: When this autocommand is executed, the
533 current buffer "%" may be different from the
534 buffer being unloaded "<afile>".
Bram Moolenaar64d8e252016-09-06 22:12:34 +0200535 Don't change to another buffer or window, it
536 will cause problems!
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +0200537 When exiting and v:dying is 2 or more this
538 event is not triggered.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000539 *BufWinEnter*
540BufWinEnter After a buffer is displayed in a window. This
541 can be when the buffer is loaded (after
Bram Moolenaar446cb832008-06-24 21:56:24 +0000542 processing the modelines) or when a hidden
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000543 buffer is displayed in a window (and is no
Bram Moolenaar446cb832008-06-24 21:56:24 +0000544 longer hidden).
545 Does not happen for |:split| without
546 arguments, since you keep editing the same
547 buffer, or ":split" with a file that's already
Bram Moolenaarc236c162008-07-13 17:41:49 +0000548 open in a window, because it re-uses an
549 existing buffer. But it does happen for a
550 ":split" with the name of the current buffer,
551 since it reloads that buffer.
Bram Moolenaar606cb8b2018-05-03 20:40:20 +0200552 Does not happen for a terminal window, because
553 it starts in Terminal-Job mode and Normal mode
554 commands won't work. Use |TerminalOpen| instead.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000555 *BufWinLeave*
556BufWinLeave Before a buffer is removed from a window.
557 Not when it's still visible in another window.
558 Also triggered when exiting. It's triggered
559 before BufUnload or BufHidden.
560 NOTE: When this autocommand is executed, the
561 current buffer "%" may be different from the
562 buffer being unloaded "<afile>".
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +0200563 When exiting and v:dying is 2 or more this
564 event is not triggered.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000565 *BufWipeout*
566BufWipeout Before completely deleting a buffer. The
567 BufUnload and BufDelete events may be called
568 first (if the buffer was loaded and was in the
569 buffer list). Also used just before a buffer
570 is renamed (also when it's not in the buffer
571 list).
572 NOTE: When this autocommand is executed, the
573 current buffer "%" may be different from the
574 buffer being deleted "<afile>".
Bram Moolenaarb849e712009-06-24 15:51:37 +0000575 Don't change to another buffer, it will cause
576 problems.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000577 *BufWrite* *BufWritePre*
578BufWrite or BufWritePre Before writing the whole buffer to a file.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000579 *BufWriteCmd*
580BufWriteCmd Before writing the whole buffer to a file.
581 Should do the writing of the file and reset
Bram Moolenaar1cd871b2004-12-19 22:46:22 +0000582 'modified' if successful, unless '+' is in
583 'cpo' and writing to another file |cpo-+|.
584 The buffer contents should not be changed.
Bram Moolenaar5302d9e2011-09-14 17:55:08 +0200585 When the command resets 'modified' the undo
586 information is adjusted to mark older undo
587 states as 'modified', like |:write| does.
Bram Moolenaar1cd871b2004-12-19 22:46:22 +0000588 |Cmd-event|
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000589 *BufWritePost*
590BufWritePost After writing the whole buffer to a file
591 (should undo the commands for BufWritePre).
Bram Moolenaard5005162014-08-22 23:05:54 +0200592 *CmdUndefined*
593CmdUndefined When a user command is used but it isn't
594 defined. Useful for defining a command only
595 when it's used. The pattern is matched
596 against the command name. Both <amatch> and
597 <afile> are set to the name of the command.
598 NOTE: Autocompletion won't work until the
599 command is defined. An alternative is to
600 always define the user command and have it
601 invoke an autoloaded function. See |autoload|.
Bram Moolenaar153b7042018-01-31 15:48:32 +0100602 *CmdlineChanged*
Bram Moolenaarb5b75622018-03-09 22:22:21 +0100603CmdlineChanged After a change was made to the text in the
604 command line. Be careful not to mess up
605 the command line, it may cause Vim to lock up.
Bram Moolenaar153b7042018-01-31 15:48:32 +0100606 <afile> is set to a single character,
607 indicating the type of command-line.
608 |cmdwin-char|
Bram Moolenaarfafcf0d2017-10-19 18:35:51 +0200609 *CmdlineEnter*
610CmdlineEnter After moving the cursor to the command line,
611 where the user can type a command or search
Bram Moolenaar957cf672020-11-12 14:21:06 +0100612 string; including non-interactive use of ":"
613 in a mapping, but not when using |<Cmd>|.
Bram Moolenaar938ae282023-02-20 20:44:55 +0000614 The pattern is matched against the character
615 representing the type of command-line.
616 |cmdwin-char|
Bram Moolenaarfafcf0d2017-10-19 18:35:51 +0200617 <afile> is set to a single character,
618 indicating the type of command-line.
Bram Moolenaarfafcf0d2017-10-19 18:35:51 +0200619 *CmdlineLeave*
Bram Moolenaar957cf672020-11-12 14:21:06 +0100620CmdlineLeave Before leaving the command line; including
621 non-interactive use of ":" in a mapping, but
622 not when using |<Cmd>|.
Bram Moolenaar01164a62017-11-02 22:58:42 +0100623 Also when abandoning the command line, after
624 typing CTRL-C or <Esc>.
625 When the commands result in an error the
626 command line is still executed.
Bram Moolenaarfafcf0d2017-10-19 18:35:51 +0200627 <afile> is set to a single character,
628 indicating the type of command-line.
629 |cmdwin-char|
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000630 *CmdwinEnter*
631CmdwinEnter After entering the command-line window.
632 Useful for setting options specifically for
Bram Moolenaar96e38a82019-09-09 18:35:33 +0200633 this special type of window.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000634 <afile> is set to a single character,
635 indicating the type of command-line.
636 |cmdwin-char|
637 *CmdwinLeave*
638CmdwinLeave Before leaving the command-line window.
639 Useful to clean up any global setting done
Bram Moolenaar96e38a82019-09-09 18:35:33 +0200640 with CmdwinEnter.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000641 <afile> is set to a single character,
642 indicating the type of command-line.
643 |cmdwin-char|
644 *ColorScheme*
645ColorScheme After loading a color scheme. |:colorscheme|
Bram Moolenaar0daafaa2022-09-04 17:45:43 +0100646 Not triggered if the color scheme is not
647 found.
Bram Moolenaarb95186f2013-11-28 18:53:52 +0100648 The pattern is matched against the
649 colorscheme name. <afile> can be used for the
650 name of the actual file where this option was
651 set, and <amatch> for the new colorscheme
652 name.
653
Bram Moolenaar15142e22018-04-30 22:19:58 +0200654 *ColorSchemePre*
655ColorSchemePre Before loading a color scheme. |:colorscheme|
656 Useful to setup removing things added by a
657 color scheme, before another one is loaded.
Bram Moolenaar589edb32019-09-20 14:38:13 +0200658CompleteChanged *CompleteChanged*
Bram Moolenaard7f246c2019-04-08 18:15:41 +0200659 After each time the Insert mode completion
660 menu changed. Not fired on popup menu hide,
Bram Moolenaar3f169ce2020-01-26 22:43:31 +0100661 use |CompleteDonePre| or |CompleteDone| for
662 that. Never triggered recursively.
Bram Moolenaar754b5602006-02-09 23:53:20 +0000663
Bram Moolenaard7f246c2019-04-08 18:15:41 +0200664 Sets these |v:event| keys:
Bram Moolenaar911ead12019-04-21 00:03:35 +0200665 completed_item See |complete-items|.
Bram Moolenaard7f246c2019-04-08 18:15:41 +0200666 height nr of items visible
667 width screen cells
668 row top screen row
669 col leftmost screen column
670 size total nr of items
671 scrollbar TRUE if visible
672
673 It is not allowed to change the text |textlock|.
Bram Moolenaare9bd5722019-08-17 19:36:06 +0200674
675 The size and position of the popup are also
676 available by calling |pum_getpos()|.
677
Bram Moolenaar3f169ce2020-01-26 22:43:31 +0100678 *CompleteDonePre*
679CompleteDonePre After Insert mode completion is done. Either
680 when something was completed or abandoning
681 completion. |ins-completion|
682 |complete_info()| can be used, the info is
683 cleared after triggering CompleteDonePre.
684 The |v:completed_item| variable contains
685 information about the completed item.
686
Bram Moolenaar30b65812012-07-12 22:01:11 +0200687 *CompleteDone*
688CompleteDone After Insert mode completion is done. Either
689 when something was completed or abandoning
690 completion. |ins-completion|
Bram Moolenaar3f169ce2020-01-26 22:43:31 +0100691 |complete_info()| cannot be used, the info is
692 cleared before triggering CompleteDone. Use
693 CompleteDonePre if you need it.
Bram Moolenaar42a45122015-07-10 17:56:23 +0200694 The |v:completed_item| variable contains
695 information about the completed item.
Bram Moolenaar30b65812012-07-12 22:01:11 +0200696
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000697 *CursorHold*
698CursorHold When the user doesn't press a key for the time
Bram Moolenaard58a3bf2020-09-28 21:48:16 +0200699 specified with 'updatetime'. Not triggered
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000700 until the user has pressed a key (i.e. doesn't
701 fire every 'updatetime' ms if you leave Vim to
702 make some coffee. :) See |CursorHold-example|
703 for previewing tags.
704 This event is only triggered in Normal mode.
Bram Moolenaard7afed32007-05-06 13:26:41 +0000705 It is not triggered when waiting for a command
706 argument to be typed, or a movement after an
707 operator.
Bram Moolenaare3226be2005-12-18 22:10:00 +0000708 While recording the CursorHold event is not
709 triggered. |q|
Bram Moolenaar3a991dd2014-10-02 01:41:41 +0200710 *<CursorHold>*
711 Internally the autocommand is triggered by the
712 <CursorHold> key. In an expression mapping
713 |getchar()| may see this character.
714
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000715 Note: Interactive commands cannot be used for
716 this event. There is no hit-enter prompt,
717 the screen is updated directly (when needed).
718 Note: In the future there will probably be
719 another option to set the time.
720 Hint: to force an update of the status lines
721 use: >
722 :let &ro = &ro
Bram Moolenaar5666fcd2019-12-26 14:35:26 +0100723< {only on Amiga, Unix, Win32 and all GUI
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000724 versions}
Bram Moolenaar754b5602006-02-09 23:53:20 +0000725 *CursorHoldI*
726CursorHoldI Just like CursorHold, but in Insert mode.
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +0200727 Not triggered when waiting for another key,
728 e.g. after CTRL-V, and not when in CTRL-X mode
729 |insert_expand|.
Bram Moolenaar754b5602006-02-09 23:53:20 +0000730
731 *CursorMoved*
Bram Moolenaar52b91d82013-06-15 21:39:51 +0200732CursorMoved After the cursor was moved in Normal or Visual
733 mode. Also when the text of the cursor line
734 has been changed, e.g., with "x", "rx" or "p".
Bram Moolenaar46eea442022-03-30 10:51:39 +0100735 Not always triggered when there is typeahead,
736 while executing commands in a script file,
737 when an operator is pending or when moving to
Bram Moolenaar90df4b92021-07-07 20:26:08 +0200738 another window while remaining at the same
739 cursor position.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +0000740 For an example see |match-parens|.
Bram Moolenaar26967612019-03-17 17:13:16 +0100741 Note: This can not be skipped with
742 `:noautocmd`.
Bram Moolenaarbf884932013-04-05 22:26:15 +0200743 Careful: This is triggered very often, don't
744 do anything that the user does not expect or
745 that is slow.
Bram Moolenaar754b5602006-02-09 23:53:20 +0000746 *CursorMovedI*
747CursorMovedI After the cursor was moved in Insert mode.
Bram Moolenaar5302d9e2011-09-14 17:55:08 +0200748 Not triggered when the popup menu is visible.
Bram Moolenaar754b5602006-02-09 23:53:20 +0000749 Otherwise the same as CursorMoved.
Bram Moolenaar75ab5902022-04-18 15:36:40 +0100750 *DiffUpdated*
751DiffUpdated After diffs have been updated. Depending on
752 what kind of diff is being used (internal or
753 external) this can be triggered on every
754 change or when doing |:diffupdate|.
755 *DirChangedPre*
756DirChangedPre The working directory is going to be changed,
757 as with |DirChanged|. The pattern is like
758 with |DirChanged|. The new directory can be
759 found in v:event.directory.
760 *DirChanged*
761DirChanged The working directory has changed in response
762 to the |:cd| or |:tcd| or |:lcd| commands, or
763 as a result of the 'autochdir' option.
764 The pattern can be:
765 "window" to trigger on `:lcd`
766 "tabpage" to trigger on `:tcd`
767 "global" to trigger on `:cd`
768 "auto" to trigger on 'autochdir'.
769 "drop" to trigger on editing a file
770 <afile> is set to the new directory name.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000771 *EncodingChanged*
772EncodingChanged Fires off after the 'encoding' option has been
773 changed. Useful to set up fonts, for example.
Bram Moolenaar75ab5902022-04-18 15:36:40 +0100774 *ExitPre*
775ExitPre When using `:quit`, `:wq` in a way it makes
776 Vim exit, or using `:qall`, just after
777 |QuitPre|. Can be used to close any
778 non-essential window. Exiting may still be
779 cancelled if there is a modified buffer that
780 isn't automatically saved, use |VimLeavePre|
781 for really exiting.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000782 *FileAppendCmd*
783FileAppendCmd Before appending to a file. Should do the
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +0000784 appending to the file. Use the '[ and ']
Bram Moolenaar22863042021-10-16 15:23:36 +0100785 marks for the range of lines. |Cmd-event|
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000786 *FileAppendPost*
787FileAppendPost After appending to a file.
788 *FileAppendPre*
789FileAppendPre Before appending to a file. Use the '[ and ']
790 marks for the range of lines.
791 *FileChangedRO*
792FileChangedRO Before making the first change to a read-only
793 file. Can be used to check-out the file from
794 a source control system. Not triggered when
795 the change was caused by an autocommand.
796 This event is triggered when making the first
797 change in a buffer or the first change after
Bram Moolenaar61660ea2006-04-07 21:40:07 +0000798 'readonly' was set, just before the change is
799 applied to the text.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000800 WARNING: If the autocommand moves the cursor
801 the effect of the change is undefined.
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000802 *E788*
803 It is not allowed to change to another buffer
804 here. You can reload the buffer but not edit
805 another one.
Bram Moolenaar92dff182014-02-11 19:15:50 +0100806 *E881*
807 If the number of lines changes saving for undo
808 may fail and the change will be aborted.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000809 *FileChangedShell*
810FileChangedShell When Vim notices that the modification time of
811 a file has changed since editing started.
812 Also when the file attributes of the file
Bram Moolenaare968e362014-05-13 20:23:24 +0200813 change or when the size of the file changes.
814 |timestamp|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000815 Mostly triggered after executing a shell
816 command, but also with a |:checktime| command
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +0200817 or when gvim regains input focus.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000818 This autocommand is triggered for each changed
819 file. It is not used when 'autoread' is set
820 and the buffer was not changed. If a
821 FileChangedShell autocommand is present the
822 warning message and prompt is not given.
Bram Moolenaar19a09a12005-03-04 23:39:37 +0000823 The |v:fcs_reason| variable is set to indicate
824 what happened and |v:fcs_choice| can be used
825 to tell Vim what to do next.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000826 NOTE: When this autocommand is executed, the
827 current buffer "%" may be different from the
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +0200828 buffer that was changed, which is in "<afile>".
Bram Moolenaar071d4272004-06-13 20:20:40 +0000829 NOTE: The commands must not change the current
830 buffer, jump to another buffer or delete a
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100831 buffer. *E246* *E811*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000832 NOTE: This event never nests, to avoid an
833 endless loop. This means that while executing
834 commands for the FileChangedShell event no
835 other FileChangedShell event will be
836 triggered.
Bram Moolenaar7d47b6e2006-03-15 22:59:18 +0000837 *FileChangedShellPost*
838FileChangedShellPost After handling a file that was changed outside
839 of Vim. Can be used to update the statusline.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000840 *FileEncoding*
841FileEncoding Obsolete. It still works and is equivalent
842 to |EncodingChanged|.
843 *FileReadCmd*
844FileReadCmd Before reading a file with a ":read" command.
845 Should do the reading of the file. |Cmd-event|
846 *FileReadPost*
847FileReadPost After reading a file with a ":read" command.
848 Note that Vim sets the '[ and '] marks to the
849 first and last line of the read. This can be
850 used to operate on the lines just read.
851 *FileReadPre*
852FileReadPre Before reading a file with a ":read" command.
853 *FileType*
Bram Moolenaard7afed32007-05-06 13:26:41 +0000854FileType When the 'filetype' option has been set. The
855 pattern is matched against the filetype.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000856 <afile> can be used for the name of the file
857 where this option was set, and <amatch> for
Bram Moolenaar74675a62017-07-15 13:53:23 +0200858 the new value of 'filetype'. Navigating to
859 another window or buffer is not allowed.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000860 See |filetypes|.
861 *FileWriteCmd*
862FileWriteCmd Before writing to a file, when not writing the
863 whole buffer. Should do the writing to the
864 file. Should not change the buffer. Use the
865 '[ and '] marks for the range of lines.
866 |Cmd-event|
867 *FileWritePost*
868FileWritePost After writing to a file, when not writing the
869 whole buffer.
870 *FileWritePre*
871FileWritePre Before writing to a file, when not writing the
872 whole buffer. Use the '[ and '] marks for the
873 range of lines.
874 *FilterReadPost*
875FilterReadPost After reading a file from a filter command.
876 Vim checks the pattern against the name of
877 the current buffer as with FilterReadPre.
878 Not triggered when 'shelltemp' is off.
879 *FilterReadPre* *E135*
880FilterReadPre Before reading a file from a filter command.
881 Vim checks the pattern against the name of
882 the current buffer, not the name of the
883 temporary file that is the output of the
884 filter command.
885 Not triggered when 'shelltemp' is off.
886 *FilterWritePost*
887FilterWritePost After writing a file for a filter command or
Bram Moolenaar4c05fa02019-01-01 15:32:17 +0100888 making a diff with an external diff (see
Bram Moolenaar22863042021-10-16 15:23:36 +0100889 |DiffUpdated| for internal diff).
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000890 Vim checks the pattern against the name of
891 the current buffer as with FilterWritePre.
892 Not triggered when 'shelltemp' is off.
893 *FilterWritePre*
894FilterWritePre Before writing a file for a filter command or
Bram Moolenaar4c05fa02019-01-01 15:32:17 +0100895 making a diff with an external diff.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000896 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.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000901 *FocusGained*
902FocusGained When Vim got input focus. Only for the GUI
903 version and a few console versions where this
904 can be detected.
905 *FocusLost*
906FocusLost When Vim lost input focus. Only for the GUI
907 version and a few console versions where this
Bram Moolenaar843ee412004-06-30 16:16:41 +0000908 can be detected. May also happen when a
909 dialog pops up.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000910 *FuncUndefined*
911FuncUndefined When a user function is used but it isn't
912 defined. Useful for defining a function only
Bram Moolenaard7afed32007-05-06 13:26:41 +0000913 when it's used. The pattern is matched
914 against the function name. Both <amatch> and
915 <afile> are set to the name of the function.
Bram Moolenaar4072ba52020-12-23 13:56:35 +0100916 Not triggered when compiling a |Vim9|
917 function.
Bram Moolenaard5005162014-08-22 23:05:54 +0200918 NOTE: When writing Vim scripts a better
919 alternative is to use an autoloaded function.
Bram Moolenaar7c626922005-02-07 22:01:03 +0000920 See |autoload-functions|.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000921 *GUIEnter*
922GUIEnter After starting the GUI successfully, and after
923 opening the window. It is triggered before
924 VimEnter when using gvim. Can be used to
925 position the window from a .gvimrc file: >
926 :autocmd GUIEnter * winpos 100 50
Bram Moolenaard7afed32007-05-06 13:26:41 +0000927< *GUIFailed*
928GUIFailed After starting the GUI failed. Vim may
929 continue to run in the terminal, if possible
930 (only on Unix and alikes, when connecting the
931 X server fails). You may want to quit Vim: >
932 :autocmd GUIFailed * qall
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000933< *InsertChange*
934InsertChange When typing <Insert> while in Insert or
935 Replace mode. The |v:insertmode| variable
936 indicates the new mode.
937 Be careful not to move the cursor or do
938 anything else that the user does not expect.
Bram Moolenaare659c952011-05-19 17:25:41 +0200939 *InsertCharPre*
940InsertCharPre When a character is typed in Insert mode,
941 before inserting the char.
942 The |v:char| variable indicates the char typed
943 and can be changed during the event to insert
944 a different character. When |v:char| is set
945 to more than one character this text is
946 inserted literally.
947 It is not allowed to change the text |textlock|.
948 The event is not triggered when 'paste' is
Bram Moolenaarb5b75622018-03-09 22:22:21 +0100949 set. {only with the +eval feature}
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000950 *InsertEnter*
Bram Moolenaard7afed32007-05-06 13:26:41 +0000951InsertEnter Just before starting Insert mode. Also for
952 Replace mode and Virtual Replace mode. The
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000953 |v:insertmode| variable indicates the mode.
Bram Moolenaar097c9922013-05-19 21:15:15 +0200954 Be careful not to do anything else that the
955 user does not expect.
956 The cursor is restored afterwards. If you do
957 not want that set |v:char| to a non-empty
958 string.
Bram Moolenaarb53e13a2020-10-21 12:19:53 +0200959 *InsertLeavePre*
960InsertLeavePre Just before leaving Insert mode. Also when
Bram Moolenaarcb80aa22020-10-26 21:12:46 +0100961 using CTRL-O |i_CTRL-O|. Be careful not to
Bram Moolenaarb53e13a2020-10-21 12:19:53 +0200962 change mode or use `:normal`, it will likely
963 cause trouble.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000964 *InsertLeave*
Bram Moolenaarb53e13a2020-10-21 12:19:53 +0200965InsertLeave Just after leaving Insert mode. Also when
966 using CTRL-O |i_CTRL-O|. But not for |i_CTRL-C|.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000967 *MenuPopup*
968MenuPopup Just before showing the popup menu (under the
969 right mouse button). Useful for adjusting the
970 menu for what is under the cursor or mouse
971 pointer.
Bram Moolenaar4c5d8152018-10-19 22:36:53 +0200972 The pattern is matched against one or two
973 characters representing the mode:
Bram Moolenaar4e330bb2005-12-07 21:04:31 +0000974 n Normal
975 v Visual
976 o Operator-pending
977 i Insert
Bram Moolenaar551dbcc2006-04-25 22:13:59 +0000978 c Command line
Bram Moolenaar4c5d8152018-10-19 22:36:53 +0200979 tl Terminal
=?UTF-8?q?Magnus=20Gro=C3=9F?=f1e88762021-09-12 13:39:55 +0200980 *ModeChanged*
981ModeChanged After changing the mode. The pattern is
982 matched against `'old_mode:new_mode'`, for
=?UTF-8?q?Magnus=20Gro=C3=9F?=25def2c2021-10-22 18:56:39 +0100983 example match against `*:c*` to simulate
984 |CmdlineEnter|.
=?UTF-8?q?Magnus=20Gro=C3=9F?=f1e88762021-09-12 13:39:55 +0200985 The following values of |v:event| are set:
986 old_mode The mode before it changed.
987 new_mode The new mode as also returned
=?UTF-8?q?Magnus=20Gro=C3=9F?=25def2c2021-10-22 18:56:39 +0100988 by |mode()| called with a
989 non-zero argument.
=?UTF-8?q?Magnus=20Gro=C3=9F?=f1e88762021-09-12 13:39:55 +0200990 When ModeChanged is triggered, old_mode will
991 have the value of new_mode when the event was
992 last triggered.
=?UTF-8?q?Magnus=20Gro=C3=9F?=25def2c2021-10-22 18:56:39 +0100993 This will be triggered on every minor mode
994 change.
=?UTF-8?q?Magnus=20Gro=C3=9F?=f1e88762021-09-12 13:39:55 +0200995 Usage example to use relative line numbers
Bram Moolenaar6e649222021-10-04 21:32:54 +0100996 when entering Visual mode: >
=?UTF-8?q?Magnus=20Gro=C3=9F?=25def2c2021-10-22 18:56:39 +0100997 :au ModeChanged [vV\x16]*:* let &l:rnu = mode() =~# '^[vV\x16]'
998 :au ModeChanged *:[vV\x16]* let &l:rnu = mode() =~# '^[vV\x16]'
999 :au WinEnter,WinLeave * let &l:rnu = mode() =~# '^[vV\x16]'
=?UTF-8?q?Magnus=20Gro=C3=9F?=f1e88762021-09-12 13:39:55 +02001000< *OptionSet*
Bram Moolenaar53744302015-07-17 17:38:22 +02001001OptionSet After setting an option. The pattern is
1002 matched against the long option name.
Bram Moolenaard7c96872019-06-15 17:12:48 +02001003 |<amatch>| indicates what option has been set.
Bram Moolenaar53744302015-07-17 17:38:22 +02001004
Bram Moolenaard7c96872019-06-15 17:12:48 +02001005 |v:option_type| indicates whether it's global
Bram Moolenaar6c1e1572019-06-22 02:13:00 +02001006 or local scoped.
Bram Moolenaard7c96872019-06-15 17:12:48 +02001007 |v:option_command| indicates what type of
1008 set/let command was used (follow the tag to
1009 see the table).
1010 |v:option_new| indicates the newly set value.
Bram Moolenaar6c1e1572019-06-22 02:13:00 +02001011 |v:option_oldlocal| has the old local value.
1012 |v:option_oldglobal| has the old global value.
Bram Moolenaard7c96872019-06-15 17:12:48 +02001013 |v:option_old| indicates the old option value.
1014
1015 |v:option_oldlocal| is only set when |:set|
1016 or |:setlocal| or a |modeline| was used to set
1017 the option. Similarly |v:option_oldglobal| is
1018 only set when |:set| or |:setglobal| was used.
1019
Bram Moolenaar10e8ff92023-06-10 21:40:39 +01001020 This does not set |<abuf>|, you could use
1021 |bufnr()|.
1022
Bram Moolenaard7c96872019-06-15 17:12:48 +02001023 Note that when setting a |global-local| string
1024 option with |:set|, then |v:option_old| is the
1025 old global value. However, for all other kinds
1026 of options (local string options, global-local
1027 number options, ...) it is the old local
1028 value.
1029
1030 OptionSet is not triggered on startup and for
1031 the 'key' option for obvious reasons.
Bram Moolenaar53744302015-07-17 17:38:22 +02001032
Bram Moolenaarf9132812015-07-21 19:19:13 +02001033 Usage example: Check for the existence of the
1034 directory in the 'backupdir' and 'undodir'
1035 options, create the directory if it doesn't
1036 exist yet.
1037
1038 Note: It's a bad idea to reset an option
1039 during this autocommand, this may break a
1040 plugin. You can always use `:noa` to prevent
1041 triggering this autocommand.
Bram Moolenaar53744302015-07-17 17:38:22 +02001042
Bram Moolenaar95bafa22018-10-02 13:26:25 +02001043 When using |:set| in the autocommand the event
1044 is not triggered again.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001045 *QuickFixCmdPre*
1046QuickFixCmdPre Before a quickfix command is run (|:make|,
Bram Moolenaara6557602006-02-04 22:43:20 +00001047 |:lmake|, |:grep|, |:lgrep|, |:grepadd|,
1048 |:lgrepadd|, |:vimgrep|, |:lvimgrep|,
Bram Moolenaar6be7f872012-01-20 21:08:56 +01001049 |:vimgrepadd|, |:lvimgrepadd|, |:cscope|,
Bram Moolenaar84f72352012-03-11 15:57:40 +01001050 |:cfile|, |:cgetfile|, |:caddfile|, |:lfile|,
1051 |:lgetfile|, |:laddfile|, |:helpgrep|,
Bram Moolenaar64d8e252016-09-06 22:12:34 +02001052 |:lhelpgrep|, |:cexpr|, |:cgetexpr|,
1053 |:caddexpr|, |:cbuffer|, |:cgetbuffer|,
1054 |:caddbuffer|).
Bram Moolenaarf1eeae92010-05-14 23:14:42 +02001055 The pattern is matched against the command
1056 being run. When |:grep| is used but 'grepprg'
1057 is set to "internal" it still matches "grep".
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001058 This command cannot be used to set the
1059 'makeprg' and 'grepprg' variables.
1060 If this command causes an error, the quickfix
1061 command is not executed.
1062 *QuickFixCmdPost*
1063QuickFixCmdPost Like QuickFixCmdPre, but after a quickfix
Bram Moolenaarf9393ef2006-04-24 19:47:27 +00001064 command is run, before jumping to the first
Bram Moolenaar8ec1f852012-03-07 20:13:49 +01001065 location. For |:cfile| and |:lfile| commands
Bram Moolenaarb59ae592022-11-23 23:46:31 +00001066 it is run after the error file is read and
1067 before moving to the first error.
Bram Moolenaar8ec1f852012-03-07 20:13:49 +01001068 See |QuickFixCmdPost-example|.
Bram Moolenaar30b65812012-07-12 22:01:11 +02001069 *QuitPre*
Bram Moolenaarac7bd632013-03-19 11:35:58 +01001070QuitPre When using `:quit`, `:wq` or `:qall`, before
1071 deciding whether it closes the current window
Bram Moolenaard2ea7cf2021-05-30 20:54:13 +02001072 or quits Vim. For `:wq` the buffer is written
1073 before QuitPre is triggered. Can be used to
1074 close any non-essential window if the current
1075 window is the last ordinary window.
Bram Moolenaar12a96de2018-03-11 14:44:18 +01001076 Also see |ExitPre|.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001077 *RemoteReply*
1078RemoteReply When a reply from a Vim that functions as
Bram Moolenaard7afed32007-05-06 13:26:41 +00001079 server was received |server2client()|. The
1080 pattern is matched against the {serverid}.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001081 <amatch> is equal to the {serverid} from which
1082 the reply was sent, and <afile> is the actual
1083 reply string.
1084 Note that even if an autocommand is defined,
1085 the reply should be read with |remote_read()|
1086 to consume it.
Bram Moolenaar8aeec402019-09-15 23:02:04 +02001087 *SafeState*
1088SafeState When nothing is pending, going to wait for the
1089 user to type a character.
1090 This will not be triggered when:
1091 - an operator is pending
1092 - a register was entered with "r
1093 - halfway executing a command
1094 - executing a mapping
1095 - there is typeahead
1096 - Insert mode completion is active
1097 - Command line completion is active
1098 You can use `mode()` to find out what state
1099 Vim is in. That may be:
1100 - VIsual mode
1101 - Normal mode
1102 - Insert mode
1103 - Command-line mode
1104 Depending on what you want to do, you may also
1105 check more with `state()`, e.g. whether the
1106 screen was scrolled for messages.
Bram Moolenaar69198cb2019-09-16 21:58:13 +02001107 *SafeStateAgain*
1108SafeStateAgain Like SafeState but after processing any
1109 messages and invoking callbacks. This may be
1110 triggered often, don't do something that takes
1111 time.
Bram Moolenaar8aeec402019-09-15 23:02:04 +02001112
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001113 *SessionLoadPost*
1114SessionLoadPost After loading the session file created using
1115 the |:mksession| command.
Bram Moolenaara94bc432006-03-10 21:42:59 +00001116 *ShellCmdPost*
1117ShellCmdPost After executing a shell command with |:!cmd|,
1118 |:shell|, |:make| and |:grep|. Can be used to
1119 check for any changed files.
1120 *ShellFilterPost*
1121ShellFilterPost After executing a shell command with
1122 ":{range}!cmd", ":w !cmd" or ":r !cmd".
1123 Can be used to check for any changed files.
Bram Moolenaar1f35bf92006-03-07 22:38:47 +00001124 *SourcePre*
1125SourcePre Before sourcing a Vim script. |:source|
Bram Moolenaar8dd1aa52007-01-16 20:33:19 +00001126 <afile> is the name of the file being sourced.
Bram Moolenaar2b618522019-01-12 13:26:03 +01001127 *SourcePost*
1128SourcePost After sourcing a Vim script. |:source|
1129 <afile> is the name of the file being sourced.
1130 Not triggered when sourcing was interrupted.
1131 Also triggered after a SourceCmd autocommand
1132 was triggered.
Bram Moolenaar8dd1aa52007-01-16 20:33:19 +00001133 *SourceCmd*
1134SourceCmd When sourcing a Vim script. |:source|
1135 <afile> is the name of the file being sourced.
1136 The autocommand must source this file.
1137 |Cmd-event|
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +00001138 *SpellFileMissing*
1139SpellFileMissing When trying to load a spell checking file and
Bram Moolenaar8dd1aa52007-01-16 20:33:19 +00001140 it can't be found. The pattern is matched
1141 against the language. <amatch> is the
1142 language, 'encoding' also matters. See
Bram Moolenaarafeb4fa2006-02-01 21:51:12 +00001143 |spell-SpellFileMissing|.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001144 *StdinReadPost*
1145StdinReadPost After reading from the stdin into the buffer,
1146 before executing the modelines. Only used
1147 when the "-" argument was used when Vim was
1148 started |--|.
1149 *StdinReadPre*
1150StdinReadPre Before reading from stdin into the buffer.
1151 Only used when the "-" argument was used when
1152 Vim was started |--|.
1153 *SwapExists*
1154SwapExists Detected an existing swap file when starting
1155 to edit a file. Only when it is possible to
1156 select a way to handle the situation, when Vim
1157 would ask the user what to do.
1158 The |v:swapname| variable holds the name of
Bram Moolenaarb3480382005-12-11 21:33:32 +00001159 the swap file found, <afile> the file being
1160 edited. |v:swapcommand| may contain a command
1161 to be executed in the opened file.
1162 The commands should set the |v:swapchoice|
1163 variable to a string with one character to
1164 tell Vim what should be done next:
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001165 'o' open read-only
1166 'e' edit the file anyway
1167 'r' recover
1168 'd' delete the swap file
1169 'q' quit, don't edit the file
1170 'a' abort, like hitting CTRL-C
1171 When set to an empty string the user will be
1172 asked, as if there was no SwapExists autocmd.
Bram Moolenaarb849e712009-06-24 15:51:37 +00001173 *E812*
1174 It is not allowed to change to another buffer,
1175 change a buffer name or change directory
1176 here.
Bram Moolenaarb5b75622018-03-09 22:22:21 +01001177 {only available with the +eval feature}
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001178 *Syntax*
Bram Moolenaard7afed32007-05-06 13:26:41 +00001179Syntax When the 'syntax' option has been set. The
1180 pattern is matched against the syntax name.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001181 <afile> can be used for the name of the file
1182 where this option was set, and <amatch> for
1183 the new value of 'syntax'.
1184 See |:syn-on|.
Bram Moolenaar12c11d52016-07-19 23:13:03 +02001185 *TabClosed*
1186TabClosed After closing a tab page.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00001187 *TabEnter*
1188TabEnter Just after entering a tab page. |tab-page|
Bram Moolenaar56a907a2006-05-06 21:44:30 +00001189 After triggering the WinEnter and before
1190 triggering the BufEnter event.
Bram Moolenaarfaa959a2006-02-20 21:37:40 +00001191 *TabLeave*
1192TabLeave Just before leaving a tab page. |tab-page|
1193 A WinLeave event will have been triggered
1194 first.
Bram Moolenaarc917da42016-07-19 22:31:36 +02001195 *TabNew*
1196TabNew When a tab page was created. |tab-page|
1197 A WinEnter event will have been triggered
1198 first, TabEnter follows.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001199 *TermChanged*
1200TermChanged After the value of 'term' has changed. Useful
1201 for re-loading the syntax file to update the
1202 colors, fonts and other terminal-dependent
1203 settings. Executed for all loaded buffers.
Bram Moolenaarb852c3e2018-03-11 16:55:36 +01001204 *TerminalOpen*
1205TerminalOpen Just after a terminal buffer was created, with
1206 `:terminal` or |term_start()|. This event is
1207 triggered even if the buffer is created
1208 without a window, with the ++hidden option.
Bram Moolenaar28ed4df2019-10-26 16:21:40 +02001209 *TerminalWinOpen*
1210TerminalWinOpen Just after a terminal buffer was created, with
1211 `:terminal` or |term_start()|. This event is
1212 triggered only if the buffer is created
1213 with a window. Can be used to set window
1214 local options for the terminal window.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001215 *TermResponse*
1216TermResponse After the response to |t_RV| is received from
1217 the terminal. The value of |v:termresponse|
1218 can be used to do things depending on the
Bram Moolenaar8e5af3e2011-04-28 19:02:44 +02001219 terminal version. Note that this event may be
1220 triggered halfway executing another event,
1221 especially if file I/O, a shell command or
1222 anything else that takes time is involved.
Bram Moolenaarbf884932013-04-05 22:26:15 +02001223 *TextChanged*
1224TextChanged After a change was made to the text in the
Bram Moolenaard09091d2019-01-17 16:07:22 +01001225 current buffer in Normal mode. That is after
1226 |b:changedtick| has changed (also when that
1227 happened before the TextChanged autocommand
1228 was defined).
Bram Moolenaarbf884932013-04-05 22:26:15 +02001229 Not triggered when there is typeahead or when
1230 an operator is pending.
Bram Moolenaar26967612019-03-17 17:13:16 +01001231 Note: This can not be skipped with
1232 `:noautocmd`.
Bram Moolenaarbf884932013-04-05 22:26:15 +02001233 Careful: This is triggered very often, don't
1234 do anything that the user does not expect or
1235 that is slow.
1236 *TextChangedI*
1237TextChangedI After a change was made to the text in the
1238 current buffer in Insert mode.
1239 Not triggered when the popup menu is visible.
1240 Otherwise the same as TextChanged.
Bram Moolenaar5a093432018-02-10 18:15:19 +01001241 *TextChangedP*
1242TextChangedP After a change was made to the text in the
1243 current buffer in Insert mode, only when the
1244 popup menu is visible. Otherwise the same as
1245 TextChanged.
Shougo Matsushita4ccaedf2022-10-15 11:48:00 +01001246 *TextChangedT*
1247TextChangedT After a change was made to the text in the
1248 current buffer in Terminal mode.
1249 Otherwise the same as TextChanged.
Bram Moolenaarf0b03c42017-12-17 17:17:07 +01001250 *TextYankPost*
Bram Moolenaar7e1652c2017-12-16 18:27:02 +01001251TextYankPost After text has been yanked or deleted in the
1252 current buffer. The following values of
1253 |v:event| can be used to determine the operation
1254 that triggered this autocmd:
Bram Moolenaara016eeb2022-04-09 11:37:38 +01001255 inclusive TRUE if the motion is
1256 |inclusive| else the motion is
1257 |exclusive|.
Bram Moolenaar589edb32019-09-20 14:38:13 +02001258 operator The operation performed.
1259 regcontents Text that was stored in the
Bram Moolenaar7e1652c2017-12-16 18:27:02 +01001260 register, as a list of lines,
1261 like with: >
1262 getreg(r, 1, 1)
Bram Moolenaar22863042021-10-16 15:23:36 +01001263< regname Name of the register or empty
1264 string for the unnamed
1265 register, see |registers|.
Bram Moolenaar7e1652c2017-12-16 18:27:02 +01001266 regtype Type of the register, see
1267 |getregtype()|.
Bram Moolenaar37d16732020-06-12 22:09:01 +02001268 visual True if the operation is
1269 performed on a |Visual| area.
Bram Moolenaar7e1652c2017-12-16 18:27:02 +01001270 Not triggered when |quote_| is used nor when
1271 called recursively.
1272 It is not allowed to change the buffer text,
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00001273 see |textlock|. *E1064*
Bram Moolenaarb5b75622018-03-09 22:22:21 +01001274 {only when compiled with the +eval feature}
Bram Moolenaarbe5ee862020-06-10 20:56:58 +02001275
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001276 *User*
1277User Never executed automatically. To be used for
1278 autocommands that are only executed with
1279 ":doautocmd".
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02001280 Note that when `:doautocmd User MyEvent` is
1281 used while there are no matching autocommands,
1282 you will get an error. If you don't want
LemonBoy09371822022-04-08 15:18:45 +01001283 that, either check whether an autocommand is
1284 defined using `exists('#User#MyEvent')` or
1285 define a dummy autocommand yourself.
1286 Example: >
1287 if exists('#User#MyEvent')
1288 doautocmd User MyEvent
1289 endif
Bram Moolenaarb529cfb2022-07-25 15:42:07 +01001290<
Bram Moolenaarbe5ee862020-06-10 20:56:58 +02001291 *SigUSR1*
1292SigUSR1 After the SIGUSR1 signal has been detected.
1293 Could be used if other ways of notifying Vim
1294 are not feasible. E.g. to check for the
1295 result of a build that takes a long time, or
1296 when a motion sensor is triggered.
1297 {only on Unix}
1298
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001299 *UserGettingBored*
Bram Moolenaarbf884932013-04-05 22:26:15 +02001300UserGettingBored When the user presses the same key 42 times.
1301 Just kidding! :-)
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001302 *VimEnter*
1303VimEnter After doing all the startup stuff, including
1304 loading .vimrc files, executing the "-c cmd"
1305 arguments, creating all windows and loading
1306 the buffers in them.
Bram Moolenaar14735512016-03-26 21:00:08 +01001307 Just before this event is triggered the
1308 |v:vim_did_enter| variable is set, so that you
1309 can do: >
1310 if v:vim_did_enter
1311 call s:init()
1312 else
Bram Moolenaar589edb32019-09-20 14:38:13 +02001313 au VimEnter * call s:init()
Bram Moolenaar14735512016-03-26 21:00:08 +01001314 endif
1315< *VimLeave*
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001316VimLeave Before exiting Vim, just after writing the
1317 .viminfo file. Executed only once, like
1318 VimLeavePre.
1319 To detect an abnormal exit use |v:dying|.
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +02001320 When v:dying is 2 or more this event is not
1321 triggered.
Bram Moolenaarf0068c52020-11-30 17:42:10 +01001322 To get the exit code use |v:exiting|.
Bram Moolenaar4e330bb2005-12-07 21:04:31 +00001323 *VimLeavePre*
1324VimLeavePre Before exiting Vim, just before writing the
1325 .viminfo file. This is executed only once,
1326 if there is a match with the name of what
1327 happens to be the current buffer when exiting.
1328 Mostly useful with a "*" pattern. >
1329 :autocmd VimLeavePre * call CleanupStuff()
1330< To detect an abnormal exit use |v:dying|.
Bram Moolenaar0e1e25f2010-05-28 21:07:08 +02001331 When v:dying is 2 or more this event is not
1332 triggered.
Bram Moolenaarf0068c52020-11-30 17:42:10 +01001333 To get the exit code use |v:exiting|.
Bram Moolenaar7d47b6e2006-03-15 22:59:18 +00001334 *VimResized*
1335VimResized After the Vim window was resized, thus 'lines'
1336 and/or 'columns' changed. Not when starting
1337 up though.
Bram Moolenaar100118c2020-12-11 19:30:34 +01001338 *VimResume*
1339VimResume When the Vim instance is resumed after being
1340 suspended and |VimSuspend| was triggered.
1341 Useful for triggering |:checktime| and ensure
1342 the buffers content did not change while Vim
1343 was suspended: >
1344 :autocmd VimResume * checktime
1345< *VimSuspend*
1346VimSuspend When the Vim instance is suspended. Only when
dbivolaruab16ad32021-12-29 19:41:47 +00001347 CTRL-Z was typed inside Vim, or when the SIGTSTP
1348 signal was sent to Vim, but not for SIGSTOP.
naohiro ono23beefe2021-11-13 12:38:49 +00001349 *WinClosed*
Bram Moolenaarb59ae592022-11-23 23:46:31 +00001350WinClosed When closing a window, just before it is
1351 removed from the window layout. The pattern
1352 is matched against the |window-ID|. Both
naohiro ono23beefe2021-11-13 12:38:49 +00001353 <amatch> and <afile> are set to the
1354 |window-ID|. Non-recursive (event cannot
1355 trigger itself).
Bram Moolenaar071d4272004-06-13 20:20:40 +00001356 *WinEnter*
1357WinEnter After entering another window. Not done for
1358 the first window, when Vim has just started.
1359 Useful for setting the window height.
1360 If the window is for another buffer, Vim
1361 executes the BufEnter autocommands after the
1362 WinEnter autocommands.
Bram Moolenaar7dda86f2018-04-20 22:36:41 +02001363 Note: For split and tabpage commands the
1364 WinEnter event is triggered after the split
1365 or tab command but before the file is loaded.
1366
Bram Moolenaar071d4272004-06-13 20:20:40 +00001367 *WinLeave*
1368WinLeave Before leaving a window. If the window to be
1369 entered next is for a different buffer, Vim
1370 executes the BufLeave autocommands before the
1371 WinLeave autocommands (but not for ":new").
1372 Not used for ":qa" or ":q" when exiting Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001373
Bram Moolenaar12c11d52016-07-19 23:13:03 +02001374 *WinNew*
1375WinNew When a new window was created. Not done for
Bram Moolenaar50ba5262016-09-22 22:33:02 +02001376 the first window, when Vim has just started.
Bram Moolenaar12c11d52016-07-19 23:13:03 +02001377 Before a WinEnter event.
1378
LemonBoy09371822022-04-08 15:18:45 +01001379 *WinScrolled*
Bram Moolenaar35fc61c2022-11-22 12:40:50 +00001380WinScrolled After any window in the current tab page
1381 scrolled the text (horizontally or vertically)
1382 or changed width or height. See
1383 |win-scrolled-resized|.
Bram Moolenaar0a60f792022-11-19 21:18:11 +00001384
1385 The pattern is matched against the |window-ID|
1386 of the first window that scrolled or resized.
1387 Both <amatch> and <afile> are set to the
1388 |window-ID|.
1389
Bram Moolenaar35fc61c2022-11-22 12:40:50 +00001390 |v:event| is set with information about size
1391 and scroll changes. |WinScrolled-event|
1392
Bram Moolenaar0a60f792022-11-19 21:18:11 +00001393 Only starts triggering after startup finished
1394 and the first screen redraw was done.
Bram Moolenaar35fc61c2022-11-22 12:40:50 +00001395 Does not trigger when defining the first
1396 WinScrolled or WinResized event, but may
1397 trigger when adding more.
Bram Moolenaar0a60f792022-11-19 21:18:11 +00001398
1399 Non-recursive: the event will not trigger
1400 while executing commands for the WinScrolled
1401 event. However, if the command causes a
1402 window to scroll or change size, then another
LemonBoy09371822022-04-08 15:18:45 +01001403 WinScrolled event will be triggered later.
Bram Moolenaar0a60f792022-11-19 21:18:11 +00001404
Bram Moolenaar35fc61c2022-11-22 12:40:50 +00001405
1406 *WinResized*
1407WinResized After a window in the current tab page changed
1408 width or height.
1409 See |win-scrolled-resized|.
1410
1411 |v:event| is set with information about size
1412 changes. |WinResized-event|
1413
1414 Same behavior as |WinScrolled| for the
1415 pattern, triggering and recursiveness.
LemonBoy09371822022-04-08 15:18:45 +01001416
Bram Moolenaar071d4272004-06-13 20:20:40 +00001417==============================================================================
Bram Moolenaarfd31be22022-01-16 14:46:06 +000014186. Patterns *autocmd-patterns* *{aupat}*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001419
LemonBoy09371822022-04-08 15:18:45 +01001420The {aupat} argument of `:autocmd` can be a comma-separated list. This works as
Bram Moolenaarfd31be22022-01-16 14:46:06 +00001421if the command was given with each pattern separately. Thus this command: >
Bram Moolenaar5a5f4592015-04-13 12:43:06 +02001422 :autocmd BufRead *.txt,*.info set et
1423Is equivalent to: >
1424 :autocmd BufRead *.txt set et
1425 :autocmd BufRead *.info set et
1426
Bram Moolenaarfd31be22022-01-16 14:46:06 +00001427The file pattern {aupat} is tested for a match against the file name in one of
Bram Moolenaar071d4272004-06-13 20:20:40 +00001428two ways:
14291. When there is no '/' in the pattern, Vim checks for a match against only
1430 the tail part of the file name (without its leading directory path).
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +010014312. When there is a '/' in the pattern, Vim checks for a match against both the
1432 short file name (as you typed it) and the full file name (after expanding
1433 it to a full path and resolving symbolic links).
Bram Moolenaar071d4272004-06-13 20:20:40 +00001434
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00001435The special pattern <buffer> or <buffer=N> is used for buffer-local
1436autocommands |autocmd-buflocal|. This pattern is not matched against the name
1437of a buffer.
1438
Bram Moolenaar071d4272004-06-13 20:20:40 +00001439Examples: >
1440 :autocmd BufRead *.txt set et
1441Set the 'et' option for all text files. >
1442
1443 :autocmd BufRead /vim/src/*.c set cindent
1444Set the 'cindent' option for C files in the /vim/src directory. >
1445
1446 :autocmd BufRead /tmp/*.c set ts=5
1447If you have a link from "/tmp/test.c" to "/home/nobody/vim/src/test.c", and
1448you start editing "/tmp/test.c", this autocommand will match.
1449
1450Note: To match part of a path, but not from the root directory, use a '*' as
1451the first character. Example: >
1452 :autocmd BufRead */doc/*.txt set tw=78
1453This autocommand will for example be executed for "/tmp/doc/xx.txt" and
1454"/usr/home/piet/doc/yy.txt". The number of directories does not matter here.
1455
1456
1457The file name that the pattern is matched against is after expanding
Bram Moolenaar446cb832008-06-24 21:56:24 +00001458wildcards. Thus if you issue this command: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001459 :e $ROOTDIR/main.$EXT
1460The argument is first expanded to: >
1461 /usr/root/main.py
1462Before it's matched with the pattern of the autocommand. Careful with this
1463when using events like FileReadCmd, the value of <amatch> may not be what you
1464expect.
1465
1466
1467Environment variables can be used in a pattern: >
1468 :autocmd BufRead $VIMRUNTIME/doc/*.txt set expandtab
1469And ~ can be used for the home directory (if $HOME is defined): >
1470 :autocmd BufWritePost ~/.vimrc so ~/.vimrc
1471 :autocmd BufRead ~archive/* set readonly
1472The environment variable is expanded when the autocommand is defined, not when
1473the autocommand is executed. This is different from the command!
1474
1475 *file-pattern*
1476The pattern is interpreted like mostly used in file names:
Bram Moolenaar3b1db362013-08-10 15:00:24 +02001477 * matches any sequence of characters; Unusual: includes path
Bram Moolenaar9d98fe92013-08-03 18:35:36 +02001478 separators
Bram Moolenaar071d4272004-06-13 20:20:40 +00001479 ? matches any single character
1480 \? matches a '?'
1481 . matches a '.'
1482 ~ matches a '~'
1483 , separates patterns
1484 \, matches a ','
1485 { } like \( \) in a |pattern|
1486 , inside { }: like \| in a |pattern|
Bram Moolenaara946afe2013-08-02 15:22:39 +02001487 \} literal }
1488 \{ literal {
1489 \\\{n,m\} like \{n,m} in a |pattern|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001490 \ special meaning like in a |pattern|
1491 [ch] matches 'c' or 'h'
1492 [^ch] match any character but 'c' and 'h'
1493
1494Note that for all systems the '/' character is used for path separator (even
Bram Moolenaar6f345a12019-12-17 21:27:18 +01001495for MS-Windows). This was done because the backslash is difficult to use in a
1496pattern and to make the autocommands portable across different systems.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001497
Bram Moolenaar64d8e252016-09-06 22:12:34 +02001498It is possible to use |pattern| items, but they may not work as expected,
1499because of the translation done for the above.
1500
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00001501 *autocmd-changes*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001502Matching with the pattern is done when an event is triggered. Changing the
1503buffer name in one of the autocommands, or even deleting the buffer, does not
1504change which autocommands will be executed. Example: >
1505
1506 au BufEnter *.foo bdel
1507 au BufEnter *.foo set modified
1508
1509This will delete the current buffer and then set 'modified' in what has become
1510the current buffer instead. Vim doesn't take into account that "*.foo"
1511doesn't match with that buffer name. It matches "*.foo" with the name of the
1512buffer at the moment the event was triggered.
1513
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00001514However, buffer-local autocommands will not be executed for a buffer that has
1515been wiped out with |:bwipe|. After deleting the buffer with |:bdel| the
1516buffer actually still exists (it becomes unlisted), thus the autocommands are
1517still executed.
1518
Bram Moolenaar071d4272004-06-13 20:20:40 +00001519==============================================================================
Bram Moolenaarc9b4b052006-04-30 18:54:39 +000015207. Buffer-local autocommands *autocmd-buflocal* *autocmd-buffer-local*
1521 *<buffer=N>* *<buffer=abuf>* *E680*
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00001522
1523Buffer-local autocommands are attached to a specific buffer. They are useful
1524if the buffer does not have a name and when the name does not match a specific
1525pattern. But it also means they must be explicitly added to each buffer.
1526
1527Instead of a pattern buffer-local autocommands use one of these forms:
1528 <buffer> current buffer
1529 <buffer=99> buffer number 99
1530 <buffer=abuf> using <abuf> (only when executing autocommands)
1531 |<abuf>|
1532
1533Examples: >
1534 :au CursorHold <buffer> echo 'hold'
1535 :au CursorHold <buffer=33> echo 'hold'
Bram Moolenaar88774fd2015-08-25 19:52:04 +02001536 :au BufNewFile * au CursorHold <buffer=abuf> echo 'hold'
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00001537
1538All the commands for autocommands also work with buffer-local autocommands,
1539simply use the special string instead of the pattern. Examples: >
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001540 :au! * <buffer> " remove buffer-local autocommands for
1541 " current buffer
1542 :au! * <buffer=33> " remove buffer-local autocommands for
1543 " buffer #33
Bram Moolenaar446cb832008-06-24 21:56:24 +00001544 :bufdo :au! CursorHold <buffer> " remove autocmd for given event for all
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001545 " buffers
1546 :au * <buffer> " list buffer-local autocommands for
1547 " current buffer
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00001548
1549Note that when an autocommand is defined for the current buffer, it is stored
1550with the buffer number. Thus it uses the form "<buffer=12>", where 12 is the
1551number of the current buffer. You will see this when listing autocommands,
1552for example.
1553
1554To test for presence of buffer-local autocommands use the |exists()| function
1555as follows: >
1556 :if exists("#CursorHold#<buffer=12>") | ... | endif
1557 :if exists("#CursorHold#<buffer>") | ... | endif " for current buffer
1558
1559When a buffer is wiped out its buffer-local autocommands are also gone, of
1560course. Note that when deleting a buffer, e.g., with ":bdel", it is only
1561unlisted, the autocommands are still present. In order to see the removal of
1562buffer-local autocommands: >
1563 :set verbose=6
1564
1565It is not possible to define buffer-local autocommands for a non-existent
1566buffer.
1567
1568==============================================================================
15698. Groups *autocmd-groups*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001570
1571Autocommands can be put together in a group. This is useful for removing or
1572executing a group of autocommands. For example, all the autocommands for
1573syntax highlighting are put in the "highlight" group, to be able to execute
1574":doautoall highlight BufRead" when the GUI starts.
1575
1576When no specific group is selected, Vim uses the default group. The default
1577group does not have a name. You cannot execute the autocommands from the
1578default group separately; you can execute them only by executing autocommands
1579for all groups.
1580
1581Normally, when executing autocommands automatically, Vim uses the autocommands
1582for all groups. The group only matters when executing autocommands with
1583":doautocmd" or ":doautoall", or when defining or deleting autocommands.
1584
1585The group name can contain any characters except white space. The group name
1586"end" is reserved (also in uppercase).
1587
1588The group name is case sensitive. Note that this is different from the event
1589name!
1590
1591 *:aug* *:augroup*
1592:aug[roup] {name} Define the autocmd group name for the
1593 following ":autocmd" commands. The name "end"
1594 or "END" selects the default group.
Bram Moolenaar256972a2015-12-29 19:10:25 +01001595 To avoid confusion, the name should be
1596 different from existing {event} names, as this
1597 most likely will not do what you intended.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001598
Bram Moolenaar64d8e252016-09-06 22:12:34 +02001599 *:augroup-delete* *E367* *W19* *E936*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001600:aug[roup]! {name} Delete the autocmd group {name}. Don't use
1601 this if there is still an autocommand using
Bram Moolenaarbc8801c2016-08-02 21:04:33 +02001602 this group! You will get a warning if doing
Bram Moolenaare7b1ea02020-08-07 19:54:59 +02001603 it anyway. When the group is the current
1604 group you will get error E936.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001605
1606To enter autocommands for a specific group, use this method:
16071. Select the group with ":augroup {name}".
16082. Delete any old autocommands with ":au!".
16093. Define the autocommands.
16104. Go back to the default group with "augroup END".
1611
1612Example: >
1613 :augroup uncompress
1614 : au!
1615 : au BufEnter *.gz %!gunzip
1616 :augroup END
1617
1618This prevents having the autocommands defined twice (e.g., after sourcing the
1619.vimrc file again).
1620
Bram Moolenaar6e649222021-10-04 21:32:54 +01001621 *FileExplorer*
1622There is one group that is recognized by Vim: FileExplorer. If this group
1623exists Vim assumes that editing a directory is possible and will trigger a
1624plugin that lists the files in that directory. This is used by the |netrw|
1625plugin. This allows you to do: >
1626 browse edit
1627
Bram Moolenaar071d4272004-06-13 20:20:40 +00001628==============================================================================
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +000016299. Executing autocommands *autocmd-execute*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001630
1631Vim can also execute Autocommands non-automatically. This is useful if you
1632have changed autocommands, or when Vim has executed the wrong autocommands
1633(e.g., the file pattern match was wrong).
1634
1635Note that the 'eventignore' option applies here too. Events listed in this
1636option will not cause any commands to be executed.
1637
Bram Moolenaar61da1bf2019-06-06 12:14:49 +02001638 *:do* *:doau* *:doaut* *:doautocmd* *E217*
Bram Moolenaar5dc62522012-02-13 00:05:22 +01001639:do[autocmd] [<nomodeline>] [group] {event} [fname]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001640 Apply the autocommands matching [fname] (default:
1641 current file name) for {event} to the current buffer.
1642 You can use this when the current file name does not
1643 match the right pattern, after changing settings, or
1644 to execute autocommands for a certain event.
1645 It's possible to use this inside an autocommand too,
1646 so you can base the autocommands for one extension on
1647 another extension. Example: >
Bram Moolenaarf1568ec2011-12-14 21:17:39 +01001648 :au BufEnter *.cpp so ~/.vimrc_cpp
1649 :au BufEnter *.cpp doau BufEnter x.c
Bram Moolenaar071d4272004-06-13 20:20:40 +00001650< Be careful to avoid endless loops. See
1651 |autocmd-nested|.
1652
1653 When the [group] argument is not given, Vim executes
1654 the autocommands for all groups. When the [group]
1655 argument is included, Vim executes only the matching
1656 autocommands for that group. Note: if you use an
1657 undefined group name, Vim gives you an error message.
Bram Moolenaar60542ac2012-02-12 20:14:01 +01001658 *<nomodeline>*
1659 After applying the autocommands the modelines are
1660 processed, so that their settings overrule the
1661 settings from autocommands, like what happens when
1662 editing a file. This is skipped when the <nomodeline>
1663 argument is present. You probably want to use
1664 <nomodeline> for events that are not used when loading
1665 a buffer, such as |User|.
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001666 Processing modelines is also skipped when no
1667 matching autocommands were executed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001668
1669 *:doautoa* *:doautoall*
Bram Moolenaara61d5fb2012-02-12 00:18:58 +01001670:doautoa[ll] [<nomodeline>] [group] {event} [fname]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001671 Like ":doautocmd", but apply the autocommands to each
Bram Moolenaardad44732021-03-31 20:07:33 +02001672 loaded buffer. The current buffer is done last.
1673
1674 Note that [fname] is used to select the autocommands,
Bram Moolenaar4c295022021-05-02 17:19:11 +02001675 not the buffers to which they are applied. Example: >
1676 augroup mine
1677 autocmd!
1678 autocmd FileType * echo expand('<amatch>')
1679 augroup END
1680 doautoall mine FileType Loaded-Buffer
1681< Sourcing this script, you'll see as many
1682 "Loaded-Buffer" echoed as there are loaded buffers.
Bram Moolenaardad44732021-03-31 20:07:33 +02001683
Bram Moolenaar071d4272004-06-13 20:20:40 +00001684 Careful: Don't use this for autocommands that delete a
1685 buffer, change to another buffer or change the
1686 contents of a buffer; the result is unpredictable.
1687 This command is intended for autocommands that set
1688 options, change highlighting, and things like that.
1689
1690==============================================================================
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +0000169110. Using autocommands *autocmd-use*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001692
1693For WRITING FILES there are four possible sets of events. Vim uses only one
1694of these sets for a write command:
1695
1696BufWriteCmd BufWritePre BufWritePost writing the whole buffer
1697 FilterWritePre FilterWritePost writing to filter temp file
1698FileAppendCmd FileAppendPre FileAppendPost appending to a file
1699FileWriteCmd FileWritePre FileWritePost any other file write
1700
1701When there is a matching "*Cmd" autocommand, it is assumed it will do the
1702writing. No further writing is done and the other events are not triggered.
1703|Cmd-event|
1704
1705Note that the *WritePost commands should undo any changes to the buffer that
1706were caused by the *WritePre commands; otherwise, writing the file will have
1707the side effect of changing the buffer.
1708
1709Before executing the autocommands, the buffer from which the lines are to be
1710written temporarily becomes the current buffer. Unless the autocommands
1711change the current buffer or delete the previously current buffer, the
1712previously current buffer is made the current buffer again.
1713
1714The *WritePre and *AppendPre autocommands must not delete the buffer from
1715which the lines are to be written.
1716
1717The '[ and '] marks have a special position:
1718- Before the *ReadPre event the '[ mark is set to the line just above where
1719 the new lines will be inserted.
1720- Before the *ReadPost event the '[ mark is set to the first line that was
1721 just read, the '] mark to the last line.
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +00001722- Before executing the *WriteCmd, *WritePre and *AppendPre autocommands the '[
1723 mark is set to the first line that will be written, the '] mark to the last
1724 line.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001725Careful: '[ and '] change when using commands that change the buffer.
1726
1727In commands which expect a file name, you can use "<afile>" for the file name
1728that is being read |:<afile>| (you can also use "%" for the current file
1729name). "<abuf>" can be used for the buffer number of the currently effective
Bram Moolenaard2f3a8b2018-06-19 14:35:59 +02001730buffer. This also works for buffers that don't have a name. But it doesn't
Bram Moolenaar071d4272004-06-13 20:20:40 +00001731work for files without a buffer (e.g., with ":r file").
1732
1733 *gzip-example*
1734Examples for reading and writing compressed files: >
1735 :augroup gzip
1736 : autocmd!
1737 : autocmd BufReadPre,FileReadPre *.gz set bin
1738 : autocmd BufReadPost,FileReadPost *.gz '[,']!gunzip
1739 : autocmd BufReadPost,FileReadPost *.gz set nobin
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001740 : autocmd BufReadPost,FileReadPost *.gz execute ":doautocmd BufReadPost " .. expand("%:r")
Bram Moolenaar071d4272004-06-13 20:20:40 +00001741 : autocmd BufWritePost,FileWritePost *.gz !mv <afile> <afile>:r
1742 : autocmd BufWritePost,FileWritePost *.gz !gzip <afile>:r
1743
1744 : autocmd FileAppendPre *.gz !gunzip <afile>
1745 : autocmd FileAppendPre *.gz !mv <afile>:r <afile>
1746 : autocmd FileAppendPost *.gz !mv <afile> <afile>:r
1747 : autocmd FileAppendPost *.gz !gzip <afile>:r
1748 :augroup END
1749
1750The "gzip" group is used to be able to delete any existing autocommands with
1751":autocmd!", for when the file is sourced twice.
1752
1753("<afile>:r" is the file name without the extension, see |:_%:|)
1754
1755The commands executed for the BufNewFile, BufRead/BufReadPost, BufWritePost,
1756FileAppendPost and VimLeave events do not set or reset the changed flag of the
1757buffer. When you decompress the buffer with the BufReadPost autocommands, you
1758can still exit with ":q". When you use ":undo" in BufWritePost to undo the
1759changes made by BufWritePre commands, you can still do ":q" (this also makes
1760"ZZ" work). If you do want the buffer to be marked as modified, set the
1761'modified' option.
1762
1763To execute Normal mode commands from an autocommand, use the ":normal"
1764command. Use with care! If the Normal mode command is not finished, the user
1765needs to type characters (e.g., after ":normal m" you need to type a mark
1766name).
1767
1768If you want the buffer to be unmodified after changing it, reset the
1769'modified' option. This makes it possible to exit the buffer with ":q"
1770instead of ":q!".
1771
1772 *autocmd-nested* *E218*
Bram Moolenaar26967612019-03-17 17:13:16 +01001773By default, autocommands do not nest. For example, if you use ":e" or ":w" in
1774an autocommand, Vim does not execute the BufRead and BufWrite autocommands for
Bram Moolenaar071d4272004-06-13 20:20:40 +00001775those commands. If you do want this, use the "nested" flag for those commands
1776in which you want nesting. For example: >
Bram Moolenaareb93f3f2019-04-04 15:04:56 +02001777 :autocmd FileChangedShell *.c ++nested e!
Bram Moolenaar071d4272004-06-13 20:20:40 +00001778The nesting is limited to 10 levels to get out of recursive loops.
1779
1780It's possible to use the ":au" command in an autocommand. This can be a
1781self-modifying command! This can be useful for an autocommand that should
1782execute only once.
1783
Bram Moolenaarb3480382005-12-11 21:33:32 +00001784If you want to skip autocommands for one command, use the |:noautocmd| command
1785modifier or the 'eventignore' option.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001786
1787Note: When reading a file (with ":read file" or with a filter command) and the
1788last line in the file does not have an <EOL>, Vim remembers this. At the next
1789write (with ":write file" or with a filter command), if the same line is
1790written again as the last line in a file AND 'binary' is set, Vim does not
1791supply an <EOL>. This makes a filter command on the just read lines write the
1792same file as was read, and makes a write command on just filtered lines write
1793the same file as was read from the filter. For example, another way to write
1794a compressed file: >
1795
1796 :autocmd FileWritePre *.gz set bin|'[,']!gzip
1797 :autocmd FileWritePost *.gz undo|set nobin
1798<
1799 *autocommand-pattern*
1800You can specify multiple patterns, separated by commas. Here are some
1801examples: >
1802
1803 :autocmd BufRead * set tw=79 nocin ic infercase fo=2croq
1804 :autocmd BufRead .letter set tw=72 fo=2tcrq
1805 :autocmd BufEnter .letter set dict=/usr/lib/dict/words
1806 :autocmd BufLeave .letter set dict=
1807 :autocmd BufRead,BufNewFile *.c,*.h set tw=0 cin noic
1808 :autocmd BufEnter *.c,*.h abbr FOR for (i = 0; i < 3; ++i)<CR>{<CR>}<Esc>O
1809 :autocmd BufLeave *.c,*.h unabbr FOR
1810
1811For makefiles (makefile, Makefile, imakefile, makefile.unix, etc.): >
1812
1813 :autocmd BufEnter ?akefile* set include=^s\=include
1814 :autocmd BufLeave ?akefile* set include&
1815
1816To always start editing C files at the first function: >
1817
1818 :autocmd BufRead *.c,*.h 1;/^{
1819
1820Without the "1;" above, the search would start from wherever the file was
1821entered, rather than from the start of the file.
1822
1823 *skeleton* *template*
1824To read a skeleton (template) file when opening a new file: >
1825
1826 :autocmd BufNewFile *.c 0r ~/vim/skeleton.c
1827 :autocmd BufNewFile *.h 0r ~/vim/skeleton.h
1828 :autocmd BufNewFile *.java 0r ~/vim/skeleton.java
1829
1830To insert the current date and time in a *.html file when writing it: >
1831
1832 :autocmd BufWritePre,FileWritePre *.html ks|call LastMod()|'s
1833 :fun LastMod()
1834 : if line("$") > 20
1835 : let l = 20
1836 : else
1837 : let l = line("$")
1838 : endif
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001839 : exe "1," .. l .. "g/Last modified: /s/Last modified: .*/Last modified: " ..
Bram Moolenaar071d4272004-06-13 20:20:40 +00001840 : \ strftime("%Y %b %d")
1841 :endfun
1842
1843You need to have a line "Last modified: <date time>" in the first 20 lines
1844of the file for this to work. Vim replaces <date time> (and anything in the
1845same line after it) with the current date and time. Explanation:
1846 ks mark current position with mark 's'
1847 call LastMod() call the LastMod() function to do the work
1848 's return the cursor to the old position
1849The LastMod() function checks if the file is shorter than 20 lines, and then
1850uses the ":g" command to find lines that contain "Last modified: ". For those
1851lines the ":s" command is executed to replace the existing date with the
1852current one. The ":execute" command is used to be able to use an expression
1853for the ":g" and ":s" commands. The date is obtained with the strftime()
1854function. You can change its argument to get another date string.
1855
1856When entering :autocmd on the command-line, completion of events and command
1857names may be done (with <Tab>, CTRL-D, etc.) where appropriate.
1858
1859Vim executes all matching autocommands in the order that you specify them.
1860It is recommended that your first autocommand be used for all files by using
1861"*" as the file pattern. This means that you can define defaults you like
1862here for any settings, and if there is another matching autocommand it will
1863override these. But if there is no other matching autocommand, then at least
1864your default settings are recovered (if entering this file from another for
1865which autocommands did match). Note that "*" will also match files starting
1866with ".", unlike Unix shells.
1867
1868 *autocmd-searchpat*
1869Autocommands do not change the current search patterns. Vim saves the current
1870search patterns before executing autocommands then restores them after the
1871autocommands finish. This means that autocommands do not affect the strings
1872highlighted with the 'hlsearch' option. Within autocommands, you can still
1873use search patterns normally, e.g., with the "n" command.
1874If you want an autocommand to set the search pattern, such that it is used
1875after the autocommand finishes, use the ":let @/ =" command.
1876The search-highlighting cannot be switched off with ":nohlsearch" in an
1877autocommand. Use the 'h' flag in the 'viminfo' option to disable search-
1878highlighting when starting Vim.
1879
1880 *Cmd-event*
1881When using one of the "*Cmd" events, the matching autocommands are expected to
Bram Moolenaar8dd1aa52007-01-16 20:33:19 +00001882do the file reading, writing or sourcing. This can be used when working with
1883a special kind of file, for example on a remote system.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001884CAREFUL: If you use these events in a wrong way, it may have the effect of
1885making it impossible to read or write the matching files! Make sure you test
1886your autocommands properly. Best is to use a pattern that will never match a
1887normal file name, for example "ftp://*".
1888
1889When defining a BufReadCmd it will be difficult for Vim to recover a crashed
1890editing session. When recovering from the original file, Vim reads only those
1891parts of a file that are not found in the swap file. Since that is not
1892possible with a BufReadCmd, use the |:preserve| command to make sure the
1893original file isn't needed for recovery. You might want to do this only when
1894you expect the file to be modified.
1895
Bram Moolenaar8dd1aa52007-01-16 20:33:19 +00001896For file read and write commands the |v:cmdarg| variable holds the "++enc="
1897and "++ff=" argument that are effective. These should be used for the command
1898that reads/writes the file. The |v:cmdbang| variable is one when "!" was
1899used, zero otherwise.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001900
Bram Moolenaarc88ebf72010-07-22 22:30:23 +02001901See the $VIMRUNTIME/plugin/netrwPlugin.vim for examples.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001902
Bram Moolenaarb3480382005-12-11 21:33:32 +00001903==============================================================================
190411. Disabling autocommands *autocmd-disable*
1905
1906To disable autocommands for some time use the 'eventignore' option. Note that
1907this may cause unexpected behavior, make sure you restore 'eventignore'
1908afterwards, using a |:try| block with |:finally|.
1909
1910 *:noautocmd* *:noa*
1911To disable autocommands for just one command use the ":noautocmd" command
1912modifier. This will set 'eventignore' to "all" for the duration of the
1913following command. Example: >
1914
1915 :noautocmd w fname.gz
1916
1917This will write the file without triggering the autocommands defined by the
1918gzip plugin.
1919
Bram Moolenaar26967612019-03-17 17:13:16 +01001920Note that some autocommands are not triggered right away, but only later.
1921This specifically applies to |CursorMoved| and |TextChanged|.
1922
Bram Moolenaarb5bf5b82004-12-24 14:35:23 +00001923
Bram Moolenaar91f84f62018-07-29 15:07:52 +02001924 vim:tw=78:ts=8:noet:ft=help:norl: