Nvim :help
pages, generated
from source
using the tree-sitter-vimdoc parser.
<F1>
, have no predefined meaning in Vim, these are
good choices to map. Example::map <F2> GoDate: <Esc>:read !date<CR>kJThis shows how three modes are used. After going to the last line with "G", the "o" command opens a new line and starts Insert mode. The text "Date: " is inserted and
<Esc>
takes you out of insert mode.
Notice the use of special keys inside <>. This is called angle bracket
notation. You type these as separate characters, not by pressing the key
itself. This makes the mappings better readable and you can copy and paste
the text without problems.
The ":" character takes Vim to the command line. The ":read !date" command
reads the output from the "date" command and appends it below the current
line. The <CR>
is required to execute the ":read" command.
At this point of execution the text looks like this::imap <F2> <CR>Date: <Esc>:read !date<CR>kJIt looks a lot like the mapping for
<F2>
in Normal mode, only the start is
different. The <F2>
mapping for Normal mode is still there. Thus you can map
the same key differently for each mode.
Notice that, although this mapping starts in Insert mode, it ends in Normal
mode. If you want it to continue in Insert mode, append an "a" to the
mapping.<F7>
so that the command d<F7> deletes a C
program block (text enclosed in curly braces, {}). Similarly y<F7> would yank
the program block into the unnamed register. Therefore, what you need to do
is to define <F7>
to select the current program block. You can do this with
the following command::omap <F7> a{This causes
<F7>
to perform a select block "a{" in operator-pending mode, just
like you typed it. This mapping is useful if typing a { on your keyboard is a
bit difficult.<F2>
:s/^/> /<CR>:noh<CR>``<F2>
:.,$s/^/> /<CR>:noh<CR>``<xHome>
<Home>
<xEnd>
<End>
<Esc>
is displayed in color, it stands for the escape character.
When it has the same color as the other text, it is five characters.<F2>
above could be shortened to::map <F2> G<F3> :imap <F2> <Esc><F3> :map <F3> oDate: <Esc>:read !date<CR>kJFor Normal mode
<F2>
is mapped to go to the last line, and then behave like
<F3>
was pressed. In Insert mode <F2>
stops Insert mode with <Esc>
and then
also uses <F3>
. Then <F3>
is mapped to do the actual work.:map Q gqBut, in rare cases you need to use Ex mode anyway. Let's map "gQ" to Q, so that you can still go to Ex mode:
:map gQ QWhat happens now is that when you type "gQ" it is mapped to "Q". So far so good. But then "Q" is mapped to "gq", thus typing "gQ" results in "gq", and you don't get to Ex mode at all. To avoid keys to be mapped again, use the ":noremap" command:
:noremap gQ QNow Vim knows that the "Q" is not to be inspected for mappings that apply to it. There is a similar command for every mode:
vim *.txt
. You are now editing the
first file. Define this mapping::map ,, :s/5.1/5.2/<CR>:wnext<CR>,,Now you type ",,". This triggers the mapping. It replaces "5.1" with "5.2" in the first line. Then it does a ":wnext" to write the file and edit the next one. The mapping ends in ",,". This triggers the same mapping again, thus doing the substitution, etc. This continues until there is an error. In this case it could be a file where the substitute command doesn't find a match for "5.1". You can then make a change to insert "5.1" and continue by typing ",," again. Or the ":wnext" fails, because you are in the last file in the list. When a mapping runs into an error halfway, the rest of the mapping is discarded.
CTRL-C
interrupts the mapping (CTRL-Break
on MS-Windows).:map <C-A> /---><CR> :vunmap <C-A>Notice that the five characters "<C-A>" stand for the single key
CTRL-A
.<Bar>
(five characters). Example:
:map <F8> :write <Bar> !checkin %:S<CR>The same problem applies to the ":unmap" command, with the addition that you have to watch out for trailing white space. These two commands are different:
:unmap a | unmap b :unmap a| unmap bThe first command tries to unmap "a ", with a trailing space.
<Space>
(seven characters)::map <Space> WThis makes the spacebar move a blank-separated word forward.
|"
, this
starts a new, empty command with a comment. Example::map <Space> W| " Use spacebar to move forward a word
:imap aa foo :imap aaa barNow, when you type "aa", Vim doesn't know if it should apply the first or the second mapping. It waits for another character to be typed. If it is an "a", the second mapping is applied and results in "bar". If it is a space, for example, the first mapping is applied, resulting in "foo", and then the space is inserted.
<script>
keyword can be used to make a mapping local to a script. See
:map-<script>.<buffer>
keyword can be used to make a mapping local to a specific buffer.
See :map-<buffer><unique>
keyword can be used to make defining a new mapping fail when it
already exists. Otherwise a new mapping simply overwrites the old one. See
:map-<unique>.<Nop>
(five characters). This will make
the <F7>
key do nothing at all::map <F7> <Nop>| map! <F7> <Nop>There must be no space after
<Nop>
.40.2
Defining command-line commands:command DeleteFirst 1deleteNow when you execute the command ":DeleteFirst" Vim executes ":1delete", which deletes the first line.
:commandJust like with the builtin commands, the user defined commands can be abbreviated. You need to type just enough to distinguish the command from another. Command line completion can be used to get the full name.
:command -nargs=0 DeleteFirst 1deleteHowever, because zero arguments is the default, you do not need to add "-nargs=0". The other values of -nargs are as follows:
<args>
keyword. For example::command -nargs=+ Say :echo "<args>"Now when you type
:Say Hello WorldVim echoes "Hello World". However, if you add a double quote, it won't work. For example:
:Say he said "hello"To get special characters turned into a string, properly escaped to use as an expression, use "<q-args>":
:command -nargs=+ Say :echo <q-args>Now the above ":Say" command will result in this to be executed:
:echo "he said \"hello\""The
<f-args>
keyword contains the same information as the <args>
keyword,
except in a format suitable for use as function call arguments. For example:
:command -nargs=* DoIt :call AFunction(<f-args>) :DoIt a b cExecutes the following command:
:call AFunction("a", "b", "c")
{count}
.<line1>
and <line2>
get the values of
the first and last line in the range. For example, the following command
defines the SaveIt command, which writes out the specified range to the file
"save_file"::command -range=% SaveIt :<line1>,<line2>write! save_file
{number}
. The resulting count can be used
through the <count>
keyword.
-bang You can use a !. If present, using <bang>
will
result in a !.
-register You can specify a register. (The default is
the unnamed register.)
The register specification is available as
<reg>
(a.k.a. <register>
).
-complete={type} Type of command-line completion used. See
:command-completion for the list of possible
values.
-bar The command can be followed by | and another
command, or " and a comment.
-buffer The command is only available for the current
buffer.<lt>
keyword. It stands for the character <. Use this
to escape the special meaning of the <> items mentioned.:command -nargs=+ Say :echo "<args>" :command! -nargs=+ Say :echo <q-args>To delete a user command use ":delcommand". It takes a single argument, which is the name of the command. Example:
:delcommand SaveItTo delete all the user commands:
:comclearCareful, this can't be undone!
40.3
Autocommands:function DateInsert() : $delete : read !date :endfunctionYou want this function to be called each time, just before a buffer is written to a file. This will make that happen:
:autocmd BufWritePre * call DateInsert()"BufWritePre" is the event for which this autocommand is triggered: Just before (pre) writing a buffer to a file. The "*" is a pattern to match with the file name. In this case it matches all files. With this command enabled, when you do a ":write", Vim checks for any matching BufWritePre autocommands and executes them, and then it performs the ":write". The general form of the :autocmd command is as follows:
:autocmd [group] {events} {file-pattern} [++nested] {command}The [group] name is optional. It is used in managing and calling the commands (more on this later). The
{events}
parameter is a list of events (comma
separated) that trigger the command.
{file-pattern}
is a filename, usually with wildcards. For example, using
"*.txt" makes the autocommand be used for all files whose name end in ".txt".
The optional [++nested] flag allows for nesting of autocommands (see below),
and finally, {command}
is the command to be executed.:augroup updateDate : autocmd! : autocmd BufWritePre * call DateInsert() :augroup ENDThis will delete any previously defined autocommand with
:autocmd!
before
defining the new one. Groups are explained later.:autocmd BufReadPost *.gsm set filetype=asmIf Vim is able to detect the type of file, it will set the 'filetype' option for you. This triggers the Filetype event. Use this to do something when a certain type of file is edited. For example, to load a list of abbreviations for text files:
:autocmd Filetype text source ~/.config/nvim/abbrevs.vimWhen starting to edit a new file, you could make Vim insert a skeleton:
:autocmd BufNewFile *.[ch] 0read ~/skeletons/skel.cSee autocmd-events for a complete list of events.
{file-pattern}
argument can actually be a comma-separated list of file
patterns. For example: *.c,*.h
matches files ending in ".c" and ".h".
The usual file wildcards can be used. Here is a summary of the most often
used ones:{command}
at the end and use a !. Example::autocmd! FileWritePre *This will delete all autocommands for the "FileWritePre" event that use the "*" pattern.
:autocmdThe list can be very long, especially when filetype detection is used. To list only part of the commands, specify the group, event and/or pattern. For example, to list all BufNewFile autocommands:
:autocmd BufNewFileTo list all autocommands for the pattern "*.c":
:autocmd * *.cUsing "*" for the event will list all the events. To list all autocommands for the cprograms group:
:autocmd cprograms
{group}
item, used when defining an autocommand, groups related autocommands
together. This can be used to delete all the autocommands in a certain group,
for example.
When defining several autocommands for a certain group, use the ":augroup"
command. For example, let's define autocommands for C programs::augroup cprograms : autocmd BufReadPost *.c,*.h :set sw=4 sts=4 : autocmd BufReadPost *.cpp :set sw=3 sts=3 :augroup ENDThis will do the same as:
:autocmd cprograms BufReadPost *.c,*.h :set sw=4 sts=4 :autocmd cprograms BufReadPost *.cpp :set sw=3 sts=3To delete all autocommands in the "cprograms" group:
:autocmd! cprograms
:autocmd FileChangedShell * ++nested edit
:autocmd BufReadPost *.new execute "doautocmd BufReadPost " . expand("<afile>:r")This defines an autocommand that is triggered when a new file has been edited. The file name must end in ".new". The ":execute" command uses expression evaluation to form a new command and execute it. When editing the file "tryout.c.new" the executed command will be:
:doautocmd BufReadPost tryout.cThe expand() function takes the "<afile>" argument, which stands for the file name the autocommand was executed for, and takes the root of the file name with ":r".
:autocmd BufReadPost *.log normal GThis will make the cursor jump to the last line of
*.log
files when you start
to edit it.
Using the ":normal" command is a bit tricky. First of all, make sure its
argument is a complete command, including all the arguments. When you use "i"
to go to Insert mode, there must also be a <Esc>
to leave Insert mode again.
If you use a "/" to start a search pattern, there must be a <CR>
to execute
it.
The ":normal" command uses all the text after it as commands. Thus there
can be no | and another command following. To work around this, put the
":normal" command inside an ":execute" command. This also makes it possible
to pass unprintable characters in a convenient way. Example::autocmd BufReadPost *.chg execute "normal ONew entry:\<Esc>" | \ 1read !dateThis also shows the use of a backslash to break a long command into more lines. This can be used in Vim scripts (not at the command line).
:set eventignore=WinEnter,WinLeaveTo ignore all events, use the following command:
:set eventignore=allTo set it back to the normal behavior, make 'eventignore' empty:
:set eventignore=