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: |