Razzi's guide to vim


Vim is a great terminal text editor.

Much ink has been spilled about how to be productive in vim. I recommend reading https://pragprog.com/titles/dnvim2/practical-vim-second-edition/

Vim configuration can be endless, but to start somewhere, I’ll cover how I track my vim configuration in git, and how I track plugins using my vimrc and built-in plugin management.

configuring vim

Run vim --version, and you’ll see, after all the vim features, the many vimrc files:

$ vim --version
VIM - Vi IMproved 9.0 (2022 Jun 28, compiled Dec 04 2023 12:42:16)
Included patches: 1-1672, 1729, 1747, 2107, 1840, 1846-1848, 1857-1858, 1873, 1969, 1992, 2010, 2068, 2106, 2108-2112, 2121
Modified by team+vim@tracker.debian.org
Compiled by team+vim@tracker.debian.org
Huge version without GUI.  Features included (+) or not (-):
+acl               +file_in_path      +mouse_urxvt       -tag_any_white
+extra_search      +mouse_sgr         +tag_binary
-farsi             -mouse_sysmouse    -tag_old_static
   system vimrc file: "/etc/vim/vimrc"
     user vimrc file: "$HOME/.vimrc"
 2nd user vimrc file: "~/.vim/vimrc"
      user exrc file: "$HOME/.exrc"
       defaults file: "$VIMRUNTIME/defaults.vim"
  fall-back for $VIM: "/usr/share/vim"

I recommend using ~/.vim/vimrc, so that you can make the whole .vim directory a git repository.

$ mkdir ~/.vim
$ cd ~/.vim
.vim $ echo '# vim config' > README.md
.vim $ git init
.vim $ git add .
.vim $ git commit -m 'Initial commit'

# and you're all set to start configuring vim!

.vim $ vim vimrc

vim plugin management

Perhaps you’ll be a stoic vim user with a minimal vimrc. I do recommend learning how to do most things in vim without plugins; especially since I use vim on remote machines which don’t have my config, it’s useful to know how vim works out-of-the-box. And it is already quite powerful! But if you’re like me, eventually you’ll start adding plugins to your vim config.

To manage plugins, I tried several solutions, and Plug is in fact quite nice, but I ended up creating my own solution for 3 reasons:

Luckily there is a solid alternative! Since vim version 8 (released in 2016), vim has built-in package management.

You can read about it with :help package but I’ll give you my guide here.

vim built-in package management

There are 2 places you can put plugins:

For a while I was just putting packages directly in /start/ as follows:

$ git clone https://github.com/DataWraith/auto_mkdir ~/.vim/pack/vendor/start/auto_mkdir

This will work in that it will load the package. However this has a couple downsides:

Using /opt/, it doesn’t load a package until you call packadd <package> in your vimrc, so it takes care of the second concern. I used this for a bit, manually cloning repositories whenever I needed to set up a new development environment, but I wanted to track the url of the plugins as well, without submodules. So I added pack/ to my .gitignore, and wrote the following package loading code:

function! EnsurePackage(url)
  let name = split(a:url, '/')[-1]
  let target = $HOME . '/.vim/pack/vendor/opt/' . name

  if !isdirectory(target)
    silent execute '!git clone ' . a:url . ' ' . target

  execute 'packadd! ' . name

command! -nargs=1 Package :call EnsurePackage(<q-args>)

which I can use it as follows:

Package https://github.com/bkad/CamelCaseMotion

And it will clone the plugin repository if it does not exist, and enable it.

Long story short, if you want to manage plugins like me, put the function! EnsurePackage and command! -nargs=1 Package lines verbatim in your vimrc (making them their own package would have the bootstrapping problem) then add Package commands anywhere after that.

You can then configure your packages right there next to these Package calls.

Package https://github.com/tpope/vim-surround
vmap s S

This guide is a work in progress; eventually I’d like to cover tips and tricks and the plugins I use; for now, feel free to browse my personal configuration.

my vim configuration


vim source code