vimrctips - vim

There seem to be some recurring points whenever a vimrc review thread comes up here on r/vim.

Before submitting your vimrc for review, consider going through the following checklist first:

vimrc checklist:

You don't need set nocompatible

Vim automatically sets nocompatible if it finds a vimrc or gvimrc upon startup. The extra line is superfluous in the usual cases.

But there's another reason it might be dangerous! Setting or resetting the compatible option triggers a lot of other options to be set or reset. You might accidentally be overwriting some pre-vimrc settings by doing set nocompatible, e.g. from a system-wide vimrc or from the --cmd startup option.

Read :help compatible for more details. :help startup will be helpful to track which files get sourced in which order.

Don't use short names

Vim offers short names for most commands and options to help with quickly inputting them within a running Vim instance. After all, typing :set ts=8 noet is a lot faster than typing :set tabstop=8 noexpandtab.

Using the latter is easier to understand and should always be used in scripts, as they will have to be maintained and debugged.

Wrap your autocmds in proper augroups

autocmds provide a nice way to run commands in response to certain events, i.e the following will run :make when a .c file is saved:

autocmd BufWrite *.c make

When you source your vimrc for the second time the auto-commands will be added again, efficiently running :make twice when saving a .c file. A recommended way around this problem is to use augroup to group your auto-commands in a "namespace" and then remove all auto-commands each time the vimrc is sourced:

augroup AutoMake
    autocmd! " Remove all auto-commands from the group "AutoMake"

    autocmd BufWrite *.c make
augroup END

You can also remove the auto-commands manually by running :autocmd! AutoMake.

See :help autocmd-groups, and this thread for more details.

Use noremap, unless you need recursion

When placing maps in your vimrc, strongly consider using the noremap variant instead. This helps guarantee that your maps actually do what you intend, since allowing recursion means some other maps (maybe from plugins) can affect your maps' behavior.

However, one frequent use case for using recursive maps is for working with <Plug> mappings. <Plug> mappings are set up by plugins by mapping them to a command or a function, e.g.

nnoremap <Plug>CallCommand :Command<CR>

which is why you must use recursive maps in order for Vim to use that plugin-defined behavior for your mapping, e.g.

nmap g: <Plug>CallCommand

See :help <Plug> for more details.

Be specific in your mappings

:[nore]map covers normal mode, visual mode, select mode, and operator-pending mode. Do you really want your mapping to work in all those modes? If all you want is a normal mode mapping, make a normal mode mapping: :n[nore]map.

Same story for :v[nore]map, which covers visual mode and select mode. If all you want is a visual mode mapping, use :x[nore]map.

Do not use smartindent

smartindent is an old script that was meant, when it was written, to be a "smart" complement to autoindent. Since then, most languages have either specific indentation functions or use cindent with specific options.

Generally, smartindent should not be used at all.

The following lines are usually enough to deal with indentation:

set autoindent
filetype plugin indent on

autoindent is not strictly necessary but it's good to have it when working with plain text.

Think twice before changing tabstop

See https://www.reddit.com/r/vim/wiki/tabstop.

Allow your functions to abort upon encountering an error

When making a custom function it is worth adding abort to the end of the function declaration, this will allow Vim to abort your function if something were to go wrong, rather than attempting to run the rest of the function.

function! s:ExampleFunction(phrase) abort
    echo a:phrase
endfunction

For more info, read :help :func-abort

Put your highlight commands in an autocmd

Check out this Gist for rationale and more details.

Do not use source

There is a bunch of ways to make vim handle loading external files for you:

• plugin/ directory (:h load-plugins)
• autoload/ directory for functions (:h autoload)
• after/ for ftplugins and stuff that overrides other files
• and if it comes to necessity of loading files outside of paths above then there is :runtime[!] command which sources files in your &runtimepath (:h :runtime)

You possibly wonder why, the reason is that source requires pat to the file that you want to source, but that path is relative to :pwd not to the path of vimrc. Using any of the above methods you just use &runtimepath which is much easier to manage.

vimrc maintenance:

Suggestions on how to maintain and redistribute your vimrc.

Put your vimrc under version control

Nothing is more frustrating than messing up a nice configuration file by (accidentally) adding/deleting something wrong and thus destroying it. Just create a git{hub,lab} / whatever repository to manage your configuration files (btw. this goes for any configuration file you are editing once in a while).

Never put anything you don't understand in your vimrc

Before you put anything into your vimrc, make sure you understand it. You can use the built-in :help to learn about a specific option. See Help With Help for how to navigate the built-in help pages.

Examples of what not to do:

• Adding a plugin because a blogger said to use it (without giving a solid reason why to)
• Copy and pasting from someone else's vimrc or blog because they "recommend" it
• Using someone else's Vim config, (what works for one person will likely not work for you)

Vim supports comments

One can use comments to elaborate on why certain options is set and possible what these are supposed to do. This will help with debugging later.

One can also group similar options together and comment them all at once.

Comments don't work after mappings and shell commands. See :h :comment for more details.