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