This is autocmd.txt in view mode; [Download] [Up]
*autocmd.txt* For Vim version 5.0f. Last modification: 1997 Apr 21
VIM REFERENCE MANUAL by Bram Moolenaar
Automatic commands *autocommand*
1. Introduction |autocmd-intro|
2. Defining autocommands |autocmd-define|
3. Events |autocmd-events|
4. 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 a 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}. It is not added if it is already there (as may
happen when .vimrc is sourced again). The order of
entering {cmd} and {pat} is important. 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|.
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.
==============================================================================
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. 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.
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 a path separator
character (eg '/' on Unix) 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 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".
vim:tw=78:ts=8:sw=8:
These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.