Surviving Your First Week

Vimtutor

We recommend beginning your Vim adventure with the vimtutor. vimtutor will be installed along with Vim so you should be able to start it by simply running the following in your shell.

$ vimtutor

Vimtutor will open a sample document with exercises inline for your to learn and practice your first Vim actions. One of the best parts of vimtutor is that no prior knowledge of Vim is needed, you can simply start it up and get learning.

Have a Cheatsheet

Rather than trying to memorize everything, we recommend having a cheat sheet that you can reference as you learn Vim.

We've provided an initial cheat sheet to get you started below. We recommend printing it out and keeping it by your computer as you work. Cross off commands as they become muscle memory and you no longer need the reminder, and add to this list as you move on to new Vim commands and mappings.

Mapping	Summary
<esc>	Exit out of any mode back into normal mode
:q or :quit	Quit out of Vim
:w or :write	Write the current file
j, k	Move the cursor down / up
h, l	Move the cursor left / right
i	Go into "insert mode" to enter text
x	Delete the character under the cursor

As a rough guideline, try to keep around 7 items on the list in order to keep it manageable and engaging, and then regularly add new items as old ones become muscle memory and you cross them off.

Stick With It

Vim provides a unique interface and approach to editing text and as such it will be a bit awkward at the very start, but stick with it and push through that discomfort as it will fade quickly. Typically it takes about a week to get back to solid productivity levels, and from there you can continue getting more and more efficient consistently.

As part of this, try to write as much text as possible in Vim. Obviously this includes the code you'll be writing, but also consider editing longer emails or other non-code content in Vim as well.

In addition, you may want to enable other utilities that use Vim-like keyboard shortcuts to further enforce the muscle memory for these mappings, especially for motion. Some examples of programs that use Vim-like keybindings are:

• [Vimium plugin for chrome][]
• [keyboard shortcuts in gmail][]
• [keyboard shortcuts in trello][]

[Vimium plugin for chrome]: https://vimium.github.io/ [keyboard shortcuts in gmail]: https://support.google.com/mail/answer/6594?hl=en [keyboard shortcuts in trello]: https://trello.com/shortcuts

Getting Help

Vim's Builtin Help

Vim has an amazing help system built in, and the best way to get acquainted is by reading the first help page in that system. You can access it by running typing :help and hitting enter in Vim. This initial page contains a summary of how Vim's help docs are laid out, and how to structure searches to find the exact help section you need.

There is a lot of content in the initial :help page so don't worry about remembering all of it, but read through it once to get an idea of what is there and remember to come back to it the next time you are having difficulty finding what you need in the help system.

Another feature of the help system worth knowing about are the tags found throughout Vim's help system. They will be normal words, but will be highlighted distinctly from the surrounding text (in purple in the Video above with Ben's colorscheme). Each of these tags is essentially a link to another part of the help docs, much like a hyperlink on the web. To follow a tag, press <C-]> (hold down control and press the right bracket key).

Vim Wiki

While Vim's built in help help system is great when you know exactly what you want to search for, it is a bit lacking when you want to search for "how to reindent a whole file" or other more general questions. This is where the Vim wiki comes in. [Vim wiki][] is a community resource with an amazing depth of content on how to make even better use of Vim.

Tip - When you find something of interest on the Vim wiki, add it to your cheatsheet to ensure you will remember and learn it.

[Vim wiki]: https://vim.wikia.com/

Vim IRC Channel

If the existing help and Vim wiki resources are not cutting it, another option is to check out the [Vim channel on IRC][]. It is a beginner-friendly channel where you can ask your questions and get help from other Vim users.

[Vim channel on IRC]: http://vim.wikia.com/wiki/Vim_on_Freenode

Vim Category in the Upcase Forum

Lastly, we have a [Vim category in the forum][] where you can post your questions and get answers from your fellow Upcase subscribers and the team here at thoughtbot.

[Vim category in the forum]: https://forum.upcase.com/c/vim

Avoid Too Much Configuration

Vim allows you to configure and extend its behavior almost endlessly, but we recommend spending your first few weeks getting to know Vim's core behavior and key bindings and avoiding any customization or configuration.

There is one small bit of configuration that we do recommend, a plugin called [sensible.vim][]. It contains a base set of configurations that will make your first few weeks more enjoyable. You can use the following snippet to install it and Vim will automatically load it whenever you start Vim.

mkdir -p ~/.vim/plugin
curl https://raw.githubusercontent.com/tpope/vim-sensible/master/plugin/sensible.vim > ~/.vim/plugin/sensible.vim

[sensible.vim]: https://github.com/tpope/vim-sensible