1*starting.txt* For Vim version 8.1. Last change: 2018 May 05 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7Starting Vim *starting* 8 91. Vim arguments |vim-arguments| 102. Vim on the Amiga |starting-amiga| 113. Running eVim |evim-keys| 124. Initialization |initialization| 135. $VIM and $VIMRUNTIME |$VIM| 146. Suspending |suspend| 157. Exiting |exiting| 168. Saving settings |save-settings| 179. Views and Sessions |views-sessions| 1810. The viminfo file |viminfo-file| 19 20============================================================================== 211. Vim arguments *vim-arguments* 22 23Most often, Vim is started to edit a single file with the command 24 25 vim filename *-vim* 26 27More generally, Vim is started with: 28 29 vim [option | filename] .. 30 31Option arguments and file name arguments can be mixed, and any number of them 32can be given. However, watch out for options that take an argument. 33 34For compatibility with various Vi versions, see |cmdline-arguments|. 35 36Exactly one out of the following five items may be used to choose how to 37start editing: 38 39 *-file* *---* 40filename One or more file names. The first one will be the current 41 file and read into the buffer. The cursor will be positioned 42 on the first line of the buffer. 43 To avoid a file name starting with a '-' being interpreted as 44 an option, precede the arglist with "--", e.g.: > 45 vim -- -filename 46< All arguments after the "--" will be interpreted as file names, 47 no other options or "+command" argument can follow. 48 For behavior of quotes on MS-Windows, see |win32-quotes|. 49 50 *--* 51- This argument can mean two things, depending on whether Ex 52 mode is to be used. 53 54 Starting in Normal mode: > 55 vim - 56 ex -v - 57< Start editing a new buffer, which is filled with text 58 that is read from stdin. The commands that would normally be 59 read from stdin will now be read from stderr. Example: > 60 find . -name "*.c" -print | vim - 61< The buffer will not be marked as modified, so that it's easy 62 to exit. Be careful to mark it as modified if you don't want 63 to accidentally lose it. Example: > 64 ls | view - 65< 66 Starting in Ex mode: > 67 ex - 68 vim -e - 69 exim - 70 vim -E 71< Start editing in silent mode. See |-s-ex|. 72 73 *-t* *-tag* 74-t {tag} A tag. "tag" is looked up in the tags file, the associated 75 file becomes the current file, and the associated command is 76 executed. Mostly this is used for C programs, in which case 77 "tag" often is a function name. The effect is that the file 78 containing that function becomes the current file and the 79 cursor is positioned on the start of the function (see 80 |tags|). 81 82 *-q* *-qf* 83-q [errorfile] QuickFix mode. The file with the name [errorfile] is read 84 and the first error is displayed. See |quickfix|. 85 If [errorfile] is not given, the 'errorfile' option is used 86 for the file name. See 'errorfile' for the default value. 87 {not in Vi} 88 89(nothing) Without one of the four items above, Vim will start editing a 90 new buffer. It's empty and doesn't have a file name. 91 92 93The startup mode can be changed by using another name instead of "vim", which 94is equal to giving options: 95ex vim -e Start in Ex mode (see |Ex-mode|). *ex* 96exim vim -E Start in improved Ex mode (see |Ex-mode|). *exim* 97 (normally not installed) 98view vim -R Start in read-only mode (see |-R|). *view* 99gvim vim -g Start the GUI (see |gui|). *gvim* 100gex vim -eg Start the GUI in Ex mode. *gex* 101gview vim -Rg Start the GUI in read-only mode. *gview* 102rvim vim -Z Like "vim", but in restricted mode (see |-Z|) *rvim* 103rview vim -RZ Like "view", but in restricted mode. *rview* 104rgvim vim -gZ Like "gvim", but in restricted mode. *rgvim* 105rgview vim -RgZ Like "gview", but in restricted mode. *rgview* 106evim vim -y Easy Vim: set 'insertmode' (see |-y|) *evim* 107eview vim -yR Like "evim" in read-only mode *eview* 108vimdiff vim -d Start in diff mode |diff-mode| 109gvimdiff vim -gd Start in diff mode |diff-mode| 110 111Additional characters may follow, they are ignored. For example, you can have 112"gvim-5" to start the GUI. You must have an executable by that name then, of 113course. 114 115On Unix, you would normally have one executable called Vim, and links from the 116different startup-names to that executable. If your system does not support 117links and you do not want to have several copies of the executable, you could 118use an alias instead. For example: > 119 alias view vim -R 120 alias gvim vim -g 121< 122 *startup-options* 123The option arguments may be given in any order. Single-letter options can be 124combined after one dash. There can be no option arguments after the "--" 125argument. 126 127On VMS all option arguments are assumed to be lowercase, unless preceded with 128a slash. Thus "-R" means recovery and "-/R" readonly. 129 130--help *-h* *--help* *-?* 131-? 132-h Give usage (help) message and exit. {not in Vi} 133 See |info-message| about capturing the text. 134 135 *--version* 136--version Print version information and exit. Same output as for 137 |:version| command. {not in Vi} 138 See |info-message| about capturing the text. 139 140 *--noplugin* 141--noplugin Skip loading plugins. Resets the 'loadplugins' option. 142 {not in Vi} 143 Note that the |-u| argument may also disable loading plugins: 144 argument load: vimrc files plugins defaults.vim ~ 145 (nothing) yes yes yes 146 -u NONE no no no 147 -u DEFAULTS no no yes 148 -u NORC no yes no 149 --noplugin yes no yes 150 151--startuptime {fname} *--startuptime* 152 During startup write timing messages to the file {fname}. 153 This can be used to find out where time is spent while loading 154 your .vimrc, plugins and opening the first file. 155 When {fname} already exists new messages are appended. 156 (Only available when compiled with the |+startuptime| 157 feature). 158 159 *--literal* 160--literal Take file names literally, don't expand wildcards. Not needed 161 for Unix, because Vim always takes file names literally (the 162 shell expands wildcards). 163 Applies to all the names, also the ones that come before this 164 argument. 165 166 *-+* 167+[num] The cursor will be positioned on line "num" for the first 168 file being edited. If "num" is missing, the cursor will be 169 positioned on the last line. 170 171 *-+/* 172+/{pat} The cursor will be positioned on the first line containing 173 "pat" in the first file being edited (see |pattern| for the 174 available search patterns). The search starts at the cursor 175 position, which can be the first line or the cursor position 176 last used from |viminfo|. To force a search from the first 177 line use "+1 +/pat". 178 179+{command} *-+c* *-c* 180-c {command} {command} will be executed after the first file has been 181 read (and after autocommands and modelines for that file have 182 been processed). "command" is interpreted as an Ex command. 183 If the "command" contains spaces, it must be enclosed in 184 double quotes (this depends on the shell that is used). 185 Example: > 186 vim "+set si" main.c 187 vim "+find stdio.h" 188 vim -c "set ff=dos" -c wq mine.mak 189< 190 Note: You can use up to 10 "+" or "-c" arguments in a Vim 191 command. They are executed in the order given. A "-S" 192 argument counts as a "-c" argument as well. 193 {Vi only allows one command} 194 195--cmd {command} *--cmd* 196 {command} will be executed before processing any vimrc file. 197 Otherwise it acts like -c {command}. You can use up to 10 of 198 these commands, independently from "-c" commands. 199 {not in Vi} 200 201 *-S* 202-S {file} The {file} will be sourced after the first file has been read. 203 This is an easy way to do the equivalent of: > 204 -c "source {file}" 205< It can be mixed with "-c" arguments and repeated like "-c". 206 The limit of 10 "-c" arguments applies here as well. 207 {file} cannot start with a "-". 208 {not in Vi} 209 210-S Works like "-S Session.vim". Only when used as the last 211 argument or when another "-" option follows. 212 213 *-r* 214-r Recovery mode. Without a file name argument, a list of 215 existing swap files is given. With a file name, a swap file 216 is read to recover a crashed editing session. See 217 |crash-recovery|. 218 219 *-L* 220-L Same as -r. {only in some versions of Vi: "List recoverable 221 edit sessions"} 222 223 *-R* 224-R Readonly mode. The 'readonly' option will be set for all the 225 files being edited. You can still edit the buffer, but will 226 be prevented from accidentally overwriting a file. If you 227 forgot that you are in View mode and did make some changes, 228 you can overwrite a file by adding an exclamation mark to 229 the Ex command, as in ":w!". The 'readonly' option can be 230 reset with ":set noro" (see the options chapter, |options|). 231 Subsequent edits will not be done in readonly mode. Calling 232 the executable "view" has the same effect as the -R argument. 233 The 'updatecount' option will be set to 10000, meaning that 234 the swap file will not be updated automatically very often. 235 See |-M| for disallowing modifications. 236 237 *-m* 238-m Modifications not allowed to be written. The 'write' option 239 will be reset, so that writing files is disabled. However, 240 the 'write' option can be set to enable writing again. 241 {not in Vi} 242 243 *-M* 244-M Modifications not allowed. The 'modifiable' option will be 245 reset, so that changes are not allowed. The 'write' option 246 will be reset, so that writing files is disabled. However, 247 the 'modifiable' and 'write' options can be set to enable 248 changes and writing. 249 {not in Vi} 250 251 *-Z* *restricted-mode* *E145* 252-Z Restricted mode. All commands that make use of an external 253 shell are disabled. This includes suspending with CTRL-Z, 254 ":sh", filtering, the system() function, backtick expansion, 255 delete(), rename(), mkdir(), writefile(), libcall(), 256 job_start(), etc. 257 {not in Vi} 258 259 *-g* 260-g Start Vim in GUI mode. See |gui|. For the opposite see |-v|. 261 {not in Vi} 262 263 *-v* 264-v Start Ex in Vi mode. Only makes a difference when the 265 executable is called "ex" or "gvim". For gvim the GUI is not 266 started if possible. 267 268 *-e* 269-e Start Vim in Ex mode |Q|. Only makes a difference when the 270 executable is not called "ex". 271 272 *-E* 273-E Start Vim in improved Ex mode |gQ|. Only makes a difference 274 when the executable is not called "exim". 275 {not in Vi} 276 277 *-s-ex* 278-s Silent or batch mode. Only when Vim was started as "ex" or 279 when preceded with the "-e" argument. Otherwise see |-s|, 280 which does take an argument while this use of "-s" doesn't. 281 To be used when Vim is used to execute Ex commands from a file 282 instead of a terminal. Switches off most prompts and 283 informative messages. Also warnings and error messages. 284 The output of these commands is displayed (to stdout): 285 :print 286 :list 287 :number 288 :set to display option values. 289 When 'verbose' is non-zero messages are printed (for 290 debugging, to stderr). 291 'term' and $TERM are not used. 292 If Vim appears to be stuck try typing "qa!<Enter>". You don't 293 get a prompt thus you can't see Vim is waiting for you to type 294 something. 295 Initializations are skipped (except the ones given with the 296 "-u" argument). 297 Example: > 298 vim -e -s < thefilter thefile 299< 300 *-b* 301-b Binary mode. File I/O will only recognize <NL> to separate 302 lines. The 'expandtab' option will be reset. The 'textwidth' 303 option is set to 0. 'modeline' is reset. The 'binary' option 304 is set. This is done after reading the vimrc/exrc files but 305 before reading any file in the arglist. See also 306 |edit-binary|. {not in Vi} 307 308 *-l* 309-l Lisp mode. Sets the 'lisp' and 'showmatch' options on. 310 311 *-A* 312-A Arabic mode. Sets the 'arabic' option on. (Only when 313 compiled with the |+arabic| features (which include 314 |+rightleft|), otherwise Vim gives an error message 315 and exits.) {not in Vi} 316 317 *-F* 318-F Farsi mode. Sets the 'fkmap' and 'rightleft' options on. 319 (Only when compiled with |+rightleft| and |+farsi| features, 320 otherwise Vim gives an error message and exits.) {not in Vi} 321 322 *-H* 323-H Hebrew mode. Sets the 'hkmap' and 'rightleft' options on. 324 (Only when compiled with the |+rightleft| feature, otherwise 325 Vim gives an error message and exits.) {not in Vi} 326 327 *-V* *verbose* 328-V[N] Verbose. Sets the 'verbose' option to [N] (default: 10). 329 Messages will be given for each file that is ":source"d and 330 for reading or writing a viminfo file. Can be used to find 331 out what is happening upon startup and exit. {not in Vi} 332 Example: > 333 vim -V8 foobar 334 335-V[N]{filename} 336 Like -V and set 'verbosefile' to {filename}. The result is 337 that messages are not displayed but written to the file 338 {filename}. {filename} must not start with a digit. 339 Example: > 340 vim -V20vimlog foobar 341< 342 *-D* 343-D Debugging. Go to debugging mode when executing the first 344 command from a script. |debug-mode| 345 {not available when compiled without the |+eval| feature} 346 {not in Vi} 347 348 *-C* 349-C Compatible mode. Sets the 'compatible' option. You can use 350 this to get 'compatible', even though a .vimrc file exists. 351 Keep in mind that the command ":set nocompatible" in some 352 plugin or startup script overrules this, so you may end up 353 with 'nocompatible' anyway. To find out, use: > 354 :verbose set compatible? 355< Several plugins won't work with 'compatible' set. You may 356 want to set it after startup this way: > 357 vim "+set cp" filename 358< Also see |compatible-default|. {not in Vi} 359 360 *-N* 361-N Not compatible mode. Resets the 'compatible' option. You can 362 use this to get 'nocompatible', when there is no .vimrc file 363 or when using "-u NONE". 364 Also see |compatible-default|. {not in Vi} 365 366 *-y* *easy* 367-y Easy mode. Implied for |evim| and |eview|. Starts with 368 'insertmode' set and behaves like a click-and-type editor. 369 This sources the script $VIMRUNTIME/evim.vim. Mappings are 370 set up to work like most click-and-type editors, see 371 |evim-keys|. The GUI is started when available. 372 {not in Vi} 373 374 *-n* 375-n No swap file will be used. Recovery after a crash will be 376 impossible. Handy if you want to view or edit a file on a 377 very slow medium (e.g., a floppy). 378 Can also be done with ":set updatecount=0". You can switch it 379 on again by setting the 'updatecount' option to some value, 380 e.g., ":set uc=100". 381 NOTE: Don't combine -n with -b, making -nb, because that has a 382 different meaning: |-nb|. 383 'updatecount' is set to 0 AFTER executing commands from a 384 vimrc file, but before the GUI initializations. Thus it 385 overrides a setting for 'updatecount' in a vimrc file, but not 386 in a gvimrc file. See |startup|. 387 When you want to reduce accesses to the disk (e.g., for a 388 laptop), don't use "-n", but set 'updatetime' and 389 'updatecount' to very big numbers, and type ":preserve" when 390 you want to save your work. This way you keep the possibility 391 for crash recovery. 392 {not in Vi} 393 394 *-o* 395-o[N] Open N windows, split horizontally. If [N] is not given, 396 one window is opened for every file given as argument. If 397 there is not enough room, only the first few files get a 398 window. If there are more windows than arguments, the last 399 few windows will be editing an empty file. 400 {not in Vi} 401 402 *-O* 403-O[N] Open N windows, split vertically. Otherwise it's like -o. 404 If both the -o and the -O option are given, the last one on 405 the command line determines how the windows will be split. 406 {not in Vi} 407 408 *-p* 409-p[N] Open N tab pages. If [N] is not given, one tab page is opened 410 for every file given as argument. The maximum is set with 411 'tabpagemax' pages (default 10). If there are more tab pages 412 than arguments, the last few tab pages will be editing an 413 empty file. Also see |tabpage|. 414 {not in Vi} 415 416 *-T* 417-T {terminal} Set the terminal type to "terminal". This influences the 418 codes that Vim will send to your terminal. This is normally 419 not needed, because Vim will be able to find out what type 420 of terminal you are using. (See |terminal-info|.) {not in Vi} 421 422 *--not-a-term* 423--not-a-term Tells Vim that the user knows that the input and/or output is 424 not connected to a terminal. This will avoid the warning and 425 the two second delay that would happen. 426 Also avoids the "Reading from stdin..." message. 427 {not in Vi} 428 429 *--ttyfail* 430--ttyfail When the stdin or stdout is not a terminal (tty) then exit 431 right away. 432 433 *-d* 434-d Start in diff mode, like |vimdiff|. 435 {not in Vi} {not available when compiled without the |+diff| 436 feature} 437 438-d {device} Only on the Amiga and when not compiled with the |+diff| 439 feature. Works like "-dev". 440 *-dev* 441-dev {device} Only on the Amiga: The {device} is opened to be used for 442 editing. 443 Normally you would use this to set the window position and 444 size: "-d con:x/y/width/height", e.g., 445 "-d con:30/10/600/150". But you can also use it to start 446 editing on another device, e.g., AUX:. {not in Vi} 447 *-f* 448-f GUI: Do not disconnect from the program that started Vim. 449 'f' stands for "foreground". If omitted, the GUI forks a new 450 process and exits the current one. "-f" should be used when 451 gvim is started by a program that will wait for the edit 452 session to finish (e.g., mail or readnews). If you want gvim 453 never to fork, include 'f' in 'guioptions' in your |gvimrc|. 454 Careful: You can use "-gf" to start the GUI in the foreground, 455 but "-fg" is used to specify the foreground color. |gui-fork| 456 457 Amiga: Do not restart Vim to open a new window. This 458 option should be used when Vim is started by a program that 459 will wait for the edit session to finish (e.g., mail or 460 readnews). See |amiga-window|. 461 462 MS-Windows: This option is not supported. However, when 463 running Vim with an installed vim.bat or gvim.bat file it 464 works. 465 {not in Vi} 466 467 468 *--nofork* 469--nofork GUI: Do not fork. Same as |-f|. 470 *-u* *E282* 471-u {vimrc} The file {vimrc} is read for initializations. Most other 472 initializations are skipped; see |initialization|. 473 474 This can be used to start Vim in a special mode, with special 475 mappings and settings. A shell alias can be used to make 476 this easy to use. For example: > 477 alias vimc vim -u ~/.c_vimrc !* 478< Also consider using autocommands; see |autocommand|. 479 480 When {vimrc} is equal to "NONE" (all uppercase), all 481 initializations from files and environment variables are 482 skipped, including reading the |gvimrc| file when the GUI 483 starts. Loading plugins is also skipped. 484 485 When {vimrc} is equal to "NORC" (all uppercase), this has the 486 same effect as "NONE", but loading plugins is not skipped. 487 488 When {vimrc} is equal to "DEFAULTS" (all uppercase), this has 489 the same effect as "NONE", but the |defaults.vim| script is 490 loaded, which will also set 'nocompatible'. Also see 491 |--clean|. 492 493 Using the "-u" argument with another argument than DEFAULTS 494 has the side effect that the 'compatible' option will be on by 495 default. This can have unexpected effects. See 496 |'compatible'|. 497 {not in Vi} 498 499 *-U* *E230* 500-U {gvimrc} The file {gvimrc} is read for initializations when the GUI 501 starts. Other GUI initializations are skipped. When {gvimrc} 502 is equal to "NONE", no file is read for GUI initializations at 503 all. |gui-init| 504 Exception: Reading the system-wide menu file is always done. 505 {not in Vi} 506 507 *-i* 508-i {viminfo} The file "viminfo" is used instead of the default viminfo 509 file. If the name "NONE" is used (all uppercase), no viminfo 510 file is read or written, even if 'viminfo' is set or when 511 ":rv" or ":wv" are used. See also |viminfo-file|. 512 {not in Vi} 513 514 *--clean* 515--clean Similar to "-u DEFAULTS -U NONE -i NONE": 516 - initializations from files and environment variables is 517 skipped 518 - 'runtimepath' and 'packpath' are set to exclude home 519 directory entries (does not happen with -u DEFAULTS). 520 - the |defaults.vim| script is loaded, which implies 521 'nocompatible': use Vim defaults 522 - no |gvimrc| script is loaded 523 - no viminfo file is read or written 524 525 *-x* 526-x Use encryption to read/write files. Will prompt for a key, 527 which is then stored in the 'key' option. All writes will 528 then use this key to encrypt the text. The '-x' argument is 529 not needed when reading a file, because there is a check if 530 the file that is being read has been encrypted, and Vim asks 531 for a key automatically. |encryption| 532 533 *-X* 534-X Do not try connecting to the X server to get the current 535 window title and copy/paste using the X clipboard. This 536 avoids a long startup time when running Vim in a terminal 537 emulator and the connection to the X server is slow. 538 See |--startuptime| to find out if affects you. 539 Only makes a difference on Unix or VMS, when compiled with the 540 |+X11| feature. Otherwise it's ignored. 541 To disable the connection only for specific terminals, see the 542 'clipboard' option. 543 When the X11 Session Management Protocol (XSMP) handler has 544 been built in, the -X option also disables that connection as 545 it, too, may have undesirable delays. 546 When the connection is desired later anyway (e.g., for 547 client-server messages), call the |serverlist()| function. 548 This does not enable the XSMP handler though. 549 {not in Vi} 550 551 *-s* 552-s {scriptin} The script file "scriptin" is read. The characters in the 553 file are interpreted as if you had typed them. The same can 554 be done with the command ":source! {scriptin}". If the end 555 of the file is reached before the editor exits, further 556 characters are read from the keyboard. Only works when not 557 started in Ex mode, see |-s-ex|. See also |complex-repeat|. 558 {not in Vi} 559 560 *-w_nr* 561-w {number} 562-w{number} Set the 'window' option to {number}. 563 564 *-w* 565-w {scriptout} All the characters that you type are recorded in the file 566 "scriptout", until you exit Vim. This is useful if you want 567 to create a script file to be used with "vim -s" or 568 ":source!". When the "scriptout" file already exists, new 569 characters are appended. See also |complex-repeat|. 570 {scriptout} cannot start with a digit. 571 {not in Vi} 572 573 *-W* 574-W {scriptout} Like -w, but do not append, overwrite an existing file. 575 {not in Vi} 576 577--remote [+{cmd}] {file} ... 578 Open the {file} in another Vim that functions as a server. 579 Any non-file arguments must come before this. 580 See |--remote|. {not in Vi} 581 582--remote-silent [+{cmd}] {file} ... 583 Like --remote, but don't complain if there is no server. 584 See |--remote-silent|. {not in Vi} 585 586--remote-wait [+{cmd}] {file} ... 587 Like --remote, but wait for the server to finish editing the 588 file(s). 589 See |--remote-wait|. {not in Vi} 590 591--remote-wait-silent [+{cmd}] {file} ... 592 Like --remote-wait, but don't complain if there is no server. 593 See |--remote-wait-silent|. {not in Vi} 594 595--servername {name} 596 Specify the name of the Vim server to send to or to become. 597 See |--servername|. {not in Vi} 598 599--remote-send {keys} 600 Send {keys} to a Vim server and exit. 601 See |--remote-send|. {not in Vi} 602 603--remote-expr {expr} 604 Evaluate {expr} in another Vim that functions as a server. 605 The result is printed on stdout. 606 See |--remote-expr|. {not in Vi} 607 608--serverlist Output a list of Vim server names and exit. See 609 |--serverlist|. {not in Vi} 610 611--socketid {id} *--socketid* 612 GTK+ GUI Vim only. Make gvim try to use GtkPlug mechanism, so 613 that it runs inside another window. See |gui-gtk-socketid| 614 for details. {not in Vi} 615 616--windowid {id} *--windowid* 617 Win32 GUI Vim only. Make gvim try to use the window {id} as a 618 parent, so that it runs inside that window. See 619 |gui-w32-windowid| for details. {not in Vi} 620 621--echo-wid *--echo-wid* 622 GTK+ GUI Vim only. Make gvim echo the Window ID on stdout, 623 which can be used to run gvim in a kpart widget. The format 624 of the output is: > 625 WID: 12345\n 626< {not in Vi} 627 628--role {role} *--role* 629 GTK+ 2 GUI only. Set the role of the main window to {role}. 630 The window role can be used by a window manager to uniquely 631 identify a window, in order to restore window placement and 632 such. The --role argument is passed automatically when 633 restoring the session on login. See |gui-gnome-session| 634 {not in Vi} 635 636-P {parent-title} *-P* *MDI* *E671* *E672* 637 Win32 only: Specify the title of the parent application. When 638 possible, Vim will run in an MDI window inside the 639 application. 640 {parent-title} must appear in the window title of the parent 641 application. Make sure that it is specific enough. 642 Note that the implementation is still primitive. It won't 643 work with all applications and the menu doesn't work. 644 645-nb *-nb* 646-nb={fname} 647-nb:{hostname}:{addr}:{password} 648 Attempt connecting to Netbeans and become an editor server for 649 it. The second form specifies a file to read connection info 650 from. The third form specifies the hostname, address and 651 password for connecting to Netbeans. |netbeans-run| 652 {only available when compiled with the |+netbeans_intg| 653 feature; if not then -nb will make Vim exit} 654 655If the executable is called "view", Vim will start in Readonly mode. This is 656useful if you can make a hard or symbolic link from "view" to "vim". 657Starting in Readonly mode can also be done with "vim -R". 658 659If the executable is called "ex", Vim will start in "Ex" mode. This means it 660will accept only ":" commands. But when the "-v" argument is given, Vim will 661start in Normal mode anyway. 662 663Additional arguments are available on unix like systems when compiled with 664X11 GUI support. See |gui-resources|. 665 666============================================================================== 6672. Vim on the Amiga *starting-amiga* 668 669Starting Vim from the Workbench *workbench* 670------------------------------- 671 672Vim can be started from the Workbench by clicking on its icon twice. It will 673then start with an empty buffer. 674 675Vim can be started to edit one or more files by using a "Project" icon. The 676"Default Tool" of the icon must be the full pathname of the Vim executable. 677The name of the ".info" file must be the same as the name of the text file. 678By clicking on this icon twice, Vim will be started with the file name as 679current file name, which will be read into the buffer (if it exists). You can 680edit multiple files by pressing the shift key while clicking on icons, and 681clicking twice on the last one. The "Default Tool" for all these icons must 682be the same. 683 684It is not possible to give arguments to Vim, other than file names, from the 685workbench. 686 687Vim window *amiga-window* 688---------- 689 690Vim will run in the CLI window where it was started. If Vim was started with 691the "run" or "runback" command, or if Vim was started from the workbench, it 692will open a window of its own. 693 694Technical detail: 695 To open the new window a little trick is used. As soon as Vim 696 recognizes that it does not run in a normal CLI window, it will 697 create a script file in "t:". This script file contains the same 698 command as the one Vim was started with, and an "endcli" command. 699 This script file is then executed with a "newcli" command (the "c:run" 700 and "c:newcli" commands are required for this to work). The script 701 file will hang around until reboot, or until you delete it. This 702 method is required to get the ":sh" and ":!" commands to work 703 correctly. But when Vim was started with the -f option (foreground 704 mode), this method is not used. The reason for this is that 705 when a program starts Vim with the -f option it will wait for Vim to 706 exit. With the script trick, the calling program does not know when 707 Vim exits. The -f option can be used when Vim is started by a mail 708 program which also waits for the edit session to finish. As a 709 consequence, the ":sh" and ":!" commands are not available when the 710 -f option is used. 711 712Vim will automatically recognize the window size and react to window 713resizing. Under Amiga DOS 1.3, it is advised to use the fastfonts program, 714"FF", to speed up display redrawing. 715 716============================================================================== 7173. Running eVim *evim-keys* 718 719EVim runs Vim as click-and-type editor. This is very unlike the original Vi 720idea. But it helps for people that don't use Vim often enough to learn the 721commands. Hopefully they will find out that learning to use Normal mode 722commands will make their editing much more effective. 723 724In Evim these options are changed from their default value: 725 726 :set nocompatible Use Vim improvements 727 :set insertmode Remain in Insert mode most of the time 728 :set hidden Keep invisible buffers loaded 729 :set backup Keep backup files (not for VMS) 730 :set backspace=2 Backspace over everything 731 :set autoindent auto-indent new lines 732 :set history=50 keep 50 lines of Ex commands 733 :set ruler show the cursor position 734 :set incsearch show matches halfway typing a pattern 735 :set mouse=a use the mouse in all modes 736 :set hlsearch highlight all matches for a search pattern 737 :set whichwrap+=<,>,[,] <Left> and <Right> wrap around line breaks 738 :set guioptions-=a non-Unix only: don't do auto-select 739 740Key mappings: 741 <Down> moves by screen lines rather than file lines 742 <Up> idem 743 Q does "gq", formatting, instead of Ex mode 744 <BS> in Visual mode: deletes the selection 745 CTRL-X in Visual mode: Cut to clipboard 746 <S-Del> idem 747 CTRL-C in Visual mode: Copy to clipboard 748 <C-Insert> idem 749 CTRL-V Pastes from the clipboard (in any mode) 750 <S-Insert> idem 751 CTRL-Q do what CTRL-V used to do 752 CTRL-Z undo 753 CTRL-Y redo 754 <M-Space> system menu 755 CTRL-A select all 756 <C-Tab> next window, CTRL-W w 757 <C-F4> close window, CTRL-W c 758 759Additionally: 760- ":behave mswin" is used |:behave| 761- syntax highlighting is enabled 762- filetype detection is enabled, filetype plugins and indenting is enabled 763- in a text file 'textwidth' is set to 78 764 765One hint: If you want to go to Normal mode to be able to type a sequence of 766commands, use CTRL-L. |i_CTRL-L| 767 768============================================================================== 7694. Initialization *initialization* *startup* 770 771This section is about the non-GUI version of Vim. See |gui-fork| for 772additional initialization when starting the GUI. 773 774At startup, Vim checks environment variables and files and sets values 775accordingly. Vim proceeds in this order: 776 7771. Set the 'shell' and 'term' option *SHELL* *COMSPEC* *TERM* 778 The environment variable SHELL, if it exists, is used to set the 779 'shell' option. On MS-DOS and Win32, the COMSPEC variable is used 780 if SHELL is not set. 781 The environment variable TERM, if it exists, is used to set the 'term' 782 option. However, 'term' will change later when starting the GUI (step 783 8 below). 784 7852. Process the arguments 786 The options and file names from the command that start Vim are 787 inspected. Buffers are created for all files (but not loaded yet). 788 The |-V| argument can be used to display or log what happens next, 789 useful for debugging the initializations. 790 7913. Execute Ex commands, from environment variables and/or files 792 An environment variable is read as one Ex command line, where multiple 793 commands must be separated with '|' or "<NL>". 794 *vimrc* *exrc* 795 A file that contains initialization commands is called a "vimrc" file. 796 Each line in a vimrc file is executed as an Ex command line. It is 797 sometimes also referred to as "exrc" file. They are the same type of 798 file, but "exrc" is what Vi always used, "vimrc" is a Vim specific 799 name. Also see |vimrc-intro|. 800 801 Places for your personal initializations: 802 Unix $HOME/.vimrc or $HOME/.vim/vimrc 803 OS/2 $HOME/.vimrc, $HOME/vimfiles/vimrc 804 or $VIM/.vimrc (or _vimrc) 805 MS-Windows $HOME/_vimrc, $HOME/vimfiles/vimrc 806 or $VIM/_vimrc 807 Amiga s:.vimrc, home:.vimrc, home:vimfiles:vimrc 808 or $VIM/.vimrc 809 810 The files are searched in the order specified above and only the first 811 one that is found is read. 812 813 RECOMMENDATION: Put all your Vim configuration stuff in the 814 $HOME/.vim/ directory ($HOME/vimfiles/ for MS-Windows). That makes it 815 easy to copy it to another system. 816 817 If Vim was started with "-u filename", the file "filename" is used. 818 All following initializations until 4. are skipped. $MYVIMRC is not 819 set. 820 "vim -u NORC" can be used to skip these initializations without 821 reading a file. "vim -u NONE" also skips loading plugins. |-u| 822 823 If Vim was started in Ex mode with the "-s" argument, all following 824 initializations until 4. are skipped. Only the "-u" option is 825 interpreted. 826 *evim.vim* 827 a. If vim was started as |evim| or |eview| or with the |-y| argument, the 828 script $VIMRUNTIME/evim.vim will be loaded. 829 *system-vimrc* 830 b. For Unix, MS-DOS, MS-Windows, OS/2, VMS, Macintosh, RISC-OS and Amiga 831 the system vimrc file is read for initializations. The path of this 832 file is shown with the ":version" command. Mostly it's "$VIM/vimrc". 833 Note that this file is ALWAYS read in 'compatible' mode, since the 834 automatic resetting of 'compatible' is only done later. Add a ":set 835 nocp" command if you like. 836 For the Macintosh the $VIMRUNTIME/macmap.vim is read. 837 838 *VIMINIT* *.vimrc* *_vimrc* *EXINIT* *.exrc* *_exrc* *$MYVIMRC* 839 c. Five places are searched for initializations. The first that exists 840 is used, the others are ignored. The $MYVIMRC environment variable is 841 set to the file that was first found, unless $MYVIMRC was already set 842 and when using VIMINIT. 843 I The environment variable VIMINIT (see also |compatible-default|) (*) 844 The value of $VIMINIT is used as an Ex command line. 845 II The user vimrc file(s): 846 "$HOME/.vimrc" (for Unix and OS/2) (*) 847 "$HOME/.vim/vimrc" (for Unix and OS/2) (*) 848 "s:.vimrc" (for Amiga) (*) 849 "home:.vimrc" (for Amiga) (*) 850 "home:vimfiles:vimrc" (for Amiga) (*) 851 "$VIM/.vimrc" (for OS/2 and Amiga) (*) 852 "$HOME/_vimrc" (for MS-DOS and Win32) (*) 853 "$HOME/vimfiles/vimrc" (for MS-DOS and Win32) (*) 854 "$VIM/_vimrc" (for MS-DOS and Win32) (*) 855 Note: For Unix, OS/2 and Amiga, when ".vimrc" does not exist, 856 "_vimrc" is also tried, in case an MS-DOS compatible file 857 system is used. For MS-DOS and Win32 ".vimrc" is checked 858 after "_vimrc", in case long file names are used. 859 Note: For MS-DOS and Win32, "$HOME" is checked first. If no 860 "_vimrc" or ".vimrc" is found there, "$VIM" is tried. 861 See |$VIM| for when $VIM is not set. 862 III The environment variable EXINIT. 863 The value of $EXINIT is used as an Ex command line. 864 IV The user exrc file(s). Same as for the user vimrc file, but with 865 "vimrc" replaced by "exrc". But only one of ".exrc" and "_exrc" is 866 used, depending on the system. And without the (*)! 867 V The default vimrc file, $VIMRUNTIME/defaults.vim. This sets up 868 options values and has "syntax on" and "filetype on" commands, 869 which is what most new users will want. See |defaults.vim|. 870 871 d. If the 'exrc' option is on (which is NOT the default), the current 872 directory is searched for three files. The first that exists is used, 873 the others are ignored. 874 - The file ".vimrc" (for Unix, Amiga and OS/2) (*) 875 "_vimrc" (for MS-DOS and Win32) (*) 876 - The file "_vimrc" (for Unix, Amiga and OS/2) (*) 877 ".vimrc" (for MS-DOS and Win32) (*) 878 - The file ".exrc" (for Unix, Amiga and OS/2) 879 "_exrc" (for MS-DOS and Win32) 880 881 (*) Using this file or environment variable will cause 'compatible' to be 882 off by default. See |compatible-default|. 883 884 Note: When using the |mzscheme| interface, it is initialized after loading 885 the vimrc file. Changing 'mzschemedll' later has no effect. 886 8874. Load the plugin scripts. *load-plugins* 888 This does the same as the command: > 889 :runtime! plugin/**/*.vim 890< The result is that all directories in the 'runtimepath' option will be 891 searched for the "plugin" sub-directory and all files ending in ".vim" 892 will be sourced (in alphabetical order per directory), also in 893 subdirectories. 894 However, directories in 'runtimepath' ending in "after" are skipped 895 here and only loaded after packages, see below. 896 Loading plugins won't be done when: 897 - The 'loadplugins' option was reset in a vimrc file. 898 - The |--noplugin| command line argument is used. 899 - The |--clean| command line argument is used. 900 - The "-u NONE" command line argument is used |-u|. 901 - When Vim was compiled without the |+eval| feature. 902 Note that using "-c 'set noloadplugins'" doesn't work, because the 903 commands from the command line have not been executed yet. You can 904 use "--cmd 'set noloadplugins'" or "--cmd 'set loadplugins'" |--cmd|. 905 906 Packages are loaded. These are plugins, as above, but found in the 907 "start" directory of each entry in 'packpath'. Every plugin directory 908 found is added in 'runtimepath' and then the plugins are sourced. See 909 |packages|. 910 911 The plugins scripts are loaded, as above, but now only the directories 912 ending in "after" are used. Note that 'runtimepath' will have changed 913 if packages have been found, but that should not add a directory 914 ending in "after". 915 9165. Set 'shellpipe' and 'shellredir' 917 The 'shellpipe' and 'shellredir' options are set according to the 918 value of the 'shell' option, unless they have been set before. 919 This means that Vim will figure out the values of 'shellpipe' and 920 'shellredir' for you, unless you have set them yourself. 921 9226. Set 'updatecount' to zero, if "-n" command argument used 923 9247. Set binary options 925 If the "-b" flag was given to Vim, the options for binary editing will 926 be set now. See |-b|. 927 9288. Perform GUI initializations 929 Only when starting "gvim", the GUI initializations will be done. See 930 |gui-init|. 931 9329. Read the viminfo file 933 If the 'viminfo' option is not empty, the viminfo file is read. See 934 |viminfo-file|. 935 93610. Read the quickfix file 937 If the "-q" flag was given to Vim, the quickfix file is read. If this 938 fails, Vim exits. 939 94011. Open all windows 941 When the |-o| flag was given, windows will be opened (but not 942 displayed yet). 943 When the |-p| flag was given, tab pages will be created (but not 944 displayed yet). 945 When switching screens, it happens now. Redrawing starts. 946 If the "-q" flag was given to Vim, the first error is jumped to. 947 Buffers for all windows will be loaded. 948 94912. Execute startup commands 950 If a "-t" flag was given to Vim, the tag is jumped to. 951 The commands given with the |-c| and |+cmd| arguments are executed. 952 If the 'insertmode' option is set, Insert mode is entered. 953 The starting flag is reset, has("vim_starting") will now return zero. 954 The |v:vim_did_enter| variable is set to 1. 955 The |VimEnter| autocommands are executed. 956 957The $MYVIMRC or $MYGVIMRC file will be set to the first found vimrc and/or 958gvimrc file. 959 960 961Some hints on using initializations ~ 962 963Standard setup: 964Create a vimrc file to set the default settings and mappings for all your edit 965sessions. Put it in a place so that it will be found by 3b: 966 ~/.vimrc (Unix and OS/2) 967 s:.vimrc (Amiga) 968 $VIM\_vimrc (MS-DOS and Win32) 969Note that creating a vimrc file will cause the 'compatible' option to be off 970by default. See |compatible-default|. 971 972Local setup: 973Put all commands that you need for editing a specific directory only into a 974vimrc file and place it in that directory under the name ".vimrc" ("_vimrc" 975for MS-DOS and Win32). NOTE: To make Vim look for these special files you 976have to turn on the option 'exrc'. See |trojan-horse| too. 977 978System setup: 979This only applies if you are managing a Unix system with several users and 980want to set the defaults for all users. Create a vimrc file with commands 981for default settings and mappings and put it in the place that is given with 982the ":version" command. 983 984 985Saving the current state of Vim to a file ~ 986 987Whenever you have changed values of options or when you have created a 988mapping, then you may want to save them in a vimrc file for later use. See 989|save-settings| about saving the current state of settings to a file. 990 991 992Avoiding setup problems for Vi users ~ 993 994Vi uses the variable EXINIT and the file "~/.exrc". So if you do not want to 995interfere with Vi, then use the variable VIMINIT and the file "vimrc" instead. 996 997 998Amiga environment variables ~ 999 1000On the Amiga, two types of environment variables exist. The ones set with the 1001DOS 1.3 (or later) setenv command are recognized. See the AmigaDos 1.3 1002manual. The environment variables set with the old Manx Set command (before 1003version 5.0) are not recognized. 1004 1005 1006MS-DOS line separators ~ 1007 1008On MS-DOS-like systems (MS-DOS itself, Win32, and OS/2), Vim assumes that all 1009the vimrc files have <CR> <NL> pairs as line separators. This will give 1010problems if you have a file with only <NL>s and have a line like 1011":map xx yy^M". The trailing ^M will be ignored. 1012 1013 1014Vi compatible default value ~ 1015 *compatible-default* 1016When Vim starts, the 'compatible' option is on. This will be used when Vim 1017starts its initializations. But as soon as: 1018- a user vimrc file is found, or 1019- a vimrc file in the current directory is found, or 1020- the "VIMINIT" environment variable is set, or 1021- the "-N" command line argument is given, or 1022- the "--clean" command line argument is given, or 1023- the |defaults.vim| script is loaded, or 1024- a gvimrc file was found, 1025then the option will be set to 'nocompatible'. 1026 1027Note that this does NOT happen when a system-wide vimrc file was found. 1028 1029This has the side effect of setting or resetting other options (see 1030'compatible'). But only the options that have not been set or reset will be 1031changed. This has the same effect like the value of 'compatible' had this 1032value when starting Vim. 1033 1034'compatible' is NOT reset, and |defaults.vim| is not loaded: 1035- when Vim was started with the |-u| command line argument, especially with 1036 "-u NONE", or 1037- when started with the |-C| command line argument, or 1038- when the name of the executable ends in "ex". (This has been done to make 1039 Vim behave like "ex", when it is started as "ex") 1040 1041But there is a side effect of setting or resetting 'compatible' at the moment 1042a .vimrc file is found: Mappings are interpreted the moment they are 1043encountered. This makes a difference when using things like "<CR>". If the 1044mappings depend on a certain value of 'compatible', set or reset it before 1045giving the mapping. 1046 1047 1048Defaults without a .vimrc file ~ 1049 *defaults.vim* 1050If Vim is started normally and no user vimrc file is found, the 1051$VIMRUNTIME/defaults.vim script is loaded. This will set 'compatible' off, 1052switch on syntax highlighting and a few more things. See the script for 1053details. NOTE: this is done since Vim 8.0, not in Vim 7.4. (it was added in 1054patch 7.4.2111 to be exact). 1055 1056This should work well for new Vim users. If you create your own .vimrc, it is 1057recommended to add these lines somewhere near the top: > 1058 unlet! skip_defaults_vim 1059 source $VIMRUNTIME/defaults.vim 1060Then Vim works like before you had a .vimrc. Copying $VIMRUNTIME/vimrc_example 1061is way to do this. Alternatively, you can copy defaults.vim to your .vimrc 1062and modify it (but then you won't get updates when it changes). 1063 1064If you don't like some of the defaults, you can still source defaults.vim and 1065revert individual settings. See the defaults.vim file for hints on how to 1066revert each item. 1067 *skip_defaults_vim* 1068If you use a system-wide vimrc and don't want defaults.vim to change settings, 1069set the "skip_defaults_vim" variable. If this was set and you want to load 1070defaults.vim from your .vimrc, first unlet skip_defaults_vim, as in the 1071example above. 1072 1073 1074Avoiding trojan horses ~ 1075 *trojan-horse* 1076While reading the "vimrc" or the "exrc" file in the current directory, some 1077commands can be disabled for security reasons by setting the 'secure' option. 1078This is always done when executing the command from a tags file. Otherwise it 1079would be possible that you accidentally use a vimrc or tags file that somebody 1080else created and contains nasty commands. The disabled commands are the ones 1081that start a shell, the ones that write to a file, and ":autocmd". The ":map" 1082commands are echoed, so you can see which keys are being mapped. 1083 If you want Vim to execute all commands in a local vimrc file, you 1084can reset the 'secure' option in the EXINIT or VIMINIT environment variable or 1085in the global "exrc" or "vimrc" file. This is not possible in "vimrc" or 1086"exrc" in the current directory, for obvious reasons. 1087 On Unix systems, this only happens if you are not the owner of the 1088vimrc file. Warning: If you unpack an archive that contains a vimrc or exrc 1089file, it will be owned by you. You won't have the security protection. Check 1090the vimrc file before you start Vim in that directory, or reset the 'exrc' 1091option. Some Unix systems allow a user to do "chown" on a file. This makes 1092it possible for another user to create a nasty vimrc and make you the owner. 1093Be careful! 1094 When using tag search commands, executing the search command (the last 1095part of the line in the tags file) is always done in secure mode. This works 1096just like executing a command from a vimrc/exrc in the current directory. 1097 1098 1099If Vim startup is slow ~ 1100 *slow-start* 1101If Vim takes a long time to start up, use the |--startuptime| argument to find 1102out what happens. There are a few common causes: 1103- If the Unix version was compiled with the GUI and/or X11 (check the output 1104 of ":version" for "+GUI" and "+X11"), it may need to load shared libraries 1105 and connect to the X11 server. Try compiling a version with GUI and X11 1106 disabled. This also should make the executable smaller. 1107 Use the |-X| command line argument to avoid connecting to the X server when 1108 running in a terminal. 1109- If you have "viminfo" enabled, the loading of the viminfo file may take a 1110 while. You can find out if this is the problem by disabling viminfo for a 1111 moment (use the Vim argument "-i NONE", |-i|). Try reducing the number of 1112 lines stored in a register with ":set viminfo='20,<50,s10". |viminfo-file|. 1113 1114 1115Intro message ~ 1116 *:intro* 1117When Vim starts without a file name, an introductory message is displayed (for 1118those who don't know what Vim is). It is removed as soon as the display is 1119redrawn in any way. To see the message again, use the ":intro" command (if 1120there is not enough room, you will see only part of it). 1121 To avoid the intro message on startup, add the 'I' flag to 'shortmess'. 1122 1123 *info-message* 1124The |--help| and |--version| arguments cause Vim to print a message and then 1125exit. Normally the message is sent to stdout, thus can be redirected to a 1126file with: > 1127 1128 vim --help >file 1129 1130From inside Vim: > 1131 1132 :read !vim --help 1133 1134When using gvim, it detects that it might have been started from the desktop, 1135without a terminal to show messages on. This is detected when both stdout and 1136stderr are not a tty. This breaks the ":read" command, as used in the example 1137above. To make it work again, set 'shellredir' to ">" instead of the default 1138">&": > 1139 1140 :set shellredir=> 1141 :read !gvim --help 1142 1143This still won't work for systems where gvim does not use stdout at all 1144though. 1145 1146============================================================================== 11475. $VIM and $VIMRUNTIME 1148 *$VIM* 1149The environment variable "$VIM" is used to locate various user files for Vim, 1150such as the user startup script ".vimrc". This depends on the system, see 1151|startup|. 1152 1153To avoid the need for every user to set the $VIM environment variable, Vim 1154will try to get the value for $VIM in this order: 11551. The value defined by the $VIM environment variable. You can use this to 1156 make Vim look in a specific directory for its support files. Example: > 1157 setenv VIM /home/paul/vim 11582. The path from 'helpfile' is used, unless it contains some environment 1159 variable too (the default is "$VIMRUNTIME/doc/help.txt": chicken-egg 1160 problem). The file name ("help.txt" or any other) is removed. Then 1161 trailing directory names are removed, in this order: "doc", "runtime" and 1162 "vim{version}" (e.g., "vim54"). 11633. For MSDOS, Win32 and OS/2 Vim tries to use the directory name of the 1164 executable. If it ends in "/src", this is removed. This is useful if you 1165 unpacked the .zip file in some directory, and adjusted the search path to 1166 find the vim executable. Trailing directory names are removed, in this 1167 order: "runtime" and "vim{version}" (e.g., "vim54"). 11684. For Unix the compile-time defined installation directory is used (see the 1169 output of ":version"). 1170 1171Once Vim has done this once, it will set the $VIM environment variable. To 1172change it later, use a ":let" command like this: > 1173 :let $VIM = "/home/paul/vim/" 1174< 1175 *$VIMRUNTIME* 1176The environment variable "$VIMRUNTIME" is used to locate various support 1177files, such as the on-line documentation and files used for syntax 1178highlighting. For example, the main help file is normally 1179"$VIMRUNTIME/doc/help.txt". 1180You don't normally set $VIMRUNTIME yourself, but let Vim figure it out. This 1181is the order used to find the value of $VIMRUNTIME: 11821. If the environment variable $VIMRUNTIME is set, it is used. You can use 1183 this when the runtime files are in an unusual location. 11842. If "$VIM/vim{version}" exists, it is used. {version} is the version 1185 number of Vim, without any '-' or '.'. For example: "$VIM/vim54". This is 1186 the normal value for $VIMRUNTIME. 11873. If "$VIM/runtime" exists, it is used. 11884. The value of $VIM is used. This is for backwards compatibility with older 1189 versions. 11905. When the 'helpfile' option is set and doesn't contain a '$', its value is 1191 used, with "doc/help.txt" removed from the end. 1192 1193For Unix, when there is a compiled-in default for $VIMRUNTIME (check the 1194output of ":version"), steps 2, 3 and 4 are skipped, and the compiled-in 1195default is used after step 5. This means that the compiled-in default 1196overrules the value of $VIM. This is useful if $VIM is "/etc" and the runtime 1197files are in "/usr/share/vim/vim54". 1198 1199Once Vim has done this once, it will set the $VIMRUNTIME environment variable. 1200To change it later, use a ":let" command like this: > 1201 :let $VIMRUNTIME = "/home/piet/vim/vim54" 1202 1203In case you need the value of $VIMRUNTIME in a shell (e.g., for a script that 1204greps in the help files) you might be able to use this: > 1205 1206 VIMRUNTIME=`vim -e -T dumb --cmd 'exe "set t_cm=\<C-M>"|echo $VIMRUNTIME|quit' | tr -d '\015' ` 1207 1208============================================================================== 12096. Suspending *suspend* 1210 1211 *iconize* *iconise* *CTRL-Z* *v_CTRL-Z* 1212CTRL-Z Suspend Vim, like ":stop". 1213 Works in Normal and in Visual mode. In Insert and 1214 Command-line mode, the CTRL-Z is inserted as a normal 1215 character. In Visual mode Vim goes back to Normal 1216 mode. 1217 Note: if CTRL-Z undoes a change see |mswin.vim|. 1218 1219 1220:sus[pend][!] or *:sus* *:suspend* *:st* *:stop* 1221:st[op][!] Suspend Vim. 1222 If the '!' is not given and 'autowrite' is set, every 1223 buffer with changes and a file name is written out. 1224 If the '!' is given or 'autowrite' is not set, changed 1225 buffers are not written, don't forget to bring Vim 1226 back to the foreground later! 1227 1228In the GUI, suspending is implemented as iconising gvim. In Windows 95/NT, 1229gvim is minimized. 1230 1231On many Unix systems, it is possible to suspend Vim with CTRL-Z. This is only 1232possible in Normal and Visual mode (see next chapter, |vim-modes|). Vim will 1233continue if you make it the foreground job again. On other systems, CTRL-Z 1234will start a new shell. This is the same as the ":sh" command. Vim will 1235continue if you exit from the shell. 1236 1237In X-windows the selection is disowned when Vim suspends. this means you 1238can't paste it in another application (since Vim is going to sleep an attempt 1239to get the selection would make the program hang). 1240 1241============================================================================== 12427. Exiting *exiting* 1243 1244There are several ways to exit Vim: 1245- Close the last window with `:quit`. Only when there are no changes. 1246- Close the last window with `:quit!`. Also when there are changes. 1247- Close all windows with `:qall`. Only when there are no changes. 1248- Close all windows with `:qall!`. Also when there are changes. 1249- Use `:cquit`. Also when there are changes. 1250 1251When using `:cquit` or when there was an error message Vim exits with exit 1252code 1. Errors can be avoided by using `:silent!` or with `:catch`. 1253 1254============================================================================== 12558. Saving settings *save-settings* 1256 1257Mostly you will edit your vimrc files manually. This gives you the greatest 1258flexibility. There are a few commands to generate a vimrc file automatically. 1259You can use these files as they are, or copy/paste lines to include in another 1260vimrc file. 1261 1262 *:mk* *:mkexrc* 1263:mk[exrc] [file] Write current key mappings and changed options to 1264 [file] (default ".exrc" in the current directory), 1265 unless it already exists. {not in Vi} 1266 1267:mk[exrc]! [file] Always write current key mappings and changed 1268 options to [file] (default ".exrc" in the current 1269 directory). {not in Vi} 1270 1271 *:mkv* *:mkvimrc* 1272:mkv[imrc][!] [file] Like ":mkexrc", but the default is ".vimrc" in the 1273 current directory. The ":version" command is also 1274 written to the file. {not in Vi} 1275 1276These commands will write ":map" and ":set" commands to a file, in such a way 1277that when these commands are executed, the current key mappings and options 1278will be set to the same values. The options 'columns', 'endofline', 1279'fileformat', 'key', 'lines', 'modified', 'scroll', 'term', 'textmode', 1280'ttyfast' and 'ttymouse' are not included, because these are terminal or file 1281dependent. Note that the options 'binary', 'paste' and 'readonly' are 1282included, this might not always be what you want. 1283 1284When special keys are used in mappings, The 'cpoptions' option will be 1285temporarily set to its Vim default, to avoid the mappings to be 1286misinterpreted. This makes the file incompatible with Vi, but makes sure it 1287can be used with different terminals. 1288 1289Only global mappings are stored, not mappings local to a buffer. 1290 1291A common method is to use a default ".vimrc" file, make some modifications 1292with ":map" and ":set" commands and write the modified file. First read the 1293default ".vimrc" in with a command like ":source ~piet/.vimrc.Cprogs", change 1294the settings and then save them in the current directory with ":mkvimrc!". If 1295you want to make this file your default .vimrc, move it to your home directory 1296(on Unix), s: (Amiga) or $VIM directory (MS-DOS). You could also use 1297autocommands |autocommand| and/or modelines |modeline|. 1298 1299 *vimrc-option-example* 1300If you only want to add a single option setting to your vimrc, you can use 1301these steps: 13021. Edit your vimrc file with Vim. 13032. Play with the option until it's right. E.g., try out different values for 1304 'guifont'. 13053. Append a line to set the value of the option, using the expression register 1306 '=' to enter the value. E.g., for the 'guifont' option: > 1307 o:set guifont=<C-R>=&guifont<CR><Esc> 1308< [<C-R> is a CTRL-R, <CR> is a return, <Esc> is the escape key] 1309 You need to escape special characters, esp. spaces. 1310 1311Note that when you create a .vimrc file, this can influence the 'compatible' 1312option, which has several side effects. See |'compatible'|. 1313":mkvimrc", ":mkexrc" and ":mksession" write the command to set or reset the 1314'compatible' option to the output file first, because of these side effects. 1315 1316============================================================================== 13179. Views and Sessions *views-sessions* 1318 1319This is introduced in sections |21.4| and |21.5| of the user manual. 1320 1321 *View* *view-file* 1322A View is a collection of settings that apply to one window. You can save a 1323View and when you restore it later, the text is displayed in the same way. 1324The options and mappings in this window will also be restored, so that you can 1325continue editing like when the View was saved. 1326 1327 *Session* *session-file* 1328A Session keeps the Views for all windows, plus the global settings. You can 1329save a Session and when you restore it later the window layout looks the same. 1330You can use a Session to quickly switch between different projects, 1331automatically loading the files you were last working on in that project. 1332 1333Views and Sessions are a nice addition to viminfo-files, which are used to 1334remember information for all Views and Sessions together |viminfo-file|. 1335 1336You can quickly start editing with a previously saved View or Session with the 1337|-S| argument: > 1338 vim -S Session.vim 1339< 1340All this is {not in Vi} and {not available when compiled without the 1341|+mksession| feature}. 1342 1343 *:mks* *:mksession* 1344:mks[ession][!] [file] Write a Vim script that restores the current editing 1345 session. 1346 When [!] is included an existing file is overwritten. 1347 When [file] is omitted "Session.vim" is used. 1348 1349The output of ":mksession" is like ":mkvimrc", but additional commands are 1350added to the file. Which ones depends on the 'sessionoptions' option. The 1351resulting file, when executed with a ":source" command: 13521. Restores global mappings and options, if 'sessionoptions' contains 1353 "options". Script-local mappings will not be written. 13542. Restores global variables that start with an uppercase letter and contain 1355 at least one lowercase letter, if 'sessionoptions' contains "globals". 13563. Unloads all currently loaded buffers. 13574. Restores the current directory if 'sessionoptions' contains "curdir", or 1358 sets the current directory to where the Session file is if 'sessionoptions' 1359 contains "sesdir". 13605. Restores GUI Vim window position, if 'sessionoptions' contains "winpos". 13616. Restores screen size, if 'sessionoptions' contains "resize". 13627. Reloads the buffer list, with the last cursor positions. If 1363 'sessionoptions' contains "buffers" then all buffers are restored, 1364 including hidden and unloaded buffers. Otherwise only buffers in windows 1365 are restored. 13668. Restores all windows with the same layout. If 'sessionoptions' contains 1367 "help", help windows are restored. If 'sessionoptions' contains "blank", 1368 windows editing a buffer without a name will be restored. 1369 If 'sessionoptions' contains "winsize" and no (help/blank) windows were 1370 left out, the window sizes are restored (relative to the screen size). 1371 Otherwise, the windows are just given sensible sizes. 13729. Restores the Views for all the windows, as with |:mkview|. But 1373 'sessionoptions' is used instead of 'viewoptions'. 137410. If a file exists with the same name as the Session file, but ending in 1375 "x.vim" (for eXtra), executes that as well. You can use *x.vim files to 1376 specify additional settings and actions associated with a given Session, 1377 such as creating menu items in the GUI version. 1378 1379After restoring the Session, the full filename of your current Session is 1380available in the internal variable "v:this_session" |this_session-variable|. 1381An example mapping: > 1382 :nmap <F2> :wa<Bar>exe "mksession! " . v:this_session<CR>:so ~/sessions/ 1383This saves the current Session, and starts off the command to load another. 1384 1385A session includes all tab pages, unless "tabpages" was removed from 1386'sessionoptions'. |tab-page| 1387 1388The |SessionLoadPost| autocmd event is triggered after a session file is 1389loaded/sourced. 1390 *SessionLoad-variable* 1391While the session file is loading the SessionLoad global variable is set to 1. 1392Plugins can use this to postpone some work until the SessionLoadPost event is 1393triggered. 1394 1395 *:mkvie* *:mkview* 1396:mkvie[w][!] [file] Write a Vim script that restores the contents of the 1397 current window. 1398 When [!] is included an existing file is overwritten. 1399 When [file] is omitted or is a number from 1 to 9, a 1400 name is generated and 'viewdir' prepended. When the 1401 last path part of 'viewdir' does not exist, this 1402 directory is created. E.g., when 'viewdir' is 1403 "$VIM/vimfiles/view" then "view" is created in 1404 "$VIM/vimfiles". 1405 An existing file is always overwritten then. Use 1406 |:loadview| to load this view again. 1407 When [file] is the name of a file ('viewdir' is not 1408 used), a command to edit the file is added to the 1409 generated file. 1410 1411The output of ":mkview" contains these items: 14121. The argument list used in the window. When the global argument list is 1413 used it is reset to the global list. 1414 The index in the argument list is also restored. 14152. The file being edited in the window. If there is no file, the window is 1416 made empty. 14173. Restore mappings, abbreviations and options local to the window if 1418 'viewoptions' contains "options" or "localoptions". For the options it 1419 restores only values that are local to the current buffer and values local 1420 to the window. 1421 When storing the view as part of a session and "options" is in 1422 'sessionoptions', global values for local options will be stored too. 14234. Restore folds when using manual folding and 'viewoptions' contains 1424 "folds". Restore manually opened and closed folds. 14255. The scroll position and the cursor position in the file. Doesn't work very 1426 well when there are closed folds. 14276. The local current directory, if it is different from the global current 1428 directory and 'viewoptions' contains "curdir". 1429 1430Note that Views and Sessions are not perfect: 1431- They don't restore everything. For example, defined functions, autocommands 1432 and ":syntax on" are not included. Things like register contents and 1433 command line history are in viminfo, not in Sessions or Views. 1434- Global option values are only set when they differ from the default value. 1435 When the current value is not the default value, loading a Session will not 1436 set it back to the default value. Local options will be set back to the 1437 default value though. 1438- Existing mappings will be overwritten without warning. An existing mapping 1439 may cause an error for ambiguity. 1440- When storing manual folds and when storing manually opened/closed folds, 1441 changes in the file between saving and loading the view will mess it up. 1442- The Vim script is not very efficient. But still faster than typing the 1443 commands yourself! 1444 1445 *:lo* *:loadview* 1446:lo[adview] [nr] Load the view for the current file. When [nr] is 1447 omitted, the view stored with ":mkview" is loaded. 1448 When [nr] is specified, the view stored with ":mkview 1449 [nr]" is loaded. 1450 1451The combination of ":mkview" and ":loadview" can be used to store up to ten 1452different views of a file. These are remembered in the directory specified 1453with the 'viewdir' option. The views are stored using the file name. If a 1454file is renamed or accessed through a (symbolic) link the view will not be 1455found. 1456 1457You might want to clean up your 'viewdir' directory now and then. 1458 1459To automatically save and restore views for *.c files: > 1460 au BufWinLeave *.c mkview 1461 au BufWinEnter *.c silent loadview 1462 1463============================================================================== 146410. The viminfo file *viminfo* *viminfo-file* *E136* 1465 *E575* *E576* *E577* 1466If you exit Vim and later start it again, you would normally lose a lot of 1467information. The viminfo file can be used to remember that information, which 1468enables you to continue where you left off. 1469 1470This is introduced in section |21.3| of the user manual. 1471 1472The viminfo file is used to store: 1473- The command line history. 1474- The search string history. 1475- The input-line history. 1476- Contents of non-empty registers. 1477- Marks for several files. 1478- File marks, pointing to locations in files. 1479- Last search/substitute pattern (for 'n' and '&'). 1480- The buffer list. 1481- Global variables. 1482 1483The viminfo file is not supported when the |+viminfo| feature has been 1484disabled at compile time. 1485 1486You could also use a Session file. The difference is that the viminfo file 1487does not depend on what you are working on. There normally is only one 1488viminfo file. Session files are used to save the state of a specific editing 1489Session. You could have several Session files, one for each project you are 1490working on. Viminfo and Session files together can be used to effectively 1491enter Vim and directly start working in your desired setup. |session-file| 1492 1493 *viminfo-read* 1494When Vim is started and the 'viminfo' option is non-empty, the contents of 1495the viminfo file are read and the info can be used in the appropriate places. 1496The |v:oldfiles| variable is filled. The marks are not read in at startup 1497(but file marks are). See |initialization| for how to set the 'viminfo' 1498option upon startup. 1499 1500 *viminfo-write* 1501When Vim exits and 'viminfo' is non-empty, the info is stored in the viminfo 1502file (it's actually merged with the existing one, if one exists). The 1503'viminfo' option is a string containing information about what info should be 1504stored, and contains limits on how much should be stored (see 'viminfo'). 1505 1506Merging happens in two ways. Most items that have been changed or set in the 1507current Vim session are stored, and what was not changed is filled from what 1508is currently in the viminfo file. For example: 1509- Vim session A reads the viminfo, which contains variable START. 1510- Vim session B does the same 1511- Vim session A sets the variables AAA and BOTH and exits 1512- Vim session B sets the variables BBB and BOTH and exits 1513Now the viminfo will have: 1514 START - it was in the viminfo and wasn't changed in session A or B 1515 AAA - value from session A, session B kept it 1516 BBB - value from session B 1517 BOTH - value from session B, value from session A is lost 1518 1519 *viminfo-timestamp* 1520For some items a timestamp is used to keep the last changed version. Here it 1521doesn't matter in which sequence Vim sessions exit, the newest item(s) are 1522always kept. This is used for: 1523- The command line history. 1524- The search string history. 1525- The input-line history. 1526- Contents of non-empty registers. 1527- The jump list 1528- File marks 1529The timestamp feature was added before Vim 8.0. Older versions of Vim, 1530starting with 7.4.1131, will keep the items with timestamp, but not use them. 1531Thus when using both an older and a newer version of Vim the most recent data 1532will be kept. 1533 1534Notes for Unix: 1535- The file protection for the viminfo file will be set to prevent other users 1536 from being able to read it, because it may contain any text or commands that 1537 you have worked with. 1538- If you want to share the viminfo file with other users (e.g. when you "su" 1539 to another user), you can make the file writable for the group or everybody. 1540 Vim will preserve this when replacing the viminfo file. Be careful, don't 1541 allow just anybody to read and write your viminfo file! 1542- Vim will not overwrite a viminfo file that is not writable by the current 1543 "real" user. This helps for when you did "su" to become root, but your 1544 $HOME is still set to a normal user's home directory. Otherwise Vim would 1545 create a viminfo file owned by root that nobody else can read. 1546- The viminfo file cannot be a symbolic link. This is to avoid security 1547 issues. 1548 1549Marks are stored for each file separately. When a file is read and 'viminfo' 1550is non-empty, the marks for that file are read from the viminfo file. NOTE: 1551The marks are only written when exiting Vim, which is fine because marks are 1552remembered for all the files you have opened in the current editing session, 1553unless ":bdel" is used. If you want to save the marks for a file that you are 1554about to abandon with ":bdel", use ":wv". The '[' and ']' marks are not 1555stored, but the '"' mark is. The '"' mark is very useful for jumping to the 1556cursor position when the file was last exited. No marks are saved for files 1557that start with any string given with the "r" flag in 'viminfo'. This can be 1558used to avoid saving marks for files on removable media (for MS-DOS you would 1559use "ra:,rb:", for Amiga "rdf0:,rdf1:,rdf2:"). 1560The |v:oldfiles| variable is filled with the file names that the viminfo file 1561has marks for. 1562 1563 *viminfo-file-marks* 1564Uppercase marks ('A to 'Z) are stored when writing the viminfo file. The 1565numbered marks ('0 to '9) are a bit special. When the viminfo file is written 1566(when exiting or with the ":wviminfo" command), '0 is set to the current cursor 1567position and file. The old '0 is moved to '1, '1 to '2, etc. This 1568resembles what happens with the "1 to "9 delete registers. If the current 1569cursor position is already present in '0 to '9, it is moved to '0, to avoid 1570having the same position twice. The result is that with "'0", you can jump 1571back to the file and line where you exited Vim. To do that right away, try 1572using this command: > 1573 1574 vim -c "normal '0" 1575 1576In a csh compatible shell you could make an alias for it: > 1577 1578 alias lvim vim -c '"'normal "'"0'"' 1579 1580For a bash-like shell: > 1581 1582 alias lvim='vim -c "normal '\''0"' 1583 1584Use the "r" flag in 'viminfo' to specify for which files no marks should be 1585remembered. 1586 1587 1588VIMINFO FILE NAME *viminfo-file-name* 1589 1590- The default name of the viminfo file is "$HOME/.viminfo" for Unix and OS/2, 1591 "s:.viminfo" for Amiga, "$HOME\_viminfo" for MS-DOS and Win32. For the last 1592 two, when $HOME is not set, "$VIM\_viminfo" is used. When $VIM is also not 1593 set, "c:\_viminfo" is used. For OS/2 "$VIM/.viminfo" is used when $HOME is 1594 not set and $VIM is set. 1595- The 'n' flag in the 'viminfo' option can be used to specify another viminfo 1596 file name |'viminfo'|. 1597- The "-i" Vim argument can be used to set another file name, |-i|. When the 1598 file name given is "NONE" (all uppercase), no viminfo file is ever read or 1599 written. Also not for the commands below! 1600- The 'viminfofile' option can be used like the "-i" argument. In fact, the 1601 value form the "-i" argument is stored in the 'viminfofile' option. 1602- For the commands below, another file name can be given, overriding the 1603 default and the name given with 'viminfo' or "-i" (unless it's NONE). 1604 1605 1606CHARACTER ENCODING *viminfo-encoding* 1607 1608The text in the viminfo file is encoded as specified with the 'encoding' 1609option. Normally you will always work with the same 'encoding' value, and 1610this works just fine. However, if you read the viminfo file with another 1611value for 'encoding' than what it was written with, some of the text 1612(non-ASCII characters) may be invalid. If this is unacceptable, add the 'c' 1613flag to the 'viminfo' option: > 1614 :set viminfo+=c 1615Vim will then attempt to convert the text in the viminfo file from the 1616'encoding' value it was written with to the current 'encoding' value. This 1617requires Vim to be compiled with the |+iconv| feature. Filenames are not 1618converted. 1619 1620 1621MANUALLY READING AND WRITING *viminfo-read-write* 1622 1623Two commands can be used to read and write the viminfo file manually. This 1624can be used to exchange registers between two running Vim programs: First 1625type ":wv" in one and then ":rv" in the other. Note that if the register 1626already contained something, then ":rv!" would be required. Also note 1627however that this means everything will be overwritten with information from 1628the first Vim, including the command line history, etc. 1629 1630The viminfo file itself can be edited by hand too, although we suggest you 1631start with an existing one to get the format right. It is reasonably 1632self-explanatory once you're in there. This can be useful in order to 1633create a second file, say "~/.my_viminfo" which could contain certain 1634settings that you always want when you first start Vim. For example, you 1635can preload registers with particular data, or put certain commands in the 1636command line history. A line in your .vimrc file like > 1637 :rviminfo! ~/.my_viminfo 1638can be used to load this information. You could even have different viminfos 1639for different types of files (e.g., C code) and load them based on the file 1640name, using the ":autocmd" command (see |:autocmd|). 1641 1642 *viminfo-errors* 1643When Vim detects an error while reading a viminfo file, it will not overwrite 1644that file. If there are more than 10 errors, Vim stops reading the viminfo 1645file. This was done to avoid accidentally destroying a file when the file 1646name of the viminfo file is wrong. This could happen when accidentally typing 1647"vim -i file" when you wanted "vim -R file" (yes, somebody accidentally did 1648that!). If you want to overwrite a viminfo file with an error in it, you will 1649either have to fix the error, or delete the file (while Vim is running, so 1650most of the information will be restored). 1651 1652 *:rv* *:rviminfo* *E195* 1653:rv[iminfo][!] [file] Read from viminfo file [file] (default: see above). 1654 If [!] is given, then any information that is 1655 already set (registers, marks, |v:oldfiles|, etc.) 1656 will be overwritten {not in Vi} 1657 1658 *:wv* *:wviminfo* *E137* *E138* *E574* *E886* *E929* 1659:wv[iminfo][!] [file] Write to viminfo file [file] (default: see above). 1660 The information in the file is first read in to make 1661 a merge between old and new info. When [!] is used, 1662 the old information is not read first, only the 1663 internal info is written. If 'viminfo' is empty, marks 1664 for up to 100 files will be written. 1665 When you get error "E929: Too many viminfo temp files" 1666 check that no old temp files were left behind (e.g. 1667 ~/.viminf*) and that you can write in the directory of 1668 the .viminfo file. 1669 {not in Vi} 1670 1671 *:ol* *:oldfiles* 1672:ol[dfiles] List the files that have marks stored in the viminfo 1673 file. This list is read on startup and only changes 1674 afterwards with `:rviminfo!`. Also see |v:oldfiles|. 1675 The number can be used with |c_#<|. 1676 The output can be filtered with |:filter|, e.g.: > 1677 filter /\.vim/ oldfiles 1678< The filtering happens on the file name. 1679 {not in Vi, only when compiled with the |+eval| 1680 feature} 1681 1682:bro[wse] ol[dfiles][!] 1683 List file names as with |:oldfiles|, and then prompt 1684 for a number. When the number is valid that file from 1685 the list is edited. 1686 If you get the |press-enter| prompt you can press "q" 1687 and still get the prompt to enter a file number. 1688 Use ! to abandon a modified buffer. |abandon| 1689 {not when compiled with tiny or small features} 1690 1691 vim:tw=78:ts=8:noet:ft=help:norl: 1692