A Practical Guide to UNIX for Mac OS X Users

Tutorial: Creating and Editing a File with vim

This section explains how to start vim, enter text, move the cursor, correct text, save the file to the disk, and exit from vim. The tutorial discusses two of the modes of operation of vim and explains how to switch from one mode to the other.

vimtutor

In addition to working with this tutorial, you may want to try vim's tutor, named vimtutor: Give its name as a command to run it.

Specifying a terminal

Because vim takes advantage of features that are specific to various kinds of terminals, you must tell it what type of terminal or terminal emulator you are using. On many systems, and usually when you work on a terminal emulator such as Terminal, your terminal type is set automatically. If you need to specify your terminal type, refer to "Specifying a Terminal" on page 913.

Tip: The vi command runs vim

On some systems the command vi runs a minimal build of vim that is compact and faster to load than vim but includes fewer features. See "The compatible Parameter" on page 153 for information on running vim in vi compatible mode.

Starting vim

Start vim with the following command line to create and edit a file named practice:

$ vim practice

When you press RETURN, the command line disappears, and the screen looks similar to the one shown in Figure 6-1.

The tildes (~) at the left of the screen indicate that the file is empty. They disappear as you add lines of text to the file. If your screen looks like a distorted version of the one shown, your terminal type is probably not set correctly.

If you start vim with a terminal type that is not in the terminfo database, vim displays an error message and the terminal type defaults to ansi, which works on many terminals. In the following example, the user mistyped vt100 and set the terminal type to vg100:

Terminal entry not found in terminfo 'vg100' not known. Available builtin terminals are: builtin_ansi builtin_xterm builtin_iris-ansi builtin_dumb defaulting to 'ansi'

If you want to reset the terminal type, press ESCAPE and then give the following command to exit from vim and get the shell prompt back:

:q!

When you enter the colon (:), vim moves the cursor to the bottom line of the screen. The characters q! tell vim to quit without saving your work. (You will not ordinarily exit from vim this way because you typically want to save your work.) You must press RETURN after you give this command. Once you get the shell prompt back, refer to "Specifying a Terminal" on page 913, and then start vim again.

If you start it without a filename, vim assumes that you are a novice and tells you how to get started (Figure 6-2).

The practice file is new so it does not contain any text. The vim editor displays a message similar to the one shown in Figure 6-1 on the status (bottom) line of the terminal to show that you are creating and editing a new file. When you edit an existing file, vim displays the first few lines of the file and gives status information about the file on the status line.

Command and Input Modes

Two of vim's modes of operation are Command mode (also called Normal mode) and Input mode (Figure 6-3). While vim is in Command mode, you can give vim commands. For example, you can delete text or exit from vim. You can also command vim to enter Input mode. In Input mode, vim accepts anything you enter as text and displays it on the screen. Press ESCAPE to return vim to Command mode.

By default the vim editor keeps you informed about which mode it is in. You will see - - INSERT - - at the lower-left corner of the screen while vim is in Insert mode.

The following command causes vim to display line numbers next to the text you are editing:

:set number RETURN

Last Line mode

The colon (:) in the preceding command puts vim into another mode, Last Line mode. While in this mode, vim keeps the cursor on the bottom line of the screen. When you finish entering the command by pressing RETURN, vim restores the cursor to its place in the text. Give the command :set nonumber RETURN to turn off line numbers.

vim is case sensitive

When you give vim a command, remember that the editor is case sensitive. Thus vim editor interprets the same letter as two different commands, depending on whether you enter an uppercase or lowercase character. Beware of the CAPS LOCK (SHIFTLOCK) key. If you set this key to enter uppercase text while you are in Input mode and then exit to Command mode, vim interprets your commands as uppercase letters. It can be confusing when this happens because vim does not appear to be executing the commands you are entering.

Entering Text

Input mode (i/a)

When you start vim, you must put it in Input mode before you can enter text. To put vim in Input mode, press the i key (insert before the cursor) or the a key (append after the cursor).

If you are not sure whether vim is currently in Input mode, press the ESCAPE key; vim returns to Command mode if it was in Input mode or beeps, flashes, or does nothing if it is already in Command mode. You can put vim back in Input mode by pressing the i or a key again.

While vim is in Input mode, you can enter text by typing on the keyboard. If the text does not appear on the screen as you type, you are not in Input mode.

To continue with this tutorial, enter the sample paragraph shown in Figure 6-4, pressing the RETURN key to end each line. If you do not press RETURN before the cursor reaches the right side of the screen or window, vim will wrap the text so that it appears to start a new line. Physical lines will not correspond to programmatic (logical) lines in this situation, and editing will be more difficult.

While you are using vim, you can always correct any typing mistakes you make. If you notice a mistake on the line you are entering, you can correct it before you continue (page 151). You can correct other mistakes later. When you finish entering the paragraph, press ESCAPE to return vim to Command mode.

Getting Help

To get help while you are using vim, give the command :help [feature] followed by RETURN (you must be in Command mode when you give this command). The colon puts the cursor on the last line of the screen. If you type :help, vim displays an introduction to vim Help (Figure 6-5). Each dark band near the bottom of the screen names the file that is displayed above it. (Each area of the screen that displays a file, such as the two areas shown in Figure 6-5, is a vim "window.") The help.txt file occupies most of the screen (the upper window) in Figure 6-5. The file that is being edited (practice) occupies a few lines in the lower portion of the screen (the lower window).

Read through the introduction to Help by scrolling the text as you read. Pressing j or the DOWN ARROW key moves the cursor down one line at a time; pressing CONTROL-D or CONTROL-U scrolls the cursor down or up half a window at a time. Give the command :q! to close the Help window.

You can get help with the insert commands by giving the command :help insert while vim is in Command mode (Figure 6-6).

Correcting Text as You Insert It

The keys that back up and correct a shell command line serve the same functions when vim is in Input mode. These keys include the erase, line kill, and word kill keys (usually CONTROL-H, CONTROL-U, and CONTROL-W, respectively). Although vim may not remove deleted text from the screen as you back up over it, the editor does remove it when you type over it or press RETURN.

Moving the Cursor

You need to be able to move the cursor on the screen so that you can delete, insert, and correct text. While vim is in Command mode, you can use the RETURN key, the SPACE bar, and the ARROW keys to move the cursor. If you prefer to keep your hand closer to the center of the keyboard, if your terminal does not have ARROW keys, or if the emulator you are using does not support them, you can use the h, j, k, and l (lowercase "l") keys to move the cursor left, down, up, and right, respectively.

Deleting Text

Delete character (x) Delete word (dw) Delete line (dd)

You can delete a single character by moving the cursor until it is over the character you want to delete and then giving the command x. You can delete a word by positioning the cursor on the first letter of the word and then giving the command dw (Delete word). You can delete a line of text by moving the cursor until it is anywhere on the line and then giving the command dd.

Undoing Mistakes

Undo (u)

If you delete a character, line, or word by mistake or give any command you want to undo, give the command u (Undo) immediately after the command you want to undo. The vim editor will restore the text to the way it was before you gave the last command. If you give the u command again, vim will undo the command you gave before the one it just undid. You can use this technique to back up over many of your actions. With the compatible parameter (page 153) set, vim can undo only the most recent change.

Redo (:redo)

If you undo a command you did not mean to undo, give a Redo command: CONTROL-R or :redo (followed by a RETURN). The vim editor will redo the undone command. As with the Undo command, you can give the Redo command many times in a row.

Entering Additional Text

Insert (i) Append (a)

When you want to insert new text within existing text, move the cursor so it is on the character that follows the new text you plan to enter. Then give the i (Insert) command to put vim in Input mode, enter the new text, and press ESCAPE to return vim to Command mode. Alternatively, you can position the cursor on the character that precedes the new text, and use the a (Append) command.

Open (o and O)

To enter one or more lines, position the cursor on the line above where you want the new text to go. Give the command o (Open). The vim editor opens a blank line, puts the cursor on it, and goes into Input mode. Enter the new text, ending each line with a RETURN. When you are finished entering text, press ESCAPE to return vim to Command mode. The O command works in the same way o works, except that it opens a line above the line the cursor is on.

Correcting Text

To correct text, use dd, dw, or x to remove the incorrect text. Then use i, a, o, or O to insert the correct text.

For example, to change the word pressing to hitting in Figure 6-4 on page 150 you might use the ARROW keys to move the cursor until it is on top of the p in pressing. Then give the command dw to delete the word pressing. Put vim in Input mode by giving an i command, enter the word hitting followed by a SPACE, and press ESCAPE. The word is changed and vim is in Command mode, waiting for another command. A shorthand for the two commands dw followed by the i command is cw (Change word). The command cw puts vim into Input mode.

Tip: Page breaks for the printer

CONTROL-L is a signal to a printer to skip to the top of the next page. You can enter this character anywhere in a document by pressing CONTROL-L while you are in Input mode. If ^L does not appear, press CONTROL-V before CONTROL-L.

Ending the Editing Session

While you are editing, vim keeps the edited text in an area named the Work buffer. When you finish editing, you must write out the contents of the Work buffer to a disk file so that the edited text is saved and available when you next want it.

Make sure that vim is in Command mode, and then use the ZZ command (you must use uppercase Z's) to write your newly entered text to the disk and end the editing session. After you give the ZZ command, vim returns control to the shell. You can exit with :q! if you do not want to save your work. Refer to page 191 for a summary of vim commands.