diff options
Diffstat (limited to 'usr.bin/vim/doc/vim_ref.txt')
| -rw-r--r-- | usr.bin/vim/doc/vim_ref.txt | 9855 |
1 files changed, 9855 insertions, 0 deletions
diff --git a/usr.bin/vim/doc/vim_ref.txt b/usr.bin/vim/doc/vim_ref.txt new file mode 100644 index 00000000000..e9358ebe02d --- /dev/null +++ b/usr.bin/vim/doc/vim_ref.txt @@ -0,0 +1,9855 @@ +*vim_ref.txt* For Vim version 4.2. Last modification: 1996 June 17 + + + 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_<Esc>| + Command line commands ":" |:quit| + Command line editing "c_" |c_<Del>| + 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 <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 *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 <Del> to erase the last + digit (|N<Del>|). + +["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|. + +<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 lowercase 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, |options|. + +"command" In examples, the commands you can type are enclosed in double + quotes. + + *key_notation* +notation meaning equivalent decimal value(s) +----------------------------------------------------------------------- +<Nul> zero CTRL-@ 0 (stored as 10) +<BS> backspace CTRL-H 8 *backspace* +<Tab> tab CTRL-I 9 *tab* + *linefeed* +<NL> linefeed CTRL-J 10 (used for <Nul>) + *carriage return* +<CR> carriage return CTRL-M 13 +<Esc> escape CTRL-[ 27 *escape* +<Space> space 32 *space* +<Del> delete 127 + +<Up> cursor-up *cursor-up* *cursor_up* +<Down> cursor-down *cursor-down* *cursor_down* +<Left> cursor-left *cursor-left* *cursor_left* +<Right> cursor-right *cursor-right* *cursor_right* +<S-Up> shift-cursor-up +<S-Down> shift-cursor-down +<S-Left> shift-cursor-left +<S-Right> shift-cursor-right +<F1> - <F12> function keys 1 to 12 *function_key* *function-key* +<S-F1> - <S-F12> shift-function keys 1 to 12 +<Help> help key +<Undo> undo key +<Insert> insert key +<Home> home *home* +<End> end *end* +<PageUp> page-up *page_up* *page-up* +<PageDown> page-down *page_down* *page-down* +<S-...> shift-key *shift* +<C-...> control-key *control* *ctrl* +<M-...> alt-key or meta-key *meta* *alt* +<t_xx> 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 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|. + + *<>* +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. "<key>" means the special key typed. This is the notation explained in + the table above. A few examples: + <Esc> Escape key + <C-G> CTRL-G + <Up> cursor up key + <C-LeftMouse> Control- left mouse click + <S-F11> Shifted function key 11 + <M-a> Meta- a ('a' with bit 8 set) + <M-A> Meta- A ('A' with bit 8 set) + <t_kd> "kd" termcap entry (cursor down key) + +If you want to use this 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 +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 "<NL>". + *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 <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. + +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. +Otherwise it would be possible that you accidentally use a vimrc 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! + + *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|). + + *: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 <Esc> twice. You will know you are back in +Normal mode when you see the screen flash or hear the bell after you type +<Esc>. + +- 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 <Esc> (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 <Esc> or 'v', which does + nothing. +- go from Command-line mode to Normal mode by: + - hitting <CR> or <NL>, which causes the entered command to be executed + - deleting the complete line (e.g., with CTRL-U) and giving a final <BS> + - hitting CTRL-C or <Esc>, which quits the command line without executing + the command. + In the last case <Esc> may be the character defined with the 'wildchar' + option, in which case it will start command line completion. You can ignore + that and type <Esc> again. {Vi: when hitting <Esc> the command line is + executed. This is unexpected for most people; therefore it was changed in + Vim. But when the <Esc> is part of a mapping, the command line is executed. + If you want the Vi behaviour also when typing <Esc>, use ":cmap ^V<Esc> + ^V^M"} + +- go from Insert mode to Replace mode by hitting <Insert>. +- go from Replace mode to Insert mode by hitting <Insert>. +- 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 <Nul> +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_<Esc>* +<Esc> 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_<BS>* +<BS> or CTRL-H Delete the character before the cursor (see below). + See |:fixdel| if your <BS> does not do what you want. + {Vi: does not delete autoindents} + *i_<Del>* +<Del> 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 <Del> 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_<Tab>* +<Tab> or CTRL-I Insert a tab. If the 'expandtab' option is on, the + equivalent number of spaces is inserted (use CTRL-V <Tab> to + avoid the expansion). See also the 'smarttab' option and + section 4.3.4, |ins_expandtab|. + *i_CTRL-J* *i_<NL>* +<NL> or CTRL-J Begin new line. + *i_CTRL-M* *i_<CR>* +<CR> 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_<Insert>* +<Insert> Toggle between insert and replace mode. {not in Vi} +----------------------------------------------------------------------- + +The effect of the <BS>, 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 <NL>, which is used internally to represent the <Nul> character. +When writing the buffer to a file, the <NL> character is translated into +<Nul>. The <NL> character is written at the end of each line. Thus if you +want to insert a <NL> 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 +----------------------------------------------------------------------- +<Up> cursor one line up *i_<Up>* +<Down> cursor one line down *i_<Down>* +<Left> cursor one character left *i_<Left>* +<Right> cursor one character right *i_<Right>* +<S-Left> cursor one word back (like "b" command) *i_<S-Left>* +<S-Right> cursor one word forward (like "w" command) *i_<S-Right>* +<Home> cursor to first char in the line *i_<Home>* +<End> cursor to after last char in the line *i_<End>* +<C-Home> cursor to first char in the file *i_<C-Home>* +<C-End> cursor to after last char in the file *i_<C-End>* +<LeftMouse> cursor to position of mouse click *i_<LeftMouse>* +<S-Up> move window one page up *i_<S-Up>* +<PageUp> move window one page up *i_<PageUp>* +<S-Down> move window one page down *i_<S-Down>* +<PageDown> move window one page down *i_<PageDown>* +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 <Left> and <Right> +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 <Tab>, 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 <Tab> inserts 'shiftwidth' positions at +the beginning of a line and 'tabstop' positions in other places. This means +that often spaces instead of a <Tab> character are inserted. When 'smarttab +is off, a <Tab> 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 <NL> is typed, a line break is inserted and no character is deleted. + +Be careful with <Tab> 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 <BS>, 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 <Tab> 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 +of 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 <Tab>, 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 +<Insert> 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 ^A <Home> + :cnoremap ^F <Right> + :cnoremap ^B <Left> + :cnoremap ^[b <S-Left> + :cnoremap ^[f <S-Right> +(All ^x characters entered with CTRL-V CTRL-x, <xx> typed 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 <CR>). 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_<Left>* +<Left> cursor left + *c_<Right>* +<Right> cursor right + *c_<S-Left>* +<S-Left> cursor one word left + *c_<S-Right>* +<S-Right> cursor one word right +CTRL-B or <Home> *c_CTRL-B* *c_<Home>* + cursor to beginning of command line +CTRL-E or <End> *c_CTRL-E* *c_<End>* + cursor to end of command line + + *c_<LeftMouse>* +<LeftMouse> cursor to position of mouse click. + +CTRL-H *c_<BS>* *c_CTRL-H* +<BS> delete the character in front of the cursor (see |:fixdel| if + your <BS> key does not do what you want). + *c_<Del>* +<Del> delete the character under the cursor (at end of line: + character before the cursor) (see |:fixdel| if your <Del> + 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_<Insert>* +<Insert> Toggle between insert and overstrike. {not in Vi} + +{char1} <BS> {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_<NL>* *c_<CR>* +<CR> or <NL> start entered command + *c_<Esc>* +<Esc> 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_<Up>* +<Up> recall older command line from history, whose beginning + matches the current command line (see below). + *c_<Down>* +<Down> recall more recent command line from history, whose beginning + matches the current command line (see below). + + *c_<S-Up>* *c_<PageUp>* +<S-Up> or <PageUp> + recall older command line from history + *c_<S-Down>* *c_<PageDown>* +<S-Down> or <PageDown> + 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 <Up> and <Down> 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 <Up>. +The same could be done by typing <S-Up> 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_<Tab>* +'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 <Tab> or <Esc> 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. +<S-Tab> *c_CTRL-P* *c_<S-Tab>* +CTRL-P After using 'wildchar' which got multiple matches, go to + previous match. Otherwise recall older command line from + history. <S-Tab> 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 <Tab> (CTRL-E when compiled with +COMPATIBLE; in a previous version <Esc> 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 <C-L><C-D> +(Where X is the command key to use, <C-L> is CTRL-L and <C-D> 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 <S-Tab> for CTRL-P in an xterm, put this command in +your .cshrc: + xmodmap -e "keysym Tab = Tab Find" +And this in your .vimrc: + cmap <Esc>[1~ <C-P> (<C-P> 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 +execption: When the 'b' flag is present in 'cpoptions', with the ":map" and +":abbr" commands and friends CTRL-V needs to be used instead of '\'. 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 <NL> to separate commands in the same way as with '|'. To +insert a <NL> use CTRL-V CTRL-J. "^@" will be shown. Using '|' is the +preferred method. But for external commands a <NL> must be used, because a +'|' is included in the external command. To avoid the special meaning of <NL> +it must be preceded with a backslash. Example: + :r !date<NL>-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<CR> is translated into: .,.+2d<CR> + + *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! + *:<cword>* *:<cWORD>* *:<cfile>* *:<afile>* + <cword> is replaced with the word under the cursor + <cWORD> is replaced with the WORD under the cursor (see |WORD|) + <cfile> is replaced with the path name under the cursor + <afile> when executing autocommands, is replaced with the file name + for a file read or write + + *:_%:* *::p* *::h* *::t* *::r* *::e* +After "%", "#", "#n", "<cfile>" or "<afile>" 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 there is no head 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 + <cword> word under the cursor + <cWORD> WORD under the cursor (see |WORD|) + <cfile> path name under the cursor + <cfile>< 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 <Tab> +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, <Tab> 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 <CR>, <SP> or <NL> 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 <Esc> that ends insert mode or the <CR> 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 <Tab>. + +end-id In front of the match is a keyword character, or a space or a <Tab>, + or this is where the line or insertion starts. + +non-id In front of the match is a space, <Tab> or the start of the line or + the insertion. + +Examples: (<CURSOR> is where you type a non-keyword character) + ":ab foo four old otters" (Note that spaces in the <rhs> are allowed + and included in the replacement string.) + " foo<CURSOR>" is expanded to " four old otters" + " foobar<CURSOR>" is not expanded + "barfoo<CURSOR>" is not expanded + + ":ab #i #include" + "#i<CURSOR>" is expanded to "#include" + ">#i<CURSOR>" is not expanded + + ":ab ;; <endofline>" + "test;;" is not expanded + "test ;;" is expanded to "test <endofline>" + +To avoid the abbreviation in insert mode: Type part of the abbreviation, exit +insert mode with <Esc>, re-enter insert mode with "a" and type the rest. Or +type CTRL-V before the character after the abbreviation. +To avoid the abbreviation in Command-line mode: Type CTRL-V twice somewhere in +the abbreviation to avoid it to be replaced. A CTRL-V in front of a normal +character is mostly ignored otherwise. + +There are no default abbreviations. + +Abbreviations are never recursive. You can use ":ab f f-o-o" without any +problem. But abbreviations can be mapped. {some versions of Vi support +recursive abbreviations, for no apparent reason} + +Abbreviations are disabled if the 'paste' option is on. + + *:ab* *:abbreviate* +:ab[breviate] list all abbreviations. The character in the first + column indicates the mode where the abbreviation is + used: 'i' for insert mode, 'c' for Command-line + mode, '!' for both. + +:ab[breviate] <lhs> list the abbreviations that start with <lhs> + +:ab[breviate] <lhs> <rhs> + add abbreviation for <lhs> to <rhs>. If <lhs> already + existed it is replaced with the new <rhs>. <rhs> may + contain spaces. + + *:una* *:unabbreviate* +:una[bbreviate] <lhs> remove abbreviation for <lhs> from the list + + *:norea* *:noreabbrev* +:norea[bbrev] [lhs] [rhs] + same as ":ab", but no remapping for this <rhs> {not + in Vi} + + *:ca* *:cabbrev* +:ca[bbrev] [lhs] [rhs] same as ":ab", but for Command-line mode only. {not + in Vi} + + *:cuna* *:cunabbrev* +:cuna[bbrev] <lhs> same as ":una", but for Command-line mode only. {not + in Vi} + + *:cnorea* *:cnoreabbrev* +:cnorea[bbrev] [lhs] [rhs] + same as ":ab", but for Command-line mode only and no + remapping for this <rhs> {not in Vi} + + *:ia* *:iabbrev* +:ia[bbrev] [lhs] [rhs] same as ":ab", but for Insert mode only. {not in Vi} + + *:iuna* *:iunabbrev* +:iuna[bbrev] <lhs> same as ":una", but for insert mode only. {not in + Vi} + + *:inorea* *:inoreabbrev* +:inorea[bbrev] [lhs] [rhs] + same as ":ab", but for Insert mode only and no + remapping for this <rhs> {not in Vi} + + *:abc* *:abclear* +:abc[lear] Remove all abbreviations. {not in Vi} + + *:iabc* *:iabclear* +:iabc[lear] Remove all abbreviations for Insert mode. {not in Vi} + + *:cabc* *:cabclear* +:cabc[lear] Remove all abbreviations for Command-line mode. {not + in Vi} + + + +4.7 Digraphs *digraphs* + + *:dig* *:digraphs* +:dig[raphs] show currently defined digraphs. {not in Vi} + +:dig[raphs] {char1}{char2} {number} ... + Add digraph {char1}{char2} to the list. {number} is + the decimal representation of the character. + +Digraphs are used to enter characters that normally cannot be entered by +an ordinary keyboard. These are mostly accented characters which have the +eighth bit set. The digraphs are easier to remember than the decimal number +that can be entered with CTRL-V (see above). + +Vim must have been compiled with DIGRAPHS defined. If this wasn't done, the +":digraph" command will display an error message. You can also check this +with the ":version" command. If it shows "+digraphs" then it's included, +"-digraphs" means it's not included. + +There are two methods to enter digraphs: *i_digraph* + CTRL-K {char1} {char2} or + {char1} <BS> {char2} +The first is always available. The second only when the 'digraph' option is +set. + +If a digraph with {char1}{char2} does not exist, a digraph {char2}{char1} is +searched for. This will help when you don't remember which character comes +first. + +Note that when you enter CTRL-K {char1}, where {char1} is a special key, the +code for that special key is entered. This is not a digraph. + +Once you have entered the digraph the character is treated like a normal +character, taking up only one character in the file and on the screen. +Example: + '|' <BS> '|' will enter the double '|' character (166) + 'a' <BS> '^' will enter an 'a' with a hat (226) + CTRL-K '-' '-' will enter a minus sign (173) + +The default digraphs are listed in the file "vim_digr.txt" |digraph_table|. +There are two sets: One that is used for MS-DOS and one for the international +standard character set that is mostly used on Unix systems and the Amiga. +With the wrong character set they will look illogical. + +For CTRL-K there is one general digraph: CTRL-K <Space> {char} will enter +{char} with the highest bit set. This can be used to enter meta-characters. + +The <Esc> character cannot be part of a digraph. When hitting <Esc> the +entering of the digraph is aborted and Insert mode or command-line mode is +ended, just like hitting an <Esc>. + +If you accidently typed an 'a' that should be an 'e', you will type 'a' <BS> +'e'. But that is a digraph, so you will not get what you want. To correct +this, you will have to type <BS> e again. To avoid this don't set the +'digraph' option and use CTRL-K to enter digraphs. + +You may have problems using Vim with characters which have an ascii value > +128. For example: You insert ue (u-umlaut) and the editor echoes \334 in +Insert mode. After leaving the Insert mode everything is fine. Also fmt +removes all characters with ascii > 128 from the text being formated. +On some Unix systems this means you have to define the environment-variable +LC_CTYPE. If you are using csh then put in your .cshrc following line: + setenv LC_CTYPE=iso_8859_1 + + +4.8 Using the mouse *mouse_using* + +This section is about using the mouse on a terminal or a terminal window. How +to use the mouse in a GUI window is explained in |gui_mouse|. Don't forget to +do ":set mouse=a", otherwise Vim won't recognize the mouse in all modes (See +'mouse'). + +Currently the mouse is supported for Unix in an xterm window and for MS-DOS. +Mouse clicks can be used to position the cursor, select the Visual area and +paste. There are no menus, use the GUI version for that. + +The characters in the 'mouse' option tell in which situations the mouse will +be used by Vim: + n Normal mode + v Visual mode + i Insert mode + c Command-line mode + h all previous modes when in a help file + a all previous modes + r for "Hit return ..." question + +The default for 'mouse' is empty, the mouse is not used. Normally you would do + :set mouse=a +to start using the mouse (this is equivalent to setting 'mouse' to "nvich"). +If you only want to use the mouse in a few modes or also want to use it for +the two questions you will have to concatenate the letters for those modes. +For example: + :set mouse=nv +Will make the mouse work in Normal mode and Visual mode. + :set mouse=h +Will make the mouse work in help files only (so you can use "g<LeftMouse>" to +jump to tags). + +In an xterm, with the currently active mode included in the 'mouse' option, +normal mouse clicks are used by Vim, mouse clicks with the shift or ctrl key +pressed go the the xterm. With the currently active mode not included in +'mouse' all mouse clicks go to the xterm. + +Here is how you copy and paste a piece of text: + +Copy/paste with the mouse and Visual mode ('mouse' option must be set, see +above): +1. Press left mouse button on first letter of text, move mouse pointer to last + letter of the text and release the button. This will start Visual mode and + highlight the selected area. +2. Press "y" to yank the Visual text in the unnamed register. +3. Click the left mouse button at the insert position. +4. Click the middle mouse button. + +Shortcut: If the insert position is on the screen at the same time as the +Visual text, you can do 2, 3 and 4 all in one: Click the middle mouse button +at the insert position. + + *xterm_copy_paste* +Copy/paste in xterm with (current mode NOT included in 'mouse'): +1. Press left mouse button on first letter of text, move mouse pointer to last + letter of the text and release the button. +2. Use normal Vim commands to put the cursor at the insert position. +3. Press "a" to start Insert mode. +4. Click the middle mouse button. +5. Press ESC to end Insert mode. +(The same can be done with anything in 'mouse' if you keep the shift key +pressed while using the mouse) + +Note: if you loose the 8th bit when pasting (special characters are translated +into other characters), you may have to do "stty cs8 -istrip" in your shell +before starting Vim. + +Thus in an xterm the shift and ctrl keys cannot be used with the mouse. To +make it possible to do the mouse commands that require the ctrl modifier, the +"g" key can be typed before using the mouse: + "g<LeftMouse>" is "<C-LeftMouse> (jump to tag under mouse click) + "g<RightMouse>" is "<C-RightMouse> ("CTRL-T") + +A short overview of what the mouse buttons do: + +Normal Mode: +event position Visual change action + cursor window +<LeftMouse> yes end yes +<C-LeftMouse> yes end yes "CTRL-]" (2) +<S-LeftMouse> yes no change yes "*" (2) *<S-LeftMouse>* +<LeftDrag> yes start or extend (1) no *<LeftDrag>* +<LeftRelease> yes start or extend (1) no +<MiddleMouse> yes if not active no put +<MiddleMouse> yes if active no yank and put +<RightMouse> yes start or extend yes +<S-RightMouse> yes no change yes "#" (2) *<S-RightMouse>* +<C-RightMouse> no no change no "CTRL-T" +<RightDrag> yes extend no *<RightDrag>* +<RightRelease> yes extend no *<RightRelease>* + +Insert or Replace Mode: +event position Visual change action + cursor window +<LeftMouse> yes (cannot be active) yes +<C-LeftMouse> yes (cannot be active) yes "CTRL-O^]" (2) +<S-LeftMouse> yes (cannot be active) yes "CTRL-O*" (2) +<LeftDrag> yes start or extend (1) no like CTRL-O (1) +<LeftRelease> yes start or extend (1) no like CTRL-O (1) +<MiddleMouse> no (cannot be active) no put register +<RightMouse> yes start or extend yes like CTRL-O +<S-RightMouse> yes (cannot be active) yes "CTRL-O#" (2) +<C-RightMouse> no (cannot be active) no "CTRL-O CTRL-T" + +(1) only if mouse pointer moved since press +(2) only if click is in same buffer + +Clicking the left mouse button causes the cursor to be positioned. If the +click is in another window that window is made the active window. When +editing the command line the cursor can only be positioned on the +command line. When in Insert mode Vim remains in Insert mode. If 'scrolloff' +is set, and the cursor is positioned within 'scrolloff' lines from the window +border, the text is scrolled. + +A Visual area can be selected by pressing the left mouse button on the first +character, moving the mouse to the last character, then releasing the mouse +button. You will not always see the Visual selection until you release the +button, only in some versions (GUI, MS-DOS, WIN32) will the dragging be shown +immediately. Note that you can make the text scroll by moving the mouse at +least one character in the first/last line in the window when 'scrolloff' is +non-zero. + +In Normal and Visual mode clicking the right mouse button causes the Visual +area to be extended. When clicking in a window which is editing another +buffer, the Visual mode is stopped. + +Double, triple and quadruple clicks are supported when the GUI is active, +for MS-DOS and Win32, and for an xterm (if the gettimeofday() function is +available). Double clicking may be done to make the selection word-wise, +triple clicking makes it line-wise, and quadruple clicking makes it +rectangular block-wise. For MS-DOS and xterm the time for double clicking can +be set with the 'mousetime' option. For the other systems this time is +defined outside of Vim. + +In Insert mode, when a Visual area is selected, Vim goes into Normal mode +temporarily. When Visual mode ends, it returns to Insert mode. This is like +using CTRL-O in Insert mode. + + *drag_status_line* +When working with several windows, the size of the windows can be changed by +dragging the status line with the mouse. Point the mouse at a status line, +press the left button, move the mouse to the new position of the status line, +release the button. Just clicking the mouse in a status line makes that window +the current window, without moving the cursor. If by selecting a window it +will change position or size, the dragging of the status line will look +confusing, but it will work (just try it). + +Mouse clicks can be mapped. The codes for mouse clicks are: + code mouse button normal action + <LeftMouse> left pressed set cursor position + <LeftDrag> left moved while pressed extend Visual area + <LeftRelease> left released set Visual area end + <MiddleMouse> middle pressed paste text at cursor position + <MiddleDrag> middle moved while pressed - + <MiddleRelease> middle released - + <RightMouse> right pressed extend Visual area + <RightDrag> right moved while pressed extend Visual area + <RightRelease> right released set Visual area end + +Examples: + :noremap <MiddleMouse> <LeftMouse><MiddleMouse> +Paste at the position of the middle mouse button click (otherwise the paste +would be done at the cursor position). + + :noremap <LeftRelease> <LeftRelease>y +Immediately yank the Visually highlighted text. + +Note the use of ":noremap" instead of "map" to avoid a recursive mapping. + + *mouse_swap_buttons* +To swap the meaning of the left and right mouse buttons: + :noremap <LeftMouse> <RightMouse> + :noremap <LeftDrag> <RightDrag> + :noremap <LeftRelease> <RightRelease> + :noremap <RightMouse> <LeftMouse> + :noremap <RightDrag> <LeftDrag> + :noremap <RightRelease> <LeftRelease> + :noremap g<LeftMouse> <C-RightMouse> + :noremap g<RightMouse> <C-LeftMouse> + :noremap! <LeftMouse> <RightMouse> + :noremap! <LeftDrag> <RightDrag> + :noremap! <LeftRelease> <RightRelease> + :noremap! <RightMouse> <LeftMouse> + :noremap! <RightDrag> <LeftDrag> + :noremap! <RightRelease> <LeftRelease> + + +4.9 Online help *online_help* + + *help* *<Help>* *:h* *:help* *<F1>* *i_<F1>* *i_<Help>* +<Help> or +:h[elp] Split the window and display the help file in + read-only mode. If there is a help window open + already, use that one. {not in Vi} + +:h[elp] {subject} Like ":help", additionally jump to the tag + {subject}. {subject} can be a regular expression. + :help z. jump to help for any "z" command + :help z\. jump to the help for "z." + If there is no full match for the pattern, or there + are several matches, the "best" match will be used. + A match is considered to be better when: + - if no match with same case is found, a match with + ignoring case will be used + - the match is after a non-alphanumereic character + - it is at near the beginning of the tag + - more alphanumeric characters match + - the length of the matched is smaller + Note that the longer the {subject} you give, the less + matches will be found. You can get an idea how this + all works by using commandline completion (type CTRL-D + after ":help subject". {not in Vi} + +The help file name can be set with the 'helpfile' option. The initial height +of the help window can be set with the 'helpheight' option (default 20). +Jump to specific subjects by using tags. This can be done in two ways: +- Use the "CTRL-]" command while standing on the name of a command or option. + This only works when the tag is a keyword. "<C-Leftmouse>" and + "g<LeftMouse>" work just like "CTRL-]". +- use the ":ta {subject}" command. This works with all characters. + +Use "CTRL-T" to jump back. +Use ":q" to close the help window. + + *help_xterm_window* +If you want to have the help in another xterm window, you could use this +command: + :!xterm -e vim +help & + + *doc_files* +All the help files must be in the same directory. The files are: + vim_help.txt overview and quick reference |vim_help.txt| + vim_idx.txt alphabetical index of all commands |vim_idx.txt| + vim_ref.txt reference manual (this file) |vim_ref.txt| + vim_win.txt reference manual for windows commands |vim_win.txt| + vim_diff.txt main differences between Vim and Vi |vim_diff.txt| + vim_digr.txt list of available digraphs |vim_digr.txt| + vim_tips.txt tips on using Vim |vim_tips.txt| + vim_gui.txt about the Graphical User Interface |vim_gui.txt| + vim_40.txt about version 4.0 |vim_40.txt| + vim_rlh.txt about the 'rightleft' option |vim_rlh.txt| + + vim_unix.txt Unix specific remarks |vim_unix.txt| + vim_ami.txt Amiga specific remarks |vim_ami.txt| + vim_dos.txt MS-DOS specific remarks |vim_dos.txt| + vim_w32.txt Windows-NT/95 specific remarks |vim_w32.txt| + vim_os2.txt OS/2 specific remarks |vim_os2.txt| + vim_arch.txt Archimedes specific remarks |vim_arch.txt| + vim_mac.txt Macintosh specific remarks |vim_mac.txt| + vim_mint.txt Atari MiNT specific remarks |vim_mint.txt| + + vim_tags tags file for documentation + + +5. Editing files *edit_files* +================ + +5.1 Introduction *edit_intro* + +Editing a file with Vim means: + +1. reading the file into the internal buffer +2. changing the buffer with editor commands +3. writing the buffer into a file + +As long as you don't write the buffer, the original file remains unchanged. +If you start editing a file (read a file into the buffer), the file name is +remembered as the "current filename". + +If there already was a current filename, then that one becomes the alternate +file name. All filenames are remembered in the file list. When you enter a +filename, for editing (e.g., with ":e filename") or writing (e.g., with (:w +filename"), the filename is added to the list. You can use this list to +remember which files you edited and to quickly switch from one file to +another with the CTRL-^ command (e.g., to copy text). First type the number +of the file and then hit CTRL-^. {Vi: only one alternate filename} + +CTRL-G or *CTRL-G* *:f* *:file* +:f[ile] Prints the current filename (as typed), the + cursor position (unless the 'ruler' option is set), + and the file status (readonly, modified). See the + 'shortmess' option about how tho make this message + shorter. {Vi does not include column number} + +{count}CTRL-G Like CTRL-G, but prints the current filename with full + path. If the count is higher than 1 the current + buffer number is also given. {not in Vi} + + *g_CTRL-G* +g CTRL-G Prints the current position of the cursor in three + ways: Column, Line and Character. If there are + characters in the line that take more than one + position on the screen (<Tab> or special character), + both the "real" column and the screen column are + shown, separated with a dash. See also 'ruler' + option. {not in Vi} + + *:file_f* +:f[ile] {name} Sets the current filename to {name}. + +:buffers +:files +:ls List all the currently known file names. See + 'vim_win.txt' |:files| |:buffers| |:ls|. {not in + Vi} + +Vim will remember the full path name of a file name that you enter. In most +cases when the file name is displayed only the name you typed is shown, but +the full path name is being used if you used the ":cd" command |:cd|. + + *home_replace* +If the environment variable 'HOME' is set, and the file name starts with that +string, it is often displayed with HOME replaced with "~". This was done to +keep file names short. When reading or writing files the full name is still +used, the "~" is only used when displaying file names. When replacing the +file name would result in just "~", "~/" is used instead (to avoid confusion +with 'backupext' set to "~"). + +When writing the buffer, the default is to use the current filename. Thus +when you give the "ZZ" or ":wq" command, the original file will be +overwritten. If you do not want this, the buffer can be written into another +file by giving a filename argument to the ":write" command. For example: + + vim testfile + [change the buffer with editor commands] + :w newfile + :q + +This will create a file "newfile", that is a modified copy of "testfile". +The file "testfile" will remain unchanged. Anyway, if the 'backup' option is +set, Vim renames or copies the original file before it will be overwritten. +You can use this file if you discover that you need the original file. See +also the 'patchmode' option. The name of the backup file is normally the same +as the original file with 'backupext' appended. The default "~" is a bit +strange to avoid accidently overwriting existing files. If you prefer ".bak" +change the 'backupext' option. Extra dots are replaced with '_' on MS-DOS +machines, when Vim has detected that an MS-DOS-like filesystem is being used +(e.g., messydos or crossdos) or when the 'shortname' option is on. The +backup file can be placed in another directory by setting 'backupdir'. + + *auto_shortname* +Technical: On the Amiga you can use 30 characters for a file name. But on an + MS-DOS-compatible filesystem only 8 plus 3 characters are + available. Vim tries to detect the type of filesystem when it is + creating the .swp file. If an MS-DOS-like filesystem is suspected, + a flag is set that has the same effect as setting the 'shortname' + option. This flag will be reset as soon as you start editing a + new file. The flag will be used when making the filename for the + ".swp" and ".~" files for the current file. But when you are + editing a file in a normal filesystem and write to an MS-DOS-like + filesystem the flag will not have been set. In that case the + creation of the ".~" file may fail and you will get an error + message. Use the 'shortname' option in this case. + +When you started editing without giving a file name, "No File" is displayed in +messages. If the ":write" command is used with a file name argument, the file +name for the current file is set to that file name. This only happens when +the 'F' flag is included in 'cpoptions' (by default it is included). This is +useful when entering text in an empty buffer and then writing it to a file. +If 'cpoptions' contains the 'f' flag (by default it is NOT included) the file +name is set for the ":read file" command. This is useful when starting Vim +without an argument and then doing ":read file" to start editing a file. +Because the file name was set without really starting to edit that file, you +are protected from overwriting that file. This is done by setting the +"notedited" flag. You can see if this flag is set with the CTRL-G or ":file" +command. It will include "[Not edited]" when the "notedited" flag is set. +When writing the buffer to the current file name (with ":w!"), the "notedited" +flag is reset. + +Vim remembers whether you have changed the buffer. You are protected from +losing the changes you made. If you try to quit without writing, or want to +start editing another file, this will be refused. In order to overrule this +protection add a '!' to the command. The changes will then be lost. For +example: ":q" will not work if the buffer was changed, but ":q!" will. To see +whether the buffer was changed use the "CTRL-G" command. The message includes +the string "[Modified]" if the buffer has been changed. + + +5.2 Editing a file *edit_a_file* + + *:e* *:edit* +:e[dit] [+cmd] Edit the current file, unless changes have been made. + + *:edit!* +:e[dit]! [+cmd] Edit the current file always. Discard any changes to + the buffer. + + *:edit_f* +:e[dit] [+cmd] {file} Edit {file}, unless changes have been made. + + *:edit!_f* +:e[dit]! [+cmd] {file} Edit {file} always. Discard any changes to the + buffer. + +:e[dit] #[count] Edit the [count]th alternate filename (as shown by + :files). This command does the same as [count] CTRL-^. + + *:ex* +:ex [+cmd] [file] Same as :edit. {Vi: go from visual to Ex mode} + + *:vi* *:visual* +:vi[sual] [+cmd] [file] Same as :edit. {Vi: go from Ex to visual mode} + + *:vie* *:view* +:vie[w] [+cmd] file Same as :edit, but set 'readonly' option for this + buffer. {not in Vi} + + *CTRL-^* +[count]CTRL-^ Edit [count]th alternate file (equivalent to ":e + #[count]"). Without count this gets you to the + previously edited file. This is a quick way to + toggle between two (or more) files. If the + 'autowrite' option is on and the buffer was + changed, write it. + +]f *]f* +[f *[f* *gf* +gf Edit the file whose name is under or after the + cursor. Mnemonic: "goto file". Uses the 'isfname' + option to find out which characters are supposed to be + in a file name. Uses the 'path' variable as a list of + directory names to look for the file. Also looks for + the file relative to the current file. This command + fails if the current file cannot be abandoned. If the + name is a hypertext link, that looks like + "type://machine/path", only "/path" is used. For Unix + the '~' character is expanded, like in "~user/file". + {not in Vi} + + *:cd* +:cd On non-Unix systems: Print the current directory + name. On Unix systems: Change the current directory + to the home directory. + +:cd {path} Change the current directory to {path}. Does not + change the meaning of an already entered file name, + because its full path name is remembered. On MS-DOS + this also changes the active drive. + + *:chd* *:chdir* +:chd[ir] [path] Same as :cd. + + *:pw* *:pwd* +:pw[d] Print the current directory name. {Vi: no pwd} + +These commands are used to start editing a single file. This means that the +file is read into the buffer and the current filename is set. You may use the +":cd" command to get to another directory, so you will not have to type that +directory name in front of the filenames. One warning: After using ":cd" the +full path name will be used for reading and writing files. On some networked +file systems this may cause problems. The result of using the full path name +is that the file names currently in use will remain referring to the same +file. Example: If you have a file a:test and a directory a:vim the commands +":e test" ":cd vim" ":w" will overwrite the file a:test and not write +a:vim/test. But if you do ":w test" the file a:vim/test will be written, +because you gave a new file name and did not refer to a file name before the +":cd". + + *:filename* +Note for systems other than Unix and MS-DOS: When using a command that +accepts a single file name (like ":edit file") spaces in the file name are +allowed, but trailing spaces are ignored. This is useful on systems that +allow file names with embedded spaces (like the Amiga). Example: The command +":e Long File Name " will edit the file "Long File Name". When using a +command that accepts more than one file name (like ":next file1 file2") +embedded spaces must be escaped with a backslash. + +On Unix you can also use backticks in the file name, for example: + :e `find . -name ver\\*.c -print` +The backslashes before the star are required to prevent "ver*.c" to be +expanded by the shell before executing the find program. + +You can use the ":e!" command if you messed up the buffer and want to start +all over again. The ":e" command is only useful if you have changed the +current filename. + +Note that ":e file" will fail if there are changes in the current buffer, +also when the 'autowrite' option is on. This is illogical, because with +other commands (e.g., ":next") the current buffer would be written and +abandoned, but this behaviour is compatible with Vi. If you encounter this +problem, you can use CTRL-^ to jump to the file, because the alternate file +name is set to the argument of the ":e" command. + + *:+cmd* +The [+cmd] can be used to position the cursor in the newly opened file: + + Start at the last line. + +{num} Start at line {num}. + +/{pat} Start at first line containing {pat}. {pat} must not + contain any spaces. + +{command} Execute {command} after opening the new file. + {command} is an Ex command. It must not contain + spaces. + + *textmode_io* +When reading a file when the 'textmode' option is off (default for +non-MS-DOS) the <NL> character is interpreted as end-of-line. If 'textmode' +is on (default for MS-DOS), <CR><NL> is also interpreted as end-of-line. +Also see |textmode_read|. + +When writing a file when the 'textmode' option is off a <NL> character is +used to separate lines. When the 'textmode' option is on <CR><NL> is used. +Also see |textmode_write|. + +You can read a file with 'textmode' set and write it with 'textmode' reset. +This will replace all <CR><NL> pairs by <NL>. If you read a file with +'textmode' reset and write with 'textmode' set, all <NL> characters will be +replaced with <CR><NL>. + +If you start editing a new file and the 'textauto' option is on (which is the +default), Vim will try to detect whether the lines in the file are separated +by a single <NL> (as used on Unix and Amiga) or by a <CR><NL> pair (MS-DOS). +Only when ALL lines end in <CR><NL> the 'textmode' option is set, otherwise it +is reset. If the 'textmode' option is set on non-MS-DOS systems the message +"[textmode]" is shown to remind you that something unusual is happening. On +MS-DOS systems you get the message "[notextmode]" if the 'textmode' option is +not set. + +If the 'textauto' option is off and 'textmode' is on, but while reading a file +some lines did not end in <CR><NL>, "[CR missing]" will be included in the +file message. + +Before editing binary, executable or Vim script files you should set the +'textmode' and 'textauto' options off. With 'textmode' on you risk that +single <NL> characters are unexpectedly replaced with <CR><NL>. A simple way +to do this is by starting Vim with the "-b" option. + + +5.3 The argument list *argument_list* + +If you give more than one filename when starting Vim, this list is +remembered as the argument list. Do not confuse this with the file list, +which you can see with the ":files" command |:files|. The argument list was +already present in Vi, the file list is new in Vim. The file names in the +argument list will also be present in the file list (unless they were +deleted with ":bdel"). + +You can use the argument list with the following commands: + + *:ar* *:args* +:ar[gs] Print the argument list, with the current file in + square brackets. + + *:argu* *:argument* +:[count]argu[ment] [count] [+cmd] + Edit file [count] in the argument list, unless + changes have been made and the 'autowrite' option is + off. {Vi: no such command} + +:[count]argu[ment]! [count] [+cmd] + Edit file [count] in the argument list, discard any + changes to the current buffer. {Vi: no such command} + + *:n* *:next* +:[count]n[ext] [+cmd] Edit [count] next file, unless changes have been + made and the 'autowrite' option is off {Vi: no + count}. + +:[count]n[ext]! [+cmd] Edit [count] next file, discard any changes to the + buffer {Vi: no count}. + +:ar[gs] [+cmd] {arglist} +:n[ext] [+cmd] {arglist} + Define {arglist} as the new argument list and edit + the first one, unless changes have been made and the + 'autowrite' option is off. + +:ar[gs]! [+cmd] {arglist} +:n[ext]! [+cmd] {arglist} *:next_f* + Define {arglist} as the new argument list and edit + the first one. Discard any changes to the buffer. + +:[count]N[ext] [count] [+cmd] *:Next* *:N* + Edit [count] previous file in argument list, unless + changes have been made and the 'autowrite' option is + off {Vi: no count}. + +:[count]N[ext]! [count] [+cmd] + Edit [count] previous file in argument list. Discard + any changes to the buffer {Vi: no count}. + +:[count]prev[ious] [count] [+cmd] *:prev* *:previous* + Same as :Next {Vi: only in some versions} + + *:rew* *:rewind* +:rew[ind] [+cmd] Start editing the first file in the argument list, + unless changes have been made and the 'autowrite' + option is off. + +:rew[ind]! [+cmd] Start editing the first file in the argument list. + Discard any changes to the buffer. + + *:la* *:last* +:la[st] [+cmd] Start editing the last file in the argument list, + unless changes have been made and the 'autowrite' + option is off. {not in Vi} + +:la[st]! [+cmd] Start editing the last file in the argument list. + Discard any changes to the buffer. {not in Vi} + + *:wn* *:wnext* +:[count]wn[ext] [+cmd] Write current file and start editing the [count] + next file. {not in Vi} + +:[count]wn[ext] [+cmd] {file} + Write current file to {file} and start editing the + [count] next file, unless {file} already exists and + the 'writeany' option is off. {not in Vi} + +:[count]wn[ext]! [+cmd] {file} + Write current file to {file} and start editing the + [count] next file. {not in Vi} + +:[count]wN[ext][!] [+cmd] [file] *:wN* *:wNext* +:[count]wp[revous][!] [+cmd] [file] *:wp* *:wprevious* + Same as :wnext, but go to previous file instead of + next. {not in Vi} + +The [count] in the commands above defaults to one. For some commands it is +possible to use two counts. The last one (rightmost one) is used. + +For [+cmd] see 5.2 |edit_a_file|. + +The wildcards in the argument list are expanded and the filenames are sorted. +Thus you can use the command "vim *.c" to edit all the C files. From within +Vim the command ":n *.c" does the same. On Unix you can also use backticks, +for example: + :n `find . -name \\*.c -print` +The backslashes before the star are required to prevent "*.c" to be expanded +by the shell before executing the find program. + + *arglist_quit* +You are protected from leaving Vim if you have not been editing the last file +in the argument list. This prevents you from forgetting that you were editing +one out of several files. To exit anyway try to exit twice. If there are +changes in the current buffer this will fail. You can exit anyway, and save +any changes, with the ":wq!" command. To lose any changes use the ":q!" +command. + +When there is an argument list you can see which file you are editing in the +title of the window (if there is one and 'title' is on) and with the file +message you get with the "CTRL-G" command. You will see something like + (file 4 of 11) +If 'shortmess' contains 'f' it will be + (4 of 11) +If you are not really editing the file at the current position in the argument +list it will be + (file (4) of 11) +This means that you are position 4 in the argument list, but not editing the +fourth file in the argument list. This happens when you do ":e file". + + +5.4 Writing and quitting *write_quit* *save_file* + + *:w* *:write* +:[range]w[rite][!] Write the specified lines to the current file. + + *:w_f* *:write_f* +:[range]w[rite] {file} Write the specified lines to {file}, unless it + already exists and the 'writeany' option is off. + + *:w!* +:[range]w[rite]! {file} Write the specified lines to {file}. Overwrite an + existing file. + + *:w_a* *:write_a* +:[range]w[rite][!] >> Append the specified lines to the current file. + +:[range]w[rite][!] >> {file} + Append the specified lines to {file}. '!' forces the + write even if file does not exist. + + *:w_c* *:write_c* +:[range]w[rite] !{cmd} Execute {cmd} with [range] lines as standard input + (note the space in front of the '!'). {cmd} is + executed like with ":!{cmd}", any '!' is replaced with + the previous command |:!|. + +The default [range] for the ":w" command is the whole buffer (1,$). +If a file name is give with ":w" it becomes the alternate file. This can be +used when the write fails and you want to try again later with ":w #". + + + *:q* *:quit* +:q[uit] Quit, unless changes have been made or not editing + the last file in the argument list. + +:q[uit]! Quit always, without writing. + +:cq Quit always, without writing, and return an error + code. Used for Manx's QuickFix mode (see 5.5 + |quickfix|). + + *:wq* +:wq Write the current file and exit (unless editing the + last file in the argument list or the file is + read-only). + +:wq! Write the current file and exit. + +:wq {file} Write to {file}. Exit if not editing the last + file in the argument list. + +:wq! {file} Write to {file} and exit. + +:[range]wq[!] [file] Same as above, but only write the lines in [range]. + + *:x* *:xit* +:[range]x[it][!] [file] + Like ":wq", but write only when changes have been + made. + + *:exi* *:exit* +:[range]exi[t][!] [file] + Same as :xit. + + *ZZ* +ZZ Write current file, if modified, and exit (same as + ":x"). (Note: If there are several windows for the + current file, the file is written if it was modified + and the window is closed). + + *timestamp* +Vim remembers the timestamp of the file when you start editing it. When you +write a file the timestamp is checked. If the file has been changed since you +started editing it, Vim will ask you if you really want to overwrite the file: + + WARNING: The file has been changed since reading it!!! + Do you really want to write to it (y/n)? + +If you hit 'y' Vim will continue writing the file. If you hit 'n' the write is +aborted. If you used ":wq" or "ZZ" Vim will not exit, you will get another +chance to write the file. +The message would normally mean that somebody has written to the file after +the edit session started. This could be another person, in which case you +probably want to check if your changes to the file and the changes from the +other person should be merged. Write the file under another name and check for +differences (the "diff" program can be used for this). +It is also possible that you modified the file yourself, from another edit +session or with another command (e.g., a filter command). Then you will know +which version of the file you want to keep. + + *backup* +If you write to an existing file (but do not append) while the 'backup', +'writebackup' or 'patchmode' option is on, a backup of the original file is +made. On Unix systems the file is copied, on other systems the file is +renamed. After the file has been successfully written and when the +'writebackup' option is on and the 'backup' option is off, the backup file is +deleted. When the 'patchmode' option is on the backup file may be renamed. + + *backup_table* +'backup' 'writebackup' action + off off no backup made + off on backup current file, deleted afterwards (default) + on off delete old backup, backup current file + on on delete old backup, backup current file + +When the 'backup' option is on, an old backup file (with the same name as the +new backup file) will be deleted. If 'backup' is not set, but 'writebackup' is +set, an existing backup file will not be deleted. The backup file that is made +while the file is being written will have a different name. + +The directories given with the 'backupdir' option is used to put the backup +file in. (default: same directory as the written file). + +On Unix systems: +When you write to an existing file, that file is truncated and then filled +with the new text. This means that protection bits, owner and symbolic links +are unmodified. The backup file however, is a new file, owned by the user who +edited the file. The group of the backup is set to the group of the original +file. If this fails, the protection bits for the group are made the same as +for others. + +If the creation of a backup file fails, the write is not done. If you want +to write anyway add a '!' to the command. + + *write_fail* +If the writing of the new file fails, you have to be careful not to lose +your changes AND the original file. If there is no backup file and writing +the new file failed, you have already lost the original file! DON'T EXIT VIM +UNTIL YOU WRITE OUT THE FILE! If a backup was made, it is put back in place +of the original file (if possible). If you exit Vim, and lose the changes +you made, the original file will mostly still be there. If putting back the +original file fails, there will be an error message telling you that you +lost the original file. + + *textmode_write* +If the 'textmode' option is on <CR><NL> is used for end-of-line. This is +default for MS-DOS, Win32 and OS/2. On other systems the message "[textmode]" +is shown to remind you that an usual end-of-line marker was used. If the +'textmode' is not set NL is used for end-of-line. On MS-DOS, Win32 and OS/2 +the message "[notextmode]" is shown. See also |textmode_io| and the +'textmode' and 'textauto' options. + + +5.5 Using the QuickFix mode *quickfix* + +Vim has a special mode to speedup the edit-compile-edit cycle. This is +inspired by the quickfix option of the Manx's Aztec C compiler on the Amiga. +The idea is to save the error messages from the compiler in a file and use +Vim to jump to the errors one by one. You can then examine each problem and +fix it, without having to remember all the error messages. + +If you are using Manx's Aztec C compiler on the Amiga you should do the +following: +- Set the CCEDIT environment variable with the command + mset "CCEDIT=vim -e" +- Compile with the -qf option. If the compiler finds any errors, Vim is + started and the cursor is positioned on the first error. The error message + will be displayed on the last line. You can go to other errors with the + commands mentioned below. You can fix the errors and write the file(s). +- If you exit Vim normally the compiler will re-compile the same file. If you + exit with the :cq command, the compiler will terminate. Do this if you + cannot fix the error, or if another file needs to be compiled first. + +If you are using another compiler you should save the error messages in a +file and start Vim with "vim -e filename". An easy way to do this is with +the ":make" command (see below). The 'errorformat' option should be set to +match the error messages from your compiler (see below). + +The following commands can be used if you are in QuickFix mode: + + *:cc* +:cc [nr] Display error [nr]. If [nr] is omitted, the same + error is displayed again. {not in Vi} + + *:cn* *:cnext* +:[count]cn[ext] Display the [count] next error in the list that + includes a file name. If there are no file names at + all, go the the [count] next error. {not in Vi} + +:[count]cN[ext] *:cp* *:cprevious* *:cN* *:cNext* +:[count]cp[revious] Display the [count] previous error in the list that + includes a file name. If there are no file names at + all, go the the [count] previous error. {not in Vi} + + *:cq* *:cquit* +:cq[uit] Quit Vim with an error code, so that the compiler + will not compile the same file again. {not in Vi} + + *:cf* *:cfile* +:cf[ile] [errorfile] Read the error file and jump to the first error. + This is done automatically when Vim is started with + the -e option. You can use this command when you + keep Vim running while compiling. If you give the + name of the errorfile, the 'errorfile' option will + be set to [errorfile] {not in Vi} + + *:cl* *:clist* +:cl[ist] List all errors that inlcude a file name. {not in Vi} + +:cl[ist]! List all errors. {not in Vi} + + *:mak* *:make* +:mak[e] [arguments] 1. If the 'autowrite' option is on, write any changed + buffers + 2. Any existing 'errorfile' is deleted. + 3. The program given with the 'makeprg' option is + started (default "make") with the optional + [arguments] and the output is saved in + 'errorfile' (for Unix it is also echoed on the + screen). + 4. The 'errorfile' is then read and the first error + is jumped to. + 5. The 'errorfile' is deleted. + {not in Vi} + +The name of the file can be set with the 'errorfile' option. The default is +"AztecC.Err" for the Amiga and "errors.vim" for other systems. The format of +the file from the Aztec compiler is: + + filename>linenumber:columnnumber:errortype:errornumber:errormessage + + filename name of the file in which the error was detected + linenumber line number where the error was detected + columnnumber column number where the error was detected + errortype type of the error, normally a single 'E' or 'W' + errornumber number of the error (for lookup in the manual) + errormessage description of the error + + *errorformat* +Another compiler is likely to use a different format. You should set the +'errorformat' option to a scanf-like string that describes the format. +First, you need to know how scanf works. Look in the documentation of your +C compiler. Vim will understand eight conversion characters. Others are +invalid. + %f file name (finds a string) + %l line number (finds a number) + %c column number (finds a number) + %t error type (finds a single character) + %n error number (finds a number) + %m error message (finds a string) + %*<conv> any scanf non-assignable conversion + %% the single '%' character + +Examples: +%f>%l:%c:%t:%n:%m" for the AztecC.Err file +%f:%l:\ %t%*[^0123456789]%n:\ %m for Manx/Aztec C error messages + (scanf() doesn't understand [0-9]) +%f\ %l\ %t%*[^0-9]%n:\ %m for SAS C +\"%f\"\\,%*[^0-9]%l:\ %m for generic C compilers +%f:%l:\ %m for GCC +%f(%l)\ :\ %*[^:]:\ %m old SCO C compiler (pre-OS5) +%f(%l)\ :\ %t%*[^0-9]%n:\ %m idem, with error type and number +%f:%l:\ %m,In\ file\ included\ from\ %f:%l:,\^I\^Ifrom\ %f:%l%m + for GCC, with some extras + +Note the backslash in front of a space and double quote. It is required for +the :set command. There are two backslashes in front of a comma, one for the +:set command and one to avoid recognizing the comma as a separator of error +formats. + +The "%f" and "%m" conversions have to detect the end of the string. They +should be followed by a character that cannot be in the string. Everything +up to that character is included in the string. Be careful: "%f%l" will +include everything up to the first '%' in the file name. If the "%f" or "%m" +is at the end, everything up to the end of the line is included. + +To be able to detect output from several compilers, several format patterns +may be put in 'errorformat', separated by commas (note: blanks after the comma +are ignored). The first pattern that has a complete match is used. If no +match is found, matching parts from the last one will be used, although the +file name is removed and the error message is set to the whole message. If +there is a pattern that may match output from several compilers (but not in a +right way), put it after one that is more restrictive. To include a comma in +a pattern precede it with a backslash (you have to type two in a set command). +To include a backslash itself give two backslashes (you have to type four in a +set command). + +If a line is detected that does not completely match the 'errorformat', the +whole line is put in the error message and the entry is marked "not valid" +These lines are skipped with the ":cn" and ":cp" commands (unless there is +no valid line at all). You can use ":cl!" to display all the error messages. + +If the error format does not contain a file name Vim cannot switch to the +correct file. You will have to do this by hand. + +If you have a compiler that produces error messages that do not fit in the +format string, you could write a program that translates the error messages +into this format. You can use this program with the ":make" command by +changing the 'makeprg' option. For example: + ":set mp=make\ \\\|&\ error_filter". +The backslashes before the pipe character are required to avoid it to be +recognized as a command separator. The backslash before each space is +required for the set command. + + *:make_makeprg* +The ":make" command executes the command given with the 'makeprg' option. +This is done by passing the command to the shell given with the 'shell' +option. This works almost like typing + + ":!{makeprg} [arguments] {shellpipe} {errorfile}". + +{makeprg} is the string given with the 'makeprg' option. Any command can be +used, not just "make". Characters '%' and '#' are expanded as usual on a +command line. You can use "#<" to insert the current filename without +extension, for example ":set makeprg=make\ #<.o". + +[arguments] is anything that is typed after ":make". +{shellpipe} is the 'shellpipe' option. +{errorfile} is the 'errorfile' option. + +The 'shellpipe' option defaults to ">" for the Amiga, MS-DOS and Win32. This +means that the output of the compiler is saved in a file and not shown on the +screen directly. For Unix "| tee" is used. The compiler output is shown on +the screen and saved in a file the same time. Depending on the shell used +"|& tee" or "2>&1| tee" is the default, so stderr output will be included. + +There are some restrictions to the Quickfix mode on the Amiga. The +compiler only writes the first 25 errors to the errorfile (Manx's +documentation does not say how to get more). If you want to find the others, +you will have to fix a few errors and exit the editor. After recompiling, +up to 25 remaining errors will be found. + +On the Amiga, if Vim was started from the compiler, the :sh and :! commands +will not work, because Vim is then running in the same process as the +compiler and these two commands may guru the machine then. + +If you insert or delete lines, mostly the correct error location is still +found because hidden marks are used (Manx's Z editor does not do this). +Sometimes, when the mark has been deleted for some reason, the message "line +changed" is shown to warn you that the error location may not be correct. If +you quit Vim and start again the marks are lost and the error locations may +not be correct anymore. + + +5.6 Editing binary files *edit_binary* + +Although Vim was made to edit text files, it is possible to edit binary +files. The "-b" Vim argument (b for binary) sets some options for +editing binary files ('binary' on, 'textwidth' to 0, 'textmode' and +'textauto' off, 'modeline' off, 'expandtab' off). Setting the 'binary' +option has the same effect. Don't forget to do this before reading the file. + +There are a few things to remember when editing binary files: +- When editing executable files the number of characters must not change. + Use only the "R" or "r" command to change text. Do not delete characters + with "x" or by backspacing. +- Set the 'textwidth' option to 0. Otherwise lines will unexpectedly be + split in two. +- When there are not many end-of-line characters, the lines will become very + long. If you want to edit a line that does not fit on the screen reset the + 'wrap' option. Horizontal scrolling is used then. If a line becomes too + long (more than about 32767 characters on the Amiga, much more on 32-bit + systems, see |limits|) you cannot edit that line. The line will be split + when reading the file. It is also possible that you get an "out of memory" + error when reading the file. +- Make sure the 'textmode' and 'textauto' options are off before loading the + file. In 'textmode' both <CR><NL> and <NL> are considered to end a line + and when the file is written the <NL> will be replaced with <CR><NL>. The + 'modelines' option should also be off, because there may be a string like + ":vi:" in the file that would give unpredictable results. +- <Nul> characters are shown on the screen as ^@. You can enter them with + "CTRL-V CTRL-@" or "CTRL-V 000" {Vi cannot handle <Nul> characters in the + file} +- To insert a <NL> character in the file split up a line. When writing the + buffer to a file a <NL> will be written for the end of line. +- Vim normally appends an end-of-line character at the end of the file if + there is none. Setting the 'binary' option prevents this. If you want to + add the final end-of-line, set the 'endofline' option. You can also read the + value of this option to see if there was an end-of-line character for the + last line (you cannot see this in the text). + + +5.7 Automatic commands *autocommand* + +You can specify commands to be executed automatically for when reading or +writing a file, when entering or leaving a buffer or window, and when exiting +Vim. For example, 'cindent' can be set for files matching *.c, and unset +otherwise. Autocommands can be used to edit compressed files. These commands +are normally put in your .vimrc or .exrc file. {All this is not in Vi} + +WARNING: Using autocommands is very powerful, but may lead to unexpected side +effects. Be careful not to destroy your text. +- It's a good idea to first do some testing on a copy of a file first. For + example: If you use autocommands to decompress a file when starting to edit + it, make sure that the autocommands for compressing when writing work + correctly. +- Be prepared for an error halfway through (e.g., disk full). Vim will mostly + be able to undo the changes to the buffer, but you may have to clean up the + changes to other files by hand (e.g., compress a file that has been + decompressed). +- If the BufRead* events allow you to edit a compressed file, the FileRead* + events should do the same (to be able to do recovery in some rare cases). + It's a good idea to use the same autocommands for the File* and Buf* events + when possible. + +The autocommand feature is only included if Vim has been compiled with AUTOCMD +defined. If the output of ":version" contains "+autocmd" it is included (this +is the default), if it contains "-autocmd" then the autocommand feature +doesn't work. + +Note: This command cannot be followed by another command, since any '|' is +considered part of the command. + + *:au* *:autocmd* +:au[tocmd] {event} {pat} {cmd} + Add {cmd} to the list of commands that will be + automatically executed on {event} for a file matching + {pat}. It is not added if it is already there (as may + happen when .vimrc is sourced again). The order of + entering {cmd} and {pat} is important. + +:au[tocmd] {event} {pat} + Show the auto-commands associated with {event} and + {pat}. + +:au[tocmd] * {pat} Show the auto-commands associated with pat} for all + events. + +:au[tocmd] {event} Show all auto-commands for {event}. + +:au[tocmd] Show all auto-commands. + +:au[tocmd]! {event} {pat} {cmd} + Remove all auto-commands associated with {event} and + {pat}, and add the command {cmd}. + +:au[tocmd]! {event} {pat} + Remove all auto-commands associated with {event} and + {pat}. + +:au[tocmd]! * {pat} Remove all auto-commands associated with {pat} for all + events. + +:au[tocmd]! {event} Remove ALL auto-commands for {event}. + +:au[tocmd]! Remove ALL auto-commands. + + *:do* *:doautocmd* +:do[autocmd] {event} [fname] + Apply the autocommands matching [fname] (default: + current file name) for {event} to the current buffer. + This can be used when the current file name does not + match the right pattern, after changing settings, or + to execute autocommands for a certain event. + +These events are recognized. Case is ignored, for example "BUFread" and +"bufread" can be used instead of "BufRead". + + *BufNewFile* +BufNewFile When starting to edit a file that doesn't + exist. Can be used to read in a skeleton + file. + *BufReadPre* +BufReadPre When starting to edit a new buffer, before + reading the file into the buffer. Not used + when starting to edit a new file. + *BufRead* *BufReadPost* +BufRead or BufReadPost When starting to edit a new buffer, after + reading the file into the buffer, before + executing the modelines. This does NOT work + for ":r file". Not used when starting to edit + a new file. + *FileReadPre* +FileReadPre Before reading a file with a ":read" command. + *FileReadPost* +FileReadPost After reading a file with a ":read" command. + Note that the '[ and '] marks are set to the + first and last line of the read, this can be + used to operate on the just read lines. + *FilterReadPre* +FilterReadPre Before reading a file from a filter command. + The file name of the current buffer is used to + match with the pattern, not the name of the + temporary file that is the output of the + filter command. + *FilterReadPost* +FilterReadPost After reading a file from a filter command. + Like FilterReadPre, the file name of the + current buffer is used. + *BufWrite* *BufWritePre* +BufWrite or BufWritePre Before writing the whole buffer to a file. + *BufWritePost* +BufWritePost After writing the whole buffer to a file + (should undo the commands for BufWritePre). + *FileWritePre* +FileWritePre Before writing to a file, when not writing the + whole buffer. + *FileWritePost* +FileWritePost After writing to a file, when not writing the + whole buffer. + *FileAppendPre* +FileAppendPre Before appending to a file. + *FileAppendPost* +FileAppendPost After appending to a file. + *FilterWritePre* +FilterWritePre Before writing a file for a filter command. + The file name of the current buffer is used to + match with the pattern, not the name of the + temporary file that is the input for the + filter command. + *FilterWritePost* +FilterWritePost After writing a file for a filter command. + Like FilterWritePre, the file name of the + current buffer is used. + *BufEnter* +BufEnter After entering a buffer. Useful for setting + options for a file type. Also executed when + starting to edit a buffer, after the + BufReadPost autocommands. + *BufLeave* +BufLeave Before leaving to another buffer. Also when + leaving or closing the current window and the + new current window is not for the same buffer. + *WinEnter* +WinEnter After entering another window. Not done for + the first window, when Vim is just started. + Useful for setting the window height. + If the window is for another buffer, the + BufEnter autocommands are executed after the + WinEnter autocommands. + *WinLeave* +WinLeave Before leaving to another window. If the + window to be entered is for a different + buffer, the BufLeave autocommands are executed + before the WinLeave autocommands. + *VimLeave* +VimLeave Before exiting Vim, just before writing the + .viminfo file. There is no VimEnter event, + because you can use the .vimrc for that. + +For READING FILES there are three possible pairs of events, only one pair is +used at a time: +BufNewFile starting to edit a non-existant file +BufReadPre BufReadPost starting to edit an existing file +FilterReadPre FilterReadPost read the temp file with filter output +FileReadPre FileReadPost any other file read + +Before the *ReadPre event the '[ mark is set to the line just above where the +new lines will be inserted. +Before the *ReadPost event the '[ mark is set to the first line that was just +read, the '] mark to the last line. +Careful: '[ and '] will change when using commands that change the buffer. +"<afile>" can be used for the file name that is being read, in commands where +a file name is expected (where you can also use "%" for the current file +name) |:<afile>|. + +Examples for reading compressed files: + :autocmd! BufReadPre,FileReadPre *.gz set bin + :autocmd BufReadPost,FileReadPost *.gz '[,']!gunzip + :autocmd BufReadPost,FileReadPost *.gz set nobin + +NOTE: When using the examples given, any existing autocommands for the same +event/pattern combination will be removed, because of the '!'. + +For WRITING FILES there are four possible pairs of events, only one pair is +used at a time: +BufWritePre BufWritePost writing the whole buffer +FilterWritePre FilterWritePost writing to the temp file with filter input +FileAppendPre FileAppendPost appending to a file +FileWritePre FileWritePost any other file write + +Note that the *WritePost commands should undo any changes to the buffer that +were caused by the *WritePre commands, otherwise writing the file will have +the side effect of changing the buffer. + +Before the *WritePre event the '[ mark is set to the first line that will be +written, the '] mark to the last line. +Careful: '[ and '] will change when using commands that change the buffer. +"<afile>" can be used for the file name that is being written, in commands +where a file name is expected (where you can also use "%" for the current file +name) |:<afile>|. + +Examples for writing compressed files: + :autocmd! BufWritePost,FileWritePost *.gz !mv <afile> <afile>:r + :autocmd BufWritePost,FileWritePost *.gz !gzip <afile>:r + + :autocmd! FileAppendPre *.gz !gunzip <afile> + :autocmd FileAppendPre *.gz !mv <afile>:r <afile> + :autocmd! FileAppendPost *.gz !mv <afile> <afile>:r + :autocmd FileAppendPost *.gz !gzip <afile>:r + +("<afile>:r" is the file name without the extension, see |:_%:|) + +The commands executed for the BufNewFile, BufRead/BufReadPost, BufWritePost, +FileAppendPost and VimLeave events do not set or reset the changed flag of the +buffer. When you decompress the buffer with the BufReadPost autocommands, you +can still exit with ":q". When you use ":undo" in BufWritePost to undo the +changes made by BufWritePre commands, you can still do ":q" (this also makes +"ZZ" work). + +To execute Normal mode commands from an autocommand, use the ":normal" +command. Use with care! If the Normal mode command is not finished, the user +needs to type characters (e.g., after ":normal m" you need to type a mark +name). + +If you want the buffer not to be modified after changing it, reset the +'modified' option. This makes it possible to exit the buffer with ":q" +instead of ":q!". + +Autocommands do not nest. If you use ":r" or ":w" in an autocommand, the +BufRead and BufWrite autocommands are not executed for those commands. It's +also not possible to use the ":au" command in an autocommand (that could be a +self-modifying command!). + +There is currently no way to disable the autocommands. If you want to write a +file without executing the autocommands for that type of file, write it under +another name and rename it with a shell command. + +Note: When doing a ":read file" command and the last line in the file does not +have an end-of-line character, this is remembered. When executing the +FileReadPost autocommands and the same line is written again as the last line +in a file, no end-of-line character is written if 'binary' is set. This makes +a filter command on the just read lines write the same file as was read. + +Multiple patterns may be given separated by commas. Here are some examples: + + :autocmd BufRead * set tw=79 nocin ic infercase fo=2croq + :autocmd BufRead .letter set tw=72 fo=2tcrq + :autocmd BufEnter .letter set dict=/usr/lib/dict/words + :autocmd BufLeave .letter set dict= + :autocmd BufRead,BufNewFile *.c,*.h set tw=0 cin noic + :autocmd BufEnter *.c,*.h abbr FOR for(i = 0; i < 3; i++)^M{^M}^[O + :autocmd BufLeave *.c,*.h unabbr FOR + +For makefiles (makefile, Makefile, imakefile, makefile.unix, etc.): + + :autocmd BufEnter ?akefile* set include=^s\=include + :autocmd BufLeave ?akefile* set include& + +To always start editing C files at the first function: + + :autocmd BufRead *.c,*.h 1;/^{ + +Without the "1;" above, the search would start from wherever the file was +entered, rather than from the start of the file. + +To read a skeleton file for new C files: + + :autocmd BufNewFile *.c 0r ~/.skeleton.c + :autocmd BufNewFile *.h 0r ~/.skeleton.h + +To insert the current date and time in a *.html file when writing it: + +:autocmd BufWritePre,FileWritePre *.html ks|1,20g/Last modification: /normal f:lD:read !date^MkJ's + +(to insert the ^M type CTRL-V CTRL-M) +You need to have a line "Last modification: <date time>" in the first 20 lines +of the file for this to work. The <date time> (and anything in the same line +after it) will be replaced with the current date and time. Explanation: + ks mark current position with mark 's' + 1,20g/pattern/ find lines that contain the pattern + normal f: find the ':' + lD delete the old date and time + !date^M read the current date and time into the next line + kJ Join the date and time with the previous line + 's return the cursor to the old position + +When entering :autocmd on the command line, completion of events and command +names may be done (with <Tab>, CTRL-D, etc.) where appropriate. + +All matching auto-commands will be executed in the order that they were +specified. It is recommended that your first auto-command be used for all +files by using "*" as the file pattern. This means that you can define +defaults you like here for any settings, and if there is another matching +auto-command it will override these. But if there is no other matching +auto-command, then at least your default settings are recovered (if entering +this file from another for which auto-commands did match). Note that "*" will +also match files starting with ".", unlike Unix shells. + +Normally the file pattern is tested for a match against just the tail part of +the file name (without its leading directory path), but if a path separator +character (eg '/' on Unix) appears in the pattern, then it will be tested +against the full file name. For example: + + :autocmd BufRead */vim/src/* set wrap + + +6. Cursor motions *cursor_motions* +================= + +These commands move the cursor position. If the new position is off of the +screen, the screen is scrolled to show the cursor (see also 'scrolljump' and +'scrolloff' options). + + *operator* +The motion commands can be used after an operator command, to have the command +operate on the text that was moved over. That is the text between the cursor +position before and after the motion. Operators are generally used to delete +or change text. The following operators are available: + |c| c change + |d| d delete + |y| y yank into register (does not change the text) + |~| ~ swap case (only if 'tildeop' is set) + |g~| g~ swap case + |gu| gu make lower case + |gU| gU make upper case + |!| ! filter through an external program + |=| = filter through 'equalprg' or C-indenting if empty + |Q| Q text formatting (obsolete) + |gq| gq text formatting + |>| > shift right + |<| < shift left +If the motion includes a count and the operator also had a count before it, +the two counts are multiplied. For example: "2d3w" deletes six words. + The operator either affects whole lines, or the characters between the +start and end position. Generally, motions that move between lines affect +lines (are linewise), and motions that move within a line affect characters. +However, there are some exceptions. + A character motion is either inclusive or exclusive. When inclusive, +the start and end position of the motion are included in the operation. +When exclusive, the last character towards the end of the buffer is not +included. Linewise motions always include the start and end position. + Which motions are linewise, inclusive or exclusive is mentioned +below. There are however, two general exceptions: +1. If the motion is exclusive and the end of the motion is in column 1, the + end of the motion is moved to the end of the previous line and the motion + becomes inclusive. Example: "}" ends at the first line after a paragraph, + but "V}" will not include that line. +2. If the motion is exclusive, the end of the motion is in column 1 and the + start of the motion was at or before the first non-blank in the line, the + motion becomes linewise. Example: If a paragraph begins with some blanks + and you do "d}" while standing on the first non-blank, all the lines of + the paragraph are deleted, including the blanks. If you do a put now, the + deleted lines will be inserted below the cursor position. + +Instead of first giving the operator and then a motion you can use Visual +mode: mark the start of the text with "v", move the cursor to the end of the +text that is to be affected and then hit the operator. The text between the +start and the cursor position is highlighted, so you can see what text will +be operated upon. This allows much more freedom, but requires more key +strokes and has limited redo functionality. See the chapter on Visual mode +|Visual_mode|. + +If you want to know where you are in the file use the "CTRL-G" command +|CTRL-G| or the "g CTRL-G command |g_CTRL-G|. If you set the 'ruler' option, +the cursor position is continuously shown in the status line (which slows down +Vim a little). + +NOTE: Experienced users prefer the hjkl keys because they are always right +under their fingers. Beginners often prefer the arrow keys, because they +do not know what the hjkl keys do. The mnemonic value of hjkl is clear from +looking at the keyboard. Think of j as an arrow pointing downwards. + + +6.1 Left-right motions *left_right_motions* + +h or *h* +<Left> or *<Left>* +CTRL-H or *CTRL-H* *<BS>* +<BS> [count] characters to the left (exclusive). + Note: If you prefer <BS> to delete a character, use + the mapping: + :map CTRL-V<BS> X + (to enter "CTRL-V<BS>" type the CTRL-V key, followed + by the <BS> key) + See |:fixdel| if the <BS> key does not do what you + want. + +l or *l* +<Right> or *<Right>* *<Space>* +<Space> [count] characters to the right (exclusive). + + *0* +0 To the first character of the line (exclusive). When + moving up or down, stay in same screen column (if + possible). + + *<Home>* +<Home> To the first character of the line (exclusive). When + moving up or down, stay in same text column (if + possible). Works like "1|", which differs from "0" + when the line starts with a <Tab>. {not in Vi} + + *^* +^ To the first non-blank character of the line + (exclusive). + + *$* *<End>* +$ or <End> To the end of line and [count - 1] lines downward + (inclusive). + + *g0* *g<Home>* +g0 or g<Home> When lines wrap ('wrap on): To the first character of + the screen line (exclusive). Differs from "0" when a + line is wider than the screen. + When lines don't wrap ('wrap' off): To the leftmost + character of the current line that is on the screen. + Differs from "0" when the first character of the line + is not on the screen. {not in Vi} + + *g^* +g^ When lines wrap ('wrap' on): To the first non-blank + character of the screen line (exclusive). Differs + from "^" when a line is wider than the screen. + When lines don't wrap ('wrap' off): To the leftmost + non-blank character of the current line that is on the + screen. Differs from "^" when the first non-blank + character of the line is not on the screen. {not in + Vi} + + *g$* *g<End>* +g$ or g<End> When lines wrap ('wrap' on): To the last character of + the screen line and [count - 1] screen lines downward + (inclusive). Differs from "$" when a line is wider + than the screen. + When lines don't wrap ('wrap' off): To the righmost + character of the current line that is visible on the + screen. Differs from "$" when the last character of + the line is not on the screen or when a count is used. + {not in Vi} + + *bar* +| To screen column [count] in the current line + (exclusive). + + *f* +f{char} To [count]'th occurrence of {char} to the right. The + cursor is placed on {char} (inclusive). + + *F* +F{char} To the [count]'th occurrence of {char} to the left. + The cursor is placed on {char} (inclusive). + + *t* +t{char} Till before [count]'th occurrence of {char} to the + right. The cursor is placed on the character left of + {char} (inclusive). + + *T* +T{char} Till after [count]'th occurrence of {char} to the + left. The cursor is placed on the character right of + {char} (inclusive). + + *;* +; Repeat latest f, t, F or T [count] times. + + *,* +, Repeat latest f, t, F or T in opposite direction + [count] times. + +These commands move the cursor to the specified column in the current line. +They stop at the first column and at the end of the line, except "$", which +may move to one of the next lines. See 'whichwrap' option to make some of the +commands move accross line boundaries. + + +6.2 Up-down motions *up_down_motions* + +k or *k* +<Up> or *<Up>* *CTRL-P* +CTRL-P [count] lines upward (linewise). + +j or *j* +<Down> or *<Down>* +CTRL-J or *CTRL-J* +<NL> or *<NL>* *CTRL-N* +CTRL-N [count] lines downward (linewise). + +gk or *gk* *g<Up>* +g<Up> [count] display lines upward (exclusive). Differs + from 'k' when lines wrap. {not in Vi} + +gj or *gj* *g<Down>* +g<Down> [count] display lines downward (exclusive). Differs + from 'j' when lines wrap. {not in Vi} + + *-* +- <minus> [count] lines upward, on the first non-blank + character (linewise). + ++ or *+* +CTRL-M or *CTRL-M* *<CR>* +<CR> [count] lines downward, on the first non-blank + character (linewise). + + *_* +_ <underscore> [count] - 1 lines downward, on the first non-blank + character (linewise). + +<C-End> or *G* *<C-End>* +G Goto line [count], default last line, on the first + non-blank character (linewise). If 'startofline' not + set, keep the same column. + +<C-Home> or *gg* *<C-Home>* +gg Goto line [count], default first line, on the first + non-blank character (linewise). If 'startofline' not + set, keep the same column. + +:[range] Set the cursor on the (last) specified line number + (cannot be used with an operator). + + *N%* +{count}% Go to {count} percentage in the file, on the first + non-blank in the line (linewise). To compute the new + line number this formula is used: {count} * + number-of-lines / 100. See also 'startofline' + option. {not in Vi} + +These commands move to the specified line. They stop when reaching the first +or the last line. The first two commands put the cursor in the same column +(if possible) as it was after the last command that changed the column, +except after the "$" command, then the cursor will be put on the last +character of the line. + + +6.3 Word motions *word_motions* + +<S-Right> or *<S-Right>* *w* +w [count] words forward (exclusive). + + *W* +W [count] WORDS forward (exclusive). + + *e* +e Forward to the end of word [count] (inclusive). + + *E* +E Forward to the end of WORD [count] (inclusive). + +<S-Left> or *<S-Left>* *b* +b [count] words backward (exclusive). + + *B* +B [count] WORDS backward (exclusive). + + *ge* +ge Backward to the end of word [count] (inclusive). + + *gE* +gE Backward to the end of WORD [count] (inclusive). + + *word* *WORD* +These commands move over words or WORDS. A word consists of a sequence of +letters, digits and underscores, or a sequence of other non-blank +characters, separated with white space (spaces, tabs, end of line). A WORD +consists of a sequence of non-blank characters, separated with white space. +An empty line is also considered to be a word and a WORD. + +Special case: "cw" and "cW" are treated like "ce" and "cE" if the cursor is +on a non-blank. This is because "cw" is interpreted as change-word, and a +word does not include the following white space. {Vi: "cw" when on a blank +followed by other blanks changes only the first blank; this is probably a +bug, because "dw" deletes all the blanks} + +Another special case: When using the "w" motion in combination with an +operator and the last word moved over is at the end of a line, the end of +that word becomes the end of the operated text, not the first word in the +next line. + +The original Vi implementation of "e" is buggy. For example, the "e" command +will stop on the first character of a line if the previous line was empty. +But when you use "2e" this does not happen. In Vim "ee" and "2e" are the +same, which is more logical. However, this causes a small incompatibility +between Vi and Vim. + + +6.4 Text object motions *object_motions* + + *(* +( [count] sentences backward (exclusive). + + *)* +) [count] sentences forward (exclusive). + + *{* +{ [count] paragraphs backward (exclusive). + + *}* +} [count] paragraphs forward (exclusive). + + *]]* +]] [count] sections forward or to the next '{' in the + first column. When used after an operator, then the + '}' in the first column. (linewise). + + *][* +][ [count] sections forward or to the next '}' in the + first column (linewise). + + *[[* +[[ [count] sections backward or to the previous '{' in + the first column (linewise). + + *[]* +[] [count] sections backward or to the previous '}' in + the first column (linewise). + +These commands move over three kinds of text objects. + + *sentence* +A sentence is defined as ending at a '.', '!' or '?' followed by either the +end of a line, or by a space. {Vi: two spaces} Any number of closing ')', +']', '"' and ''' characters my appear after the '.', '!' or '?' before the +spaces or end of line. A paragraph and section boundary is also a sentence +boundary. + + *paragraph* +A paragraph begins after each empty line, and also at each of a set of +paragraph macros, specified by the pairs of characters in the 'paragraphs' +option. The default is "IPLPPPQPP LIpplpipbp", which corresponds to the +macros ".IP", ".LP", etc. (These are nroff macros, so the dot must be in the +first column). A section boundary is also a paragraph boundary. Note that +this does not include a '{' or '}' in the first column. + + *section* +A section begins after a form-feed in the first column and at each of a set +of section macros, specified by the pairs of characters in the 'sections' +option. The default is "SHNHH HUnhsh". + +The "]" and "[" commands stop at the '{' or <}" in the first column. This is +useful to find the start or end of a function in a C program. Note that the +first character of the command determines the search direction and the +second character the type of brace found. + + +6.5 Text object selection *object_select* + + *v_a* +a select [count] words (see |word|). {not in Vi} + + *v_A* +A select [count] WORDS (see |WORD|). {not in Vi} + + *v_s* +s select [count] sentences (see |sentence|). {not in Vi} + + *v_p* +p select [count] paragraphs (see |paragraph|). {not in + Vi} + + *v_S* +S select [count] blocks, from "[count] [(" to the + matching ')' (see |[(|). {not in Vi} + + *v_P* +P select [count] blocks, from "[count] [{" to the + matching '}' (see |[{|). {not in Vi} + +These object selection commands can only be used in Visual mode and after an +operator. + +When used after an operator: +For non-block objects: + The operator applies to the object and the white space after the + object. If there is no white space after the object or when the + cursor was in the white space before the object, the white space + before the object is included. +For a block object: + The operator applies to the block excluding the surrounding braces. + If the cursor was on one of the braces (or on the indent before '{' or + '}) they are included. + +When used in Visual mode: +When start and end of the Visual area are the same (just after typing "v"): + One object is selected, the same as for using an operator. +When start and end of the Visual area are not the same: + For non-block objects the area is extended by one object or the white + space up to the next object. The direction in which this happens + depends on which side of the Visual area the cursor is. For the block + objects the block is extended one level outwards. + +For illustration, here is a list of delete commands, grouped from small to big +objects. Note that for a single character and a whole line the existing vi +movement commands are used. + "dl" delete character (alias: "x") |dl| + "da" delete word *da* + "dA" delete WORD (see |WORD|) *dA* + "dd" delete line |dd| + "ds" delete sentence *ds* + "dS" delete '(' ')' block *dS* + "dp" delete paragraph *dp* + "dP" delete '{' '}' block *dP* + +Note the difference between using a movement command and an object. The +movement command operates from here (cursor position) to where the movement +takes us. When using an object the whole object is operated upon, no matter +where on the object the cursor is. For example, compare "dw" and "da": "dw" +deletes from the cursor position to the start of the next word, "da" deletes +the word under the cursor and the space after or before it. + + +6.6 Pattern searches *pattern_searches* + + */* +/{pattern}[/]<CR> Search forward for the [count]'th occurrence of + {pattern} (exclusive). + +/{pattern}/{offset}<CR> Search forward for the [count]'th occurrence of + {pattern} and go {offset} lines up or down (see + below). (linewise). + + */<CR>* +/<CR> Search forward for the [count]'th latest used + pattern with latest used {offset}. + +//{offset}<CR> Search forward for the [count]'th latest used + pattern with new {offset}. If {offset} is empty no + offset is used. + + *?* +?{pattern}[?]<CR> Search backward for the [count]'th previous + occurrence of {pattern} (exclusive). + +?{pattern}?{offset}<CR> Search backward for the [count]'th previous + occurrence of {pattern} and go {offset} lines up or + down (see below) (linewise). + + *?<CR>* +?<CR> Search backward for the [count]'th latest used + pattern with latest used {offset}. + +??{offset}<CR> Search backward for the [count]'th latest used + pattern with new {offset}. If {offset} is empty no + offset is used. + + *n* +n Repeat the latest "/" or "?" [count] times. {Vi: no + count} + + *N* +N Repeat the latest "/" or "?" [count] times in + opposite direction. {Vi: no count} + + *star* +* Search forward for the [count]'th occurrence of the + keyword after or under the cursor (exclusive). Only + whole keywords are search for, like with the command + "/\<keyword\>". If there is no keyword after or + under the cursor, any non-blank word is used to + search for. {not in Vi} + + *#* +# Same as "*", but search backward. The English pound + sign (character 163) also works. {not in Vi} + + *gstar* +g* Like "*", but don't put "\<" and "\>" around the word. + This makes the search also find matches that are not a + whole word. {not in Vi} + + *g#* +g# Like "#", but don't put "\<" and "\>" around the word. + This makes the search also find matches that are not a + whole word. {not in Vi} + + HINT: If you want to search for something else than a + whole word, you could use these mappings, to search + for Visually highlighted text: + :vmap / y/<C-R>"<CR> + :vmap ? y?<C-R>"<CR> + (<> notation, see |<>|). + + *gd* +gd Goto local Declaration. When the cursor is on a local + variable, this command will jump to its declaration. + First a search is made for the end of the previous + function, just like "[]". If it is not found the + search stops in line 1. From this position a search is + made for the keyword under the cursor, like with "*", + but lines that look like a comment are ignored (see + 'comments' option). Note that this is not guaranteed + to work, Vim does not really check the syntax, it only + searches for a match with the keyword. If included + files also need to be searched use the commands listed + in |include_search|. {not in Vi} + + *gD* +gD Goto global Declaration. When the cursor is on a + global variable that is defined in the file, this + command will jump to its declaration. This works just + like "gd", except that the search for the keyword + always starts in line 1. {not in Vi} + + *CTRL-C* +CTRL-C Interrupt current (search) command. + +While typing the search pattern the current match will be shown if the +'incsearch' option is on. + +These commands search for the specified pattern. With "/" and "?" an +additional offset may be given. There are two types of offsets: line offsets +and character offsets. {the character offsets are not in Vi} + + *search_offset* +The offset gives the cursor position relative to the found match: + [num] [num] lines downwards, in column 1 + +[num] [num] lines downwards, in column 1 + -[num] [num] lines upwards, in column 1 + e[+num] [num] characters to the right of the end of the match + e[-num] [num] characters to the left of the end of the match + s[+num] [num] characters to the right of the start of the match + s[-num] [num] characters to the left of the start of the match + b[+num] [num] characters to the right of the start (begin) of the match + b[-num] [num] characters to the left of the start (begin) of the match + +If a '-' or '+' is given but [num] is omitted, a count of one will be used. +When including an offset with 'e', the search becomes inclusive (the +character the cursor lands on is included in operations). + +Examples: + +pattern cursor position +/test/+1 one line below "test", in column 1 +/test/e on the last t of "test" +/test/s+2 on the 's' of "test" +/test/b-3 three characters before "test" + +If one of these commands is used after an operator, the characters between +the cursor position before and after the search is affected. However, if a +line offset is given, the whole lines between the two cursor positions are +affected. + + *//;* +A very special offset is ';' followed by another search command. For example: + + /test 1/;/test + /test.*/+1;?ing? + +The first one first finds the next occurence of "test 1", and then the first +occurence of "test" after that. + +This is like executing two search commands after each other, except that: +- It can be used as a single motion command after an operator. +- The direction for a following "n" or "N" command comes from the first + search command. +- When an error occurs the cursor is not moved at all. + +The last used <pattern> and <offset> are remembered. They can be used to +repeat the search, possibly in another direction or with another count. Note +that two patterns are remembered: one for 'normal' search commands and one +for the substitute command ":s". Each time an empty <pattern> is given, the +previously used <pattern> is used. + +In Vi the ":tag" command sets the last search pattern when the tag is searched +for. In Vim this is not done, the previous search pattern is still remembered, +unless the 't' flag is present in 'cpoptions'. The search pattern is always +put in the search history. + +If the 'wrapscan' option is on (which is the default), searches wrap around +the end of the buffer. If 'wrapscan' is not set, the backward search stops +at the beginning and the forward search stops at the end of the buffer. If +'wrapscan' is set and the pattern was not found the error message "pattern +not found" is given, and the cursor will not be moved. If 'wrapscan' is not +set the message becomes "search hit BOTTOM without match" when searching +forward, or "search hit TOP without match" when searching backward. If +wrapscan is set and the search wraps around the end of the file the message +"search hit TOP, continuing at BOTTOM" or "search hit BOTTOM, continuing at +TOP" is given when searching backwards or forwards respectively. This can be +switched off by setting the 's' flag in the 'shortmess' option. The highlight +method 'w' is used for this message (default: standout). + +The "*" and "#" commands search for the keyword currently under the cursor. +If there is no keyword under the cursor, the first one to the right is used. +This keyword may only contain letters and characters in 'iskeyword'. Note +that if you type with ten fingers, the characters are easy to remember: the +"#" is under your left hand middle finger (search to the left and up) and +the "*" is under your right hand middle finger (search to the right and +down). If there is no keyword under or after the cursor, a search is done +for any word under or after the cursor. Blanks (<Tab>s and/or <Space>s) are +then recognized as delimiters for the word. + + +The definition of a pattern: *search_pattern* + +Patterns may contain special characters, depending on the setting of the +'magic' option. + +1. A pattern is one or more branches, separated by "\|". It matches anything + that matches one of the branches. Example: "foo\|bar" matches "foo" and + "bar". + +2. A branch is one or more pieces, concatenated. It matches a match for the + first, followed by a match for the second, etc. Example: "foo[0-9]bar", + first match "foo", then a digit and then "bar". + +3. A piece is an atom, possibly followed by: + 'magic' 'nomagic' + option option + * \* matches 0 or more of the preceding atom + \+ \+ matches 1 or more of the preceding atom {not + in Vi} + \= \= matches 0 or 1 of the preceding atom {not in + Vi} + Examples: + .* .\* matches anything, also empty string + ^.\+$ ^.\+$ matches any non-empty line + foo\= foo\= matches "fo" and "foo" + + +4. An atom can be: + - One of these five: + magic nomagic + ^ ^ at beginning of pattern, matches start of + line + $ $ at end of pattern or in front of "\|", + matches end of line + . \. matches any single character + \< \< matches the beginning of a word + \> \> matches the end of a word + \i \i matches any identifier character (see + 'isident' option) {not in Vi} + \I \I like "\i", but excluding digits {not in Vi} + \k \k matches any keyword character (see + 'iskeyword' option) {not in Vi} + \K \K like "\k", but excluding digits {not in Vi} + \f \f matches any file name character (see + 'isfname' option) {not in Vi} + \F \F like "\f", but excluding digits {not in Vi} + \p \p matches any printable character (see + 'isprint' option) {not in Vi} + \P \P like "\p", but excluding digits {not in Vi} + \e \e <Esc> + \t \t <Tab> + \r \r <CR> + \b \b <BS> + ~ \~ matches the last given substitute pattern + \(\) \(\) A pattern enclosed by escaped parentheses + (e.g., "\(^a\)") matches that pattern + x x A single character, with no special meaning, + matches itself + \x \x A backslash followed by a single character, + with no special meaning, matches the single + character + [] \[] A range. This is a sequence of characters + enclosed in "[]" or "\[]". It matches any + single character from the sequence. If the + sequence begins with "^", it matches any + single character NOT in the sequence. If two + characters in the sequence are separated by + '-', this is shorthand for the full list of + ASCII characters between them. E.g., "[0-9]" + matches any decimal digit. To include a + literal "]" in the sequence, make it the + first character (following a possible "^"). + E.g., "[]xyz]" or "[^]xyz]". To include a + literal '-', make it the first or last + character. + +If the 'ignorecase' option is on, the case of letters is ignored. + +It is impossible to have a pattern that contains a line break. + +Examples: +^beep( Probably the start of the C function "beep". + +[a-zA-Z]$ Any alphabetic character at the end of a line. + +\<\I\i or +\(^\|[^a-zA-Z0-9_]\)[a-zA-Z_]\+[a-zA-Z0-9_]* + A C identifier (will stop in front of it). + +\(\.$\|\. \) A period followed by end-of-line or a space. + Note that "\(\. \|\.$\)" does not do the same, + because '$' is not end-of-line in front of '\)'. + This was done to remain Vi-compatible. + +[.!?][])"']*\($\|[ ]\) A search pattern that finds the end of a sentence, + with almost the same definition as the ")" command. + +Technical detail: +<Nul> characters in the file are stored as <NL> in memory. In the display +they are shown as "^@". The translation is done when reading and writing +files. To match a <Nul> with a search pattern you can just enter CTRL-@ or +"CTRL-V 000". This is probably just what you expect. Internally the +character is replaced with a <NL> in the search pattern. What is unusual is +that typing CTRL-V CTRL-J also inserts a <NL>, thus also searches for a +<Nul> in the file. {Vi cannot handle <Nul> characters in the file at all} + + +6.7 Various motions *various_motions* + + *m* +m<a-zA-Z> Set mark <a-zA-Z> at cursor position (does not move + the cursor, this is not a motion command). + + *:ma* *:mark* +:[range]ma[rk] <a-zA-Z> Set mark <a-zA-Z> at last line number in [range], + column 0. Default is cursor line. + + *:k* +:[range]k<a-zA-Z> Same as :mark, but the space before the mark name can + be omitted. + + *'* *'a* +'<a-z> To the first non-blank character on the line with + mark <a-z> (linewise). + *'A* *'0* +'<A-Z0-9> To the first non-blank character on the line with + mark <A-Z0-9> in the correct file (linewise when in + same file, not a motion command when in other file). + {not in Vi} + + *`* *`a* +`<a-z> To the mark <a-z> (exclusive). + *`A* *`0* +`<A-Z0-9> To the mark <A-Z0-9> in the correct file (exclusive + when in same file, not a motion command when in + other file). {not in Vi} + + *:marks* +:marks List all the current marks (not a motion command). + {not in Vi} + +:marks {arg} List the marks that are mentioned in {arg} (not a + motion command). For example: + :marks aB + to list marks 'a' and 'B'. {not in Vi} + +A mark is not visible in any way. It is just a position in the file that is +remembered. Do not confuse marks with named registers, they are totally +unrelated. + +'a - 'z lowercase marks, valid within one file +'A - 'Z uppercase marks, also called file marks, valid between files +'0 - '9 numbered marks, set from .viminfo file + +Lowercase marks 'a to 'z are remembered as long as the file remains in the +buffer list. If you remove the file from the buffer list, change a character +in a line or delete a line that contains a mark, that mark is erased. +Lowercase marks can be used in combination with operators. For example: "d't" +deletes the lines from the cursor position to mark 't'. Hint: Use mark 't' for +Top, 'b' for Bottom, etc.. Lowercase marks are restored when using undo and +redo. + +Uppercase marks 'A to 'Z include the file name. {Vi: no uppercase marks} You +can use them to jump from file to file. You can only use an uppercase mark +with an operator if the mark is in the current file. The line number of the +mark remains correct, even if you insert/delete lines or edit another file for +a moment. When the 'viminfo' option is not empty, uppercase marks are kept in +the .viminfo file. See |viminfo_file_marks|. + +Numbered marks '0 to '9 are quite different. They can not be set directly. +They are only present when using a viminfo file |viminfo_file|. Basically '0 +is the location of the cursor when you last exited Vim, '1 the last but one +time, etc. See |viminfo_file_marks|. + + *'[* +'[ To the first non-blank character on the first line + of the previously operated, inserted or putted text. + {not in Vi} + + *`[* +`[ To the first character of the previously operated, + inserted or putted text. {not in Vi} + + *']* +'] To the first non-blank character on the last line of + the previously operated, inserted or putted text. + {not in Vi} + + *`]* +`] To the last character of the previously operated, + inserted or putted text. {not in Vi} + +After executing an operator the Cursor is put at the beginning of the text +that was operated upon. After a put command ("p" or "P") the cursor is +sometimes placed at the first inserted line and sometimes on the last inserted +character. The four commands above put the cursor at either end. Example: +After yanking 10 lines you want to go to the last one of them: "10Y']". After +inserting several lines with the "p" command you want to jump to the lowest +inserted line: "p']". This also works for text that has been inserted. + +Note: After deleting text, the start and end positions are the same, except +when using blockwise Visual mode. These commands do not work when no +operator or put command has been used yet in the current file. + + *'<* +'< To the first non-blank character on the first line + of the last selected Visual area. {not in Vi}. + + *`<* +`< To the first character of the last selected Visual + area. {not in Vi}. + + *'>* +'> To the first non-blank character on the last line + of the last selected Visual area. {not in Vi}. + + *`>* +`> To the last character of the last selected Visual + area. {not in Vi}. + + *''* +'' To the first non-blank character of the line where + the cursor was before the latest jump (linewise). + + *``* +`` To the position before latest jump (exclusive). + + *'"* +'" To the first non-blank character of the line where + the cursor was the last time the current buffer was + exited (linewise). {not in Vi}. + + *`"* +`" To the cursor position when last exiting the current + buffer (exclusive). {not in Vi}. + +A "jump" is one of the following commands: "'", "`", "G", "/", "?", "n", +"N", "%", "(", ")", "[[", "]]", "{", "}", ":s", ":tag", "L", "M", "H" and +the commands that start editing a new file. If you make the cursor "jump" +with one of these commands, the position of the cursor before the jump is +remembered. You can return to that position with the "''" and "``" command, +unless the line containing that position was changed or deleted. + + *CTRL-O* +CTRL-O Go to [count] Older cursor position in jump list + (not a motion command). {not in Vi} + +<Tab> or *CTRL-I* *<Tab>* +CTRL-I Go to [count] newer cursor position in jump list + (not a motion command). {not in Vi} + + *:ju* *:jumps* +:ju[mps] Print the jump list (not a motion command). {not in + Vi} + + *jumplist* +Jumps are remembered in a jump list. With the CTRL-O and CTRL-I command you +can go to cursor positions before older jumps, and back again. Thus you can +move up and down the list. + +For example, after three jump commands you have this jump list: + + jump line file + 1 1 -current- + 2 70 -current- + 3 1154 -current- +> + +You are currently in line 1167. If you then use the CTRL-O command, the +cursor is put in line 1154. This results in: + + jump line file + 1 1 -current- + 2 70 -current- +> 3 1154 -current- + 4 1167 -current- + +The pointer will be set at the last used jump position. The next CTRL-O +command will use the entry above it, the next CTRL-I command will use the +entry below it. If the pointer is below the last entry, this indicates that +you did not use a CTRL-I or CTRL-O before. In this case the CTRL-O command +will cause the cursor position to be added to the jump list, so you can get +back to the position before the CTRL-O. In this case this is line 1167. + +With more CTRL-O commands you will go to lines 70 and 1. If you use CTRL-I +you can go back to 1154 and 1167 again. + +If you use a jump command, the current line number is inserted at the end of +the jump list. If the same line was already in the jump list, it is removed. +The result is that when repeating CTRL-O you will get back to old positions +only once. + +After the CTRL-O command that got you into line 1154 you could give another +jump command (e.g., "G"). The jump list would then become: + + jump line file + 1 1 -current- + 2 70 -current- + 3 1167 -current- + 4 1154 -current- +> + +The line numbers will be adjusted for deleted and inserted lines. This fails +if you stop editing a file without writing, like with ":n!". + + *%* +% Find the next item in this line after or under the + cursor and jump to its match (inclusive). Items can + be: + ([{}]) parenthesis or (curly/square) brackets + /* */ start or end of C-style comment + #if, #ifdef, #else, #elif, #endif + C preprocessor conditionals + Parens and braces preceded with a backslash are + ignored. When the '%' character is not present in + 'cpoptions', parens and braces inside quotes are + ignored, unless the number of parens/braces in a line + is uneven and this line and the previous one does not + end in a backslash. No count is allowed ({count}% + jumps to a line {count} percentage down the file). + Using '%' on #if/#else/#endif makes the movement + linewise. + + *[(* +[( go to [count] previous unmatched '('. {not in Vi} + + *[{* +[{ go to [count] previous unmatched '{'. {not in Vi} + + *])* +]) go to [count] next unmatched ')'. {not in Vi} + + *]}* +]} go to [count] next unmatched '}'. {not in Vi} + +The above four commands can be used to go to the start or end of the current +code block. It is like doing "%" on the '(', ')', '{' or '}' at the other +end of the code block, but you can do this from anywhere in the code block. +Very useful for C programs. Example: When standing on "case x:", "[{" will +bring you back to the switch statement. + + *[#* +[# go to [count] previous unmatched "#if" or "#else". + {not in Vi} + + *]#* +]# go to [count] next unmatched "#else" or "#endif". {not + in Vi} + +These two commands work in C programs that contain #if/#else/#endif +constructs. It brings you to the start or end of the #if/#else/#endif where +the current line is included. You can then use "%" to go to the matching line. + + *[star* *[/* +[* or [/ go to [count] previous start of a C comment "/*". {not + in Vi} + + *]star* *]/* +]* or ]/ go to [count] next end of a C comment "*/". {not + in Vi} + + + *H* +H To line [count] from top (Home) of screen (default: + first line on the screen) on the first non-blank + character (linewise). See also 'startofline' option. + Cursor is adjusted for 'scrolloff' option. + + *M* +M To Middle line of screen, on the first non-blank + character (linewise). See also 'startofline' option. + + *L* +L To line [count] from bottom of screen (default: Last + line on the screen) on the first non-blank character + (linewise). See also 'startofline' option. + Cursor is adjusted for 'scrolloff' option. + +<LeftMouse> Moves to the position on the screen where the mouse + click is (inclusive). See also |<LeftMouse>|. If the + position is in a status line, that window is made the + active window and the cursor is not moved. {not in Vi} + + +7. Scrolling *scrolling* +============ + +Move edit window (the part of the buffer that you see) downwards (this means +that more lines downwards in the text buffer are seen): + + *CTRL-E* +CTRL-E Scroll window [count] lines downwards in the buffer. + Mnemonic: Extra lines. + + *CTRL-D* +CTRL-D Scroll window Downwards in the buffer. The number of + lines comes from the 'scroll' option (default: half a + screen). If [count] given, first set 'scroll' option + to [count]. The cursor is moved the same number of + lines down in the file (if possible; when lines wrap + and when hitting the end of the file there may be a + difference). When the cursor is on the last line of + the buffer nothing happens and a beep is produced. + See also 'startofline' option. + {difference from vi: Vim scrolls 'scroll' screen + lines, instead of file lines; makes a difference when + lines wrap} + +<S-Down> or *<S-Down>* +<PageDown> or *<PageDown>* *CTRL-F* +CTRL-F Scroll window [count] pages Forwards (downwards) in + the buffer. See also 'startofline' option. + +Move edit window (the part of the buffer that you see) upwards (this means +that more lines upwards in the text buffer are seen): + + *CTRL-Y* +CTRL-Y Scroll window [count] lines upwards in the buffer. + + *CTRL-U* +CTRL-U Scroll window Upwards in the buffer. The number of + lines comes from the 'scroll' option (default: half a + screen). If [count] given, first set the 'scroll' + option to [count]. The cursor is moved the same + number of lines up in the file (if possible; when + lines wrap and when hitting the end of the file there + may be a difference). When the cursor is on the first + line of the buffer nothing happens and a beep is + produced. See also 'startofline' option. + {difference from vi: Vim scrolls 'scroll' screen + lines, instead of file lines; makes a difference when + lines wrap} + +<S-Up> or *<S-Up>* +<PageUp> or *<PageUp>* *CTRL-B* +CTRL-B Scroll window [count] pages Backwards (upwards) in the + buffer. See also 'startofline' option. + +Window repositioning: + + *z* *z<CR>* +z<CR> Redraw, line [count] at top of window (default + cursor line). Put cursor at first non-blank in the + line. + + *zt* +zt Like "z<CR>", but leave the cursor in the same + column. {not in Vi} + + *zN<CR>* +z{height}<CR> Redraw, make window {height} lines tall. This is + useful to make the number of lines small when screen + updating is very slow. Cannot make the height more + than the physical screen height. + + *z.* +z. Redraw, line [count] at center of window (default + cursor line). Put cursor at first non-blank in the + line. + + *zz* +zz Like "z.", but leave the cursor in the same column. + Careful: If caps-lock is on, this commands becomes + "ZZ": write buffer and exit! {not in Vi} + + *z-* +z- Redraw, line [count] at bottom of window (default + cursor line). Put cursor at first non-blank in the + line. + + *zb* +zb Like "z-", but leave the cursor in the same column. + {not in Vi} + +These commands move the contents of the window. If the cursor position is +moved off of the window, the cursor is moved onto the window (with +'scrolloff' screen lines around it). A page is the number of lines in the +window minus two. The mnemonics for these commands may be a bit confusing. +Remember that the commands refer to moving the window upwards or downwards +in the buffer. When the window moves upwards in the buffer, the text in the +window moves downwards on your screen. + +z<Right> or *zl* *z<Right>* +zl Scroll the screen [count] characters to the left. + This only works when 'wrap' is off. {not in Vi} + +z<Left> or *zh* *z<Left>* +zh Scroll the screen [count] characters to the right. + This only works when 'wrap' is off. {not in Vi} + +For these two commands the cursor follows the screen. If the character that +the cursor is on is moved off the screen, the cursor is moved to the closest +character that is on the screen. The value of 'sidescroll' is not used. + + *zs* +zs Scroll the screen horizontally to position the cursor + at the start (left side) of the screen. This only + works when 'wrap' is off. {not in Vi} + + *ze* +ze Scroll the screen horizontally to position the cursor + at the end (right side) of the screen. This only + works when 'wrap' is off. {not in Vi} + +For these two commands the cursor is not moved in the text, only the text +scrolls on the screen. + + +8. Tags and special searches *tags_and_searches* +============================ + +8.1 Tags *tag_commands* + + *:ta* *:tag* +:ta[g][!] {ident} Jump to the definition of {ident}, using the + information in the tags file. Put {ident} in the tag + stack. See below for [!]. + +g<LeftMouse> *g<LeftMouse>* +<C-LeftMouse> *<C-LeftMouse>* *CTRL-]* +CTRL-] ":ta" to the keyword under or after cursor. Put the + keyword in the tag stack. {Vi: identifier after the + cursor} + + *v_CTRL-]* +{Visual}CTRL-] ":ta" to the text that is highlighted. {not in Vi} + +g<RightMouse> *g<RightMouse>* +<C-RightMouse> *<C-RightMouse>* *CTRL-T* +CTRL-T Jump to [count] older entry in the tag stack + (default 1). {not in Vi} + + *:po* *:pop* +:[count]po[p][!] Jump to [count] older entry in tag stack (default 1). + See below for [!]. {not in Vi} + +:[count]ta[g][!] Jump to [count] newer entry in tag stack (default 1). + See below for [!]. {not in Vi} + + *:tags* +:tags Show the contents of the tag stack. The active + entry is marked with a '>'. {not in Vi} + +A tag is an identifier that appears in the "tags" file. It is a sort of label +that can be jumped to. For example: In C programs each function name can be +used as a tag. + +With the ":tag" command the cursor will be positioned on the tag. With the +CTRL-] command, the keyword on which the cursor is standing is used as the +tag. If the cursor is not on a keyword, the first keyword to the right of the +cursor is used. + + *tag_priority* +When there are multiple matches for a tag, this priority is used: +1. The first matching static tag with a full matching tag for the current + file. +2. The first matching global tag with a full matching tag. +3. The first matching static tag with a full matching tag for another file. +4. The first matching static tag with an ignore-case matching tag for the + current file. +5. The first matching global tag with an ignore-case matching tag. +6. The first matching static tag with an ignore-case matching tag for another + file. + + *static_tag* +A static tag is a tag that is defined for a specific file. In a C program this +could be a static function. + +In Vi jumping to a tag sets the current search pattern. This means that +the "n" command after jumping to a tag does not search for the same pattern +that it did before jumping to the tag. Vim does not do this as we consider it +to be a bug. You can still find the tag search pattern in the search history. +If you really want the old Vi behaviour, set the 't' flag in 'cpoptions'. + +If the tag is in the current file this will always work. Otherwise the +performed actions depend on whether the current file was changed, whether a ! +is added to the command and on the 'autowrite' option: + + tag in file autowrite +current file changed ! option action +----------------------------------------------------------------------------- + yes x x x goto tag + no no x x read other file, goto tag + no yes yes x abandon current file, read other file, goto + tag + no yes no on write current file, read other file, goto + tag + no yes no off fail +----------------------------------------------------------------------------- + +- If the tag is in the current file, the command will always work. +- If the tag is in another file and the current file was not changed, the + other file will be made the current file and read into the buffer. +- If the tag is in another file, the current file was changed and a ! is + added to the command, the changes to the current file are lost, the other + file will be made the current file and read into the buffer. +- If the tag is in another file, the current file was changed and the + 'autowrite' option is on, the current file will be written, the other + file will be made the current file and read into the buffer. +- If the tag is in another file, the current file was changed and the + 'autowrite' option is off, the command will fail. If you want to save + the changes, use the ":w" command and then use ":tag" without an argument. + This works because the tag is put on the stack anyway. If you want to lose + the changes you can use the ":tag!" command. + +The ":tag" command works very well for C programs. If you see a call to a +function and wonder what that function does, position the cursor inside of +the function name and hit CTRL-]. This will bring you to the function +definition. An easy way back is with the CTRL-T command. Also read about the +tag stack below. + +A tags file can be created with the external command 'ctags'. It will +contain a tag for each function. Some versions of 'ctags' will also make a +tag for each "#defined" macro. + +The lines in the tags file should have this format: + + {tag}{separator}{filename}{separator}{command} + +{tag} the identifier +{separator} one or more <Tab> or space characters +{filename} the file that contains the definition of {tag} +{command} the Ex command that positions the cursor on the tag. + +The identifier normally is the name of a function, but it can be any +identifier. There is one special form for local (static) functions: +{filename}:{identifier}. Some ctags programs make use of this to separate +local (static) functions from global functions. +(Detail: Vim compares only the last part of the filename and ignores any +path before it). + + *tag_search* +The command can be any Ex command, but normally it is a search command like + "/^main(argc, argv)" +If it is a search command, and the search fails, another try is done ignoring +case. If that fails too, a search is done for: + "^main[ \t]*(" +(the tag with '^' prepended and "[ \t]*(" appended). When using function +names, this will find the function name when it is in column 0. This will +help when the arguments to the function have changed since the tags file was +made. If this search also fails another search is done with: + "^[#a-zA-Z_].*main[ \t]*(" +This means: A line starting with '#' or an identifier and containing the tag +followed by white space and a '('. This will find macro names and function +names with a type prepended. {the extra searches are not in Vi}. + +In Vi the ":tag" command sets the last search pattern when the tag is searched +for. In Vim this is not done, the previous search pattern is still remembered, +unless the 't' flag is present in 'cpoptions'. The search pattern is always +put in the search history. + + *emacs_tags* +Emacs style tag files are supported if Vim was compiled with EMACS_TAGS +defined. Check the output of ":version", if it contains "+emacs_tags" then it +was. Sorry, there is no explanation about Emacs tag files here, it is only +supported for backwards compatibility :-). + + *tags_option* +The 'tags' option is a list of file names. Each of these files is searched +for the tag. This can be used to use a different tags file than the default +file "tags". It can also be used to access a common tags file. + +The next file in the list is not used when: +- A matching static tag for the current buffer has been found. +- A matching global tag has been found. +This also depends on the 'ignorecase' option. If it is off, and the tags file +only has a match without matching case, the next tags file is searched for a +match with matching case. If no tag with matching case is found, the first +match without matching case is used. If 'ignorecase' is on, and a matching +global tag with or without matching case is found, this one is used, no +further tags files are searched. + +When a tag file name starts with "./", the '.' is replaced with the path of +the current file. This makes it possible to use a tags file in the directory +where the current file is (no matter what the current directory is). The idea +of using "./" is that you can define which tag file is searched first: In the +current directory ("tags,./tags") or in the directory of the current file +("./tags,tags"). + +For example: + + :set tags=./tags,tags,/home/user/commontags + +In this example the tag will first be searched for in the file "tags" in the +directory where the current file is. Next the "tags" file in the current +directory. If it is not found there, then the file "/home/user/commontags" +will be searched for the tag. + +Instead of the comma a space may be used. Then a backslash is required for +the space to be included in the string option: + + :set tags=tags\ /home/user/commontags + +To include a space in a file name use three backslashes. To include a comma in +a file name use two backslashes. For example, use: + + :set tags=tag\\\ file,/home/user/common\\,tags + +for the files "tag file" and "/home/user/common,tags". The 'tags' option will +have the value "tag\ file,/home/user/common\,tags". + +If the 'tagrelative' option is on (which is the default) and using a tag file +in another directory, file names in that tag file are relative to the +directory where the tag file is. + + + *tagstack* +The tags that you use are remembered in the tag stack. You can print this +stack with the ":tags" command. The result looks like this: + + # TO tag FROM line in file + 1 main 1 harddisk2:text/vim/test +> 2 FuncA 58 -current- + 3 FuncC 357 harddisk2:text/vim/src/amiga.c + +This list shows the tags that you jumped to and the cursor position before that +jump. The older tags are at the top, the newer at the bottom. + +The '>' points to the active entry. This is the tag that will be used by the +next ":tag" command. The CTRL-T and ":pop" command will use the position +above the active entry. + +The line number and file name are remembered to be able to get back to where +you were before the tag command. The line number will be correct, also when +deleting/inserting lines, unless this was done by another program (e.g. +another instance of Vim). + +You can jump to previously used tags with several commands. Some examples: + + ":pop" or CTRL-T to position before previous tag + {count}CTRL-T to position before {count} older tag + ":tag" to newer tag + ":0tag" to last used tag + +The most obvious way to use this is while browsing through the call graph of +a program. Consider the following call graph: + + main ---> FuncA ---> FuncC + ---> FuncB + +(Explanation: main calls FuncA and FuncB; FuncA calls FuncC). +You can get from main to FuncA by using CTRL-] on the call to FuncA. Then +you can CTRL-] to get to FuncC. If you now want to go back to main you can +use CTRL-T twice. Then you can CTRL-] to FuncB. + +If you issue a ":ta {ident}" or CTRL-] command, this tag is inserted at the +current position in the stack. If the stack was full (it can hold up to 20 +entries), the oldest entry is deleted and the older entries shift one +position up (their index number is decremented by one). If the last used +entry was not at the bottom, the entries below the last used one are +deleted. This means that an old branch in the call graph is lost. After the +commands explained above the tag stack will look like this: + + # TO tag FROM line in file + 1 main 1 harddisk2:text/vim/test + 2 FuncB 59 harddisk2:text/vim/src/main.c +> + + +8.2 Include file searches *include_search* + +These commands look for a string in the current file and in all encountered +included files (recursively). This can be used to find the definition of a +variable, function or macro. If you only want to search in the current +buffer, use the commands listed at |pattern_searches|. + +When a line is encountered that includes another file, that file is searched +before continuing in the current buffer. Files included by included files are +also searched. When an include file could not be found it is silently +ignored. Use the ":checkpath" command to discover which files could not be +found, possibly your 'path' option is not set up correctly. Note: the +included file is searched, not a buffer that may be editing that file. Only +for the current file the lines in the buffer are used. + +The string can be any keyword or a defined macro. For the keyword any match +will be found. For defined macros only lines that match with the 'define' +option will be found. The default is "\^#[ \t]*define", which is for C +programs. Also, when a match is found for a defined macro, the displaying of +lines continues with the next line when a line ends in a backslash. + +The commands that start with "[" start searching from the start of the current +file. The commands that start with "]" start at the current cursor position. + +The 'include' option is used to define a line that includes another file. The +default is "\^#[ \t]*include", which is for C programs. Note: Vim does not +recognize C syntax, if the 'include' option matches a line inside +"#ifdef/#endif" or inside a comment, it is searched anyway. The 'isfname' +option is used to recognize the file name that comes after the matched +pattern. + +The 'path' option is used to find the directory for the include files that +do not have an absolute path. + +The 'comments' option is used for the commands that display a single line or +jump to a line. It defines patterns that may start a comment. Those lines +are ignored for the search, unless [!] is used. One exception: When the line +matches the pattern "^# *define" it is not considered to be a comment. + + *[i* +[i Display the first line that contains the keyword + under the cursor. The search starts at the beginning + of the file. Lines that look like a comment are + ignored (see 'comments' option). If a count is given, + the count'th matching line is displayed. {not in Vi} + + *]i* +]i like "[i", but start at the current cursor position. + {not in Vi} + + *:is* *:isearch* +:[range]is[earch][!] [count] [/]pattern[/] + Like "[i" and "]i", but search in [range] lines + (default: whole file). Without [!] lines that are + recognized as comments are skipped. Without [/] only + whole words are matched, using the pattern + "\<pattern\>". {not in Vi} + + *[I* +[I Display all lines that contain the keyword under the + cursor. File names and line numbers are displayed + for the found lines. The search starts at the + beginning of the file. {not in Vi} + + *]I* +]I like "[I", but start at the current cursor position. + {not in Vi} + + *:il* *:ilist* +:[range]il[ist][!] [/]pattern[/] + Like "[I" and "]I", but search in [range] lines + (default: whole file). Without [!] lines that are + recognized as comments are skipped. Without [/] only + whole words are matched, using the pattern + "\<pattern\>". {not in Vi} + + *[_CTRL-I* +[ CTRL-I Jump to the first line that contains the keyword + under the cursor. The search starts at the beginning + of the file. Lines that look like a comment are + ignored (see 'comments' option). If a count is given, + the count'th matching line is jumped to. {not in Vi} + + *]_CTRL-I* +] CTRL-I like "[ CTRL-I", but start at the current cursor + position. {not in Vi} + + *:ij* *:ijump* +:[range]ij[ump][!] [count] [/]pattern[/] + Like "[ CTRL-I" and "] CTRL-I", but search in + [range] lines (default: whole file). Without [!] + lines that are recognized as comments are skipped. + Without [/] only whole words are matched, using the + pattern "\<pattern\>". {not in Vi} + +CTRL-W CTRL-I *CTRL-W_CTRL-I* *CTRL-W_i* +CTRL-W i Open a new window, with the cursor on the first line + that contains the keyword under the cursor. The + search starts at the beginning of the file. Lines + that look like a comment line are ignored (see + 'comments' option). If a count is given, the count'th + matching line is jumped to. {not in Vi} + + *:isp* *:isplit* +:[range]isp[lit][!] [count] [/]pattern[/] + Like "CTRL-W i" and "CTRL-W i", but search in + [range] lines (default: whole file). Without [!] + lines that are recognized as comments are skipped. + Without [/] only whole words are matched, using the + pattern "\<pattern\>". {not in Vi} + + *[d* +[d Display the first macro definition that contains the + macro under the cursor. The search starts from the + beginning of the file. If a count is given, the + count'th matching line is displayed. {not in Vi} + + *]d* +]d like "[d", but start at the current cursor position. + {not in Vi} + + *:ds* *:dsearch* +:[range]ds[earch][!] [count] [/]pattern[/] + Like "[d" and "]d", but search in [range] lines + (default: whole file). Without [!] lines that are + recognized as comments are skipped. Without [/] only + whole words are matched, using the pattern + "\<pattern\>". {not in Vi} + + *[D* +[D Display all macro definitions that contain the macro + under the cursor. File names and line numbers are + displayed for the found lines. The search starts + from the beginning of the file. {not in Vi} + + *]D* +]D like "[D", but start at the current cursor position. + {not in Vi} + + *:dl* *:dlist* +:[range]dl[ist][!] [/]pattern[/] + Like "[D" and "]D", but search in [range] lines + (default: whole file). Without [!] lines that are + recognized as comments are skipped. Without [/] only + whole words are matched, using the pattern + "\<pattern\>". {not in Vi} + + *[_CTRL-D* +[ CTRL-D Jump to the first macro definition that contains the + keyword under the cursor. The search starts from + the beginning of the file. If a count is given, the + count'th matching line is jumped to. {not in Vi} + + *]_CTRL-D* +] CTRL-D like "[ CTRL-D", but start at the current cursor + position. {not in Vi} + + *:dj* *:djump* +:[range]dj[ump][!] [count] [/]pattern[/] + Like "[ CTRL-D" and "] CTRL-D", but search in + [range] lines (default: whole file). Without [!] + lines that are recognized as comments are skipped. + Without [/] only whole words are matched, using the + pattern "\<pattern\>". {not in Vi} + +CTRL-W CTRL-D *CTRL-W_CTRL-D* *CTRL-W_d* +CTRL-W d Open a new window, with the cursor on the first + macro definition line that contains the keyword + under the cursor. The search starts from the + beginning of the file. If a count is given, the + count'th matching line is jumped to. {not in Vi} + + *:dsp* *:dsplit* +:[range]dsp[lit][!] [count] [/]pattern[/] + Like "CTRL-W d", but search in [range] lines + (default: whole file). Without [!] lines that are + recognized as comments are skipped. Without [/] only + whole words are matched, using the pattern + "\<pattern\>". {not in Vi} + + *:che* *:checkpath* +:che[ckpath] List all the included files that could not be found. + {not in Vi} + +:che[ckpath]! List all the included files. {not in Vi} + + +9. Inserting text *inserting* +================= + +The following commands can be used to insert new text into the buffer. They +can all be undone. The non-Ex commands can be repeated with the "." command. + + *a* +a Append text after the cursor [count] times. + + *A* +A Append text at the end of the line [count] times. + +<Insert> or *i* *insert* *<Insert>* +i Insert text before the cursor [count] times. + + *I* +I Insert text before the first CHAR on the line + [count] times. + + *gI* +gI Insert text in column 1 [count] times. {not in Vi} + + *o* +o Begin a new line below the cursor and insert text, + repeat [count] times. {Vi: blank [count] screen + lines} + + *O* +O Begin a new line above the cursor and insert text, + repeat [count] times. {Vi: blank [count] screen + lines} + +These commands are used to start inserting text. They can be undone and +repeated. You can end Insert mode with <Esc>. See the section "Insert and +Replace mode" |mode_ins_repl| for the other special characters in Insert +mode. The effect of [count] takes place after Insert mode is exited. + +When 'autoindent' is on, the indent for a new line is obtained from the +previous line. When 'smartindent' or 'cindent' is on, the indent for a line +is automatically adjusted for C programs. + +'textwidth' can be set to the maximum width for a line. When a line becomes +too long when appending characters a line break is automatically inserted. + + *:r* *:read* +:r[ead] [name] Insert the file [name] (default: current file) below + the cursor. + +:{range}r[ead] [name] Insert the file [name] (default: current file) below + the specified line. + + *:r!* *:read!* +:r[ead] !{cmd} Execute {cmd} and insert its standard output below + the cursor. A temporary file is used to store the + output of the command which is then read into the + buffer. 'shellredir' is used to save the output of + the command, which can be set to include stderr or + not. {cmd} is executed like with ":!{cmd}", any '!' + is replaced with the previous command |:!|. + +These commands insert the contents of a file, or the output of a command, +into the buffer. They can be undone. They cannot be repeated with the "." +command. They work on a line basis, insertion starts below the line in which +the cursor is, or below the specified line. To insert text above the first +line use the command ":0r {name}". + + *textmode_read* +The <NL> character is recognized as end-of-line marker. If the 'textmode' +option is on, a <CR> in front of an <NL> is ignored and a CTRL-Z at the end +of the file is ignored. The 'textmode' option is default on for MS-DOS, Win32 +and OS/2. + +If the 'textauto' option is on Vim tries to recognize the type of end-of-line +marker (see |textmode_io|). However, the 'textmode' option will not be +changed. Only while reading the file the text mode is used or not. + +On non-MS-DOS, Win32, and OS/2 systems the message "[textmode]" is shown if a +file is read in text mode, to remind you that something unusual is done. On +MS-DOS, Win32, and OS/2 the message "[notextmode]" is shown if a file is read +without text mode. + +An example on how to use ":r !": + :r !uuencode binfile binfile +This command reads "binfile", uuencodes it and reads it into the current +buffer. Useful when you are editing e-mail and want to include a binary +file. + + +10. Deleting text *deleting* +================= + +["x]<Del> or *<Del>* *x* *dl* +["x]x Delete [count] characters under and after the cursor + [into register x] (not linewise). Does the same as + "dl". See |:fixdel| if the <Del> key does not do what + you want. Also see |'whichwrap'|. {<Del> not in Vi} + + *X* *dh* +["x]X Delete [count] characters before the cursor [into + register x] (not linewise). Does the same as "dh". + Also see |'whichwrap'|. + + *d* +["x]d{motion} Delete text that is moved over [into register x]. + See below for exception. + + *dd* +["x]dd Delete [count] lines [into register x] (linewise). + + *D* +["x]D Delete the characters under the cursor until the end + of the line and [count]-1 more lines [into register + x]; synonym for d$ (not linewise). + +{Visual}["x]x or *v_x* *v_d* +{Visual}["x]d Delete the highlighted text [into register x] (see + the chapter on Visual mode |Visual_mode|). {not in + Vi} + +{Visual}["x]X or *v_X* *v_D* +{Visual}["x]D Delete the highlighted lines [into register x] (see + the chapter on Visual mode |Visual_mode|). {not in + Vi} + + *:d* *:delete* +:[range]d[elete] [x] Delete [range] lines (default: current line) [into + register x]. + +:[range]d[elete] [x] {count} + Delete {count} lines, starting with [range] + (default: current line |cmdline_ranges|) [into + register x]. + +These commands delete text. They can be repeated with the "." command +(except ":d") and undone. Use Visual mode to delete blocks of text. See +|registers| for an explanation of registers. + +An exception for the d{motion} command: If the motion is not linewise, the +start and end of the motion are not in the same line and before the start +and after the end are only blanks, the delete becomes linewise. This means +that the blank line that would remain is also deleted. + + + *J* +J Join [count] lines, with a minimum of two lines. + + *v_J* +{Visual}J Join the highlighted lines, with a minimum of two + lines. {not in Vi} + + *:j* *:join* +:[range]j[oin][!] Join [range] lines. Same as "J", except when [!] is + given, then no spaces will be inserted or deleted. + When [range] is given and the start and end of the + range are equal, nothing happens. Default is to join + two lines. + +:[range]j[oin][!] {count} + Join {count} lines, starting with [range] (default: + current line |cmdline_ranges|). Same as "J", except + when [!] is given, then no spaces will be inserted + or deleted. + +These commands delete the newline between lines. This has the effect of +joining them into one line. They can be repeated (except ":j") and undone. + +One space is inserted in place of the <NL>, unless the line ended with a +space, <Tab> or the next line started with a ')'. If the next line has +leading white space it is deleted first. If the 'joinspaces' option is on, +two spaces are inserted after a period. + + +11. Changing text *changing* +================= + +The following commands can be used to change text, that is delete some text +and insert something else, with one command. They can all be undone. The +non-Ex commands can be repeated with the "." command. + + +11.1 Delete and insert *delete_insert* + + *R* +R Enter Replace mode: Each character you type replaces + an existing character, starting with the character + under the cursor. Repeat the entered text [count]-1 + times. + + *c* +["x]c{motion} Delete {motion} text [into register x] and start + insert. + + *cc* +["x]cc Delete [count] lines [into register x] and start + insert (linewise). If 'autoindent' is on, preserve + the indent of the first line. + + *C* +["x]C Delete from the cursor position to the end of the + line and [count]-1 more lines [into register x], and + start insert. Synonym for c$ (not linewise). + + *s* +["x]s Delete [count] characters [into register x] and start + insert (s stands for Substitute). Synonym for "cl" + (not linewise). + + *S* +["x]S Delete [count] lines [into register x] and start + insert. Synonym for "cc" (not linewise). + +{Visual}["x]c or *v_c* *v_r* +{Visual}["x]r Delete the highlighted text [into register x] and + start insert (see the chapter on Visual mode + |Visual_mode|). {not in Vi} + +{Visual}["x]C or *v_C* *v_R* +{Visual}["x]R Delete the highlighted lines [into register x] and + start insert (see the chapter on Visual mode + |Visual_mode|). {not in Vi} + +Notes: +- You can end Insert and Replace mode with <Esc>. +- See the section "Insert and Replace mode" |mode_ins_repl| for the other + special characters in these modes. +- The effect of [count] takes place after Insert or Replace mode is exited. +- 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. + +See |registers| for an explanation of registers. + +Replace mode is just like Insert mode, except that for every character you +enter, one character is deleted. If the end of a line is reached, further +characters are appended (just like Insert mode). In Replace mode the +backspace key restores the original text (if there was any) (see section +"Insert and Replace mode" |mode_ins_repl|). + + *cw* *cW* +Special case: "cw" and "cW" are treated like "ce" and "cE" if the cursor is +on a non-blank. This is because "cw" is interpreted as change-word, and a +word does not include the following white space. {Vi: "cw" when on a blank +followed by other blanks changes only the first blank; this is probably a +bug, because "dw" deletes all the blanks} + + +11.2 Simple changes *simple_change* + + *r* +r{char} Replace the character under the cursor with {char}. If + {char} is a <CR> or <NL> the character will be + replaced with a line break. Replacing with a real <CR> + can be done by using CTRL-V <CR>. CTRL-V <NL> will + replace with a <Nul>. {Vi: CTRL-V <CR> still replaces + with a line break, cannot replace something with a + <CR>} + If a [count] is given that many characters will be + replaced with [count] {char}s. When {char} is a <CR> + or <NL> only one is inserted. "5r<CR>" replaces five + characters with a single line break; + When replacing with a <CR> or <NL> autoindenting is + done. This works just like deleting the characters + that are replaced and then doing "i<CR><Esc>". + + *~* +~ 'notildeop' option: switch case of the character + under the cursor and move the cursor to the right. + If a [count] is given do that many characters {Vi: + no count} + +~{motion} 'tildeop' option: switch case of {motion} text. {Vi: + tilde cannot be used as an operator} + + *g~* +g~{motion} switch case of {motion} text. {Not in Vi} + + *v_~* +{Visual}~ switch case of highlighted text (see the chapter on + Visual mode |Visual_mode|). {not in Vi} + + *v_U* +{Visual}U Make highlighted text uppercase (see the chapter on + Visual mode |Visual_mode|). {not in Vi} + + *gU* +gU{motion} Make {motion} text uppercase. {not in Vi} + + *v_u* +{Visual}u Make highlighted text lowercase (see the chapter on + Visual mode |Visual_mode|). {not in Vi} + + *gu* +gu{motion} Make {motion} text lowercase. {not in Vi} + + *CTRL-A* +CTRL-A Add [count] to the number at or after the cursor. + {not in Vi} + + *CTRL-X* +CTRL-X Subtract [count] from the number at or after the + cursor. {not in Vi} + +The CTRL-A and CTRL-X commands work for (signed) decimal numbers and +unsigned octal and hexadecimal numbers. Numbers starting with '0x' or '0X' +are assumed to be hexadecimal. To decide whether the hexadecimal number +should be printed uppercase or not, the case of the rightmost letter in the +number is considered. If there is no letter in the current number, the +previously detected case is used. Numbers starting with a '0' are considered +to be octal. Other numbers are decimal and may be preceded with a minus +sign. If the cursor is on a number, that one will be used. Otherwise the +number right of the cursor will be used. + +For octal and hexadecimal numbers with leading zeros, the number of +characters in the number remains equal (when possible). When doing CTRL-A on +"0077" it becomes "0100", CTRL-X on "0x0100" becomes "0x00ff". Note that +when there are no leading zeros this does not work, so CTRL-X on "0x100" +results in "0xff". Note that decimal numbers with leading zeros are +impossible, because they are recognized as octal numbers. + +The CTRL-A command is very useful in a macro. Example: How to make a +numbered list. + +1. Create the first entry. The entry should start with a number. +2. qa - start recording into buffer 'a' +3. Y - yank the entry +4. p - put a copy of the entry below the first one +5. CTRL-A - increment the number +6. q - stop recording +7. <count>@a - repeat the yank, put and increment <count> times + + *<* +<{motion} Shift the {motion} lines one 'shiftwidth' leftwards. + + *<<* +<< Shift [count] lines one 'shiftwidth' leftwards. + + *v_<* +{Visual}[count]< Shift the highlighted lines [count] 'shiftwidth' + leftwards (see the chapter on Visual mode + |Visual_mode|). {not in Vi} + + *>* +>{motion} Shift {motion} lines one 'shiftwidth' rightwards. + + *>>* +>> Shift [count] lines one 'shiftwidth' rightwards. + + *v_>* +{Visual}[count]> Shift the highlighted lines [count] 'shiftwidth' + rightwards (see the chapter on Visual mode + |Visual_mode|). {not in Vi} + + *:<* +:[range]< Shift [range] lines one 'shiftwidth' left. Repeat '<' + for shifting multiple 'shiftwidth's. + +:[range]< {count} Shift {count} lines one 'shiftwidth' left, starting + with [range] (default current line |cmdline_ranges|). + Repeat '<' for shifting multiple 'shiftwidth's. + +:[range]le[ft] [indent] left align lines in [range]. Sets the indent in the + lines to [indent] (default 0). {not in Vi} + + *:>* +:[range]> Shift {count} [range] lines one 'shiftwidth' right. + Repeat '>' for shifting multiple 'shiftwidth's. + +:[range]> {count} Shift {count} lines one 'shiftwidth' right, starting + with [range] (default current line |cmdline_ranges|). + Repeat '>' for shifting multiple 'shiftwidth's. + +The ">" and "<" commands are handy for changing the indent within programs. +The size of the white space which is inserted or deleted can be set with the +'shiftwidth' option. Normally the 'shiftwidth' option is 8, but you can set it +to, say, 3 to make smaller indents. The shift leftwards stops when there is no +indent. The shift right does not do anything with empty lines. + +If the 'shiftround' option is on, the indent is rounded to a multiple of +'shiftwidth'. + +If the 'smartindent' option is on, or 'cindent' is on and 'cinkeys' contains +'#', lines starting with '#' will not be shifted right (they are supposed to +be C preprocessor lines that must stay in column 1). + +When the 'expandtab' option is off (this is the default) <Tab>s are used as +much as possible to make the indent. You can use ">><<" to replace an indent +made out of spaces with the same indent made out of <Tab>s (and a few +spaces if necessary). If the 'expandtab' option is on, only spaces are +used. Then you can use ">><<" to replace <Tab>s in the indent by spaces (or +use ":retab!"). + +To move a line several 'shiftwidth's use the Visual mode or the ":" +commands. For example: + Vjj4> move three lines 4 indents to the right + :<<< move current line 3 indents to the left + :>> 5 move 5 lines 2 indents to the right + :5>> move line 5 2 indents to the right + + +11.3 Complex changes *complex_change* + + *!* +!{motion}{filter} Filter {motion} text through the external program + {filter}. + + *!!* +!!{filter} Filter [count] lines through the external program + {filter}. + + *v_!* +{Visual}!{filter} Filter the highlighted lines through the external + program {filter} (see the chapter on Visual mode + |Visual_mode|). {not in Vi} + +:{range}![!]{filter} [!][arg] *:range!* + Filter {range} lines through the external program + {filter}. The optional bangs are replaced with the + latest given command. The optional [arg] is + appended. The output of the filter command is + temporaryly saved in a file and then read into the + buffer. The 'shellredir' option is used to write the + output of the filter in the temporary file. + + *=* +={motion} Filter {motion} lines through the external program + given with the 'equalprg' option. When the 'equalprg' + option is empty (this is the default), use the + internal formatting function to set the indent of each + line |C_indenting|. + + *==* +== Filter [count] lines through the external program + given with the 'equalprg' option. When the 'equalprg' + option is empty (this is the default), use the + internal formatting function |C_indenting|. + + *v_=* +{Visual}= Filter the highlighted lines through the external + program given with the 'equalprg' option. When the + 'equalprg' option is empty (this is the default), + use the internal formatting function |C_indenting|. + (see the chapter on Visual mode |Visual_mode|). {not + in Vi} + +A filter is a program that accepts text at standard input, changes it in some +way, and sends it to standard output. The commands above can be used to send +some text through a filter. An example of a filter is "sort", which sorts +lines alphabetically. The "indent" program is used to pretty indent C programs +(you need a version of indent that works like a filter, not all versions do +that). The shell, given with the 'shell' option, is used to execute the +command (See also the 'shelltype' option). The filter commands can be redone +with ".". There cannot be a comment (with '"') after the ":!" command. + + + *:s* *:substitute* +:[range]s[ubstitute]/{pattern}/{string}/[g][c][r][p] [count] + For each line in [range] replace {pattern} with + {string}. See below for the flags. + +:[range]s[ubstitute] [g][c][r] [count] +:[range]&[g][c][r] [count] *:&* + Repeat last :substitute with same search pattern and + substitute string. The flags may be different (see + below). + +:[range]~[g][c][r] [count] *:~* + Repeat last substitute with same substitute string + but with last used search pattern. This is like + "&r". See explanation for [r] below. + + *&* +& Synonym for ":s//~/" (repeat last substitute). + +The arguments that can be given to the substitute commands: +[g] All occurrences in the line are replaced. Otherwise only the first + occurrence in the line is replaced. If the 'edcompatible' option is + on this flag is remembered and toggled each time it is used. It is + reset when a new search pattern is given. If the 'gdefault' option + is on, this flag is default on, give the [g] to switch it off. +[c] Each substitute has to be confirmed. The cursor is positioned on the + matching string. You can type: *:s_c* + 'y' to substitute this match + 'n' to skip this match + <Esc> to skip this match + 'a' to substitute this and all remaining matches {not in Vi} + 'q' to quit substituting {not in Vi} + CTRL-E to scroll the screen up {not in Vi} + CTRL-Y to scroll the screen down {not in Vi}. + If the 'edcompatible' option is on the [c] flag is remembered and + toggled each time it is used. It is reset when a new search pattern + is given. +[r] When the search pattern is empty use the previously used search + pattern instead of the search pattern from the last substitute or + ":global". If the last command that did a search was a substitute or + ":global" there is no effect. If the last command was a search + command, like "/", the pattern from that command is used. +[p] Print the line containing the last substitute. +[count] That many lines are are searched, starting with the last line number + in [range] (default current line |cmdline_ranges|). + +If the {pattern} for the substitute command is empty, the pattern from the +last substitute or ":global" command is used. With the [r] flag the pattern +from the last substitute, ":global" or search command is used. + +For compatibility with Vi these two execptions are allowed: +"\/{string}/" and "\?{string}?" do the same as "//{string}/r". +"\&{string}&" does the same as "//{string}/". + +Instead of the '/' which surrounds the pattern and replacement string, you +can use any other character, but not an alphanumeric character, '"' or '|' +or '#'. This is useful if you want to include a '/' in the search pattern or +replacement string. Example: ":s+/+//+" + +For the definition of a pattern see 6.6, "Pattern searches" |search_pattern|. + +Some characters in {string} have a special meaning: + +magic nomagic action + & \& replaced with the whole matched pattern + \& & replaced with & + \0 replaced with the whole matched pattern + \1 replaced with the matched pattern in the first pair of () + \2 replaced with the matched pattern in the second pair of () + .. .. + \9 replaced with the matched pattern in the ninth pair of () + ~ \~ replaced with the {string} of the previous substitute + \~ ~ replaced with ~ + \u next character made uppercase + \U following characters made uppercase + \l next character made lowercase + \L following characters made lowercase + \e end of /u, /U, /l and /L + \E end of /u, /U, /l and /L + <CR> split line in two at this point + \r idem + \n <NL> + \b <BS> + \t <Tab> + CTRL-V <CR> insert a carriage-return (CTRL-M) + +Examples: +:s/a\|b/xxx\0xxx/g modifies "a b" in "xxxaxxx xxxbxxx" +:s/\([abc]\)\([efg]\)/\2\1/g modifies "af fa bg" in "fa fa gb" +:s/abcde/abc^Mde/ modifies "abcde" in "abc", "de" (two lines) +:s/$/^V^M/ modifies "abcde" in "abcde^M" + +Note: To insert a ^M you have to type CTRL-V <CR>. To insert a ^V you have +to type CTRL-V CTRL-V. So to insert the ^V^M in the last example you have to +type CTRL-V CTRL-V CTRL-V <CR>. + +Because CTRL-V <CR> inserts a <CR>, it is impossible to insert a CTRL-V just +in front of a line break. You will have to split it up in two parts: + :s/foo/^Vxxxx/ + :s/xxxx/^M/ + +When using parentheses in combination with '|', like in \([ab]\)\|\([cd]\), +either the first or second pattern in parentheses did not match, so either +\1 or \2 is empty. Example: +:s/\([ab]\)\|\([cd]\)/\1x/g modifies "a b c d" in "ax bx x x" + + *:ret* *:retab* +:[range]ret[ab][!] [new_tabstop] + All sequences of white-space containing a tab are + replaced with new strings of white-space using the new + tabstop value given. If no new tabstop size is + given, the current value of 'tabstop' is used. With + !, strings of normal spaces will also be replace with + tabs where appropriate. With 'expandtab' on, all + tabs will be replaced with the appropriate number of + spaces. This command sets 'tabstop' to the new + value given, and if performed on the whole file, + which is default, should not make any visible + change. Careful: In a C program a <Tab> inside a + string will also be affected. Use "\t" to avoid this + (that's a good habit anyway). {not in Vi} + + +11.4 Formatting text *formatting* + +:[range]ce[nter] [width] *:ce* *:center* + Center lines in [range] between [width] columns + (default 'textwidth' or 80 when 'textwidth' is 0). + {not in Vi} + +:[range]ri[ght] [width] *:ri* *:right* + right align lines in [range] at [width] columns + (default 'textwidth' or 80 when 'textwidth' is 0). + {not in Vi} + + *:le* *:left* +:[range]le[ft] [indent] left align lines in [range]. Sets the indent in the + lines to [indent] (default 0). {not in Vi} + +gq{motion} *Q* *gq* +Q{motion} Format the lines that were moved over. The length of + each line will be restricted to the width given with + the 'textwidth' option. See below. If the + 'textwidth' option is 0, the width of the screen is + used (with a maximum of 79). {not in Vi} + NOTE: The "Q" command is used in Vi to go to Ex mode. + In a future version of Vim this will be made + compatible. Use "gq" for formatting now, to avoid + problems when upgrading to a newer version of Vim. + +{Visual}gq *v_Q* *v_gq* +{Visual}Q Format the highlighted text. (see the chapter on + Visual mode |Visual_mode|). {not in Vi} + +Example: To format the current paragraph use "gqp". + +After the "gq" command the cursor is left in the line where the motion command +would take the cursor. This allows for the formatting to be repeated with +".". This works fine with "gqj" (format current and next line) and "gq}" +(format until end of paragraph). Note: When 'formatprg' is set, the cursor is +left on the first formatted line (like when using a filter command). + +If the 'autoindent' option is on, the indent of the first line is used for +the following lines. + +Empty lines are left unchanged (but lines with spaces or tabs are!). + +The 'formatprg' option can be set to the name of an external program, which +will be used instead of the internal function. The 'textwidth' and other +options will not be used then. + + *format_comments* +Comments can be formatted in a special way. A comment is recognized by a +specific string at the start of the line (ignoring white space). Three types +of comments can be used: + +- Repeating the comment string at the start of each line. An example is the + type of comment used in shell scripts, starting with "#". +- Only the first line has the comment string, following lines don't. An + example is this list with dashes. +- Three-piece comments, that have a start string, an end string and optional + lines in between. The strings for the start, middle and end are different. + An example is the C-style comment: + /* + * this is a C comment + */ + +The 'comments' option can be set to a comma separated list of parts. Each +part defines a type of comment that is recognized. A part consists of: + {flags}:{string} + +{string} is the literal text that must appear. + +{flags}: + n Nested comment. Nesting with mixed parts is allowed. If 'comments' + is "n:),n:>" a line starting with "> ) >" is accepted as comment. + + b Blank (<Space>, <Tab> or end-of-line) required after {string}. + + f First line has comment only, will not be repeated on next line, but + indent is kept (for bullet-lists). + s Start of three-piece comment + m Middle of a three-piece comment + e End of a three-piece comment + + l Left adjust middle with start or end (default). Only recognized when + used together with 's' or 'e'. + r Right adjust middle with start or end. Only recognized when used + together with 's' or 'e'. + +When neither 'f', 's', 'm' or 'e' is given, a repeated comment string is +assumed. It is possible to have an empty flags field. + +Blank space in the text before and after the {string} is also included. The +{string} in the 'comments' option should not include leading or trailing +blanks (although it is allowed, in which case they are required). + +When one comment leader is part of another, put it after that one. For +example, to include both "-" and "->", use + :set comments=f:->,f:- + +A three-piece comment must always be given as start-middle-end, with no other +parts in between. An example of a three-piece comment is "sr:/*,mb:*,el:*/" for +C-comments. To avoid recognizing "*ptr" the 'b' flag is included for the +middle. For three-piece comments the text after the start and middle is +checked for the appearance of the end. If it is, the comment will not +continue below. The middle part must be present, because otherwise Vim can't +recognize the middle lines. + +Examples: +"b:*" Includes lines starting with "*", but not if the "*" is followed by a + non-blank. This avoids a pointer dereference like "*str" to be + recognized as a comment. +"n:>" Includes a line starting with ">", ">>", ">>>", etc. +"fb:-" Format a list that starts with "- ". + +By default, "b:#" is included. This means that a line that starts with +"#include" is not recognized as a comment line. But a line that starts with +"# define" is recognized. In C code this is good, because somewhere after this +a "#endif" is needed. + + *fo_table* +The 'formatoptions' option can be set to influence the way how comments are +formatted. It is a string option, that may contain any of these letters. The +default is "tcq". Commas can be added for readability. + +letter meaning when present in 'formatoptions' + +t Do text autowrapping using textwidth +c Do comment autowrapping using textwidth, inserting the current + comment leader automatically. +r Automatically insert the current comment leader after hitting + <return> in insert mode. +o Automatically insert the current comment leader after hitting 'o' or + 'O' in Normal mode. +q Allow formatting of comments with "gq" (or "Q", which is obsolete). + Note that blank lines, or lines containing only the comment leader + will be left untouched. A new paragraph starts after such a line, or + when the comment leader changes. +2 When formatting text the indent of the second line of a paragraph is + used for the rest of the paragraph. This allows for paragraphs with + a different indent for the first line. +v Vi-compatible auto wrapping in insert mode: Only break a line at a + blank that has been entered during the current insert command. (Note: + this is not 100% Vi compatible, Vi has some "unexpected features" or + bugs in this area. It uses the screen column instead of the line + column) +b Like 'v', but only auto wrap if a blank has been entered at or before + the wrap margin. If the line was longer than 'textwidth' when the + insert started, or no blank was entered in the current insert before + reaching 'textwidth', there is no auto wrapping. +l Long lines are not broken in insert mode: When a line was longer than + 'textwidth' when the insert command started it is not automatically + formatted. + +With 't' and 'c' you can decide when auto-wrapping is done: +value action +"" no automatic formatting, "gq" can be used for manual formatting +"t" automatic formatting of text, not for comments +"c" automatic formatting for comments, not for text (good for C code) +"tc" automatic formatting for text and comments + +Note that when 'textwidth' is 0, no formatting is done anyway (but the comment +leader is inserted). +Note that when 'paste' is on, no formatting is done at all. +Note that 'textwidth' can be non-zero even though auto-wrapping never occurs. +This is good because it can be used for formatting only in this case (with +"gq"). + +If "/*", "*" and/or "*/" are in the 'comments' variable, then Vim has some +built in stuff to treat these types of comments a bit more cleverly. +Opening a new line before or after "/*" or "*/" (with 'r' or 'o' present in +'formatoptions') gives the correct start of the line automatically. The same +happens with formatting and auto-wrapping. Opening a line after a line +starting with "/*" or "*" and containing "*/", will cause no comment leader to +be inserted, and the indent of the new line is taken from the line containing +the start of the comment. +E.g.: + /* + * Your typical comment. + */ + The indent on this line is the same as the start of the above + comment. + +All this should be really cool, especially in conjunction with the new +:autocmd command to prepare different settings for different types of file. + +Some examples: + for C code: fo="croq" (only format comments) + for Mail/news: fo="tcrq" (format all, don't start comment with "o" + command) + + +11.5 Indenting C programs *C_indenting* + +C programs can be automatically indented. Only the indent is set, no other +formatting is done. To format comments see |format_comments|. + +There are in fact three methods that can be used. +'autoindent' Just takes the indent from the previous line. +'smartindent' Is like 'autoindent' but also recognizes some C syntax to + increase/reduce the indent where appropriate. +'cindent' Works more clever than the other two and can be configured to + different indenting styles. +The rest of this section is about the 'cindent' option. + +Note that the indenting done with 'cindent' does not work for 100%. Vim is +not a C compiler, not all syntax is recognized. + +Four options are used for C program indenting: +'cindent' When on automatic C program indenting is enabled. +'cinkeys' Keys that trigger reindenting in insert mode. +'cinoptions' For setting your preferred indent style. +'cinwords' Defines keywords that start an extra indent in the next line. + +If 'lisp' is not on and 'equalprg' is empty, the "=" operator indents using +this algorithm rather than calling an external program. + +See |autocommand| for how to automatically set the 'cindent' option for C code +files and reset it for others. + + *'cinkeys'* *'cink'* +The 'cinkeys' option can be set to a string that says when to do indenting. +The default is "0{,0},:,0#,!^F,o,O,e". This means that indenting is done +when: + "0{" typing '{' as the first character in a line + "0}" typing '}' as the first character in a line + ":" typing ':' anywhere + "0#" typing '#' as the first character in a line + "!^F" typing CTRL-F, which is not inserted + "o" typing a <CR> anywhere and for the "o" command (not in insert + mode!) + "O" for the "O" command (not in insert mode!) + "e" typing the second 'e' for an "else" at the start of a line + +Characters that can be prepended: +'!' When the key is preceded with a '!' the key will not be inserted but + will just cause the current line to be reindented. This allows you to + set a command key for reindenting the current line. By default CTRL-F + is used for this. Careful with CTRL-I, you might think that it is a + nice command for Indenting, but it is the same as a <Tab>. +'*' When the key is preceded with a '*' the reindenting will be done + before inserting the key. If you use "*<Return>" this means that the + current line will be reindented, before opening a new line. + +When the key is not preceded with a '!' or '*' the reindenting will be done +after inserting the key. So ';' will set the indentation of the line +including the ';'. + +'0' When a zero is used before the key (but after '!' or '*') it will only + trigger reindenting if the key is the first character typed in the + line. + +Special key names: +<> Angle brackets mean spelled-out names of keys. For example: "<Up>", + "<Ins>". +'^' Letters preceded by a caret (^) are control characters. For example: + "^F" is CTRL-F. +'o' Means to reindent a line for the "o" command and whenever a new + line is opened below the current one. This includes hitting <Return> + in insert mode. +'O' Means to reindent a line for the "O" command. +'e' Means to reindent a line that starts with "else" when an 'e' is + inserted. + +If you really want to reindent when you type 'o', 'O', 'e', '0', '<', '>', '*' +or '!', use "<o>", "<O>", "<e>", "<0>", "<<>", "<>>", "<*>" or "<!>", +respectively, for those keys. + +For an emacs-style indent mode, where lines aren't indented every time you +press Return but only if you press Tab, I suggest: + :set cinkeys=0{,0},:,0#,!<Tab>,!^F + +Note: When the indent of the current line was changed manually, cindenting +won't be done for any key. This is to avoid re-indenting after you changed +the indent by typing <BS>, <Tab> or <Space> in the indent, or used CTRL-T or +CTRL-D. + +How the indenting is done can be set with 'cinoptions'. In the list below, +"N" represents a number of your choice. It can be negative. When there is an +'s' after the number, it is multiplied with 'shiftwidth'. "1s" is +'shiftwidth', "2s" is two times 'shiftwidth', etc. A decimal point is allowed +too: "-0.5s" is minus half a 'shiftwidth'. The examples given below assume a +'shiftwidth' of 4. + + >N Amount added for "normal" indent. Used after a line that should + increase the indent (lines starting with "if", an opening brace, + etc.). (default 'shiftwidth'). + + cino= cino=>2 cino=>2s + if (cond) if (cond) if (cond) + { { { + foo; foo; foo; + } } } + + eN Add N to the prevailing indent inside a set of braces if the + opening brace at the End of the line (more precise: is not the + first character in a line). This is useful if you want a + different indent when the '{' is at the start of the line from + when '{' is at the end of the line. (default 0). + + cino= cino=e2 cino=e-2 + if (cond) { if (cond) { if (cond) { + foo; foo; foo; + } } } + else else else + { { { + bar; bar; bar; + } } } + + nN Add N to the prevailing indent for a statement after an "if", + "while", etc., if it is Not inside a set of braces. This is + useful if you want a different indent when there is no '{' + before the statement from when there is a '{' before it. + (default 0). + + cino= cino=n2 cino=n-2 + if (cond) if (cond) if (cond) + foo; foo; foo; + else else else + { { { + bar; bar; bar; + } } } + + fN The First opening brace of a function or other block is placed + in column N. Only for an opening brace that is not inside other + braces and is at the start of the line. What comes after the + brace is put relative to this brace. (default 0). + + cino= cino=f.5s cino=f1s + func() func() func() + { { { + int foo; int foo; int foo; + + {N Opening braces are placed N characters from the prevailing + indent. Only for opening braces that are inside + other braces. (default 0). + + cino= cino={.5s cino={1s + if (cond) if (cond) if (cond) + { { { + foo; foo; foo; + + }N Closing braces are placed N characters from the matching opening + brace. (default 0). + + cino= cino={2,}-0.5s cino=}2 + if (cond) if (cond) if (cond) + { { { + foo; foo; foo; + } } } + + ^N Add N to the prevailing indent inside a set of braces if the + opening brace is in column 0. This is used to have a different + indent for whole of a function (some may like to set it to a + negative number). (default 0). + + cino= cino=^-2 cino=^-s + func() func() func() + { { { + if (cond) if (cond) if (cond) + { { { + a = b; a = b; a = b; + } } } + } } } + + :N Case labels are placed N characters from the indent of the + switch(). (default 'shiftwidth'). + + cino= cino=:0 + switch (x) switch(x) + { { + case 1: case 1: + a = b; a = b; + default: default: + } } + + =N Statements after a case label are placed N characters from the + indent of the label. (default 'shiftwidth'). + + cino= cino==10 + case 11: case 11: a = a + 1; + a = a + 1; b = b + 1; + + pN Parameter declarations for K&R-style function declarations will + be indented N characters from the margin. (default + 'shiftwidth'). + + cino= cino=p0 cino=p2s + func(a, b) func(a, b) func(a, b) + int a; int a; int a; + char b; char b; char b; + + tN Type for a function declaration will be indented N characters + from the margin. (default 'shiftwidth'). + + cino= cino=t0 cino=t7 + int int int + func() func() func() + + +N Continuation lines (lines that spill onto two) are indented N + additional characters. (default 'shiftwidth'). + + cino= cino=+10 + a = b + 9 * a = b + 9 * + c; c; + + cN Comment lines after the comment opener, when there is no other + text to line up with, are indented N characters from the comment + opener. (default 3). See also |format_comments|. + + cino= cino=c5 + /* /* + text. text. + */ */ + + (N When in unclosed parentheses, indent N characters from the line + with the unclosed parentheses. When N is 0 or the line starts + with '(' line up with the unclosed parentheses. (default + 'shiftwidth' * 2). + + cino= cino=(0 + if (c1 && (c2 || if (c1 && (c2 || + c3)) c3)) + foo; + if (c1 && if (c1 && + (c2 || c3) (c2 || c3) + } } + + )N Unclosed parentheses will be searched for at most N lines away. + This is just to limit the time needed to search for parentheses. + (default 20 lines). + + *N Unclosed comments will be searched for at most N lines away. + This is just to limit the time needed to search for the start of + a comment. (default 30 lines). + +The defaults, spelled out in full, would be + cinoptions=>s,e0,n0,f0,{0,}0,^0,:s,=s,ps,ts,+s,(2s,)20,*30 + +Lines are put in column 1 if: +- It starts with '#' (preprocessor directives), if 'cinkeys' contains '#'. +- It starts with a label (a keyword followed by ':', other than "case" and + "default"). +- Any combination of indentations causes the line to have less than 0 + indentation. + + +12. Copying and moving text *copy_move* +=========================== + + *quote* +"<a-zA-Z0-9.%:-"> Use register <a-zA-Z0-9.%:-"> for next delete, yank + or put (use uppercase character to append with + delete and yank) (<.%:> only work with put). + + *:reg* *:registers* +:reg[isters] Display the contents of all numbered and named + registers. {not in Vi} + +:reg[isters] {arg} Display the contents of the numbered and named + registers that are mentioned in {arg}. For example: + :dis 1a + to display registers '1' and 'a'. Spaces are allowed + in {arg}. {not in Vi} + + *:di* *:display* +:di[splay] [arg] Same as :registers. {not in Vi} + + *y* +["x]y{motion} Yank {motion} text [into register x]. + + *yy* +["x]yy Yank [count] lines [into register x] (linewise). + + *Y* +["x]Y yank [count] lines [into register x] (synonym for + yy, linewise). If you like "Y" to work from the + cursor to the end of line (which is more logical, + but not Vi-compatible) use ":map Y y$". + + *v_y* +{Visual}["x]y Yank the highlighed text [into register x] (see the + chapter on Visual mode |Visual_mode|). {not in Vi} + + *v_Y* +{Visual}["x]Y Yank the highlighted lines [into register x] (see the + chapter on Visual mode |Visual_mode|). {not in Vi} + + *:y* *:yank* +:[range]y[ank] [x] Yank [range] lines [into register x]. + +:[range]y[ank] [x] {count} + Yank {count} lines, starting with last line number + in [range] (default: current line |cmdline_ranges|), + [into register x]. + + *p* +["x]p Put the text [from register x] after the cursor + [count] times. {Vi: no count} + +["x]P or *P* *<MiddleMouse>* +["x]<MiddleMouse> Put the text [from register x] before the cursor + [count] times. Using the mouse only works when + 'mouse' contains 'n' or 'a'. {Vi: no count} + + *:pu* *:put* +:[line]pu[t] [x] Put the text [from register x] after [line] (default + current line). + +:[line]pu[t]! [x] Put the text [from register x] before [line] (default + current line). + +["x]]p or *]p* *]<MiddleMouse>* +["x]]<MiddleMouse> Like "p", but adjust the indent to the current line. + Using the mouse only works when 'mouse' contains 'n' + or 'a'. {not in Vi} + +["x][P or *[P* +["x]]P or *]P* +["x][p or *[p* *[<MiddleMouse>* +["x][<MiddleMouse> Like "P", but adjust the indent to the current line. + Using the mouse only works when 'mouse' contains 'n' + or 'a'. {not in Vi} + +These commands can be used to copy text from one place to another. This is +done by first getting the text into a register with a yank, delete or change +command. The register can then be inserted with a put command. All registers +are kept when changing files. Thus you can also use this to move text from +one file to another (the CTRL-^ command is a quick way to toggle between two +files). + +The put commands can be repeated with "." (except for :put) and undone. If +the command that was used to get the text into the register was linewise, the +text will be inserted below ("p") or above ("P") the line where the cursor +is. Otherwise the text will be inserted after ("p") or before ("P") the +cursor. With the ":put" command the text will always be inserted in the next +line. You can exchange two characters with the command sequence "xp". You +can exchange two lines with the command sequence "ddp". You can exchange +two words with the command sequence "deep" (start with the cursor in the +blank space before the first word). The "']" or "`]" command can be used +after the put command to move the cursor to the end of the inserted text, +"'[" or "`[" to move the cursor to the start. + +If the command that was used to get the text into the register used +blockwise Visual mode, the block of text will be inserted before ("P") or +after ("p") the cursor column, in the current and next lines. Vim will make +the whole block of text start in the same column. Thus the inserted text +looks the same as when it was yanked or deleted. Some <Tab> characters may +be replaced with spaces to make this happen. However, if the width of the +block is not a multiple of a <Tab> width and the text after the inserted +block contains <Tab>s, that text may be misaligned. + +There are five types of registers: *registers* +- The unnamed register "" *quote_quote* *quotequote* +- 10 numbered registers "0 to "9 *quote_number* *quote0* +- The small delete register "- *quote_-* *quote-* +- 26 named registers "a to "z or "A to "Z *quote_alpha* *quotea* +- three read-only registers ":, ". and "% + + The unnamed register is the register where all text deleted with +the "d", "c", "s", "x" commands or copied with the yank "y" command is +placed, regardless of whether or not a specific register was used (e.g. +"xdd). The contents of this register are used by any put command (p or P) +which does not specify a register. Additionally it can be accessed by the +name '"'. This means you have to type two double quotes. {Vi: register +contents lost when changing files, no '"'} + The numbered registers are filled with yank and delete commands. +Numbered register 0 is filled with the last yank command, unless another +register was specified with ["x]. Numbered register 1 is filled with the text +that was deleted by each delete or change command, unless another register was +specified or the text is less than one line (text deleted with "x" or "dw" +will be put in the small delete register). The contents of register 1 are put +in 2, 2 in 3, and so forth. The contents of register 9 are lost. {Vi: +numbered register contents are lost when changing files; register 0 does not +exist} + The small delete register is filled with delete commands that delete +less than one line, except when a register was specified with ["x]. + The named registers are only filled when you say so. They are named +'a' to 'z' normally. If you use an uppercase letter, the same registers as +with the lower case letter is used, but the text is appended to the previous +register contents. With a lower case letter the previous contents are lost. + The read-only registers are '%', ':' and '.'. They can only be used +with the commands "p", "P", ":put" and with CTRL-R. + *quote_.* *quote.* + ". Contains the last inserted text (the same as what is inserted + with the insert mode commands CTRL-A and CTRL-@). Note: this + doesn't work with CTRL-R on the command line. It works a bit + differently, like inserting the text instead of putting it + ('textwidth' and other options affect what is inserted). + *quote_%* *quote%* + "% Contains the name of the current file. + *quote_:* *quote:* + ": Contains the last command line. It can be used with "@:", + this repeats the last command line. + +If you use a put command without specifying a register, the register that +was last written to is used (this is also the contents of the unnamed +register). If you are confused, use the ":dis" command to find out what will +be put (all named and numbered registers are displayed; the unnamed register +is labelled '"'). + +The next three commands always work on whole lines. + +:[range]co[py] {address} *:co* *:copy* + Copy the lines given by [range] to below the line + given by {address}. + + *:t* +:t Synonym for copy. + +:[range]m[ove] {address} *:m* *:move* + Move the lines given by [range] to below the line + given by {address}. + + +13. Visual mode *Visual_mode* +=============== + +Visual mode is a flexible and easy way to select a piece of text for an +operator. It is the only way to select a block of text. {Vi has no Visual +mode, the name "visual" is used for Normal mode, to distinguish it from Ex +mode} + + *v* +v start Visual mode per character. {not in Vi} + + *V* +V start Visual mode linewise. {not in Vi} + + *CTRL-V* +CTRL-V start Visual mode blockwise. {not in Vi} + + *v_o* +o go to Other end of highlighted text: The current + cursor position becomes the start of the highlighted + text and the cursor is moved to the Other end of the + highlighted text. {not in Vi} + + *gv* *v_gv* +gv Start Visual mode with the same area as the previous + area and the same mode. In Visual mode the current and + the previous Visual area are exchanged. {not in Vi} + + *<LeftMouse>* +<LeftMouse> Set the current cursor position. If Visual mode is + active it is stopped. Only when 'mouse' option is + contains 'n' or 'a'. If the position is within 'so' + lines from the last line on the screen the text is + scrolled up. If the position is within 'so' lines from + the first line on the screen the text is scrolled + down. {not in Vi} + + *<RightMouse>* +<RightMouse> Start Visual mode if it is not active. The text from + the cursor position to the position of the click is + highlighted. If Visual mode was already active move + the start or end of the highlighted text, which ever + is closest, to the position of the click. Only when + 'mouse' option contains 'n' or 'a'. {not in Vi} + + *<LeftRelease>* +<LeftRelease> This works like a <LeftMouse>, if it is not a + the same position as <LeftMouse>. In an xterm you + won't see the selected area until the button is + released. Only when 'mouse' option contains 'n' or + 'a'. {not in Vi} + + +To apply an operator on a piece of text: + 1. mark the start of the text with "v", "V" or CTRL-V + The character under the cursor will be used as the start. + 2. move to the end of the text + The text from the start of the Visual mode up to and + including the character under the cursor is highlighted. + 3. hit an operator + The highlighted characters will be operated upon. + +The 'highlight' option can be used to set the display mode to use for +highlighting in Visual mode. + +The highlighted text includes the character under the cursor. On terminals +where it is possible to make the cursor invisible the cursor position is +also highlighted. On terminals where this is not possible the cursor is +displayed normally. If your cursor cannot be made invisible and you want Vim +to highlight the character under the cursor anyway, you could set the 't_cv' +and 't_ci' options to something harmless, for example: + :set t_cv=^[^[ t_ci=^[^[ + +With "v" the text before the start position and after the end position will +not be highlighted. However, All uppercase and non-alpha operators, except +"~", will work on whole lines anyway. See the list of operators below. + + *visual_block* +With CTRL-V (blockwise Visual mode) the highlighted text will be a rectangle +between start position and the cursor. However, some operators work on whole +lines anyway (see the list below). The change and substitute operators will +delete the highlighted text and then start insertion at the top left +position. + +When the "$" command is used with blockwise Visual mode, the right end of the +highlighted text will be determined by the longest highlighted line. This +stops when a motion command is used that does not move straight up or down. + +If you use <Esc>, click the left mouse button or use any command that +does a jump to another buffer while in Visual mode, the highlighting stops +and no text is affected. Also when you hit "v" in characterwise Visual mode, +"CTRL-V" in blockwise Visual mode or "V" in linewise Visual mode. If you hit +CTRL-Z the highlighting stops and the editor is suspended or a new shell is +started |CTRL-Z|. + + new mode after typing: *v_v* *v_CTRL-V* *v_V* +old mode "v" "CTRL-V" "V" + +Normal Visual blockwise Visual linewise Visual +Visual Normal blockwise Visual linewise Visual +blockwise Visual Visual Normal linewise Visual +linewise Visual Visual blockwise Visual Normal + +For moving the end of the block many commands can be used, but you cannot +use Ex commands, commands that make changes or abandon the file. Commands +(starting with) ".pPiIaAO&", CTRL-^, "ZZ", CTRL-], CTRL-T, CTRL-R, CTRL-I +and CTRL-O cause a beep and Visual mode continues. + +If Visual mode is not active and the "v", "V" or CTRL-V is preceded with a +count, the size of the previously highlighted area is used for a start. You +can then move the end of the highlighted area and give an operator. The type +of the old area is used (character, line or blockwise). +- Linewise Visual mode: The number of lines is multiplied with the count. +- Blockwise Visual mode: The number of lines and columns is multiplied with + the count. +- Normal Visual mode within one line: The number of characters is multiplied + with the count. +- Normal Visual mode with several lines: The number of lines is multiplied + with the count, in the last line the same number of characters is used as + in the last line in the previously highlighted area. +The start of the text is the Cursor position. If the "$" command was used as +one of the last commands to extend the highlighted text, the area will be +extended to the rightmost column of the longest line. + +If you want to highlight exactly the same area as the last time, you can use +"gv" |gv| |v_gv|. + +The operators that can be used are: + ~ switch case |v_tilde| + d delete |v_d| + c change |v_c| + y yank |v_y| + > shift right (1)(*) |v_>| + < shift left (1)(*) |v_<| + ! filter through external command (1) |v_!| + = filter through 'equalprg' option command (1) |v_=| + Q format lines to 'textwidth' length (1)(obsolete)|v_Q| + gq format lines to 'textwidth' length (1) |v_gq| + +The objects that can be used are: + a word |v_a| + A WORD (see |WORD|) |v_A| + s sentence |v_s| + p paragraph |v_p| + P block |v_P| + +Additionally the following commands can be used: + : start ex command for highlighted lines (1) |v_:| + r change |v_r| + C change (2) |v_C| + R change (2) |v_R| + x delete |v_x| + D delete (2) |v_D| + X delete (2) |v_X| + Y yank (2) |v_Y| + J join (1) |v_J| + U make uppercase |v_U| + u make lowercase |v_u| + ^] find tag |v_CTRL-]| + +(1): always whole lines, see |:visual_example| +(2): whole lines when not using CTRL-V +(*): in a future a blockwise shift will move the block only, not whole + lines. + +Note that the ":vmap" command can be used to specifically map keys in Visual +mode. + +If you want to give a register name using the """ command, do this just before +typing the operator character: "v{move around}"xd". + +If you want to give a count to the command, do this just before typing the +operator character: "v{move around}3>" (move lines 3 indents to the right). + + *repeat_Visual* +When repeating a Visual mode operator, the operator will be applied to the +same amount of text as the last time: +- Linewise Visual mode: The same number of lines. +- Blockwise Visual mode: The same number of lines and columns. +- Normal Visual mode within one line: The same number of characters. +- Normal Visual mode with several lines: The same number of lines, in the + last line the same number of characters as in the last line the last time. +The start of the text is the Cursor position. If the "$" command was used as +one of the last commands to extend the highlighted text, the repeating will +be applied up to the rightmost column of the longest line. + + *:visual_example* +Currently the ":" command works on whole lines only. When you select part of +a line, doing something like ":!date" will replace the whole line. If you +want only part of the line to be replaced you will have to make a mapping for +it. In a future release ":" may work on partial lines. + +Here is an example, to replace the selected text with the output of "date": + +:vmap _a <Esc>a<CR><Esc>`\<i<CR><Esc>!!date<CR>kJJ + +(In the <> notation |<>|, when typing it you should type it literally; you +need to remove the 'B' and '<' flags from 'cpoptions') + +What this does is: +<Esc> stop Visual mode +a<CR><Esc> break the line after the Visual area +`\< jump to the start of the Visual area +i<CR><Esc> break the line before the Visual area +!!date<CR> filter the Visual text through date +kJJ Join the lines again + + +14. Various commands *various* +==================== + + *CTRL-L* +CTRL-L Clear and redraw the screen. + + *N<Del>* +<Del> When entering a number: Remove the last digit. + Note: if you like to use <BS> for this, add this + mapping to your .vimrc: + :map CTRL-V <BS> CTRL-V <Del> + See |:fixdel| if your <Del> key does not do what you + want. + +:as[cii] or *ga* *:as* *:ascii* +ga Print the ascii value of the character under the + cursor in decimal, hexadecimal and octal. For + example, when the cursor is on a 'R': + <R> 82, Hex 52, Octal 122 + When the character is a non-standard ASCII character, + but printable according to the 'isprint' option, the + non-printable version is also given. When the + character is larger than 127, the <M-x> form is also + printed. For example: + <~A> <M-^A> 129, Hex 81, Octal 201 + <p> <|~> <M-~> 254, Hex fe, Octal 376 + (where <p> is a special character) + The <Nul> character in a file is stored internally as + <NL>, but it will be shown as: + <^@> 0, Hex 00, Octal 000 + Mnemonic: Get Ascii value. {not in Vi} + + *:p* *:print* +:[range]p[rint] Print [range] lines (default current line). + +:[range]p[rint] {count} + Print {count} lines, starting with [range] (default + current line |cmdline_ranges|). + + *:l* *:list* +:[range]l[ist] [count] + Same as :print, but display unprintable characters + with '^'. + + *:nu* *:number* +:[range]nu[mber] [count] + Same as :print, but precede each line with its line + number. (See also 'highlight' option). + + *:#* +:[range]# [count] synonym for :number. + + *:=* +:= Print the cursor line number. + +:norm[al][!] {commands} *:norm* *:normal* + Execute Normal mode commands {commands}. This makes + it possible to execute normal mode commands typed on + the command line. {commands} is executed like it is + typed. For undo all commands are undone together. If + the [!] is given, mappings will not be used. If + {commands} does not finish a command, more characters + need to be typed. Mostly useful for autocommands. + This command cannot be followed by another command, + since any '|' is considered part of the command. + {not in vi} + + *:sh* *:shell* +:sh[ell] Escape to a shell (name from 'shell' option). + + *:!cmd* *:!* +:!{cmd} Execute {cmd} with the shell. See also the 'shell' + and 'shelltype' option. Any '!' in {cmd} is replaced + with the previous external command (see also + 'cpoptions'). But not when there is a backslash + before the '!', then that backslash is removed. + Example: ":!ls" followed by ":!echo ! \! \\!" + executes "echo ls ! \!". Also see |shell_window|. + + *:!!* +:!! Repeat last ":!{cmd}". + + *:ve* *:version* +:ve[rsion] Print the version number of the editor. If the + compiler used understands "__DATE__" the compilation + date is mentioned. Otherwise a fixed release-date is + shown. The following lines contain information about + which options were defined when Vim was compiled. + +:ve[rsion] {nr} Set the version number to {nr}. Used in .vimrc files. + When omitted Vim will give a warning message. If {nr} + is higher than the current Vim version this will + result in an error message. {not in Vi} + + *K* +K Run a program to lookup the keyword under the + cursor. The name of the program is given with the + 'keywordprg' (kp) option (default is "man"). The + keyword is formed of letters, numbers and the + characters in 'iskeyword'. The keyword under or + right of the cursor is used. The same can be done + with the command + ":!{program} {keyword}". + There is an example of a program to use in the tools + directory of Vim. It is called 'ref' and does a + simple spelling check. + If 'keywordprg' is empty, the ":help" command is used. + {not in Vi} + + *v_K* +{Visual}K Like "K", but use the visually highlighted text for + the keyword. Only works when the highlighted text is + not more than one line. {not in Vi} + +[N]gs *gs* *:sl* *:sleep* +:[N]sl[eep] [N] Do nothing for [N] seconds. Can be interrupted with + CTRL-C (CTRL-break on MS-DOS). "gs" stands for "goto + sleep". While sleeping the cursor is positioned in + the text (if visible). {not in Vi} + + +15. Repeating commands *repeating* +====================== + +15.1 Single repeats *single_repeat* + + *.* +. Repeat last change with count replaced with [count]. + +Simple changes can be repeated with the "." command. Without a count, the +count of the last change is used. If you enter a count, it will replace the +last one. If the last change included a specification of a numbered register, +the register number will be incremented. See the section on undo and redo for +an example how to use this |undo_redo|. Note that when repeating a command +that used a Visual selection, the same SIZE of area is used, see +|repeat_Visual|. + + *@:* +@: Repeat last command line [count] times. + + +15.2 Multiple repeats *multi_repeat* + + *:g* *:global* +:[range]g[lobal]/{pattern}/[cmd] + Execute the Ex command [cmd] (default ":p") on the + lines within [range] where {pattern} matches. + +:[range]g[lobal]!/{pattern}/[cmd] + Execute the Ex command [cmd] (default ":p") on the + lines within [range] where {pattern} does NOT match. + + *:v* *:vglobal* +:[range]v[global]/{pattern}/[cmd] + Same as :g!. + +The global commands work by first scanning through the [range] lines and +marking each line where a match occurs. In a second scan the [cmd] is +executed for each marked line with its line number prepended. If a line is +changed or deleted its mark disappears. The default for [range] is the whole +buffer (1,$). Use "CTRL-C" to interrupt the command. If an error message is +given for a line the global command aborts. + +To repeat a non-Ex command, you will have to put the command in a file and +use "source!". For example: + :g/pat/so! scriptfile +Make sure that the scriptfile ends with a whole command, otherwise Vim will +wait for you to type the rest of the command for each match. The screen will +not have been updated, so you don't know what you are doing. + +The undo/redo command will undo/redo the whole global command at once. +The previous context mark will only be set once (with "''" you go back to +where the cursor was before the global command). + +The global command sets both the last used search pattern and the last used +substitute pattern (this is vi compatible). This makes it easy to globally +replace a string: + :g/pat/s//PAT/g +This replaces all occurences of "pat" with "PAT". The same can be done with: + :%s/pat/PAT/g +Which is two characters shorter! + + +15.3 Complex repeats *complex_repeat* + + *q* +q<0-9a-zA-Z"> Record typed characters into register <0-9a-zA-Z"> + (uppercase to append). The 'q' command is disabled + while executing a register. {Vi: no recording} + +q Stops recording. (Implementation note: The 'q' that + stops recording is not stored in the register, unless + it was the result of a mapping) {Vi: no recording} + + *@* +@<0-9a-z".> Execute the contents of register <0-9a-z".> [count] + times. Note that register '%' (name of the current + file) cannot be used. See also |@:|. {Vi: only named + registers} + + *@@* +@@ Repeat the previous @<0-9a-z":> [count] times. + + *:@* +:[addr]@<0-9a-z"> Execute the contents of register <0-9a-z"> as an Ex + command. First set cursor at line [addr] (default is + current line). When the last line in the register does + not have a <CR> it will be added automatically when + the 'e' flag is present in 'cpoptions'. {Vi: only in + some versions} Future: Will execute the register for + each line in the address range. + +:[addr]@: Repeat last command line [count] times. First set + cursor at line [addr] (default is current line). + {Vi: only in some versions} + + *:@@* +:[addr]@@ Repeat the previous :@<0-9a-z">. First set cursor at + line [addr] (default is current line). {Vi: only in + some versions} + + *:so* *:source* +:so[urce] {file} Read Ex commands from {file}. + +:so[urce]! {file} Read Vim commands from {file}. {not in Vi} + +All commands and command sequences can be repeated by putting them in a named +register and then executing it. There are two ways to get the commands in the +register: +- Use the record command "q". You type the commands once, and while they are + being executed they are stored in a register. Easy, because you can see + what you are doing. If you make a mistake, 'put' the register into the + file, edit the command sequence, and then delete it into the register + again. You can continue recording by appending to the register (use an + uppercase letter). +- Delete or yank the command sequence into the register. + +Often used command sequences can be put under a function key with the ':map' +command. + +An alternative is to put the commands in a file, and execute them with the +':source!' command. Useful for long command sequences. Can be combined with +the ':map' command to put complicated commands under a function key. + +The ':source' command reads Ex commands from a file line by line. You will +have to type any needed keyboard input. The ':source!' command reads from a +script file character by character, interpreting each character as if you +typed it. + +Example: When you give the ":!ls" command you are asked to "hit return to +continue". If you ':source' a file with the line "!ls" in it, you will have +to type the return yourself. But if you ':source!' a file with the line +":!ls" in it, the next characters from that file are read until a <CR> is +found. You will not have to type <CR> yourself, unless ":!ls" was the last +line in the file. + +It is possible to put ':source[!]' commands in the script file, so you can +make a top-down hierarchy of script files. The ':source' command can be +nested as deep as the number of files that can be opened at one time (about +15). The ':source!' command can be nested up to 15 levels deep. + +In script files terminal-dependent key codes are represented by +terminal-independent two character codes. This means that they can be used +in the same way on different kinds of terminals. The first character of a +key code is 0x80 or 128, shown on the screen as "~@". The second one can be +found in the list |key_notation|. Any of these codes can also be entered +with CTRL-V followed by the three digit decimal code. This does NOT work for +the <t_xx> termcap codes, these can only be used in mappings. + + *:source_crnl* +MS-DOS, Win32 and OS/2: Files that are read with ":source" normally have +<CR>-<NL> line separators. These always work. If you are using a file with +<NL> line separators (for example, a file made on Unix), this will be +recognized if you have 'textauto' on and the first line does not end in a +<CR>. This fails if the first line has something like ":map <F1> :help^M", +where "^M" is a <CR>. If the first line ends in a <CR>, but following ones +don't, you will get an error message, because the <CR> from the first lines +will be lost. + + +16. Undo and redo *undo_redo* +================= + +<Undo> or *undo* *<Undo>* *u* +u Undo [count] changes. {Vi: only one level} + + *:u* *:undo* +:u[ndo] Undo one change. {Vi: only one level} + + *CTRL-R* +CTRL-R Redo [count] changes which were undone. {Vi: redraw + screen} + + *:red* *:redo* +:red[o] Redo one change which was undone. {Vi: no redo} + + *U* +U Undo all latest changes on one line. {Vi: while not + moved off of it} + +The last changes are remembered. You can go back in time with the "u" +command. You can then go forward again with the 'CTRL-R' command. If you +make a new change after the "u" command, the 'CTRL-R' will not be possible +anymore. The number of changes that are remembered is set with the +'undolevels' option. If it is zero, the old fashioned Vi undo is present: +one level of undo and undo undoes itself. If it is negative no undo is +possible. Use this if you are running out of memory. + +The "U" command is treated by undo/redo just like any other command. Thus a +"u" command undos a "U" command and a 'CTRL-R' command redoes it again. When +mixing "U", "u" and 'CTRL-R' you will notice that the "U" command will +restore the situation of a line to before the previous "U" command. This may +be confusing. Try it out to get used to it. + +When all changes have been undone the buffer is not considered to be changed. +Vim can then be exit with ":q" instead of ":q!". {this is not in Vi} + +The numbered registers can also be used for undoing deletes. Each time you +delete text, it is put into register "1. The contents of register "1 are +shifted to "2, etc. The contents of register "9 are lost. You can now get +back the most recent deleted text with the put command: '"1P'. (also, if the +deleted text was the result of the last delete or copy operation, 'P' or 'p' +also works as this puts the contents of the unnamed register). You can get +back the text of three deletes ago with '"3P'. + +If you want to get back more than one part of deleted text, you can use a +special feature of the repeat command ".". It will increase the number of the +register used. So if you first do ""1P", the following "." will result in a +'"2P'. Repeating this will result in all numbered registers being inserted. + +Example: If you deleted text with 'dd....' it can be restored with + '"1P....'. + +If you don't know in which register the deleted text is, you can use the +:display command. An alternative is to try the first register with '"1P', and +if it is not what you want do 'u.'. This will remove the contents of the +first put, and repeat the put command for the second register. Repeat the +'u.' until you got what you want. + + +17. Key mapping *key_mapping* +=============== + +There are commands to enter new mappings, remove mappings and list mappings: + +:map {lhs} {rhs} *:map* +:nm[ap] {lhs} {rhs} *:nm* *:nmap* +:vm[ap] {lhs} {rhs} *:vm* *:vmap* +:map! {lhs} {rhs} *:map!* +:im[ap] {lhs} {rhs} *:im* *:imap* +:cm[ap] {lhs} {rhs} *:cm* *:cmap* + Map the key sequence {lhs} to {rhs} for the modes + where the map command applies. + + +:no[remap] {lhs} {rhs} *:no* *:noremap* +:nn[oremap] {lhs} {rhs} *:nn* *:nnoremap* +:vn[oremap] {lhs} {rhs} *:vn* *:vnoremap* +:no[remap]! {lhs} {rhs} *:no!* *:noremap!* +:ino[remap] {lhs} {rhs} *:ino* *:inoremap* +:cno[remap] {lhs} {rhs} *:cno* *:cnoremap* + Map the key sequence {lhs} to {rhs} for the modes + where the map command applies. Disallow mapping of + {rhs}. {not in Vi} + + +:unm[ap] {lhs} *:unm* *:unmap* +:nun[map] {lhs} *:nun* *:nunmap* +:vu[nmap] {lhs} *:vu* *:vunmap* +:unm[ap]! {lhs} *:unm!* *:unmap!* +:iu[nmap] {lhs} *:iu* *:iunmap* +:cu[nmap] {lhs} *:cu* *:cunmap* + Remove the mapping of {lhs} for the modes where the + map command applies. + +:mapc[lear] *:mapc* *:mapclear* +:nmapc[lear] *:nmapc* *:nmapclear* +:vmapc[lear] *:vmapc* *:vmapclear* +:mapc[lear]! *:mapc!* *:mapclear!* +:imapc[lear] *:imapc* *:imapclear* +:cmapc[lear] *:cmapc* *:cmapclear* + Remove all mappings for the modes where the map + command applies. {not in Vi} + +:map +:nm[ap] +:vm[ap] +:map! +:im[ap] +:cm[ap] + List all key mappings for the modes where the map + command applies. + +:map {lhs} *:map_l* +:nm[ap] {lhs} *:nmap_l* +:vm[ap] {lhs} *:vmap_l* +:map! {lhs} *:map_l!* +:im[ap] {lhs} *:imap_l* +:cm[ap] {lhs} *:cmap_l* + List the key mappings for the key sequences starting + with {lhs} in the modes where the map command applies. + {not in Vi} + +These commands are used to map a key or key sequence to a string of +characters. You can use this to put command sequences under function keys, +translate one key into another, etc. See the "Options" chapter below for how +to save and restore the current mapping |options|. + +There are four sets of mappings +- For Insert mode. These are also used in Replace mode. +- For Command-line mode: When entering a ":" or "/" command. +- For Normal mode: When typing commands. +- For Visual mode: When typing commands while the Visual area is highlighted. + +Overview of which map command works in which mode: + + commands: modes: + Normal Visual Insert Command-line +:map :noremap :unmap :mapclear X X . . +:nmap :nnoremap :nunmap :nmapclear X . . . +:vmap :vnoremap :vunmap :vmapclear . X . . +:map! :noremap! :unmap! :mapclear! . . X X +:imap :inoremap :iunmap :imapclear . . X . +:cmap :cnoremap :cunmap :cmapclear . . . X + +The original Vi did not have separate mappings for Normal/Visual mode and +Insert/Command-line mode. Therefore the ":map" and ":map!" commands enter +and display mappings for both. In Vim you can use the ":nmap", "vmap", +":cmap" and ":imap" commands to enter mappings for each mode separately. +When listing mappings the character in column 1 is + + char mode + <Space> Normal and Visual + n Normal + v Visual + ! Insert and Command-line + i Insert + c Command-line + +Note: When using mappings for Visual mode, you can use the '<' mark, which +is the start of the last selected Visual area |'<|. + +Everything from the first non-blank after {lhs} up to the end of the line +(or '|') is considered to be part of {rhs}. This allows the {rhs} to end +with a space. + + *map_backslash* +Note that only CTRL-V is mentioned here as a special character for mappings +and abbreviations. When 'cpoptions' does not contain 'B', a backslash can +also be used like CTRL-V. The <> notation can be fully used then |<>|. + + *map_space_in_lhs* +To include a space in {lhs} precede it with a CTRL-V (type two CTRL-Vs for +each space). + *map_space_in_rhs* +If you want a {rhs} that starts with a space, precede {rhs} with a single +CTRL-V (you have to type CTRL-V two times). + *map_empty_rhs* +You can create an empty {rhs} by typing nothing after a single CTRL-V (you +have to type CTRL-V two times). + + *map_bar* +It is not possible to put a comment after this command, because the '"' +character is considered to be part of the {rhs}. To put a '|' in {rhs} +escape it with a backslash or a CTRL-V (to get one CTRL-V you have to type +it twice). When 'b' is present in 'cpoptions', only CTRL-V can be used, "\|" +will be recognized as a mapping ending in a '\' and then another command. This +is vi compatible, but unlogical. Summary: + :map _l :!ls \| more^M works in Vim when 'b' is not in 'cpo' + :map _l :!ls ^V| more^M works always, in Vim and vi + +To avoid mapping of the characters you type in insert or Command-line mode, +type a CTRL-V first. The mapping in Insert mode is disabled if the 'paste' +option is on. + +Note that when an error is enountered (that causes an error message) the rest +of the mapping is not executed. This is vi-compatible. + +Note that the second character (argument) of the commands @zZtTfF[]rm'`"v +and CTRL-X is not mapped. This was done to be able to use all the named +registers and marks, even when the command with the same name has been +mapped. + +Some examples (given as you type them; e.g., the "^V" is CTRL-V which you +type, but will not show up on the screen): + + :map g /foo^V^Mcwbar^V^[ (replace next "foo" with "bar") + :map! qq quadrillion questions + +Vim will compare what you type with the start of a mapped sequence. If there +is an incomplete match, it will get more characters until there either is a +complete match or until there is no match at all. Example: If you map! "qq", +the first 'q' will not appear on the screen until you type another +character. This is because Vim cannot know if the next character will be a +'q' or not. If the 'timeout' option is on (which is the default) Vim will +only wait for one second (or as long as specified with the 'timeoutlen' +option). After that it assumes that the 'q' is to be interpreted as such. If +type slowly, or your system is slow, reset the 'timeout' option. Then you +might want to set the 'ttimeout' option. See the "Options" chapter |options|. + + *recursive_mapping* +If you include the {lhs} in the {rhs} you have a recursive mapping. When +{lhs} is typed, it will be replaced with {rhs}. When the {lhs} which is +included in {rhs} is encountered it will be replaced with {rhs}, and so on. +This makes it possible to repeat a command an infinite number of times. The +only problem is that the only way to stop this is by causing an error. The +macros to solve a maze uses this, look there for an example. There is one +exception: If the {rhs} starts with {lhs}, that part is not mapped again. +For example: + :map a ab +will execute the "a" command and insert a 'b' in the text. The 'a' in the +{rhs} will not be mapped again. + +If you want to exchange the meaning of two keys you should use the :noremap +command. For example: + :noremap k j + :noremap j k +This will exchange the cursor up and down commands. + +With the normal :map command, when the 'remap' option is on, mapping takes +place until the text is found not to be a part of a {lhs}. For example, if +you use: + :map x y + :map y x +Vim will replace x with y, and then y with x, etc. When this has happened +'maxmapdepth' times (default 1000), Vim will give the error message +"recursive mapping". + +See the file "index" for keys that are not used and thus can be mapped +without losing any builtin function. I suggest you use function keys, +and meta-keys. If you are prepared to lose a command that you hardly ever use +you can make mappings that start with '_' or '-'. You can also use +":help <key>^D" to find out if a key is used for some command. (<key> is the +specific key you want to find out about, ^D is CTRL-D). + +If you include an undo command inside a mapped sequence, this will bring the +text back in the state before executing the macro. This is compatible with +the original Vi, as long as there is only one undo command in the mapped +sequence (having two undo commands in a mapped sequence did not make sense +in the original Vi, you would get back the text before the first undo). + +There are three ways to map a special key: +1. The Vi-compatible method: Map the key code. Often this is a sequence that + starts with <Esc>. To enter a mapping like this you type ":map " and then + you have to type CTRL-V before hitting the function key. Note that when + the key code for the key is in the termcap (the t_ options), it will + automatically be translated into the internal code and become the second + way of mapping (unless the 'k' flag is included in 'cpoptions'). +2. The second method is to use the internal code for the function key. To + enter such a mapping type CTRL-K and then hit the function key, or use + the form "#1", "#2", .. "#9", "#0", "<Up>", "<S-Down>", "<S-F7>", etc. + (see table of keys |key_notation|, all keys from <Up> can be used). The + first ten function keys can be defined in two ways: Just the number, like + "#2", and with "<F>", like "<F2>". Both stand for function key 2. "#0" + refers to function key 10, defined with option 't_f10', which may be + function key zero on some keyboards. The <> form cannot be used when + 'cpoptions' includes the '<' flag. +3. Use the termcap entry, with the form <t_xx>, where "xx" is the name of the + termcap entry. Any string entry can be used. For example: + :map <t_F3> G + Maps function key 13 to "G". This does not work if 'cpoptions' includes + the '<' flag. + +The advantage of the second and third method is that the mapping will work on +different terminals without modification (the function key will be +translated into the same internal code or the actual key code, no matter what +terminal you are using. The termcap must be correct for this to work, and you +must use the same mappings). + +DETAIL: Vim first checks if a sequence from the keyboard is mapped. If it +isn't the terminal key codes are tried (see section 20.2 +|terminal_options|). If a terminal code is found it is replaced with the +internal code. Then the check for a mapping is done again (so you can map an +internal code to something else). What is written into the script file +depends on what is recognized. If the terminal key code was recognized as a +mapping the key code itself is written to the script file. If it was +recognized as a terminal code the internal code is written to the script +file. + + +18. Recovery after a crash *crash_recovery* +========================== + +You have spent several hours typing in that text that has to be finished +next morning, and then disaster strikes: Your computer crashes. + + DON'T PANIC! + +You can recover most of your changes from the files that Vim uses to store +the contents of the file. Mostly you can recover your work with one command: + vim -r filename + +18.1 The swap file *swap_file* + +Vim stores the things you changed in a swap file. Using the original file +you started from plus the swap file you can mostly recover your work. + +You can see the name of the current swap file being used with the command: + + :sw[apname] *:sw* *:swapname* + +The name of the swap file is normally the same as the file you are editing, +with the extension ".swp". On MS-DOS and Win32 machines and when the +'shortname' option is on, any '.' in the original file name is replaced with +'_'. If this file already exists (e.g., when you are recovering from a crash) +a warning is given and another extension is used, ".swo", ".swn", etc. An +existing file will never be overwritten. The swap file is deleted as soon as +Vim stops editing the file. + +Technical: The replacement of '.' with '_' is done to avoid problems with + MS-DOS compatible filesystems (e.g., crossdos, multidos). If Vim + is able to detect that the file is on an MS-DOS-like filesystem, a + flag is set that has the same effect as the 'shortname' option. + This flag is reset when you start editing another file. + + If the ".swp" filename already exists, the last character is + decremented until there is no file with that name or ".swa" is + reached. In the last case, no swap file is created. + +By setting the 'directory' option you can place the swap file in another place +than where the edited file is. +Advantages: +- You will not pollute the directories with ".swp" files. +- When the 'directory' is on another partition, reduce the risk of damaging + the file system where the file is (in a crash). +Disadvantages: +- You can get name collisions from files with the same name but in different + directories (although Vim tries to avoid that by comparing the path name). + This will result in bogus ATTENTION warning messages. +- When you use your home directory, and somebody else tries to edit the same + file, he will not see your swap file and will not get the ATTENTION waring + message. +On the Amiga you can also use a recoverable ram disk, but there is no 100% +guarantee that this works. Putting swap files in a normal ram disk (like RAM: +on the Amiga) or in a place that is cleared when rebooting (like /tmp on Unix) +makes no sense, you will lose the swap file in a crash. + +If you want to put swap files in a fixed place, put a command resembling the +following ones in your .vimrc: + :set dir=dh2:tmp (for Amiga) + :set dir=~/tmp (for Unix) + :set dir=c:\\tmp (for MS-DOS and Win32) +This is also very handy when editing files on floppy. Of course you will have +to create that "tmp" directory for this to work! + +When starting to edit a file, Vim checks if a swap file already exists for +that file. If there is one, you will get a message indicating that something +is wrong: + + ATTENTION + Found a swap file by the name "../doc/vim_ref.txt.swp" + dated: Thu May 16 11:46:31 1996 + file name: ~mool/vim/vim/doc/vim_ref.txt + host name: Kibaale + user name: mool + process ID: 211 (still running) + While opening file "../doc/vim_ref.txt" + dated: Wed May 15 21:38:40 1996 + +You are to take one of two actions: + +1. Quit editing this file, because another edit session is active on this + file. Continuing to edit will result in two versions of the same file. + The one that is written last will overwrite the other one, resulting in + loss of changes. The text "(still running)" indicates that the process + editing this file runs on the same computer (Unix only). When working over + a network you will not see this message, because the process will be + running on another computer. +2. Recover a previously crashed edit session. See below |recovery|. + +Vim cannot always detect that a swap file already exists for a file. This is +the case when the other edit session puts the swap files in another +directory or when the path name for the file is different when editing it on +different machines. + +The swap file is updated after typing 200 characters or when you have not +typed anything for four seconds. This only happens if the buffer was +changed, not when you only moved around. The reason why it is not kept up to +date all the time is that this would slow down normal work too much. You can +change the 200 character count with the 'updatecount' option. You can set +the time with the 'updatetime' option. The time is given in milliseconds. +After writing to the swap file Vim syncs the file to disk. This takes some +time, especially on busy Unix systems. If you don't want this you can set the +'swapsync' option to an empty string. The risk of loosing work becomes bigger +though. On some non-Unix systems (MS-DOS, Amiga) the swap file won't be +written at all. + +If the writing to the swap file is not wanted, it can be switched off by +setting the 'updatecount' option to 0. The same is done when starting Vim +with the "-n" option. Writing can be switched back on by setting the +'updatecount' option to non-zero. Swap files will be created for all buffers +when doing this. But when setting 'updatecount' to zero, the existing swap +files will not be removed, it will only affect files that will be opened +after this. + +If you want to make sure that your changes are in the swap file use this +command: + + *:pre* *:preserve* +:pre[serve] Write all text for all buffers into swap file. The + original file is no longer needed for recovery. {Vi: + emergency exit} + +A Vim swap file can be recognized by the first six characters: "b0VIM ". +After that comes the version number, e.g., "3.0". + + +18.2 Recovery *recovery* + +In most cases recovery is quite easy: Start Vim on the same file you were +editing when the crash happened, with the "-r" option added. Vim will read +the ".swp" file and may read bits and pieces of the original file. + +Example: vim -r vim_ref.txt + +If you were editing without a file name, give an empty string as argument: + vim -r "" + +If there are several swap files that look they may be the one you want to +use, a list is given of these swap files and you are requested to enter the +number of the one you want to use. In case you don't know which one to use, +just try them one by one and check the resulting files if they are what you +expected. + +If you know which swap file needs to be used, you can recover by giving the +swap file name. Vim will then find out the name of the original file from +the swap file. + +Example: Vim -r vim_ref.txt.swo + +This is also handy when the swap file is in another directory than expected. +If this still does not work, see what file names Vim reports and rename the +files accordingly. Check the 'directory' option to see where Vim may have +put the swap file. + +Another way to do recovery is to start Vim and use the ":recover" command. +This is easy when you start Vim to edit a file and you get the "ATTENTION: +Found a swap file ..." message. In this case the single command ":recover" +will do the work. You can also give the name of the file or the swap file to +the recover command: + *:rec* *:recover* +:rec[over] [file] Try to recover [file] from the swap file. If [file] + is not given use the file name for the current + buffer. The current contents of the buffer are lost. + This command fails if the buffer was modified. + +:rec[over]! [file] Like ":recover", but any changes in the current + buffer are lost. + +Vim has some intelligence about what to do if the swap file is corrupt in +some way. If Vim has doubt about what it found, it will give an error +message and insert lines with "???" in the text. If you see an error message +while recovering, search in the file for "???" to see what is wrong. You may +want to cut and paste to get the text you need. + +Be sure that the recovery was successful before overwriting the original +file or deleting the swap file. It is good practice to write the recovered +file elsewhere and run 'diff' to find out if the changes you want are in the +recovered file. + +Once you are sure the recovery is ok delete the swap file. Otherwise, you +will continue to get warning messages that the ".swp" file already exists. + +{Vi: recovers in another way and sends mail if there is something to recover} + + +19. Options *options* +=========== + +Vi has a number of internal variables and switches which can be set to +achieve special effects. These options come in three forms: + toggle can only be on or off *toggle* + number has a numeric value + string has a string value + +19.1 Setting options *set_option* + + *:se* *:set* +:se[t] Show all options that differ from their default value. + +:se[t] all Show all but terminal options. + +:se[t] termcap Show all terminal options. + +:se[t] {option}? Show value of {option}. + +:se[t] {option} Toggle option: set, switch it on. + Number option: show value. + String option: show value. + +:se[t] no{option} Toggle option: Reset, switch it off. + +:se[t] {option}! or +:se[t] inv{option} Toggle option: Invert value. {not in Vi} + +:se[t] {option}& Reset option to its default value. {not in Vi} + +:se[t] {option}={value} or +:se[t] {option}:{value} + Set string or number option to {value}. For numeric + options the value can be given in decimal, hex + (preceded with 0x) or octal (preceded with '0') + (hex and octal are only available for machines which + have the strtol() function). The old value can be + inserted by typing <Tab> (or whatever the value of + 'wildchar' is). See 4.4.2 |cmdline_completion|. + See |option_backslash| for using backslashes in + {value}. + + *:fix* *:fixdel* +:fix[del] Set the value of 't_kD': + 't_kb' is 't_kD' becomes + CTRL-? CTRL-H + not CTRL-? CTRL-? + + (CTRL-? is 0177 octal, 0x7f hex) {not in Vi} + + If your delete key terminal code is wrong, but the + code for backspace is allright, you can put this in + your .vimrc: + :fixdel + This works no matter what the actual code for + backspace is. + + If the backspace key terminal code is + wrong you can use this: + :set t_kb=^V<BS> + :fixdel + Where "^V" is CTRL-V and "<BS>" is the backspace + key. This will only work for terminals with the same + code for the backspace key, you cannot use this in + your .vimrc unless the code for backspace is the same + on all your systems. + + If your <Delete> key sends a strange key sequence (not + CTRL-? or CTRL-H) you cannot use ":fixdel". Then use: + :set t_kD=^V<Delete> + Where "^V" is CTRL-V and "<Delete>" is the delete key. + This will only work on systems with the same terminal + codes for delete. + + Note about Linux: By default the backspace key + produces CTRL-?, which is wrong. You can fix it by + putting this line in your rc.local: + echo "keycode 14 = BackSpace" | loadkeys + +The {option} arguments to ":set" may be repeated. For example: + ":set ai nosi sw=3 ts=3". +If you make an error in one of the arguments an error message will be given +and the text up to the next space will be skipped. Thus following arguments +will be processed. + +For {option} the form "t_xx" may be used to set a termcap option. This will +override the value from the termcap. You can then use it in a mapping. If +the "xx" part contains special characters, use the <t_xx> form: + :set <t_#4>=^[Ot + +The listing from ":set" looks different from Vi. Long string options are put +at the end of the list. The number of options is quite large. The output of +"set all" probably does not fit on the screen, causing Vim to give the +"--more--" message. See the 'more' option. + + *:set_env* +Environment variables in most string options will be expanded. If the +environment variable exists the '$' and the following environment variable +name is replaced with its value. If it does not exist the '$' and the name +are not modified. Any non-id character (not a letter, digit or '_') may +follow the environment variable name. That character and what follows is +appended to the value of the environment variable. Examples: + :set term=$TERM.new + :set path=/usr/$INCLUDE,$HOME/include,. + +Using "~" is like using "$HOME", but it is only recognized at the start of an +option and after a space or comma. + + *option_backslash* +To include white space in a string option value it has to be preceded with a +backslash. To include a backslash you have to use two. Effectively this +means that the number of backslashes in an option value is halved (rounded +down). +A few examples: + :set tags=tags\ /usr/tags results in "tags /usr/tags" + :set tags=tags\\,file results in "tags\,file" + :set tags=tags\\\ file results in "tags\ file" + +For MS-DOS and WIN32 backslashes in file names are mostly not removed. More +precise: For options that expect a file name (those where environment +variables are expanded) a backslash before a normal file name character is not +removed. But a backslash before a special character (space, backslash, comma, +etc.) is used like explained above. + + +19.2 Automatically setting options *auto_setting* + +Besides changing options with the ":set" command, there are three alternatives +to set options automatically for one or more files: + +1. When starting Vim initializations are read from various places. See + |initialization|. Most of them are performed for all editing sessions, + and some of them depend on the directory where Vim is started. +2. If you start editing a new file, the automatic commands are executed. + This can be used to set options for files matching a particular pattern and + many other things. See the section "Automatic commands" |autocommand|. +3. If you start editing a new file, and the 'modeline' option is on, a + number of lines at the beginning and end of the file are checked for + modelines. This is explained here. + + *modeline* +There are two forms of modelines. The first form: + [text]{white}{vi:|vim:|ex:}[white]{options} + +[text] any text or empty +{white} at least one white space (<Space> or <Tab>) +{vi:|vim:|ex:} the string "vi:", "vim:" or "ex:" +[white] optional white space +{options} a list of option settings, separated with white space or ':', + where each part between ':' is the argument for a ":set" + command + +Example: + " vi:noai:sw=3 ts=6" + +The second form (this is compatible with some versions of Vi): + + [text]{white}{vi:|vim:|ex:}[white]set {options}:[text] + +[text] any text or empty +{white} at least one white space (<Space> or <Tab>) +{vi:|vim:|ex:} the string "vi:", "vim:" or "ex:" +[white] optional white space +set the string "set " (note the space) +{options} a list of options, separated with white space, which is the + argument for a ":set" command +: a colon +[text] any text or empty + +Example: + "/* vim: set ai tw=75: */" + +The white space before {vi:|vim:|ex:} is required. This minimizes the chance +that a normal word like "lex:" is caught. There is one exception: "vi:" and +"vim:" can also be at the start of the line (for compatibility with version +3.0). Using "ex:" at the start of the line will be ignored (this could be +short for "example:"). + +The number of lines that are checked can be set with the 'modelines' option. +If 'modeline' is off or 'modelines' is 0 no lines are checked. + +Note that for the first form all of the rest of the line is used, thus a line +like: + "/* vi:ts=4: */" +will give an error message for the trailing "*/". This line is OK: + "/* vi:set ts=4: */" + +If an error is detected the rest of the line is skipped. + +If you want to include a ':' in a set command precede it with a '\'. No other +commands than "set" are supported, for security reasons (somebody might create +a trojan horse text file with modelines). + + +19.3 Saving settings *save_settings* + + *:mk* *:mkexrc* +:mk[exrc] [file] Write current key mappings and changed options to + [file] (default ".exrc" in the current directory), + unless it already exists. {not in Vi} + +:mk[exrc]! [file] Always write current key mappings and changed + options to [file] (default ".exrc" in the current + directory). {not in Vi} + + *:mkv* *:mkvimrc* +:mkv[imrc][!] [file] Like as :mkexrc, but default is ".vimrc" in the + current directory. The ":version" command is also + written to the file. {not in Vi} + +These commands will write ":map" and ":set" commands to a file, in such a way +that when these commands are executed, the current key mappings and options +will be set to the same values. The options 'columns', 'endofline', 'lines', +'modified', 'scroll', 'term' and 'ttyfast' are not included, because these are +terminal or file dependent. Note that the options 'binary', 'textmode', +'paste' and 'readonly' are included, this might not always be what you want. + +A common method is to use a default ".vimrc" file, make some modifications +with ":map" and ":set" commands and write the modified file. First read the +default ".vimrc" in with a command like ":source ~piet/.vimrc.Cprogs", change +the settings and then save them in the current directory with ":mkvimrc!". If +you want to make this file your default .vimrc, move it to your home directory +(on Unix), s: (Amiga) or $VIM directory (MS-DOS). You could also use +autocommands |autocommand| and/or modelines |modeline|. + + +19.4 Options summary *option_summary* + +In the list below all the options are mentioned with their full name and some +with an abbreviation between parens. Both forms may be used. In this +document when an option that can be toggled is "set" that means that ":set +option" is entered. When an option is "reset", ":set nooption" is used. + +Most options are the same in all windows and buffers. There are a few that +are specific to how the text is presented in a window. These can be set to a +different value in each window. For example the 'list' option can be set in +one window and reset in another for the same text, giving both types of view +at the same time. There are a few options that are specific to a certain +file. These can have a different value for each file or buffer. For example +the 'textwith' option can be 78 for a normal text file and 0 for a C +program. + + global one option for all buffers and windows + local to window each window has its own copy of this option + local to buffer each buffer has its own copy of this option + +When creating a new window the option values from the currently active window +are used as a default value for the window-specific options. For the +buffer-specific options this depends on the 's' and 'S' flags in the +'cpoptions' option. If 's' in included (which is the default) the values for +buffer options are copied from the currently active buffer when a buffer is +first entered. If 'S' is present the options are copied each time the buffer +is entered, this is almost like having global options. If 's' and 'S' are not +present, the options are copied from the currently active buffer when the +buffer is created. + +A jump table for the options with a short description can be found at |X_op|. + + *'aleph'* *'al'* +aleph (al) number (default 128 for MS-DOS, 224 otherwise) + global + {not in Vi} + {This option applies only if Vim was compiled with + RIGHTLEFT defined} + The ASCII code for the first letter of the Hebrew alphabet. The + routine that maps the keyboard in Hebrew mode, both in Insert mode + (when hkmap is set) and on the command line (when hitting CTRL-_) + outputs the Hebrew characters in the range [aleph..aleph+26]. + aleph=128 applies to PC code, and aleph=224 applies to ISO 8859-8. + See |vim_rlh.txt|. + + *'autoindent'* *'ai'* *'noautoindent'* *'noai'* +autoindent (ai) toggle (default off) + local to buffer + Copy indent from current line when starting a new line (typing <CR> + in Insert mode or when using the "o" or "O" command). If you do not + type anything on the new line except <BS> and then type <Esc> or + <CR>, the indent is deleted again. When autoindent is on, + formatting (with the "gq" command or when you reach 'textwidth' in + Insert mode) uses the indentation of the first line. When + 'smartindent' or 'cindent' is on the indent is changed in specific + cases. The 'autoindent' option is reset when the 'paste' option is + set. {small difference from Vi: After the indent is deleted when + typing <Esc> or <CR>, the cursor position when moving up or down is + after the deleted indent; Vi puts the cursor somewhere in the deleted + indent}. + + *'autowrite'* *'aw'* *'noautowrite'* *'noaw'* +autowrite (aw) toggle (default off) + global + Write the contents of the file, if it has been modified, on each + :next, :rewind, :previous, :stop, :suspend, :tag, :!, :make, CTRL-] + and CTRL-^ command; and when a CTRL-O, CTRL-I, '<A-Z0-9>, or `<A-Z0-9> + command takes one to another file. + + *'backspace'* *'bs'* +backspace (bs) number (default 0) + global + {not in Vi} + Influences the working of <BS>, <Del>, CTRL-W and CTRL-U in Insert + mode. If set to 0 Vi compatible backspacing is used. When 1 allow + backspacing over newlines. When larger than 1 allow backspacing over + the start of insert. In the last case CTRL-W and CTRL-U stop once at + the start of insert. See |:fixdel| if your <BS> or <Del> key does not + do what you want. + + *'backup'* *'bk'* *'nobackup'* *'nobk'* +backup (bk) toggle (default off) + global + {not in Vi} + Make a backup before overwriting a file. Leave it around after the + file has been successfully written. If you do not want to keep the + backup file, but you do want a backup while the file is being + written, reset this option and set the 'writebackup' option (this is + the default). If you do not want a backup file at all reset both + options (use this if your file system is almost full). See the table + in section 5.4 for more explanations |backup_table|. + + *'backupdir'* *'bdir'* +backupdir (bdir) string (default for Amiga: ".,t:", + for MS-DOS and Win32: ".,c:/tmp,c:/temp" + for Unix: ".,~/tmp,~/") + global + {not in Vi} + List of directories for the backup file, separated with commas. + - The backup file will be created in the first directory in the list + where this is possible. + - Empty means that no backup file will be created ('patchmode' is + impossible!). + - A directory '.' means to put the backup file in the same directory + as the edited file. Characters after the "." are ignored, "./temp" + is handled in the same way as ".". + - Spaces after the comma are ignored, other spaces are considered part + of the directory name. To have a space at the start of a directory + name, precede it with a backslash. + - To include a comma in a directory name precede it with a backslash. + - A directory name may end in an '/'. + - Environment variables are expanded |:set_env|. + - Careful with '\' characters, type one before a space, type two to + get one in the option (see |option_backslash|), for example: + :set bdir=c:\\tmp,\ dir\\,with\\,commas,\\\ dir\ with\ spaces + - For backwards compatibility with Vim version 3.0 a '>' at the start + of the option is removed. + See also 'backup' and 'writebackup' options. + + *'backupext'* *'bex'* +backupext (bex) string (default "~") + global + {not in Vi} + String which is appended to a file name to make the name of the + backup file. The default is quite unusual, because this avoids + accidently overwriting existing files with a backup file. You might + prefer using ".bak", but make sure that you don't have files with + ".bak" that you want to keep. + + *'binary'* *'bin'* *'nobinary'* *'nobin'* +binary (bin) toggle (default off) + local to buffer + {not in Vi} + This option should be set before editing a binary file. You can also + use the "-b" Vim argument. When this option is switched on a few + options will be changed (also when it already was on): + 'textwidth' will be set to 0 + 'wrapmargin' will be set to 0 + 'modeline' will be off + 'textmode' will be off + 'textauto' will be off + 'expandtab' will be off + NOTE: When you start editing a(nother) file while the 'bin' option is + on, settings from the modelines or autocommands may change the + settings again (e.g., 'textwidth'), causing trouble when editing. You + might want to set 'bin' again when the file has been loaded. + The previous values of these options are remembered and restored when + 'bin' is switched fron on to off. Each buffer has its own set of + saved option values, except for 'textauto', which is global. + When writing a file the end-of-line for the last line is only written + if there was one in the original file (normally Vim appends an + end-of-line to the last line if there is none; this would make the + file longer). See the 'endofline' option. + + *'bioskey'* *'biosk'* *'nobioskey'* *'nobiosk'* +bioskey (biosk) toggle (default on) + global + {not in Vi} {Only for MS-DOS} + When on the bios is called to obtain a keyboard character. This works + better to detect CTRL-C, but only works for the console. When using a + terminal over a serial port reset this option. + + *'breakat'* *'brk'* +breakat (brk) string (default " ^I!@*-+_;:,./?") + global + {not in Vi} + This option lets you choose which characters might cause a line + break if 'linebreak' is on. + + *'cindent'* *'cin'* *'nocindent'* *'nocin'* +cindent (cin) toggle (default off) + local to buffer + {not in Vi} + {Only present when compiled with CINDENT enabled, + ":version" says "+cindent" instead of "-cindent"} + Enables automatic C program indenting See 'cinkeys' to set the keys + that trigger reindenting in insert mode and 'cinoptions' to set your + preferred indent style. If 'lisp' is not on and 'equalprg' is empty, + the "=" operator indents using this algorithm rather than calling an + external program. See |C_indenting|. This option is switched off + when 'paste' is set. When you don't like the way 'cindent' works, try + the 'smartindent' option. + +cinkeys (cink) string (default "0{,0},:,0#,!^F,o,O,e") + local to buffer + {not in Vi} + {Only present when compiled with CINDENT enabled} + A list of keys that, when typed in insert mode, cause reindenting of + the current line. Only happens if 'cindent' is on. See + |C_indenting|. + + *'cinoptions'* *'cino'* +cinoptions (cino) string (default "") + local to buffer + {not in Vi} + {Only present when compiled with CINDENT enabled} + The 'cinoptions' affect the way 'cindent' reindents lines in a C + program. See |C_indenting|. + + *'cinwords'* *'cinw'* +cinwords (cinw) string (default "if,else,while,do,for,switch") + local to buffer + {not in Vi} + {Only present when compiled with CINDENT or + SMARTINDENT enabled} + These keywords start an extra indent in the next line when + 'smartindent' or 'cindent' is set. For 'cindent' this is only done at + an appropriate place (inside {}). + + *'cmdheight'* *'ch'* +cmdheight (ch) number (default 1) + global + {not in Vi} + Number of lines to use for the command line. If you are annoyed by + "Hit return ..." caused by long messages, set this option to a larger + value. + + *'columns'* *'co'* +columns (co) number (default 80 or terminal width) + global + {not in Vi} + Number of columns of the screen. Normally this is set by the terminal + initialization and does not have to be set by hand. + + *'comments'* *'com'* +comments (com) string (default + "sr:/*,mb:*,el:*/,://,b:#,:%,:XCOMM,n:>,fb:-") + local to buffer + {not in Vi} + A comma separated list of patterns that can start a comment line. See + |format_comments|. See |option_backslash| about using backslashes to + insert a space. + + *'compatible'* *'cp'* *'nocompatible'* *'nocp'* +compatible (cp) toggle (default off, on when compiled with COMPATIBLE + defined, ":version" shows "+compatible") + global + {not in Vi} + At the moment this option is set, several other options will be set + or reset to make Vim Vi-compatible. Switching this option off has no + effect. See also 'cpoptions'. + + option new value effect + + backspace 0 normal backspace + backup off no backup file + cindent off no C code indentation + cpoptions "bcefFkmorsStx$!%" vi-compatible flags + digraph off no digraphs + esckeys off no <Esc>-keys in Insert mode + expandtab off tabs not expanded to spaces + formatoptions "vt" Vi compatible formatting + gdefault off no default 'g' flag for ":s" + history 0 no commandline history + insertmode off do not start in Insert mode + iskeyword "@,48-57,_" keywords contain alphanumeric + characters and '_' + joinspaces on insert 2 spaces after period + modeline off no modelines + more off no pauses in listings + revins off no reverse insert + ruler off no ruler + scrolljump 1 no jump scroll + scrolloff 0 no scroll offset + shiftround off indent not rounded to shiftwidth + showcmd off command characters not shown + showmode off current mode not shown + smartcase off no automatic ignore case switch + smartindent off no smart indentation + smarttab off no smart tab size + startofline on goto startofline with some commands + textauto off no automatic textmode detection + textwidth 0 no automatic line wrap + tildeop off tilde is not an operator + ttimeout off no terminal timeout + undolevels 0 no multilevel undo + updatecount 0 no swap file + whichwrap "" left-right movements don't wrap + wildchar CTRL-E only when the current value is <Tab> + use CTRL-E for cmdline completion + writebackup off no backup file written + + *'cpoptions'* *'cpo'* +cpoptions (cpo) string (default "BceFs", unless compiled with + COMPATIBLE defined, then all flags are + included) + global + {not in Vi} + Sequence of characters. When a character is present this indicates + vi-compatible behaviour. This is used for things where not being + vi-compatible is mostly or sometimes preferred. 'cpoptions' stands + for 'compatibleoptions'. Commas can be added for readability. + + contains behaviour + b "\|" in a ":map" command is recognized as the end of + the map command. The '\' is included in the mapping, + the text after the '|' is interpreted as the next + command. Use a CTRL-V instead of a backslash to + include the '|' in the mapping. Applies to all + mapping, abbreviation, menu and autocmd commands. + See also |map_bar|. + B A backslash has no special meaning in mappings, + abbreviations and the "to" part of the menu commands. + Remove this flag to be able to use a backslash like a + CTRL-V. This flag must be removed to be able to fully + use the <> notation. For example, the command + ":map X \<Esc>" results in X being mapped to: + 'B' included: "\^[" (^[ is a real <Esc>) + 'B' excluded: "<Esc>" (5 characters) + ('<' excluded in both cases) + < Disable the recognition of special key codes in <> + form in mappings, abbreviations, and the "to" part of + menu commands. For example, the command + ":map X <Tab>" results in X being mapped to: + '<' included: "<Tab>" (5 characters) + '<' excluded: "^I" (^I is a real <Tab>) + Also see the 'k' flag below. + c Searching continues at the end of any match at the + cursor position. When not present searching continues + one character from the cursor position. With 'c' + "abababababab" only gets three matches when repeating + "/abab", without 'c' there are five matches. + e When executing a register with ":@r", always add a + <CR> to the last line, also when the register is not + linewise. If this flag is not present, the register + is not linewise and the last line does not end in a + <CR>, then the last line is put on the command line + and can be edited before hitting <CR>. + f When included, a ":read" command with a file name + argument will set the file name for the current buffer, + if the current buffer doesn't have a file name yet. + F When included, a ":write" command with a file name + argument will set the file name for the current buffer, + if the current buffer doesn't have a file name yet. + k Disable the recognition of raw key codes in + mappings, abbreviations, and the "to" part of menu + commands. For example, if <Key> sends ^[OA (where ^[ + is <Esc>), the command ":map X ^[OA" results in X + being mapped to: + 'k' included: "^[OA" (3 characters) + 'k' excluded: "<Key>" (one key code) + Also see the '<' flag above. + m When included, a showmatch will always wait half a + second. When not included, a showmatch will wait half + a second or until a character is typed. |'showmatch'| + o Line offset to search command is not remembered for + next search. + r Redo ("." command) uses "/" to repeat a search + command, instead of the actually used search string. + s Set buffer options when entering the buffer for the + first time. This is like it is in Vim version 3.0. + And it is the default. If not present the options are + set when the buffer is created. + S Set buffer options always when entering a buffer + (except 'readonly' and 'textmode'). This is the + (most) vi compatible setting. + The options are set to the values in the current + buffer. When you change an option and go to another + buffer, the value is copied. Effectively makes the + buffer options global to all buffers. + + 's' 'S' copy buffer options + no no when buffer created + yes no when buffer first entered (default) + no yes each time when buffer entered (vi comp.) + yes yes when buffer created or first entered + + t Search pattern for the tag command is remembered for + "n" command. Otherwise Vim only puts the pattern in + the history for search pattern, but doesn't change the + last used search pattern. + x <Esc> on the command line executes the command line. + The default in Vim is to abandon the command line, + because <Esc> normally aborts a command. |c_<Esc>| + $ When making a change to one line, don't redisplay the + line, but put a '$' at the end of the changed text. + The changed text will be overwritten when you type the + new text. The line is redisplayed if you type any + command that moves the cursor from the insertion + point. + ! When redoing a filter command, use the last used + external command, whatever it was. Otherwise the last + used -filter- command is used. + % Vi-compatible matching is done for the "%" command. + Parens inside single and double quotes are also + counted, causing a string that contains a paren to + disturb the matching. For example, in a line like + "if (strcmp("foo(", s))" the first paren does not + match the last one. When this flag is not included, + parens inside single and double quotes are treated + specially. When matching a paren outside of quotes, + everyting inside quotes is ignored. When matching a + paren inside quotes, it will find the matching one (if + there is one). This works very well for C programs. + + *'define'* *'def'* +define (def) string (default "^#[ \t]*define") + global + {not in Vi} + Pattern to be used to find a macro definition. It is a search + pattern, just like for the "/" command. The default value is for C + programs. This option is used for the commands like "[i" and "[d" + |include_search|. The 'isident' option is used to recognize the + identifier name after the match. See |option_backslash| about + inserting backslashes to include a space or backslash. + + *'dictionary'* *'dict'* +dictionary (dict) string (default "") + global + {not in Vi} + List of file names, separated by commas, that are used to lookup words + for keyword completion commands |i_CTRL-X_CTRL-K|. Each file should + contain a list of words, one word per line. To include a comma in a + file name precede it with a backslash. Spaces after a comma are + ignored, otherwise spaces are included in the file name. See + |option_backslash| about using backslashes. + + *'digraph'* *'dg'* *'nodigraph'* *'nodg'* +digraph (dg) toggle (default off) + global + {not in Vi} + {Only applies when compiled with DIGRAPHS defined, + check with ":version"} + Enable the entering of digraphs in Insert mode with {char1} <BS> + {char2}. See |digraphs|. + + *'directory'* *'dir'* +directory (dir) string (default for Amiga: ".,t:", + for MS-DOS and Win32: ".,c:\tmp,c:\temp" + for Unix: ".,~/tmp,/tmp") + global + List of directory names for the swap file, separated with commas. + - The swap file will be created in the first directory where this is + possible. + - Empty means that no swap file will be used (recovery is + impossible!). + - A directory '.' means to put the swap file in the same directory as + the edited file. Everything after the "." is ignored, "./temp" is + handled in the same way as ".". + - Spaces after the comma are ignored, other spaces are considered part + of the directory name. To have a space at the start of a directory + name, precede it with a backslash. + - To include a comma in a directory name precede it with a backslash. + - A directory name may end in an ':' or '/'. + - Environment variables are expanded |:set_env|. + - Careful with '\' characters, type one before a space, type two to + get one in the option (see |option_backslash|), for example: + :set dir=c:\\tmp,\ dir\\,with\\,commas,\\\ dir\ with\ spaces + - For backwards compatibility with Vim version 3.0 a '>' at the start + of the option is removed. + Using "." first in the list is recommended. This means that editing + the same file twice will result in a warning. Using "/tmp" on Unix is + discouraged, when the system crashes you lose the swap file. That is + why a "tmp" directory in your home directory is used first. + {Vi: directory to put temp file in, defaults to "/tmp"} + + *'ed'* *'edcompatible'* *'noed'* *'noedcompatible'* +edcompatible (ed) toggle (default off) + global + Makes the 'g' and 'c' flags of the ":substitute" command to be + toggled each time the flag is given. See 11.3 |complex_change|. See + also 'gdefault' option. + + *'endofline'* *'eol'* *'noendofline'* *'noeol'* +endofline (eol) toggle (default on) + local to buffer + {not in Vi} + When writing a file and this option is off and the 'binary' option + is on, no end of line (newline) character will be written for the + last line in the file. This option is automatically set when + starting to edit a new file, unless the file does not have an end of + line (newline) for the last line in the file, in which case it is + reset. Normally you don't have to set or reset this option. When + 'binary' is off the value is not used when writing the file. When + 'binary' is on it is used to remember the presence of a newline for + the last line in the file, so that when you write the file the + situation from the original file can be kept. But you can change it + when you want to. + + *'equalalways'* *'ea'* *'noequalalways'* *'noea'* +equalalways (ea) toggle (default on) + global + {not in Vi} + When on all the windows are automatically made the same size after + splitting or closing a window. When off, splitting a window will + reduce the size of the current window and leave the other windows the + same. When closing a window the extra lines are given the the window + above it. + + *'equalprg'* *'ep'* +equalprg (ep) string (default "") + global + {not in Vi} + External program to use for "=" command. When this option is empty + the internal formatting functions are used ('lisp' or 'cindent'). + Environment variables are expanded |:set_env|. See |option_backslash| + about including spaces and backslashes. + + *'errorbells'* *'eb'* *'noerrorbells'* *'noeb'* +errorbells (eb) toggle (default off) + global + Ring the bell (beep or screen flash) for error messages. This only + makes a difference for error messages, the bell will be used always + for a lot of errors without a message (e.g., hitting <Esc> in Normal + mode). See 'visualbell' on how to make the bell behave like a beep, + screen flash or do nothing. + + *'errorfile'* *'ef'* +errorfile (ef) string (default "AztecC.Err" or "errors.vim") + global + {not in Vi} + Name of the error file for the QuickFix mode (see 5.5 + |:make_makeprg|). Environment variables are expanded |:set_env|. See + |option_backslash| about including spaces and backslashes. + + *'errorformat'* *'efm'* +errorformat (efm) string (default is very long) + global + {not in Vi} + Scanf-like description of the format for the lines in the error file + (see 5.5 |errorformat|). + + *'esckeys'* *'ek'* *'noesckeys'* *'noek'* +esckeys (ek) toggle (default on, off when compiled with COMPATIBLE + defined) + global + {not in Vi} + Function keys that start with an <Esc> are recognized in Insert + mode. When this option is off, the cursor and function keys cannot be + used in Insert mode if they start with an <Esc>. The advantage of + this is that the single <Esc> is recognized immediately, instead of + after one second. Instead of resetting this option, you might want to + try changing the values for 'timeoutlen' and 'ttimeoutlen'. + + *'expandtab'* *'et'* *'noexpandtab'* *'noet'* +expandtab (et) toggle (default off) + local to buffer + {not in Vi} + In Insert mode: Use the appropriate number of spaces to insert a + <Tab>. Spaces are used in indents with the '>' and '<' commands and + when 'autoindent' is on. To insert a real tab when 'expandtab' is + on, use CTRL-V<Tab>. See also ":retab" command in 11.3 |:retab| + and section 4.3.4 |ins_expandtab|. + + *'exrc'* *'noexrc'* +exrc toggle (default off) + global + {not in Vi} + Enables the reading of .vimrc and .exrc in the current directory. If + you switch this option on you should also consider setting the + 'secure' option (see 3.4 |initialization|). Using a local .exrc or + .vimrc is a potential security leak, use with care! + + *'formatoptions'* *'fo'* +formatoptions (fo) string (default "tcq", "vt" when compiled with + COMPATIBLE defined) + local to buffer + {not in Vi} + This is a sequence of letters which describes how automatic + formatting is to be done. See |fo_table|. When the 'paste' option is + on, no formatting is done (like 'formatoptions' is empty). Commas can + be inserted for readability. + + *'formatprg'* *'fp'* +formatprg (fp) string (default "") + global + {not in Vi} + The name of an external program that will be used to format the lines + selected with the "gq" command. The program must take the input on + stdin and produce the output on stdout. The Unix program 'fmt' is + such a program. If this option is an empty string, the internal + format function will be used |C_indenting|. Environment variables are + expanded |:set_env|. See |option_backslash| about including spaces + and backslashes. + + *'gdefault'* *'gd'* *'nogdefault'* *'nogd'* +gdefault (gd) toggle (default off) + global + {not in Vi} + When on, the ":substitute" flag 'g' is default on. This means that + all matches in a line are substituted instead of one. When a 'g' flag + is given to a ":substitute" command, this will toggle the substitution + of all or one match. See 11.3 |complex_change|. + + command 'gdefault' on 'gdefault' off + :s/// subst. all subst. one + :s///g subst. one subst. all + :s///gg subst. all subst. one + + *'guifont'* *'gfn'* +guifont (gfn) string (default "") + global + {not in Vi} + {Only available when compiled with GUI enabled} + This is a list of fonts which should be tried when starting the GUI + version of vim. The fonts are separated with commas. Spaces after a + comma are ignored. To include a comma in a font name precede it with + a backslash. Setting an option requires an extra backslash before a + space and a backslash. See also |option_backslash|. For example: + :set guifont=Screen15,\ 7x13,font\\,with\\,commas + will make vim try to use the font "Screen15" first, and if it fails + it will try to use "7x13" and then "font,with,commas" instead. If + none of the fonts can be loaded, vim will try using other resource + settings (for X, it will use the Vim.font resource), and finally it + will try some builtin default which should always be there ("7x13" in + the case of X). The font names given should be "normal" fonts. Vim + will try to find the related bold and italic fonts. + + *'guioptions'* *'go'* +guioptions (go) string (default "agmr") + global + {not in Vi} + {Only available when compiled with GUI enabled} + This option only has an effect in the GUI version of vim. It is a + sequence of letters which describes what components and options of the + GUI should be used. Valid letters are as follows: + + 'a' Autoselect: If present, then whenever VISUAL mode is started, + or the Visual area extended, vim tries to become the owner of + the windowing system's global selection. This means that the + Visually highlighted text is available for pasting into other + applications as well as into vim itself. When the Visual mode + ends, possibly due to an operation on the text, or when an + application wants to paste the selection, the highlighted text + is automatically yanked into the <"*> GUI selection register. + Thus the selection is still available for pasting into other + applications after the VISUAL mode has ended. + If not present, then vim won't become the owner of the + windowing system's global selection unless explicitly told to + by selecting "Cut" or "Copy" etc from the "Edit" menu (which + have not been implemented yet!). + + 'f' Foreground: Don't use fork() to detatch the GUI from the shell + where it was started. Use this for programs that wait for the + editor to finish (e.g., an e-mail program). Altenatively you + can use "gvim -f" or ":gui -f" to start the GUI in the + foreground. |gui_fork| + + 'm' Menu bar is present when 'm' is included. + 'g' Grey menu items: Make menu items that are not active grey. If + 'g' is not included inactive menu items are not shown at all. + + 'r' Right-hand scrollbar is present when 'r' is included. + 'l' Left-hand scrollbar is present when 'l' is included. + 'b' Bottom (horizontal) scrollbar is present when 'b' is included. + + And yes, you may even have scrollbars on the left AND the right if + you really want to :-). See |gui_scrollbars| for more information. + + *'guipty'* *'noguipty'* +guipty toggle (default off) + global + {not in Vi} + {Only available when compiled with GUI enabled} + Only in the GUI: If on, an attempt is made to open a pseudo-tty for + I/O to/from shell commands. See |gui_pty|. + + *'helpfile'* *'hf'* +helpfile (hf) string (default (Amiga) "vim:vim_help.txt" + (MS-DOS, Win32, OS/2) "$VIM/vim_help.txt" + (Unix) "/usr/local/lib/vim/vim_help.txt") + global + {not in Vi} + Name of the help file. All help files should be placed together in + one directory. Environment variables are expanded |:set_env|. For + example: "$VIM/doc/vim_help.txt". If $VIM is not set, $HOME is also + tried. For Unix the default is adjusted at compile time to where the + help files are being installed. See |option_backslash| about + including spaces and backslashes. + + *'helpheight'* *'hh'* +helpheight (hh) number (default 20) + global + {not in Vi} + Minimal initial height of the help window when it is opened with the + ":help" command. The initial height of the help window is half of the + current window, or (when the 'ea' option is on) the same as other + windows. When the height is less than 'helpheight', the height is + set to 'helpheight'. Set to zero to disable. + + *'hidden'* *'hid'* *'nohidden'* *'nohid'* +hidden (hid) toggle (default off) + global + {not in Vi} + When off the current buffer is unloaded when it is abandoned. When + on the current buffer becomes hidden when starting to edit another + buffer. If the current buffer is also displayed in another window it + does not become hidden. The commands that move through the buffer + list make the current buffer hidden although the 'hidden' option is + off. See also |vim_win.txt|. + + *'highlight'* *'hl'* +highlight (hl) string (default "8b,db,es,hs,mb,Mn,nu,rs,sr,tb,vr,ws") + global + {not in Vi} + This option can be used to set highlighting mode for various + occasions. It is a comma separated list of character pairs. The + first character in a pair gives the occasion, the second the mode to + use for that occasion. The occasions are: + 8 Meta & special keys listed with ":map" + d directories in CTRL-D listing + e error messages + h help file headers + m "--More--" message + M Mode (e.g., "-- INSERT --") + n line number for ":number" and ":#" commands + r return to continue message and yes/no questions + s status lines + t Titles for output from ":set all", ":autocmd" etc. + v Visual mode + w warning messages + The display modes are: + r reverse (termcap entry "mr" and "me") + i italic (termcap entry "ZH" and "ZR") + b bold (termcap entry "md" and "me") + s standout (termcap entry "so" and "se") + u underline (termcap entry "us" and "ue") + n no highlighting + The default is used for occasions that are not included. + + *'history'* *'hi'* +history (hi) number (default 20) + global + {not in Vi} + A history of ":" commands, and a history of previous search patterns + are remembered. This option decides how many entries may be stored in + each of these histories (see |cmdline_editing|). + + *'hkmap'* *'hk'* *'nohkmap'* *'nohk'* +hkmap (kh) toggle (default off) + global + {not in Vi} + {Only available if Vim was compiled with RIGHTLEFT + defined} + When on, the keyboard is mapped for the Hebrew character set. + Normally you would use CTRL-_ in insert mode to toggle this option. + See |vim_rlh.txt|. + + *'icon'* *'noicon'* +icon toggle (default off, on when title can be restored) + global + {not in Vi} + When on the icon of the window will be set to the name of the file + currently being edited. Only the last part of the name is used. Only + works if the terminal supports setting window icons (currently only + Unix xterm and iris-ansi). When Vim was compiled with HAVE_X11 + defined, the original icon will be restored if possible |X11|. + + *'ignorecase'* *'ic'* *'noignorecase'* *'noic'* +ignorecase (ic) toggle (default off) + global + Ignore case in search patterns. Also used when searching in the tags + file. + + *'include'* *'inc'* +include (inc) string (default "^#[ \t]*include") + global + {not in Vi} + Pattern to be used to find an include command. It is a search + pattern, just like for the "/" command (See 6.6, "Pattern + searches" |search_pattern|). The default value is for C programs. + This option is used for the commands "[i", "]I", "[d", etc.. The + 'isfname' option is used to recognize the file name that comes after + the matched pattern. See |option_backslash| about including spaces + and backslashes. + + *'incsearch'* *'is'* *'noincsearch'* *'nois'* +incsearch (is) toggle (default off) + global + {not in Vi} + While typing a search pattern, show immediately where the so far + typed pattern matches. The matched string is highlighted. If the + pattern is invalid or not found, nothing is shown. The screen will + be updated often, this is only useful on fast terminals. + + *'infercase'* *'inf'* *'noinfercase'* *'noinf'* +infercase (inf) toggle (default off) + local to buffer + {not in Vi} + When doing keyword completion in insert mode |ins_completion|, and + 'ignorecase' is also on, the case of the match is adjusted. If the + typed text contains a lowercase letter where the match has an upper + case letter, the completed part is made lower case. If the typed text + has no lower case letters and the match has a lower case letter where + the typed text has an upper case letter, and there is a letter before + it, the completed part is made uppercase. + + *'insertmode'* *'im'* *'noinsertmode'* *'noim'* +insertmode (im) toggle (default off) + global + {not in Vi} + Start the edit of a file in Insert mode. Useful if you want to use + Vim like a modeless editor (use the cursor keys to move around, use + CTRL-O for other commands |i_CTRL-O|). + + *'isfname'* *'isf'* +isfname (isf) string (default for MS-DOS, Win32 and OS/2: + "@,48-57,/,.,-,_,+,,,$,:,\" + for AMIGA: "@,48-57,/,.,-,_,+,,,$,:" + otherwise: "@,48-57,/,.,-,_,+,,,$,:,~") + global + {not in Vi} + The characters given by this option are included in file names and + path names. File names are used for commands like "gf", "[i" and in + the tags file. Besides the characters in this option characters that + are defined by the C function isalpha() are also always included + (this depends on the character set and "locale"). + + The format of this option is a list of parts, separated with commas. + Each part can be a single character number or a range. A range is two + character numbers with '-' in between. A character number can be a + decimal number between 0 and 255 or the ASCII character itself (does + not work for digits). Example: + "_,-,128-140,#-43" (include '_' and '-' and the range + 128 to 140 and '#' to 43) + If a part starts with '^', the following character number or range + will be excluded from the option. The option is interpreted from left + to right. Put the excluded character after the range where it is + included. To include '^' itself use it as the last character of the + option or the end of a range. Example: + "^a-z,#,^" (exclude 'a' to 'z', include '#' and '^') + If the character is '@', all characters where isalpha() returns TRUE + are included. Normally these are the characters a to z and A to Z, + plus accented characters. To include '@' itself use "@-@". Examples: + "@,^a-z" All alphabetic characters, excluding lower + case letters. + "a-z,A-Z,@-@" All letters plus the '@' character. + A comma can be included by using it where a character number is + expected. Example: + "48-57,,,_" Digits, command and underscore. + A comma can be excluded by prepending a '^'. Example: + " -~,^,,9" All characters from space to '~', excluding + comma, plus <Tab>. + See |option_backslash| about including spaces and backslashes. + + *'isident'* *'isi'* +isident (isi) string (default for MS-DOS, Win32 and OS/2: + "@,48-57,_,128-167,224-235" + otherwise: "@,48-57,_,192-255") + global + {not in Vi} + The characters given by this option are included in identifiers. + Identifiers are used in recognizing environment variables and after + a match of the 'define' option. See 'isfname' for a description of + the format of this option. + + *'iskeyword'* *'isk'* +iskeyword (isk) string (default for MS-DOS and Win32: + "@,48-57,_,128-167,224-235" + otherwise: "@,48-57,_,192-255" + but when compiled with COMPATIBLE defined: + "@,48-57,_") + local to buffer + {not in Vi} + Keywords are used in searching and recognizing with many commands: + "*", "[i", etc. See 'isfname' for a description of the format of this + option. For C programs you could use "a-z,A-Z,48-57,_,.,-,>". For a + help file it is set to all non-blank printable characters except '*', + '"' and '|'. When the 'lisp' option is on the '-' character is always + included. + + *'isprint'* *'isp'* +isprint (isp) string (default for MS-DOS and Win32: "@,~-255" + otherwise: "@,161-255") + global + {not in Vi} + The characters given by this option are displayed directly on the + screen. The characters from space (ascii 32) to '~' (ascii 126) are + always displayed directly, even when they are not included in + 'isprint' or excluded. See 'isfname' for a description of the format + of this option. Non-printable characters are displayed with two + characters: + 0 - 31 "^@" - "^_" + 32 - 126 always single characters + 127 "^?" + 128 - 159 "~@" - "~_" + 160 - 254 "| " - "|~" + 255 "~?" + + *'joinspaces'* *'js'* *'nojoinspaces'* *'nojs'* +joinspaces (js) toggle (default on) + global + {not in Vi} + Insert two spaces after a period with a join command. + + *'keywordprg'* *'kp'* +keywordprg (kp) string (default "man") + global + {not in Vi} + Program to use for the "K" command. Environment variables are + expanded |:set_env|. When empty ":help" is used. See + |option_backslash| about including spaces and backslashes. + + *'langmap'* *'lmap'* +langmap (lmap) string (default "") + global + {not in Vi} + {Only included when Vim was compiled with HAVE_LANGMAP + defined (Check ":version" for "+langmap"). + This option allows support for keyboards that have a mode for a + special language. The idea is that when you are typing text in Insert + mode your keyboard is switched in the special language mode, you get + different key codes for the special characters. When in command mode + the 'langmap' option takes care of translating these special + characters to the original meaning of the key. This means you don't + have to change the keyboard mode to be able to execute normal mode + commands. + + Example (for greek): *greek* + :set langmap=ÁA,ÂB,ØC,ÄD,ÅE,ÖF,ÃG,ÇH,ÉI,ÎJ,ÊK,ËL,ÌM,ÍN,ÏO,ÐP,QQ,ÑR,ÓS,ÔT,ÈU,ÙV,WW,×X,ÕY,ÆZ,áa,âb,øc,äd,åe,öf,ãg,çh,éi,îj,êk,ël,ìm,ín,ïo,ðp,qq,ñr,ós,ôt,èu,ùv,òw,÷x,õy,æz + Example (exchanges meaning of z and y for commands): + :set langmap=zy,yz,ZY,YZ + + The 'langmap' option is a list of parts, separated with commas. Each + part can be in one of two forms: + 1. A list of pairs. Each pair is a "from" character immediately + followed by the "to" character. Examples: "aA", "aAbBcC". + 2. A list of "from" characters, a semi-colon and a list of "to" + characters. Example: "abc;ABC" + Example: "aA,fgh;FGH,cCdDeE" + Special characters need to be preceded with a backslash. These are + ";", ',' and backslash itself. + + This will allow you to activate vim actions without having to switch + back and forth between the languages. Your language characters will + be understood as normal vim English characters (according to the + langmap mappings) in the following cases: + o Normal/Visual mode (commands, buffer/register names, user mappings) + o Insert/Replace Mode: Register names after CTRL-R + o Insert/Replace Mode: Mappings + Characters entered in Command-line mode will NOT be affected by + this option. Note that this option can be changed at any time + allowing to switch between mappings for different languages/encodings. + Use a mapping to avoid having to type it each time! + + *'laststatus'* *'ls'* +laststatus (ls) number (default 1) + global + {not in Vi} + The value of this option influences when the last window will have a + status line: + 0: never + 1: only if there are at least two windows + 2: always + The screen looks nicer with a status line if you have several + windows, but it takes another screen line. + + *'linebreak'* *'lbr'* *'nolinebreak'* *'nolbr'* +linebreak (lbr) toggle (default off) + local to window + {not in Vi} + If on Vim will wrap long lines at a character in 'breakat' rather + than at the last character that fits on the screen. Unlike + 'wrapmargin' and 'textwidth', this does not insert newline characters + in the file, it only affects the way the file is displayed, not its + contents. The value of 'showbreak' is used to put in front of wrapped + lines. This option is not used when the 'wrap' option is off. Note + that <Tab> characters after a line break are mostly not displayed + correctly. + + *'lines'* +lines number (default 24 or terminal height) + global + Number of lines in the display. Normally you don't need to set this. + That is done automatically by the terminal initialization code. When + you do set this, and Vim is unable to change the physical number of + lines on the display, redisplaying may be wrong. + + *'lisp'* *'nolisp'* +lisp toggle (default off) + local to buffer + {Only included when compiled with LISPINDENT enabled, + ":version" says "+lispindent" instead of + "-lispindent"} + Lisp mode: When a return is typed in insert mode set the indent for + the next line to Lisp standards (well, sort of). Also happens with + "cc" or "S". 'autoindent' must also be on for this to work. The '-' + character is included in keyword characters. Redefines the "=" + operator to use this same indentation algorithm rather than calling an + external program if 'equalprg' is empty. This option is reset when + 'paste' is set. {Vi: Does it a little bit differently} + + *'list'* *'nolist'* +list toggle (default off) + local to window + List mode: Show tabs as CTRL-I, show end of line with $. Useful to + see the difference between tabs and spaces and for trailing blanks. + Note that this will also affect formatting (set with 'textwidth' or + 'wrapmargin'). + + *'magic'* *'nomagic'* +magic toggle (default on) + global + Changes the special characters that can be used in search patterns. + See section "Pattern searches" |search_pattern|. + + *'makeprg'* *'mp'* +makeprg (mp) string (default "make") + global + {not in Vi} + Program to use for the ":make" command. See |:make_makeprg|. This + option may contain '%' and '#' characters, which are expanded like + when used in a command line. Environment variables are expanded + |:set_env|. See |option_backslash| about including spaces and + backslashes. + + *'maxmapdepth'* *'mmd'* +maxmapdepth (mmd) number (default 1000) + global + {not in Vi} + Maximum number of times a mapping is done without resulting in a + character to be used. This normally catches endless mappings, like + ":map x y" with ":map y x". It still does not catch ":map g wg", + because the 'w' is used before the next mapping is done. See also + |key_mapping|. + + *'maxmem'* *'mm'* +maxmem (mm) number (default 512) + global + {not in Vi} + Maximum amount of memory (in Kbyte) to use for one buffer. When this + limit is reached allocating extra memory for a buffer will cause + other memory to be freed. See also 'maxmemtot'. + + *'maxmemtot'* *'mmt'* +maxmemtot (mmt) number (default 2048, or half the amount of memory + available) + global + {not in Vi} + Maximum amount of memory (in Kbyte) to use for all buffers together. + See also 'maxmem'. + + *'modeline'* *'ml'* *'nomodeline'* *'noml'* +modeline (ml) toggle (default on, off when compiled with COMPATIBLE + defined) + local to buffer + *'modelines'* *'mls'* +modelines (mls) number (default 5) + global + {not in Vi} + If 'modeline' is on 'modelines' gives the number of lines that is + checked for set commands. If 'modeline' is off or 'modelines' is zero + no lines are checked. See 19.1 |modeline|. 'modeline' is reset when + 'compatible' is set. + + *'modified'* *'mod'* *'nomodified'* *'nomod'* +modified (mod) toggle (default off) + local to buffer + {not in Vi} + When on the buffer is considered to be modified. This option is set + by every command that makes a change to the buffer. Only the undo + command may reset it, when all changes have been undone. + + *'more'* *'nomore'* +more toggle (default on, off when compiled with COMPATIBLE + defined) + global + {not in Vi} + Listings pause when the whole screen is filled. Type: + <CR> or <NL> for one more line. + <Space> for the next page. + 'd' for down half a page. + 'q' or CTRL-C to stop the listing. + ':' to stop the listing and enter a command line. + Any other key causes the meaning of the keys to be displayed. + When this option is off there are no pauses, the listing continues + until finished. When 'compatible' is set this option is reset. + Note: The key typed at the "more" prompt is directly obtained from the + terminal, it is not mapped and typeahead is ignored. + + *'mouse'* +mouse string (default "", "a" for MS-DOS and Win32) + global + {not in Vi} + Enable the use of the mouse. Only works for certain terminals + (MS-DOS, Win32 and xterm). The mouse can be enabled for different + modes: + n Normal mode + v Visual mode + i Insert mode + c Command-line mode + h all previous modes when editing a help file + a all previous modes + r for "Hit return ..." question + Normally you would enable the mouse in all four modes with: + :set mouse=a + Note: Normal copy/paste in an xterm can still be used by pressing the + shift key when the mouse is being used by Vim. See |mouse_using|. + + *'mousetime'* *'mouset'* +mousetime (mouset) number (default 500) + global + {not in Vi} + Only for GUI, MS-DOS, Win32 and Unix with xterm. Defines the maximum + time in msec between two mouse clicks for the second click to be + recognized as a multi click. + + *'number'* *'nu'* *'nonumber'* *'nonu'* +number (nu) toggle (default off) + local to window + Print the line number in front of each line. Tip: If you don't like + wrapping lines to mix with the line numbers, set the 'showbreak' + option to eight spaces: + :set showbreak=\ \ \ \ \ \ \ \ + + *'paragraphs'* *'para'* +paragraphs (para) string (default "IPLPPPQPP LIpplpipbp") + global + Specifies the nroff macros that separate paragraphs. These are pairs + of two letters (see section 6.4 |object_motions|). + + *'paste'* *'nopaste'* +paste toggle (default off) + global + {not in Vi} + Put Vim in Paste mode. This is useful if you want to cut or copy + some text from one window and paste it in Vim. This will avoid + unexpected effects. When the 'paste' option is switched on (also when + it was already on): + - mapping in Insert mode is disabled + - abbreviations are disabled + - 'textwidth' is set to 0 + - 'autoindent' is reset + - 'smartindent' is reset + - 'cindent' is reset + - 'lisp' is reset + - 'revins' is reset + - 'ruler' is reset + - 'showmatch' is reset + - 'formatoptions' is used like it is empty + NOTE: When you start editing another file while the 'paste' option is + on, settings from the modelines or autocommands may change the + settings again, causing trouble when pasting text. You might want to + set the 'paste' option again. + When the 'paste' option is reset the mentioned options are restored to + the value before the moment 'paste' was switched from off to on. + Resetting 'paste' before ever setting it does not have any effect. If + you use this often, you could map a function key to the command ":set + invpaste^V^M". + + *'patchmode'* *'pm'* +patchmode (pm) string (default "") + global + {not in Vi} + When non-empty the oldest version of a file is kept. This can be used + to keep the original version of a file if you are changing files in a + source distribution. Only the first time that a file is edited a copy + of the original file will be kept. The name of the copy is the name + of the original file with the string in the 'patchmode' option + appended. This option should start with a dot. Use a string like + ".org". 'backupdir' must not be empty for this to work (Detail: The + backup file is renamed to the patchmode file after the new file has + been succesfully written, that's why it must be possible to write a + backup file). If there was no file to be backed up, an empty file is + created. + + *'path'* *'pa'* +path (pa) string (default on Unix: ".,/usr/include,," + on OS/2: ".,/emx/include,," + other systems: ".,,") + global + {not in Vi} + This is a list of directories which will be searched when using the + gf, [f, ]f, ^Wf and other commands, provided that the file being + searched for has a relative path (not starting with '/'). The + directories in the 'path' option may be relative or absolute. + - Use commas to separate directory names: + :set path=.,/usr/local/include,/usr/include + - Spaces can also be used to separate directory names (for backwards + compatibility with version 3.0). To have a space in a directory + name, precede it with an extra backslash: + :set path=.,/dir/with\\ space + - To include a comma in a directory name precede it with an extra + backslash: + :set path=.,/dir/with\\,comma + - To search relative to the directory where the current file is use + :set path=. + - To search in the current directory use an empty string between two + commas: + :set path=,, + - A directory name may end in a ':' or '/'. + - Environment variables are expanded |:set_env|. + - Careful with '\' characters, type two to get one in the option: + :set path=.,c:\\include + Or just use '/' instead: + :set path=.,c:/include + Don't forget "." or files won't even be found in the same directory as + the file! + + *'readonly'* *'ro'* *'noreadonly'* *'noro'* +readonly (ro) toggle (default off) + local to buffer + {not in Vi} + If on, writes fail unless you use a '!'. Protects you from + accidentally overwriting a file. Default on when Vim is started + in view mode ("vim -v") or when the executable is called "view". + {not in Vi:} When using the ":view" command the 'readonly' option is + set for the newly edited buffer. When using ":w!" the 'readonly' + option is reset for the current buffer. + + *'remap'* *'noremap'* +remap toggle (default on) + global + Allows for mappings to work recursively. If you do not want this for + a single entry, use the :noremap[!] command. + + *'report'* +report number (default 2) + global + Threshold for reporting number of lines changed. When the number of + changed lines is more than 'report' a message will be given for most + ":" commands. For the ":substitute" command the number of + substitutions is used instead of the number of lines. + + *'restorescreen'* *'rs'* *'norestorescreen'* *'nors'* +restorescreen (rs) toggle (default on) + global + {not in Vi} {Windows 95/NT version only} + When set, the screen contents is restored when exiting Vim. This also + happens when executing external commands. + + *'revins'* *'ri'* *'norevins'* *'nori'* +revins (ri) toggle (default off) + global + {not in Vi} + {only when compiled with RIGHTLEFT defined} + Inserting characters in Insert mode will work backwards. See "typing + backwards" |ins_reverse|. This option can be toggled with the CTRL-B + command in Insert mode. This option is reset when 'compatible' or + 'paste' is set. + + *'rightleft'* *'rl'* *'norightleft'* *'norl'* +rightleft (rl) toggle (default off) + local to window + {not in Vi} + {only when compiled with RIGHTLEFT defined} + When on, display orientation becomes right-to-left, i.e., character + that are stored in the file apear from the right to the left. Using + this option, it is possible to edit files for languages that are + written from the right to the left such as Hebrew and Arabic. This + option is per window, so it is possible to edit mixed files + simultaneously, or to view the same file in both ways (this is + sometimes usefull when editing Hebrew TeX--XeT files). See + |vim_rlh.txt|. + + *'ruler'* *'ru'* *'noruler'* *'noru'* +ruler (ru) toggle (default off) + global + {not in Vi} + Show the line and column number of the cursor position in the status + line, separated by a comma. If there are characters in the line that + take two positions on the screen, both the "real" column and the + screen column are shown, separated with a dash. For an empty line + "0-1" is shown. For an empty buffer the line number will also be + zero: "0,0-1". This option is reset when the 'paste' option is set. + If you don't want to see the ruler all the time but want to know where + you are, use "g CTRL-G" |g_CTRL-G|. + + *'scroll'* *'scr'* +scroll (scr) number (default 'lines' / 2) + local to window + Number of lines to scroll with CTRL-U and CTRL-D commands. Will be + set to half the number of lines in the window when the window size + changes. If you give a count to the CTRL-U or CTRL-D command it will + be used as the new value for 'scroll'. Reset to 'lines' / 2 with + ":set scroll=0". {difference from vi: 'scroll' gives the number of + screen lines instead of file lines, makes a difference when lines + wrap} + + *'scrolljump'* *'sj'* +scrolljump (sj) number (default 1) + global + {not in Vi} + Minimal number of lines to scroll when the cursor gets off the + screen (e.g., with "j"). Not used for scroll commands (e.g., CTRL-E, + CTRL-D). Useful if your terminal scrolls very slowly. + + *'scrolloff'* *'so'* +scrolloff (so) number (default 0) + global + {not in Vi} + Minimal number of screen lines to keep above and below the cursor. + This will make some context visible around where you are working. If + you set it to a very large value (999) the cursor line will always be + in the middle of the window (except at the start or end of the file or + when long lines wrap). + + *'sections'* *'sect'* +sections (sect) string (default "SHNHH HUnhsh") + global + Specifies the nroff macros that separate sections. These are pairs of + two letters (See section 6.4 |object_motions|). + + *'secure'* *'nosecure'* +secure toggle (default off) + global + {not in Vi} + When on, ":autocmd", shell and write commands are not allowed in + ".vimrc" and ".exrc" in the current directory and map commands are + displayed. Switch it off only if you know that you will not run into + problems, or when the 'exrc' option is off. On Unix this option is + only used if the ".vimrc" or ".exrc" is not owned by you. This can be + dangerous if the systems allows users to do a "chown". You better set + 'secure' at the end of your ~/.vimrc then. + + *'shell'* *'sh'* +shell (sh) string (default $SHELL or "sh", + MS-DOS and Win32: "command", + OS/2: "cmd") + global + Name of the shell to use for ! and :! commands. When changing the + value also check the 'shelltype', 'shellpipe' and 'shellredir' + options. It is allowed to give an argument to the command, e.g. + "csh -f". See |option_backslash| about including spaces and + backslashes. Environment variables are expanded |:set_env|. + + *'shellpipe'* *'sp'* +shellpipe (sp) string (default ">", "| tee", "|& tee" or "2>&1| tee") + global + {not in Vi} + String to be used to put the output of the ":make" command in the + error file. See also |:make_makeprg|. See |option_backslash| about + including spaces and backslashes. + For the Amiga and MS-DOS the default is ">". The output is directly + saved in a file and not echoed to the screen. + For Unix the default it "| tee". The stdout of the compiler is saved + in a file and echoed to the screen. If the 'shell' option is "csh" or + "tcsh" after initializations, the default becomes "|& tee". If the + 'shell' option is "sh", "ksh", "zsh" or "bash" the default becomes + "2>&1| tee". This means that stderr is also included. + The initialization of this option is done after reading the ".vimrc" + and the other initializations, so that when the 'shell' option is set + there, the 'shellpipe' option changes automatically, unless it was + explicitly set before. + In the future pipes may be used for filtering and this option will + become obsolete (at least for Unix). + + *'shellredir'* *'srr'* +shellredir (srr) string (default ">", ">&" or ">%s 2>&1") + global + {not in Vi} + String to be used to put the output of a filter in a temporary file. + See also |:!|. See |option_backslash| about including spaces and + backslashes. + The name of the temporary file can be represented by "%s" if necessary + (the file name is appended automatically if no %s appears in the value + of this option). + The default is ">". For Unix, if the 'shell' option is "csh", "tcsh" + or "zsh" during initializations, the default becomes ">&". If the + 'shell' option is "sh", "ksh" or "bash" the default becomes + ">%s 2>&1". This means that stderr is also included. + The initialization of this option is done after reading the ".vimrc" + and the other initializations, so that when the 'shell' option is set + there, the 'shellredir' option changes automatically unless it was + explicitly set before. + In the future pipes may be used for filtering and this option will + become obsolete (at least for Unix). + + *'shelltype'* *'st'* +shelltype (st) number (default 0) + global + {not in Vi} + On the Amiga this option influences the way how the commands work + which use a shell. + 0 and 1: always use the shell + 2 and 3: use the shell only to filter lines + 4 and 5: use shell only for ':sh' command + When not using the shell, the command is executed directly. + + 0 and 2: use 'shell -c cmd' to start external commands + 1 and 3: use 'shell cmd' to start external commands + + *'shiftround'* *'sr'* *'noshiftround'* *'nosr'* +shiftround (sr) toggle (default off) + global + {not in Vi} + Round indent to multiple of 'shiftwidth'. Applies to > and < + commands. CTRL-T and CTRL-D in Insert mode always round the indent to + a multiple of 'shiftwidth' (this is vi compatible). + + *'shiftwidth'* *'sw'* +shiftwidth (sw) number (default 8) + local to buffer + Number of spaces to use for each step of (auto)indent. + + *'shortmess'* *'shm'* +shortmess (shm) string (default "") + global + {not in Vi} + This option helps to avoid all the "Hit return" messages caused by + file messages, for example with CTRL-G, and to avoid some other + messages. It is a list of flags: + flag meaning when present + l use "999L, 888C" instead of "999 lines, 888 characters" + m use "[+]" instead of "[Modified]" + r use "[RO]" instead of "[readonly]" + x use "[tx]" instead of "[textmode]" and "[notx]" instead of + "[notextmode]" + f use "(3 of 5)" instead of "(file 3 of 5)" + i use "[noeol]" instead of "[Incomplete last line]" + n use "[New]" instead of "[New File]" + w use "[w]" instead of "written" for file write message. + a all of the above abbreviations + + o overwrite message for writing a file with subsequent message + for reading a file (useful for ":wn" or when 'autowrite' on) + W don't give "written" or "[w]" when writing a file + s don't give "search hit BOTTOM, continuing at TOP" or "search + hit TOP, continuing at BOTTOM" messages + t trunctate file message at the start if it is too long to fit + on the command line, "<" will appear in the left most column. + This gives you the opportunity to avoid that a change between buffers + requires you to hit return, but still gives as useful a message as + possible for the space available. To get the whole message that you + would have got with 'shm' empty, use ":file!" + Useful values: + shm= -- No abbreviation of message. + shm=a -- Abbreviation, but no loss of information. + shm=at -- Abbreviation, and truncate message when necessary. + + *'shortname'* *'sn'* *'noshortname'* *'nosn'* +shortname (sn) toggle (default off) + local to buffer + {not in Vi} + Filenames can be 8 characters plus one extension of 3 characters. + Multiple dots in file names are not allowed. When this option is on, + dots in filenames are replaced with underscores when adding an + extension (".~" or ".swp"). This option is not available for + MS-DOS and Win32, because then it would always be on. This option is + useful when editing files on an MS-DOS compatible filesystem, e.g., + messydos or crossdos. + + *'showbreak'* *'sbr'* +showbreak (sbr) string (default "") + global + {not in Vi} + String to put at the start of lines that have been wrapped. Useful + values are "> " or "+++ ". Only printable characters are allowed, + excluding <Tab> and comma (in a future version the comma might be used + to separate the part that is shown at the end and at the start of a + line). + + *'showcmd'* *'sc'* *'noshowcmd'* *'nosc'* +showcmd (sc) toggle (default on, off for Unix) + global + {not in Vi} + Show (partial) command in status line. Set this option off if your + terminal is slow. + + *'showmatch'* *'sm'* *'noshowmatch'* *'nosm'* +showmatch (sm) toggle (default off) + global + When a bracket is inserted, briefly jump to the matching one. The + jump is only done if the match can be seen on the screen. + A Beep is given if there is no match (no matter if the match can be + seen or not). This option is reset when the 'paste' option is set. + When the 'm' flag is not included in 'cpoptions', typing a character + will immediately move the cursor back to where it belongs. + + *'showmode'* *'smd'* *'noshowmode'* *'nosmd'* +showmode (smd) toggle (default on, off when compiled with COMPATIBLE + defined) + global + If in Insert, Replace or Visual mode put a message on the last line. + Use the 'M' flag in 'highlight' to set the type of highlighting for + this message. + + *'sidescroll'* *'ss'* +sidescroll (ss) number (default 0) + global + {not in Vi} + The minimal number of columns to scroll horizontally. Used only when + the 'wrap' option is off and the cursor is moved off of the screen. + When it is zero the cursor will be put in the middle of the screen. + When using a slow terminal set it to a large number or 0. When using + a fast terminal use a small number or 1. Not used for "zh" and "zl" + commands. + + *'smartcase'* *'scs'* *'nosmartcase'* *'noscs'* +smartcase (scs) toggle (default off) + global + {not in Vi} + Override the 'ignorecase' option if the search pattern contains upper + case characters. Only used when the search pattern is typed and + 'ignorecase' option is on. Used for the commands "/", "?", "n", "N", + ":g" and ":s". Not used for "*", "#", "gd", tag search, etc.. + + *'smartindent'* *'si'* *'nosmartindent'* *'nosi'* +smartindent (si) toggle (default off) + local to buffer + {not in Vi} + {Only included when compiled with SMARTINDENT defined, + check with ":version"} + Do smart autoindenting when starting a new line. Works best for C + programs, but can also be used for other languages. 'cindent' does + something like this, works better in most cases, but is more strict, + see |C_indenting|. When 'cindent' is on setting 'si' has no effect. + Normally 'autoindent' should also be on when using 'smartindent'. + An indent is automatically inserted: + - After a line ending in '{'. + - After a line starting with a keyword from 'cinwords'. + - Before a line starting with '}' (only with the "O" command). + When typing '}' as the first character in a new line, that line is + given the same indent as the matching '{'. + When typing '#' as the first character in a new line, the indent for + that line is removed, the '#' is put in the first column. The indent + is restored for the next line. If you don't want this, use this + mapping: ":inoremap # X^H#", where ^H is entered with CTRL-V CTRL-H. + When using the ">>" command, lines starting with '#' are not shifted + right. + 'smartindent' is reset when the 'paste' option is set. + + *'smarttab'* *'sta'* *'nosmarttab'* *'nosta'* +smarttab (sta) toggle (default off) + global + {not in Vi} + When on, a <Tab> in front of a line inserts 'shiftwidth' positions, + 'tabstop' in other places. When off a <Tab> always inserts 'tabstop' + positions, 'shiftwidth' is only used for ">>" and the like. See also + section 4.3.4 |ins_expandtab|. + + *'splitbelow'* *'sb'* *'nosplitbelow'* *'nosb'* +splitbelow (sb) toggle (default off) + global + {not in Vi} + When on, spliting a window will put the new window below the current + one. + + *'startofline'* *'sol'* *'nostartofline'* *'nosol'* +startofline (sol) toggle (default on) + global + {not in Vi} + When on the commands listed below move the cursor to the first + blank of the line. When off the cursor is kept in the same column + (if possible). This applies to the commands: CTRL-D, CTRL-U, CTRL-B, + CTRL-F, "G", "H", "M", "L", , and to the commands "d", "<<" and ">>" + with a linewise operator and with "%" with a count. This option is + set when the 'compatible' option is set. + + *'suffixes'* *'su'* +suffixes (su) string (default ".bak,~,.o,.h,.info,.swp") + global + {not in Vi} + Files with these suffixes are ignored when multiple files match a + wildcard. See |suffixes|. Commas can be used to separate the + suffixes. Spaces after the comma are ignored. A dot is also seen as + the start of a suffix. To include a dot or comma in a suffix, precede + it with a backslash (see |option_backslash| about including spaces and + backslashes). + + *'swapsync'* *'sws'* +swapsync (sws) string (default "fsync") + global + {not in Vi} + When this option is not empty a swap file is synced to disk after + writing to it. This takes some time, especially on busy unix systems. + When this option is empty parts of the swap file may be in memory and + not written to disk. When the system crashes you may lose more work. + On Unix the system does a sync now and then without Vim asking for it, + so the disadvantage of setting this option off is small. On some + systems the swap file will not be written at all. For a unix system + setting it to "sync" will use the sync() call instead of the default + fsync(), which may work better on some systems. + + *'tabstop'* *'ts'* +tabstop (ts) number (default 8) + local to buffer + Number of spaces that a <Tab> in the file counts for. (See also + ":retab" command in 11.3 |:retab|). + + *'taglength'* *'tl'* +taglength (tl) number (default 0) + global + If non-zero, tags are significant up to this number of characters. + + *'tagrelative'* *'tr'* *'notagrelative'* *'notr'* +tagrelative (tr) toggle (default on, off when compiled with COMPATIBLE + defined) + global + {not in Vi} + If on and using a tag file in another directory, file names in that + tag file are relative to the directory where the tag file is. When + the 'compatible' option is set, this option is reset. + + *'tags'* *'tag'* +tags (tag) string (default "./tags,tags", when compiled with + Emacs tags enabled: "./tags,./TAGS,tags,TAGS") + global + Filenames for the tag command, separated by spaces or commas. To + include a space or comma in a filename, precede it with a backslash + (see |option_backslash| about including spaces and backslashes). + When a file name starts with "./", the '.' is replaced with the path + of the current file. Environment variables are expanded |:set_env|. + Also see |tags_option|. + When Vim was compiled with EMACS_TAGS defined Emacs-style tag files + are also supported. They are automatically recognized. The default + value becomes "./tags,./TAGS,tags,TAGS". If ":version" shows + "+emacs_tags" then the Emacs tags support is included. {Vi: default + is "tags /usr/lib/tags"} + + *'term'* +term string (default is $TERM, if that fails: + on Unix: "ansi" + on Amiga: "amiga" + on MS-DOS: "pcterm" + on OS/2: "os2ansi" + on Win 32: "win32") + global + Name of the terminal. Used for choosing the terminal control + characters. Environment variables are expanded |:set_env|. + For example: + :set term=$TERM + See |termcap|. + + *'terse'* *'noterse'* +terse toggle (default off) + global + {not in Vi} + When set: Add 's' flag to 'shortmess' option (this makes the message + for a search that hits the start or end of the file not being + displayed). When reset: Remove 's' flag from 'shortmess' option. {Vi + shortens a lot of messages} + + *'textauto'* *'ta'* *'notextauto'* *'nota'* +textauto (ta) toggle (default on, off when compiled with COMPATIBLE + defined) + global + {not in Vi} + When starting to edit a file a check is done for the line separator. + If all lines end in <CR><NL> 'textmode' is set, otherwise 'textmode' + is reset. When reading a file, the same is done, but this happens + like 'textmode' has been set appropriately for that file only, the + option is not changed. See |textmode_io|. + + *'textmode'* *'tx'* *'notextmode'* *'notx'* +textmode (tx) toggle (MS-DOS, Win32 and OS/2: default on, others: + default off) + local to buffer + {not in Vi} + When off, <NL> separates lines. When on, <CR><NL> separates lines + and CTRL-Z at end of file is ignored. Only used when reading and + writing files. Set automatically when starting to edit a file and + 'textauto' is on. See |textmode_io|. + + *'textwidth'* *'tw'* +textwidth (tw) number (default 0) + local to buffer + {not in Vi} + Maximum width of text that is being inserted. A longer line will be + broken after white space to get this width. A zero value disables + this. 'textwidth' is set to 0 when the 'paste' option is set. When + 'textwidth' is zero, 'wrapmargin' may be used. See also + 'formatoptions' and |ins_textwidth|. + + *'tildeop'* *'top'* *'notildeop'* *'notop'* +tildeop (top) toggle (default off) + global + {not in Vi} + When on: The tilde command "~" behaves like an operator. + + *'timeout'* *'to'* *'notimeout'* *'noto'* +timeout (to) toggle (default on) + global + *'ttimeout'* *'nottimeout'* +ttimeout toggle (default off) + global + {not in Vi} + These two options together determine the behaviour when part of a + mapped key sequence or keyboard code has been received: + + timeout ttimeout action + off off no time out + on on or off time out on :mappings and key codes + off on time out on key codes + + If there is no time out, Vim will wait until either the complete + mapping or key sequence has been received, or it is clear that there + is no mapping or key sequence for the received characters. For + example: if you have mapped "vl" and Vim has received 'v', the next + character is needed to see if the 'v' is followed by an 'l'. With a + time out Vim will wait for about 1 second for the next character to + arrive. After that the already received characters are interpreted + as single characters. The waiting time can be changed with the + 'timeoutlen' option. + On slow terminals or very busy systems time out may cause + malfunctioning cursor keys. If both options are off, Vim waits + forever after an entered <Esc> if there are key codes that start + with <Esc>. You will have to type <Esc> twice. If you do not have + problems with key codes, but would like to have :mapped key + sequences not time out in 1 second, set the ttimeout option and + reset the timeout option. + + *'timeoutlen'* *'tm'* +timeoutlen (tm) number (default 1000) + global + {not in all versions of Vi} + *'ttimeoutlen'* *'ttm'* +ttimeoutlen (ttm) number (default -1) + global + {not in Vi} + The time in milliseconds that is waited for a key code or mapped key + sequence to complete. Normally only 'timeoutlen' is used and + 'ttimeoutline' is -1. When a different timeout value for key codes is + desired set 'ttimeoutlen' to a non-negative number. + + ttimeoutlen mapping delay key code delay + < 0 'timeoutlen' 'timeoutlen' + >= 0 'timeoutlen' 'ttimeoutlen' + + The timeout only happens when the 'timeout' and 'ttimeout' options + tell so. A useful setting would be + :set timeout timeoutlen=3000 ttimeloutlen=100 + (time out on mapping after three seconds, time out on key codes after + a tenth of a second). + + *'title'* *'notitle'* +title toggle (default off, on when title can be restored) + global + {not in Vi} + When on the title of the window will be set to "VIM - filename", + where filename is the name of the file currently being edited. Only + works if the terminal supports setting window titles (currently Amiga + console, Unix xterm and iris-ansi). + *X11* + When Vim was compiled with HAVE_X11 defined, the original title will + be restored if possible. The output of ":version" will include "+X11" + when HAVE_X11 was defined, otherwise it will be "-X11". This also + works for the icon name |'icon'|. + If the title cannot be restored, it is set to "Thanks for flying Vim". + You will have to restore the title outside of Vim then. When using an + xterm from a remote machine you can use this command: + rsh machine_name xterm -display $DISPLAY & + then the WINDOWID environment variable should be inherited and the + title of the window should change back to what it should be after + exiting Vim (rather than using the "Thanks..." message). + + *'ttybuiltin'* *'tbi'* *'nottybuiltin'* *'notbi'* +ttybuiltin (tbi) toggle (default on) + global + {not in Vi} + When on, the builtin termcaps are searched before the external ones. + When off the builtin termcaps are searched after the external ones. + When this option is changed, you should set the 'term' option next for + the change to take effect, for example: + :set notbi term=$TERM + See also |termcap|. + + *'ttyfast'* *'tf'* *'nottyfast'* *'notf'* +ttyfast (tf) toggle (default off, on when 'term' is xterm, hpterm, + sun-cmd, scren, dtterm or iris-ansi) + global + {not in Vi} + Indicates a fast terminal connection. More characters will be sent to + the screen for redrawing, instead of using insert/delete line + commands. Improves smoothness of redrawing when there are multiple + windows and the terminal does not support a scrolling region. + Also enables the extra writing of characters at the end of each screen + line for lines that wrap. This helps when using copy/paste with the + mouse in an xterm and other terminals. + + *'ttyscroll'* *'tsl'* +ttyscroll (tsl) number (default 999) + global + Maximum number of lines to scroll the screen. If there are more lines + to scroll the window is redrawn. For terminals where scrolling is + very slow and redrawing is not slow this can be set to a small number, + e.g., 3, to speed up displaying. + + *'ttytype'* *'tty'* +ttytype (tty) string (default from $TERM) + global + Alias for 'term', see above. + + *'undolevels'* *'ul'* +undolevels (ul) number (default 100, 1000 for Unix and OS/2, 0 when + compiled with COMPATIBLE defined) + global + {not in Vi} + Maximum number of changes that can be undone. Set to 0 for Vi + compatibility: one level of undo and 'u' undoes itself. Set to a + negative number for no undo at all (saves memory). + + *'updatecount'* *'uc'* +updatecount (uc) number (default 200, 0 when compiled with COMPATIBLE + defined) + global + {not in Vi} + After typing this many characters the swap file will be written to + disk. When zero no swap file will be created at all (see chapter on + recovery |crash_recovery|). 'updatecount' is set to zero by starting + Vim with the "-n" option, see |starting|. When editing in readonly + mode this option will be initialized to 10000. Also see |'swapsync'|. + + *'updatetime'* *'ut'* +updatetime (ut) number (default 4000) + global + {not in Vi} + If this many milliseconds nothing is typed the swap file will be + written to disk (see chapter on recovery |crash_recovery|). + + *'viminfo'* *'vi'* +viminfo (vi) string (default "") + global + {not in Vi} + {only included when Vim was compiled with VIMINFO + defined, use ":version" to check this} + When non-empty, the viminfo file is read upon startup and written + when exiting Vim (see |viminfo_file|). The string should be a comma + separated list of parameters, each consisting of a single character + identifying the particular parameter, followed by a number or string + which specifies the value of that parameter. If a particular + character is left out, then the default value is used for that + parameter. The following is a list characters and their meanings. + char value + ' Maximum number of previously edited files for which + the marks are remembered. This parameter must always + be included when 'viminfo' is non-empty. + f Whether file marks need to be stored. If zero, file + marks ('0 to '9, 'A to 'Z) are not stored. When not + present or when non-zero, they are all stored. '0 is + used for the current cursor position (when exiting or + when doing ":wviminfo"). + r Removable media. The argument is a string (up to the + next ','). This parameter can be given several times. + Each specifies the start of a path for which no marks + will be stored. This is to avoid removable media. + For MS-DOS you could use "ra:,rb:", for Amiga + "rdf0:,rdf1:,rdf2:". Case is ignored. Maximum length + is 50 characters. + " Maximum number of lines saved for each register. If + zero then registers are not saved. If no number given + all lines are saved. Dont forget to put a backslash + before the ", otherwise it will be recognized as the + start of a comment! + : Maximum number of items in the command line history to + be saved. Default: value of 'history'. + / Maximum number of items in the search pattern history + to be saved. If non-zero, then the previous search + and substitute patterns are also saved. Default: + value of 'history'. + Example: + :set viminfo='50,\"1000,:0 + means that marks will be remembered for the last 50 files you edited, + contents of registers (up to 1000 lines each) will be remembered, + command line history will not be saved, and since '/' is not + specified, the default will be used, that is, save all of the search + history, and also the previous search and substitute patterns. + + *'visualbell'* *'vb'* *'novisualbell'* *'novb'* *beep* +visualbell (vb) toggle (default off) + global + {not in Vi} + Use visual bell instead of beeping. The terminal code to display the + visual bell is given with 't_vb'. When no beep of flash is wanted, + Does not work on the Amiga, you always get a screen flash. use ":set + vb t_vb=". Also see 'errorbells'. + + *'warn'* *'nowarn'* +warn toggle (default on) + global + Give a warning message when a shell command is used while the buffer + has been changed. + + *'weirdinvert'* *'wiv'* *'noweirdinvert'* *'nowiv'* +weirdinvert (wiv) toggle (default off) + global + {not in Vi} + Set this option for terminals that have a weird inversion method. + Makes the start/end invert code outputted before every character. + Slows down terminal I/O a lot, but it makes Visual mode work. + + *'whichwrap'* *'ww'* +whichwrap (ww) string (default "b,s", "" when compiled with + COMPATIBLE defined) + global + {not in Vi} + Allow specified keys that move the cursor left/right to wrap to the + previous/next line when the cursor is on the first/last character in + the line. Concatenate characters to allow this for these keys: + char key mode + b <BS> Normal and Visual + s <Space> Normal and Visual + h "h" Normal and Visual + l "l" Normal and Visual + < <Left> Normal and Visual + > <Right> Normal and Visual + [ <Left> Insert and Replace + ] <Right> Insert and Replace + For example: + ":set ww=<,>,[,]" + allows wrap only when cursor keys are used. + When the movement keys are used in combination with a delete or change + operator, the newline also counts for a character. This makes "3h" + different from "3dh" when the cursor crosses the end of a line. This + is also true for "x" and "X", because they do the same as "dl" and + "dh". If you use this, you may also want to use the mapping + ":map <BS> X" to make backspace delete the character in front of the + cursor. When 'compatible' is set, 'whichwrap' is set to "". + + *'wildchar'* *'wc'* +wildchar (wc) number (default <Tab>, CTRL-E when compiled with + COMPATIBLE defined) + global + {not in Vi} + Character you have to type to start wildcard expansion in the + command line. CTRL-E is used when the 'compatible' option is set. + The character is not recognized when used inside a macro. Although + 'wc' is a number option, you can set it to a special key: ":set + wc=<Esc>". + + *'winheight'* *'wh'* +winheight (wh) number (default 0) + global + {not in Vi} + Minimal number of lines for the current window. If the current + window is smaller, its size is increased, at the cost of the height + of other windows. Set it to 999 to make the current window always + fill the screen. Set it to a small number for normal editing. The + height is not adjusted after one of the commands to change the + height of the current window. + + *'wrap'* *'nowrap'* +wrap toggle (default on) + local to window + {not in Vi} + When on, lines longer than the width of the window will wrap and + displaying continues on the next line. When off lines will not wrap + and only part of long lines will be displayed. When the cursor is + moved to a part that is not shown, the screen will scroll horizontally + (also see 'sidescroll' option and |wrap_off|). If you want to break + long lines, see 'textwidth'. + + *'wrapmargin'* *'wm'* +wrapmargin (wm) number (default 0) + local to buffer + Number of characters from the right window border where wrapping + starts. When typing text beyond this limit, a newline will be + inserted and inserting continues on the next line. When 'textwidth' + is non-zero, this option is not used. See also 'formatoptions' and + |ins_textwidth|. {Vi: works differently and less useful} + + *'wrapscan'* *'ws'* *'nowrapscan'* *'nows'* +wrapscan (ws) toggle (default on) + global + Searches wrap around the end of the file. + + *'writeany'* *'wa'* *'nowriteany'* *'nowa'* +writeany (wa) toggle (default off) + global + Allows writing to any file with no need for "!" override. + + *'writebackup'* *'wb'* *'nowritebackup'* *'nowb'* +writebackup (wb) toggle (default on, off when compiled with WRITEBACKUP + not defined or COMPATIBLE defined) + global + {not in Vi} + Make a backup before overwriting a file. The backup is removed after + the file was successfully written, unless the 'backup' option is + also on. Reset this option if your file system is almost full. See + the table in section 5.4 for another explanation |backup_table|. + + *'writedelay'* *'wd'* +writedelay (wd) number (default 0) + global + {not in Vi} + The number of microseconds to wait for each character sent to the + screen. When non-zero, characters are sent to the terminal one by + one. For MS-DOS pcterm this does not work. For debugging purposes. + + +20. Terminal information *terminal_info* +======================== + +Vim uses information about the terminal you are using to fill the screen and +recognize what keys you hit. If this information is not correct the screen +may be messed up or keys may not be recognized. The actions which have to be +performed on the screen are accomplished by outputting a string of +characters. Special keys produce a string of characters. These strings are +stored in the terminal options, see section 20.2 |terminal_options|. + + +20.1 Startup *startup_terminal* + +When Vim is started a default terminal type is assumed. For the Amiga this is +a standard CLI window, for MS-DOS the pc terminal, for Unix an ansi terminal. +A few other terminal types are always available, see below |builtin_terms|. + +You can give the terminal name with the '-T' Vim argument. If it is not given +Vim will try to get the name from the TERM environment variable. + + *termcap* *terminfo* +On Unix the terminfo database or termcap file is used. This is referred to as +"termcap" in all the documentation. At compile time, when running configure, +the choice whether to use terminfo or termcap is done automatically. When +running Vim the output of ":version" will show "+terminfo" if terminfo is +used. If terminfo is not used "-terminfo" is shown. + +On non-Unix systems a termcap is only available if Vim was compiled with +TERMCAP defined. + + *builtin_terms* +Which builtin terminals are available depends on a few defines in feature.h, +which needs to be set at compile time: + define output of ":version" terminals builtin +NO_BUILTIN_TCAPS -builtin_terms none +SOME_BUILTIN_TCAPS +builtin_terms most common ones (default) +ALL_BUILTIN_TCAPS ++builtin_terms all available + +You can see a list of available builtin terminals with ":set term=xxx". + +If the termcap code is included Vim will try to get the strings for the +terminal you are using from the termcap file and the builtin termcaps. Both +are always used, if an entry for the terminal you are using is present. Which +one is used first depends on the 'ttybuiltin' option: + +'ttybuiltin' on 1: builtin termcap 2: external termcap +'ttybuiltin' off 1: external termcap 2: builtin termcap + +If an option is missing in one of them, it will be obtained from the other +one. If an option is present in both, the one first encountered is used. + +Which external termcap file is used varies from system to system and may +depend on the environment variables "TERMCAP" and "TERMPATH". See "man +tgetent". + +For normal editing the terminal will be put into "raw" mode. The strings +defined with 't_ti' and 't_ks' will be sent to the terminal. Normally this +puts the terminal in a state where the termcap codes are valid and activates +the cursor and function keys. When Vim exits the terminal will be put back +into the mode it was before Vim started. The strings defined with 't_te' and +'t_ke' will be sent to the terminal. On the Amiga with commands that execute +an external command (e.g., "!!") the terminal will be put into Normal mode for +a moment. This means that you can stop the output to the screen by hitting a +printing key. Output resumes when you hit <BS>. + +Some termcap entries are wrong in the sense that after sending 't_ks' the +cursor keys send codes different from the codes defined in the termcap. To +avoid this you can set 't_ks' (and 't_ke') to empty strings. This must be +done during initialization (see 3.4 |initialization|), otherwise its too late. + +Some termcap entries assume that the highest bit is always reset. For +example: The cursor-up entry for the amiga could be ":ku=\EA:". But the Amiga +really sends "\233A". This works fine if the highest bit is reset, e.g., when +using an Amiga over a serial line. If the cursor keys don't work, try the +entry ":ku=\233A:". + +Some termcap entries have the entry ":ku=\E[A:". But the Amiga really sends +"\233A". On output "\E[" and "\233" are often equivalent, on input they +aren't. You will have to change the termcap entry, or change the key code with +the :set command to fix this. + +Many cursor key codes start with an <Esc>. Vim must find out if this a single +hit of the <Esc> key or the start of a cursor key sequence. It waits for a +next character to arrive. If it does not arrive within one second a single +<Esc> is assumed. On very slow systems this may fail, causing cursor keys not +to work sometimes. If you discover this problem reset the 'timeout' option. +Vim will wait for the next character to arrive after an <Esc>. If you want to +enter a single <Esc> you must type it twice. Resetting the 'esckeys' option +avoids this problems in Insert mode, but you lose the possibility to use +cursor and function keys in Insert mode. + +On the Amiga the recognition of window resizing is activated only when the +terminal name is "amiga" or "builtin_amiga". + +Some terminals have confusing codes for the cursor keys. The televideo 925 is +such a terminal. It sends a CTRL-H for cursor-left. This would make it +impossible to distinguish a backspace and cursor-left. To avoid this problem +CTRL-H is never recognized as cursor-left. + + *vt100_cursor_keys* *xterm_cursor_keys* +Other terminals (e.g., vt100 and xterm) have cursor keys that send <Esc>OA, +<Esc>OB, etc. Unfortunately these are valid commands in insert mode: Stop +insert, Open a new line above the new one, start inserting 'A', 'B', etc. +Instead of performing these commands Vim will recognize this key sequence as a +cursor key movement. To avoid this you could use these settings: + :set notimeout " don't timeout on mappings + :set ttimeout " do timeout on terminal key codes + :set timeoutlen=100 " timemout in 100 msec +This requires the keys to be hit withing 100msec. When you type you normally +are not that fast. The cursor key codes arrive within 100 msec, so they are +still recognized. + +The default termcap entry for xterm on sun and other platforms does not +contain the entry for scroll regions. Add ":cs=\E[%i%d;%dr:" to the xterm +entry in /etc/termcap and everything should work. + + +20.2 Terminal options *terminal_options* + +The terminal options can be set just like normal options. But they are not +shown with the ":set all" command. Instead use ":set termcap". + +It is always possible to change individual strings by setting the +appropriate option. For example: + + :set t_ce=^V^[[K (CTRL-V, <Esc>, [, K) + +{Vi: no terminal options. You have to exit Vi, edit the termcap entry and +try again} + +The options are listed below. The associated termcap code is always equal to +the last two characters of the option name. Two termcap codes are required: +Cursor positioning and clear screen. + +OUTPUT CODES + option meaning + + t_AL add number of blank lines *t_AL* *'t_AL'* + t_al add new blank line *t_al* *'t_al'* + t_cd clear to end of screen *t_cd* *'t_cd'* + t_ce clear to end of line *t_ce* *'t_ce'* + t_cl clear screen (required!) *t_cl* *'t_cl'* + t_cm cursor motion (required!) *t_cm* *'t_cm'* + t_CS if non-empty, cursor relative to scroll region *t_CS* *'t_CS'* + t_cs define scrolling region *t_cs* *'t_cs'* + t_da if non-empty, lines from above scroll down *t_da* *'t_da'* + t_db if non-empty, lines from below scroll up *t_db* *'t_db'* + t_DL delete number of lines *t_DL* *'t_DL'* + t_dl delete line *t_dl* *'t_dl'* + t_ke out of "keypad transmit" mode *t_ke* *'t_ke'* + t_ks put terminal in "keypad transmit" mode *t_ks* *'t_ks'* + t_md bold mode *t_md* *'t_md'* + t_me Normal mode (undoes t_mr and t_md) *t_me* *'t_me'* + t_mr reverse (invert) mode *t_mr* *'t_mr'* + *t_ms* *'t_ms'* + t_ms if non-empty, cursor can be moved in standout/inverse mode + t_RI cursor number of chars right *t_RI* *'t_RI'* + t_se standout end *t_se* *'t_se'* + t_so standout mode *t_so* *'t_so'* + t_sr scroll reverse (backward) *t_sr* *'t_sr'* + t_te out of "termcap" mode *t_te* *'t_te'* + t_ti put terminal in "termcap" mode *t_ti* *'t_ti'* + t_ue underline end *t_ue* *'t_ue'* + t_us underline mode *t_us* *'t_us'* + t_vb visual bell *t_vb* *'t_vb'* + t_ve cursor visible *t_ve* *'t_ve'* + t_vi cursor invisible *t_vi* *'t_vi'* + t_vs cursor very visible *t_vs* *'t_vs'* + t_ZH italics mode *t_ZH* *'t_ZH'* + t_ZR italics end *t_ZR* *'t_ZR'* + +KEY CODES +Note: Use the <> form if possible + + option name meaning + + t_ku <Up> arrow up *t_ku* *'t_ku'* + t_kd <Down> arrow down *t_kd* *'t_kd'* + t_kr <Right> arrow right *t_kr* *'t_kr'* + t_kl <Left> arrow left *t_kl* *'t_kl'* + <S-Up> shift arrow up + <S-Down> shift arrow down + t_%i <S-Right> shift arrow right *t_%i* *'t_%i'* + t_#4 <S-Left> shift arrow left *t_#4* *'t_#4'* + t_k1 <F1> function key 1 *t_k1* *'t_k1'* + t_k2 <F2> function key 2 *t_k2* *'t_k2'* + t_k3 <F3> function key 3 *t_k3* *'t_k3'* + t_k4 <F4> function key 4 *t_k4* *'t_k4'* + t_k5 <F5> function key 5 *t_k5* *'t_k5'* + t_k6 <F6> function key 6 *t_k6* *'t_k6'* + t_k7 <F7> function key 7 *t_k7* *'t_k7'* + t_k8 <F8> function key 8 *t_k8* *'t_k8'* + t_k9 <F9> function key 9 *t_k9* *'t_k9'* + t_k; <F10> function key 10 *t_k;* *'t_k;'* + t_F1 <F11> function key 11 *t_F1* *'t_F1'* + t_F2 <F12> function key 12 *t_F2* *'t_F2'* + <S-F1) shifted function key 1 + <S-F2> shifted function key 2 + <S-F3> shifted function key 3 + <S-F4> shifted function key 4 + <S-F5> shifted function key 5 + <S-F6> shifted function key 6 + <S-F7> shifted function key 7 + <S-F8> shifted function key 8 + <S-F9> shifted function key 9 + <S-F10> shifted function key 10 + <S-F11> shifted function key 11 + <S-F12> shifted function key 12 + t_%1 <Help> help key *t_%1* *'t_%1'* + t_&8 <Undo> undo key *t_&8* *'t_&8'* + t_kI <Insert> insert key *t_kI* *'t_kI'* + t_kD <Delete> delete key *t_kD* *'t_kD'* + t_kb <BS> backspace key *t_kb* *'t_kb'* + t_kh <Home> home key *t_kh* *'t_kh'* + t_@7 <End> end key *t_@7* *'t_@7'* + t_kP <PageUp> page-up key *t_kP* *'t_kP'* + t_kN <PageDown> page-down key *t_kN* *'t_kN'* + +Note about t_so and t_mr: When the termcap entry "so" is not present the +entry for "mr" is used. And vice versa. The same is done for "se" and "me". +If your terminal supports both inversion and standout mode, you can see two +different modes. If you terminal supports only one of the modes, both will +look the same. + +If inversion or other highlighting does not work correctly, try setting the +'weirdinvert' option. This makes the start-highlight or end-highlight termcap +code to be outputted before every character. This slows down terminal I/O a +lot, but it makes inversion work on some terminals. + +Some termcaps do not include an entry for 'cs' (scroll region), although the +terminal does support it. For example: xterm on a sun. You can use the +builtin_xterm or define t_cs yourself. For example: + + :set t_cs=^V^[[%i%d;%dr + +Where ^V is CTRL-V and ^[ is <Esc>. + +Unfortunately it is not possible to deduct from the termcap how cursor +positioning should be done when using a scrolling region: Relative to the +beginning of the screen or relative to the beginning of the scrolling region. +Most terminals use the first method. A known exception is the MS-DOS console +(pcterm). The 't_CS' option should be set to any string when cursor +positioning is relative to the start of the scrolling region. It should be +set to an empty string otherwise. It is default "yes" when 'term' is +"pcterm". + +Note for xterm users: The shifted cursor keys normally don't work. You can + make them work with the xmodmap command and some mappings in Vim. + + Give these commands in the xterm: + xmodmap -e "keysym Up = Up F13" + xmodmap -e "keysym Down = Down F16" + xmodmap -e "keysym Left = Left F18" + xmodmap -e "keysym Right = Right F19" + + And use these mappings in Vim: + :map <t_F3> <S-Up> + :map! <t_F3> <S-Up> + :map <t_F6> <S-Down> + :map! <t_F6> <S-Down> + :map <t_F8> <S-Left> + :map! <t_F8> <S-Left> + :map <t_F9> <S-Right> + :map! <t_F9> <S-Right> + +Instead of, say, <S-Up> you can use any other command that you want to use the +shift-cursor-up key for. (Note: To help people that have a Sun keyboard with +left side keys F14 is not used because it is confused with the undo key; F15 +is not used, because it does a window-to-front; F17 is not used, because it +closes the window. On other systems you can probably use them) + + +20.3 Window size *window_size* + +[This is about the size of the whole window Vim is using, not a window that is +created with the :split command] + +If you are running Vim on an Amiga and the terminal name is "amiga" or +"builtin_amiga", the amiga-specific window resizing will be enabled. On Unix +systems three methods are tried to get the window size: + +- an ioctl call (TIOCGSIZE or TIOCGWINSZ, depends on your system) +- the environment variables "LINES" and "COLUMNS" +- from the termcap entries "li" and "co" + +If everything fails a default size of 24 lines and 80 columns is assumed. If +a window-resize signal is received the size will be set again. If the window +size is wrong you can use the 'lines' and 'columns' options to set the +correct values. + +One command can be used to set the screen size: + + *:mod* *:mode* +:mod[e] [mode] + +Without argument this only detects the screen size. With MS-DOS it is +possible to switch screen mode. [mode] can be one of these values: + "bw40" 40 columns black&white + "c40" 40 columns color + "bw80" 80 columns black&white + "c80" 80 columns color (most people use this) + "mono" 80 columns monochrome + "c4350" 43 or 50 lines EGA/VGA mode + number mode number to use, depends on your video card + + +20.4 Slow and fast terminals *slow_fast_terminal* + *slow_terminal* + +If you have a fast terminal you may like to set the 'ruler' option. The +cursor position is shown in the status line. If you are using horizontal +scrolling ('wrap' option off) consider setting 'sidescroll' to a small +number. + +If you have a slow terminal you may want to reset the 'showcmd' option. +The command characters will not be shown in the status line. If the terminal +scrolls very slowly, set the 'scrolljump' to 5 or so. If the cursor is moved +off the screen (e.g., with "j") Vim will scroll 5 lines at a time. Another +possibility is to reduce the number of lines that Vim uses with the command +"z<height><CR>". + +If the characters from the terminal are arriving with more than 1 second +between them you might want to set the 'timeout' and/or 'ttimeout' option. +See the "Options" chapter |options|. + +If your terminal does not support a scrolling region, but it does support +insert/delete line commands, scrolling with multiple windows may make the +lines jump up and down. If you don't want this set the 'ttyfast' option. +This will redraw the window instead of scroll it. + +If your terminal scrolls very slowly, but redrawing is not slow, set the +'ttyscroll' option to a small number, e.g., 3. This will make Vim redraw the +screen instead of scrolling, when there are more than 3 lines to be scrolled. + +If you are using Vim over a slow serial line, you might want to try running +Vim inside the "screen" program. Screen will optimize the terminal I/O quite +a bit. + +If you are testing termcap options, but you cannot see what is happening, +you might want to set the 'writedelay' option. When non-zero, one character +is sent to the terminal at a time (does not work for MS-DOS). This makes the +screen updating a lot slower, making it possible to see what is happening. + + *hpterm* +When you are using an hpterm you probably run into a few problems. The best +thing to do is to use an xterm instead. If you want to use an hpterm for some +reason, try (re)setting some options: + :set t_sr= + :set t_al= + :set t_dl= + :set ttyfast redraw screen instead of scrolling + + :set weirdinvert makes highlighting work better, but + slows down screen updating a lot + + +21. Differences from Vi and Ex *vi_differences* +============================== + +Throughout this document differences between Vim and Vi/Ex are given in +curly braces. This chapter only lists what has not been mentioned in +previous chapters. Also see |vim_diff.txt| for an overview. + + +21.1 Missing commands *missing_commands* + +A large number of the "Ex" commands (the commands that start with a colon) +are included. However, there is no Ex mode. + +These commands are in Vi, but not in Vim. + +Q {Vi: go to Ex mode} See |pseudo-Q|. + +:a[ppend] {Vi: append text} *:a* *:append* +:c[hange] {Vi: replace lines} *:c* *:change* +:i[nsert] {Vi: insert text} *:i* *:insert* +:o[pen] {Vi: start editing in open mode}*:o* *:open* +:z {Vi: print some lines} *:z* + + +21.2 Missing options *missing_options* + +These options are in the Unix Vi, but not in Vim. If you try to set one of +them you won't get an error message, but the value is not used and cannot be +printed. + +autoprint (ap) toggle (default on) *'autoprint'* *'ap'* +beautify (bf) toggle (default off) *'beautify'* *'bf'* +flash (fl) toggle (default ??) *'flash'* *'fl'* +graphic (gr) toggle (default off) *'graphic'* *'gr'* +hardtabs (ht) number (default 8) *'hardtabs'* *'ht'* + number of spaces that a <Tab> moves on the display +mesg toggle (default on) *'mesg'* +novice toggle (default ??) *'novice'* +open toggle (default on) *'open'* +optimize (op) toggle (default off) *'optimize'* *'op'* +prompt toggle (default on) *'prompt'* +redraw toggle (default off) *'redraw'* +slowopen (slow) toggle (default off) *'slowopen'* *'slow'* +sourceany toggle (default off) *'sourceany'* +tagstack (tgst) toggle (default on) *'tagstack'* *'tgst'* + enables the tagstack and ":pop". +window (wi) number (default 23) *'window'* *'wi'* +w300 number (default 23) *'w300'* +w1200 number (default 23) *'w1200'* +w9600 number (default 23) *'w9600'* + + +21.3 Limits *limits* + +Vim has only a few limits for the files that can be edited {Vi: can not handle +<Nul> characters and characters above 128, has limited line length, many other +limits}. + +Maximum line length On machines with 16-bit ints (Amiga and MS-DOS real + mode): 32767, otherwise 2147483647 characters. + Longer lines are split. +Maximum number of lines 2147483647 lines. +Maximum file size Only limited by available disk space for the swap + file. +Length of a file name Unix and Win32: 1024 characters, otherwise 128 + characters. +Maximum display width Unix and Win32: 1024 characters, otherwise 255 + characters + +Information for undo and registers are kept in memory, thus when making (big) +changes the amount of (virtual) memory available limits the number of undo +levels and the text that can be kept in registers. Other things are also kept +in memory: Command line history, error messages for Quickfix mode, etc. + + +CONTENTS *reference_contents* *ref* *reference* + +[Note: The commands for multiple windows and buffers are explained in +a different file, see |vim_win.txt|] + + 1. Introduction |intro| + 2. Notation |notation| + 3. Starting Vim |starting| + 3.1 Vim arguments |vim_arguments| + 3.2 Workbench (Amiga only) |workbench| + 3.3 Vim window (Amiga only) |amiga_window| + 3.4 Initialization |initialization| + 3.5 Suspending |suspend| + 3.6 The viminfo file |viminfo_file| + 4. Modes |vim_modes| + 4.1 Introduction + 4.2 Switching from mode to mode |mode_switching| + 4.3 Insert and Replace mode |mode_ins_repl| + 4.3.1 special keys |ins_special_keys| + 4.3.2 special special keys |ins_special_special| + 4.3.3 'textwidth' option |ins_textwidth| + 4.3.4 'expandtab' option |ins_expandtab| + 4.3.5 Replace mode |replace_mode| + 4.3.6 Insert mode completion |ins_completion| + 4.4 Command-line mode |mode_cmdline| + 4.4.1 Command line editing |cmdline_editing| + 4.4.2 Command line completion |cmdline_completion| + 4.4.3 Ex command lines |cmdline_lines| + 4.4.4 Ex command line ranges |cmdline_ranges| + 4.4.5 Ex special characters |cmdline_special| + 4.5 The window contents |window_contents| + 4.6 Abbreviations |abbreviations| + 4.7 Digraphs |digraphs| + 4.8 Using the mouse |mouse_using| + 4.9 Online help |online_help| + 5. Editing files |edit_files| + 5.1 Introduction |edit_intro| + 5.2 Editing a file |edit_a_file| + 5.3 The argument list |argument_list| + 5.4 Writing and quitting |write_quit| + 5.5 Using the QuickFix mode |quickfix| + 5.6 Editing binary files |edit_binary| + 5.7 Automatic commands |autocommand| + 6. Cursor motions |cursor_motions| + 6.1 Left-right motions |left_right_motions| + 6.2 Up-down motions |up_down_motions| + 6.3 Word motions |word_motions| + 6.4 Text object motions |object_motions| + 6.5 Text object selection |object_select| + 6.6 Pattern searches |pattern_searches| + 6.7 Various motions |various_motions| + 7. Scrolling |scrolling| + 8. Tags and special searches |tags_and_searches| + 8.1 Tags |tag_commands| + 8.2 Identifier searches |include_search| + 9. Inserting text |inserting| +10. Deleting text |deleting| +11. Changing text |changing| + 11.1 Delete and insert |delete_insert| + 11.2 Simple changes |simple_change| + 11.3 Complex changes |complex_change| + 11.4 Formatting text |formatting| + 11.5 Formatting C programs |C_indenting| +12. Copying and moving text |copy_move| +13. Visual mode |Visual_mode| +14. Various commands |various| +15. Repeating commands |repeating| + 15.1 Single repeats |single_repeat| + 15.2 Multiple repeats |multi_repeat| + 15.3 Complex repeats |complex_repeat| +16. Undo and redo |undo_redo| +17. Key mapping |key_mapping| +18. Recovery after a crash |crash_recovery| + 18.1 The swap file |swap_file| + 18.2 Recovery |recovery| +19. Options |options| + 19.1 Setting options |set_option| + 19.2 Automatically setting options |auto_setting| + 19.3 Saving settings |save_settings| + 19.4 Options summary |option_summary| +20. Terminal information |terminal_info| + 20.1 Startup |startup| + 20.2 Terminal options |terminal_options| + 20.3 Window size |window_size| + 20.4 Slow and fast terminals |slow_fast_terminal| +21. Differences from Vi and Ex |vi_differences| + 21.1 Missing commands |missing_commands| + 21.2 Missing options |missing_options| + 21.3 Limits |limits| + + vim:tw=78:ts=8:sw=8: |