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