*autocmd.txt*   Nvim


		  VIM REFERENCE MANUAL    by Bram Moolenaar


Automatic commands					*autocmd* *autocommand*

For a basic explanation, see section |40.3| in the user manual.

				      Type |gO| to see the table of contents.

==============================================================================
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 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.

==============================================================================
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-pattern|.
			Note: A quote character is seen as argument to the
			:autocmd and won't start a comment.
			Nvim always adds {cmd} after existing autocommands so
			they execute in the order in which they were defined.
			See |autocmd-nested| for [++nested].
							*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|.

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