The Book of Vim

Choosing the right editor is the first
step towards effective editing.

If you don't know which editor to use or are
dissatisfied with what you are currently using,
give Vim a try; **you won't be disappointed**.

  - Bram Moolenaar, 
    High Alchemist of the Dutchy of Lisse,
    Scroll of Seven Habits of Effective Text Editing

Welcome to The Order. You have been selected, hand-picked, because you’ve shown promise in the arcane arts of javascript-mancy, demonstrated sound judgment and an affinity for defeating evil. Yet for all your prowess you are but a baby out of the cradle: ignorant, unknowing, with senses so dull and underdeveloped that you can’t even begin to understand how much lies beyond your understanding and how far you are from achieving your true potential.

We’re the keepers of balance. We keep the world from burning. The discovery of JavaScript-mancy was a magnificent moment that started an Age of Wonders. But it also meant that a small part of the inhabitants of Terra acquired the power to level mountains and split the world apart. We live in the shadows, we counsel, we nudge, we protect and as a last resort we strike with deadly might. That means that we have to be better, wiser, smarter, stronger and faster than other practitioners of the arcane. And that’s why we cultivate The Path. And The Path starts with The Book of Vim.

This is The Book of Vim. A collection of teachings about Vim from our wisest masters of the exoteric. Vim is our text editor because unlike ferals and wild mages, we carefully craft and improve our spells, an even adapt the REPL to our own personal inclinations and strengths. This book will become your closest companion for the next weeks, years and ages to come. Read it, learn it, practice it, until it becomes part of your very being. Then, and only then will you get a glimpse of the possibilities that lie beyond.

Now take the first step and lay the foundation of a new you. An awe-inspiring version, capable of anything you can imagine.

Follow the Path. Protect from the Shadows.

— Randalf Saa’den
Keeper of the Red Flame,
Quartermaster of The Order, 5th Age

What is Vim?

Vi is an ancient text editor, old even before the first age of the world. It was designed to work on contraptions called terminals with the very uncommon yet inspired characteristic of functioning in a modal fashion. Vim has a mode for inserting text, another for editing text, a different one for selecting text, and so on. Quaint isn’t it? Don’t dismiss it though, you’ll soon learn how powerful this concept can be.

Vi’s latest and most celebrated incarnation is Vim (Vi IMproved and formerly Vi IMitation) which works both with text and graphical interfaces, comes with a plethora of improvements over vi and is supported on every platform known to the wizardkin. But the impact of Vim doesn’t stop with Vim, Vim’s ideas are so very remarkable that they’ve trascended the Vim editor itself and propagated into other editors. Today you can find Vim-like modes in almost any editor and IDE that you can imagine.

Why Vim?

Why should you care about learning an ancient editor in this day and age? Aren’t there newer and better alternatives out there? The truth is that Vim provides a different way of interacting with text from anything I’ve ever seen, a way that gives you a completely different level of control and fluency when editing code. At the hands of an experienced user, editing text with Vim seems like magic.

With Vim, the main way in which you interact with your code is not through inserting characters and using the mouse to click, select and move around. Instead you’ll be like a code surgeon that makes expert incisions with surgical precision whenever and wherever it is required, navigating through your code and codebase with the ninja lightning speed and accuracy of a entirely keyboard driven workflow.

Indeed, with Vim the keyboard reigns supreme. Any aspect of the editor can be controlled through the keyboard. Moreover, Vim is designed to provide the touch typist with the highest degree of productivity, with the most common commands comfortably laid out in the home row and its neighbouring keys. Vim is a modal editor with its normal mode at the forefront. A mode devised to read, navigate and transform code at will. The fact that Vim has modes allows keys near the home row to be reused in each separate mode, minimizing the need for slow and contorted key combinations, and heightening your speed and the longevity of your fingers and wrists.

Vim is extremely customizable and you can adapt it to your way of coding and the manner in which you do things. Part of the beauty, and the complexity of learning Vim, is how you can slowly but surely make it work in the way that you work, in your project, alone or with your team.

Using Vim makes writing code even more fun and satisfying. There’s something deeply rewarding - pleasurable even - in the very act of editing text when you’ve achieved a certain level of mastery in Vim that you can’t quite explain until you’ve experienced it for yourself. When you get to that point, the edge between your thoughts and their expression in code nearly disappears, and code becomes as malleable as clay wanting to be shaped into something wonderful.

Finally, even if you don’t jump straight into Vim, even if you don’t intend to have Vim be your main editor, you can reap the rewards of learning Vim by bringing all the commands and motions that you learn here to your favorite editor. That’s it. Vim is so good that most other editors today support some sort of Vim mode which brings a Vim-like experience right into the comfort of your well known editor. Following this approach, you’ll be able to improve your text editing skills while keeping all the time invested, and all the knowledge acquired in your current editor. A great example of this is Visual Studio Code with its VsCodeVim extension which not only supports motions and commands but even custom mappings, ex mode and a lot more.

So Why would you want to learn Vim in this day and age? Paraphrasing the mighty Drew Neil author of Practical Vim and master of the most obscure arts of Vim:

Vim is for programmers who want to raise their game. In the hands of an expert, Vim shreds text at the speed of thought.

Drew Neil - Practical vim

And who wouldn’t want that, right? Are you ready to raise your game? Are you ready to begin your journey along The Path and into text editing awesomeness?

Is this book for you?

This book is for you if you fall in any or several of these categories:

• You’ve been wanting to learn Vim for ages but it is too intimidating
• You’ve tried to learn Vim in the past and given up
• You’ve seen a friend using Vim, been mesmerized by what they can do and would love to be able to do the same but don’t know where to start and the mere idea of getting started feels daunting
• You’re not afraid of getting your hands dirty with lots of practice and exercises
• You enjoy a little bit of fantasy and whimsy
• You feel you’ve hit a ceiling when coding and want to be more productive

This is a complete step by step guide of Vim from beginning to expert, with an intense focus in helping you understand the principles and mental models behind Vim so that you can get up to speed quickly. There’ll be lots of exercises to help you learn faster, build the right habits to practice your Vim skills consistently and, in time, become a very proficient Vim user. And since this is a JavaScript-mancy side quest there’ll be a significant amount of fun references to fantasy.

Why write this book?

I started my career as a software engineer at 26. Up until then I had no idea what I wanted to do with my life but after I discovered the power of programming and how a fulfilling job it was, I immediately understood that I wanted to dedicate my life to becoming a truly awesome software engineer. This is to say that my baseline for programming is “I love this job. I love this thing.” so that you have the right context to understand what I’m going to tell you next. Learning Vim was like falling in love with programming all over again, there’s something really satisfying to programming with Vim that I can’t quite put in words. You have to experience it for yourself.

I write this book because I want people to find out how awesome Vim is and have them enjoy programming as much as I do, have you enjoy programming as much as I do. This book is my love letter to Vim.

What About Neovim?

Over the past couple of years you may have heard people talking about Neovim and wondered… what is that!?

Neovim is a modern fork of Vim that aims to refactor Vim and make it more maintainable, extensible and easier to contribute to by a wider community. It’s main innovation over traditional Vim was that it supported asynchronous processing, an integrated terminal and external plugins. Vim 8 later caught up with support for asynchronous processing and an integrated terminal but Neovim still remains very relevant.

Neovim is still very active, healthy and pushing the boundaries: Its support for external plugins written in JavaScript through node.js is a great boon to create an even more inclusive community of plugin writers. Its headless mode allows GUI applications (like Visual Studio Code or Oni) to consume Vim as a service. Its focus in a great user experience has brought cool new features to Vim like virtual lines with in-editor messages, floating windows and built-in LSP support just as what you have come to expect from modern text editors. Finally, its more sensible defaults make it a more approachable editor than the original Vim.

Finally, the mere existence of Neovim as a competitor to Vim is something healthy for the community as a whole. For instance, features like the integrated terminal, async processing or floating windows were added to Vim after they were available in Neovim.

You can find out more information about Neovim at neovim.io.

A Brief Note About the Conventions Used in This Book

Since a lot of what happens in Vim depends on the location of your cursor, I’ve used a series of diagrams that show the position of the cursor changing over time as you type commands. And since it is quite unconventional from other programming books, I think you’ll find it helpful to have it explained so you’re prepared before you encounter it for the first time. Here’s an example:

wwww ==> v   v v  v   v
         word. is two words

That means the following:

  commands you type    position of the
   /                    /   cursor changing
  /                    /    as you type
wwww ==> v   v v  v   v  
         word. is two words
           /
          /
      text in your editor

So:

• The text word. is two words is the text that is inside your editor which is subject to change or navigation
• You type the command w successively (in this case 4 times)
• Every time you type the command, you move the cursor (represented by v) to a new location

At times, it will be helpful to compare how two commands perform when applied to the same bit of text. In those cases I’ve used the following diagrams:

wwww ==> v   v v  v   v
         word. is two words
         word. is one WORD
WWW  ==> ^     ^  ^   ^

Where the bottom part is similar in meaning to the top part we discussed earlier but for the fact that the cursor is represented by a caret ^ instead of v.

Other times it will be important to convey that some text has been selected (like in Visual mode). In order to that, we’ll use an asterisk * to represent the breadth of the selected text:

  --red: #0F0;
        ******

Since this the online version of the book, and I have all the mighty power of the web platform at the tip of my fingers, that gives me a tiddy bit more freedom to design how you experience this book.

So sometimes I’ll add interactive examples and mini-games with the hope that they’ll improve your learning experience. Experimenting and tinkering with things like this is quite a fun endeavor so you may consider coming back now and then to see if anything has improved. Oh, and please do leave feedback (more on that at the very bottom).

Start

word. is two words

When explaining commands we’ll pay heed to the following conventions. For operations and motions:

f{character}

f            - f is a literal f, expected to 
               be typed as-is.
{character}  - is a placeholder that needs to be
               substituted by something. The name
               between {} will be descriptive of
               what that something is expected to
               be. In this case a character.

When constructing and applying text-objects:

{operator}{a|i}{text-object}

{operator}    - placeholder
{a|i}         - either type the letter a or the letter i
{text-object} - another placeholder

And for ex-commands:

:[range]s/{pattern}/{substitute}/[flags]

:            - denotes the beginning of an ex-command.
[range]      - the [] denote that this part is optional.
               The name will be descriptive as in the 
               case of placeholders.
s            - command to be typed as-is.
{pattern}    - again this is a placeholder.
{substitute} - another placeholder.
[flags]      - another optional part.

Give Feedback

If you find any diagram or explanation confusing, have any questions, want to share your thoughts, or even if you enjoyed the book and just want to say kudos! Don’t hesitate to ask me on twitter at twitter.com/vintharas. My DMs are open and I’ll always be more than happy to answer your questions.