Notation for Simulating Vim on the Page
Ctrl-s is a common convention for representing chordal key commands. It means “While holding down the Ctrl key, press the s key.” But this convention isn’t well suited to describing Vim’s modal command set. In Modern Vim, I use a specific notation to illustrate Vim usage, which I outline here.
Playing Melodies
In Normal mode, commands are composed by typing one or more keystrokes in sequence. These commands appear as follows:
| Notation | Meaning |
|---|---|
x | Press x once |
dw | In sequence, press d, then w |
dap | In sequence, press d, a, then p |
Most of these sequences involve two or three keystrokes, but some are longer. Deciphering the meaning of Vim’s Normal mode command sequences can be challenging, but you’ll get better at it with practice.
Playing Chords
When you see a keystroke such as <C-p>, it doesn’t mean “Press <, then C, then -, and so on.” The <C-p> notation is equivalent to Ctrl-p, which means “While holding down the Ctrl key, press the p key.”
I didn’t choose this notation without good reason. Vim’s documentation uses it (:help key-notation), and we can also use it in defining custom key mappings. Some of Vim’s commands are formed by combining chords and keystrokes in sequence, and this notation handles them well. Consider these examples:
| Notation | Meaning |
|---|---|
<C-n> | While holding Ctrl press n |
g<C-]> | Press g, then while holding Ctrl press ] |
<C-r>0 | While holding Ctrl press r, then release Ctrl and press 0 |
<C-w><C-=> | While holding Ctrl press w then = |
Placeholders
Many of Vim’s commands require two or more keystrokes to be entered in sequence. Some commands must be followed by a particular kind of keystroke, while other commands can be followed by any key on the keyboard. I use curly braces to denote the set of valid keystrokes that can follow a command. Here are some examples:
| Notation | Meaning |
|---|---|
f{char} | Press f, followed by any other character |
`{a-z} | Press `, followed by any lowercase letter |
m{a-zA-Z} | Press m, followed by any lowercase or uppercase letter |
d{motion} | Press d, followed by any motion command |
<C-r>{register} | While holding Ctrl press r, then release Ctrl and press the address of a register |
<C-v>{nondigit} | While holding Ctrl press v, then release Ctrl and press any nondigit key |
Showing Special Keys
Some keys are called by name. This table shows a selection of them:
| Notation | Meaning |
|---|---|
<Esc> | Press the Escape key |
<CR> | Press the carriage return key (also known as <Enter>) |
<Tab> | Press the Tab key |
<S-Tab> | While holding Shift press <Tab> |
<M-j> | While holding Meta press j |
<Up> | Press the up arrow key |
<Down> | Press the down arrow key |
<Space> | Press the space bar |
<Leader>g | In sequence, press <Leader> then g |
Note that the Meta key goes by other names such as Alt and Option.
The Leader Key
The <Leader> key can be customized to suit your preference. The default <Leader> key is , but lots of people prefer to set it to the , key. You can set the leader key by putting this in your vimrc file:
| | let mapleader = ',' |
When you see the <Leader>g notation, you can translate the meaning to ,g, or g, or whatever is appropriate for your configuration.
Interacting with the Command Line
In some tips you’ll execute a command line, either in a shell or from inside Vim. For example, you might be instructed to change to a directory from the provided source code examples, before opening a particular file. The $ prompt in these examples indicates that the commands are to be run in an external shell:
| => | $ cd code/terminal/ |
| => | $ nvim readme.md |
Inside of Vim, pressing the : key switches from Normal mode to Command-Line mode. In this mode, you can type out Ex commands such as :write and :quit, using the <CR> key to execute the command. In the following examples, the : prompt indicates that the commands are to be executed using Vim’s Command-Line mode:
| => | :s/cool/awesome/g |
| => | :write |
Any time you see an Ex command listed inline, such as :write, assume that the <CR> key is pressed to execute the command. Nothing happens otherwise, so consider <CR> to be implicit.
In Neovim, you can run a shell inside of a terminal buffer using the :terminal command. (This is covered in detail in Chapter 5, Neovim’s Built-In Terminal Emulator.) In the following examples, the » prompt indicates that the commands are to be executed in a shell within a terminal buffer:
| => | » cat readme.md |
| => | » top |
This table summarizes the meaning of these different prompts:
| Prompt | Meaning |
|---|---|
: | Use Command-Line mode to execute an Ex command |
$ | Enter the command line in an external shell |
» | Enter the command line in an internal shell (within a terminal buffer) |