codekingpro/portable-devtools
114k
1*starting.txt* For Vim version 9.2. Last change: 2026 Mar 172 3 4 VIM REFERENCE MANUAL by Bram Moolenaar5 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 command24 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 them32can 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 to37start editing:38 39 *-file* *---*40filename One or more file names. The first one will be the current41 file and read into the buffer. The cursor will be positioned42 on the first line of the buffer.43 To avoid a file name starting with a '-' being interpreted as44 an option, precede the arglist with "--", e.g.: >45 vim -- -filename46< All arguments after the "--" will be interpreted as file47 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 Ex52 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 text58 that is read from stdin. The commands that would normally be59 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 are63 reminded to save the text when trying to exit. If you don't64 like that, put this these lines in your vimrc: >65 " Don't set 'modified' when reading from stdin66 au StdinReadPost * set nomodified67<68 Starting in Ex mode: >69 ex -70 vim -e -71 exim -72 vim -E73< 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 associated77 file becomes the current file, and the associated command is78 executed. Mostly this is used for C programs, in which case79 "tag" often is a function name. The effect is that the file80 containing that function becomes the current file and the81 cursor is positioned on the start of the function (see82 |tags|).83 84 *-q* *-qf*85-q [errorfile] QuickFix mode. The file with the name [errorfile] is read86 and the first error is displayed. See |quickfix|.87 If [errorfile] is not given, the 'errorfile' option is used88 for the file name. See 'errorfile' for the default value.89 90(nothing) Without one of the four items above, Vim will start editing a91 new buffer. It's empty and doesn't have a file name.92 93 94The startup mode can be changed by using another name instead of "vim", which95is equal to giving options:96ex vim -e Start in Ex mode (see |Ex-mode|). *ex*97exim vim -E Start in improved Ex mode (see |Ex-mode|). *exim*98 (normally not installed)99view vim -R Start in read-only mode (see |-R|). *view*100gvim vim -g Start the GUI (see |gui|). *gvim*101gex vim -eg Start the GUI in Ex mode. *gex*102gview vim -Rg Start the GUI in read-only mode. *gview*103rvim vim -Z Like "vim", but in restricted mode (see |-Z|) *rvim*104rview vim -RZ Like "view", but in restricted mode. *rview*105rgvim vim -gZ Like "gvim", but in restricted mode. *rgvim*106rgview vim -RgZ Like "gview", but in restricted mode. *rgview*107evim vim -y Easy Vim: set 'insertmode' (see |-y|) *evim*108eview vim -yR Like "evim" in read-only mode *eview*109vimdiff vim -d Start in diff mode |diff-mode|110gvimdiff vim -gd Start in diff mode |diff-mode|111 112Additional characters may follow, they are ignored. For example, you can have113"gvim-8" to start the GUI. You must have an executable by that name then, of114course.115 116On Unix, you would normally have one executable called "vim", and links from117the different startup-names to that executable. If your system does not118support links and you do not want to have several copies of the executable,119you could use an alias instead. For example, in a C shell descendant: >120 alias view vim -R121 alias gvim vim -g122<123 *startup-options*124The option arguments may be given in any order. Single-letter options can be125combined after one dash. There can be no option arguments after the "--"126argument.127 128On VMS all option arguments are assumed to be lowercase, unless preceded with129a 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 for138 |: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 yes147 -u NONE no no no148 -u DEFAULTS no no yes149 -u NORC no yes no150 --noplugin yes no yes151 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 loading155 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 needed162 for Unix, because Vim always takes file names literally (the163 shell expands wildcards).164 Applies to all the names, also the ones that come before this165 argument.166 167 *-+*168+[num] The cursor will be positioned on line "num" for the first169 file being edited. If "num" is missing, the cursor will be170 positioned on the last line.171 172 *-+/*173+/{pat} The cursor will be positioned on the first line containing174 "pat" in the first file being edited (see |pattern| for the175 available search patterns). The search starts at the cursor176 position, which can be the first line or the cursor position177 last used from |viminfo|. To force a search from the first178 line use "+1 +/pat".179 180+{command} *-+c* *-c*181-c {command} {command} will be executed after the first file has been182 read (and after autocommands and modelines for that file have183 been processed). "command" is interpreted as an Ex command.184 If the "command" contains spaces, it must be enclosed in185 double quotes (this depends on the shell that is used).186 Example: >187 vim "+set si" main.c188 vim "+find stdio.h"189 vim -c "set ff=dos" -c wq mine.mak190<191 Note: You can use up to 10 "+" or "-c" arguments in a Vim192 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 of198 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 exit209 Vim, you won't see error messages. Use |-u| instead.210 211-S Works like "-S Session.vim". Only when used as the last212 argument or when another "-" option follows.213 214 *-r*215-r Recovery mode. Without a file name argument, a list of216 existing swap files is given. With a file name, a swap file217 is read to recover a crashed editing session. See218 |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 the225 files being edited. You can still edit the buffer, but will226 be prevented from accidentally overwriting a file. If you227 forgot that you are in View mode and did make some changes,228 you can overwrite a file by adding an exclamation mark to229 the Ex command, as in ":w!". The 'readonly' option can be230 reset with ":set noro" (see the options chapter, |options|).231 Subsequent edits will not be done in readonly mode. Calling232 the executable "view" has the same effect as the -R argument.233 The 'updatecount' option will be set to 10000, meaning that234 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' option239 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 be244 reset, so that changes are not allowed. The 'write' option245 will be reset, so that writing files is disabled. However,246 the 'modifiable' and 'write' options can be set to enable247 changes and writing.248 249 *-Z* *restricted-mode* *E145* *E981*250-Z Restricted mode. All commands that make use of an external251 shell are disabled. This includes suspending with CTRL-Z,252 ":sh", filtering, the |system()| function, backtick expansion253 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 uses259 the Safe module.260 For Unix restricted mode is used when the last part of $SHELL261 is "nologin" or "false".262 Note that the user may still find a loophole to execute a263 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 the270 executable is called "ex" or "gvim". For gvim the GUI is not271 started if possible.272 273 *-e*274-e Start Vim in Ex mode, see |Ex-mode|. Only makes a difference275 when the executable is not called "ex".276 277 *-E*278-E Start Vim in improved Ex mode |gQ|. Only makes a difference279 when the executable is not called "exim".280 281 *-s-ex*282-s Silent or batch mode. Only when Vim was started as "ex" or283 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 file286 instead of a terminal. Switches off most prompts and287 informative messages. Also warnings and error messages.288 The output of these commands is displayed (to stdout):289 :print290 :list291 :number292 :set to display option values.293 When 'verbose' is non-zero, messages are printed (for294 debugging, to stderr).295 'term' and $TERM are not used.296 If Vim appears to be stuck, try typing "qa!<Enter>". You297 don't get a prompt, thus you can't see Vim is waiting for you298 to type something.299 Initializations are skipped (except the ones given with the300 "-u" argument).301 Example: >302 vim -e -s < thefilter thefile303< For the opposite, to see errors from the script, execute the304 file with the |-u| flag: >305 vim -u thefilter thefile306<307 *-b*308-b Binary mode. File I/O will only recognize <NL> to separate309 lines. The 'expandtab' option will be reset. The 'textwidth'310 option is set to 0. 'modeline' is reset. The 'binary' option311 is set. This is done after reading the vimrc/exrc files but312 before reading any file in the arglist. See also313 |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 when320 compiled with the |+arabic| features (which include321 |+rightleft|), otherwise, Vim gives an error message322 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 and336 for reading or writing a viminfo file. Can be used to find337 out what is happening upon startup and exit.338 Example: >339 vim -V8 foobar340 341-V[N]{filename}342 Like -V and set 'verbosefile' to {filename}. The result is343 that messages are not displayed but written to the file344 {filename}. {filename} must not start with a digit.345 Example: >346 vim -V20vimlog foobar347<348--log {filename} *--log*349 Start logging and write entries to {filename}.350 This works like calling `ch_logfile({filename}, 'ao')` very351 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 first356 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 use361 this to get 'compatible', even though a .vimrc file exists.362 Keep in mind that the command ":set nocompatible" in some363 plugin or startup script overrules this, so you may end up364 with 'nocompatible' anyway. To find out, use: >365 :verbose set compatible?366< Several plugins won't work with 'compatible' set. You may367 want to set it after startup this way: >368 vim "+set cp" filename369< Also see |compatible-default|.370 371 *-N*372-N Not compatible mode. Resets the 'compatible' option. You can373 use this to get 'nocompatible', when there is no .vimrc file374 or when using "-u NONE".375 Also see |compatible-default|.376 377 *-y* *easy*378-y Easy mode. Implied for |evim| and |eview|. Starts with379 'insertmode' set and behaves like a click-and-type editor.380 This sources the script $VIMRUNTIME/evim.vim. Mappings are381 set up to work like most click-and-type editors, see382 |evim-keys|. The GUI is started when available.383 384 *-n*385-n No swap file will be used. Recovery after a crash will be386 impossible. Handy if you want to view or edit a file on a387 very slow medium (e.g., a floppy).388 Can also be done with ":set updatecount=0". You can switch it389 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 a392 different meaning: |-nb|.393 'updatecount' is set to 0 AFTER executing commands from a394 vimrc file, but before the GUI initializations. Thus it395 overrides a setting for 'updatecount' in a vimrc file, but not396 in a gvimrc file. See |startup|.397 When you want to reduce accesses to the disk (e.g., for a398 laptop), don't use "-n", but set 'updatetime' and399 'updatecount' to very big numbers, and type ":preserve" when400 you want to save your work. This way you keep the possibility401 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. If406 there is not enough room, only the first few files get a407 window. If there are more windows than arguments, the last408 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 on413 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 opened417 for every file given as argument. The maximum is set with418 'tabpagemax' pages (default 10). If there are more tab pages419 than arguments, the last few tab pages will be editing an420 empty file. Also see |tabpage|.421 422 *-T*423-T {terminal} Set the terminal type to "terminal". This influences the424 codes that Vim will send to your terminal. This is normally425 not needed, because Vim will be able to find out what type426 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 is430 not connected to a terminal. This will avoid the warning and431 the two second delay that would happen.432 Also avoids the "Reading from stdin..." as well as the433 "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 the437 title and message of the dialog to file {name}. The file is438 created or appended to. Only useful for testing, to avoid439 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 exit444 right away.445 446 *-d*447-d Start in diff mode, like |vimdiff|.448 {not available when compiled without the |+diff| feature}449 450-d {device} Only on the Amiga and when not compiled with the |+diff|451 feature. Works like "-dev".452 *-dev*453-dev {device} Only on the Amiga: The {device} is opened to be used for454 editing.455 Normally you would use this to set the window position and456 size: "-d con:x/y/width/height", e.g.,457 "-d con:30/10/600/150". But you can also use it to start458 editing on another device, e.g., AUX:.459 *-f*460-f GUI: Do not disconnect from the program that started Vim.461 'f' stands for "foreground". If omitted, the GUI forks a new462 process and exits the current one. "-f" should be used when463 gvim is started by a program that will wait for the edit464 session to finish (e.g., mail or readnews). If you want gvim465 never to fork, include 'f' in 'guioptions' in your |gvimrc|.466 Careful: You can use "-gf" to start the GUI in the foreground,467 but "-fg" is used to specify the foreground color. |gui-fork|468 469 Amiga: Do not restart Vim to open a new window. This470 option should be used when Vim is started by a program that471 will wait for the edit session to finish (e.g., mail or472 readnews). See |amiga-window|.473 474 MS-Windows: This option is not supported. However, when475 running Vim with an installed vim.bat or gvim.bat file it476 works.477 478 479 *--nofork*480--nofork GUI: Do not fork. Same as |-f|.481 *-u* *E282*482-u {vimrc} The file {vimrc} is read for initializations. Most other483 initializations are skipped; see |initialization|.484 485 This can be used to start Vim in a special mode, with special486 mappings and settings. A shell alias can be used to make487 this easy to use. For example, in a C shell descendant: >488 alias vimc 'vim -u ~/.c_vimrc \!*'489< And in a Bash shell: >490 alias vimc='vim -u ~/.c_vimrc'491< Also consider using autocommands; see |autocommand|.492 493 When {vimrc} is equal to "NONE" (all uppercase), all494 initializations from files and environment variables are495 skipped, including reading the |gvimrc| file when the GUI496 starts. Loading plugins is also skipped.497 498 When {vimrc} is equal to "NORC" (all uppercase), this has the499 same effect as "NONE", but loading plugins is not skipped.500 501 When {vimrc} is equal to "DEFAULTS" (all uppercase), this has502 the same effect as "NONE", but the |defaults.vim| script is503 loaded, which will also set 'nocompatible'. Also see504 |--clean|.505 506 Using the "-u" argument with another argument than DEFAULTS507 has the side effect that the 'compatible' option will be on by508 default. This can have unexpected effects. See509 'compatible'.510 511 *-U* *E230*512-U {gvimrc} The file {gvimrc} is read for initializations when the GUI513 starts. Other GUI initializations are skipped. When {gvimrc}514 is equal to "NONE", no file is read for GUI initializations at515 all. |gui-init|516 Exception: Reading the system-wide menu file is always done.517 518 *-i*519-i {viminfo} The file "viminfo" is used instead of the default viminfo520 file. If the name "NONE" is used (all uppercase), no viminfo521 file is read or written, even if 'viminfo' is set or when522 ":rv" or ":wv" are used. See also |viminfo-file|.523 524 *--clean*525--clean Similar to "-u DEFAULTS -U NONE -i NONE":526 - initializations from files and environment variables is527 skipped528 - 'runtimepath' and 'packpath' are set to exclude home529 directory entries (does not happen with -u DEFAULTS).530 - the |defaults.vim| script is loaded, which implies531 'nocompatible': use Vim defaults532 - no |gvimrc| script is loaded533 - no viminfo file is read or written534 Note that a following "-u" argument overrules the effect of535 "-u DEFAULTS".536 537 *-x*538-x Use encryption to read/write files. Will prompt for a key,539 which is then stored in the 'key' option. All writes will540 then use this key to encrypt the text. The '-x' argument is541 not needed when reading a file, because there is a check if542 the file that is being read has been encrypted, and Vim asks543 for a key automatically. |encryption|544 {only available when compiled with the |+cryptv| feature}545 546 *-X*547-X Do not try connecting to the X server to get the current548 window title and copy/paste using the X clipboard. This549 avoids a long startup time when running Vim in a terminal550 emulator and the connection to the X server is slow.551 See |--startuptime| to find out if this affects you.552 Only makes a difference on Unix or VMS, when compiled with the553 |+X11| feature. Otherwise, it's ignored.554 To disable the connection only for specific terminals, see the555 'clipboard' option.556 When the X11 Session Management Protocol (XSMP) handler has557 been built in, the -X option also disables that connection as558 it, too, may have undesirable delays.559 When the connection is desired later anyway (e.g., for560 client-server messages), call the |serverlist()| function.561 This does not enable the XSMP handler though.562 563 *-Y*564-Y Do not try connecting to the Wayland compositor. Is only565 relevant for Unix when compiled with the |+wayland| feature,566 otherwise it's ignored. Note that this will make any feature567 that uses Wayland unavailable, such as the clipboard.568 569 *-s*570-s {scriptin} The script file "scriptin" is read. The characters in the571 file are interpreted as if you had typed them. The same can572 be done with the command ":source! {scriptin}". If the end573 of the file is reached before the editor exits, further574 characters are read from the keyboard. Only works when not575 started in Ex mode, see |-s-ex|. See also |complex-repeat|.576 577 *-w_nr*578-w {number}579-w{number} Set the 'window' option to {number}.580 581 *-w*582-w {scriptout} All the characters that you type are recorded in the file583 "scriptout", until you exit Vim. This is useful if you want584 to create a script file to be used with "vim -s" or585 ":source!". When the "scriptout" file already exists, new586 characters are appended. See also |complex-repeat|.587 {scriptout} cannot start with a digit.588 If you want to record what is typed in a human readable form,589 you can use |ch_logfile()|. It adds "raw key input" lines.590 Also see |--log|.591 592 *-W*593-W {scriptout} Like -w, but do not append, overwrite an existing file.594 595--remote [+{cmd}] {file} ...596 Open the {file} in another Vim that functions as a server.597 Any non-file arguments must come before this.598 See |--remote|.599 600--remote-silent [+{cmd}] {file} ...601 Like --remote, but don't complain if there is no server.602 See |--remote-silent|.603 604--remote-wait [+{cmd}] {file} ...605 Like --remote, but wait for the server to finish editing the606 file(s).607 See |--remote-wait|.608 609--remote-wait-silent [+{cmd}] {file} ...610 Like --remote-wait, but don't complain if there is no server.611 See |--remote-wait-silent|.612 613--servername {name}614 Specify the name of the Vim server to send to or to become.615 See |--servername|.616 617--remote-send {keys}618 Send {keys} to a Vim server and exit.619 See |--remote-send|.620 621--remote-expr {expr}622 Evaluate {expr} in another Vim that functions as a server.623 The result is printed on stdout.624 See |--remote-expr|.625 626--serverlist Output a list of Vim server names and exit. See627 |--serverlist|.628 629--socketid {id} *--socketid*630 GTK+ GUI Vim only. Make gvim try to use GtkPlug mechanism, so631 that it runs inside another window. See |gui-gtk-socketid|632 for details.633 634--windowid {id} *--windowid*635 Win32 GUI Vim only. Make gvim try to use the window {id} as a636 parent, so that it runs inside that window. See637 |gui-w32-windowid| for details.638 639--echo-wid *--echo-wid*640 GTK+ GUI Vim only. Make gvim echo the Window ID on stdout,641 which can be used to run gvim in a kpart widget. The format642 of the output is: >643 WID: 12345\n644 645--role {role} *--role*646 GTK+ 2 GUI only. Set the role of the main window to {role}.647 The window role can be used by a window manager to uniquely648 identify a window, in order to restore window placement and649 such. The --role argument is passed automatically when650 restoring the session on login. See |gui-gnome-session|651 652-P {parent-title} *-P* *MDI* *E671* *E672*653 Win32 only: Specify the title of the parent application. When654 possible, Vim will run in an MDI window inside the655 application.656 {parent-title} must appear in the window title of the parent657 application. Make sure that it is specific enough.658 Note that the implementation is still primitive. It won't659 work with all applications and the menu doesn't work.660 661-nb *-nb*662-nb={fname}663-nb:{hostname}:{addr}:{password}664 Attempt connecting to Netbeans and become an editor server for665 it. The second form specifies a file to read connection info666 from. The third form specifies the hostname, address and667 password for connecting to Netbeans. |netbeans-run|668 {only available when compiled with the |+netbeans_intg|669 feature; if not then -nb will make Vim exit}670 671If the executable is called "view", Vim will start in Readonly mode. This is672useful if you can make a hard or symbolic link from "view" to "vim".673Starting in Readonly mode can also be done with "vim -R".674 675If the executable is called "ex", Vim will start in "Ex" mode. This means it676will accept only ":" commands. But when the "-v" argument is given, Vim will677start in Normal mode anyway.678 679Additional arguments are available on Unix like systems when compiled with680X11 GUI support. See |gui-resources|.681 682==============================================================================6832. Vim on the Amiga *starting-amiga*684 685Starting Vim from the Workbench *workbench*686-------------------------------687 688Vim can be started from the Workbench by clicking on its icon twice. It will689then start with an empty buffer.690 691Vim can be started to edit one or more files by using a "Project" icon. The692"Default Tool" of the icon must be the full pathname of the Vim executable.693The name of the ".info" file must be the same as the name of the text file.694By clicking on this icon twice, Vim will be started with the file name as695current file name, which will be read into the buffer (if it exists). You can696edit multiple files by pressing the shift key while clicking on icons, and697clicking twice on the last one. The "Default Tool" for all these icons must698be the same.699 700It is not possible to give arguments to Vim, other than file names, from the701workbench.702 703Vim window *amiga-window*704----------705 706Vim will run in the CLI window where it was started. If Vim was started with707the "run" or "runback" command, or if Vim was started from the workbench, it708will open a window of its own.709 710Technical detail:711 To open the new window a little trick is used. As soon as Vim712 recognizes that it does not run in a normal CLI window, it will713 create a script file in "t:". This script file contains the same714 command as the one Vim was started with, and an "endcli" command.715 This script file is then executed with a "newcli" command (the "c:run"716 and "c:newcli" commands are required for this to work). The script717 file will hang around until reboot, or until you delete it. This718 method is required to get the ":sh" and ":!" commands to work719 correctly. But when Vim was started with the -f option (foreground720 mode), this method is not used. The reason for this is that721 when a program starts Vim with the -f option it will wait for Vim to722 exit. With the script trick, the calling program does not know when723 Vim exits. The -f option can be used when Vim is started by a mail724 program which also waits for the edit session to finish. As a725 consequence, the ":sh" and ":!" commands are not available when the726 -f option is used.727 728Vim will automatically recognize the window size and react to window729resizing. Under Amiga DOS 1.3, it is advised to use the fastfonts program,730"FF", to speed up display redrawing.731 732==============================================================================7333. Running eVim *evim-keys*734 735EVim runs Vim as click-and-type editor. This is very unlike the original Vi736idea. But it helps for people that don't use Vim often enough to learn the737commands. Hopefully they will find out that learning to use Normal mode738commands will make their editing much more effective.739 740In Evim these options are changed from their default value:741 742 :set nocompatible Use Vim improvements743 :set insertmode Remain in Insert mode most of the time744 :set hidden Keep invisible buffers loaded745 :set backup Keep backup files (not for VMS)746 :set backspace=2 Backspace over everything747 :set autoindent auto-indent new lines748 :set history=50 keep 50 lines of Ex commands749 :set ruler show the cursor position750 :set incsearch show matches halfway typing a pattern751 :set mouse=a use the mouse in all modes752 :set hlsearch highlight all matches for a search pattern753 :set whichwrap+=<,>,[,] <Left> and <Right> wrap around line breaks754 :set guioptions-=a non-Unix only: don't do auto-select755 756Key mappings:757 <CTRL-Q> quit, using `:confirm` prompt if there are changes758 <Down> moves by screen lines rather than file lines759 <Up> idem760 Q does "gq", formatting, instead of Ex mode761 <BS> in Visual mode: deletes the selection762 CTRL-X in Visual mode: Cut to clipboard763 <S-Del> idem764 CTRL-C in Visual mode: Copy to clipboard765 <C-Insert> idem766 CTRL-V Pastes from the clipboard (in any mode)767 <S-Insert> idem768 CTRL-Z undo769 CTRL-Y redo770 <M-Space> system menu771 CTRL-A select all772 <C-Tab> next window, CTRL-W w773 <C-F4> close window, CTRL-W c774 775Additionally:776- ":behave mswin" is used |:behave|777- syntax highlighting is enabled778- filetype detection is enabled, filetype plugins and indenting is enabled779- in a text file 'textwidth' is set to 78780 781One hint: If you want to go to Normal mode to be able to type a sequence of782commands, use CTRL-L. |i_CTRL-L|783 784There is no way to stop "easy mode", you need to exit Vim.785 786==============================================================================7874. Initialization *initialization* *startup*788 789This section is about the non-GUI version of Vim. See |gui-fork| for790additional initialization when starting the GUI.791 792At startup, Vim checks environment variables and files and sets values793accordingly. Vim proceeds in this order:794 7951. Set the 'shell' and 'term' option *SHELL* *COMSPEC* *TERM*796 The environment variable SHELL, if it exists, is used to set the797 'shell' option. On Win32, the COMSPEC variable is used798 if SHELL is not set.799 The environment variable TERM, if it exists, is used to set the 'term'800 option. However, 'term' will change later when starting the GUI (step801 8 below).802 8032. Process the arguments804 The options and file names from the command that start Vim are805 inspected.806 The |-V| argument can be used to display or log what happens next,807 useful for debugging the initializations.808 The |--cmd| arguments are executed.809 Buffers are created for all files (but not loaded yet).810 8113. Execute Ex commands, from environment variables and/or files812 An environment variable is read as one Ex command line, where multiple813 commands must be separated with '|' or "<NL>".814 *vimrc* *exrc*815 A file that contains initialization commands is called a "vimrc" file.816 Each line in a vimrc file is executed as an Ex command line. It is817 sometimes also referred to as "exrc" file. They are the same type of818 file, but "exrc" is what Vi always used, "vimrc" is a Vim specific819 name. Also see |vimrc-intro|.820 821 Places for your personal initializations:822 Unix $HOME/.vimrc, $HOME/.vim/vimrc823 or $XDG_CONFIG_HOME/vim/vimrc824 MS-Windows $HOME/_vimrc, $HOME/vimfiles/vimrc825 or $VIM/_vimrc826 Amiga s:.vimrc, home:.vimrc, home:vimfiles:vimrc827 or $VIM/.vimrc828 Haiku $HOME/config/settings/vim/vimrc829 830 The files are searched in the order specified above and only the first831 one that is found is read.832 833 RECOMMENDATION: Put all your Vim configuration stuff in the834 $HOME/.vim/ directory ($HOME/vimfiles/ for MS-Windows). That makes it835 easy to copy it to another system.836 837 If Vim was started with "-u filename", the file "filename" is used.838 All following initializations until 4. are skipped. `$MYVIMRC` and839 `$MYVIMDIR` are not set (but `$MYVIMDIR` will be set, if 'rtp' is840 updated).841 "vim -u NORC" can be used to skip these initializations without842 reading a file. "vim -u NONE" also skips loading plugins. |-u|843 844 If Vim was started in Ex mode with the "-s" argument, all following845 initializations until 4. are skipped. Only the "-u" option is846 interpreted.847 848 The |v:vim_did_init| variable is set to 1 after this step is finished.849 850 *evim.vim*851 a. If Vim was started as |evim| or |eview| or with the |-y| argument, the852 script $VIMRUNTIME/evim.vim will be loaded.853 *system-vimrc*854 b. For Unix, MS-Windows, VMS, Macintosh and Amiga the system vimrc file855 is read for initializations. The path of this file is shown with the856 ":version" command. Mostly it's "$VIM/vimrc". Note that this file is857 ALWAYS read in 'compatible' mode, since the automatic resetting of858 'compatible' is only done later. Add a ":set nocp" command if you859 like. For the Macintosh the $VIMRUNTIME/macmap.vim is read.860 861 *VIMINIT* *.vimrc* *_vimrc* *EXINIT* *.exrc* *_exrc*862 *$MYVIMRC* *$MYVIMDIR*863 c. Five places are searched for initializations. The first that exists864 is used, the others are ignored. The `$MYVIMRC` environment variable is865 set to the file that was first found, unless `$MYVIMRC` was already set866 when using VIMINIT. The `$MYVIMDIR` environment variable is867 set to the personal 'rtp' directory, however it is not verified868 that the directory actually exists.869 I The environment variable VIMINIT (see also |compatible-default|) (*)870 The value of $VIMINIT is used as an Ex command line.871 II The user vimrc file(s):872 "$HOME/.vimrc" (for Unix) (*)873 "$HOME/.vim/vimrc" (for Unix) (*)874 "$XDG_CONFIG_HOME/vim/vimrc" (for Unix) (*)875 "s:.vimrc" (for Amiga) (*)876 "home:.vimrc" (for Amiga) (*)877 "home:vimfiles:vimrc" (for Amiga) (*)878 "$VIM/.vimrc" (for Amiga) (*)879 "$HOME/_vimrc" (for Win32) (*)880 "$HOME/vimfiles/vimrc" (for Win32) (*)881 "$VIM/_vimrc" (for Win32) (*)882 "$HOME/config/settings/vim/vimrc" (for Haiku) (*)883 884 Note: For Unix and Amiga, when ".vimrc" does not exist,885 "_vimrc" is also tried, in case an MS-DOS compatible file886 system is used. For MS-Windows ".vimrc" is checked after887 "_vimrc", in case long file names are used.888 Note: For Win32, "$HOME" is checked first. If no "_vimrc" or889 ".vimrc" is found there, "$VIM" is tried. See |$VIM| for when890 $VIM is not set.891 III The environment variable EXINIT.892 The value of $EXINIT is used as an Ex command line.893 IV The user exrc file(s). Same as for the user vimrc file, but with894 "vimrc" replaced by "exrc". But only one of ".exrc" and "_exrc"895 is used, depending on the system. And without the (*)!896 V The default vimrc file, $VIMRUNTIME/defaults.vim. This sets up897 options values and has "syntax on" and "filetype on" commands,898 which is what most new users will want. See |defaults.vim|.899 900 d. If the 'exrc' option is on (which is NOT the default), the current901 directory is searched for three files. The first that exists is used,902 the others are ignored.903 - The file ".vimrc" (for Unix, Amiga) (*)904 "_vimrc" (for Win32) (*)905 - The file "_vimrc" (for Unix, Amiga) (*)906 ".vimrc" (for Win32) (*)907 - The file ".exrc" (for Unix, Amiga)908 "_exrc" (for Win32)909 910 (*) Using this file or environment variable will cause 'compatible' to be911 off by default. See |compatible-default|.912 913 Note: When using the |mzscheme| interface, it is initialized after loading914 the vimrc file. Changing 'mzschemedll' later has no effect.915 9164. Load the plugin scripts. *load-plugins*917 This does the same as the command: >918 :runtime! plugin/**/*.vim919< The result is that all directories in the 'runtimepath' option will be920 searched for the "plugin" sub-directory and all files ending in ".vim"921 will be sourced (in alphabetical order per directory), also in922 subdirectories.923 However, directories in 'runtimepath' ending in "after" are skipped924 here and only loaded after packages, see below.925 Loading plugins won't be done when:926 - The 'loadplugins' option was reset in a vimrc file.927 - The |--noplugin| command line argument is used.928 - The |--clean| command line argument is used.929 - The "-u NONE" command line argument is used |-u|.930 - When Vim was compiled without the |+eval| feature.931 Note that using "-c 'set noloadplugins'" doesn't work, because the932 commands from the command line have not been executed yet. You can933 use "--cmd 'set noloadplugins'" or "--cmd 'set loadplugins'" |--cmd|.934 935 Packages are loaded. These are plugins, as above, but found in the936 "start" directory of each entry in 'packpath'. Every plugin directory937 found is added in 'runtimepath' and then the plugins are sourced. See938 |packages|.939 940 The plugins scripts are loaded, as above, but now only the directories941 ending in "after" are used. Note that 'runtimepath' will have changed942 if packages have been found, but that should not add a directory943 ending in "after".944 9455. Set 'shellpipe' and 'shellredir'946 The 'shellpipe' and 'shellredir' options are set according to the947 value of the 'shell' option, unless they have been set before.948 This means that Vim will figure out the values of 'shellpipe' and949 'shellredir' for you, unless you have set them yourself.950 9516. Set 'updatecount' to zero, if "-n" command argument used.952 9537. Set binary options954 If the "-b" flag was given to Vim, the options for binary editing will955 be set now. See |-b|.956 9578. Perform GUI initializations958 Only when starting "gvim", the GUI initializations will be done. See959 |gui-init|.960 9619. Read the viminfo file962 If the 'viminfo' option is not empty, the viminfo file is read. See963 |viminfo-file|.964 96510. Read the quickfix file966 If the "-q" flag was given to Vim, the quickfix file is read. If this967 fails, Vim exits.968 96911. Open all windows970 When the |-o| flag was given, windows will be opened (but not971 displayed yet).972 When the |-p| flag was given, tab pages will be created (but not973 displayed yet).974 When switching screens, it happens now. Redrawing starts.975 If the "-q" flag was given to Vim, the first error is jumped to.976 Buffers for all windows will be loaded, without triggering |BufAdd|977 autocommands.978 97912. Execute startup commands980 If a "-t" flag was given to Vim, the tag is jumped to.981 The commands given with the |-c| and |+cmd| arguments are executed.982 If the 'insertmode' option is set, Insert mode is entered.983 The starting flag is reset, has("vim_starting") will now return zero.984 The |v:vim_did_enter| variable is set to 1.985 The |VimEnter| autocommands are executed.986 987The `$MYVIMRC` or `$MYGVIMRC` environment variable will be set to the first found988vimrc and/or gvimrc file while `$MYVIMDIR` is set to the users personal runtime989directory 'rtp' (typically the first entry in 'runtimepath'). If 'rtp'990changes, `$MYVIMDIR` will be updated.991Note: These environment variables resolve symbolic links, but 'rtp' does not.992 993 994Some hints on using initializations ~995 996Standard setup:997Create a vimrc file to set the default settings and mappings for all your edit998sessions. Put it in a place so that it will be found by 3b.:999 ~/.vimrc (Unix)1000 s:.vimrc (Amiga)1001 $VIM\_vimrc (Win32)1002 ~/config/settings/vim/vimrc (Haiku)1003 1004Note that creating a vimrc file will cause the 'compatible' option to be off1005by default. See |compatible-default|.1006 1007Local setup:1008Put all commands that you need for editing a specific directory only into a1009vimrc file and place it in that directory under the name ".vimrc" ("_vimrc"1010for Win32). NOTE: To make Vim look for these special files you have to turn1011on the option 'exrc'. See |trojan-horse| too.1012 1013System setup:1014This only applies if you are managing a Unix system with several users and1015want to set the defaults for all users. Create a vimrc file with commands1016for default settings and mappings and put it in the place that is given with1017the ":version" command.1018 1019 1020Saving the current state of Vim to a file ~1021 1022Whenever you have changed values of options or when you have created a1023mapping, then you may want to save them in a vimrc file for later use. See1024|save-settings| about saving the current state of settings to a file.1025 1026 1027Avoiding setup problems for Vi users ~1028 1029Vi uses the variable EXINIT and the file "~/.exrc". So if you do not want to1030interfere with Vi, then use the variable VIMINIT and the file "vimrc" instead.1031 1032 1033Amiga environment variables ~1034 1035On the Amiga, two types of environment variables exist. The ones set with the1036DOS 1.3 (or later) setenv command are recognized. See the AmigaDos 1.31037manual. The environment variables set with the old Manx Set command (before1038version 5.0) are not recognized.1039 1040 1041MS-Windows line separators ~1042 1043On MS-Windows, Vim assumes that all the vimrc files have <CR><NL> pairs as1044line separators. This will give problems if you have a file with only <NL>s1045and have a line like ":map xx yy^M". The trailing ^M will be ignored.1046 1047 1048Vi compatible default value ~1049 *compatible-default*1050When Vim starts, the 'compatible' option is on. This will be used when Vim1051starts its initializations. But as soon as:1052- a user vimrc file is found, or1053- a vimrc file in the current directory is found, or1054- the "VIMINIT" environment variable is set, or1055- the "-N" command line argument is given, or1056- the "--clean" command line argument is given, or1057- the |defaults.vim| script is loaded, or1058- a gvimrc file was found,1059then the option will be set to 'nocompatible'.1060 1061Note that this does NOT happen when a system-wide vimrc file was found.1062 1063This has the side effect of setting or resetting other options (see1064'compatible'). But only the options that have not been set or reset will be1065changed. This has the same effect like the value of 'compatible' had this1066value when starting Vim.1067 1068'compatible' is NOT reset, and |defaults.vim| is not loaded:1069- when Vim was started with the |-u| command line argument, especially with1070 "-u NONE", or1071- when started with the |-C| command line argument, or1072- when the name of the executable ends in "ex". (This has been done to make1073 Vim behave like "ex", when it is started as "ex")1074 1075But there is a side effect of setting or resetting 'compatible' at the moment1076a .vimrc file is found: Mappings are interpreted the moment they are1077encountered. This makes a difference when using things like "<CR>". If the1078mappings depend on a certain value of 'compatible', set or reset it before1079giving the mapping.1080 1081 1082Defaults without a .vimrc file ~1083 *defaults.vim* *E1187*1084If Vim is started normally and no user vimrc file is found, the1085$VIMRUNTIME/defaults.vim script is loaded. This will set 'compatible' off,1086switch on syntax highlighting and a few more things. See the script for1087details. NOTE: this is done since Vim 8.0, not in Vim 7.4. (it was added in1088patch 7.4.2111 to be exact).1089 1090This should work well for new Vim users. If you create your own .vimrc, it is1091recommended to add these lines somewhere near the top: >1092 unlet! skip_defaults_vim1093 source $VIMRUNTIME/defaults.vim1094Then Vim works like before you had a .vimrc.1095Copying $VIMRUNTIME/vimrc_example.vim to your .vimrc is another way to do1096this. Alternatively, you can copy defaults.vim to your .vimrc and modify it1097(but then you won't get updates when it changes).1098 1099If you don't like some of the defaults, you can still source defaults.vim and1100revert individual settings. See the defaults.vim file for hints on how to1101revert each item.1102 *skip_defaults_vim*1103If you use a system-wide vimrc and don't want defaults.vim to change settings,1104set the "skip_defaults_vim" variable. If this was set and you want to load1105defaults.vim from your .vimrc, first unlet skip_defaults_vim, as in the1106example above.1107 1108 1109 *xdg-base-dir* *$XDG_CONFIG_HOME*1110XDG Base Directory Specification ~1111 1112The XDG Base Directory Specification aims to define a standard location for1113configuration files used by applications. This is mainly done to prevent1114the legacy behavior of dumping everything into the user's home directory.1115The specification can be found online at1116https://specifications.freedesktop.org/basedir-spec/latest/1117 1118The location of this standard configuration directory is configurable by the1119user, using an environment variable but should also give fallback in case1120those variables weren't set.1121 1122This is not an exhaustive list of those directories:1123 Environment var Default location Description ~1124 `$XDG_CACHE_HOME` $HOME/.cache Ephemeral data files1125 `$XDG_CONFIG_HOME` $HOME/.config Configuration files1126 `$XDG_DATA_HOME` $HOME/.local/share Persistent data files1127 `$XDG_STATE_HOME` $HOME/.local/state State data files1128 1129 *xdg.vim*1130Vim itself will only use the $XDG_CONFIG_HOME directory. Support for the1131other XDG directories is provided by the "$VIMRUNTIME/xdg.vim" script.1132Note: xdg.vim is only effective if the $XDG_CONFIG_HOME/vim directory (or1133its default fallback) exists. By default, it only sets the 'viminfofile'1134option. Other option settings are commented out, see the script for1135details on how to enable them.1136 1137 *xdg-vimrc*1138Vim, on Unix systems, will look at `$XDG_CONFIG_HOME/vim/vimrc` for its1139configuration (see |vimrc|) but it will source it only if no other1140initialization file is found in `$HOME` or `$HOME/.vim` (thus making this1141feature backward compatible). However, if you want to migrate to use1142`$XDG_CONFIG_HOME/vim/` directory, you will have to move away your `~/.vimrc`1143and `~/.vim/vimrc` file.1144 1145 *xdg-runtime*1146When the |xdg-vimrc| is used the 'runtimepath' and 'packpath' options will be1147modified accordingly to respect the |xdg-base-dir|: >1148 1149 "$XDG_CONFIG_HOME/vim,$VIM/vimfiles,$VIMRUNTIME,$VIM/vimfiles/after,1150 $XDG_CONFIG_HOME/vim/after"1151<1152 1153Avoiding trojan horses ~1154 *trojan-horse*1155While reading the "vimrc" or the "exrc" file in the current directory, some1156commands can be disabled for security reasons by setting the 'secure' option.1157This is always done when executing the command from a tags file. Otherwise,1158it would be possible that you accidentally use a vimrc or tags file that1159somebody else created and contains nasty commands. The disabled commands are1160the ones that start a shell, the ones that write to a file, and ":autocmd".1161The ":map" commands are echoed, so you can see which keys are being mapped.1162 If you want Vim to execute all commands in a local vimrc file, you1163can reset the 'secure' option in the EXINIT or VIMINIT environment variable or1164in the global "exrc" or "vimrc" file. This is not possible in "vimrc" or1165"exrc" in the current directory, for obvious reasons.1166 On Unix systems, this only happens if you are not the owner of the1167vimrc file. Warning: If you unpack an archive that contains a vimrc or exrc1168file, it will be owned by you. You won't have the security protection. Check1169the vimrc file before you start Vim in that directory, or reset the 'exrc'1170option. Some Unix systems allow a user to do "chown" on a file. This makes1171it possible for another user to create a nasty vimrc and make you the owner.1172Be careful!1173 When using tag search commands, executing the search command (the last1174part of the line in the tags file) is always done in secure mode. This works1175just like executing a command from a vimrc/exrc in the current directory.1176 1177 1178If Vim startup is slow ~1179 *slow-start*1180If Vim takes a long time to start up, use the |--startuptime| argument to find1181out what happens. There are a few common causes:1182- If the Unix version was compiled with the GUI and/or X11 (check the output1183 of ":version" for "+GUI" and "+X11"), it may need to load shared libraries1184 and connect to the X11 server. Try compiling a version with GUI and X111185 disabled. This also should make the executable smaller.1186 Use the |-X| command line argument to avoid connecting to the X server when1187 running in a terminal.1188- If you have "viminfo" enabled, the loading of the viminfo file may take a1189 while. You can find out if this is the problem by disabling viminfo for a1190 moment (use the Vim argument "-i NONE", |-i|). Try reducing the number of1191 lines stored in a register with ":set viminfo='20,<50,s10". |viminfo-file|.1192 1193 1194Intro message ~1195 *:intro*1196When Vim starts without a file name, an introductory message is displayed (for1197those who don't know what Vim is). It is removed as soon as the display is1198redrawn in any way. To see the message again, use the ":intro" command (if1199there is not enough room, you will see only part of it).1200 To avoid the intro message on startup, add the 'I' flag to 'shortmess'.