The Basics of vim and neovim

The installation of neovim on macOS is covered in a separate post. This one is about actually using the editor. If you’ve never really used vi, vim or neovim, or it’s been a while, this is a quick rundown of the commands you’ll need day to day. It applies to vim and neovim equally, the basics are identical.

Starting the Editor

On most systems, vi launches vim directly these days. Neovim is started with nvim. By default these editors live in the command line, so Terminal, iTerm2, or whatever terminal you use.

You can pass a file to open right at startup, e.g. nvim ~/.zshrc.

On the Mac there’s MacVim as a GUI for classic vim and VimR as a GUI for neovim. If you mostly live in the terminal, you don’t need either.

When you start the editor, you land in Normal mode.

Normal, Insert, Command?

Mode	What it’s for
normal	Navigation and text manipulation. Press `ESC` to get back here.
insert	The actual mode for typing text. Enter it with `i` (and others).
visual	Select a region to act on.
command	The editor’s command line. From normal mode press `:`.
Ex mode	Originally for batch processing and the ancestor of vi.

ESC always brings you back to normal mode. There you move around and run commands like dd to delete a line. In insert mode you actually type.

It sounds awkward at first but becomes second nature quickly.

The Most Important Commands in Command Mode

The first thing people struggle with is quitting the editor, so let’s start there.

In command mode (: from normal mode) you type real commands. Saving, opening, quitting and so on. I always write a leading colon so it’s clear the command goes into command mode.

Listing every command would explode this post. These are the essentials to actually operate vim or neovim.

Help

Take a look at :help at some point. vim ships with extremely thorough documentation. If a help window blocks part of the screen, :q usually gets you out.

Open, Save, Quit

Command	What it does
`:q`	Quits the editor. Won’t quit if there are unsaved changes.
`:q!`	Quits even with unsaved changes. Data loss possible.
`:w`	Saves without quitting. `:w filename` saves under a new name.
`:w! filename`	Saves and overwrites an existing file, without quitting.
`:wq`	Save and quit. The cool kids press `ZZ` in normal mode.
`:wqa`	Save and close all tabs. Useful once you start using tabs.
`:e filename`	Opens a file in another buffer. Think of a buffer as another layer in the editor.

Search and Replace

Searching itself happens from normal mode, that’s covered further down.

Command	What it does
`:%s/needle/replacement/g`	Searches and replaces across the whole document.
`:%s/needle/replacement/gc`	Same, but asks before each replacement.
`:%s/needle/replacement`	Without `/g`, only the next occurrence is replaced.
`:s/needle/replacement/g`	Search and replace only in the current line.
`:set ignorecase`	Searches case-insensitively. Active for the current session only.
`:set smartcase`	Pairs with `ignorecase`. If you use uppercase, case is respected again.

For set commands to stick, they need to go into your vim or neovim config.

Buffers

Command	What it does
`:bn`	Jumps to the next buffer. You can have multiple files open in different buffers.
`:bp`	Jumps to the previous buffer.
`:bf`	Jumps to the first buffer.
`:bl`	Jumps to the last buffer.
`:buffers`	Lists all open files (buffers).

That looks clunky but you can map it to keys. Splits and tabs are also a thing, but that’s a different topic.

Keyboard Commands for Normal, Insert, Visual and Friends

Moving Around in Normal Mode

Command	What it does
`h`	Cursor left. Arrow keys also work.
`j`	Cursor down.
`k`	up.
`l`	right.
`$`	Jumps to the end of the line.
`0`	Jumps to the start of the line.
`^`	Jumps to the first non-whitespace character of the line.
`gg`	Jumps to the start of the document.
`G`	Jumps to the end of the document.
`w`	Moves to the first character of the next word. Special characters count as words.
`W`	Jumps to the next word after a whitespace.
`b`	Like `w`, but backwards.
`B`	Like `W`, but backwards.
`e`	Like `w`, but lands on the last character of the word.
`E`	Like `W`, but on the last character of the word.
`ge`	Like `b`, but backwards.
`gE`	Like `B`, but backwards.
`)`	Jumps to the first character of the next sentence.
`(`	Jumps to the first character of the previous sentence.
`}`	Jumps to the next paragraph.
`{`	Jumps to the previous paragraph.
`+`	Cursor to the first character of the next line.
`-`	Cursor to the previous line.
`H`	Jumps to the first line of the visible window.
`M`	Jumps to the line in the middle of the visible area.
`L`	Jumps to the last line of the visible area.
`fx`	Jumps to the next occurrence of `x` in the current line. `f,` jumps to the next comma.
`Fx`	Like `fx`, but backwards.
`tx`	Like `fx`, but lands one character before.
`Tx`	Like `Fx`, but one character after.
`%`	Jumps to the matching bracket, brace or comment partner at the cursor.

Moving in Normal and Insert Mode

Command	What it does
Arrow keys	Behave like in any other editor.
`Ctrl+u`	Half a page up.
`Ctrl+d`	Half a page down.
`Ctrl+b`	Full page up.
`Ctrl+f`	Full page down.

Searching in Normal Mode

Command	What it does
`*`	Searches for the next occurrence of the word under the cursor.
`#`	Same backwards.
`/needle`	Forward search. Case sensitivity depends on settings.
`?needle`	Backward search.
`n`	Jumps to the next match.
`N`	Jumps to the previous match.

From Normal to Insert Mode

Command	What it does
`i`	Enters insert mode to type text.
`a`	Moves one character forward, then enters insert mode.
`I`	Jumps to the first character of the line and enters insert mode.
`A`	Goes to the end of the line and enters insert mode.
`o`	Adds a line below the current one and enters insert mode.
`O`	Adds a line above and enters insert mode.
`cw`	Replaces the current word. Deletes it and enters insert mode.
`cc`	Deletes the entire line and enters insert mode.
`C`	Deletes everything from the cursor to the end of the line and enters insert mode.
`s`	Deletes the character under the cursor and enters insert mode.

Deleting in Normal Mode

Command	What it does
`x`	Deletes the character under the cursor. Backspace works too.
`r`	Replaces the character under the cursor and stays in normal mode. `ra` puts an `a` there.
`dw`	Deletes the word. `dW`, `db` and other combinations work too.
`dd`	Deletes the entire line.
`D`	Deletes from the cursor to the end of the line.

Copy and Paste in Normal Mode

Command	What it does
`y`	Yanks (copies) the selected text (see `v` and `V`).
`yy`	Yanks the entire line.
`yw`	Yanks the word under the cursor. The combinations keep repeating.
`5yy`	Yanks 5 lines. Works with other numbers too.
`y$`	Yanks to the end of the line.
`p`	Pastes after the cursor.
`P`	Pastes before the cursor.
`J`	Joins the current and next line.

Visual Mode

Command	What it does
`v`	Visual mode, select text.
`V`	Visual mode for whole lines.
`o`	Moves the cursor in visual mode between the first and last character of the selection.
`~`	Toggles case of the selection.
`>`	Indents the selection to the right.
`<`	Outdents the selection.

Case

Command	What it does
`g~`	Toggles case of the character under the cursor.
`g~$`	Toggles case from cursor to end of line.
`g~~`	Toggles case for the current line.
`gUU`	Whole line to uppercase.
`guu`	Whole line to lowercase.

Undo, Redo, Repeat

Command	What it does
`u`	Undo.
`U`	Reverts all changes on the current line.
`Ctrl+r`	Redo.
`.`	Repeats the last change. Delete a line, hit `.`, and another line is gone.
`;`	Repeats the last `f`, `t`, `F` or `T` command.
`,`	Like `;`, but in the other direction.

You can prefix many movement and editing commands with a number. 5dd deletes 5 lines, 2dw deletes two words, 5j jumps 5 lines down.

For a much longer list, see tuxfight3r’s vim Keyboard Shortcuts. It goes well beyond what makes sense to dump here.

Starting the Editor¶

Normal, Insert, Command?¶

The Most Important Commands in Command Mode¶

Help¶

Open, Save, Quit¶

Search and Replace¶

Buffers¶

Keyboard Commands for Normal, Insert, Visual and Friends¶

Moving Around in Normal Mode¶

Moving in Normal and Insert Mode¶

Searching in Normal Mode¶

From Normal to Insert Mode¶

Deleting in Normal Mode¶

Copy and Paste in Normal Mode¶

Visual Mode¶

Case¶

Undo, Redo, Repeat¶

More¶