usr_05 - Vim Documentation

usr_05.txt    For Vim version 9.1.  Last change: 2024 Oct 05

                     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  The defaults.vim file explained
05.4  Simple mappings
05.5  Adding a package
05.6  Adding a plugin
05.7  Adding a help file
05.8  The option window
05.9  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-intro

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:


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-Windows you can use one of these:

        $HOME/_vimrc
        $VIM/_vimrc

If you are creating the vimrc file for the first time, it is recommended to
put this line at the top:


This initializes Vim for new users (as opposed to traditional Vi users). See
defaults.vim for the details.

The vimrc file can contain all the commands that you type after a colon.  The
simplest 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:


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.vim

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.



This loads the "defaults.vim" file in the $VIMRUNTIME directory.  This sets up
Vim for how most users like it.  If you are one of the few that don't, then
comment out this line.  The commands are explained below:
defaults.vim-explained



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

This also sets the 'undofile' option, if available.  This will store the
multi-level undo information in a file.  The result is that when you change a
file, exit Vim, and then edit the file again, you can undo the changes made
previously.  It's a very powerful and useful feature, at the cost of storing a
file.  For more information see undo-persistence.

The "if" command is very useful to set options
only when some condition is met.  More about that in usr_41.txt.



This switches on the 'hlsearch' option, telling Vim to highlight matches with
the last used search pattern.



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.

The wrapper with "augroup vimrcEx" and "augroup END" makes it possible to
delete the autocommand with the "au!" command.  See :augroup.



This loads the "matchit" plugin if the required features are available.
It makes the % command more powerful.  This is explained at
matchit-install.


==============================================================================
05.3  The defaults.vim file explained         defaults.vim-explained

The defaults.vim file is loaded when the user has no vimrc file.  When you
create a new vimrc file, add this line near the top to keep using it:


Or use the vimrc_example.vim file, as explained above.

The following explains what defaults.vim is doing.



Loading defaults.vim can be disabled with this command:
This has to be done in the system vimrc file.  See system-vimrc.  If you
have a user vimrc this is not needed, since defaults.vim will not be loaded
automatically.



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.



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.  See 'backspace'.



Keep 200 commands and 200 search patterns in the history.  Use another number
if you want to remember fewer or more lines.  See 'history'.



Always display the current cursor position in the lower right corner of the
Vim window.  See 'ruler'.



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'




Display completion matches in a status line.  That is when you type <Tab> and
there is more than one match.  See 'wildmenu'.



This makes typing Esc take effect more quickly.  Normally Vim waits a second
to see if the Esc is the start of an escape sequence.  If you have a very slow
remote connection, increase the number.  See 'ttimeout'.



Show @@@ in the last line if it is truncated, instead of hiding the whole
line.  See 'display'.



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



Do not recognize numbers starting with a zero as octal.  See 'nrformats'.



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.



CTRL-U in insert mode deletes all entered text in the current line.  Use
CTRL-G u to first break undo, so that you can undo CTRL-U after inserting a
line break.  Revert with ":iunmap <C-U>".



Enable using the mouse if available.  See 'mouse'.



This mapping yanks the visually selected text and searches for it in C files.
You can see that a mapping can be used to do quite complicated things.  Still,
it is just a sequence of commands that are executed like you typed them.



Enable highlighting files in color.  See syntax.

                                                        vimrc-filetype 

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'.


                                restore-cursor last-position-jump 

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.  It doesn't do that for a commit or rebase message, which are likely
a different one than last time, and when using xxd(1) to filter and edit
binary files, which transforms input files back and forth, causing them to
have dual nature, so to speak.  See also using-xxd.

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.



This adds the ":DiffOrig" command.  Use this in a modified buffer to see the
differences with the file it was loaded from.  See diff and :DiffOrig.



Prevent that the langmap option applies to characters that result from a
mapping.  If set (default), this may break plugins (but it's backward
compatible).  See 'langremap'.

==============================================================================
05.4  Simple mappings

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:


        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:


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.5  Adding a package                        add-package matchit-install

A package is a set of files that you can add to Vim.  There are two kinds of
packages: optional and automatically loaded on startup.

The Vim distribution comes with a few packages that you can optionally use.
For example, the matchit plugin.  This plugin makes the "%" command jump to
matching HTML tags, if/else/endif in Vim scripts, etc.  Very useful, although
it's not backwards compatible (that's why it is not enabled by default).

To start using the matchit plugin, add one line to your vimrc file:

That's all!  After restarting Vim you can find help about this plugin:

This works, because when :packadd loaded the plugin it also added the
package directory in 'runtimepath', so that the help file can be found.

You can find packages on the Internet in various places.  It usually comes as
an archive or as a repository.  For an archive you can follow these steps:
        1. create the package directory:
           "fancy" can be any name of your liking.  Use one that describes the
           package.
        2. unpack the archive in that directory.  This assumes the top
           directory in the archive is "start":
           If the archive layout is different make sure that you end up with a
           path like this:
                ~/.vim/pack/fancy/start/fancytext/plugin/fancy.vim
           Here "fancytext" is the name of the package, it can be anything
           else.

Adding the editorconfig package                         editorconfig-install

Similar to the matchit package, to load the distributed editorconfig plugin
when Vim starts, add the following line to your vimrc file:

After restarting your Vim, the plugin is active and you can read about it at:


Adding comment package                                  comment-install

Load the plugin with this command:

This way you can use the plugin with the default key bindings gc and similar
for commenting (which is a well-established mapping in the Vim community).

If you add this line to your vimrc file, then you need to restart Vim to have
the package loaded.  Once the package is loaded, read about it at:


Adding nohlsearch package                               nohlsearch-install

Load the plugin with this command:

Automatically execute :nohlsearch after 'updatetime' or getting into
Insert mode.
Thus assuming default updatetime, hlsearch would be suspended/turned off after
4 seconds of idle time.

To disable the effect of the plugin after it has been loaded:



More information about packages can be found here: packages.

==============================================================================
05.6  Adding a plugin                                 add-plugin plugin

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-plugin distributed-plugins

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.

For locally installed plugins and packages (which come with a separated help
file) a similar list can be found in the help section local-additions.

Also see load-plugins.

                                                        add-global-plugin
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 are always loaded, you can see them in the directory $VIMRUNTIME/plugin.
- Some come with Vim.  You can find them in the directory $VIMRUNTIME/macros
  and its sub-directories and under $VIM/vimfiles/pack/dist/opt/.
- 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              $HOME/vimfiles/plugin or $VIM/vimfiles/plugin
        Amiga           s:vimfiles/plugin
        Macintosh       $VIM:vimfiles:plugin
        Mac OS X        ~/.vim/plugin/

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


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

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 ftplugins

The Vim distribution comes with a set of plugins for different filetypes that
you can start using with this command:


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-name

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:


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:


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 like filesystems 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:


The generic names for the filetype plugins are:


Here "<name>" can be any name that you prefer.
Examples for the "stuff" filetype on Unix:


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".


Further reading:
filetype-plugins      Documentation for the filetype plugins and information
                        about how to avoid that mappings cause problems.
load-plugins          When the global plugins are loaded during startup.
ftplugin-overrule     Overruling the settings from a global plugin.
write-plugin          How to write a plugin script.
plugin-details        For more information about using plugins or when your
                        plugin doesn't work.
new-filetype          How to detect a new file type.

==============================================================================
05.7  Adding a help file                              add-local-help

If you are lucky, the plugin you installed also comes with a help file.  We
will explain how to install the help file, so that you can easily find help
for your new plugin.
   Let us use the "doit.vim" plugin as an example.  This plugin comes with
documentation: "doit.txt".  Let's first copy the plugin to the right
directory.  This time we will do it from inside Vim.  (You may skip some of
the "mkdir" commands if you already have the directory.)


The "cp" command is for Unix, on MS-Windows you can use "copy".

Now create a "doc" directory in one of the directories in 'runtimepath'.


Copy the help file to the "doc" directory.


Now comes the trick, which allows you to jump to the subjects in the new help
file: Generate the local tags file with the :helptags command.


Now you can use the


command to find help for "doit" in the help file you just added.  You can see
an entry for the local help file when you do:


The title lines from the local help files are automagically added to this
section.  There you can see which local help files have been added and jump to
them through the tag.

For writing a local help file, see write-local-help.

==============================================================================
05.8  The option window

If you are looking for an option that does what you want, you can search in
the help files here: options.  Another way is by using this command:


This opens a new window, with a list of options with a one-line explanation.
The options are grouped by subject.  Move the cursor to a subject and press
<Enter> to jump there.  Press <Enter> again to jump back.  Or use CTRL-O.

You can change the value of an option.  For example, move to the "displaying
text" subject.  Then move the cursor down to this line:

        set wrap        nowrap

When you hit <Enter>, the line will change to:

        set nowrap      wrap

The option has now been switched off.

Just above this line is a short description of the 'wrap' option.  Move the
cursor one line up to place it in this line.  Now hit <Enter> and you jump to
the full help on the 'wrap' option.

For options that take a number or string argument you can edit the value.
Then press <Enter> to apply the new value.  For example, move the cursor a few
lines up to this line:

        set so=0

Position the cursor on the zero with "$".  Change it into a five with "r5".
Then press <Enter> to apply the new value.  When you now move the cursor
around you will notice that the text starts scrolling before you reach the
border.  This is what the 'scrolloff' option does, it specifies an offset
from the window border where scrolling starts.

==============================================================================
05.9  Often used options

There are an awful lot of options.  Most of them you will hardly ever use.
Some of the more useful ones will be mentioned here.  Don't forget you can
find more help on these options with the ":help" command, with single quotes
before and after the option name.  For example:


In case you have messed up an option value, you can set it back to the
default by putting an ampersand (&) after the option name.  Example:



NOT WRAPPING LINES

Vim normally wraps long lines, so that you can see all of the text.  Sometimes
it's better to let the text continue right of the window.  Then you need to
scroll the text left-right to see all of a long line.  Switch wrapping off
with this command:


Vim will automatically scroll the text when you move to text that is not
displayed.  To see a context of ten characters, do this:


This doesn't change the text in the file, only the way it is displayed.


WRAPPING MOVEMENT COMMANDS

Most commands for moving around will stop moving at the start and end of a
line.  You can change that with the 'whichwrap' option.  This sets it to the
default value:


This allows the <BS> key, when used in the first position of a line, to move
the cursor to the end of the previous line.  And the <Space> key moves from
the end of a line to the start of the next one.

To allow the cursor keys <Left> and <Right> to also wrap, use this command:


This is still only for Normal mode.  To let <Left> and <Right> do this in
Insert mode as well:


There are a few other flags that can be added, see 'whichwrap'.


VIEWING TABS

When there are tabs in a file, you cannot see where they are.  To make them
visible:


Now every tab is displayed as ^I.  And a $ is displayed at the end of each
line, so that you can spot trailing spaces that would otherwise go unnoticed.
   A disadvantage is that this looks ugly when there are many Tabs in a file.
If you have a color terminal, or are using the GUI, Vim can show the spaces
and tabs as highlighted characters.  Use the 'listchars' option:


Now every tab will be displayed as ">---" (with more or less "-") and trailing
white space as "-".  Looks a lot better, doesn't it?


KEYWORDS

The 'iskeyword' option specifies which characters can appear in a word:

          iskeyword=@,48-57,_,192-255

The "@" stands for all alphabetic letters.  "48-57" stands for ASCII
characters 48 to 57, which are the numbers 0 to 9.  "192-255" are the
printable latin characters.
   Sometimes you will want to include a dash in keywords, so that commands
like "w" consider "upper-case" to be one word.  You can do it like this:

          iskeyword=@,48-57,_,192-255,-

If you look at the new value, you will see that Vim has added a comma for you.
   To remove a character use "-=".  For example, to remove the underscore:

          iskeyword=@,48-57,192-255,-

This time a comma is automatically deleted.


ROOM FOR MESSAGES

When Vim starts there is one line at the bottom that is used for messages.
When a message is long, it is either truncated, thus you can only see part of
it, or the text scrolls and you have to press <Enter> to continue.
   You can set the 'cmdheight' option to the number of lines used for
messages.  Example:


This does mean there is less room to edit text, thus it's a compromise.

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

Next chapter: usr_06.txt  Using syntax highlighting

Copyright: see manual-copyright  vim:tw=78:ts=8:noet:ft=help:norl: