|
3920
|
1 *usr_21.txt* For Vim version 7.3. Last change: 2012 Nov 02
|
|
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
|
|
1733
|
156 GETTING BACK TO WHERE YOU STOPPED VIM
|
|
7
|
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
|
|
1733
|
171 GETTING BACK TO SOME FILE
|
|
|
172
|
|
|
173 If you want to go back to a file that you edited recently, but not when
|
|
|
174 exiting Vim, there is a slightly more complicated way. You can see a list of
|
|
|
175 files by typing the command: >
|
|
|
176
|
|
|
177 :oldfiles
|
|
|
178 < 1: ~/.viminfo ~
|
|
|
179 2: ~/text/resume.txt ~
|
|
|
180 3: /tmp/draft ~
|
|
|
181
|
|
|
182 Now you would like to edit the second file, which is in the list preceded by
|
|
|
183 "2:". You type: >
|
|
|
184
|
|
|
185 :e #<2
|
|
|
186
|
|
|
187 Instead of ":e" you can use any command that has a file name argument, the
|
|
|
188 "#<2" item works in the same place as "%" (current file name) and "#"
|
|
|
189 (alternate file name). So you can also split the window to edit the third
|
|
|
190 file: >
|
|
|
191
|
|
|
192 :split #<3
|
|
|
193
|
|
|
194 That #<123 thing is a bit complicated when you just want to edit a file.
|
|
|
195 Fortunately there is a simpler way: >
|
|
|
196
|
|
|
197 :browse oldfiles
|
|
|
198 < 1: ~/.viminfo ~
|
|
|
199 2: ~/text/resume.txt ~
|
|
|
200 3: /tmp/draft ~
|
|
|
201 -- More --
|
|
|
202
|
|
|
203 You get the same list of files as with |:oldfiles|. If you want to edit
|
|
|
204 "resume.txt" first press "q" to stop the listing. You will get a prompt:
|
|
|
205
|
|
|
206 Type number and <Enter> (empty cancels): ~
|
|
|
207
|
|
|
208 Type "2" and press <Enter> to edit the second file.
|
|
|
209
|
|
|
210 More info at |:oldfiles|, |v:oldfiles| and |c_#<|.
|
|
|
211
|
|
|
212
|
|
7
|
213 MOVE INFO FROM ONE VIM TO ANOTHER
|
|
|
214
|
|
|
215 You can use the ":wviminfo" and ":rviminfo" commands to save and restore the
|
|
|
216 information while still running Vim. This is useful for exchanging register
|
|
|
217 contents between two instances of Vim, for example. In the first Vim do: >
|
|
|
218
|
|
|
219 :wviminfo! ~/tmp/viminfo
|
|
|
220
|
|
|
221 And in the second Vim do: >
|
|
|
222
|
|
|
223 :rviminfo! ~/tmp/viminfo
|
|
|
224
|
|
|
225 Obviously, the "w" stands for "write" and the "r" for "read".
|
|
|
226 The ! character is used by ":wviminfo" to forcefully overwrite an existing
|
|
|
227 file. When it is omitted, and the file exists, the information is merged into
|
|
|
228 the file.
|
|
|
229 The ! character used for ":rviminfo" means that all the information is
|
|
|
230 used, this may overwrite existing information. Without the ! only information
|
|
|
231 that wasn't set is used.
|
|
|
232 These commands can also be used to store info and use it again later. You
|
|
|
233 could make a directory full of viminfo files, each containing info for a
|
|
|
234 different purpose.
|
|
|
235
|
|
|
236 ==============================================================================
|
|
|
237 *21.4* Sessions
|
|
|
238
|
|
|
239 Suppose you are editing along, and it is the end of the day. You want to quit
|
|
|
240 work and pick up where you left off the next day. You can do this by saving
|
|
|
241 your editing session and restoring it the next day.
|
|
|
242 A Vim session contains all the information about what you are editing.
|
|
|
243 This includes things such as the file list, window layout, global variables,
|
|
236
|
244 options and other information. (Exactly what is remembered is controlled by
|
|
7
|
245 the 'sessionoptions' option, described below.)
|
|
|
246 The following command creates a session file: >
|
|
|
247
|
|
|
248 :mksession vimbook.vim
|
|
|
249
|
|
|
250 Later if you want to restore this session, you can use this command: >
|
|
|
251
|
|
|
252 :source vimbook.vim
|
|
|
253
|
|
|
254 If you want to start Vim and restore a specific session, you can use the
|
|
|
255 following command: >
|
|
|
256
|
|
|
257 vim -S vimbook.vim
|
|
|
258
|
|
|
259 This tells Vim to read a specific file on startup. The 'S' stands for
|
|
|
260 session (actually, you can source any Vim script with -S, thus it might as
|
|
|
261 well stand for "source").
|
|
|
262
|
|
|
263 The windows that were open are restored, with the same position and size as
|
|
|
264 before. Mappings and option values are like before.
|
|
|
265 What exactly is restored depends on the 'sessionoptions' option. The
|
|
|
266 default value is "blank,buffers,curdir,folds,help,options,winsize".
|
|
|
267
|
|
|
268 blank keep empty windows
|
|
|
269 buffers all buffers, not only the ones in a window
|
|
|
270 curdir the current directory
|
|
|
271 folds folds, also manually created ones
|
|
|
272 help the help window
|
|
|
273 options all options and mappings
|
|
|
274 winsize window sizes
|
|
|
275
|
|
|
276 Change this to your liking. To also restore the size of the Vim window, for
|
|
|
277 example, use: >
|
|
|
278
|
|
|
279 :set sessionoptions+=resize
|
|
|
280
|
|
|
281
|
|
|
282 SESSION HERE, SESSION THERE
|
|
|
283
|
|
|
284 The obvious way to use sessions is when working on different projects.
|
|
3920
|
285 Suppose you store your session files in the directory "~/.vim". You are
|
|
7
|
286 currently working on the "secret" project and have to switch to the "boring"
|
|
|
287 project: >
|
|
|
288
|
|
|
289 :wall
|
|
|
290 :mksession! ~/.vim/secret.vim
|
|
|
291 :source ~/.vim/boring.vim
|
|
|
292
|
|
|
293 This first uses ":wall" to write all modified files. Then the current session
|
|
|
294 is saved, using ":mksession!". This overwrites the previous session. The
|
|
|
295 next time you load the secret session you can continue where you were at this
|
|
|
296 point. And finally you load the new "boring" session.
|
|
|
297
|
|
3920
|
298 If you open help windows, split and close various windows, and generally mess
|
|
7
|
299 up the window layout, you can go back to the last saved session: >
|
|
|
300
|
|
|
301 :source ~/.vim/boring.vim
|
|
|
302
|
|
|
303 Thus you have complete control over whether you want to continue next time
|
|
|
304 where you are now, by saving the current setup in a session, or keep the
|
|
|
305 session file as a starting point.
|
|
|
306 Another way of using sessions is to create a window layout that you like to
|
|
|
307 use, and save this in a session. Then you can go back to this layout whenever
|
|
|
308 you want.
|
|
|
309 For example, this is a nice layout to use:
|
|
|
310
|
|
|
311 +----------------------------------------+
|
|
|
312 | VIM - main help file |
|
|
|
313 | |
|
|
|
314 |Move around: Use the cursor keys, or "h|
|
|
|
315 |help.txt================================|
|
|
|
316 |explorer | |
|
|
|
317 |dir |~ |
|
|
|
318 |dir |~ |
|
|
|
319 |file |~ |
|
|
|
320 |file |~ |
|
|
|
321 |file |~ |
|
|
|
322 |file |~ |
|
|
|
323 |~/=========|[No File]===================|
|
|
|
324 | |
|
|
|
325 +----------------------------------------+
|
|
|
326
|
|
|
327 This has a help window at the top, so that you can read this text. The narrow
|
|
|
328 vertical window on the left contains a file explorer. This is a Vim plugin
|
|
|
329 that lists the contents of a directory. You can select files to edit there.
|
|
|
330 More about this in the next chapter.
|
|
|
331 Create this from a just started Vim with: >
|
|
|
332
|
|
|
333 :help
|
|
|
334 CTRL-W w
|
|
|
335 :vertical split ~/
|
|
|
336
|
|
|
337 You can resize the windows a bit to your liking. Then save the session with:
|
|
|
338 >
|
|
|
339 :mksession ~/.vim/mine.vim
|
|
|
340
|
|
|
341 Now you can start Vim with this layout: >
|
|
|
342
|
|
|
343 vim -S ~/.vim/mine.vim
|
|
|
344
|
|
|
345 Hint: To open a file you see listed in the explorer window in the empty
|
|
|
346 window, move the cursor to the filename and press "O". Double clicking with
|
|
|
347 the mouse will also do this.
|
|
|
348
|
|
|
349
|
|
|
350 UNIX AND MS-WINDOWS
|
|
|
351
|
|
|
352 Some people have to do work on MS-Windows systems one day and on Unix another
|
|
|
353 day. If you are one of them, consider adding "slash" and "unix" to
|
|
|
354 'sessionoptions'. The session files will then be written in a format that can
|
|
|
355 be used on both systems. This is the command to put in your vimrc file: >
|
|
|
356
|
|
|
357 :set sessionoptions+=unix,slash
|
|
|
358
|
|
|
359 Vim will use the Unix format then, because the MS-Windows Vim can read and
|
|
|
360 write Unix files, but Unix Vim can't read MS-Windows format session files.
|
|
|
361 Similarly, MS-Windows Vim understands file names with / to separate names, but
|
|
|
362 Unix Vim doesn't understand \.
|
|
|
363
|
|
|
364
|
|
|
365 SESSIONS AND VIMINFO
|
|
|
366
|
|
|
367 Sessions store many things, but not the position of marks, contents of
|
|
|
368 registers and the command line history. You need to use the viminfo feature
|
|
|
369 for these things.
|
|
|
370 In most situations you will want to use sessions separately from viminfo.
|
|
|
371 This can be used to switch to another session, but keep the command line
|
|
|
372 history. And yank text into registers in one session, and paste it back in
|
|
|
373 another session.
|
|
|
374 You might prefer to keep the info with the session. You will have to do
|
|
|
375 this yourself then. Example: >
|
|
|
376
|
|
|
377 :mksession! ~/.vim/secret.vim
|
|
|
378 :wviminfo! ~/.vim/secret.viminfo
|
|
|
379
|
|
|
380 And to restore this again: >
|
|
|
381
|
|
|
382 :source ~/.vim/secret.vim
|
|
|
383 :rviminfo! ~/.vim/secret.viminfo
|
|
|
384
|
|
|
385 ==============================================================================
|
|
|
386 *21.5* Views
|
|
|
387
|
|
|
388 A session stores the looks of the whole of Vim. When you want to store the
|
|
|
389 properties for one window only, use a view.
|
|
|
390 The use of a view is for when you want to edit a file in a specific way.
|
|
|
391 For example, you have line numbers enabled with the 'number' option and
|
|
|
392 defined a few folds. Just like with sessions, you can remember this view on
|
|
|
393 the file and restore it later. Actually, when you store a session, it stores
|
|
|
394 the view of each window.
|
|
|
395 There are two basic ways to use views. The first is to let Vim pick a name
|
|
|
396 for the view file. You can restore the view when you later edit the same
|
|
|
397 file. To store the view for the current window: >
|
|
|
398
|
|
|
399 :mkview
|
|
|
400
|
|
|
401 Vim will decide where to store the view. When you later edit the same file
|
|
|
402 you get the view back with this command: >
|
|
|
403
|
|
|
404 :loadview
|
|
|
405
|
|
|
406 That's easy, isn't it?
|
|
|
407 Now you want to view the file without the 'number' option on, or with all
|
|
|
408 folds open, you can set the options to make the window look that way. Then
|
|
|
409 store this view with: >
|
|
|
410
|
|
|
411 :mkview 1
|
|
|
412
|
|
|
413 Obviously, you can get this back with: >
|
|
|
414
|
|
|
415 :loadview 1
|
|
|
416
|
|
|
417 Now you can switch between the two views on the file by using ":loadview" with
|
|
|
418 and without the "1" argument.
|
|
|
419 You can store up to ten views for the same file this way, one unnumbered
|
|
|
420 and nine numbered 1 to 9.
|
|
|
421
|
|
|
422
|
|
|
423 A VIEW WITH A NAME
|
|
|
424
|
|
|
425 The second basic way to use views is by storing the view in a file with a name
|
|
3920
|
426 you choose. This view can be loaded while editing another file. Vim will
|
|
|
427 then switch to editing the file specified in the view. Thus you can use this
|
|
|
428 to quickly switch to editing another file, with all its options set as you
|
|
|
429 saved them.
|
|
7
|
430 For example, to save the view of the current file: >
|
|
|
431
|
|
|
432 :mkview ~/.vim/main.vim
|
|
|
433
|
|
|
434 You can restore it with: >
|
|
|
435
|
|
|
436 :source ~/.vim/main.vim
|
|
|
437
|
|
|
438 ==============================================================================
|
|
|
439 *21.6* Modelines
|
|
|
440
|
|
|
441 When editing a specific file, you might set options specifically for that
|
|
|
442 file. Typing these commands each time is boring. Using a session or view for
|
|
|
443 editing a file doesn't work when sharing the file between several people.
|
|
|
444 The solution for this situation is adding a modeline to the file. This is
|
|
|
445 a line of text that tells Vim the values of options, to be used in this file
|
|
|
446 only.
|
|
|
447 A typical example is a C program where you make indents by a multiple of 4
|
|
|
448 spaces. This requires setting the 'shiftwidth' option to 4. This modeline
|
|
|
449 will do that:
|
|
|
450
|
|
|
451 /* vim:set shiftwidth=4: */ ~
|
|
|
452
|
|
|
453 Put this line as one of the first or last five lines in the file. When
|
|
|
454 editing the file, you will notice that 'shiftwidth' will have been set to
|
|
|
455 four. When editing another file, it's set back to the default value of eight.
|
|
|
456 For some files the modeline fits well in the header, thus it can be put at
|
|
|
457 the top of the file. For text files and other files where the modeline gets
|
|
|
458 in the way of the normal contents, put it at the end of the file.
|
|
|
459
|
|
|
460 The 'modelines' option specifies how many lines at the start and end of the
|
|
|
461 file are inspected for containing a modeline. To inspect ten lines: >
|
|
|
462
|
|
|
463 :set modelines=10
|
|
|
464
|
|
|
465 The 'modeline' option can be used to switch this off. Do this when you are
|
|
1122
|
466 working as root on Unix or Administrator on MS-Windows, or when you don't
|
|
|
467 trust the files you are editing: >
|
|
7
|
468
|
|
|
469 :set nomodeline
|
|
|
470
|
|
|
471 Use this format for the modeline:
|
|
|
472
|
|
|
473 any-text vim:set {option}={value} ... : any-text ~
|
|
|
474
|
|
|
475 The "any-text" indicates that you can put any text before and after the part
|
|
|
476 that Vim will use. This allows making it look like a comment, like what was
|
|
|
477 done above with /* and */.
|
|
1122
|
478 The " vim:" part is what makes Vim recognize this line. There must be
|
|
|
479 white space before "vim", or "vim" must be at the start of the line. Thus
|
|
|
480 using something like "gvim:" will not work.
|
|
7
|
481 The part between the colons is a ":set" command. It works the same way as
|
|
|
482 typing the ":set" command, except that you need to insert a backslash before a
|
|
|
483 colon (otherwise it would be seen as the end of the modeline).
|
|
|
484
|
|
|
485 Another example:
|
|
|
486
|
|
|
487 // vim:set textwidth=72 dir=c\:\tmp: use c:\tmp here ~
|
|
|
488
|
|
|
489 There is an extra backslash before the first colon, so that it's included in
|
|
|
490 the ":set" command. The text after the second colon is ignored, thus a remark
|
|
|
491 can be placed there.
|
|
|
492
|
|
|
493 For more details see |modeline|.
|
|
|
494
|
|
|
495 ==============================================================================
|
|
|
496
|
|
|
497 Next chapter: |usr_22.txt| Finding the file to edit
|
|
|
498
|
|
|
499 Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl:
|
