zeertzjq | 476b65e | 2025-06-19 19:40:51 +0200 | [diff] [blame] | 1 | *autocmd.txt* For Vim version 9.1. Last change: 2025 Jun 19 |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 2 | |
| 3 | |
| 4 | VIM REFERENCE MANUAL by Bram Moolenaar |
| 5 | |
| 6 | |
Bram Moolenaar | 675e8d6 | 2018-06-24 20:42:01 +0200 | [diff] [blame] | 7 | Automatic commands *autocommand* *autocommands* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 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| |
Bram Moolenaar | b5bf5b8 | 2004-12-24 14:35:23 +0000 | [diff] [blame] | 17 | 7. Buffer-local autocommands |autocmd-buflocal| |
| 18 | 8. Groups |autocmd-groups| |
| 19 | 9. Executing autocommands |autocmd-execute| |
| 20 | 10. Using autocommands |autocmd-use| |
Bram Moolenaar | b348038 | 2005-12-11 21:33:32 +0000 | [diff] [blame] | 21 | 11. Disabling autocommands |autocmd-disable| |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 22 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 23 | |
| 24 | ============================================================================== |
| 25 | 1. Introduction *autocmd-intro* |
| 26 | |
Bram Moolenaar | d4755bb | 2004-09-02 19:12:26 +0000 | [diff] [blame] | 27 | You can specify commands to be executed automatically when reading or writing |
| 28 | a file, when entering or leaving a buffer or window, and when exiting Vim. |
| 29 | For example, you can create an autocommand to set the 'cindent' option for |
| 30 | files matching *.c. You can also use autocommands to implement advanced |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 31 | features, such as editing compressed files (see |gzip-example|). The usual |
| 32 | place to put autocommands is in your .vimrc or .exrc file. |
| 33 | |
Bram Moolenaar | 7254067 | 2018-02-09 22:00:53 +0100 | [diff] [blame] | 34 | *E203* *E204* *E143* *E855* *E937* *E952* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 35 | WARNING: Using autocommands is very powerful, and may lead to unexpected side |
| 36 | effects. 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 Lakshmanan | 971f682 | 2022-05-24 11:40:11 +0100 | [diff] [blame] | 50 | Recommended 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 Moolenaar | cfa8f9a | 2022-06-03 21:59:47 +0100 | [diff] [blame] | 53 | - Make it so that the script it is defined in can be sourced several times |
Yegappan Lakshmanan | 971f682 | 2022-05-24 11:40:11 +0100 | [diff] [blame] | 54 | without the autocommand being repeated. |
| 55 | |
| 56 | Example in Vim9 script: > |
Boyang Du | 7298565 | 2024-07-09 18:46:12 +0200 | [diff] [blame] | 57 | autocmd_add([{replace: true, |
Yegappan Lakshmanan | 971f682 | 2022-05-24 11:40:11 +0100 | [diff] [blame] | 58 | group: 'DemoGroup', |
| 59 | event: 'BufEnter', |
| 60 | pattern: '*.txt', |
| 61 | cmd: 'call DemoBufEnter()' |
Boyang Du | 7298565 | 2024-07-09 18:46:12 +0200 | [diff] [blame] | 62 | }]) |
Yegappan Lakshmanan | 971f682 | 2022-05-24 11:40:11 +0100 | [diff] [blame] | 63 | |
| 64 | In legacy script: > |
Boyang Du | 7298565 | 2024-07-09 18:46:12 +0200 | [diff] [blame] | 65 | call autocmd_add([#{replace: v:true, |
Yegappan Lakshmanan | 971f682 | 2022-05-24 11:40:11 +0100 | [diff] [blame] | 66 | \ group: 'DemoGroup', |
Bram Moolenaar | 938ae28 | 2023-02-20 20:44:55 +0000 | [diff] [blame] | 67 | \ event: 'BufEnter', |
Yegappan Lakshmanan | 971f682 | 2022-05-24 11:40:11 +0100 | [diff] [blame] | 68 | \ pattern: '*.txt', |
| 69 | \ cmd: 'call DemoBufEnter()' |
Boyang Du | 7298565 | 2024-07-09 18:46:12 +0200 | [diff] [blame] | 70 | \ }]) |
Yegappan Lakshmanan | 971f682 | 2022-05-24 11:40:11 +0100 | [diff] [blame] | 71 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 72 | ============================================================================== |
| 73 | 2. Defining autocommands *autocmd-define* |
| 74 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 75 | *:au* *:autocmd* |
Bram Moolenaar | fd31be2 | 2022-01-16 14:46:06 +0000 | [diff] [blame] | 76 | :au[tocmd] [group] {event} {aupat} [++once] [++nested] {cmd} |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 77 | Add {cmd} to the list of commands that Vim will |
| 78 | execute automatically on {event} for a file matching |
Bram Moolenaar | fd31be2 | 2022-01-16 14:46:06 +0000 | [diff] [blame] | 79 | {aupat} |autocmd-patterns|. |
Bram Moolenaar | 8538867 | 2021-01-31 17:03:52 +0100 | [diff] [blame] | 80 | Here {event} cannot be "*". *E1155* |
Bram Moolenaar | 98ef233 | 2018-03-18 14:44:37 +0100 | [diff] [blame] | 81 | Note: A quote character is seen as argument to the |
| 82 | :autocmd and won't start a comment. |
Bram Moolenaar | 8f3f58f | 2010-01-06 20:52:26 +0100 | [diff] [blame] | 83 | Vim always adds the {cmd} after existing autocommands, |
| 84 | so that the autocommands execute in the order in which |
Bram Moolenaar | eb93f3f | 2019-04-04 15:04:56 +0200 | [diff] [blame] | 85 | they were given. |
| 86 | See |autocmd-nested| for [++nested]. "nested" |
| 87 | (without the ++) can also be used, for backwards |
Bram Moolenaar | 1588bc8 | 2022-03-08 21:35:07 +0000 | [diff] [blame] | 88 | compatibility, but not in |Vim9| script. *E1078* |
Bram Moolenaar | eb93f3f | 2019-04-04 15:04:56 +0200 | [diff] [blame] | 89 | *autocmd-once* |
| 90 | If [++once] is supplied the command is executed once, |
| 91 | then removed ("one shot"). |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 92 | |
Bram Moolenaar | b5bf5b8 | 2004-12-24 14:35:23 +0000 | [diff] [blame] | 93 | The special pattern <buffer> or <buffer=N> defines a buffer-local autocommand. |
| 94 | See |autocmd-buflocal|. |
| 95 | |
Bram Moolenaar | 1b884a0 | 2020-12-10 21:11:27 +0100 | [diff] [blame] | 96 | If the `:autocmd` is in Vim9 script (a script that starts with `:vim9script` |
| 97 | and in a `:def` function) then {cmd} will be executed as in Vim9 |
Bram Moolenaar | 4466ad6 | 2020-11-21 13:16:30 +0100 | [diff] [blame] | 98 | script. Thus this depends on where the autocmd is defined, not where it is |
| 99 | triggered. |
Bram Moolenaar | f1dcd14 | 2022-12-31 15:30:45 +0000 | [diff] [blame] | 100 | *:autocmd-block* |
Bram Moolenaar | 6aa5729 | 2021-08-14 21:25:52 +0200 | [diff] [blame] | 101 | {cmd} can be a block, like with `:command`, see |:command-repl|. Example: > |
Bram Moolenaar | 73b8b0a | 2021-08-01 14:52:32 +0200 | [diff] [blame] | 102 | au BufReadPost *.xml { |
| 103 | setlocal matchpairs+=<:> |
| 104 | /<start |
| 105 | } |
| 106 | |
Yegappan Lakshmanan | 1755a91 | 2022-05-19 10:31:47 +0100 | [diff] [blame] | 107 | The |autocmd_add()| function can be used to add a list of autocmds and autocmd |
Yegappan Lakshmanan | 971f682 | 2022-05-24 11:40:11 +0100 | [diff] [blame] | 108 | groups from a Vim script. It is preferred if you have anything that would |
| 109 | require using `:execute` with `:autocmd`. |
Yegappan Lakshmanan | 1755a91 | 2022-05-19 10:31:47 +0100 | [diff] [blame] | 110 | |
Bram Moolenaar | e99e844 | 2016-07-26 20:43:40 +0200 | [diff] [blame] | 111 | Note: The ":autocmd" command can only be followed by another command when the |
Bram Moolenaar | 88a4205 | 2021-11-21 21:13:36 +0000 | [diff] [blame] | 112 | '|' appears where the pattern is expected. This works: > |
Bram Moolenaar | e99e844 | 2016-07-26 20:43:40 +0200 | [diff] [blame] | 113 | :augroup mine | au! BufRead | augroup END |
| 114 | But this sees "augroup" as part of the defined command: > |
Bram Moolenaar | b0d45e7 | 2017-11-05 18:19:24 +0100 | [diff] [blame] | 115 | :augroup mine | au! BufRead * | augroup END |
Bram Moolenaar | e99e844 | 2016-07-26 20:43:40 +0200 | [diff] [blame] | 116 | :augroup mine | au BufRead * set tw=70 | augroup END |
Bram Moolenaar | b0d45e7 | 2017-11-05 18:19:24 +0100 | [diff] [blame] | 117 | Instead you can put the group name into the command: > |
| 118 | :au! mine BufRead * |
| 119 | :au mine BufRead * set tw=70 |
| 120 | Or use `:execute`: > |
| 121 | :augroup mine | exe "au! BufRead *" | augroup END |
| 122 | :augroup mine | exe "au BufRead * set tw=70" | augroup END |
Bram Moolenaar | e99e844 | 2016-07-26 20:43:40 +0200 | [diff] [blame] | 123 | |
Bram Moolenaar | 75ab590 | 2022-04-18 15:36:40 +0100 | [diff] [blame] | 124 | < *autocmd-expand* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 125 | Note that special characters (e.g., "%", "<cword>") in the ":autocmd" |
| 126 | arguments are not expanded when the autocommand is defined. These will be |
| 127 | expanded when the Event is recognized, and the {cmd} is executed. The only |
| 128 | exception is that "<sfile>" is expanded when the autocmd is defined. Example: |
| 129 | > |
| 130 | :au BufNewFile,BufRead *.html so <sfile>:h/html.vim |
| 131 | |
| 132 | Here Vim expands <sfile> to the name of the file containing this line. |
zeertzjq | 476b65e | 2025-06-19 19:40:51 +0200 | [diff] [blame] | 133 | However, <sfile> works differently in a function, in which case it's better to |
| 134 | use `:execute` with <script> to achieve the same purpose: |
| 135 | > |
| 136 | :exe $'au BufNewFile,BufRead *.html so {expand("<script>:h")}/html.vim' |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 137 | |
Bram Moolenaar | 2ec618c | 2016-10-01 14:47:05 +0200 | [diff] [blame] | 138 | `:autocmd` adds to the list of autocommands regardless of whether they are |
| 139 | already present. When your .vimrc file is sourced twice, the autocommands |
| 140 | will appear twice. To avoid this, define your autocommands in a group, so |
| 141 | that you can easily clear them: > |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 142 | |
Bram Moolenaar | 2ec618c | 2016-10-01 14:47:05 +0200 | [diff] [blame] | 143 | augroup vimrc |
Bram Moolenaar | 98ef233 | 2018-03-18 14:44:37 +0100 | [diff] [blame] | 144 | " Remove all vimrc autocommands |
| 145 | autocmd! |
Bram Moolenaar | 2ec618c | 2016-10-01 14:47:05 +0200 | [diff] [blame] | 146 | au BufNewFile,BufRead *.html so <sfile>:h/html.vim |
| 147 | augroup END |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 148 | |
| 149 | If you don't want to remove all autocommands, you can instead use a variable |
| 150 | to ensure that Vim includes the autocommands only once: > |
| 151 | |
| 152 | :if !exists("autocommands_loaded") |
| 153 | : let autocommands_loaded = 1 |
| 154 | : au ... |
| 155 | :endif |
| 156 | |
| 157 | When the [group] argument is not given, Vim uses the current group (as defined |
| 158 | with ":augroup"); otherwise, Vim uses the group defined with [group]. Note |
| 159 | that [group] must have been defined before. You cannot define a new group |
| 160 | with ":au group ..."; use ":augroup" for that. |
| 161 | |
| 162 | While testing autocommands, you might find the 'verbose' option to be useful: > |
| 163 | :set verbose=9 |
| 164 | This setting makes Vim echo the autocommands as it executes them. |
| 165 | |
| 166 | When defining an autocommand in a script, it will be able to call functions |
| 167 | local to the script and use mappings local to the script. When the event is |
| 168 | triggered and the command executed, it will run in the context of the script |
| 169 | it was defined in. This matters if |<SID>| is used in a command. |
| 170 | |
Bram Moolenaar | 446cb83 | 2008-06-24 21:56:24 +0000 | [diff] [blame] | 171 | When executing the commands, the message from one command overwrites a |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 172 | previous message. This is different from when executing the commands |
| 173 | manually. Mostly the screen will not scroll up, thus there is no hit-enter |
| 174 | prompt. When one command outputs two messages this can happen anyway. |
| 175 | |
| 176 | ============================================================================== |
| 177 | 3. Removing autocommands *autocmd-remove* |
| 178 | |
Yegappan Lakshmanan | 1755a91 | 2022-05-19 10:31:47 +0100 | [diff] [blame] | 179 | In addition to the below described commands, the |autocmd_delete()| function can |
| 180 | be used to remove a list of autocmds and autocmd groups from a Vim script. |
| 181 | |
Bram Moolenaar | fd31be2 | 2022-01-16 14:46:06 +0000 | [diff] [blame] | 182 | :au[tocmd]! [group] {event} {aupat} [++once] [++nested] {cmd} |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 183 | Remove all autocommands associated with {event} and |
Bram Moolenaar | fd31be2 | 2022-01-16 14:46:06 +0000 | [diff] [blame] | 184 | {aupat}, and add the command {cmd}. |
Bram Moolenaar | eb93f3f | 2019-04-04 15:04:56 +0200 | [diff] [blame] | 185 | See |autocmd-once| for [++once]. |
| 186 | See |autocmd-nested| for [++nested]. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 187 | |
Bram Moolenaar | fd31be2 | 2022-01-16 14:46:06 +0000 | [diff] [blame] | 188 | :au[tocmd]! [group] {event} {aupat} |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 189 | Remove all autocommands associated with {event} and |
Bram Moolenaar | fd31be2 | 2022-01-16 14:46:06 +0000 | [diff] [blame] | 190 | {aupat}. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 191 | |
Bram Moolenaar | fd31be2 | 2022-01-16 14:46:06 +0000 | [diff] [blame] | 192 | :au[tocmd]! [group] * {aupat} |
| 193 | Remove all autocommands associated with {aupat} for |
| 194 | all events. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 195 | |
| 196 | :au[tocmd]! [group] {event} |
| 197 | Remove ALL autocommands for {event}. |
Bram Moolenaar | 2ec618c | 2016-10-01 14:47:05 +0200 | [diff] [blame] | 198 | Warning: You should not do this without a group for |
| 199 | |BufRead| and other common events, it can break |
| 200 | plugins, syntax highlighting, etc. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 201 | |
| 202 | :au[tocmd]! [group] Remove ALL autocommands. |
Bram Moolenaar | 98ef233 | 2018-03-18 14:44:37 +0100 | [diff] [blame] | 203 | Note: a quote will be seen as argument to the :autocmd |
| 204 | and won't start a comment. |
Bram Moolenaar | 2ec618c | 2016-10-01 14:47:05 +0200 | [diff] [blame] | 205 | Warning: You should normally not do this without a |
| 206 | group, it breaks plugins, syntax highlighting, etc. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 207 | |
| 208 | When the [group] argument is not given, Vim uses the current group (as defined |
| 209 | with ":augroup"); otherwise, Vim uses the group defined with [group]. |
| 210 | |
| 211 | ============================================================================== |
| 212 | 4. Listing autocommands *autocmd-list* |
| 213 | |
Bram Moolenaar | fd31be2 | 2022-01-16 14:46:06 +0000 | [diff] [blame] | 214 | :au[tocmd] [group] {event} {aupat} |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 215 | Show the autocommands associated with {event} and |
Bram Moolenaar | fd31be2 | 2022-01-16 14:46:06 +0000 | [diff] [blame] | 216 | {aupat}. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 217 | |
Bram Moolenaar | fd31be2 | 2022-01-16 14:46:06 +0000 | [diff] [blame] | 218 | :au[tocmd] [group] * {aupat} |
| 219 | Show the autocommands associated with {aupat} for all |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 220 | events. |
| 221 | |
| 222 | :au[tocmd] [group] {event} |
| 223 | Show all autocommands for {event}. |
| 224 | |
| 225 | :au[tocmd] [group] Show all autocommands. |
| 226 | |
| 227 | If you provide the [group] argument, Vim lists only the autocommands for |
| 228 | [group]; otherwise, Vim lists the autocommands for ALL groups. Note that this |
| 229 | argument behavior differs from that for defining and removing autocommands. |
| 230 | |
Bram Moolenaar | b5bf5b8 | 2004-12-24 14:35:23 +0000 | [diff] [blame] | 231 | In order to list buffer-local autocommands, use a pattern in the form <buffer> |
| 232 | or <buffer=N>. See |autocmd-buflocal|. |
| 233 | |
Yegappan Lakshmanan | 1755a91 | 2022-05-19 10:31:47 +0100 | [diff] [blame] | 234 | The |autocmd_get()| function can be used from a Vim script to get a list of |
| 235 | autocmds. |
| 236 | |
Bram Moolenaar | ac6e65f | 2005-08-29 22:25:38 +0000 | [diff] [blame] | 237 | *:autocmd-verbose* |
| 238 | When 'verbose' is non-zero, listing an autocommand will also display where it |
| 239 | was last defined. Example: > |
| 240 | |
| 241 | :verbose autocmd BufEnter |
| 242 | FileExplorer BufEnter |
Bram Moolenaar | c9b4b05 | 2006-04-30 18:54:39 +0000 | [diff] [blame] | 243 | * call s:LocalBrowse(expand("<amatch>")) |
Bram Moolenaar | ac6e65f | 2005-08-29 22:25:38 +0000 | [diff] [blame] | 244 | Last set from /usr/share/vim/vim-7.0/plugin/NetrwPlugin.vim |
| 245 | < |
| 246 | See |:verbose-cmd| for more information. |
| 247 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 248 | ============================================================================== |
| 249 | 5. Events *autocmd-events* *E215* *E216* |
| 250 | |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 251 | You can specify a comma-separated list of event names. No white space can be |
| 252 | used in this list. The command applies to all the events in the list. |
| 253 | |
| 254 | For READING FILES there are four kinds of events possible: |
| 255 | BufNewFile starting to edit a non-existent file |
| 256 | BufReadPre BufReadPost starting to edit an existing file |
| 257 | FilterReadPre FilterReadPost read the temp file with filter output |
| 258 | FileReadPre FileReadPost any other file read |
| 259 | Vim uses only one of these four kinds when reading a file. The "Pre" and |
| 260 | "Post" events are both triggered, before and after reading the file. |
| 261 | |
| 262 | Note that the autocommands for the *ReadPre events and all the Filter events |
| 263 | are not allowed to change the current buffer (you will get an error message if |
| 264 | this happens). This is to prevent the file to be read into the wrong buffer. |
| 265 | |
| 266 | Note that the 'modified' flag is reset AFTER executing the BufReadPost |
| 267 | and BufNewFile autocommands. But when the 'modified' option was set by the |
| 268 | autocommands, this doesn't happen. |
| 269 | |
| 270 | You can use the 'eventignore' option to ignore a number of events or all |
| 271 | events. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 272 | *autocommand-events* *{event}* |
| 273 | Vim recognizes the following events. Vim ignores the case of event names |
| 274 | (e.g., you can use "BUFread" or "bufread" instead of "BufRead"). |
| 275 | |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 276 | First an overview by function with a short explanation. Then the list |
Bram Moolenaar | 551dbcc | 2006-04-25 22:13:59 +0000 | [diff] [blame] | 277 | alphabetically with full explanations |autocmd-events-abc|. |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 278 | |
| 279 | Name triggered by ~ |
| 280 | |
| 281 | Reading |
| 282 | |BufNewFile| starting to edit a file that doesn't exist |
| 283 | |BufReadPre| starting to edit a new buffer, before reading the file |
| 284 | |BufRead| starting to edit a new buffer, after reading the file |
| 285 | |BufReadPost| starting to edit a new buffer, after reading the file |
| 286 | |BufReadCmd| before starting to edit a new buffer |Cmd-event| |
| 287 | |
| 288 | |FileReadPre| before reading a file with a ":read" command |
| 289 | |FileReadPost| after reading a file with a ":read" command |
Bram Moolenaar | 551dbcc | 2006-04-25 22:13:59 +0000 | [diff] [blame] | 290 | |FileReadCmd| before reading a file with a ":read" command |Cmd-event| |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 291 | |
| 292 | |FilterReadPre| before reading a file from a filter command |
| 293 | |FilterReadPost| after reading a file from a filter command |
| 294 | |
| 295 | |StdinReadPre| before reading from stdin into the buffer |
| 296 | |StdinReadPost| After reading from the stdin into the buffer |
| 297 | |
| 298 | Writing |
| 299 | |BufWrite| starting to write the whole buffer to a file |
| 300 | |BufWritePre| starting to write the whole buffer to a file |
| 301 | |BufWritePost| after writing the whole buffer to a file |
| 302 | |BufWriteCmd| before writing the whole buffer to a file |Cmd-event| |
| 303 | |
| 304 | |FileWritePre| starting to write part of a buffer to a file |
| 305 | |FileWritePost| after writing part of a buffer to a file |
| 306 | |FileWriteCmd| before writing part of a buffer to a file |Cmd-event| |
| 307 | |
| 308 | |FileAppendPre| starting to append to a file |
| 309 | |FileAppendPost| after appending to a file |
| 310 | |FileAppendCmd| before appending to a file |Cmd-event| |
| 311 | |
| 312 | |FilterWritePre| starting to write a file for a filter command or diff |
| 313 | |FilterWritePost| after writing a file for a filter command or diff |
| 314 | |
| 315 | Buffers |
| 316 | |BufAdd| just after adding a buffer to the buffer list |
| 317 | |BufCreate| just after adding a buffer to the buffer list |
| 318 | |BufDelete| before deleting a buffer from the buffer list |
| 319 | |BufWipeout| before completely deleting a buffer |
| 320 | |
| 321 | |BufFilePre| before changing the name of the current buffer |
| 322 | |BufFilePost| after changing the name of the current buffer |
| 323 | |
| 324 | |BufEnter| after entering a buffer |
| 325 | |BufLeave| before leaving to another buffer |
| 326 | |BufWinEnter| after a buffer is displayed in a window |
| 327 | |BufWinLeave| before a buffer is removed from a window |
| 328 | |
| 329 | |BufUnload| before unloading a buffer |
Bram Moolenaar | cb80aa2 | 2020-10-26 21:12:46 +0100 | [diff] [blame] | 330 | |BufHidden| just before a buffer becomes hidden |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 331 | |BufNew| just after creating a new buffer |
| 332 | |
| 333 | |SwapExists| detected an existing swap file |
| 334 | |
| 335 | Options |
| 336 | |FileType| when the 'filetype' option has been set |
| 337 | |Syntax| when the 'syntax' option has been set |
| 338 | |EncodingChanged| after the 'encoding' option has been changed |
| 339 | |TermChanged| after the value of 'term' has changed |
Bram Moolenaar | 5374430 | 2015-07-17 17:38:22 +0200 | [diff] [blame] | 340 | |OptionSet| after setting any option |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 341 | |
| 342 | Startup and exit |
| 343 | |VimEnter| after doing all the startup stuff |
| 344 | |GUIEnter| after starting the GUI successfully |
Bram Moolenaar | d09acef | 2012-09-21 14:54:30 +0200 | [diff] [blame] | 345 | |GUIFailed| after starting the GUI failed |
Bram Moolenaar | d7afed3 | 2007-05-06 13:26:41 +0000 | [diff] [blame] | 346 | |TermResponse| after the terminal response to |t_RV| is received |
Danek Duvall | d7d5603 | 2024-01-14 20:19:59 +0100 | [diff] [blame] | 347 | |TermResponseAll| after the terminal response to |t_RV| and others is received |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 348 | |
Bram Moolenaar | 12a96de | 2018-03-11 14:44:18 +0100 | [diff] [blame] | 349 | |QuitPre| when using `:quit`, before deciding whether to exit |
| 350 | |ExitPre| when using a command that may make Vim exit |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 351 | |VimLeavePre| before exiting Vim, before writing the viminfo file |
| 352 | |VimLeave| before exiting Vim, after writing the viminfo file |
| 353 | |
Bram Moolenaar | 100118c | 2020-12-11 19:30:34 +0100 | [diff] [blame] | 354 | |VimSuspend| when suspending Vim |
| 355 | |VimResume| when Vim is resumed after being suspended |
| 356 | |
Bram Moolenaar | 28ed4df | 2019-10-26 16:21:40 +0200 | [diff] [blame] | 357 | Terminal |
| 358 | |TerminalOpen| after a terminal buffer was created |
| 359 | |TerminalWinOpen| after a terminal buffer was created in a new window |
| 360 | |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 361 | Various |
| 362 | |FileChangedShell| Vim notices that a file changed since editing started |
Bram Moolenaar | 7d47b6e | 2006-03-15 22:59:18 +0000 | [diff] [blame] | 363 | |FileChangedShellPost| After handling a file changed since editing started |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 364 | |FileChangedRO| before making the first change to a read-only file |
| 365 | |
Bram Moolenaar | 2c64ca1 | 2018-10-19 16:22:31 +0200 | [diff] [blame] | 366 | |DiffUpdated| after diffs have been updated |
Bram Moolenaar | 28e8f73 | 2022-02-09 12:58:20 +0000 | [diff] [blame] | 367 | |DirChangedPre| before the working directory will change |
Bram Moolenaar | b7407d3 | 2018-02-03 17:36:27 +0100 | [diff] [blame] | 368 | |DirChanged| after the working directory has changed |
| 369 | |
Bram Moolenaar | a94bc43 | 2006-03-10 21:42:59 +0000 | [diff] [blame] | 370 | |ShellCmdPost| after executing a shell command |
| 371 | |ShellFilterPost| after filtering with a shell command |
| 372 | |
Bram Moolenaar | d500516 | 2014-08-22 23:05:54 +0200 | [diff] [blame] | 373 | |CmdUndefined| a user command is used but it isn't defined |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 374 | |FuncUndefined| a user function is used but it isn't defined |
Bram Moolenaar | afeb4fa | 2006-02-01 21:51:12 +0000 | [diff] [blame] | 375 | |SpellFileMissing| a spell file is used but it can't be found |
Bram Moolenaar | 1f35bf9 | 2006-03-07 22:38:47 +0000 | [diff] [blame] | 376 | |SourcePre| before sourcing a Vim script |
Bram Moolenaar | 2a953fc | 2019-01-26 17:41:47 +0100 | [diff] [blame] | 377 | |SourcePost| after sourcing a Vim script |
Bram Moolenaar | 8dd1aa5 | 2007-01-16 20:33:19 +0000 | [diff] [blame] | 378 | |SourceCmd| before sourcing a Vim script |Cmd-event| |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 379 | |
Bram Moolenaar | 7d47b6e | 2006-03-15 22:59:18 +0000 | [diff] [blame] | 380 | |VimResized| after the Vim window size changed |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 381 | |FocusGained| Vim got input focus |
| 382 | |FocusLost| Vim lost input focus |
| 383 | |CursorHold| the user doesn't press a key for a while |
Bram Moolenaar | 754b560 | 2006-02-09 23:53:20 +0000 | [diff] [blame] | 384 | |CursorHoldI| the user doesn't press a key for a while in Insert mode |
| 385 | |CursorMoved| the cursor was moved in Normal mode |
Shougo Matsushita | d095214 | 2024-06-20 22:05:16 +0200 | [diff] [blame] | 386 | |CursorMovedC| the cursor was moved in the |Command-line| |
Bram Moolenaar | 754b560 | 2006-02-09 23:53:20 +0000 | [diff] [blame] | 387 | |CursorMovedI| the cursor was moved in Insert mode |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 388 | |
Sergey Vlasov | 1f47db7 | 2024-01-25 23:07:00 +0100 | [diff] [blame] | 389 | |WinNewPre| before creating a new window |
Bram Moolenaar | c917da4 | 2016-07-19 22:31:36 +0200 | [diff] [blame] | 390 | |WinNew| after creating a new window |
Bram Moolenaar | 12c11d5 | 2016-07-19 23:13:03 +0200 | [diff] [blame] | 391 | |TabNew| after creating a new tab page |
naohiro ono | 23beefe | 2021-11-13 12:38:49 +0000 | [diff] [blame] | 392 | |WinClosed| after closing a window |
Bram Moolenaar | 12c11d5 | 2016-07-19 23:13:03 +0200 | [diff] [blame] | 393 | |TabClosed| after closing a tab page |
Jim Zhou | 5606ca5 | 2025-03-13 21:58:25 +0100 | [diff] [blame] | 394 | |TabClosedPre| before closing a tab page |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 395 | |WinEnter| after entering another window |
| 396 | |WinLeave| before leaving a window |
Bram Moolenaar | faa959a | 2006-02-20 21:37:40 +0000 | [diff] [blame] | 397 | |TabEnter| after entering another tab page |
| 398 | |TabLeave| before leaving a tab page |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 399 | |CmdwinEnter| after entering the command-line window |
| 400 | |CmdwinLeave| before leaving the command-line window |
| 401 | |
Bram Moolenaar | b5b7562 | 2018-03-09 22:22:21 +0100 | [diff] [blame] | 402 | |CmdlineChanged| after a change was made to the command-line text |
| 403 | |CmdlineEnter| after the cursor moves to the command line |
| 404 | |CmdlineLeave| before the cursor leaves the command line |
Girish Palya | 92f68e2 | 2025-04-21 11:12:41 +0200 | [diff] [blame] | 405 | |CmdlineLeavePre| before preparing to leave the command line |
Bram Moolenaar | b5b7562 | 2018-03-09 22:22:21 +0100 | [diff] [blame] | 406 | |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 407 | |InsertEnter| starting Insert mode |
| 408 | |InsertChange| when typing <Insert> while in Insert or Replace mode |
| 409 | |InsertLeave| when leaving Insert mode |
Bram Moolenaar | 938ae28 | 2023-02-20 20:44:55 +0000 | [diff] [blame] | 410 | |InsertLeavePre| just before leaving Insert mode |
Bram Moolenaar | e659c95 | 2011-05-19 17:25:41 +0200 | [diff] [blame] | 411 | |InsertCharPre| when a character was typed in Insert mode, before |
| 412 | inserting it |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 413 | |
=?UTF-8?q?Magnus=20Gro=C3=9F?= | f1e8876 | 2021-09-12 13:39:55 +0200 | [diff] [blame] | 414 | |ModeChanged| after changing the mode |
| 415 | |
Bram Moolenaar | dfb1841 | 2013-12-11 18:53:29 +0100 | [diff] [blame] | 416 | |TextChanged| after a change was made to the text in Normal mode |
| 417 | |TextChangedI| after a change was made to the text in Insert mode |
Bram Moolenaar | 5a09343 | 2018-02-10 18:15:19 +0100 | [diff] [blame] | 418 | when popup menu is not visible |
| 419 | |TextChangedP| after a change was made to the text in Insert mode |
| 420 | when popup menu visible |
Shougo Matsushita | 4ccaedf | 2022-10-15 11:48:00 +0100 | [diff] [blame] | 421 | |TextChangedT| after a change was made to the text in Terminal mode |
Bram Moolenaar | b477af2 | 2018-07-15 20:20:18 +0200 | [diff] [blame] | 422 | |TextYankPost| after text has been yanked or deleted |
Bram Moolenaar | dfb1841 | 2013-12-11 18:53:29 +0100 | [diff] [blame] | 423 | |
Bram Moolenaar | 8aeec40 | 2019-09-15 23:02:04 +0200 | [diff] [blame] | 424 | |SafeState| nothing pending, going to wait for the user to type a |
| 425 | character |
Bram Moolenaar | 69198cb | 2019-09-16 21:58:13 +0200 | [diff] [blame] | 426 | |SafeStateAgain| repeated SafeState |
Bram Moolenaar | 8aeec40 | 2019-09-15 23:02:04 +0200 | [diff] [blame] | 427 | |
Bram Moolenaar | 15142e2 | 2018-04-30 22:19:58 +0200 | [diff] [blame] | 428 | |ColorSchemePre| before loading a color scheme |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 429 | |ColorScheme| after loading a color scheme |
| 430 | |
| 431 | |RemoteReply| a reply from a server Vim was received |
| 432 | |
| 433 | |QuickFixCmdPre| before a quickfix command is run |
| 434 | |QuickFixCmdPost| after a quickfix command is run |
| 435 | |
| 436 | |SessionLoadPost| after loading a session file |
| 437 | |
h-east | 53753f6 | 2024-05-05 18:42:31 +0200 | [diff] [blame] | 438 | |SessionWritePost| after writing the session file using |
| 439 | the |:mksession| command |
Colin Kennedy | e5f2280 | 2024-03-26 18:20:16 +0100 | [diff] [blame] | 440 | |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 441 | |MenuPopup| just before showing the popup menu |
Bram Moolenaar | d7f246c | 2019-04-08 18:15:41 +0200 | [diff] [blame] | 442 | |CompleteChanged| after Insert mode completion menu changed |
Bram Moolenaar | 3f169ce | 2020-01-26 22:43:31 +0100 | [diff] [blame] | 443 | |CompleteDonePre| after Insert mode completion is done, before clearing |
| 444 | info |
| 445 | |CompleteDone| after Insert mode completion is done, after clearing |
| 446 | info |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 447 | |
Shougo Matsushita | 8367884 | 2024-07-11 22:05:12 +0200 | [diff] [blame] | 448 | |KeyInputPre| just before a key is processed |
| 449 | |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 450 | |User| to be used in combination with ":doautocmd" |
Bram Moolenaar | be5ee86 | 2020-06-10 20:56:58 +0200 | [diff] [blame] | 451 | |SigUSR1| after the SIGUSR1 signal has been detected |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 452 | |
LemonBoy | 0937182 | 2022-04-08 15:18:45 +0100 | [diff] [blame] | 453 | |WinScrolled| after scrolling or resizing a window |
| 454 | |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 455 | |
| 456 | The alphabetical list of autocommand events: *autocmd-events-abc* |
| 457 | |
| 458 | *BufCreate* *BufAdd* |
| 459 | BufAdd or BufCreate Just after creating a new buffer which is |
| 460 | added to the buffer list, or adding a buffer |
| 461 | to the buffer list. |
| 462 | Also used just after a buffer in the buffer |
| 463 | list has been renamed. |
Bram Moolenaar | 469bdbd | 2019-12-11 23:05:48 +0100 | [diff] [blame] | 464 | Not triggered for the initial buffers created |
| 465 | during startup. |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 466 | The BufCreate event is for historic reasons. |
| 467 | NOTE: When this autocommand is executed, the |
| 468 | current buffer "%" may be different from the |
| 469 | buffer being created "<afile>". |
| 470 | *BufDelete* |
| 471 | BufDelete Before deleting a buffer from the buffer list. |
| 472 | The BufUnload may be called first (if the |
| 473 | buffer was loaded). |
| 474 | Also used just before a buffer in the buffer |
| 475 | list is renamed. |
| 476 | NOTE: When this autocommand is executed, the |
| 477 | current buffer "%" may be different from the |
Bram Moolenaar | 446cb83 | 2008-06-24 21:56:24 +0000 | [diff] [blame] | 478 | buffer being deleted "<afile>" and "<abuf>". |
Bram Moolenaar | b849e71 | 2009-06-24 15:51:37 +0000 | [diff] [blame] | 479 | Don't change to another buffer, it will cause |
| 480 | problems. |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 481 | *BufEnter* |
| 482 | BufEnter After entering a buffer. Useful for setting |
| 483 | options for a file type. Also executed when |
| 484 | starting to edit a buffer, after the |
| 485 | BufReadPost autocommands. |
| 486 | *BufFilePost* |
| 487 | BufFilePost After changing the name of the current buffer |
| 488 | with the ":file" or ":saveas" command. |
Bram Moolenaar | 4770d09 | 2006-01-12 23:22:24 +0000 | [diff] [blame] | 489 | *BufFilePre* |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 490 | BufFilePre Before changing the name of the current buffer |
| 491 | with the ":file" or ":saveas" command. |
| 492 | *BufHidden* |
Bram Moolenaar | 790c18b | 2019-07-04 17:22:06 +0200 | [diff] [blame] | 493 | BufHidden Just before a buffer becomes hidden. That is, |
| 494 | when there are no longer windows that show |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 495 | the buffer, but the buffer is not unloaded or |
| 496 | deleted. Not used for ":qa" or ":q" when |
| 497 | exiting Vim. |
| 498 | NOTE: When this autocommand is executed, the |
| 499 | current buffer "%" may be different from the |
| 500 | buffer being unloaded "<afile>". |
| 501 | *BufLeave* |
| 502 | BufLeave Before leaving to another buffer. Also when |
| 503 | leaving or closing the current window and the |
| 504 | new current window is not for the same buffer. |
| 505 | Not used for ":qa" or ":q" when exiting Vim. |
| 506 | *BufNew* |
| 507 | BufNew Just after creating a new buffer. Also used |
| 508 | just after a buffer has been renamed. When |
| 509 | the buffer is added to the buffer list BufAdd |
| 510 | will be triggered too. |
| 511 | NOTE: When this autocommand is executed, the |
| 512 | current buffer "%" may be different from the |
| 513 | buffer being created "<afile>". |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 514 | *BufNewFile* |
| 515 | BufNewFile When starting to edit a file that doesn't |
| 516 | exist. Can be used to read in a skeleton |
| 517 | file. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 518 | *BufRead* *BufReadPost* |
| 519 | BufRead or BufReadPost When starting to edit a new buffer, after |
| 520 | reading the file into the buffer, before |
| 521 | executing the modelines. See |BufWinEnter| |
| 522 | for when you need to do something after |
| 523 | processing the modelines. |
Bram Moolenaar | 75ab590 | 2022-04-18 15:36:40 +0100 | [diff] [blame] | 524 | Also triggered: |
| 525 | - when writing an unnamed buffer in a way that |
| 526 | the buffer gets a name |
| 527 | - after successfully recovering a file |
| 528 | - for the filetypedetect group when executing |
| 529 | ":filetype detect" |
| 530 | Not triggered: |
| 531 | - for the `:read file` command |
| 532 | - when the file doesn't exist |
Bram Moolenaar | 4770d09 | 2006-01-12 23:22:24 +0000 | [diff] [blame] | 533 | *BufReadCmd* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 534 | BufReadCmd Before starting to edit a new buffer. Should |
| 535 | read the file into the buffer. |Cmd-event| |
Bram Moolenaar | 4770d09 | 2006-01-12 23:22:24 +0000 | [diff] [blame] | 536 | *BufReadPre* *E200* *E201* |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 537 | BufReadPre When starting to edit a new buffer, before |
| 538 | reading the file into the buffer. Not used |
| 539 | if the file doesn't exist. |
| 540 | *BufUnload* |
| 541 | BufUnload Before unloading a buffer. This is when the |
| 542 | text in the buffer is going to be freed. This |
| 543 | may be after a BufWritePost and before a |
| 544 | BufDelete. Also used for all buffers that are |
| 545 | loaded when Vim is going to exit. |
| 546 | NOTE: When this autocommand is executed, the |
| 547 | current buffer "%" may be different from the |
| 548 | buffer being unloaded "<afile>". |
Bram Moolenaar | 64d8e25 | 2016-09-06 22:12:34 +0200 | [diff] [blame] | 549 | Don't change to another buffer or window, it |
| 550 | will cause problems! |
Bram Moolenaar | 0e1e25f | 2010-05-28 21:07:08 +0200 | [diff] [blame] | 551 | When exiting and v:dying is 2 or more this |
| 552 | event is not triggered. |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 553 | *BufWinEnter* |
| 554 | BufWinEnter After a buffer is displayed in a window. This |
| 555 | can be when the buffer is loaded (after |
Bram Moolenaar | 446cb83 | 2008-06-24 21:56:24 +0000 | [diff] [blame] | 556 | processing the modelines) or when a hidden |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 557 | buffer is displayed in a window (and is no |
Bram Moolenaar | 446cb83 | 2008-06-24 21:56:24 +0000 | [diff] [blame] | 558 | longer hidden). |
| 559 | Does not happen for |:split| without |
| 560 | arguments, since you keep editing the same |
| 561 | buffer, or ":split" with a file that's already |
Bram Moolenaar | c236c16 | 2008-07-13 17:41:49 +0000 | [diff] [blame] | 562 | open in a window, because it re-uses an |
| 563 | existing buffer. But it does happen for a |
| 564 | ":split" with the name of the current buffer, |
| 565 | since it reloads that buffer. |
Bram Moolenaar | 606cb8b | 2018-05-03 20:40:20 +0200 | [diff] [blame] | 566 | Does not happen for a terminal window, because |
| 567 | it starts in Terminal-Job mode and Normal mode |
| 568 | commands won't work. Use |TerminalOpen| instead. |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 569 | *BufWinLeave* |
| 570 | BufWinLeave Before a buffer is removed from a window. |
| 571 | Not when it's still visible in another window. |
| 572 | Also triggered when exiting. It's triggered |
| 573 | before BufUnload or BufHidden. |
| 574 | NOTE: When this autocommand is executed, the |
| 575 | current buffer "%" may be different from the |
| 576 | buffer being unloaded "<afile>". |
Bram Moolenaar | 0e1e25f | 2010-05-28 21:07:08 +0200 | [diff] [blame] | 577 | When exiting and v:dying is 2 or more this |
| 578 | event is not triggered. |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 579 | *BufWipeout* |
| 580 | BufWipeout Before completely deleting a buffer. The |
| 581 | BufUnload and BufDelete events may be called |
| 582 | first (if the buffer was loaded and was in the |
| 583 | buffer list). Also used just before a buffer |
| 584 | is renamed (also when it's not in the buffer |
| 585 | list). |
| 586 | NOTE: When this autocommand is executed, the |
| 587 | current buffer "%" may be different from the |
| 588 | buffer being deleted "<afile>". |
Bram Moolenaar | b849e71 | 2009-06-24 15:51:37 +0000 | [diff] [blame] | 589 | Don't change to another buffer, it will cause |
| 590 | problems. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 591 | *BufWrite* *BufWritePre* |
| 592 | BufWrite or BufWritePre Before writing the whole buffer to a file. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 593 | *BufWriteCmd* |
| 594 | BufWriteCmd Before writing the whole buffer to a file. |
| 595 | Should do the writing of the file and reset |
Bram Moolenaar | 1cd871b | 2004-12-19 22:46:22 +0000 | [diff] [blame] | 596 | 'modified' if successful, unless '+' is in |
| 597 | 'cpo' and writing to another file |cpo-+|. |
| 598 | The buffer contents should not be changed. |
Bram Moolenaar | 5302d9e | 2011-09-14 17:55:08 +0200 | [diff] [blame] | 599 | When the command resets 'modified' the undo |
| 600 | information is adjusted to mark older undo |
Christian Brabandt | df68419 | 2025-04-03 12:33:02 +0200 | [diff] [blame] | 601 | states as 'modified', like |:write| does. Use |
| 602 | the |'[| and |']| marks for the range of lines. |
Bram Moolenaar | 1cd871b | 2004-12-19 22:46:22 +0000 | [diff] [blame] | 603 | |Cmd-event| |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 604 | *BufWritePost* |
| 605 | BufWritePost After writing the whole buffer to a file |
| 606 | (should undo the commands for BufWritePre). |
Bram Moolenaar | d500516 | 2014-08-22 23:05:54 +0200 | [diff] [blame] | 607 | *CmdUndefined* |
| 608 | CmdUndefined When a user command is used but it isn't |
| 609 | defined. Useful for defining a command only |
| 610 | when it's used. The pattern is matched |
| 611 | against the command name. Both <amatch> and |
| 612 | <afile> are set to the name of the command. |
zeertzjq | af05694 | 2025-03-08 16:45:20 +0100 | [diff] [blame] | 613 | This is triggered even when inside an |
| 614 | autocommand defined without |autocmd-nested|. |
Bram Moolenaar | d500516 | 2014-08-22 23:05:54 +0200 | [diff] [blame] | 615 | NOTE: Autocompletion won't work until the |
| 616 | command is defined. An alternative is to |
| 617 | always define the user command and have it |
| 618 | invoke an autoloaded function. See |autoload|. |
Bram Moolenaar | 153b704 | 2018-01-31 15:48:32 +0100 | [diff] [blame] | 619 | *CmdlineChanged* |
Bram Moolenaar | b5b7562 | 2018-03-09 22:22:21 +0100 | [diff] [blame] | 620 | CmdlineChanged After a change was made to the text in the |
| 621 | command line. Be careful not to mess up |
| 622 | the command line, it may cause Vim to lock up. |
Bram Moolenaar | 153b704 | 2018-01-31 15:48:32 +0100 | [diff] [blame] | 623 | <afile> is set to a single character, |
| 624 | indicating the type of command-line. |
| 625 | |cmdwin-char| |
Bram Moolenaar | fafcf0d | 2017-10-19 18:35:51 +0200 | [diff] [blame] | 626 | *CmdlineEnter* |
| 627 | CmdlineEnter After moving the cursor to the command line, |
| 628 | where the user can type a command or search |
Bram Moolenaar | 957cf67 | 2020-11-12 14:21:06 +0100 | [diff] [blame] | 629 | string; including non-interactive use of ":" |
| 630 | in a mapping, but not when using |<Cmd>|. |
Bram Moolenaar | 938ae28 | 2023-02-20 20:44:55 +0000 | [diff] [blame] | 631 | The pattern is matched against the character |
| 632 | representing the type of command-line. |
| 633 | |cmdwin-char| |
Bram Moolenaar | fafcf0d | 2017-10-19 18:35:51 +0200 | [diff] [blame] | 634 | <afile> is set to a single character, |
| 635 | indicating the type of command-line. |
Bram Moolenaar | fafcf0d | 2017-10-19 18:35:51 +0200 | [diff] [blame] | 636 | *CmdlineLeave* |
Bram Moolenaar | 957cf67 | 2020-11-12 14:21:06 +0100 | [diff] [blame] | 637 | CmdlineLeave Before leaving the command line; including |
| 638 | non-interactive use of ":" in a mapping, but |
| 639 | not when using |<Cmd>|. |
Bram Moolenaar | 01164a6 | 2017-11-02 22:58:42 +0100 | [diff] [blame] | 640 | Also when abandoning the command line, after |
| 641 | typing CTRL-C or <Esc>. |
| 642 | When the commands result in an error the |
| 643 | command line is still executed. |
Bram Moolenaar | fafcf0d | 2017-10-19 18:35:51 +0200 | [diff] [blame] | 644 | <afile> is set to a single character, |
| 645 | indicating the type of command-line. |
| 646 | |cmdwin-char| |
Girish Palya | 92f68e2 | 2025-04-21 11:12:41 +0200 | [diff] [blame] | 647 | *CmdlineLeavePre* |
| 648 | CmdlineLeavePre Just before leaving the command line, and |
| 649 | before |CmdlineLeave|. Useful for capturing |
| 650 | completion info with |cmdcomplete_info()|, as |
| 651 | this information is cleared before |
| 652 | |CmdlineLeave| is triggered. Triggered for |
| 653 | non-interactive use of ":" in a mapping, but |
| 654 | not when using |<Cmd>|. Also triggered when |
| 655 | abandoning the command line by typing CTRL-C |
| 656 | or <Esc>. <afile> is set to a single |
| 657 | character indicating the command-line type. |
| 658 | See |cmdwin-char| for details. |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 659 | *CmdwinEnter* |
| 660 | CmdwinEnter After entering the command-line window. |
| 661 | Useful for setting options specifically for |
Bram Moolenaar | 96e38a8 | 2019-09-09 18:35:33 +0200 | [diff] [blame] | 662 | this special type of window. |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 663 | <afile> is set to a single character, |
| 664 | indicating the type of command-line. |
| 665 | |cmdwin-char| |
| 666 | *CmdwinLeave* |
| 667 | CmdwinLeave Before leaving the command-line window. |
| 668 | Useful to clean up any global setting done |
Bram Moolenaar | 96e38a8 | 2019-09-09 18:35:33 +0200 | [diff] [blame] | 669 | with CmdwinEnter. |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 670 | <afile> is set to a single character, |
| 671 | indicating the type of command-line. |
| 672 | |cmdwin-char| |
| 673 | *ColorScheme* |
| 674 | ColorScheme After loading a color scheme. |:colorscheme| |
Bram Moolenaar | 0daafaa | 2022-09-04 17:45:43 +0100 | [diff] [blame] | 675 | Not triggered if the color scheme is not |
| 676 | found. |
Bram Moolenaar | b95186f | 2013-11-28 18:53:52 +0100 | [diff] [blame] | 677 | The pattern is matched against the |
| 678 | colorscheme name. <afile> can be used for the |
| 679 | name of the actual file where this option was |
| 680 | set, and <amatch> for the new colorscheme |
| 681 | name. |
| 682 | |
Bram Moolenaar | 15142e2 | 2018-04-30 22:19:58 +0200 | [diff] [blame] | 683 | *ColorSchemePre* |
| 684 | ColorSchemePre Before loading a color scheme. |:colorscheme| |
| 685 | Useful to setup removing things added by a |
| 686 | color scheme, before another one is loaded. |
Bram Moolenaar | 589edb3 | 2019-09-20 14:38:13 +0200 | [diff] [blame] | 687 | CompleteChanged *CompleteChanged* |
Bram Moolenaar | d7f246c | 2019-04-08 18:15:41 +0200 | [diff] [blame] | 688 | After each time the Insert mode completion |
| 689 | menu changed. Not fired on popup menu hide, |
Bram Moolenaar | 3f169ce | 2020-01-26 22:43:31 +0100 | [diff] [blame] | 690 | use |CompleteDonePre| or |CompleteDone| for |
| 691 | that. Never triggered recursively. |
Bram Moolenaar | 754b560 | 2006-02-09 23:53:20 +0000 | [diff] [blame] | 692 | |
Bram Moolenaar | d7f246c | 2019-04-08 18:15:41 +0200 | [diff] [blame] | 693 | Sets these |v:event| keys: |
Bram Moolenaar | 911ead1 | 2019-04-21 00:03:35 +0200 | [diff] [blame] | 694 | completed_item See |complete-items|. |
Bram Moolenaar | d7f246c | 2019-04-08 18:15:41 +0200 | [diff] [blame] | 695 | height nr of items visible |
| 696 | width screen cells |
| 697 | row top screen row |
| 698 | col leftmost screen column |
| 699 | size total nr of items |
| 700 | scrollbar TRUE if visible |
| 701 | |
| 702 | It is not allowed to change the text |textlock|. |
Bram Moolenaar | e9bd572 | 2019-08-17 19:36:06 +0200 | [diff] [blame] | 703 | |
| 704 | The size and position of the popup are also |
| 705 | available by calling |pum_getpos()|. |
| 706 | |
Bram Moolenaar | 3f169ce | 2020-01-26 22:43:31 +0100 | [diff] [blame] | 707 | *CompleteDonePre* |
| 708 | CompleteDonePre After Insert mode completion is done. Either |
| 709 | when something was completed or abandoning |
| 710 | completion. |ins-completion| |
| 711 | |complete_info()| can be used, the info is |
| 712 | cleared after triggering CompleteDonePre. |
| 713 | The |v:completed_item| variable contains |
| 714 | information about the completed item. |
| 715 | |
Bram Moolenaar | 30b6581 | 2012-07-12 22:01:11 +0200 | [diff] [blame] | 716 | *CompleteDone* |
| 717 | CompleteDone After Insert mode completion is done. Either |
| 718 | when something was completed or abandoning |
| 719 | completion. |ins-completion| |
Bram Moolenaar | 3f169ce | 2020-01-26 22:43:31 +0100 | [diff] [blame] | 720 | |complete_info()| cannot be used, the info is |
| 721 | cleared before triggering CompleteDone. Use |
| 722 | CompleteDonePre if you need it. |
Bram Moolenaar | 42a4512 | 2015-07-10 17:56:23 +0200 | [diff] [blame] | 723 | The |v:completed_item| variable contains |
| 724 | information about the completed item. |
Bram Moolenaar | 30b6581 | 2012-07-12 22:01:11 +0200 | [diff] [blame] | 725 | |
glepnir | 1c5a120 | 2024-12-04 20:27:34 +0100 | [diff] [blame] | 726 | Sets these |v:event| keys: |
| 727 | complete_word The word that was |
| 728 | selected, empty if |
| 729 | abandoned complete. |
| 730 | complete_type |complete_info_mode| |
| 731 | |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 732 | *CursorHold* |
| 733 | CursorHold When the user doesn't press a key for the time |
Bram Moolenaar | d58a3bf | 2020-09-28 21:48:16 +0200 | [diff] [blame] | 734 | specified with 'updatetime'. Not triggered |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 735 | until the user has pressed a key (i.e. doesn't |
| 736 | fire every 'updatetime' ms if you leave Vim to |
| 737 | make some coffee. :) See |CursorHold-example| |
| 738 | for previewing tags. |
| 739 | This event is only triggered in Normal mode. |
Bram Moolenaar | d7afed3 | 2007-05-06 13:26:41 +0000 | [diff] [blame] | 740 | It is not triggered when waiting for a command |
| 741 | argument to be typed, or a movement after an |
| 742 | operator. |
Bram Moolenaar | e3226be | 2005-12-18 22:10:00 +0000 | [diff] [blame] | 743 | While recording the CursorHold event is not |
| 744 | triggered. |q| |
Bram Moolenaar | 3a991dd | 2014-10-02 01:41:41 +0200 | [diff] [blame] | 745 | *<CursorHold>* |
| 746 | Internally the autocommand is triggered by the |
| 747 | <CursorHold> key. In an expression mapping |
| 748 | |getchar()| may see this character. |
| 749 | |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 750 | Note: Interactive commands cannot be used for |
| 751 | this event. There is no hit-enter prompt, |
| 752 | the screen is updated directly (when needed). |
| 753 | Note: In the future there will probably be |
| 754 | another option to set the time. |
| 755 | Hint: to force an update of the status lines |
| 756 | use: > |
| 757 | :let &ro = &ro |
Bram Moolenaar | 5666fcd | 2019-12-26 14:35:26 +0100 | [diff] [blame] | 758 | < {only on Amiga, Unix, Win32 and all GUI |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 759 | versions} |
Bram Moolenaar | 754b560 | 2006-02-09 23:53:20 +0000 | [diff] [blame] | 760 | *CursorHoldI* |
| 761 | CursorHoldI Just like CursorHold, but in Insert mode. |
Bram Moolenaar | aa3b15d | 2016-04-21 08:53:19 +0200 | [diff] [blame] | 762 | Not triggered when waiting for another key, |
| 763 | e.g. after CTRL-V, and not when in CTRL-X mode |
| 764 | |insert_expand|. |
Bram Moolenaar | 754b560 | 2006-02-09 23:53:20 +0000 | [diff] [blame] | 765 | |
| 766 | *CursorMoved* |
Bram Moolenaar | 52b91d8 | 2013-06-15 21:39:51 +0200 | [diff] [blame] | 767 | CursorMoved After the cursor was moved in Normal or Visual |
| 768 | mode. Also when the text of the cursor line |
| 769 | has been changed, e.g., with "x", "rx" or "p". |
Bram Moolenaar | 46eea44 | 2022-03-30 10:51:39 +0100 | [diff] [blame] | 770 | Not always triggered when there is typeahead, |
| 771 | while executing commands in a script file, |
| 772 | when an operator is pending or when moving to |
Bram Moolenaar | 90df4b9 | 2021-07-07 20:26:08 +0200 | [diff] [blame] | 773 | another window while remaining at the same |
| 774 | cursor position. |
Bram Moolenaar | 1d2ba7f | 2006-02-14 22:29:30 +0000 | [diff] [blame] | 775 | For an example see |match-parens|. |
Bram Moolenaar | 2696761 | 2019-03-17 17:13:16 +0100 | [diff] [blame] | 776 | Note: This can not be skipped with |
| 777 | `:noautocmd`. |
Bram Moolenaar | bf88493 | 2013-04-05 22:26:15 +0200 | [diff] [blame] | 778 | Careful: This is triggered very often, don't |
| 779 | do anything that the user does not expect or |
| 780 | that is slow. |
Shougo Matsushita | d095214 | 2024-06-20 22:05:16 +0200 | [diff] [blame] | 781 | *CursorMovedC* |
| 782 | CursorMovedC After the cursor was moved in the command |
zeertzjq | 8145620 | 2024-07-07 20:48:25 +0200 | [diff] [blame] | 783 | line. Be careful not to mess up the command |
| 784 | line, it may cause Vim to lock up. |
Shougo Matsushita | d095214 | 2024-06-20 22:05:16 +0200 | [diff] [blame] | 785 | <afile> is set to a single character, |
| 786 | indicating the type of command-line. |
| 787 | |cmdwin-char| |
Bram Moolenaar | 754b560 | 2006-02-09 23:53:20 +0000 | [diff] [blame] | 788 | *CursorMovedI* |
| 789 | CursorMovedI After the cursor was moved in Insert mode. |
Bram Moolenaar | 5302d9e | 2011-09-14 17:55:08 +0200 | [diff] [blame] | 790 | Not triggered when the popup menu is visible. |
Bram Moolenaar | 754b560 | 2006-02-09 23:53:20 +0000 | [diff] [blame] | 791 | Otherwise the same as CursorMoved. |
Bram Moolenaar | 75ab590 | 2022-04-18 15:36:40 +0100 | [diff] [blame] | 792 | *DiffUpdated* |
| 793 | DiffUpdated After diffs have been updated. Depending on |
| 794 | what kind of diff is being used (internal or |
| 795 | external) this can be triggered on every |
| 796 | change or when doing |:diffupdate|. |
| 797 | *DirChangedPre* |
| 798 | DirChangedPre The working directory is going to be changed, |
| 799 | as with |DirChanged|. The pattern is like |
| 800 | with |DirChanged|. The new directory can be |
| 801 | found in v:event.directory. |
| 802 | *DirChanged* |
| 803 | DirChanged The working directory has changed in response |
| 804 | to the |:cd| or |:tcd| or |:lcd| commands, or |
| 805 | as a result of the 'autochdir' option. |
| 806 | The pattern can be: |
| 807 | "window" to trigger on `:lcd` |
| 808 | "tabpage" to trigger on `:tcd` |
| 809 | "global" to trigger on `:cd` |
| 810 | "auto" to trigger on 'autochdir'. |
| 811 | "drop" to trigger on editing a file |
| 812 | <afile> is set to the new directory name. |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 813 | *EncodingChanged* |
| 814 | EncodingChanged Fires off after the 'encoding' option has been |
| 815 | changed. Useful to set up fonts, for example. |
Bram Moolenaar | 75ab590 | 2022-04-18 15:36:40 +0100 | [diff] [blame] | 816 | *ExitPre* |
| 817 | ExitPre When using `:quit`, `:wq` in a way it makes |
| 818 | Vim exit, or using `:qall`, just after |
| 819 | |QuitPre|. Can be used to close any |
| 820 | non-essential window. Exiting may still be |
| 821 | cancelled if there is a modified buffer that |
| 822 | isn't automatically saved, use |VimLeavePre| |
| 823 | for really exiting. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 824 | *FileAppendCmd* |
| 825 | FileAppendCmd Before appending to a file. Should do the |
Bram Moolenaar | 3fdfa4a | 2004-10-07 21:02:47 +0000 | [diff] [blame] | 826 | appending to the file. Use the '[ and '] |
Bram Moolenaar | 2286304 | 2021-10-16 15:23:36 +0100 | [diff] [blame] | 827 | marks for the range of lines. |Cmd-event| |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 828 | *FileAppendPost* |
| 829 | FileAppendPost After appending to a file. |
| 830 | *FileAppendPre* |
| 831 | FileAppendPre Before appending to a file. Use the '[ and '] |
| 832 | marks for the range of lines. |
| 833 | *FileChangedRO* |
| 834 | FileChangedRO Before making the first change to a read-only |
| 835 | file. Can be used to check-out the file from |
| 836 | a source control system. Not triggered when |
| 837 | the change was caused by an autocommand. |
| 838 | This event is triggered when making the first |
| 839 | change in a buffer or the first change after |
Bram Moolenaar | 61660ea | 2006-04-07 21:40:07 +0000 | [diff] [blame] | 840 | 'readonly' was set, just before the change is |
| 841 | applied to the text. |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 842 | WARNING: If the autocommand moves the cursor |
| 843 | the effect of the change is undefined. |
Bram Moolenaar | 910f66f | 2006-04-05 20:41:53 +0000 | [diff] [blame] | 844 | *E788* |
| 845 | It is not allowed to change to another buffer |
| 846 | here. You can reload the buffer but not edit |
| 847 | another one. |
Bram Moolenaar | 92dff18 | 2014-02-11 19:15:50 +0100 | [diff] [blame] | 848 | *E881* |
| 849 | If the number of lines changes saving for undo |
| 850 | may fail and the change will be aborted. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 851 | *FileChangedShell* |
| 852 | FileChangedShell When Vim notices that the modification time of |
| 853 | a file has changed since editing started. |
| 854 | Also when the file attributes of the file |
Bram Moolenaar | e968e36 | 2014-05-13 20:23:24 +0200 | [diff] [blame] | 855 | change or when the size of the file changes. |
| 856 | |timestamp| |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 857 | Mostly triggered after executing a shell |
| 858 | command, but also with a |:checktime| command |
Bram Moolenaar | 6aa8cea | 2017-06-05 14:44:35 +0200 | [diff] [blame] | 859 | or when gvim regains input focus. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 860 | This autocommand is triggered for each changed |
| 861 | file. It is not used when 'autoread' is set |
| 862 | and the buffer was not changed. If a |
| 863 | FileChangedShell autocommand is present the |
| 864 | warning message and prompt is not given. |
Bram Moolenaar | 19a09a1 | 2005-03-04 23:39:37 +0000 | [diff] [blame] | 865 | The |v:fcs_reason| variable is set to indicate |
| 866 | what happened and |v:fcs_choice| can be used |
| 867 | to tell Vim what to do next. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 868 | NOTE: When this autocommand is executed, the |
| 869 | current buffer "%" may be different from the |
Bram Moolenaar | cd5c8f8 | 2017-04-09 20:11:58 +0200 | [diff] [blame] | 870 | buffer that was changed, which is in "<afile>". |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 871 | NOTE: The commands must not change the current |
| 872 | buffer, jump to another buffer or delete a |
Bram Moolenaar | 8f3f58f | 2010-01-06 20:52:26 +0100 | [diff] [blame] | 873 | buffer. *E246* *E811* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 874 | NOTE: This event never nests, to avoid an |
| 875 | endless loop. This means that while executing |
| 876 | commands for the FileChangedShell event no |
| 877 | other FileChangedShell event will be |
| 878 | triggered. |
Bram Moolenaar | 7d47b6e | 2006-03-15 22:59:18 +0000 | [diff] [blame] | 879 | *FileChangedShellPost* |
| 880 | FileChangedShellPost After handling a file that was changed outside |
| 881 | of Vim. Can be used to update the statusline. |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 882 | *FileEncoding* |
| 883 | FileEncoding Obsolete. It still works and is equivalent |
| 884 | to |EncodingChanged|. |
| 885 | *FileReadCmd* |
| 886 | FileReadCmd Before reading a file with a ":read" command. |
| 887 | Should do the reading of the file. |Cmd-event| |
| 888 | *FileReadPost* |
| 889 | FileReadPost After reading a file with a ":read" command. |
| 890 | Note that Vim sets the '[ and '] marks to the |
| 891 | first and last line of the read. This can be |
| 892 | used to operate on the lines just read. |
| 893 | *FileReadPre* |
| 894 | FileReadPre Before reading a file with a ":read" command. |
| 895 | *FileType* |
Bram Moolenaar | d7afed3 | 2007-05-06 13:26:41 +0000 | [diff] [blame] | 896 | FileType When the 'filetype' option has been set. The |
| 897 | pattern is matched against the filetype. |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 898 | <afile> can be used for the name of the file |
| 899 | where this option was set, and <amatch> for |
Bram Moolenaar | 74675a6 | 2017-07-15 13:53:23 +0200 | [diff] [blame] | 900 | the new value of 'filetype'. Navigating to |
| 901 | another window or buffer is not allowed. |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 902 | See |filetypes|. |
| 903 | *FileWriteCmd* |
| 904 | FileWriteCmd Before writing to a file, when not writing the |
| 905 | whole buffer. Should do the writing to the |
| 906 | file. Should not change the buffer. Use the |
Christian Brabandt | df68419 | 2025-04-03 12:33:02 +0200 | [diff] [blame] | 907 | |'[| and |']| marks for the range of lines. |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 908 | |Cmd-event| |
| 909 | *FileWritePost* |
| 910 | FileWritePost After writing to a file, when not writing the |
| 911 | whole buffer. |
| 912 | *FileWritePre* |
| 913 | FileWritePre Before writing to a file, when not writing the |
Christian Brabandt | df68419 | 2025-04-03 12:33:02 +0200 | [diff] [blame] | 914 | whole buffer. Use the |'[| and |']| marks for the |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 915 | range of lines. |
| 916 | *FilterReadPost* |
| 917 | FilterReadPost After reading a file from a filter command. |
| 918 | Vim checks the pattern against the name of |
| 919 | the current buffer as with FilterReadPre. |
| 920 | Not triggered when 'shelltemp' is off. |
| 921 | *FilterReadPre* *E135* |
| 922 | FilterReadPre Before reading a file from a filter command. |
| 923 | Vim checks the pattern against the name of |
| 924 | the current buffer, not the name of the |
| 925 | temporary file that is the output of the |
| 926 | filter command. |
| 927 | Not triggered when 'shelltemp' is off. |
| 928 | *FilterWritePost* |
| 929 | FilterWritePost After writing a file for a filter command or |
Bram Moolenaar | 4c05fa0 | 2019-01-01 15:32:17 +0100 | [diff] [blame] | 930 | making a diff with an external diff (see |
Bram Moolenaar | 2286304 | 2021-10-16 15:23:36 +0100 | [diff] [blame] | 931 | |DiffUpdated| for internal diff). |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 932 | Vim checks the pattern against the name of |
| 933 | the current buffer as with FilterWritePre. |
| 934 | Not triggered when 'shelltemp' is off. |
| 935 | *FilterWritePre* |
| 936 | FilterWritePre Before writing a file for a filter command or |
Bram Moolenaar | 4c05fa0 | 2019-01-01 15:32:17 +0100 | [diff] [blame] | 937 | making a diff with an external diff. |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 938 | Vim checks the pattern against the name of |
| 939 | the current buffer, not the name of the |
| 940 | temporary file that is the output of the |
| 941 | filter command. |
| 942 | Not triggered when 'shelltemp' is off. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 943 | *FocusGained* |
| 944 | FocusGained When Vim got input focus. Only for the GUI |
| 945 | version and a few console versions where this |
Christian Brabandt | 49ddeef | 2024-07-07 20:29:43 +0200 | [diff] [blame] | 946 | can be detected. |xterm-focus-event| |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 947 | *FocusLost* |
| 948 | FocusLost When Vim lost input focus. Only for the GUI |
| 949 | version and a few console versions where this |
Christian Brabandt | 49ddeef | 2024-07-07 20:29:43 +0200 | [diff] [blame] | 950 | can be detected. |xterm-focus-event| |
| 951 | May also happen when a dialog pops up. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 952 | *FuncUndefined* |
| 953 | FuncUndefined When a user function is used but it isn't |
| 954 | defined. Useful for defining a function only |
Bram Moolenaar | d7afed3 | 2007-05-06 13:26:41 +0000 | [diff] [blame] | 955 | when it's used. The pattern is matched |
| 956 | against the function name. Both <amatch> and |
| 957 | <afile> are set to the name of the function. |
zeertzjq | af05694 | 2025-03-08 16:45:20 +0100 | [diff] [blame] | 958 | This is triggered even when inside an |
| 959 | autocommand defined without |autocmd-nested|, |
| 960 | but not triggered when compiling a |Vim9| |
Bram Moolenaar | 4072ba5 | 2020-12-23 13:56:35 +0100 | [diff] [blame] | 961 | function. |
Bram Moolenaar | d500516 | 2014-08-22 23:05:54 +0200 | [diff] [blame] | 962 | NOTE: When writing Vim scripts a better |
| 963 | alternative is to use an autoloaded function. |
Bram Moolenaar | 7c62692 | 2005-02-07 22:01:03 +0000 | [diff] [blame] | 964 | See |autoload-functions|. |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 965 | *GUIEnter* |
| 966 | GUIEnter After starting the GUI successfully, and after |
| 967 | opening the window. It is triggered before |
| 968 | VimEnter when using gvim. Can be used to |
| 969 | position the window from a .gvimrc file: > |
| 970 | :autocmd GUIEnter * winpos 100 50 |
Bram Moolenaar | d7afed3 | 2007-05-06 13:26:41 +0000 | [diff] [blame] | 971 | < *GUIFailed* |
| 972 | GUIFailed After starting the GUI failed. Vim may |
| 973 | continue to run in the terminal, if possible |
| 974 | (only on Unix and alikes, when connecting the |
| 975 | X server fails). You may want to quit Vim: > |
| 976 | :autocmd GUIFailed * qall |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 977 | < *InsertChange* |
| 978 | InsertChange When typing <Insert> while in Insert or |
| 979 | Replace mode. The |v:insertmode| variable |
| 980 | indicates the new mode. |
| 981 | Be careful not to move the cursor or do |
| 982 | anything else that the user does not expect. |
Bram Moolenaar | e659c95 | 2011-05-19 17:25:41 +0200 | [diff] [blame] | 983 | *InsertCharPre* |
| 984 | InsertCharPre When a character is typed in Insert mode, |
| 985 | before inserting the char. |
| 986 | The |v:char| variable indicates the char typed |
| 987 | and can be changed during the event to insert |
| 988 | a different character. When |v:char| is set |
| 989 | to more than one character this text is |
| 990 | inserted literally. |
| 991 | It is not allowed to change the text |textlock|. |
| 992 | The event is not triggered when 'paste' is |
Bram Moolenaar | b5b7562 | 2018-03-09 22:22:21 +0100 | [diff] [blame] | 993 | set. {only with the +eval feature} |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 994 | *InsertEnter* |
Bram Moolenaar | d7afed3 | 2007-05-06 13:26:41 +0000 | [diff] [blame] | 995 | InsertEnter Just before starting Insert mode. Also for |
| 996 | Replace mode and Virtual Replace mode. The |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 997 | |v:insertmode| variable indicates the mode. |
Bram Moolenaar | 097c992 | 2013-05-19 21:15:15 +0200 | [diff] [blame] | 998 | Be careful not to do anything else that the |
| 999 | user does not expect. |
| 1000 | The cursor is restored afterwards. If you do |
| 1001 | not want that set |v:char| to a non-empty |
| 1002 | string. |
Bram Moolenaar | b53e13a | 2020-10-21 12:19:53 +0200 | [diff] [blame] | 1003 | *InsertLeavePre* |
| 1004 | InsertLeavePre Just before leaving Insert mode. Also when |
Bram Moolenaar | cb80aa2 | 2020-10-26 21:12:46 +0100 | [diff] [blame] | 1005 | using CTRL-O |i_CTRL-O|. Be careful not to |
Bram Moolenaar | b53e13a | 2020-10-21 12:19:53 +0200 | [diff] [blame] | 1006 | change mode or use `:normal`, it will likely |
| 1007 | cause trouble. |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 1008 | *InsertLeave* |
Bram Moolenaar | b53e13a | 2020-10-21 12:19:53 +0200 | [diff] [blame] | 1009 | InsertLeave Just after leaving Insert mode. Also when |
| 1010 | using CTRL-O |i_CTRL-O|. But not for |i_CTRL-C|. |
Shougo Matsushita | 8367884 | 2024-07-11 22:05:12 +0200 | [diff] [blame] | 1011 | *KeyInputPre* |
Shougo Matsushita | fcc1b57 | 2024-07-17 20:25:22 +0200 | [diff] [blame] | 1012 | KeyInputPre Just before a key is processed after mappings |
| 1013 | have been applied. The pattern is matched |
| 1014 | against a string that indicates the current |
| 1015 | mode, which is the same as what is returned by |
| 1016 | `mode(1)`. |
Shougo Matsushita | 8367884 | 2024-07-11 22:05:12 +0200 | [diff] [blame] | 1017 | The |v:char| variable indicates the key typed |
| 1018 | and can be changed during the event to process |
| 1019 | a different key. When |v:char| is not a |
| 1020 | single character or a special key, the first |
| 1021 | character is used. |
| 1022 | The following values of |v:event| are set: |
| 1023 | typed The key is typed or not. |
Shougo Matsushita | 890f97c | 2024-08-18 16:57:04 +0200 | [diff] [blame] | 1024 | typedchar The (actual) typed key since |
| 1025 | the last |KeyInputPre| call. |
| 1026 | Note: "typedchar" may be empty if successive |
| 1027 | |KeyInputPre| autocmds are processed. |
Shougo Matsushita | 8367884 | 2024-07-11 22:05:12 +0200 | [diff] [blame] | 1028 | It is not allowed to change the text |
| 1029 | |textlock| or the current mode. |
| 1030 | {only with the +eval feature} |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 1031 | *MenuPopup* |
| 1032 | MenuPopup Just before showing the popup menu (under the |
| 1033 | right mouse button). Useful for adjusting the |
| 1034 | menu for what is under the cursor or mouse |
| 1035 | pointer. |
Bram Moolenaar | 4c5d815 | 2018-10-19 22:36:53 +0200 | [diff] [blame] | 1036 | The pattern is matched against one or two |
| 1037 | characters representing the mode: |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 1038 | n Normal |
| 1039 | v Visual |
| 1040 | o Operator-pending |
| 1041 | i Insert |
Bram Moolenaar | 551dbcc | 2006-04-25 22:13:59 +0000 | [diff] [blame] | 1042 | c Command line |
Bram Moolenaar | 4c5d815 | 2018-10-19 22:36:53 +0200 | [diff] [blame] | 1043 | tl Terminal |
=?UTF-8?q?Magnus=20Gro=C3=9F?= | f1e8876 | 2021-09-12 13:39:55 +0200 | [diff] [blame] | 1044 | *ModeChanged* |
| 1045 | ModeChanged After changing the mode. The pattern is |
| 1046 | matched against `'old_mode:new_mode'`, for |
=?UTF-8?q?Magnus=20Gro=C3=9F?= | 25def2c | 2021-10-22 18:56:39 +0100 | [diff] [blame] | 1047 | example match against `*:c*` to simulate |
| 1048 | |CmdlineEnter|. |
=?UTF-8?q?Magnus=20Gro=C3=9F?= | f1e8876 | 2021-09-12 13:39:55 +0200 | [diff] [blame] | 1049 | The following values of |v:event| are set: |
| 1050 | old_mode The mode before it changed. |
| 1051 | new_mode The new mode as also returned |
=?UTF-8?q?Magnus=20Gro=C3=9F?= | 25def2c | 2021-10-22 18:56:39 +0100 | [diff] [blame] | 1052 | by |mode()| called with a |
| 1053 | non-zero argument. |
=?UTF-8?q?Magnus=20Gro=C3=9F?= | f1e8876 | 2021-09-12 13:39:55 +0200 | [diff] [blame] | 1054 | When ModeChanged is triggered, old_mode will |
| 1055 | have the value of new_mode when the event was |
| 1056 | last triggered. |
=?UTF-8?q?Magnus=20Gro=C3=9F?= | 25def2c | 2021-10-22 18:56:39 +0100 | [diff] [blame] | 1057 | This will be triggered on every minor mode |
| 1058 | change. |
=?UTF-8?q?Magnus=20Gro=C3=9F?= | f1e8876 | 2021-09-12 13:39:55 +0200 | [diff] [blame] | 1059 | Usage example to use relative line numbers |
Bram Moolenaar | 6e64922 | 2021-10-04 21:32:54 +0100 | [diff] [blame] | 1060 | when entering Visual mode: > |
=?UTF-8?q?Magnus=20Gro=C3=9F?= | 25def2c | 2021-10-22 18:56:39 +0100 | [diff] [blame] | 1061 | :au ModeChanged [vV\x16]*:* let &l:rnu = mode() =~# '^[vV\x16]' |
| 1062 | :au ModeChanged *:[vV\x16]* let &l:rnu = mode() =~# '^[vV\x16]' |
| 1063 | :au WinEnter,WinLeave * let &l:rnu = mode() =~# '^[vV\x16]' |
=?UTF-8?q?Magnus=20Gro=C3=9F?= | f1e8876 | 2021-09-12 13:39:55 +0200 | [diff] [blame] | 1064 | < *OptionSet* |
Bram Moolenaar | 5374430 | 2015-07-17 17:38:22 +0200 | [diff] [blame] | 1065 | OptionSet After setting an option. The pattern is |
| 1066 | matched against the long option name. |
Bram Moolenaar | d7c9687 | 2019-06-15 17:12:48 +0200 | [diff] [blame] | 1067 | |<amatch>| indicates what option has been set. |
Bram Moolenaar | 5374430 | 2015-07-17 17:38:22 +0200 | [diff] [blame] | 1068 | |
Bram Moolenaar | d7c9687 | 2019-06-15 17:12:48 +0200 | [diff] [blame] | 1069 | |v:option_type| indicates whether it's global |
Bram Moolenaar | 6c1e157 | 2019-06-22 02:13:00 +0200 | [diff] [blame] | 1070 | or local scoped. |
Bram Moolenaar | d7c9687 | 2019-06-15 17:12:48 +0200 | [diff] [blame] | 1071 | |v:option_command| indicates what type of |
| 1072 | set/let command was used (follow the tag to |
| 1073 | see the table). |
| 1074 | |v:option_new| indicates the newly set value. |
Bram Moolenaar | 6c1e157 | 2019-06-22 02:13:00 +0200 | [diff] [blame] | 1075 | |v:option_oldlocal| has the old local value. |
| 1076 | |v:option_oldglobal| has the old global value. |
Bram Moolenaar | d7c9687 | 2019-06-15 17:12:48 +0200 | [diff] [blame] | 1077 | |v:option_old| indicates the old option value. |
| 1078 | |
| 1079 | |v:option_oldlocal| is only set when |:set| |
| 1080 | or |:setlocal| or a |modeline| was used to set |
| 1081 | the option. Similarly |v:option_oldglobal| is |
| 1082 | only set when |:set| or |:setglobal| was used. |
| 1083 | |
Bram Moolenaar | 10e8ff9 | 2023-06-10 21:40:39 +0100 | [diff] [blame] | 1084 | This does not set |<abuf>|, you could use |
| 1085 | |bufnr()|. |
| 1086 | |
Bram Moolenaar | d7c9687 | 2019-06-15 17:12:48 +0200 | [diff] [blame] | 1087 | Note that when setting a |global-local| string |
| 1088 | option with |:set|, then |v:option_old| is the |
| 1089 | old global value. However, for all other kinds |
| 1090 | of options (local string options, global-local |
| 1091 | number options, ...) it is the old local |
| 1092 | value. |
| 1093 | |
| 1094 | OptionSet is not triggered on startup and for |
| 1095 | the 'key' option for obvious reasons. |
Bram Moolenaar | 5374430 | 2015-07-17 17:38:22 +0200 | [diff] [blame] | 1096 | |
Bram Moolenaar | f913281 | 2015-07-21 19:19:13 +0200 | [diff] [blame] | 1097 | Usage example: Check for the existence of the |
| 1098 | directory in the 'backupdir' and 'undodir' |
| 1099 | options, create the directory if it doesn't |
| 1100 | exist yet. |
| 1101 | |
| 1102 | Note: It's a bad idea to reset an option |
| 1103 | during this autocommand, this may break a |
| 1104 | plugin. You can always use `:noa` to prevent |
| 1105 | triggering this autocommand. |
Bram Moolenaar | 5374430 | 2015-07-17 17:38:22 +0200 | [diff] [blame] | 1106 | |
Bram Moolenaar | 95bafa2 | 2018-10-02 13:26:25 +0200 | [diff] [blame] | 1107 | When using |:set| in the autocommand the event |
| 1108 | is not triggered again. |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 1109 | *QuickFixCmdPre* |
| 1110 | QuickFixCmdPre Before a quickfix command is run (|:make|, |
Bram Moolenaar | a655760 | 2006-02-04 22:43:20 +0000 | [diff] [blame] | 1111 | |:lmake|, |:grep|, |:lgrep|, |:grepadd|, |
| 1112 | |:lgrepadd|, |:vimgrep|, |:lvimgrep|, |
Bram Moolenaar | 6be7f87 | 2012-01-20 21:08:56 +0100 | [diff] [blame] | 1113 | |:vimgrepadd|, |:lvimgrepadd|, |:cscope|, |
Bram Moolenaar | 84f7235 | 2012-03-11 15:57:40 +0100 | [diff] [blame] | 1114 | |:cfile|, |:cgetfile|, |:caddfile|, |:lfile|, |
| 1115 | |:lgetfile|, |:laddfile|, |:helpgrep|, |
Bram Moolenaar | 64d8e25 | 2016-09-06 22:12:34 +0200 | [diff] [blame] | 1116 | |:lhelpgrep|, |:cexpr|, |:cgetexpr|, |
| 1117 | |:caddexpr|, |:cbuffer|, |:cgetbuffer|, |
| 1118 | |:caddbuffer|). |
Bram Moolenaar | f1eeae9 | 2010-05-14 23:14:42 +0200 | [diff] [blame] | 1119 | The pattern is matched against the command |
| 1120 | being run. When |:grep| is used but 'grepprg' |
| 1121 | is set to "internal" it still matches "grep". |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 1122 | This command cannot be used to set the |
| 1123 | 'makeprg' and 'grepprg' variables. |
| 1124 | If this command causes an error, the quickfix |
| 1125 | command is not executed. |
| 1126 | *QuickFixCmdPost* |
| 1127 | QuickFixCmdPost Like QuickFixCmdPre, but after a quickfix |
Bram Moolenaar | f9393ef | 2006-04-24 19:47:27 +0000 | [diff] [blame] | 1128 | command is run, before jumping to the first |
Bram Moolenaar | 8ec1f85 | 2012-03-07 20:13:49 +0100 | [diff] [blame] | 1129 | location. For |:cfile| and |:lfile| commands |
Bram Moolenaar | b59ae59 | 2022-11-23 23:46:31 +0000 | [diff] [blame] | 1130 | it is run after the error file is read and |
| 1131 | before moving to the first error. |
Bram Moolenaar | 8ec1f85 | 2012-03-07 20:13:49 +0100 | [diff] [blame] | 1132 | See |QuickFixCmdPost-example|. |
Bram Moolenaar | 30b6581 | 2012-07-12 22:01:11 +0200 | [diff] [blame] | 1133 | *QuitPre* |
Bram Moolenaar | ac7bd63 | 2013-03-19 11:35:58 +0100 | [diff] [blame] | 1134 | QuitPre When using `:quit`, `:wq` or `:qall`, before |
| 1135 | deciding whether it closes the current window |
Bram Moolenaar | d2ea7cf | 2021-05-30 20:54:13 +0200 | [diff] [blame] | 1136 | or quits Vim. For `:wq` the buffer is written |
| 1137 | before QuitPre is triggered. Can be used to |
| 1138 | close any non-essential window if the current |
| 1139 | window is the last ordinary window. |
Bram Moolenaar | 12a96de | 2018-03-11 14:44:18 +0100 | [diff] [blame] | 1140 | Also see |ExitPre|. |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 1141 | *RemoteReply* |
| 1142 | RemoteReply When a reply from a Vim that functions as |
Bram Moolenaar | d7afed3 | 2007-05-06 13:26:41 +0000 | [diff] [blame] | 1143 | server was received |server2client()|. The |
| 1144 | pattern is matched against the {serverid}. |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 1145 | <amatch> is equal to the {serverid} from which |
| 1146 | the reply was sent, and <afile> is the actual |
| 1147 | reply string. |
| 1148 | Note that even if an autocommand is defined, |
| 1149 | the reply should be read with |remote_read()| |
| 1150 | to consume it. |
Bram Moolenaar | 8aeec40 | 2019-09-15 23:02:04 +0200 | [diff] [blame] | 1151 | *SafeState* |
| 1152 | SafeState When nothing is pending, going to wait for the |
| 1153 | user to type a character. |
| 1154 | This will not be triggered when: |
| 1155 | - an operator is pending |
| 1156 | - a register was entered with "r |
| 1157 | - halfway executing a command |
| 1158 | - executing a mapping |
| 1159 | - there is typeahead |
| 1160 | - Insert mode completion is active |
| 1161 | - Command line completion is active |
| 1162 | You can use `mode()` to find out what state |
| 1163 | Vim is in. That may be: |
zeertzjq | e13b665 | 2024-01-24 03:39:04 +0800 | [diff] [blame] | 1164 | - Visual mode |
Bram Moolenaar | 8aeec40 | 2019-09-15 23:02:04 +0200 | [diff] [blame] | 1165 | - Normal mode |
| 1166 | - Insert mode |
| 1167 | - Command-line mode |
| 1168 | Depending on what you want to do, you may also |
| 1169 | check more with `state()`, e.g. whether the |
| 1170 | screen was scrolled for messages. |
Bram Moolenaar | 69198cb | 2019-09-16 21:58:13 +0200 | [diff] [blame] | 1171 | *SafeStateAgain* |
| 1172 | SafeStateAgain Like SafeState but after processing any |
| 1173 | messages and invoking callbacks. This may be |
| 1174 | triggered often, don't do something that takes |
| 1175 | time. |
Bram Moolenaar | 8aeec40 | 2019-09-15 23:02:04 +0200 | [diff] [blame] | 1176 | |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 1177 | *SessionLoadPost* |
| 1178 | SessionLoadPost After loading the session file created using |
| 1179 | the |:mksession| command. |
Colin Kennedy | e5f2280 | 2024-03-26 18:20:16 +0100 | [diff] [blame] | 1180 | *SessionWritePost* |
| 1181 | SessionWritePost After writing a session file by calling |
| 1182 | the |:mksession| command. |
Bram Moolenaar | a94bc43 | 2006-03-10 21:42:59 +0000 | [diff] [blame] | 1183 | *ShellCmdPost* |
| 1184 | ShellCmdPost After executing a shell command with |:!cmd|, |
| 1185 | |:shell|, |:make| and |:grep|. Can be used to |
| 1186 | check for any changed files. |
| 1187 | *ShellFilterPost* |
| 1188 | ShellFilterPost After executing a shell command with |
| 1189 | ":{range}!cmd", ":w !cmd" or ":r !cmd". |
| 1190 | Can be used to check for any changed files. |
Bram Moolenaar | 1f35bf9 | 2006-03-07 22:38:47 +0000 | [diff] [blame] | 1191 | *SourcePre* |
| 1192 | SourcePre Before sourcing a Vim script. |:source| |
Bram Moolenaar | 8dd1aa5 | 2007-01-16 20:33:19 +0000 | [diff] [blame] | 1193 | <afile> is the name of the file being sourced. |
Bram Moolenaar | 2b61852 | 2019-01-12 13:26:03 +0100 | [diff] [blame] | 1194 | *SourcePost* |
| 1195 | SourcePost After sourcing a Vim script. |:source| |
| 1196 | <afile> is the name of the file being sourced. |
| 1197 | Not triggered when sourcing was interrupted. |
| 1198 | Also triggered after a SourceCmd autocommand |
| 1199 | was triggered. |
Bram Moolenaar | 8dd1aa5 | 2007-01-16 20:33:19 +0000 | [diff] [blame] | 1200 | *SourceCmd* |
| 1201 | SourceCmd When sourcing a Vim script. |:source| |
| 1202 | <afile> is the name of the file being sourced. |
| 1203 | The autocommand must source this file. |
| 1204 | |Cmd-event| |
Bram Moolenaar | afeb4fa | 2006-02-01 21:51:12 +0000 | [diff] [blame] | 1205 | *SpellFileMissing* |
| 1206 | SpellFileMissing When trying to load a spell checking file and |
Bram Moolenaar | 8dd1aa5 | 2007-01-16 20:33:19 +0000 | [diff] [blame] | 1207 | it can't be found. The pattern is matched |
| 1208 | against the language. <amatch> is the |
| 1209 | language, 'encoding' also matters. See |
Bram Moolenaar | afeb4fa | 2006-02-01 21:51:12 +0000 | [diff] [blame] | 1210 | |spell-SpellFileMissing|. |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 1211 | *StdinReadPost* |
| 1212 | StdinReadPost After reading from the stdin into the buffer, |
| 1213 | before executing the modelines. Only used |
| 1214 | when the "-" argument was used when Vim was |
| 1215 | started |--|. |
| 1216 | *StdinReadPre* |
| 1217 | StdinReadPre Before reading from stdin into the buffer. |
| 1218 | Only used when the "-" argument was used when |
| 1219 | Vim was started |--|. |
| 1220 | *SwapExists* |
| 1221 | SwapExists Detected an existing swap file when starting |
| 1222 | to edit a file. Only when it is possible to |
| 1223 | select a way to handle the situation, when Vim |
| 1224 | would ask the user what to do. |
| 1225 | The |v:swapname| variable holds the name of |
Bram Moolenaar | b348038 | 2005-12-11 21:33:32 +0000 | [diff] [blame] | 1226 | the swap file found, <afile> the file being |
| 1227 | edited. |v:swapcommand| may contain a command |
| 1228 | to be executed in the opened file. |
| 1229 | The commands should set the |v:swapchoice| |
| 1230 | variable to a string with one character to |
| 1231 | tell Vim what should be done next: |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 1232 | 'o' open read-only |
| 1233 | 'e' edit the file anyway |
| 1234 | 'r' recover |
| 1235 | 'd' delete the swap file |
| 1236 | 'q' quit, don't edit the file |
| 1237 | 'a' abort, like hitting CTRL-C |
| 1238 | When set to an empty string the user will be |
| 1239 | asked, as if there was no SwapExists autocmd. |
Bram Moolenaar | b849e71 | 2009-06-24 15:51:37 +0000 | [diff] [blame] | 1240 | *E812* |
| 1241 | It is not allowed to change to another buffer, |
| 1242 | change a buffer name or change directory |
| 1243 | here. |
Bram Moolenaar | b5b7562 | 2018-03-09 22:22:21 +0100 | [diff] [blame] | 1244 | {only available with the +eval feature} |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 1245 | *Syntax* |
Bram Moolenaar | d7afed3 | 2007-05-06 13:26:41 +0000 | [diff] [blame] | 1246 | Syntax When the 'syntax' option has been set. The |
| 1247 | pattern is matched against the syntax name. |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 1248 | <afile> can be used for the name of the file |
| 1249 | where this option was set, and <amatch> for |
| 1250 | the new value of 'syntax'. |
| 1251 | See |:syn-on|. |
Bram Moolenaar | 12c11d5 | 2016-07-19 23:13:03 +0200 | [diff] [blame] | 1252 | *TabClosed* |
| 1253 | TabClosed After closing a tab page. |
Jim Zhou | 5606ca5 | 2025-03-13 21:58:25 +0100 | [diff] [blame] | 1254 | *TabClosedPre* |
| 1255 | TabClosedPre Before closing a tab page. The window layout |
| 1256 | is locked, thus opening and closing of windows |
| 1257 | is prohibited. |
Bram Moolenaar | faa959a | 2006-02-20 21:37:40 +0000 | [diff] [blame] | 1258 | *TabEnter* |
| 1259 | TabEnter Just after entering a tab page. |tab-page| |
Bram Moolenaar | 56a907a | 2006-05-06 21:44:30 +0000 | [diff] [blame] | 1260 | After triggering the WinEnter and before |
| 1261 | triggering the BufEnter event. |
Bram Moolenaar | faa959a | 2006-02-20 21:37:40 +0000 | [diff] [blame] | 1262 | *TabLeave* |
| 1263 | TabLeave Just before leaving a tab page. |tab-page| |
| 1264 | A WinLeave event will have been triggered |
| 1265 | first. |
Bram Moolenaar | c917da4 | 2016-07-19 22:31:36 +0200 | [diff] [blame] | 1266 | *TabNew* |
| 1267 | TabNew When a tab page was created. |tab-page| |
| 1268 | A WinEnter event will have been triggered |
| 1269 | first, TabEnter follows. |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 1270 | *TermChanged* |
| 1271 | TermChanged After the value of 'term' has changed. Useful |
| 1272 | for re-loading the syntax file to update the |
| 1273 | colors, fonts and other terminal-dependent |
| 1274 | settings. Executed for all loaded buffers. |
Bram Moolenaar | b852c3e | 2018-03-11 16:55:36 +0100 | [diff] [blame] | 1275 | *TerminalOpen* |
| 1276 | TerminalOpen Just after a terminal buffer was created, with |
| 1277 | `:terminal` or |term_start()|. This event is |
| 1278 | triggered even if the buffer is created |
| 1279 | without a window, with the ++hidden option. |
Bram Moolenaar | 28ed4df | 2019-10-26 16:21:40 +0200 | [diff] [blame] | 1280 | *TerminalWinOpen* |
| 1281 | TerminalWinOpen Just after a terminal buffer was created, with |
| 1282 | `:terminal` or |term_start()|. This event is |
| 1283 | triggered only if the buffer is created |
| 1284 | with a window. Can be used to set window |
| 1285 | local options for the terminal window. |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 1286 | *TermResponse* |
| 1287 | TermResponse After the response to |t_RV| is received from |
| 1288 | the terminal. The value of |v:termresponse| |
| 1289 | can be used to do things depending on the |
Christian Brabandt | 2abec43 | 2024-10-27 21:33:09 +0100 | [diff] [blame] | 1290 | terminal version. |
| 1291 | This is used in |defaults.vim| to detect |
| 1292 | putty terminal and set a dark background: > |
| 1293 | |
| 1294 | au TermResponse * |
| 1295 | \ if v:termresponse == "\e[>0;136;0c" |
| 1296 | \ set bg=dark |
| 1297 | \ endif |
| 1298 | < |
| 1299 | Note: that this event may be triggered halfway |
| 1300 | executing another event, especially if file |
| 1301 | I/O, a shell command or anything else that |
| 1302 | takes time is involved. |
Danek Duvall | d7d5603 | 2024-01-14 20:19:59 +0100 | [diff] [blame] | 1303 | *TermResponseAll* |
| 1304 | TermResponseAll After the response to |t_RV|, |t_RC|, |t_RS|, |
| 1305 | |t_RB|, |t_RF|, or |t_u7| are received from |
| 1306 | the terminal. The value of |v:termresponse|, |
| 1307 | |v:termblinkresp|, |v:termstyleresp|, |
| 1308 | |v:termrbgresp|, |v:termrfgresp|, and |
| 1309 | |v:termu7resp|, correspondingly, can be used. |
| 1310 | <amatch> will be set to any of: |
| 1311 | "version", |
| 1312 | "cursorblink", |
| 1313 | "cursorshape", |
| 1314 | "background", |
| 1315 | "foreground", |
| 1316 | "ambiguouswidth" |
| 1317 | Note that this event may be triggered halfway |
| 1318 | executing another event, especially if file I/O, |
| 1319 | a shell command or anything else that takes time |
| 1320 | is involved. |
Bram Moolenaar | bf88493 | 2013-04-05 22:26:15 +0200 | [diff] [blame] | 1321 | *TextChanged* |
| 1322 | TextChanged After a change was made to the text in the |
Bram Moolenaar | d09091d | 2019-01-17 16:07:22 +0100 | [diff] [blame] | 1323 | current buffer in Normal mode. That is after |
| 1324 | |b:changedtick| has changed (also when that |
| 1325 | happened before the TextChanged autocommand |
| 1326 | was defined). |
Bram Moolenaar | bf88493 | 2013-04-05 22:26:15 +0200 | [diff] [blame] | 1327 | Not triggered when there is typeahead or when |
| 1328 | an operator is pending. |
Bram Moolenaar | 2696761 | 2019-03-17 17:13:16 +0100 | [diff] [blame] | 1329 | Note: This can not be skipped with |
| 1330 | `:noautocmd`. |
Bram Moolenaar | bf88493 | 2013-04-05 22:26:15 +0200 | [diff] [blame] | 1331 | Careful: This is triggered very often, don't |
| 1332 | do anything that the user does not expect or |
| 1333 | that is slow. |
| 1334 | *TextChangedI* |
| 1335 | TextChangedI After a change was made to the text in the |
| 1336 | current buffer in Insert mode. |
| 1337 | Not triggered when the popup menu is visible. |
| 1338 | Otherwise the same as TextChanged. |
Bram Moolenaar | 5a09343 | 2018-02-10 18:15:19 +0100 | [diff] [blame] | 1339 | *TextChangedP* |
| 1340 | TextChangedP After a change was made to the text in the |
| 1341 | current buffer in Insert mode, only when the |
| 1342 | popup menu is visible. Otherwise the same as |
| 1343 | TextChanged. |
Shougo Matsushita | 4ccaedf | 2022-10-15 11:48:00 +0100 | [diff] [blame] | 1344 | *TextChangedT* |
| 1345 | TextChangedT After a change was made to the text in the |
| 1346 | current buffer in Terminal mode. |
| 1347 | Otherwise the same as TextChanged. |
Bram Moolenaar | f0b03c4 | 2017-12-17 17:17:07 +0100 | [diff] [blame] | 1348 | *TextYankPost* |
Bram Moolenaar | 7e1652c | 2017-12-16 18:27:02 +0100 | [diff] [blame] | 1349 | TextYankPost After text has been yanked or deleted in the |
| 1350 | current buffer. The following values of |
| 1351 | |v:event| can be used to determine the operation |
| 1352 | that triggered this autocmd: |
Bram Moolenaar | a016eeb | 2022-04-09 11:37:38 +0100 | [diff] [blame] | 1353 | inclusive TRUE if the motion is |
| 1354 | |inclusive| else the motion is |
| 1355 | |exclusive|. |
Bram Moolenaar | 589edb3 | 2019-09-20 14:38:13 +0200 | [diff] [blame] | 1356 | operator The operation performed. |
| 1357 | regcontents Text that was stored in the |
Bram Moolenaar | 7e1652c | 2017-12-16 18:27:02 +0100 | [diff] [blame] | 1358 | register, as a list of lines, |
| 1359 | like with: > |
| 1360 | getreg(r, 1, 1) |
Bram Moolenaar | 2286304 | 2021-10-16 15:23:36 +0100 | [diff] [blame] | 1361 | < regname Name of the register or empty |
| 1362 | string for the unnamed |
| 1363 | register, see |registers|. |
Bram Moolenaar | 7e1652c | 2017-12-16 18:27:02 +0100 | [diff] [blame] | 1364 | regtype Type of the register, see |
| 1365 | |getregtype()|. |
Bram Moolenaar | 37d1673 | 2020-06-12 22:09:01 +0200 | [diff] [blame] | 1366 | visual True if the operation is |
| 1367 | performed on a |Visual| area. |
Bram Moolenaar | 7e1652c | 2017-12-16 18:27:02 +0100 | [diff] [blame] | 1368 | Not triggered when |quote_| is used nor when |
| 1369 | called recursively. |
| 1370 | It is not allowed to change the buffer text, |
Bram Moolenaar | 6f4754b | 2022-01-23 12:07:04 +0000 | [diff] [blame] | 1371 | see |textlock|. *E1064* |
Jim Zhou | 7db9613 | 2025-03-12 20:57:24 +0100 | [diff] [blame] | 1372 | Also triggered indirectly when Vim tries to |
| 1373 | become owner of the Visual selection because |
| 1374 | of setting "autoselect" for 'guioptions' or |
| 1375 | 'clipboard'. |
Bram Moolenaar | b5b7562 | 2018-03-09 22:22:21 +0100 | [diff] [blame] | 1376 | {only when compiled with the +eval feature} |
Bram Moolenaar | be5ee86 | 2020-06-10 20:56:58 +0200 | [diff] [blame] | 1377 | |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 1378 | *User* |
| 1379 | User Never executed automatically. To be used for |
| 1380 | autocommands that are only executed with |
| 1381 | ":doautocmd". |
Bram Moolenaar | 7dda86f | 2018-04-20 22:36:41 +0200 | [diff] [blame] | 1382 | Note that when `:doautocmd User MyEvent` is |
| 1383 | used while there are no matching autocommands, |
| 1384 | you will get an error. If you don't want |
LemonBoy | 0937182 | 2022-04-08 15:18:45 +0100 | [diff] [blame] | 1385 | that, either check whether an autocommand is |
| 1386 | defined using `exists('#User#MyEvent')` or |
| 1387 | define a dummy autocommand yourself. |
| 1388 | Example: > |
| 1389 | if exists('#User#MyEvent') |
| 1390 | doautocmd User MyEvent |
| 1391 | endif |
Bram Moolenaar | b529cfb | 2022-07-25 15:42:07 +0100 | [diff] [blame] | 1392 | < |
Bram Moolenaar | be5ee86 | 2020-06-10 20:56:58 +0200 | [diff] [blame] | 1393 | *SigUSR1* |
| 1394 | SigUSR1 After the SIGUSR1 signal has been detected. |
| 1395 | Could be used if other ways of notifying Vim |
| 1396 | are not feasible. E.g. to check for the |
| 1397 | result of a build that takes a long time, or |
| 1398 | when a motion sensor is triggered. |
| 1399 | {only on Unix} |
| 1400 | |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 1401 | *UserGettingBored* |
Bram Moolenaar | bf88493 | 2013-04-05 22:26:15 +0200 | [diff] [blame] | 1402 | UserGettingBored When the user presses the same key 42 times. |
| 1403 | Just kidding! :-) |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 1404 | *VimEnter* |
| 1405 | VimEnter After doing all the startup stuff, including |
| 1406 | loading .vimrc files, executing the "-c cmd" |
| 1407 | arguments, creating all windows and loading |
| 1408 | the buffers in them. |
Bram Moolenaar | 1473551 | 2016-03-26 21:00:08 +0100 | [diff] [blame] | 1409 | Just before this event is triggered the |
| 1410 | |v:vim_did_enter| variable is set, so that you |
| 1411 | can do: > |
| 1412 | if v:vim_did_enter |
| 1413 | call s:init() |
| 1414 | else |
Bram Moolenaar | 589edb3 | 2019-09-20 14:38:13 +0200 | [diff] [blame] | 1415 | au VimEnter * call s:init() |
Bram Moolenaar | 1473551 | 2016-03-26 21:00:08 +0100 | [diff] [blame] | 1416 | endif |
| 1417 | < *VimLeave* |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 1418 | VimLeave Before exiting Vim, just after writing the |
| 1419 | .viminfo file. Executed only once, like |
| 1420 | VimLeavePre. |
| 1421 | To detect an abnormal exit use |v:dying|. |
Bram Moolenaar | 0e1e25f | 2010-05-28 21:07:08 +0200 | [diff] [blame] | 1422 | When v:dying is 2 or more this event is not |
| 1423 | triggered. |
Bram Moolenaar | f0068c5 | 2020-11-30 17:42:10 +0100 | [diff] [blame] | 1424 | To get the exit code use |v:exiting|. |
Bram Moolenaar | 4e330bb | 2005-12-07 21:04:31 +0000 | [diff] [blame] | 1425 | *VimLeavePre* |
| 1426 | VimLeavePre Before exiting Vim, just before writing the |
| 1427 | .viminfo file. This is executed only once, |
| 1428 | if there is a match with the name of what |
| 1429 | happens to be the current buffer when exiting. |
| 1430 | Mostly useful with a "*" pattern. > |
| 1431 | :autocmd VimLeavePre * call CleanupStuff() |
| 1432 | < To detect an abnormal exit use |v:dying|. |
Bram Moolenaar | 0e1e25f | 2010-05-28 21:07:08 +0200 | [diff] [blame] | 1433 | When v:dying is 2 or more this event is not |
| 1434 | triggered. |
Bram Moolenaar | f0068c5 | 2020-11-30 17:42:10 +0100 | [diff] [blame] | 1435 | To get the exit code use |v:exiting|. |
Bram Moolenaar | 7d47b6e | 2006-03-15 22:59:18 +0000 | [diff] [blame] | 1436 | *VimResized* |
| 1437 | VimResized After the Vim window was resized, thus 'lines' |
| 1438 | and/or 'columns' changed. Not when starting |
| 1439 | up though. |
Bram Moolenaar | 100118c | 2020-12-11 19:30:34 +0100 | [diff] [blame] | 1440 | *VimResume* |
| 1441 | VimResume When the Vim instance is resumed after being |
| 1442 | suspended and |VimSuspend| was triggered. |
| 1443 | Useful for triggering |:checktime| and ensure |
| 1444 | the buffers content did not change while Vim |
| 1445 | was suspended: > |
| 1446 | :autocmd VimResume * checktime |
| 1447 | < *VimSuspend* |
| 1448 | VimSuspend When the Vim instance is suspended. Only when |
dbivolaru | ab16ad3 | 2021-12-29 19:41:47 +0000 | [diff] [blame] | 1449 | CTRL-Z was typed inside Vim, or when the SIGTSTP |
| 1450 | signal was sent to Vim, but not for SIGSTOP. |
naohiro ono | 23beefe | 2021-11-13 12:38:49 +0000 | [diff] [blame] | 1451 | *WinClosed* |
Bram Moolenaar | b59ae59 | 2022-11-23 23:46:31 +0000 | [diff] [blame] | 1452 | WinClosed When closing a window, just before it is |
| 1453 | removed from the window layout. The pattern |
| 1454 | is matched against the |window-ID|. Both |
naohiro ono | 23beefe | 2021-11-13 12:38:49 +0000 | [diff] [blame] | 1455 | <amatch> and <afile> are set to the |
| 1456 | |window-ID|. Non-recursive (event cannot |
| 1457 | trigger itself). |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1458 | *WinEnter* |
| 1459 | WinEnter After entering another window. Not done for |
| 1460 | the first window, when Vim has just started. |
| 1461 | Useful for setting the window height. |
| 1462 | If the window is for another buffer, Vim |
| 1463 | executes the BufEnter autocommands after the |
| 1464 | WinEnter autocommands. |
Bram Moolenaar | 7dda86f | 2018-04-20 22:36:41 +0200 | [diff] [blame] | 1465 | Note: For split and tabpage commands the |
| 1466 | WinEnter event is triggered after the split |
| 1467 | or tab command but before the file is loaded. |
| 1468 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1469 | *WinLeave* |
| 1470 | WinLeave Before leaving a window. If the window to be |
| 1471 | entered next is for a different buffer, Vim |
| 1472 | executes the BufLeave autocommands before the |
| 1473 | WinLeave autocommands (but not for ":new"). |
| 1474 | Not used for ":qa" or ":q" when exiting Vim. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1475 | |
Sergey Vlasov | 1f47db7 | 2024-01-25 23:07:00 +0100 | [diff] [blame] | 1476 | *WinNewPre* |
| 1477 | WinNewPre Before creating a new window. Triggered |
| 1478 | before commands that modify window layout by |
Christian Brabandt | fb3f969 | 2024-08-11 20:09:17 +0200 | [diff] [blame] | 1479 | creating a split. |
h-east | 90e1fe4 | 2024-08-12 18:26:08 +0200 | [diff] [blame] | 1480 | Not done when creating tab pages and for the |
| 1481 | first window, as the window structure is not |
Christian Brabandt | fb3f969 | 2024-08-11 20:09:17 +0200 | [diff] [blame] | 1482 | initialized yet and so is generally not safe. |
Sergey Vlasov | 1f47db7 | 2024-01-25 23:07:00 +0100 | [diff] [blame] | 1483 | It is not allowed to modify window layout |
| 1484 | while executing commands for the WinNewPre |
| 1485 | event. |
| 1486 | Most useful to store current window layout |
| 1487 | and compare it with the new layout after the |
| 1488 | Window has been created. |
| 1489 | |
Bram Moolenaar | 12c11d5 | 2016-07-19 23:13:03 +0200 | [diff] [blame] | 1490 | *WinNew* |
| 1491 | WinNew When a new window was created. Not done for |
Bram Moolenaar | 50ba526 | 2016-09-22 22:33:02 +0200 | [diff] [blame] | 1492 | the first window, when Vim has just started. |
Bram Moolenaar | 12c11d5 | 2016-07-19 23:13:03 +0200 | [diff] [blame] | 1493 | Before a WinEnter event. |
| 1494 | |
LemonBoy | 0937182 | 2022-04-08 15:18:45 +0100 | [diff] [blame] | 1495 | *WinScrolled* |
Bram Moolenaar | 35fc61c | 2022-11-22 12:40:50 +0000 | [diff] [blame] | 1496 | WinScrolled After any window in the current tab page |
| 1497 | scrolled the text (horizontally or vertically) |
| 1498 | or changed width or height. See |
| 1499 | |win-scrolled-resized|. |
Bram Moolenaar | 0a60f79 | 2022-11-19 21:18:11 +0000 | [diff] [blame] | 1500 | |
Christian Brabandt | b8d5c85 | 2025-04-04 19:11:13 +0200 | [diff] [blame] | 1501 | Note: This can not be skipped with |
| 1502 | `:noautocmd`, because it triggers after |
| 1503 | processing normal commands when Vim is back in |
| 1504 | the main loop. If you want to disable this, |
| 1505 | consider setting the 'eventignore' option |
| 1506 | instead. |
| 1507 | |
Bram Moolenaar | 0a60f79 | 2022-11-19 21:18:11 +0000 | [diff] [blame] | 1508 | The pattern is matched against the |window-ID| |
| 1509 | of the first window that scrolled or resized. |
| 1510 | Both <amatch> and <afile> are set to the |
| 1511 | |window-ID|. |
| 1512 | |
Bram Moolenaar | 35fc61c | 2022-11-22 12:40:50 +0000 | [diff] [blame] | 1513 | |v:event| is set with information about size |
| 1514 | and scroll changes. |WinScrolled-event| |
| 1515 | |
Bram Moolenaar | 0a60f79 | 2022-11-19 21:18:11 +0000 | [diff] [blame] | 1516 | Only starts triggering after startup finished |
| 1517 | and the first screen redraw was done. |
Bram Moolenaar | 35fc61c | 2022-11-22 12:40:50 +0000 | [diff] [blame] | 1518 | Does not trigger when defining the first |
| 1519 | WinScrolled or WinResized event, but may |
| 1520 | trigger when adding more. |
Bram Moolenaar | 0a60f79 | 2022-11-19 21:18:11 +0000 | [diff] [blame] | 1521 | |
| 1522 | Non-recursive: the event will not trigger |
| 1523 | while executing commands for the WinScrolled |
| 1524 | event. However, if the command causes a |
| 1525 | window to scroll or change size, then another |
LemonBoy | 0937182 | 2022-04-08 15:18:45 +0100 | [diff] [blame] | 1526 | WinScrolled event will be triggered later. |
Bram Moolenaar | 0a60f79 | 2022-11-19 21:18:11 +0000 | [diff] [blame] | 1527 | |
Bram Moolenaar | 35fc61c | 2022-11-22 12:40:50 +0000 | [diff] [blame] | 1528 | |
| 1529 | *WinResized* |
| 1530 | WinResized After a window in the current tab page changed |
| 1531 | width or height. |
| 1532 | See |win-scrolled-resized|. |
| 1533 | |
| 1534 | |v:event| is set with information about size |
| 1535 | changes. |WinResized-event| |
| 1536 | |
| 1537 | Same behavior as |WinScrolled| for the |
| 1538 | pattern, triggering and recursiveness. |
LemonBoy | 0937182 | 2022-04-08 15:18:45 +0100 | [diff] [blame] | 1539 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1540 | ============================================================================== |
Bram Moolenaar | fd31be2 | 2022-01-16 14:46:06 +0000 | [diff] [blame] | 1541 | 6. Patterns *autocmd-patterns* *{aupat}* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1542 | |
LemonBoy | 0937182 | 2022-04-08 15:18:45 +0100 | [diff] [blame] | 1543 | The {aupat} argument of `:autocmd` can be a comma-separated list. This works as |
Bram Moolenaar | fd31be2 | 2022-01-16 14:46:06 +0000 | [diff] [blame] | 1544 | if the command was given with each pattern separately. Thus this command: > |
Bram Moolenaar | 5a5f459 | 2015-04-13 12:43:06 +0200 | [diff] [blame] | 1545 | :autocmd BufRead *.txt,*.info set et |
| 1546 | Is equivalent to: > |
| 1547 | :autocmd BufRead *.txt set et |
| 1548 | :autocmd BufRead *.info set et |
| 1549 | |
Bram Moolenaar | fd31be2 | 2022-01-16 14:46:06 +0000 | [diff] [blame] | 1550 | The file pattern {aupat} is tested for a match against the file name in one of |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1551 | two ways: |
| 1552 | 1. When there is no '/' in the pattern, Vim checks for a match against only |
| 1553 | the tail part of the file name (without its leading directory path). |
Bram Moolenaar | 8f3f58f | 2010-01-06 20:52:26 +0100 | [diff] [blame] | 1554 | 2. When there is a '/' in the pattern, Vim checks for a match against both the |
| 1555 | short file name (as you typed it) and the full file name (after expanding |
| 1556 | it to a full path and resolving symbolic links). |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1557 | |
Bram Moolenaar | b5bf5b8 | 2004-12-24 14:35:23 +0000 | [diff] [blame] | 1558 | The special pattern <buffer> or <buffer=N> is used for buffer-local |
| 1559 | autocommands |autocmd-buflocal|. This pattern is not matched against the name |
| 1560 | of a buffer. |
| 1561 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1562 | Examples: > |
| 1563 | :autocmd BufRead *.txt set et |
| 1564 | Set the 'et' option for all text files. > |
| 1565 | |
| 1566 | :autocmd BufRead /vim/src/*.c set cindent |
| 1567 | Set the 'cindent' option for C files in the /vim/src directory. > |
| 1568 | |
| 1569 | :autocmd BufRead /tmp/*.c set ts=5 |
| 1570 | If you have a link from "/tmp/test.c" to "/home/nobody/vim/src/test.c", and |
| 1571 | you start editing "/tmp/test.c", this autocommand will match. |
| 1572 | |
| 1573 | Note: To match part of a path, but not from the root directory, use a '*' as |
| 1574 | the first character. Example: > |
| 1575 | :autocmd BufRead */doc/*.txt set tw=78 |
| 1576 | This autocommand will for example be executed for "/tmp/doc/xx.txt" and |
| 1577 | "/usr/home/piet/doc/yy.txt". The number of directories does not matter here. |
| 1578 | |
| 1579 | |
| 1580 | The file name that the pattern is matched against is after expanding |
Bram Moolenaar | 446cb83 | 2008-06-24 21:56:24 +0000 | [diff] [blame] | 1581 | wildcards. Thus if you issue this command: > |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1582 | :e $ROOTDIR/main.$EXT |
| 1583 | The argument is first expanded to: > |
| 1584 | /usr/root/main.py |
| 1585 | Before it's matched with the pattern of the autocommand. Careful with this |
| 1586 | when using events like FileReadCmd, the value of <amatch> may not be what you |
| 1587 | expect. |
| 1588 | |
| 1589 | |
| 1590 | Environment variables can be used in a pattern: > |
| 1591 | :autocmd BufRead $VIMRUNTIME/doc/*.txt set expandtab |
| 1592 | And ~ can be used for the home directory (if $HOME is defined): > |
| 1593 | :autocmd BufWritePost ~/.vimrc so ~/.vimrc |
| 1594 | :autocmd BufRead ~archive/* set readonly |
| 1595 | The environment variable is expanded when the autocommand is defined, not when |
| 1596 | the autocommand is executed. This is different from the command! |
| 1597 | |
| 1598 | *file-pattern* |
| 1599 | The pattern is interpreted like mostly used in file names: |
Bram Moolenaar | 3b1db36 | 2013-08-10 15:00:24 +0200 | [diff] [blame] | 1600 | * matches any sequence of characters; Unusual: includes path |
Bram Moolenaar | 9d98fe9 | 2013-08-03 18:35:36 +0200 | [diff] [blame] | 1601 | separators |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1602 | ? matches any single character |
| 1603 | \? matches a '?' |
| 1604 | . matches a '.' |
| 1605 | ~ matches a '~' |
| 1606 | , separates patterns |
| 1607 | \, matches a ',' |
| 1608 | { } like \( \) in a |pattern| |
| 1609 | , inside { }: like \| in a |pattern| |
Bram Moolenaar | a946afe | 2013-08-02 15:22:39 +0200 | [diff] [blame] | 1610 | \} literal } |
| 1611 | \{ literal { |
| 1612 | \\\{n,m\} like \{n,m} in a |pattern| |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1613 | \ special meaning like in a |pattern| |
| 1614 | [ch] matches 'c' or 'h' |
| 1615 | [^ch] match any character but 'c' and 'h' |
| 1616 | |
| 1617 | Note that for all systems the '/' character is used for path separator (even |
Bram Moolenaar | 6f345a1 | 2019-12-17 21:27:18 +0100 | [diff] [blame] | 1618 | for MS-Windows). This was done because the backslash is difficult to use in a |
| 1619 | pattern and to make the autocommands portable across different systems. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1620 | |
Bram Moolenaar | 64d8e25 | 2016-09-06 22:12:34 +0200 | [diff] [blame] | 1621 | It is possible to use |pattern| items, but they may not work as expected, |
| 1622 | because of the translation done for the above. |
| 1623 | |
Bram Moolenaar | b5bf5b8 | 2004-12-24 14:35:23 +0000 | [diff] [blame] | 1624 | *autocmd-changes* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1625 | Matching with the pattern is done when an event is triggered. Changing the |
| 1626 | buffer name in one of the autocommands, or even deleting the buffer, does not |
| 1627 | change which autocommands will be executed. Example: > |
| 1628 | |
| 1629 | au BufEnter *.foo bdel |
| 1630 | au BufEnter *.foo set modified |
| 1631 | |
| 1632 | This will delete the current buffer and then set 'modified' in what has become |
| 1633 | the current buffer instead. Vim doesn't take into account that "*.foo" |
| 1634 | doesn't match with that buffer name. It matches "*.foo" with the name of the |
| 1635 | buffer at the moment the event was triggered. |
| 1636 | |
Bram Moolenaar | b5bf5b8 | 2004-12-24 14:35:23 +0000 | [diff] [blame] | 1637 | However, buffer-local autocommands will not be executed for a buffer that has |
| 1638 | been wiped out with |:bwipe|. After deleting the buffer with |:bdel| the |
| 1639 | buffer actually still exists (it becomes unlisted), thus the autocommands are |
| 1640 | still executed. |
| 1641 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1642 | ============================================================================== |
Bram Moolenaar | c9b4b05 | 2006-04-30 18:54:39 +0000 | [diff] [blame] | 1643 | 7. Buffer-local autocommands *autocmd-buflocal* *autocmd-buffer-local* |
| 1644 | *<buffer=N>* *<buffer=abuf>* *E680* |
Bram Moolenaar | b5bf5b8 | 2004-12-24 14:35:23 +0000 | [diff] [blame] | 1645 | |
| 1646 | Buffer-local autocommands are attached to a specific buffer. They are useful |
| 1647 | if the buffer does not have a name and when the name does not match a specific |
| 1648 | pattern. But it also means they must be explicitly added to each buffer. |
| 1649 | |
| 1650 | Instead of a pattern buffer-local autocommands use one of these forms: |
| 1651 | <buffer> current buffer |
| 1652 | <buffer=99> buffer number 99 |
| 1653 | <buffer=abuf> using <abuf> (only when executing autocommands) |
| 1654 | |<abuf>| |
| 1655 | |
| 1656 | Examples: > |
| 1657 | :au CursorHold <buffer> echo 'hold' |
| 1658 | :au CursorHold <buffer=33> echo 'hold' |
Bram Moolenaar | 88774fd | 2015-08-25 19:52:04 +0200 | [diff] [blame] | 1659 | :au BufNewFile * au CursorHold <buffer=abuf> echo 'hold' |
Bram Moolenaar | b5bf5b8 | 2004-12-24 14:35:23 +0000 | [diff] [blame] | 1660 | |
| 1661 | All the commands for autocommands also work with buffer-local autocommands, |
| 1662 | simply use the special string instead of the pattern. Examples: > |
Bram Moolenaar | c9b4b05 | 2006-04-30 18:54:39 +0000 | [diff] [blame] | 1663 | :au! * <buffer> " remove buffer-local autocommands for |
| 1664 | " current buffer |
| 1665 | :au! * <buffer=33> " remove buffer-local autocommands for |
| 1666 | " buffer #33 |
Bram Moolenaar | 446cb83 | 2008-06-24 21:56:24 +0000 | [diff] [blame] | 1667 | :bufdo :au! CursorHold <buffer> " remove autocmd for given event for all |
Bram Moolenaar | c9b4b05 | 2006-04-30 18:54:39 +0000 | [diff] [blame] | 1668 | " buffers |
| 1669 | :au * <buffer> " list buffer-local autocommands for |
| 1670 | " current buffer |
Bram Moolenaar | b5bf5b8 | 2004-12-24 14:35:23 +0000 | [diff] [blame] | 1671 | |
| 1672 | Note that when an autocommand is defined for the current buffer, it is stored |
| 1673 | with the buffer number. Thus it uses the form "<buffer=12>", where 12 is the |
| 1674 | number of the current buffer. You will see this when listing autocommands, |
| 1675 | for example. |
| 1676 | |
| 1677 | To test for presence of buffer-local autocommands use the |exists()| function |
| 1678 | as follows: > |
| 1679 | :if exists("#CursorHold#<buffer=12>") | ... | endif |
| 1680 | :if exists("#CursorHold#<buffer>") | ... | endif " for current buffer |
| 1681 | |
| 1682 | When a buffer is wiped out its buffer-local autocommands are also gone, of |
| 1683 | course. Note that when deleting a buffer, e.g., with ":bdel", it is only |
| 1684 | unlisted, the autocommands are still present. In order to see the removal of |
| 1685 | buffer-local autocommands: > |
| 1686 | :set verbose=6 |
| 1687 | |
| 1688 | It is not possible to define buffer-local autocommands for a non-existent |
| 1689 | buffer. |
| 1690 | |
| 1691 | ============================================================================== |
| 1692 | 8. Groups *autocmd-groups* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1693 | |
| 1694 | Autocommands can be put together in a group. This is useful for removing or |
| 1695 | executing a group of autocommands. For example, all the autocommands for |
| 1696 | syntax highlighting are put in the "highlight" group, to be able to execute |
| 1697 | ":doautoall highlight BufRead" when the GUI starts. |
| 1698 | |
| 1699 | When no specific group is selected, Vim uses the default group. The default |
| 1700 | group does not have a name. You cannot execute the autocommands from the |
| 1701 | default group separately; you can execute them only by executing autocommands |
| 1702 | for all groups. |
| 1703 | |
| 1704 | Normally, when executing autocommands automatically, Vim uses the autocommands |
| 1705 | for all groups. The group only matters when executing autocommands with |
| 1706 | ":doautocmd" or ":doautoall", or when defining or deleting autocommands. |
| 1707 | |
| 1708 | The group name can contain any characters except white space. The group name |
| 1709 | "end" is reserved (also in uppercase). |
| 1710 | |
| 1711 | The group name is case sensitive. Note that this is different from the event |
| 1712 | name! |
| 1713 | |
| 1714 | *:aug* *:augroup* |
| 1715 | :aug[roup] {name} Define the autocmd group name for the |
| 1716 | following ":autocmd" commands. The name "end" |
| 1717 | or "END" selects the default group. |
Bram Moolenaar | 256972a | 2015-12-29 19:10:25 +0100 | [diff] [blame] | 1718 | To avoid confusion, the name should be |
| 1719 | different from existing {event} names, as this |
| 1720 | most likely will not do what you intended. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1721 | |
Bram Moolenaar | 64d8e25 | 2016-09-06 22:12:34 +0200 | [diff] [blame] | 1722 | *:augroup-delete* *E367* *W19* *E936* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1723 | :aug[roup]! {name} Delete the autocmd group {name}. Don't use |
| 1724 | this if there is still an autocommand using |
Bram Moolenaar | bc8801c | 2016-08-02 21:04:33 +0200 | [diff] [blame] | 1725 | this group! You will get a warning if doing |
Bram Moolenaar | e7b1ea0 | 2020-08-07 19:54:59 +0200 | [diff] [blame] | 1726 | it anyway. When the group is the current |
| 1727 | group you will get error E936. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1728 | |
| 1729 | To enter autocommands for a specific group, use this method: |
| 1730 | 1. Select the group with ":augroup {name}". |
| 1731 | 2. Delete any old autocommands with ":au!". |
| 1732 | 3. Define the autocommands. |
| 1733 | 4. Go back to the default group with "augroup END". |
| 1734 | |
| 1735 | Example: > |
| 1736 | :augroup uncompress |
| 1737 | : au! |
| 1738 | : au BufEnter *.gz %!gunzip |
| 1739 | :augroup END |
| 1740 | |
| 1741 | This prevents having the autocommands defined twice (e.g., after sourcing the |
| 1742 | .vimrc file again). |
| 1743 | |
Bram Moolenaar | 6e64922 | 2021-10-04 21:32:54 +0100 | [diff] [blame] | 1744 | *FileExplorer* |
| 1745 | There is one group that is recognized by Vim: FileExplorer. If this group |
| 1746 | exists Vim assumes that editing a directory is possible and will trigger a |
| 1747 | plugin that lists the files in that directory. This is used by the |netrw| |
| 1748 | plugin. This allows you to do: > |
| 1749 | browse edit |
| 1750 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1751 | ============================================================================== |
Bram Moolenaar | b5bf5b8 | 2004-12-24 14:35:23 +0000 | [diff] [blame] | 1752 | 9. Executing autocommands *autocmd-execute* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1753 | |
| 1754 | Vim can also execute Autocommands non-automatically. This is useful if you |
| 1755 | have changed autocommands, or when Vim has executed the wrong autocommands |
| 1756 | (e.g., the file pattern match was wrong). |
| 1757 | |
| 1758 | Note that the 'eventignore' option applies here too. Events listed in this |
| 1759 | option will not cause any commands to be executed. |
| 1760 | |
Bram Moolenaar | 61da1bf | 2019-06-06 12:14:49 +0200 | [diff] [blame] | 1761 | *:do* *:doau* *:doaut* *:doautocmd* *E217* |
Bram Moolenaar | 5dc6252 | 2012-02-13 00:05:22 +0100 | [diff] [blame] | 1762 | :do[autocmd] [<nomodeline>] [group] {event} [fname] |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1763 | Apply the autocommands matching [fname] (default: |
| 1764 | current file name) for {event} to the current buffer. |
| 1765 | You can use this when the current file name does not |
| 1766 | match the right pattern, after changing settings, or |
| 1767 | to execute autocommands for a certain event. |
| 1768 | It's possible to use this inside an autocommand too, |
| 1769 | so you can base the autocommands for one extension on |
| 1770 | another extension. Example: > |
Bram Moolenaar | f1568ec | 2011-12-14 21:17:39 +0100 | [diff] [blame] | 1771 | :au BufEnter *.cpp so ~/.vimrc_cpp |
| 1772 | :au BufEnter *.cpp doau BufEnter x.c |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1773 | < Be careful to avoid endless loops. See |
| 1774 | |autocmd-nested|. |
| 1775 | |
| 1776 | When the [group] argument is not given, Vim executes |
| 1777 | the autocommands for all groups. When the [group] |
| 1778 | argument is included, Vim executes only the matching |
| 1779 | autocommands for that group. Note: if you use an |
| 1780 | undefined group name, Vim gives you an error message. |
Bram Moolenaar | 60542ac | 2012-02-12 20:14:01 +0100 | [diff] [blame] | 1781 | *<nomodeline>* |
| 1782 | After applying the autocommands the modelines are |
| 1783 | processed, so that their settings overrule the |
| 1784 | settings from autocommands, like what happens when |
| 1785 | editing a file. This is skipped when the <nomodeline> |
| 1786 | argument is present. You probably want to use |
| 1787 | <nomodeline> for events that are not used when loading |
| 1788 | a buffer, such as |User|. |
Bram Moolenaar | c95a302 | 2016-06-12 23:01:46 +0200 | [diff] [blame] | 1789 | Processing modelines is also skipped when no |
| 1790 | matching autocommands were executed. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1791 | |
| 1792 | *:doautoa* *:doautoall* |
Bram Moolenaar | a61d5fb | 2012-02-12 00:18:58 +0100 | [diff] [blame] | 1793 | :doautoa[ll] [<nomodeline>] [group] {event} [fname] |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1794 | Like ":doautocmd", but apply the autocommands to each |
Bram Moolenaar | dad4473 | 2021-03-31 20:07:33 +0200 | [diff] [blame] | 1795 | loaded buffer. The current buffer is done last. |
| 1796 | |
| 1797 | Note that [fname] is used to select the autocommands, |
Bram Moolenaar | 4c29502 | 2021-05-02 17:19:11 +0200 | [diff] [blame] | 1798 | not the buffers to which they are applied. Example: > |
| 1799 | augroup mine |
| 1800 | autocmd! |
| 1801 | autocmd FileType * echo expand('<amatch>') |
| 1802 | augroup END |
| 1803 | doautoall mine FileType Loaded-Buffer |
| 1804 | < Sourcing this script, you'll see as many |
| 1805 | "Loaded-Buffer" echoed as there are loaded buffers. |
Bram Moolenaar | dad4473 | 2021-03-31 20:07:33 +0200 | [diff] [blame] | 1806 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1807 | Careful: Don't use this for autocommands that delete a |
| 1808 | buffer, change to another buffer or change the |
| 1809 | contents of a buffer; the result is unpredictable. |
| 1810 | This command is intended for autocommands that set |
| 1811 | options, change highlighting, and things like that. |
| 1812 | |
| 1813 | ============================================================================== |
Bram Moolenaar | b5bf5b8 | 2004-12-24 14:35:23 +0000 | [diff] [blame] | 1814 | 10. Using autocommands *autocmd-use* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1815 | |
| 1816 | For WRITING FILES there are four possible sets of events. Vim uses only one |
| 1817 | of these sets for a write command: |
| 1818 | |
| 1819 | BufWriteCmd BufWritePre BufWritePost writing the whole buffer |
| 1820 | FilterWritePre FilterWritePost writing to filter temp file |
| 1821 | FileAppendCmd FileAppendPre FileAppendPost appending to a file |
| 1822 | FileWriteCmd FileWritePre FileWritePost any other file write |
| 1823 | |
| 1824 | When there is a matching "*Cmd" autocommand, it is assumed it will do the |
| 1825 | writing. No further writing is done and the other events are not triggered. |
| 1826 | |Cmd-event| |
| 1827 | |
| 1828 | Note that the *WritePost commands should undo any changes to the buffer that |
| 1829 | were caused by the *WritePre commands; otherwise, writing the file will have |
| 1830 | the side effect of changing the buffer. |
| 1831 | |
| 1832 | Before executing the autocommands, the buffer from which the lines are to be |
| 1833 | written temporarily becomes the current buffer. Unless the autocommands |
| 1834 | change the current buffer or delete the previously current buffer, the |
| 1835 | previously current buffer is made the current buffer again. |
| 1836 | |
| 1837 | The *WritePre and *AppendPre autocommands must not delete the buffer from |
| 1838 | which the lines are to be written. |
| 1839 | |
| 1840 | The '[ and '] marks have a special position: |
| 1841 | - Before the *ReadPre event the '[ mark is set to the line just above where |
| 1842 | the new lines will be inserted. |
| 1843 | - Before the *ReadPost event the '[ mark is set to the first line that was |
| 1844 | just read, the '] mark to the last line. |
Bram Moolenaar | 3fdfa4a | 2004-10-07 21:02:47 +0000 | [diff] [blame] | 1845 | - Before executing the *WriteCmd, *WritePre and *AppendPre autocommands the '[ |
| 1846 | mark is set to the first line that will be written, the '] mark to the last |
| 1847 | line. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1848 | Careful: '[ and '] change when using commands that change the buffer. |
| 1849 | |
| 1850 | In commands which expect a file name, you can use "<afile>" for the file name |
| 1851 | that is being read |:<afile>| (you can also use "%" for the current file |
| 1852 | name). "<abuf>" can be used for the buffer number of the currently effective |
Bram Moolenaar | d2f3a8b | 2018-06-19 14:35:59 +0200 | [diff] [blame] | 1853 | buffer. This also works for buffers that don't have a name. But it doesn't |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1854 | work for files without a buffer (e.g., with ":r file"). |
| 1855 | |
| 1856 | *gzip-example* |
| 1857 | Examples for reading and writing compressed files: > |
| 1858 | :augroup gzip |
| 1859 | : autocmd! |
| 1860 | : autocmd BufReadPre,FileReadPre *.gz set bin |
| 1861 | : autocmd BufReadPost,FileReadPost *.gz '[,']!gunzip |
| 1862 | : autocmd BufReadPost,FileReadPost *.gz set nobin |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 1863 | : autocmd BufReadPost,FileReadPost *.gz execute ":doautocmd BufReadPost " .. expand("%:r") |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1864 | : autocmd BufWritePost,FileWritePost *.gz !mv <afile> <afile>:r |
| 1865 | : autocmd BufWritePost,FileWritePost *.gz !gzip <afile>:r |
| 1866 | |
| 1867 | : autocmd FileAppendPre *.gz !gunzip <afile> |
| 1868 | : autocmd FileAppendPre *.gz !mv <afile>:r <afile> |
| 1869 | : autocmd FileAppendPost *.gz !mv <afile> <afile>:r |
| 1870 | : autocmd FileAppendPost *.gz !gzip <afile>:r |
| 1871 | :augroup END |
| 1872 | |
| 1873 | The "gzip" group is used to be able to delete any existing autocommands with |
| 1874 | ":autocmd!", for when the file is sourced twice. |
| 1875 | |
| 1876 | ("<afile>:r" is the file name without the extension, see |:_%:|) |
| 1877 | |
| 1878 | The commands executed for the BufNewFile, BufRead/BufReadPost, BufWritePost, |
| 1879 | FileAppendPost and VimLeave events do not set or reset the changed flag of the |
| 1880 | buffer. When you decompress the buffer with the BufReadPost autocommands, you |
| 1881 | can still exit with ":q". When you use ":undo" in BufWritePost to undo the |
| 1882 | changes made by BufWritePre commands, you can still do ":q" (this also makes |
| 1883 | "ZZ" work). If you do want the buffer to be marked as modified, set the |
| 1884 | 'modified' option. |
| 1885 | |
| 1886 | To execute Normal mode commands from an autocommand, use the ":normal" |
| 1887 | command. Use with care! If the Normal mode command is not finished, the user |
| 1888 | needs to type characters (e.g., after ":normal m" you need to type a mark |
| 1889 | name). |
| 1890 | |
| 1891 | If you want the buffer to be unmodified after changing it, reset the |
| 1892 | 'modified' option. This makes it possible to exit the buffer with ":q" |
| 1893 | instead of ":q!". |
| 1894 | |
| 1895 | *autocmd-nested* *E218* |
Bram Moolenaar | 2696761 | 2019-03-17 17:13:16 +0100 | [diff] [blame] | 1896 | By default, autocommands do not nest. For example, if you use ":e" or ":w" in |
| 1897 | an autocommand, Vim does not execute the BufRead and BufWrite autocommands for |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1898 | those commands. If you do want this, use the "nested" flag for those commands |
| 1899 | in which you want nesting. For example: > |
Bram Moolenaar | eb93f3f | 2019-04-04 15:04:56 +0200 | [diff] [blame] | 1900 | :autocmd FileChangedShell *.c ++nested e! |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1901 | The nesting is limited to 10 levels to get out of recursive loops. |
| 1902 | |
| 1903 | It's possible to use the ":au" command in an autocommand. This can be a |
| 1904 | self-modifying command! This can be useful for an autocommand that should |
| 1905 | execute only once. |
| 1906 | |
Bram Moolenaar | b348038 | 2005-12-11 21:33:32 +0000 | [diff] [blame] | 1907 | If you want to skip autocommands for one command, use the |:noautocmd| command |
| 1908 | modifier or the 'eventignore' option. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1909 | |
| 1910 | Note: When reading a file (with ":read file" or with a filter command) and the |
| 1911 | last line in the file does not have an <EOL>, Vim remembers this. At the next |
| 1912 | write (with ":write file" or with a filter command), if the same line is |
| 1913 | written again as the last line in a file AND 'binary' is set, Vim does not |
| 1914 | supply an <EOL>. This makes a filter command on the just read lines write the |
| 1915 | same file as was read, and makes a write command on just filtered lines write |
| 1916 | the same file as was read from the filter. For example, another way to write |
| 1917 | a compressed file: > |
| 1918 | |
| 1919 | :autocmd FileWritePre *.gz set bin|'[,']!gzip |
| 1920 | :autocmd FileWritePost *.gz undo|set nobin |
| 1921 | < |
| 1922 | *autocommand-pattern* |
| 1923 | You can specify multiple patterns, separated by commas. Here are some |
| 1924 | examples: > |
| 1925 | |
| 1926 | :autocmd BufRead * set tw=79 nocin ic infercase fo=2croq |
| 1927 | :autocmd BufRead .letter set tw=72 fo=2tcrq |
| 1928 | :autocmd BufEnter .letter set dict=/usr/lib/dict/words |
| 1929 | :autocmd BufLeave .letter set dict= |
| 1930 | :autocmd BufRead,BufNewFile *.c,*.h set tw=0 cin noic |
| 1931 | :autocmd BufEnter *.c,*.h abbr FOR for (i = 0; i < 3; ++i)<CR>{<CR>}<Esc>O |
| 1932 | :autocmd BufLeave *.c,*.h unabbr FOR |
| 1933 | |
| 1934 | For makefiles (makefile, Makefile, imakefile, makefile.unix, etc.): > |
| 1935 | |
| 1936 | :autocmd BufEnter ?akefile* set include=^s\=include |
| 1937 | :autocmd BufLeave ?akefile* set include& |
| 1938 | |
| 1939 | To always start editing C files at the first function: > |
| 1940 | |
| 1941 | :autocmd BufRead *.c,*.h 1;/^{ |
| 1942 | |
| 1943 | Without the "1;" above, the search would start from wherever the file was |
| 1944 | entered, rather than from the start of the file. |
| 1945 | |
| 1946 | *skeleton* *template* |
| 1947 | To read a skeleton (template) file when opening a new file: > |
| 1948 | |
| 1949 | :autocmd BufNewFile *.c 0r ~/vim/skeleton.c |
| 1950 | :autocmd BufNewFile *.h 0r ~/vim/skeleton.h |
| 1951 | :autocmd BufNewFile *.java 0r ~/vim/skeleton.java |
| 1952 | |
| 1953 | To insert the current date and time in a *.html file when writing it: > |
| 1954 | |
| 1955 | :autocmd BufWritePre,FileWritePre *.html ks|call LastMod()|'s |
| 1956 | :fun LastMod() |
| 1957 | : if line("$") > 20 |
| 1958 | : let l = 20 |
| 1959 | : else |
| 1960 | : let l = line("$") |
| 1961 | : endif |
Bram Moolenaar | c51cf03 | 2022-02-26 12:25:45 +0000 | [diff] [blame] | 1962 | : exe "1," .. l .. "g/Last modified: /s/Last modified: .*/Last modified: " .. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1963 | : \ strftime("%Y %b %d") |
| 1964 | :endfun |
| 1965 | |
| 1966 | You need to have a line "Last modified: <date time>" in the first 20 lines |
| 1967 | of the file for this to work. Vim replaces <date time> (and anything in the |
| 1968 | same line after it) with the current date and time. Explanation: |
| 1969 | ks mark current position with mark 's' |
| 1970 | call LastMod() call the LastMod() function to do the work |
| 1971 | 's return the cursor to the old position |
| 1972 | The LastMod() function checks if the file is shorter than 20 lines, and then |
| 1973 | uses the ":g" command to find lines that contain "Last modified: ". For those |
| 1974 | lines the ":s" command is executed to replace the existing date with the |
| 1975 | current one. The ":execute" command is used to be able to use an expression |
| 1976 | for the ":g" and ":s" commands. The date is obtained with the strftime() |
| 1977 | function. You can change its argument to get another date string. |
| 1978 | |
| 1979 | When entering :autocmd on the command-line, completion of events and command |
| 1980 | names may be done (with <Tab>, CTRL-D, etc.) where appropriate. |
| 1981 | |
| 1982 | Vim executes all matching autocommands in the order that you specify them. |
| 1983 | It is recommended that your first autocommand be used for all files by using |
| 1984 | "*" as the file pattern. This means that you can define defaults you like |
| 1985 | here for any settings, and if there is another matching autocommand it will |
| 1986 | override these. But if there is no other matching autocommand, then at least |
| 1987 | your default settings are recovered (if entering this file from another for |
| 1988 | which autocommands did match). Note that "*" will also match files starting |
| 1989 | with ".", unlike Unix shells. |
| 1990 | |
| 1991 | *autocmd-searchpat* |
| 1992 | Autocommands do not change the current search patterns. Vim saves the current |
| 1993 | search patterns before executing autocommands then restores them after the |
| 1994 | autocommands finish. This means that autocommands do not affect the strings |
| 1995 | highlighted with the 'hlsearch' option. Within autocommands, you can still |
| 1996 | use search patterns normally, e.g., with the "n" command. |
| 1997 | If you want an autocommand to set the search pattern, such that it is used |
| 1998 | after the autocommand finishes, use the ":let @/ =" command. |
| 1999 | The search-highlighting cannot be switched off with ":nohlsearch" in an |
| 2000 | autocommand. Use the 'h' flag in the 'viminfo' option to disable search- |
| 2001 | highlighting when starting Vim. |
| 2002 | |
| 2003 | *Cmd-event* |
| 2004 | When using one of the "*Cmd" events, the matching autocommands are expected to |
Bram Moolenaar | 8dd1aa5 | 2007-01-16 20:33:19 +0000 | [diff] [blame] | 2005 | do the file reading, writing or sourcing. This can be used when working with |
| 2006 | a special kind of file, for example on a remote system. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 2007 | CAREFUL: If you use these events in a wrong way, it may have the effect of |
| 2008 | making it impossible to read or write the matching files! Make sure you test |
| 2009 | your autocommands properly. Best is to use a pattern that will never match a |
| 2010 | normal file name, for example "ftp://*". |
| 2011 | |
| 2012 | When defining a BufReadCmd it will be difficult for Vim to recover a crashed |
| 2013 | editing session. When recovering from the original file, Vim reads only those |
| 2014 | parts of a file that are not found in the swap file. Since that is not |
| 2015 | possible with a BufReadCmd, use the |:preserve| command to make sure the |
| 2016 | original file isn't needed for recovery. You might want to do this only when |
| 2017 | you expect the file to be modified. |
| 2018 | |
Bram Moolenaar | 8dd1aa5 | 2007-01-16 20:33:19 +0000 | [diff] [blame] | 2019 | For file read and write commands the |v:cmdarg| variable holds the "++enc=" |
| 2020 | and "++ff=" argument that are effective. These should be used for the command |
| 2021 | that reads/writes the file. The |v:cmdbang| variable is one when "!" was |
| 2022 | used, zero otherwise. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 2023 | |
Bram Moolenaar | c88ebf7 | 2010-07-22 22:30:23 +0200 | [diff] [blame] | 2024 | See the $VIMRUNTIME/plugin/netrwPlugin.vim for examples. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 2025 | |
Bram Moolenaar | b348038 | 2005-12-11 21:33:32 +0000 | [diff] [blame] | 2026 | ============================================================================== |
| 2027 | 11. Disabling autocommands *autocmd-disable* |
| 2028 | |
| 2029 | To disable autocommands for some time use the 'eventignore' option. Note that |
| 2030 | this may cause unexpected behavior, make sure you restore 'eventignore' |
| 2031 | afterwards, using a |:try| block with |:finally|. |
| 2032 | |
Luuk van Baal | b7147f8 | 2025-02-08 18:52:39 +0100 | [diff] [blame] | 2033 | To disable autocmds indefinitely in a specific window use the 'eventignorewin' |
| 2034 | option. This can only be used to ignore window and buffer related events. |
| 2035 | |
Bram Moolenaar | b348038 | 2005-12-11 21:33:32 +0000 | [diff] [blame] | 2036 | *:noautocmd* *:noa* |
| 2037 | To disable autocommands for just one command use the ":noautocmd" command |
| 2038 | modifier. This will set 'eventignore' to "all" for the duration of the |
| 2039 | following command. Example: > |
| 2040 | |
| 2041 | :noautocmd w fname.gz |
| 2042 | |
| 2043 | This will write the file without triggering the autocommands defined by the |
| 2044 | gzip plugin. |
| 2045 | |
Bram Moolenaar | 2696761 | 2019-03-17 17:13:16 +0100 | [diff] [blame] | 2046 | Note that some autocommands are not triggered right away, but only later. |
| 2047 | This specifically applies to |CursorMoved| and |TextChanged|. |
| 2048 | |
Bram Moolenaar | b5bf5b8 | 2004-12-24 14:35:23 +0000 | [diff] [blame] | 2049 | |
Bram Moolenaar | 91f84f6 | 2018-07-29 15:07:52 +0200 | [diff] [blame] | 2050 | vim:tw=78:ts=8:noet:ft=help:norl: |