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.html. It can be accessed from within Vim with the <Help> or <F1> 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

[]

Characters in square brackets are optional.

[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, the (partially) entered count is shown at the bottom of the window. You can use <Del> to erase the last digit.

["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 lower case letter designate the same register, but the lower case 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 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}

A command that moves the cursor. They are listed in chapter 6. This is used after an "operator" command 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 and xterm under Unix.

{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" to highlight the text that is to be operated upon. See the chapter on Visual_mode.

<character>

A special character from the table below or a single ASCII character.

'character'

A single ASCII character.

<char1-char2>

A single character from the range <char1> to <char2>. For example: <a-z> is a lower case letter. Multiple ranges may be concatenated. For example: <a-zA-Z0-9> 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.

'option'

An option, or parameter, that can be set to a value is enclosed in single quotes. See chapter 19.

"command"

In examples the commands you can type are enclosed in double quotes.

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

3. Starting Vim

More generally Vim is started with:

If the filelist 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..

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.

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

-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" . {not in Vi}

The options, if present, must precede the filelist. The options may be given in any order.

+[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 ).

+{command}

-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

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

-L

Same as -r. {only in some versions of Vi: "List recoverable edit sessions"}

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

Readonly mode. Same as -v.

-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 a file. See also 5.6: "Editing binary files". {not in Vi}

-l

Lisp mode. Sets the 'lisp' and 'showmatch' options on.

-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

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. 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[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 {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). {not in Vi}

-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

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. {not in Vi}

-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 reset 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 'cpoptions'. {not in Vi} gui_fork

-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. {not in Vi}

-i {viminfo}

The file "viminfo" is used instead of the default ".viminfo" file. If the name "NONE" is used (uppercase) no viminfo file is read or written, even if 'viminfo' is set or when ":rv" or ":wv" is used. See also viminfo_file. {not in Vi}

-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". {not in Vi}

-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!". See also the section "complex repeats".

-w{number}

Does nothing. This was included for Vi-compatibility. In Vi it sets the 'window' option, which is not implemented in Vim.

Execute Vim on all files you want to change:

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)

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)

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 how Vim was started, 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.

1. The environment variable SHELL, if it exists, is used to set the 'shell' option. With MS-DOS the COMPSPEC variable is used if SHELL does not exist.

2. The environment variable TERM, if it exists, is used to set the 'term' option.

3. If the -u command-line option was given, the associated file is read for initializations. Otherwise the following is done:
   • For Unix the system vimrc file is read for initializations. The path of this file can be found with ":version".
   • Four places are searched for initializations. The first that exists is used, the others are ignored.
   • The environment variable VIMINIT
   • The file "~/.vimrc" (for Unix), "s:.vimrc" (Amiga) or "$VIM\_vimrc" (MS-DOS).
   • The environment variable EXINIT
   • The file "~/.exrc" (for Unix), "s:.exrc" (Amiga) or "$VIM\_exrc" (MS-DOS).

4. If the 'exrc' option is set (default is 'noexrc'), and the -u command-line option u is not used, the current directory is searched for two files. The first that exists is used, the other is ignored.
   1. The file ".vimrc" (MS-DOS: "_vimrc")
   2. The file ".exrc" (MS-DOS: "_exrc")

5. The 'shellpipe' and 'shellredir' options are set according to the value of the 'shell' option, unless they have been set before.

6. If the 'viminfo' option is set to non-empty by the previous initializations, the viminfo file is read. See viminfo_file.

If the VIMINIT environment variable or ".vimrc" exist the EXINIT and ".exrc" are skipped. This can be used to initialize Vim without interfering with another version of Vi.

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.

On MS-DOS systems Vim assumes that all the "_vimrc" and "_exrc" files have <CR><NL> pairs as line separators. This will give problems if you have a file with only <NL>s and have a line like ":map xx yy^M". The trailing ^M will be ignored.

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. Otherwise it would be possible to create a .exrc that contains nasty commands, which another user may automatically execute when he starts Vim it that directory. 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.

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" or ".exrc" file. Warning: If you unpack an archive that contains a .exrc file, it will be owned by you. You won't have the security protection. Check the .exrc 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!

If Vim takes a long time to startup 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 command line argument "-i NONE"). Try reducing the number of lines stored in a register with ":set viminfo='20\"50". See viminfo_file.

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][!]

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

• 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 '&').

When Vim is started and the 'viminfo' option is non-empty, the contents of the viminfo file is 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 to be able to jump 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:").

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. The "-i" command line option can be used to set another file name . 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" command line option is "NONE" (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

: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[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 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}