doc/en/vi-guide.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/vi-guide.xml,v 1.17 2011/08/15 20:37:55 swift Exp $ -->
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">

<guide>
<title>Learning vi -- the "cheatsheet" technique</title>
<author title="Author">
  <mail link="drobbins@gentoo.org">Daniel Robbins</mail>
</author>
<author title="Author">
  <mail link="stocke2@gentoo.org">Eric Stockbridge</mail>
</author>
<author title="Editor">
  <mail link="bennyc@gentoo.org">Benny Chuang</mail>
</author>

<abstract>
This guide will teach you how to use vi, using a cheat sheet method to
accelerate the learning process. This will be the first guide for vi,
catering to beginners.
</abstract>

<version>2</version>
<date>2011-08-15</date>

<chapter>
<title>Getting Started</title>
<section>
<title>Introduction</title>
<body>

<p>
This tutorial will show you how to use vi, a powerful visual editor.
Using a special accelerated <e>cheat sheet</e> method, this tutorial is
designed to make you a proficient vi user without requiring a huge
time commitment. In this vi tutorial, you'll learn how to move
around, edit text, use insert mode, copy and paste text, and use
important vim extensions like visual mode and multi-window editing.
</p>

<p>
If you either don't know or aren't comfortable using vi, then you owe
it to yourself to take this tutorial and get up to speed with one of
the most popular and powerful Linux/UNIX visual editing programs.
</p>

</body>
</section>
<section>
<title>About the guide</title>
<body>

<p>
There's one thing in particular that makes it difficult to learn vi --
vi has lots of commands. In order to use vi effectively, you need to
memorize quite a few. This can take a long time, and one of the goals
of this tutorial is not to take up a lot of your time. So, initially,
we have a challenge -- how exactly do I help you to memorize lots of
commands in a short period of time?
</p>

<p>
To tackle this challenge, as we proceed through this tutorial, we're
going to gradually put together a vi cheat sheet. This sheet will
contain all the important vi commands. After you've completed this
tutorial, you'll be able to refer to this cheat sheet if you forget a
particular command. Over time, as you memorize commands, you'll
gradually become less and less dependent on the cheat sheet. By using
the cheat-sheet technique, you'll be able to learn how to use vi
faster than ever possible before!
</p>

</body>
</section>
<section>
<title>The learning process</title>
<body>

<p>
In this guide, I'm going to use several techniques to help you
learn. First, I'm going to describe how a particular command works,
as you'd expect. Then, I'm going to ask you to try to use the command
in vi (for practice), and then I'm going to ask you to transcribe the
command to the cheat sheet (for later reference.) If you want to
learn vi quickly, it's important that you perform all these steps.
Trying out a command in vi and transcribing the command onto your
cheat sheet will help you to memorize the command.
</p>

</body>
</section>
<section>
<title>Introducing vim</title>
<body>

<p>
There are many versions of vi, and I'm going to be showing you how to
use a version of vi called <c>vim</c>. vim is very popular and has a
number of extensions that make vi a lot nicer (whenever I demonstrate
a vim-specific command, I'll make a note of it.) If you need to
install vim, you can get it from <uri
link="http://www.vim.org/">www.vim.org</uri>. In addition to an
enhanced command-line vi, vim also comes with <c>gvim</c>, a nice graphical
editor which can be configured to use the excellent GTK+ gui library.
Here's a gvim screenshot from my system:
</p>

<figure link="/images/vishot.png" short="screenshot" caption="VIM screenshot"/>

<p>
If you're a vi newbie, try to get gvim running on your system. Using
vi from a gui can make things a bit easier for beginners.
</p>

</body>
</section>
</chapter>

<chapter>
<title>First Steps</title>
<section>
<title>Pick a file</title>
<body>

<p>
Before using vi to edit files, you need to know how to use vi to move
around in a file. vi has a lot of movement commands, and we're going
to take a look at many of them. For this part of the tutorial, find
an unimportant text file and load it into vi by typing:
</p>

<pre caption="Loading a file into vi">
$ <i>vi myfile.txt</i>
</pre>

<p>
If you have vim installed, type <c>vim myfile.txt</c>. If you'd prefer to
use gvim, type <c>gvim myfile.txt</c>. <path>myfile.txt</path> should be the
name of a text file on your system.
</p>

</body>
</section>
<section>
<title>Inside vi</title>
<body>

<p>
After vi loads, you should see a part of the text file you loaded
on your screen. Congratulations -- you're in vi! Unlike many
editors, when vi starts up, it is in a special mode called <e>command
mode</e>. This means that if you press <c>l</c>on the keyboard, instead of
inserting an <c>l</c> into the file at the current cursor position, the
cursor will move one character to the right instead. In command mode,
the characters on your keyboard are used to send commands to vi rather
than insert literal characters into the text. One of the most
essential types of commands are movement commands; let's take a look
at some.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Moving around</title>
<section>
<title>Moving in vi, part 1</title>
<body>

<p>
When in command mode, you can use the <c>h</c>,<c>j</c>,<c>k</c> and
<c>l</c> keys to move the cursor left, down, up and right
respectively. If you're using a modern version of vi, you can also
use the arrow keys for this purpose. The <c>h</c>,<c>j</c>,<c>k</c>
and <c>l</c> keys are handy because once you're comfortable with them,
you'll be able to move around in the file without moving your fingers
from the home keyboard row. Try using <c>h</c>,<c>j</c>,<c>k</c> and
<c>l</c> (and the arrow keys) to move around in the text file. Try
using <c>h</c> until you get to the beginning of a line. Notice that
vi doesn't allow you to "wrap around" to the previous line by hitting
<c>h</c> while you're on the first character. Likewise, you can't
"wrap around" to the next line by hitting <c>l</c> at the end of a
line.
</p>

</body>
</section>
<section>
<title>Moving in vi, part 2</title>
<body>

<p>
vi offers special shortcuts for jumping to the beginning or end of the
current line. You can press <c>0</c> (zero) to jump to the first
character of a line, and <c>$</c> to jump to the last character of the
line. Try 'em and see. Since vi has so many handy movement commands,
it makes a great "pager" (like the more or less commands.) Using vi
as a pager will also help you to learn all the movement commands very
quickly.
</p>

<p>
You can also use <c>&lt;CTR&gt;F</c> and <c>&lt;CTR&gt;B</c> to move
forwards and backwards a page at a time. Modern versions of vi (like
vim) will also allow you to use the <c>PGUP</c> and <c>PGDOWN</c> keys for this
purpose.
</p>

</body>
</section>
<section>
<title>Word moves, part 1</title>
<body>

<p>
vi also allows you to move to the left or right by word increments.
To move to the <e>first</e> character of the next word, press
<c>w</c>. To move to the <e>last</e> character of the next word,
press <c>e</c>. To move to the first character of the <e>previous</e>
word, press <c>b</c>. Test 'em out.
</p>

</body>
</section>
<section>
<title>Word moves, part 2</title>
<body>

<p>
After playing around with the word movement commands, you may have
noticed that vi considers words like <c>foo-bar-oni</c> as five separate
words! This is because by default, vi delimits words by spaces
<e>or</e> punctuation. <c>foo-bar-oni</c> is therefore considered five
words: <c>foo</c>, <c>-</c>, <c>bar</c>, <c>-</c> and <c>oni</c>.
</p>

<p>
Sometimes, this is what you want, and sometimes it isn't.
Fortunately, vi also understands the concept of a "bigword". vi
delimits bigwords by <e>spaces or newlines only</e>. This means that
while <c>foo-bar-oni</c> is considered five vi words, it's considered only
one vi bigword.
</p>

</body>
</section>
<section>
<title>Word moves, part 3</title>
<body>

<p>
To jump around to the next and previous bigword, you can use a
<e>capitalized</e> word move command. Use <c>W</c> to jump to the
first character of the next bigword, <c>E</c> to jump to the last
character of the next bigword, and <c>B</c> to jump to the first
character of the previous bigword. Test 'em out, and compare the
matching word and bigword movement commands until you understand their
differences.
</p>

</body>
</section>
<section>
<title>Bigger moves</title>
<body>

<p>
We just have a few more commands to cover before it's time to start
puting together our cheat sheet. You can use the <c>(</c> and
<c>)</c> characters to move to the beginning of the previous and next
sentence. In addition, you can hit <c>{</c> or <c>}</c> to jump to
the beginning of the current paragraph, and the beginning of the next.
Test 'em out.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Quitting</title>
<section>
<body>

<p>
We've covered the basic movement commands, but there are another
couple of commands that you need to know. Typing <c>:q</c> will quit
vi. If this doesn't work, then you probably accidentally modified the
file in some way. To tell vi to quit, throwing away any changes, type
<c>:q!</c>. You should now be at the command prompt.
</p>

<p>
In vi, any command that begins with a <c>:</c> is said to be an
<e>ex-mode</e> command. This is because vi has a built-in non-visual
editor called <e>ex</e>. It can be used similarly to sed to perform
line-based editing operations. In addition, it can also be used to
quit, as we've just seen. If you ever hit the <c>Q</c> key while in
command mode, you'll be transported to ex mode. If this ever happens
to you, you'll be confronted with a : prompt, and hitting enter will
scroll the entire screen upwards. To get back to good 'ol vi mode,
simply type vi and hit enter.
</p>

</body>
</section>
</chapter>

<chapter>
<title>The Cheat Sheet</title>
<section>
<title>The beginnings of the cheat sheet</title>
<body>

<p>
We've covered a lot of commands, and it's time to transcribe them to
our cheat sheet. For the cheat sheet, you'll need a US letter or A4
sized piece of paper (we're going to pack a lot of info onto this
sheet!) Here's a picture of my cheat sheet after I've transcribed all
the commands that we've covered so far. Try to follow my layout if
possible so that we can fit everything on one sheet.
</p>

<figure link="/images/vicheat-first.png" short="First part of the cheat sheet"
caption="Cheat Sheet"/>

</body>
</section>
<section>
<title>Miscellaneous vi</title>
<body>

<p>
Let's continue our rapid command-covering pace. In command-mode, you
can jump to a particularline by typing <c>G</c>. To jump to the first
line of a file, type <c>1G</c>. Note that <c>G</c> is capitalized.
</p>

<p>
If you want to jump to the next occurence of a particular text
pattern, type <c>/&lt;regexp&gt;</c> and hit <c>enter</c>. Replace
&lt;regexp&gt; with the regular expression you're looking for. If you
don't know how to use regular expressions, don't fret -- typing
<c>/foo</c> will move to the next occurence of <e>foo</e>. The only
thing you'll need to watch out for is when you want to refer to the
literal <c>^</c>, <c>.</c>, <c>$</c> or <c>\</c> characters. Prefix
these characters with a backslash (<c>\</c>), and you'll be set. For
example, <c>/foo\.gif</c> will search for the next occurence of
"foo.gif".
</p>

<p>
To repeat the search forwards, hit <c>n</c>. To repeat the search
backwards, type <c>N</c>. As always, test these commands out in your
very own vi editor. You can also type <c>//</c> to repeat the last
search.
</p>

</body>
</section>
</chapter>

<chapter>
<title>Saving and Editing</title>
<section>
<title>Save and save as...</title>
<body>

<p>
We've covered how you can use the <e>ex</e> command <c>:q</c> to quit
from vi. If you want to save your changes, type <c>:w</c>. If you
want to save your changes to another file, type <c>:w filename.txt</c>
to save as <e>filename.txt</e>. If you want to save and quit, type
<c>:x</c> or <c>:wq</c>.
</p>

<p>
In vim (and other advanced vi editors, like elvis)<c>:w</c>, you can
have multiple buffers open at once. To open a file into a new window,
type <c>:sp filename.txt</c>. <path>filename.txt</path> will appear open
for editing in a new split window. To switch between windows, type
<c>&lt;CTR&gt;w&lt;CTR&gt;w</c> (control-w twice). Any <c>:q</c>,
<c>:q!</c>, <c>:w</c> and <c>:x</c> commands that you enter will only
be applied to the currently-active window.
</p>

</body>
</section>
<section>
<title>Simple edits</title>
<body>

<p>
Now, it's time to start learning some of the simple editing commands.
The commands that we'll cover here are considered <e>simple</e> because the
commands keep you in command mode. The more complex editing commands
automatically put you into insert mode -- a mode that allows you to
enter literal data from the keyboard. We'll cover those in a bit.
</p>

<p>
For now, try moving over some characters and hitting <c>x</c>
repeatedly. You'll see that <c>x</c> will delete the current
character under the cursor. Now, move to the middle of the paragraph
somewhere in your text file, and hit <c>J</c> (capitalized). You'll
see that the <c>J</c> command tells vi to join the next line to the
end of the current line. Now, move over a character and hit
<c>r</c>, and then type in a new character; you'll see that the
original character has been replaced. Finally, move to any line in
the file and type <c>dd</c>. You'll see that <c>dd</c> deletes the
current line of text.
</p>

</body>
</section>
<section>
<title>Repeating and deleting</title>
<body>

<p>
You can repeat any editing command by hitting the <c>.</c> key. If
you experiment, you'll see that typing <c>dd...</c> will delete 4
lines, and <c>J......</c> will join four lines. As usual, vi provides
with another handy shortcut.
</p>

<p>
To delete text, you can also use the <c>d</c> command combined with
any movement command. For example, <c>dw</c> will delete from the
current position to the beginning of the next word; <c>d)</c> will
delete up until the end of the next sentence, and <c>d}</c> will
delete the remainder of the paragraph. Experiment with the
<c>d</c> command and the other editing commands until you're
comfortable with them.
</p>

</body>
</section>
<section>
<title>Undo!</title>
<body>

<p>
Now that we're experimenting with deletion, it would be a good time to
learn how to undo any changes. By pressing <c>u</c>, the original
version of vi allowed you to undo the last edit only. However, modern
versions of vi like vim will allow you to repeatedly press <c>u</c> to
continue to undo changes to your file. Try combining some <c>d</c>
and <c>u</c> commands together.
</p>

</body>
</section>
<section>
<title>Updating the cheat sheet</title>
<body>

<p>
Time to update the cheat sheet! After adding all the commands we've
covered so far, your cheat sheet should look like this:
</p>

<figure link="/images/vicheat-edit.png" short="Cheat sheet" caption="Cheat
sheet with editing commands"/>

</body>
</section>
</chapter>

<chapter>
<title>Insert mode</title>
<section>
<body>

<p>
So far, we've covered how to move around in vi, perform file i/o, and
perform basic editing operations. However, I still haven't shown you
how to actually type in free-form text! This was intentional, because
vi's insert mode is a bit complicated at first. However, after you
become comfortable with insert mode, its complexity (and flexibility)
will become an asset.
</p>

<p>
In vi <e>insert mode</e>, you'll be able to enter text directly to the screen
just like you can in many other visual editors. Once you've entered
your modifications, you can hit escape to return to <e>command mode</e>. You
can enter insert mode by pressing <c>i</c> or <c>a</c>. If you press
<c>i</c>, your text will be <e>inserted</e> before the current
character, and if you hit <c>a</c>, your text will be <e>appended</e>
after the current character. Remember, after you enter your text, hit
<c>&lt;ESC&gt;</c> to return to command mode.
</p>

</body>
</section>
<section>
<title>Benefits of insert mode</title>
<body>

<p>
Go ahead and try using the <c>a</c> and <c>i</c> commands. Hit either
<c>a</c> or <c>i</c>, type some text, and then hit escape to get back
to command mode. After hitting <c>a</c> or <c>i</c>, try hitting
<c>&lt;ENTER&gt;</c>, and see what happens. Try using the arrow keys
and the <c>&lt;DEL&gt;</c> key to get a feel for how insert mode
works. By using the arrow keys and <c>&lt;DEL&gt;</c> key, you can
perform significant editing steps without repeatedly entering and
leaving insert mode.
</p>

</body>
</section>
<section>
<title>Insert options</title>
<body>

<p>
Here are some other handy ways to enter insert mode. Press <c>A</c>
(captial) to begin appending to the <e>end</e> of the current line,
regardless of your current position on the line. Likewise, press
<c>I</c> (capital) to begin inserting text at the <e>beginning</e> of
the current line. Press <c>o</c> to create a new blank line below the
current line into which you can insert text, and press <c>O</c>
(capital) to create a new line above the current line. To replace the
entire current line with a new line, press <c>cc</c>. To replace
everything from the current position to the end of the line, type
<c>c$</c>. To replace everything from the current position to the
beginning of the line, type <c>c0</c>.
</p>

<p>
In addition to performing a special operation, every one of these
commands will put you into insert mode. After typing in your text,
hit <c>&lt;ESC&gt;</c> to return to command mode.
</p>

</body>
</section>
<section>
<title>Changing text</title>
<body>

<p>
We've used the <c>c</c> (change) command a little bit so far when we
typed <c>cc</c>, <c>c0</c> and <c>c$</c>. <c>cc</c> is a special form
of the change command, similar to <c>dd</c>. the <c>c0</c> and
<c>c$</c> commands are examples of using the change command in
combination with a movement command. In this form, <c>c</c> works
similarly to <c>d</c>, except that it leaves you in insert mode so
that you can enter replacement text for the deleted region. Try
combining some movement commands with <c>c</c> and test them out on
your file (hint: <c>cW</c>, <c>ce</c>, <c>c(</c> .)
</p>

</body>
</section>
</chapter>

<chapter>
<title>Compound Commands</title>
<section>
<body>

<p>
vi <e>really</e> becomes powerful when you start using compound
("combo") commands, like <c>d{</c> and <c>cw</c>. In addition to
these commands, you can also combine a number with any movement
command, such as <c>3w</c>, which will tell vi to jump three words to
the right. Here are some more movement "combo" command examples:
<c>12b</c>, <c>4j</c>.
</p>

<p>
vi, in addition to allowing (number)(movement command) combinations,
also allows <c>d</c> or <c>c</c> to be combined with a number or
movement command. So, <c>d3w</c> will delete the next three words,
<c>d2j</c> will delete the current and next two lines, etc. Test out
some <c>c</c> and <c>d</c> combo moves to get a feel for how powerful
and concise vi editing can be. Once these commands are second-nature,
you'll be able to edit files at blazing speed.
</p>

</body>
</section>
<section>
<title>Updating the cheat sheet</title>
<body>

<p>
Time to update the cheat sheet again. Here's what it looks like so
far:
</p>

<figure link="/images/vicheat-compound.png" short="Cheat Sheet" caption="Cheat
sheet with compound commands"/>

</body>
</section>
<section>
<title>Productivity features</title>
<body>

<p>
So far, we've covered how to move, save and quit, perform simple edits
and deletions, and use insert mode. With everything listed on the
cheat sheet so far, you should be able to use vi to perform almost any
task.
</p>

<p>
However, vi also has many more powerful commands. In this section,
you'll learn how to <e>cut</e>, <e>copy</e> and <e>paste</e>,
<e>search</e> and <e>replace</e>, and use <e>autoindent</e> features.
These commands will help make vi more fun and productive.
</p>

</body>
</section>
<section>
<title>Visual mode</title>
<body>

<p>
The best way to cut and paste is to use <e>visual mode</e>, a special mode that
has been added to modern versions of vi, like vim and elvis. You can think
of visual mode as a "highlight text" mode. Once the text is highlighted,
it can be copied or deleted, and then pasted. If you are using gvim, you
can highlight by simply dragging the left mouse button over a particular
region:
</p>

<figure link="/images/vihighlight.png" short="Highlighted text" caption="VIM
with highlighted text"/>

<p>
In addition, you can also enter visual mode by hitting <c>v</c> (this
may be your only option if you are using vi from the console.) Then,
by moving the cursor using movement commands (typically the arrow
keys), you'll be able to highlight a region of text. Once
highlighted, we are ready to cut or copy the text.
</p>

<p>
If you're copying the text, hit <c>y</c> (which stands for "yank").
If you're cutting the text, hit <c>d</c>. You'll be placed back in
command mode. Now, move to the position where you'd like to insert
the cut or copied text, and hit <c>P</c> to insert before the cursor,
or <c>p</c> to insert after the cursor. Voila, the cut/copy and
paste is complete! Test out several copy/cut and paste operations
before advancing to the next section.
</p>

</body>
</section>
<section>
<title>Replacing text</title>
<body>

<p>
To replace patterns of text, we use <e>ex</e> mode. If you'd like to
replace the first pattern that appears on the current line, type
<c>:s/&lt;regexp&gt;/&lt;replacement&gt;/</c> and hit
<c>&lt;ENTER&gt;</c>, where &lt;regexp&gt; is the pattern you'd like
to match and &lt;replacement&gt; is the replacement string. To
replace all matches on the current line, type
<c>:s/&lt;regexp&gt;/&lt;replacement&gt;/g</c> and hit enter. To
replace every occurence of this pattern in your file (normally what
you want), type <c>:%s/&lt;regexp&gt;/&lt;replacement&gt;/g</c>. If
you'd like to do a global replace, but have vi prompt you for each
change, type <c>:%s/&lt;regexp&gt;/&lt;replacement&gt;/gc</c> (stands
for "confirm") and hit <c>&lt;ENTER&gt;</c>.
</p>

</body>
</section>
<section>
<title>Indentation</title>
<body>

<p>
vi supports autoindentation, for when you are editing source code.
Most modern versions of vi (like vim) will auto-enable autoindent mode
when you are editing a source file (like a .c file, for example).
When autoindent is enabled, you can use <c>&lt;CTR&gt;d</c>
(control-d) to move one indent level to the left, and
<c>&lt;CTR&gt;t</c> (control-t) to move one indent level to the right.
If autoindent wasn't enabled automatically, you can manually enable it
by typing in the <e>ex</e> command <c>:set autoindent</c>. You can
also tell vi to set the tab size to your favorite setting by using the
<c>:set tabstop</c> command; <c>:set tabstop=4</c> is quite popular.
</p>

</body>
</section>
<section>
<title>Our final cheat sheet</title>
<body>

<p>
Well, we've reached the end of the vi tutorial! After adding all the
advanced editing commands to your cheat sheet, it should look like
this:
</p>

<figure link="/images/vicheat-final.png" short="Cheat Sheet" caption="Final
cheet sheet"/>

<p>
Keep your cheat sheet handy, and begin using vi to edit files and
compose emails. Refer to the cheat sheet when needed; you'll find
that within the week, you'll have nearly all the commands memorized
and your vi productivity will shoot through the roof!
</p>

<p>
If you want to use vi as your default editor, use <c>eselect</c>:
</p>

<pre caption="Setting vi as the default editor">
~# <i>eselect editor list</i>
Available targets for the EDITOR variable:
  [1]   /bin/nano
  [2]   /bin/ed
  [3]   /usr/bin/ex
  [4]   /usr/bin/vi
  [ ]   (free form)

~# <i>eselect editor set 4</i>
Setting EDITOR to /usr/bin/vi ...
>>> Regenerating /etc/ld.so.cache...
Run ". /etc/profile" to update the variable in your shell.
</pre>

<p>
If you want to set this for your user only instead of system wide, set the
<c>EDITOR</c> variable in your <path>~/.bashrc</path>:
</p>

<pre caption="Setting vi as the users' editor">
~$ <i>vi ~/.bashrc</i>
<comment>(...)</comment>
export EDITOR="/usr/bin/vi"
</pre>

</body>
</section>
<section>
<title>Resources</title>
<body>

<p>
Here are some resources you may find helpful as you continue to learn
more about vi:
</p>

<ul>
  <li>
    <uri link="http://www.thomer.com/thomer/vi/vi.html">The vi Lovers
    Home Page</uri>, an excellent resource for all things vi
  </li>
  <li>
    <uri link="http://www.vim.org/">The vim homepage</uri> is the place
    to go for all your vim needs
  </li>
  <li>
    If you're looking for a good, old-fashioned book, <uri
    link="http://www.oreilly.com/catalog/vi6/">Learning the vi Editor,
    6th Edition</uri> would be an excellent choice. Contains good
    coverage of vi and vi clones.
  </li>
</ul>

</body>
</section>
<section>
<title>About this document</title>
<body>

<p>
The original version of this article was first published on IBM
developerWorks, and is property of Westtech Information Services. This
document is an updated version of the original article, and contains
various improvements made by the Gentoo Linux documentation team.
</p>

</body>
</section>
</chapter>
</guide>