| blob | 3884f41d9a99e08430d3935b3dbecf8756ee80bf |
1 *starting.txt* For Vim version 5.8. Last change: 2000 Nov 16
4 VIM REFERENCE MANUAL by Bram Moolenaar
7 Starting Vim *starting*
9 1. Vim arguments |vim-arguments|
10 2. Vim on the Amiga |starting-amiga|
11 3. Running Vim from xargs |xargs|
12 4. Initialization |initialization|
13 5. Suspending |suspend|
14 6. The vimrc file |vimrc-intro|
15 7. The viminfo file |viminfo-file|
17 ==============================================================================
18 1. Vim arguments *vim-arguments*
20 Most often, Vim is started to edit a single file with the command
22 vim filename *-vim*
24 More generally, Vim is started with:
26 vim [option | filename] ..
28 Option arguments and file name arguments can be mixed, and any number of them
29 can be given. However, watch out for options that take an argument.
31 For compatibility with various Vi versions, see |cmdline-arguments|.
33 Exactly one out of the following five items may be used to choose how to
34 start editing:
36 *-file* *---*
37 filename One or more file names. The first one will be the current
38 file and read into the buffer. The cursor will be positioned
39 on the first line of the buffer.
40 To avoid a file name starting with a '-' being interpreted as
41 an option, precede the arglist with "--", e.g.:
42 Vim -- -filename
43 All arguments after the "--" will be interpreted as file names,
44 no other options or "+command" argument can follow.
46 *--*
47 - This argument can mean two things, depending on whether Ex
48 mode is to be used.
50 Starting in Normal mode:
51 > vim - or ex -v -
52 Start editing a new buffer, which is filled with text
53 that is read from stdin. The commands that would normally be
54 read from stdin will now be read from stderr. Example:
55 > find . -name "*.c" -print | vim -
56 The buffer will be marked modified, because it contains text
57 that needs to be saved. Except when in readonly mode, then
58 the buffer is not marked modified. Example:
59 > ls | view -
61 Starting in Ex mode:
62 > ex - or vim -e -
63 Start editing in silent mode. See |-s-ex|.
65 *-t* *-tag*
66 -t {tag} A tag. "tag" is looked up in the tags file, the associated
67 file becomes the current file, and the associated command is
68 executed. Mostly this is used for C programs, in which case
69 "tag" often is a function name. The effect is that the file
70 containing that function becomes the current file and the
71 cursor is positioned on the start of the function (see
72 |tags|).
74 *-q* *-qf*
75 -q [errorfile] QuickFix mode. The file with the name [errorfile] is read
76 and the first error is displayed. See |quickfix|.
77 If [errorfile] is not given, the 'errorfile' option is used
78 for the file name. See 'errorfile' for the default value.
79 {not in Vi}
81 (nothing) Without one of the four items above, Vim will start editing a
82 new buffer. It's empty and doesn't have a file name.
85 The startup mode can be changed by using another name instead of "vim", which
86 is equal to giving options:
87 ex vim -e Start in Ex mode (see |Ex-mode|). *ex*
88 view vim -R Start in read-only mode (see |-R|). *view*
89 gvim vim -g Start the GUI (see |gui|). *gvim*
90 gex vim -eg Start the GUI in Ex mode. *gex*
91 gview vim -Rg Start the GUI in read-only mode. *gview*
92 rvim vim -Z Like "vim", but in restricted mode (see |-Z|) *rvim*
93 rview vim -RZ Like "view", but in restricted mode. *rview*
94 rgvim vim -gZ Like "gvim", but in restricted mode. *rgvim*
95 rgview vim -RgZ Like "gview", but in restricted mode. *rgview*
97 Additional characters may follow, they are ignored. For example, you can have
98 "gvim-5" to start the GUI. You must have an executable by that name then, of
99 course.
101 On Unix, you would normally have one executable called Vim, and links from the
102 different startup-names to that executable. If your system does not support
103 links and you do not want to have several copies of the executable, you could
104 use an alias instead. For example:
105 > alias view vim -R
106 > alias gvim vim -g
108 *startup-options*
109 The option arguments may be given in any order. Single-letter options can be
110 combined after one dash. There can be no option arguments after the "--"
111 argument.
113 --help *-h* *--help*
114 -h Give usage (help) message and exit. {not in Vi}
116 *--version*
117 --version Print version information and exit. Same output as for
118 |:version| command. {not in Vi}
120 *-+*
121 +[num] The cursor will be positioned on line "num" for the first
122 file being edited. If "num" is missing, the cursor will be
123 positioned on the last line.
125 *-+/*
126 +/{pat} The cursor will be positioned on the first line containing
127 "pat" in the first file being edited (see |pattern| for the
128 available search patterns).
130 +{command} *-+c* *-c*
131 -c {command} "command" will be executed after the first file has been
132 read (and after autocommands and modelines for that file have
133 been processed). "command" is interpreted as an Ex command.
134 If the "command" contains spaces, it must be enclosed in
135 double quotes (this depends on the shell that is used).
136 Example:
137 > vim "+set si" main.c
138 > vim -c "set ff=dos" -c wq mine.mak
140 Note: You can use up to 10 "+" or "-c" arguments in a Vim
141 command. They are executed in the order given. {Vi only
142 allows one command}
144 *-r*
145 -r Recovery mode. Without a file name argument, a list of
146 existing swap files is given. With a file name, a swap file
147 is read to recover a crashed editing session. See
148 |crash-recovery|.
150 *-L*
151 -L Same as -r. {only in some versions of Vi: "List recoverable
152 edit sessions"}
154 *-R*
155 -R Readonly mode. The 'readonly' option will be set for all the
156 files being edited. You can still edit the buffer, but will
157 be prevented from accidentally overwriting a file. If you
158 forgot that you are in View mode and did make some changes,
159 you can overwrite a file by adding an exclamation mark to
160 the Ex command, as in ":w!". The 'readonly' option can be
161 reset with ":set noro" (see the options chapter, |options|).
162 Subsequent edits will not be done in readonly mode. Calling
163 the executable "view" has the same effect as the -R argument.
164 The 'updatecount' option will be set to 10000, meaning that
165 the swap file will not be updated automatically very often.
167 *-m*
168 -m Modifications not allowed. The 'write' option will be reset,
169 so that writing files is disabled. The 'write' option can be
170 set to enable writing again.
172 *-Z* *restricted-mode*
173 -Z Restricted mode. All commands that make use of an external
174 shell are disabled. This includes suspending with CTRL-Z,
175 ":sh", filtering, the system() function, backtick expansion,
176 etc.
178 *-g*
179 -g Start Vim in GUI mode. See |gui|.
181 *-v*
182 -v Start Ex in Vi mode. Only makes a difference when the
183 executable is called "ex" or "gvim". For gvim the GUI is not
184 started if possible.
186 *-e*
187 -e Start Vim in Ex mode. Only makes a difference when the
188 executable is not called "ex".
190 *-s-ex*
191 -s Silent or batch mode. Only when Vim was started as "ex" or
192 when preceded with the "-e" argument. Otherwise see |-s|.
193 To be used when Vim is used to execute Ex commands from a file
194 instead of a terminal. Switches off most prompts and
195 informative messages. But not warning and error messages, and
196 the output from commands that print text lines, like ":print"
197 and ":list".
198 Initializations are skipped (except the ones given with the
199 "-u" argument).
201 *-b*
202 -b Binary mode. File I/O will only recognize <NL> to separate
203 lines. The 'expandtab' option will be reset. The 'textwidth'
204 option is set to 0. 'modeline' is reset. The 'binary' option
205 is set. This is done after reading the vimrc/exrc files but
206 before reading any file in the arglist. See also
207 |edit-binary|. {not in Vi}
209 *-l*
210 -l Lisp mode. Sets the 'lisp' and 'showmatch' options on.
212 *-F*
213 -F Farsi mode. Sets the 'fkmap' and 'rightleft' options on.
214 (Only when compiled with |+rightleft| and |+farsi| features,
215 otherwise Vim gives an error message and exits). {not in Vi}
217 *-H*
218 -H Hebrew mode. Sets the 'hkmap' and 'rightleft' options on.
219 (Only when compiled with the |+rightleft| feature, otherwise
220 Vim gives an error message and exits). {not in Vi}
222 *-V* *verbose*
223 -V[n] Verbose. Sets the 'verbose' option to [n][ (default: 10).
224 Messages will be given for each file that is ":source"d and
225 for reading or writing a viminfo file. Can be used to find
226 out what is happening upon startup and exit. {not in Vi}
228 *-C*
229 -C Compatible mode. Sets the 'compatible' option. You can use
230 this to get 'compatible', even though there is a .vimrc file.
231 Also see |compatible-default|. {not in Vi}
233 *-N*
234 -N Not compatible mode. Resets the 'compatible' option. You can
235 use this to get 'nocompatible', when there is no .vimrc file.
236 Also see |compatible-default|. {not in Vi}
238 *-n*
239 -n No swap file will be used. Recovery after a crash will be
240 impossible. Handy if you want to view or edit a file on a
241 very slow medium (e.g., a floppy).
242 Can also be done with ":set updatecount=0". You can switch it
243 on again by setting the 'updatecount' option to some value,
244 e.g., ":set uc=100".
245 'updatecount' is set to 0 AFTER executing commands from a
246 vimrc file, but before the GUI initializations. Thus it
247 overrides a setting for 'updatecount' in a vimrc file, but not
248 in a gvimrc file. See |startup|. {not in Vi}
249 When you want to reduce accesses to the disk (e.g., for a
250 laptop), don't use "-n", but set 'updatetime' and
251 'udpatecount' to very big numbers, and type ":preserve" when
252 you want to save your work. This way you keep the possibility
253 for crash recovery.
255 *-o*
256 -o[N] Open N windows. If [N] is not given, one window is opened
257 for every file given as argument. If there is not enough
258 room, only the first few files get a window. If there are
259 more windows than arguments, the last few windows will be
260 editing an empty file. {not in Vi}
262 *-T*
263 -T {terminal} Set the terminal type to "terminal". This influences the
264 codes that Vim will send to your terminal. This is normally
265 not needed, because Vim will be able to find out what type
266 of terminal you are using (See |terminal-info|). {not in Vi}
268 *-d*
269 -d {device} Amiga only: The "device" is opened to be used for editing.
270 Normally you would use this to set the window position and
271 size: "-d con:x/y/width/height", e.g.,
272 "-d con:30/10/600/150". But you can also use it to start
273 editing on another device, e.g., AUX:. {not in Vi}
275 *-f*
276 -f Amiga: Do not restart Vim to open a new window. This
277 option should be used when Vim is started by a program that
278 will wait for the edit session to finish (e.g., mail or
279 readnews). See |amiga-window|. {not in Vi}
281 GUI: Do not disconnect from the program that started Vim.
282 'f' stands for "foreground". If omitted, the GUI forks a new
283 process and exits the current one. "-f" should be used when
284 gvim is started by a program that will wait for the edit
285 session to finish (e.g., mail or readnews). If you want gvim
286 never to fork, include 'f' in 'guioptions' in your .gvimrc.
287 Careful: You can use "-gf" to start the GUI in the foreground,
288 but "-fg" is used to specify the foreground color. {not in
289 Vi} |gui-fork|
291 *-u*
292 -u {vimrc} The file "vimrc" is read for initializations. Other
293 initializations are skipped; see |initialization|. This can
294 be used to start Vim in a special mode, with special
295 mappings and settings. A shell alias can be used to make
296 this easy to use. For example:
297 > alias vimc vim -u ~/.c_vimrc !*
298 Also consider using autocommands; see |autocommand|.
299 When {vimrc} is equal to "NONE" (all uppercase), all
300 initializations from files and environment variables are
301 skipped, including reading the .gvimrc file when the GUI
302 starts.
303 Using the "-u" argument also means that the 'compatible'
304 option will be on by default. This can have unexpected side
305 effects. See |'compatible'|.
306 {not in Vi}
308 *-U*
309 -U {gvimrc} The file "gvimrc" is read for initializations when the GUI
310 starts. Other GUI initializations are skipped. When {gvimrc}
311 is equal to "NONE", no file is read for initializations at
312 all.
313 Exception: Reading the system-wide menu file is always done.
315 *-i*
316 -i {viminfo} The file "viminfo" is used instead of the default viminfo
317 file. If the name "NONE" is used (all uppercase), no viminfo
318 file is read or written, even if 'viminfo' is set or when
319 ":rv" or ":wv" are used. See also |viminfo-file|. {not in Vi}
321 *-x*
322 -x Use encryption to read/write files. Will prompt for a key,
323 which is then stored in the 'key' option. All writes will
324 then use this key to encrypt the text. The '-x' argument is
325 not needed when reading a file, because there is a check if
326 the file that is being read has been encrypted, and Vim asks
327 for a key automatically. |encryption|
329 *-s*
330 -s {scriptin} The script file "scriptin" is read. The characters in the
331 file are interpreted as if you had typed them. The same can
332 be done with the command ":source! {scriptin}". If the end
333 of the file is reached before the editor exits, further
334 characters are read from the keyboard. Only works when not
335 started in Ex mode, see |-s-ex|. See also |complex-repeat|.
336 {not in Vi}
338 *-w*
339 -w {scriptout} All the characters that you type are recorded in the file
340 "scriptout", until you exit Vim. This is useful if you want
341 to create a script file to be used with "vim -s" or
342 ":source!". When the "scriptout" file already exists, new
343 characters are appended. See also |complex-repeat|. {not in
344 Vi}
346 *-W*
347 -W {scriptout} Like -w, but do not append, overwrite an existing file. {not
348 in Vi}
350 *-w_nr*
351 -w{number} Does nothing. This was included for Vi-compatibility. In Vi
352 it sets the 'window' option, which is not implemented in Vim.
354 Example for using a script file to change a name in several files:
355 Create a file "subs.vi" containing substitute commands and a :wq
356 command:
357 > :%s/Jones/Smith/g
358 > :%s/Allen/Peter/g
359 > :wq
361 Execute Vim on all files you want to change:
363 > foreach i ( *.let ) vim -s subs.vi $i
365 If the executable is called "view", Vim will start in Readonly mode. This is
366 useful if you can make a hard or symbolic link from "view" to "vim".
367 Starting in Readonly mode can also be done with "vim -R".
369 If the executable is called "ex", Vim will start in "Ex" mode. This means it
370 will accept only ":" commands. But when the "-v" argument is given, Vim will
371 start in in Normal mode anyway.
373 ==============================================================================
374 2. Vim on the Amiga *starting-amiga*
376 Starting Vim from the Workbench *workbench*
377 -------------------------------
379 Vim can be started from the Workbench by clicking on its icon twice. It will
380 then start with an empty buffer.
382 Vim can be started to edit one or more files by using a "Project" icon. The
383 "Default Tool" of the icon must be the full pathname of the Vim executable.
384 The name of the ".info" file must be the same as the name of the text file.
385 By clicking on this icon twice, Vim will be started with the file name as
386 current file name, which will be read into the buffer (if it exists). You can
387 edit multiple files by pressing the shift key while clicking on icons, and
388 clicking twice on the last one. The "Default Tool" for all these icons must
389 be the same.
391 It is not possible to give arguments to Vim, other than file names, from the
392 workbench.
394 Vim window *amiga-window*
395 ----------
397 Vim will run in the CLI window where it was started. If Vim was started with
398 the "run" or "runback" command, or if Vim was started from the workbench, it
399 will open a window of its own.
401 Technical detail:
402 To open the new window a little trick is used. As soon as Vim
403 recognizes that it does not run in a normal CLI window, it will
404 create a script file in "t:". This script file contains the same
405 command as the one Vim was started with, and an "endcli" command.
406 This script file is then executed with a "newcli" command (the "c:run"
407 and "c:newcli" commands are required for this to work). The script
408 file will hang around until reboot, or until you delete it. This
409 method is required to get the ":sh" and ":!" commands to work
410 correctly. But when Vim was started with the -f option (foreground
411 mode), this method is not used. The reason for this is that
412 when a program starts Vim with the -f option it will wait for Vim to
413 exit. With the script trick, the calling program does not know when
414 Vim exits. The -f option can be used when Vim is started by a mail
415 program which also waits for the edit session to finish. As a
416 consequence, the ":sh" and ":!" commands are not available when the
417 -f option is used.
419 Vim will automatically recognize the window size and react to window
420 resizing. Under Amiga DOS 1.3, it is advised to use the fastfonts program,
421 "FF", to speed up display redrawing.
423 ==============================================================================
424 3. Running Vim from xargs *xargs*
426 The xargs program can be used to start a program with arguments that come from
427 stdin. A typical example:
429 > find . -name "*.c" -print | xargs vim
431 A problem is that stdin for the program run by xargs is not setup properly,
432 which causes problems for Vim. That is because Vim expects commands to come
433 from stdin. The symptoms are that typed characters are echoed and don't take
434 effect until <Return> is hit.
436 This is really a problem in xargs. To work around it, you can use this small
437 program:
439 > #include <unistd.h>
440 > #include <stdio.h>
441 >
442 > main(argc, argv)
443 > int argc;
444 > char **argv;
445 > {
446 > close(0); /* close stdin */
447 > dup(2); /* duplicate stdin from stderr */
448 > execvp(argv[1], argv + 1);
449 > perror("could not execute program");
450 > }
452 Store this in "start.c", compile it to "start" and put it somewhere in your
453 search path. You might have to make a few adjustments for your system. An
454 example of using this:
456 > find . -name "*.c" -print | xargs start vim
458 ==============================================================================
459 4. Initialization *initialization* *startup*
461 This section is about the non-GUI version of Vim. See |gui-fork| for
462 additional initialization when starting the GUI.
464 At startup, Vim checks environment variables and files and sets values
465 accordingly. Vim proceeds in this order:
467 1. Set the 'shell' option *SHELL* *COMSPEC*
468 The environment variable SHELL, if it exists, is used to set the
469 'shell' option. On MS-DOS and Win32, the COMPSPEC variable is used
470 if SHELL is not set.
472 2. Set the 'term' option *TERM*
473 The environment variable TERM, if it exists, is used to set the 'term'
474 option.
476 3. Execute Ex commands, from environment variables and/or files
477 An environment variable is read as one Ex command line, where multiple
478 commands must be separated with '|' or "<NL>".
479 *vimrc* *exrc*
480 A file that contains initialization commands is called a "vimrc" file.
481 Each line in a vimrc file is executed as an Ex command line. It is
482 sometimes also referred to as "exrc" file. They are the same type of
483 file, but "exrc" is what Vi always used, "vimrc" is a Vim specific
484 name. Also see |vimrc-intro|.
486 Recommended place for your personal initializations:
487 Unix $HOME/.vimrc
488 OS/2 $HOME/.vimrc or $VIM/.vimrc (or _vimrc)
489 MS-DOS and Win32 $HOME/_vimrc or $VIM/_vimrc
490 Amiga s:.vimrc or $VIM/.vimrc
492 If Vim was started with "-u filename", the file "filename" is used.
493 All following initializations until 5. are skipped.
494 "vim -u NONE" can be used to skip these initializations. |-u|
496 If Vim was started in Ex mode with the "-s" argument, all following
497 initializations until 4. are skipped. Only the "-u" option is
498 interpreted.
499 *system-vimrc*
500 a. For Unix, OS/2, VMS, Macintosh, RISC-OS and Amiga the system vimrc
501 file is read for initializations. The path of this file is shown with
502 the ":version" command. Note that this file is ALWAYS read in
503 'compatible' mode, since the automatic resetting of 'compatible' is
504 only done later. Add a ":set nocp" command if you like.
506 *VIMINIT* *.vimrc* *_vimrc* *EXINIT* *.exrc* *_exrc*
507 b. Four places are searched for initializations. The first that exists
508 is used, the others are ignored.
509 - The environment variable VIMINIT (see also |compatible-default|) (*)
510 - The user vimrc file(s):
511 "$HOME/.vimrc" (for Unix and OS/2) (*)
512 "s:.vimrc" (for Amiga) (*)
513 "home:.vimrc" (for Amiga) (*)
514 "$VIM/.vimrc" (for OS/2 and Amiga) (*)
515 "$HOME/_vimrc" (for MS-DOS and Win32) (*)
516 "$VIM\_vimrc" (for MS-DOS and Win32) (*)
517 Note: For Unix, OS/2 and Amiga, when ".vimrc" does not exist,
518 "_vimrc" is also tried, in case an MS-DOS compatible file
519 system is used. For MS-DOS and Win32 ".vimrc" is checked
520 after "_vimrc", in case long file names are used.
521 Note: For MS-DOS and Win32, "$HOME" is checked first. If no
522 "_vimrc" or ".vimrc" is found there, "$VIM" is tried.
523 See |$VIM| for when $VIM is not set.
524 - The environment variable EXINIT
525 - The user exrc file(s). Same as for the user vimrc file, but with
526 "vimrc" replaced by "exrc". But without the (*)!
528 c. If the 'exrc' option is on (which is not the default), the current
529 directory is searched for four files. The first that exists is used,
530 the others are ignored.
531 - The file ".vimrc" (for Unix, Amiga and OS/2) (*)
532 "_vimrc" (for MS-DOS and Win32) (*)
533 - The file "_vimrc" (for Unix, Amiga and OS/2) (*)
534 ".vimrc" (for MS-DOS and Win32) (*)
535 - The file ".exrc" (for Unix, Amiga and OS/2)
536 "_exrc" (for MS-DOS and Win32)
537 - The file "_exrc" (for Unix, Amiga and OS/2)
538 ".exrc" (for MS-DOS and Win32)
540 (*) Using this file or environment variable will cause 'compatible' to be
541 off by default. See |compatible-default|.
543 4. Load the default file type detection script.
544 This script is used to set autocommands for the FileType event. See
545 |FileType| and |'filetype'|. This is only done if Vim was compiled
546 with the |+autocmd| feature.
547 If Vim was started with "-u filename", this is skipped. |-u|
548 The name of this file depends on the system:
549 Amiga $VIMRUNTIME/filetype.vim
550 Mac $VIMRUNTIME:filetype.vim
551 MS-DOS $VIMRUNTIME\filetype.vim
552 RiscOS Vim:Filetype
553 Unix $VIMRUNTIME/filetype.vim
554 VMS $VIMRUNTIME/filetype.vim
556 5. Set 'shellpipe' and 'shellredir'
557 The 'shellpipe' and 'shellredir' options are set according to the
558 value of the 'shell' option, unless they have been set before.
559 This means that Vim will figure out the values of 'shellpipe' and
560 'shellredir' for you, unless you have set them yourself.
562 6. Set 'updatecount' to zero, if "-n" command argument used
564 7. Set binary options
565 If the "-b" flag was given to Vim, the options for binary editing will
566 be set now. See |-b|.
568 8. Perform GUI initializations
569 Only when starting "gvim", the GUI initializations will be done. See
570 |gui-init|.
572 9. Read the viminfo file
573 If the 'viminfo' option is not empty, the viminfo file is read. The
574 default is empty, so 'viminfo' must have been set by one of the
575 previous initializations. See |viminfo-file|.
577 10. Read the quickfix file
578 If the "-q" flag was given to Vim, the quickfix file is read. If this
579 fails, Vim exits.
581 11. Open all windows
582 When the |-o| flag was given, windows will be opened (but not
583 displayed yet).
584 When switching screens, it happens now. Redrawing starts.
585 If the "-q" flag was given to Vim, the first error is jumped to.
586 Buffers for all windows will be loaded.
588 12. Execute startup commands
589 If a "-t" flag was given to Vim, the tag is jumped to.
590 The commands given with the |-c| and |+cmd| arguments are executed.
591 If the 'insertmode' option is set, Insert mode is entered.
592 The |VimEnter| autocommands are executed.
594 Some hints on using initializations:
596 Standard setup:
597 Create a vimrc file to set the default settings and mappings for all your edit
598 sessions. Put it in a place so that it will be found by 3b:
599 ~/.vimrc (Unix and OS/2)
600 s:.vimrc (Amiga)
601 $VIM\_vimrc (MS-DOS and Win32)
602 Note that creating a vimrc file will cause the 'compatible' option to be off
603 by default. See |compatible-default|.
605 Local setup:
606 Put all commands that you need for editing a specific directory only into a
607 vimrc file and place it in that directory under the name ".vimrc" ("_vimrc"
608 for MS-DOS and Win32). NOTE: To make Vim look for these special files you
609 have to turn on the option 'exrc'. See |trojan-horse| too.
611 System setup:
612 This only applies if you are managing a Unix system with several users and
613 want to set the defaults for all users. Create a vimrc file with commands
614 for default settings and mappings and put it in the place that is given with
615 the ":version" command.
617 Saving the current state of Vim to a file:
618 Whenever you have changed values of options or when you have created a
619 mapping, then you may want to save them in a vimrc file for later use. See
620 |save-settings| about saving the current state of settings to a file.
622 Avoiding setup problems for Vi users:
623 Vi uses the variable EXINIT and the file "~/.exrc". So if you do not want to
624 interfere with Vi, then use the variable VIMINIT and the file "vimrc" instead.
626 Amiga environment variables:
627 On the Amiga, two types of environment variables exist. The ones set with the
628 DOS 1.3 (or later) setenv command are recognized. See the AmigaDos 1.3
629 manual. The environment variables set with the old Manx Set command (before
630 version 5.0) are not recognized.
632 MS-DOS line separators:
633 On MS-DOS-like systems (MS-DOS itself, Win32, and OS/2), Vim assumes that all
634 the vimrc files have <CR> <NL> pairs as line separators. This will give
635 problems if you have a file with only <NL>s and have a line like
636 ":map xx yy^M". The trailing ^M will be ignored.
638 *compatible-default*
639 When Vim starts, the 'compatible' option is on. This will be used when Vim
640 starts its initializations. But as soon as a user vimrc file is found, or a
641 vimrc file in the current directory, or the "VIMINIT" environment variable is
642 set, it will be set to 'nocompatible'. This has the side effect of setting or
643 resetting other options (see 'compatible'). But only the options that have
644 not been set or reset will be changed. This has the same effect like the
645 value of 'compatible' had this value when starting Vim. Note that this
646 doesn't happen for the system-wide vimrc file.
648 But there is a side effect of setting or resetting 'compatible' at the moment
649 a .vimrc file is found: Mappings are interpreted the moment they are
650 encountered. This makes a difference when using things like "<CR>". If the
651 mappings depend on a certain value of 'compatible', set or reset it before
652 giving the mapping.
654 The above behavior can be overridden in these ways:
655 - If the "-N" command line argument is given, 'nocompatible' will be used,
656 even when no vimrc file exists.
657 - If the "-C" command line argument is given, 'compatible' will be used, even
658 when a vimrc file exists.
659 - If the "-u {vimrc}" argument is used, 'compatible' will be used.
660 - When the name of the executable ends in "ex", then this works like the "-C"
661 argument was given: 'compatible' will be used, even when a vimrc file
662 exists. This has been done to make Vim behave like "ex", when it is started
663 as "ex".
665 Avoiding trojan horses: *trojan-horse*
666 While reading the "vimrc" or the "exrc" file in the current directory, some
667 commands can be disabled for security reasons by setting the 'secure' option.
668 This is always done when executing the command from a tags file. Otherwise it
669 would be possible that you accidentally use a vimrc or tags file that somebody
670 else created and contains nasty commands. The disabled commands are the ones
671 that start a shell, the ones that write to a file, and ":autocmd". The ":map"
672 commands are echoed, so you can see which keys are being mapped.
673 If you want Vim to execute all commands in a local vimrc file, you
674 can reset the 'secure' option in the EXINIT or VIMINIT environment variable or
675 in the global "exrc" or "vimrc" file. This is not possible in "vimrc" or
676 "exrc" in the current directory, for obvious reasons.
677 On Unix systems, this only happens if you are not the owner of the
678 vimrc file. Warning: If you unpack an archive that contains a vimrc or exrc
679 file, it will be owned by you. You won't have the security protection. Check
680 the vimrc file before you start Vim in that directory, or reset the 'exrc'
681 option. Some Unix systems allow a user to do "chown" on a file. This makes
682 it possible for another user to create a nasty vimrc and make you the owner.
683 Be careful!
684 When using tag search commands, executing the search command (the last
685 part of the line in the tags file) is always done in secure mode. This works
686 just like executing a command from a vimrc/exrc in the current directory.
688 *slow-start*
689 If Vim takes a long time to start up, there may be a few causes:
690 - If the Unix version was compiled with the GUI and/or X11 (check the output
691 of ":version" for "+GUI" and "+X11"), it may need to load shared libraries
692 and connect to the X11 server. Try compiling a version with GUI and X11
693 disabled. This also should make the executable smaller.
694 - If you have "viminfo" enabled, the loading of the viminfo file may take a
695 while. You can find out if this is the problem by disabling viminfo for a
696 moment (use the Vim argument "-i NONE", |-i|). Try reducing the number of
697 lines stored in a register with ":set viminfo='20\"50".
698 |viminfo-file|.
700 *:intro*
701 When Vim starts without a file name, an introductory message is displayed (for
702 those who don't know what Vim is). It is removed as soon as the display is
703 redrawn in any way. To see the message again, use the ":intro" command.
704 To avoid the intro message on startup, add the 'I' flag to 'shortmess'.
706 ==============================================================================
707 5. Suspending *suspend*
709 *iconise* *CTRL-Z* *v_CTRL-Z*
710 CTRL-Z Suspend Vim, like ":stop".
711 Works in Normal and in Visual mode. In Insert and
712 Command-line mode, the CTRL-Z is inserted as a normal
713 character.
716 :sus[pend][!] or *:sus* *:suspend* *:st* *:stop*
717 :st[op][!] Suspend Vim.
718 If the '!' is not given and 'autowrite' is set, every
719 buffer with changes and a file name is written out.
720 If the '!' is given or 'autowrite' is not set, changed
721 buffers are not written, don't forget to bring Vim
722 back to the foreground later!
724 In the GUI, suspending is implemented as iconising gvim. In Windows 95/NT,
725 gvim is minimized.
727 On many Unix systems, it is possible to suspend Vim with CTRL-Z. This is only
728 possible in Normal and Visual mode (see next chapter, |vim-modes|). Vim will
729 continue if you make it the foreground job again. On other systems, CTRL-Z
730 will start a new shell. This is the same as the ":sh" command. Vim will
731 continue if you exit from the shell.
733 ==============================================================================
734 6. The vimrc file *vimrc-intro* *vim-script-intro*
736 A vimrc file can be used for settings you intend to use more-or-less for every
737 of your Vim sessions. Normally the file is called $HOME/.vimrc, but other
738 files can also be used, see |vimrc|. Vim will read it (them) when starting
739 and interpret the commands in them.
741 You can also use Vim script files for other purposes. The files used for
742 syntax highlighting are an example. There are enough commands in Vim to
743 accomplish just about any task.
745 *vimrc_example.vim*
746 You should be able to find an example vimrc file at
747 $VIMRUNTIME/vimrc_example.vim. You could use this as a start for your own
748 vimrc file. You can also find a lot of examples in vimrc files made by
749 others. Have a look at http://www.vim.org/user.html.
752 USING EX COMMANDS ~
754 The vimrc file can contain anything that can be typed on the Vim command line.
755 The recommended practice is not to include the preceding colon sign ":", thus
756 if one would type
757 > :set number
758 on the Vim command line, the same can appear in the vimrc file simply as
759 > set number
761 The end-of-line character depends on the system. For Unix a single <NL>
762 character is used. For MS-DOS, Windows, OS/2 and the like, <CR><LF> is used.
763 This is important when using mappings that end in a <CR>. See |:source_crnl|.
765 Long lines can be split up by inserting a "\" (backslash) at the start of
766 the next line where the line has been broken, see |line-continuation|.
767 Example:
768 > iabbr Http Hyper Text Transfer
769 > \ Protocol
770 Note that this only works in a Vim script file.
773 WHITE SPACE ~
775 Blank lines are allowed and ignored.
777 Leading whitespace characters (blanks and TABs) are always ignored. The
778 whitespaces between parameters (e.g. between the 'set' and the 'number' in the
779 example above) are reduced to one blank character and plays the role of a
780 separator, the whitespaces after the last (visible) character may or may not
781 be ignored depending on the situation, see below.
783 For a ":set" command involving the "=" (equal) sign, such as in
784 > set cpoptions =aABceFst
785 the whitespace immediately before the "=" sign is ignored. But there can be
786 no whitespace after the "=" sign!
788 To include a whitespace character in the value of an option, it must be
789 escaped by a "\" (backslash) as in the following example:
790 > set tags=my\ nice\ file
791 The same example written as
792 > set tags=my nice file
793 will issue an error, because it is interpreted as:
794 > set tags=my
795 > set nice
796 > set file
799 COMMENTS ~
801 The character " (the double quote mark) starts a comment. Everything after
802 and including this character until the end-of-line is considered a comment and
803 is ignored, except for commands that don't consider comments, as shown in
804 examples below. A comment can start on any character position on the line.
806 There is a little "catch" with comments for some commands. Examples:
807 > abbrev dev development " shorthand
808 > map <F3> o#include " insert include
809 > execute cmd " do it
810 > !ls *.c " list C files
811 The abbreviation 'dev' will be expanded to 'development " shorthand'. The
812 mapping of <F3> will actually be the whole line after the 'o# ....' including
813 the '" insert include'. The "execute" command will give an error. The "!"
814 command will send everything after it to the shell, causing an error for an
815 unmatched '"' character.
816 There can be no comment after ":map", ":abbreviate", ":execute" and "!"
817 commands (there are a few more commands with this restriction). For the
818 "map", ":abbreviate" and "execute" commands there is a trick:
819 > abbrev dev development|" shorthand
820 > map <F3> o#include|" insert include
821 > execute cmd |" do it
822 With the '|' character the command is separated from the next one. And that
823 next command is only a comment.
825 Note that there is no white space before the '|' in the abbreviation and
826 mapping. For these commands, any character until the end-of-line or '|' is
827 included. As a consequence of this behavior, you don't always see that
828 trailing whitespace is included:
829 > map <F4> o#include
830 To avoid these problems, you can set the 'list' option when editing vimrc
831 files.
834 PITFALLS ~
836 Even bigger problem arises in the following example:
837 > map ,ab o#include
838 > unmap ,ab
839 Here the mapping of ,ab will be ',ab', no trailing whitespaces is included.
840 However, the "unmap" does not end directly with the end-of-line, Vim will try
841 to unmap ',ab ', which does not exist as a mapped sequence. An error will be
842 issued, which is very hard to identify, because the ending whitespace
843 character on the 'unmap ,ab ' are not visible.
845 And this is exactly the same what happens when one uses a comment after an
846 'unmap' command:
847 > unmap ,ab " comment
848 Here the comment part will be ignored. However, Vim will try to unmap
849 ',ab ', which does not exist, Deleting the comment as well as all the
850 whitespaces up the ending 'b' character will cure the problem.
852 Except for the situations as above, it is legal to put a comment on the same
853 line as the Vim definitions, such as
854 > set number " display line numbers
857 NORMAL MODE COMMANDS ~
859 To execute normal mode commands, the |:normal| command can be used. To avoid
860 trouble with special characters, use the |:execute| command. Its argument is
861 an expression (more about that further down). Example:
862 > exe "normal mxGOA test.\<Esc>`x"
863 This appends "A test." below the last line in the file and returns the cursor
864 to where it was. Note the use of "\<Esc>", which is translated into the
865 escape character. To use a backslash or double quote here you have to put a
866 backslash before it:
867 > exe "normal \"aYgg\"aP"
868 This yanks the current line and puts it above the first line in the file. To
869 do this without changing the cursor position and the text displayed in the
870 window, this has to be extended a bit:
871 > exe "normal ma\"aYHmbgg\"aP`bzt`a"
872 What this does:
873 ma set mark a at cursor position
874 "aY yank current line into register a
875 Hmb go to top line in window and set mark b there
876 gg go to first line in file
877 "aP put the yanked line above it
878 `b go back to top line in display
879 zt position the text in the window as it was before
880 `a go back to saved cursor position
883 IF - ELSE - ENDIF ~
885 Sometimes you will want to execute a command only under a certain condition.
886 The |:if| command can be used for this. Example:
887 > if &term == "xterm"
888 > echo "this is an xterm"
889 > endif
890 The argument for the "if" command is an expression. If this expression
891 evaluates to true (non-zero), the statements until the "endif" are executed.
892 If the expression evaluates to zero, these commands are skipped.
893 The |:echo| command prints its argument, which is also an expression.
895 Many constructions can be used in an expression. In the example we see this:
896 &term The value of the 'term' option. A name prepended with
897 '&' is the value of the option by that name.
898 == "equal", compares the strings or numbers on each
899 side, and evaluates to true when they are equal.
900 "xterm" A literal string.
901 For more information about expressions, see |expression|.
903 You can also use "else":
904 > if &tabstop != 8
905 > echo "tabstop is " . &tabstop
906 > else
907 > echo "tabstop is OK"
908 > endif
909 Note that a dot is used in the first echo command, to concatenate the literal
910 string with the value of the 'tabstop' option. It is automatically converted
911 from a number to a string, so that it can be concatenated.
914 WHILE - ENDWHILE ~
916 To repeat a sequence of commands the |:while| command can be used:
917 > let i = 1
918 > while i < 10
919 > echo i
920 > let i = i + 1
921 > endwhile
922 This uses the internal variable "i". An internal variable is used just like
923 in many programming languages. The |:let| command is used to assign a value
924 to a variable. The variable need not be declared and can hold a number or a
925 string.
926 The statements between the "while" and the "endwhile" are executed nine times.
927 Note that the variable "i" is incremented with the "let i = i + 1" command.
928 If you would forget this, the loop would run forever! Fortunately you can
929 interrupt it with a CTRL-C (CTRL-Break on DOS).
932 BUILTIN FUNCTIONS ~
934 Vim has builtin functions that you can use. Example:
935 > echo exists("did_my_inits")
936 This will print a one when the variable "did_my_inits" exists, and a zero if
937 it doesn't exist.
938 > if has("gui_running")
939 > syntax on
940 > endif
941 This will switch on syntax highlighting if the GUI is started. The has()
942 function can be used to check if a certain feature is supported.
943 > call append(0, hostname() . " - " . strftime("%Y %b %d"))
944 This inserts a line with the name of the computer and the current date at the
945 start of the current buffer.
947 There are many more functions, which can be used to accomplish most things you
948 would want to do in Vim, which are too complicated to do with normal commands.
949 See |functions|.
952 USER DEFINED FUNCTIONS ~
954 You will often have a number of commands that you use in several places. You
955 can define a function for these, and call it where you want. Example:
956 > function My_Func(name)
957 > if a:name ==? "john"
958 > let s = "Hello "
959 > else
960 > let s = "I don't know "
961 > endif
962 > echo s . a:name . "."
963 > endfun
964 Explanation:
965 The function "My_Func" is defined with one argument. "a:name" is used to
966 refer to that argument. The "==?" operator is used to compare the argument
967 with "john" while ignoring case. You could call it like this:
968 > call My_Func("John")
969 > Hello John.
970 > call My_Func("James")
971 > I don't know James.
973 Note that the name of a user function always starts with a capital letter.
974 There can be any number of arguments. See |:function|.
977 PACKAGING ~
979 To avoid your function names to interfere with functions that you get from
980 others, use this scheme:
981 - Prepend a unique string before each function name. I often use an
982 abbreviation. For example, "OW_" is used for the option window functions.
983 - Put the definition of your functions together in a file. Set a global
984 variable to indicate that the functions have been loaded. When sourcing the
985 file again, first unload the functions.
986 Example:
987 > " This is the XXX package
988 >
989 > if exists("XXX_loaded")
990 > delfun XXX_one
991 > delfun XXX_two
992 > endif
993 >
994 > function XXX_one(a)
995 > ... body of function ...
996 > endfun
997 >
998 > function XXX_two(b)
999 > ... body of function ...
1000 > endfun
1001 >
1002 > let XXX_loaded = 1
1005 AUTOCOMMANDS ~
1007 You might want to set options or define mappings when editing a certain kind
1008 of file. Fortunatly, Vim already recognizes a lot of file types. This is
1009 used for syntax highlighting, but you can use it for other things too. You
1010 need to have syntax enabled |:syn-on|, or use this command:
1011 > filetype on
1013 For example, this autocommand sets the 'cindent' option in a C program file:
1014 > au FileType c set cindent
1015 This autocommand consists of three parts:
1016 FileType the name of the event which is used
1017 c the name of the file type detected
1018 set cindent the command executed when the event happens and the
1019 file type is "c"
1020 See |:autocmd| for more information.
1022 This works fine for the 'cindent' option, which is local to a buffer. When
1023 this is used for defining a mapping, this will not work properly when there
1024 are two windows. For example, if you are editing foo.txt in one window and
1025 foo.c in another, a mapping defined for foo.c will also be used in foo.txt.
1026 To make the mapping only work in the foo.c file, it needs to be removed as
1027 soon as the foo.c file is no longer the current buffer. That can be done in
1028 this way:
1029 > au BufEnter * if &ft == "c" | call CM_map() | endif
1030 > au BufLeave * if &ft == "c" | call CM_unmap() | endif
1031 > fun CM_map()
1032 > set cindent
1033 > imap { {<CR> <BS><CR>}<Up><End>
1034 > endfun
1035 > fun CM_unmap()
1036 > iunmap {
1037 > endfun
1038 One function is used here to define the mapping and another to remove it.
1039 This makes it possible to add more mappings, without changing the
1040 autocommands.
1041 The use of functions makes it possible to keep the autocommands short. With
1042 the '|' character commands are separated.
1043 In the ":imap" command the <> codes are used to avoid the need for control
1044 characters. This is easy to type and to read back. The " <BS> is used to
1045 avoid that the indent is removed when <CR> is typed.
1047 ==============================================================================
1048 7. The viminfo file *viminfo-file*
1050 If you exit Vim and later start it again, you would normally lose a lot of
1051 information. The viminfo file can be used to remember that information, which
1052 enables you to continue where you left off.
1054 The viminfo file is used to store:
1055 - The command line history.
1056 - The search string history.
1057 - The input-line history.
1058 - Contents of registers.
1059 - Marks for several files.
1060 - File marks, pointing to locations in files.
1061 - Last search/substitute pattern (for 'n' and '&').
1062 - The buffer list.
1063 - Global variables.
1065 The viminfo file is not supported when the |+viminfo| feature has been
1066 disabled at compile time.
1068 You could also use a session file. The difference is that the viminfo file
1069 does not depend on what you are working on. There normally is only one
1070 viminfo file. Session files are used to save the state of a specific editing
1071 session. You could have several session files, one for each project you are
1072 working on. Viminfo and session files together can be used to effectively
1073 enter Vim and directly start working in your desired setup. |session-file|
1075 *viminfo-read*
1076 When Vim is started and the 'viminfo' option is non-empty, the contents of
1077 the viminfo file are read and the info can be used in the appropriate places.
1078 The marks are not read in at startup (but file marks are). See
1079 |initialization| for how to set the 'viminfo' option upon startup.
1081 *viminfo-write*
1082 When Vim exits and 'viminfo' is non-empty, the info is stored in the viminfo
1083 file (it's actually merged with the existing one, if one exists). The
1084 'viminfo' option is a string containing information about what info should be
1085 stored, and contains limits on how much should be stored (see 'viminfo').
1087 Notes for Unix:
1088 - The file protection for the viminfo file will be set to prevent other users
1089 from being able to read it, because it may contain any text or commands that
1090 you have worked with.
1091 - If you want to share the viminfo file with other users (e.g. when you "su"
1092 to another user), you can make the file writable for the group or everybody.
1093 Vim will preserve this when writing new viminfo files. Be careful, don't
1094 allow just anybody to read and write your viminfo file!
1095 - Vim will not overwrite a viminfo file that is not writable by the current
1096 "real" user. This helps for when you did "su" to become root, but your
1097 $HOME is still set to a normal user's home directory. Otherwise Vim would
1098 create a viminfo file owned by root that nobody else can read.
1100 Marks are stored for each file separately. When a file is read and 'viminfo'
1101 is non-empty, the marks for that file are read from the viminfo file. NOTE:
1102 The marks are only written when exiting Vim, which is fine because marks are
1103 remembered for all the files you have opened in the current editing session,
1104 unless ":bdel" is used. If you want to save the marks for a file that you are
1105 about to abandon with ":bdel", use ":wv". The '[' and ']' marks are not
1106 stored, but the '"' mark is. The '"' mark is very useful for jumping to the
1107 cursor position when the file was last exited. No marks are saved for files
1108 that start with any string given with the "r" flag in 'viminfo'. This can be
1109 used to avoid saving marks for files on removable media (for MS-DOS you would
1110 use "ra:,rb:", for Amiga "rdf0:,rdf1:,rdf2:").
1112 *viminfo-file-marks*
1113 Uppercase marks ('A to 'Z) are stored when writing the viminfo file. The
1114 numbered marks ('0 to '9) are a bit special. When the viminfo file is written
1115 (when exiting or with the ":wviminfo" command), '0 is set to the current cursor
1116 position and file. The old '0 is moved to '1, '1 to '2, etc. This
1117 resembles what happens with the "1 to "9 delete registers. If the current
1118 cursor position is already present in '0 to '9, it is moved to '0, to avoid
1119 having the same position twice. The result is that with "'0", you can jump
1120 back to the file and line where you exited Vim. To do that right away, try
1121 using this command:
1123 > vim -c "normal '0"
1125 In (c)sh, you could make an alias for it:
1127 > alias lvim vim -c '"'normal "'"0'"'
1129 Viminfo file name: *viminfo-file-name*
1130 - The default name of the viminfo file is "$HOME/.viminfo" for Unix and OS/2,
1131 "s:.viminfo" for Amiga, "$HOME\_viminfo" for MS-DOS and Win32. For the last
1132 two, when $HOME is not set, "$VIM\_viminfo" is used. When $VIM is also not
1133 set, "c:\_viminfo" is used. For OS/2 "$VIM/.viminfo" is used when $HOME is
1134 not set and $VIM is set.
1135 - The 'n' flag in the 'viminfo' option can be used to specify another viminfo
1136 file name |'viminfo'|.
1137 - The "-i" Vim argument can be used to set another file name, |-i|. When the
1138 file name given is "NONE" (all uppercase), no viminfo file is ever read or
1139 written. Also not for the commands below!
1140 - For the commands below, another file name can be given, overriding the
1141 default and the name given with 'viminfo' or "-i" (unless it's NONE).
1143 Two commands can be used to read and write the viminfo file manually. This
1144 can be used to exchange registers between two running Vim programs: First
1145 type ":wv" in one and then ":rv" in the other. Note that if the register
1146 already contained something, then ":rv!" would be required. Also note
1147 however that this means everything will be overwritten with information from
1148 the first Vim, including the command line history, etc.
1150 The viminfo file itself can be edited by hand too, although we suggest you
1151 start with an existing one to get the format right. It is reasonably
1152 self-explanatory once you're in there. This can be useful in order to
1153 create a second file, say "~/.my_viminfo" which could contain certain
1154 settings that you always want when you first start Vim. For example, you
1155 can preload registers with particular data, or put certain commands in the
1156 command line history. A line in your .vimrc file like
1157 > rviminfo! ~/.my_viminfo
1158 can be used to load this information. You could even have different viminfos
1159 for different types of files (e.g., C code) and load them based on the file
1160 name, using the ":autocmd" command (see |:autocmd|).
1162 *viminfo-errors*
1163 When Vim detects an error while reading a viminfo file, it will not overwrite
1164 that file. If there are more than 10 errors, Vim stops reading the viminfo
1165 file. This was done to avoid accidentally destroying a file when the file
1166 name of the viminfo file is wrong. This could happen when accidentally typing
1167 "vim -i file" when you wanted "vim -R file" (yes, somebody accidentally did
1168 that!). If you want to overwrite a viminfo file with an error in it, you will
1169 either have to fix the error, or delete the file (while Vim is running, so
1170 most of the information will be restored).
1172 *:rv* *:rviminfo*
1173 :rv[iminfo][!] [file] Read from viminfo file [file] (default: see above).
1174 If [!] is given, then any information that is
1175 already set (registers, marks, etc.) will be
1176 overwritten. {not in Vi}
1178 *:wv* *:wviminfo*
1179 :wv[iminfo][!] [file] Write to viminfo file [file] (default: see above).
1180 The information in the file is first read in to make
1181 a merge between old and new info. When [!] is used,
1182 the old information is not read first, only the
1183 internal info is written. If 'viminfo' is empty, marks
1184 for up to 100 files will be written. {not in Vi}
1186 vim:tw=78:ts=8:sw=8: