:h usr_02.txt

usr_02.txt For Vim version 7.4. Last change: 2010 Jul 20LINK

VIM USER MANUAL - by Bram Moolenaar

The first steps in Vim

This chapter provides just enough information to edit a file with Vim. Not

well or fast, but you can edit. Take some time to practice with these

commands, they form the base for what follows.

02.1 Running Vim for the First Time

02.2 Inserting text

02.3 Moving around

02.4 Deleting characters

02.5 Undo and Redo

02.6 Other editing commands

02.7 Getting out

02.8 Finding help

Next chapter: usr_03.txt Moving around

Previous chapter: usr_01.txt About the manuals

Table of contents: usr_toc.txt

==============================================================================

02.1 Running Vim for the First TimeLINK

To start Vim, enter this command:

gvim file.txt

In UNIX you can type this at any command prompt. If you are running Microsoft

Windows, open an MS-DOS prompt window and enter the command.

In either case, Vim starts editing a file called file.txt. Because this

is a new file, you get a blank window. This is what your screen will look

like:

+---------------------------------------+

|# |

|~ |

|"file.txt" [New file] |

+---------------------------------------+

('#" is the cursor position.)

The tilde (~) lines indicate lines not in the file. In other words, when Vim

runs out of file to display, it displays tilde lines. At the bottom of the

screen, a message line indicates the file is named file.txt and shows that you

are creating a new file. The message information is temporary and other

information overwrites it.

THE VIM COMMAND

The gvim command causes the editor to create a new window for editing. If you

use this command:

vim file.txt

the editing occurs inside your command window. In other words, if you are

running inside an xterm, the editor uses your xterm window. If you are using

an MS-DOS command prompt window under Microsoft Windows, the editing occurs

inside this window. The text in the window will look the same for both

versions, but with gvim you have extra features, like a menu bar. More about

that later.

==============================================================================

02.2 Inserting textLINK

The Vim editor is a modal editor. That means that the editor behaves

differently, depending on which mode you are in. The two basic modes are

called Normal mode and Insert mode. In Normal mode the characters you type

are commands. In Insert mode the characters are inserted as text.

Since you have just started Vim it will be in Normal mode. To start Insert

mode you type the "i" command (i for Insert). Then you can enter

the text. It will be inserted into the file. Do not worry if you make

mistakes; you can correct them later. To enter the following programmer's

limerick, this is what you type:

iA very intelligent turtle

Found programming UNIX a hurdle

After typing "turtle" you press the <Enter> key to start a new line. Finally

you press the <Esc> key to stop Insert mode and go back to Normal mode. You

now have two lines of text in your Vim window:

+---------------------------------------+

|A very intelligent turtle |

|Found programming UNIX a hurdle |

|~ |

| |

+---------------------------------------+

WHAT IS THE MODE?

To be able to see what mode you are in, type this command:

:set showmode

You will notice that when typing the colon Vim moves the cursor to the last

line of the window. That's where you type colon commands (commands that start

with a colon). Finish this command by pressing the <Enter> key (all commands

that start with a colon are finished this way).

Now, if you type the "i" command Vim will display --INSERT-- at the bottom

of the window. This indicates you are in Insert mode.

+---------------------------------------+

|A very intelligent turtle |

|Found programming UNIX a hurdle |

|~ |

|-- INSERT -- |

+---------------------------------------+

If you press <Esc> to go back to Normal mode the last line will be made blank.

GETTING OUT OF TROUBLE

One of the problems for Vim novices is mode confusion, which is caused by

forgetting which mode you are in or by accidentally typing a command that

switches modes. To get back to Normal mode, no matter what mode you are in,

press the <Esc> key. Sometimes you have to press it twice. If Vim beeps back

at you, you already are in Normal mode.

==============================================================================

02.3 Moving aroundLINK

After you return to Normal mode, you can move around by using these keys:

h left hjklLINK

j down

k up

l right

At first, it may appear that these commands were chosen at random. After all,

who ever heard of using l for right? But actually, there is a very good

reason for these choices: Moving the cursor is the most common thing you do in

an editor, and these keys are on the home row of your right hand. In other

words, these commands are placed where you can type them the fastest

(especially when you type with ten fingers).

Note:

You can also move the cursor by using the arrow keys. If you do,

however, you greatly slow down your editing because to press the arrow

keys, you must move your hand from the text keys to the arrow keys.

Considering that you might be doing it hundreds of times an hour, this

can take a significant amount of time.

Also, there are keyboards which do not have arrow keys, or which

locate them in unusual places; therefore, knowing the use of the hjkl

keys helps in those situations.

One way to remember these commands is that h is on the left, l is on the

right and j points down. In a picture:

h l

The best way to learn these commands is by using them. Use the "i" command to

insert some more lines of text. Then use the hjkl keys to move around and

insert a word somewhere. Don't forget to press <Esc> to go back to Normal

mode. The vimtutor is also a nice way to learn by doing.

For Japanese users, Hiroshi Iwatani suggested using this:

Komsomolsk

Huan Ho <--- ---> Los Angeles

(Yellow river) |

Java (the island, not the programming language)

==============================================================================

02.4 Deleting charactersLINK

To delete a character, move the cursor over it and type "x". (This is a

throwback to the old days of the typewriter, when you deleted things by typing

xxxx over them.) Move the cursor to the beginning of the first line, for

example, and type xxxxxxx (seven x's) to delete "A very ". The result should

look like this:

+---------------------------------------+

|intelligent turtle |

|Found programming UNIX a hurdle |

|~ |

| |

+---------------------------------------+

Now you can insert new text, for example by typing:

iA young <Esc>

This begins an insert (the i), inserts the words "A young", and then exits

insert mode (the final <Esc>). The result:

+---------------------------------------+

|A young intelligent turtle |

|Found programming UNIX a hurdle |

|~ |

| |

+---------------------------------------+

DELETING A LINE

To delete a whole line use the "dd" command. The following line will

then move up to fill the gap:

+---------------------------------------+

|Found programming UNIX a hurdle |

|~ |

| |

+---------------------------------------+

DELETING A LINE BREAK

In Vim you can join two lines together, which means that the line break

between them is deleted. The "J" command does this.

Take these two lines:

A young intelligent

turtle

Move the cursor to the first line and press "J":

A young intelligent turtle

==============================================================================

02.5 Undo and RedoLINK

Suppose you delete too much. Well, you can type it in again, but an easier

way exists. The "u" command undoes the last edit. Take a look at this in

action: After using "dd" to delete the first line, "u" brings it back.

Another one: Move the cursor to the A in the first line:

A young intelligent turtle

Now type xxxxxxx to delete "A young". The result is as follows:

intelligent turtle

Type "u" to undo the last delete. That delete removed the g, so the undo

restores the character.

g intelligent turtle

The next u command restores the next-to-last character deleted:

ng intelligent turtle

The next u command gives you the u, and so on:

ung intelligent turtle

oung intelligent turtle

young intelligent turtle

A young intelligent turtle

Note:

If you type "u" twice, and the result is that you get the same text

back, you have Vim configured to work Vi compatible. Look here to fix

this: not-compatible.

This text assumes you work "The Vim Way". You might prefer to use

the good old Vi way, but you will have to watch out for small

differences in the text then.

REDO

If you undo too many times, you can press CTRL-R (redo) to reverse the

preceding command. In other words, it undoes the undo. To see this in

action, press CTRL-R twice. The character A and the space after it disappear:

young intelligent turtle

There's a special version of the undo command, the "U" (undo line) command.

The undo line command undoes all the changes made on the last line that was

edited. Typing this command twice cancels the preceding "U".

A very intelligent turtle

xxxx Delete very

A intelligent turtle

xxxxxx Delete turtle

A intelligent

Restore line with "U"

A very intelligent turtle

Undo "U" with "u"

A intelligent

The "U" command is a change by itself, which the "u" command undoes and CTRL-R

redoes. This might be a bit confusing. Don't worry, with "u" and CTRL-R you

can go to any of the situations you had. More about that in section 32.2.

==============================================================================

02.6 Other editing commandsLINK

Vim has a large number of commands to change the text. See Q_in and below.

Here are a few often used ones.

APPENDING

The "i" command inserts a character before the character under the cursor.

That works fine; but what happens if you want to add stuff to the end of the

line? For that you need to insert text after the cursor. This is done with

the "a" (append) command.

For example, to change the line

and that's not saying much for the turtle.

and that's not saying much for the turtle!!!

move the cursor over to the dot at the end of the line. Then type "x" to

delete the period. The cursor is now positioned at the end of the line on the

e in turtle. Now type

a!!!<Esc>

to append three exclamation points after the e in turtle:

and that's not saying much for the turtle!!!

OPENING UP A NEW LINE

The "o" command creates a new, empty line below the cursor and puts Vim in

Insert mode. Then you can type the text for the new line.

Suppose the cursor is somewhere in the first of these two lines:

A very intelligent turtle

Found programming UNIX a hurdle

If you now use the "o" command and type new text:

oThat liked using Vim<Esc>

The result is:

A very intelligent turtle

That liked using Vim

Found programming UNIX a hurdle

The "O" command (uppercase) opens a line above the cursor.

USING A COUNT

Suppose you want to move up nine lines. You can type "kkkkkkkkk" or you can

enter the command "9k". In fact, you can precede many commands with a number.

Earlier in this chapter, for instance, you added three exclamation points to

the end of a line by typing "a!!!<Esc>". Another way to do this is to use the

command "3a!<Esc>". The count of 3 tells the command that follows to triple

its effect. Similarly, to delete three characters, use the command "3x". The

count always comes before the command it applies to.

==============================================================================

02.7 Getting outLINK

To exit, use the "ZZ" command. This command writes the file and exits.

Note:

Unlike many other editors, Vim does not automatically make a backup

file. If you type "ZZ", your changes are committed and there's no

turning back. You can configure the Vim editor to produce backup

files, see 07.4.

DISCARDING CHANGES

Sometimes you will make a sequence of changes and suddenly realize you were

better off before you started. Not to worry; Vim has a

quit-and-throw-things-away command. It is:

:q!

Don't forget to press <Enter> to finish the command.

For those of you interested in the details, the three parts of this command

are the colon (:), which enters Command-line mode; the q command, which tells

the editor to quit; and the override command modifier (!).

The override command modifier is needed because Vim is reluctant to throw

away changes. If you were to just type ":q", Vim would display an error

message and refuse to exit:

E37: No write since last change (use ! to override)

By specifying the override, you are in effect telling Vim, "I know that what

I'm doing looks stupid, but I'm a big boy and really want to do this."

If you want to continue editing with Vim: The ":e!" command reloads the

original version of the file.

==============================================================================

02.8 Finding helpLINK

Everything you always wanted to know can be found in the Vim help files.

Don't be afraid to ask!

To get generic help use this command:

:help

You could also use the first function key <F1>. If your keyboard has a <Help>

key it might work as well.

If you don't supply a subject, ":help" displays the general help window.

The creators of Vim did something very clever (or very lazy) with the help

system: They made the help window a normal editing window. You can use all

the normal Vim commands to move through the help information. Therefore h, j,

k, and l move left, down, up and right.

To get out of the help window, use the same command you use to get out of

the editor: "ZZ". This will only close the help window, not exit Vim.

As you read the help text, you will notice some text enclosed in vertical bars

(for example, help). This indicates a hyperlink. If you position the

cursor anywhere between the bars and press CTRL-] (jump to tag), the help

system takes you to the indicated subject. (For reasons not discussed here,

the Vim terminology for a hyperlink is tag. So CTRL-] jumps to the location

of the tag given by the word under the cursor.)

After a few jumps, you might want to go back. CTRL-T (pop tag) takes you

back to the preceding position. CTRL-O (jump to older position) also works

nicely here.

At the top of the help screen, there is the notation *help.txt*. This name

between "*" characters is used by the help system to define a tag (hyperlink

destination).

See 29.1 for details about using tags.

To get help on a given subject, use the following command:

:help {subject}

To get help on the "x" command, for example, enter the following:

:help x

To find out how to delete text, use this command:

:help deleting

To get a complete index of all Vim commands, use the following command:

:help index

When you need to get help for a control character command (for example,

CTRL-A), you need to spell it with the prefix "CTRL-".

:help CTRL-A

The Vim editor has many different modes. By default, the help system displays

the normal-mode commands. For example, the following command displays help

for the normal-mode CTRL-H command:

:help CTRL-H

To identify other modes, use a mode prefix. If you want the help for the

insert-mode version of a command, use "i_". For CTRL-H this gives you the

following command:

:help i_CTRL-H

When you start the Vim editor, you can use several command-line arguments.

These all begin with a dash (-). To find what the -t argument does, for

example, use the command:

:help -t

The Vim editor has a number of options that enable you to configure and

customize the editor. If you want help for an option, you need to enclose it

in single quotation marks. To find out what the 'number' option does, for

example, use the following command:

:help 'number'

The table with all mode prefixes can be found here: help-context.

Special keys are enclosed in angle brackets. To find help on the up-arrow key

in Insert mode, for instance, use this command:

:help i_<Up>

If you see an error message that you don't understand, for example:

E37: No write since last change (use ! to override)

You can use the error ID at the start to find help about it:

:help E37

Summary: help-summary LINK

:help

Gives you very general help. Scroll down to see a list of all

helpfiles, including those added locally (i.e. not distributed

with Vim).

:help user-toc.txt

Table of contents of the User Manual.

:help :subject

Ex-command "subject", for instance the following:

:help :help

Help on getting help.

:help abc

normal-mode command "abc".

:help CTRL-B

Control key <C-B> in Normal mode.

:help i_abc

:help i_CTRL-B

The same in Insert mode.

:help v_abc

:help v_CTRL-B

The same in Visual mode.

:help c_abc

:help c_CTRL-B

The same in Command-line mode.

:help 'subject'

Option 'subject'.

:help subject()

Function "subject".

:help -subject

Command-line option "-subject".

:help +subject

Compile-time feature "+subject".

:help EventName

Autocommand event "EventName".

:help digraphs.txt

The top of the helpfile "digraph.txt".

Similarly for any other helpfile.

:help pattern<Tab>

Find a help tag starting with "pattern". Repeat <Tab> for

others.

:help pattern<Ctrl-D>

See all possible help tag matches "pattern" at once.

:helpgrep pattern

Search the whole text of all help files for pattern "pattern".

Jumps to the first match. Jump to other matches with:

:cn

next match

:cprev

:cN

previous match

:cfirst

:clast

first or last match

:copen

:cclose

open/close the quickfix window; press <Enter> to jump

to the item under the cursor

==============================================================================

Next chapter: usr_03.txt Moving around