|
1154
|
1 *autocmd.txt* For Vim version 7.1a. Last change: 2007 Mar 27
|
|
7
|
2
|
|
|
3
|
|
|
4 VIM REFERENCE MANUAL by Bram Moolenaar
|
|
|
5
|
|
|
6
|
|
|
7 Automatic commands *autocommand*
|
|
|
8
|
|
|
9 For a basic explanation, see section |40.3| in the user manual.
|
|
|
10
|
|
|
11 1. Introduction |autocmd-intro|
|
|
|
12 2. Defining autocommands |autocmd-define|
|
|
|
13 3. Removing autocommands |autocmd-remove|
|
|
|
14 4. Listing autocommands |autocmd-list|
|
|
|
15 5. Events |autocmd-events|
|
|
|
16 6. Patterns |autocmd-patterns|
|
|
40
|
17 7. Buffer-local autocommands |autocmd-buflocal|
|
|
|
18 8. Groups |autocmd-groups|
|
|
|
19 9. Executing autocommands |autocmd-execute|
|
|
|
20 10. Using autocommands |autocmd-use|
|
|
590
|
21 11. Disabling autocommands |autocmd-disable|
|
|
7
|
22
|
|
|
23 {Vi does not have any of these commands}
|
|
|
24 {only when the |+autocmd| feature has not been disabled at compile time}
|
|
|
25
|
|
|
26 ==============================================================================
|
|
|
27 1. Introduction *autocmd-intro*
|
|
|
28
|
|
22
|
29 You can specify commands to be executed automatically when reading or writing
|
|
|
30 a file, when entering or leaving a buffer or window, and when exiting Vim.
|
|
|
31 For example, you can create an autocommand to set the 'cindent' option for
|
|
|
32 files matching *.c. You can also use autocommands to implement advanced
|
|
7
|
33 features, such as editing compressed files (see |gzip-example|). The usual
|
|
|
34 place to put autocommands is in your .vimrc or .exrc file.
|
|
|
35
|
|
|
36 *E203* *E204* *E143*
|
|
|
37 WARNING: Using autocommands is very powerful, and may lead to unexpected side
|
|
|
38 effects. Be careful not to destroy your text.
|
|
|
39 - It's a good idea to do some testing on an expendable copy of a file first.
|
|
|
40 For example: If you use autocommands to decompress a file when starting to
|
|
|
41 edit it, make sure that the autocommands for compressing when writing work
|
|
|
42 correctly.
|
|
|
43 - Be prepared for an error halfway through (e.g., disk full). Vim will mostly
|
|
|
44 be able to undo the changes to the buffer, but you may have to clean up the
|
|
|
45 changes to other files by hand (e.g., compress a file that has been
|
|
|
46 decompressed).
|
|
|
47 - If the BufRead* events allow you to edit a compressed file, the FileRead*
|
|
|
48 events should do the same (this makes recovery possible in some rare cases).
|
|
|
49 It's a good idea to use the same autocommands for the File* and Buf* events
|
|
|
50 when possible.
|
|
|
51
|
|
|
52 ==============================================================================
|
|
|
53 2. Defining autocommands *autocmd-define*
|
|
|
54
|
|
|
55 Note: The ":autocmd" command cannot be followed by another command, since any
|
|
|
56 '|' is considered part of the command.
|
|
|
57
|
|
|
58 *:au* *:autocmd*
|
|
|
59 :au[tocmd] [group] {event} {pat} [nested] {cmd}
|
|
|
60 Add {cmd} to the list of commands that Vim will
|
|
|
61 execute automatically on {event} for a file matching
|
|
|
62 {pat}. Vim always adds the {cmd} after existing
|
|
|
63 autocommands, so that the autocommands execute in the
|
|
|
64 order in which they were given. See |autocmd-nested|
|
|
|
65 for [nested].
|
|
|
66
|
|
40
|
67 The special pattern <buffer> or <buffer=N> defines a buffer-local autocommand.
|
|
|
68 See |autocmd-buflocal|.
|
|
|
69
|
|
7
|
70 Note that special characters (e.g., "%", "<cword>") in the ":autocmd"
|
|
|
71 arguments are not expanded when the autocommand is defined. These will be
|
|
|
72 expanded when the Event is recognized, and the {cmd} is executed. The only
|
|
|
73 exception is that "<sfile>" is expanded when the autocmd is defined. Example:
|
|
|
74 >
|
|
|
75 :au BufNewFile,BufRead *.html so <sfile>:h/html.vim
|
|
|
76
|
|
|
77 Here Vim expands <sfile> to the name of the file containing this line.
|
|
|
78
|
|
|
79 When your .vimrc file is sourced twice, the autocommands will appear twice.
|
|
|
80 To avoid this, put this command in your .vimrc file, before defining
|
|
|
81 autocommands: >
|
|
|
82
|
|
|
83 :autocmd! " Remove ALL autocommands for the current group.
|
|
|
84
|
|
|
85 If you don't want to remove all autocommands, you can instead use a variable
|
|
|
86 to ensure that Vim includes the autocommands only once: >
|
|
|
87
|
|
|
88 :if !exists("autocommands_loaded")
|
|
|
89 : let autocommands_loaded = 1
|
|
|
90 : au ...
|
|
|
91 :endif
|
|
|
92
|
|
|
93 When the [group] argument is not given, Vim uses the current group (as defined
|
|
|
94 with ":augroup"); otherwise, Vim uses the group defined with [group]. Note
|
|
|
95 that [group] must have been defined before. You cannot define a new group
|
|
|
96 with ":au group ..."; use ":augroup" for that.
|
|
|
97
|
|
|
98 While testing autocommands, you might find the 'verbose' option to be useful: >
|
|
|
99 :set verbose=9
|
|
|
100 This setting makes Vim echo the autocommands as it executes them.
|
|
|
101
|
|
|
102 When defining an autocommand in a script, it will be able to call functions
|
|
|
103 local to the script and use mappings local to the script. When the event is
|
|
|
104 triggered and the command executed, it will run in the context of the script
|
|
|
105 it was defined in. This matters if |<SID>| is used in a command.
|
|
|
106
|
|
|
107 When executing the commands, the messages from one command overwrites a
|
|
|
108 previous message. This is different from when executing the commands
|
|
|
109 manually. Mostly the screen will not scroll up, thus there is no hit-enter
|
|
|
110 prompt. When one command outputs two messages this can happen anyway.
|
|
|
111
|
|
|
112 ==============================================================================
|
|
|
113 3. Removing autocommands *autocmd-remove*
|
|
|
114
|
|
|
115 :au[tocmd]! [group] {event} {pat} [nested] {cmd}
|
|
|
116 Remove all autocommands associated with {event} and
|
|
|
117 {pat}, and add the command {cmd}. See
|
|
|
118 |autocmd-nested| for [nested].
|
|
|
119
|
|
|
120 :au[tocmd]! [group] {event} {pat}
|
|
|
121 Remove all autocommands associated with {event} and
|
|
|
122 {pat}.
|
|
|
123
|
|
|
124 :au[tocmd]! [group] * {pat}
|
|
|
125 Remove all autocommands associated with {pat} for all
|
|
|
126 events.
|
|
|
127
|
|
|
128 :au[tocmd]! [group] {event}
|
|
|
129 Remove ALL autocommands for {event}.
|
|
|
130
|
|
|
131 :au[tocmd]! [group] Remove ALL autocommands.
|
|
|
132
|
|
|
133 When the [group] argument is not given, Vim uses the current group (as defined
|
|
|
134 with ":augroup"); otherwise, Vim uses the group defined with [group].
|
|
|
135
|
|
|
136 ==============================================================================
|
|
|
137 4. Listing autocommands *autocmd-list*
|
|
|
138
|
|
|
139 :au[tocmd] [group] {event} {pat}
|
|
|
140 Show the autocommands associated with {event} and
|
|
|
141 {pat}.
|
|
|
142
|
|
|
143 :au[tocmd] [group] * {pat}
|
|
|
144 Show the autocommands associated with {pat} for all
|
|
|
145 events.
|
|
|
146
|
|
|
147 :au[tocmd] [group] {event}
|
|
|
148 Show all autocommands for {event}.
|
|
|
149
|
|
|
150 :au[tocmd] [group] Show all autocommands.
|
|
|
151
|
|
|
152 If you provide the [group] argument, Vim lists only the autocommands for
|
|
|
153 [group]; otherwise, Vim lists the autocommands for ALL groups. Note that this
|
|
|
154 argument behavior differs from that for defining and removing autocommands.
|
|
|
155
|
|
40
|
156 In order to list buffer-local autocommands, use a pattern in the form <buffer>
|
|
|
157 or <buffer=N>. See |autocmd-buflocal|.
|
|
|
158
|
|
500
|
159 *:autocmd-verbose*
|
|
|
160 When 'verbose' is non-zero, listing an autocommand will also display where it
|
|
|
161 was last defined. Example: >
|
|
|
162
|
|
|
163 :verbose autocmd BufEnter
|
|
|
164 FileExplorer BufEnter
|
|
856
|
165 * call s:LocalBrowse(expand("<amatch>"))
|
|
500
|
166 Last set from /usr/share/vim/vim-7.0/plugin/NetrwPlugin.vim
|
|
|
167 <
|
|
|
168 See |:verbose-cmd| for more information.
|
|
|
169
|
|
7
|
170 ==============================================================================
|
|
|
171 5. Events *autocmd-events* *E215* *E216*
|
|
|
172
|
|
579
|
173 You can specify a comma-separated list of event names. No white space can be
|
|
|
174 used in this list. The command applies to all the events in the list.
|
|
|
175
|
|
|
176 For READING FILES there are four kinds of events possible:
|
|
|
177 BufNewFile starting to edit a non-existent file
|
|
|
178 BufReadPre BufReadPost starting to edit an existing file
|
|
|
179 FilterReadPre FilterReadPost read the temp file with filter output
|
|
|
180 FileReadPre FileReadPost any other file read
|
|
|
181 Vim uses only one of these four kinds when reading a file. The "Pre" and
|
|
|
182 "Post" events are both triggered, before and after reading the file.
|
|
|
183
|
|
|
184 Note that the autocommands for the *ReadPre events and all the Filter events
|
|
|
185 are not allowed to change the current buffer (you will get an error message if
|
|
|
186 this happens). This is to prevent the file to be read into the wrong buffer.
|
|
|
187
|
|
|
188 Note that the 'modified' flag is reset AFTER executing the BufReadPost
|
|
|
189 and BufNewFile autocommands. But when the 'modified' option was set by the
|
|
|
190 autocommands, this doesn't happen.
|
|
|
191
|
|
|
192 You can use the 'eventignore' option to ignore a number of events or all
|
|
|
193 events.
|
|
7
|
194 *autocommand-events* *{event}*
|
|
|
195 Vim recognizes the following events. Vim ignores the case of event names
|
|
|
196 (e.g., you can use "BUFread" or "bufread" instead of "BufRead").
|
|
|
197
|
|
579
|
198 First an overview by function with a short explanation. Then the list
|
|
843
|
199 alphabetically with full explanations |autocmd-events-abc|.
|
|
579
|
200
|
|
|
201 Name triggered by ~
|
|
|
202
|
|
|
203 Reading
|
|
|
204 |BufNewFile| starting to edit a file that doesn't exist
|
|
|
205 |BufReadPre| starting to edit a new buffer, before reading the file
|
|
|
206 |BufRead| starting to edit a new buffer, after reading the file
|
|
|
207 |BufReadPost| starting to edit a new buffer, after reading the file
|
|
|
208 |BufReadCmd| before starting to edit a new buffer |Cmd-event|
|
|
|
209
|
|
|
210 |FileReadPre| before reading a file with a ":read" command
|
|
|
211 |FileReadPost| after reading a file with a ":read" command
|
|
843
|
212 |FileReadCmd| before reading a file with a ":read" command |Cmd-event|
|
|
579
|
213
|
|
|
214 |FilterReadPre| before reading a file from a filter command
|
|
|
215 |FilterReadPost| after reading a file from a filter command
|
|
|
216
|
|
|
217 |StdinReadPre| before reading from stdin into the buffer
|
|
|
218 |StdinReadPost| After reading from the stdin into the buffer
|
|
|
219
|
|
|
220 Writing
|
|
|
221 |BufWrite| starting to write the whole buffer to a file
|
|
|
222 |BufWritePre| starting to write the whole buffer to a file
|
|
|
223 |BufWritePost| after writing the whole buffer to a file
|
|
|
224 |BufWriteCmd| before writing the whole buffer to a file |Cmd-event|
|
|
|
225
|
|
|
226 |FileWritePre| starting to write part of a buffer to a file
|
|
|
227 |FileWritePost| after writing part of a buffer to a file
|
|
|
228 |FileWriteCmd| before writing part of a buffer to a file |Cmd-event|
|
|
|
229
|
|
|
230 |FileAppendPre| starting to append to a file
|
|
|
231 |FileAppendPost| after appending to a file
|
|
|
232 |FileAppendCmd| before appending to a file |Cmd-event|
|
|
|
233
|
|
|
234 |FilterWritePre| starting to write a file for a filter command or diff
|
|
|
235 |FilterWritePost| after writing a file for a filter command or diff
|
|
|
236
|
|
|
237 Buffers
|
|
|
238 |BufAdd| just after adding a buffer to the buffer list
|
|
|
239 |BufCreate| just after adding a buffer to the buffer list
|
|
|
240 |BufDelete| before deleting a buffer from the buffer list
|
|
|
241 |BufWipeout| before completely deleting a buffer
|
|
|
242
|
|
|
243 |BufFilePre| before changing the name of the current buffer
|
|
|
244 |BufFilePost| after changing the name of the current buffer
|
|
|
245
|
|
|
246 |BufEnter| after entering a buffer
|
|
|
247 |BufLeave| before leaving to another buffer
|
|
|
248 |BufWinEnter| after a buffer is displayed in a window
|
|
|
249 |BufWinLeave| before a buffer is removed from a window
|
|
|
250
|
|
|
251 |BufUnload| before unloading a buffer
|
|
|
252 |BufHidden| just after a buffer has become hidden
|
|
|
253 |BufNew| just after creating a new buffer
|
|
|
254
|
|
|
255 |SwapExists| detected an existing swap file
|
|
|
256
|
|
|
257 Options
|
|
|
258 |FileType| when the 'filetype' option has been set
|
|
|
259 |Syntax| when the 'syntax' option has been set
|
|
|
260 |EncodingChanged| after the 'encoding' option has been changed
|
|
|
261 |TermChanged| after the value of 'term' has changed
|
|
|
262
|
|
|
263 Startup and exit
|
|
|
264 |VimEnter| after doing all the startup stuff
|
|
|
265 |GUIEnter| after starting the GUI successfully
|
|
1154
|
266 |TermResponse| after the terminal response to |t_RV| is received
|
|
579
|
267
|
|
|
268 |VimLeavePre| before exiting Vim, before writing the viminfo file
|
|
|
269 |VimLeave| before exiting Vim, after writing the viminfo file
|
|
|
270
|
|
|
271 Various
|
|
|
272 |FileChangedShell| Vim notices that a file changed since editing started
|
|
766
|
273 |FileChangedShellPost| After handling a file changed since editing started
|
|
579
|
274 |FileChangedRO| before making the first change to a read-only file
|
|
|
275
|
|
724
|
276 |ShellCmdPost| after executing a shell command
|
|
|
277 |ShellFilterPost| after filtering with a shell command
|
|
|
278
|
|
579
|
279 |FuncUndefined| a user function is used but it isn't defined
|
|
650
|
280 |SpellFileMissing| a spell file is used but it can't be found
|
|
716
|
281 |SourcePre| before sourcing a Vim script
|
|
1061
|
282 |SourceCmd| before sourcing a Vim script |Cmd-event|
|
|
579
|
283
|
|
766
|
284 |VimResized| after the Vim window size changed
|
|
579
|
285 |FocusGained| Vim got input focus
|
|
|
286 |FocusLost| Vim lost input focus
|
|
|
287 |CursorHold| the user doesn't press a key for a while
|
|
661
|
288 |CursorHoldI| the user doesn't press a key for a while in Insert mode
|
|
|
289 |CursorMoved| the cursor was moved in Normal mode
|
|
|
290 |CursorMovedI| the cursor was moved in Insert mode
|
|
579
|
291
|
|
|
292 |WinEnter| after entering another window
|
|
|
293 |WinLeave| before leaving a window
|
|
677
|
294 |TabEnter| after entering another tab page
|
|
|
295 |TabLeave| before leaving a tab page
|
|
579
|
296 |CmdwinEnter| after entering the command-line window
|
|
|
297 |CmdwinLeave| before leaving the command-line window
|
|
|
298
|
|
|
299 |InsertEnter| starting Insert mode
|
|
|
300 |InsertChange| when typing <Insert> while in Insert or Replace mode
|
|
|
301 |InsertLeave| when leaving Insert mode
|
|
|
302
|
|
|
303 |ColorScheme| after loading a color scheme
|
|
|
304
|
|
|
305 |RemoteReply| a reply from a server Vim was received
|
|
|
306
|
|
|
307 |QuickFixCmdPre| before a quickfix command is run
|
|
|
308 |QuickFixCmdPost| after a quickfix command is run
|
|
|
309
|
|
|
310 |SessionLoadPost| after loading a session file
|
|
|
311
|
|
|
312 |MenuPopup| just before showing the popup menu
|
|
|
313
|
|
|
314 |User| to be used in combination with ":doautocmd"
|
|
|
315
|
|
|
316
|
|
|
317 The alphabetical list of autocommand events: *autocmd-events-abc*
|
|
|
318
|
|
|
319 *BufCreate* *BufAdd*
|
|
|
320 BufAdd or BufCreate Just after creating a new buffer which is
|
|
|
321 added to the buffer list, or adding a buffer
|
|
|
322 to the buffer list.
|
|
|
323 Also used just after a buffer in the buffer
|
|
|
324 list has been renamed.
|
|
|
325 The BufCreate event is for historic reasons.
|
|
|
326 NOTE: When this autocommand is executed, the
|
|
|
327 current buffer "%" may be different from the
|
|
|
328 buffer being created "<afile>".
|
|
|
329 *BufDelete*
|
|
|
330 BufDelete Before deleting a buffer from the buffer list.
|
|
|
331 The BufUnload may be called first (if the
|
|
|
332 buffer was loaded).
|
|
|
333 Also used just before a buffer in the buffer
|
|
|
334 list is renamed.
|
|
|
335 NOTE: When this autocommand is executed, the
|
|
|
336 current buffer "%" may be different from the
|
|
|
337 buffer being deleted "<afile>".
|
|
|
338 *BufEnter*
|
|
|
339 BufEnter After entering a buffer. Useful for setting
|
|
|
340 options for a file type. Also executed when
|
|
|
341 starting to edit a buffer, after the
|
|
|
342 BufReadPost autocommands.
|
|
|
343 *BufFilePost*
|
|
|
344 BufFilePost After changing the name of the current buffer
|
|
|
345 with the ":file" or ":saveas" command.
|
|
625
|
346 *BufFilePre*
|
|
579
|
347 BufFilePre Before changing the name of the current buffer
|
|
|
348 with the ":file" or ":saveas" command.
|
|
|
349 *BufHidden*
|
|
|
350 BufHidden Just after a buffer has become hidden. That
|
|
|
351 is, when there are no longer windows that show
|
|
|
352 the buffer, but the buffer is not unloaded or
|
|
|
353 deleted. Not used for ":qa" or ":q" when
|
|
|
354 exiting Vim.
|
|
|
355 NOTE: When this autocommand is executed, the
|
|
|
356 current buffer "%" may be different from the
|
|
|
357 buffer being unloaded "<afile>".
|
|
|
358 *BufLeave*
|
|
|
359 BufLeave Before leaving to another buffer. Also when
|
|
|
360 leaving or closing the current window and the
|
|
|
361 new current window is not for the same buffer.
|
|
|
362 Not used for ":qa" or ":q" when exiting Vim.
|
|
|
363 *BufNew*
|
|
|
364 BufNew Just after creating a new buffer. Also used
|
|
|
365 just after a buffer has been renamed. When
|
|
|
366 the buffer is added to the buffer list BufAdd
|
|
|
367 will be triggered too.
|
|
|
368 NOTE: When this autocommand is executed, the
|
|
|
369 current buffer "%" may be different from the
|
|
|
370 buffer being created "<afile>".
|
|
7
|
371 *BufNewFile*
|
|
|
372 BufNewFile When starting to edit a file that doesn't
|
|
|
373 exist. Can be used to read in a skeleton
|
|
|
374 file.
|
|
|
375 *BufRead* *BufReadPost*
|
|
|
376 BufRead or BufReadPost When starting to edit a new buffer, after
|
|
|
377 reading the file into the buffer, before
|
|
|
378 executing the modelines. See |BufWinEnter|
|
|
|
379 for when you need to do something after
|
|
|
380 processing the modelines.
|
|
|
381 This does NOT work for ":r file". Not used
|
|
|
382 when the file doesn't exist. Also used after
|
|
|
383 successfully recovering a file.
|
|
625
|
384 *BufReadCmd*
|
|
7
|
385 BufReadCmd Before starting to edit a new buffer. Should
|
|
|
386 read the file into the buffer. |Cmd-event|
|
|
625
|
387 *BufReadPre* *E200* *E201*
|
|
579
|
388 BufReadPre When starting to edit a new buffer, before
|
|
|
389 reading the file into the buffer. Not used
|
|
|
390 if the file doesn't exist.
|
|
|
391 *BufUnload*
|
|
|
392 BufUnload Before unloading a buffer. This is when the
|
|
|
393 text in the buffer is going to be freed. This
|
|
|
394 may be after a BufWritePost and before a
|
|
|
395 BufDelete. Also used for all buffers that are
|
|
|
396 loaded when Vim is going to exit.
|
|
|
397 NOTE: When this autocommand is executed, the
|
|
|
398 current buffer "%" may be different from the
|
|
|
399 buffer being unloaded "<afile>".
|
|
|
400 *BufWinEnter*
|
|
|
401 BufWinEnter After a buffer is displayed in a window. This
|
|
|
402 can be when the buffer is loaded (after
|
|
|
403 processing the modelines), when a hidden
|
|
|
404 buffer is displayed in a window (and is no
|
|
|
405 longer hidden) or a buffer already visible in
|
|
|
406 a window is also displayed in another window.
|
|
|
407 *BufWinLeave*
|
|
|
408 BufWinLeave Before a buffer is removed from a window.
|
|
|
409 Not when it's still visible in another window.
|
|
|
410 Also triggered when exiting. It's triggered
|
|
|
411 before BufUnload or BufHidden.
|
|
|
412 NOTE: When this autocommand is executed, the
|
|
|
413 current buffer "%" may be different from the
|
|
|
414 buffer being unloaded "<afile>".
|
|
|
415 *BufWipeout*
|
|
|
416 BufWipeout Before completely deleting a buffer. The
|
|
|
417 BufUnload and BufDelete events may be called
|
|
|
418 first (if the buffer was loaded and was in the
|
|
|
419 buffer list). Also used just before a buffer
|
|
|
420 is renamed (also when it's not in the buffer
|
|
|
421 list).
|
|
|
422 NOTE: When this autocommand is executed, the
|
|
|
423 current buffer "%" may be different from the
|
|
|
424 buffer being deleted "<afile>".
|
|
7
|
425 *BufWrite* *BufWritePre*
|
|
|
426 BufWrite or BufWritePre Before writing the whole buffer to a file.
|
|
|
427 *BufWriteCmd*
|
|
|
428 BufWriteCmd Before writing the whole buffer to a file.
|
|
|
429 Should do the writing of the file and reset
|
|
39
|
430 'modified' if successful, unless '+' is in
|
|
|
431 'cpo' and writing to another file |cpo-+|.
|
|
|
432 The buffer contents should not be changed.
|
|
|
433 |Cmd-event|
|
|
579
|
434 *BufWritePost*
|
|
|
435 BufWritePost After writing the whole buffer to a file
|
|
|
436 (should undo the commands for BufWritePre).
|
|
|
437 *CmdwinEnter*
|
|
|
438 CmdwinEnter After entering the command-line window.
|
|
|
439 Useful for setting options specifically for
|
|
|
440 this special type of window. This is
|
|
|
441 triggered _instead_ of BufEnter and WinEnter.
|
|
|
442 <afile> is set to a single character,
|
|
|
443 indicating the type of command-line.
|
|
|
444 |cmdwin-char|
|
|
|
445 *CmdwinLeave*
|
|
|
446 CmdwinLeave Before leaving the command-line window.
|
|
|
447 Useful to clean up any global setting done
|
|
|
448 with CmdwinEnter. This is triggered _instead_
|
|
|
449 of BufLeave and WinLeave.
|
|
|
450 <afile> is set to a single character,
|
|
|
451 indicating the type of command-line.
|
|
|
452 |cmdwin-char|
|
|
|
453 *ColorScheme*
|
|
|
454 ColorScheme After loading a color scheme. |:colorscheme|
|
|
661
|
455
|
|
579
|
456 *CursorHold*
|
|
|
457 CursorHold When the user doesn't press a key for the time
|
|
|
458 specified with 'updatetime'. Not re-triggered
|
|
|
459 until the user has pressed a key (i.e. doesn't
|
|
|
460 fire every 'updatetime' ms if you leave Vim to
|
|
|
461 make some coffee. :) See |CursorHold-example|
|
|
|
462 for previewing tags.
|
|
|
463 This event is only triggered in Normal mode.
|
|
1154
|
464 It is not triggered when waiting for a command
|
|
|
465 argument to be typed, or a movement after an
|
|
|
466 operator.
|
|
610
|
467 While recording the CursorHold event is not
|
|
|
468 triggered. |q|
|
|
579
|
469 Note: Interactive commands cannot be used for
|
|
|
470 this event. There is no hit-enter prompt,
|
|
|
471 the screen is updated directly (when needed).
|
|
|
472 Note: In the future there will probably be
|
|
|
473 another option to set the time.
|
|
|
474 Hint: to force an update of the status lines
|
|
|
475 use: >
|
|
|
476 :let &ro = &ro
|
|
|
477 < {only on Amiga, Unix, Win32, MSDOS and all GUI
|
|
|
478 versions}
|
|
661
|
479 *CursorHoldI*
|
|
|
480 CursorHoldI Just like CursorHold, but in Insert mode.
|
|
|
481
|
|
|
482 *CursorMoved*
|
|
|
483 CursorMoved After the cursor was moved in Normal mode.
|
|
694
|
484 Also when the text of the cursor line has been
|
|
|
485 changed, e.g., with "x", "rx" or "p".
|
|
661
|
486 Not triggered when there is typeahead or when
|
|
|
487 an operator is pending.
|
|
667
|
488 For an example see |match-parens|.
|
|
661
|
489 Careful: Don't do anything that the user does
|
|
|
490 not expect or that is slow.
|
|
|
491 *CursorMovedI*
|
|
|
492 CursorMovedI After the cursor was moved in Insert mode.
|
|
|
493 Otherwise the same as CursorMoved.
|
|
579
|
494 *EncodingChanged*
|
|
|
495 EncodingChanged Fires off after the 'encoding' option has been
|
|
|
496 changed. Useful to set up fonts, for example.
|
|
7
|
497 *FileAppendCmd*
|
|
|
498 FileAppendCmd Before appending to a file. Should do the
|
|
26
|
499 appending to the file. Use the '[ and ']
|
|
|
500 marks for the range of lines.|Cmd-event|
|
|
579
|
501 *FileAppendPost*
|
|
|
502 FileAppendPost After appending to a file.
|
|
|
503 *FileAppendPre*
|
|
|
504 FileAppendPre Before appending to a file. Use the '[ and ']
|
|
|
505 marks for the range of lines.
|
|
|
506 *FileChangedRO*
|
|
|
507 FileChangedRO Before making the first change to a read-only
|
|
|
508 file. Can be used to check-out the file from
|
|
|
509 a source control system. Not triggered when
|
|
|
510 the change was caused by an autocommand.
|
|
|
511 This event is triggered when making the first
|
|
|
512 change in a buffer or the first change after
|
|
823
|
513 'readonly' was set, just before the change is
|
|
|
514 applied to the text.
|
|
579
|
515 WARNING: If the autocommand moves the cursor
|
|
|
516 the effect of the change is undefined.
|
|
819
|
517 *E788*
|
|
|
518 It is not allowed to change to another buffer
|
|
|
519 here. You can reload the buffer but not edit
|
|
|
520 another one.
|
|
7
|
521 *FileChangedShell*
|
|
|
522 FileChangedShell When Vim notices that the modification time of
|
|
|
523 a file has changed since editing started.
|
|
|
524 Also when the file attributes of the file
|
|
|
525 change. |timestamp|
|
|
|
526 Mostly triggered after executing a shell
|
|
|
527 command, but also with a |:checktime| command
|
|
179
|
528 or when Gvim regains input focus.
|
|
7
|
529 This autocommand is triggered for each changed
|
|
|
530 file. It is not used when 'autoread' is set
|
|
|
531 and the buffer was not changed. If a
|
|
|
532 FileChangedShell autocommand is present the
|
|
|
533 warning message and prompt is not given.
|
|
179
|
534 The |v:fcs_reason| variable is set to indicate
|
|
|
535 what happened and |v:fcs_choice| can be used
|
|
|
536 to tell Vim what to do next.
|
|
7
|
537 NOTE: When this autocommand is executed, the
|
|
|
538 current buffer "%" may be different from the
|
|
|
539 buffer that was changed "<afile>".
|
|
|
540 NOTE: The commands must not change the current
|
|
|
541 buffer, jump to another buffer or delete a
|
|
|
542 buffer. *E246*
|
|
|
543 NOTE: This event never nests, to avoid an
|
|
|
544 endless loop. This means that while executing
|
|
|
545 commands for the FileChangedShell event no
|
|
|
546 other FileChangedShell event will be
|
|
|
547 triggered.
|
|
766
|
548 *FileChangedShellPost*
|
|
|
549 FileChangedShellPost After handling a file that was changed outside
|
|
|
550 of Vim. Can be used to update the statusline.
|
|
579
|
551 *FileEncoding*
|
|
|
552 FileEncoding Obsolete. It still works and is equivalent
|
|
|
553 to |EncodingChanged|.
|
|
|
554 *FileReadCmd*
|
|
|
555 FileReadCmd Before reading a file with a ":read" command.
|
|
|
556 Should do the reading of the file. |Cmd-event|
|
|
|
557 *FileReadPost*
|
|
|
558 FileReadPost After reading a file with a ":read" command.
|
|
|
559 Note that Vim sets the '[ and '] marks to the
|
|
|
560 first and last line of the read. This can be
|
|
|
561 used to operate on the lines just read.
|
|
|
562 *FileReadPre*
|
|
|
563 FileReadPre Before reading a file with a ":read" command.
|
|
|
564 *FileType*
|
|
1154
|
565 FileType When the 'filetype' option has been set. The
|
|
|
566 pattern is matched against the filetype.
|
|
579
|
567 <afile> can be used for the name of the file
|
|
|
568 where this option was set, and <amatch> for
|
|
|
569 the new value of 'filetype'.
|
|
|
570 See |filetypes|.
|
|
|
571 *FileWriteCmd*
|
|
|
572 FileWriteCmd Before writing to a file, when not writing the
|
|
|
573 whole buffer. Should do the writing to the
|
|
|
574 file. Should not change the buffer. Use the
|
|
|
575 '[ and '] marks for the range of lines.
|
|
|
576 |Cmd-event|
|
|
|
577 *FileWritePost*
|
|
|
578 FileWritePost After writing to a file, when not writing the
|
|
|
579 whole buffer.
|
|
|
580 *FileWritePre*
|
|
|
581 FileWritePre Before writing to a file, when not writing the
|
|
|
582 whole buffer. Use the '[ and '] marks for the
|
|
|
583 range of lines.
|
|
|
584 *FilterReadPost*
|
|
|
585 FilterReadPost After reading a file from a filter command.
|
|
|
586 Vim checks the pattern against the name of
|
|
|
587 the current buffer as with FilterReadPre.
|
|
|
588 Not triggered when 'shelltemp' is off.
|
|
|
589 *FilterReadPre* *E135*
|
|
|
590 FilterReadPre Before reading a file from a filter command.
|
|
|
591 Vim checks the pattern against the name of
|
|
|
592 the current buffer, not the name of the
|
|
|
593 temporary file that is the output of the
|
|
|
594 filter command.
|
|
|
595 Not triggered when 'shelltemp' is off.
|
|
|
596 *FilterWritePost*
|
|
|
597 FilterWritePost After writing a file for a filter command or
|
|
|
598 making a diff.
|
|
|
599 Vim checks the pattern against the name of
|
|
|
600 the current buffer as with FilterWritePre.
|
|
|
601 Not triggered when 'shelltemp' is off.
|
|
|
602 *FilterWritePre*
|
|
|
603 FilterWritePre Before writing a file for a filter command or
|
|
|
604 making a diff.
|
|
|
605 Vim checks the pattern against the name of
|
|
|
606 the current buffer, not the name of the
|
|
|
607 temporary file that is the output of the
|
|
|
608 filter command.
|
|
|
609 Not triggered when 'shelltemp' is off.
|
|
7
|
610 *FocusGained*
|
|
|
611 FocusGained When Vim got input focus. Only for the GUI
|
|
|
612 version and a few console versions where this
|
|
|
613 can be detected.
|
|
|
614 *FocusLost*
|
|
|
615 FocusLost When Vim lost input focus. Only for the GUI
|
|
|
616 version and a few console versions where this
|
|
11
|
617 can be detected. May also happen when a
|
|
|
618 dialog pops up.
|
|
7
|
619 *FuncUndefined*
|
|
|
620 FuncUndefined When a user function is used but it isn't
|
|
|
621 defined. Useful for defining a function only
|
|
1154
|
622 when it's used. The pattern is matched
|
|
|
623 against the function name. Both <amatch> and
|
|
|
624 <afile> are set to the name of the function.
|
|
161
|
625 See |autoload-functions|.
|
|
579
|
626 *GUIEnter*
|
|
|
627 GUIEnter After starting the GUI successfully, and after
|
|
|
628 opening the window. It is triggered before
|
|
|
629 VimEnter when using gvim. Can be used to
|
|
|
630 position the window from a .gvimrc file: >
|
|
|
631 :autocmd GUIEnter * winpos 100 50
|
|
1154
|
632 < *GUIFailed*
|
|
|
633 GUIFailed After starting the GUI failed. Vim may
|
|
|
634 continue to run in the terminal, if possible
|
|
|
635 (only on Unix and alikes, when connecting the
|
|
|
636 X server fails). You may want to quit Vim: >
|
|
|
637 :autocmd GUIFailed * qall
|
|
579
|
638 < *InsertChange*
|
|
|
639 InsertChange When typing <Insert> while in Insert or
|
|
|
640 Replace mode. The |v:insertmode| variable
|
|
|
641 indicates the new mode.
|
|
|
642 Be careful not to move the cursor or do
|
|
|
643 anything else that the user does not expect.
|
|
|
644 *InsertEnter*
|
|
1154
|
645 InsertEnter Just before starting Insert mode. Also for
|
|
|
646 Replace mode and Virtual Replace mode. The
|
|
579
|
647 |v:insertmode| variable indicates the mode.
|
|
|
648 Be careful not to move the cursor or do
|
|
|
649 anything else that the user does not expect.
|
|
|
650 *InsertLeave*
|
|
|
651 InsertLeave When leaving Insert mode. Also when using
|
|
|
652 CTRL-O |i_CTRL-O|. But not for |i_CTRL-C|.
|
|
|
653 *MenuPopup*
|
|
|
654 MenuPopup Just before showing the popup menu (under the
|
|
|
655 right mouse button). Useful for adjusting the
|
|
|
656 menu for what is under the cursor or mouse
|
|
|
657 pointer.
|
|
|
658 The pattern is matched against a single
|
|
|
659 character representing the mode:
|
|
|
660 n Normal
|
|
|
661 v Visual
|
|
|
662 o Operator-pending
|
|
|
663 i Insert
|
|
843
|
664 c Command line
|
|
579
|
665 *QuickFixCmdPre*
|
|
|
666 QuickFixCmdPre Before a quickfix command is run (|:make|,
|
|
657
|
667 |:lmake|, |:grep|, |:lgrep|, |:grepadd|,
|
|
|
668 |:lgrepadd|, |:vimgrep|, |:lvimgrep|,
|
|
1154
|
669 |:vimgrepadd|, |:lvimgrepadd|). The pattern is
|
|
657
|
670 matched against the command being run. When
|
|
|
671 |:grep| is used but 'grepprg' is set to
|
|
|
672 "internal" it still matches "grep".
|
|
579
|
673 This command cannot be used to set the
|
|
|
674 'makeprg' and 'grepprg' variables.
|
|
|
675 If this command causes an error, the quickfix
|
|
|
676 command is not executed.
|
|
|
677 *QuickFixCmdPost*
|
|
|
678 QuickFixCmdPost Like QuickFixCmdPre, but after a quickfix
|
|
842
|
679 command is run, before jumping to the first
|
|
|
680 location.
|
|
579
|
681 *RemoteReply*
|
|
|
682 RemoteReply When a reply from a Vim that functions as
|
|
1154
|
683 server was received |server2client()|. The
|
|
|
684 pattern is matched against the {serverid}.
|
|
579
|
685 <amatch> is equal to the {serverid} from which
|
|
|
686 the reply was sent, and <afile> is the actual
|
|
|
687 reply string.
|
|
|
688 Note that even if an autocommand is defined,
|
|
|
689 the reply should be read with |remote_read()|
|
|
|
690 to consume it.
|
|
|
691 *SessionLoadPost*
|
|
|
692 SessionLoadPost After loading the session file created using
|
|
|
693 the |:mksession| command.
|
|
724
|
694 *ShellCmdPost*
|
|
|
695 ShellCmdPost After executing a shell command with |:!cmd|,
|
|
|
696 |:shell|, |:make| and |:grep|. Can be used to
|
|
|
697 check for any changed files.
|
|
|
698 *ShellFilterPost*
|
|
|
699 ShellFilterPost After executing a shell command with
|
|
|
700 ":{range}!cmd", ":w !cmd" or ":r !cmd".
|
|
|
701 Can be used to check for any changed files.
|
|
716
|
702 *SourcePre*
|
|
|
703 SourcePre Before sourcing a Vim script. |:source|
|
|
1061
|
704 <afile> is the name of the file being sourced.
|
|
|
705 *SourceCmd*
|
|
|
706 SourceCmd When sourcing a Vim script. |:source|
|
|
|
707 <afile> is the name of the file being sourced.
|
|
|
708 The autocommand must source this file.
|
|
|
709 |Cmd-event|
|
|
650
|
710 *SpellFileMissing*
|
|
|
711 SpellFileMissing When trying to load a spell checking file and
|
|
1061
|
712 it can't be found. The pattern is matched
|
|
|
713 against the language. <amatch> is the
|
|
|
714 language, 'encoding' also matters. See
|
|
650
|
715 |spell-SpellFileMissing|.
|
|
579
|
716 *StdinReadPost*
|
|
|
717 StdinReadPost After reading from the stdin into the buffer,
|
|
|
718 before executing the modelines. Only used
|
|
|
719 when the "-" argument was used when Vim was
|
|
|
720 started |--|.
|
|
|
721 *StdinReadPre*
|
|
|
722 StdinReadPre Before reading from stdin into the buffer.
|
|
|
723 Only used when the "-" argument was used when
|
|
|
724 Vim was started |--|.
|
|
|
725 *SwapExists*
|
|
|
726 SwapExists Detected an existing swap file when starting
|
|
|
727 to edit a file. Only when it is possible to
|
|
|
728 select a way to handle the situation, when Vim
|
|
|
729 would ask the user what to do.
|
|
|
730 The |v:swapname| variable holds the name of
|
|
590
|
731 the swap file found, <afile> the file being
|
|
|
732 edited. |v:swapcommand| may contain a command
|
|
|
733 to be executed in the opened file.
|
|
|
734 The commands should set the |v:swapchoice|
|
|
|
735 variable to a string with one character to
|
|
|
736 tell Vim what should be done next:
|
|
579
|
737 'o' open read-only
|
|
|
738 'e' edit the file anyway
|
|
|
739 'r' recover
|
|
|
740 'd' delete the swap file
|
|
|
741 'q' quit, don't edit the file
|
|
|
742 'a' abort, like hitting CTRL-C
|
|
|
743 When set to an empty string the user will be
|
|
|
744 asked, as if there was no SwapExists autocmd.
|
|
|
745 Note: Do not try to change the buffer, the
|
|
|
746 results are unpredictable.
|
|
|
747 *Syntax*
|
|
1154
|
748 Syntax When the 'syntax' option has been set. The
|
|
|
749 pattern is matched against the syntax name.
|
|
579
|
750 <afile> can be used for the name of the file
|
|
|
751 where this option was set, and <amatch> for
|
|
|
752 the new value of 'syntax'.
|
|
|
753 See |:syn-on|.
|
|
677
|
754 *TabEnter*
|
|
|
755 TabEnter Just after entering a tab page. |tab-page|
|
|
872
|
756 After triggering the WinEnter and before
|
|
|
757 triggering the BufEnter event.
|
|
677
|
758 *TabLeave*
|
|
|
759 TabLeave Just before leaving a tab page. |tab-page|
|
|
|
760 A WinLeave event will have been triggered
|
|
|
761 first.
|
|
579
|
762 *TermChanged*
|
|
|
763 TermChanged After the value of 'term' has changed. Useful
|
|
|
764 for re-loading the syntax file to update the
|
|
|
765 colors, fonts and other terminal-dependent
|
|
|
766 settings. Executed for all loaded buffers.
|
|
|
767 *TermResponse*
|
|
|
768 TermResponse After the response to |t_RV| is received from
|
|
|
769 the terminal. The value of |v:termresponse|
|
|
|
770 can be used to do things depending on the
|
|
|
771 terminal version.
|
|
|
772 *User*
|
|
|
773 User Never executed automatically. To be used for
|
|
|
774 autocommands that are only executed with
|
|
|
775 ":doautocmd".
|
|
|
776 *UserGettingBored*
|
|
|
777 UserGettingBored When the user hits CTRL-C. Just kidding! :-)
|
|
|
778 *VimEnter*
|
|
|
779 VimEnter After doing all the startup stuff, including
|
|
|
780 loading .vimrc files, executing the "-c cmd"
|
|
|
781 arguments, creating all windows and loading
|
|
|
782 the buffers in them.
|
|
|
783 *VimLeave*
|
|
|
784 VimLeave Before exiting Vim, just after writing the
|
|
|
785 .viminfo file. Executed only once, like
|
|
|
786 VimLeavePre.
|
|
|
787 To detect an abnormal exit use |v:dying|.
|
|
|
788 *VimLeavePre*
|
|
|
789 VimLeavePre Before exiting Vim, just before writing the
|
|
|
790 .viminfo file. This is executed only once,
|
|
|
791 if there is a match with the name of what
|
|
|
792 happens to be the current buffer when exiting.
|
|
|
793 Mostly useful with a "*" pattern. >
|
|
|
794 :autocmd VimLeavePre * call CleanupStuff()
|
|
|
795 < To detect an abnormal exit use |v:dying|.
|
|
766
|
796 *VimResized*
|
|
|
797 VimResized After the Vim window was resized, thus 'lines'
|
|
|
798 and/or 'columns' changed. Not when starting
|
|
|
799 up though.
|
|
7
|
800 *WinEnter*
|
|
|
801 WinEnter After entering another window. Not done for
|
|
|
802 the first window, when Vim has just started.
|
|
|
803 Useful for setting the window height.
|
|
|
804 If the window is for another buffer, Vim
|
|
|
805 executes the BufEnter autocommands after the
|
|
|
806 WinEnter autocommands.
|
|
|
807 Note: When using ":split fname" the WinEnter
|
|
|
808 event is triggered after the split but before
|
|
|
809 the file "fname" is loaded.
|
|
|
810 *WinLeave*
|
|
|
811 WinLeave Before leaving a window. If the window to be
|
|
|
812 entered next is for a different buffer, Vim
|
|
|
813 executes the BufLeave autocommands before the
|
|
|
814 WinLeave autocommands (but not for ":new").
|
|
|
815 Not used for ":qa" or ":q" when exiting Vim.
|
|
|
816
|
|
|
817 ==============================================================================
|
|
|
818 6. Patterns *autocmd-patterns* *{pat}*
|
|
|
819
|
|
|
820 The file pattern {pat} is tested for a match against the file name in one of
|
|
|
821 two ways:
|
|
|
822 1. When there is no '/' in the pattern, Vim checks for a match against only
|
|
|
823 the tail part of the file name (without its leading directory path).
|
|
|
824 2. When there is a '/' in the pattern, Vim checks for a match against the
|
|
|
825 both short file name (as you typed it) and the full file name (after
|
|
|
826 expanding it to a full path and resolving symbolic links).
|
|
|
827
|
|
40
|
828 The special pattern <buffer> or <buffer=N> is used for buffer-local
|
|
|
829 autocommands |autocmd-buflocal|. This pattern is not matched against the name
|
|
|
830 of a buffer.
|
|
|
831
|
|
7
|
832 Examples: >
|
|
|
833 :autocmd BufRead *.txt set et
|
|
|
834 Set the 'et' option for all text files. >
|
|
|
835
|
|
|
836 :autocmd BufRead /vim/src/*.c set cindent
|
|
|
837 Set the 'cindent' option for C files in the /vim/src directory. >
|
|
|
838
|
|
|
839 :autocmd BufRead /tmp/*.c set ts=5
|
|
|
840 If you have a link from "/tmp/test.c" to "/home/nobody/vim/src/test.c", and
|
|
|
841 you start editing "/tmp/test.c", this autocommand will match.
|
|
|
842
|
|
|
843 Note: To match part of a path, but not from the root directory, use a '*' as
|
|
|
844 the first character. Example: >
|
|
|
845 :autocmd BufRead */doc/*.txt set tw=78
|
|
|
846 This autocommand will for example be executed for "/tmp/doc/xx.txt" and
|
|
|
847 "/usr/home/piet/doc/yy.txt". The number of directories does not matter here.
|
|
|
848
|
|
|
849
|
|
|
850 The file name that the pattern is matched against is after expanding
|
|
|
851 wildcards. Thus is you issue this command: >
|
|
|
852 :e $ROOTDIR/main.$EXT
|
|
|
853 The argument is first expanded to: >
|
|
|
854 /usr/root/main.py
|
|
|
855 Before it's matched with the pattern of the autocommand. Careful with this
|
|
|
856 when using events like FileReadCmd, the value of <amatch> may not be what you
|
|
|
857 expect.
|
|
|
858
|
|
|
859
|
|
|
860 Environment variables can be used in a pattern: >
|
|
|
861 :autocmd BufRead $VIMRUNTIME/doc/*.txt set expandtab
|
|
|
862 And ~ can be used for the home directory (if $HOME is defined): >
|
|
|
863 :autocmd BufWritePost ~/.vimrc so ~/.vimrc
|
|
|
864 :autocmd BufRead ~archive/* set readonly
|
|
|
865 The environment variable is expanded when the autocommand is defined, not when
|
|
|
866 the autocommand is executed. This is different from the command!
|
|
|
867
|
|
|
868 *file-pattern*
|
|
|
869 The pattern is interpreted like mostly used in file names:
|
|
|
870 * matches any sequence of characters
|
|
|
871 ? matches any single character
|
|
|
872 \? matches a '?'
|
|
|
873 . matches a '.'
|
|
|
874 ~ matches a '~'
|
|
|
875 , separates patterns
|
|
|
876 \, matches a ','
|
|
|
877 { } like \( \) in a |pattern|
|
|
|
878 , inside { }: like \| in a |pattern|
|
|
|
879 \ special meaning like in a |pattern|
|
|
|
880 [ch] matches 'c' or 'h'
|
|
|
881 [^ch] match any character but 'c' and 'h'
|
|
|
882
|
|
|
883 Note that for all systems the '/' character is used for path separator (even
|
|
|
884 MS-DOS and OS/2). This was done because the backslash is difficult to use
|
|
|
885 in a pattern and to make the autocommands portable across different systems.
|
|
|
886
|
|
40
|
887 *autocmd-changes*
|
|
7
|
888 Matching with the pattern is done when an event is triggered. Changing the
|
|
|
889 buffer name in one of the autocommands, or even deleting the buffer, does not
|
|
|
890 change which autocommands will be executed. Example: >
|
|
|
891
|
|
|
892 au BufEnter *.foo bdel
|
|
|
893 au BufEnter *.foo set modified
|
|
|
894
|
|
|
895 This will delete the current buffer and then set 'modified' in what has become
|
|
|
896 the current buffer instead. Vim doesn't take into account that "*.foo"
|
|
|
897 doesn't match with that buffer name. It matches "*.foo" with the name of the
|
|
|
898 buffer at the moment the event was triggered.
|
|
|
899
|
|
40
|
900 However, buffer-local autocommands will not be executed for a buffer that has
|
|
|
901 been wiped out with |:bwipe|. After deleting the buffer with |:bdel| the
|
|
|
902 buffer actually still exists (it becomes unlisted), thus the autocommands are
|
|
|
903 still executed.
|
|
|
904
|
|
7
|
905 ==============================================================================
|
|
856
|
906 7. Buffer-local autocommands *autocmd-buflocal* *autocmd-buffer-local*
|
|
|
907 *<buffer=N>* *<buffer=abuf>* *E680*
|
|
40
|
908
|
|
|
909 Buffer-local autocommands are attached to a specific buffer. They are useful
|
|
|
910 if the buffer does not have a name and when the name does not match a specific
|
|
|
911 pattern. But it also means they must be explicitly added to each buffer.
|
|
|
912
|
|
|
913 Instead of a pattern buffer-local autocommands use one of these forms:
|
|
|
914 <buffer> current buffer
|
|
|
915 <buffer=99> buffer number 99
|
|
|
916 <buffer=abuf> using <abuf> (only when executing autocommands)
|
|
|
917 |<abuf>|
|
|
|
918
|
|
|
919 Examples: >
|
|
|
920 :au CursorHold <buffer> echo 'hold'
|
|
|
921 :au CursorHold <buffer=33> echo 'hold'
|
|
|
922 :au CursorHold <buffer=abuf> echo 'hold'
|
|
|
923
|
|
|
924 All the commands for autocommands also work with buffer-local autocommands,
|
|
|
925 simply use the special string instead of the pattern. Examples: >
|
|
856
|
926 :au! * <buffer> " remove buffer-local autocommands for
|
|
|
927 " current buffer
|
|
|
928 :au! * <buffer=33> " remove buffer-local autocommands for
|
|
|
929 " buffer #33
|
|
40
|
930 :dobuf :au! CursorHold <buffer> " remove autocmd for given event for all
|
|
856
|
931 " buffers
|
|
|
932 :au * <buffer> " list buffer-local autocommands for
|
|
|
933 " current buffer
|
|
40
|
934
|
|
|
935 Note that when an autocommand is defined for the current buffer, it is stored
|
|
|
936 with the buffer number. Thus it uses the form "<buffer=12>", where 12 is the
|
|
|
937 number of the current buffer. You will see this when listing autocommands,
|
|
|
938 for example.
|
|
|
939
|
|
|
940 To test for presence of buffer-local autocommands use the |exists()| function
|
|
|
941 as follows: >
|
|
|
942 :if exists("#CursorHold#<buffer=12>") | ... | endif
|
|
|
943 :if exists("#CursorHold#<buffer>") | ... | endif " for current buffer
|
|
|
944
|
|
|
945 When a buffer is wiped out its buffer-local autocommands are also gone, of
|
|
|
946 course. Note that when deleting a buffer, e.g., with ":bdel", it is only
|
|
|
947 unlisted, the autocommands are still present. In order to see the removal of
|
|
|
948 buffer-local autocommands: >
|
|
|
949 :set verbose=6
|
|
|
950
|
|
|
951 It is not possible to define buffer-local autocommands for a non-existent
|
|
|
952 buffer.
|
|
|
953
|
|
|
954 ==============================================================================
|
|
|
955 8. Groups *autocmd-groups*
|
|
7
|
956
|
|
|
957 Autocommands can be put together in a group. This is useful for removing or
|
|
|
958 executing a group of autocommands. For example, all the autocommands for
|
|
|
959 syntax highlighting are put in the "highlight" group, to be able to execute
|
|
|
960 ":doautoall highlight BufRead" when the GUI starts.
|
|
|
961
|
|
|
962 When no specific group is selected, Vim uses the default group. The default
|
|
|
963 group does not have a name. You cannot execute the autocommands from the
|
|
|
964 default group separately; you can execute them only by executing autocommands
|
|
|
965 for all groups.
|
|
|
966
|
|
|
967 Normally, when executing autocommands automatically, Vim uses the autocommands
|
|
|
968 for all groups. The group only matters when executing autocommands with
|
|
|
969 ":doautocmd" or ":doautoall", or when defining or deleting autocommands.
|
|
|
970
|
|
|
971 The group name can contain any characters except white space. The group name
|
|
|
972 "end" is reserved (also in uppercase).
|
|
|
973
|
|
|
974 The group name is case sensitive. Note that this is different from the event
|
|
|
975 name!
|
|
|
976
|
|
|
977 *:aug* *:augroup*
|
|
|
978 :aug[roup] {name} Define the autocmd group name for the
|
|
|
979 following ":autocmd" commands. The name "end"
|
|
|
980 or "END" selects the default group.
|
|
|
981
|
|
|
982 *:augroup-delete* *E367*
|
|
|
983 :aug[roup]! {name} Delete the autocmd group {name}. Don't use
|
|
|
984 this if there is still an autocommand using
|
|
|
985 this group! This is not checked.
|
|
|
986
|
|
|
987 To enter autocommands for a specific group, use this method:
|
|
|
988 1. Select the group with ":augroup {name}".
|
|
|
989 2. Delete any old autocommands with ":au!".
|
|
|
990 3. Define the autocommands.
|
|
|
991 4. Go back to the default group with "augroup END".
|
|
|
992
|
|
|
993 Example: >
|
|
|
994 :augroup uncompress
|
|
|
995 : au!
|
|
|
996 : au BufEnter *.gz %!gunzip
|
|
|
997 :augroup END
|
|
|
998
|
|
|
999 This prevents having the autocommands defined twice (e.g., after sourcing the
|
|
|
1000 .vimrc file again).
|
|
|
1001
|
|
|
1002 ==============================================================================
|
|
40
|
1003 9. Executing autocommands *autocmd-execute*
|
|
7
|
1004
|
|
|
1005 Vim can also execute Autocommands non-automatically. This is useful if you
|
|
|
1006 have changed autocommands, or when Vim has executed the wrong autocommands
|
|
|
1007 (e.g., the file pattern match was wrong).
|
|
|
1008
|
|
|
1009 Note that the 'eventignore' option applies here too. Events listed in this
|
|
|
1010 option will not cause any commands to be executed.
|
|
|
1011
|
|
|
1012 *:do* *:doau* *:doautocmd* *E217*
|
|
|
1013 :do[autocmd] [group] {event} [fname]
|
|
|
1014 Apply the autocommands matching [fname] (default:
|
|
|
1015 current file name) for {event} to the current buffer.
|
|
|
1016 You can use this when the current file name does not
|
|
|
1017 match the right pattern, after changing settings, or
|
|
|
1018 to execute autocommands for a certain event.
|
|
|
1019 It's possible to use this inside an autocommand too,
|
|
|
1020 so you can base the autocommands for one extension on
|
|
|
1021 another extension. Example: >
|
|
|
1022 :au Bufenter *.cpp so ~/.vimrc_cpp
|
|
|
1023 :au Bufenter *.cpp doau BufEnter x.c
|
|
|
1024 < Be careful to avoid endless loops. See
|
|
|
1025 |autocmd-nested|.
|
|
|
1026
|
|
|
1027 When the [group] argument is not given, Vim executes
|
|
|
1028 the autocommands for all groups. When the [group]
|
|
|
1029 argument is included, Vim executes only the matching
|
|
|
1030 autocommands for that group. Note: if you use an
|
|
|
1031 undefined group name, Vim gives you an error message.
|
|
|
1032
|
|
557
|
1033 After applying the autocommands the modelines are
|
|
|
1034 processed, so that their overrule the settings from
|
|
|
1035 autocommands, like what happens when editing a file.
|
|
|
1036
|
|
7
|
1037 *:doautoa* *:doautoall*
|
|
|
1038 :doautoa[ll] [group] {event} [fname]
|
|
|
1039 Like ":doautocmd", but apply the autocommands to each
|
|
|
1040 loaded buffer. Note that {fname} is used to select
|
|
|
1041 the autocommands, not the buffers to which they are
|
|
|
1042 applied.
|
|
|
1043 Careful: Don't use this for autocommands that delete a
|
|
|
1044 buffer, change to another buffer or change the
|
|
|
1045 contents of a buffer; the result is unpredictable.
|
|
|
1046 This command is intended for autocommands that set
|
|
|
1047 options, change highlighting, and things like that.
|
|
|
1048
|
|
|
1049 ==============================================================================
|
|
40
|
1050 10. Using autocommands *autocmd-use*
|
|
7
|
1051
|
|
|
1052 For WRITING FILES there are four possible sets of events. Vim uses only one
|
|
|
1053 of these sets for a write command:
|
|
|
1054
|
|
|
1055 BufWriteCmd BufWritePre BufWritePost writing the whole buffer
|
|
|
1056 FilterWritePre FilterWritePost writing to filter temp file
|
|
|
1057 FileAppendCmd FileAppendPre FileAppendPost appending to a file
|
|
|
1058 FileWriteCmd FileWritePre FileWritePost any other file write
|
|
|
1059
|
|
|
1060 When there is a matching "*Cmd" autocommand, it is assumed it will do the
|
|
|
1061 writing. No further writing is done and the other events are not triggered.
|
|
|
1062 |Cmd-event|
|
|
|
1063
|
|
|
1064 Note that the *WritePost commands should undo any changes to the buffer that
|
|
|
1065 were caused by the *WritePre commands; otherwise, writing the file will have
|
|
|
1066 the side effect of changing the buffer.
|
|
|
1067
|
|
|
1068 Before executing the autocommands, the buffer from which the lines are to be
|
|
|
1069 written temporarily becomes the current buffer. Unless the autocommands
|
|
|
1070 change the current buffer or delete the previously current buffer, the
|
|
|
1071 previously current buffer is made the current buffer again.
|
|
|
1072
|
|
|
1073 The *WritePre and *AppendPre autocommands must not delete the buffer from
|
|
|
1074 which the lines are to be written.
|
|
|
1075
|
|
|
1076 The '[ and '] marks have a special position:
|
|
|
1077 - Before the *ReadPre event the '[ mark is set to the line just above where
|
|
|
1078 the new lines will be inserted.
|
|
|
1079 - Before the *ReadPost event the '[ mark is set to the first line that was
|
|
|
1080 just read, the '] mark to the last line.
|
|
26
|
1081 - Before executing the *WriteCmd, *WritePre and *AppendPre autocommands the '[
|
|
|
1082 mark is set to the first line that will be written, the '] mark to the last
|
|
|
1083 line.
|
|
7
|
1084 Careful: '[ and '] change when using commands that change the buffer.
|
|
|
1085
|
|
|
1086 In commands which expect a file name, you can use "<afile>" for the file name
|
|
|
1087 that is being read |:<afile>| (you can also use "%" for the current file
|
|
|
1088 name). "<abuf>" can be used for the buffer number of the currently effective
|
|
|
1089 buffer. This also works for buffers that doesn't have a name. But it doesn't
|
|
|
1090 work for files without a buffer (e.g., with ":r file").
|
|
|
1091
|
|
|
1092 *gzip-example*
|
|
|
1093 Examples for reading and writing compressed files: >
|
|
|
1094 :augroup gzip
|
|
|
1095 : autocmd!
|
|
|
1096 : autocmd BufReadPre,FileReadPre *.gz set bin
|
|
|
1097 : autocmd BufReadPost,FileReadPost *.gz '[,']!gunzip
|
|
|
1098 : autocmd BufReadPost,FileReadPost *.gz set nobin
|
|
|
1099 : autocmd BufReadPost,FileReadPost *.gz execute ":doautocmd BufReadPost " . expand("%:r")
|
|
|
1100 : autocmd BufWritePost,FileWritePost *.gz !mv <afile> <afile>:r
|
|
|
1101 : autocmd BufWritePost,FileWritePost *.gz !gzip <afile>:r
|
|
|
1102
|
|
|
1103 : autocmd FileAppendPre *.gz !gunzip <afile>
|
|
|
1104 : autocmd FileAppendPre *.gz !mv <afile>:r <afile>
|
|
|
1105 : autocmd FileAppendPost *.gz !mv <afile> <afile>:r
|
|
|
1106 : autocmd FileAppendPost *.gz !gzip <afile>:r
|
|
|
1107 :augroup END
|
|
|
1108
|
|
|
1109 The "gzip" group is used to be able to delete any existing autocommands with
|
|
|
1110 ":autocmd!", for when the file is sourced twice.
|
|
|
1111
|
|
|
1112 ("<afile>:r" is the file name without the extension, see |:_%:|)
|
|
|
1113
|
|
|
1114 The commands executed for the BufNewFile, BufRead/BufReadPost, BufWritePost,
|
|
|
1115 FileAppendPost and VimLeave events do not set or reset the changed flag of the
|
|
|
1116 buffer. When you decompress the buffer with the BufReadPost autocommands, you
|
|
|
1117 can still exit with ":q". When you use ":undo" in BufWritePost to undo the
|
|
|
1118 changes made by BufWritePre commands, you can still do ":q" (this also makes
|
|
|
1119 "ZZ" work). If you do want the buffer to be marked as modified, set the
|
|
|
1120 'modified' option.
|
|
|
1121
|
|
|
1122 To execute Normal mode commands from an autocommand, use the ":normal"
|
|
|
1123 command. Use with care! If the Normal mode command is not finished, the user
|
|
|
1124 needs to type characters (e.g., after ":normal m" you need to type a mark
|
|
|
1125 name).
|
|
|
1126
|
|
|
1127 If you want the buffer to be unmodified after changing it, reset the
|
|
|
1128 'modified' option. This makes it possible to exit the buffer with ":q"
|
|
|
1129 instead of ":q!".
|
|
|
1130
|
|
|
1131 *autocmd-nested* *E218*
|
|
|
1132 By default, autocommands do not nest. If you use ":e" or ":w" in an
|
|
|
1133 autocommand, Vim does not execute the BufRead and BufWrite autocommands for
|
|
|
1134 those commands. If you do want this, use the "nested" flag for those commands
|
|
|
1135 in which you want nesting. For example: >
|
|
|
1136 :autocmd FileChangedShell *.c nested e!
|
|
|
1137 The nesting is limited to 10 levels to get out of recursive loops.
|
|
|
1138
|
|
|
1139 It's possible to use the ":au" command in an autocommand. This can be a
|
|
|
1140 self-modifying command! This can be useful for an autocommand that should
|
|
|
1141 execute only once.
|
|
|
1142
|
|
590
|
1143 If you want to skip autocommands for one command, use the |:noautocmd| command
|
|
|
1144 modifier or the 'eventignore' option.
|
|
7
|
1145
|
|
|
1146 Note: When reading a file (with ":read file" or with a filter command) and the
|
|
|
1147 last line in the file does not have an <EOL>, Vim remembers this. At the next
|
|
|
1148 write (with ":write file" or with a filter command), if the same line is
|
|
|
1149 written again as the last line in a file AND 'binary' is set, Vim does not
|
|
|
1150 supply an <EOL>. This makes a filter command on the just read lines write the
|
|
|
1151 same file as was read, and makes a write command on just filtered lines write
|
|
|
1152 the same file as was read from the filter. For example, another way to write
|
|
|
1153 a compressed file: >
|
|
|
1154
|
|
|
1155 :autocmd FileWritePre *.gz set bin|'[,']!gzip
|
|
|
1156 :autocmd FileWritePost *.gz undo|set nobin
|
|
|
1157 <
|
|
|
1158 *autocommand-pattern*
|
|
|
1159 You can specify multiple patterns, separated by commas. Here are some
|
|
|
1160 examples: >
|
|
|
1161
|
|
|
1162 :autocmd BufRead * set tw=79 nocin ic infercase fo=2croq
|
|
|
1163 :autocmd BufRead .letter set tw=72 fo=2tcrq
|
|
|
1164 :autocmd BufEnter .letter set dict=/usr/lib/dict/words
|
|
|
1165 :autocmd BufLeave .letter set dict=
|
|
|
1166 :autocmd BufRead,BufNewFile *.c,*.h set tw=0 cin noic
|
|
|
1167 :autocmd BufEnter *.c,*.h abbr FOR for (i = 0; i < 3; ++i)<CR>{<CR>}<Esc>O
|
|
|
1168 :autocmd BufLeave *.c,*.h unabbr FOR
|
|
|
1169
|
|
|
1170 For makefiles (makefile, Makefile, imakefile, makefile.unix, etc.): >
|
|
|
1171
|
|
|
1172 :autocmd BufEnter ?akefile* set include=^s\=include
|
|
|
1173 :autocmd BufLeave ?akefile* set include&
|
|
|
1174
|
|
|
1175 To always start editing C files at the first function: >
|
|
|
1176
|
|
|
1177 :autocmd BufRead *.c,*.h 1;/^{
|
|
|
1178
|
|
|
1179 Without the "1;" above, the search would start from wherever the file was
|
|
|
1180 entered, rather than from the start of the file.
|
|
|
1181
|
|
|
1182 *skeleton* *template*
|
|
|
1183 To read a skeleton (template) file when opening a new file: >
|
|
|
1184
|
|
|
1185 :autocmd BufNewFile *.c 0r ~/vim/skeleton.c
|
|
|
1186 :autocmd BufNewFile *.h 0r ~/vim/skeleton.h
|
|
|
1187 :autocmd BufNewFile *.java 0r ~/vim/skeleton.java
|
|
|
1188
|
|
|
1189 To insert the current date and time in a *.html file when writing it: >
|
|
|
1190
|
|
|
1191 :autocmd BufWritePre,FileWritePre *.html ks|call LastMod()|'s
|
|
|
1192 :fun LastMod()
|
|
|
1193 : if line("$") > 20
|
|
|
1194 : let l = 20
|
|
|
1195 : else
|
|
|
1196 : let l = line("$")
|
|
|
1197 : endif
|
|
|
1198 : exe "1," . l . "g/Last modified: /s/Last modified: .*/Last modified: " .
|
|
|
1199 : \ strftime("%Y %b %d")
|
|
|
1200 :endfun
|
|
|
1201
|
|
|
1202 You need to have a line "Last modified: <date time>" in the first 20 lines
|
|
|
1203 of the file for this to work. Vim replaces <date time> (and anything in the
|
|
|
1204 same line after it) with the current date and time. Explanation:
|
|
|
1205 ks mark current position with mark 's'
|
|
|
1206 call LastMod() call the LastMod() function to do the work
|
|
|
1207 's return the cursor to the old position
|
|
|
1208 The LastMod() function checks if the file is shorter than 20 lines, and then
|
|
|
1209 uses the ":g" command to find lines that contain "Last modified: ". For those
|
|
|
1210 lines the ":s" command is executed to replace the existing date with the
|
|
|
1211 current one. The ":execute" command is used to be able to use an expression
|
|
|
1212 for the ":g" and ":s" commands. The date is obtained with the strftime()
|
|
|
1213 function. You can change its argument to get another date string.
|
|
|
1214
|
|
|
1215 When entering :autocmd on the command-line, completion of events and command
|
|
|
1216 names may be done (with <Tab>, CTRL-D, etc.) where appropriate.
|
|
|
1217
|
|
|
1218 Vim executes all matching autocommands in the order that you specify them.
|
|
|
1219 It is recommended that your first autocommand be used for all files by using
|
|
|
1220 "*" as the file pattern. This means that you can define defaults you like
|
|
|
1221 here for any settings, and if there is another matching autocommand it will
|
|
|
1222 override these. But if there is no other matching autocommand, then at least
|
|
|
1223 your default settings are recovered (if entering this file from another for
|
|
|
1224 which autocommands did match). Note that "*" will also match files starting
|
|
|
1225 with ".", unlike Unix shells.
|
|
|
1226
|
|
|
1227 *autocmd-searchpat*
|
|
|
1228 Autocommands do not change the current search patterns. Vim saves the current
|
|
|
1229 search patterns before executing autocommands then restores them after the
|
|
|
1230 autocommands finish. This means that autocommands do not affect the strings
|
|
|
1231 highlighted with the 'hlsearch' option. Within autocommands, you can still
|
|
|
1232 use search patterns normally, e.g., with the "n" command.
|
|
|
1233 If you want an autocommand to set the search pattern, such that it is used
|
|
|
1234 after the autocommand finishes, use the ":let @/ =" command.
|
|
|
1235 The search-highlighting cannot be switched off with ":nohlsearch" in an
|
|
|
1236 autocommand. Use the 'h' flag in the 'viminfo' option to disable search-
|
|
|
1237 highlighting when starting Vim.
|
|
|
1238
|
|
|
1239 *Cmd-event*
|
|
|
1240 When using one of the "*Cmd" events, the matching autocommands are expected to
|
|
1061
|
1241 do the file reading, writing or sourcing. This can be used when working with
|
|
|
1242 a special kind of file, for example on a remote system.
|
|
7
|
1243 CAREFUL: If you use these events in a wrong way, it may have the effect of
|
|
|
1244 making it impossible to read or write the matching files! Make sure you test
|
|
|
1245 your autocommands properly. Best is to use a pattern that will never match a
|
|
|
1246 normal file name, for example "ftp://*".
|
|
|
1247
|
|
|
1248 When defining a BufReadCmd it will be difficult for Vim to recover a crashed
|
|
|
1249 editing session. When recovering from the original file, Vim reads only those
|
|
|
1250 parts of a file that are not found in the swap file. Since that is not
|
|
|
1251 possible with a BufReadCmd, use the |:preserve| command to make sure the
|
|
|
1252 original file isn't needed for recovery. You might want to do this only when
|
|
|
1253 you expect the file to be modified.
|
|
|
1254
|
|
1061
|
1255 For file read and write commands the |v:cmdarg| variable holds the "++enc="
|
|
|
1256 and "++ff=" argument that are effective. These should be used for the command
|
|
|
1257 that reads/writes the file. The |v:cmdbang| variable is one when "!" was
|
|
|
1258 used, zero otherwise.
|
|
7
|
1259
|
|
|
1260 See the $VIMRUNTIME/plugin/netrw.vim for examples.
|
|
|
1261
|
|
590
|
1262 ==============================================================================
|
|
|
1263 11. Disabling autocommands *autocmd-disable*
|
|
|
1264
|
|
|
1265 To disable autocommands for some time use the 'eventignore' option. Note that
|
|
|
1266 this may cause unexpected behavior, make sure you restore 'eventignore'
|
|
|
1267 afterwards, using a |:try| block with |:finally|.
|
|
|
1268
|
|
|
1269 *:noautocmd* *:noa*
|
|
|
1270 To disable autocommands for just one command use the ":noautocmd" command
|
|
|
1271 modifier. This will set 'eventignore' to "all" for the duration of the
|
|
|
1272 following command. Example: >
|
|
|
1273
|
|
|
1274 :noautocmd w fname.gz
|
|
|
1275
|
|
|
1276 This will write the file without triggering the autocommands defined by the
|
|
|
1277 gzip plugin.
|
|
|
1278
|
|
40
|
1279
|
|
7
|
1280 vim:tw=78:ts=8:ft=help:norl:
|
