Mercurial > vim
annotate runtime/doc/usr_21.txt @ 19673:62ea983a9cb4 v8.2.0393
patch 8.2.0393: Coverity warns for not using return value
Commit: https://github.com/vim/vim/commit/c0300633292ee648c7154a7828eb1c76637bd9af
Author: Bram Moolenaar <Bram@vim.org>
Date: Mon Mar 16 20:07:16 2020 +0100
patch 8.2.0393: Coverity warns for not using return value
Problem: Coverity warns for not using return value.
Solution: Add (void).
author | Bram Moolenaar <Bram@vim.org> |
---|---|
date | Mon, 16 Mar 2020 20:15:05 +0100 |
parents | af69c9335223 |
children | f8116058ca76 |
rev | line source |
---|---|
18879 | 1 *usr_21.txt* For Vim version 8.2. Last change: 2019 Apr 25 |
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 | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
14519
diff
changeset
|
266 default value is: |
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
14519
diff
changeset
|
267 "blank,buffers,curdir,folds,help,options,tabpages,winsize,terminal". |
7 | 268 |
269 blank keep empty windows | |
270 buffers all buffers, not only the ones in a window | |
271 curdir the current directory | |
272 folds folds, also manually created ones | |
273 help the help window | |
274 options all options and mappings | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
14519
diff
changeset
|
275 tabpages all tab pages |
7 | 276 winsize window sizes |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
14519
diff
changeset
|
277 terminal include terminal windows |
7 | 278 |
279 Change this to your liking. To also restore the size of the Vim window, for | |
280 example, use: > | |
281 | |
282 :set sessionoptions+=resize | |
283 | |
284 | |
285 SESSION HERE, SESSION THERE | |
286 | |
287 The obvious way to use sessions is when working on different projects. | |
3920 | 288 Suppose you store your session files in the directory "~/.vim". You are |
7 | 289 currently working on the "secret" project and have to switch to the "boring" |
290 project: > | |
291 | |
292 :wall | |
293 :mksession! ~/.vim/secret.vim | |
294 :source ~/.vim/boring.vim | |
295 | |
296 This first uses ":wall" to write all modified files. Then the current session | |
297 is saved, using ":mksession!". This overwrites the previous session. The | |
298 next time you load the secret session you can continue where you were at this | |
299 point. And finally you load the new "boring" session. | |
300 | |
3920 | 301 If you open help windows, split and close various windows, and generally mess |
7 | 302 up the window layout, you can go back to the last saved session: > |
303 | |
304 :source ~/.vim/boring.vim | |
305 | |
306 Thus you have complete control over whether you want to continue next time | |
307 where you are now, by saving the current setup in a session, or keep the | |
308 session file as a starting point. | |
309 Another way of using sessions is to create a window layout that you like to | |
310 use, and save this in a session. Then you can go back to this layout whenever | |
311 you want. | |
312 For example, this is a nice layout to use: | |
313 | |
314 +----------------------------------------+ | |
315 | VIM - main help file | | |
316 | | | |
317 |Move around: Use the cursor keys, or "h| | |
318 |help.txt================================| | |
319 |explorer | | | |
320 |dir |~ | | |
321 |dir |~ | | |
322 |file |~ | | |
323 |file |~ | | |
324 |file |~ | | |
325 |file |~ | | |
326 |~/=========|[No File]===================| | |
327 | | | |
328 +----------------------------------------+ | |
329 | |
330 This has a help window at the top, so that you can read this text. The narrow | |
331 vertical window on the left contains a file explorer. This is a Vim plugin | |
332 that lists the contents of a directory. You can select files to edit there. | |
333 More about this in the next chapter. | |
334 Create this from a just started Vim with: > | |
335 | |
336 :help | |
337 CTRL-W w | |
338 :vertical split ~/ | |
339 | |
340 You can resize the windows a bit to your liking. Then save the session with: | |
341 > | |
342 :mksession ~/.vim/mine.vim | |
343 | |
344 Now you can start Vim with this layout: > | |
345 | |
346 vim -S ~/.vim/mine.vim | |
347 | |
348 Hint: To open a file you see listed in the explorer window in the empty | |
349 window, move the cursor to the filename and press "O". Double clicking with | |
350 the mouse will also do this. | |
351 | |
352 | |
353 UNIX AND MS-WINDOWS | |
354 | |
355 Some people have to do work on MS-Windows systems one day and on Unix another | |
356 day. If you are one of them, consider adding "slash" and "unix" to | |
357 'sessionoptions'. The session files will then be written in a format that can | |
358 be used on both systems. This is the command to put in your vimrc file: > | |
359 | |
360 :set sessionoptions+=unix,slash | |
361 | |
362 Vim will use the Unix format then, because the MS-Windows Vim can read and | |
363 write Unix files, but Unix Vim can't read MS-Windows format session files. | |
364 Similarly, MS-Windows Vim understands file names with / to separate names, but | |
365 Unix Vim doesn't understand \. | |
366 | |
367 | |
368 SESSIONS AND VIMINFO | |
369 | |
370 Sessions store many things, but not the position of marks, contents of | |
371 registers and the command line history. You need to use the viminfo feature | |
372 for these things. | |
373 In most situations you will want to use sessions separately from viminfo. | |
374 This can be used to switch to another session, but keep the command line | |
375 history. And yank text into registers in one session, and paste it back in | |
376 another session. | |
377 You might prefer to keep the info with the session. You will have to do | |
378 this yourself then. Example: > | |
379 | |
380 :mksession! ~/.vim/secret.vim | |
381 :wviminfo! ~/.vim/secret.viminfo | |
382 | |
383 And to restore this again: > | |
384 | |
385 :source ~/.vim/secret.vim | |
386 :rviminfo! ~/.vim/secret.viminfo | |
387 | |
388 ============================================================================== | |
389 *21.5* Views | |
390 | |
391 A session stores the looks of the whole of Vim. When you want to store the | |
392 properties for one window only, use a view. | |
393 The use of a view is for when you want to edit a file in a specific way. | |
394 For example, you have line numbers enabled with the 'number' option and | |
395 defined a few folds. Just like with sessions, you can remember this view on | |
396 the file and restore it later. Actually, when you store a session, it stores | |
397 the view of each window. | |
398 There are two basic ways to use views. The first is to let Vim pick a name | |
399 for the view file. You can restore the view when you later edit the same | |
400 file. To store the view for the current window: > | |
401 | |
402 :mkview | |
403 | |
404 Vim will decide where to store the view. When you later edit the same file | |
405 you get the view back with this command: > | |
406 | |
407 :loadview | |
408 | |
409 That's easy, isn't it? | |
410 Now you want to view the file without the 'number' option on, or with all | |
411 folds open, you can set the options to make the window look that way. Then | |
412 store this view with: > | |
413 | |
414 :mkview 1 | |
415 | |
416 Obviously, you can get this back with: > | |
417 | |
418 :loadview 1 | |
419 | |
420 Now you can switch between the two views on the file by using ":loadview" with | |
421 and without the "1" argument. | |
422 You can store up to ten views for the same file this way, one unnumbered | |
423 and nine numbered 1 to 9. | |
424 | |
425 | |
426 A VIEW WITH A NAME | |
427 | |
428 The second basic way to use views is by storing the view in a file with a name | |
3920 | 429 you choose. This view can be loaded while editing another file. Vim will |
430 then switch to editing the file specified in the view. Thus you can use this | |
431 to quickly switch to editing another file, with all its options set as you | |
432 saved them. | |
7 | 433 For example, to save the view of the current file: > |
434 | |
435 :mkview ~/.vim/main.vim | |
436 | |
437 You can restore it with: > | |
438 | |
439 :source ~/.vim/main.vim | |
440 | |
441 ============================================================================== | |
442 *21.6* Modelines | |
443 | |
444 When editing a specific file, you might set options specifically for that | |
445 file. Typing these commands each time is boring. Using a session or view for | |
446 editing a file doesn't work when sharing the file between several people. | |
447 The solution for this situation is adding a modeline to the file. This is | |
448 a line of text that tells Vim the values of options, to be used in this file | |
449 only. | |
450 A typical example is a C program where you make indents by a multiple of 4 | |
451 spaces. This requires setting the 'shiftwidth' option to 4. This modeline | |
452 will do that: | |
453 | |
454 /* vim:set shiftwidth=4: */ ~ | |
455 | |
456 Put this line as one of the first or last five lines in the file. When | |
457 editing the file, you will notice that 'shiftwidth' will have been set to | |
458 four. When editing another file, it's set back to the default value of eight. | |
459 For some files the modeline fits well in the header, thus it can be put at | |
460 the top of the file. For text files and other files where the modeline gets | |
461 in the way of the normal contents, put it at the end of the file. | |
462 | |
463 The 'modelines' option specifies how many lines at the start and end of the | |
464 file are inspected for containing a modeline. To inspect ten lines: > | |
465 | |
466 :set modelines=10 | |
467 | |
468 The 'modeline' option can be used to switch this off. Do this when you are | |
1122 | 469 working as root on Unix or Administrator on MS-Windows, or when you don't |
470 trust the files you are editing: > | |
7 | 471 |
472 :set nomodeline | |
473 | |
474 Use this format for the modeline: | |
475 | |
476 any-text vim:set {option}={value} ... : any-text ~ | |
477 | |
478 The "any-text" indicates that you can put any text before and after the part | |
479 that Vim will use. This allows making it look like a comment, like what was | |
480 done above with /* and */. | |
1122 | 481 The " vim:" part is what makes Vim recognize this line. There must be |
482 white space before "vim", or "vim" must be at the start of the line. Thus | |
483 using something like "gvim:" will not work. | |
7 | 484 The part between the colons is a ":set" command. It works the same way as |
485 typing the ":set" command, except that you need to insert a backslash before a | |
486 colon (otherwise it would be seen as the end of the modeline). | |
487 | |
488 Another example: | |
489 | |
490 // vim:set textwidth=72 dir=c\:\tmp: use c:\tmp here ~ | |
491 | |
492 There is an extra backslash before the first colon, so that it's included in | |
493 the ":set" command. The text after the second colon is ignored, thus a remark | |
494 can be placed there. | |
495 | |
496 For more details see |modeline|. | |
497 | |
498 ============================================================================== | |
499 | |
500 Next chapter: |usr_22.txt| Finding the file to edit | |
501 | |
14519 | 502 Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl: |