:h usr_05.txt

usr_05.txt For Vim version 7.4. Last change: 2012 Nov 20LINK

VIM USER MANUAL - by Bram Moolenaar

Set your settings

Vim can be tuned to work like you want it to. This chapter shows you how to

make Vim start with options set to different values. Add plugins to extend

Vim's capabilities. Or define your own macros.

05.1 The vimrc file

05.2 The example vimrc file explained

05.3 Simple mappings

05.4 Adding a plugin

05.5 Adding a help file

05.6 The option window

05.7 Often used options

Next chapter: usr_06.txt Using syntax highlighting

Previous chapter: usr_04.txt Making small changes

Table of contents: usr_toc.txt

==============================================================================

05.1 The vimrc file vimrc-introLINK

You probably got tired of typing commands that you use very often. To start

Vim with all your favorite option settings and mappings, you write them in

what is called the vimrc file. Vim executes the commands in this file when it

starts up.

If you already have a vimrc file (e.g., when your sysadmin has one setup for

you), you can edit it this way:

:edit $MYVIMRC

If you don't have a vimrc file yet, see vimrc to find out where you can

create a vimrc file. Also, the ":version" command mentions the name of the

"user vimrc file" Vim looks for.

For Unix and Macintosh this file is always used and is recommended:

~/.vimrc

For MS-DOS and MS-Windows you can use one of these:

$HOME/_vimrc

$VIM/_vimrc

The vimrc file can contain all the commands that you type after a colon. The

most simple ones are for setting options. For example, if you want Vim to

always start with the 'incsearch' option on, add this line your vimrc file:

set incsearch

For this new line to take effect you need to exit Vim and start it again.

Later you will learn how to do this without exiting Vim.

This chapter only explains the most basic items. For more information on how

to write a Vim script file: usr_41.txt.

==============================================================================

05.2 The example vimrc file explained vimrc_example.vimLINK

In the first chapter was explained how the example vimrc (included in the

Vim distribution) file can be used to make Vim startup in not-compatible mode

(see not-compatible). The file can be found here:

$VIMRUNTIME/vimrc_example.vim

In this section we will explain the various commands used in this file. This

will give you hints about how to set up your own preferences. Not everything

will be explained though. Use the ":help" command to find out more.

set nocompatible

As mentioned in the first chapter, these manuals explain Vim working in an

improved way, thus not completely Vi compatible. Setting the 'compatible'

option off, thus 'nocompatible' takes care of this.

set backspace=indent,eol,start

This specifies where in Insert mode the <BS> is allowed to delete the

character in front of the cursor. The three items, separated by commas, tell

Vim to delete the white space at the start of the line, a line break and the

character before where Insert mode started.

set autoindent

This makes Vim use the indent of the previous line for a newly created line.

Thus there is the same amount of white space before the new line. For example

when pressing <Enter> in Insert mode, and when using the "o" command to open a

new line.

if has("vms")

set nobackup

else

set backup

endif

This tells Vim to keep a backup copy of a file when overwriting it. But not

on the VMS system, since it keeps old versions of files already. The backup

file will have the same name as the original file with "~" added. See 07.4

set history=50

Keep 50 commands and 50 search patterns in the history. Use another number if

you want to remember fewer or more lines.

set ruler

Always display the current cursor position in the lower right corner of the

Vim window.

set showcmd

Display an incomplete command in the lower right corner of the Vim window,

left of the ruler. For example, when you type "2f", Vim is waiting for you to

type the character to find and "2f" is displayed. When you press "w" next,

the "2fw" command is executed and the displayed "2f" is removed.

+-------------------------------------------------+

|text in the Vim window |

|~ |

|-- VISUAL -- 2f 43,8 17% |

+-------------------------------------------------+

^^^^^^^^^^^ ^^^^^^^^ ^^^^^^^^^^

'showmode' 'showcmd' 'ruler'

set incsearch

Display the match for a search pattern when halfway typing it.

map Q gq

This defines a key mapping. More about that in the next section. This

defines the "Q" command to do formatting with the "gq" operator. This is how

it worked before Vim 5.0. Otherwise the "Q" command starts Ex mode, but you

will not need it.

vnoremap _g y:exe "grep /" . escape(@", '\\/') . "/ *.c *.h"<CR>

This mapping yanks the visually selected text and searches for it in C files.

This is a complicated mapping. You can see that mappings can be used to do

quite complicated things. Still, it is just a sequence of commands that are

executed like you typed them.

if &t_Co > 2 || has("gui_running")

syntax on

set hlsearch

endif

This switches on syntax highlighting, but only if colors are available. And

the 'hlsearch' option tells Vim to highlight matches with the last used search

pattern. The "if" command is very useful to set options only when some

condition is met. More about that in usr_41.txt.

vimrc-filetype LINK

filetype plugin indent on

This switches on three very clever mechanisms:

1. Filetype detection.

Whenever you start editing a file, Vim will try to figure out what kind of

file this is. When you edit "main.c", Vim will see the ".c" extension and

recognize this as a "c" filetype. When you edit a file that starts with

"#!/bin/sh", Vim will recognize it as a "sh" filetype.

The filetype detection is used for syntax highlighting and the other two

items below.

See filetypes.

2. Using filetype plugin files

Many different filetypes are edited with different options. For example,

when you edit a "c" file, it's very useful to set the 'cindent' option to

automatically indent the lines. These commonly useful option settings are

included with Vim in filetype plugins. You can also add your own, see

write-filetype-plugin.

3. Using indent files

When editing programs, the indent of a line can often be computed

automatically. Vim comes with these indent rules for a number of

filetypes. See :filetype-indent-on and 'indentexpr'.

autocmd FileType text setlocal textwidth=78

This makes Vim break text to avoid lines getting longer than 78 characters.

But only for files that have been detected to be plain text. There are

actually two parts here. "autocmd FileType text" is an autocommand. This

defines that when the file type is set to "text" the following command is

automatically executed. "setlocal textwidth=78" sets the 'textwidth' option

to 78, but only locally in one file.

restore-cursor LINK

autocmd BufReadPost *

\ if line("'\"") > 1 && line("'\"") <= line("$") |

\ exe "normal! g`\"" |

\ endif

Another autocommand. This time it is used after reading any file. The

complicated stuff after it checks if the '" mark is defined, and jumps to it

if so. The backslash at the start of a line is used to continue the command

from the previous line. That avoids a line getting very long.

See line-continuation. This only works in a Vim script file, not when

typing commands at the command-line.

==============================================================================

05.3 Simple mappingsLINK

A mapping enables you to bind a set of Vim commands to a single key. Suppose,

for example, that you need to surround certain words with curly braces. In

other words, you need to change a word such as "amount" into "{amount}". With

the :map command, you can tell Vim that the F5 key does this job. The command

is as follows:

:map <F5> i{<Esc>ea}<Esc>

Note:

When entering this command, you must enter <F5> by typing four

characters. Similarly, <Esc> is not entered by pressing the <Esc>

key, but by typing five characters. Watch out for this difference

when reading the manual!

Let's break this down:

<F5> The F5 function key. This is the trigger key that causes the

command to be executed as the key is pressed.

i{<Esc> Insert the { character. The <Esc> key ends Insert mode.

e Move to the end of the word.

a}<Esc> Append the } to the word.

After you execute the ":map" command, all you have to do to put {} around a

word is to put the cursor on the first character and press F5.

In this example, the trigger is a single key; it can be any string. But when

you use an existing Vim command, that command will no longer be available.

You better avoid that.

One key that can be used with mappings is the backslash. Since you

probably want to define more than one mapping, add another character. You

could map "\p" to add parentheses around a word, and "\c" to add curly braces,

for example:

:map \p i(<Esc>ea)<Esc>

:map \c i{<Esc>ea}<Esc>

You need to type the \ and the p quickly after another, so that Vim knows they

belong together.

The ":map" command (with no arguments) lists your current mappings. At

least the ones for Normal mode. More about mappings in section 40.1.

==============================================================================

05.4 Adding a plugin add-plugin pluginLINK

Vim's functionality can be extended by adding plugins. A plugin is nothing

more than a Vim script file that is loaded automatically when Vim starts. You

can add a plugin very easily by dropping it in your plugin directory.

{not available when Vim was compiled without the +eval feature}

There are two types of plugins:

global plugin: Used for all kinds of files

filetype plugin: Only used for a specific type of file

The global plugins will be discussed first, then the filetype ones

add-filetype-plugin.

GLOBAL PLUGINS standard-pluginLINK

When you start Vim, it will automatically load a number of global plugins.

You don't have to do anything for this. They add functionality that most

people will want to use, but which was implemented as a Vim script instead of

being compiled into Vim. You can find them listed in the help index

standard-plugin-list. Also see load-plugins.

add-global-pluginLINK

You can add a global plugin to add functionality that will always be present

when you use Vim. There are only two steps for adding a global plugin:

1. Get a copy of the plugin.

2. Drop it in the right directory.

GETTING A GLOBAL PLUGIN

Where can you find plugins?

- Some come with Vim. You can find them in the directory $VIMRUNTIME/macros

and its sub-directories.

- Download from the net. There is a large collection on http://www.vim.org.

- They are sometimes posted in a Vim maillist.

- You could write one yourself, see write-plugin.

Some plugins come as a vimball archive, see vimball.

Some plugins can be updated automatically, see getscript.

USING A GLOBAL PLUGIN

First read the text in the plugin itself to check for any special conditions.

Then copy the file to your plugin directory:

system plugin directory

Unix ~/.vim/plugin/

PC and OS/2 $HOME/vimfiles/plugin or $VIM/vimfiles/plugin

Amiga s:vimfiles/plugin

Macintosh $VIM:vimfiles:plugin

Mac OS X ~/.vim/plugin/

RISC-OS Choices:vimfiles.plugin

Example for Unix (assuming you didn't have a plugin directory yet):

mkdir ~/.vim

mkdir ~/.vim/plugin

cp /usr/local/share/vim/vim60/macros/justify.vim ~/.vim/plugin

That's all! Now you can use the commands defined in this plugin to justify

text.

Instead of putting plugins directly into the plugin/ directory, you may

better organize them by putting them into subdirectories under plugin/.

As an example, consider using "~/.vim/plugin/perl/*.vim" for all your Perl

plugins.

FILETYPE PLUGINS add-filetype-plugin ftpluginsLINK

The Vim distribution comes with a set of plugins for different filetypes that

you can start using with this command:

:filetype plugin on

That's all! See vimrc-filetype.

If you are missing a plugin for a filetype you are using, or you found a

better one, you can add it. There are two steps for adding a filetype plugin:

1. Get a copy of the plugin.

2. Drop it in the right directory.

GETTING A FILETYPE PLUGIN

You can find them in the same places as the global plugins. Watch out if the

type of file is mentioned, then you know if the plugin is a global or a

filetype one. The scripts in $VIMRUNTIME/macros are global ones, the filetype

plugins are in $VIMRUNTIME/ftplugin.

USING A FILETYPE PLUGIN ftplugin-nameLINK

You can add a filetype plugin by dropping it in the right directory. The

name of this directory is in the same directory mentioned above for global

plugins, but the last part is "ftplugin". Suppose you have found a plugin for

the "stuff" filetype, and you are on Unix. Then you can move this file to the

ftplugin directory:

mv thefile ~/.vim/ftplugin/stuff.vim

If that file already exists you already have a plugin for "stuff". You might

want to check if the existing plugin doesn't conflict with the one you are

adding. If it's OK, you can give the new one another name:

mv thefile ~/.vim/ftplugin/stuff_too.vim

The underscore is used to separate the name of the filetype from the rest,

which can be anything. If you use "otherstuff.vim" it wouldn't work, it would

be loaded for the "otherstuff" filetype.

On MS-DOS you cannot use long filenames. You would run into trouble if you

add a second plugin and the filetype has more than six characters. You can

use an extra directory to get around this:

mkdir $VIM/vimfiles/ftplugin/fortran

copy thefile $VIM/vimfiles/ftplugin/fortran/too.vim

The generic names for the filetype plugins are:

ftplugin/<filetype>.vim

ftplugin/<filetype>_<name>.vim

ftplugin/<filetype>/<name>.vim

Here "<name>" can be any name that you prefer.

Examples for the "stuff" filetype on Unix:

~/.vim/ftplugin/stuff.vim

~/.vim/ftplugin/stuff_def.vim

~/.vim/ftplugin/stuff/header.vim

The <filetype> part is the name of the filetype the plugin is to be used for.

Only files of this filetype will use the settings from the plugin. The <name>

part of the plugin file doesn't matter, you can use it to have several plugins

for the same filetype. Note that it must end in ".vim".