autocmd.txt

MSYS在windows下模拟了一个类unix的终端

*autocmd.txt*   For Vim version 5.8.  Last change: 2001 Feb 01


		  VIM REFERENCE MANUAL    by Bram Moolenaar


Automatic commands					*autocommand*

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.  Filetypes			|autocmd-filetypes|
8.  Groups			|autocmd-groups|
9.  Executing autocommands	|autocmd-execute|
10. Using autocommands		|autocmd-use|

{Vi does not have any of these commands}

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

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.

The |+autocmd| feature is only included if it has not been disabled at compile
time.

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

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

							*:au* *:autocmd*
:au[tocmd] [group] {event} {pat} [nested] {cmd}
			Add {cmd} to the list of commands that Vim will
			execute automatically on {event} for a file matching
			{pat}.  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].

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.

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

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.

==============================================================================
3. Removing autocommands				*autocmd-remove*

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

:au[tocmd]! [group] {event} {pat}
			Remove all autocommands associated with {event} and
			{pat}.

:au[tocmd]! [group] * {pat}
			Remove all autocommands associated with {pat} for all
			events.

:au[tocmd]! [group] {event}
			Remove ALL autocommands for {event}.

:au[tocmd]! [group]	Remove ALL autocommands.

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} {pat}
			Show the autocommands associated with {event} and
			{pat}.

:au[tocmd] [group] * {pat}
			Show the autocommands associated with {pat} 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.

==============================================================================
5. Events						*autocmd-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").

							*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
				if 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.  Also used after successfully recovering
				a file.
							*BufFilePre*
BufFilePre			Before changing the name of the current buffer
				with the ":file" command.
							*BufFilePost*
BufFilePost			After changing the name of the current buffer
				with the ":file" command.
							*FileReadPre*
FileReadPre			Before reading a file with a ":read" command.
							*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.
							*FilterReadPre*
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.
							*FilterReadPost*
FilterReadPost			After reading a file from a filter command.
				Vim checks the pattern against the name of
				the current buffer as with FilterReadPre.
							*FileType*
FileType			When the 'filetype' option has been set.
				<afile> can be used for the name of the file
				where this option was set, and <amatch> for
				the new value of 'filetype'.
				See |autocmd-filetypes|.
							*Syntax*
Syntax				When the 'syntax' option has been set.
				<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|.
							*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.
				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.
							*FilterWritePost*
FilterWritePost			After writing a file for a filter command.
				Vim checks the pattern against the name of
				the current buffer as with FilterWritePre.
							*FileChangedShell*
FileChangedShell		After Vim runs a shell command and notices
				that the modification time of a file has
				changed since editing started.  This
				autocommand is triggered for each changed
				file.  Run in place of the 'has been changed'
				message.  See |timestamp|.  Useful for
				reloading related buffers which are affected
				by a single command.
				NOTE: When this autocommand is executed, the
				current buffer "%" may be different from the
				buffer that was changed "<afile>".
				NOTE: This even never nests, to avoid an
				endless loop.
							*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.
							*CursorHold*
CursorHold			When the user doesn't press a key for the time
				specified with 'updatetime'.  Not re-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.
				Note: Interactive commands and ":normal"
				cannot be used for this event.
				Note: In the future there will probably be
				another option to set the time.
				{only on Amiga, Unix, Win32, MSDOS and all GUI
				versions}
							*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.
				Not used for ":qa" or ":q" when exiting Vim.
							*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.  NOTE: When this autocommand is
				executed, the current buffer "%" may be
				different from the buffer being unloaded