Basic Vim Configuration

After studying Vim for Beginners, you’ll have seen that the relative line numbering for your files do not survive a reload. Though this behaviour can be defined in the Vim configuration file.

The .vimrc File

All of Vim configuration information is in the .vimrc file found in the home directory. You can open it with the edit file command from inside Vim:

1

:e ~/.vimrc

This file is empty because it has not been used. This tutorial will show you how to use it.

Commenting Code

Before you insert any code, you should document what is done. You might know what you are doing right now, but a month from now is a different matter. Always comment the code so that when you come back to it you’ll be reminded of why you coded something.

For the .vimrc file, anything after a double quote to the end of a line is not used. Therefore, you can put anything there to help you remember what you did.

1

set number  "This turns on line numbering

Now you will always know that the set number command turns on line numbering. 

Options and Variables

To turn on line numbers and relative numbering, you need to put this in to the .vimrc file:

1

set number          "This turns on line numberingset relativenumber  "This turns on relative numbering

Save that and you no longer have to think about it. Every time Vim opens a file, it will now show relative line numbers. The set command sets any option that is in Vim. An option is turned off by setting the opposite option. Opposite options are the same as the option with no in front.

Use the following to turn off line numbering and relative numbering:

1

set nonumber            "This turns off line numberingset norelativenumber    "This turns off relative numbering

Don’t put both sets in to the .vimrc file. That will turn it on and back off. In a little bit, I will show you how to do that more programmatically.

If you already know the state of an option, toggling the option is another way to set the option. Options are toggled by putting a ! after the option name. This toggles on/off the options:

1

set number!             "This toggles the value of numberset relativienumber!    "This toggles relative line numbers

If the current state of an option is needed, use a ? after the option name. In Vim, type:

1

set number?

It will return number. This enables you know the state of the option.

If you want to change the number of columns that the line number area shows, you can set the numberwidth to a value. The following will set the column width to 4:

1

set numberwidth=4       "Set the line numbers to 4 spaces

Try it out and see how many spaces you like and set that in to the .vimrc file.

If you need a variable, variables are created using the let statement. For example:

1

let name = "Richard Guay"   "Set my name in to the name variable

When you save that in the .vimrc file (but use your own name), it can displayed in command mode with :echo name.

Options are treated as a variable by prefixing the option with an &. Options can be printed by:

1

:echo &numberwidth

The echo command is only for variables, but the prefixing an option with an & tells Vim to treat the option as a variable. This enables you to use the option’s value in math. Therefore, to increase the line number area width by one is done by using

1

:let &numberwidth = &numberwidth + 1

An echo &numberwidth should now show 5.

All variables have their scope as well. Scope is defined by a letter, :, and the variable name. Undefined scope is treated as global scope. The different scopes are:

The proper definition for the name variable using global scope is:

1

let g:name = "Richard Guay" "Set my name in to the name variable

Getting Information

Now that you know how to set options and variables, you might wonder how do you find out the different options. Searching the web is one option, but the information is in Vim. Type:

1

:set all

And Vim will show every option in the program. Typing the :let and an enter will show all of the variables.

The :help command is used to lookup the extensive documentation built into Vim. To get out of :help, use :q. In help mode, this does not exit the program, but puts the editor in to normal mode.

Functions

Functions are very useful in the .vimrc file. Since the Vim’s configuration files use a full programing language, I will from here out refer to it’s true name: VimScript.

In VimScript, define a function using:

1

function <function name>()    <function body>endfunc

I love the line numbering and relative numbering, but sometimes you do not want relative numbering. Typing the full string :set norelativenumber or even :set relativenumber! is a lot of typing. A function to turn it on and off would be good.

1

function TRelative()    set relativenumber!endfunc

A function is run with the :call command.

1

:call TRelative()

The function command does not allow you to overwrite an already defined function. If that function was already defined somewhere else or you tried to reload the file again, Vim will error and stop processing the file at that point. If you use the function! command, it will overwrite the function without an error. It is good programming practice in VimScript to mostly use function!.

To turn off all numbering, a function can be created to do that and it’s opposite. Add this to the .vimrc:

1

function! NoNumber()    set nonumber    set norelativenumberendfuncfunction! Numbers()    set number    set relativenumberendfunc

To pass parameters to a function, you place a variable name inside the parenthesis. For example:

1

function! Hi( name )    echo "Hello" a:nameendfunc

As you see, you have to scope variables that are arguments of a function. When you call the function now with a name, you will get

1

:call Hi( "Richard" )Hello Richard

Basic Key Mapping

One of the most important uses for the configuration file is to setup key mappings. For example, you toggle relative numbers on and off a whole lot. Instead of typing :call TRelative all the time, a hotkey is much faster. To do that, the map command will help.

1

map <c-t> :call TRelative()<cr>

With this line in the .vimrc file, you can now type Control-T and the relative numbering will toggle on and off. Try it out by making a mapping for toggling all line numbering.

Key maps are not just for normal mode, but for every mode. If you prefix the command with the first letter of a mode, it will map the key for that mode. nmap also maps for normal mode. vmap maps for visual mode. imap maps for insert mode.

Now that you know these command, forget them. These commands can be dangerous. If you remap a key again, it will use the new mapping and can create an infinite loop in the mappings.

To prevent that happening, you need to add nore after the mode and before the map. Therefore, nmap is nnoremap, vmap is vnoremap, and imap is inoremap. These use the default mapping for any key command you reference in the macro. These are much safer to use in the configuration file.

Conclusion

In this tutorial I have shown you the basics of creating a Vim configuration file. I have shown you how to: comment the configuration file, set/unset options and variables, create basic functions, and mapping keyboard shortcuts. The best way to remember is by practicing.