*autocmd.txt*   For Vim version 5.0j.  Last modification: 1997 May 31


		  VIM REFERENCE MANUAL    by Bram Moolenaar


Automatic commands					*autocommand*

1. Introduction			|autocmd-intro|
2. Defining autocommands	|autocmd-define|
3. Events			|autocmd-events|
4. Patterns			|autocmd-patterns|
5. Using autocommands		|autocmd-use|

==============================================================================
1. Introduction						*autocmd-intro*

You can specify commands to be executed automatically for when reading or
writing a file, when entering or leaving a buffer or window, and when exiting
Vim.  For example, 'cindent' can be set for files matching *.c, and unset
otherwise.  Autocommands can be used to edit compressed files.  These commands
are normally put in your .vimrc or .exrc file.  {All this is not in Vi}

WARNING: Using autocommands is very powerful, but may lead to unexpected side
effects.  Be careful not to destroy your text.
- It's a good idea to first 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 (to be able to do recovery in some rare cases).
  It's a good idea to use the same autocommands for the File* and Buf* events
  when possible.

The autocommand feature is only included if Vim has been compiled with AUTOCMD
defined.  If the output of ":version" contains "+autocmd" it is included (this
is the default), if it contains "-autocmd" then the autocommand feature
doesn't work.

==============================================================================
2. Defining autocommands				*autocmd-define*

Note: This command cannot be followed by another command, since any '|' is
considered part of the command.

							*:au* *:autocmd*
:au[tocmd] {event} {pat} [nested] {cmd}
			Add {cmd} to the list of commands that will be
			automatically executed on {event} for a file matching
			{pat}.  The {cmd} is always added after existing
			autocommands, so that the autocommands are executed in
			the order in which they were given.  See
			|autocmd-nest| for [nested].

:au[tocmd] {event} {pat}
			Show the auto-commands associated with {event} and
			{pat}.

:au[tocmd] * {pat}	Show the auto-commands associated with {pat} for all
			events.

:au[tocmd] {event}	Show all auto-commands for {event}.

:au[tocmd]		Show all auto-commands.

:au[tocmd]! {event} {pat} [nested] {cmd}
			Remove all auto-commands associated with {event} and
			{pat}, and add the command {cmd}.  See |autocmd-nest|
			for [nested].

:au[tocmd]! {event} {pat}
			Remove all auto-commands associated with {event} and
			{pat}.

:au[tocmd]! * {pat}	Remove all auto-commands associated with {pat} for all
			events.

:au[tocmd]! {event}	Remove ALL auto-commands for {event}.

:au[tocmd]!		Remove ALL auto-commands.

							*:do* *:doautocmd*
:do[autocmd] {event} [fname]
			Apply the autocommands matching [fname] (default:
			current file name) for {event} to the current buffer.
			This can be used 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 for endless loops.  See |autocmd-nest|.

						*:doautoa* *:doautoall*
:doautoa[ll] {event} [fname]
			Like ":doautocmd", but execute it for each loaded
			buffer.  Careful: Don't use this for autocommands that
			delete a buffer, change to another buffer or change
			the contents of a buffer, the result will be
			unpredictable.  It is only meant to perform
			autocommands that set options, change highlighting,
			and things like that.

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 BufEnter *.html so <sfile>:h/html.vim

Here <sfile> is expanded to the file that contains this line.

When your .vimrc file is sourced twice, the autocommands will appear twice.
To avoid this, put this command in your .vimrc file, before defining
autocommands:

	:autocmd!	" Remove ALL auto-commands.

==============================================================================
3. Events						*autocmd-events*

					*autocommand-events* *{event}*
These events are recognized.  Case is ignored, for example "BUFread" and
"bufread" can be used instead of "BufRead".

							*BufNewFile*
BufNewFile			When starting to edit a file that doesn't
				exist.  Can be used to read in a skeleton
				file.
							*BufReadPre*
BufReadPre			When starting to edit a new buffer, before
				reading the file into the buffer.  Not used
				when the file doesn't exist.
						*BufRead* *BufReadPost*
BufRead or BufReadPost		When starting to edit a new buffer, after
				reading the file into the buffer, before
				executing the modelines.  This does NOT work
				for ":r file".  Not used when the file doesn't
				exist.
							*FileReadPre*
FileReadPre			Before reading a file with a ":read" command.
							*FileReadPost*
FileReadPost			After reading a file with a ":read" command.
				Note that the '[ and '] marks are set to the
				first and last line of the read, this can be
				used to operate on the just read lines.
							*FilterReadPre*
FilterReadPre			Before reading a file from a filter command.
				The file name of the current buffer is used to
				match with the pattern, not the name of the
				temporary file that is the output of the
				filter command.
							*FilterReadPost*
FilterReadPost			After reading a file from a filter command.
				Like FilterReadPre, the file name of the
				current buffer is used.
							*StdinReadPre*
StdinReadPre			Before reading from stdin into the buffer.
				Only used when the "-" argument was used when
				Vim was started |--|.
							*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 |--|.
						*BufWrite* *BufWritePre*
BufWrite or BufWritePre		Before writing the whole buffer to a file.
							*BufWritePost*
BufWritePost			After writing the whole buffer to a file
				(should undo the commands for BufWritePre).
							*FileWritePre*
FileWritePre			Before writing to a file, when not writing the
				whole buffer.
							*FileWritePost*
FileWritePost			After writing to a file, when not writing the
				whole buffer.
							*FileAppendPre*
FileAppendPre			Before appending to a file.
							*FileAppendPost*
FileAppendPost			After appending to a file.
							*FilterWritePre*
FilterWritePre			Before writing a file for a filter command.
				The file name of the current buffer is used to
				match with the pattern, not the name of the
				temporary file that is the input for the
				filter command.
							*FilterWritePost*
FilterWritePost			After writing a file for a filter command.
				Like FilterWritePre, the file name of the
				current buffer is used.
							*FileChangedShell*
FileChangedShell		After a shell command is run, and vim notices
				that the modification time of the current file
				has changed since editing started.  Run in
				place of the 'has been changed' message.  See
				|timestamp|.  Useful for reloading related
				buffers which are affected by a single
				command.
							*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.
							*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.
							*WinEnter*
WinEnter			After entering another window.  Not done for
				the first window, when Vim is just started.
				Useful for setting the window height.
				If the window is for another buffer, the
				BufEnter autocommands are executed after the
				WinEnter autocommands.
							*TermChanged*
TermChanged			After the value of 'term' was changed.  Useful
				for re-loading the syntax file to update the
				colors, fonts and other terminal-dependent
				settings.  Executed for all loaded buffers.
							*WinLeave*
WinLeave			Before leaving to another window.  If the
				window to be entered is for a different
				buffer, the BufLeave autocommands are executed
				before the WinLeave autocommands.
							*VimLeave*
VimLeave			Before exiting Vim, just before writing the
				.viminfo file.  There is no VimEnter event,
				because you can use the .vimrc for that.

For READING FILES there are three possible pairs of events, only one pair is
used at a time:
BufNewFile			starting to edit a non-existant file
BufReadPre	BufReadPost	starting to edit an existing file
FilterReadPre	FilterReadPost	read the temp file with filter output
FileReadPre	FileReadPost	any other file read

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 anyway.  This is to prevent the file to be read into the wrong
buffer.

==============================================================================
4. Patterns						*autocmd-patterns*

Normally the file pattern is tested for a match against just the tail part of
the file name (without its leading directory path), but if the path separator
character '/' appears in the pattern, then it will be tested against the full
file name.  For example:

  :autocmd BufRead */vim/src/*.c	set wrap

Note that for all systems the '/' character is used for path separator, also
on MS-DOS and OS/2.  This was done because the backslash is difficult to use
in a pattern, and to make the autocommands portable accross different systems.

Note that using ~ in a file name (for home directory) doesn't work.  Use a
pattern that matches the full path name, for example "*home/user/.cshrc".

==============================================================================
5. Using autocommands					*autocmd-use*

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.
Careful: '[ and '] will change when using commands that change the buffer.

"<afile>" can be used for the file name that is being read, in commands where
a file name is expected (where you can also use "%" for the current file
name) |:<afile>|.

Examples for reading compressed files:
  :autocmd! BufReadPre,FileReadPre   *.gz set bin
  :autocmd  BufReadPost,FileReadPost *.gz '[,']!gunzip
  :autocmd  BufReadPost,FileReadPost *.gz set nobin

NOTE: When using the examples given, any existing autocommands for the same
event/pattern combination will be removed, because of the '!'.

For WRITING FILES there are four possible pairs of events, only one pair is
used at a time:
BufWritePre	BufWritePost	writing the whole buffer
FilterWritePre	FilterWritePost	writing to the temp file with filter input
FileAppendPre	FileAppendPost	appending to a file
FileWritePre	FileWritePost	any other file write

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 where the lines are to be
written is temporarily made 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
where the lines are to be written.

Before executing the *WritePre and *AppendPre autocommands the '[ mark is set
to the first line that will be written, the '] mark to the last line.
Careful: '[ and '] will change when using commands that change the buffer.

"<afile>" can be used for the file name that is being written, in commands
where a file name is expected (where you can also use "%" for the current file
name) |:<afile>|.

							*gzip-example*
Examples for writing compressed files:
  :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

("<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).

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 not to be modified after changing it, reset the
'modified' option.  This makes it possible to exit the buffer with ":q"
instead of ":q!".

							*autocmd-nest*
By default, autocommands do not nest.  If you use ":e" or ":w" in an
autocommand, the BufRead and BufWrite autocommands are not executed for those
commands.  If you do want this, the "nested" flag must be given for those
commands where nesting is desired.  For example:
	:autocmd FileChangedShell *.c nested e!
The nesting is limited to 10 levels, to get out of recursive loops.

It's not possible to use the ":au" command in an autocommand (that could be a
self-modifying command!).

There is currently no way to disable the autocommands.  If you want to write a
file without executing the autocommands for that type of file, write it under
another name and rename it with a shell command.

Note: When reading a file (with ":read file" or with a filter command) and the
last line in the file does not have an end-of-line character, this is
remembered.  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, no end-of-line character is written.  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*
Multiple patterns may be given 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++)^M{^M}^[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.

To read a skeleton file for new C files:

  :autocmd BufNewFile  *.c	0r ~/.skeleton.c
  :autocmd BufNewFile  *.h	0r ~/.skeleton.h

To insert the current date and time in a *.html file when writing it:

:autocmd BufWritePre,FileWritePre *.html ks|1,20g/Last modification: /normal f:lD:read !date^MkJ's

(to insert the ^M type CTRL-V CTRL-M)
You need to have a line "Last modification: <date time>" in the first 20 lines
of the file for this to work.  The <date time> (and anything in the same line
after it) will be replaced with the current date and time.  Explanation:
	ks		mark current position with mark 's'
	1,20g/pattern/	find lines that contain the pattern
	normal f:	find the ':'
	lD		delete the old date and time
	!date^M		read the current date and time into the next line
	kJ		Join the date and time with the previous line
	's		return the cursor to the old position

When entering :autocmd on the command line, completion of events and command
names may be done (with <Tab>, CTRL-D, etc.) where appropriate.

All matching auto-commands will be executed in the order that they were
specified.  It is recommended that your first auto-command 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
auto-command it will override these.  But if there is no other matching
auto-command, then at least your default settings are recovered (if entering
this file from another for which auto-commands did match).  Note that "*" will
also match files starting with ".", unlike Unix shells.

 vim:tw=78:ts=8:sw=8:
