summaryrefslogtreecommitdiffstats
path: root/runtime/doc/autocmd.txt
diff options
context:
space:
mode:
Diffstat (limited to 'runtime/doc/autocmd.txt')
-rw-r--r--runtime/doc/autocmd.txt1921
1 files changed, 1921 insertions, 0 deletions
diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
new file mode 100644
index 0000000..04f0191
--- /dev/null
+++ b/runtime/doc/autocmd.txt
@@ -0,0 +1,1921 @@
+*autocmd.txt* For Vim version 9.0. Last change: 2023 Feb 18
+
+
+ VIM REFERENCE MANUAL by Bram Moolenaar
+
+
+Automatic commands *autocommand* *autocommands*
+
+For a basic explanation, see section |40.3| in the user manual.
+
+1. Introduction |autocmd-intro|
+2. Defining autocommands |autocmd-define|
+3. Removing autocommands |autocmd-remove|
+4. Listing autocommands |autocmd-list|
+5. Events |autocmd-events|
+6. Patterns |autocmd-patterns|
+7. Buffer-local autocommands |autocmd-buflocal|
+8. Groups |autocmd-groups|
+9. Executing autocommands |autocmd-execute|
+10. Using autocommands |autocmd-use|
+11. Disabling autocommands |autocmd-disable|
+
+
+==============================================================================
+1. Introduction *autocmd-intro*
+
+You can specify commands to be executed automatically when reading or writing
+a file, when entering or leaving a buffer or window, and when exiting Vim.
+For example, you can create an autocommand to set the 'cindent' option for
+files matching *.c. You can also use autocommands to implement advanced
+features, such as editing compressed files (see |gzip-example|). The usual
+place to put autocommands is in your .vimrc or .exrc file.
+
+ *E203* *E204* *E143* *E855* *E937* *E952*
+WARNING: Using autocommands is very powerful, and may lead to unexpected side
+effects. Be careful not to destroy your text.
+- It's a good idea to do some testing on an expendable copy of a file first.
+ For example: If you use autocommands to decompress a file when starting to
+ edit it, make sure that the autocommands for compressing when writing work
+ correctly.
+- Be prepared for an error halfway through (e.g., disk full). Vim will mostly
+ be able to undo the changes to the buffer, but you may have to clean up the
+ changes to other files by hand (e.g., compress a file that has been
+ decompressed).
+- If the BufRead* events allow you to edit a compressed file, the FileRead*
+ events should do the same (this makes recovery possible in some rare cases).
+ It's a good idea to use the same autocommands for the File* and Buf* events
+ when possible.
+
+Recommended use:
+- Always use a group, so that it's easy to delete the autocommand.
+- Keep the command itself short, call a function to do more work.
+- Make it so that the script it is defined in can be sourced several times
+ without the autocommand being repeated.
+
+Example in Vim9 script: >
+ autocmd_add({replace: true,
+ group: 'DemoGroup',
+ event: 'BufEnter',
+ pattern: '*.txt',
+ cmd: 'call DemoBufEnter()'
+ })
+
+In legacy script: >
+ call autocmd_add(#{replace: v:true,
+ \ group: 'DemoGroup',
+ \ event: 'BufEnter',
+ \ pattern: '*.txt',
+ \ cmd: 'call DemoBufEnter()'
+ \ })
+
+==============================================================================
+2. Defining autocommands *autocmd-define*
+
+ *:au* *:autocmd*
+:au[tocmd] [group] {event} {aupat} [++once] [++nested] {cmd}
+ Add {cmd} to the list of commands that Vim will
+ execute automatically on {event} for a file matching
+ {aupat} |autocmd-patterns|.
+ Here {event} cannot be "*". *E1155*
+ Note: A quote character is seen as argument to the
+ :autocmd and won't start a comment.
+ Vim always adds the {cmd} after existing autocommands,
+ so that the autocommands execute in the order in which
+ they were given.
+ See |autocmd-nested| for [++nested]. "nested"
+ (without the ++) can also be used, for backwards
+ compatibility, but not in |Vim9| script. *E1078*
+ *autocmd-once*
+ If [++once] is supplied the command is executed once,
+ then removed ("one shot").
+
+The special pattern <buffer> or <buffer=N> defines a buffer-local autocommand.
+See |autocmd-buflocal|.
+
+If the `:autocmd` is in Vim9 script (a script that starts with `:vim9script`
+and in a `:def` function) then {cmd} will be executed as in Vim9
+script. Thus this depends on where the autocmd is defined, not where it is
+triggered.
+ *:autocmd-block*
+{cmd} can be a block, like with `:command`, see |:command-repl|. Example: >
+ au BufReadPost *.xml {
+ setlocal matchpairs+=<:>
+ /<start
+ }
+
+The |autocmd_add()| function can be used to add a list of autocmds and autocmd
+groups from a Vim script. It is preferred if you have anything that would
+require using `:execute` with `:autocmd`.
+
+Note: The ":autocmd" command can only be followed by another command when the
+'|' appears where the pattern is expected. This works: >
+ :augroup mine | au! BufRead | augroup END
+But this sees "augroup" as part of the defined command: >
+ :augroup mine | au! BufRead * | augroup END
+ :augroup mine | au BufRead * set tw=70 | augroup END
+Instead you can put the group name into the command: >
+ :au! mine BufRead *
+ :au mine BufRead * set tw=70
+Or use `:execute`: >
+ :augroup mine | exe "au! BufRead *" | augroup END
+ :augroup mine | exe "au BufRead * set tw=70" | augroup END
+
+< *autocmd-expand*
+Note that special characters (e.g., "%", "<cword>") in the ":autocmd"
+arguments are not expanded when the autocommand is defined. These will be
+expanded when the Event is recognized, and the {cmd} is executed. The only
+exception is that "<sfile>" is expanded when the autocmd is defined. Example:
+>
+ :au BufNewFile,BufRead *.html so <sfile>:h/html.vim
+
+Here Vim expands <sfile> to the name of the file containing this line.
+
+`:autocmd` adds to the list of autocommands regardless of whether they are
+already present. When your .vimrc file is sourced twice, the autocommands
+will appear twice. To avoid this, define your autocommands in a group, so
+that you can easily clear them: >
+
+ augroup vimrc
+ " Remove all vimrc autocommands
+ autocmd!
+ au BufNewFile,BufRead *.html so <sfile>:h/html.vim
+ augroup END
+
+If you don't want to remove all autocommands, you can instead use a variable
+to ensure that Vim includes the autocommands only once: >
+
+ :if !exists("autocommands_loaded")
+ : let autocommands_loaded = 1
+ : au ...
+ :endif
+
+When the [group] argument is not given, Vim uses the current group (as defined
+with ":augroup"); otherwise, Vim uses the group defined with [group]. Note
+that [group] must have been defined before. You cannot define a new group
+with ":au group ..."; use ":augroup" for that.
+
+While testing autocommands, you might find the 'verbose' option to be useful: >
+ :set verbose=9
+This setting makes Vim echo the autocommands as it executes them.
+
+When defining an autocommand in a script, it will be able to call functions
+local to the script and use mappings local to the script. When the event is
+triggered and the command executed, it will run in the context of the script
+it was defined in. This matters if |<SID>| is used in a command.
+
+When executing the commands, the message from one command overwrites a
+previous message. This is different from when executing the commands
+manually. Mostly the screen will not scroll up, thus there is no hit-enter
+prompt. When one command outputs two messages this can happen anyway.
+
+==============================================================================
+3. Removing autocommands *autocmd-remove*
+
+In addition to the below described commands, the |autocmd_delete()| function can
+be used to remove a list of autocmds and autocmd groups from a Vim script.
+
+:au[tocmd]! [group] {event} {aupat} [++once] [++nested] {cmd}
+ Remove all autocommands associated with {event} and
+ {aupat}, and add the command {cmd}.
+ See |autocmd-once| for [++once].
+ See |autocmd-nested| for [++nested].
+
+:au[tocmd]! [group] {event} {aupat}
+ Remove all autocommands associated with {event} and
+ {aupat}.
+
+:au[tocmd]! [group] * {aupat}
+ Remove all autocommands associated with {aupat} for
+ all events.
+
+:au[tocmd]! [group] {event}
+ Remove ALL autocommands for {event}.
+ Warning: You should not do this without a group for
+ |BufRead| and other common events, it can break
+ plugins, syntax highlighting, etc.
+
+:au[tocmd]! [group] Remove ALL autocommands.
+ Note: a quote will be seen as argument to the :autocmd
+ and won't start a comment.
+ Warning: You should normally not do this without a
+ group, it breaks plugins, syntax highlighting, etc.
+
+When the [group] argument is not given, Vim uses the current group (as defined
+with ":augroup"); otherwise, Vim uses the group defined with [group].
+
+==============================================================================
+4. Listing autocommands *autocmd-list*
+
+:au[tocmd] [group] {event} {aupat}
+ Show the autocommands associated with {event} and
+ {aupat}.
+
+:au[tocmd] [group] * {aupat}
+ Show the autocommands associated with {aupat} for all
+ events.
+
+:au[tocmd] [group] {event}
+ Show all autocommands for {event}.
+
+:au[tocmd] [group] Show all autocommands.
+
+If you provide the [group] argument, Vim lists only the autocommands for
+[group]; otherwise, Vim lists the autocommands for ALL groups. Note that this
+argument behavior differs from that for defining and removing autocommands.
+
+In order to list buffer-local autocommands, use a pattern in the form <buffer>
+or <buffer=N>. See |autocmd-buflocal|.
+
+The |autocmd_get()| function can be used from a Vim script to get a list of
+autocmds.
+
+ *:autocmd-verbose*
+When 'verbose' is non-zero, listing an autocommand will also display where it
+was last defined. Example: >
+
+ :verbose autocmd BufEnter
+ FileExplorer BufEnter
+ * call s:LocalBrowse(expand("<amatch>"))
+ Last set from /usr/share/vim/vim-7.0/plugin/NetrwPlugin.vim
+<
+See |:verbose-cmd| for more information.
+
+==============================================================================
+5. Events *autocmd-events* *E215* *E216*
+
+You can specify a comma-separated list of event names. No white space can be
+used in this list. The command applies to all the events in the list.
+
+For READING FILES there are four kinds of events possible:
+ BufNewFile starting to edit a non-existent file
+ BufReadPre BufReadPost starting to edit an existing file
+ FilterReadPre FilterReadPost read the temp file with filter output
+ FileReadPre FileReadPost any other file read
+Vim uses only one of these four kinds when reading a file. The "Pre" and
+"Post" events are both triggered, before and after reading the file.
+
+Note that the autocommands for the *ReadPre events and all the Filter events
+are not allowed to change the current buffer (you will get an error message if
+this happens). This is to prevent the file to be read into the wrong buffer.
+
+Note that the 'modified' flag is reset AFTER executing the BufReadPost
+and BufNewFile autocommands. But when the 'modified' option was set by the
+autocommands, this doesn't happen.
+
+You can use the 'eventignore' option to ignore a number of events or all
+events.
+ *autocommand-events* *{event}*
+Vim recognizes the following events. Vim ignores the case of event names
+(e.g., you can use "BUFread" or "bufread" instead of "BufRead").
+
+First an overview by function with a short explanation. Then the list
+alphabetically with full explanations |autocmd-events-abc|.
+
+Name triggered by ~
+
+ Reading
+|BufNewFile| starting to edit a file that doesn't exist
+|BufReadPre| starting to edit a new buffer, before reading the file
+|BufRead| starting to edit a new buffer, after reading the file
+|BufReadPost| starting to edit a new buffer, after reading the file
+|BufReadCmd| before starting to edit a new buffer |Cmd-event|
+
+|FileReadPre| before reading a file with a ":read" command
+|FileReadPost| after reading a file with a ":read" command
+|FileReadCmd| before reading a file with a ":read" command |Cmd-event|
+
+|FilterReadPre| before reading a file from a filter command
+|FilterReadPost| after reading a file from a filter command
+
+|StdinReadPre| before reading from stdin into the buffer
+|StdinReadPost| After reading from the stdin into the buffer
+
+ Writing
+|BufWrite| starting to write the whole buffer to a file
+|BufWritePre| starting to write the whole buffer to a file
+|BufWritePost| after writing the whole buffer to a file
+|BufWriteCmd| before writing the whole buffer to a file |Cmd-event|
+
+|FileWritePre| starting to write part of a buffer to a file
+|FileWritePost| after writing part of a buffer to a file
+|FileWriteCmd| before writing part of a buffer to a file |Cmd-event|
+
+|FileAppendPre| starting to append to a file
+|FileAppendPost| after appending to a file
+|FileAppendCmd| before appending to a file |Cmd-event|
+
+|FilterWritePre| starting to write a file for a filter command or diff
+|FilterWritePost| after writing a file for a filter command or diff
+
+ Buffers
+|BufAdd| just after adding a buffer to the buffer list
+|BufCreate| just after adding a buffer to the buffer list
+|BufDelete| before deleting a buffer from the buffer list
+|BufWipeout| before completely deleting a buffer
+
+|BufFilePre| before changing the name of the current buffer
+|BufFilePost| after changing the name of the current buffer
+
+|BufEnter| after entering a buffer
+|BufLeave| before leaving to another buffer
+|BufWinEnter| after a buffer is displayed in a window
+|BufWinLeave| before a buffer is removed from a window
+
+|BufUnload| before unloading a buffer
+|BufHidden| just before a buffer becomes hidden
+|BufNew| just after creating a new buffer
+
+|SwapExists| detected an existing swap file
+
+ Options
+|FileType| when the 'filetype' option has been set
+|Syntax| when the 'syntax' option has been set
+|EncodingChanged| after the 'encoding' option has been changed
+|TermChanged| after the value of 'term' has changed
+|OptionSet| after setting any option
+
+ Startup and exit
+|VimEnter| after doing all the startup stuff
+|GUIEnter| after starting the GUI successfully
+|GUIFailed| after starting the GUI failed
+|TermResponse| after the terminal response to |t_RV| is received
+
+|QuitPre| when using `:quit`, before deciding whether to exit
+|ExitPre| when using a command that may make Vim exit
+|VimLeavePre| before exiting Vim, before writing the viminfo file
+|VimLeave| before exiting Vim, after writing the viminfo file
+
+|VimSuspend| when suspending Vim
+|VimResume| when Vim is resumed after being suspended
+
+ Terminal
+|TerminalOpen| after a terminal buffer was created
+|TerminalWinOpen| after a terminal buffer was created in a new window
+
+ Various
+|FileChangedShell| Vim notices that a file changed since editing started
+|FileChangedShellPost| After handling a file changed since editing started
+|FileChangedRO| before making the first change to a read-only file
+
+|DiffUpdated| after diffs have been updated
+|DirChangedPre| before the working directory will change
+|DirChanged| after the working directory has changed
+
+|ShellCmdPost| after executing a shell command
+|ShellFilterPost| after filtering with a shell command
+
+|CmdUndefined| a user command is used but it isn't defined
+|FuncUndefined| a user function is used but it isn't defined
+|SpellFileMissing| a spell file is used but it can't be found
+|SourcePre| before sourcing a Vim script
+|SourcePost| after sourcing a Vim script
+|SourceCmd| before sourcing a Vim script |Cmd-event|
+
+|VimResized| after the Vim window size changed
+|FocusGained| Vim got input focus
+|FocusLost| Vim lost input focus
+|CursorHold| the user doesn't press a key for a while
+|CursorHoldI| the user doesn't press a key for a while in Insert mode
+|CursorMoved| the cursor was moved in Normal mode
+|CursorMovedI| the cursor was moved in Insert mode
+
+|WinNew| after creating a new window
+|TabNew| after creating a new tab page
+|WinClosed| after closing a window
+|TabClosed| after closing a tab page
+|WinEnter| after entering another window
+|WinLeave| before leaving a window
+|TabEnter| after entering another tab page
+|TabLeave| before leaving a tab page
+|CmdwinEnter| after entering the command-line window
+|CmdwinLeave| before leaving the command-line window
+
+|CmdlineChanged| after a change was made to the command-line text
+|CmdlineEnter| after the cursor moves to the command line
+|CmdlineLeave| before the cursor leaves the command line
+
+|InsertEnter| starting Insert mode
+|InsertChange| when typing <Insert> while in Insert or Replace mode
+|InsertLeave| when leaving Insert mode
+|InsertLeavePre| just before leaving Insert mode
+|InsertCharPre| when a character was typed in Insert mode, before
+ inserting it
+
+|ModeChanged| after changing the mode
+
+|TextChanged| after a change was made to the text in Normal mode
+|TextChangedI| after a change was made to the text in Insert mode
+ when popup menu is not visible
+|TextChangedP| after a change was made to the text in Insert mode
+ when popup menu visible
+|TextChangedT| after a change was made to the text in Terminal mode
+|TextYankPost| after text has been yanked or deleted
+
+|SafeState| nothing pending, going to wait for the user to type a
+ character
+|SafeStateAgain| repeated SafeState
+
+|ColorSchemePre| before loading a color scheme
+|ColorScheme| after loading a color scheme
+
+|RemoteReply| a reply from a server Vim was received
+
+|QuickFixCmdPre| before a quickfix command is run
+|QuickFixCmdPost| after a quickfix command is run
+
+|SessionLoadPost| after loading a session file
+
+|MenuPopup| just before showing the popup menu
+|CompleteChanged| after Insert mode completion menu changed
+|CompleteDonePre| after Insert mode completion is done, before clearing
+ info
+|CompleteDone| after Insert mode completion is done, after clearing
+ info
+
+|User| to be used in combination with ":doautocmd"
+|SigUSR1| after the SIGUSR1 signal has been detected
+
+|WinScrolled| after scrolling or resizing a window
+
+
+The alphabetical list of autocommand events: *autocmd-events-abc*
+
+ *BufCreate* *BufAdd*
+BufAdd or BufCreate Just after creating a new buffer which is
+ added to the buffer list, or adding a buffer
+ to the buffer list.
+ Also used just after a buffer in the buffer
+ list has been renamed.
+ Not triggered for the initial buffers created
+ during startup.
+ The BufCreate event is for historic reasons.
+ NOTE: When this autocommand is executed, the
+ current buffer "%" may be different from the
+ buffer being created "<afile>".
+ *BufDelete*
+BufDelete Before deleting a buffer from the buffer list.
+ The BufUnload may be called first (if the
+ buffer was loaded).
+ Also used just before a buffer in the buffer
+ list is renamed.
+ NOTE: When this autocommand is executed, the
+ current buffer "%" may be different from the
+ buffer being deleted "<afile>" and "<abuf>".
+ Don't change to another buffer, it will cause
+ problems.
+ *BufEnter*
+BufEnter After entering a buffer. Useful for setting
+ options for a file type. Also executed when
+ starting to edit a buffer, after the
+ BufReadPost autocommands.
+ *BufFilePost*
+BufFilePost After changing the name of the current buffer
+ with the ":file" or ":saveas" command.
+ *BufFilePre*
+BufFilePre Before changing the name of the current buffer
+ with the ":file" or ":saveas" command.
+ *BufHidden*
+BufHidden Just before a buffer becomes hidden. That is,
+ when there are no longer windows that show
+ the buffer, but the buffer is not unloaded or
+ deleted. Not used for ":qa" or ":q" when
+ exiting Vim.
+ NOTE: When this autocommand is executed, the
+ current buffer "%" may be different from the
+ buffer being unloaded "<afile>".
+ *BufLeave*
+BufLeave Before leaving to another buffer. Also when
+ leaving or closing the current window and the
+ new current window is not for the same buffer.
+ Not used for ":qa" or ":q" when exiting Vim.
+ *BufNew*
+BufNew Just after creating a new buffer. Also used
+ just after a buffer has been renamed. When
+ the buffer is added to the buffer list BufAdd
+ will be triggered too.
+ NOTE: When this autocommand is executed, the
+ current buffer "%" may be different from the
+ buffer being created "<afile>".
+ *BufNewFile*
+BufNewFile When starting to edit a file that doesn't
+ exist. Can be used to read in a skeleton
+ file.
+ *BufRead* *BufReadPost*
+BufRead or BufReadPost When starting to edit a new buffer, after
+ reading the file into the buffer, before
+ executing the modelines. See |BufWinEnter|
+ for when you need to do something after
+ processing the modelines.
+ Also triggered:
+ - when writing an unnamed buffer in a way that
+ the buffer gets a name
+ - after successfully recovering a file
+ - for the filetypedetect group when executing
+ ":filetype detect"
+ Not triggered:
+ - for the `:read file` command
+ - when the file doesn't exist
+ *BufReadCmd*
+BufReadCmd Before starting to edit a new buffer. Should
+ read the file into the buffer. |Cmd-event|
+ *BufReadPre* *E200* *E201*
+BufReadPre When starting to edit a new buffer, before
+ reading the file into the buffer. Not used
+ if the file doesn't exist.
+ *BufUnload*
+BufUnload Before unloading a buffer. This is when the
+ text in the buffer is going to be freed. This
+ may be after a BufWritePost and before a
+ BufDelete. Also used for all buffers that are
+ loaded when Vim is going to exit.
+ NOTE: When this autocommand is executed, the
+ current buffer "%" may be different from the
+ buffer being unloaded "<afile>".
+ Don't change to another buffer or window, it
+ will cause problems!
+ When exiting and v:dying is 2 or more this
+ event is not triggered.
+ *BufWinEnter*
+BufWinEnter After a buffer is displayed in a window. This
+ can be when the buffer is loaded (after
+ processing the modelines) or when a hidden
+ buffer is displayed in a window (and is no
+ longer hidden).
+ Does not happen for |:split| without
+ arguments, since you keep editing the same
+ buffer, or ":split" with a file that's already
+ open in a window, because it re-uses an
+ existing buffer. But it does happen for a
+ ":split" with the name of the current buffer,
+ since it reloads that buffer.
+ Does not happen for a terminal window, because
+ it starts in Terminal-Job mode and Normal mode
+ commands won't work. Use |TerminalOpen| instead.
+ *BufWinLeave*
+BufWinLeave Before a buffer is removed from a window.
+ Not when it's still visible in another window.
+ Also triggered when exiting. It's triggered
+ before BufUnload or BufHidden.
+ NOTE: When this autocommand is executed, the
+ current buffer "%" may be different from the
+ buffer being unloaded "<afile>".
+ When exiting and v:dying is 2 or more this
+ event is not triggered.
+ *BufWipeout*
+BufWipeout Before completely deleting a buffer. The
+ BufUnload and BufDelete events may be called
+ first (if the buffer was loaded and was in the
+ buffer list). Also used just before a buffer
+ is renamed (also when it's not in the buffer
+ list).
+ NOTE: When this autocommand is executed, the
+ current buffer "%" may be different from the
+ buffer being deleted "<afile>".
+ Don't change to another buffer, it will cause
+ problems.
+ *BufWrite* *BufWritePre*
+BufWrite or BufWritePre Before writing the whole buffer to a file.
+ *BufWriteCmd*
+BufWriteCmd Before writing the whole buffer to a file.
+ Should do the writing of the file and reset
+ 'modified' if successful, unless '+' is in
+ 'cpo' and writing to another file |cpo-+|.
+ The buffer contents should not be changed.
+ When the command resets 'modified' the undo
+ information is adjusted to mark older undo
+ states as 'modified', like |:write| does.
+ |Cmd-event|
+ *BufWritePost*
+BufWritePost After writing the whole buffer to a file
+ (should undo the commands for BufWritePre).
+ *CmdUndefined*
+CmdUndefined When a user command is used but it isn't
+ defined. Useful for defining a command only
+ when it's used. The pattern is matched
+ against the command name. Both <amatch> and
+ <afile> are set to the name of the command.
+ NOTE: Autocompletion won't work until the
+ command is defined. An alternative is to
+ always define the user command and have it
+ invoke an autoloaded function. See |autoload|.
+ *CmdlineChanged*
+CmdlineChanged After a change was made to the text in the
+ command line. Be careful not to mess up
+ the command line, it may cause Vim to lock up.
+ <afile> is set to a single character,
+ indicating the type of command-line.
+ |cmdwin-char|
+ *CmdlineEnter*
+CmdlineEnter After moving the cursor to the command line,
+ where the user can type a command or search
+ string; including non-interactive use of ":"
+ in a mapping, but not when using |<Cmd>|.
+ The pattern is matched against the character
+ representing the type of command-line.
+ |cmdwin-char|
+ <afile> is set to a single character,
+ indicating the type of command-line.
+ *CmdlineLeave*
+CmdlineLeave Before leaving the command line; including
+ non-interactive use of ":" in a mapping, but
+ not when using |<Cmd>|.
+ Also when abandoning the command line, after
+ typing CTRL-C or <Esc>.
+ When the commands result in an error the
+ command line is still executed.
+ <afile> is set to a single character,
+ indicating the type of command-line.
+ |cmdwin-char|
+ *CmdwinEnter*
+CmdwinEnter After entering the command-line window.
+ Useful for setting options specifically for
+ this special type of window.
+ <afile> is set to a single character,
+ indicating the type of command-line.
+ |cmdwin-char|
+ *CmdwinLeave*
+CmdwinLeave Before leaving the command-line window.
+ Useful to clean up any global setting done
+ with CmdwinEnter.
+ <afile> is set to a single character,
+ indicating the type of command-line.
+ |cmdwin-char|
+ *ColorScheme*
+ColorScheme After loading a color scheme. |:colorscheme|
+ Not triggered if the color scheme is not
+ found.
+ The pattern is matched against the
+ colorscheme name. <afile> can be used for the
+ name of the actual file where this option was
+ set, and <amatch> for the new colorscheme
+ name.
+
+ *ColorSchemePre*
+ColorSchemePre Before loading a color scheme. |:colorscheme|
+ Useful to setup removing things added by a
+ color scheme, before another one is loaded.
+CompleteChanged *CompleteChanged*
+ After each time the Insert mode completion
+ menu changed. Not fired on popup menu hide,
+ use |CompleteDonePre| or |CompleteDone| for
+ that. Never triggered recursively.
+
+ Sets these |v:event| keys:
+ completed_item See |complete-items|.
+ height nr of items visible
+ width screen cells
+ row top screen row
+ col leftmost screen column
+ size total nr of items
+ scrollbar TRUE if visible
+
+ It is not allowed to change the text |textlock|.
+
+ The size and position of the popup are also
+ available by calling |pum_getpos()|.
+
+ *CompleteDonePre*
+CompleteDonePre After Insert mode completion is done. Either
+ when something was completed or abandoning
+ completion. |ins-completion|
+ |complete_info()| can be used, the info is
+ cleared after triggering CompleteDonePre.
+ The |v:completed_item| variable contains
+ information about the completed item.
+
+ *CompleteDone*
+CompleteDone After Insert mode completion is done. Either
+ when something was completed or abandoning
+ completion. |ins-completion|
+ |complete_info()| cannot be used, the info is
+ cleared before triggering CompleteDone. Use
+ CompleteDonePre if you need it.
+ The |v:completed_item| variable contains
+ information about the completed item.
+
+ *CursorHold*
+CursorHold When the user doesn't press a key for the time
+ specified with 'updatetime'. Not triggered
+ until the user has pressed a key (i.e. doesn't
+ fire every 'updatetime' ms if you leave Vim to
+ make some coffee. :) See |CursorHold-example|
+ for previewing tags.
+ This event is only triggered in Normal mode.
+ It is not triggered when waiting for a command
+ argument to be typed, or a movement after an
+ operator.
+ While recording the CursorHold event is not
+ triggered. |q|
+ *<CursorHold>*
+ Internally the autocommand is triggered by the
+ <CursorHold> key. In an expression mapping
+ |getchar()| may see this character.
+
+ Note: Interactive commands cannot be used for
+ this event. There is no hit-enter prompt,
+ the screen is updated directly (when needed).
+ Note: In the future there will probably be
+ another option to set the time.
+ Hint: to force an update of the status lines
+ use: >
+ :let &ro = &ro
+< {only on Amiga, Unix, Win32 and all GUI
+ versions}
+ *CursorHoldI*
+CursorHoldI Just like CursorHold, but in Insert mode.
+ Not triggered when waiting for another key,
+ e.g. after CTRL-V, and not when in CTRL-X mode
+ |insert_expand|.
+
+ *CursorMoved*
+CursorMoved After the cursor was moved in Normal or Visual
+ mode. Also when the text of the cursor line
+ has been changed, e.g., with "x", "rx" or "p".
+ Not always triggered when there is typeahead,
+ while executing commands in a script file,
+ when an operator is pending or when moving to
+ another window while remaining at the same
+ cursor position.
+ For an example see |match-parens|.
+ Note: This can not be skipped with
+ `:noautocmd`.
+ Careful: This is triggered very often, don't
+ do anything that the user does not expect or
+ that is slow.
+ *CursorMovedI*
+CursorMovedI After the cursor was moved in Insert mode.
+ Not triggered when the popup menu is visible.
+ Otherwise the same as CursorMoved.
+ *DiffUpdated*
+DiffUpdated After diffs have been updated. Depending on
+ what kind of diff is being used (internal or
+ external) this can be triggered on every
+ change or when doing |:diffupdate|.
+ *DirChangedPre*
+DirChangedPre The working directory is going to be changed,
+ as with |DirChanged|. The pattern is like
+ with |DirChanged|. The new directory can be
+ found in v:event.directory.
+ *DirChanged*
+DirChanged The working directory has changed in response
+ to the |:cd| or |:tcd| or |:lcd| commands, or
+ as a result of the 'autochdir' option.
+ The pattern can be:
+ "window" to trigger on `:lcd`
+ "tabpage" to trigger on `:tcd`
+ "global" to trigger on `:cd`
+ "auto" to trigger on 'autochdir'.
+ "drop" to trigger on editing a file
+ <afile> is set to the new directory name.
+ *EncodingChanged*
+EncodingChanged Fires off after the 'encoding' option has been
+ changed. Useful to set up fonts, for example.
+ *ExitPre*
+ExitPre When using `:quit`, `:wq` in a way it makes
+ Vim exit, or using `:qall`, just after
+ |QuitPre|. Can be used to close any
+ non-essential window. Exiting may still be
+ cancelled if there is a modified buffer that
+ isn't automatically saved, use |VimLeavePre|
+ for really exiting.
+ *FileAppendCmd*
+FileAppendCmd Before appending to a file. Should do the
+ appending to the file. Use the '[ and ']
+ marks for the range of lines. |Cmd-event|
+ *FileAppendPost*
+FileAppendPost After appending to a file.
+ *FileAppendPre*
+FileAppendPre Before appending to a file. Use the '[ and ']
+ marks for the range of lines.
+ *FileChangedRO*
+FileChangedRO Before making the first change to a read-only
+ file. Can be used to check-out the file from
+ a source control system. Not triggered when
+ the change was caused by an autocommand.
+ This event is triggered when making the first
+ change in a buffer or the first change after
+ 'readonly' was set, just before the change is
+ applied to the text.
+ WARNING: If the autocommand moves the cursor
+ the effect of the change is undefined.
+ *E788*
+ It is not allowed to change to another buffer
+ here. You can reload the buffer but not edit
+ another one.
+ *E881*
+ If the number of lines changes saving for undo
+ may fail and the change will be aborted.
+ *FileChangedShell*
+FileChangedShell When Vim notices that the modification time of
+ a file has changed since editing started.
+ Also when the file attributes of the file
+ change or when the size of the file changes.
+ |timestamp|
+ Mostly triggered after executing a shell
+ command, but also with a |:checktime| command
+ or when gvim regains input focus.
+ This autocommand is triggered for each changed
+ file. It is not used when 'autoread' is set
+ and the buffer was not changed. If a
+ FileChangedShell autocommand is present the
+ warning message and prompt is not given.
+ The |v:fcs_reason| variable is set to indicate
+ what happened and |v:fcs_choice| can be used
+ to tell Vim what to do next.
+ NOTE: When this autocommand is executed, the
+ current buffer "%" may be different from the
+ buffer that was changed, which is in "<afile>".
+ NOTE: The commands must not change the current
+ buffer, jump to another buffer or delete a
+ buffer. *E246* *E811*
+ NOTE: This event never nests, to avoid an
+ endless loop. This means that while executing
+ commands for the FileChangedShell event no
+ other FileChangedShell event will be
+ triggered.
+ *FileChangedShellPost*
+FileChangedShellPost After handling a file that was changed outside
+ of Vim. Can be used to update the statusline.
+ *FileEncoding*
+FileEncoding Obsolete. It still works and is equivalent
+ to |EncodingChanged|.
+ *FileReadCmd*
+FileReadCmd Before reading a file with a ":read" command.
+ Should do the reading of the file. |Cmd-event|
+ *FileReadPost*
+FileReadPost After reading a file with a ":read" command.
+ Note that Vim sets the '[ and '] marks to the
+ first and last line of the read. This can be
+ used to operate on the lines just read.
+ *FileReadPre*
+FileReadPre Before reading a file with a ":read" command.
+ *FileType*
+FileType When the 'filetype' option has been set. The
+ pattern is matched against the filetype.
+ <afile> can be used for the name of the file
+ where this option was set, and <amatch> for
+ the new value of 'filetype'. Navigating to
+ another window or buffer is not allowed.
+ See |filetypes|.
+ *FileWriteCmd*
+FileWriteCmd Before writing to a file, when not writing the
+ whole buffer. Should do the writing to the
+ file. Should not change the buffer. Use the
+ '[ and '] marks for the range of lines.
+ |Cmd-event|
+ *FileWritePost*
+FileWritePost After writing to a file, when not writing the
+ whole buffer.
+ *FileWritePre*
+FileWritePre Before writing to a file, when not writing the
+ whole buffer. Use the '[ and '] marks for the
+ range of lines.
+ *FilterReadPost*
+FilterReadPost After reading a file from a filter command.
+ Vim checks the pattern against the name of
+ the current buffer as with FilterReadPre.
+ Not triggered when 'shelltemp' is off.
+ *FilterReadPre* *E135*
+FilterReadPre Before reading a file from a filter command.
+ Vim checks the pattern against the name of
+ the current buffer, not the name of the
+ temporary file that is the output of the
+ filter command.
+ Not triggered when 'shelltemp' is off.
+ *FilterWritePost*
+FilterWritePost After writing a file for a filter command or
+ making a diff with an external diff (see
+ |DiffUpdated| for internal diff).
+ Vim checks the pattern against the name of
+ the current buffer as with FilterWritePre.
+ Not triggered when 'shelltemp' is off.
+ *FilterWritePre*
+FilterWritePre Before writing a file for a filter command or
+ making a diff with an external diff.
+ Vim checks the pattern against the name of
+ the current buffer, not the name of the
+ temporary file that is the output of the
+ filter command.
+ Not triggered when 'shelltemp' is off.
+ *FocusGained*
+FocusGained When Vim got input focus. Only for the GUI
+ version and a few console versions where this
+ can be detected.
+ *FocusLost*
+FocusLost When Vim lost input focus. Only for the GUI
+ version and a few console versions where this
+ can be detected. May also happen when a
+ dialog pops up.
+ *FuncUndefined*
+FuncUndefined When a user function is used but it isn't
+ defined. Useful for defining a function only
+ when it's used. The pattern is matched
+ against the function name. Both <amatch> and
+ <afile> are set to the name of the function.
+ Not triggered when compiling a |Vim9|
+ function.
+ NOTE: When writing Vim scripts a better
+ alternative is to use an autoloaded function.
+ See |autoload-functions|.
+ *GUIEnter*
+GUIEnter After starting the GUI successfully, and after
+ opening the window. It is triggered before
+ VimEnter when using gvim. Can be used to
+ position the window from a .gvimrc file: >
+ :autocmd GUIEnter * winpos 100 50
+< *GUIFailed*
+GUIFailed After starting the GUI failed. Vim may
+ continue to run in the terminal, if possible
+ (only on Unix and alikes, when connecting the
+ X server fails). You may want to quit Vim: >
+ :autocmd GUIFailed * qall
+< *InsertChange*
+InsertChange When typing <Insert> while in Insert or
+ Replace mode. The |v:insertmode| variable
+ indicates the new mode.
+ Be careful not to move the cursor or do
+ anything else that the user does not expect.
+ *InsertCharPre*
+InsertCharPre When a character is typed in Insert mode,
+ before inserting the char.
+ The |v:char| variable indicates the char typed
+ and can be changed during the event to insert
+ a different character. When |v:char| is set
+ to more than one character this text is
+ inserted literally.
+ It is not allowed to change the text |textlock|.
+ The event is not triggered when 'paste' is
+ set. {only with the +eval feature}
+ *InsertEnter*
+InsertEnter Just before starting Insert mode. Also for
+ Replace mode and Virtual Replace mode. The
+ |v:insertmode| variable indicates the mode.
+ Be careful not to do anything else that the
+ user does not expect.
+ The cursor is restored afterwards. If you do
+ not want that set |v:char| to a non-empty
+ string.
+ *InsertLeavePre*
+InsertLeavePre Just before leaving Insert mode. Also when
+ using CTRL-O |i_CTRL-O|. Be careful not to
+ change mode or use `:normal`, it will likely
+ cause trouble.
+ *InsertLeave*
+InsertLeave Just after leaving Insert mode. Also when
+ using CTRL-O |i_CTRL-O|. But not for |i_CTRL-C|.
+ *MenuPopup*
+MenuPopup Just before showing the popup menu (under the
+ right mouse button). Useful for adjusting the
+ menu for what is under the cursor or mouse
+ pointer.
+ The pattern is matched against one or two
+ characters representing the mode:
+ n Normal
+ v Visual
+ o Operator-pending
+ i Insert
+ c Command line
+ tl Terminal
+ *ModeChanged*
+ModeChanged After changing the mode. The pattern is
+ matched against `'old_mode:new_mode'`, for
+ example match against `*:c*` to simulate
+ |CmdlineEnter|.
+ The following values of |v:event| are set:
+ old_mode The mode before it changed.
+ new_mode The new mode as also returned
+ by |mode()| called with a
+ non-zero argument.
+ When ModeChanged is triggered, old_mode will
+ have the value of new_mode when the event was
+ last triggered.
+ This will be triggered on every minor mode
+ change.
+ Usage example to use relative line numbers
+ when entering Visual mode: >
+ :au ModeChanged [vV\x16]*:* let &l:rnu = mode() =~# '^[vV\x16]'
+ :au ModeChanged *:[vV\x16]* let &l:rnu = mode() =~# '^[vV\x16]'
+ :au WinEnter,WinLeave * let &l:rnu = mode() =~# '^[vV\x16]'
+< *OptionSet*
+OptionSet After setting an option. The pattern is
+ matched against the long option name.
+ |<amatch>| indicates what option has been set.
+
+ |v:option_type| indicates whether it's global
+ or local scoped.
+ |v:option_command| indicates what type of
+ set/let command was used (follow the tag to
+ see the table).
+ |v:option_new| indicates the newly set value.
+ |v:option_oldlocal| has the old local value.
+ |v:option_oldglobal| has the old global value.
+ |v:option_old| indicates the old option value.
+
+ |v:option_oldlocal| is only set when |:set|
+ or |:setlocal| or a |modeline| was used to set
+ the option. Similarly |v:option_oldglobal| is
+ only set when |:set| or |:setglobal| was used.
+
+ Note that when setting a |global-local| string
+ option with |:set|, then |v:option_old| is the
+ old global value. However, for all other kinds
+ of options (local string options, global-local
+ number options, ...) it is the old local
+ value.
+
+ OptionSet is not triggered on startup and for
+ the 'key' option for obvious reasons.
+
+ Usage example: Check for the existence of the
+ directory in the 'backupdir' and 'undodir'
+ options, create the directory if it doesn't
+ exist yet.
+
+ Note: It's a bad idea to reset an option
+ during this autocommand, this may break a
+ plugin. You can always use `:noa` to prevent
+ triggering this autocommand.
+
+ When using |:set| in the autocommand the event
+ is not triggered again.
+ *QuickFixCmdPre*
+QuickFixCmdPre Before a quickfix command is run (|:make|,
+ |:lmake|, |:grep|, |:lgrep|, |:grepadd|,
+ |:lgrepadd|, |:vimgrep|, |:lvimgrep|,
+ |:vimgrepadd|, |:lvimgrepadd|, |:cscope|,
+ |:cfile|, |:cgetfile|, |:caddfile|, |:lfile|,
+ |:lgetfile|, |:laddfile|, |:helpgrep|,
+ |:lhelpgrep|, |:cexpr|, |:cgetexpr|,
+ |:caddexpr|, |:cbuffer|, |:cgetbuffer|,
+ |:caddbuffer|).
+ The pattern is matched against the command
+ being run. When |:grep| is used but 'grepprg'
+ is set to "internal" it still matches "grep".
+ This command cannot be used to set the
+ 'makeprg' and 'grepprg' variables.
+ If this command causes an error, the quickfix
+ command is not executed.
+ *QuickFixCmdPost*
+QuickFixCmdPost Like QuickFixCmdPre, but after a quickfix
+ command is run, before jumping to the first
+ location. For |:cfile| and |:lfile| commands
+ it is run after the error file is read and
+ before moving to the first error.
+ See |QuickFixCmdPost-example|.
+ *QuitPre*
+QuitPre When using `:quit`, `:wq` or `:qall`, before
+ deciding whether it closes the current window
+ or quits Vim. For `:wq` the buffer is written
+ before QuitPre is triggered. Can be used to
+ close any non-essential window if the current
+ window is the last ordinary window.
+ Also see |ExitPre|.
+ *RemoteReply*
+RemoteReply When a reply from a Vim that functions as
+ server was received |server2client()|. The
+ pattern is matched against the {serverid}.
+ <amatch> is equal to the {serverid} from which
+ the reply was sent, and <afile> is the actual
+ reply string.
+ Note that even if an autocommand is defined,
+ the reply should be read with |remote_read()|
+ to consume it.
+ *SafeState*
+SafeState When nothing is pending, going to wait for the
+ user to type a character.
+ This will not be triggered when:
+ - an operator is pending
+ - a register was entered with "r
+ - halfway executing a command
+ - executing a mapping
+ - there is typeahead
+ - Insert mode completion is active
+ - Command line completion is active
+ You can use `mode()` to find out what state
+ Vim is in. That may be:
+ - VIsual mode
+ - Normal mode
+ - Insert mode
+ - Command-line mode
+ Depending on what you want to do, you may also
+ check more with `state()`, e.g. whether the
+ screen was scrolled for messages.
+ *SafeStateAgain*
+SafeStateAgain Like SafeState but after processing any
+ messages and invoking callbacks. This may be
+ triggered often, don't do something that takes
+ time.
+
+ *SessionLoadPost*
+SessionLoadPost After loading the session file created using
+ the |:mksession| command.
+ *ShellCmdPost*
+ShellCmdPost After executing a shell command with |:!cmd|,
+ |:shell|, |:make| and |:grep|. Can be used to
+ check for any changed files.
+ *ShellFilterPost*
+ShellFilterPost After executing a shell command with
+ ":{range}!cmd", ":w !cmd" or ":r !cmd".
+ Can be used to check for any changed files.
+ *SourcePre*
+SourcePre Before sourcing a Vim script. |:source|
+ <afile> is the name of the file being sourced.
+ *SourcePost*
+SourcePost After sourcing a Vim script. |:source|
+ <afile> is the name of the file being sourced.
+ Not triggered when sourcing was interrupted.
+ Also triggered after a SourceCmd autocommand
+ was triggered.
+ *SourceCmd*
+SourceCmd When sourcing a Vim script. |:source|
+ <afile> is the name of the file being sourced.
+ The autocommand must source this file.
+ |Cmd-event|
+ *SpellFileMissing*
+SpellFileMissing When trying to load a spell checking file and
+ it can't be found. The pattern is matched
+ against the language. <amatch> is the
+ language, 'encoding' also matters. See
+ |spell-SpellFileMissing|.
+ *StdinReadPost*
+StdinReadPost After reading from the stdin into the buffer,
+ before executing the modelines. Only used
+ when the "-" argument was used when Vim was
+ started |--|.
+ *StdinReadPre*
+StdinReadPre Before reading from stdin into the buffer.
+ Only used when the "-" argument was used when
+ Vim was started |--|.
+ *SwapExists*
+SwapExists Detected an existing swap file when starting
+ to edit a file. Only when it is possible to
+ select a way to handle the situation, when Vim
+ would ask the user what to do.
+ The |v:swapname| variable holds the name of
+ the swap file found, <afile> the file being
+ edited. |v:swapcommand| may contain a command
+ to be executed in the opened file.
+ The commands should set the |v:swapchoice|
+ variable to a string with one character to
+ tell Vim what should be done next:
+ 'o' open read-only
+ 'e' edit the file anyway
+ 'r' recover
+ 'd' delete the swap file
+ 'q' quit, don't edit the file
+ 'a' abort, like hitting CTRL-C
+ When set to an empty string the user will be
+ asked, as if there was no SwapExists autocmd.
+ *E812*
+ It is not allowed to change to another buffer,
+ change a buffer name or change directory
+ here.
+ {only available with the +eval feature}
+ *Syntax*
+Syntax When the 'syntax' option has been set. The
+ pattern is matched against the syntax name.
+ <afile> can be used for the name of the file
+ where this option was set, and <amatch> for
+ the new value of 'syntax'.
+ See |:syn-on|.
+ *TabClosed*
+TabClosed After closing a tab page.
+ *TabEnter*
+TabEnter Just after entering a tab page. |tab-page|
+ After triggering the WinEnter and before
+ triggering the BufEnter event.
+ *TabLeave*
+TabLeave Just before leaving a tab page. |tab-page|
+ A WinLeave event will have been triggered
+ first.
+ *TabNew*
+TabNew When a tab page was created. |tab-page|
+ A WinEnter event will have been triggered
+ first, TabEnter follows.
+ *TermChanged*
+TermChanged After the value of 'term' has changed. Useful
+ for re-loading the syntax file to update the
+ colors, fonts and other terminal-dependent
+ settings. Executed for all loaded buffers.
+ *TerminalOpen*
+TerminalOpen Just after a terminal buffer was created, with
+ `:terminal` or |term_start()|. This event is
+ triggered even if the buffer is created
+ without a window, with the ++hidden option.
+ *TerminalWinOpen*
+TerminalWinOpen Just after a terminal buffer was created, with
+ `:terminal` or |term_start()|. This event is
+ triggered only if the buffer is created
+ with a window. Can be used to set window
+ local options for the terminal window.
+ *TermResponse*
+TermResponse After the response to |t_RV| is received from
+ the terminal. The value of |v:termresponse|
+ can be used to do things depending on the
+ terminal version. Note that this event may be
+ triggered halfway executing another event,
+ especially if file I/O, a shell command or
+ anything else that takes time is involved.
+ *TextChanged*
+TextChanged After a change was made to the text in the
+ current buffer in Normal mode. That is after
+ |b:changedtick| has changed (also when that
+ happened before the TextChanged autocommand
+ was defined).
+ Not triggered when there is typeahead or when
+ an operator is pending.
+ Note: This can not be skipped with
+ `:noautocmd`.
+ Careful: This is triggered very often, don't
+ do anything that the user does not expect or
+ that is slow.
+ *TextChangedI*
+TextChangedI After a change was made to the text in the
+ current buffer in Insert mode.
+ Not triggered when the popup menu is visible.
+ Otherwise the same as TextChanged.
+ *TextChangedP*
+TextChangedP After a change was made to the text in the
+ current buffer in Insert mode, only when the
+ popup menu is visible. Otherwise the same as
+ TextChanged.
+ *TextChangedT*
+TextChangedT After a change was made to the text in the
+ current buffer in Terminal mode.
+ Otherwise the same as TextChanged.
+ *TextYankPost*
+TextYankPost After text has been yanked or deleted in the
+ current buffer. The following values of
+ |v:event| can be used to determine the operation
+ that triggered this autocmd:
+ inclusive TRUE if the motion is
+ |inclusive| else the motion is
+ |exclusive|.
+ operator The operation performed.
+ regcontents Text that was stored in the
+ register, as a list of lines,
+ like with: >
+ getreg(r, 1, 1)
+< regname Name of the register or empty
+ string for the unnamed
+ register, see |registers|.
+ regtype Type of the register, see
+ |getregtype()|.
+ visual True if the operation is
+ performed on a |Visual| area.
+ Not triggered when |quote_| is used nor when
+ called recursively.
+ It is not allowed to change the buffer text,
+ see |textlock|. *E1064*
+ {only when compiled with the +eval feature}
+
+ *User*
+User Never executed automatically. To be used for
+ autocommands that are only executed with
+ ":doautocmd".
+ Note that when `:doautocmd User MyEvent` is
+ used while there are no matching autocommands,
+ you will get an error. If you don't want
+ that, either check whether an autocommand is
+ defined using `exists('#User#MyEvent')` or
+ define a dummy autocommand yourself.
+ Example: >
+ if exists('#User#MyEvent')
+ doautocmd User MyEvent
+ endif
+<
+ *SigUSR1*
+SigUSR1 After the SIGUSR1 signal has been detected.
+ Could be used if other ways of notifying Vim
+ are not feasible. E.g. to check for the
+ result of a build that takes a long time, or
+ when a motion sensor is triggered.
+ {only on Unix}
+
+ *UserGettingBored*
+UserGettingBored When the user presses the same key 42 times.
+ Just kidding! :-)
+ *VimEnter*
+VimEnter After doing all the startup stuff, including
+ loading .vimrc files, executing the "-c cmd"
+ arguments, creating all windows and loading
+ the buffers in them.
+ Just before this event is triggered the
+ |v:vim_did_enter| variable is set, so that you
+ can do: >
+ if v:vim_did_enter
+ call s:init()
+ else
+ au VimEnter * call s:init()
+ endif
+< *VimLeave*
+VimLeave Before exiting Vim, just after writing the
+ .viminfo file. Executed only once, like
+ VimLeavePre.
+ To detect an abnormal exit use |v:dying|.
+ When v:dying is 2 or more this event is not
+ triggered.
+ To get the exit code use |v:exiting|.
+ *VimLeavePre*
+VimLeavePre Before exiting Vim, just before writing the
+ .viminfo file. This is executed only once,
+ if there is a match with the name of what
+ happens to be the current buffer when exiting.
+ Mostly useful with a "*" pattern. >
+ :autocmd VimLeavePre * call CleanupStuff()
+< To detect an abnormal exit use |v:dying|.
+ When v:dying is 2 or more this event is not
+ triggered.
+ To get the exit code use |v:exiting|.
+ *VimResized*
+VimResized After the Vim window was resized, thus 'lines'
+ and/or 'columns' changed. Not when starting
+ up though.
+ *VimResume*
+VimResume When the Vim instance is resumed after being
+ suspended and |VimSuspend| was triggered.
+ Useful for triggering |:checktime| and ensure
+ the buffers content did not change while Vim
+ was suspended: >
+ :autocmd VimResume * checktime
+< *VimSuspend*
+VimSuspend When the Vim instance is suspended. Only when
+ CTRL-Z was typed inside Vim, or when the SIGTSTP
+ signal was sent to Vim, but not for SIGSTOP.
+ *WinClosed*
+WinClosed When closing a window, just before it is
+ removed from the window layout. The pattern
+ is matched against the |window-ID|. Both
+ <amatch> and <afile> are set to the
+ |window-ID|. Non-recursive (event cannot
+ trigger itself).
+ *WinEnter*
+WinEnter After entering another window. Not done for
+ the first window, when Vim has just started.
+ Useful for setting the window height.
+ If the window is for another buffer, Vim
+ executes the BufEnter autocommands after the
+ WinEnter autocommands.
+ Note: For split and tabpage commands the
+ WinEnter event is triggered after the split
+ or tab command but before the file is loaded.
+
+ *WinLeave*
+WinLeave Before leaving a window. If the window to be
+ entered next is for a different buffer, Vim
+ executes the BufLeave autocommands before the
+ WinLeave autocommands (but not for ":new").
+ Not used for ":qa" or ":q" when exiting Vim.
+
+ *WinNew*
+WinNew When a new window was created. Not done for
+ the first window, when Vim has just started.
+ Before a WinEnter event.
+
+ *WinScrolled*
+WinScrolled After any window in the current tab page
+ scrolled the text (horizontally or vertically)
+ or changed width or height. See
+ |win-scrolled-resized|.
+
+ The pattern is matched against the |window-ID|
+ of the first window that scrolled or resized.
+ Both <amatch> and <afile> are set to the
+ |window-ID|.
+
+ |v:event| is set with information about size
+ and scroll changes. |WinScrolled-event|
+
+ Only starts triggering after startup finished
+ and the first screen redraw was done.
+ Does not trigger when defining the first
+ WinScrolled or WinResized event, but may
+ trigger when adding more.
+
+ Non-recursive: the event will not trigger
+ while executing commands for the WinScrolled
+ event. However, if the command causes a
+ window to scroll or change size, then another
+ WinScrolled event will be triggered later.
+
+
+ *WinResized*
+WinResized After a window in the current tab page changed
+ width or height.
+ See |win-scrolled-resized|.
+
+ |v:event| is set with information about size
+ changes. |WinResized-event|
+
+ Same behavior as |WinScrolled| for the
+ pattern, triggering and recursiveness.
+
+==============================================================================
+6. Patterns *autocmd-patterns* *{aupat}*
+
+The {aupat} argument of `:autocmd` can be a comma-separated list. This works as
+if the command was given with each pattern separately. Thus this command: >
+ :autocmd BufRead *.txt,*.info set et
+Is equivalent to: >
+ :autocmd BufRead *.txt set et
+ :autocmd BufRead *.info set et
+
+The file pattern {aupat} is tested for a match against the file name in one of
+two ways:
+1. When there is no '/' in the pattern, Vim checks for a match against only
+ the tail part of the file name (without its leading directory path).
+2. When there is a '/' in the pattern, Vim checks for a match against both the
+ short file name (as you typed it) and the full file name (after expanding
+ it to a full path and resolving symbolic links).
+
+The special pattern <buffer> or <buffer=N> is used for buffer-local
+autocommands |autocmd-buflocal|. This pattern is not matched against the name
+of a buffer.
+
+Examples: >
+ :autocmd BufRead *.txt set et
+Set the 'et' option for all text files. >
+
+ :autocmd BufRead /vim/src/*.c set cindent
+Set the 'cindent' option for C files in the /vim/src directory. >
+
+ :autocmd BufRead /tmp/*.c set ts=5
+If you have a link from "/tmp/test.c" to "/home/nobody/vim/src/test.c", and
+you start editing "/tmp/test.c", this autocommand will match.
+
+Note: To match part of a path, but not from the root directory, use a '*' as
+the first character. Example: >
+ :autocmd BufRead */doc/*.txt set tw=78
+This autocommand will for example be executed for "/tmp/doc/xx.txt" and
+"/usr/home/piet/doc/yy.txt". The number of directories does not matter here.
+
+
+The file name that the pattern is matched against is after expanding
+wildcards. Thus if you issue this command: >
+ :e $ROOTDIR/main.$EXT
+The argument is first expanded to: >
+ /usr/root/main.py
+Before it's matched with the pattern of the autocommand. Careful with this
+when using events like FileReadCmd, the value of <amatch> may not be what you
+expect.
+
+
+Environment variables can be used in a pattern: >
+ :autocmd BufRead $VIMRUNTIME/doc/*.txt set expandtab
+And ~ can be used for the home directory (if $HOME is defined): >
+ :autocmd BufWritePost ~/.vimrc so ~/.vimrc
+ :autocmd BufRead ~archive/* set readonly
+The environment variable is expanded when the autocommand is defined, not when
+the autocommand is executed. This is different from the command!
+
+ *file-pattern*
+The pattern is interpreted like mostly used in file names:
+ * matches any sequence of characters; Unusual: includes path
+ separators
+ ? matches any single character
+ \? matches a '?'
+ . matches a '.'
+ ~ matches a '~'
+ , separates patterns
+ \, matches a ','
+ { } like \( \) in a |pattern|
+ , inside { }: like \| in a |pattern|
+ \} literal }
+ \{ literal {
+ \\\{n,m\} like \{n,m} in a |pattern|
+ \ special meaning like in a |pattern|
+ [ch] matches 'c' or 'h'
+ [^ch] match any character but 'c' and 'h'
+
+Note that for all systems the '/' character is used for path separator (even
+for MS-Windows). This was done because the backslash is difficult to use in a
+pattern and to make the autocommands portable across different systems.
+
+It is possible to use |pattern| items, but they may not work as expected,
+because of the translation done for the above.
+
+ *autocmd-changes*
+Matching with the pattern is done when an event is triggered. Changing the
+buffer name in one of the autocommands, or even deleting the buffer, does not
+change which autocommands will be executed. Example: >
+
+ au BufEnter *.foo bdel
+ au BufEnter *.foo set modified
+
+This will delete the current buffer and then set 'modified' in what has become
+the current buffer instead. Vim doesn't take into account that "*.foo"
+doesn't match with that buffer name. It matches "*.foo" with the name of the
+buffer at the moment the event was triggered.
+
+However, buffer-local autocommands will not be executed for a buffer that has
+been wiped out with |:bwipe|. After deleting the buffer with |:bdel| the
+buffer actually still exists (it becomes unlisted), thus the autocommands are
+still executed.
+
+==============================================================================
+7. Buffer-local autocommands *autocmd-buflocal* *autocmd-buffer-local*
+ *<buffer=N>* *<buffer=abuf>* *E680*
+
+Buffer-local autocommands are attached to a specific buffer. They are useful
+if the buffer does not have a name and when the name does not match a specific
+pattern. But it also means they must be explicitly added to each buffer.
+
+Instead of a pattern buffer-local autocommands use one of these forms:
+ <buffer> current buffer
+ <buffer=99> buffer number 99
+ <buffer=abuf> using <abuf> (only when executing autocommands)
+ |<abuf>|
+
+Examples: >
+ :au CursorHold <buffer> echo 'hold'
+ :au CursorHold <buffer=33> echo 'hold'
+ :au BufNewFile * au CursorHold <buffer=abuf> echo 'hold'
+
+All the commands for autocommands also work with buffer-local autocommands,
+simply use the special string instead of the pattern. Examples: >
+ :au! * <buffer> " remove buffer-local autocommands for
+ " current buffer
+ :au! * <buffer=33> " remove buffer-local autocommands for
+ " buffer #33
+ :bufdo :au! CursorHold <buffer> " remove autocmd for given event for all
+ " buffers
+ :au * <buffer> " list buffer-local autocommands for
+ " current buffer
+
+Note that when an autocommand is defined for the current buffer, it is stored
+with the buffer number. Thus it uses the form "<buffer=12>", where 12 is the
+number of the current buffer. You will see this when listing autocommands,
+for example.
+
+To test for presence of buffer-local autocommands use the |exists()| function
+as follows: >
+ :if exists("#CursorHold#<buffer=12>") | ... | endif
+ :if exists("#CursorHold#<buffer>") | ... | endif " for current buffer
+
+When a buffer is wiped out its buffer-local autocommands are also gone, of
+course. Note that when deleting a buffer, e.g., with ":bdel", it is only
+unlisted, the autocommands are still present. In order to see the removal of
+buffer-local autocommands: >
+ :set verbose=6
+
+It is not possible to define buffer-local autocommands for a non-existent
+buffer.
+
+==============================================================================
+8. Groups *autocmd-groups*
+
+Autocommands can be put together in a group. This is useful for removing or
+executing a group of autocommands. For example, all the autocommands for
+syntax highlighting are put in the "highlight" group, to be able to execute
+":doautoall highlight BufRead" when the GUI starts.
+
+When no specific group is selected, Vim uses the default group. The default
+group does not have a name. You cannot execute the autocommands from the
+default group separately; you can execute them only by executing autocommands
+for all groups.
+
+Normally, when executing autocommands automatically, Vim uses the autocommands
+for all groups. The group only matters when executing autocommands with
+":doautocmd" or ":doautoall", or when defining or deleting autocommands.
+
+The group name can contain any characters except white space. The group name
+"end" is reserved (also in uppercase).
+
+The group name is case sensitive. Note that this is different from the event
+name!
+
+ *:aug* *:augroup*
+:aug[roup] {name} Define the autocmd group name for the
+ following ":autocmd" commands. The name "end"
+ or "END" selects the default group.
+ To avoid confusion, the name should be
+ different from existing {event} names, as this
+ most likely will not do what you intended.
+
+ *:augroup-delete* *E367* *W19* *E936*
+:aug[roup]! {name} Delete the autocmd group {name}. Don't use
+ this if there is still an autocommand using
+ this group! You will get a warning if doing
+ it anyway. When the group is the current
+ group you will get error E936.
+
+To enter autocommands for a specific group, use this method:
+1. Select the group with ":augroup {name}".
+2. Delete any old autocommands with ":au!".
+3. Define the autocommands.
+4. Go back to the default group with "augroup END".
+
+Example: >
+ :augroup uncompress
+ : au!
+ : au BufEnter *.gz %!gunzip
+ :augroup END
+
+This prevents having the autocommands defined twice (e.g., after sourcing the
+.vimrc file again).
+
+ *FileExplorer*
+There is one group that is recognized by Vim: FileExplorer. If this group
+exists Vim assumes that editing a directory is possible and will trigger a
+plugin that lists the files in that directory. This is used by the |netrw|
+plugin. This allows you to do: >
+ browse edit
+
+==============================================================================
+9. Executing autocommands *autocmd-execute*
+
+Vim can also execute Autocommands non-automatically. This is useful if you
+have changed autocommands, or when Vim has executed the wrong autocommands
+(e.g., the file pattern match was wrong).
+
+Note that the 'eventignore' option applies here too. Events listed in this
+option will not cause any commands to be executed.
+
+ *:do* *:doau* *:doaut* *:doautocmd* *E217*
+:do[autocmd] [<nomodeline>] [group] {event} [fname]
+ Apply the autocommands matching [fname] (default:
+ current file name) for {event} to the current buffer.
+ You can use this when the current file name does not
+ match the right pattern, after changing settings, or
+ to execute autocommands for a certain event.
+ It's possible to use this inside an autocommand too,
+ so you can base the autocommands for one extension on
+ another extension. Example: >
+ :au BufEnter *.cpp so ~/.vimrc_cpp
+ :au BufEnter *.cpp doau BufEnter x.c
+< Be careful to avoid endless loops. See
+ |autocmd-nested|.
+
+ When the [group] argument is not given, Vim executes
+ the autocommands for all groups. When the [group]
+ argument is included, Vim executes only the matching
+ autocommands for that group. Note: if you use an
+ undefined group name, Vim gives you an error message.
+ *<nomodeline>*
+ After applying the autocommands the modelines are
+ processed, so that their settings overrule the
+ settings from autocommands, like what happens when
+ editing a file. This is skipped when the <nomodeline>
+ argument is present. You probably want to use
+ <nomodeline> for events that are not used when loading
+ a buffer, such as |User|.
+ Processing modelines is also skipped when no
+ matching autocommands were executed.
+
+ *:doautoa* *:doautoall*
+:doautoa[ll] [<nomodeline>] [group] {event} [fname]
+ Like ":doautocmd", but apply the autocommands to each
+ loaded buffer. The current buffer is done last.
+
+ Note that [fname] is used to select the autocommands,
+ not the buffers to which they are applied. Example: >
+ augroup mine
+ autocmd!
+ autocmd FileType * echo expand('<amatch>')
+ augroup END
+ doautoall mine FileType Loaded-Buffer
+< Sourcing this script, you'll see as many
+ "Loaded-Buffer" echoed as there are loaded buffers.
+
+ Careful: Don't use this for autocommands that delete a
+ buffer, change to another buffer or change the
+ contents of a buffer; the result is unpredictable.
+ This command is intended for autocommands that set
+ options, change highlighting, and things like that.
+
+==============================================================================
+10. Using autocommands *autocmd-use*
+
+For WRITING FILES there are four possible sets of events. Vim uses only one
+of these sets for a write command:
+
+BufWriteCmd BufWritePre BufWritePost writing the whole buffer
+ FilterWritePre FilterWritePost writing to filter temp file
+FileAppendCmd FileAppendPre FileAppendPost appending to a file
+FileWriteCmd FileWritePre FileWritePost any other file write
+
+When there is a matching "*Cmd" autocommand, it is assumed it will do the
+writing. No further writing is done and the other events are not triggered.
+|Cmd-event|
+
+Note that the *WritePost commands should undo any changes to the buffer that
+were caused by the *WritePre commands; otherwise, writing the file will have
+the side effect of changing the buffer.
+
+Before executing the autocommands, the buffer from which the lines are to be
+written temporarily becomes the current buffer. Unless the autocommands
+change the current buffer or delete the previously current buffer, the
+previously current buffer is made the current buffer again.
+
+The *WritePre and *AppendPre autocommands must not delete the buffer from
+which the lines are to be written.
+
+The '[ and '] marks have a special position:
+- Before the *ReadPre event the '[ mark is set to the line just above where
+ the new lines will be inserted.
+- Before the *ReadPost event the '[ mark is set to the first line that was
+ just read, the '] mark to the last line.
+- Before executing the *WriteCmd, *WritePre and *AppendPre autocommands the '[
+ mark is set to the first line that will be written, the '] mark to the last
+ line.
+Careful: '[ and '] change when using commands that change the buffer.
+
+In commands which expect a file name, you can use "<afile>" for the file name
+that is being read |:<afile>| (you can also use "%" for the current file
+name). "<abuf>" can be used for the buffer number of the currently effective
+buffer. This also works for buffers that don't have a name. But it doesn't
+work for files without a buffer (e.g., with ":r file").
+
+ *gzip-example*
+Examples for reading and writing compressed files: >
+ :augroup gzip
+ : autocmd!
+ : autocmd BufReadPre,FileReadPre *.gz set bin
+ : autocmd BufReadPost,FileReadPost *.gz '[,']!gunzip
+ : autocmd BufReadPost,FileReadPost *.gz set nobin
+ : autocmd BufReadPost,FileReadPost *.gz execute ":doautocmd BufReadPost " .. expand("%:r")
+ : autocmd BufWritePost,FileWritePost *.gz !mv <afile> <afile>:r
+ : autocmd BufWritePost,FileWritePost *.gz !gzip <afile>:r
+
+ : autocmd FileAppendPre *.gz !gunzip <afile>
+ : autocmd FileAppendPre *.gz !mv <afile>:r <afile>
+ : autocmd FileAppendPost *.gz !mv <afile> <afile>:r
+ : autocmd FileAppendPost *.gz !gzip <afile>:r
+ :augroup END
+
+The "gzip" group is used to be able to delete any existing autocommands with
+":autocmd!", for when the file is sourced twice.
+
+("<afile>:r" is the file name without the extension, see |:_%:|)
+
+The commands executed for the BufNewFile, BufRead/BufReadPost, BufWritePost,
+FileAppendPost and VimLeave events do not set or reset the changed flag of the
+buffer. When you decompress the buffer with the BufReadPost autocommands, you
+can still exit with ":q". When you use ":undo" in BufWritePost to undo the
+changes made by BufWritePre commands, you can still do ":q" (this also makes
+"ZZ" work). If you do want the buffer to be marked as modified, set the
+'modified' option.
+
+To execute Normal mode commands from an autocommand, use the ":normal"
+command. Use with care! If the Normal mode command is not finished, the user
+needs to type characters (e.g., after ":normal m" you need to type a mark
+name).
+
+If you want the buffer to be unmodified after changing it, reset the
+'modified' option. This makes it possible to exit the buffer with ":q"
+instead of ":q!".
+
+ *autocmd-nested* *E218*
+By default, autocommands do not nest. For example, if you use ":e" or ":w" in
+an autocommand, Vim does not execute the BufRead and BufWrite autocommands for
+those commands. If you do want this, use the "nested" flag for those commands
+in which you want nesting. For example: >
+ :autocmd FileChangedShell *.c ++nested e!
+The nesting is limited to 10 levels to get out of recursive loops.
+
+It's possible to use the ":au" command in an autocommand. This can be a
+self-modifying command! This can be useful for an autocommand that should
+execute only once.
+
+If you want to skip autocommands for one command, use the |:noautocmd| command
+modifier or the 'eventignore' option.
+
+Note: When reading a file (with ":read file" or with a filter command) and the
+last line in the file does not have an <EOL>, Vim remembers this. At the next
+write (with ":write file" or with a filter command), if the same line is
+written again as the last line in a file AND 'binary' is set, Vim does not
+supply an <EOL>. This makes a filter command on the just read lines write the
+same file as was read, and makes a write command on just filtered lines write
+the same file as was read from the filter. For example, another way to write
+a compressed file: >
+
+ :autocmd FileWritePre *.gz set bin|'[,']!gzip
+ :autocmd FileWritePost *.gz undo|set nobin
+<
+ *autocommand-pattern*
+You can specify multiple patterns, separated by commas. Here are some
+examples: >
+
+ :autocmd BufRead * set tw=79 nocin ic infercase fo=2croq
+ :autocmd BufRead .letter set tw=72 fo=2tcrq
+ :autocmd BufEnter .letter set dict=/usr/lib/dict/words
+ :autocmd BufLeave .letter set dict=
+ :autocmd BufRead,BufNewFile *.c,*.h set tw=0 cin noic
+ :autocmd BufEnter *.c,*.h abbr FOR for (i = 0; i < 3; ++i)<CR>{<CR>}<Esc>O
+ :autocmd BufLeave *.c,*.h unabbr FOR
+
+For makefiles (makefile, Makefile, imakefile, makefile.unix, etc.): >
+
+ :autocmd BufEnter ?akefile* set include=^s\=include
+ :autocmd BufLeave ?akefile* set include&
+
+To always start editing C files at the first function: >
+
+ :autocmd BufRead *.c,*.h 1;/^{
+
+Without the "1;" above, the search would start from wherever the file was
+entered, rather than from the start of the file.
+
+ *skeleton* *template*
+To read a skeleton (template) file when opening a new file: >
+
+ :autocmd BufNewFile *.c 0r ~/vim/skeleton.c
+ :autocmd BufNewFile *.h 0r ~/vim/skeleton.h
+ :autocmd BufNewFile *.java 0r ~/vim/skeleton.java
+
+To insert the current date and time in a *.html file when writing it: >
+
+ :autocmd BufWritePre,FileWritePre *.html ks|call LastMod()|'s
+ :fun LastMod()
+ : if line("$") > 20
+ : let l = 20
+ : else
+ : let l = line("$")
+ : endif
+ : exe "1," .. l .. "g/Last modified: /s/Last modified: .*/Last modified: " ..
+ : \ strftime("%Y %b %d")
+ :endfun
+
+You need to have a line "Last modified: <date time>" in the first 20 lines
+of the file for this to work. Vim replaces <date time> (and anything in the
+same line after it) with the current date and time. Explanation:
+ ks mark current position with mark 's'
+ call LastMod() call the LastMod() function to do the work
+ 's return the cursor to the old position
+The LastMod() function checks if the file is shorter than 20 lines, and then
+uses the ":g" command to find lines that contain "Last modified: ". For those
+lines the ":s" command is executed to replace the existing date with the
+current one. The ":execute" command is used to be able to use an expression
+for the ":g" and ":s" commands. The date is obtained with the strftime()
+function. You can change its argument to get another date string.
+
+When entering :autocmd on the command-line, completion of events and command
+names may be done (with <Tab>, CTRL-D, etc.) where appropriate.
+
+Vim executes all matching autocommands in the order that you specify them.
+It is recommended that your first autocommand be used for all files by using
+"*" as the file pattern. This means that you can define defaults you like
+here for any settings, and if there is another matching autocommand it will
+override these. But if there is no other matching autocommand, then at least
+your default settings are recovered (if entering this file from another for
+which autocommands did match). Note that "*" will also match files starting
+with ".", unlike Unix shells.
+
+ *autocmd-searchpat*
+Autocommands do not change the current search patterns. Vim saves the current
+search patterns before executing autocommands then restores them after the
+autocommands finish. This means that autocommands do not affect the strings
+highlighted with the 'hlsearch' option. Within autocommands, you can still
+use search patterns normally, e.g., with the "n" command.
+If you want an autocommand to set the search pattern, such that it is used
+after the autocommand finishes, use the ":let @/ =" command.
+The search-highlighting cannot be switched off with ":nohlsearch" in an
+autocommand. Use the 'h' flag in the 'viminfo' option to disable search-
+highlighting when starting Vim.
+
+ *Cmd-event*
+When using one of the "*Cmd" events, the matching autocommands are expected to
+do the file reading, writing or sourcing. This can be used when working with
+a special kind of file, for example on a remote system.
+CAREFUL: If you use these events in a wrong way, it may have the effect of
+making it impossible to read or write the matching files! Make sure you test
+your autocommands properly. Best is to use a pattern that will never match a
+normal file name, for example "ftp://*".
+
+When defining a BufReadCmd it will be difficult for Vim to recover a crashed
+editing session. When recovering from the original file, Vim reads only those
+parts of a file that are not found in the swap file. Since that is not
+possible with a BufReadCmd, use the |:preserve| command to make sure the
+original file isn't needed for recovery. You might want to do this only when
+you expect the file to be modified.
+
+For file read and write commands the |v:cmdarg| variable holds the "++enc="
+and "++ff=" argument that are effective. These should be used for the command
+that reads/writes the file. The |v:cmdbang| variable is one when "!" was
+used, zero otherwise.
+
+See the $VIMRUNTIME/plugin/netrwPlugin.vim for examples.
+
+==============================================================================
+11. Disabling autocommands *autocmd-disable*
+
+To disable autocommands for some time use the 'eventignore' option. Note that
+this may cause unexpected behavior, make sure you restore 'eventignore'
+afterwards, using a |:try| block with |:finally|.
+
+ *:noautocmd* *:noa*
+To disable autocommands for just one command use the ":noautocmd" command
+modifier. This will set 'eventignore' to "all" for the duration of the
+following command. Example: >
+
+ :noautocmd w fname.gz
+
+This will write the file without triggering the autocommands defined by the
+gzip plugin.
+
+Note that some autocommands are not triggered right away, but only later.
+This specifically applies to |CursorMoved| and |TextChanged|.
+
+
+ vim:tw=78:ts=8:noet:ft=help:norl: