diff options
Diffstat (limited to 'runtime/doc/starting.txt')
| -rw-r--r-- | runtime/doc/starting.txt | 1418 |
1 files changed, 1418 insertions, 0 deletions
diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt new file mode 100644 index 0000000000..160bcb914d --- /dev/null +++ b/runtime/doc/starting.txt @@ -0,0 +1,1418 @@ +*starting.txt* For Vim version 7.0aa. Last change: 2004 May 28 + + + VIM REFERENCE MANUAL by Bram Moolenaar + + +Starting Vim *starting* + +1. Vim arguments |vim-arguments| +2. Vim on the Amiga |starting-amiga| +3. Running eVim |evim-keys| +4. Initialization |initialization| +5. $VIM and $VIMRUNTIME |$VIM| +6. Suspending |suspend| +7. Saving settings |save-settings| +8. Views and Sessions |views-sessions| +9. The viminfo file |viminfo-file| + +============================================================================== +1. Vim arguments *vim-arguments* + +Most often, Vim is started to edit a single file with the command + + vim filename *-vim* + +More generally, Vim is started with: + + vim [option | filename] .. + +Option arguments and file name arguments can be mixed, and any number of them +can be given. However, watch out for options that take an argument. + +For compatibility with various Vi versions, see |cmdline-arguments|. + +Exactly one out of the following five items may be used to choose how to +start editing: + + *-file* *---* +filename One or more file names. The first one will be the current + file and read into the buffer. The cursor will be positioned + on the first line of the buffer. + To avoid a file name starting with a '-' being interpreted as + an option, precede the arglist with "--", e.g.: > + vim -- -filename +< All arguments after the "--" will be interpreted as file names, + no other options or "+command" argument can follow. + + *--* +- This argument can mean two things, depending on whether Ex + mode is to be used. + + Starting in Normal mode: > + vim - + ex -v - +< Start editing a new buffer, which is filled with text + that is read from stdin. The commands that would normally be + read from stdin will now be read from stderr. Example: > + find . -name "*.c" -print | vim - +< The buffer will be marked modified, because it contains text + that needs to be saved. Except when in readonly mode, then + the buffer is not marked modified. Example: > + ls | view - +< + Starting in Ex mode: > + ex - + vim -e - + exim - + vim -E +< Start editing in silent mode. See |-s-ex|. + + *-t* *-tag* +-t {tag} A tag. "tag" is looked up in the tags file, the associated + file becomes the current file, and the associated command is + executed. Mostly this is used for C programs, in which case + "tag" often is a function name. The effect is that the file + containing that function becomes the current file and the + cursor is positioned on the start of the function (see + |tags|). + + *-q* *-qf* +-q [errorfile] QuickFix mode. The file with the name [errorfile] is read + and the first error is displayed. See |quickfix|. + If [errorfile] is not given, the 'errorfile' option is used + for the file name. See 'errorfile' for the default value. + {not in Vi} + +(nothing) Without one of the four items above, Vim will start editing a + new buffer. It's empty and doesn't have a file name. + + +The startup mode can be changed by using another name instead of "vim", which +is equal to giving options: +ex vim -e Start in Ex mode (see |Ex-mode|). *ex* +exim vim -E Start in improved Ex mode (see |Ex-mode|). *exim* + (normally not installed) +view vim -R Start in read-only mode (see |-R|). *view* +gvim vim -g Start the GUI (see |gui|). *gvim* +gex vim -eg Start the GUI in Ex mode. *gex* +gview vim -Rg Start the GUI in read-only mode. *gview* +rvim vim -Z Like "vim", but in restricted mode (see |-Z|) *rvim* +rview vim -RZ Like "view", but in restricted mode. *rview* +rgvim vim -gZ Like "gvim", but in restricted mode. *rgvim* +rgview vim -RgZ Like "gview", but in restricted mode. *rgview* +evim vim -y Easy Vim: set 'insertmode' (see |-y|) *evim* +eview vim -yR Like "evim" in read-only mode *eview* +vimdiff vim -d Start in diff mode |diff-mode| +gvimdiff vim -gd Start in diff mode |diff-mode| + +Additional characters may follow, they are ignored. For example, you can have +"gvim-5" to start the GUI. You must have an executable by that name then, of +course. + +On Unix, you would normally have one executable called Vim, and links from the +different startup-names to that executable. If your system does not support +links and you do not want to have several copies of the executable, you could +use an alias instead. For example: > + alias view vim -R + alias gvim vim -g +< + *startup-options* +The option arguments may be given in any order. Single-letter options can be +combined after one dash. There can be no option arguments after the "--" +argument. + +On VMS all option arguments are assumed to be lowercase, unless preceded with +a slash. Thus "-R" means recovery and "-/R" readonly. + +--help *-h* *--help* +-h Give usage (help) message and exit. {not in Vi} + See |info-message| about capturing the text. + + *--version* +--version Print version information and exit. Same output as for + |:version| command. {not in Vi} + See |info-message| about capturing the text. + + *--noplugin* +--noplugin Skip loading plugins. Resets the 'loadplugins' option. + {not in Vi} + Note that the |-u| argument may also disable loading plugins: + argument load vimrc files load plugins ~ + (nothing) yes yes + -u NONE no no + -u NORC no yes + --noplugin yes no + + *--literal* +--literal Take file names literally, don't expand wildcards. Not needed + for Unix, because Vim always takes file names literally (the + shell expands wildcards). + Applies to all the names, also the ones that come before this + argument. + + *-+* ++[num] The cursor will be positioned on line "num" for the first + file being edited. If "num" is missing, the cursor will be + positioned on the last line. + + *-+/* ++/{pat} The cursor will be positioned on the first line containing + "pat" in the first file being edited (see |pattern| for the + available search patterns). + ++{command} *-+c* *-c* +-c {command} {command} will be executed after the first file has been + read (and after autocommands and modelines for that file have + been processed). "command" is interpreted as an Ex command. + If the "command" contains spaces, it must be enclosed in + double quotes (this depends on the shell that is used). + Example: > + vim "+set si" main.c + vim "+find stdio.h" + vim -c "set ff=dos" -c wq mine.mak +< + Note: You can use up to 10 "+" or "-c" arguments in a Vim + command. They are executed in the order given. A "-S" + argument counts as a "-c" argument as well. + {Vi only allows one command} + +--cmd {command} *--cmd* + {command} will be executed before processing any vimrc file. + Otherwise it acts like -c {command}. You can use up to 10 of + these commands, independently from "-c" commands. + {not in Vi} + + *-S* +-S {file} The {file} will be sourced after the first file has been read. + This is an easy way to do the equivalent of: > + -c "source {file}" +< It can be mixed with "-c" arguments and repeated like "-c". + The limit of 10 "-c" arguments applies here as well. + {file} cannot start with a "-". + {not in Vi} + +-S Works like "-S Session.vim". Only when used as the last + argument or when another "-" option follows. + + *-r* +-r Recovery mode. Without a file name argument, a list of + existing swap files is given. With a file name, a swap file + is read to recover a crashed editing session. See + |crash-recovery|. + + *-L* +-L Same as -r. {only in some versions of Vi: "List recoverable + edit sessions"} + + *-R* +-R Readonly mode. The 'readonly' option will be set for all the + files being edited. You can still edit the buffer, but will + be prevented from accidentally overwriting a file. If you + forgot that you are in View mode and did make some changes, + you can overwrite a file by adding an exclamation mark to + the Ex command, as in ":w!". The 'readonly' option can be + reset with ":set noro" (see the options chapter, |options|). + Subsequent edits will not be done in readonly mode. Calling + the executable "view" has the same effect as the -R argument. + The 'updatecount' option will be set to 10000, meaning that + the swap file will not be updated automatically very often. + + *-m* +-m Modifications not allowed to be written. The 'write' option + will be reset, so that writing files is disabled. However, + the 'write' option can be set to enable writing again. + {not in Vi} + + *-M* +-M Modifications not allowed. The 'modifiable' option will be + reset, so that changes are not allowed. The 'write' option + will be reset, so that writing files is disabled. However, + the 'modifiable' and 'write' options can be set to enable + changes and writing. + {not in Vi} + + *-Z* *restricted-mode* *E145* +-Z Restricted mode. All commands that make use of an external + shell are disabled. This includes suspending with CTRL-Z, + ":sh", filtering, the system() function, backtick expansion, + etc. + {not in Vi} + + *-g* +-g Start Vim in GUI mode. See |gui|. {not in Vi} + + *-v* +-v Start Ex in Vi mode. Only makes a difference when the + executable is called "ex" or "gvim". For gvim the GUI is not + started if possible. + + *-e* +-e Start Vim in Ex mode |Q|. Only makes a difference when the + executable is not called "ex". + + *-E* +-E Start Vim in improved Ex mode |gQ|. Only makes a difference + when the executable is not called "exim". + {not in Vi} + + *-s-ex* +-s Silent or batch mode. Only when Vim was started as "ex" or + when preceded with the "-e" argument. Otherwise see |-s|, + which does take an argument while this use of "-s" doesn't. + To be used when Vim is used to execute Ex commands from a file + instead of a terminal. Switches off most prompts and + informative messages. Also warnings and error messages. + But ":print" output is displayed. And when 'verbose' is + non-zero messages are printed (for debugging). + If Vim appears to be stuck try typing "qa!<Enter>". You don't + get a prompt thus you can't see Vim is waiting for you to type + something. + Initializations are skipped (except the ones given with the + "-u" argument). + Example: > + vim -e -s < thefilter thefile +< + *-b* +-b Binary mode. File I/O will only recognize <NL> to separate + lines. The 'expandtab' option will be reset. The 'textwidth' + option is set to 0. 'modeline' is reset. The 'binary' option + is set. This is done after reading the vimrc/exrc files but + before reading any file in the arglist. See also + |edit-binary|. {not in Vi} + + *-l* +-l Lisp mode. Sets the 'lisp' and 'showmatch' options on. + + *-A* +-A Arabic mode. Sets the 'arabic' option on. (Only when + compiled with the |+arabic| features (which include + |+rightleft|), otherwise Vim gives an error message + and exits. {not in Vi} + + *-F* +-F Farsi mode. Sets the 'fkmap' and 'rightleft' options on. + (Only when compiled with |+rightleft| and |+farsi| features, + otherwise Vim gives an error message and exits). {not in Vi} + + *-H* +-H Hebrew mode. Sets the 'hkmap' and 'rightleft' options on. + (Only when compiled with the |+rightleft| feature, otherwise + Vim gives an error message and exits). {not in Vi} + + *-V* *verbose* +-V[N] Verbose. Sets the 'verbose' option to [N] (default: 10). + Messages will be given for each file that is ":source"d and + for reading or writing a viminfo file. Can be used to find + out what is happening upon startup and exit. {not in Vi} + + *-D* +-D Debugging. Go to debugging mode when executing the first + command from a script. |debug-mode| + {not available when compiled without the |+eval| feature} + {not in Vi} + + *-C* +-C Compatible mode. Sets the 'compatible' option. You can use + this to get 'compatible', even though a .vimrc file exists. + But the command ":set nocompatible" overrules it anyway. + Also see |compatible-default|. {not in Vi} + + *-N* +-N Not compatible mode. Resets the 'compatible' option. You can + use this to get 'nocompatible', when there is no .vimrc file. + Also see |compatible-default|. {not in Vi} + + *-y* *easy* +-y Easy mode. Implied for |evim| and |eview|. Starts with + 'insertmode' set and behaves like a click-and-type editor. + This sources the script $VIMRUNTIME/evim.vim. Mappings are + set up to work like most click-and-type editors, see + |evim-keys|. The GUI is started when available. + {not in Vi} + + *-n* +-n No swap file will be used. Recovery after a crash will be + impossible. Handy if you want to view or edit a file on a + very slow medium (e.g., a floppy). + Can also be done with ":set updatecount=0". You can switch it + on again by setting the 'updatecount' option to some value, + e.g., ":set uc=100". + 'updatecount' is set to 0 AFTER executing commands from a + vimrc file, but before the GUI initializations. Thus it + overrides a setting for 'updatecount' in a vimrc file, but not + in a gvimrc file. See |startup|. + When you want to reduce accesses to the disk (e.g., for a + laptop), don't use "-n", but set 'updatetime' and + 'updatecount' to very big numbers, and type ":preserve" when + you want to save your work. This way you keep the possibility + for crash recovery. + {not in Vi} + + *-o* +-o[N] Open N windows, split horizontally. If [N] is not given, + one window is opened for every file given as argument. If + there is not enough room, only the first few files get a + window. If there are more windows than arguments, the last + few windows will be editing an empty file. + {not in Vi} + + *-O* +-O[N] Open N windows, split vertically. Otherwise it's like -o. + If both the -o and the -O option are given, the last one on + the command line determines how the windows will be split. + {not in Vi} + + *-T* +-T {terminal} Set the terminal type to "terminal". This influences the + codes that Vim will send to your terminal. This is normally + not needed, because Vim will be able to find out what type + of terminal you are using (See |terminal-info|). {not in Vi} + + *-d* +-d Start in diff mode, like |vimdiff|. + {not in Vi} {not available when compiled without the |+diff| + feature} + +-d {device} Only on the Amiga and when not compiled with the |+diff| + feature. Works like "-dev". + *-dev* +-dev {device} Only on the Amiga: The {device} is opened to be used for + editing. + Normally you would use this to set the window position and + size: "-d con:x/y/width/height", e.g., + "-d con:30/10/600/150". But you can also use it to start + editing on another device, e.g., AUX:. {not in Vi} + *-f* +-f Amiga: Do not restart Vim to open a new window. This + option should be used when Vim is started by a program that + will wait for the edit session to finish (e.g., mail or + readnews). See |amiga-window|. + + GUI: Do not disconnect from the program that started Vim. + 'f' stands for "foreground". If omitted, the GUI forks a new + process and exits the current one. "-f" should be used when + gvim is started by a program that will wait for the edit + session to finish (e.g., mail or readnews). If you want gvim + never to fork, include 'f' in 'guioptions' in your .gvimrc. + Careful: You can use "-gf" to start the GUI in the foreground, + but "-fg" is used to specify the foreground color. |gui-fork| + {not in Vi} + + *--nofork* +--nofork GUI: Do not fork. Same as |-f|. + *-u* *E282* +-u {vimrc} The file {vimrc} is read for initializations. Most other + initializations are skipped; see |initialization|. This can + be used to start Vim in a special mode, with special + mappings and settings. A shell alias can be used to make + this easy to use. For example: > + alias vimc vim -u ~/.c_vimrc !* +< Also consider using autocommands; see |autocommand|. + When {vimrc} is equal to "NONE" (all uppercase), all + initializations from files and environment variables are + skipped, including reading the .gvimrc file when the GUI + starts. Loading plugins is also skipped. + When {vimrc} is equal to "NORC" (all uppercase), this has the + same effect as "NONE", but loading plugins is not skipped. + Using the "-u" argument has the side effect that the + 'compatible' option will be on by default. This can have + unexpected effects. See |'compatible'|. + {not in Vi} + + *-U* *E230* +-U {gvimrc} The file "gvimrc" is read for initializations when the GUI + starts. Other GUI initializations are skipped. When {gvimrc} + is equal to "NONE", no file is read for initializations at + all. + Exception: Reading the system-wide menu file is always done. + {not in Vi} + + *-i* +-i {viminfo} The file "viminfo" is used instead of the default viminfo + file. If the name "NONE" is used (all uppercase), no viminfo + file is read or written, even if 'viminfo' is set or when + ":rv" or ":wv" are used. See also |viminfo-file|. + {not in Vi} + + *-x* +-x Use encryption to read/write files. Will prompt for a key, + which is then stored in the 'key' option. All writes will + then use this key to encrypt the text. The '-x' argument is + not needed when reading a file, because there is a check if + the file that is being read has been encrypted, and Vim asks + for a key automatically. |encryption| + + *-X* +-X Do not try connecting to the X server to get the current + window title and copy/paste using the X clipboard. This + avoids a long startup time when running Vim in a terminal + emulator and the connection to the X server is slow. + Only makes a difference on Unix or VMS, when compiled with the + |+X11| feature. Otherwise it's ignored. + To disable the connection only for specific terminals, see the + 'clipboard' option. + When the X11 Session Management Protocol (XSMP) handler has + been built in, the -X option also disables that connection as + it, too, may have undesirable delays. + When the connection is desired later anyway (e.g., for + client-server messages), call the |serverlist()| function. + This does not enable the XSMP handler though. + {not in Vi} + + *-s* +-s {scriptin} The script file "scriptin" is read. The characters in the + file are interpreted as if you had typed them. The same can + be done with the command ":source! {scriptin}". If the end + of the file is reached before the editor exits, further + characters are read from the keyboard. Only works when not + started in Ex mode, see |-s-ex|. See also |complex-repeat|. + {not in Vi} + + *-w* +-w {scriptout} All the characters that you type are recorded in the file + "scriptout", until you exit Vim. This is useful if you want + to create a script file to be used with "vim -s" or + ":source!". When the "scriptout" file already exists, new + characters are appended. See also |complex-repeat|. + {not in Vi} + + *-W* +-W {scriptout} Like -w, but do not append, overwrite an existing file. + {not in Vi} + + *-w_nr* +-w{number} Does nothing. This was included for Vi-compatibility. In Vi + it sets the 'window' option, which is not implemented in Vim. + +--remote [+{cmd}] {file} ... + Open the {file} in another Vim that functions as a server. + Any non-file arguments must come before this. + See |--remote|. {not in Vi} + +--remote-silent [+{cmd}] {file} ... + Like --remote, but don't complain if there is no server. + See |--remote-silent|. {not in Vi} + +--remote-wait [+{cmd}] {file} ... + Like --remote, but wait for the server to finish editing the + file(s). + See |--remote-wait|. {not in Vi} + +--remote-wait-silent [+{cmd}] {file} ... + Like --remote-wait, but don't complain if there is no server. + See |--remote-wait-silent|. {not in Vi} + +--servername {name} + Specify the name of the Vim server to send to or to become. + See |--servername|. {not in Vi} + +--remote-send {keys} + Send {keys} to a Vim server and exit. + See |--remote-send|. {not in Vi} + +--remote-expr {expr} + Evaluate {expr} in another Vim that functions as a server. + The result is printed on stdout. + See |--remote-expr|. {not in Vi} + +--serverlist Output a list of Vim server names and exit. See + See |--serverlist|. {not in Vi} + +--socketid {id} *--socketid* + GTK+ GUI Vim only. Make gvim try to use GtkPlug mechanism, so + that it runs inside another window. See |gui-gtk-socketid| + for details. {not in Vi} + +--echo-wid *--echo-wid* + GTK+ GUI Vim only. Make gvim echo the Window ID on stdout, + which can be used to run gvim in a kpart widget. The format + of the output is: > + WID: 12345\n +< {not in Vi} + +--role {role} *--role* + GTK+ 2 GUI only. Set the role of the main window to {role}. + The window role can be used by a window manager to uniquely + identify a window, in order to restore window placement and + such. The --role argument is passed automatically when + restoring the session on login. See |gui-gnome-session| + {not in Vi} + +-P {parent-title} *-P* *MDI* *E671* *E672* + Win32 only: Specify the title of the parent application. When + possible, Vim will run in an MDI window inside the + application. + {parent-title} must appear in the window title of the parent + application. Make sure that it is specific enough. + Note that the implementation is still primitive. It won't + work with all applications and the menu doesn't work. + +-nb *-nb* +-nb={fname} +-nb:{hostname}:{addr}:{password} + Attempt connecting to Netbeans and become an editor server for + it. The second form specifies a file to read connection info + from. The third form specifies the hostname, address and + password for connecting to Netbeans. |netbeans-run| + +Example for using a script file to change a name in several files: + Create a file "subs.vi" containing substitute commands and a :wq + command: > + :%s/Jones/Smith/g + :%s/Allen/Peter/g + :wq +< + Execute Vim on all files you want to change: > + + foreach i ( *.let ) vim -s subs.vi $i + +If the executable is called "view", Vim will start in Readonly mode. This is +useful if you can make a hard or symbolic link from "view" to "vim". +Starting in Readonly mode can also be done with "vim -R". + +If the executable is called "ex", Vim will start in "Ex" mode. This means it +will accept only ":" commands. But when the "-v" argument is given, Vim will +start in Normal mode anyway. + +Additional arguments are available on unix like systems when compiled with +X11 GUI support. See |gui-resources|. + +============================================================================== +2. Vim on the Amiga *starting-amiga* + +Starting Vim from the Workbench *workbench* +------------------------------- + +Vim can be started from the Workbench by clicking on its icon twice. It will +then start with an empty buffer. + +Vim can be started to edit one or more files by using a "Project" icon. The +"Default Tool" of the icon must be the full pathname of the Vim executable. +The name of the ".info" file must be the same as the name of the text file. +By clicking on this icon twice, Vim will be started with the file name as +current file name, which will be read into the buffer (if it exists). You can +edit multiple files by pressing the shift key while clicking on icons, and +clicking twice on the last one. The "Default Tool" for all these icons must +be the same. + +It is not possible to give arguments to Vim, other than file names, from the +workbench. + +Vim window *amiga-window* +---------- + +Vim will run in the CLI window where it was started. If Vim was started with +the "run" or "runback" command, or if Vim was started from the workbench, it +will open a window of its own. + +Technical detail: + To open the new window a little trick is used. As soon as Vim + recognizes that it does not run in a normal CLI window, it will + create a script file in "t:". This script file contains the same + command as the one Vim was started with, and an "endcli" command. + This script file is then executed with a "newcli" command (the "c:run" + and "c:newcli" commands are required for this to work). The script + file will hang around until reboot, or until you delete it. This + method is required to get the ":sh" and ":!" commands to work + correctly. But when Vim was started with the -f option (foreground + mode), this method is not used. The reason for this is that + when a program starts Vim with the -f option it will wait for Vim to + exit. With the script trick, the calling program does not know when + Vim exits. The -f option can be used when Vim is started by a mail + program which also waits for the edit session to finish. As a + consequence, the ":sh" and ":!" commands are not available when the + -f option is used. + +Vim will automatically recognize the window size and react to window +resizing. Under Amiga DOS 1.3, it is advised to use the fastfonts program, +"FF", to speed up display redrawing. + +============================================================================== +3. Running eVim *evim-keys* + +EVim runs Vim as click-and-type editor. This is very unlike the original Vi +idea. But it helps for people that don't use Vim often enough to learn the +commands. Hopefully they will find out that learning to use Normal mode +commands will make their editing much more effective. + +In Evim these options are changed from their default value: + + :set nocompatible Use Vim improvements + :set insertmode Remain in Insert mode most of the time + :set hidden Keep invisible buffers loaded + :set backup Keep backup files (not for VMS) + :set backspace=2 Backspace over everything + :set autoindent auto-indent new lines + :set history=50 keep 50 lines of Ex commands + :set ruler show the cursor position + :set incsearch show matches halfway typing a pattern + :set mouse=a use the mouse in all modes + :set hlsearch highlight all matches for a search pattern + :set whichwrap+=<,>,[,] <Left> and <Right> wrap around line breaks + :set guioptions-=a non-Unix only: don't do auto-select + +Key mappings: + <Down> moves by screen lines rather than file lines + <Up> idem + Q does "gq", formatting, instead of Ex mode + <BS> in Visual mode: deletes the selection + CTRL-X in Visual mode: Cut to clipboard + <S-Del> idem + CTRL-C in Visual mode: Copy to clipboard + <C-Insert> idem + CTRL-V Pastes from the clipboard (in any mode) + <S-Insert> idem + CTRL-Q do what CTRL-V used to do + CTRL-Z undo + CTRL-Y redo + <M-Space> system menu + CTRL-A select all + <C-Tab> next window, CTRL-W w + <C-F4> close window, CTRL-W c + +Additionally: +- ":behave mswin" is used |:behave| +- syntax highlighting is enabled +- filetype detection is enabled, filetype plugins and indenting is enabled +- in a text file 'textwidth' is set to 78 + +One hint: If you want to go to Normal mode to be able to type a sequence of +commands, use CTRL-L. |i_CTRL-L| + +============================================================================== +4. Initialization *initialization* *startup* + +This section is about the non-GUI version of Vim. See |gui-fork| for +additional initialization when starting the GUI. + +At startup, Vim checks environment variables and files and sets values +accordingly. Vim proceeds in this order: + +1. Set the 'shell' and 'term' option *SHELL* *COMSPEC* *TERM* + The environment variable SHELL, if it exists, is used to set the + 'shell' option. On MS-DOS and Win32, the COMSPEC variable is used + if SHELL is not set. + The environment variable TERM, if it exists, is used to set the 'term' + option. + +2. Process the arguments + The options and file names from the command that start Vim are + inspected. Buffers are created for all files (but not loaded yet). + +3. Execute Ex commands, from environment variables and/or files + An environment variable is read as one Ex command line, where multiple + commands must be separated with '|' or "<NL>". + *vimrc* *exrc* + A file that contains initialization commands is called a "vimrc" file. + Each line in a vimrc file is executed as an Ex command line. It is + sometimes also referred to as "exrc" file. They are the same type of + file, but "exrc" is what Vi always used, "vimrc" is a Vim specific + name. Also see |vimrc-intro|. + + Recommended place for your personal initializations: + Unix $HOME/.vimrc + OS/2 $HOME/.vimrc or $VIM/.vimrc (or _vimrc) + MS-DOS and Win32 $HOME/_vimrc or $VIM/_vimrc + Amiga s:.vimrc or $VIM/.vimrc + + If Vim was started with "-u filename", the file "filename" is used. + All following initializations until 4. are skipped. + "vim -u NORC" can be used to skip these initializations without + reading a file. "vim -u NONE" also skips loading plugins. |-u| + + If Vim was started in Ex mode with the "-s" argument, all following + initializations until 4. are skipped. Only the "-u" option is + interpreted. + *evim.vim* + a. If vim was started as |evim| or |eview| or with the |-y| argument, the + script $VIMRUNTIME/evim.vim will be loaded. + *system-vimrc* + b. For Unix, MS-DOS, MS-Windows, OS/2, VMS, Macintosh, RISC-OS and Amiga + the system vimrc file is read for initializations. The path of this + file is shown with the ":version" command. Mostly it's "$VIM/vimrc". + Note that this file is ALWAYS read in 'compatible' mode, since the + automatic resetting of 'compatible' is only done later. Add a ":set + nocp" command if you like. + + *VIMINIT* *.vimrc* *_vimrc* *EXINIT* *.exrc* *_exrc* + c. Four places are searched for initializations. The first that exists + is used, the others are ignored. + - The environment variable VIMINIT (see also |compatible-default|) (*) + The value of $VIMINIT is used as an Ex command line. + - The user vimrc file(s): + "$HOME/.vimrc" (for Unix and OS/2) (*) + "s:.vimrc" (for Amiga) (*) + "home:.vimrc" (for Amiga) (*) + "$VIM/.vimrc" (for OS/2 and Amiga) (*) + "$HOME/_vimrc" (for MS-DOS and Win32) (*) + "$VIM\_vimrc" (for MS-DOS and Win32) (*) + Note: For Unix, OS/2 and Amiga, when ".vimrc" does not exist, + "_vimrc" is also tried, in case an MS-DOS compatible file + system is used. For MS-DOS and Win32 ".vimrc" is checked + after "_vimrc", in case long file names are used. + Note: For MS-DOS and Win32, "$HOME" is checked first. If no + "_vimrc" or ".vimrc" is found there, "$VIM" is tried. + See |$VIM| for when $VIM is not set. + - The environment variable EXINIT. + The value of $EXINIT is used as an Ex command line. + - The user exrc file(s). Same as for the user vimrc file, but with + "vimrc" replaced by "exrc". But without the (*)! + + d. If the 'exrc' option is on (which is not the default), the current + directory is searched for four files. The first that exists is used, + the others are ignored. + - The file ".vimrc" (for Unix, Amiga and OS/2) (*) + "_vimrc" (for MS-DOS and Win32) (*) + - The file "_vimrc" (for Unix, Amiga and OS/2) (*) + ".vimrc" (for MS-DOS and Win32) (*) + - The file ".exrc" (for Unix, Amiga and OS/2) + "_exrc" (for MS-DOS and Win32) + - The file "_exrc" (for Unix, Amiga and OS/2) + ".exrc" (for MS-DOS and Win32) + + (*) Using this file or environment variable will cause 'compatible' to be + off by default. See |compatible-default|. + +4. Load the plugin scripts. *load-plugins* + This does the same as the command: > + :runtime! plugin/*.vim +< The result is that all directories in the 'runtimepath' option will be + searched for the "plugin" sub-directory and all files ending in ".vim" + will be sourced (in alphabetical order per directory). + Loading plugins won't be done when: + - The 'loadplugins' option was reset in a vimrc file. + - The |--noplugin| command line argument is used. + - The "-u NONE" command line argument is used |-u|. + - When Vim was compiled without the |+eval| feature. + Note that using "-c set noloadplugins" doesn't work, because the + commands from the command line have not been executed yet. + +5. Set 'shellpipe' and 'shellredir' + The 'shellpipe' and 'shellredir' options are set according to the + value of the 'shell' option, unless they have been set before. + This means that Vim will figure out the values of 'shellpipe' and + 'shellredir' for you, unless you have set them yourself. + +6. Set 'updatecount' to zero, if "-n" command argument used + +7. Set binary options + If the "-b" flag was given to Vim, the options for binary editing will + be set now. See |-b|. + +8. Perform GUI initializations + Only when starting "gvim", the GUI initializations will be done. See + |gui-init|. + +9. Read the viminfo file + If the 'viminfo' option is not empty, the viminfo file is read. See + |viminfo-file|. + +10. Read the quickfix file + If the "-q" flag was given to Vim, the quickfix file is read. If this + fails, Vim exits. + +11. Open all windows + When the |-o| flag was given, windows will be opened (but not + displayed yet). + When switching screens, it happens now. Redrawing starts. + If the "-q" flag was given to Vim, the first error is jumped to. + Buffers for all windows will be loaded. + +12. Execute startup commands + If a "-t" flag was given to Vim, the tag is jumped to. + The commands given with the |-c| and |+cmd| arguments are executed. + If the 'insertmode' option is set, Insert mode is entered. + The |VimEnter| autocommands are executed. + +Some hints on using initializations: + +Standard setup: +Create a vimrc file to set the default settings and mappings for all your edit +sessions. Put it in a place so that it will be found by 3b: + ~/.vimrc (Unix and OS/2) + s:.vimrc (Amiga) + $VIM\_vimrc (MS-DOS and Win32) +Note that creating a vimrc file will cause the 'compatible' option to be off +by default. See |compatible-default|. + +Local setup: +Put all commands that you need for editing a specific directory only into a +vimrc file and place it in that directory under the name ".vimrc" ("_vimrc" +for MS-DOS and Win32). NOTE: To make Vim look for these special files you +have to turn on the option 'exrc'. See |trojan-horse| too. + +System setup: +This only applies if you are managing a Unix system with several users and +want to set the defaults for all users. Create a vimrc file with commands +for default settings and mappings and put it in the place that is given with +the ":version" command. + +Saving the current state of Vim to a file: +Whenever you have changed values of options or when you have created a +mapping, then you may want to save them in a vimrc file for later use. See +|save-settings| about saving the current state of settings to a file. + +Avoiding setup problems for Vi users: +Vi uses the variable EXINIT and the file "~/.exrc". So if you do not want to +interfere with Vi, then use the variable VIMINIT and the file "vimrc" instead. + +Amiga environment variables: +On the Amiga, two types of environment variables exist. The ones set with the +DOS 1.3 (or later) setenv command are recognized. See the AmigaDos 1.3 +manual. The environment variables set with the old Manx Set command (before +version 5.0) are not recognized. + +MS-DOS line separators: +On MS-DOS-like systems (MS-DOS itself, Win32, and OS/2), Vim assumes that all +the vimrc files have <CR> <NL> pairs as line separators. This will give +problems if you have a file with only <NL>s and have a line like +":map xx yy^M". The trailing ^M will be ignored. + + *compatible-default* +When Vim starts, the 'compatible' option is on. This will be used when Vim +starts its initializations. But as soon as a user vimrc file is found, or a +vimrc file in the current directory, or the "VIMINIT" environment variable is +set, it will be set to 'nocompatible'. This has the side effect of setting or +resetting other options (see 'compatible'). But only the options that have +not been set or reset will be changed. This has the same effect like the +value of 'compatible' had this value when starting Vim. Note that this +doesn't happen for the system-wide vimrc file. + +But there is a side effect of setting or resetting 'compatible' at the moment +a .vimrc file is found: Mappings are interpreted the moment they are +encountered. This makes a difference when using things like "<CR>". If the +mappings depend on a certain value of 'compatible', set or reset it before +giving the mapping. + +The above behavior can be overridden in these ways: +- If the "-N" command line argument is given, 'nocompatible' will be used, + even when no vimrc file exists. +- If the "-C" command line argument is given, 'compatible' will be used, even + when a vimrc file exists. +- If the "-u {vimrc}" argument is used, 'compatible' will be used. +- When the name of the executable ends in "ex", then this works like the "-C" + argument was given: 'compatible' will be used, even when a vimrc file + exists. This has been done to make Vim behave like "ex", when it is started + as "ex". + +Avoiding trojan horses: *trojan-horse* +While reading the "vimrc" or the "exrc" file in the current directory, some +commands can be disabled for security reasons by setting the 'secure' option. +This is always done when executing the command from a tags file. Otherwise it +would be possible that you accidentally use a vimrc or tags file that somebody +else created and contains nasty commands. The disabled commands are the ones +that start a shell, the ones that write to a file, and ":autocmd". The ":map" +commands are echoed, so you can see which keys are being mapped. + If you want Vim to execute all commands in a local vimrc file, you +can reset the 'secure' option in the EXINIT or VIMINIT environment variable or +in the global "exrc" or "vimrc" file. This is not possible in "vimrc" or +"exrc" in the current directory, for obvious reasons. + On Unix systems, this only happens if you are not the owner of the +vimrc file. Warning: If you unpack an archive that contains a vimrc or exrc +file, it will be owned by you. You won't have the security protection. Check +the vimrc file before you start Vim in that directory, or reset the 'exrc' +option. Some Unix systems allow a user to do "chown" on a file. This makes +it possible for another user to create a nasty vimrc and make you the owner. +Be careful! + When using tag search commands, executing the search command (the last +part of the line in the tags file) is always done in secure mode. This works +just like executing a command from a vimrc/exrc in the current directory. + + *slow-start* +If Vim takes a long time to start up, there may be a few causes: +- |