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