Emergency vim: You didn’t mean to open this editor

So you’re working along in shell and you enter a seemingly innocuous command like git commit (sans flags) and suddenly you are greeted with something like this:

Welcome to vim! If you’ve opted out of using vim in favor of other shell editors like pico, nano, et al you’re probably experiencing a non-trivial amount of adrenaline right now. That’s ok! The goal of this post is to provide the bear necessities of vim.

First thing to know: there are two modes

vim has two modes called insert (edit) mode and command mode. Insert mode is similar to opening up a document editor like Google Docs or Microsoft Word and just starting to type: it’s the mode that allows you to edit the text of whatever file is open. Command mode is what allows you to enter commands like write (save) or quit - this is similar to using the various drop down and ribbon menus in a document editor. Since there aren’t visual menus in shell, you’re using command keys to accomplish this.

Second thing to know: how to toggle

If you are in command mode, which is the default when vim opens, you can enter insert (edit) mode by pressing the i key. Likewise, if you are in insert (edit) mode and would like to switch to command mode, press the escape (esc) key.

You may notice that I keep typing the edit mode as “insert (edit) mode”, rather than simply “edit mode”. The reason for this is the command keys that vim uses are most typically the first letter of the command’s name. If you learn the name of the command you want to execute, like insert, you can make good faith guesses on future commands or at the least have an easier time searching for them.

Third thing to know: save before you quit

Once you have made the edits you wish you make, you will need to write (save) and quit. For those of us that remember what it was like to have document editors before autosave, you’ll be relieved to know that while vim may not autosave, it will throw an error if you try to quit with unsaved changes.

Many commands in vim are prefixed by a colon, so write (save) is :w and quit is :q. You can either run these as two separate commands, using enter/return to execute, or you can stack the commands like this: :wq. An added bonus: most commands in vim can be stacked this way.

But wait! What if you want to quit without those changes you definitely didn’t mean to make? The command to “quit without saving” or “force quit” is :q! Note that this is also a stacked command - ! is used for “force” with other commands where it applies as well.

Fourth thing to know: there’s more to know

If you want to learn more vim so you can do more tasks, like use a command sequence to delete individual words, change the case of a single character or whole line, or quickly use a command sequence to convert a bunch of newlines to a bulleted list, or at the very least reduce your stress when you unintentionally encounter it, then you’ll need more resources and practice. For hands on practice, there’s a Zelda-like game called Vim Adventures that has the first few levels free, after that there is a small paywall to unlock the remaining levels. There is also a free interactive tutorial at OpenVim. If interactive tutorials aren’t your jam, try taking a look at DevHints Vim Cheatsheet.

Command Summary

For when you just want the commands in this post, here they are:

• i - enter insert (edit) mode from command mode
• esc - enter command mode from insert (edit) mode
• :w - write (save)
• :q - quit
• :wq - stacking “write & quit”
• ! - force, when stacked with another command, e.g. :q! to force quit