A First Vim Tutorial

An Introduction to Vim.

I've started using vim again. I thought I would post some of my vim notes.

I generally use vim 50% in the terminal, and now 50% as Cream (UPDATE: After learning more Vim commands I switched from Cream to regular Gvim).

Cream is a version of gvim that makes using vim really easy. If you want an easy introduction to vim, try Cream first.

Vim has a reputation as being difficult to use. That is because when you first start it up you are presented with nothing but the following screen. It won't let you type any text, and depending on what keys you push, the editor may perform strange behavior.

Basically there are two modes in Vim: Normal mode and Insert mode. It starts up in normal mode which means that you cannot type text into your text file until you enter insert mode.

Because just about every Unix-based system (including Linux and Mac OSX) has vim by default, knowing the basics of vim can be good for emergencies. On some Linux distros there is no emacs but there is vim. If your computer becomes unbootable but you can still boot into a terminal, just knowing the basics of Vim might be able to help you edit the required files to fix your system.

Also, despite their somewhat cryptic operation, editors like Vim and emacs are very powerful and very fast to use once you learn them. There are entire books written about Vim, and the links at the bottom of this page can give you an idea about how complex and powerful Vim is.

How to use Vim

To start Vim in Linux, just type vim in the terminal. You can optionally specify a file to open or create — if the file exists it will open the file, and if the file does not exist, it will be created. For example:

$ vim file.txt

Pressing either the letter i key or the INS key will put you into Insert mode where you can enter text. Push the ESC key to switch to Normal mode where you can enter Vim commands.

The following commands will be enough to start. There is also a tutorial built into vim that you can study to learn more. To start the Vim tutor, just type vimtutor in a terminal. The following summarizes most of what the vimtutor teaches as well as additional commands found in the user manual. After you go through the vimtutor, the following makes a good review that you can bookmark in case your memory of vim gets a little rusty down the road. The vimtutor also gives instructions on how to set up a configuration file that will automatically provide syntax highlighting when you start vim.

Getting help

F1 — this key will get you into the help pages of Vim from within the program, although if you are running vim inside a something like GNOME terminal, you might get the help pages for GNOME terminal when you use F1. The following help commands will always be available:

• :help — open the help pages
• :q — this will close the help screen. If the help screen is not open, it will exit Vim.
• :help user-manual — this will open the full user manual

Closing Vim

• :q — quit Vim
• :wq — save file and quit Vim
• :q! — quit without saving

Saving a file in Vim

• :w — saves the current file.
• :w FILENAME — save the file with the filename that you provide. If you specify a different name than the filename that you originally opened, Vim will go back to the original file name if you save it another time in the same session without specifying the new file name.
• :saveas FILENAME — this will save the file with your new name and continue editing it under the new filename.
• :#,# w FILENAME — saves just text between line numbers that you specify.

Moving around the document

• h — moves cursor left
• l — moves cursor right
• j — moves cursor down
• k — moves cursor up

USEFUL TIP: If you want to get used to navigating through a document in vim, start playing a free game called Nethack. If you are using Ubuntu or another Debian-based version of GNU/Linux, you can install Nethack in the terminal by typing: sudo apt-get install nethack-console. Once Nethack is installed, start it by typing nethack in a terminal.

• w — moves cursor to beginning of next word
• b — moves to the beginning of previous word
• e — moves cursor to end of the next word
• ge — moves to the end of the previous word
• $ — moves cursor to the end of line
• ^ — moves cursor to the first non-space character of line
• 0 — pressing the number zero moves to the absolute beginning of the line
• [number] Shift-g — moves you to the specified line number
• Ctrl-g — tells you what line you are on
• gg — go to the first line of the file
• [number]% — moves to to a certain percentage of the file, e.g., typing 30% moves you to 30% from the top of the file.

Like most Vim commands, prefix the command with a number to repeat it. So typing 3w will move the cursor forward by 3 words.

Adding text

Vim generally starts in Normal mode. To insert text into your file, press the letter i. To return to Normal mode, press the ESC key, or more conveniently Ctrl-c or Ctrl-[.

• i — enters insert mode, inserting new text before the point of the cursor
• Shift-I — moves the cursor to the beginning of the line and enters insert mode.
• a — enters insert mode, inserting (appending) new text after the current point of the cursor
• Shift-A — enters insert mode, appending text to the end of the current line
• o — opens a line below the cursor and enters insert mode.
• Shift-O — opens a line above the cursor and enters insert mode

Deleting text

• dd — deletes the current line
• x — deletes one letter under the cursor
• dw — deletes from the cursor to the end of the word including the space
• de — deletes from the cursor to the end of the word not including the space
• d$ — deletes from cursor to the end of the current line

You can tell Vim to repeat commands by giving it a number. For example, typing 4dw will delete from the cursor to the end of the current word, plus 3 more words including the space after the word. It can also be typed with the number in the middle like this d4w and it will do the exact same thing as the previous example.

How to undo commands in Vim

This is one of the most important things to know:

• u — undo command
• U — undo everything on the line
• CTRL-r — redo command (after undoing it)

"Copy / paste" in Vim, or "putting" text

When you delete text it is stored by Vim and you replace it by putting it back with the p key.

• p — paste the last deleted text on the line below the cursor.

Retreiving and inserting a file into another file

You can insert another text file into the current text file.

• :r FILENAME — inserts FILENAME into the current file.

Replacing text

• r — press the letter r and then the letter that you want to replace the letter under the cursor with.
• Shift-R — this works like the Insert key. It allows you to type on top of the text, replacing it. When done, press ESC to exit.

Changing text

• cw — change the text from the cursor to the end of the word (deletes and goes into insert mode
• c$ — change the text from the cursor to the end of the line

Searching for text

• / — search for text in a forward direction
• ? — search for text in a backwards direction
• n — search again in the same direction
• Shift-N — search again in the opposite direction
• f — press f and then another character and the cursor will move to that character on the current line.
• Shift-F — like f but searches backwards
• t — like f except that it moves the cursor one character before the specified character
• Shift-T — like t but in a backwards direction

There are many other nice tricks you can employ. While in the search mode, try the following options:

• :set ic — ignore case (i.e., case-insensitive search)
• :set hls is — make it a highlighted incremental search
• :set noh — remove the highlighing option

Substitute, or find and replace text

• :s/old/new — Substitutes new for old on the current line, but only the first occurance of the word.
• :s/old/new/g — substitutes new for old every time it appears on the current line.
• :#,#s/old/new/g — substitutes new for old every time it occurs between line numbers placed where the # symbols are. (Ctrl-g will tell you the current line number that the cursor is on.)
• :%s/old/new/g — substitutes new for old every time it occurs in the entire file.
• :%s/old/new/gc — this works like the previous example except asks for confirmation each time the text is replaced.

Matching parentheses

• % — helps you find matching brackets: (, [, and {

Executing commands

You can send commands to the terminal from within Vim, for example to list the contents of a directory.

Here are a couple of examples in Linux, or in Windows under Cygwin:

• :!ls — This will list the contents of the current directory, and then return you to Vim when you are done. If you are using Vim at a command prompt in Microsoft Windows without Cygwin, you should be able to type :!dir to get a list of directory contents. If you are using Vim at the command line in Windows and don't have Cygwin, consider downloading it and trying it.

You can even run external programs from within Vim by prefixing the commands with :!.

More vim Tutorials

• Vim docs — Everything about vim.
• More good vim tips, especially for advanced searching.
• Seven Habits of Effective Text Editing
• Vim Cookbook
• Portable GVim — Take Vim with you.

Vim Cheatsheets

• Graphical cheatsheet and tutorials
• Vim cheatsheet
• Small Vim cheatsheet — good for beginners because there is not a lot of information on it.
• Vim cheatsheet in several formats
• Download a good Vim cheatsheet here
• Learning Vi, the cheatsheet technique

Getting Started With Vim

I have often wished that I could talk to my text editor. "Editor, delete the text up to the next closing HTML tag. Take this list of 15 words and enclose each line in <li> tags."

I've been using Vim since last summer and I am finally able to talk to my editor. It took a while to learn Vim's language, but it began to make sense after learning enough of the commands.

This tutorial shows some of the great things that I like about using Vim.

I'm using Vim 7 on Ubuntu Dapper, and most of what I've written here should work on Vim 7 anywhere. (To my knowledge tabs will only work in Vim 7.)

I usually start Vim in one of three ways:

1. Open a terminal (mapped to Ctrl-Alt-Shift-t in my GNOME) and type vim
2. Press Alt-F2 in GNOME and type gvim
3. Right click on a file in Nautilus and choose "open in vim"

Quick Tips

Cream

Cream is an easy-to-use version on Gvim. It is a good way to get started with Vim because it removes the complexities of the modal editing. You can set Cream up for expert mode which allows you to turn modal edition on and off. As you learn more commands you will probably want to switch to plain Gvim because modal editing is the main benefit of Vim.

Switching Between Vim and Gvim

When running Vim in the terminal you can type :gui to move the current file to Gvim.

The .vimrc File

The .vimrc file allows you to customize Vim. I've attached my .vimrc file which is just the default .vimrc file with a few modifications. I had a more extensive .vimrc file which disappeared on my last OS re-installation.

This is the section that I added to the default .vimrc file:

" ADDED BY ME
set softtabstop=4
set shiftwidth=4
set tabstop=4
" Use spaces instead of tabs
set expandtab
colorscheme desert
set guifont=monospace\ 13
set number
set ignorecase
set vb " turns off visual bell

Editing Markup With surround.vim

If you write any kind of markup (like XML or HTML) then you should try tpope's excellent surround.vim plugin. Surround.vim lets you highlight a section of text and automatically enclose it with markup tags.

For example, you could highlight the current line with a capital V, then type s<li> and the line will automatically be enclosed in <li></li> tags. It will even accept HTML attributes. So you can highlight a section of text and type s<a href="http://www.example.com"> and surround.vim will properly enclose the text with the link code.

You can repeat the surround.vim commands by recording a macro. The letter q starts and stops the macro recording. To enclose many sections of text in <strong> tags, you could highlight the first section of text with something like ve (visual/highlight until the end of the word), then type qss<strong> followed by the enter key. Then q again to stop the recording. The macro will be stored in the s key (the first key that you pushed after starting the macro). To repeat the recorded action, highlight the next set of text and press @s to surround it with the <strong> tags.

Talking to Vim

A first step in learning Vim should be the Vim tutor. Just type vimtutor in a terminal to begin. If running Gvim on Windows, I believe there is an option to start vimtutor from the Start Menu.

I have a Vim tutorial that lists many of the commands found in the vimtutor.

The Vim tutorial on Gentoo.org is great.

The article Efficient Editing With vim is highly recommended because it groups common commands in a logical way.

Consider pasting a Vim cheatsheet like this, this, and/or this next to your computer. Post a blank sheet next to the Vim cheatsheet(s) to take notes on commands that you would like to remember.

Programming Tools

Syntax Highlighting

If you have started a new file in Gvim and tried to save it, the syntax highlighting might not turn on automatically. Just use :e and the syntax highlighting will be applied.

If you haven't saved the file yet, but would like syntax highlighting, use :setf [filetype] to tell Vim what kind of file it is. An example usage would be :setf python or :setf html.

Line Numbers

I set my .vimrc file to always have line numbering on. Sometimes I have to turn it off, for example when copying/pasting multiple lines or exporting code as HTML. To turn off line numbering use :set nonumber. To turn it back on use :set number.

Converting Code to HTML

You can export your file as HTML with :TOhtml. I haven't figured out how to export clean HTML though. The :TOhtml command exports deprecated HTML filled with font tags. If someone knows a way to get Vim to export better HTML, please let me know.

Vim Tabs

Vim 7 has tabs. You can open a new tab with the command :tabnew or :tabnew [filename].

To switch between tabs you can use gt or if in Gvim you can click on a tab to switch to it.

The images below show tabs in both Vim and Gvim.

Tabs in Vim 7

Tabs in Gvim 7

HTML and XML in Vim

Install the excellent XML Edit for extra features when editing XML, HTML, SGML documents with Vim.

Ruby on Rails and Vim

If you use Ruby on Rails, check out rails.vim — another excellent Vim plugin by tpope. It contains many of the features of Textmate while still allowing you to use your favorite operating system. I previously covered this plugin in an earlier post about editors for Rails.

See also the excellent article Vim for Textmate fans...

Other Vim Plugins

I'm experimenting with other Vim plugins at the moment.

TVO—The Vim Outliners allows you to create outlined documents in Vim. After you install it, type :he tvo for documentation.

Vim Taglist — View some screenshots.

More on Vim coming soon...

How to Use Vim's Spellchecker

Vim 7 has built in spellchecking. There are two easy ways to turn on spellchecking. If you are using Gvim, you can use Tools > Spelling > Spellcheck On:

If you are using Vim in the terminal, or prefer to type, you can turn on spellchecking in Vim with the command :set spell and turn off spellchecking with :set nospell.

Mispelled words will then be underlined in red in Gvim:

Or highlighted in using Vim in the terminal:

Here are the commands you need to know:

• ]s — move to the next mispelled word
• [s — move to the previous mispelled word
• zg — add a word to the dictionary
• zug — undo the addition of a word to the dictionary
• z= — view spelling suggestions for a mispelled word

Here is the Vim spellchecker offering suggestions for the word Nihon:

That is Vim spell checking in a nutshell. For more commands and documentation, just type :help spell into Vim or read the Vim spell docs online.

Vim Syntax Highlighting

If you are working on files with unusual extensions and want to have vim add a certain type of syntax highlighting, you can edit your .vimrc file to recognize new file extensions.

First, be sure that your vim has syntax highlighting enabled. You can add this to your .vimrc file to always turn on syntax highlighting:

" Switch syntax highlighting on, when the terminal has colors
" Also switch on highlighting the last used search pattern.
if &t_Co > 2 || has("gui_running")
  syntax on
  set hlsearch
endif

Example: CakePHP Syntax Highlighting in Vim

Here is an example from CakePHP, which uses PHP in files with the extension .thtml:

You could add the following line to have vim highlight .thtml files as XML files. I like having Vim treat .thtml files as XML files because much of the content of the files is XML (XHTML):

au BufNewFile,BufRead *.thtml setfiletype xml

I prefer the XML settings because the xmledit plugin for vim gives you extra features when editing xml (or xhtml) files.

Vim Color Schemes / Themes

I found a nice Vim color theme called Wombat.

To install the Wombat scheme, download the file from the site above and put it in ~/.vim/colors/. You can then enable it in your ~/.vimrc file with the following line:

colorscheme wombat

(Replace the word wombat with the name of your desired Vim color scheme. I'm on Ubuntu Dapper with Vim 7, so the locations of your files may differ.)

My favorite Vim scheme is the Desert scheme, but I don't like the green color when in visual mode. So I created a custom scheme by copying the file /usr/share/vim/vim70/colors/desert.vim to the desktop and making a couple of modifications:

I changed line 22 from let g:colors_name="desert" to the name of a new Vim color theme. Then I changed line 49 where it says hi Visual gui=none guifg=khaki guibg=olivedrab. I changed khaki to #000000 (black) and olivedrab to #c4c4c4 (light gray). Then I saved the file with a new name that matched the name that I gave the scheme inside the file.

Here is the original green highlighting the in Desert scheme's visual mode:

Here is the desert scheme with my modified highlighted color:

This is the Wombat color scheme for Vim — it's a nice theme, but the highlighting is a little faint. It could be changed by using the instructions above:

More Vim Color Options

Type :hi to get a list of entities that you can change the color on. It's fairly easy to make a custom syntax highlighting file in Vim.

This is what the Desert color scheme looks like in Vim 7 on Ubuntu 6.06:

How to Convert Code to HTML With Vim

If you have a code snippet that you want to convert to HTML for posting on the web, you can use Vim, or one of the Vim derivatives such as gVim or Cream.

Just put Vim into normal mode. Generally, that means pressing the ESC key. Then type the following command:

:TOhtml

Vim will output your code as HTML for posting on a web page. If syntax highlighting is on, it will even colorize the code for you. Here is a screenshot of some HTML being HTMLized for posting on the web:

Here is the output of Vim, pasted into this web page:

<html>
<head>
<title>This is a test</title>
</head>
<body>
<h1>Hi there</h1>
<p>This is going to be converted to HTML with Vim.</p>
</body>
</html>

Here is the same code HTMLized with gVim and code coloring:

<html>
<head>
<title>This is a test</title>
</head>
<body>
<h1>Hi there</h1>
<p>This is going to be converted to HTML with Vim.</p>
</body>
</html>

The colorized HTML is not clean, but it works if you need a quick solution for getting some colorized code onto a web page.

Vim Tips Page

This page will contain a list of great Vim resources.

• Vim as Development Environment — there are some great Vim tips here.
• Vim regular expressions