1*usr_05.txt* For Vim version 7.3. Last change: 2009 Jun 04 2 3 VIM USER MANUAL - by Bram Moolenaar 4 5 Set your settings 6 7 8Vim can be tuned to work like you want it to. This chapter shows you how to 9make Vim start with options set to different values. Add plugins to extend 10Vim's capabilities. Or define your own macros. 11 12|05.1| The vimrc file 13|05.2| The example vimrc file explained 14|05.3| Simple mappings 15|05.4| Adding a plugin 16|05.5| Adding a help file 17|05.6| The option window 18|05.7| Often used options 19 20 Next chapter: |usr_06.txt| Using syntax highlighting 21 Previous chapter: |usr_04.txt| Making small changes 22Table of contents: |usr_toc.txt| 23 24============================================================================== 25*05.1* The vimrc file *vimrc-intro* 26 27You probably got tired of typing commands that you use very often. To start 28Vim with all your favorite option settings and mappings, you write them in 29what is called the vimrc file. Vim executes the commands in this file when it 30starts up. 31 32If you already have a vimrc file (e.g., when your sysadmin has one setup for 33you), you can edit it this way: > 34 35 :edit $MYVIMRC 36 37If you don't have a vimrc file yet, see |vimrc| to find out where you can 38create a vimrc file. Also, the ":version" command mentions the name of the 39"user vimrc file" Vim looks for. 40 41For Unix and Macintosh this file is always used and is recommended: 42 43 ~/.vimrc ~ 44 45For MS-DOS and MS-Windows you can use one of these: 46 47 $HOME/_vimrc ~ 48 $VIM/_vimrc ~ 49 50The vimrc file can contain all the commands that you type after a colon. The 51most simple ones are for setting options. For example, if you want Vim to 52always start with the 'incsearch' option on, add this line you your vimrc 53file: > 54 55 set incsearch 56 57For this new line to take effect you need to exit Vim and start it again. 58Later you will learn how to do this without exiting Vim. 59 60This chapter only explains the most basic items. For more information on how 61to write a Vim script file: |usr_41.txt|. 62 63============================================================================== 64*05.2* The example vimrc file explained *vimrc_example.vim* 65 66In the first chapter was explained how the example vimrc (included in the 67Vim distribution) file can be used to make Vim startup in not-compatible mode 68(see |not-compatible|). The file can be found here: 69 70 $VIMRUNTIME/vimrc_example.vim ~ 71 72In this section we will explain the various commands used in this file. This 73will give you hints about how to set up your own preferences. Not everything 74will be explained though. Use the ":help" command to find out more. 75 76> 77 set nocompatible 78 79As mentioned in the first chapter, these manuals explain Vim working in an 80improved way, thus not completely Vi compatible. Setting the 'compatible' 81option off, thus 'nocompatible' takes care of this. 82 83> 84 set backspace=indent,eol,start 85 86This specifies where in Insert mode the <BS> is allowed to delete the 87character in front of the cursor. The three items, separated by commas, tell 88Vim to delete the white space at the start of the line, a line break and the 89character before where Insert mode started. 90> 91 92 set autoindent 93 94This makes Vim use the indent of the previous line for a newly created line. 95Thus there is the same amount of white space before the new line. For example 96when pressing <Enter> in Insert mode, and when using the "o" command to open a 97new line. 98> 99 100 if has("vms") 101 set nobackup 102 else 103 set backup 104 endif 105 106This tells Vim to keep a backup copy of a file when overwriting it. But not 107on the VMS system, since it keeps old versions of files already. The backup 108file will have the same name as the original file with "~" added. See |07.4| 109> 110 111 set history=50 112 113Keep 50 commands and 50 search patterns in the history. Use another number if 114you want to remember fewer or more lines. 115> 116 117 set ruler 118 119Always display the current cursor position in the lower right corner of the 120Vim window. 121 122> 123 set showcmd 124 125Display an incomplete command in the lower right corner of the Vim window, 126left of the ruler. For example, when you type "2f", Vim is waiting for you to 127type the character to find and "2f" is displayed. When you press "w" next, 128the "2fw" command is executed and the displayed "2f" is removed. 129 130 +-------------------------------------------------+ 131 |text in the Vim window | 132 |~ | 133 |~ | 134 |-- VISUAL -- 2f 43,8 17% | 135 +-------------------------------------------------+ 136 ^^^^^^^^^^^ ^^^^^^^^ ^^^^^^^^^^ 137 'showmode' 'showcmd' 'ruler' 138 139> 140 set incsearch 141 142Display the match for a search pattern when halfway typing it. 143 144> 145 map Q gq 146 147This defines a key mapping. More about that in the next section. This 148defines the "Q" command to do formatting with the "gq" operator. This is how 149it worked before Vim 5.0. Otherwise the "Q" command starts Ex mode, but you 150will not need it. 151 152> 153 vnoremap _g y:exe "grep /" . escape(@", '\\/') . "/ *.c *.h"<CR> 154 155This mapping yanks the visually selected text and searches for it in C files. 156This is a complicated mapping. You can see that mappings can be used to do 157quite complicated things. Still, it is just a sequence of commands that are 158executed like you typed them. 159 160> 161 if &t_Co > 2 || has("gui_running") 162 syntax on 163 set hlsearch 164 endif 165 166This switches on syntax highlighting, but only if colors are available. And 167the 'hlsearch' option tells Vim to highlight matches with the last used search 168pattern. The "if" command is very useful to set options only when some 169condition is met. More about that in |usr_41.txt|. 170 171 *vimrc-filetype* > 172 filetype plugin indent on 173 174This switches on three very clever mechanisms: 1751. Filetype detection. 176 Whenever you start editing a file, Vim will try to figure out what kind of 177 file this is. When you edit "main.c", Vim will see the ".c" extension and 178 recognize this as a "c" filetype. When you edit a file that starts with 179 "#!/bin/sh", Vim will recognize it as a "sh" filetype. 180 The filetype detection is used for syntax highlighting and the other two 181 items below. 182 See |filetypes|. 183 1842. Using filetype plugin files 185 Many different filetypes are edited with different options. For example, 186 when you edit a "c" file, it's very useful to set the 'cindent' option to 187 automatically indent the lines. These commonly useful option settings are 188 included with Vim in filetype plugins. You can also add your own, see 189 |write-filetype-plugin|. 190 1913. Using indent files 192 When editing programs, the indent of a line can often be computed 193 automatically. Vim comes with these indent rules for a number of 194 filetypes. See |:filetype-indent-on| and 'indentexpr'. 195 196> 197 autocmd FileType text setlocal textwidth=78 198 199This makes Vim break text to avoid lines getting longer than 78 characters. 200But only for files that have been detected to be plain text. There are 201actually two parts here. "autocmd FileType text" is an autocommand. This 202defines that when the file type is set to "text" the following command is 203automatically executed. "setlocal textwidth=78" sets the 'textwidth' option 204to 78, but only locally in one file. 205 206 *restore-cursor* > 207 autocmd BufReadPost * 208 \ if line("'\"") > 1 && line("'\"") <= line("$") | 209 \ exe "normal! g`\"" | 210 \ endif 211 212Another autocommand. This time it is used after reading any file. The 213complicated stuff after it checks if the '" mark is defined, and jumps to it 214if so. The backslash at the start of a line is used to continue the command 215from the previous line. That avoids a line getting very long. 216See |line-continuation|. This only works in a Vim script file, not when 217typing commands at the command-line. 218 219============================================================================== 220*05.3* Simple mappings 221 222A mapping enables you to bind a set of Vim commands to a single key. Suppose, 223for example, that you need to surround certain words with curly braces. In 224other words, you need to change a word such as "amount" into "{amount}". With 225the :map command, you can tell Vim that the F5 key does this job. The command 226is as follows: > 227 228 :map <F5> i{<Esc>ea}<Esc> 229< 230 Note: 231 When entering this command, you must enter <F5> by typing four 232 characters. Similarly, <Esc> is not entered by pressing the <Esc> 233 key, but by typing five characters. Watch out for this difference 234 when reading the manual! 235 236Let's break this down: 237 <F5> The F5 function key. This is the trigger key that causes the 238 command to be executed as the key is pressed. 239 240 i{<Esc> Insert the { character. The <Esc> key ends Insert mode. 241 242 e Move to the end of the word. 243 244 a}<Esc> Append the } to the word. 245 246After you execute the ":map" command, all you have to do to put {} around a 247word is to put the cursor on the first character and press F5. 248 249In this example, the trigger is a single key; it can be any string. But when 250you use an existing Vim command, that command will no longer be available. 251You better avoid that. 252 One key that can be used with mappings is the backslash. Since you 253probably want to define more than one mapping, add another character. You 254could map "\p" to add parentheses around a word, and "\c" to add curly braces, 255for example: > 256 257 :map \p i(<Esc>ea)<Esc> 258 :map \c i{<Esc>ea}<Esc> 259 260You need to type the \ and the p quickly after another, so that Vim knows they 261belong together. 262 263The ":map" command (with no arguments) lists your current mappings. At 264least the ones for Normal mode. More about mappings in section |40.1|. 265 266============================================================================== 267*05.4* Adding a plugin *add-plugin* *plugin* 268 269Vim's functionality can be extended by adding plugins. A plugin is nothing 270more than a Vim script file that is loaded automatically when Vim starts. You 271can add a plugin very easily by dropping it in your plugin directory. 272{not available when Vim was compiled without the |+eval| feature} 273 274There are two types of plugins: 275 276 global plugin: Used for all kinds of files 277 filetype plugin: Only used for a specific type of file 278 279The global plugins will be discussed first, then the filetype ones 280|add-filetype-plugin|. 281 282 283GLOBAL PLUGINS *standard-plugin* 284 285When you start Vim, it will automatically load a number of global plugins. 286You don't have to do anything for this. They add functionality that most 287people will want to use, but which was implemented as a Vim script instead of 288being compiled into Vim. You can find them listed in the help index 289|standard-plugin-list|. Also see |load-plugins|. 290 291 *add-global-plugin* 292You can add a global plugin to add functionality that will always be present 293when you use Vim. There are only two steps for adding a global plugin: 2941. Get a copy of the plugin. 2952. Drop it in the right directory. 296 297 298GETTING A GLOBAL PLUGIN 299 300Where can you find plugins? 301- Some come with Vim. You can find them in the directory $VIMRUNTIME/macros 302 and its sub-directories. 303- Download from the net. There is a large collection on http://www.vim.org. 304- They are sometimes posted in a Vim |maillist|. 305- You could write one yourself, see |write-plugin|. 306 307Some plugins come as a vimball archive, see |vimball|. 308Some plugins can be updated automatically, see |getscript|. 309 310 311USING A GLOBAL PLUGIN 312 313First read the text in the plugin itself to check for any special conditions. 314Then copy the file to your plugin directory: 315 316 system plugin directory ~ 317 Unix ~/.vim/plugin/ 318 PC and OS/2 $HOME/vimfiles/plugin or $VIM/vimfiles/plugin 319 Amiga s:vimfiles/plugin 320 Macintosh $VIM:vimfiles:plugin 321 Mac OS X ~/.vim/plugin/ 322 RISC-OS Choices:vimfiles.plugin 323 324Example for Unix (assuming you didn't have a plugin directory yet): > 325 326 mkdir ~/.vim 327 mkdir ~/.vim/plugin 328 cp /usr/local/share/vim/vim60/macros/justify.vim ~/.vim/plugin 329 330That's all! Now you can use the commands defined in this plugin to justify 331text. 332 333Instead of putting plugins directly into the plugin/ directory, you may 334better organize them by putting them into subdirectories under plugin/. 335As an example, consider using "~/.vim/plugin/perl/*.vim" for all your Perl 336plugins. 337 338 339FILETYPE PLUGINS *add-filetype-plugin* *ftplugins* 340 341The Vim distribution comes with a set of plugins for different filetypes that 342you can start using with this command: > 343 344 :filetype plugin on 345 346That's all! See |vimrc-filetype|. 347 348If you are missing a plugin for a filetype you are using, or you found a 349better one, you can add it. There are two steps for adding a filetype plugin: 3501. Get a copy of the plugin. 3512. Drop it in the right directory. 352 353 354GETTING A FILETYPE PLUGIN 355 356You can find them in the same places as the global plugins. Watch out if the 357type of file is mentioned, then you know if the plugin is a global or a 358filetype one. The scripts in $VIMRUNTIME/macros are global ones, the filetype 359plugins are in $VIMRUNTIME/ftplugin. 360 361 362USING A FILETYPE PLUGIN *ftplugin-name* 363 364You can add a filetype plugin by dropping it in the right directory. The 365name of this directory is in the same directory mentioned above for global 366plugins, but the last part is "ftplugin". Suppose you have found a plugin for 367the "stuff" filetype, and you are on Unix. Then you can move this file to the 368ftplugin directory: > 369 370 mv thefile ~/.vim/ftplugin/stuff.vim 371 372If that file already exists you already have a plugin for "stuff". You might 373want to check if the existing plugin doesn't conflict with the one you are 374adding. If it's OK, you can give the new one another name: > 375 376 mv thefile ~/.vim/ftplugin/stuff_too.vim 377 378The underscore is used to separate the name of the filetype from the rest, 379which can be anything. If you use "otherstuff.vim" it wouldn't work, it would 380be loaded for the "otherstuff" filetype. 381 382On MS-DOS you cannot use long filenames. You would run into trouble if you 383add a second plugin and the filetype has more than six characters. You can 384use an extra directory to get around this: > 385 386 mkdir $VIM/vimfiles/ftplugin/fortran 387 copy thefile $VIM/vimfiles/ftplugin/fortran/too.vim 388 389The generic names for the filetype plugins are: > 390 391 ftplugin/<filetype>.vim 392 ftplugin/<filetype>_<name>.vim 393 ftplugin/<filetype>/<name>.vim 394 395Here "<name>" can be any name that you prefer. 396Examples for the "stuff" filetype on Unix: > 397 398 ~/.vim/ftplugin/stuff.vim 399 ~/.vim/ftplugin/stuff_def.vim 400 ~/.vim/ftplugin/stuff/header.vim 401 402The <filetype> part is the name of the filetype the plugin is to be used for. 403Only files of this filetype will use the settings from the plugin. The <name> 404part of the plugin file doesn't matter, you can use it to have several plugins 405for the same filetype. Note that it must end in ".vim". 406 407 408Further reading: 409|filetype-plugins| Documentation for the filetype plugins and information 410 about how to avoid that mappings cause problems. 411|load-plugins| When the global plugins are loaded during startup. 412|ftplugin-overrule| Overruling the settings from a global plugin. 413|write-plugin| How to write a plugin script. 414|plugin-details| For more information about using plugins or when your 415 plugin doesn't work. 416|new-filetype| How to detect a new file type. 417 418============================================================================== 419*05.5* Adding a help file *add-local-help* *matchit-install* 420 421If you are lucky, the plugin you installed also comes with a help file. We 422will explain how to install the help file, so that you can easily find help 423for your new plugin. 424 Let us use the "matchit.vim" plugin as an example (it is included with 425Vim). This plugin makes the "%" command jump to matching HTML tags, 426if/else/endif in Vim scripts, etc. Very useful, although it's not backwards 427compatible (that's why it is not enabled by default). 428 This plugin comes with documentation: "matchit.txt". Let's first copy the 429plugin to the right directory. This time we will do it from inside Vim, so 430that we can use $VIMRUNTIME. (You may skip some of the "mkdir" commands if 431you already have the directory.) > 432 433 :!mkdir ~/.vim 434 :!mkdir ~/.vim/plugin 435 :!cp $VIMRUNTIME/macros/matchit.vim ~/.vim/plugin 436 437The "cp" command is for Unix, on MS-DOS you can use "copy". 438 439Now create a "doc" directory in one of the directories in 'runtimepath'. > 440 441 :!mkdir ~/.vim/doc 442 443Copy the help file to the "doc" directory. > 444 445 :!cp $VIMRUNTIME/macros/matchit.txt ~/.vim/doc 446 447Now comes the trick, which allows you to jump to the subjects in the new help 448file: Generate the local tags file with the |:helptags| command. > 449 450 :helptags ~/.vim/doc 451 452Now you can use the > 453 454 :help g% 455 456command to find help for "g%" in the help file you just added. You can see an 457entry for the local help file when you do: > 458 459 :help local-additions 460 461The title lines from the local help files are automagically added to this 462section. There you can see which local help files have been added and jump to 463them through the tag. 464 465For writing a local help file, see |write-local-help|. 466 467============================================================================== 468*05.6* The option window 469 470If you are looking for an option that does what you want, you can search in 471the help files here: |options|. Another way is by using this command: > 472 473 :options 474 475This opens a new window, with a list of options with a one-line explanation. 476The options are grouped by subject. Move the cursor to a subject and press 477<Enter> to jump there. Press <Enter> again to jump back. Or use CTRL-O. 478 479You can change the value of an option. For example, move to the "displaying 480text" subject. Then move the cursor down to this line: 481 482 set wrap nowrap ~ 483 484When you hit <Enter>, the line will change to: 485 486 set nowrap wrap ~ 487 488The option has now been switched off. 489 490Just above this line is a short description of the 'wrap' option. Move the 491cursor one line up to place it in this line. Now hit <Enter> and you jump to 492the full help on the 'wrap' option. 493 494For options that take a number or string argument you can edit the value. 495Then press <Enter> to apply the new value. For example, move the cursor a few 496lines up to this line: 497 498 set so=0 ~ 499 500Position the cursor on the zero with "$". Change it into a five with "r5". 501Then press <Enter> to apply the new value. When you now move the cursor 502around you will notice that the text starts scrolling before you reach the 503border. This is what the 'scrolloff' option does, it specifies an offset 504from the window border where scrolling starts. 505 506============================================================================== 507*05.7* Often used options 508 509There are an awful lot of options. Most of them you will hardly ever use. 510Some of the more useful ones will be mentioned here. Don't forget you can 511find more help on these options with the ":help" command, with single quotes 512before and after the option name. For example: > 513 514 :help 'wrap' 515 516In case you have messed up an option value, you can set it back to the 517default by putting an ampersand (&) after the option name. Example: > 518 519 :set iskeyword& 520 521 522NOT WRAPPING LINES 523 524Vim normally wraps long lines, so that you can see all of the text. Sometimes 525it's better to let the text continue right of the window. Then you need to 526scroll the text left-right to see all of a long line. Switch wrapping off 527with this command: > 528 529 :set nowrap 530 531Vim will automatically scroll the text when you move to text that is not 532displayed. To see a context of ten characters, do this: > 533 534 :set sidescroll=10 535 536This doesn't change the text in the file, only the way it is displayed. 537 538 539WRAPPING MOVEMENT COMMANDS 540 541Most commands for moving around will stop moving at the start and end of a 542line. You can change that with the 'whichwrap' option. This sets it to the 543default value: > 544 545 :set whichwrap=b,s 546 547This allows the <BS> key, when used in the first position of a line, to move 548the cursor to the end of the previous line. And the <Space> key moves from 549the end of a line to the start of the next one. 550 551To allow the cursor keys <Left> and <Right> to also wrap, use this command: > 552 553 :set whichwrap=b,s,<,> 554 555This is still only for Normal mode. To let <Left> and <Right> do this in 556Insert mode as well: > 557 558 :set whichwrap=b,s,<,>,[,] 559 560There are a few other flags that can be added, see 'whichwrap'. 561 562 563VIEWING TABS 564 565When there are tabs in a file, you cannot see where they are. To make them 566visible: > 567 568 :set list 569 570Now every tab is displayed as ^I. And a $ is displayed at the end of each 571line, so that you can spot trailing spaces that would otherwise go unnoticed. 572 A disadvantage is that this looks ugly when there are many Tabs in a file. 573If you have a color terminal, or are using the GUI, Vim can show the spaces 574and tabs as highlighted characters. Use the 'listchars' option: > 575 576 :set listchars=tab:>-,trail:- 577 578Now every tab will be displayed as ">---" (with more or less "-") and trailing 579white space as "-". Looks a lot better, doesn't it? 580 581 582KEYWORDS 583 584The 'iskeyword' option specifies which characters can appear in a word: > 585 586 :set iskeyword 587< iskeyword=@,48-57,_,192-255 ~ 588 589The "@" stands for all alphabetic letters. "48-57" stands for ASCII 590characters 48 to 57, which are the numbers 0 to 9. "192-255" are the 591printable latin characters. 592 Sometimes you will want to include a dash in keywords, so that commands 593like "w" consider "upper-case" to be one word. You can do it like this: > 594 595 :set iskeyword+=- 596 :set iskeyword 597< iskeyword=@,48-57,_,192-255,- ~ 598 599If you look at the new value, you will see that Vim has added a comma for you. 600 To remove a character use "-=". For example, to remove the underscore: > 601 602 :set iskeyword-=_ 603 :set iskeyword 604< iskeyword=@,48-57,192-255,- ~ 605 606This time a comma is automatically deleted. 607 608 609ROOM FOR MESSAGES 610 611When Vim starts there is one line at the bottom that is used for messages. 612When a message is long, it is either truncated, thus you can only see part of 613it, or the text scrolls and you have to press <Enter> to continue. 614 You can set the 'cmdheight' option to the number of lines used for 615messages. Example: > 616 617 :set cmdheight=3 618 619This does mean there is less room to edit text, thus it's a compromise. 620 621============================================================================== 622 623Next chapter: |usr_06.txt| Using syntax highlighting 624 625Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: 626