|
1668
|
1 *usr_21.txt* For Vim version 7.2b. Last change: 2007 May 01
|
|
7
|
2
|
|
|
3 VIM USER MANUAL - by Bram Moolenaar
|
|
|
4
|
|
|
5 Go away and come back
|
|
|
6
|
|
|
7
|
|
|
8 This chapter goes into mixing the use of other programs with Vim. Either by
|
|
|
9 executing program from inside Vim or by leaving Vim and coming back later.
|
|
|
10 Furthermore, this is about the ways to remember the state of Vim and restore
|
|
|
11 it later.
|
|
|
12
|
|
|
13 |21.1| Suspend and resume
|
|
|
14 |21.2| Executing shell commands
|
|
|
15 |21.3| Remembering information; viminfo
|
|
|
16 |21.4| Sessions
|
|
|
17 |21.5| Views
|
|
|
18 |21.6| Modelines
|
|
|
19
|
|
|
20 Next chapter: |usr_22.txt| Finding the file to edit
|
|
|
21 Previous chapter: |usr_20.txt| Typing command-line commands quickly
|
|
|
22 Table of contents: |usr_toc.txt|
|
|
|
23
|
|
|
24 ==============================================================================
|
|
|
25 *21.1* Suspend and resume
|
|
|
26
|
|
|
27 Like most Unix programs Vim can be suspended by pressing CTRL-Z. This stops
|
|
|
28 Vim and takes you back to the shell it was started in. You can then do any
|
|
|
29 other commands until you are bored with them. Then bring back Vim with the
|
|
|
30 "fg" command. >
|
|
|
31
|
|
|
32 CTRL-Z
|
|
|
33 {any sequence of shell commands}
|
|
|
34 fg
|
|
|
35
|
|
|
36 You are right back where you left Vim, nothing has changed.
|
|
|
37 In case pressing CTRL-Z doesn't work, you can also use ":suspend".
|
|
|
38 Don't forget to bring Vim back to the foreground, you would lose any changes
|
|
|
39 that you made!
|
|
|
40
|
|
|
41 Only Unix has support for this. On other systems Vim will start a shell for
|
|
|
42 you. This also has the functionality of being able to execute shell commands.
|
|
|
43 But it's a new shell, not the one that you started Vim from.
|
|
|
44 When you are running the GUI you can't go back to the shell where Vim was
|
|
|
45 started. CTRL-Z will minimize the Vim window instead.
|
|
|
46
|
|
|
47 ==============================================================================
|
|
|
48 *21.2* Executing shell commands
|
|
|
49
|
|
|
50 To execute a single shell command from Vim use ":!{command}". For example, to
|
|
|
51 see a directory listing: >
|
|
|
52
|
|
|
53 :!ls
|
|
|
54 :!dir
|
|
|
55
|
|
|
56 The first one is for Unix, the second one for MS-Windows.
|
|
|
57 Vim will execute the program. When it ends you will get a prompt to hit
|
|
|
58 <Enter>. This allows you to have a look at the output from the command before
|
|
|
59 returning to the text you were editing.
|
|
|
60 The "!" is also used in other places where a program is run. Let's take
|
|
|
61 a look at an overview:
|
|
|
62
|
|
|
63 :!{program} execute {program}
|
|
|
64 :r !{program} execute {program} and read its output
|
|
|
65 :w !{program} execute {program} and send text to its input
|
|
|
66 :[range]!{program} filter text through {program}
|
|
|
67
|
|
29
|
68 Notice that the presence of a range before "!{program}" makes a big
|
|
7
|
69 difference. Without it executes the program normally, with the range a number
|
|
|
70 of text lines is filtered through the program.
|
|
|
71
|
|
|
72 Executing a whole row of programs this way is possible. But a shell is much
|
|
|
73 better at it. You can start a new shell this way: >
|
|
|
74
|
|
|
75 :shell
|
|
|
76
|
|
|
77 This is similar to using CTRL-Z to suspend Vim. The difference is that a new
|
|
|
78 shell is started.
|
|
|
79
|
|
|
80 When using the GUI the shell will be using the Vim window for its input and
|
|
|
81 output. Since Vim is not a terminal emulator, this will not work perfectly.
|
|
|
82 If you have trouble, try toggling the 'guipty' option. If this still doesn't
|
|
|
83 work well enough, start a new terminal to run the shell in. For example with:
|
|
|
84 >
|
|
|
85 :!xterm&
|
|
|
86
|
|
|
87 ==============================================================================
|
|
|
88 *21.3* Remembering information; viminfo
|
|
|
89
|
|
|
90 After editing for a while you will have text in registers, marks in various
|
|
|
91 files, a command line history filled with carefully crafted commands. When
|
|
|
92 you exit Vim all of this is lost. But you can get it back!
|
|
|
93
|
|
|
94 The viminfo file is designed to store status information:
|
|
|
95
|
|
|
96 Command-line and Search pattern history
|
|
|
97 Text in registers
|
|
|
98 Marks for various files
|
|
|
99 The buffer list
|
|
|
100 Global variables
|
|
|
101
|
|
|
102 Each time you exit Vim it will store this information in a file, the viminfo
|
|
|
103 file. When Vim starts again, the viminfo file is read and the information
|
|
|
104 restored.
|
|
|
105
|
|
|
106 The 'viminfo' option is set by default to restore a limited number of items.
|
|
|
107 You might want to set it to remember more information. This is done through
|
|
|
108 the following command: >
|
|
|
109
|
|
|
110 :set viminfo=string
|
|
|
111
|
|
|
112 The string specifies what to save. The syntax of this string is an option
|
|
|
113 character followed by an argument. The option/argument pairs are separated by
|
|
|
114 commas.
|
|
|
115 Take a look at how you can build up your own viminfo string. First, the '
|
|
|
116 option is used to specify how many files for which you save marks (a-z). Pick
|
|
|
117 a nice even number for this option (1000, for instance). Your command now
|
|
|
118 looks like this: >
|
|
|
119
|
|
|
120 :set viminfo='1000
|
|
|
121
|
|
|
122 The f option controls whether global marks (A-Z and 0-9) are stored. If this
|
|
236
|
123 option is 0, none are stored. If it is 1 or you do not specify an f option,
|
|
7
|
124 the marks are stored. You want this feature, so now you have this: >
|
|
|
125
|
|
|
126 :set viminfo='1000,f1
|
|
|
127
|
|
|
128 The < option controls how many lines are saved for each of the registers. By
|
|
|
129 default, all the lines are saved. If 0, nothing is saved. To avoid adding
|
|
|
130 thousands of lines to your viminfo file (which might never get used and makes
|
|
|
131 starting Vim slower) you use a maximum of 500 lines: >
|
|
|
132
|
|
|
133 :set viminfo='1000,f1,<500
|
|
|
134 <
|
|
|
135 Other options you might want to use:
|
|
|
136 : number of lines to save from the command line history
|
|
|
137 @ number of lines to save from the input line history
|
|
|
138 / number of lines to save from the search history
|
|
|
139 r removable media, for which no marks will be stored (can be
|
|
|
140 used several times)
|
|
|
141 ! global variables that start with an uppercase letter and
|
|
|
142 don't contain lowercase letters
|
|
|
143 h disable 'hlsearch' highlighting when starting
|
|
|
144 % the buffer list (only restored when starting Vim without file
|
|
|
145 arguments)
|
|
|
146 c convert the text using 'encoding'
|
|
|
147 n name used for the viminfo file (must be the last option)
|
|
|
148
|
|
|
149 See the 'viminfo' option and |viminfo-file| for more information.
|
|
|
150
|
|
|
151 When you run Vim multiple times, the last one exiting will store its
|
|
|
152 information. This may cause information that previously exiting Vims stored
|
|
|
153 to be lost. Each item can be remembered only once.
|
|
|
154
|
|
|
155
|
|
|
156 GETTING BACK TO WHERE YOU WERE
|
|
|
157
|
|
|
158 You are halfway editing a file and it's time to leave for holidays. You exit
|
|
|
159 Vim and go enjoy yourselves, forgetting all about your work. After a couple
|
|
|
160 of weeks you start Vim, and type:
|
|
|
161 >
|
|
|
162 '0
|
|
|
163
|
|
|
164 And you are right back where you left Vim. So you can get on with your work.
|
|
|
165 Vim creates a mark each time you exit Vim. The last one is '0. The
|
|
|
166 position that '0 pointed to is made '1. And '1 is made to '2, and so forth.
|
|
|
167 Mark '9 is lost.
|
|
843
|
168 The |:marks| command is useful to find out where '0 to '9 will take you.
|
|
7
|
169
|
|
|
170
|
|
|
171 MOVE INFO FROM ONE VIM TO ANOTHER
|
|
|
172
|
|
|
173 You can use the ":wviminfo" and ":rviminfo" commands to save and restore the
|
|
|
174 information while still running Vim. This is useful for exchanging register
|
|
|
175 contents between two instances of Vim, for example. In the first Vim do: >
|
|
|
176
|
|
|
177 :wviminfo! ~/tmp/viminfo
|
|
|
178
|
|
|
179 And in the second Vim do: >
|
|
|
180
|
|
|
181 :rviminfo! ~/tmp/viminfo
|
|
|
182
|
|
|
183 Obviously, the "w" stands for "write" and the "r" for "read".
|
|
|
184 The ! character is used by ":wviminfo" to forcefully overwrite an existing
|
|
|
185 file. When it is omitted, and the file exists, the information is merged into
|
|
|
186 the file.
|
|
|
187 The ! character used for ":rviminfo" means that all the information is
|
|
|
188 used, this may overwrite existing information. Without the ! only information
|
|
|
189 that wasn't set is used.
|
|
|
190 These commands can also be used to store info and use it again later. You
|
|
|
191 could make a directory full of viminfo files, each containing info for a
|
|
|
192 different purpose.
|
|
|
193
|
|
|
194 ==============================================================================
|
|
|
195 *21.4* Sessions
|
|
|
196
|
|
|
197 Suppose you are editing along, and it is the end of the day. You want to quit
|
|
|
198 work and pick up where you left off the next day. You can do this by saving
|
|
|
199 your editing session and restoring it the next day.
|
|
|
200 A Vim session contains all the information about what you are editing.
|
|
|
201 This includes things such as the file list, window layout, global variables,
|
|
236
|
202 options and other information. (Exactly what is remembered is controlled by
|
|
7
|
203 the 'sessionoptions' option, described below.)
|
|
|
204 The following command creates a session file: >
|
|
|
205
|
|
|
206 :mksession vimbook.vim
|
|
|
207
|
|
|
208 Later if you want to restore this session, you can use this command: >
|
|
|
209
|
|
|
210 :source vimbook.vim
|
|
|
211
|
|
|
212 If you want to start Vim and restore a specific session, you can use the
|
|
|
213 following command: >
|
|
|
214
|
|
|
215 vim -S vimbook.vim
|
|
|
216
|
|
|
217 This tells Vim to read a specific file on startup. The 'S' stands for
|
|
|
218 session (actually, you can source any Vim script with -S, thus it might as
|
|
|
219 well stand for "source").
|
|
|
220
|
|
|
221 The windows that were open are restored, with the same position and size as
|
|
|
222 before. Mappings and option values are like before.
|
|
|
223 What exactly is restored depends on the 'sessionoptions' option. The
|
|
|
224 default value is "blank,buffers,curdir,folds,help,options,winsize".
|
|
|
225
|
|
|
226 blank keep empty windows
|
|
|
227 buffers all buffers, not only the ones in a window
|
|
|
228 curdir the current directory
|
|
|
229 folds folds, also manually created ones
|
|
|
230 help the help window
|
|
|
231 options all options and mappings
|
|
|
232 winsize window sizes
|
|
|
233
|
|
|
234 Change this to your liking. To also restore the size of the Vim window, for
|
|
|
235 example, use: >
|
|
|
236
|
|
|
237 :set sessionoptions+=resize
|
|
|
238
|
|
|
239
|
|
|
240 SESSION HERE, SESSION THERE
|
|
|
241
|
|
|
242 The obvious way to use sessions is when working on different projects.
|
|
|
243 Suppose you store you session files in the directory "~/.vim". You are
|
|
|
244 currently working on the "secret" project and have to switch to the "boring"
|
|
|
245 project: >
|
|
|
246
|
|
|
247 :wall
|
|
|
248 :mksession! ~/.vim/secret.vim
|
|
|
249 :source ~/.vim/boring.vim
|
|
|
250
|
|
|
251 This first uses ":wall" to write all modified files. Then the current session
|
|
|
252 is saved, using ":mksession!". This overwrites the previous session. The
|
|
|
253 next time you load the secret session you can continue where you were at this
|
|
|
254 point. And finally you load the new "boring" session.
|
|
|
255
|
|
|
256 If you open help windows, split and close various window, and generally mess
|
|
|
257 up the window layout, you can go back to the last saved session: >
|
|
|
258
|
|
|
259 :source ~/.vim/boring.vim
|
|
|
260
|
|
|
261 Thus you have complete control over whether you want to continue next time
|
|
|
262 where you are now, by saving the current setup in a session, or keep the
|
|
|
263 session file as a starting point.
|
|
|
264 Another way of using sessions is to create a window layout that you like to
|
|
|
265 use, and save this in a session. Then you can go back to this layout whenever
|
|
|
266 you want.
|
|
|
267 For example, this is a nice layout to use:
|
|
|
268
|
|
|
269 +----------------------------------------+
|
|
|
270 | VIM - main help file |
|
|
|
271 | |
|
|
|
272 |Move around: Use the cursor keys, or "h|
|
|
|
273 |help.txt================================|
|
|
|
274 |explorer | |
|
|
|
275 |dir |~ |
|
|
|
276 |dir |~ |
|
|
|
277 |file |~ |
|
|
|
278 |file |~ |
|
|
|
279 |file |~ |
|
|
|
280 |file |~ |
|
|
|
281 |~/=========|[No File]===================|
|
|
|
282 | |
|
|
|
283 +----------------------------------------+
|
|
|
284
|
|
|
285 This has a help window at the top, so that you can read this text. The narrow
|
|
|
286 vertical window on the left contains a file explorer. This is a Vim plugin
|
|
|
287 that lists the contents of a directory. You can select files to edit there.
|
|
|
288 More about this in the next chapter.
|
|
|
289 Create this from a just started Vim with: >
|
|
|
290
|
|
|
291 :help
|
|
|
292 CTRL-W w
|
|
|
293 :vertical split ~/
|
|
|
294
|
|
|
295 You can resize the windows a bit to your liking. Then save the session with:
|
|
|
296 >
|
|
|
297 :mksession ~/.vim/mine.vim
|
|
|
298
|
|
|
299 Now you can start Vim with this layout: >
|
|
|
300
|
|
|
301 vim -S ~/.vim/mine.vim
|
|
|
302
|
|
|
303 Hint: To open a file you see listed in the explorer window in the empty
|
|
|
304 window, move the cursor to the filename and press "O". Double clicking with
|
|
|
305 the mouse will also do this.
|
|
|
306
|
|
|
307
|
|
|
308 UNIX AND MS-WINDOWS
|
|
|
309
|
|
|
310 Some people have to do work on MS-Windows systems one day and on Unix another
|
|
|
311 day. If you are one of them, consider adding "slash" and "unix" to
|
|
|
312 'sessionoptions'. The session files will then be written in a format that can
|
|
|
313 be used on both systems. This is the command to put in your vimrc file: >
|
|
|
314
|
|
|
315 :set sessionoptions+=unix,slash
|
|
|
316
|
|
|
317 Vim will use the Unix format then, because the MS-Windows Vim can read and
|
|
|
318 write Unix files, but Unix Vim can't read MS-Windows format session files.
|
|
|
319 Similarly, MS-Windows Vim understands file names with / to separate names, but
|
|
|
320 Unix Vim doesn't understand \.
|
|
|
321
|
|
|
322
|
|
|
323 SESSIONS AND VIMINFO
|
|
|
324
|
|
|
325 Sessions store many things, but not the position of marks, contents of
|
|
|
326 registers and the command line history. You need to use the viminfo feature
|
|
|
327 for these things.
|
|
|
328 In most situations you will want to use sessions separately from viminfo.
|
|
|
329 This can be used to switch to another session, but keep the command line
|
|
|
330 history. And yank text into registers in one session, and paste it back in
|
|
|
331 another session.
|
|
|
332 You might prefer to keep the info with the session. You will have to do
|
|
|
333 this yourself then. Example: >
|
|
|
334
|
|
|
335 :mksession! ~/.vim/secret.vim
|
|
|
336 :wviminfo! ~/.vim/secret.viminfo
|
|
|
337
|
|
|
338 And to restore this again: >
|
|
|
339
|
|
|
340 :source ~/.vim/secret.vim
|
|
|
341 :rviminfo! ~/.vim/secret.viminfo
|
|
|
342
|
|
|
343 ==============================================================================
|
|
|
344 *21.5* Views
|
|
|
345
|
|
|
346 A session stores the looks of the whole of Vim. When you want to store the
|
|
|
347 properties for one window only, use a view.
|
|
|
348 The use of a view is for when you want to edit a file in a specific way.
|
|
|
349 For example, you have line numbers enabled with the 'number' option and
|
|
|
350 defined a few folds. Just like with sessions, you can remember this view on
|
|
|
351 the file and restore it later. Actually, when you store a session, it stores
|
|
|
352 the view of each window.
|
|
|
353 There are two basic ways to use views. The first is to let Vim pick a name
|
|
|
354 for the view file. You can restore the view when you later edit the same
|
|
|
355 file. To store the view for the current window: >
|
|
|
356
|
|
|
357 :mkview
|
|
|
358
|
|
|
359 Vim will decide where to store the view. When you later edit the same file
|
|
|
360 you get the view back with this command: >
|
|
|
361
|
|
|
362 :loadview
|
|
|
363
|
|
|
364 That's easy, isn't it?
|
|
|
365 Now you want to view the file without the 'number' option on, or with all
|
|
|
366 folds open, you can set the options to make the window look that way. Then
|
|
|
367 store this view with: >
|
|
|
368
|
|
|
369 :mkview 1
|
|
|
370
|
|
|
371 Obviously, you can get this back with: >
|
|
|
372
|
|
|
373 :loadview 1
|
|
|
374
|
|
|
375 Now you can switch between the two views on the file by using ":loadview" with
|
|
|
376 and without the "1" argument.
|
|
|
377 You can store up to ten views for the same file this way, one unnumbered
|
|
|
378 and nine numbered 1 to 9.
|
|
|
379
|
|
|
380
|
|
|
381 A VIEW WITH A NAME
|
|
|
382
|
|
|
383 The second basic way to use views is by storing the view in a file with a name
|
|
|
384 you chose. This view can be loaded while editing another file. Vim will then
|
|
|
385 switch to editing the file specified in the view. Thus you can use this to
|
|
|
386 quickly switch to editing another file, with all its options set as you saved
|
|
|
387 them.
|
|
|
388 For example, to save the view of the current file: >
|
|
|
389
|
|
|
390 :mkview ~/.vim/main.vim
|
|
|
391
|
|
|
392 You can restore it with: >
|
|
|
393
|
|
|
394 :source ~/.vim/main.vim
|
|
|
395
|
|
|
396 ==============================================================================
|
|
|
397 *21.6* Modelines
|
|
|
398
|
|
|
399 When editing a specific file, you might set options specifically for that
|
|
|
400 file. Typing these commands each time is boring. Using a session or view for
|
|
|
401 editing a file doesn't work when sharing the file between several people.
|
|
|
402 The solution for this situation is adding a modeline to the file. This is
|
|
|
403 a line of text that tells Vim the values of options, to be used in this file
|
|
|
404 only.
|
|
|
405 A typical example is a C program where you make indents by a multiple of 4
|
|
|
406 spaces. This requires setting the 'shiftwidth' option to 4. This modeline
|
|
|
407 will do that:
|
|
|
408
|
|
|
409 /* vim:set shiftwidth=4: */ ~
|
|
|
410
|
|
|
411 Put this line as one of the first or last five lines in the file. When
|
|
|
412 editing the file, you will notice that 'shiftwidth' will have been set to
|
|
|
413 four. When editing another file, it's set back to the default value of eight.
|
|
|
414 For some files the modeline fits well in the header, thus it can be put at
|
|
|
415 the top of the file. For text files and other files where the modeline gets
|
|
|
416 in the way of the normal contents, put it at the end of the file.
|
|
|
417
|
|
|
418 The 'modelines' option specifies how many lines at the start and end of the
|
|
|
419 file are inspected for containing a modeline. To inspect ten lines: >
|
|
|
420
|
|
|
421 :set modelines=10
|
|
|
422
|
|
|
423 The 'modeline' option can be used to switch this off. Do this when you are
|
|
1122
|
424 working as root on Unix or Administrator on MS-Windows, or when you don't
|
|
|
425 trust the files you are editing: >
|
|
7
|
426
|
|
|
427 :set nomodeline
|
|
|
428
|
|
|
429 Use this format for the modeline:
|
|
|
430
|
|
|
431 any-text vim:set {option}={value} ... : any-text ~
|
|
|
432
|
|
|
433 The "any-text" indicates that you can put any text before and after the part
|
|
|
434 that Vim will use. This allows making it look like a comment, like what was
|
|
|
435 done above with /* and */.
|
|
1122
|
436 The " vim:" part is what makes Vim recognize this line. There must be
|
|
|
437 white space before "vim", or "vim" must be at the start of the line. Thus
|
|
|
438 using something like "gvim:" will not work.
|
|
7
|
439 The part between the colons is a ":set" command. It works the same way as
|
|
|
440 typing the ":set" command, except that you need to insert a backslash before a
|
|
|
441 colon (otherwise it would be seen as the end of the modeline).
|
|
|
442
|
|
|
443 Another example:
|
|
|
444
|
|
|
445 // vim:set textwidth=72 dir=c\:\tmp: use c:\tmp here ~
|
|
|
446
|
|
|
447 There is an extra backslash before the first colon, so that it's included in
|
|
|
448 the ":set" command. The text after the second colon is ignored, thus a remark
|
|
|
449 can be placed there.
|
|
|
450
|
|
|
451 For more details see |modeline|.
|
|
|
452
|
|
|
453 ==============================================================================
|
|
|
454
|
|
|
455 Next chapter: |usr_22.txt| Finding the file to edit
|
|
|
456
|
|
|
457 Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl:
|
