Skip to content
Tutorials Center
My learning

Topics

Lesson 34 of 36 ยท Projects and Practice

Project: Build a Starter vimrc

Build a clean, commented, version-controlled Vim configuration in stages: options, search, leader mappings, autocommands, a statusline and plugins, then lint it with a checker.

In this project you assemble a small, readable configuration from the pieces in this chapter. The goal is not a copy of someone's 800-line setup but a file you understand line by line, organized so it can grow. Each stage is a section of one file; at the end you check it with a small linter written in JavaScript.

The finished file is a Vim vimrc. Neovim users can follow the same plan in init.lua using the translations from the init.lua lesson.

Plan

Six stages

Basics Options that help everyone
Search Smart and visible
Leader Your own shortcuts

One stage at a time, test after each.

1 / 2

Stage 1: basics

Create ~/.vimrc (or ~/.config/nvim/init.vim for Neovim). Begin with a header and the sane base:

VIM
" ============================================================
" vimrc: keep every setting commented with WHY it is there
" ============================================================
if has('vim_starting')
  set nocompatible
endif
filetype plugin indent on
syntax on

set encoding=utf-8
set hidden              " allow switching away from modified buffers
set mouse=a
set updatetime=300
set undofile            " persistent undo
set undodir=~/.vim/undo//
set backupcopy=yes
set wildmenu
set scrolloff=8
set number relativenumber
set cursorline
set signcolumn=yes

Create the undo folder once: mkdir -p ~/.vim/undo. The trailing // makes Vim use the full path in file names, avoiding collisions. Source the file with :source $MYVIMRC and check :set undofile?.

VIM
set tabstop=4 shiftwidth=4 softtabstop=4 expandtab
set autoindent

set ignorecase smartcase
set incsearch hlsearch

Test it: open a file, type /foo and see matches highlight as you type; /Foo matches only capitalized text.

Stage 3: leader mappings

VIM
let mapleader = " "
let maplocalleader = ","

nnoremap <leader>w :write<CR>
nnoremap <leader>q :quit<CR>
nnoremap <silent> <leader>h :nohlsearch<CR>
nnoremap <leader>ev :edit $MYVIMRC<CR>
nnoremap <leader>sv :source $MYVIMRC<CR>

nnoremap j gj
nnoremap k gk
nnoremap Y y$

nnoremap <C-h> <C-w>h
nnoremap <C-j> <C-w>j
nnoremap <C-k> <C-w>k
nnoremap <C-l> <C-w>l

xnoremap < <gv
xnoremap > >gv
nnoremap <leader>b :ls<CR>:b<Space>

Every mapping is non-recursive, <leader> is set before use, and each one solves a real irritation. If a key does nothing, run :verbose nmap <leader>w to find a conflict.

Stage 4: autocommands in one group

VIM
augroup my_config
  autocmd!
  autocmd BufWritePre * :%s/\s\+$//e
  autocmd FileType yaml,json,lua setlocal shiftwidth=2 softtabstop=2
  autocmd BufReadPost *
        \ if line("'\"") > 1 && line("'\"") <= line("$") |
        \   exe "normal! g`\"" |
        \ endif
augroup END

The third rule restores the cursor to where you last left a file (the mark "). Note the single group with autocmd! at the top. Trimming whitespace on every file type is deliberate here; restrict the pattern (*.py) if you edit files where trailing spaces matter, such as Markdown line breaks.

Stage 5: statusline

VIM
set laststatus=2
set statusline=%f\ %m%r%=%y\ %l:%c\ %p%%

That reads: file name, modified and read-only flags, a gap, file type, line:column and percentage. :help statusline lists the codes.

Stage 6: plugins, sparingly

Pick two or three. A reasonable first set is commenting, surrounding and a fuzzy finder. With native packages, no manager is needed:

Terminal
mkdir -p ~/.vim/pack/plugins/start
git clone https://github.com/tpope/vim-commentary ~/.vim/pack/plugins/start/vim-commentary
git clone https://github.com/tpope/vim-surround   ~/.vim/pack/plugins/start/vim-surround

Put packadd! matchit in the vimrc for smarter %. Run :helptags ALL once.

Put the file under version control

Terminal
cd ~
mkdir -p ~/dotfiles && mv ~/.vimrc ~/dotfiles/vimrc
ln -s ~/dotfiles/vimrc ~/.vimrc
cd ~/dotfiles && git init && git add vimrc && git commit -m "Add vimrc"

On a new machine, clone the repository and recreate the link.

Lint your config

Here is a small checker for the mistakes that cause the most trouble. Paste a vimrc into the string and run it. It is a stand-in, not Vim's parser: it only looks at patterns.

JS Stand-in: a vimrc linter

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Stand-in: summarize what your options do

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Your checklist

  • Every line has a reason you can explain.
  • :source $MYVIMRC runs with no errors, twice in a row.
  • vim -u NONE still works, so you can compare behaviour.
  • The file is in Git.
  • You can add or remove a plugin in under a minute.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Why does the project put all autocommands inside one augroup with autocmd! at the top?

    autocmd! clears the group, so sourcing the file again leaves one copy of every rule.
  2. 2. Why use nnoremap rather than nmap for personal shortcuts?

    Recursive mappings expand their right-hand side again.
  3. 3. What is the purpose of keeping the vimrc in Git?

    A plain-text vimrc in version control is portable and has a history.

Summary

  • Build a config in stages, one commented section at a time, testing with :source.
  • Keep mappings non-recursive, autocommands grouped and plugins few.
  • Put the file under version control and keep vim -u NONE as your baseline.

Next: Project: Refactor Text with Macros and :cdo