vi(C)

Syntax

view [ -option ... ] [ command ... ] [ filename ... ]

vedit [ -option ... ] [ command ... ] [ filename ... ]

Description

The vi command offers a powerful set of text editing operations based on a set of mnemonic commands. Most commands are single keystrokes that perform simple editing functions. vi displays a full screen ``window'' into the file you are editing. The contents of this window can be changed quickly and easily within vi. While editing, visual feedback is provided (the name vi itself is short for ``visual'').

The view command is the same as vi except that the read-only option (-R) is set automatically. The file cannot be changed with view.

The vedit command is the same as vi except for differences in the option settings. vedit uses novice mode, turns off the magic option, sets the option report=1 and turns on the options showmode and redraw.

The showmode option informs the vedit user, in a message in the lower right corner of the screen, which mode is being used. For instance after the <Esc>i command is used, the message reads INSERT MODE.

Note that you cannot set the novice option from within vi or ex. If you want to use the novice option you must use the vedit utility. (It is possible to set the nonovice option from within vedit.)

vi and the line editor ex are one and the same editor: the names vi and ex identify a particular user interface rather than any underlying functional difference. The differences in user interface, however, are quite striking. ex is a powerful line-oriented editor, similar to the editor ed. However, in both ex and ed, visual updating of the terminal screen is limited, and commands are entered on a command line. vi, on the other hand, is a screen-oriented editor
designed so that what you see on the screen corresponds exactly and immediately to the contents of the file you are editing. In the following discussion, vi commands and options are printed in boldface type.

Options available on the vi command line include:

-x

Encryption option; when used, the file is encrypted as it is being written and requires an encryption key to be read. vi makes an educated guess to determine if a file is encrypted or not.

Refer to the crypt(C) page for information about restrictions on the availability of encryption options.

-C

Encryption option; the same as -x except that vi assumes files are encrypted.

Refer to the crypt(C) page for information about restrictions on the availability of encryption options.

-c command
+command

Begins editing by executing the specified editor command (usually a search or positioning command).

-t tag

Equivalent to an initial tag command; edits the file containing tag and positions the editor at its definition.

-r file

Used in recovering after an editor or system crash; retrieves the last saved version of the named file.

-l

Specific to editing LISP; sets the showmatch and lisp options.

-L

Lists the names of all files saved as a result of an editor or system crash. Files may be recovered with the -r option.

-wn

Sets the default window size to n; useful on dialups to start in small windows.

-R

Sets a read-only option so that files can be viewed but not edited.

The editing buffer

When vi is invoked with a single filename argument, the named file is copied to a temporary editing buffer. The editor remembers the name of the file specified at invocation, so that it can later copy the editing buffer back to the named file. The contents of the named file are not affected until the changes are copied back to the original file.

Modes of operation

Command Mode

Within command mode, signals from the keyboard are interpreted as editing commands.

Insert Mode

Insert mode can be entered by typing any of the vi insert, append, open, substitute, change, or replace commands. In insert mode, letters typed at the keyboard are inserted into the editing buffer.

ex Escape Mode

The vi and ex editors are one and the same editor differing mainly in their user interface. In vi, commands are usually single keystrokes. In ex, commands are lines of text terminated by a <Return>. vi has a special ``escape'' command that gives access to many of these line-oriented ex commands. To use the ex escape mode, type a colon (:). The colon is echoed on the status line as a prompt for the ex command. An executing command can be aborted by pressing INTERRUPT. Most file manipulation commands are executed in ex escape mode (for example, the commands to read in a file and to write out the editing buffer to a file).

Special keys

<Esc>

Returns to vi command mode or cancels partially formed commands.

<Return>

Terminates ex commands when in ex escape mode; also starts a newline when in insert mode.

INTERRUPT

Often the same as the <Del> or RUBOUT key on many terminals; generates an interrupt, telling the editor to stop what it is doing; aborts any command that is executing.

/

Specifies a string to be searched for. The slash appears on the status line as a prompt for a search string. The question mark (?) works exactly like the slash key, except that it is used to search backward in a file instead of forward.

:

Prompts for an ex command. You can then type in any ex command, followed by an <Esc> or <Return>, and the given ex command is executed.

The following characters are special in insert mode:

<Bksp>

Backs up the cursor one character on the current line. The last character typed before the <Bksp> is removed from the input buffer, but remains displayed on the screen.

<Ctrl>U

Moves the cursor back to the first character of the insertion and restarts insertion.

<Ctrl>V

Removes the special significance of the next typed character. Use <Ctrl>V to insert control characters. Linefeed and <Ctrl>J cannot be inserted in the text except as newline characters. Both <Ctrl>Q and <Ctrl>S are trapped by the operating system before they are interpreted by vi, so they too cannot be inserted as text.

<Ctrl>W

Moves the cursor back to the first character of the last inserted word.

<Ctrl>T

During an insertion, with the autoindent option set and at the beginning of the current line, this inserts shiftwidth whitespace.

<Ctrl>@

If entered as the first character of an insertion, this is replaced with the last text inserted, and the insertion terminates. Only 128 characters are saved from the last insertion. If more than 128 characters were inserted, then this command inserts no characters. A <Ctrl>@ cannot be part of a file, even if quoted.

Starting and exiting vi

vi

Edits empty editing buffer

vi file

Edits named file

vi +123 file

Goes to line 123

vi + 45 file

Goes to line 45

vi +/word file

Finds first occurrence of word

vi +/tty file

Finds first occurrence of tty

There are several ways to exit the editor:

:wq

Writes the editing buffer to the file you are editing, quits the editor, and returns to the UNIX shell.

:ZZ

Writes the editing buffer to the file only if any changes were made.

:x

Writes the editing buffer to the file only if any changes were made.

:q!

Cancels an editing session. The exclamation mark (!) tells vi to quit unconditionally. In this case, the editing buffer is not written out.

vi commands

Cursor movement

Forward Space

Syntax:

l
<Space>
right direction key

Function:

Moves the cursor forward one character. If a count is given, it moves the cursor forward count characters. Note that the cursor cannot move past the end of the line.

Backspace

Syntax:

h
<Bksp>
left direction key

Function:

Moves the cursor backward one character. If a count is given, it moves the cursor backward count characters. Note that the cursor cannot move past the beginning of the current line.

Next Line

Syntax:

+
<Return>

Function:

Moves the cursor down to the beginning of the next line.

Syntax:

j
<Ctrl>N
<LF>
down direction key

Function:

Moves the cursor down one line, remaining in the same column. Note the difference between these commands and the preceding set of next line commands which move to the beginning of the next line.

Previous Line

Syntax:

-

Function:

Moves the cursor up to the beginning of the previous line. If a count is given, the cursor is moved up count lines.

Syntax:

k
<Ctrl>P
up direction key

Function:

Moves the cursor up one line, remaining in the same column. If a count is given, the cursor is moved up count lines.

Beginning of Line

Syntax:

^
0

Function:

Moves the cursor to the beginning of the current line. Note that 0 always moves the cursor to the first character of the current line. The caret (^) works somewhat differently: it moves to the first character on a line that is not a tab or a space. This is useful when editing files that have a great deal of indentation, such as program texts.

End of Line

Syntax:

$

Function:

Moves the cursor to the end of the current line. Note that the cursor resides on top of the last character on the line. If a count is given, the cursor is moved forward count-1 lines to the end of the line.

Goto Line

Syntax:

[linenumber]G

Function:

Moves the cursor to the beginning of the line specified by linenumber. If no linenumber is given, the cursor moves to the beginning of the last line in the file. To find the line number of the current line, use <Ctrl>G.

Column

Syntax:

[column]|

Function:

Moves the cursor to the column in the current line given by column. If no column is given, the cursor is moved to the first column in the current line.

Word Forward

Syntax:

w
W

Function:

Moves the cursor forward to the beginning of the next word. The lowercase w command searches for a word defined as a string of alphanumeric characters separated by punctuation or whitespace (that is, tab, newline, or space characters). The uppercase W command searches for a word defined as a string of non-whitespace characters.

Back Word

Syntax:

b
B

Function:

Moves the cursor backward to the beginning of a word. The lowercase b command searches backward for a word defined as a string of alphanumeric characters separated by punctuation or whitespace (that is, tab, newline, or space characters). The uppercase B command searches for a word defined as a string of non-whitespace characters. If the cursor is already within a word, it moves backward to the beginning of that word.

End

Syntax:

e
E

Function:

Moves the cursor to the end of a word. The lowercase e command moves the cursor to the last character of a word, where a word is defined as a string of alphanumeric characters separated by punctuation or whitespace (that is, tab, newline, or space characters). The uppercase E moves the cursor to the last character of a word where a word is defined as a string of non-whitespace characters. If the cursor is already within a word, it moves to the end of that word.

Sentence

Syntax:

(
)

Function:

Moves the cursor to the beginning (left parenthesis) or end of a sentence (right parenthesis). A sentence is defined as a sequence of characters ending with a dot (.), question mark (?), or exclamation mark (!) followed by either two spaces or a newline. A sentence begins on the first non-whitespace character following a preceding sentence. Sentences are also delimited by paragraph and section delimiters. See below.

Paragraph

Syntax:

}
{

Function:

Moves the cursor to the beginning left curly brace ({) or end right curly brace (}) of a paragraph. A paragraph is defined with the paragraphs option. By default, paragraphs are delimited by the nroff macros .IP, .LP, .P, .QP, and .bp. Paragraphs also begin after empty lines.

Section

Syntax:

]]
[[

Function:

Moves the cursor to the beginning left double square brackets ([[) or end right double square brackets (]]) of a section. A section is defined with the sections option. By default, sections are delimited by the nroff macros .NH and .SH. Sections also start at formfeeds (<Ctrl>L) and at lines beginning with a brace ({).

Match Delimiter

Syntax:

%

Function:

Moves the cursor to a matching delimiter, where a delimiter is a parenthesis, a bracket, or a brace. This is useful when matching pairs of nested parentheses, brackets, and braces.

Home

Syntax:

[offset]H

Function:

Moves the cursor to the upper left corner of the screen. Use this command to move quickly to the top of the screen. If an offset is given, the cursor is homed offset-1 number of lines from the top of the screen. Note that the command dH deletes all lines from the current line to the top line shown on the screen.

Middle Screen

Syntax:

M

Function:

Moves the cursor to the beginning of the screen's middle line. Use this command to move quickly to the middle of the screen from either the top or the bottom. Note that the command dM deletes from the current line to the line specified by the M command.

Lower Screen

Syntax:

[offset]L

Function:

Moves the cursor to the lowest line on the screen. Use this command to move quickly to the bottom of the screen. If an offset is given, the cursor is homed offset-1 number of lines from the bottom of the screen. Note that the command dL deletes all lines from the current line to the bottom line shown on the screen.

Previous Context

Syntax:

´´
´character
``
`character

Function:

Moves the cursor to previous context or to context marked with the m command. If the single quotation mark (´) or back quotation mark (`) is doubled (`` or ''), the cursor is moved to previous context. If a single character is given after either quotation mark, the cursor is moved to the location of the specified mark as defined by the m command. The previous context is the location in the file of the last ``non-relative'' cursor movement. The single quotation mark (´) syntax is used to move to the beginning of the line representing the previous context. The back quotation mark (`) syntax is used to move to the previous context within a line.

The screen commands

Scroll

Syntax:

[size]<Ctrl>U
[size]<Ctrl>D

Function:

Scrolls the screen up a half window (<Ctrl>U) or down a half window (<Ctrl>D). If size is given, the scroll is size number of lines. This value is remembered for all later scrolling commands.

Page

Syntax:

<Ctrl>F
<Ctrl>B

Function:

Pages the screen forward and backward. Two lines of continuity are kept between pages if possible. A preceding count gives the number of pages to move forward or backward.

Status

Syntax:

BELL
<Ctrl>G

Function:

Displays vi status on the status line. This gives you the name of the file you are editing, whether it has been modified, the current line number, the number of lines in the file, and the percentage of the file (in lines) that precedes the cursor.

Zero Screen

Syntax:

[linenumber]z[size]<Return>
[linenumber]z[size].
[linenumber]z[size]-

Function:

Redraws the display with the current line placed at or ``zeroed'' at the top, middle, or bottom of the screen, respectively. If you give a size, the number of lines displayed is equal to size. If a preceding linenumber is given, the given line is placed at the top of the screen. If the last argument is a <Return>, the current line is placed at the top of the screen. If the last argument is a dot (.), the current line is placed in the middle of the screen. If the last argument is a minus sign (-), the current line is placed at the bottom of the screen.

Redraw

Syntax:

<Ctrl>R
<Ctrl>L
(Command depends on terminal type.)

Function:

Redraws the screen. Use this command to erase any system messages or line noise that may scramble your screen. Note that system messages do not affect the file you are editing.

Text insertion

Insert

Syntax:

i[text]<Esc>
I[text]<Esc>

Function:

Inserts text in editing buffer. The lowercase i command places you in insert mode. text is inserted before the cursor. To insert a newline, press <Return>. Exit insert mode by pressing <Esc>. The uppercase I command places you in insert mode, but begins text insertion at the beginning of the current line, rather than before the cursor. (The beginning of the line here is the first non-blank character on the line.)

Append

Syntax:

a[text]<Esc>
A[text]<Esc>

Function:

Appends text to the editing buffer. The lowercase a command works exactly like the lowercase i command, except that text insertion begins after the cursor and not before. This is the only way to add text to the end of a line. The uppercase A command begins appending text at the end of the current line rather than after the cursor.

Open New Line

Syntax:

o[text]<Esc>
O[text]<Esc>

Function:

Opens a new line and inserts text. The lowercase o command opens a new line below the current line; uppercase O opens a new line above the current line. After the new line has been opened, both these commands work like the I command.

Text deletion

Delete Character

Syntax:

x
X

Function:

Deletes a character. The lowercase x command deletes the character at the cursor. With a preceding count, count characters are deleted to the right, beginning with the character at the cursor. This is a quick and easy way to delete a few characters. The uppercase X command deletes the character just before the cursor. With a preceding count, count characters are deleted backward, beginning with the character just before the cursor.

Delete

Syntax:

dcursor-movement
dd
D

Function:

Deletes a text object. The lowercase d command takes a cursor-movement as an argument. If the cursor-movement is an intraline command, deletion takes place from the cursor to the end of the text object delimited by the cursor-movement. Deletion forward deletes the character at the cursor; deletion backward does not. If the cursor-movement is a multi-line command, deletion takes place from and including the current line to the text object delimited by the cursor-movement.

The dd command deletes whole lines. The uppercase D command deletes from and including the cursor to the end of the current line.

Deleted text is automatically pushed on a stack of buffers numbered 1 through 9. The most recently deleted text is also placed in a special delete buffer that is logically buffer 0. This special buffer is the default buffer for all put commands using the double quotation mark (") to specify the number of the buffer for delete, put, and yank commands. The buffers 1 through 9 can be accessed with the p and P put commands by appending the double quotation mark (") to the number of the buffer. For example:

"4p

puts the contents of delete buffer number 4 in your editing buffer just below the current line. Note that the last deleted text is put by default and does not need a preceding buffer number.

Text modification

Undo

Syntax:

u
U

Function:

Undoes the last insert or delete command. The lowercase u command undoes the last insert or delete command. This means that after an insert, u deletes text; and after a delete, u inserts text. For the purposes of undo, all text modification commands are considered insertions.

The uppercase U command restores the current line to its state before it was edited, no matter how many times the current line has been edited since you moved to it.

Repeat

Syntax:

.

Function:

Repeats the last insert or delete command. A special case exists for repeating the p and P put commands. When these commands are preceded by the name of a delete buffer, successive u commands display the contents of the delete buffers.

Change

Syntax:

ccursor-movement text <Esc>
Ctext <Esc>
cctext <Esc>

Function:

Changes a text object and replaces it with text. Text is inserted as with the i command. A dollar sign ($) marks the extent of the change. The c command changes arbitrary text objects delimited by the cursor and a cursor-movement. C affects from the cursor to the end of the line, cc affects the whole line; otherwise, they are identical in function.

Replace

Syntax:

rchar
Rtext <Esc>

Function:

Overstrikes a character or line with char or text, respectively. Use r to overstrike a single character and R to overstrike a whole line. A preceding count multiplies the replacement text count times.

Substitute

Syntax:

stext <Esc>
Stext <Esc>

Function:

Substitutes the current character or current line with text. Use s to replace a single character with new text. Use S to replace the current line with new text. If a preceding count is given, text substitutes for count number of characters or lines depending on whether the command is s or S, respectively.

Filter

Syntax:

!cursor-movement cmd <Return>

Function:

Filters the text object delimited by the cursor and cursor-movement through the UNIX^® command, cmd. For example, the following command sorts all lines between the cursor and the bottom of the screen, substituting the designated lines with the sorted lines:

!Lsort

Arguments and shell metacharacters may be included as part of cmd; however, standard input and output are always associated with the text object being filtered.

Join Lines

Syntax:

J

Function:

Joins the current line with the following line. If a count is given, count lines are joined.

Shift

Syntax:

>[cursor-movement]
<[cursor-movement]
>>
<<

Function:

Shifts text right (>) or left (<). Text is shifted by the value of the option shiftwidth, which is normally set to eight spaces. Both the > and < commands shift all lines in the text object delimited by the current line and cursor-movement. The >> and << commands affect whole lines. All versions of the command can take a preceding count that acts to multiply the number of objects affected.

Text movement

The named buffers are most useful for keeping track of several sections of text that you want to keep on hand for later access, movement, or rearrangement. These buffers are named with the letters a through z. To refer to one of these buffers (or one of the numbered delete buffers) in a command, use a quotation mark. For example, to yank a line into the buffer named a, enter:

"ayy

To put this text back into the file, enter:

"ap

If you delete text in the buffer named A rather than a, text is appended to the buffer named a (that is, A and a refer to the same buffer but are handled differently).

Note that the contents of the named buffers are not destroyed when you switch files. Therefore, you can delete or yank text into a buffer, switch files, and then do a put. Buffer contents are destroyed when you exit the editor, so be careful.

Put

Syntax:

["alphanumeric]p
["alphanumeric]P

Function:

Puts text from a buffer into the editing buffer. If no buffer name is specified, text is put from the unnamed buffer. The lowercase p command puts text either below the current line or after the cursor, depending on whether the buffer contains a partial line or not. The uppercase P command puts text either above the current line or before the cursor, again depending on whether the buffer contains a partial line or not.

Yank

Syntax:

["letter]ycursor-movement
["letter]yy
["letter]

Function:

Copies text in the editing buffer to a named buffer. If no buffer name is specified, text is yanked into the unnamed buffer. If an uppercase letter is used, text is appended to the buffer and does not overwrite and destroy the previous contents. When a cursor-movement is given as an argument, the delimited text object is yanked. The y and yy commands yank a single line, or, if a preceding count is given, multiple lines.

Searching

Search

Syntax:

/[pattern]/[offset]<Return>
/[pattern]<Return>
?[pattern]?[offset]<Return>
?[pattern]<Return>

Function:

Searches forward (/) or backward (?) for pattern. A string is actually a regular expression as described in regexp(M). The trailing delimiter is not required. If no pattern is given, then the last pattern searched for is used. After the second delimiter, an offset may be given, specifying the beginning of a line relative to the line on which pattern was found. For example:

/word/-

finds the beginning of the line immediately preceding the line containing word and the following command:

/word/+2

finds the beginning of the line two lines after the line containing word. See also the ignorecase and magic options.

Next String

Syntax:

n
N

Function:

Repeats the last search command. The n command repeats the search in the same direction as the last search command. The N command repeats the search in the opposite direction of the last search command.

Find Character

Syntax:

fchar
Fchar
;
,

Function:

Finds character char on the current line. The f command searches forward on the line; the F command searches backward. The semicolon (;) repeats the last character search. The comma (,) reverses the direction of the search.

To Character

Syntax:

tchar
Tchar
;
,

Function:

Moves the cursor up to but not on char. The semicolon (;) repeats the last character search. The comma (,) reverses the direction of the search.

Mark

Syntax:

mletter

Function:

Marks a place in the file with a lowercase letter. You can move to a mark using the ``to mark'' commands described below. It is often useful to create a mark, move the cursor, and then delete from the cursor to the mark with the following command:

d´a

To Mark

Syntax:

´letter
`letter

Function:

Moves to letter. These commands let you move to the location of a mark. Marks are denoted by single lowercase alphabetic characters. Before you can move to a mark, it must first be created with the m command. The back quotation mark (`) moves you to the exact location of the mark within a line; the forward quotation mark (') moves you to the beginning of the line containing the mark. Note that these commands are also legal cursor movement commands.

Exit and escape commands

ex Escape

Syntax:

:

Function:

Enters ex escape mode to execute an ex command. The colon appears on the status line as a prompt for an ex command. You then can enter an ex command line terminated by either a <Return> or an <Esc> and the ex command executes. You are then prompted to press <Return> to return to vi command mode. During the input of the ex command line or during execution of the ex command, you may press INTERRUPT to stop what you are doing and return to vi command mode.

Exit Editor

Syntax:

ZZ

Function:

Exits vi and writes out the file if any changes have been made. This returns you to the shell from which you started vi.

Quit to ex

Syntax:

Q

Function:

Enters the ex editor. When you do this, you will still be editing the same file. You can return to vi by entering the vi command from ex.

ex commands

Many of these commands perform actions that affect the current file by default. The current file is normally the file that you named when you started vi, although the current file can be changed with the file command, f, or with the next command, n. In most respects, these commands are identical to similar commands for the editor, ed. All such ex commands are aborted by either <Return> or INTERRUPT. <Return> is used in the examples. Command entry is terminated by pressing INTERRUPT.

Command structure

Most commands accept prefix addresses specifying the lines in the file that they are to affect. A number of commands also may take a trailing count specifying the number of lines to be involved in the command. Counts are rounded down if necessary. Thus, the command 10p displays the tenth line in the buffer while move 5 moves the current line after line 5.

Some commands take other information or parameters, stated after the command name. Examples are option names in a set command, such as set number, a filename in an edit command, a regular expression in a substitute command, or a target address for a copy command. For example:

1,5 copy 25

A number of commands have variants. The variant form of the command is invoked by placing an exclamation mark (!) immediately after the command name. Some of the default variants may be controlled by options; in this case, the exclamation mark turns off the meaning of the default.

In addition, many commands take flags, including the characters p and l. A p or l must be preceded by a blank or tab. In this case, the command abbreviated by these characters is executed after the command completes. Since ex normally displays the new current line after each change, p is rarely necessary. Any number of plus (+) or minus (-) characters may also be given with these flags. If they appear, the specified offset is applied to the current line value before the printing command is executed.

Most commands that change the contents of the editor buffer give feedback if the scope of the change exceeds a threshold given by the report option. This feedback helps to detect undesirably large changes so that they may be quickly and easily reversed with the undo command. After commands with global effect, you are informed if the net change in the number of lines in the buffer during this command exceeds this threshold.

Command addressing

.

The current line. Most commands leave the current line as the last line which they affect. The default address for most commands is the current line, thus ``.'' is rarely used alone as an address.

n

The nth line in the editor's buffer, lines being numbered sequentially from 1.

$

The last line in the buffer.

%

An abbreviation for 1,$, the entire buffer.

+n or -n

An offset, n relative to the current buffer line. The forms .+3, +3 and +++ are all equivalent. If the current line is line 100 they all address line 103.

/pattern/ or ?pattern?

Scan forward and backward respectively for a text matching the regular expression given by pattern. Scans normally wrap around the end of the buffer. If all that is desired is to print the next line containing pattern, the trailing slash (/) or question mark (?) may be omitted. If pattern is omitted or explicitly empty, the string matching the last specified regular expression is located. The forms <Return> and ?<Return> scan using the last named regular expression. After a substitute, <Return> and ??<Return> scan using that substitute's regular expression.

´´ or ´x

Before each non-relative motion of the current line dot (.), the previous current line is marked with a label, subsequently referred to with two single quotation marks (´´). This makes it easy to refer or return to this previous context. Marks are established with the vi m command, using a single lowercase letter as the name of the mark. Marked lines are later referred to with the following notation:

´x.

where x is the name of a mark.

Command format

All parts are optional depending on the particular command and its options. The following sections describe specific commands.

Argument list commands

args

Displays the members of the argument list, with the current argument delimited by brackets.

For example, a list might look like this:

file1 file2 [file3] file4 file5

The current file is file3.

f

Displays the current filename; modification status since the last write command; current read or write status; the current line number; the number of lines in the buffer; and the percentage of the buffer that you have edited. In the rare case that the current file is ``[Not edited]'', this is noted also; in this case you have to use w! to write to the file, since the editor is not sure that a w command will not destroy a file unrelated to the current contents of the buffer.

f file

Changes the current filename to file which is considered ``[Not edited]''.

n

Edits the next file in the command line argument list.

n!

Suppresses warnings about the modifications to the buffer not having been written out, discarding irretrievably any changes that may have been made.

n [+command] filelist

Expands the specified filelist; the resulting list replaces the current argument list; the first file in the new list is then edited. If command is given (it must contain no spaces), then it is executed after editing the first such file.

rew

Rewinds the argument list; the first file in the list is then edited.

rew!

Rewinds the argument list, discarding any changes made to the current buffer.

Edit commands

In the following discussions, note that the name of the current file is always remembered by vi and is specified by a percent sign (%). The name of the previous file in the editing buffer is specified by a number sign (#).

The edit commands are described below:

e file

Begins an editing session on a new file. The editor first checks to see if the buffer has been modified since the last w command was issued. If it has been, a warning is issued and the command is aborted. The command otherwise deletes the entire contents of the editor buffer, makes the named file the current file, and displays the new filename. After ensuring that this file is sensible, (that is, it is not a binary file, directory, or a device), the editor reads the file into its buffer. If the read of the file completes without error, the number of lines and characters read is displayed on the status line. If no errors occurred, the file is considered edited. If the last line of the input file is missing the trailing newline character, it is supplied and a complaint issued. The current line is initially the first line of the file.

e! file

Suppresses the complaint about modifications having been made and not written from the editor buffer, thus discarding all changes that have been made before editing the new file.

e +n file

Causes the editor to begin editing at line n rather than at the first line. The argument n may also be an editor command containing no spaces; for example, +/pattern.

<Ctrl>^

Returns to the previous position in the last edited file; this is a shorthand equivalent for :e #<Return>. If you do not want to write the file, you should use :e! #<Return> instead.

Write commands

w file

Writes changes made back to file, displaying the number of lines and characters written. Normally, file is omitted and the buffer is written to the name of the current file. If file is specified, text is written to that file. The editor writes to a file only if it is the current file and is edited, or if the file does not exist. Otherwise, you must give the variant form w! to force the write. If the file does not exist it is created. The current filename is changed only if there is no current filename; the current line is never changed.

If an error occurs while writing the current and edited file, the editor displays:

No write since last change

even if the buffer had not previously been modified.

w>> file

Appends the buffer contents at the end of an existing file. Previous file contents are not destroyed.

w! name

Overrides the checking of the normal write command, and writes to any file that the system permits.

w !command

Writes the specified lines into command. Note the difference in spacing between

w! file

which overrides checks and

w !cmd

which writes to a command. (A blank or tab before the exclamation mark is mandatory.) The output of this command is displayed on the screen and not inserted in the editing buffer.

Read commands

r file

Places a copy of the text of the given file in the editing buffer after the specified line. If no file is given, the current filename is used. The current filename is not changed unless there is none, in which case the file becomes the current name. If the file buffer is empty and there is no current name, this is treated as an e command.

Address 0 is legal for this command and causes the file to be read at the beginning of the buffer. Statistics are given as for the e command when the r successfully terminates. After an r the current line is the last line read.

r !command

Reads the output of command into the buffer after the specified line. A blank or tab before the exclamation mark (!) is mandatory.

Quit commands

q

Exits vi. No automatic write of the editor buffer to a file is performed. However, vi displays a warning message if the file has changed since the last w command was issued, and does not quit. vi also displays a diagnostic if there are more files in the argument list left to edit. Normally, you will wish to save your changes, and you should enter a w command. If you wish to discard them, enter the q! command variant.

q!

Quits from the editor, discarding changes to the buffer without complaint.

wq name

Like a w and then a q command.

wq! name

Overrides checking normally made before execution of the w command to any file. For example, if you own a file but do not have write permission turned on, wq! allows you to update the file anyway.

x name

If any changes have been made and not written, writes the buffer out and then quits. Otherwise, it just quits.

Global and substitute commands

g/pattern/cmds

The g command has two distinct phases. In the first phase, each line matching pattern in the editing buffer is marked. Next, the given command list is executed with the current line, dot (.), initially set to each marked line.

The command list consists of the remaining commands on the current input line and may continue to multiple lines by ending all but the last such line with a backslash (\). This multiple-line option will not work from within vi. You must switch to ex to do it. The vi command Q can be used to exit to ex, and the ex command vi will return you to visual mode. If cmds (or the trailing slash (/) delimiter) is omitted, each line matching pattern is displayed.

The g command itself may not appear in cmds. The options autoprint and autoindent are inhibited during a global command and the value of the report option is temporarily infinite, in deference to a report for the entire global. Finally, the context mark ( ' ) or ( ` ) is set to the value of the current line (.) before the global command begins and is not changed during a global command.

The following global commands, most of them substitutions, cover the most frequent uses of the global command.

g/s1/p

Prints all lines that contain the string s1.

g/s1/s//s2/

Substitutes the first occurrence of s1 on all lines that contain it with the string s2.

g/s1/s//s2/g

Substitutes all occurrences of s1 with the string s2. This includes multiple occurrences of s1 on a line.

g/s1/s//s2/gp

Works the same as the preceding example, except that in addition, all changed lines are displayed on the screen.

g/s1/s//s2/gc

Prompts you to confirm that you want to make each substitution of the string s1 with the string s2. If you enter a Y, the given substitution is made, otherwise it is not.

g/s0/s/s1/s2/g

Marks all those lines that contain the string s0, and then for those lines only, substitutes all occurrences of the string s1 with s2.

g!/pattern/cmds

Runs cmds at each line not matching pattern.

g/^/s// /g

Inserts blank spaces at the beginning of each line in a file.

s/pattern/repl/options

On each specified line, replaces the first instance of text matching the regular expression pattern by the replacement text repl. If the global indicator option character g appears, all instances on a line are substituted. If the confirm indication character c appears, before each substitution the line to be substituted is printed on the screen with the string to be substituted marked with caret (^) characters. By entering Y, you cause the substitution to be performed; any other input causes no change to take place. After an s command, the current line is the last line substituted.

v/pattern/cmds

A synonym for the global command variant g!, runs the specified cmds on each line that does not match pattern.

Text movement commands

co addr flags

Places a copy of the specified lines after addr, which may be 0. The current line (.) addresses the last line of the copy.

[range]maddr

Moves the lines specified by range after the line given by addr. For example, m+ swaps the current line and the following line, since the default range is just the current line. The first of the moved lines becomes the current line (.).

Shell escape commands

cd directory

Causes the specified directory to become the current directory. If no directory is specified, the current value of the home option is used as the target directory. After a cd, the current file is not considered to have been edited so that write restrictions on existing files still apply.

sh

Creates a new shell. You may invoke as many commands as you like in this shell. To return to vi, enter a <Ctrl>D to terminate the shell.

!command

Sends the remainder of the line after the exclamation (!) to a shell to be executed. Within the text of command, the characters ``%'' and ``#'' are expanded as the filenames of the current file and the last edited file and the character ``!'' is replaced with the text of the previous command. Thus, in particular, ``!!'' repeats the last such shell escape. If any such expansion is performed, the expanded line is echoed. The current line is unchanged by this command.

If you use C-Shell and set the prompt variable to output a prompt for non-interactive shells, the prompt is interpreted as an argument for command in shell escapes. This causes unexpected problems. To avoid these problems, use the default prompt value as shown in /usr/lib/mkuser/csh/cshrc.

Other commands

The abbr, map, and set commands can also be defined with the EXINIT environment variable, which is read by the editor each time it starts up. For more information, see environ(M). Alternatively, these commands can be placed in a .exrc file in your home directory, which the editor reads if EXINIT is not defined.

abbr

Maps the first argument to the following string. For example, the command:

:abbr rainbow yellow green blue red

maps ``rainbow'' to ``yellow green blue red''. Abbreviations can be turned off with the unabbreviate command, as in:

:una rainbow

map, map!

Maps any character or escape sequence to a command sequence. For example, the following command maps the <Ctrl>A key to a shell escape that runs the clear(C) command:

map ^A:!clear^M

To include the <Ctrl>A and <Ctrl>M characters in the mapping, you must use vi's <Ctrl>V escape.

Characters mapped with map work in command mode, while characters mapped with map! work in insert mode. Characters mapped with map! cannot be unmapped using unmap.

nu

Displays each specified line preceded by its buffer line number. The current line is left at the last line displayed. To get automatic line numbering of lines in the buffer, set the number option.

preserve

Saves the current editor buffer as though the system had just crashed. This command is for use only in emergencies when a w command has resulted in an error and you do not know how to save your work.

=

Displays the line number of the addressed line. The current line is unchanged.

recover file

Recovers file from the system save area. The system saves a copy of the editing buffer only if you have made changes to the file, the system crashes, or you execute a preserve command. When you use preserve, you are notified by mail.

set argument

With no arguments, set displays those options whose values have been changed from their defaults; with the argument all, it displays all of the option values.

Giving an option name followed by a question mark (?) causes the current value of that option to be displayed. The question mark is unnecessary unless the option is a Boolean value. Switch options are given values either with:

set option

to turn them on or:

set nooption

to turn them off. String and numeric options are assigned with:

set option=value

More than one option can be given to set; all are interpreted from left to right. See ``Options'' for a complete list and descriptions.

tag label

Switches the focus of editing to the location of label. If necessary, vi will switch to a different file in the current directory to find label. If you have modified the current file before giving a tag command, you must first write it out. If you give another tag command with no argument, the previous label is used.

Similarly, if you press <Ctrl>], vi searches for the word immediately after the cursor as a tag. This is equivalent to entering ``:tag'', the word following the cursor, and then pressing the <Return> key.

The tags file is normally created by a program such as ctags, and consists of a number of lines with three fields separated by blanks or tabs. The first field gives the name of the tag, the second the name of the file where the tag resides, and the third gives an addressing form which can be used by the editor to find the tag. This field is usually a contextual scan using /pattern/ to be immune to minor changes in the file. Such scans are always performed as if the nomagic option was set. The tag names in the tags file must be sorted alphabetically.

unmap

Unmaps any character or escape sequence that has been mapped using the map command.

Options

The first thing that must be done before you can use vi, is to set the terminal type so that vi understands how to talk to the particular terminal you are using.

There are only two kinds of options: switch options and string options. A switch option is either on or off. A switch is turned off by prefixing the word no to the name of the switch within a set command. String options are strings of characters that are assigned values with the syntax option=string. Multiple options may be specified on a line. vi options are listed below:

autoindent, ai  (default: noai)

Eases the preparation of structured program text. For each line created by an append, change, insert, open, or substitute operation, vi looks at the preceding line to determine and insert an appropriate amount of indentation. To back the cursor up to the preceding tab stop, press <Ctrl>D. The tab stops going backward are defined as multiples of the shiftwidth option. You cannot backspace over the indent, except by pressing <Ctrl>D.

Specially processed in this mode is a line with no characters added to it, which turns into a completely blank line (the whitespace provided for the autoindent is discarded). Also specially processed in this mode are lines beginning with a caret (^) and immediately followed by a <Ctrl>D. This causes the input to be repositioned at the beginning of the line, but retains the previous indent for the next line. Similarly, a ``0'' followed by a <Ctrl>D repositions the cursor at the beginning without retaining the previous indent. autoindent does not happen in global commands.

autoprint ap   (default: ap)

Causes the current line to be displayed after each ex copy, move, or substitute command. This has the same effect as supplying a trailing ``p'' to each such command. autoprint is suppressed in globals, and only applies to the last command on a line.

autowrite, aw  (default: noaw)

Causes the contents of the buffer to be automatically written to the current file if you have modified it when you give a next, rewind, tag, or ! command, or a <Ctrl>^ (switch files) or <Ctrl>] (goto tag) command.

beautify, bf  (default: nobeautify)

Causes all control characters except tab, newline and formfeed to be discarded from the input. A complaint is registered the first time a backspace character is discarded. beautify does not apply to command input.

directory, dir  (default: dir=/tmp)

Specifies the directory in which vi places the editing buffer file. If the directory does not have write permission, the editor exits abruptly when it fails to write to the buffer file.

edcompatible  (default: noedcompatible)

Causes the presence or absence of g and c suffixes on substitute commands to be remembered, and to be toggled on and off by repeating the suffixes. The suffix r causes the substitution to be like the tilde (~) command, instead of like the ampersand (&) command.

errorbells, eb  (default: noeb)

Precedes error messages by a bell. If possible, the editor always places the error message in inverse video instead of ringing the bell.

hardtabs, ht  (default: ht=8)

Gives the boundaries on which terminal hardware tabs are set or on which tabs the system expands.

ignorecase, ic  (default: noic)

Maps all uppercase characters in the text to lowercase in regular expression matching. In addition, all uppercase characters in regular expressions are mapped to lowercase except in character class specifications enclosed in brackets.

lisp  (default: nolisp)

Causes autoindent to indent appropriately for LISP code, and the ( ) { } [[ and ]] commands to be modified to have meaning for LISP.

list  (default: nolist)

Displays all printed lines, showing tabs and end-of-lines.

magic  (default: magic)

If nomagic is set, the number of regular expression metacharacters is greatly reduced, with only caret (^) and dollar sign ($) having special effects. In addition, the metacharacters tilde (~) and ampersand (&) in replacement patterns are treated as normal characters. All the normal metacharacters may be made magic when nomagic is set by preceding them with a backslash (\).

mesg  (default: nomesg)

Causes write permission to be turned off to the terminal while you are in visual mode, if nomesg is set. This prevents people writing to your screen with the UNIX write command and scrambling your screen as you edit.

modelines  (default: nomodelines)

Allows the first five and last five lines of a file being read in to be interpreted as vi or ex commands. The lines must have the form:

vi:command:

or

ex:command:

for the command to be interpreted.

Note that setting modelines exposes you to a potential security threat from files containing such lines, particularly if you are logged in as root.

number, n  (default: nonumber)

Causes all output lines to be printed with their line numbers.

optimize, opt  (default: optimize)

Expedites output of text to the screen by setting the terminal so that it does not perform automatic carriage returns when displaying more than one line of output, thus greatly speeding output on terminals without addressable cursors when text with leading whitespace is printed.

paragraphs, para  (default: para =IPLPPPQPP TPbp)

Specifies paragraph delimiters for the { and } operations. The pairs of characters in the option's value are the names of the nroff macros that start paragraphs.

prompt  (default: prompt)

Causes ex input to be prompted for with a colon (:). If noprompt is set, when ex command mode is entered with the Q command, no colon prompt is displayed on the status line.

redraw  (default: noredraw)

Causes the editor to simulate (using great amounts of output) an intelligent terminal on a dumb terminal. This is useful only at very high speed.

remap  (default: remap)

If on, causes mapped characters to be repeatedly tried until they are unchanged. For example, if o is mapped to O and O is mapped to I, o will map to I if remap is set, and to O if noremap is set.

report  (default: report=5)

Specifies a threshold for feedback from commands. Any command that modifies more than the specified number of lines provides feedback as to the scope of its changes. For global commands and the undo command, the net change in the number of lines in the buffer is presented at the end of the command. Thus notification is suppressed during a g command on the individual commands performed.

scroll  (default: scroll=½ window)

Determines the number of logical lines scrolled when <Ctrl>D is received from a terminal input in command mode, and the number of lines displayed by a command mode z command (double the value of scroll).

sections  (default: sections=SHNHH HU)

Specifies the section macros for the [[ and ]] operations. The pairs of characters in the option's value are the names of the nroff macros that start sections.

shell, sh  (default: sh=/bin/sh)

Gives the pathname of the shell forked for the shell escape (!) command, and by the shell command. The default is taken from SHELL in the environment, if present.

shiftwidth, sw  (default:sw=8)

Gives the width of a software tab stop, used in reverse tabbing with <Ctrl>D when using autoindent to append text, and by the shift commands.

showmatch, sm  (default: nosm)

When a ``)'' or ``}'' is typed, moves the cursor to the matching ``('' or ``{'' for one second if this matching character is on the screen.

showmode  (default:noshowmode)

Causes the message INPUT MODE to appear on the lower right corner of the screen when insert mode is activated.

slowopen  (default: noslowopen)

Postpones update of the display during inserts.

tabstop, ts  (default: ts=8)

Causes the editor to expand tabs in the input file to be on n boundaries for the purposes of display.

taglength, tl  (default: tl=0)

Causes the first n characters in a tag name to be significant, but all others to be ignored. A value of 0 (the default) means that all characters are significant.

tags  (default: tags=tags /usr/lib/tags)

Specifies a path of files to be used as tag files for the tag command. A requested tag is searched for in the specified files, sequentially. By default, files named tags are searched for in the current directory and in /usr/lib.

term  (default=value of shell TERM variable)

Specifies the terminal type of the output device.

terse  (default: noterse)

Produces shorter error diagnostics for the experienced user.

timeout [=n], to [=n]  (default: to=xxx)

Specifies the milliseconds to wait for subsequent input characters. This is the maximum allowed waiting time between characters in multicharacter sequences, such as arrow keys or :map functions. If no value is given, vi determines the timeout period from the type and speed of the terminal connection; setting notimeout requires the next character to be input, and is not the same as setting timeout to 0 (never waiting).

warn (default: warn)

Warns if there has been ``[No write since last change]'' before a shell escape command (!).

window  (default: window = speed dependent)

Specifies the number of lines in a text window. The default is 8 at slow speeds (600 baud or less), 16 at medium speed (1200 baud), and the full screen (minus one line) at higher speeds.

w300, w1200, w9600

These are not true options but set window (above) only if the speed is slow (300), medium (1200), or high (9600), respectively.

wrapscan, ws  (default: ws)

Causes searches, using the regular expressions in addressing, to wrap around past the end of the file.

wrapmargin, wm  (default: wm=0)

Defines the margin for automatic insertion of newlines during text input. The value specified is the width of the margin at the right side of the screen within which word wrap will be carried out. A newline will be inserted immediately after a word that ends in the margin. A value of 0 specifies no wrap margin.

writeany, wa  (default: nowa)

Inhibits the checks normally made before write commands, allowing a write to any file that the system protection mechanism allows.

Regular expressions

\<

Forces the match to occur only at the beginning of a word: the beginning of a line, or a letter, digit, or underline that follows a character that is not any of these.

\>

Similar to \<, but matches the end of a word: the end of the line, or a character that is not a letter, digit, or underline.

Examples

   set wrapmargin=15
   set nomagic
   "
   "Macro: <Ctrl>A puts current word in quotes
   "
   map! <Ctrl>A <Esc>B"aywi``<Esc>a"<Esc>"apa''
   "
   "Abbreviation: mY inserts "My Company Name"
   "
   abbr mY "My Company Name"

vi can be invoked as a line editor by using the ex command. ex reads commands from the standard input and executes them. The following short shell script contains an example of using ex to process a file. ls(C) is invoked to obtain a full directory listing. ex is used to remove all entries except those for directories from the listing, which is then displayed with more:

   tmpfile=$$.tmp
   ls -al > ${tmpfile}
   ex ${tmpfile} <<%%
   :g/^-.*/s///g
   :g/^$/d
   :w
   :q
   %%
   more ${tmpfile}

Limitations

The /usr/lib/expreserve program must be placed in the system startup file, /etc/rc.d/3/recovery, before the command that cleans out the /tmp directory. See the System Administration Guide for more information on the /etc/rc2 scripts.

Two options, although they continue to be supported, have been replaced in the documentation by the options that follow the Command Syntax Standard (see Intro(C)). A -r option that is not followed with an argument has been replaced by -L, and +command has been replaced by -c command.

vi does not strip the high bit from 8-bit characters read in from text files, text insertion, and editing commands. It does not look for ``magic numbers'' of object files when reading in a text file. It also writes out text and displays text without stripping the high bit.

vi uses the LC_CTYPE environment variable to determine if a character is printable, displaying the octal codes of non-printable 8-bit characters. It also uses LC_CTYPE and LANG to convert between upper and lowercase characters for the tilde command and for the ignorecase option.

When the percent sign (%) is used in a shell escape from vi via the exclamation mark (!), the ``%'' is replaced with the name of the file being edited. In previous versions of vi, each character in this replacement had the high bit set to 1 to quote it; in the current version of vi it is left alone.
Tampering with the entries in /usr/lib/terminfo/?/ (for example, changing or removing an entry) can affect programs such as vi that expect all entries to be present and correct. In particular, removing the ``dumb'' terminal entry may cause unexpected problems.

Software tabs using ^T work only immediately after the autoindent.

Left and right shifts on intelligent terminals do not make use of insert and delete operations in the terminal.

Files

/tmp

default directory where temporary work files are placed; it can be changed using the directory option (see the ex(C) set command)

/usr/lib/terminfo/?/

compiled terminal description database

See also

Chapter 4, ``Writing and editing'' in the SCO OpenServer Operating System Tutorial

Standards conformance

ISO/IEC DIS 99452:1992, Information technology Portable Operating System Interface (POSIX) Part 2: Shell and Utilities (IEEE Std 1003.21992);
AT&T SVID Issue 2;
X/Open CAE Specification, Commands and Utilities, Issue 4, 1992.

vedit and view are conformant with AT&T SVID Issue 2.

vi was developed at the University of California at Berkeley and is used with permission.