Editing your .vimrc file

Vim’s core configuration file can be found at ~/.vimrc Without it you’ll have the default configuration: no syntax highlighting, no line numbers, etc.. ~/.vimrc is where you put all your global stuff, like turning on syntax highlighting by default.

Editing your ~/.vimrc is something you shouldn’t fear. It’s actually pretty difficult to screw up your Vim configuration so badly that it’s unusable, and in a worst-case-scenario you can always tell vim to ignore it upon launch by saying vim -u NONE and then remove whatever you borked.

~/.vimrc is written in vimscript, but there are only two things you really need to know about it.

comments begin with a double quote character " and continue to the end of the line.
most all of the lines are things you can type into Vim’s command line at any time to modify your current window.

The .vim Directory

Vim stores plugins and filetype specific configurations, custom syntax highlighting files, and stuff like that in a variety of places under your ~/.vim directory. Mostly though, you can just ignore it.

Don’t hesitate!

Vim is much more Legos™ than Star Wars™ Play Set. It wants you to customize it to be perfect for you. When we’re done you’re going to have a number of customizations in there to make this your Vim, and ~/.vimrc is where you’ll be making those customizations.

Reloading after change

Once you’ve modified your ~/.vimrc (for any reason) you need to tell vim to use the changes. Run :source %. % is an abbreviated way of specifying the path to the current file. So, you’re telling Vim to “source” the changes in the current file.

Unfortunately, this doesn’t affect all running instances of Vim, and in GUI clients like MacVim it only affects the current tab. So, as a rule of thumb, you’ll want to restart after any configuration tweaks.

Vim may give you warnings like this when you reload your ~/.vimrc E122: Function Foo already exists, add ! to replace it Unless you’ve actually edited the specified function you can ignore these.

Note: the source command is running Vimscript commands to a vim that’s already running. It is not reloading the world from scratch. So, if you added a line that enabled something, then decided you didn’t like the result and deleted it. Reloading the file won’t make it go away. You have to either turn it off with another command or restart Vim.

When all else fails

I’ve never had things actually get this bad, but in theory you could have some horrible combination of functions and plugins and dark magic defined in your .vimrc that make your Vim completely unusable. If that happens you can launch vim with vim -u NONE and no configuration files will be loaded.

Advanced Geekery

Vim has a pretty cool feature that you don’t hear about much. It supports per-project .vimrc files. All you have to do is add this to your primary ~/.vimrc file.

set exrc " Enable use of directory-specific .vimrc

I’ve only played around with this a little so far, but here’s the advice I can impart.

Your ~/.vimrc file is always going to be read first.
Because of 1, your ~/.vimrc file should only contain the bare minimum configuration that you absolutely want everywhere.
Leave the plugins out of your ~/.vimrc and just specify them in the project. It’s not clear how each plugin manager will handle this functionality, so better to just avoid the problem entirely.
Plugin managers like vim-plug allow you to specify where plugins are stored. When using this I like to specify a per-project plugin folder. I’ll usually go with ~/.vim/plugged-<project> instead of storing them in the project itself.