romainl's vim tute - 00 - intro

gistfile1.md

TODO: Possible Title Ideas

• The Patient Vimmer
• Vim from the Bottom Up
• The Competent Vimmer
• Versed in Vim
• Cultivating Vimmers
• Grooming Vimmers
• The Vim of Editing
• Vim is Beautiful -- Editing as if People Mattered
• Becoming a Craftsman with Vim
• Vim in the hands of a Craftsman
• Handy with Vim
• The Handy Vimmer

TODO: A poem for your consideration:

Master Bram, tell us, man,
How does a Vimmer grow?
With solid roots, and crafted tutes
From people in the know.

00 - Introduction

The first contact with Vim is always frustrating: the incapacity to type some text right away, the non-obvious commands for writing and quitting…

Most of us bail out and learn to mentally replace vim with nano in every tutorial they read.

Others learn the bare minimum to make those occasional edits as painless as possible, knowing that there are vastly better editors for serious work anyway.

The rest are lucky enough to see the potential behind the weirdness and decide to do what it takes to become more efficient with Vim.

This tutorial is directed toward that third group of people. Picking up where vimtutor left off, it will hopefully give your Vim experience the right kind of foundations: deep and dependable.

Vim does a lot and thus requires quite a bit of learning as well as a significant amount of will and patience. In that respect, it is not worse than Photoshop, any serious 3D modeling software, font editor or digital audio workstation: you can learn quickly the basics needed for performing simple tasks but you can not honestly put "ProTools" on your resumé after watching a bunch of tutorials on YouTube.

But what kind of involvement are we talking about? Is it the kind that requires us to commit all of [that meaningless garbage](viemu cheatsheet) to memory?

No. I don't believe "knowing all of Vim" or "being a Vim guru" should be anyone's goal. These are consequences of using Vim daily for 10 or 20 years, maybe, but the real goal is much less visible; much less quantifiable: we should learn Vim because it helps us be better at what we do, not because we want to reach a grand goal.

Learning Vim is a long journey where the destination doesn't really matter. What happens along the way and the positive changes it causes in us is all that counts.

You are playing in your own Tolkien trilogy, goddammit!

Before we begin

The default Vim on your system — if you have one — is usually a very small build that lacks a lot of features useful for serious usage. While there is no problem with that, those missing features are really a PITA if you intend to use Vim seriously, as your main text editor.

It is therefore recommended to upgrade your default Vim to a more up-to-date and full-featured build. How to do that, depends on your platform.

On Linux

On Linux, the trick is generally to install the "gvim" — or similar — package, which generally comes with the vim command.

You may need slightly different packages depending on your Desktop Environment or even distribution variant. There are too many for me to check all of them so… use your package manager and common-sense to decide what to install.

Arch

$ sudo pacman -Sy
$ sudo pacman -R vim
$ sudo pacman -S gvim

Debian

$ sudo apt-get update
$ sudo apt-get install vim-gnome

Gentoo

$ sudo emerge --sync
$ sudo emerge app-editors/gvim

RedHat

$ sudo yum check-update
$ sudo yum install vim-enhanced

Slackware

$ sudo slackpkg update
$ sudo slackpkg install-new vim-gvim

On Mac OS X

MacVim is the most complete Vim you can get on Mac OS X and comes with both a GUI version and a CLI version.

Regular install

1. Download and install an official snapshot like you would with any other application.

2. Place the mvim script that is bundled with MacVim somewhere in your $PATH.

You can now use MacVim's CLI executable from your shell with $ mvim -v or the GUI with $ mvim.

Package manager

• MacPorts:

    $ sudo port selfupdate
    $ sudo port install macvim
  

• Homebrew:

    $ brew install macvim
  

On Windows

Vim is not installed on Windows by default so you are forced to install it. The default download from vim.org is OK but slightly outdated. You can get up-to-date builds from these two projects:

• Cream

• Tuxproject

The mother of all commands

Every complex piece of software comes with extensive documentation and Vim is no stranger to that rule. Learning how to use that documentation is more important than learning how to edit "at the speed of thought" or making your editor look like a Christmas tree in Las Vegas.

Learning how to use the documentation makes you self-reliant. With self-reliance comes confidence and with confidence comes efficiency.

So, without further ado, let me introduce you to Vim's amazing…

:help

Now take a moment to read the first paragraph: it's short, factual and chock-full of important info.

You are now capable of searching Vim's documentation for anything and ready to explore a few interesting areas. Again, the focus of this tutorial is not on rote learning. Skim these sections, get a feel for how they are organized, the vocabulary, the extent of Vim's features… but don't learn everything; there's absolutely no point doing that.

• Keys

    :help key-notation
  

• Normal mode commands

    :help normal-index
  

• Visual mode commands

    :help visual-index
  

• Insert mode commands

    :help insert-index
  

• Ex commands

    :help ex-cmd-index
  

• Various points of interest

    :help navigation
  

TODO (others)

• Quick Reference

    :help quickref
  

Making Vim more friendly

As is, even a "huge" build with plenty of developer-friendly features is still the frustrating alien editor that newcomers fear.

What happens, here, is that Vim is just being humble and professional. Its role is to act as a stand-in for old vi and it tries its best to look and behave like vi to the point of being as obnoxious as the original.

Or more if we consider all the features hidden behind that impenetrable vi persona.

Making Vim a little bit more comfortable is a quick and easy exercise that will give us many opportunities to learn useful things: let's do it step by step, one problem at a time…

Problem #0 — Vi compatibility

The closest we have from a definitive list of vi-compatible behaviours can be found at :help 'cpoptions'. A quick glance at that table should be enough to understand the importance of dropping vi-compatibility for regular use.

'compatible' being enabled by default, Vim always starts in what is called "compatible mode" and never comes back to its senses unless instructed to do so. There are two ways to disable "compatible mode":

1. The first way consists of typing this command:

    :set nocompatible
   

   every time we start Vim to set 'cpoptions and many other options to their "Vim" value.

2. The second way consists of creating our very own vimrc.

   As soon as Vim's configuration file is found, 'compatible' is disabled — just as if you typed :set nocompatible — but without having to type anything.

TODO: Consider removing this sentence.

The very existence of that file makes set nocompatible totally useless and redundant so… don't put that at the top of your vimrc like many samples and blog posts tell you to do.

In short, creating an empty vimrc serves two purposes:

• forces Vim to start in nocompatible "mode",
• gives us a place to put all our future settings and mappings.

Solution

UNIX                  Windows

$ cd                  C:cd %userprofile%
$ touch .vimrc        C:echo.>_vimrc

Reference

:help 'compatible'
:help 'cpoptions'
:help startup
:help vimrc-intro

Problem #1 — Backspace

Sadly, 'nocompatible' didn't fix everything.

As you probably noticed, the backspace key doesn't work as expected but we are lucky: :help 'backspace' shows us how to right this wrong.

Solution

Add this line to your newly created vimrc:

set backspace=indent,eol,start

write the file to disk:

:write

and source it with:

:source %

When used as an argument for an Ex command, % is replaced before execution by the current file name, so :source % is exactly the same as :source ~/.vimrc, except a lot shorter and generic. That will certainly come in handy later!

Reference

:help 'backspace'
:help :write
:help :source
:help c_%

Problem #2 — Automatic indentation

Next comes automatic indentation. This one is more of a comfort thing but how are we supposed to be efficient at text editing if we are forced to adjust the indent of every new line manually?

It turns out Vim has got a bunch of automatic indentation mechanisms, none of which are enabled by default. The most basic, 'autoindent', doesn't try to be smart or do different things for different filetypes… That is all we need for now.

Solution

Add this line to your vimrc:

set autoindent

write the file to disk:

:w

and source it with:

:so %

Most Ex commands and options can be shortened to a couple of letters — which undoubtedly make things easier to type — but it is recommended to always use their long form in configuration files and scripts. The short form is hard to read and is not "faster" than the long form so don't use it; your future self will thank you.

On the command-line, however, short commands and options are a must!

Reference

:help 'autoindent'

Problem #3 — Dealing with multiple files

Vim will refuse to edit another file when there are unsaved changes in the current buffer and leaves us with a Cornelian dilemma: write that buffer or abandon our changes.

Thanks for watching our back, Vim, but that feature can really slow us down.

Luckily, we have a 'hidden' option for that (pun intended).

Solution

Add this line to your vimrc:

set hidden

and do the :write/:source dance again, but in one go:

:w|so %

In Vim's command-line, the vertical bar allows us to chain Ex commands but it is not the equivalent of a "UNIX" pipe at all as no data is sent from one command to the next. It is equivalent to the semi-colon ; in C.

Reference

:help 'hidden'
:help :bar

Problem #4 — Syntax highlighting

Syntax highlighting is a staple of programming. It helps readability, eye-comfort, bug-fixing… and it is pretty. Well, it can be pretty.

Vim does syntax highlighting, of course, but the feature is not enabled by default. Thankfully, it is easy to turn it on.

Solution

Add this line to your vimrc:

syntax on

and… type :<Up> to recall the last Ex command. Vim remembers 20 commands by default, helping us save a lot of typing!

Reference

:help :syntax-on
:help history

Problem #5 — Line numbers

Well, I don't like line numbers but people are attached to them and it is very easy to enable them.

Solution

Add this line to your vimrc:

set number

Reference

:help 'number'

Problem #6 — Huge tabs

Vim follows the de-facto standard of 8 spaces but we, programmers, need our 4 or 2 spaces-wide tabs, don't we? :help 'tabstop' does a good job of explaining what strategy to adopt when dealing with tab-width.

Solution

Add these lines to your vimrc, using the value you want:

set shiftwidth=4
set softtabstop=4

and, if you need spaces instead of tabs:

set expandtab

Reference

:help 'tabstop'
:help 'shiftwidth'
:help 'softtabstop'
:help 'expandtab'

That's it

Our short vimrc already gives us most of the comfort we sorely missed the many times we had to use vim to edit various configuration files in the past.

That basic configuration has taught us quite a lot of useful things:

TODO: consider cutting the repeated "we learned" from the points below.

• we learned how to use Vim's online documentation,
• we learned how to recall command history,
• we learned how to chain commands together,
• we learned how to reference the current file on the command-line,
• we learned that we can shorten commands and options…

I would say we've done well here.