ex, vi, view -- display-oriented interactive text editor

SYNOPSIS

ex [-elRsvx] [-c command] [-t tag] [-w size] [-U[[[c][lb8oa]][p[lb8oa]]]] [file ...]

ex [-elRsvx] [+command] [-t tag] [-w size] [-U[[[c][lb8oa]][p[lb8oa]]]] [file ...]

vi [-elRsvx] [-c command] [-t tag] [-w size] [-U[[[c][lb8oa]][p[lb8oa]]]] [file ...]

vi [-elRsvx] [+command] [-t tag] [-w size] [-U[[[c][lb8oa]][p[lb8oa]]]] [file ...]

view [-elsvx] [-c command] [-t tag] [-w size] [-U[[[c][lb8oa]][p[lb8oa]]]] [file ...]

view [-elsvx] [+command] [-t tag] [-w size] [-U[[[c][lb8oa]][p[lb8oa]]]] [file ...]

CONVENTIONS

Throughout this document the following symbols are used:

CTRL-L: CTRL followed by a single letter indicates the control character transmitted by holding down the CTRL key and the letter key at the same time.
BACKSPACE: This indicates the real backspace key. On the PC, this has a back-arrow (<-) on it. This may differ from the CTRL-H key.
ENTER: This indicates the ENTER key, which is labelled RETURN on some keyboards. This may differ in effect from the CTRL-M key.
ESC: This indicates the Escape key.
INTERRUPT: This indicates the break key; CTRL-C or CTRL-BREAK on the PC.
→: This indicates the right arrow key.
←: This indicates the left arrow key.
↓: This indicates the down arrow key.
↑: This indicates the up arrow key.

DESCRIPTION

vi is a display-oriented interactive text editor.

view behaves identically to vi except that it automatically opens all files as read-only. This is equivalent to specifying the -R option for vi or setting the readonly variable.

viw (or Vi for Windows) is the same editor modified for the Windows environment. It supports all of the features of vi with the added benefits of Windows. For details about viw, see the viw reference page.

A version of viw can also be used as the editor for Microsoft Visual Studio. For details, see the viw_vs reference page.

There are two components to vi: a screen editor (Vi), and a line editor (Ex). Each has a different set of commands; you can invoke the line editor from within the screen editor and conversely, you can invoke the screen editor from within the line editor.

In the screen editor, you are in either insert mode or command mode. In command mode, every character you type is immediately interpreted as a command. In insert mode, every character you type is added to the text that you are editing.

There are two ways to start your session in Ex mode: you can invoke the command under the name ex; or you can invoke it under the name vi but specify the -e option. Similarly, there are two ways to start your session in Vi mode; you can invoke the command under the name vi (without specifying -e); or you can invoke it under the name ex but specify -v.

Vi and Ex work on text files. If a file contains the NUL character (value 0 or \0), it is turned into the value 0x7F. The newline character is interpreted as a line delimiter. Each line is limited to a maximum length of 1K bytes, including the newline. If any lines exceed that length, they are truncated at that length. If the last line in the file does not end in a newline, a newline is added. In all these abnormal cases, vi marks the file as modified and displays a message.

Besides normal ASCII text files, vi also works on UTF-8 files and 16-bit wide Unicode files. You can specify the format that vi uses to read the input by specifying a value for the infileformat option variable (see Set Option Variables). You can also set this variable to DETECT in which case, vi uses the multiple-byte marker that usually begins Unicode and UTF-8 files to determine if the file is Unicode big-endian, Unicode little-endian, or UTF-8. However, when the multiple-byte marker is missing, you can use the -U option or the TK_STDIO_DEFAULT_INPUT_FORMAT and TK_STDIO_DEFAULT_OUTPUT_FORMAT environment variables to force any file to be treated in a given forrmat (for example, UTF-8 or Unicode).

When writing new files, vi writes them out using the the value of the defaultfileformat option variable (see Set Option Variables) whose default value is determined by the -U option (if an output format is given) or the TK_STDIO_DEFAULT_OUTPUT_FORMAT environment variable. When writing to an existing file, vi uses the same format that was used to last read or write the file.

Additionally, the outfileformat option variable (see Set Option Variables) as well as the -f option of the edit, read, and write Ex commands (see Ex Commands) can also affect the input and output formats used.

For more details on this and other Unicode-related file handling issues see the unicode reference page.

Options

-c command

runs command before displaying any text on the screen. command is any Ex command. To specify multiple Ex commands, separate them with a vertical line character (|) and enclose them in quotes. The quotes ensure that the shell does not interpret the | as a pipe character. For example,

-c 'set all | ver'

runs both the set all and ver commands prior to displaying text.

-e

invokes ex.

-l

sets lisp mode. The ( and ) commands use blocks of lisp code as their context rather than sentences.

-R

sets the readonly variable, preventing the accidental overwriting of files. Any command that writes to a file requires the ! suffix.

-s

turns on quiet mode; this tells the editor not to display file information messages, thus allowing Ex to be used as a filter; since it doesn't display the file, it doesn't read the value of the TERM environment variable. This option also keeps Ex from reading any startup files, (ex.rc or EXINIT).

-t tag

edits the file containing the specified tag and sets the virtual position in the edit buffer to point of definition for the tag. (See ctags.) This is the same as the Ex tag command (described later).

-U[[[c][lb8oa]][p[lb8oa]]]

specifies the input format of any file missing the initial multiple-byte marker, the output format produced, or both.

When c is specified, the specifiers that follow it apply to the input consumed.

When p is specified, the specifiers that follow it apply to the output produced.

When neither c nor p are specified, the remaining -U specifiers apply to the input consumed.

When both c and p are specified, the remaining -U arguments apply to both input and output.

The remaining specifiers indicate the format of the characters read from input or written to output (as determined by c and p):

l     little-endian 16-bit wide characters
b     big-endian 16-bit wide characters
8     UTF-8 characters
a     ASCII characters from the ANSI code page
o     ASCII characters from the OEM code page

When multiple format specifiers can be associated with either c or p, the last appropriate one given on the command for each of c and p is used. For example:

-Ucoapl8

is the same as:

-Ucap8

When a p specifier is given without a c specifier and format specifiers are given before the p specifier, those format specifiers apply to the input. For example:

-Uopl

is the same as:

-Ucopl

When c or p is specified with no format specifies, little endian 16-bit wide characters are used by default for either input or output, as appropriate.

As an alternative to specifying formats for both input and output with the same -U option, you can specify the -U option multiple times. For example, the following are identical:

-Uca -Upb
-Ucapb

Note:

The -U specifiers are actually case-insensitive. For example, the following are all identical in their behavior:

-Ucl
-UcL
-UCl
-UCL

-v

puts the editor into Vi mode. With vi, view, and viw, its use is redundant.

-x

prompts you for an encryption key. All files read and written are run through the crypt utility using the key that you enter. The crypt utility must be in the current search path.

When reading encrypted files, vi uses crypt -t (not crypt -d). When writing encrypted files, vi uses crypt (not crypt -e).

-w size

sets the option variable window to size. See section Set Option Variables for more information.

+command

is an obsolete version of the -c option.

Syntax Highlighting

Syntax highlighting uses color to denote different syntax types while editing a source file. For example, reserved words may be colored blue and comments green. This makes user code stand out and may even help in the detection of errors prior to compilation or the display of HTML/XML source. Characters are highlighted as the user types so an unclosed syntax or comment block may temporarily cause user code or reserved words to be colored as comments or the other way round until the closing syntax patterns is entered.

Syntax highlighting in vi and viw (both standalone and the version for use with Microsoft Visual Studio) is controlled by the syntaxlanguage option variable, as described in Set Option Variables.

Syntax definitions for various programming, scripting, and markup languages are contained in vi syntax configuration files which have a .viw extension and reside in either the $ROOTDIR/etc/syntax directory or the $HOME/syntax directory. Additionally, the $ROOTDIR/etc/syntax/syntax.map file specifies which files (based on their names and extensions) should use which syntax configuration file. This file can be overridden by a $HOME/syntax/syntax.map file of your own creation which provides additional and alternative associations between file names or extensions and syntax configuration files. For a complete description of syntax configuration files and the syntax.map files, see the vi file format reference page.

Current Position Pointer

The current position pointer indicates a position in the text that is currently being edited (or has just been edited). In Ex mode, the current position pointer is just the line number of the line being edited. In Vi mode, the pointer gives this line number plus the position of the cursor within the line. The line indicated by the current position pointer is always on the screen.

Display Conventions

vi uses three display conventions that should be noted.

vi displays the input for search commands (/ and ?), Ex commands (:), and system commands (!) on the bottom line of the screen. Error and informational messages also appear on this line.

If the last line in the file is above the bottom of the screen, screen lines beyond the end of the file are displayed with a single ~ character in column one.

In certain infrequent circumstances (usually involving lines longer than the width of the screen), vi is unable to fill the display with complete lines. In this case, one or more screen lines are shown with a single @ character in column one.

These lines are not part of the file content and should be ignored.

Vi Command Summary

Vi commands may be divided into several categories.

(a): adjust the position of text on the screen. The current position pointer only changes if the current line is scrolled off the screen. For example, CTRL-E scrolls the text on the screen up one line. The cursor remains pointing to the same text that it was pointing to, unless that text is moved off the screen.
(b): move the cursor in the file. For example, the character j moves the cursor down one line and the screen is scrolled only if necessary. There are two types of movement commands: absolute movements and context-dependent movements. An absolute movement moves the cursor, regardless of the nature of the surrounding text; for example, j always moves the cursor down one line. A context-dependent movement moves the cursor based on the nature of the text; for example, w moves the cursor to the beginning of the next word, so it must look at the text to determine where the next word begins.
(c): commands let you change the text that is already in the file.
(d): commands let you add new text to the existing text.

Vi scrolling and movement commands may be preceded by a decimal integer which serves as a count, as in:

[count] command

count means different things with different commands. If you type count, it is not displayed anywhere on the screen.

Scrolling

CTRL-B: scrolls text back a page (that is, a screen), less two lines. The cursor is placed on the bottom line of the screen. count specifies a number of pages to scroll. The default value for count is 1.
CTRL-D: scrolls text onto the bottom of the screen. The current position pointer moves forward the same amount in the text, which means that the cursor stays in the same relative position on the screen. If count is given, the screen scrolls forward by the given number of lines; this number is used for all future CTRL-D and CTRL-U commands (until a new count is given). The default scrolling amount is half the screen.
CTRL-E: scrolls a new line onto the bottom of the screen. The current position pointer is not changed unless the current line scrolls off the top of the screen; then the pointer is set to the top line. If count is given, the screen scrolls forward the given number of lines. The default value for count is 1.
CTRL-F: scrolls text forward a page (that is, a screen), less two lines. The cursor is placed on the top line of the screen. count specifies the number of pages to scroll. The default value for count is 1.
CTRL-U: scrolls text onto the top of the screen. The current position pointer moves backward the same amount in the text, which means that the cursor stays in the same relative position on the screen. count operates as for CTRL-D. The default scrolling amount is half the screen.
CTRL-Y: scrolls a new line onto the top of the screen. The current position pointer is not changed unless the current line scrolls off the bottom of the screen; then the pointer is set to the bottom line. If count is given, the screen scrolls backward the given number of lines. The default value for count is 1.
[n] z [m] type: redraws the screen in a window of m lines. type determines the position of the current line. If type is the newline character, the current line is placed at the top of the window. If type is a period (.), the current line is placed in the middle of the window. If type is a minus sign (-), the current line is placed at the bottom of the window. If n is given, the current position pointer is first set to that absolute line number; then the screen is positioned according to type. If you omit n, it defaults to the current line. If you omit m, it defaults to window (see Set Option Variables).

Absolute Movement

All the following movement commands except m, 0, ^, `, and ' may be preceded by count to repeat the movement that many times.

G: moves to the absolute line number specified as count. If count is zero or is not specified, the cursor is moved to the last line of the file.
h
←
CTRL-H
BACKSPACE: moves the cursor one position to the left.
j
↓
CTRL-J
CTRL-N: moves the cursor to the next line at the same column on the screen. Scroll the screen one line if needed.
k
↑
CTRL-P: moves the cursor to the previous line at the same column on the screen. Scroll the screen up one line if needed.
l
→
SPACE: moves the cursor one position to the right.
m: records the current position pointer under a mark name. A mark name is a single lowercase letter, given immediately after the m. For example, the command ma records the current location of the current position pointer under the name a.
0: (Zero) moves the cursor to the first character of the current line.
+
CTRL-M: moves the cursor to the first non-blank character on the next line. The screen scrolls one line if needed.
-: moves the cursor to the first non-space character on the previous line. The screen scrolls one line if needed.
|: moves the cursor to the column number specified as count. This is a screen column number, not a line offset. If count is greater than the length of the current line, vi moves the cursor to the last character on the line. If the column indicated is spanned by a tab, vi moves the cursor to the first character after the tab.
^: moves the cursor to the first non-blank character of the current line.
_: moves the cursor to the first non-blank character of a line. count specifies the number of lines, including the current line, to move forward. As a result, the command 1_ is the same as ^.
$: moves the cursor forward to the end of a line. count specifies the number of lines, including the current line, to move forward.
`: when followed by a mark name, moves the cursor to the position that has been associated with that name. The position is set by the m command. A grave character followed by another grave character moves the cursor to the previous context. The previous context is typically the last place where you made a change. More precisely, the previous context is set whenever you move the cursor in a non-relative manner.
': is similar to the grave (`) character, except that the cursor is set to the first non-blank character on the marked line.

Movement By Context

vi defines a word in the following two ways:

a sequence of letters, digits, and underscores delimited at both ends by: (1) characters that are not letters, digits, or underscores, (2) the beginning or end of a line, or (3) the end of the editing buffer.

a sequence of characters other than letters, digits, underscores, or white space delimited at both ends by: (1) a letter, digit, underscore, white space, (2) the beginning or end of a line, or (3) the end of the editing buffer.

vi defines a full word as a sequence of non-blank characters delimited at both ends by blank characters (SPACE, TAB, NEWLINE) or by the beginning or end of a line or file.

B

moves the cursor back to the first character of the current full word. If the cursor is already at the beginning of a full word, vi moves it to the first character of the preceding full word.

b

moves the cursor back to the first character of the current word. If the cursor is already at the beginning of a word, vi moves it to the first character of the preceding word.

E

moves the cursor forward to the end of the current full word. If the cursor is already at the end of a full word, vi moves it to the last character of the next full word.

e

moves the cursor forward to the end of the current word. If the cursor is already at the end of a word, vi moves it to the last character of the next word.

Fc

searches backward in the line for the single character c and positions the cursor on top of it. When count is given, the editor searches back for the countth such character.

fc

searches forward in the line for the single character c and positions the cursor on top of it. When count is given, the editor searches for the countth such character.

H

places the cursor on the first non-blank character of the top line of the screen. count specifies the number of lines from the top of the screen.

L

places the cursor on the first non-blank character of the bottom line of the screen. count specifies the number of lines up from the bottom of the screen.

M

places the cursor on the first non-blank character of the middle line of the screen.

N

repeats previous / or ? command, but in the opposite direction.

n

repeats previous / or ? command.

Tc

searches backward in the line for the character c and positions the cursor after the character being sought. count searches backward for the countth matching character and then positions the cursor after the character being sought.

tc

searches forward in the line for the character c and positions the cursor on the preceding character. count searches forward for the countth matching character and positions the cursor on the preceding character.

W

moves to the start of the next full word.

w

moves to the start of the next word.

(

moves back to the beginning of the current sentence. A sentence is bounded by a period (.), exclamation mark (!), or question mark (?); followed by any number of closing double quotes, ("), closing single quotes ('), closing parentheses (), or closing square brackets (]); followed by two spaces or the end of the line. Paragraph and section boundaries are also sentence boundaries; see [[ and {.

)

moves to the beginning of the next sentence. See ( for the definition of a sentence.

{

moves back to the beginning of a paragraph. A paragraph begins on a blank line, a section boundary (see [[) or a text formatter macro in the paragraphs variable.

}

moves to the beginning of the next paragraph. See { for the definition of a paragraph.

[[

moves back to the beginning of a section. A section begins on lines starting with a formfeed (CTRL-L); starting with an open brace {; a text formatter macro in the sections variable; or begin or end of file.

]]

moves to the beginning of the next section. See [[ for the definition of a section.

%

finds the balancing character to that under the cursor. The character should be one of the following characters:

[{(<  >)}].

;

repeats the previous F, f, T, or t command.

,

repeats the previous F, f, T, or t command in the opposite direction.

/regexp

searches forward in the file for a line matching the regular expression regexp and positions the cursor at the first character of the matching string. When used with an operator to define a text range, the range begins with the character at the current cursor position and ends with the first character of the matching string. You can specify whole lines by following regexp with /+n or /-n where n is the offset from the matched line.

?regexp

is similar to /, but searches backwards in the file.

CTRL-]

uses the word after the cursor as a tag. See tag under Ex Commands.

Object Manipulators

An object manipulator command works on a block of text. The command character is followed immediately by any kind of movement command. The object that is manipulated by the object manipulator command is the text from the current position pointer to wherever the movement command would leave the cursor.

For example, in dL, d is the object manipulator command to delete an object. It is followed by the movement command L which means move to the bottom line of the screen. The object manipulated by the command thus extends from the current line to the bottom line on the screen; these lines are deleted.

Normally an object extends up to, but not including, the position of the cursor after the move command; however, some movements work in a line mode; for example, L puts the cursor on the first non-blank character of the last line on the screen. If it is used in an object manipulation command, it includes the entire starting line and the entire ending line. Some other objects include the cursor position; for example, d$ deletes up to and including the last character on a line; by itself the $ would have placed the cursor on the final character. Repeating the command letter (or symbol) implies working on a line basis; thus 5dd deletes five lines.

Objects that are deleted or otherwise manipulated have their original values placed in a buffer, an area of computer memory that can hold text. There are several ways this can be done:

You can use a named buffer. Buffers are named with single lowercase letters. To place an object in a buffer, type a double quote " followed by the buffer name, followed by the object manipulator command, as in
```
"adL
```
This deletes text from the current line to the bottom line on the screen and puts the deleted text in buffer a. Normally, this sort of operation overwrites the current contents of the buffer; however, if you use the same form but specify the buffer name in uppercase, the object is appended to the current contents of the buffer. For example,
```
"AdL
```
deletes from the current line to the bottom line on the screen, and adds the deleted text to buffer a.

By setting the clipboardbuffer (or clip for short) option variable (see Set Option Variables to a named buffer, you can cut, copy, and paste text to and from the Windows clipboard by simply accessing that buffer.

For example, suppose your $HOME/ex.rc contained
```
set clip=x
```
The following vi instructions would have the listed effects:
```
"x4yy    copies four lines to the clipboard
"Xdw     appends a word to the clipboard
"xp      pastes from the clipboard
```

If you are deleting material and delete at least one full line, vi uses buffers numbered 1 through 9. The first time a full line or more is deleted, the text is placed in buffer 1. The next time, the old contents of 1 are copied to 2, and the newly deleted text is put into 1. In the same way, deleted text continues to be rippled through the nine numbered buffers. When text is rippled out of buffer 9, it is gone for good.

In all other cases, the object manipulated goes to the unnamed buffer. For example, the unnamed buffer is used if you delete less than a line of text. The unnamed buffer is like the other buffers, but doesn't have a name.

The following examples illustrate the use of buffers.

dL: deletes text from current cursor position through to the bottom of the screen and places it into buffer 1; it also ripples numbered buffers.
ad/fred/: delete from current cursor position through to the next position containing (but not including) the string fred, and place the deleted text into buffer a.
dw: deletes the current word and places it in an unnamed buffer.

The object manipulator commands are:

c: deletes the object and enters insert mode for text insertion after the current cursor position. If less than one line is changed, a dollar sign ($) is placed on the final character of the object and typing goes directly over top of the current object until the dollar sign ($) is reached. Additional text is inserted, and the existing text shifts to make room for the new text.
d: deletes the object.
y: yanks the object to the appropriate buffer; the original object is not changed. This may be used to duplicate or copy objects.
<: shifts the object left by the value of the variable shiftwidth. This operator always works on a line basis. This command replaces existing blanks and tabs at the beginning of the line with the minimum number of tabs and spaces required to create the new indent amount. count shifts count lines.
>: shifts the object right by the value of the variable shiftwidth. This operator always works on a line basis. This command replaces existing blanks and tabs at the beginning of the line with the minimum number of tabs and spaces required to create the new indent amount. count shifts count lines.
!: filters the object through an external command. After typing the object, the command line opens up for a system command which is parsed in the same manner as the Ex system command (:!). This operator then invokes the given command and sends the entire object on a line basis to that command. The object is then deleted and the output from the command replaces it. For example, 1G!Gsort moves to the first line of the file; then takes all the text from the first line to the last line and runs it through the sort command.

Object Manipulator Abbreviations

To make things easier, vi supports the following shorthand commands. Each can be preceded by count and/or by a buffer name to save the manipulated text.

C: changes to the end of the current line. This is equivalent to the c$ command.
D: deletes to the end of the current line. This is equivalent to the d$ command.
S: substitutes current line. This is equivalent to the cc command.
s: substitutes current character. This is equivalent to the cl command.
X: deletes the previous character. This is equivalent to the dh command.
x: deletes the current character. This is equivalent to the dl command.
Y: yanks current line. This is equivalent to the yy command.

Inserting Text

vi supports the following commands for inserting text:

A: enters insert mode at end of line. This is equivalent to the $a command.
a: enters insert mode after the current cursor position.
I: enters insert mode before first non-blank character on line. This is equivalent to the ^i command.
i: enters insert mode before the current cursor position.
O: opens up a new line before the current line and enters insert mode on it.
o: opens up a new line after the current line and enters insert mode on it.
R: replaces characters on the screen with characters typed up to the next ESC. Each character typed overlays a character on the screen. The newline character is an exception; it is simply inserted and no other character is replaced. While you are doing this, the screen may not correspond exactly to the contents of the file, due to tabs, etc. The screen is properly updated when you leave insert mode.
r: replaces the character under the cursor with the next character typed. When count is given, count characters following the cursor are all changed to the next character typed. If count is given and the newline character is the replacement character, count characters are deleted (as usual) and replaced with a single newline character, not count newlines.

Miscellaneous

J: joins count lines together. If you do not specify count or count is less than 2, vi uses a count of 2, joining the current line and the next line. This command supplies appropriate spacing: one space between words, two spaces after a period, and no spaces at all when the first character of the next line is a closing parenthesis ()). When a line ends with white space, vi retains the white space, does not add any further spaces, and then appends the next line.
P: puts buffer contents before the cursor. This is also called a paste operation. If preceded by quote buffername (for example, "b), the contents of that buffer are used; otherwise the contents of the unnamed buffer are used. If the buffer was created in Ex mode, the contents of the buffer are inserted before the current line. If the buffer was created in Vi mode, the contents are inserted before the cursor. As a special case, if a paste operation is repeated with the period (.) command and it used a numbered buffer, the number of the buffer is incremented. Thus, "1p....., pastes in the contents of buffer 1 through buffer 6; in other words the last six things that were deleted are put back.
p: is similar to P except that text is pasted after the cursor instead of before it.
Q: switches to Ex mode. You leave Vi mode and the Ex prompt is shown on the bottom line of the screen.
U: undoes all changes to current line. As soon as you move off a line or invoke an Ex command on the line, the original contents of the line are forgotten and U is not successful.
u: undoes last change. If repeated, you undo the undo (that is, go back to what the text was before the undo). Some operations are treated as single changes; for example, everything done by a global G is undone with undo.
ZZ: writes the file out, if changed, then exits. Equivalent to the Ex command xit.
.: repeats the last command. Any command which changes the contents of the file may be repeated by this command. If you do not specify count with the . command, vi uses the count that was specified for the command being repeated.
~: toggles the case of the character under the cursor and moves the cursor right by one. This command may be preceded by count to change the case of count characters.
&: repeats the previous Ex substitute command using the current line as the target. Flags set by the previous command are ignored. Equivalent to the Ex command &.
:: invokes an Ex command. The editor places the cursor on the bottom line of the screen and displays a colon (:) to prompt for input. You may then type an Ex command; when you press ESC or ENTER, the line you have entered is passed to Ex and run there.
@: invokes a macro. When the next character is a letter from a through z, vi treats it as the name of a buffer. The contents of that buffer are treated as input typed to vi. The text of a macro may contain an @ calling another macro. A macro may call itself, provided it is invoked at the end of the macro (tail recursion). Such a macro runs forever or until an error occurs or the INTERRUPT key is pressed. A macro that invokes itself at the beginning (head recursion) loops until it runs out of memory. A vi error terminates all currently executing macros. All changes made during a macro call are treated as a unit and may be undone with a single u command.
CTRL-G: displays the current path name, current line number, total number of lines in the file, and the percentage of the way through the file. This is equivalent to invoking the Ex command file.
CTRL-L: redraws the screen assuming another process has written on it. This should normally never happen unless a filter ! command writes to the screen rather than the standard output.
CTRL-R: redraws the screen, removing any deleted lines flagged with the @ convention.
CTRL-^: switches to editing the alternate file (see write under Ex Commands). If you attempt this and you have not written out the file since you made the most recent change, vi does not switch to the alternate file.

Special Keys

Keys like the function keys and the cursor arrow keys do not correspond to particular characters. These keys can be programmed to be interpreted as any character sequence, using the Ex map and map! commands. See vipc for the symbolic names and default programming of these keys.

Insert Mode

The object manipulation command c, and the text insertion commands [AaIiOoRr] put Vi into INSERT mode. In this mode, most characters typed are inserted in the file. The following characters have special meaning.

CTRL-D: decrements the autoindent for the current line by one level. This is only relevant if the variable autoindent is on. See the Set Option Variables section for more details.
CTRL-H
BACKSPACE: deletes the last typed character. The character is not removed from the screen; however it is no longer in your file. When you backspace over characters, new text overwrites the old ones. You are permitted to backspace to the start of the current line regardless of where you started to insert text. (This is not true of some other versions of Vi.)
CTRL-J
CTRL-M
ENTER: ends the current line and starts a new one.
CTRL-Q
CTRL-V: inserts the next character typed as that character instead of using its special meaning. This is normally used to escape, say, the ESC character itself. It is impossible to escape CTRL-J or the null character in your line. If you try to insert a CTRL-M, it disappears the next time you edit your file under Windows.
CTRL-T: increments the autoindent for the current line by one level. This is only relevant if the variable autoindent is on.
CTRL-W: deletes the word preceding the cursor and blanks. Even though the characters are not removed from the screen, they are no longer in your file.
CTRL-@
ALT-A: when this is the first character typed after entering insert mode, the previously typed insert mode contents are repeated; after this, you exit insert mode. Only up to the first 256 characters from the previous insertion are inserted. CTRL-@ is the keystroke that performs this operation on UNIX; however on Windows, this keystroke is not returned by the system. ALT-A must be used instead.
←: backs over the last typed character. Characters typed are inserted before these characters backed over.
CTRL-U: deletes inserted line. The cursor is moved to the first character that was inserted on the current line. The characters are not removed from the screen; however they are no longer in your file. If you have backspaced past the point that you started inserting text, this deletes to the start of the current line. You can change the character that deletes an inserted line with the linedelete variable described in Set Option Variables.
ESC
INTERRUPT: leaves insert mode.

Ex Command Mode

vi enters Ex command mode if the program is invoked with the -e option or if the Q command is issued from Vi. You can issue a single Ex command from Vi mode by using the : command.

An Ex command takes the general form

[address-list] [[command] [!] [parameters]]

Each part is optional and may be invalid for some commands. You may specify multiple commands on a line by separating them with a vertical line character (|).

address-list

Commands may take zero, one, or two addresses. The address % is a short form to indicate the entire file. You may omit any or all of the addresses. In the command description in the Ex Commands section, the addresses shown are the addresses that the commands use by default.

Possible default addresses are:

[.,.]: Indicates a two address line range defaulting to the current line.
[1,$]: Indicates a two address line range defaulting to the entire file.
[.+1]: Indicates a single address defaulting to the next line.

address

An address refers to a line in the text being edited. An address may be an expression involving the following forms:

.: The value of the current line indicator.
n: A line number indicating an absolute line in the file; the first line has absolute line number 1.
$: The last line in the file.
+[n]: n lines forward in the file. If you omit n, it defaults to 1.
-[n]: n lines backward in the file. If you omit n, it defaults to 1.
'x: The value of the mark x.
/pat/: Search for regular expression pat forward from the current line.
?pat?: Search for regular expression pat backwards from the current line.

Thus,

/pattern/+3
++
100

are three addresses: the first searches for a pattern and then goes three lines further; the second indicates two lines after the current line; and the third indicates the 100th line in the file.

command

The command is a word, which can be abbreviated. Characters shown in square brackets are optional. For example,

a[ppend]

indicates that the append command can be abbreviated to simply a.

!

Some commands have a variant; this is usually toggled with an exclamation mark (!) immediately after the command.

parameters

Many Ex commands use parameters to allow you to specify more information about the command. Common parameters include:

buffer

specifies one of the named areas for saving text. For more information, see the description of buffers in the Object Manipulators section of this reference page.

count

is a positive integer, specifying the number of lines to be affected by the command. If you omit count, it defaults to 1.

file

is the path name for a file. If file includes the % character, vi replaces that character with the path name of the current file. If file includes the # character, vi replaces that character with the path name of the alternate file. If you do not specify file, the default is the current file.

flags

indicate actions to be taken after the command is run. It may consist of leading plus (+) and minus (-) signs to adjust the value of the current line indicator; followed by p, l, or # to display, list or number a line.

Thus

.+5 delete 6 ++#

deletes starting five lines down from the current line; six lines are deleted; the current line indicator is set to the following line, then incremented by two; and that line is displayed with its line number.

Regular Expressions and Replacements

Many Ex commands use regular expressions when searching and replacing text. A regular expression (indicated by pat in the command descriptions) is used to match a set of characters. A replacement (indicated by repl in the command descriptions) describes what to put back in a line for the set of characters matched by the regular expression.

A regular expression consists of a string of normal characters which exactly match characters in a line. These may be intermixed with special characters (known as metacharacters) which allow matching in some special manner. Metacharacters may themselves be matched directly by preceding them with the backslash (\) character. If the variable magic (see the Set Option Variables section) is turned off, all but two of the metacharacters are disabled; in this case, the backslash character must precede them to allow their use as metacharacters. See regexp for examples.

Regular Expression Summary

^: matches the start of a line. This is only a metacharacter if it is the first character in the expression.
$: matches the end of a line. This is only a metacharacter if it is the last character in the expression.
.: matches any single character.
*: Matches zero or more occurrences of the previous expression.
\<: matches the empty string preceding the start of a word. A word is a series of alphanumeric or underscore characters preceded and followed by characters which are not alphanumeric or underscore.
\>: matches the empty string following the end of a word. A word is a series of alphanumeric or underscore characters preceded and followed by characters which are not alphanumeric or underscore.
[string]: matches any of the characters in the class of characters defined by string. For example, [aeiouy] matches any of the vowels. You can put a range of characters in a class by specifying the first and last characters of the range, with a hyphen (-) between them. For example, in ASCII [A-Za-z] matches any upper or lowercase letter. If the first character of a class is the caret (^), the class matches any character not specified inside the square brackets. Thus, in ASCII [a-z_][^0-9] matches a single alphabetic character or the underscore, followed by any non-numeric character.
$...$: (escaped parentheses) may surround a set of characters in the pattern. See the discussion of the \n replacement pattern, that appears under Replacement Pattern Summary, to find the meaning of this construct. This is not affected by the setting of the variable magic (see the Set Option Variables section).
~: matches the replacement part of the last substitute command.

Replacement Pattern Summary

&

is replaced by the entire string of matched characters.

~

is replaced by the entire replacement pattern from the last substitute.

\n

is replaced by the string that matched the nth occurrence of a $ ... $ in the regular expression. For example, consider

s/\([a-zA-Z]*\)our/\1or/

The \1 represents the string that matched the regular expression $[a-zA-Z]*$. Thus the previous command might change the word colour to color.

\u

turns the next character in the replacement to uppercase.

\l

turns the next character in the replacement to lowercase.

\U

turns subsequent characters in the replacement to uppercase.

\L

turns subsequent characters in the replacement to lowercase.

\E, \e

turns off the effects of \U or \L.

Ex Commands

These commands can be entered as shown in Ex mode. In Vi mode, they must be preceded by the colon (:) character.

ab[breviate] [word rhs]

indicates the word word is to be interpreted as an abbreviation for rhs (see previous definition of word in the section entitled Movement By Context). If you enter word surrounded by white space (or any characters that cannot be part of a word) in Vi INSERT mode, it is automatically changed into rhs. If you do not specify any arguments for the ab command, it displays the abbreviations that are already defined. Abbreviated names cannot contain # or any other forms of punctuation.

[.] a[ppend][!]

enters Ex INSERT mode. Text is read and placed after the specified line. An input line consisting of one period (.) leaves INSERT mode without inserting the period. If you specify an address of zero, text is inserted before the first line of the file. The current line indicator points to the last line typed.

If an exclamation mark (!) is specified, the autoindent option is toggled during input. This command may not be invoked from Vi mode.

ar[gs]

displays the current list of files being edited. The current file is shown enclosed by square brackets.

cd[!] [path]

changes the current directory to path. If you omit path, cd sets the current working directory to the directory identified by the home variable. If path is a relative path name, cd searches for it using the directories specified in the cdpath variable. If path is - (the dash), then cd changes to the previous working directory. If you have modified the buffer since the last write, vi displays a warning message. You can override this behavior by including the exclamation mark (!).

[.,.] c[hange][!] [count]

deletes the line range given and then enters INSERT mode. If an exclamation mark (!) is specified, autoindent is toggled during input. This command may not be invoked from Vi mode.

chd[ir][!] [path]

is the same as cd.

[.,.] co[py] addr [flags]

copies the line range given after addr. If addr is zero, the lines are inserted before the first line of the file. The current line indicator points to the last line of the inserted copied text.

[.,.] d[elete] [buffer] [count] [flags]

deletes the specified line range. After deleting the line range, the current line indicator points to the line after the deleted range. A buffer may be specified as a letter a-z; if so, deleted lines are saved in the buffer with that name. If an uppercase letter is specified for buffer, the lines are appended to the buffer of the corresponding lowercase name. If no buffer name is given, deleted lines go to the unnamed buffer.

e[dit] [!] [-f filefmt] [+line] [file]

ex [!] [-f filefmt] [+line] [file]

begins a new editing session on a new file; the new file replaces the old file on the screen. Normally, this command is invalid if you have modified the contents of the current file without writing it back to the file. Specifying an exclamation mark (!) goes on to start a new session even if you have not saved the changes of the current session. You can specify line as either a line number or as a string of the form /regexp or ?regexp where regexp is a regular expression. When line is a line number, the current line indicator is set to that position. When it has the form /regexp, vi searches forward through the file for the first occurrence of regexp and sets the current line indicator to that line. ?regexp is similar to /regexp, except that vi searches through the file backwards. If you omit line and do not specify a file, the value of the current line indicator does not change; otherwise if a file is specified, the current line indicator is set to either the first or last line of tha buffer, depending upon whether the command was issued in Vi or Ex mode.

The edit command does not destroy buffers, so you can use the yank and put commands to move text between files. The edit command sets the alternate file name to the old file, so you can return to that file with e #.

The -f option, if present, specifies filefmt, one of the file character formats defined in the File Character Formats section of the unicode reference page. If the specified file exists, it is read as though it was in that format. If file does not exist, -f has no effect.

f[ile] [file]

changes the current file name to file and marks it [Not Edited]. If this file exists, it may not be overwritten without using the exclamation mark (!) variant of the write command. If no file is specified, the editor displays information about the current file.

[1,$] g[lobal] [!] /pat/ [commands]

matches pat against every line in the given range. On lines which match, the commands are run. If the exclamation mark (!) variant is set, the commands are run on lines which do not match. This is the same as using the v command (described later in this section).

The global command and the undo command may not occur in the list of commands. A subsequent undo command undoes the effect of the entire global command. In Ex mode, multiple command lines may be entered by ending all but the last with backslash (\). Commands which would take input are permitted; the input is included in the command list, and the trailing period (.) may be omitted at the end of the list. For example,

g/rhino/a\
hippo

appends the single line hippo to each line containing rhino. The total length of a global command list is limited (see LIMITS).

You can use any non-alphabetic character to delimit pat instead of the slash (/).

[.] i[nsert][!]

enters Ex INSERT mode, reads text and places it before the specified line; otherwise, this is identical to the append command. This command may not be entered from Vi mode.

[.,.+1] j[oin][!] [count] [flags]

joins together the lines of text within the range. If an exclamation mark (!) is specified, the lines are join with no content change.

If an exclamation mark (!) is not specified, all white space between adjacent joined lines is deleted and replaced with zero, one, or two spaces. Two spaces are used if the previous line ended in a period (.); zero spaces if the joined line begins with a closing parenthesis ()); and one space in all other cases.

[.] k x

is synonymous with the mark command.

[.,.] l[ist] [count] [flags]

displays the line range in a visually unambiguous manner. This command displays tabs as ^I, and the end of lines as $. The only useful flag is #, for line numbering. The current line indicator points to the last line displayed.

map[!] [lhs rhs]

defines macros for use in Vi. The lhs is a string of characters; whenever that string is typed exactly, vi behaves as if the string rhs had been typed. If lhs is more than one character long, none of the characters are echoed or acted upon until either a character is typed that isn't in the lhs (in which case all the characters up to that point in the lhs are run) or the last character of lhs is typed. If the variable remap is set, rhs itself may contain macros. If the flag ! is specified, the map applies within Vi INSERT mode; otherwise it applies to command mode. A map command with no arguments lists all macros currently defined. Special keys, such as function keys, may also be set; see vipc.

[.] ma[rk] x

records the specified line as being marked with the single lowercase letter x. The line may then be addressed at any point as 'x.

[.,.] m[ove] addr [flags]

moves the specified line range after the addr given. If addr is zero, the text is moved to the start of the file. The current line indicator is set to the last line moved.

n[ext][!] [+command] [file ...]

begins editing the next file in the file list (where the file list was either specified on the command line or in a previous next command). If the current file has been modified since the last write, Ex normally prevents you from leaving the current file; you can get around this by specifying an exclamation mark (!). If autowrite is set, the current file is written automatically and you go to the next file. If a list of files is specified, they become the new file list. If necessary, expressions in this list are expanded, thus

next *.c

sets the file list to all the files in the current directory with names ending in .c (typically C source files).

[.,.] nu[mber] [count] [flags]

[.,.] # [count] [flags]

displays the specified line range with leading line numbers. The current line indicator points to the last line displayed.

[.] o[pen] [/pat/] [flags]

enters open mode, which is simply Vi mode with a variable length one line window. If a match is found for the regular expression pat in the specified line the cursor is placed at the start of the matching pattern.

You can use any non-alphabetic character to delimit pat instead of the slash (/).

[.,.] p[rint] [count] [flags]

displays the specified line range. The current line indicator points to the last line displayed.

[.] pu[t] [buffer]

pastes deleted or yanked lines back into the file after the given line. If no buffer name is given, the most recently changed buffer is used.

Since the edit command does not destroy buffers, you can use that command in conjunction with put and yank to move text between files.

q[uit][!

exits from Vi/Ex. If the current file has been modified, an exclamation mark (!) must be used or you cannot exit until you write the file.

[.] r[ead][!] [-f filefmt] [file]

reads the contents of file and inserts them into the current file after the given line number. If the line number is 0, the contents of the given file are inserted at the beginning of the file being edited. If the current file name is not set, a file must be given, and it becomes the current file name; otherwise, if a file is given, it becomes the alternate file name. If the file begins with an exclamation mark (!), it is taken as a system command. The output from that system command is read in via a pipe after the given line number.

The -f option, if present, specifies filefmt, one of the file character formats defined in the File Character Formats section of the unicode reference page. The specified file is read as though it was in that format.

rew[ind][!

rewinds the file argument list back to the beginning and starts editing the first file in the list. If the current file has been modified, an exclamation mark (!) must be specified; otherwise, you cannot leave the current file until you have written it out. If autowrite is set, the current file is written out automatically if it needs to be.

se[t] [parameter-list]

assigns or displays the values of option variables. If you do not specify a parameter list, set displays all the variables with values that have changed since the editing session started. If the parameter all is specified, Ex displays all variables and their values. You may use the parameter list to set or display each of many variable values. Each argument in the list is a variable name; if it is a Boolean variable, the value is set on or off depending on whether the name is prefixed by no. Non-Boolean variables alone in an argument are a request to display their values. You may display a Boolean variable's value by appending a question mark (?) to the name. You can set numeric or string variables with

name=value

In a string variable, spaces must be preceded by a backslash. As an example,

set readonly? noautowrite shell=/bin/sh

shows the value of the readonly flag, sets noautowrite, and sets the shell to ROOTDIR/bin/sh.

set report report=5

shows the value of the report variable and then sets the value to 5. See section Set Option Variables for further details.

sh[ell]

invokes a subshell. The SHELL environment variable is used to find the name of the shell to run. On Windows systems, this is normally cmd.exe. It can also be one of the shells provided by the MKS Toolkit, such as the MKS KornShell (sh) or MKS C Shell (csh). You normally return to the editor from the launched subshell with the exit.

so[urce] file

runs editor commands from file. A file being run with source may contain source commands of its own.

st[op]

vi and view do not support this command. When this command is issued in viw, the viw program window is minimized.

[.,.] s[ubstitute] [/pat/repl/] [options] [count] [flags]

searches each line in the line range for the regular expression pat and replaces matching strings with repl. Normally, Ex only replaces the first matching string in each line; if options contains g (global), all matching strings are changed. If options contains c (confirm), Ex first displays the line with caret (^) characters marking the pat matching location; you can then type y if you want Ex to go ahead with the substitution. pat cannot match over a line boundary; however in Ex mode, repl may contain a newline, escaped by a preceding backslash (\). See the section on regular expressions for full information on both pat and repl. If there is no pat and/or repl, Ex uses the most recently specified regular expression and/or replacement string. You can use any non-alphabetic character in place of the slash (/) to delimit pat and repl.

su[spend]

is the same as stop.

[.,.] t addr [flags]

is the same as the copy command.

ta[g][!] tagname

looks up tagname in the files listed in the variable tags. If the tag name is found in a tags file, that file also contains the name of the file that contains the tag and a regular expression required within that file to locate that tag. If the given file is different from the one you are currently editing, Ex normally begins editing the new file; however, if you have modified the current file since the last time it was written out, Ex does not start editing a new file unless the tag command contains an exclamation mark (!). (If autowrite is on, the current file is automatically written out and the new file read in.) When the new file is read in, the regular expression from the tags file is invoked with the variable magic off (see the Set Option Variables section).

Tag names are typically used to locate C function definitions in C source files. The first step is to create a tags file using the ctags command. Once you do this, you can use the Ex tag command to look up a particular function definition and go directly to that definition in the file that contains it.

All characters in tag names are significant unless the variable taglength is non-zero; in this case, only the given number of characters are used in the comparison.

una[bbreviate] lhs

The abbreviation lhs previously created by abbreviate is deleted.

u[ndo]

undoes the last change or set of changes which modified the buffer. Global changes and Vi macros are considered single changes that can be undone. A second undo undoes the undo restoring the previous state. The edit command may not be undone, since it cleans up the temporary file used to maintain undo information. You cannot undo operating system commands and commands that write output to the file system.

unm[ap][!] lhs

deletes the map of lhs. If the flag !, this applies to the insert mode maps; otherwise it applies to the command mode maps.

[1,$] v /pat/ commands

is the same as the global command with the ! flag; that is, a global for all non-matching lines. You can use any non-alphabetic character to delimit pat instead of the slash (/).

ve[rsion]

displays the current version information for Vi/Ex.

[.] vi[sual] [type] [count] [flags]

enters Vi mode. If no type is specified, the current line is at the top of the screen. If type is caret (^), the bottom line of the screen is one window before the current line. If type is a minus sign, (-), the current line is at the bottom of the screen and if type is a period (.), the current line is in the middle of the screen.

You can use the undo command to undo all changes that occurred during the vi command.

[1,$] w[rite][!] [-f filefmt] [>>] [file]

writes the given range of lines to file. If two right angle brackets (>>) are included, the lines are appended to the file's current contents. If the current file name is not set, file must be given; this becomes the current file name; otherwise, file (if specified) becomes the alternate file name. If file begins with an exclamation mark (!), it is taken as a system command. vi writes the given range to the command through a pipe.

If a file is given, it must not already exist. The variable readonly must not be set. If a file is not given, the file must be edited; that is, it must be the same file as that read in. All these conditions may be overridden by using the flag !.

[1,$] wn[!] [>>] [file]

is similar to write, except that it begins editing the next file in the file list immediately afterwards (if the write is successful).

[1,$] wq[!] [>>] [file]

is similar to write, except that it exits the editor immediately afterwards (if the write is successful).

[1,$] x[it][!] [file]

if you have modified the current file since the last write, performs a write command using the specified range and file name and terminates.

[.,.] y[ank] [buffer] [count]

copies the given line range to the specified buffer (a letter from a through z). If a buffer is not specified, the unnamed buffer is used.

Since the edit command does not destroy buffers, you can use that command in conjunction with put and yank to move text between files.

[.+1]z [type] [count\] [flags]

displays count lines. If no count is specified, Ex uses the current value of the scroll variable. The lines are displayed with the given line located according to the type. If type is a plus sign (+), the editor displays the given line and a screenful after that. If type is a period (.), the editor displays a screenful with the given line in the middle. If type is a minus sign (-), the editor displays a screenful with the given line at the end. If type is a caret (^), the editor displays the screenful before that and if type is an equals sign (=), the current line is centered on the screen with a line of hyphens displayed immediately before and after it. The current line indicator points to the last line displayed.

[.,.] <[<...] [count] [flags]

shifts the line range by the value of the shiftwidth variable. If there are multiple left angle brackets (<), each one causes another shift. The current line indicator points to the last line of the range. If a count is specified, that many lines are shifted.

[.,.] >[>...] [count] [flags]

shifts the line range right by the value of the shiftwidth variable. If there are multiple right angle brackets (>), each one causes another shift. The current line indicator points to the last line of the range. If a count is specified, that many lines are shifted.

[range] ! command

submits command to be run by the command interpreter named by the shell variable. If a range is given, the command is invoked with the contents of that line range as input. The output from the command then replaces that line range. Thus

1,$!sort

sorts the entire contents of the file.

Substitutions are made in command before it is run. Any occurrences of an exclamation mark (!) are replaced by the previous command line, while occurrences of percentage (%) and hash mark (#) characters are replaced with the path names of the current and alternate files, respectively. If any such substitutions actually take place, the new command line is displayed before it is run. (See read and write under Ex Commands for more information the current and alternate files.)

If the file has been modified and the variable autowrite is on, the file is written before calling the command. If autowrite is off, a warning message is given.

[$] =

displays the given line number. The default line number is the last line of the file. The current line indicator is not changed.

" a line of text

This is a comment.

[.,.] & [options] [count] [flags]

Repeats the last substitute command. If any options, count, or flags are specified, they replace the corresponding items in the previous substitute command.

[.,.] ~ [options] [count] [flags]

repeats the last substitute command; however, the regular expression that is used is the last regular expression; that is, if there has been a search, the search's regular expression is used. The simple substitute with no arguments, or the & command, uses the regular expression from the previous substitute. substitute with an empty regular expression uses the last regular expression, like ~. If any options, count, or flags are specified, they replace the corresponding items in the previous substitute command.

@ buffer

executes each line in buffer as an Ex command. If you do not specify buffer or you specify a buffer named @, the last buffer executed is used.

CTRL-D

displays the number of lines of text given by the scroll variable. The current line indicator points to the last line displayed.

Special Characters in Ex Commands

When an Ex command contains the percentage character (%), the character is replaced by the name of the current file. For example, if you are about to try out a macro and you are worried that the macro may damage the file, you could say

!cp % /tmp

to copy the current file to a safe holding place. As another example, a macro could use the percentage character (%) to refer to the current file.

When an Ex command contains the hash mark (#), the character is replaced by the name of the alternate file. The name of the alternate file may be set with the read command as described previously. Thus a command like

e #

tells Ex to edit the alternate file. Using an alternate file can be particularly convenient when you have two files that you want to edit simultaneously. The command just given lets you flip back and forth between the two files.

Software Configuration Management Integration

MKS vi supports a variety of Software Configuration Management (SCM) applications such as RCS, CVS, MKS Source Integrity and Source Integrity Enterprise, Microsoft SourceSafe, and Rational ClearCase. With the commands listed in this section, you can perform various SCM operations such as checking in and out files, directly from within vi.

The SCM environment variable specifies which SCM application to use. Currently, it can have one of the following values:

CC         Rational ClearCase
CVS        CVS (Concurrent Versions System)
RCS        RCS (Revision Control System)
SIE        Source Integrity Enterprise
SIS        Source Integrity Standard
SS         Microsoft SourceSafe

If no value is set for SCM, RCS is assumed.

Note:: Different SCM applications use different terminology. The vi SCM command names and the terminology used in this reference page have been chosen to be reflect common concepts while avoiding confusion in cases where different application use the same word for different concepts. For example, MKS Source Integrity Enterprise calls a collection of related files a project, while Rational ClearCase calls that same concept a VOB and uses the term "project" for a different concept. As a result, the vi SCM commands and this reference page use "repository" to refer to such a collection.

The option variable SCMscript identifies the file that defines how to translate vi SCM commands into the actual commands issued to the SCM application. Initially, SCMscript is set to the value of the SCMSCRIPT environment variable, if set. When SCMSCRIPT is not set, SCMscript defaults to $ROOTDIR/etc/vi.scm.

The vi SCM commands are similar to Ex commands in format, but, unlike Ex commands, SCM commands may take options. While the individual command descriptions show precisely which options are available for which command the following list describes all the options used by these commands:

-c changeid: specifies the change package number. Not all SCM applications support change packages.
-d"Description": specifies an annotation to be associated with the new revision created when a file is checked in.
-i issue: specifies the issue number. Not all SCM applications support issues.
-l: locks the file after the SCM operation is performed.
-r rev: specifies the revision number of the file.

Here is the list of SCM-related commands available in vi:

ad[d][!] [-l] [-c changeid] [-i issue]

adds the current file to the SCM repository. When ! is not specified, the file is only added if it has been saved. When ! is specified, the file is added whether or not it has been saved. In this case, the file is added with the contents as of the last save.

an[notations] [file]

displays the annotations association with previous check in and add operations for the current file. If file is specified, the annotations for that file are displayed instead.

checkin[!] [-r rev/g] [-c changeid] [-i issue] [-d"Description"]

cki[!] [-r rev/g] [-c changeid] [-i issue] [-d"Description"]

checks in the current file. When ! is not specified, the file is only checked in if it has been saved. When ! is specified, the file is checked in whether or not it has been saved. In this case, the file is checked in with the contents as of the last save. With most SCM applications, the file must be locked or checked out before it can be checked in; otherwise, this operation fails.

Note:: When using RCS as your SCM application, the TZ environment variable must be set properly for the checkin command to work.

checkout[!] [-l] [-r rev/g] [-c changeid] [-i issue] [file]

cko[!] [-l] [-r rev/g] [-c changeid] [-i issue] [file]

checks out the current file. If file is specified, that file is checked out instead. file is required when no file is currently being edited.

When ! is not specified, the file is only checked out if the current file has changed neither in the editor nor on the disk. When ! is specified, the file is checked in whether or not it has been saved.

di[ff][!] [-r#] [file]

displays the differences between the current revision and the specified revision (or the default revision if none is specified). When ! is not specified, this operation is only performed on the current file if it has been saved. When ! is specified, this operation is performed on the current file whether or not it has been saved. In this case, the operation is performed with the current file's contents as of the last save.

When file is specified, the differences displayed for revisions of that file instead of the current file.

gu[i]

launches the GUI (graphical user interface) version of the SCM application if one is available.

hi[story] [file]

displays the history of the current file. When file is specified, the history of that file is displayed instead. The revision IDs displayed in the history may be used with the -r# option for appropriate vi SCM commands.

lo[ck][!] [-r#] [-c changeid] [-i issue]

locks the current file. When ! is specified, it locks, if possible, a branch revision if the file is already locked. When ! is not specified, the file is only locked if it is not already locked.

showc[hangeids]

displays available change IDs if the SCM application supports change packages. These IDs may be used with the -c changeid option for appropriate vi SCM commands.

showi[ssues]

displays available issues if the SCM application supports issues.

showr[epository]

displays files in the current SCM repository.

unl[ock][!] [-r#]

unlocks the current file if it is currently locked. When ! is not specified, the file is only unlocked if you hold the lock. When ! is specified, the file is unlocked if either you hold the lock or you have permission to break the holder's lock. Attempting to unlock a file that is already unlocked displays a message to that effect, but nothing else happens.

wa[dd][!] [-l] [-c changeid] [-i issue]

performs an Ex write command to save the current file and then adds it to the SCM repository as per the SCM add command. When ! is specified, a write! command followed by an add! command is performed.

wc[ki][!] [-r rev/g] [-c changeid] [-i issue] [-d"Description"]

performs an Ex write command to save the file and then checks it in as per the SCM checkin (or cki) command. When ! is specified, a write! command followed by an cki! command is performed.

wd[iff][!] [-r rev]

performs an Ex write command to save the file and then displays differences as per the SCM diff command. When ! is specified, a write! command followed by an diff! command is performed.

Set Option Variables

Option variables are set with the set command. For example,

set autowrite

sets the autowrite option. Options are turned off by putting no in front of the name in the set command, as in

set noautowrite

In the descriptions that follow, the abbreviation (if any) of each option variable is shown on the line below the full name.

Note:: There are some non-standard options specific to the PC which are separately documented in vipc.

attrib

See vipc.

autoindent

ai

When autoindent is on and you are entering text, the indentation of the current line is used for the new line. In Vi mode, you can change this default indentation by using the control keys CTRL-D (to shift left) and CTRL-T (to shift right). In Ex mode, a tab or spaces may be typed at the start of a line to increase the indent, or a CTRL-D may be typed at the start of the line to remove a level. ^ CTRL-D temporarily removes the indent for the current line. 0 CTRL-D places the current line at a zero indent level, and the next line has this indent level as well.

The size of indent levels is defined by the variable shiftwidth. Based on this value and the value of tabstop, the editor generates the number of tabs and spaces needed to produce the required indent level.

The default is noautoindent.

autoprint

ap

When this option is set in Ex mode, the current line is displayed after the following commands: copy, delete, join, move, put, substitute, undo, &, ~, <, and >. Automatic displaying of lines does not take place inside global commands.

The default is autoprint.

autowrite

aw

When this option is on, the current file is automatically written out if it has been changed since it was last written and you have run any of the following commands: next, rewind, tag, CTRL-^ (Vi), and CTRL-] (Vi). Using an exclamation mark (!) with any of these commands stops the automatic write.

The default is noautowrite.

beautify

bf

When this option is on, the editor discards all non-printing characters from text read in from files.

The default is nobeautify.

cdpath

Used by cd to find relative path names when changing directory. You must delimit entries with a semi-colon (;). If the current directory is to be included in the search, it must be indicated by a dot (.). cdpath defaults to the contents of the CDPATH environment variable if it exists, or to dot (.) if it does not.

clipboardbuffer

clip

Specifies a named buffer that corresponds to the Windows clipboard.

colorcomment

ccomm

Specifies the color to be used when highlighting members of the comment highlight group. Acceptable values are black, gray, white, red, aqua, blue, green, purple, yellow, brwhite, ltred, ltgreen, ltaqua, ltblue, ltpurple, and ltyellow. All values are case insensitive.

See the vi file format reference page for more information on highlight groups.

The default is colorcomment="green".

colorconditional

ccond

Is similar to colorcomment but specifies the color to be used when highlighting members of the conditional highlight group.

The default is colorconditional="aqua".

colorconstant

cconst

Is similar to colorcomment but specifies the color to be used when highlighting members of the constant highlight group.

The default is colorconditional="purple".

colordatatype

cdata

Is similar to colorcomment but specifies the color to be used when highlighting members of the datatype highlight group.

The default is colordatatype="ltblue".

colorexpression

cexpr

Is similar to colorcomment but specifies the color to be used when highlighting members of the expression highlight group.

The default is colorexpression="white".

colorfunction

cfunc

Is similar to colorcomment but specifies the color to be used when highlighting members of the function highlight group.

The default is colorfunction="gray".

colorkeyword

ckey

Is similar to colorcomment but specifies the color to be used when highlighting members of the keyword highlight group.

The default is colorkeyword="ltblue".

coloroperator

coper

Is similar to colorcomment but specifies the color to be used when highlighting members of the operator highlight group.

The default is coloroperator="yellow".

colorpreprocessor

cpreproc

Is similar to colorcomment but specifies the color to be used when highlighting members of the preprocessor highlight group.

The default is colorpreprocessor="red".

colorstructure

cstruct

Is similar to colorcomment but specifies the color to be used when highlighting members of the

ex, vi, view display-oriented interactive text editor	Command

ex, vi, view display-oriented interactive text editor

Command

ex, vi, view
display-oriented interactive text editor