Introduction: What Vim Is and Why Anyone Uses It | Vim Tutorial

This chapter gets you from "I don't have Vim installed" to "I saved my first file and quit on purpose".

What Vim Is

Vim is a modal text editor. You spend most of your time in a mode where every letter is a command, and a small fraction of your time in a mode that types letters into the file. That sounds backwards. It is also why Vim is fast once it clicks.

Vim is a descendant of vi, which dates to 1976. The history is interesting. It is not what you came here for.

What you get

An editor that runs in a terminal, over SSH, inside a container, on a Raspberry Pi, and on the machine in front of you
A command language that composes: learn a dozen pieces and you get hundreds of combinations for free
A help system (:help) that is genuinely excellent
Decades of stability. The muscle memory you build today still works in ten years

What you do not get

Autocomplete, debugging, and project search in the default install. You add those with configuration or plugins
A friendly onboarding flow. Vim assumes you read vimtutor and now you're a Vim user
A mouse-first experience

Installing Vim

Most systems already have a version of Vim. Check first:

vim --version | head -n 1

If you see VIM - Vi IMproved 8.2 or newer, you are set. Otherwise install it:

# macOS with Homebrew
brew install vim

# Debian, Ubuntu
sudo apt install vim

# Fedora
sudo dnf install vim

# Arch
sudo pacman -S vim

# Windows
winget install vim.vim

Neovim

Neovim is a popular fork with cleaner internals, a Lua config system, and first-class LSP support. Everything in this tutorial works in both unless called out.

brew install neovim          # macOS
sudo apt install neovim       # Debian, Ubuntu

The binary is nvim. For the rest of this tutorial, vim means "whichever one you installed".

vimtutor

Before you go further, run this:

vimtutor

You get a 30-minute interactive tour of the basics. Do it once. Do it a second time tomorrow. This tutorial assumes you have, or will.

Your First Session

Open a file:

vim scratch.txt

You are now in normal mode, staring at an empty buffer. Normal mode is where Vim starts. Letters are commands, not text. If you press i you enter insert mode and can type normally.

Try this, slowly:

i                     enter insert mode. "-- INSERT --" appears at the bottom
Hello, Vim.
This is my first file.
<Esc>                 back to normal mode
:w                    save. type : then w then Enter
:q                    quit

You wrote a file. You saved it. You left. That is the whole loop.

The `:q!` safety valve

At some point, you will open a file, change it by accident, and want to leave without saving. Vim refuses politely:

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

The fix:

:q!

The ! means "yes, I know, throw away my changes". Burn this into your hands. It is the escape hatch that keeps Vim from feeling like a trap.

The pairs of save and quit commands

:w           save
:q           quit
:wq          save and quit
:x           save if changed, then quit
ZZ           same as :x, without the colon
:q!          quit, discard changes

Pick one pair and stick with it. Most people use :w and :q.

The Help System

Vim has the best inline docs of any editor. When you hit a wall:

:help <topic>

A few topics that matter early:

:help motion          everything about moving around
:help text-objects    iw, a", and friends
:help registers       yank and paste
:help :substitute     search and replace

Navigate help with the same keys as any buffer. <C-]> follows a link, <C-t> goes back. Close help with :q.

You do not need to memorise the docs. You need to know that :help is where the answer lives.

A Realistic First Task

Open your shell config and add a line. This is a real thing you will do.

vim ~/.bashrc
# or ~/.zshrc if you use zsh

In normal mode:

G                 jump to the last line
o                 open a new line below and enter insert mode
export EDITOR=vim
<Esc>             back to normal mode
:w                save
:q                quit

Reload the shell:

source ~/.bashrc

EDITOR=vim tells git commit, crontab -e, and dozens of other tools to open Vim. You now have a reason to keep using it.

How Vim Reads Commands

Even at this stage, it helps to see the pattern. In normal mode, commands look like one of these shapes:

A single key: u (undo), x (delete character)
A letter followed by a motion: dw (delete a word), c$ (change to end of line)
A number followed by a command: 5j (move down five lines), 3dd (delete three lines)
A colon command: :w, :q, :help

You will not memorise this by staring. You will absorb it by typing the examples for the next eleven chapters.

Common Pitfalls

"I pressed keys and the file filled with garbage." You were in normal mode. Letters are commands. Press u until your file looks right again, then press i before you type.

"I can't quit." If Vim complains about unsaved changes, use :q!. If nothing happens when you type :q, you are probably still in insert mode. Press <Esc> first.

"Vim is slow to start the first time." It isn't, but terminal emulators sometimes stall on the first paint. Ignore it.

"My arrow keys work but everyone says not to use them." Arrow keys are fine. hjkl is faster once you stop thinking about it. We get there in chapter 3.

"I opened a file I didn't mean to." :q closes it. If you changed it by accident, :q! throws away the change.

Next Steps

Continue to 02-modes.md to learn the modal model that makes every other Vim feature make sense.