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