Usr_05

Nvim:help pages,generated fromsource using thetree-sitter-vimdoc parser.

VIM USER MANUALby Bram Moolenaar

Set your settings

Vim can be tuned to work like you want it to. This chapter shows you how tomake Vim start with options set to different values. Add plugins to extendVim's capabilities. Or define your own macros.

05.1 The vimrc file05.2 Example vimrc contents05.3 Simple mappings05.4 Adding a package05.5 Adding a plugin05.6 Adding a help file05.7 The option window05.8 Often used options

Next chapter:usr_06.txt Using syntax highlighting Previous chapter:usr_04.txt Making small changesTable of contents:usr_toc.txt

The vimrc filevimrc-intro

You probably got tired of typing commands that you use very often. To startVim with all your favorite option settings and mappings, you write them inwhat is called the init.vim file. Vim executes the commands in this file whenit starts up.

If you already have a init.vim file (e.g., when your sysadmin has one setupfor you), you can edit it this way:

:edit $MYVIMRC

If you don't have a vimrc file yet, seeinit.vim to find out where you cancreate a vimrc file.

This file is always used and is recommended:

~/.config/nvim/init.vim (Unix and OSX)

~/AppData/Local/nvim/init.vim (Windows)

The vimrc file can contain all the commands that you type after a colon. Thesimplest ones are for setting options. For example, if you want Vim to alwaysstart with the'ignorecase' option on, add this line your vimrc file:

set ignorecase

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 howto write a Vim script file:usr_41.txt.

05.2 Example vimrc contentsvimrc_example.vim

In the first chapter was explained how to create a vimrc file.

:exe 'edit' stdpath('config').'/init.vim'

In this section we will explain the various commands that can be specified inthis 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 outmore.

set backup

This tells Vim to keep a backup copy of a file when overwriting it. The backupfile will have the same name as the original file with "~" added. See07.4

set history=50

Keep 50 commands and 50 search patterns in the history. Use another number ifyou want to remember fewer or more lines.

map Q gq

This defines a key mapping. More about that in the next section. Thisdefines the "Q" command to do formatting with the "gq" operator. Otherwise the"Q" command repeats the last recorded register.

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 doquite complicated things. Still, it is just a sequence of commands that areexecuted like you typed them.

vimrc-filetype

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

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, seewrite-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-cursorlast-position-jump

augroup RestoreCursor  autocmd!  autocmd BufReadPre * autocmd FileType <buffer> ++once    \ let s:line = line("'\"")    \ | if s:line >= 1 && s:line <= line("$") && &filetype !~# 'commit'    \      && index(['xxd', 'gitrebase'], &filetype) == -1    \      && !&diff    \ |   execute "normal! g`\""    \ | endifaugroup END

Another autocommand. This time it is used after reading any file. Thecomplicated stuff after it checks if the '" mark is defined, and jumps to itif so. It doesn't do that when:

editing a commit or rebase message, which are likely a different one than last time,

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 alsousing-xxd) and

Vim is in diff mode

The backslash at the start of a line is used to continue the command from theprevious line. That avoids a line getting very long. Seeline-continuation.This only works in a Vim script file, not when typing commands at thecommand line.

command DiffOrig vert new | set bt=nofile | r ++edit # | 0d_          \ | diffthis | wincmd p | diffthis

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

set nolangremap

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

05.3 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. Inother words, you need to change a word such as "amount" into "{amount}". Withthe :map command, you can tell Vim that the F5 key does this job. The commandis as follows:

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

Note:When entering this command, you must enter<F5> by typing fourcharacters. Similarly,<Esc> is not entered by pressing the<Esc>key, but by typing five characters. Watch out for this differencewhen reading the manual!

Let's break this down:<F5>The F5 function key. This is the trigger key that causes thecommand to be executed as the key is pressed.

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

eMove 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 aword 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 whenyou 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 youprobably want to define more than one mapping, add another character. Youcould 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 theybelong together.

The ":map" command (with no arguments) lists your current mappings. Atleast the ones for Normal mode. More about mappings in section40.1.

05.4 Adding a packageadd-package

You may use:packadd to enable packages on demand. This is useful for pluginsyou want to enable only sometimes. To enableexample_package, use thefollowing command:

packadd example_package

That's all! Now you can find help about this plugin:

:help example_package

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

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

You can find packages on the Internet in various places. It usually comes asan archive or as a repository. For an archive you can follow these steps:1. create the package directory:

mkdir -p ~/.local/share/nvim/site/pack/fancy

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

cd ~/.local/share/nvim/site/pack/fancyunzip /tmp/fancy.zip

If the archive layout is different make sure that you end up with a path like this:

~/.local/share/nvim/site/pack/fancy/start/fancytext/plugin/fancy.vim

Here "fancytext" is the name of the package, it can be anything else.

Adding nohlsearch packagenohlsearch-installpackage-nohlsearch

Load the plugin with this command:

packadd nohlsearch

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

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

au! nohlsearch

More information about packages can be found here:packages.

05.5 Adding a pluginadd-pluginplugin

Vim's functionality can be extended by adding plugins. A plugin is nothingmore than a Vim script file that is loaded automatically when Vim starts. Youcan add a plugin very easily by dropping it in your plugin directory.

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 onesadd-filetype-plugin.

GLOBAL PLUGINSstandard-plugin

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 mostpeople will want to use, but which was implemented as a Vim script instead ofbeing compiled into Vim. You can find them listed in the help indexstandard-plugin-list. Also seeload-plugins.

add-global-plugin
You can add a global plugin to add functionality that will always be presentwhen 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/scripts and its sub-directories and under $VIM/vimfiles/pack/dist/opt/.

Download from the net. There is a large collection onhttps://www.vim.org.

They are sometimes posted in a Vim maillist.

You could write one yourself, seewrite-plugin.

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:

systemplugin directory

Unix~/.local/share/nvim/site/plugin

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

mkdir -p ~/.local/share/nvim/site/plugincp /tmp/yourplugin.vim ~/.local/share/nvim/site/plugin

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

Instead of putting plugins directly into the plugin/ directory, you maybetter organize them by putting them into subdirectories under plugin/.As an example, consider using "~/.local/share/nvim/site/plugin/perl/*.vim" forall your Perl plugins.

FILETYPE PLUGINSadd-filetype-pluginftplugins

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

:filetype plugin on

That's all! Seevimrc-filetype.

If you are missing a plugin for a filetype you are using, or you found abetter 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 thetype of file is mentioned, then you know if the plugin is a global or afiletype one. The scripts in $VIMRUNTIME/scripts are global ones, thefiletype plugins are in $VIMRUNTIME/ftplugin.

USING A FILETYPE PLUGINftplugin-name

You can add a filetype plugin by dropping it in the right directory. Thename of this directory is in the same directory mentioned above for globalplugins, but the last part is "ftplugin". Suppose you have found a plugin forthe "stuff" filetype, and you are on Unix. Then you can move this file to theftplugin directory:

mkdir -p ~/.local/share/nvim/site/ftpluginmv thefile ~/.local/share/nvim/site/ftplugin/stuff.vim

If that file already exists you already have a plugin for "stuff". You mightwant to check if the existing plugin doesn't conflict with the one you areadding. If it's OK, you can give the new one another name:

mv thefile ~/.local/share/nvim/site/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 wouldbe loaded for the "otherstuff" filetype.

The generic names for the filetype plugins are:

ftplugin/<filetype>.vimftplugin/<filetype>_<name>.vimftplugin/<filetype>/<name>.vim

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

~/.local/share/nvim/site/ftplugin/stuff.vim~/.local/share/nvim/site/ftplugin/stuff_def.vim~/.local/share/nvim/site/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 pluginsfor the same filetype. Note that it must end in ".vim" or ".lua".

Further reading:filetype-plugins Documentation for the filetype plugins and informationabout 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 yourplugin doesn't work.new-filetype How to detect a new file type.

05.6 Adding a help fileadd-local-help

If you are lucky, the plugin you installed also comes with a help file. Wewill explain how to install the help file, so that you can easily find helpfor your new plugin.

Let us suppose a plugin ("my-plugin"), which comes with a help file in anon-standard place (it usually resides in a sub-folder calleddoc/).

First, create a "doc" directory in one of the directories in'runtimepath':

:!mkdir -p ~/.local/share/nvim/site/doc

Now, copy the help file to the "doc" directory:

:!cp my-plugin/my-plugin-doc.txt ~/.local/share/nvim/site/doc

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

:helptags ~/.local/share/nvim/site/doc

You can see an entry for the local help file when you do:

:help local-additions

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

For writing a local help file, seewrite-local-help.

05.7 The option window

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

:options

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 useCTRL-O.

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

set wrapnowrap

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

set nowrapwrap

The option has now been switched off.

Just above this line is a short description of the'wrap' option. Move thecursor one line up to place it in this line. Now hit<Enter> and you jump tothe 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 fewlines 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 cursoraround you will notice that the text starts scrolling before you reach theborder. This is what the'scrolloff' option does, it specifies an offsetfrom the window border where scrolling starts.

05.8 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 canfind more help on these options with the ":help" command, with single quotesbefore and after the option name. For example:

:help 'wrap'

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

:set iskeyword&

NOT WRAPPING LINES

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

:set nowrap

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

:set sidescroll=10

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 aline. You can change that with the'whichwrap' option. This sets it to thedefault value:

:set whichwrap=b,s

This allows the<BS> key, when used in the first position of a line, to movethe cursor to the end of the previous line. And the<Space> key moves fromthe 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:

:set whichwrap=b,s,<,>

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

:set whichwrap=b,s,<,>,[,]

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 themvisible:

:set list

Now every tab is displayed as ^I. And a $ is displayed at the end of eachline, 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 spacesand tabs as highlighted characters. Use the'listchars' option:

:set listchars=tab:>-,trail:-

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

KEYWORDS

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

:set iskeyword

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

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

:set iskeyword+=-:set iskeyword

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:

:set iskeyword-=_:set iskeyword

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 ofit, or the text scrolls and you have to press<Enter> to continue. You can set the'cmdheight' option to the number of lines used formessages. Example: