blob: 7de79ce41dfda4ce03d21b62307ce5aeda2d3a0b [file] [log] [blame]
Bram Moolenaar69c2f172007-05-12 14:57:31 +00001*starting.txt* For Vim version 7.1. Last change: 2007 May 12
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.
Bram Moolenaar26a60b42005-02-22 08:49:11 +0000266 The output of these commands is displayed (to stdout):
267 :print
268 :list
269 :number
270 :set to display option values.
271 When 'verbose' is non-zero messages are printed (for
272 debugging, to stderr).
273 'term' and $TERM are not used.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000274 If Vim appears to be stuck try typing "qa!<Enter>". You don't
275 get a prompt thus you can't see Vim is waiting for you to type
276 something.
277 Initializations are skipped (except the ones given with the
278 "-u" argument).
279 Example: >
280 vim -e -s < thefilter thefile
281<
282 *-b*
283-b Binary mode. File I/O will only recognize <NL> to separate
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000284 lines. The 'expandtab' option will be reset. The 'textwidth'
Bram Moolenaar071d4272004-06-13 20:20:40 +0000285 option is set to 0. 'modeline' is reset. The 'binary' option
286 is set. This is done after reading the vimrc/exrc files but
287 before reading any file in the arglist. See also
288 |edit-binary|. {not in Vi}
289
290 *-l*
291-l Lisp mode. Sets the 'lisp' and 'showmatch' options on.
292
293 *-A*
294-A Arabic mode. Sets the 'arabic' option on. (Only when
295 compiled with the |+arabic| features (which include
296 |+rightleft|), otherwise Vim gives an error message
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000297 and exits.) {not in Vi}
Bram Moolenaar071d4272004-06-13 20:20:40 +0000298
299 *-F*
300-F Farsi mode. Sets the 'fkmap' and 'rightleft' options on.
301 (Only when compiled with |+rightleft| and |+farsi| features,
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000302 otherwise Vim gives an error message and exits.) {not in Vi}
Bram Moolenaar071d4272004-06-13 20:20:40 +0000303
304 *-H*
305-H Hebrew mode. Sets the 'hkmap' and 'rightleft' options on.
306 (Only when compiled with the |+rightleft| feature, otherwise
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000307 Vim gives an error message and exits.) {not in Vi}
Bram Moolenaar071d4272004-06-13 20:20:40 +0000308
309 *-V* *verbose*
310-V[N] Verbose. Sets the 'verbose' option to [N] (default: 10).
311 Messages will be given for each file that is ":source"d and
312 for reading or writing a viminfo file. Can be used to find
313 out what is happening upon startup and exit. {not in Vi}
Bram Moolenaarc81e5e72007-05-05 18:24:42 +0000314 Example: >
315 vim -V8 foobar
Bram Moolenaar071d4272004-06-13 20:20:40 +0000316
Bram Moolenaar54ee7752005-05-31 22:22:17 +0000317-V[N]{filename}
318 Like -V and set 'verbosefile' to {filename}. The result is
319 that messages are not displayed but written to the file
320 {filename}. {filename} must not start with a digit.
Bram Moolenaarc81e5e72007-05-05 18:24:42 +0000321 Example: >
322 vim -V20vimlog foobar
323<
Bram Moolenaar071d4272004-06-13 20:20:40 +0000324 *-D*
325-D Debugging. Go to debugging mode when executing the first
326 command from a script. |debug-mode|
327 {not available when compiled without the |+eval| feature}
328 {not in Vi}
329
330 *-C*
331-C Compatible mode. Sets the 'compatible' option. You can use
332 this to get 'compatible', even though a .vimrc file exists.
333 But the command ":set nocompatible" overrules it anyway.
334 Also see |compatible-default|. {not in Vi}
335
336 *-N*
337-N Not compatible mode. Resets the 'compatible' option. You can
338 use this to get 'nocompatible', when there is no .vimrc file.
339 Also see |compatible-default|. {not in Vi}
340
341 *-y* *easy*
342-y Easy mode. Implied for |evim| and |eview|. Starts with
343 'insertmode' set and behaves like a click-and-type editor.
344 This sources the script $VIMRUNTIME/evim.vim. Mappings are
345 set up to work like most click-and-type editors, see
346 |evim-keys|. The GUI is started when available.
347 {not in Vi}
348
349 *-n*
350-n No swap file will be used. Recovery after a crash will be
351 impossible. Handy if you want to view or edit a file on a
352 very slow medium (e.g., a floppy).
353 Can also be done with ":set updatecount=0". You can switch it
354 on again by setting the 'updatecount' option to some value,
355 e.g., ":set uc=100".
356 'updatecount' is set to 0 AFTER executing commands from a
357 vimrc file, but before the GUI initializations. Thus it
358 overrides a setting for 'updatecount' in a vimrc file, but not
359 in a gvimrc file. See |startup|.
360 When you want to reduce accesses to the disk (e.g., for a
361 laptop), don't use "-n", but set 'updatetime' and
362 'updatecount' to very big numbers, and type ":preserve" when
363 you want to save your work. This way you keep the possibility
364 for crash recovery.
365 {not in Vi}
366
367 *-o*
368-o[N] Open N windows, split horizontally. If [N] is not given,
369 one window is opened for every file given as argument. If
370 there is not enough room, only the first few files get a
371 window. If there are more windows than arguments, the last
372 few windows will be editing an empty file.
373 {not in Vi}
374
375 *-O*
376-O[N] Open N windows, split vertically. Otherwise it's like -o.
377 If both the -o and the -O option are given, the last one on
378 the command line determines how the windows will be split.
379 {not in Vi}
380
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000381 *-p*
382-p[N] Open N tab pages. If [N] is not given, one tab page is opened
Bram Moolenaarfd2ac762006-03-01 22:09:21 +0000383 for every file given as argument. The maximum is set with
384 'tabpagemax' pages (default 10). If there are more tab pages
385 than arguments, the last few tab pages will be editing an
Bram Moolenaarfa1d1402006-03-25 21:59:56 +0000386 empty file. Also see |tabpage|.
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000387 {not in Vi}
388
Bram Moolenaar071d4272004-06-13 20:20:40 +0000389 *-T*
390-T {terminal} Set the terminal type to "terminal". This influences the
391 codes that Vim will send to your terminal. This is normally
392 not needed, because Vim will be able to find out what type
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000393 of terminal you are using. (See |terminal-info|.) {not in Vi}
Bram Moolenaar071d4272004-06-13 20:20:40 +0000394
395 *-d*
396-d Start in diff mode, like |vimdiff|.
397 {not in Vi} {not available when compiled without the |+diff|
398 feature}
399
400-d {device} Only on the Amiga and when not compiled with the |+diff|
401 feature. Works like "-dev".
402 *-dev*
403-dev {device} Only on the Amiga: The {device} is opened to be used for
404 editing.
405 Normally you would use this to set the window position and
406 size: "-d con:x/y/width/height", e.g.,
407 "-d con:30/10/600/150". But you can also use it to start
408 editing on another device, e.g., AUX:. {not in Vi}
409 *-f*
410-f Amiga: Do not restart Vim to open a new window. This
411 option should be used when Vim is started by a program that
412 will wait for the edit session to finish (e.g., mail or
413 readnews). See |amiga-window|.
414
415 GUI: Do not disconnect from the program that started Vim.
416 'f' stands for "foreground". If omitted, the GUI forks a new
417 process and exits the current one. "-f" should be used when
418 gvim is started by a program that will wait for the edit
419 session to finish (e.g., mail or readnews). If you want gvim
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000420 never to fork, include 'f' in 'guioptions' in your |gvimrc|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000421 Careful: You can use "-gf" to start the GUI in the foreground,
422 but "-fg" is used to specify the foreground color. |gui-fork|
423 {not in Vi}
424
425 *--nofork*
426--nofork GUI: Do not fork. Same as |-f|.
427 *-u* *E282*
428-u {vimrc} The file {vimrc} is read for initializations. Most other
429 initializations are skipped; see |initialization|. This can
430 be used to start Vim in a special mode, with special
431 mappings and settings. A shell alias can be used to make
432 this easy to use. For example: >
433 alias vimc vim -u ~/.c_vimrc !*
434< Also consider using autocommands; see |autocommand|.
435 When {vimrc} is equal to "NONE" (all uppercase), all
436 initializations from files and environment variables are
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000437 skipped, including reading the |gvimrc| file when the GUI
Bram Moolenaar071d4272004-06-13 20:20:40 +0000438 starts. Loading plugins is also skipped.
439 When {vimrc} is equal to "NORC" (all uppercase), this has the
440 same effect as "NONE", but loading plugins is not skipped.
441 Using the "-u" argument has the side effect that the
442 'compatible' option will be on by default. This can have
443 unexpected effects. See |'compatible'|.
444 {not in Vi}
445
446 *-U* *E230*
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000447-U {gvimrc} The file {gvimrc} is read for initializations when the GUI
Bram Moolenaar13fcaaf2005-04-15 21:13:42 +0000448 starts. Other GUI initializations are skipped. When {gvimrc}
Bram Moolenaar8fc061c2004-12-29 21:03:02 +0000449 is equal to "NONE", no file is read for GUI initializations at
450 all. |gui-init|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000451 Exception: Reading the system-wide menu file is always done.
452 {not in Vi}
453
454 *-i*
455-i {viminfo} The file "viminfo" is used instead of the default viminfo
456 file. If the name "NONE" is used (all uppercase), no viminfo
457 file is read or written, even if 'viminfo' is set or when
458 ":rv" or ":wv" are used. See also |viminfo-file|.
459 {not in Vi}
460
461 *-x*
462-x Use encryption to read/write files. Will prompt for a key,
463 which is then stored in the 'key' option. All writes will
464 then use this key to encrypt the text. The '-x' argument is
465 not needed when reading a file, because there is a check if
466 the file that is being read has been encrypted, and Vim asks
467 for a key automatically. |encryption|
468
469 *-X*
470-X Do not try connecting to the X server to get the current
471 window title and copy/paste using the X clipboard. This
472 avoids a long startup time when running Vim in a terminal
473 emulator and the connection to the X server is slow.
474 Only makes a difference on Unix or VMS, when compiled with the
475 |+X11| feature. Otherwise it's ignored.
476 To disable the connection only for specific terminals, see the
477 'clipboard' option.
478 When the X11 Session Management Protocol (XSMP) handler has
479 been built in, the -X option also disables that connection as
480 it, too, may have undesirable delays.
481 When the connection is desired later anyway (e.g., for
482 client-server messages), call the |serverlist()| function.
483 This does not enable the XSMP handler though.
484 {not in Vi}
485
486 *-s*
487-s {scriptin} The script file "scriptin" is read. The characters in the
488 file are interpreted as if you had typed them. The same can
489 be done with the command ":source! {scriptin}". If the end
490 of the file is reached before the editor exits, further
491 characters are read from the keyboard. Only works when not
492 started in Ex mode, see |-s-ex|. See also |complex-repeat|.
493 {not in Vi}
494
Bram Moolenaar4399ef42005-02-12 14:29:27 +0000495 *-w_nr*
496-w {number}
497-w{number} Set the 'window' option to {number}.
498
Bram Moolenaar071d4272004-06-13 20:20:40 +0000499 *-w*
500-w {scriptout} All the characters that you type are recorded in the file
501 "scriptout", until you exit Vim. This is useful if you want
502 to create a script file to be used with "vim -s" or
503 ":source!". When the "scriptout" file already exists, new
504 characters are appended. See also |complex-repeat|.
Bram Moolenaar4399ef42005-02-12 14:29:27 +0000505 {scriptout} cannot start with a digit.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000506 {not in Vi}
507
508 *-W*
509-W {scriptout} Like -w, but do not append, overwrite an existing file.
510 {not in Vi}
511
Bram Moolenaar071d4272004-06-13 20:20:40 +0000512--remote [+{cmd}] {file} ...
513 Open the {file} in another Vim that functions as a server.
514 Any non-file arguments must come before this.
515 See |--remote|. {not in Vi}
516
517--remote-silent [+{cmd}] {file} ...
518 Like --remote, but don't complain if there is no server.
519 See |--remote-silent|. {not in Vi}
520
521--remote-wait [+{cmd}] {file} ...
522 Like --remote, but wait for the server to finish editing the
523 file(s).
524 See |--remote-wait|. {not in Vi}
525
526--remote-wait-silent [+{cmd}] {file} ...
527 Like --remote-wait, but don't complain if there is no server.
528 See |--remote-wait-silent|. {not in Vi}
529
530--servername {name}
531 Specify the name of the Vim server to send to or to become.
532 See |--servername|. {not in Vi}
533
534--remote-send {keys}
535 Send {keys} to a Vim server and exit.
536 See |--remote-send|. {not in Vi}
537
538--remote-expr {expr}
539 Evaluate {expr} in another Vim that functions as a server.
540 The result is printed on stdout.
541 See |--remote-expr|. {not in Vi}
542
543--serverlist Output a list of Vim server names and exit. See
Bram Moolenaarc81e5e72007-05-05 18:24:42 +0000544 |--serverlist|. {not in Vi}
Bram Moolenaar071d4272004-06-13 20:20:40 +0000545
546--socketid {id} *--socketid*
547 GTK+ GUI Vim only. Make gvim try to use GtkPlug mechanism, so
548 that it runs inside another window. See |gui-gtk-socketid|
549 for details. {not in Vi}
550
551--echo-wid *--echo-wid*
552 GTK+ GUI Vim only. Make gvim echo the Window ID on stdout,
553 which can be used to run gvim in a kpart widget. The format
554 of the output is: >
555 WID: 12345\n
556< {not in Vi}
557
558--role {role} *--role*
559 GTK+ 2 GUI only. Set the role of the main window to {role}.
560 The window role can be used by a window manager to uniquely
561 identify a window, in order to restore window placement and
562 such. The --role argument is passed automatically when
563 restoring the session on login. See |gui-gnome-session|
564 {not in Vi}
565
566-P {parent-title} *-P* *MDI* *E671* *E672*
567 Win32 only: Specify the title of the parent application. When
568 possible, Vim will run in an MDI window inside the
569 application.
570 {parent-title} must appear in the window title of the parent
571 application. Make sure that it is specific enough.
572 Note that the implementation is still primitive. It won't
573 work with all applications and the menu doesn't work.
574
575-nb *-nb*
576-nb={fname}
577-nb:{hostname}:{addr}:{password}
578 Attempt connecting to Netbeans and become an editor server for
579 it. The second form specifies a file to read connection info
580 from. The third form specifies the hostname, address and
581 password for connecting to Netbeans. |netbeans-run|
582
583Example for using a script file to change a name in several files:
584 Create a file "subs.vi" containing substitute commands and a :wq
585 command: >
586 :%s/Jones/Smith/g
587 :%s/Allen/Peter/g
588 :wq
589<
590 Execute Vim on all files you want to change: >
591
592 foreach i ( *.let ) vim -s subs.vi $i
593
594If the executable is called "view", Vim will start in Readonly mode. This is
595useful if you can make a hard or symbolic link from "view" to "vim".
596Starting in Readonly mode can also be done with "vim -R".
597
598If the executable is called "ex", Vim will start in "Ex" mode. This means it
599will accept only ":" commands. But when the "-v" argument is given, Vim will
600start in Normal mode anyway.
601
602Additional arguments are available on unix like systems when compiled with
603X11 GUI support. See |gui-resources|.
604
605==============================================================================
6062. Vim on the Amiga *starting-amiga*
607
608Starting Vim from the Workbench *workbench*
609-------------------------------
610
611Vim can be started from the Workbench by clicking on its icon twice. It will
612then start with an empty buffer.
613
614Vim can be started to edit one or more files by using a "Project" icon. The
615"Default Tool" of the icon must be the full pathname of the Vim executable.
616The name of the ".info" file must be the same as the name of the text file.
617By clicking on this icon twice, Vim will be started with the file name as
618current file name, which will be read into the buffer (if it exists). You can
619edit multiple files by pressing the shift key while clicking on icons, and
620clicking twice on the last one. The "Default Tool" for all these icons must
621be the same.
622
623It is not possible to give arguments to Vim, other than file names, from the
624workbench.
625
626Vim window *amiga-window*
627----------
628
629Vim will run in the CLI window where it was started. If Vim was started with
630the "run" or "runback" command, or if Vim was started from the workbench, it
631will open a window of its own.
632
633Technical detail:
634 To open the new window a little trick is used. As soon as Vim
635 recognizes that it does not run in a normal CLI window, it will
636 create a script file in "t:". This script file contains the same
637 command as the one Vim was started with, and an "endcli" command.
638 This script file is then executed with a "newcli" command (the "c:run"
639 and "c:newcli" commands are required for this to work). The script
640 file will hang around until reboot, or until you delete it. This
641 method is required to get the ":sh" and ":!" commands to work
642 correctly. But when Vim was started with the -f option (foreground
643 mode), this method is not used. The reason for this is that
644 when a program starts Vim with the -f option it will wait for Vim to
645 exit. With the script trick, the calling program does not know when
646 Vim exits. The -f option can be used when Vim is started by a mail
647 program which also waits for the edit session to finish. As a
648 consequence, the ":sh" and ":!" commands are not available when the
649 -f option is used.
650
651Vim will automatically recognize the window size and react to window
652resizing. Under Amiga DOS 1.3, it is advised to use the fastfonts program,
653"FF", to speed up display redrawing.
654
655==============================================================================
6563. Running eVim *evim-keys*
657
658EVim runs Vim as click-and-type editor. This is very unlike the original Vi
659idea. But it helps for people that don't use Vim often enough to learn the
660commands. Hopefully they will find out that learning to use Normal mode
661commands will make their editing much more effective.
662
663In Evim these options are changed from their default value:
664
665 :set nocompatible Use Vim improvements
666 :set insertmode Remain in Insert mode most of the time
667 :set hidden Keep invisible buffers loaded
668 :set backup Keep backup files (not for VMS)
669 :set backspace=2 Backspace over everything
670 :set autoindent auto-indent new lines
671 :set history=50 keep 50 lines of Ex commands
672 :set ruler show the cursor position
673 :set incsearch show matches halfway typing a pattern
674 :set mouse=a use the mouse in all modes
675 :set hlsearch highlight all matches for a search pattern
676 :set whichwrap+=<,>,[,] <Left> and <Right> wrap around line breaks
677 :set guioptions-=a non-Unix only: don't do auto-select
678
679Key mappings:
680 <Down> moves by screen lines rather than file lines
681 <Up> idem
682 Q does "gq", formatting, instead of Ex mode
683 <BS> in Visual mode: deletes the selection
684 CTRL-X in Visual mode: Cut to clipboard
685 <S-Del> idem
686 CTRL-C in Visual mode: Copy to clipboard
687 <C-Insert> idem
688 CTRL-V Pastes from the clipboard (in any mode)
689 <S-Insert> idem
690 CTRL-Q do what CTRL-V used to do
691 CTRL-Z undo
692 CTRL-Y redo
693 <M-Space> system menu
694 CTRL-A select all
695 <C-Tab> next window, CTRL-W w
696 <C-F4> close window, CTRL-W c
697
698Additionally:
699- ":behave mswin" is used |:behave|
700- syntax highlighting is enabled
701- filetype detection is enabled, filetype plugins and indenting is enabled
702- in a text file 'textwidth' is set to 78
703
704One hint: If you want to go to Normal mode to be able to type a sequence of
705commands, use CTRL-L. |i_CTRL-L|
706
707==============================================================================
7084. Initialization *initialization* *startup*
709
710This section is about the non-GUI version of Vim. See |gui-fork| for
711additional initialization when starting the GUI.
712
713At startup, Vim checks environment variables and files and sets values
714accordingly. Vim proceeds in this order:
715
7161. Set the 'shell' and 'term' option *SHELL* *COMSPEC* *TERM*
717 The environment variable SHELL, if it exists, is used to set the
718 'shell' option. On MS-DOS and Win32, the COMSPEC variable is used
719 if SHELL is not set.
720 The environment variable TERM, if it exists, is used to set the 'term'
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +0000721 option. However, 'term' will change later when starting the GUI (step
722 8 below).
Bram Moolenaar071d4272004-06-13 20:20:40 +0000723
7242. Process the arguments
725 The options and file names from the command that start Vim are
726 inspected. Buffers are created for all files (but not loaded yet).
Bram Moolenaar54ee7752005-05-31 22:22:17 +0000727 The |-V| argument can be used to display or log what happens next,
728 useful for debugging the initializations.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000729
7303. Execute Ex commands, from environment variables and/or files
731 An environment variable is read as one Ex command line, where multiple
732 commands must be separated with '|' or "<NL>".
733 *vimrc* *exrc*
734 A file that contains initialization commands is called a "vimrc" file.
735 Each line in a vimrc file is executed as an Ex command line. It is
736 sometimes also referred to as "exrc" file. They are the same type of
737 file, but "exrc" is what Vi always used, "vimrc" is a Vim specific
738 name. Also see |vimrc-intro|.
739
740 Recommended place for your personal initializations:
741 Unix $HOME/.vimrc
742 OS/2 $HOME/.vimrc or $VIM/.vimrc (or _vimrc)
743 MS-DOS and Win32 $HOME/_vimrc or $VIM/_vimrc
744 Amiga s:.vimrc or $VIM/.vimrc
745
746 If Vim was started with "-u filename", the file "filename" is used.
747 All following initializations until 4. are skipped.
748 "vim -u NORC" can be used to skip these initializations without
749 reading a file. "vim -u NONE" also skips loading plugins. |-u|
750
751 If Vim was started in Ex mode with the "-s" argument, all following
752 initializations until 4. are skipped. Only the "-u" option is
753 interpreted.
754 *evim.vim*
755 a. If vim was started as |evim| or |eview| or with the |-y| argument, the
756 script $VIMRUNTIME/evim.vim will be loaded.
757 *system-vimrc*
758 b. For Unix, MS-DOS, MS-Windows, OS/2, VMS, Macintosh, RISC-OS and Amiga
759 the system vimrc file is read for initializations. The path of this
760 file is shown with the ":version" command. Mostly it's "$VIM/vimrc".
761 Note that this file is ALWAYS read in 'compatible' mode, since the
762 automatic resetting of 'compatible' is only done later. Add a ":set
763 nocp" command if you like.
Bram Moolenaar3991dab2006-03-27 17:01:56 +0000764 For the Macintosh the $VIMRUNTIME/macmap.vim is read.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000765
766 *VIMINIT* *.vimrc* *_vimrc* *EXINIT* *.exrc* *_exrc*
767 c. Four places are searched for initializations. The first that exists
Bram Moolenaar910f66f2006-04-05 20:41:53 +0000768 is used, the others are ignored. The $MYVIMRC environment variable is
769 set to the file that was first found, unless $MYVIMRC was already set.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000770 - The environment variable VIMINIT (see also |compatible-default|) (*)
771 The value of $VIMINIT is used as an Ex command line.
772 - The user vimrc file(s):
773 "$HOME/.vimrc" (for Unix and OS/2) (*)
774 "s:.vimrc" (for Amiga) (*)
775 "home:.vimrc" (for Amiga) (*)
776 "$VIM/.vimrc" (for OS/2 and Amiga) (*)
777 "$HOME/_vimrc" (for MS-DOS and Win32) (*)
Bram Moolenaar21cf8232004-07-16 20:18:37 +0000778 "$VIM/_vimrc" (for MS-DOS and Win32) (*)
Bram Moolenaar071d4272004-06-13 20:20:40 +0000779 Note: For Unix, OS/2 and Amiga, when ".vimrc" does not exist,
780 "_vimrc" is also tried, in case an MS-DOS compatible file
781 system is used. For MS-DOS and Win32 ".vimrc" is checked
782 after "_vimrc", in case long file names are used.
783 Note: For MS-DOS and Win32, "$HOME" is checked first. If no
784 "_vimrc" or ".vimrc" is found there, "$VIM" is tried.
785 See |$VIM| for when $VIM is not set.
786 - The environment variable EXINIT.
787 The value of $EXINIT is used as an Ex command line.
788 - The user exrc file(s). Same as for the user vimrc file, but with
Bram Moolenaar5c5474b2005-04-19 21:40:26 +0000789 "vimrc" replaced by "exrc". But only one of ".exrc" and "_exrc" is
790 used, depending on the system. And without the (*)!
Bram Moolenaar071d4272004-06-13 20:20:40 +0000791
792 d. If the 'exrc' option is on (which is not the default), the current
Bram Moolenaar5c5474b2005-04-19 21:40:26 +0000793 directory is searched for three files. The first that exists is used,
Bram Moolenaar071d4272004-06-13 20:20:40 +0000794 the others are ignored.
795 - The file ".vimrc" (for Unix, Amiga and OS/2) (*)
796 "_vimrc" (for MS-DOS and Win32) (*)
797 - The file "_vimrc" (for Unix, Amiga and OS/2) (*)
798 ".vimrc" (for MS-DOS and Win32) (*)
799 - The file ".exrc" (for Unix, Amiga and OS/2)
800 "_exrc" (for MS-DOS and Win32)
Bram Moolenaar071d4272004-06-13 20:20:40 +0000801
802 (*) Using this file or environment variable will cause 'compatible' to be
803 off by default. See |compatible-default|.
804
8054. Load the plugin scripts. *load-plugins*
806 This does the same as the command: >
Bram Moolenaar1c7715d2005-10-03 22:02:18 +0000807 :runtime! plugin/**/*.vim
Bram Moolenaar071d4272004-06-13 20:20:40 +0000808< The result is that all directories in the 'runtimepath' option will be
809 searched for the "plugin" sub-directory and all files ending in ".vim"
Bram Moolenaar1c7715d2005-10-03 22:02:18 +0000810 will be sourced (in alphabetical order per directory), also in
811 subdirectories.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000812 Loading plugins won't be done when:
813 - The 'loadplugins' option was reset in a vimrc file.
814 - The |--noplugin| command line argument is used.
815 - The "-u NONE" command line argument is used |-u|.
816 - When Vim was compiled without the |+eval| feature.
Bram Moolenaar8ada17c2006-01-19 22:16:24 +0000817 Note that using "-c 'set noloadplugins'" doesn't work, because the
818 commands from the command line have not been executed yet. You can
819 use "--cmd 'set noloadplugins'" |--cmd|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000820
8215. Set 'shellpipe' and 'shellredir'
822 The 'shellpipe' and 'shellredir' options are set according to the
823 value of the 'shell' option, unless they have been set before.
824 This means that Vim will figure out the values of 'shellpipe' and
825 'shellredir' for you, unless you have set them yourself.
826
8276. Set 'updatecount' to zero, if "-n" command argument used
828
8297. Set binary options
830 If the "-b" flag was given to Vim, the options for binary editing will
831 be set now. See |-b|.
832
8338. Perform GUI initializations
834 Only when starting "gvim", the GUI initializations will be done. See
835 |gui-init|.
836
8379. Read the viminfo file
838 If the 'viminfo' option is not empty, the viminfo file is read. See
839 |viminfo-file|.
840
84110. Read the quickfix file
842 If the "-q" flag was given to Vim, the quickfix file is read. If this
843 fails, Vim exits.
844
84511. Open all windows
846 When the |-o| flag was given, windows will be opened (but not
847 displayed yet).
Bram Moolenaar7e8fd632006-02-18 22:14:51 +0000848 When the |-p| flag was given, tab pages will be created (but not
849 displayed yet).
Bram Moolenaar071d4272004-06-13 20:20:40 +0000850 When switching screens, it happens now. Redrawing starts.
851 If the "-q" flag was given to Vim, the first error is jumped to.
852 Buffers for all windows will be loaded.
853
85412. Execute startup commands
855 If a "-t" flag was given to Vim, the tag is jumped to.
856 The commands given with the |-c| and |+cmd| arguments are executed.
857 If the 'insertmode' option is set, Insert mode is entered.
858 The |VimEnter| autocommands are executed.
859
860Some hints on using initializations:
861
862Standard setup:
863Create a vimrc file to set the default settings and mappings for all your edit
864sessions. Put it in a place so that it will be found by 3b:
865 ~/.vimrc (Unix and OS/2)
866 s:.vimrc (Amiga)
867 $VIM\_vimrc (MS-DOS and Win32)
868Note that creating a vimrc file will cause the 'compatible' option to be off
869by default. See |compatible-default|.
870
871Local setup:
872Put all commands that you need for editing a specific directory only into a
873vimrc file and place it in that directory under the name ".vimrc" ("_vimrc"
874for MS-DOS and Win32). NOTE: To make Vim look for these special files you
875have to turn on the option 'exrc'. See |trojan-horse| too.
876
877System setup:
878This only applies if you are managing a Unix system with several users and
879want to set the defaults for all users. Create a vimrc file with commands
880for default settings and mappings and put it in the place that is given with
881the ":version" command.
882
883Saving the current state of Vim to a file:
884Whenever you have changed values of options or when you have created a
885mapping, then you may want to save them in a vimrc file for later use. See
886|save-settings| about saving the current state of settings to a file.
887
888Avoiding setup problems for Vi users:
889Vi uses the variable EXINIT and the file "~/.exrc". So if you do not want to
890interfere with Vi, then use the variable VIMINIT and the file "vimrc" instead.
891
892Amiga environment variables:
893On the Amiga, two types of environment variables exist. The ones set with the
894DOS 1.3 (or later) setenv command are recognized. See the AmigaDos 1.3
895manual. The environment variables set with the old Manx Set command (before
896version 5.0) are not recognized.
897
898MS-DOS line separators:
899On MS-DOS-like systems (MS-DOS itself, Win32, and OS/2), Vim assumes that all
900the vimrc files have <CR> <NL> pairs as line separators. This will give
901problems if you have a file with only <NL>s and have a line like
902":map xx yy^M". The trailing ^M will be ignored.
903
904 *compatible-default*
905When Vim starts, the 'compatible' option is on. This will be used when Vim
906starts its initializations. But as soon as a user vimrc file is found, or a
907vimrc file in the current directory, or the "VIMINIT" environment variable is
908set, it will be set to 'nocompatible'. This has the side effect of setting or
909resetting other options (see 'compatible'). But only the options that have
910not been set or reset will be changed. This has the same effect like the
911value of 'compatible' had this value when starting Vim. Note that this
Bram Moolenaarc81e5e72007-05-05 18:24:42 +0000912doesn't happen for the system-wide vimrc file nor when Vim was started with
913the |-u| command line argument. It does also happen for gvimrc files. The
914$MYVIMRC or $MYGVIMRC file will be set to the first found vimrc and/or gvimrc
915file.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000916
917But there is a side effect of setting or resetting 'compatible' at the moment
918a .vimrc file is found: Mappings are interpreted the moment they are
919encountered. This makes a difference when using things like "<CR>". If the
920mappings depend on a certain value of 'compatible', set or reset it before
921giving the mapping.
922
923The above behavior can be overridden in these ways:
924- If the "-N" command line argument is given, 'nocompatible' will be used,
925 even when no vimrc file exists.
926- If the "-C" command line argument is given, 'compatible' will be used, even
927 when a vimrc file exists.
928- If the "-u {vimrc}" argument is used, 'compatible' will be used.
929- When the name of the executable ends in "ex", then this works like the "-C"
930 argument was given: 'compatible' will be used, even when a vimrc file
931 exists. This has been done to make Vim behave like "ex", when it is started
932 as "ex".
933
934Avoiding trojan horses: *trojan-horse*
935While reading the "vimrc" or the "exrc" file in the current directory, some
936commands can be disabled for security reasons by setting the 'secure' option.
937This is always done when executing the command from a tags file. Otherwise it
938would be possible that you accidentally use a vimrc or tags file that somebody
939else created and contains nasty commands. The disabled commands are the ones
940that start a shell, the ones that write to a file, and ":autocmd". The ":map"
941commands are echoed, so you can see which keys are being mapped.
942 If you want Vim to execute all commands in a local vimrc file, you
943can reset the 'secure' option in the EXINIT or VIMINIT environment variable or
944in the global "exrc" or "vimrc" file. This is not possible in "vimrc" or
945"exrc" in the current directory, for obvious reasons.
946 On Unix systems, this only happens if you are not the owner of the
947vimrc file. Warning: If you unpack an archive that contains a vimrc or exrc
948file, it will be owned by you. You won't have the security protection. Check
949the vimrc file before you start Vim in that directory, or reset the 'exrc'
950option. Some Unix systems allow a user to do "chown" on a file. This makes
951it possible for another user to create a nasty vimrc and make you the owner.
952Be careful!
953 When using tag search commands, executing the search command (the last
954part of the line in the tags file) is always done in secure mode. This works
955just like executing a command from a vimrc/exrc in the current directory.
956
957 *slow-start*
958If Vim takes a long time to start up, there may be a few causes:
959- If the Unix version was compiled with the GUI and/or X11 (check the output
960 of ":version" for "+GUI" and "+X11"), it may need to load shared libraries
961 and connect to the X11 server. Try compiling a version with GUI and X11
962 disabled. This also should make the executable smaller.
963 Use the |-X| command line argument to avoid connecting to the X server when
964 running in a terminal.
965- If you have "viminfo" enabled, the loading of the viminfo file may take a
966 while. You can find out if this is the problem by disabling viminfo for a
967 moment (use the Vim argument "-i NONE", |-i|). Try reducing the number of
968 lines stored in a register with ":set viminfo='20,<50,s10". |viminfo-file|.
969
970 *:intro*
971When Vim starts without a file name, an introductory message is displayed (for
972those who don't know what Vim is). It is removed as soon as the display is
973redrawn in any way. To see the message again, use the ":intro" command (if
974there is not enough room, you will see only part of it).
975 To avoid the intro message on startup, add the 'I' flag to 'shortmess'.
976
977 *info-message*
978The |--help| and |--version| arguments cause Vim to print a message and then
979exit. Normally the message is send to stdout, thus can be redirected to a
980file with: >
981
982 vim --help >file
983
984From inside Vim: >
985
986 :read !vim --help
987
988When using gvim, it detects that it might have been started from the desktop,
989without a terminal to show messages on. This is detected when both stdout and
990stderr are not a tty. This breaks the ":read" command, as used in the example
991above. To make it work again, set 'shellredir' to ">" instead of the default
992">&": >
993
994 :set shellredir=>
995 :read !gvim --help
996
997This still won't work for systems where gvim does not use stdout at all
998though.
999
1000==============================================================================
10015. $VIM and $VIMRUNTIME
1002 *$VIM*
1003The environment variable "$VIM" is used to locate various user files for Vim,
1004such as the user startup script ".vimrc". This depends on the system, see
1005|startup|.
1006
1007To avoid the need for every user to set the $VIM environment variable, Vim
1008will try to get the value for $VIM in this order:
10091. The value defined by the $VIM environment variable. You can use this to
1010 make Vim look in a specific directory for its support files. Example: >
1011 setenv VIM /home/paul/vim
10122. The path from 'helpfile' is used, unless it contains some environment
1013 variable too (the default is "$VIMRUNTIME/doc/help.txt": chicken-egg
1014 problem). The file name ("help.txt" or any other) is removed. Then
1015 trailing directory names are removed, in this order: "doc", "runtime" and
1016 "vim{version}" (e.g., "vim54").
10173. For MSDOS, Win32 and OS/2 Vim tries to use the directory name of the
1018 executable. If it ends in "/src", this is removed. This is useful if you
1019 unpacked the .zip file in some directory, and adjusted the search path to
1020 find the vim executable. Trailing directory names are removed, in this
1021 order: "runtime" and "vim{version}" (e.g., "vim54").
10224. For Unix the compile-time defined installation directory is used (see the
1023 output of ":version").
1024
1025Once Vim has done this once, it will set the $VIM environment variable. To
1026change it later, use a ":let" command like this: >
1027 :let $VIM = "/home/paul/vim/"
1028<
1029 *$VIMRUNTIME*
1030The environment variable "$VIMRUNTIME" is used to locate various support
1031files, such as the on-line documentation and files used for syntax
1032highlighting. For example, the main help file is normally
1033"$VIMRUNTIME/doc/help.txt".
1034You don't normally set $VIMRUNTIME yourself, but let Vim figure it out. This
1035is the order used to find the value of $VIMRUNTIME:
10361. If the environment variable $VIMRUNTIME is set, it is used. You can use
1037 this when the runtime files are in an unusual location.
10382. If "$VIM/vim{version}" exists, it is used. {version} is the version
1039 number of Vim, without any '-' or '.'. For example: "$VIM/vim54". This is
1040 the normal value for $VIMRUNTIME.
10413. If "$VIM/runtime" exists, it is used.
10424. The value of $VIM is used. This is for backwards compatibility with older
1043 versions.
10445. When the 'helpfile' option is set and doesn't contain a '$', its value is
1045 used, with "doc/help.txt" removed from the end.
1046
1047For Unix, when there is a compiled-in default for $VIMRUNTIME (check the
1048output of ":version"), steps 2, 3 and 4 are skipped, and the compiled-in
1049default is used after step 5. This means that the compiled-in default
1050overrules the value of $VIM. This is useful if $VIM is "/etc" and the runtime
1051files are in "/usr/share/vim/vim54".
1052
1053Once Vim has done this once, it will set the $VIMRUNTIME environment variable.
1054To change it later, use a ":let" command like this: >
1055 :let $VIMRUNTIME = "/home/piet/vim/vim54"
1056
Bram Moolenaared203462004-06-16 11:19:22 +00001057In case you need the value of $VIMRUNTIME in a shell (e.g., for a script that
1058greps in the help files) you might be able to use this: >
1059
1060 VIMRUNTIME=`vim -e -T dumb --cmd 'exe "set t_cm=\<C-M>"|echo $VIMRUNTIME|quit' | tr -d '\015' `
1061
Bram Moolenaar071d4272004-06-13 20:20:40 +00001062==============================================================================
10636. Suspending *suspend*
1064
1065 *iconize* *iconise* *CTRL-Z* *v_CTRL-Z*
1066CTRL-Z Suspend Vim, like ":stop".
1067 Works in Normal and in Visual mode. In Insert and
1068 Command-line mode, the CTRL-Z is inserted as a normal
1069 character. In Visual mode Vim goes back to Normal
1070 mode.
Bram Moolenaar0d660222005-01-07 21:51:51 +00001071 Note: if CTRL-Z undoes a change see |mswin.vim|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001072
1073
1074:sus[pend][!] or *:sus* *:suspend* *:st* *:stop*
1075:st[op][!] Suspend Vim.
1076 If the '!' is not given and 'autowrite' is set, every
1077 buffer with changes and a file name is written out.
1078 If the '!' is given or 'autowrite' is not set, changed
1079 buffers are not written, don't forget to bring Vim
1080 back to the foreground later!
1081
1082In the GUI, suspending is implemented as iconising gvim. In Windows 95/NT,
1083gvim is minimized.
1084
1085On many Unix systems, it is possible to suspend Vim with CTRL-Z. This is only
1086possible in Normal and Visual mode (see next chapter, |vim-modes|). Vim will
1087continue if you make it the foreground job again. On other systems, CTRL-Z
1088will start a new shell. This is the same as the ":sh" command. Vim will
1089continue if you exit from the shell.
1090
1091In X-windows the selection is disowned when Vim suspends. this means you
1092can't paste it in another application (since Vim is going to sleep an attempt
1093to get the selection would make the program hang).
1094
1095==============================================================================
10967. Saving settings *save-settings*
1097
1098Mostly you will edit your vimrc files manually. This gives you the greatest
1099flexibility. There are a few commands to generate a vimrc file automatically.
1100You can use these files as they are, or copy/paste lines to include in another
1101vimrc file.
1102
1103 *:mk* *:mkexrc*
1104:mk[exrc] [file] Write current key mappings and changed options to
1105 [file] (default ".exrc" in the current directory),
1106 unless it already exists. {not in Vi}
1107
1108:mk[exrc]! [file] Always write current key mappings and changed
1109 options to [file] (default ".exrc" in the current
1110 directory). {not in Vi}
1111
1112 *:mkv* *:mkvimrc*
1113:mkv[imrc][!] [file] Like ":mkexrc", but the default is ".vimrc" in the
1114 current directory. The ":version" command is also
1115 written to the file. {not in Vi}
1116
1117These commands will write ":map" and ":set" commands to a file, in such a way
1118that when these commands are executed, the current key mappings and options
1119will be set to the same values. The options 'columns', 'endofline',
1120'fileformat', 'key', 'lines', 'modified', 'scroll', 'term', 'textmode',
1121'ttyfast' and 'ttymouse' are not included, because these are terminal or file
1122dependent. Note that the options 'binary', 'paste' and 'readonly' are
1123included, this might not always be what you want.
1124
1125When special keys are used in mappings, The 'cpoptions' option will be
1126temporarily set to its Vim default, to avoid the mappings to be
1127misinterpreted. This makes the file incompatible with Vi, but makes sure it
1128can be used with different terminals.
1129
1130Only global mappings are stored, not mappings local to a buffer.
1131
1132A common method is to use a default ".vimrc" file, make some modifications
1133with ":map" and ":set" commands and write the modified file. First read the
1134default ".vimrc" in with a command like ":source ~piet/.vimrc.Cprogs", change
1135the settings and then save them in the current directory with ":mkvimrc!". If
1136you want to make this file your default .vimrc, move it to your home directory
1137(on Unix), s: (Amiga) or $VIM directory (MS-DOS). You could also use
1138autocommands |autocommand| and/or modelines |modeline|.
1139
Bram Moolenaar362e1a32006-03-06 23:29:24 +00001140 *vimrc-option-example*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001141If you only want to add a single option setting to your vimrc, you can use
1142these steps:
11431. Edit your vimrc file with Vim.
11442. Play with the option until it's right. E.g., try out different values for
1145 'guifont'.
11463. Append a line to set the value of the option, using the expression register
1147 '=' to enter the value. E.g., for the 'guifont' option: >
1148 o:set guifont=<C-R>=&guifont<CR><Esc>
1149< [<C-R> is a CTRL-R, <CR> is a return, <Esc> is the escape key]
Bram Moolenaar362e1a32006-03-06 23:29:24 +00001150 You need to escape special characters, esp. spaces.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001151
1152Note that when you create a .vimrc file, this can influence the 'compatible'
1153option, which has several side effects. See |'compatible'|.
1154":mkvimrc", ":mkexrc" and ":mksession" write the command to set or reset the
1155'compatible' option to the output file first, because of these side effects.
1156
1157==============================================================================
11588. Views and Sessions *views-sessions*
1159
1160This is introduced in sections |21.4| and |21.5| of the user manual.
1161
1162 *View* *view-file*
1163A View is a collection of settings that apply to one window. You can save a
1164View and when you restore it later, the text is displayed in the same way.
1165The options and mappings in this window will also be restored, so that you can
1166continue editing like when the View was saved.
1167
1168 *Session* *session-file*
1169A Session keeps the Views for all windows, plus the global settings. You can
1170save a Session and when you restore it later the window layout looks the same.
1171You can use a Session to quickly switch between different projects,
1172automatically loading the files you were last working on in that project.
1173
1174Views and Sessions are a nice addition to viminfo-files, which are used to
1175remember information for all Views and Sessions together |viminfo-file|.
1176
1177You can quickly start editing with a previously saved View or Session with the
1178|-S| argument: >
1179 vim -S Session.vim
1180<
1181All this is {not in Vi} and {not available when compiled without the
1182|+mksession| feature}.
1183
1184 *:mks* *:mksession*
1185:mks[ession][!] [file] Write a Vim script that restores the current editing
1186 session.
1187 When [!] is included an existing file is overwritten.
1188 When [file] is omitted "Session.vim" is used.
1189
1190The output of ":mksession" is like ":mkvimrc", but additional commands are
1191added to the file. Which ones depends on the 'sessionoptions' option. The
1192resulting file, when executed with a ":source" command:
11931. Restores global mappings and options, if 'sessionoptions' contains
1194 "options". Script-local mappings will not be written.
11952. Restores global variables that start with an uppercase letter and contain
1196 at least one lowercase letter, if 'sessionoptions' contains "globals".
11973. Unloads all currently loaded buffers.
11984. Restores the current directory if 'sessionoptions' contains "curdir", or
1199 sets the current directory to where the Session file is if 'sessionoptions'
1200 contains "sesdir".
12015. Restores GUI Vim window position, if 'sessionoptions' contains "winpos".
12026. Restores screen size, if 'sessionoptions' contains "resize".
12037. Reloads the buffer list, with the last cursor positions. If
1204 'sessionoptions' contains "buffers" then all buffers are restored,
1205 including hidden and unloaded buffers. Otherwise only buffers in windows
1206 are restored.
12078. Restores all windows with the same layout. If 'sessionoptions' contains
Bram Moolenaarc81e5e72007-05-05 18:24:42 +00001208 "help", help windows are restored. If 'sessionoptions' contains "blank",
1209 windows editing a buffer without a name will be restored.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001210 If 'sessionoptions' contains "winsize" and no (help/blank) windows were
1211 left out, the window sizes are restored (relative to the screen size).
1212 Otherwise, the windows are just given sensible sizes.
12139. Restores the Views for all the windows, as with |:mkview|. But
1214 'sessionoptions' is used instead of 'viewoptions'.
121510. If a file exists with the same name as the Session file, but ending in
1216 "x.vim" (for eXtra), executes that as well. You can use *x.vim files to
1217 specify additional settings and actions associated with a given Session,
1218 such as creating menu items in the GUI version.
1219
1220After restoring the Session, the full filename of your current Session is
1221available in the internal variable "v:this_session" |this_session-variable|.
1222An example mapping: >
1223 :nmap <F2> :wa<Bar>exe "mksession! " . v:this_session<CR>:so ~/sessions/
1224This saves the current Session, and starts off the command to load another.
1225
Bram Moolenaar4a85b412006-04-23 22:40:29 +00001226A session includes all tab pages, unless "tabpages" was removed from
1227'sessionoptions'. |tab-page|
Bram Moolenaar7e8fd632006-02-18 22:14:51 +00001228
Bram Moolenaar9372a112005-12-06 19:59:18 +00001229The |SessionLoadPost| autocmd event is triggered after a session file is
1230loaded/sourced.
1231 *SessionLoad-variable*
1232While the session file is loading the SessionLoad global variable is set to 1.
1233Plugins can use this to postpone some work until the SessionLoadPost event is
1234triggered.
1235
Bram Moolenaar071d4272004-06-13 20:20:40 +00001236 *:mkvie* *:mkview*
1237:mkvie[w][!] [file] Write a Vim script that restores the contents of the
1238 current window.
1239 When [!] is included an existing file is overwritten.
1240 When [file] is omitted or is a number from 1 to 9, a
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00001241 name is generated and 'viewdir' prepended. When the
1242 last directory name in 'viewdir' does not exist, this
1243 directory is created.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001244 An existing file is always overwritten then. Use
1245 |:loadview| to load this view again.
1246 When [file] is the name of a file ('viewdir' is not
1247 used), a command to edit the file is added to the
1248 generated file.
1249
1250The output of ":mkview" contains these items:
12511. The argument list used in the window. When the global argument list is
1252 used it is reset to the global list.
1253 The index in the argument list is also restored.
12542. The file being edited in the window. If there is no file, the window is
1255 made empty.
12563. Restore mappings, abbreviations and options local to the window if
1257 'viewoptions' contains "options" or "localoptions". For the options it
1258 restores only values that are local to the current buffer and values local
1259 to the window.
1260 When storing the view as part of a session and "options" is in
1261 'sessionoptions', global values for local options will be stored too.
12624. Restore folds when using manual folding and 'viewoptions' contains
1263 "folds". Restore manually opened and closed folds.
12645. The scroll position and the cursor position in the file. Doesn't work very
1265 well when there are closed folds.
12666. The local current directory, if it is different from the global current
1267 directory.
1268
1269Note that Views and Sessions are not perfect:
1270- They don't restore everything. For example, defined functions, autocommands
1271 and ":syntax on" are not included. Things like register contents and
1272 command line history are in viminfo, not in Sessions or Views.
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001273- Global option values are only set when they differ from the default value.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001274 When the current value is not the default value, loading a Session will not
1275 set it back to the default value. Local options will be set back to the
1276 default value though.
1277- Existing mappings will be overwritten without warning. An existing mapping
1278 may cause an error for ambiguity.
1279- When storing manual folds and when storing manually opened/closed folds,
1280 changes in the file between saving and loading the view will mess it up.
1281- The Vim script is not very efficient. But still faster than typing the
1282 commands yourself!
1283
1284 *:lo* *:loadview*
1285:lo[adview] [nr] Load the view for the current file. When [nr] is
1286 omitted, the view stored with ":mkview" is loaded.
1287 When [nr] is specified, the view stored with ":mkview
1288 [nr]" is loaded.
1289
1290The combination of ":mkview" and ":loadview" can be used to store up to ten
1291different views of a file. These are remembered in the directory specified
1292with the 'viewdir' option. The views are stored using the file name. If a
1293file is renamed or accessed through a (symbolic) link the view will not be
1294found.
1295
1296You might want to clean up your 'viewdir' directory now and then.
1297
1298To automatically save and restore views for *.c files: >
1299 au BufWinLeave *.c mkview
1300 au BufWinEnter *.c silent loadview
1301
1302==============================================================================
13039. The viminfo file *viminfo* *viminfo-file* *E136*
1304 *E575* *E576* *E577*
1305If you exit Vim and later start it again, you would normally lose a lot of
1306information. The viminfo file can be used to remember that information, which
1307enables you to continue where you left off.
1308
1309This is introduced in section |21.3| of the user manual.
1310
1311The viminfo file is used to store:
1312- The command line history.
1313- The search string history.
1314- The input-line history.
Bram Moolenaar49cd9572005-01-03 21:06:01 +00001315- Contents of non-empty registers.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001316- Marks for several files.
1317- File marks, pointing to locations in files.
1318- Last search/substitute pattern (for 'n' and '&').
1319- The buffer list.
1320- Global variables.
1321
1322The viminfo file is not supported when the |+viminfo| feature has been
1323disabled at compile time.
1324
1325You could also use a Session file. The difference is that the viminfo file
1326does not depend on what you are working on. There normally is only one
1327viminfo file. Session files are used to save the state of a specific editing
1328Session. You could have several Session files, one for each project you are
1329working on. Viminfo and Session files together can be used to effectively
1330enter Vim and directly start working in your desired setup. |session-file|
1331
1332 *viminfo-read*
1333When Vim is started and the 'viminfo' option is non-empty, the contents of
1334the viminfo file are read and the info can be used in the appropriate places.
1335The marks are not read in at startup (but file marks are). See
1336|initialization| for how to set the 'viminfo' option upon startup.
1337
1338 *viminfo-write*
1339When Vim exits and 'viminfo' is non-empty, the info is stored in the viminfo
1340file (it's actually merged with the existing one, if one exists). The
1341'viminfo' option is a string containing information about what info should be
1342stored, and contains limits on how much should be stored (see 'viminfo').
1343
1344Notes for Unix:
1345- The file protection for the viminfo file will be set to prevent other users
1346 from being able to read it, because it may contain any text or commands that
1347 you have worked with.
1348- If you want to share the viminfo file with other users (e.g. when you "su"
1349 to another user), you can make the file writable for the group or everybody.
1350 Vim will preserve this when writing new viminfo files. Be careful, don't
1351 allow just anybody to read and write your viminfo file!
1352- Vim will not overwrite a viminfo file that is not writable by the current
1353 "real" user. This helps for when you did "su" to become root, but your
1354 $HOME is still set to a normal user's home directory. Otherwise Vim would
1355 create a viminfo file owned by root that nobody else can read.
Bram Moolenaar69c2f172007-05-12 14:57:31 +00001356- The viminfo file cannot be a symbolic link. This is to avoid security
1357 issues.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001358
1359Marks are stored for each file separately. When a file is read and 'viminfo'
1360is non-empty, the marks for that file are read from the viminfo file. NOTE:
1361The marks are only written when exiting Vim, which is fine because marks are
1362remembered for all the files you have opened in the current editing session,
1363unless ":bdel" is used. If you want to save the marks for a file that you are
1364about to abandon with ":bdel", use ":wv". The '[' and ']' marks are not
1365stored, but the '"' mark is. The '"' mark is very useful for jumping to the
1366cursor position when the file was last exited. No marks are saved for files
1367that start with any string given with the "r" flag in 'viminfo'. This can be
1368used to avoid saving marks for files on removable media (for MS-DOS you would
1369use "ra:,rb:", for Amiga "rdf0:,rdf1:,rdf2:").
1370
1371 *viminfo-file-marks*
1372Uppercase marks ('A to 'Z) are stored when writing the viminfo file. The
1373numbered marks ('0 to '9) are a bit special. When the viminfo file is written
1374(when exiting or with the ":wviminfo" command), '0 is set to the current cursor
1375position and file. The old '0 is moved to '1, '1 to '2, etc. This
1376resembles what happens with the "1 to "9 delete registers. If the current
1377cursor position is already present in '0 to '9, it is moved to '0, to avoid
1378having the same position twice. The result is that with "'0", you can jump
1379back to the file and line where you exited Vim. To do that right away, try
1380using this command: >
1381
1382 vim -c "normal '0"
1383
1384In a shell you could make an alias for it: >
1385
1386 alias lvim vim -c '"'normal "'"0'"'
1387
1388Use the "r" flag in 'viminfo' to specify for which files no marks should be
1389remembered.
1390
1391
1392VIMINFO FILE NAME *viminfo-file-name*
1393
1394- The default name of the viminfo file is "$HOME/.viminfo" for Unix and OS/2,
1395 "s:.viminfo" for Amiga, "$HOME\_viminfo" for MS-DOS and Win32. For the last
1396 two, when $HOME is not set, "$VIM\_viminfo" is used. When $VIM is also not
1397 set, "c:\_viminfo" is used. For OS/2 "$VIM/.viminfo" is used when $HOME is
1398 not set and $VIM is set.
1399- The 'n' flag in the 'viminfo' option can be used to specify another viminfo
1400 file name |'viminfo'|.
1401- The "-i" Vim argument can be used to set another file name, |-i|. When the
1402 file name given is "NONE" (all uppercase), no viminfo file is ever read or
1403 written. Also not for the commands below!
1404- For the commands below, another file name can be given, overriding the
1405 default and the name given with 'viminfo' or "-i" (unless it's NONE).
1406
1407
1408CHARACTER ENCODING *viminfo-encoding*
1409
1410The text in the viminfo file is encoded as specified with the 'encoding'
1411option. Normally you will always work with the same 'encoding' value, and
1412this works just fine. However, if you read the viminfo file with another
1413value for 'encoding' than what it was written with, some of the text
1414(non-ASCII characters) may be invalid. If this is unacceptable, add the 'c'
1415flag to the 'viminfo' option: >
1416 :set viminfo+=c
1417Vim will then attempt to convert the text in the viminfo file from the
1418'encoding' value it was written with to the current 'encoding' value. This
1419requires Vim to be compiled with the |+iconv| feature. Filenames are not
1420converted.
1421
1422
1423MANUALLY READING AND WRITING
1424
1425Two commands can be used to read and write the viminfo file manually. This
1426can be used to exchange registers between two running Vim programs: First
1427type ":wv" in one and then ":rv" in the other. Note that if the register
1428already contained something, then ":rv!" would be required. Also note
1429however that this means everything will be overwritten with information from
1430the first Vim, including the command line history, etc.
1431
1432The viminfo file itself can be edited by hand too, although we suggest you
1433start with an existing one to get the format right. It is reasonably
1434self-explanatory once you're in there. This can be useful in order to
1435create a second file, say "~/.my_viminfo" which could contain certain
1436settings that you always want when you first start Vim. For example, you
1437can preload registers with particular data, or put certain commands in the
1438command line history. A line in your .vimrc file like >
1439 :rviminfo! ~/.my_viminfo
1440can be used to load this information. You could even have different viminfos
1441for different types of files (e.g., C code) and load them based on the file
1442name, using the ":autocmd" command (see |:autocmd|).
1443
1444 *viminfo-errors*
1445When Vim detects an error while reading a viminfo file, it will not overwrite
1446that file. If there are more than 10 errors, Vim stops reading the viminfo
1447file. This was done to avoid accidentally destroying a file when the file
1448name of the viminfo file is wrong. This could happen when accidentally typing
1449"vim -i file" when you wanted "vim -R file" (yes, somebody accidentally did
1450that!). If you want to overwrite a viminfo file with an error in it, you will
1451either have to fix the error, or delete the file (while Vim is running, so
1452most of the information will be restored).
1453
1454 *:rv* *:rviminfo* *E195*
1455:rv[iminfo][!] [file] Read from viminfo file [file] (default: see above).
1456 If [!] is given, then any information that is
1457 already set (registers, marks, etc.) will be
1458 overwritten. {not in Vi}
1459
1460 *:wv* *:wviminfo* *E137* *E138* *E574*
1461:wv[iminfo][!] [file] Write to viminfo file [file] (default: see above).
1462 The information in the file is first read in to make
1463 a merge between old and new info. When [!] is used,
1464 the old information is not read first, only the
1465 internal info is written. If 'viminfo' is empty, marks
1466 for up to 100 files will be written.
1467 When you get error "E138: Can't write viminfo file"
1468 check that no old temp files were left behind (e.g.
1469 ~/.viminf*) and that you can write in the directory of
1470 the .viminfo file.
1471 {not in Vi}
1472
1473 vim:tw=78:ts=8:ft=help:norl: