| *usr_21.txt* For Vim version 7.4. Last change: 2012 Nov 02 |
| |
| VIM USER MANUAL - by Bram Moolenaar |
| |
| Go away and come back |
| |
| |
| This chapter goes into mixing the use of other programs with Vim. Either by |
| executing program from inside Vim or by leaving Vim and coming back later. |
| Furthermore, this is about the ways to remember the state of Vim and restore |
| it later. |
| |
| |21.1| Suspend and resume |
| |21.2| Executing shell commands |
| |21.3| Remembering information; viminfo |
| |21.4| Sessions |
| |21.5| Views |
| |21.6| Modelines |
| |
| Next chapter: |usr_22.txt| Finding the file to edit |
| Previous chapter: |usr_20.txt| Typing command-line commands quickly |
| Table of contents: |usr_toc.txt| |
| |
| ============================================================================== |
| *21.1* Suspend and resume |
| |
| Like most Unix programs Vim can be suspended by pressing CTRL-Z. This stops |
| Vim and takes you back to the shell it was started in. You can then do any |
| other commands until you are bored with them. Then bring back Vim with the |
| "fg" command. > |
| |
| CTRL-Z |
| {any sequence of shell commands} |
| fg |
| |
| You are right back where you left Vim, nothing has changed. |
| In case pressing CTRL-Z doesn't work, you can also use ":suspend". |
| Don't forget to bring Vim back to the foreground, you would lose any changes |
| that you made! |
| |
| Only Unix has support for this. On other systems Vim will start a shell for |
| you. This also has the functionality of being able to execute shell commands. |
| But it's a new shell, not the one that you started Vim from. |
| When you are running the GUI you can't go back to the shell where Vim was |
| started. CTRL-Z will minimize the Vim window instead. |
| |
| ============================================================================== |
| *21.2* Executing shell commands |
| |
| To execute a single shell command from Vim use ":!{command}". For example, to |
| see a directory listing: > |
| |
| :!ls |
| :!dir |
| |
| The first one is for Unix, the second one for MS-Windows. |
| Vim will execute the program. When it ends you will get a prompt to hit |
| <Enter>. This allows you to have a look at the output from the command before |
| returning to the text you were editing. |
| The "!" is also used in other places where a program is run. Let's take |
| a look at an overview: |
| |
| :!{program} execute {program} |
| :r !{program} execute {program} and read its output |
| :w !{program} execute {program} and send text to its input |
| :[range]!{program} filter text through {program} |
| |
| Notice that the presence of a range before "!{program}" makes a big |
| difference. Without it executes the program normally, with the range a number |
| of text lines is filtered through the program. |
| |
| Executing a whole row of programs this way is possible. But a shell is much |
| better at it. You can start a new shell this way: > |
| |
| :shell |
| |
| This is similar to using CTRL-Z to suspend Vim. The difference is that a new |
| shell is started. |
| |
| When using the GUI the shell will be using the Vim window for its input and |
| output. Since Vim is not a terminal emulator, this will not work perfectly. |
| If you have trouble, try toggling the 'guipty' option. If this still doesn't |
| work well enough, start a new terminal to run the shell in. For example with: |
| > |
| :!xterm& |
| |
| ============================================================================== |
| *21.3* Remembering information; viminfo |
| |
| After editing for a while you will have text in registers, marks in various |
| files, a command line history filled with carefully crafted commands. When |
| you exit Vim all of this is lost. But you can get it back! |
| |
| The viminfo file is designed to store status information: |
| |
| Command-line and Search pattern history |
| Text in registers |
| Marks for various files |
| The buffer list |
| Global variables |
| |
| Each time you exit Vim it will store this information in a file, the viminfo |
| file. When Vim starts again, the viminfo file is read and the information |
| restored. |
| |
| The 'viminfo' option is set by default to restore a limited number of items. |
| You might want to set it to remember more information. This is done through |
| the following command: > |
| |
| :set viminfo=string |
| |
| The string specifies what to save. The syntax of this string is an option |
| character followed by an argument. The option/argument pairs are separated by |
| commas. |
| Take a look at how you can build up your own viminfo string. First, the ' |
| option is used to specify how many files for which you save marks (a-z). Pick |
| a nice even number for this option (1000, for instance). Your command now |
| looks like this: > |
| |
| :set viminfo='1000 |
| |
| The f option controls whether global marks (A-Z and 0-9) are stored. If this |
| option is 0, none are stored. If it is 1 or you do not specify an f option, |
| the marks are stored. You want this feature, so now you have this: > |
| |
| :set viminfo='1000,f1 |
| |
| The < option controls how many lines are saved for each of the registers. By |
| default, all the lines are saved. If 0, nothing is saved. To avoid adding |
| thousands of lines to your viminfo file (which might never get used and makes |
| starting Vim slower) you use a maximum of 500 lines: > |
| |
| :set viminfo='1000,f1,<500 |
| < |
| Other options you might want to use: |
| : number of lines to save from the command line history |
| @ number of lines to save from the input line history |
| / number of lines to save from the search history |
| r removable media, for which no marks will be stored (can be |
| used several times) |
| ! global variables that start with an uppercase letter and |
| don't contain lowercase letters |
| h disable 'hlsearch' highlighting when starting |
| % the buffer list (only restored when starting Vim without file |
| arguments) |
| c convert the text using 'encoding' |
| n name used for the viminfo file (must be the last option) |
| |
| See the 'viminfo' option and |viminfo-file| for more information. |
| |
| When you run Vim multiple times, the last one exiting will store its |
| information. This may cause information that previously exiting Vims stored |
| to be lost. Each item can be remembered only once. |
| |
| |
| GETTING BACK TO WHERE YOU STOPPED VIM |
| |
| You are halfway editing a file and it's time to leave for holidays. You exit |
| Vim and go enjoy yourselves, forgetting all about your work. After a couple |
| of weeks you start Vim, and type: |
| > |
| '0 |
| |
| And you are right back where you left Vim. So you can get on with your work. |
| Vim creates a mark each time you exit Vim. The last one is '0. The |
| position that '0 pointed to is made '1. And '1 is made to '2, and so forth. |
| Mark '9 is lost. |
| The |:marks| command is useful to find out where '0 to '9 will take you. |
| |
| |
| GETTING BACK TO SOME FILE |
| |
| If you want to go back to a file that you edited recently, but not when |
| exiting Vim, there is a slightly more complicated way. You can see a list of |
| files by typing the command: > |
| |
| :oldfiles |
| < 1: ~/.viminfo ~ |
| 2: ~/text/resume.txt ~ |
| 3: /tmp/draft ~ |
| |
| Now you would like to edit the second file, which is in the list preceded by |
| "2:". You type: > |
| |
| :e #<2 |
| |
| Instead of ":e" you can use any command that has a file name argument, the |
| "#<2" item works in the same place as "%" (current file name) and "#" |
| (alternate file name). So you can also split the window to edit the third |
| file: > |
| |
| :split #<3 |
| |
| That #<123 thing is a bit complicated when you just want to edit a file. |
| Fortunately there is a simpler way: > |
| |
| :browse oldfiles |
| < 1: ~/.viminfo ~ |
| 2: ~/text/resume.txt ~ |
| 3: /tmp/draft ~ |
| -- More -- |
| |
| You get the same list of files as with |:oldfiles|. If you want to edit |
| "resume.txt" first press "q" to stop the listing. You will get a prompt: |
| |
| Type number and <Enter> (empty cancels): ~ |
| |
| Type "2" and press <Enter> to edit the second file. |
| |
| More info at |:oldfiles|, |v:oldfiles| and |c_#<|. |
| |
| |
| MOVE INFO FROM ONE VIM TO ANOTHER |
| |
| You can use the ":wviminfo" and ":rviminfo" commands to save and restore the |
| information while still running Vim. This is useful for exchanging register |
| contents between two instances of Vim, for example. In the first Vim do: > |
| |
| :wviminfo! ~/tmp/viminfo |
| |
| And in the second Vim do: > |
| |
| :rviminfo! ~/tmp/viminfo |
| |
| Obviously, the "w" stands for "write" and the "r" for "read". |
| The ! character is used by ":wviminfo" to forcefully overwrite an existing |
| file. When it is omitted, and the file exists, the information is merged into |
| the file. |
| The ! character used for ":rviminfo" means that all the information is |
| used, this may overwrite existing information. Without the ! only information |
| that wasn't set is used. |
| These commands can also be used to store info and use it again later. You |
| could make a directory full of viminfo files, each containing info for a |
| different purpose. |
| |
| ============================================================================== |
| *21.4* Sessions |
| |
| Suppose you are editing along, and it is the end of the day. You want to quit |
| work and pick up where you left off the next day. You can do this by saving |
| your editing session and restoring it the next day. |
| A Vim session contains all the information about what you are editing. |
| This includes things such as the file list, window layout, global variables, |
| options and other information. (Exactly what is remembered is controlled by |
| the 'sessionoptions' option, described below.) |
| The following command creates a session file: > |
| |
| :mksession vimbook.vim |
| |
| Later if you want to restore this session, you can use this command: > |
| |
| :source vimbook.vim |
| |
| If you want to start Vim and restore a specific session, you can use the |
| following command: > |
| |
| vim -S vimbook.vim |
| |
| This tells Vim to read a specific file on startup. The 'S' stands for |
| session (actually, you can source any Vim script with -S, thus it might as |
| well stand for "source"). |
| |
| The windows that were open are restored, with the same position and size as |
| before. Mappings and option values are like before. |
| What exactly is restored depends on the 'sessionoptions' option. The |
| default value is "blank,buffers,curdir,folds,help,options,winsize". |
| |
| blank keep empty windows |
| buffers all buffers, not only the ones in a window |
| curdir the current directory |
| folds folds, also manually created ones |
| help the help window |
| options all options and mappings |
| winsize window sizes |
| |
| Change this to your liking. To also restore the size of the Vim window, for |
| example, use: > |
| |
| :set sessionoptions+=resize |
| |
| |
| SESSION HERE, SESSION THERE |
| |
| The obvious way to use sessions is when working on different projects. |
| Suppose you store your session files in the directory "~/.vim". You are |
| currently working on the "secret" project and have to switch to the "boring" |
| project: > |
| |
| :wall |
| :mksession! ~/.vim/secret.vim |
| :source ~/.vim/boring.vim |
| |
| This first uses ":wall" to write all modified files. Then the current session |
| is saved, using ":mksession!". This overwrites the previous session. The |
| next time you load the secret session you can continue where you were at this |
| point. And finally you load the new "boring" session. |
| |
| If you open help windows, split and close various windows, and generally mess |
| up the window layout, you can go back to the last saved session: > |
| |
| :source ~/.vim/boring.vim |
| |
| Thus you have complete control over whether you want to continue next time |
| where you are now, by saving the current setup in a session, or keep the |
| session file as a starting point. |
| Another way of using sessions is to create a window layout that you like to |
| use, and save this in a session. Then you can go back to this layout whenever |
| you want. |
| For example, this is a nice layout to use: |
| |
| +----------------------------------------+ |
| | VIM - main help file | |
| | | |
| |Move around: Use the cursor keys, or "h| |
| |help.txt================================| |
| |explorer | | |
| |dir |~ | |
| |dir |~ | |
| |file |~ | |
| |file |~ | |
| |file |~ | |
| |file |~ | |
| |~/=========|[No File]===================| |
| | | |
| +----------------------------------------+ |
| |
| This has a help window at the top, so that you can read this text. The narrow |
| vertical window on the left contains a file explorer. This is a Vim plugin |
| that lists the contents of a directory. You can select files to edit there. |
| More about this in the next chapter. |
| Create this from a just started Vim with: > |
| |
| :help |
| CTRL-W w |
| :vertical split ~/ |
| |
| You can resize the windows a bit to your liking. Then save the session with: |
| > |
| :mksession ~/.vim/mine.vim |
| |
| Now you can start Vim with this layout: > |
| |
| vim -S ~/.vim/mine.vim |
| |
| Hint: To open a file you see listed in the explorer window in the empty |
| window, move the cursor to the filename and press "O". Double clicking with |
| the mouse will also do this. |
| |
| |
| UNIX AND MS-WINDOWS |
| |
| Some people have to do work on MS-Windows systems one day and on Unix another |
| day. If you are one of them, consider adding "slash" and "unix" to |
| 'sessionoptions'. The session files will then be written in a format that can |
| be used on both systems. This is the command to put in your vimrc file: > |
| |
| :set sessionoptions+=unix,slash |
| |
| Vim will use the Unix format then, because the MS-Windows Vim can read and |
| write Unix files, but Unix Vim can't read MS-Windows format session files. |
| Similarly, MS-Windows Vim understands file names with / to separate names, but |
| Unix Vim doesn't understand \. |
| |
| |
| SESSIONS AND VIMINFO |
| |
| Sessions store many things, but not the position of marks, contents of |
| registers and the command line history. You need to use the viminfo feature |
| for these things. |
| In most situations you will want to use sessions separately from viminfo. |
| This can be used to switch to another session, but keep the command line |
| history. And yank text into registers in one session, and paste it back in |
| another session. |
| You might prefer to keep the info with the session. You will have to do |
| this yourself then. Example: > |
| |
| :mksession! ~/.vim/secret.vim |
| :wviminfo! ~/.vim/secret.viminfo |
| |
| And to restore this again: > |
| |
| :source ~/.vim/secret.vim |
| :rviminfo! ~/.vim/secret.viminfo |
| |
| ============================================================================== |
| *21.5* Views |
| |
| A session stores the looks of the whole of Vim. When you want to store the |
| properties for one window only, use a view. |
| The use of a view is for when you want to edit a file in a specific way. |
| For example, you have line numbers enabled with the 'number' option and |
| defined a few folds. Just like with sessions, you can remember this view on |
| the file and restore it later. Actually, when you store a session, it stores |
| the view of each window. |
| There are two basic ways to use views. The first is to let Vim pick a name |
| for the view file. You can restore the view when you later edit the same |
| file. To store the view for the current window: > |
| |
| :mkview |
| |
| Vim will decide where to store the view. When you later edit the same file |
| you get the view back with this command: > |
| |
| :loadview |
| |
| That's easy, isn't it? |
| Now you want to view the file without the 'number' option on, or with all |
| folds open, you can set the options to make the window look that way. Then |
| store this view with: > |
| |
| :mkview 1 |
| |
| Obviously, you can get this back with: > |
| |
| :loadview 1 |
| |
| Now you can switch between the two views on the file by using ":loadview" with |
| and without the "1" argument. |
| You can store up to ten views for the same file this way, one unnumbered |
| and nine numbered 1 to 9. |
| |
| |
| A VIEW WITH A NAME |
| |
| The second basic way to use views is by storing the view in a file with a name |
| you choose. This view can be loaded while editing another file. Vim will |
| then switch to editing the file specified in the view. Thus you can use this |
| to quickly switch to editing another file, with all its options set as you |
| saved them. |
| For example, to save the view of the current file: > |
| |
| :mkview ~/.vim/main.vim |
| |
| You can restore it with: > |
| |
| :source ~/.vim/main.vim |
| |
| ============================================================================== |
| *21.6* Modelines |
| |
| When editing a specific file, you might set options specifically for that |
| file. Typing these commands each time is boring. Using a session or view for |
| editing a file doesn't work when sharing the file between several people. |
| The solution for this situation is adding a modeline to the file. This is |
| a line of text that tells Vim the values of options, to be used in this file |
| only. |
| A typical example is a C program where you make indents by a multiple of 4 |
| spaces. This requires setting the 'shiftwidth' option to 4. This modeline |
| will do that: |
| |
| /* vim:set shiftwidth=4: */ ~ |
| |
| Put this line as one of the first or last five lines in the file. When |
| editing the file, you will notice that 'shiftwidth' will have been set to |
| four. When editing another file, it's set back to the default value of eight. |
| For some files the modeline fits well in the header, thus it can be put at |
| the top of the file. For text files and other files where the modeline gets |
| in the way of the normal contents, put it at the end of the file. |
| |
| The 'modelines' option specifies how many lines at the start and end of the |
| file are inspected for containing a modeline. To inspect ten lines: > |
| |
| :set modelines=10 |
| |
| The 'modeline' option can be used to switch this off. Do this when you are |
| working as root on Unix or Administrator on MS-Windows, or when you don't |
| trust the files you are editing: > |
| |
| :set nomodeline |
| |
| Use this format for the modeline: |
| |
| any-text vim:set {option}={value} ... : any-text ~ |
| |
| The "any-text" indicates that you can put any text before and after the part |
| that Vim will use. This allows making it look like a comment, like what was |
| done above with /* and */. |
| The " vim:" part is what makes Vim recognize this line. There must be |
| white space before "vim", or "vim" must be at the start of the line. Thus |
| using something like "gvim:" will not work. |
| The part between the colons is a ":set" command. It works the same way as |
| typing the ":set" command, except that you need to insert a backslash before a |
| colon (otherwise it would be seen as the end of the modeline). |
| |
| Another example: |
| |
| // vim:set textwidth=72 dir=c\:\tmp: use c:\tmp here ~ |
| |
| There is an extra backslash before the first colon, so that it's included in |
| the ":set" command. The text after the second colon is ignored, thus a remark |
| can be placed there. |
| |
| For more details see |modeline|. |
| |
| ============================================================================== |
| |
| Next chapter: |usr_22.txt| Finding the file to edit |
| |
| Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: |