1 *usr_21.txt* For Vim version 7.2. Last change: 2008 Sep 14
3 VIM USER MANUAL - by Bram Moolenaar
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
13 |21.1| Suspend and resume
14 |21.2| Executing shell commands
15 |21.3| Remembering information; viminfo
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|
24 ==============================================================================
25 *21.1* Suspend and resume
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
33 {any sequence of shell commands}
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
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.
47 ==============================================================================
48 *21.2* Executing shell commands
50 To execute a single shell command from Vim use ":!{command}". For example, to
51 see a directory listing: >
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:
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}
68 Notice that the presence of a range before "!{program}" makes a big
69 difference. Without it executes the program normally, with the range a number
70 of text lines is filtered through the program.
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: >
77 This is similar to using CTRL-Z to suspend Vim. The difference is that a new
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:
87 ==============================================================================
88 *21.3* Remembering information; viminfo
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!
94 The viminfo file is designed to store status information:
96 Command-line and Search pattern history
98 Marks for various files
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
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: >
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
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
122 The f option controls whether global marks (A-Z and 0-9) are stored. If this
123 option is 0, none are stored. If it is 1 or you do not specify an f option,
124 the marks are stored. You want this feature, so now you have this: >
126 :set viminfo='1000,f1
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: >
133 :set viminfo='1000,f1,<500
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
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
146 c convert the text using 'encoding'
147 n name used for the viminfo file (must be the last option)
149 See the 'viminfo' option and |viminfo-file| for more information.
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.
156 GETTING BACK TO WHERE YOU STOPPED
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:
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.
168 The |:marks| command is useful to find out where '0 to '9 will take you.
171 GETTING BACK TO SOME FILE
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: >
179 1: ~/text/resume.txt ~
182 Now you would like to edit the second file, which is in the list preceded by
187 Instead of ":e" you can use any command that has a file name argument, the
188 "#<1" 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
194 More info at |:oldfiles|, |v:oldfiles| and |c_#<|.
197 MOVE INFO FROM ONE VIM TO ANOTHER
199 You can use the ":wviminfo" and ":rviminfo" commands to save and restore the
200 information while still running Vim. This is useful for exchanging register
201 contents between two instances of Vim, for example. In the first Vim do: >
203 :wviminfo! ~/tmp/viminfo
205 And in the second Vim do: >
207 :rviminfo! ~/tmp/viminfo
209 Obviously, the "w" stands for "write" and the "r" for "read".
210 The ! character is used by ":wviminfo" to forcefully overwrite an existing
211 file. When it is omitted, and the file exists, the information is merged into
213 The ! character used for ":rviminfo" means that all the information is
214 used, this may overwrite existing information. Without the ! only information
215 that wasn't set is used.
216 These commands can also be used to store info and use it again later. You
217 could make a directory full of viminfo files, each containing info for a
220 ==============================================================================
223 Suppose you are editing along, and it is the end of the day. You want to quit
224 work and pick up where you left off the next day. You can do this by saving
225 your editing session and restoring it the next day.
226 A Vim session contains all the information about what you are editing.
227 This includes things such as the file list, window layout, global variables,
228 options and other information. (Exactly what is remembered is controlled by
229 the 'sessionoptions' option, described below.)
230 The following command creates a session file: >
232 :mksession vimbook.vim
234 Later if you want to restore this session, you can use this command: >
238 If you want to start Vim and restore a specific session, you can use the
243 This tells Vim to read a specific file on startup. The 'S' stands for
244 session (actually, you can source any Vim script with -S, thus it might as
245 well stand for "source").
247 The windows that were open are restored, with the same position and size as
248 before. Mappings and option values are like before.
249 What exactly is restored depends on the 'sessionoptions' option. The
250 default value is "blank,buffers,curdir,folds,help,options,winsize".
252 blank keep empty windows
253 buffers all buffers, not only the ones in a window
254 curdir the current directory
255 folds folds, also manually created ones
257 options all options and mappings
260 Change this to your liking. To also restore the size of the Vim window, for
263 :set sessionoptions+=resize
266 SESSION HERE, SESSION THERE
268 The obvious way to use sessions is when working on different projects.
269 Suppose you store you session files in the directory "~/.vim". You are
270 currently working on the "secret" project and have to switch to the "boring"
274 :mksession! ~/.vim/secret.vim
275 :source ~/.vim/boring.vim
277 This first uses ":wall" to write all modified files. Then the current session
278 is saved, using ":mksession!". This overwrites the previous session. The
279 next time you load the secret session you can continue where you were at this
280 point. And finally you load the new "boring" session.
282 If you open help windows, split and close various window, and generally mess
283 up the window layout, you can go back to the last saved session: >
285 :source ~/.vim/boring.vim
287 Thus you have complete control over whether you want to continue next time
288 where you are now, by saving the current setup in a session, or keep the
289 session file as a starting point.
290 Another way of using sessions is to create a window layout that you like to
291 use, and save this in a session. Then you can go back to this layout whenever
293 For example, this is a nice layout to use:
295 +----------------------------------------+
296 | VIM - main help file |
298 |Move around: Use the cursor keys, or "h|
299 |help.txt================================|
307 |~/=========|[No File]===================|
309 +----------------------------------------+
311 This has a help window at the top, so that you can read this text. The narrow
312 vertical window on the left contains a file explorer. This is a Vim plugin
313 that lists the contents of a directory. You can select files to edit there.
314 More about this in the next chapter.
315 Create this from a just started Vim with: >
321 You can resize the windows a bit to your liking. Then save the session with:
323 :mksession ~/.vim/mine.vim
325 Now you can start Vim with this layout: >
327 vim -S ~/.vim/mine.vim
329 Hint: To open a file you see listed in the explorer window in the empty
330 window, move the cursor to the filename and press "O". Double clicking with
331 the mouse will also do this.
336 Some people have to do work on MS-Windows systems one day and on Unix another
337 day. If you are one of them, consider adding "slash" and "unix" to
338 'sessionoptions'. The session files will then be written in a format that can
339 be used on both systems. This is the command to put in your vimrc file: >
341 :set sessionoptions+=unix,slash
343 Vim will use the Unix format then, because the MS-Windows Vim can read and
344 write Unix files, but Unix Vim can't read MS-Windows format session files.
345 Similarly, MS-Windows Vim understands file names with / to separate names, but
346 Unix Vim doesn't understand \.
351 Sessions store many things, but not the position of marks, contents of
352 registers and the command line history. You need to use the viminfo feature
354 In most situations you will want to use sessions separately from viminfo.
355 This can be used to switch to another session, but keep the command line
356 history. And yank text into registers in one session, and paste it back in
358 You might prefer to keep the info with the session. You will have to do
359 this yourself then. Example: >
361 :mksession! ~/.vim/secret.vim
362 :wviminfo! ~/.vim/secret.viminfo
364 And to restore this again: >
366 :source ~/.vim/secret.vim
367 :rviminfo! ~/.vim/secret.viminfo
369 ==============================================================================
372 A session stores the looks of the whole of Vim. When you want to store the
373 properties for one window only, use a view.
374 The use of a view is for when you want to edit a file in a specific way.
375 For example, you have line numbers enabled with the 'number' option and
376 defined a few folds. Just like with sessions, you can remember this view on
377 the file and restore it later. Actually, when you store a session, it stores
378 the view of each window.
379 There are two basic ways to use views. The first is to let Vim pick a name
380 for the view file. You can restore the view when you later edit the same
381 file. To store the view for the current window: >
385 Vim will decide where to store the view. When you later edit the same file
386 you get the view back with this command: >
390 That's easy, isn't it?
391 Now you want to view the file without the 'number' option on, or with all
392 folds open, you can set the options to make the window look that way. Then
393 store this view with: >
397 Obviously, you can get this back with: >
401 Now you can switch between the two views on the file by using ":loadview" with
402 and without the "1" argument.
403 You can store up to ten views for the same file this way, one unnumbered
404 and nine numbered 1 to 9.
409 The second basic way to use views is by storing the view in a file with a name
410 you chose. This view can be loaded while editing another file. Vim will then
411 switch to editing the file specified in the view. Thus you can use this to
412 quickly switch to editing another file, with all its options set as you saved
414 For example, to save the view of the current file: >
416 :mkview ~/.vim/main.vim
418 You can restore it with: >
420 :source ~/.vim/main.vim
422 ==============================================================================
425 When editing a specific file, you might set options specifically for that
426 file. Typing these commands each time is boring. Using a session or view for
427 editing a file doesn't work when sharing the file between several people.
428 The solution for this situation is adding a modeline to the file. This is
429 a line of text that tells Vim the values of options, to be used in this file
431 A typical example is a C program where you make indents by a multiple of 4
432 spaces. This requires setting the 'shiftwidth' option to 4. This modeline
435 /* vim:set shiftwidth=4: */ ~
437 Put this line as one of the first or last five lines in the file. When
438 editing the file, you will notice that 'shiftwidth' will have been set to
439 four. When editing another file, it's set back to the default value of eight.
440 For some files the modeline fits well in the header, thus it can be put at
441 the top of the file. For text files and other files where the modeline gets
442 in the way of the normal contents, put it at the end of the file.
444 The 'modelines' option specifies how many lines at the start and end of the
445 file are inspected for containing a modeline. To inspect ten lines: >
449 The 'modeline' option can be used to switch this off. Do this when you are
450 working as root on Unix or Administrator on MS-Windows, or when you don't
451 trust the files you are editing: >
455 Use this format for the modeline:
457 any-text vim:set {option}={value} ... : any-text ~
459 The "any-text" indicates that you can put any text before and after the part
460 that Vim will use. This allows making it look like a comment, like what was
461 done above with /* and */.
462 The " vim:" part is what makes Vim recognize this line. There must be
463 white space before "vim", or "vim" must be at the start of the line. Thus
464 using something like "gvim:" will not work.
465 The part between the colons is a ":set" command. It works the same way as
466 typing the ":set" command, except that you need to insert a backslash before a
467 colon (otherwise it would be seen as the end of the modeline).
471 // vim:set textwidth=72 dir=c\:\tmp: use c:\tmp here ~
473 There is an extra backslash before the first colon, so that it's included in
474 the ":set" command. The text after the second colon is ignored, thus a remark
477 For more details see |modeline|.
479 ==============================================================================
481 Next chapter: |usr_22.txt| Finding the file to edit
483 Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: