Vi Command & Function Reference Alan P.W. Hewett Revised for version 2.12 by Mark Horton 1. Author's Disclaimer This document does not claim to be 100% complete. There are a few commands listed in the original document that I was unable to test either because I do not speak lisp, because they required programs we don't have, or because I wasn't able to make them work. In these cases I left the command out. The commands listed in this document have been tried and are known to work. It is expected that prospective users of this document will read it once to get the flavor of everything that vi can do and then use it as a reference document. Experimentation is recommended. If you don't understand a command, try it and see what happens. [Note: In revising this document, I have attempted to make it completely reflect version 2.12 of vi. It does not attempt to document the VAX version (version 3), but with one or two exceptions (wrapmargin, arrow keys) everything said about 2.12 should apply to 3.1. Mark Horton] 2. Notation [option] is used to denote optional parts of a command. Many vi commands have an optional count. [cnt] means that an optional number may precede the command to multiply or iterate the command. {variable item} is used to denote parts of the command which must appear, but can take a number of different values. means that the character or one of the characters in the range described between the two angle brackets is to be typed. For example means the escape key is to be typed. means that a lower case letter is to be typed. ^ means that the character is to be typed as a control character, that is, with the key held down while simultaneously typing the specified character. In this document control characters will be denoted using the upper case character, but ^ and ^ are equivalent. That is, for example, <^D> is equal to <^d>. The most common character abbreviations used in this July 6, 1987 - 2 - list are as follows: escape, octal 033 carriage return, ^M, octal 015 linefeed ^J, octal 012 newline, ^J, octal 012 (same as linefeed) backspace, ^H, octal 010 tab, ^I, octal 011 bell, ^G, octal 07 formfeed, ^L, octal 014 space, octal 040 delete, octal 0177 3. Basics To run vi the shell variable TERM must be defined and exported to your environment. How you do this depends on which shell you are using. You can tell which shell you have by the character it prompts you for commands with. The Bourne shell prompts with `$', and the C shell prompts with `%'. For these examples, we will suppose that you are using an HP 2621 terminal, whose termcap name is ``2621''. 3.1. Bourne Shell To manually set your terminal type to 2621 you would type: TERM=2621 export TERM There are various ways of having this automatically or semi-automatically done when you log in. Suppose you usu- ally dial in on a 2621. You want to tell this to the machine, but still have it work when you use a hardwired terminal. The recommended way, if you have the tset pro- gram, is to use the sequence tset -s -d 2621 > tset$$ . tset$$ rm tset$$ in your .login (for csh) or the same thing using `.' instead of `source' in your .profile (for sh). The above line says July 6, 1987 - 3 - that if you are dialing in you are on a 2621, but if you are on a hardwired terminal it figures out your terminal type from an on-line list. 3.2. The C Shell To manually set your terminal type to 2621 you would type: setenv TERM 2621 There are various ways of having this automatically or semi-automatically done when you log in. Suppose you usu- ally dial in on a 2621. You want to tell this to the machine, but still have it work when you use a hardwired terminal. The recommended way, if you have the tset pro- gram, is to use the sequence tset -s -d 2621 > tset$$ source tset$$ rm tset$$ in your .login.* The above line says that if you are dialing in you are on a 2621, but if you are on a hardwired terminal it figures out your terminal type from an on-line list. 4. Normal Commands Vi is a visual editor with a window on the file. What you see on the screen is vi's current notion of what your file will contain, (at this point in the file), when it is writ- ten out. Most commands do not cause any change in the screen until the complete command is typed. Should you get confused while typing a command, you can abort the command by typing an character. You will know you are back to command level when you hear a . Usually typing an will produce the same result. When vi gets an improp- erly formatted command it rings the . Following are the vi commands broken down by function. 4.1. Entry and Exit To enter vi on a particular file, type vi file The file will be read in and the cursor will be placed at the beginning of the first line. The first screenfull of the file will be displayed on the terminal. _________________________ * On a version 6 system without environments, the invo- cation of tset is simpler, just add the line ``tset -d 2621'' to your .login or .profile. July 6, 1987 - 4 - To get out of the editor, type ZZ If you are in some special mode, such as input mode or the middle of a multi-keystroke command, it may be necessary to type first. 4.2. Cursor and Page Motion NOTE: The arrow keys (see the next four commands) on certain kinds of terminals will not work with the PDP-11 version of vi. The control versions or the hjkl versions will work on any terminal. Experienced users prefer the hjkl keys because they are always right under their fingers. Beginners often prefer the arrow keys, since they do not require memorization of which hjkl key is which. The mnemonic value of hjkl is clear from looking at the keyboard of an adm3a. [cnt] or [cnt]h or [cnt]<- Move the cursor to the left one character. Cursor stops at the left margin of the page. If cnt is given, these commands move that many spaces. [cnt]^N or [cnt]j or [cnt] or [cnt] Move down one line. Moving off the screen scrolls the window to force a new line onto the screen. Mnemonic: Next [cnt]^P or [cnt]k or [cnt]|^ Move up one line. Moving off the top of the screen forces new text onto the screen. Mnemonic: Previous [cnt] or [cnt]l or [cnt]-> Move to the right one character. Cursor will not go beyond the end of the line. [cnt]- Move the cursor up the screen to the begin- ning of the next line. Scroll if necessary. [cnt]+ or [cnt] Move the cursor down the screen to the beginning of the next line. Scroll up if necessary. [cnt]$ Move the cursor to the end of the line. If there is a count, move to the end of the line "cnt" lines forward in the file. July 6, 1987 - 5 - ^ Move the cursor to the beginning of the first word on the line. 0 Move the cursor to the left margin of the current line. [cnt]| Move the cursor to the column specified by the count. The default is column zero. [cnt]w Move the cursor to the beginning of the next word. If there is a count, then move forward that many words and position the cursor at the beginning of the word. Mnemonic: next- word [cnt]W Move the cursor to the beginning of the next word which follows a "white space" (,, or ). Ignore other punc- tuation. [cnt]b Move the cursor to the preceding word. Mnemonic: backup-word [cnt]B Move the cursor to the preceding word that is separated from the current word by a "white space" (,, or ). [cnt]e Move the cursor to the end of the current word or the end of the "cnt"'th word hence. Mnemonic: end-of-word [cnt]E Move the cursor to the end of the current word which is delimited by "white space" (,, or ). [line number]G Move the cursor to the line specified. Of particular use are the sequences "1G" and "G", which move the cursor to the beginning and the end of the file respectively. Mnemonic: Go-to NOTE: The next four commands (^D, ^U, ^F, ^B) are not true motion commands, in that they cannot be used as the object of commands such as delete or change. [cnt]^D Move the cursor down in the file by "cnt" lines (or the last "cnt" if a new count isn't given. The initial default is half a page.) The screen is simultaneously scrolled up. Mnemonic: Down [cnt]^U Move the cursor up in the file by "cnt" lines. The screen is simultaneously July 6, 1987 - 6 - scrolled down. Mnemonic: Up [cnt]^F Move the cursor to the next page. A count moves that many pages. Two lines of the previous page are kept on the screen for continuity if possible. Mnemonic: Forward- a-page [cnt]^B Move the cursor to the previous page. Two lines of the current page are kept if possi- ble. Mnemonic: Backup-a-page [cnt]( Move the cursor to the beginning of the next sentence. A sentence is defined as ending with a ".", "!", or "?" followed by two spaces or a . [cnt]) Move the cursor backwards to the beginning of a sentence. [cnt]} Move the cursor to the beginning of the next paragraph. This command works best inside nroff documents. It understands two sets of nroff macros, -ms and -mm, for which the commands ".IP", ".LP", ".PP", ".QP", "P", as well as the nroff command ".bp" are con- sidered to be paragraph delimiters. A blank line also delimits a paragraph. The nroff macros that it accepts as paragraph delim- iters is adjustable. See paragraphs under the Set Commands section. [cnt]{ Move the cursor backwards to the beginning of a paragraph. ]] Move the cursor to the next "section", where a section is defined by two sets of nroff macros, -ms and -mm, in which ".NH", ".SH", and ".H" delimit a section. A line begin- ning with a sequence, or a line beginning with a "{" are also considered to be section delimiters. The last option makes it useful for finding the beginnings of C functions. The nroff macros that are used for section delimiters can be adjusted. See sections under the Set Commands section. [[ Move the cursor backwards to the beginning of a section. % Move the cursor to the matching parenthesis or brace. This is very useful in C or lisp code. If the cursor is sitting on a ( ) { or } the cursor is moved to the matching July 6, 1987 - 7 - character at the other end of the section. If the cursor is not sitting on a brace or a parenthesis, vi searches forward until it finds one and then jumps to the match mate. [cnt]H If there is no count move the cursor to the top left position on the screen. If there is a count, then move the cursor to the beginning of the line "cnt" lines from the top of the screen. Mnemonic: Home [cnt]L If there is no count move the cursor to the beginning of the last line on the screen. If there is a count, then move the cursor to the beginning of the line "cnt" lines from the bottom of the screen. Mnemonic: Last M Move the cursor to the beginning of the mid- dle line on the screen. Mnemonic: Middle m This command does not move the cursor, but it marks the place in the file and the char- acter "" becomes the label for refer- ring to this location in the file. See the next two commands. Mnemonic: mark NOTE: The mark command is not a motion, and cannot be used as the target of commands such as delete. ' Move the cursor to the beginning of the line that is marked with the label "". ` Move the cursor to the exact position on the line that was marked with with the label "". '' Move the cursor back to the beginning of the line where it was before the last "non- relative" move. A "non-relative" move is something such as a search or a jump to a specific line in the file, rather than mov- ing the cursor or scrolling the screen. `` Move the cursor back to the exact spot on the line where it was located before the last "non-relative" move. 4.3. Searches The following commands allow you to search for items in a file. [cnt]f{chr} July 6, 1987 - 8 - Search forward on the line for the next or "cnt"'th occurrence of the character "chr". The cursor is placed at the character of interest. Mnemonic: find character [cnt]F{chr} Search backwards on the line for the next or "cnt"'th occurrence of the character "chr". The cursor is placed at the character of interest. [cnt]t{chr} Search forward on the line for the next or "cnt"'th occurrence of the character "chr". The cursor is placed just preceding the character of interest. Mnemonic: move cur- sor up to character [cnt]T{chr} Search backwards on the line for the next or "cnt"'th occurrence of the character "chr". The cursor is placed just preceding the character of interest. [cnt]; Repeat the last "f", "F", "t" or "T" com- mand. [cnt], Repeat the last "f", "F", "t" or "T" com- mand, but in the opposite search direction. This is useful if you overshoot. [cnt]/[string]/ Search forward for the next occurrence of "string". Wrap around at the end of the file does occur. The final is not required. [cnt]?[string]? Search backwards for the next occurrence of "string". If a count is specified, the count becomes the new window size. Wrap around at the beginning of the file does occur. The final is not required. n Repeat the last /[string]/ or ?[string]? search. Mnemonic: next occurrence. N Repeat the last /[string]/ or ?[string]? search, but in the reverse direction. :g/[string]/[editor command] July 6, 1987 - 9 - Using the : syntax it is possible to do glo- bal searches ala the standard UNIX "ed" edi- tor. 4.4. Text Insertion The following commands allow for the insertion of text. All multicharacter text insertions are terminated with an character. The last change can always be undone by typing a u. The text insert in insertion mode can contain newlines. a{text} Insert text immediately following the cursor position. Mnemonic: append A{text} Insert text at the end of the current line. Mnemonic: Append i{text} Insert text immediately preceding the cursor position. Mnemonic: insert I{text} Insert text at the beginning of the current line. o{text} Insert a new line after the line on which the cursor appears and insert text there. Mnemonic: open new line O{text} Insert a new line preceding the line on which the cursor appears and insert text there. 4.5. Text Deletion The following commands allow the user to delete text in various ways. All changes can always be undone by typing the u command. [cnt]x Delete the character or characters starting at the cursor position. [cnt]X Delete the character or characters starting at the character preceding the cursor posi- tion. D Deletes the remainder of the line starting at the cursor. Mnemonic: Delete the rest of line [cnt]d{motion} Deletes one or more occurrences of the specified motion. Any motion from sections 4.1 and 4.2 can be used here. The d can be stuttered (e.g. [cnt]dd) to delete cnt lines. July 6, 1987 - 10 - 4.6. Text Replacement The following commands allow the user to simultaneously delete and insert new text. All such actions can be undone by typing u following the command. r Replaces the character at the current cursor position with . This is a one charac- ter replacement. No is required for termination. Mnemonic: replace character R{text} Starts overlaying the characters on the screen with whatever you type. It does not stop until an is typed. [cnt]s{text}Substitute for "cnt" characters beginning at the current cursor position. A "$" will appear at the position in the text where the "cnt"'th character appears so you will know how much you are erasing. Mnemonic: substi- tute [cnt]S{text}Substitute for the entire current line (or lines). If no count is given, a "$" appears at the end of the current line. If a count of more than 1 is given, all the lines to be replaced are deleted before the insertion begins. [cnt]c{motion}{text} Change the specified "motion" by replacing it with the insertion text. A "$" will appear at the end of the last item that is being deleted unless the deletion involves whole lines. Motion's can be any motion from sections 4.1 or 4.2. Stuttering the c (e.g. [cnt]cc) changes cnt lines. 4.7. Moving Text Vi provides a number of ways of moving chunks of text around. There are nine buffers into which each piece of text which is deleted or "yanked" is put in addition to the "undo" buffer. The most recent deletion or yank is in the "undo" buffer and also usually in buffer 1, the next most recent in buffer 2, and so forth. Each new deletion pushes down all the older deletions. Deletions older than 9 disap- pear. There is also a set of named registers, a-z, into which text can optionally be placed. If any delete or replacement type command is preceded by ", that named buffer will contain the text deleted after the command is executed. For example, "a3dd will delete three lines start- ing at the current line and put them in buffer "a.* There _________________________ July 6, 1987 - 11 - are two more basic commands and some variations useful in getting and putting text into a file. ["][cnt]y{motion} Yank the specified item or "cnt" items and put in the "undo" buffer or the specified buffer. The variety of "items" that can be yanked is the same as those that can be deleted with the "d" command or changed with the "c" command. In the same way that "dd" means delete the current line and "cc" means replace the current line, "yy" means yank the current line. ["][cnt]Y Yank the current line or the "cnt" lines starting from the current line. If no buffer is specified, they will go into the "undo" buffer, like any delete would. It is equivalent to "yy". Mnemonic: Yank ["]p Put "undo" buffer or the specified buffer down after the cursor. If whole lines were yanked or deleted into the buffer, then they will be put down on the line following the line the cursor is on. If something else was deleted, like a word or sentence, then it will be inserted immediately following the cursor. Mnemonic: put buffer It should be noted that text in the named buffers remains there when you start editing a new file with the :e file command. Since this is so, it is possible to copy or delete text from one file and carry it over to another file in the buffers. However, the undo buffer and the ability to undo are lost when changing files. ["]P Put "undo" buffer or the specified buffer down before the cursor. If whole lines where yanked or deleted into the buffer, then they will be put down on the line preceding the line the cursor is on. If something else was deleted, like a word or sentence, then it will be inserted immedi- ately preceding the cursor. _________________________ * Referring to an upper case letter as a buffer name (A-Z) is the same as referring to the lower case letter, except that text placed in such a buffer is ap- pended to it instead of replacing it. July 6, 1987 - 12 - [cnt]>{motion} The shift operator will right shift all the text from the line on which the cursor is located to the line where the motion is located. The text is shifted by one shiftwidth. (See section 6.) >> means right shift the current line or lines. [cnt]<{motion} The shift operator will left shift all the text from the line on which the cursor is located to the line where the item is located. The text is shifted by one shiftwidth. (See section 6.) << means left shift the current line or lines. Once the line has reached the left margin it is not further affected. [cnt]={motion} Prettyprints the indicated area according to lisp conventions. The area should be a lisp s-expression. 4.8. Miscellaneous Commands Vi has a number of miscellaneous commands that are very use- ful. They are: ZZ This is the normal way to exit from vi. If any changes have been made, the file is written out. Then you are returned to the shell. ^L Redraw the current screen. This is useful if someone "write"s you while you are in "vi" or if for any reason garbage gets onto the screen. ^R On dumb terminals, those not having the "delete line" function (the vt100 is such a terminal), vi saves redrawing the screen when you delete a line by just marking the line with an "@" at the beginning and blank- ing the line. If you want to actually get rid of the lines marked with "@" and see what the page looks like, typing a ^R will do this. . "Dot" is a particularly useful command. It repeats the last text modifying command. Therefore you can type a command once and then to another place and repeat it by just typing ".". u Perhaps the most important command in the editor, u undoes the last command that changed the buffer. Mnemonic: undo July 6, 1987 - 13 - U Undo all the text modifying commands per- formed on the current line since the last time you moved onto it. [cnt]J Join the current line and the following line. The is deleted and the two lines joined, usually with a space between the end of the first line and the beginning of what was the second line. If the first line ended with a "period", then two spaces are inserted. A count joins the next cnt lines. Mnemonic: Join lines Q Switch to ex editing mode. In this mode vi will behave very much like ed. The editor in this mode will operate on single lines normally and will not attempt to keep the "window" up to date. Once in this mode it is also possible to switch to the open mode of editing. By entering the command [line number]open you enter this mode. It is similar to the normal visual mode except the window is only one line long. Mnemonic: Quit visual mode ^] An abbreviation for a tag command. The cur- sor should be positioned at the beginning of a word. That word is taken as a tag name, and the tag with that name is found as if it had been typed in a :tag command. [cnt]!{motion}{UNIX cmd} Any UNIX filter (e.g. command that reads the standard input and outputs something to the standard output) can be sent a section of the current file and have the output of the command replace the original text. Useful examples are programs like cb, sort, and nroff. For instance, using sort it would be possible to sort a section of the current file into a new list. Using !! means take a line or lines starting at the line the cur- sor is currently on and pass them to the UNIX command. NOTE: To just escape to the shell for one command, use :!{cmd}, see section 5. z{cnt} This resets the current window size to "cnt" lines and redraws the screen. 4.9. Special Insert Characters There are some characters that have special meanings during insert modes. They are: July 6, 1987 - 14 - ^V During inserts, typing a ^V allows you to quote control characters into the file. Any character typed after the ^V will be inserted into the file. [^]^D or [0]^D <^D> without any argument backs up one shiftwidth. This is necessary to remove indentation that was inserted by the autoin- dent feature. ^<^D> temporarily removes all the autoindentation, thus placing the cursor at the left margin. On the next line, the previous indent level will be restored. This is useful for putting "labels" at the left margin. 0<^D> says remove all autoin- dents and stay that way. Thus the cursor moves to the left margin and stays there on successive lines until 's are typed. As with the , the <^D> is only effec- tive before any other "non-autoindent" con- trolling characters are typed. Mnemonic: Delete a shiftwidth ^W If the cursor is sitting on a word, <^W> moves the cursor back to the beginning of the word, thus erasing the word from the insert. Mnemonic: erase Word The backspace always serves as an erase dur- ing insert modes in addition to your normal "erase" character. To insert a into your file, use the <^V> to quote it. 5. : Commands Typing a ":" during command mode causes vi to put the cursor at the bottom on the screen in preparation for a command. In the ":" mode, vi can be given most ed commands. It is also from this mode that you exit from vi or switch to dif- ferent files. All commands of this variety are terminated by a , , or . :w[!] [file] Causes vi to write out the current text to the disk. It is written to the file you are editing unless "file" is supplied. If "file" is supplied, the write is directed to that file instead. If that file already exists, vi will not perform the write unless the "!" is supplied indicating you really want to destroy the older copy of the file. :q[!] Causes vi to exit. If you have modified the file you are looking at currently and haven't written it out, vi will refuse to exit unless the "!" is supplied. July 6, 1987 - 15 - :e[!] [+[cmd]] [file] Start editing a new file called "file" or start editing the current file over again. The command ":e!" says "ignore the changes I've made to this file and start over from the beginning". It is useful if you really mess up the file. The optional "+" says instead of starting at the beginning, start at the "end", or, if "cmd" is supplied, exe- cute "cmd" first. Useful cases of this are where cmd is "n" (any integer) which starts at line number n, and "/text", which searches for "text" and starts at the line where it is found. ^^ Switch back to the place you were before your last tag command. If your last tag command stayed within the file, ^^ returns to that tag. If you have no recent tag com- mand, it will return to the same place in the previous file that it was showing when you switched to the current file. :n[!] Start editing the next file in the argument list. Since vi can be called with multiple file names, the ":n" command tells it to stop work on the current file and switch to the next file. If the current file was modifies, it has to be written out before the ":n" will work or else the "!" must be supplied, which says discard the changes I made to the current file. :n[!] file [file file ...] Replace the current argument list with a new list of files and start editing the first file in this new list. :r file Read in a copy of "file" on the line after the cursor. :r !cmd Execute the "cmd" and take its output and put it into the file after the current line. :!cmd Execute any UNIX shell command. :ta[!] tag Vi looks in the file named tags in the current directory. Tags is a file of lines in the format: tag filename vi-search-command July 6, 1987 - 16 - If vi finds the tag you specified in the :ta command, it stops editing the current file if necessary and if the current file is up to date on the disk and switches to the file specified and uses the search pattern speci- fied to find the "tagged" item of interest. This is particularly useful when editing multi-file C programs such as the operating system. There is a program called ctags which will generate an appropriate tags file for C and f77 programs so that by saying :ta function you will be switched to that function. It could also be useful when editing multi-file documents, though the tags file would have to be generated manu- ally. 6. Special Arrangements for Startup Vi takes the value of $TERM and looks up the charac- teristics of that terminal in the file /etc/termcap. If you don't know vi's name for the terminal you are working on, look in /etc/termcap. When vi starts, it attempts to read the variable EXINIT from your environment.* If that exists, it takes the values in it as the default values for certain of its internal con- stants. See the section on "Set Values" for further details. If EXINIT doesn't exist you will get all the nor- mal defaults. Should you inadvertently hang up the phone while inside vi, or should the computer crash, all may not be lost. Upon returning to the system, type: vi -r file This will normally recover the file. If there is more than one temporary file for a specific file name, vi recovers the newest one. You can get an older version by recovering the file more than once. The command "vi -r" without a file name gives you the list of files that were saved in the last system crash (but not the file just saved when the phone was hung up). 7. Set Commands Vi has a number of internal variables and switches which can be set to achieve special affects. These options come in _________________________ * On version 6 systems Instead of EXINIT, put the startup commands in the file .exrc in your home direc- tory. July 6, 1987 - 17 - three forms, those that are switches, which toggle from off to on and back, those that require a numeric value, and those that require an alphanumeric string value. The toggle options are set by a command of the form: :set option and turned off with the command: :set nooption Commands requiring a value are set with a command of the form: :set option=value To display the value of a specific option type: :set option? To display only those that you have changed type: :set and to display the long table of all the settable parameters and their current values type: :set all Most of the options have a long form and an abbrevia- tion. Both are listed in the following table as well as the normal default value. To arrange to have values other than the default used every time you enter vi, place the appropriate set command in EXINIT in your environment, e.g. EXINIT='set ai aw terse sh=/bin/csh' export EXINIT or setenv EXINIT 'set ai aw terse sh=/bin/csh' for sh and csh, respectively. These are usually placed in your .profile or .login. If you are running a system without environments (such as version 6) you can place the set command in the file .exrc in your home directory. autoindent ai Default: noai Type: toggle When in autoindent mode, vi helps you indent code by starting each line in the same column as the preceding line. Tabbing to July 6, 1987 - 18 - the right with or <^T> will move this boundary to the right, and it can be moved to the left with <^D>. autoprint ap Default: ap Type: toggle Causes the current line to be printed after each ex text modifying command. This is not of much interest in the normal vi visual mode. autowrite aw Default: noaw type: toggle Autowrite causes an automatic write to be done if there are unsaved changes before certain commands which change files or oth- erwise interact with the outside world. These commands are :!, :tag, :next, :rewind, ^^, and ^]. beautify bf Default: nobf Type: toggle Causes all control characters except , , and to be discarded. directory dir Default: dir=/tmp Type: string This is the directory in which vi puts its temporary file. errorbells eb Default: noeb Type: toggle Error messages are preceded by a . hardtabs ht Default: hardtabs=8 Type: numeric This option contains the value of hardware tabs in your terminal, or of software tabs expanded by the Unix system. ignorecase ic Default: noic Type: toggle All upper case characters are mapped to lower case in regular expression matching. lisp Default: nolisp Type: toggle Autoindent for lisp code. The commands ( ) [[ and ]] are modified appropriately to affect s-expressions and functions. list Default: nolist Type: toggle All printed lines have the and characters displayed visually. magic Default: magic Type: toggle Enable the metacharacters for matching. These include . * < > [string] [^string] and [-]. number nu Default: nonu Type: toggle Each line is displayed with its line number. July 6, 1987 - 19 - open Default: open Type: toggle When set, prevents entering open or visual modes from ex or edit. Not of interest from vi. optimize opt Default: opt Type: toggle Basically of use only when using the ex capabilities. This option prevents automatic s from taking place, and speeds up output of indented lines, at the expense of losing typeahead on some versions of UNIX. paragraphs para Default: para=IPLPPPQPP bp Type: string Each pair of characters in the string indi- cate nroff macros which are to be treated as the beginning of a paragraph for the { and } commands. The default string is for the -ms and -mm macros. To indicate one letter nroff macros, such as .P or .H, quote a space in for the second character position. For example: :set paragraphs=P\ bp would cause vi to consider .P and .bp as paragraph delimiters. prompt Default: prompt Type: toggle In ex command mode the prompt character : will be printed when ex is waiting for a command. This is not of interest from vi. redraw Default: noredraw Type: toggle On dumb terminals, force the screen to always be up to date, by sending great amounts of output. Useful only at high speeds. report Default: report=5 Type: numeric This sets the threshold for the number of lines modified. When more than this number of lines are modified, removed, or yanked, vi will report the number of lines changed at the bottom of the screen. scroll Default: scroll={1/2 window} Type: numeric This is the number of lines that the screen scrolls up or down when using the <^U> and <^D> commands. sections Default: sections=SHNHH HU Type: string Each two character pair of this string specify nroff macro names which are to be July 6, 1987 - 20 - treated as the beginning of a section by the ]] and [[ commands. The default string is for the -ms and -mm macros. To enter one letter nroff macros, use a quoted space as the second character. See paragraphs for a fuller explanation. shell sh Default: sh=from environment SHELL or /bin/sh Type: string This is the name of the sh to be used for "escaped" commands. shiftwidth sw Default: sw=8 Type: numeric This is the number of spaces that a <^T> or <^D> will move over for indenting, and the amount < and > shift by. showmatch sm Default: nosm Type: toggle When a ) or } is typed, show the matching ( or { by moving the cursor to it for one second if it is on the current screen. slowopen slow Default: terminal dependent Type: toggle On terminals that are slow and unintelli- gent, this option prevents the updating of the screen some of the time to improve speed. tabstop ts Default: ts=8 Type: numeric s are expanded to boundaries that are multiples of this value. taglength tl Default: tl=0 Type: numeric If nonzero, tag names are only significant to this many characters. term Default: (from environment TERM, else dumb) Type: string This is the terminal and controls the visual displays. It cannot be changed when in "visual" mode, you have to Q to command mode, type a set term command, and do ``vi.'' to get back into visual. Or exit vi, fix $TERM, and reenter. The definitions that drive a particular terminal type are found in the file /etc/termcap. terse Default: terse Type: toggle When set, the error diagnostics are short. warn Default: warn Type: toggle The user is warned if she/he tries to escape to the shell without writing out the current changes. July 6, 1987 - 21 - window Default: window={8 at 600 baud or less, 16 at 1200 baud, and screen size - 1 at 2400 baud or more} Type: numeric This is the number of lines in the window whenever vi must redraw an entire screen. It is useful to make this size smaller if you are on a slow line. w300, w1200, w9600 These set window, but only within the corresponding speed ranges. They are useful in an EXINIT to fine tune window sizes. For example, set w300=4 w1200=12 causes a 4 lines window at speed up to 600 baud, a 12 line window at 1200 baud, and a full screen (the default) at over 1200 baud. wrapscan ws Default: ws Type: toggle Searches will wrap around the end of the file when is option is set. When it is off, the search will terminate when it reaches the end or the beginning of the file. wrapmargin wm Default: wm=0 Type: numeric Vi will automatically insert a when it finds a natural break point (usually a between words) that occurs within "wm" spaces of the right margin. Therefore with "wm=0" the option is off. Setting it to 10 would mean that any time you are within 10 spaces of the right margin vi would be look- ing for a or which it could replace with a . This is convenient for people who forget to look at the screen while they type. (In version 3, wrapmargin behaves more like nroff, in that the boun- dary specified by the distance from the right edge of the screen is taken as the rightmost edge of the area where a break is allowed, instead of the leftmost edge.) writeany wa Default: nowa Type: toggle Vi normally makes a number of checks before it writes out a file. This prevents the user from inadvertently destroying a file. When the "writeany" option is enabled, vi no longer makes these checks. July 6, 1987 - 23 - Appendix: character functions This appendix gives the uses the editor makes of each character. The characters are presented in their order in the ASCII character set: Control characters come first, then most special characters, then the digits, upper and then lower case characters. For each character we tell a meaning it has as a com- mand and any meaning it has during an insert. If it has only meaning as a command, then only this is discussed. Section numbers in parentheses indicate where the character is discussed; a `f' after the section number means that the character is mentioned in a footnote. ^@ Not a command character. If typed as the first character of an insertion it is replaced with the last text inserted, and the insert terminates. Only 128 characters are saved from the last insert; if more charac- ters were inserted the mechanism is not available. A ^@ cannot be part of the file due to the editor implementation (7.5f). ^A Unused. ^B Backward window. A count specifies repeti- tion. Two lines of continuity are kept if possible (2.1, 6.1, 7.2). ^C Unused. ^D As a command, scrolls down a half-window of text. A count gives the number of (logical) lines to scroll, and is remembered for future ^D and ^U commands (2.1, 7.2). During an insert, backtabs over autoindent white space at the beginning of a line (6.6, 7.5); this white space cannot be backspaced over. ^E Exposes one more line below the current screen in the file, leaving the cursor where it is if possible. (Version 3 only.) ^F Forward window. A count specifies repeti- tion. Two lines of continuity are kept if possible (2.1, 6.1, 7.2). ^G Equivalent to :fCR, printing the current file, whether it has been modified, the current line number and the number of lines in the file, and the percentage of the way through the file that you are. July 6, 1987 - 24 - ^H (BS) Same as left arrow. (See h). During an insert, eliminates the last input character, backing over it but not erasing it; it remains so you can see what you typed if you wish to type something only slightly dif- ferent (3.1, 7.5). ^I (TAB) Not a command character. When inserted it prints as some number of spaces. When the cursor is at a tab character it rests at the last of the spaces which represent the tab. The spacing of tabstops is controlled by the tabstop option (4.1, 6.6). ^J (LF) Same as down arrow (see j). ^K Unused. ^L The ASCII formfeed character, this causes the screen to be cleared and redrawn. This is useful after a transmission error, if charac- ters typed by a program other than the editor scramble the screen, or after output is stopped by an interrupt (5.4, 7.2f). ^M (CR) A carriage return advances to the next line, at the first non-white position in the line. Given a count, it advances that many lines (2.3). During an insert, a CR causes the insert to continue onto another line (3.1). ^N Same as down arrow (see j). ^O Unused. ^P Same as up arrow (see k). ^Q Not a command character. In input mode, ^Q quotes the next character, the same as ^V, except that some teletype drivers will eat the ^Q so that the editor never sees it. ^R Redraws the current screen, eliminating logi- cal lines not corresponding to physical lines (lines with only a single @ character on them). On hardcopy terminals in open mode, retypes the current line (5.4, 7.2, 7.8). ^S Unused. Some teletype drivers use ^S to suspend output until ^Qis ^T Not a command character. During an insert, with autoindent set and at the beginning of the line, inserts shiftwidth white space. July 6, 1987 - 25 - ^U Scrolls the screen up, inverting ^D which scrolls down. Counts work as they do for ^D, and the previous scroll amount is common to both. On a dumb terminal, ^U will often necessitate clearing and redrawing the screen further back in the file (2.1, 7.2). ^V Not a command character. In input mode, quotes the next character so that it is pos- sible to insert non-printing and special characters into the file (4.2, 7.5). ^W Not a command character. During an insert, backs up as b would in command mode; the deleted characters remain on the display (see ^H) (7.5). ^X Unused. ^Y Exposes one more line above the current screen, leaving the cursor where it is if possible. (No mnemonic value for this key; however, it is next to ^U which scrolls up a bunch.) (Version 3 only.) ^Z If supported by the Unix system, stops the editor, exiting to the top level shell. Same as :stopCR. Otherwise, unused. ^[ (ESC) Cancels a partially formed command, such as a z when no following character has yet been given; terminates inputs on the last line (read by commands such as : / and ?); ends insertions of new text into the buffer. If an ESC is given when quiescent in command state, the editor rings the bell or flashes the screen. You can thus hit ESC if you don't know what is happening till the editor rings the bell. If you don't know if you are in insert mode you can type ESCa, and then material to be input; the material will be inserted correctly whether or not you were in insert mode when you started (1.5, 3.1, 7.5). ^\ Unused. ^] Searches for the word which is after the cur- sor as a tag. Equivalent to typing :ta, this word, and then a CR. Mnemonically, this com- mand is ``go right to'' (7.3). ^|^ Equivalent to :e #CR, returning to the previ- ous position in the last edited file, or editing a file which you specified if you got July 6, 1987 - 26 - a `No write since last change diagnostic' and do not want to have to type the file name again (7.3). (You have to do a :w before ^|^ will work in this case. If you do not wish to write the file you should do :e! #CR instead.) ^_ Unused. Reserved as the command character for the Tektronix 4025 and 4027 terminal. SPACE Same as right arrow (see l). ! An operator, which processes lines from the buffer with reformatting commands. Follow ! with the object to be processed, and then the command name terminated by CR. Doubling ! and preceding it by a count causes count lines to be filtered; otherwise the count is passed on to the object after the !. Thus 2!}fmtCR reformats the next two paragraphs by running them through the program fmt. If you are working on LISP, the command !%grindCR,* given at the beginning of a function, will run the text of the function through the LISP grinder (6.7, 7.3). To read a file or the output of a command into the buffer use :r (7.3). To simply execute a command use :! (7.3). " Precedes a named buffer specification. There are named buffers 1-9 used for saving deleted text and named buffers a-z into which you can place text (4.3, 6.3) # The macro character which, when followed by a number, will substitute for a function key on terminals without function keys (6.9). In input mode, if this is your erase character, it will delete the last character you typed in input mode, and must be preceded with a \ to insert it, since it normally backs over the last input character you gave. $ Moves to the end of the current line. If you :se listCR, then the end of each line will be shown by printing a $ after the end of the displayed text in the line. Given a count, advances to the count'th following end of line; thus 2$ advances to the end of the fol- lowing line. _________________________ *Both fmt and grind are Berkeley programs and may not be present at all installations. July 6, 1987 - 27 - % Moves to the parenthesis or brace { } which balances the parenthesis or brace at the current cursor position. & A synonym for :&CR, by analogy with the ex & command. ' When followed by a ' returns to the previous context at the beginning of a line. The pre- vious context is set whenever the current line is moved in a non-relative way. When followed by a letter a-z, returns to the line which was marked with this letter with a m command, at the first non-white character in the line. (2.2, 5.3). When used with an operator such as d, the operation takes place over complete lines; if you use `, the opera- tion takes place from the exact marked place to the current cursor position within the line. ( Retreats to the beginning of a sentence, or to the beginning of a LISP s-expression if the lisp option is set. A sentence ends at a . ! or ? which is followed by either the end of a line or by two spaces. Any number of closing ) ] " and ' characters may appear after the . ! or ?, and before the spaces or end of line. Sentences also begin at para- graph and section boundaries (see { and [[ below). A count advances that many sentences (4.2, 6.8). ) Advances to the beginning of a sentence. A count repeats the effect. See ( above for the definition of a sentence (4.2, 6.8). * Unused. + Same as CR when used as a command. , Reverse of the last f F t or T command, look- ing the other way in the current line. Espe- cially useful after hitting too many ; char- acters. A count repeats the search. - Retreats to the previous line at the first non-white character. This is the inverse of + and RETURN. If the line moved to is not on the screen, the screen is scrolled, or cleared and redrawn if this is not possible. If a large amount of scrolling would be required the screen is also cleared and redrawn, with the current line at the center July 6, 1987 - 28 - (2.3). . Repeats the last command which changed the buffer. Especially useful when deleting words or lines; you can delete some words/lines and then hit . to delete more and more words/lines. Given a count, it passes it on to the command being repeated. Thus after a 2dw, 3. deletes three words (3.3, 6.3, 7.2, 7.4). / Reads a string from the last line on the screen, and scans forward for the next occurrence of this string. The normal input editing sequences may be used during the input on the bottom line; an returns to com- mand state without ever searching. The search begins when you hit CR to terminate the pattern; the cursor moves to the begin- ning of the last line to indicate that the search is in progress; the search may then be terminated with a DEL or RUB, or by backspac- ing when at the beginning of the bottom line, returning the cursor to its initial position. Searches normally wrap end-around to find a string anywhere in the buffer. When used with an operator the enclosed region is normally affected. By mentioning an offset from the line matched by the pat- tern you can force whole lines to be affected. To do this give a pattern with a closing a closing / and then an offset +n or -n. To include the character / in the search string, you must escape it with a preceding \. A |^ at the beginning of the pattern forces the match to occur at the beginning of a line only; this speeds the search. A $ at the end of the pattern forces the match to occur at the end of a line only. More extended pattern matching is available, see section 7.4; unless you set nomagic in your .exrc file you will have to preceed the char- acters . [ * and ~ in the search pattern with a \ to get them to work as you would naively expect (1.5, 2,2, 6.1, 7.2, 7.4). 0 Moves to the first character on the current line. Also used, in forming numbers, after an initial 1-9. 1-9 Used to form numeric arguments to commands July 6, 1987 - 29 - (2.3, 7.2). : A prefix to a set of commands for file and option manipulation and escapes to the sys- tem. Input is given on the bottom line and terminated with an CR, and the command then executed. You can return to where you were by hitting DEL or RUB if you hit : acciden- tally (see primarily 6.2 and 7.3). ; Repeats the last single character find which used f F t or T. A count iterates the basic scan (4.1). < An operator which shifts lines left one shiftwidth, normally 8 spaces. Like all operators, affects lines when repeated, as in <<. Counts are passed through to the basic object, thus 3<< shifts three lines (6.6, 7.2). = Reindents line for LISP, as though they were typed in with lisp and autoindent set (6.8). > An operator which shifts lines right one shiftwidth, normally 8 spaces. Affects lines when repeated as in >>. Counts repeat the basic object (6.6, 7.2). ? Scans backwards, the opposite of /. See the / description above for details on scanning (2.2, 6.1, 7.4). @ A macro character (6.9). If this is your kill character, you must escape it with a \ to type it in during input mode, as it nor- mally backs over the input you have given on the current line (3.1, 3.4, 7.5). A Appends at the end of line, a synonym for $a (7.2). B Backs up a word, where words are composed of non-blank sequences, placing the cursor at the beginning of the word. A count repeats the effect (2.4). C Changes the rest of the text on the current line; a synonym for c$. D Deletes the rest of the text on the current line; a synonym for d$. E Moves forward to the end of a word, defined July 6, 1987 - 30 - as blanks and non-blanks, like B and W. A count repeats the effect. F Finds a single following character, backwards in the current line. A count repeats this search that many times (4.1). G Goes to the line number given as preceding argument, or the end of the file if no preceding count is given. The screen is redrawn with the new current line in the center if necessary (7.2). H Home arrow. Homes the cursor to the top line on the screen. If a count is given, then the cursor is moved to the count'th line on the screen. In any case the cursor is moved to the first non-white character on the line. If used as the target of an operator, full lines are affected (2.3, 3.2). I Inserts at the beginning of a line; a synonym for |^i. J Joins together lines, supplying appropriate white space: one space between words, two spaces after a ., and no spaces at all if the first character of the joined on line is ). A count causes that many lines to be joined rather than the default two (6.5, 7.1f). K Unused. L Moves the cursor to the first non-white char- acter of the last line on the screen. With a count, to the first non-white of the count'th line from the bottom. Operators affect whole lines when used with L (2.3). M Moves the cursor to the middle line on the screen, at the first non-white position on the line (2.3). N Scans for the next match of the last pattern given to / or ?, but in the reverse direc- tion; this is the reverse of n. O Opens a new line above the current line and inputs text there up to an ESC. A count can be used on dumb terminals to specify a number of lines to be opened; this is generally obsolete, as the slowopen option works better (3.1). July 6, 1987 - 31 - P Puts the last deleted text back before/above the cursor. The text goes back as whole lines above the cursor if it was deleted as whole lines. Otherwise the text is inserted between the characters before and at the cur- sor. May be preceded by a named buffer specification "x to retrieve the contents of the buffer; buffers 1-9 contain deleted material, buffers a-z are available for gen- eral use (6.3). Q Quits from vi to ex command mode. In this mode, whole lines form commands, ending with a RETURN. You can give all the : commands; the editor supplies the : as a prompt (7.7). R Replaces characters on the screen with char- acters you type (overlay fashion). Ter- minates with an ESC. S Changes whole lines, a synonym for cc. A count substitutes for that many lines. The lines are saved in the numeric buffers, and erased on the screen before the substitution begins. T Takes a single following character, locates the character before the cursor in the current line, and places the cursor just after that character. A count repeats the effect. Most useful with operators such as d (4.1). U Restores the current line to its state before you started changing it (3.5). V Unused. W Moves forward to the beginning of a word in the current line, where words are defined as sequences of blank/non-blank characters. A count repeats the effect (2.4). X Deletes the character before the cursor. A count repeats the effect, but only characters on the current line are deleted. Y Yanks a copy of the current line into the unnamed buffer, to be put back by a later p or P; a very useful synonym for yy. A count yanks that many lines. May be preceded by a buffer name to put lines in that buffer (7.4). July 6, 1987 - 32 - ZZ Exits the editor. (Same as :xCR.) If any changes have been made, the buffer is written out to the current file. Then the editor quits. [[ Backs up to the previous section boundary. A section begins at each macro in the sections option, normally a `.NH' or `.SH' and also at lines which which start with a formfeed ^L. Lines beginning with { also stop [[; this makes it useful for looking backwards, a function at a time, in C programs. If the option lisp is set, stops at each ( at the beginning of a line, and is thus useful for moving backwards at the top level LISP objects. (4.2, 6.1, 6.6, 7.2). \ Unused. ]] Forward to a section boundary, see [[ for a definition (4.2, 6.1, 6.6, 7.2). |^ Moves to the first non-white position on the current line (4.4). _ Unused. ` When followed by a ` returns to the previous context. The previous context is set when- ever the current line is moved in a non- relative way. When followed by a letter a-z, returns to the position which was marked with this letter with a m command. When used with an operator such as d, the operation takes place from the exact marked place to the current position within the line; if you use ', the operation takes place over complete lines (2.2, 5.3). a Appends arbitrary text after the current cur- sor position; the insert can continue onto multiple lines by using RETURN within the insert. A count causes the inserted text to be replicated, but only if the inserted text is all on one line. The insertion terminates with an ESC (3.1, 7.2). b Backs up to the beginning of a word in the current line. A word is a sequence of alphanumerics, or a sequence of special char- acters. A count repeats the effect (2.4). c An operator which changes the following object, replacing it with the following input July 6, 1987 - 33 - text up to an ESC. If more than part of a single line is affected, the text which is changed away is saved in the numeric named buffers. If only part of the current line is affected, then the last character to be changed away is marked with a $. A count causes that many objects to be affected, thus both 3c) and c3) change the following three sentences (7.4). d An operator which deletes the following object. If more than part of a line is affected, the text is saved in the numeric buffers. A count causes that many objects to be affected; thus 3dw is the same as d3w (3.3, 3.4, 4.1, 7.4). e Advances to the end of the next word, defined as for b and w. A count repeats the effect (2.4, 3.1). f Finds the first instance of the next charac- ter following the cursor on the current line. A count repeats the find (4.1). g Unused. Arrow keys h, j, k, l, and H. h Left arrow. Moves the cursor one character to the left. Like the other arrow keys, either h, the left arrow key, or one of the synonyms (^H) has the same effect. On v2 editors, arrow keys on certain kinds of ter- minals (those which send escape sequences, such as vt52, c100, or hp) cannot be used. A count repeats the effect (3.1, 7.5). i Inserts text before the cursor, otherwise like a (7.2). j Down arrow. Moves the cursor one line down in the same column. If the position does not exist, vi comes as close as possible to the same column. Synonyms include ^J (linefeed) and ^N. k Up arrow. Moves the cursor one line up. ^P is a synonym. l Right arrow. Moves the cursor one character to the right. SPACE is a synonym. m Marks the current position of the cursor in July 6, 1987 - 34 - the mark register which is specified by the next character a-z. Return to this position or use with an operator using ` or ' (5.3). n Repeats the last / or ? scanning commands (2.2). o Opens new lines below the current line; oth- erwise like O (3.1). p Puts text after/below the cursor; otherwise like P (6.3). q Unused. r Replaces the single character at the cursor with a single character you type. The new character may be a RETURN; this is the easi- est way to split lines. A count replaces each of the following count characters with the single character given; see R above which is the more usually useful iteration of r (3.2). s Changes the single character under the cursor to the text which follows up to an ESC; given a count, that many characters from the current line are changed. The last character to be changed is marked with $ as in c (3.2). t Advances the cursor upto the character before the next character typed. Most useful with operators such as d and c to delete the char- acters up to a following character. You can use . to delete more if this doesn't delete enough the first time (4.1). u Undoes the last change made to the current buffer. If repeated, will alternate between these two states, thus is its own inverse. When used after an insert which inserted text on more than one line, the lines are saved in the numeric named buffers (3.5). v Unused. w Advances to the beginning of the next word, as defined by b (2.4). x Deletes the single character under the cur- sor. With a count deletes deletes that many characters forward from the cursor position, but only on the current line (6.5). July 6, 1987 - 35 - y An operator, yanks the following object into the unnamed temporary buffer. If preceded by a named buffer specification, "x, the text is placed in that buffer also. Text can be recovered by a later p or P (7.4). z Redraws the screen with the current line placed as specified by the following charac- ter: RETURN specifies the top of the screen, . the center of the screen, and - at the bot- tom of the screen. A count may be given after the z and before the following charac- ter to specify the new screen size for the redraw. A count before the z gives the number of the line to place in the center of the screen instead of the default current line. (5.4) { Retreats to the beginning of the beginning of the preceding paragraph. A paragraph begins at each macro in the paragraphs option, nor- mally `.IP', `.LP', `.PP', `.QP' and `.bp'. A paragraph also begins after a completely empty line, and at each section boundary (see [[ above) (4.2, 6.8, 7.6). | Places the cursor on the character in the column specified by the count (7.1, 7.2). } Advances to the beginning of the next para- graph. See { for the definition of paragraph (4.2, 6.8, 7.6). ~ Unused. ^? (DEL) Interrupts the editor, returning it to com- mand accepting state (1.5, 7.5) July 6, 1987 - 36 - . July 6, 1987