Your Vim config, line by line

All through the course you train in a dojo someone set up for you: numbers in the gutter, a few lines kept above the cursor, searches that ignore case. Your own editor is your own dojo, and the config is the list of rules on its wall. The editor reads it at every start and does what it says.

To open it, type :e $MYVIMRC in Vim or Neovim: $MYVIMRC holds the path of the config the editor loaded. No config yet? Then there's nothing to open, so make the file. In Vim, :e ~/.vimrc and :w. In Neovim, :exe 'edit' stdpath('config') .. '/init.lua', then :w ++p (the ++p makes the folder too). :echo $MYVIMRC tells you which file is in charge at any time.

• Neovim: Lua or Vim script. init.lua and init.vim both work, one at a time. This guide shows both Vim script and Lua; the options are the same names in each.
• Vim: one surprise. With no ~/.vimrc, Vim loads defaults.vim, which switches on syntax highlighting, incsearch, scrolloff=5 and the mouse. The moment your own file exists, it doesn't. Keep them with two lines at the top: unlet! skip_defaults_vim and source $VIMRUNTIME/defaults.vim.
• Neovim starts friendlier. hlsearch, incsearch, the mouse and syntax highlighting are already on, undo files already have a folder of their own (undofile itself still needs switching on), and termguicolors switches itself on when your terminal can show true colour.

The window below is Vim with an empty config, after a search for total. Each switch is one line in a config file: flip it and the window redraws the way that line would make it. Under the window, the file those switches add up to, in Vim script, Lua or VS Code's JSON, ready to copy.

Try number and then relativenumber, together and on their own, and watch what happens to your own line's number. Then flip ignorecase with hlsearch off and on.

Each line below earns its place by fixing something you'd otherwise notice every day. Vim script first, Lua after.

• Where am I? set number relativenumber (vim.opt.number = true, vim.opt.relativenumber = true). Your line shows its real number, for :42 and error messages; every other line shows how far away it is, which is the count you type before j or k.
• Searches that read your mind. set ignorecase smartcase. /total finds Total and TOTAL too; type a capital, /Total, and case counts again.
• See every match. set incsearch hlsearch: matches light up while you type the search, and stay lit after. :nohlsearch (or :noh) puts them out until the next search; Neovim already does both, and its Ctrl-l clears them.
• See where you're going. set scrolloff=8 keeps eight lines past the cursor in view, so you never edit on the window's last row.
• Long lines. wrap is on by default: a long line folds onto the next screen row. set nowrap cuts it at the edge instead, which code readers often prefer.
• Spaces, not tabs. set expandtab shiftwidth=2 tabstop=2: >> and the Tab key put in two spaces, and a real tab character shows two columns wide. Use 4 if that's your project's style.
• Undo that survives. set undofile keeps undo history after you close the file. In Vim, also set undodir=~/.vim/undo// (make that folder first), or the undo files land next to your code; Neovim already keeps them in its own folder.
• The system clipboard. set clipboard=unnamedplus (vim.opt.clipboard = "unnamedplus") makes y and p use the clipboard every other app uses. In Vim on macOS or Windows, use unnamed; Vim needs to be built with clipboard support (vim --version shows +clipboard).
• The mouse. set mouse=a lets you click, select and scroll in a terminal Vim. Neovim has it on already.
• Splits where you look. set splitbelow splitright: :split opens below and :vsplit to the right, as most apps do.
• Real colours. set termguicolors in Vim, for colour schemes made for true colour terminals.

In Lua, an on/off option is true or false, a number is a number, and a word is a string: vim.opt.clipboard = "unnamedplus". Neovim's own example config writes vim.o.number = true; vim.o and vim.opt both work for these.

Every option can be tried before it goes in the file: :set relativenumber switches it on in this editor until you quit. When it's what you want, write the same words in the config without the colon.

• Is it on? :set number? answers number or nonumber; :set scrolloff? answers scrolloff=0.
• Who set it? :verbose set scrolloff? also says which file and line last set it: the first thing to type when an option won't stay the way you wrote it (a plugin may have changed it).
• Flip it. :set number! turns it on if it's off and off if it's on; :set nonumber turns it off.
• Reload. :source % runs the file you're editing, so a change in your config takes effect at once (in Neovim, Lua files too). Deleting a line and reloading doesn't switch its option back off, though: restart for a clean slate.
• Read about it. :help 'scrolloff' (the quotes find the option) explains any option; :options lists them all, with their current values.
• When it breaks. vim --clean or nvim --clean starts with no config at all, so you can always get in and fix the file.

Neovim reads Lua, Vim reads Vim script, and the option names are the same in both. Once you can read one column below you can write the other. When there's no Lua spelling to hand, vim.cmd("set number") runs any Vim script line from Lua.

A mapping makes some keys stand for others. The shape is the same everywhere: the mode, the keys you'll press, and the keys they stand for. inoremap jk <Esc> (Lua: vim.keymap.set("i", "jk", "<Esc>")) means: in Insert mode, typing j k quickly does Esc. It's the most popular first mapping, because your fingers never leave the home row.

Why `noremap`? The nore means the right-hand side is pressed as Vim's own keys, not through your other mappings. Swap ; and : with nmap ; : and nmap : ;, and each mapping feeds the other forever; with nnoremap they swap cleanly. Always use the noremap forms (nnoremap, inoremap, vnoremap) unless you mean to chain mappings. vim.keymap.set is non-recursive already.

The leader is a key that starts commands of your own, so they never land on a key Vim already uses. It's a backslash until you choose; Space is popular, since in Normal mode it only moves one character right. Set it first, let mapleader = " ", then map: nnoremap <leader>h :nohlsearch<CR> makes ␣ h put out the search highlights. Set the leader before the mappings that use it: a mapping reads the leader when it's made.

The Vim plugins for other editors read their own config, so the same ideas travel in a different spelling.

• VS Code (VSCodeVim). Settings go in your user settings.json. Some are the extension's, under vim.: "vim.hlsearch": true, "vim.leader": "<space>", "vim.useSystemClipboard": true. Others are VS Code's own, because VS Code draws the screen: "editor.lineNumbers": "relative" for relative numbers, "editor.cursorSurroundingLines": 8 for scrolloff, "editor.wordWrap" for wrapping. vim.ignorecase and vim.smartcase are already on. Mappings are lists of before and after keys, per mode. The extension can read a .vimrc (vim.vimrc.enable), but only its mappings, and it's marked experimental.
• JetBrains IDEs (IdeaVim). ~/.ideavimrc reads like a .vimrc: set number relativenumber, set ignorecase smartcase, set scrolloff=8, inoremap jk <Esc>. It understands a subset of Vim's options, and adds its own for IDE actions. After an edit, IdeaVim offers a reload button in the editor, or type :source ~/.ideavimrc.

More on each: Vim in VS Code and Vim in JetBrains IDEs.

The fastest way to a config you hate is to copy someone's thousand lines on day one: plugins you didn't choose, mappings that move keys the tutorials assume, and no idea which line did what. Learn the stock editor first, then add options as you find a need.

• Start with nothing, or the few lines below. Use the editor for a week.
• Add a line when something bugs you twice. Try it with :set first, then write it down.
• One line, one reason. A comment above a line you might forget (" keep 8 lines in view) is worth it.
• Keep it in git. A dotfiles repo means a new laptop is one clone away, and every change has a date and a reason.
• Starting points worth reading, not pasting. Neovim 0.11 ships $VIMRUNTIME/example_init.lua, a short, commented config: :read $VIMRUNTIME/example_init.lua puts it in your file to read line by line.

A year from now your config will be a record of how you work, and every line in it will mean something to you. Practising the moves themselves is what the course is for.