vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

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: