diff options
Diffstat (limited to 'runtime/doc/autocmd.txt')
| -rw-r--r-- | runtime/doc/autocmd.txt | 104 |
1 files changed, 71 insertions, 33 deletions
diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index 180127cd52..740f44414a 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -1,4 +1,4 @@ -*autocmd.txt* For Vim version 7.4. Last change: 2016 Jun 09 +*autocmd.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -8,17 +8,7 @@ Automatic commands *autocommand* 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| + Type |gO| to see the table of contents. ============================================================================== 1. Introduction *autocmd-intro* @@ -30,7 +20,7 @@ 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* + *E203* *E204* *E143* *E855* *E937* 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. @@ -65,7 +55,14 @@ Note: The ":autocmd" command can only be followed by another command when the '|' appears before {cmd}. 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 Note that special characters (e.g., "%", "<cword>") in the ":autocmd" arguments are not expanded when the autocommand is defined. These will be @@ -76,11 +73,15 @@ exception is that "<sfile>" is expanded when the autocmd is defined. Example: 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` 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: > - :autocmd! " Remove ALL autocommands for the current group. + augroup vimrc + autocmd! " Remove all vimrc autocommands + 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: > @@ -127,8 +128,13 @@ prompt. When one command outputs two messages this can happen anyway. :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. + 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]. @@ -304,6 +310,8 @@ Name triggered by ~ |TabNew| when creating a new tab page |TabNewEntered| after entering a new tab page |TabClosed| after closing a tab page +|CmdlineEnter| after entering cmdline mode +|CmdlineLeave| before leaving cmdline mode |CmdwinEnter| after entering the command-line window |CmdwinLeave| before leaving the command-line window @@ -422,8 +430,8 @@ BufUnload Before unloading a buffer. This is when the NOTE: When this autocommand is executed, the current buffer "%" may be different from the buffer being unloaded "<afile>". - Don't change to another buffer, it will cause - problems. + 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* @@ -486,6 +494,28 @@ CmdUndefined When a user command is used but it isn't command is defined. An alternative is to always define the user command and have it invoke an autoloaded function. See |autoload|. + *CmdlineEnter* +CmdlineEnter After moving the cursor to the command line, + where the user can type a command or search + string. + <afile> is set to a single character, + indicating the type of command-line. + |cmdline-char| + Sets these |v:event| keys: + cmdlevel + cmdtype + *CmdlineLeave* +CmdlineLeave Before leaving the command line. + <afile> is set to a single character, + indicating the type of command-line. + |cmdline-char| + Sets these |v:event| keys: + abort (mutable) + cmdlevel + cmdtype + Note: `abort` can only be changed from false + to true. An autocmd cannot execute an already + aborted cmdline by changing it to false. *CmdwinEnter* CmdwinEnter After entering the command-line window. Useful for setting options specifically for @@ -606,7 +636,7 @@ FileChangedShell When Vim notices that the modification time of |timestamp| Mostly triggered after executing a shell command, but also with a |:checktime| command - or when Gvim regains input focus. + 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 @@ -617,7 +647,7 @@ FileChangedShell When Vim notices that the modification time of 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 "<afile>". + 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* @@ -644,7 +674,8 @@ 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'. + 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 @@ -794,7 +825,9 @@ QuickFixCmdPre Before a quickfix command is run (|:make|, |:vimgrepadd|, |:lvimgrepadd|, |:cscope|, |:cfile|, |:cgetfile|, |:caddfile|, |:lfile|, |:lgetfile|, |:laddfile|, |:helpgrep|, - |:lhelpgrep|). + |: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". @@ -919,7 +952,7 @@ TermClose When a terminal buffer ends. {Nvim} *TermOpen* TermOpen When a terminal buffer is starting. This can be used to configure the terminal emulator by - setting buffer variables. |terminal-emulator| + setting buffer variables. |terminal| *TermResponse* TermResponse After the response to |t_RV| is received from the terminal. The value of |v:termresponse| @@ -966,9 +999,9 @@ VimEnter After doing all the startup stuff, including VimLeave Before exiting Vim, just after writing the .shada 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. +< Use |v:dying| to detect an abnormal exit. + Use |v:exiting| to get the exit code. + Not triggered if |v:dying| is 2 or more. *VimLeavePre* VimLeavePre Before exiting Vim, just before writing the .shada file. This is executed only once, @@ -976,9 +1009,9 @@ VimLeavePre Before exiting Vim, just before writing the 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. +< Use |v:dying| to detect an abnormal exit. + Use |v:exiting| to get the exit code. + Not triggered if |v:dying| is 2 or more. *VimResized* VimResized After the Vim window was resized, thus 'lines' and/or 'columns' changed. Not when starting @@ -1002,7 +1035,7 @@ WinLeave Before leaving a window. If the window to be *WinNew* WinNew When a new window was created. Not done for - the fist window, when Vim has just started. + the first window, when Vim has just started. Before a WinEnter event. ============================================================================== @@ -1086,6 +1119,9 @@ Note that for all systems the '/' character is used for path separator (even 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 @@ -1184,10 +1220,12 @@ name! different from existing {event} names, as this most likely will not do what you intended. - *:augroup-delete* *E367* + *: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! This is not checked. + 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}". |