Vim Reference
From: https://www.cs.ucdavis.edu/~matloff/matloff/public_html/Vim/Doc.html
*vim_ref.txt* For Vim version 4.5. Last modification: 1996 Oct 2
VIM REFERENCE MANUAL
By Bram Moolenaar
There is a contents listing at the end of this document.
This manual mostly assumes that there is only one window. The commands and
options for multiple windows and buffers are explained in |vim_win.txt|.
This manual describes running Vim from a normal terminal or with a terminal
emulator in a window. See |vim_gui.txt| for the GUI version.
You can use tags to jump to the explanation of a subject. Position the cursor
on an item name between bars (e.g., |intro|) or an option name in single
quotes (e.g., 'textwidth' ) and hit CTRL-]. This mostly also works on a
command in double quotes (e.g., ":buf"). Three special characters in the
names of the tags are not allowed. They have been replaced with letters:
"bar" for '|', "star" for '*', and "quote" for '"'.
tag starts with example
Normal and Visual mode nothing |x|
Visual mode "v_" |v_u|
Insert mode "i_" |i_|
Command line commands ":" |:quit|
Command line editing "c_" |c_|
Vim command options "-" |-r|
Vim options "'" |'shell'|
1. Introduction *intro*
===============
Vim stands for Vi IMproved. It used to be Vi IMitation, but there are so many
improvements that a name change was appropriate. Vim is a text editor which
includes almost all the commands from the Unix program "Vi" and a lot of new
ones. It is very useful for editing programs and other 8-bit ASCII text. All
commands are given with the keyboard. This has the advantage that you can
keep your fingers on the keyboard and your eyes on the screen. For those who
want it, there is mouse support and a GUI version with scrollbars and menus
(see |vim_gui.txt|).
Throughout this manual the differences between Vi and Vim are mentioned in
curly braces. See |vim_diff.txt| for a summary of the differences.
This manual refers to Vim on various machines. There may be small differences
between different computers and terminals. Besides the remarks given in this
document, there is a separate document for each supported system:
system see
Amiga |vim_ami.txt|
Archimedes |vim_arch.txt|
Atari MiNT |vim_mint.txt|
Macintosh |vim_mac.txt|
MS-DOS |vim_dos.txt|
OS/2 |vim_os2.txt|
Unix |vim_unix.txt|
Win32: Windows NT / Windows 95 |vim_w32.txt|
This manual is a reference for all the Vim commands and options. This is not
an introduction to the use of Vim. There are many books on vi that contain a
section for beginners.
A summary of this manual can be found in the file "vim_help.txt",
|vim_help.txt|. It can be accessed from within Vim with the or
key and with the command ":help", |:help|. The 'helpfile' option can be set
to the name of the help file, so you can put it in any place you like.
2. Notation *notation*
===========
[] Characters in square brackets are optional.
*count*
[count] An optional number that may precede the command to multiply
or iterate the command. If no number is given, a count of one
is used, unless otherwise noted. Note that in this manual the
[count] is not mentioned in the description of the command,
but only in the explanation. This was done to make the
commands easier to lookup. If the "sc" option is on
(|'showcmd'|), the (partially) entered count is shown at the
bottom of the window. You can use to erase the last
digit (|N|).
["x] An optional register designation where text can be stored.
See |registers|. The x is a single character between 'a' and
'z' or 'A' and 'Z' or '"', and in some cases (with the put
command) between '0' and '9', '%', ':', or '.'. The uppercase
and lowercase letters designate the same register, but the
lowercase letter is used to overwrite the previous register
contents, while the uppercase letter is used to append to the
previous register contents. Without the ""x" or with """",
the stored text is put into the unnamed register.
{} Curly braces denote parts of the command which must appear,
but which can take a number of different values. The
differences between Vim and Vi are also given in curly braces
(this will be clear from the context).
*{motion}*
{motion} A command that moves the cursor. See the list in chapter 6,
|cursor_motions|. This is used after an operator command
|operator| to move over the text that is to be operated upon.
If the motion includes a count and the operator also had a
count, the two counts are multiplied. For example: "2d3w"
deletes six words. The motion can also be a mouse click. The
mouse is currently only supported for MS-DOS, Win32 and xterm
under Unix.
*{Visual}*
{Visual} A piece of text that is started with the "v", "V", or CTRL-V
command and ended by the cursor position. This is used
before an operator command |operator| to highlight the text
that is to be operated upon. See the chapter on Visual mode
|Visual_mode|.
A special character from the table below or a single ASCII
character.
'character' A single ASCII character.
A single character from the range to . For
example: is a lowercase letter. Multiple ranges may be
concatenated. For example, is any alphanumeric
character.
CTRL-{char} {char} typed as a control character; that is, typing {char}
while holding the CTRL key down. The case of {char} does not
matter; thus CTRL-A and CTRL-a are equivalent. But on some
terminals, using the SHIFT key will produce another code,
don't use it then.
'option' An option, or parameter, that can be set to a value, is
enclosed in single quotes. See chapter 19, |options|.
"command" In examples, the commands you can type are enclosed in double
quotes.
*key_notation*
notation meaning equivalent decimal value(s)
-----------------------------------------------------------------------
zero CTRL-@ 0 (stored as 10)
backspace CTRL-H 8 *backspace*
tab CTRL-I 9 *tab*
*linefeed*
linefeed CTRL-J 10 (used for )
*carriage return*
carriage return CTRL-M 13
escape CTRL-[ 27 *escape*
space 32 *space*
delete 127
cursor-up *cursor-up* *cursor_up*
cursor-down *cursor-down* *cursor_down*
cursor-left *cursor-left* *cursor_left*
cursor-right *cursor-right* *cursor_right*
shift-cursor-up
shift-cursor-down
shift-cursor-left
shift-cursor-right
- function keys 1 to 12 *function_key* *function-key*
- shift-function keys 1 to 12
help key
undo key
insert key
home *home*
end *end*
page-up *page_up* *page-up*
page-down *page_down* *page-down*
keypad home (upper left) *keypad_home*
keypad end (lower left) *keypad_end*
keypad page-up (upper right) *keypad_page_up*
keypad page-down (lower right) *keypad_page_down*
shift-key *shift*
control-key *control* *ctrl*
alt-key or meta-key *meta* *alt*
key with "xx" entry in termcap
-----------------------------------------------------------------------
Note: The shifted cursor keys, the help key, and the undo key are only
available on a few terminals. On the Amiga, shifted function key 10 produces
a code (CSI) that is also used by key sequences. It will be recognized only
after typing another key.
Note: There are two codes for the delete key. 127 is the decimal ASCII value
for the delete key, which is always recognized. Some delete keys send another
value, in which case this value is obtained from the termcap entry "kD". Both
values have the same effect. Also see |:fixdel|.
Note: The keypad keys are used in the same way as the corresponding "normal"
keys. For example, has the same effect as . If a keypad key
sends the same raw key code as it non-keypad equivalent, it will be recognized
as the non-keypad code. For example, when sends the same code as
, when pressing Vim will think was pressed. Mapping
will not work then.
*<>*
Some of the examples are given in the <> notation. The rules are:
1. Any printable characters are typed directly, except backslash and '<'
2. A backslash is represented with "\\", double backslash.
3. A real '<' is represented with "\<".
4. "" means the special key typed. This is the notation explained in
the table above. A few examples:
Escape key
CTRL-G
cursor up key
Control- left mouse click
Shifted function key 11
Meta- a ('a' with bit 8 set)
Meta- A ('A' with bit 8 set)
"kd" termcap entry (cursor down key)
If you want to use the full <> notation in Vim, you have to remove the 'B'
flag from 'cpoptions' and make sure the '<' flag is excluded (it already is by
default).
:set cpo=ceFs
If you have the 'B' flag in 'cpoptions', then <> notation mostly still works,
but you can't escape the special meaning of key names in <> with a backslash.
To distinguish using <> with and without the 'B' flag, it's called full <>
notation if the 'B' flag is excluded.
For mapping, abbreviation and menu commands you can then copy-paste the
examples and use them directly. Or type them literally, including the '<' and
'>' characters. This does NOT work for other commands, like ":set" and
":autocmd"!
3. Starting Vim *starting*
===============
3.1 Vim arguments *vim_arguments*
Most often, Vim is started to edit a single file with the command
vim file *-vim*
More generally, Vim is started with:
vim [options] [arglist]
If the arglist is missing, the editor will start with an empty buffer.
Otherwise exactly one out of the following three may be used to choose one
or more files to be edited.
*-file* *--*
file .. A list of file names. The first one will be the current file
and read into the buffer. The cursor will be positioned on
the first line of the buffer. To avoid a file name starting
with a '-' being interpreted as an option, precede the arglist
with "--", e.g.:
Vim -- -filename
*-t* *-tag*
-t {tag} A tag. "tag" is looked up in the tags file, the associated
file becomes the current file, and the associated command is
executed. Mostly this is used for C programs. In that case,
"tag" should be a function name. The effect is that the file
containing that function becomes the current file and the
cursor is positioned on the start of the function (see the
section on tags, |tags|).
*-e* *-qf*
-e [errorfile] QuickFix mode. The file with the name [errorfile] is read
and the first error is displayed. If [errorfile] is not
given, the 'errorfile' option is used for the file name
(default "AztecC.Err" for the Amiga, "errors.vim" for other
systems). See section 5.5: "using the QuickFix mode",
|quickfix|. {not in Vi}
*startup-options*
The options, if present, must precede the arglist. The options may be given
in any order. Single-letter options can be combined after one dash.
*-+*
+[num] The cursor will be positioned on line "num" for the first
file being edited. If "num" is missing, the cursor will be
positioned on the last line.
*-+/*
+/{pat} The cursor will be positioned on the first line containing
"pat" in the first file being edited (see the section
"pattern searches" for the available search patterns,
|search_pattern|).
+{command} *-+c* *-c*
-c {command} "command" will be executed after the first file has been
read (and after autocommands and modelines for that file have
been processed). "command" is interpreted as an Ex command.
If the "command" contains spaces, it must be enclosed in
double quotes (this depends on the shell that is used).
Example: vim "+set si" main.c
Note: You can use only one "+" or "-c" argument in a Vim
command.
*-r*
-r Recovery mode. Without a file name argument, a list of
existing swap files is given. With a file name, a swap file
is read to recover a crashed editing session. See the
chapter "Recovery after a crash", |crash_recovery|.
*-L*
-L Same as -r. {only in some versions of Vi: "List recoverable
edit sessions"}
*-v*
-v View mode. The 'readonly' option will be set for all the
files being edited. You can still edit the buffer, but will
be prevented from accidentally overwriting a file. If you
forgot that you are in View mode and did make some changes,
you can overwrite a file by adding an exclamation mark to
the Ex command, as in ":w!". The 'readonly' option can be
reset with ":set noro" (see the options chapter, |options|).
Subsequent edits will not be done in readonly mode. Calling
the executable "view" has the same effect as the -v option.
If your system does not support links and you do not want to
have the executable twice, you could make an alias: "alias
view vim -v". The 'updatecount' option will be set to 10000,
meaning that the swap file will not be updated automatically
very often. {Vi: "ex -v" means to start ex in vi mode.
"vi -v" does nothing}
*-R*
-R Readonly mode. Same as -v.
*-b*
-b Binary mode. The 'textauto', 'textmode', and 'expandtab'
options will be reset. The 'textwidth' option is set to 0.
'modeline' is reset. The 'binary' option is set. This is
done after reading the vimrc/exrc files but before reading
any file in the arglist. See also 5.6:
"Editing binary files", |edit_binary|. {not in Vi}
*-l*
-l Lisp mode. Sets the 'lisp' and 'showmatch' options on.
*-H*
-H Hebrew mode. Sets the 'hkmap' and 'rightleft' options on.
(Only when compiled with LEFTRIGHT defined, otherwise Vim
gives an error message and exits). {not in Vi}
*-n*
-n No swap file will be used. Recovery after a crash will be
impossible. Handy if you want to view or edit a file on a
very slow medium (e.g., a floppy). Can also be done with
":set updatecount=0". You can switch it on again by setting
the 'updatecount' option to some value, e.g., ":set uc=100".
{not in Vi}
*-o*
-o[N] Open N windows. If [N] is not given, one window is opened
for every file given as argument. If there is not enough
room, only the first few files get a window. If there are
more windows than arguments, the last few windows will be
editing an empty file. {not in Vi}
*-T*
-T {terminal} Set the terminal type to "terminal". This influences the
codes that Vim will send to your terminal. This is normally
not needed, because Vim will be able to find out what type
of terminal you are using (See chapter 20, |terminal_info|).
{not in Vi}
*-d*
-d {device} Amiga only: The "device" is opened to be used for editing.
Normally you would use this to set the window position and
size: "-d con:x/y/width/height", e.g.,
"-d con:30/10/600/150". But you can also use it to start
editing on another device, e.g., AUX:. {not in Vi}
*-x*
-x Amiga only: Do not restart Vim to open a new window. This
option should be used when Vim is started by a program that
will wait for the edit session to finish (e.g., mail or
readnews). See section 3.3, |amiga_window|. {not in Vi}
*-f*
-f GUI only: Do not disconnect from the program that started Vim.
'f' stands for "foreground". If omitted, the GUI forks a new
process and exits the current one. "-f" should be used when
gvim is started by a program that will wait for the edit
session to finish (e.g., mail or readnews). If you want gvim
never to fork, include 'f' in 'guioptions'. Careful: You can
use "-gf" to start the GUI in the foreground, but "-fg" is
used to specify the foreground color. {not in Vi} |gui_fork|
*-u*
-u {vimrc} The file "vimrc" is read for initializations. Other
initializations are skipped; see |initialization|. This can
be used to start Vim in a special mode, with special
mappings and settings. A shell alias can be used to make
this easy to use. For example:
"alias vimc vim -u ~/.c_vimrc !*".
Also consider using autocommands; see |autocommand|.
When {vimrc} is equal to "NONE" (all uppercase), all
initializations from files and environment variables are
skipped. {not in Vi}
*-i*
-i {viminfo} The file "viminfo" is used instead of the default viminfo
file. If the name "NONE" is used (all uppercase), no viminfo
file is read or written, even if 'viminfo' is set or when
":rv" or ":wv" are used. See also |viminfo_file|. {not in Vi}
*-s*
-s {scriptin} The script file "scriptin" is read. The characters in the
file are interpreted as if you had typed them. The same can
be done with the command ":source! {scriptin}". If the end
of the file is reached before the editor exits, further
characters are read from the keyboard. See also the section
"complex repeats", |complex_repeat|. {not in Vi}
*-w*
-w {scriptout} All the characters that you type are recorded in the file
"scriptout", until you exit Vim. This is useful if you want
to create a script file to be used with "vim -s" or
":source!". When the "scriptout" file already exists, new
characters are appended. See also the section "complex
repeats", |complex_repeat|. {not in Vi}
*-W*
-W {scriptout} Like -w, but do not append, overwrite an existing file. {not
in Vi}
*-w_nr*
-w{number} Does nothing. This was included for Vi-compatibility. In Vi
it sets the 'window' option, which is not implemented in Vim.
Example for using a script file to change a name in several files:
Create a file "subs.vi" containing substitute commands and a :wq
command:
:%s/Jones/Smith/g
:%s/Allen/Peter/g
:wq
Execute Vim on all files you want to change:
foreach i ( *.let ) vim -s subs.vi $i
If the executable is called "view", Vim will start in Readonly mode. This is
useful if you can make a hard or symbolic link from "view" to "vim".
Starting in Readonly mode can also be done with "vim -v".
3.2 Workbench (Amiga only) *workbench*
Vim can be started from the workbench by clicking on its icon twice. It will
then start with an empty buffer.
Vim can be started to edit one or more files by using a "Project" icon. The
"Default Tool" of the icon must be the full pathname of the Vim executable.
The name of the ".info" file must be the same as the name of the text file.
By clicking on this icon twice, Vim will be started with the filename as
current filename, which will be read into the buffer (if it exists). You can
edit multiple files by pressing the shift key while clicking on icons, and
clicking twice on the last one. The "Default Tool" for all these icons must
be the same.
It is not possible to give arguments to Vim, other than filenames, from the
workbench.
3.3 Vim window (Amiga only) *amiga_window*
Vim will run in the CLI window where it was started. If Vim was started with
the "run" or "runback" command, or if Vim was started from the workbench, it
will open a window of its own.
Technical detail:
To open the new window a little trick is used. As soon as Vim
recognizes that it does not run in a normal CLI window, it will
create a script file in "t:". This script file contains the same
command as the one Vim was started with, and an "endcli" command. This
script file is then executed with a "newcli" command (the "c:run" and
"c:newcli" commands are required for this to work). The script file
will hang around until reboot, or until you delete it. This method
is required to get the ":sh" and ":!" commands to work correctly.
But when Vim was started with the -e option (Quickfix mode) or with
the -x option, this method is not used. The reason for this is that
when a compiler starts Vim with the -e option it will wait for a
return code. With the script trick, the compiler cannot get the
return code. The -x option can be used when Vim is started by a mail
program which also waits for the edit session to finish. As a
consequence, the ":sh" and ":!" commands are not available when the
-e or -x option is used.
Vim will automatically recognize the window size and react to window
resizing. Under Amiga DOS 1.3, it is advised to use the fastfonts program,
"FF", to speed up display redrawing.
3.4 Initialization *initialization* *startup*
This section is about the non-GUI version of Vim. See |gui_fork| for
additional initialization when starting the GUI.
At startup, Vim checks environment variables and files and sets values
accordingly. Vim proceeds in this order:
1. Setting the 'shell' option *SHELL* *COMSPEC*
The environment variable SHELL, if it exists, is used to set the
'shell' option. On MS-DOS and Win32, the COMPSPEC variable is used
if SHELL is not set.
2. Setting the 'term' option *TERM*
The environment variable TERM, if it exists, is used to set the 'term'
option.
3. Reading Ex commands from environment variables and/or files
An environment variable is read as one Ex command line, where multiple
commands must be separated with '|' or "".
*vimrc* *exrc*
A file that contains initialization commands is called a "vimrc" file.
Each line in a vimrc file is executed as an Ex command line. It is
sometimes also referred to as "exrc" file. They are the same type of
file, but "exrc" is what Vi always used, "vimrc" is a Vim specific
name.
If Vim was started with "-u filename", the file "filename" is used.
All following initializations until 4. are skipped.
"vim -u NONE" can be used to skip these initializations. |-u|
a. For Unix the system vimrc file is read for initializations. The path
of this file is shown with the ":version" command.
*VIMINIT* *.vimrc* *_vimrc* *EXINIT* *.exrc* *_exrc*
b. Four places are searched for initializations. The first that exists
is used, the others are ignored.
- The environment variable VIMINIT
- The user vimrc file:
"~/.vimrc" (for Unix and OS/2)
"s:.vimrc" (for Amiga)
"$VIM\_vimrc" (for MS-DOS and Win32)
Note: For Unix, OS/2 and Amiga, when ".vimrc" does not exist,
"_vimrc" is also tried, in case an MS-DOS compatible file
system is used. For MS-DOS and Win32 ".vimrc" is checked
after "_vimrc", in case long file names are used.
If $VIM is not set, $HOME is used.
- The environment variable EXINIT
- The user exrc file:
"~/.exrc" (for Unix and OS/2)
"s:.exrc" (for Amiga)
"$VIM\_exrc" (for MS-DOS and Win32).
c. If the 'exrc' option is on (which is not the default), the current
directory is searched for three files. The first that exists is used,
the others are ignored.
- The file ".vimrc" (for Unix, Amiga and OS/2)
"_vimrc" (for MS-DOS and Win32)
- The file "_vimrc" (for Unix, Amiga and OS/2)
".vimrc" (for MS-DOS and Win32)
- The file ".exrc" (for Unix, Amiga and OS/2)
"_exrc" (for MS-DOS and Win32)
4. Setting 'shellpipe' and 'shellredir'
The 'shellpipe' and 'shellredir' options are set according to the
value of the 'shell' option, unless they have been set before.
This means that Vim will figure out the values of 'shellpipe' and
'shellredir' for you, unless you have set them yourself.
5. Read the viminfo file
If the 'viminfo' option is not empty, the viminfo file is read. The
default is empty, so 'viminfo' must have been set by one of the
previous initializations. See |viminfo_file|.
Some hints on using initializations:
Standard setup:
Create a vimrc file to set the default settings and mappings for all your edit
sessions. Put it in a place so that it will be found by 3b:
~/.vimrc (Unix and OS/2)
s:.vimrc (Amiga)
$VIM\_vimrc (MS-DOS and Win32)
Local setup:
Put all commands that you need for editing a specific directory only into a
vimrc file and place it in that directory under the name ".vimrc" ("_vimrc"
for MS-DOS and Win32). NOTE: To make Vim look for these special files you
have to turn on the option 'exrc'. See |trojan_horse| too.
System setup:
This only applies if you are managing a Unix system with several users and
want to set the defaults for all users. Create a vimrc file with commands
for default settings and mappings and put it in the place that is given with
the ":version" command.
Saving the current state of Vim to a file:
Whenever you have changed values of options or when you have created a
mapping, then you may want to save them in a vimrc file for later use. See
|save_settings| about saving the current state of settings to a file.
Avoiding setup problems for Vi users:
Vi uses the variable EXINIT and the file "~/.exrc". So if you do not want to
interfere with Vi, then use the variable VIMINIT and the file "vimrc" instead.
Amiga environment variables:
On the Amiga, two types of environment variables exist. The ones set with the
DOS 1.3 (or later) setenv command are recognized. See the AmigaDos 1.3
manual. The environment variables set with the old Manx Set command (before
version 5.0) are not recognized.
MS-DOS line separators:
On MS-DOS-like systems (MS-DOS itself, Win32, and OS/2), Vim assumes that all
the vimrc files have pairs as line separators. This will give
problems if you have a file with only s and have a line like
":map xx yy^M". The trailing ^M will be ignored.
Avoiding trojan horses: *trojan_horse*
While reading the "vimrc" or the "exrc" file in the current directory, some
commands can be disabled for security reasons by setting the 'secure' option.
This is always done when executing the command from a tags file. Otherwise it
would be possible that you accidentally use a vimrc or tags file that somebody
else created and contains nasty commands. The disabled commands are the ones
that start a shell, the ones that write to a file, and ":autocmd". The ":map"
commands are echoed, so you can see which keys are being mapped.
If you want Vim to execute all commands in a local vimrc file, you
can reset the 'secure' option in the EXINIT or VIMINIT environment variable or
in the global "exrc" or "vimrc" file. This is not possible in "vimrc" or
"exrc" in the current directory, for obvious reasons.
On Unix systems, this only happens if you are not the owner of the
vimrc file. Warning: If you unpack an archive that contains a vimrc or exrc
file, it will be owned by you. You won't have the security protection. Check
the vimrc file before you start Vim in that directory, or reset the 'exrc'
option. Some Unix systems allow a user to do "chown" on a file. This makes
it possible for another user to create a nasty vimrc and make you the owner.
Be careful!
When using tag search commands, executing the search command (the last
part of the line in the tags file) is always done in secure mode. This works
just like executing a command from a vimrc/exrc in the current directory.
*slow_start*
If Vim takes a long time to start up, there may be a few causes:
- If the Unix version was compiled with the GUI and/or X11 (check the output
of ":version" for "+GUI" and "+X11"), it may need to load shared libraries
and connect to the X11 server. Try compiling a version with GUI and X11
disabled. This also should make the executable smaller.
- If you have "viminfo" enabled, the loading of the viminfo file may take a
while. You can find out if this is the problem by disabling viminfo for a
moment (use the Vim argument "-i NONE", |-i|). Try reducing the number of
lines stored in a register with ":set viminfo='20\"50".
|viminfo_file|.
3.5 Suspending *suspend*
*CTRL-Z* *v_CTRL-Z*
CTRL-Z On Unix systems: Suspend Vim. On other systems:
start a new shell (like ":sh"). Same as ":stop".
Works in Normal and in Visual mode. In Insert and
Command-line mode, the CTRL-Z is inserted as a normal
character.
:sus[pend][!] or *:sus* *:suspend* *:st* *:stop*
:st[op][!] Suspend the editor. If the '!' is not given, the
buffer was changed, 'autowrite' is set, and a filename
is known, the buffer will be written.
On many Unix systems, it is possible to suspend Vim with CTRL-Z. This is only
possible in Normal and Visual mode (see next chapter, |vim_modes|). Vim will
continue if you make it the foreground job again. On other systems, CTRL-Z
will start a new shell. This is the same as the ":sh" command. Vim will
continue if you exit from the shell.
3.6 The viminfo file *viminfo_file*
The viminfo file is used to store:
- The command line history.
- The search string history.
- Contents of registers.
- Marks for several files.
- File marks, pointing to locations in files.
- Last search/substitute pattern (for 'n' and '&').
The viminfo file is only supported when Vim has been compiled with VIMINFO
defined. If the output of ":version" contains "+viminfo" then it was; if it
contains "-viminfo" then it wasn't. By default, VIMINFO is defined.
When Vim is started and the 'viminfo' option is non-empty, the contents of
the viminfo file are read and the info can be used in the appropriate places.
The marks are not read in at startup (but file marks are). See
|initialization| for how to set the 'viminfo' option upon startup.
When Vim is exited and 'viminfo' is non-empty, the info is stored in the
viminfo file (it's actually merged with the existing one, if one exists). The
'viminfo' option is a string containing information about what info should be
stored, and contains limits on how much should be stored (see 'viminfo').
Marks are stored for each file separately. When a file is read and 'viminfo'
is non-empty, the marks for that file are read from the viminfo file. NOTE:
The marks are only written when exiting Vim, which is fine because marks are
remembered for all the files you have opened in the current editing session,
unless ":bdel" is used. If you want to save the marks for a file that you are
about to abandon with ":bdel", use ":wv". The '[' and ']' marks are not
stored, but the '"' mark is. The '"' mark is very useful for jumping to the
cursor position when the file was last exited. No marks are saved for files
that start with any string given with the "r" flag in 'viminfo'. This can be
used to avoid saving marks for files on removable media (for MS-DOS you would
use "ra:,rb:", for Amiga "rdf0:,rdf1:,rdf2:").
*viminfo_file_marks*
Uppercase marks ('A to 'Z) are stored when writing the viminfo file. The
numbered marks ('0 to '9) are a bit special. When the viminfo file is written
(when exiting or with the ":wviminfo" command), '0 is set to the current cursor
position and file. The old '0 is moved to '1, '1 to '2, etc. This
resembles what happens with the "1 to "9 delete registers. If the current
cursor position is already present in '0 to '9, it is moved to '0, to avoid
having the same position twice. The result is that with "'0", you can jump
back to the file and line where you exited Vim.
The default name of the viminfo file is "$HOME/.viminfo" for Unix,
"s:.viminfo" for Amiga, "$VIM\viminfo" for MS-DOS and Win32. The "-i" Vim
argument can be used to set another file name, |-i|. For the commands below,
another file name can be given, overriding the default and the name given with
"-i". When the file name given with the "-i" Vim argument is "NONE"
(all uppercase), no viminfo file is ever read or written.
Two commands can be used to read and write the viminfo file manually. This
can be used to exchange registers between two running Vim programs: First
type ":wv" in one and then ":rv" in the other. Note that if the register
already contained something, then ":rv!" would be required. Also note
however that this means everything will be overwritten with information from
the first Vim, including the command line history, etc.
The viminfo file itself can be edited by hand too, although we suggest you
start with an existing one to get the format right. It is reasonably
self-explanatory once you're in there. This can be useful in order to
create a second file, say "~/.my_viminfo" which could contain certain
settings that you always want when you first start Vim. For example, you
can preload registers with particular data, or put certain commands in the
command line history. A line in your .vimrc file like
rviminfo! ~/.my_viminfo
can be used to load this information. You could even have different viminfos
for different types of files (e.g., C code) and load them based on the file
name, using the ":autocmd" command (see |:autocmd|).
*viminfo_errors*
When Vim detects an error while reading a viminfo file, it will not overwrite
that file. If there are more than 10 errors, Vim stops reading the viminfo
file. This was done to avoid accidently destroying a file when the filename
of the viminfo file is wrong. This could happen when accidently typing "vim
-i file" when you wanted "vim -v file" (yes, somebody accidently did that!).
If you want to overwrite a viminfo file with an error in it, you will either
have to fix the error, or delete the file (while Vim is running, so most of
the information will be restored).
*:rv* *:rviminfo*
:rv[iminfo][!] [file] Read from viminfo file [file] (default: see above).
If [!] is given, then any information that is
already set (registers, marks, etc.) will be
overwritten. {not in Vi}
*:wv* *:wviminfo*
:wv[iminfo][!] [file] Write to viminfo file [file] (default: see above).
The information in the file is first read in to make
a merge between old and new info. When [!] is used,
the old information is not read first, only the
internal info is written. If 'viminfo' is empty, marks
for up to 100 files will be written. {not in Vi}
4. Modes *vim_modes*
========
4.1 Introduction
Vim has four BASIC modes:
Normal mode In Normal mode you can enter all the editor
commands. If you start the editor you are in this
mode (unless you have set the 'insertmode' option,
see below). This is also known as command mode.
Visual mode This is like Normal mode, but the movement commands
extend a highlighted area. When a non-movement
command is used, it is executed for the highlighted
area. See |Visual_mode|.
Insert mode In Insert mode the text you type is inserted into the
buffer. If the 'showmode' option is on (which is
default), the string "-- INSERT --" is shown at the
bottom of the window. |mode_ins_repl|
Command-line mode In Command-line mode you can enter one line of text
at the bottom of the window. This is for the Ex
commands, ":", the pattern search commands, "?" and
"/", and the filter command, "!". |mode_cmdline|
There are two ADDITIONAL modes:
Replace mode Replace mode is a special case of Insert mode. You
can do the same things as in Insert mode, but for
each character you enter, one character of the existing
text is deleted. If the 'showmode' option is on,
(which is the default), the string "-- REPLACE --" is
shown at the bottom of the window. |replace_mode|
Insert command mode Entered when CTRL-O given in Insert mode. This is
like Normal mode, but after executing one command Vim
returns to Insert mode. The string "-- (insert) --"
is shown at the bottom of the window.
4.2 Switching from mode to mode *mode_switching*
If for any reason you do not know which mode you are in, you can always get
back to Normal mode by typing twice. You will know you are back in
Normal mode when you see the screen flash or hear the bell after you type
.
- go from Normal mode to Visual mode by giving one of the commands "vV^V"
- go from Normal mode to Insert mode by giving one of the commands
"iIaAoOcCsS".
- go from Normal mode to Replace mode with the "R" command (not the "r"
command!).
- go from Normal mode to Command-line mode with the one of the commands
":/?!".
*i_esc*
- go from Insert or Replace mode to Normal mode with (twice in some
rare cases).
- go from Visual mode to Normal mode by giving a non-movement command, which
causes the command to be executed, or by hitting or 'v', which does
nothing.
- go from Command-line mode to Normal mode by:
- hitting or , which causes the entered command to be executed
- deleting the complete line (e.g., with CTRL-U) and giving a final
- hitting CTRL-C or , which quits the command line without executing
the command.
In the last case may be the character defined with the 'wildchar'
option, in which case it will start command line completion. You can ignore
that and type again. {Vi: when hitting the command line is
executed. This is unexpected for most people; therefore it was changed in
Vim. But when the is part of a mapping, the command line is executed.
If you want the Vi behaviour also when typing , use ":cmap ^V
^V^M"}
- go from Insert mode to Replace mode by hitting .
- go from Replace mode to Insert mode by hitting .
- go from Visual mode to Command-line mode by hitting ':'. The line numbers
of the highlighted area will be inserted in the command line.
If the 'insertmode' option is on, editing a file will start in Insert mode.
4.3 Insert and Replace mode *mode_ins_repl*
If you are working in a special language mode when inserting text, see the
'langmap' option, |'langmap'|, on how to avoid switching this mode on and off
all the time.
4.3.1 special keys *ins_special_keys*
In Insert and Replace mode, the following characters have a special meaning;
other characters are inserted directly. To insert one of these special
characters into the buffer, precede it with CTRL-V. To insert a
character use "CTRL-V CTRL-@" or "CTRL-V 000". On some systems, you have to
use "CTRL-V 003" to insert a CTRL-C.
char action
-----------------------------------------------------------------------
*i_CTRL-[* *i_*
or CTRL-[ End insert or Replace mode, go back to Normal mode. Finish
abbreviation.
*i_CTRL-C*
CTRL-C Quit insert mode, go back to Normal mode. Do not check for
abbreviations.
*i_CTRL-@*
CTRL-@ Insert previously inserted text and stop insert. {Vi: only
when typed as first char, only up to 128 chars}
*i_CTRL-A*
CTRL-A Insert previously inserted text. {not in Vi}
*i_CTRL-H* *i_*
or CTRL-H Delete the character before the cursor (see below).
See |:fixdel| if your does not do what you want.
{Vi: does not delete autoindents}
*i_*
Delete the character under the cursor. If the cursor is at
the end of the line, and the 'backspace' option is non-zero,
delete the newline; the next line is appended after the
current one. See |:fixdel| if your key does not do what
you want. {not in Vi}
*i_CTRL-W*
CTRL-W Delete the word before the cursor (see below). See the
section "word motions", |word_motions|, for the definition of
a word.
*i_CTRL-U*
CTRL-U Delete all entered characters in the current line (see
below).
*i_CTRL-I* *i_*
or CTRL-I Insert a tab. If the 'expandtab' option is on, the
equivalent number of spaces is inserted (use CTRL-V to
avoid the expansion). See also the 'smarttab' option and
section 4.3.4, |ins_expandtab|.
*i_CTRL-J* *i_*
or CTRL-J Begin new line.
*i_CTRL-M* *i_*
or CTRL-M Begin new line.
*i_CTRL-K*
CTRL-K {char1} {char2}
Enter digraph (see 4.7, |digraphs|). When {char1} is a special
key, the code for that key is inserted. Neither char is
considered for mapping. {not in Vi}
CTRL-N Find next keyword (see 4.3.6, |i_CTRL-N|). {not in Vi}
CTRL-P Find previous keyword (see 4.3.6, |i_CTRL-P|). {not in Vi}
CTRL-R <0-9a-z"%:.-> *i_CTRL-R*
Insert the contents of register. Between typing CTRL-R and
the second character '"' will be displayed to indicate that
you are expected to enter the name of a register.
The text is inserted as if you typed it, but mappings and
abbreviations are not used. If you have options like
'textwidth', 'formatoptions', or 'autoindent' set, this will
influence what will be inserted. This is different from what
happens with the "p" command and pasting with the mouse.
Special registers:
'"' the unnamed register, containing the text of
the last delete or yank
'%' the current file name
':' the last command line
'.' the last inserted text
'-' the last small (less than a line) delete
See |registers| about registers. {not in Vi}
*i_CTRL-T*
CTRL-T Insert one shiftwidth of indent at the start of the current
line. The indent is always rounded to a 'shiftwidth' (this is
vi compatible). {Vi: only when in indent}
*i_CTRL-D*
CTRL-D Delete one shiftwidth of indent at the start of the current
line. The indent is always rounded to a 'shiftwidth' (this is
vi compatible). {Vi: CTRL-D works only when used after
autoindent}
*i_0_CTRL-D*
0 CTRL-D Delete all indent in the current line. {Vi: CTRL-D works
only when used after autoindent}
*i_^_CTRL-D*
^ CTRL-D Delete all indent in the current line. The indent is
restored in the next line. This is useful when inserting a
label. {Vi: CTRL-D works only when used after autoindent}
*i_CTRL-V*
CTRL-V Insert next non-digit literally. For special keys, the
terminal code is inserted. Up to three digits form the
decimal value of a single byte (see below |i_CTRL-V_digit|.
The non-digit and the three digits are not considered for
mapping. {Vi: no decimal byte entry}
*i_CTRL-Q*
CTRL-Q Same as CTRL-V.
CTRL-X Enter CTRL-X mode. This is a sub-mode where commands can
be given to complete words or scroll the window. See below,
|i_CTRL-X|, and in 4.3.6, |ins_completion|. {not in Vi}
*i_CTRL-E*
CTRL-E Insert the character which is below the cursor. {not in Vi}
*i_CTRL-Y*
CTRL-Y Insert the character which is above the cursor. {not in Vi}
*i_CTRL-B*
CTRL-B Toggle the 'revins' option (B for Backwards). Only if
compiled with RIGHTLEFT (which is not the default). See
|ins_reverse|. {not in Vi}
*i_CTRL-_*
CTRL-_ This key is only available if Vim was compiled with RIGHTLEFT.
Its purpose is to switch between languages while in insert
mode, as follows:
- When in a rightleft window, revins and nohkmap are toggled,
since English will likely be inserted in this case.
- When in a norightleft window, revins and hkmap are toggled,
since Hebrew will likely be inserted in this case.
CTRL-_ moves the cursor to the end of the typed text, unlike
CTRL-B which leaves the cursor in the same place.
Please refer to |vim_rlh.txt| for more information about
right-to-left mode. {not in Vi}
*i_*
Toggle between insert and replace mode. {not in Vi}
-----------------------------------------------------------------------
The effect of the , CTRL-W, and CTRL-U depend on the 'backspace' option
(unless 'revins' is set):
backspace action
option
0 delete stops in column 1 and start position of insert
1 delete stops at start position of insert
2 delete always; CTRL-W and CTRL-U stop once at start position of
insert
If the 'backspace' option is non-zero and the cursor is in column 1 when one
of the three keys is used, the current line is joined with the previous
line. This effectively deletes the newline in front of the cursor. {Vi: does
not cross lines, does not delete past start position of insert}
*i_CTRL-V_digit*
With CTRL-V followed by one, two, or three digits, you can enter the decimal
value of any byte, except 10. Normally CTRL-V is followed by three digits.
The formed byte is inserted as soon as you type the third digit. If you type
only one or two digits and then a non-digit, the decimal value of those one
or two digits form the byte. After that the non-digit is dealt with in the
normal way. If you enter a value of 10, it will end up in the file as a 0.
The 10 is a , which is used internally to represent the character.
When writing the buffer to a file, the character is translated into
. The character is written at the end of each line. Thus if you
want to insert a character in a file you will have to make a line
break. The maximum value that can be entered is 255.
*i_CTRL-X* *insert_expand*
CTRL-X enters a sub-mode where several commands can be used. Most of these
commands do keyword completion; see 4.3.6, |ins_completion|. These are only
available when Vim was compiled with INSERT_EXPAND defined. If ":version"
shows "+insert_expand" then it was; if it shows "-insert_expand" then these
commands are not available. Two commands can be used to scroll the window up
or down, without exiting insert mode:
*i_CTRL-X_CTRL-E*
CTRL-X CTRL-E scroll window one line up.
*i_CTRL-X_CTRL-Y*
CTRL-X CTRL-Y scroll window one line down.
After CTRL-X is pressed, each CTRL-E (CTRL-Y) scrolls the window up (down) by
one line unless that would cause the cursor to move from its current position
in the file. As soon as another key is pressed, CTRL-X mode is exited and
that key is interpreted as in Insert mode.
4.3.2 special special keys *ins_special_special*
The following keys are special. They stop the current insert, do something,
and then restart insertion. This means you can do something without getting
out of Insert mode. This is very handy if you prefer to use the Insert mode
all the time, just like editors that don't have a separate Normal mode. You
may also want to set the 'backspace' option to 2 and set the 'insertmode'
option. You can use CTRL-O if you want to map a function key to a command.
The changes (inserted or deleted characters) before and after these keys can
be undone separately. Only the last change can be redone and always behaves
like an "i" command.
char action
-----------------------------------------------------------------------
cursor one line up *i_*
cursor one line down *i_*
cursor one character left *i_*
cursor one character right *i_*
cursor one word back (like "b" command) *i_*
cursor one word forward (like "w" command) *i_*
cursor to first char in the line *i_*
cursor to after last char in the line *i_*
cursor to first char in the file *i_*
cursor to after last char in the file *i_*
cursor to position of mouse click *i_*
move window one page up *i_*
move window one page up *i_*
move window one page down *i_*
move window one page down *i_*
CTRL-O execute one command and return to Insert mode*i_CTRL-O*
-----------------------------------------------------------------------
The CTRL-O command sometimes has one side effect: If the cursor was beyond the
end of the line, it will be put on the last character in the line.
The shifted cursor keys are not available on all terminals.
When the 'whichwrap' option is set appropriately, the and
keys on the first/last character in the line make the cursor wrap to the
previous/next line.
4.3.3 'textwidth' and 'wrapmargin' options *ins_textwidth*
The 'textwidth' option can be used to automatically break a line before it
gets too long. Set the 'textwidth' option to the desired maximum line
length. If you then type more characters (not spaces or tabs), the
last word will be put on a new line (unless it is the only word on the
line). If you set 'textwidth' to 0, this feature is disabled.
The 'wrapmargin' option does almost the same. The difference is that
'textwidth' has a fixed width while 'wrapmargin' depends on the width of the
screen. When using 'wrapmargin' this is equal to using 'textwidth' with a
value equal to (columns - 'wrapmargin'), where columns is the width of the
screen.
When 'textwidth' and 'wrapmargin' are both set, 'textwidth' is used.
The line is only broken automatically when using insert mode, or when
appending to a line. When in replace mode and the line length is not
changed, the line will not be broken.
Long lines are broken if you enter a non-white character after the margin.
The situations where a line will be broken can be restricted by adding
characters to the 'formatoptions' option:
"l" Only break a line if it was not longer than 'textwidth' when the insert
started.
"v" Only break at a white character that has been entered during the
current insert command. This is mostly Vi-compatible.
"lv" Only break if the line was not longer than 'textwidth' when the insert
started and only at a white character that has been entered during the
current insert command. Only differs from "l" when entering non-white
characters while crossing the 'textwidth' boundary.
If you want to format a block of text, you can use the "gq" operator. Type
"gq" and a movement command to move the cursor to the end of the block. In
many cases, the command "gq}" will do what you want (format until the end of
paragraph). Alternatively, you can use "gqp", which will format the whole
paragraph, no matter where the cursor currently is. Or you can use Visual
mode: hit "v", move to the end of the block, and hit "gq". See also |gq|.
4.3.4 'expandtab' and 'smarttab' options *ins_expandtab*
If the 'expandtab' option is on, spaces will be used to fill the amount of
whitespace of the tab. If you want to enter a real , type CTRL-V first.
The 'expandtab' option is off by default. Note that in Replace mode, a single
character is replaced with several spaces. The result of this is that the
number of characters in the line increases. Backspacing will delete one
space at a time. The original character will be put back for only one space
that you backspace over (the last one). {Vi does not have the 'expandtab'
option}
*ins_smarttab*
When the 'smarttab' option is on, a inserts 'shiftwidth' positions at
the beginning of a line and 'tabstop' positions in other places. This means
that often spaces instead of a character are inserted. When 'smarttab
is off, a always inserts 'tabstop' positions, and 'shiftwidth' is only
used for ">>" and the like. {not in Vi}
4.3.5 Replace mode *replace_mode*
In Replace mode, one character in the line is deleted for every character you
type. If there is no character to delete (at the end of the line), the
typed character is appended (as in Insert mode). Thus the number of
characters in a line stays the same until you get to the end of the line.
If a is typed, a line break is inserted and no character is deleted.
Be careful with characters. If you type a normal printing character in
its place, the number of characters is still the same, but the number of
columns will become smaller.
If you delete characters in Replace mode (with , CTRL-W, or CTRL-U), what
happens is that you delete the changes. The characters that were replaced
are restored. If you had typed past the existing text, the characters you
added are deleted. This is effectively a character-at-a-time undo.
If the 'expandtab' option is on, a will replace one character with
several spaces. The result of this is that the number of characters in the
line increases. Backspacing will delete one space at a time. The original
character will be put back for only one space that you backspace over (the
last one). {Vi does not have the 'expandtab' option}
4.3.6 Insert mode completion *ins_completion*
In Insert and Replace modes, there are several commands to complete part of a
keyword or line that has been typed. This is useful if you are using
complicated keywords (e.g., function names with capitals and underscores).
Completion can be done for:
1. Whole lines |i_CTRL-X_CTRL-L|
2. keywords in the current file |i_CTRL-N|
3. keywords in 'dictionary' |i_CTRL-X_CTRL-K|
4. keywords in the current and included files |i_CTRL-X_CTRL-I|
5. tags |i_CTRL-X_CTRL-]|
6. file names |i_CTRL-X_CTRL-F|
7. definitions or macros |i_CTRL-X_CTRL-D|
All these (except 2) are done in CTRL-X mode. This is a sub-mode of Insert
and Replace modes. You enter CTRL-X mode by typing CTRL-X and one of the
CTRL-X commands. You exit CTRL-X mode by typing a key that is not a valid
CTRL-X mode command. Valid keys are the CTRL-X command itself, CTRL-N (next),
and CTRL-P (previous).
Also see the 'infercase' option if you want to adjust the case of the match.
Note: The keys that are valid in CTRL-X mode are not mapped. This allows for
":map ^F ^X^F" to work (where ^F is CTRL-F and ^X is CTRL-X). The key that
ends CTRL-X mode (any key that is not a valid CTRL-X mode command) is mapped.
The following mappings are suggested to make typing the completion commands
a bit easier (although they will hide other commands):
:inoremap ^] ^X^]
:inoremap ^F ^X^F
:inoremap ^D ^X^D
:inoremap ^L ^X^L
Completing whole lines *compl_whole_line*
*i_CTRL-X_CTRL-L*
CTRL-X CTRL-L Search backwards for a line that starts with the
same characters as in the current line before the
cursor. Indent is ignored. The found line is
inserted in front of the cursor.
CTRL-L or
CTRL-P Search backwards for next matching line. This line
replaces the previous matching line.
CTRL-N Search forward for next matching line. This line
replaces the previous matching line.
Completing keywords in current file *compl_current*
*i_CTRL-P*
*i_CTRL-N*
The keys CTRL-N and CTRL-P can be used to complete the keyword that is in
front of the cursor. This is useful if you are writing a program that has
complicated variable names, and you want to copy a name from the text before
or after the cursor.
If there is a keyword in front of the cursor (a name made out of alphabetic
characters and characters in 'iskeyword'), it is used as the search pattern,
with "\<" prepended (meaning: start of a word). Otherwise "\<\k\k" is used
as search pattern (start of any keyword of at least two characters).
With CTRL-N (next), the search goes forward; with CTRL-P (previous), the
search goes backward. The first time the search starts where the cursor is.
Subsequently, the search starts at the last found position. If you type any
other character than CTRL-P or CTRL-N, the current text is accepted and the
search pattern is forgotten.
If the search found a match, it is inserted at the cursor position. Any
previous match is replaced. If no match was found, Vim will beep.
In Replace mode, the number of characters that are replaced depends on the
length of the matched string. This works like typing the characters of the
matched string in Replace mode.
If there is not a valid keyword character before the cursor, any keyword of
at least two characters is matched.
e.g., to get:
printf("(%g, %g, %g)", vector[0], vector[1], vector[2]);
just type:
printf("(%g, %g, %g)", vector[0], ^P[1], ^P[2]);
Multiple repeats of the same completion are skipped; thus a different match
will be inserted at each CTRL-N and CTRL-P (unless there is only one
matching keyword).
If there is only one completion found, then a second CTRL-P or CTRL-N will
give the message 'No other matches'.
If the only match in the file is an exact match, where no extra characters
would be typed, then the message 'Exact match only' is given (this is also
useful for checking that you typed the word correctly).
The mode (-- INSERT --) is shown, unless there is another more important
message (e.g., "Pattern not found"). This other message will stay until
another key is hit, and then the mode is shown again.
Single character matches are never included, as they usually just get in
the way of what you were really after.
e.g., to get:
printf("name = %s\n", name);
just type:
printf("name = %s\n", n^P);
or even:
printf("name = %s\n", ^P);
The 'n' in '\n' is skipped.
Completing keywords in 'dictionary' *compl_dictionary*
*i_CTRL-X_CTRL-K*
CTRL-X CTRL-K Search the files given with the 'dictionary' option
for words that start with the keyword in front of the
cursor. This is like CTRL-N, but only the dictionary
files are searched, not the current file. The found
keyword is inserted in front of the cursor. This
could potentially be pretty slow, since all matches
are found before the first match is used. By default,
the 'dictionary' option is empty.
CTRL-K or
CTRL-N Search forward for next matching keyword. This
keyword replaces the previous matching keyword.
CTRL-P Search backwards for next matching keyword. This
keyword replaces the previous matching keyword.
Completing keywords in the current and included files *compl_keyword*
The 'include' option is used to specify a line that contains an include file
name. The 'path' option is used to search for include files.
*i_CTRL-X_CTRL-I*
CTRL-X CTRL-I Search for the first keyword in the current and
included files that starts with the same characters
as those before the cursor. The matched keyword is
inserted in front of the cursor.
CTRL-N Search forwards for next matching keyword. This
keyword replaces the previous matching keyword.
Note: CTRL-I is the same as , which is likely to
be typed after a succesful completion, therefore
CTRL-I is not used for searching for the next match.
CTRL-P Search backward for previous matching keyword. This
keyword replaces the previous matching keyword.
Completing tags *compl_tag*
*i_CTRL-X_CTRL-]*
CTRL-X CTRL-] Search for the first tag that starts with the same
characters as before the cursor. The matching tag is
inserted in front of the cursor. Alphabetic
characters and characters in 'iskeyword' are used
to decide which characters are included in the tag
name (same as for a keyword).
CTRL-] or
CTRL-N Search forwards for next matching tag. This tag
replaces the previous matching tag.
CTRL-P Search backward for previous matching tag. This tag
replaces the previous matching tag.
Completing file names *compl_filename*
*i_CTRL-X_CTRL-F*
CTRL-X CTRL-F Search for the first file name that starts with the
same characters as before the cursor. The matching
file name is inserted in front of the cursor.
Alphabetic characters and characters in 'isfname'
are used to decide which characters are included in
the file name. Note: the 'path' option is not used
here (yet).
CTRL-F or
CTRL-N Search forwards for next matching file name. This
file name replaces the previous matching file name.
CTRL-P Search backward for previous matching file name.
This file name replaces the previous matching file
name.
Completing definitions or macros *compl_define*
The 'define' option is used to specify a line that contains a definition.
The 'include' option is used to specify a line that contains an include file
name. The 'path' option is used to search for include files.
*i_CTRL-X_CTRL-D*
CTRL-X CTRL-D Search in the current and included files for the
first definition (or macro) name that starts with
the same characters as before the cursor. The found
definition name is inserted in front of the cursor.
CTRL-D or
CTRL-N Search forwards for next matching macro name. This
macro name replaces the previous matching macro
name.
CTRL-P Search backward for previous matching macro name.
This macro name replaces the previous matching macro
name.
4.4 Command-line mode *mode_cmdline* *:*
Command-line mode is used to enter Ex commands (":"), search patterns
("/" and "?"), and filter commands ("!").
4.4.1 Command line editing *cmdline_editing*
Normally characters are inserted in front of the cursor position. You can
move around in the command line with the left and right cursor keys. With the
key, you can toggle between inserting and overstriking characters.
{Vi: can only alter the last character in the line}
Note that if your keyboard does not have working cursor keys or any of the
other special keys, you can use ":cnoremap" to define another key for them.
For example, to define tcsh style editing keys: *tcsh-style*
:cnoremap
:cnoremap
:cnoremap
:cnoremap b
:cnoremap f
(<> notation |<>|; type all this literally)
*cmdline_history*
The command lines that you enter are remembered in a history table. You can
recall them with the up and down cursor keys. There are actually two history
tables: one for ':' commands, one for search strings. These are completely
separate. The search strings history can be accessed only when entering a
search string, the ':' history only when entering a command line for the ":"
command. Use the 'history' option to set the number of lines that are
remembered (default: 20). Note that when you enter a command line that is
excactly the same as an older one, the old one is removed (to avoid repeated
commands moving older commands out of the history). Only commands that are
typed are remembered. Ones that come from mappings are not put in the history
(detail: the decision is made from the last key that was typed for the line,
normally ). All searches are put in the search history, including the ones
that come from commands like "*" and "#". {Vi: no history}
There is an automatic completion of names on the command line; see 4.4.2,
|cmdline_completion|.
*c_CTRL-V*
CTRL-V Insert next non-digit literally. Up to three digits form the
decimal value of a single byte. The non-digit and the three
digits are not considered for mapping. This works the same
way as in Insert mode (see above, |i_CTRL-V|).
*c_CTRL-Q*
CTRL-Q Same as CTRL-V.
*c_*
cursor left
*c_*
cursor right
*c_*
cursor one word left
*c_*
cursor one word right
CTRL-B or *c_CTRL-B* *c_*
cursor to beginning of command line
CTRL-E or *c_CTRL-E* *c_*
cursor to end of command line
*c_*
cursor to position of mouse click.
CTRL-H *c_* *c_CTRL-H*
delete the character in front of the cursor (see |:fixdel| if
your key does not do what you want).
*c_*
delete the character under the cursor (at end of line:
character before the cursor) (see |:fixdel| if your
key does not do what you want).
*c_CTRL-W*
CTRL-W delete the word before the cursor
*c_CTRL-U*
CTRL-U remove all characters
Note: if the command line becomes empty with one of the
delete commands, Command-line mode is quit.
*c_*
Toggle between insert and overstrike. {not in Vi}
{char1} {char2} or *c_digraph*
CTRL-K {char1} {char2} *c_CTRL-K*
enter digraph (see 4.7, |digraphs|). When {char1} is a special
key, the code for that key is inserted. {not in Vi}
CTRL-R <0-9a-z"%:-> *c_CTRL-R*
Insert the contents of a numbered or named register. Between
typing CTRL-R and the second character '"' will be displayed
to indicate that you are expected to enter the name of a
register. The text is inserted as if you typed it, but
mappings and abbreviations are not used. Special registers:
'"' the unnamed register, containing the text of
the last delete or yank
'%' the current file name
':' the last command line
'-' the last small (less than a line) delete
Note: The '.' register (last inserted text) is not available
here. See |registers| about registers. {not in Vi}
CTRL-J *c_CTRL-J* *c_* *c_*
or start entered command
*c_*
When typed and 'x' not present in 'cpoptions', quit
Command-line mode without executing. In macros or when 'x'
present in 'cpoptions', start entered command.
*c_CTRL-C*
CTRL-C quit command line without executing
*c_*
recall older command line from history, whose beginning
matches the current command line (see below).
*c_*
recall more recent command line from history, whose beginning
matches the current command line (see below).
*c_* *c_*
or
recall older command line from history
*c_* *c_*
or
recall more recent command line from history
CTRL-D command line completion (see 4.4.2, |cmdline_completion|)
'wildchar' option
command line completion (see 4.4.2, |cmdline_completion|)
CTRL-N command line completion (see 4.4.2, |cmdline_completion|)
CTRL-P command line completion (see 4.4.2, |cmdline_completion|)
CTRL-A command line completion (see 4.4.2, |cmdline_completion|)
CTRL-L command line completion (see 4.4.2, |cmdline_completion|)
*c_CTRL-_*
CTRL-_ switch between Hebrew and English keyboard mode, which is
private to the command line and not related to hkmap.
This is useful when Hebrew text entry is required in the
command line, searches, abbreviations, etc. Applies only if
Vim is compiled with RIGHTLEFT. See |vim_rlh.txt|.
The and keys take the current command line as a search string.
The beginning of the next/previous command lines are compared with this
string. The first line that matches is the new command line. When typing
these two keys repeatedly, the same string is used again. For example, this
can be used to find the previous substitute command: Type ":s" and then .
The same could be done by typing a number of times until the desired
command line is shown. (Note: the shifted arrow keys do not work on all
terminals)
4.4.2 Command line completion *cmdline_completion*
When editing the command line, a few commands can be used to complete the
word before the cursor. This is available for:
- Command names: at the start of the command line. Works always.
- tags: only after the ":tag" command.
- file names: only after a command that accepts a file name or a setting for
an option that can be set to a file name. This is called file name
completion.
- options: only after the ":set" command.
These are the commands that can be used:
*c_CTRL-D*
CTRL-D List names that match the pattern in front of the cursor.
When showing file names, directories are highlighted (see
'highlight' option)
*c_CTRL-I* *c_wildchar* *c_*
'wildchar' option
A match is done on the pattern in front of the cursor. The
match (if there are several, the first match) is inserted
in place of the pattern. (Note: does not work inside a
macro, because or are mostly used as 'wildchar',
and these have a special meaning in some macros.) When typed
again and there were multiple matches, the next
match is inserted. After the last match, the first is used
again (wrap around).
*c_CTRL-N*
CTRL-N After using 'wildchar' which got multiple matches, go to next
match. Otherwise recall more recent command line from history.
*c_CTRL-P* *c_*
CTRL-P After using 'wildchar' which got multiple matches, go to
previous match. Otherwise recall older command line from
history. only works with the GUI, on the Amiga and
with MS-DOS.
*c_CTRL-A*
CTRL-A All names that match the pattern in front of the cursor are
inserted.
*c_CTRL-L*
CTRL-L A match is done on the pattern in front of the cursor. If
there is one match, it is inserted in place of the pattern.
If there are multiple matches the longest common part is
inserted in place of the pattern.
The 'wildchar' option defaults to (CTRL-E when compiled with
COMPATIBLE; in a previous version was used). In the pattern standard
wildcards '*' and '?' are accepted. '*' matches any string, '?' matches
exactly one character.
If you like tcsh's autolist completion, you can use this mapping:
:cnoremap X
(Where X is the command key to use, is CTRL-L and is CTRL-L)
This will find the longest match and then list all matching files.
*suffixes*
For filename completion you can use the 'suffixes' option to set a priority
between files with almost the same name. If there are multiple matches,
those files with an extension that is in the 'suffixes' option are ignored.
The default is ".bak,~,.o,.h,.info,.swp", which means that files ending in
".bak", "~", ".o", ".h", ".info" and ".swp" are sometimes ignored. It is
impossible to ignore suffixes with two dots. Examples:
pattern: files: match:
test* test.c test.h test.o test.c
test* test.h test.o test.h and test.o
test* test.i test.h test.c test.i and test.c
If there is more than one matching file (after ignoring the ones matching
the 'suffixes' option) the first file name is inserted. You can see that
there is only one match when you type 'wildchar' twice and the completed
match stays the same. You can get to the other matches by entering
'wildchar', CTRL-N or CTRL-P. All files are included, also the ones with
extensions matching the 'suffixes' option.
The old value of an option can be obtained by hitting 'wildchar' just after
the '='. For example, typing 'wildchar' after ":set dir=" will insert the
current value of 'dir'. This overrules filename completion for the options
that take a file name.
If you would like using for CTRL-P in an xterm, put this command in
your .cshrc:
xmodmap -e "keysym Tab = Tab Find"
And this in your .vimrc:
cmap [1~ ( is CTRL-P)
4.4.3 Ex command lines *cmdline_lines*
The Ex commands have a few specialties:
*:quote*
'"' at the start of a line causes the whole line to be ignored. '"'
after a command causes the rest of the line to be ignored. This can be used
to add comments. Example:
:set ai "set 'autoindent' option
It is not possible to add a comment to a shell command ":!cmd" or to the
":map" command and friends, because they see the '"' as part of their
argument.
*:bar*
'|' can be used to separate commands, so you can give multiple commands in one
line. The commands ":global", "vglobal", ":!", ":r !", ":w !", ":help" and
":autocmd" see the '|' as their argument, and can therefore not be followed by
another command. If you want '|' to be included in one of the other commands,
precede it with '\'. Note that this is confusing (inherited from Vi). With
":g" the '|' is included in the command, with ":s" it is not.
There is one exception: When the 'b' flag is present in 'cpoptions', with the
":map" and ":abbr" commands and friends CTRL-V needs to be used instead of
'\'. You can also use "" instead. See also |map_bar|.
Examples:
:!ls | wc view the output of two commands
:r !ls | wc insert the same output in the text
:%g/foo/p|> moves all matching lines one shiftwidth
:%s/foo/bar/|> moves one line one shiftwidth
:map q 10^V| map "q" to "10|"
:map q 10\| map \ l map "q" to "10\" and map "\" to "l"
(when 'b' is present in 'cpoptions')
You can also use to separate commands in the same way as with '|'. To
insert a use CTRL-V CTRL-J. "^@" will be shown. Using '|' is the
preferred method. But for external commands a must be used, because a
'|' is included in the external command. To avoid the special meaning of
it must be preceded with a backslash. Example:
:r !date-join
This reads the current date into the file and joins it with the previous line.
Because of vi compatibility the following strange commands are supported:
:| print current line (like ":p")
:3| print line 3 (like ":3p")
:3 goto line 3
A colon is allowed between the range and the command name. It is ignored
(this is vi compatible). For example ":1,$:s/pat/string".
When the character '%' or '#' is used where a filename is expected, they are
expanded to the current and alternate filename (see the chapter "editing
files" |:_%| |:_#|).
Embedded spaces in filenames are allowed on the Amiga if one filename is
expected as argument. Trailing spaces will be ignored, unless escaped with a
backslash or CTRL-V. Note that the ":next" command uses spaces to separate
file names. Escape the spaces to include them in a file name. Example:
:next foo\ bar goes\ to school\
starts editing the three files "foo bar", "goes to" and "school ".
When you want to use the special characters '"' or '|' in a command, or want
to use '%' or '#' in a filename, precede them with a backslash. The backslash
is not required in a range and in the ":substitute" command.
*:_!*
The '!' (bang) character after an Ex command makes the command behave in a
different way. The '!' should be placed immediately after the command, without
any blanks in between. If you insert blanks the '!' will be seen as an
argument for the command, which has a different meaning. For example:
:w! name write the current buffer to file "name", overwriting
any existing file
:w !name send the current buffer as standard input to command
"name"
4.4.4 Ex command line ranges *cmdline_ranges*
Some Ex commands accept a line range in front of them. This is noted as
[range]. It consists of one or more line specifiers, separated with ',' or
';'. When separated with ';' the cursor position will be set to that line
before interpreting the next line specifier. The default line specifier for
most commands is the cursor position, but the commands ":write" and
":global" have the whole file (1,$) as default. If more line specifiers are
given than required for the command, the first one(s) will be ignored.
Line numbers may be specified with: *:range*
{number} an absolute line number
. the current line *:.*
$ the last line in the file *:$*
% equal to 1,$ (the entire file) *:%*
* equal to '<,'> (the Visual area) *:star*
't position of mark t (lower case) *:'*
/{pattern}[/] the next line where {pattern} matches *:/*
?{pattern}[?] the previous line where {pattern} matches *:?*
\/ the next line where the previously used search
pattern matches
\? the previous line where the previously used search
pattern matches
\& the next line where the previously used substitute
pattern matches
Each may be followed (several times) by '+' or '-' and an optional number.
This number is added or subtracted from the preceding line number. If the
number is omitted, 1 is used.
The "/" and "?" may be preceded with another address. The search starts from
there. The "/" and "?" after {pattern} are required to separate the pattern
from anything that follows.
The {number} must be between 0 and the number of lines in the file. A 0 is
interpreted as a 1, except with the commands tag, pop and read.
Examples:
.+3 three lines below the cursor
/that/+1 the line below the next line containing "that"
.,$ from current line until end of file
0;/that the first line containing "that"
Some commands allow for a count after the command. This count is used as the
number of lines to be used, starting with the line given in the last line
specifier (the default is the cursor line). The commands that accept a count
are the ones that use a range but do not have a file name argument (because
a file name can also be a number).
Examples:
:s/x/X/g 5 substitute 'x' by 'X' in the current line and four
following lines
:23d 4 delete lines 23, 24, 25 and 26
A range should have the lower line number first. If this is not the case, Vim
will ask you if it should swap the line numbers. This is not done within the
global command ":g".
*N:*
When giving a count before entering ":", this is translated into:
:.,.+(count - 1)
In words: The 'count' lines at and after the cursor. Example: To delete
three lines:
3:d is translated into: .,.+2d
*v_:*
{Visual}: Starts a command line with the Visual selected lines as a
range. The code ":'<,'>" is used for this range, which makes
it possible to select a similar line from the command line
history for repeating a command on different Visually selected
lines.
4.4.5 Ex special characters *cmdline_special*
In Ex commands, at places where a file name can be used, the following
characters have a special meaning. To avoid the special meaning of '%' and
'#' insert a backslash before it.
% is replaced with the current filename *:_%*
# is replaced with the alternate filename *:_#*
#n (where n is a number) is replaced with the filename of
buffer n. "#0" is the same as "#"
Note: the next four are typed literally, these are not special keys!
*:* *:* *:* *:*
is replaced with the word under the cursor
is replaced with the WORD under the cursor (see |WORD|)
is replaced with the path name under the cursor
when executing autocommands, is replaced with the file name
for a file read or write
*:_%:* *::p* *::h* *::t* *::r* *::e*
After "%", "#", "#n", "" or "" modifiers can be given (in this
order):
:p Make file name a full path. Must be the first modifier.
:h Head of the file name (the last component and any
separators removed). Cannot be used with :e, :r or :t.
Can be repeated to remove several components at the end.
When the file name is an absolute path (starts with "/" for
Unix; "x:\" for MS-DOS, WIN32, OS/2; "drive:" for Amiga),
that part is not removed. When there is no head (path is
relative to current directory) the result is empty.
:t Tail of the file name (last component of the name). Must
precede any :r or :e.
:r Root of the file name (the last extension removed). When
there is only an extension (file name that starts with
'.', e.g., ".vimrc"), it is not removed. Can be repeated to
remove several extensions (last one first).
:e Extension of the file name. Only makes sense when used
alone. When there is no extension the result is empty.
When there is only an extension (file name that starts with
'.'), the result is empty. Can be repeated to include more
extensions. If there are not enough extensions (but at
least one) as much as possible are included.
Examples, when the file name is "src/version.c":
:p /home/mool/vim/src/version.c
:h src
:p:h /home/mool/vim/src
:p:h:h /home/mool/vim
:t version.c
:p:t version.c
:r src/version
:p:r /home/mool/vim/src/version
:t:r version
:e c
Examples, when the file name is "src/version.c.gz":
:p /home/mool/vim/src/version.c.gz
:e gz
:e:e c.gz
:e:e:e c.gz
:e:e:r c
:r src/version.c
:r:e c
:r:r src/version
:r:r:r src/version
*:_%<*
If a "<" is appended to "%", "#", "#n" or "CTRL-V p" the extension of the file
name is removed (everything after and including the last '.' in the file
name). This is included for backwards compatibility with version 3.0, the
":r" form is preferred. Examples:
% current file name
%< current file name without extension
# alternate file name for current window
#< idem, without extension
#31 alternate file number 31
#31< idem, without extension
word under the cursor
WORD under the cursor (see |WORD|)
path name under the cursor
< idem, without extension
Note: Where a file name is expected wildcards expansion is done. On Unix the
shell is used for this. Backticks also work, like in ":n `echo *.c`".
But expansion is only done if there are any wildcards before expanding the
'%', '#', etc.. This avoids expanding wildcards inside a file name.
Examples: (alternate filename is "?readme?")
command expands to
:e # :e ?readme?
:e `ls #` :e {files matching "?readme?"}
:e #.* :e {files matching "?readme?.*"}
4.5 The window contents *window_contents*
In command and Insert/Replace mode the screen window will show the current
contents of the buffer: What You See Is What You Get. There are two
exceptions:
- When the 'cpoptions' option contains '$', and the change is within one line,
the text is not directly deleted, but a '$' is put at the last deleted
character.
- When inserting text in one window, other windows on the same text are not
updated until the insert is finished.
{Vi: The screen is not always updated on slow terminals}
Lines longer than the window width will wrap, unless the 'wrap' option is off
(see below). The 'linebreak' option can be set to wrap at a blank character.
The bottom lines in the window may start with one of these two characters:
'@' The next line is too long to fit in the window.
'~' Below the last line in the buffer.
If the bottom line is completely filled with '@', the line that is at the
top of the window is too long to fit in the window. If the cursor is on this
line you can't see what you are doing, because this part of the line is not
shown. However, the part of the line before the '@'s can be edited normally.
{Vi: gives an "internal error" on lines that do not fit in the window}
The 'showbreak' option contains the string to put in front of wrapped lines.
*wrap_off*
If the 'wrap' option is off, long lines will not wrap. Only the part that
fits on the screen is shown. If the cursor is moved to a part of the line
that is not shown, the screen is scrolled horizontally. The advantage of
this method is that columns are shown as they are and lines that cannot fit
on the screen can be edited. The disadvantage is that you cannot see all the
characters of a line at once. The 'sidescroll' option can be set to the
minimal number of columns to scroll. {Vi: has no 'wrap' option}
All normal ASCII characters are displayed directly on the screen. The
is replaced with the number of spaces that it represents. Other non-printing
characters are replaced with "^{char}", where {char} is the non-printing
character with 64 added. Thus character 7 (bell) will be shown as "^G".
Characters between 127 and 160 are replaced with "~{char}", where {char} is
the character with 64 subtracted. These characters occupy more than one
position on the screen. The cursor can only be positioned on the first one.
If you set the 'number' option, all lines will be preceded with their
number. Tip: If you don't like wrapping lines to mix with the line numbers,
set the 'showbreak' option to eight spaces:
":set showbreak=\ \ \ \ \ \ \ \ "
If you set the 'list' option, characters will not be shown as several
spaces, but as "^I". A '$' will be placed at the end of the line, so you can
find trailing blanks.
In Command-line mode only the command line itself is shown correctly. The
display of the buffer contents is updated as soon as you go back to Command
mode.
Some commands hand over the window to external commands (e.g., ":shell" and
"="). After these commands are finished the window may be clobbered with
output from the external command, so it needs to be redrawn. This is also
the case if something is displayed on the status line that is longer than
the width of the window. If you are expected to have a look at the screen
before it is redrawn, you get this message:
Press RETURN or enter command to continue
After you type a key the screen will be redrawn and Vim continues. If you
type , or nothing else happens. If you type any other key, it
will be interpreted as (the start of) a new command. {Vi: only ":" commands
are interpreted}
The last line of the window is used for status and other messages. The
status messages will only be used if an option is on:
status message option default Unix default
current mode 'showmode' on on
command characters 'showcmd' on off
cursor position 'ruler' off off
The current mode is "-- INSERT --" or "-- REPLACE --", see |'showmode'|. The
command characters are those that you typed but were not used yet. {Vi: does
not show the characters you typed or the cursor position}
If you have a slow terminal you can switch off the status messages to speed
up editing:
:set nosc noru nosm
If there is an error, an error message will be shown for at least one second
(in reverse video). {Vi: error messages may be overwritten with other
messages before you have a chance to read them}
Some commands show how many lines were affected. Above which threshold this
happens can be controlled with the 'report' option (default 2).
On the Amiga Vim will run in a CLI window. The name Vim and the full name of
the current filename will be shown in the title bar. When the window is
resized, Vim will automatically redraw the window. You may make the window as
small as you like, but if it gets too small not a single line will fit in it.
Make it at least 40 characters wide to be able to read most messages on the
last line.
On most Unix systems window resize works ok. {Vi: not ok}
4.6 Abbreviations *abbreviations*
Abbreviations are used in insert mode, Replace mode and Command-line mode.
If you enter a word that is an abbreviation, it is replaced with the word it
stands for. This can be used to save typing for often used long words.
There are three types of abbreviations:
full-id The "full-id" type consists entirely of keyword characters (letters
and characters from 'iskeyword' option). This is the most common
abbreviation.
Examples: "foo", "g3", "-1"
end-id The "end-id" type ends in a keyword character, but all the other
characters are not keyword characters.
Examples: "#i", "..f", "$/7"
non-id The "non-id" type ends in a non-keyword character, the other
characters may be of any type, excluding space and Tab. {this type
is not supported by Vi}
Examples: "def#", "4/7$"
Examples of strings that cannot be abbreviations: "a.b", "#def", "a b", "_$r"
An abbreviation is only recognized when you type a non-keyword character.
This can also be the that ends insert mode or the that ends a
command. The characters before the cursor must match the abbreviation. Each
type has an additional rule:
full-id In front of the match is a non-keyword character, or this is where
the line or insertion starts. Exception: When the abbreviation is
only one character, it is not recognized if there is a non-keyword
character in front of it, other than a space or a