Opt-In, Project-Specific Vim Spell-Checking and Word Completion

Dan Croak

If you and your teammates use Vim, you can use these techniques for avoiding spelling mistakes.


Set up Vim spell-checking and word completion on your machine’s ~/.vimrc:

autocmd BufRead,BufNewFile *.md set filetype=markdown

" Spell-check Markdown files
autocmd FileType markdown setlocal spell

" Spell-check Git messages
autocmd FileType gitcommit setlocal spell

" Set spellfile to location that is guaranteed to exist,
" can be symlinked to Dropbox or kept in Git
" and managed outside of thoughtbot/dotfiles using rcm.
set spellfile=$HOME/.vim-spell-en.utf-8.add

" Autocomplete with dictionary words when spell check is on
set complete+=kspell

thoughtbot shares these settings in our company-wide thoughtbot/dotfiles.


Each member of the team can opt-in to a project-specific .vimrc file by setting the following in their ~/.vimrc file:

set exrc

Then, add the project-specific .vimrc file to the Git repo:

set spelllang=en_us
set spellfile=en.utf-8.add

" Disable unsafe commands.
" http://andrew.stwrt.ca/posts/project-specific-vimrc/
set secure

This is merged with the machine-wide settings.

Alternatively, we could include all necessary options inside the project-specific file to provide coverage for teammates who don’t have machine-wide settings:

set spell
set spelllang=en_us
set spellfile=en.utf-8.add
set complete+=kspell

" Disable unsafe commands.
" http://andrew.stwrt.ca/posts/project-specific-vimrc/
set secure


Edit a project file and Vim will highlight misspelled words.

Move to the next misspelled word with ]s (or move backwards with [s) and type zg (“good word”) to add the word to the custom spell file:

Add a phrase (words with whitespace between them) to the spell file by selecting characters in Visual mode and then typing zg.

Word suggestions

When the cursor is over a misspelled word, get suggestions for the word with z=:

Tab completion

The words in the spell file will show up in tab completion because .vimrc is configured with set complete+=kspell:

Shared spell file

Add the plain-text spell file, en.utf-8.add, to version control in the project.

Vim uses a binary version, en.utf-8.add.spl, as a data structure to improve performance. Ignore the binary version in .gitignore because it will be automatically updated and reloaded when words are added with zg:


The project-specific en.utf-8.add might look something like this:


If you edit the file manually, the binary version will not be updated and reloaded automatically. In that case, run:

:edit <spell file>
(make changes to the spell file)
:mkspell! %


Add a .vimrc and shared spell file to your project to build up a team-wide dictionary of shared terms, help identify and correct misspellings, and tab complete correctly-spelled words.